@humanfs/node 0.16.8: NodeHfs, NodeHfsImpl, hfs

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/%40humanfs/node@0.16.8
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40humanfs/node@0.16.8
Demonstrate these symbols/APIs:
  - NodeHfs
  - NodeHfsImpl
  - hfs

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:04876863bdec99728ae3615eebedda1a4a50e1b72eeddb0c68ffd3daf1616a5c","constraints":{"executionContext":"node"},"contract":["NodeHfs provides asynchronous file operations to write and read text and JSON files","NodeHfs supports reading and writing raw byte arrays via Uint8Array","NodeHfs accurately reports file and directory existence using isFile and isDirectory","NodeHfs creates nested directories and lists directory contents as an async iterable of directory entries","NodeHfs performs copy, move, and recursive delete operations on files and directory structures","NodeHfs and NodeHfsImpl allow constructing custom filesystem instances backed by fs/promises"],"goal":"verify pkg:npm/%40humanfs/node@0.16.8","kind":"HOW","packages":["pkg:npm/%40humanfs/node@0.16.8"],"schemaVersion":1,"symbols":["NodeHfs","NodeHfsImpl","hfs"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40humanfs/node@0.16.8"],"schemaVersion":1,"subject":"pkg:npm/%40humanfs/node@0.16.8","symbols":["NodeHfs","NodeHfsImpl","hfs"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-humanfs-node",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-humanfs-node",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@humanfs/node": "0.16.8"
      }
    },
    "node_modules/@humanfs/core": {
      "version": "0.19.2",
      "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.2.tgz",
      "integrity": "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==",
      "license": "Apache-2.0",
      "dependencies": {
        "@humanfs/types": "^0.15.0"
      },
      "engines": {
        "node": ">=18.18.0"
      }
    },
    "node_modules/@humanfs/node": {
      "version": "0.16.8",
      "resolved": "https://registry.npmjs.org/@humanfs/node/-/node-0.16.8.tgz",
      "integrity": "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "@humanfs/core": "^0.19.2",
        "@humanfs/types": "^0.15.0",
        "@humanwhocodes/retry": "^0.4.0"
      },
      "engines": {
        "node": ">=18.18.0"
      }
    },
    "node_modules/@humanfs/types": {
      "version": "0.15.0",
      "resolved": "https://registry.npmjs.org/@humanfs/types/-/types-0.15.0.tgz",
      "integrity": "sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==",
      "license": "Apache-2.0",
      "engines": {
        "node": ">=18.18.0"
      }
    },
    "node_modules/@humanwhocodes/retry": {
      "version": "0.4.3",
      "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.3.tgz",
      "integrity": "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==",
      "license": "Apache-2.0",
      "engines": {
        "node": ">=18.18"
      },
      "funding": {
        "type": "github",
        "url": "https://github.com/sponsors/nzakas"
      }
    }
  }
}

{
  "name": "sample-humanfs-node",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @humanfs/node",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@humanfs/node": "0.16.8"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40humanfs/node@0.16.8",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40humanfs/node@0.16.8"
  ],
  "symbols": [
    "NodeHfs",
    "NodeHfsImpl",
    "hfs"
  ]
}

/**
 * Clean-room wrapper for @humanfs/node operations.
 */

/**
 * Dynamically loads the @humanfs/node module.
 * @returns {Promise<typeof import('@humanfs/node')>}
 */
async function loadHumanfs() {
  return await import('@humanfs/node');
}

/**
 * Gets the default hfs instance.
 * @returns {Promise<import('@humanfs/node').hfs>}
 */
async function getDefaultHfs() {
  const { hfs } = await import('@humanfs/node');
  return hfs;
}

/**
 * Creates a new NodeHfs instance.
 * @param {object} [options]
 * @returns {Promise<import('@humanfs/node').NodeHfs>}
 */
async function createNodeHfs(options) {
  const { NodeHfs } = await import('@humanfs/node');
  return new NodeHfs(options);
}

/**
 * Creates a new NodeHfsImpl instance.
 * @param {object} [options]
 * @returns {Promise<import('@humanfs/node').NodeHfsImpl>}
 */
async function createNodeHfsImpl(options) {
  const { NodeHfsImpl } = await import('@humanfs/node');
  return new NodeHfsImpl(options);
}

module.exports = {
  loadHumanfs,
  getDefaultHfs,
  createNodeHfs,
  createNodeHfsImpl
};

import assert from 'node:assert/strict';
import path from 'node:path';
import fsp from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
import { createRequire } from 'node:module';
import { hfs, NodeHfs, NodeHfsImpl } from '@humanfs/node';

const require = createRequire(import.meta.url);
const { loadHumanfs, getDefaultHfs, createNodeHfs, createNodeHfsImpl } = require('../src/index.js');

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const testDir = path.join(__dirname, 'temp_contract_workspace');

async function cleanup() {
  try {
    await fsp.rm(testDir, { recursive: true, force: true });
  } catch {}
}

await cleanup();
await fsp.mkdir(testDir, { recursive: true });

try {
  // 1. Export verification
  assert.equal(typeof hfs, 'object', 'hfs must be exported as an object instance');
  assert.equal(typeof NodeHfs, 'function', 'NodeHfs must be exported as a class');
  assert.equal(typeof NodeHfsImpl, 'function', 'NodeHfsImpl must be exported as a class');
  assert.equal(typeof loadHumanfs, 'function', 'loadHumanfs helper must be a function');
  assert.equal(typeof getDefaultHfs, 'function', 'getDefaultHfs helper must be a function');
  assert.equal(typeof createNodeHfs, 'function', 'createNodeHfs helper must be a function');
  assert.equal(typeof createNodeHfsImpl, 'function', 'createNodeHfsImpl helper must be a function');

  const loadedDefaultHfs = await getDefaultHfs();
  assert.equal(loadedDefaultHfs, hfs, 'getDefaultHfs helper must return the default hfs instance');

  // 2. NodeHfs provides asynchronous file operations to write and read text and JSON files
  {
    const textFile = path.join(testDir, 'sample.txt');
    await hfs.write(textFile, 'Hello CodeSampleX');
    const content = await hfs.text(textFile);
    assert.equal(content, 'Hello CodeSampleX', 'hfs.text must return written file text');

    const jsonFile = path.join(testDir, 'config.json');
    const testObject = { env: 'production', port: 8080, active: true };
    await hfs.write(jsonFile, JSON.stringify(testObject));
    const parsed = await hfs.json(jsonFile);
    assert.deepEqual(parsed, testObject, 'hfs.json must parse JSON file contents');
  }

  // 3. NodeHfs supports reading and writing raw byte arrays via Uint8Array
  {
    const binFile = path.join(testDir, 'binary.bin');
    const testBytes = new Uint8Array([0x43, 0x53, 0x58, 0x01, 0x02]);
    await hfs.write(binFile, testBytes);
    const readBytes = await hfs.bytes(binFile);
    assert.deepEqual(readBytes, testBytes, 'hfs.bytes must return exact written byte array');

    const appendFile = path.join(testDir, 'append.txt');
    await hfs.write(appendFile, 'Initial');
    await hfs.append(appendFile, ' + Appended');
    const combined = await hfs.text(appendFile);
    assert.equal(combined, 'Initial + Appended', 'hfs.append must append text to existing file');
  }

  // 4. NodeHfs accurately reports file and directory existence using isFile and isDirectory
  {
    const fileTarget = path.join(testDir, 'sample.txt');
    assert.equal(await hfs.isFile(fileTarget), true, 'isFile must return true for regular file');
    assert.equal(await hfs.isDirectory(fileTarget), false, 'isDirectory must return false for regular file');

    const missingTarget = path.join(testDir, 'missing.txt');
    assert.equal(await hfs.isFile(missingTarget), false, 'isFile must return false for nonexistent file');
    assert.equal(await hfs.isDirectory(missingTarget), false, 'isDirectory must return false for nonexistent directory');

    const size = await hfs.size(fileTarget);
    assert.equal(size, Buffer.byteLength('Hello CodeSampleX'), 'size must match byte length of file content');

    const modified = await hfs.lastModified(fileTarget);
    assert.ok(modified instanceof Date, 'lastModified must return a valid Date object');
  }

  // 5. NodeHfs creates nested directories and lists directory contents as an async iterable of directory entries
  {
    const dirTarget = path.join(testDir, 'nested', 'deep', 'folder');
    await hfs.createDirectory(dirTarget);
    assert.equal(await hfs.isDirectory(dirTarget), true, 'createDirectory must create directory recursively');

    const fileA = path.join(dirTarget, 'a.txt');
    const fileB = path.join(dirTarget, 'b.txt');
    await hfs.write(fileA, 'Content A');
    await hfs.write(fileB, 'Content B');

    const listedEntries = [];
    for await (const entry of hfs.list(dirTarget)) {
      listedEntries.push(entry);
    }
    assert.equal(listedEntries.length, 2, 'list must yield all entries in directory');
    const names = listedEntries.map(e => e.name).sort();
    assert.deepEqual(names, ['a.txt', 'b.txt'], 'list must yield correct file names');
    assert.ok(listedEntries.every(e => e.isFile && !e.isDirectory), 'entry flags must identify files correctly');
  }

  // 6. NodeHfs performs copy, move, and recursive delete operations on files and directory structures
  {
    const sourceFile = path.join(testDir, 'source.txt');
    const copyDest = path.join(testDir, 'copied.txt');
    const moveDest = path.join(testDir, 'moved.txt');

    await hfs.write(sourceFile, 'MoveCopyTest');
    await hfs.copy(sourceFile, copyDest);
    assert.equal(await hfs.isFile(copyDest), true, 'copy must create destination file');
    assert.equal(await hfs.text(copyDest), 'MoveCopyTest');

    await hfs.move(copyDest, moveDest);
    assert.equal(await hfs.isFile(copyDest), false, 'move must remove source file');
    assert.equal(await hfs.isFile(moveDest), true, 'move must create destination file');

    const deletedFile = await hfs.delete(moveDest);
    assert.equal(deletedFile, true, 'delete must return true when file deleted');
    assert.equal(await hfs.isFile(moveDest), false, 'deleted file must not exist');

    const deletedTree = await hfs.deleteAll(path.join(testDir, 'nested'));
    assert.equal(deletedTree, true, 'deleteAll must return true when directory deleted');
    assert.equal(await hfs.isDirectory(path.join(testDir, 'nested')), false, 'deleted directory tree must not exist');
  }

  // 7. NodeHfs and NodeHfsImpl allow constructing custom filesystem instances backed by fs/promises
  {
    const customImpl = await createNodeHfsImpl({ fsp });
    assert.equal(typeof customImpl.bytes, 'function', 'custom NodeHfsImpl must have bytes method');

    const customHfs = await createNodeHfs({ fsp });
    const customFilePath = path.join(testDir, 'custom_instance.txt');
    await customHfs.write(customFilePath, 'Custom Instance Content');
    assert.equal(await customHfs.text(customFilePath), 'Custom Instance Content');
  }

  console.log('Contract assertions passed.');
} finally {
  await cleanup();
}