@humanfs/node 0.16.8: NodeHfs

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 @humanfs/node.NodeHfs in 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:
  - @humanfs/node.NodeHfs

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:4e6b6242e601820a21616a9f4ee2799753bb12c9535516d108eb4c0b1e25efc3","contract":["NodeHfs instances can be constructed with default or custom file system options","NodeHfs provides asynchronous methods to write and read text and parsed JSON files","NodeHfs reads and writes binary data via Uint8Array and appends text to files","NodeHfs inspects file and directory existence, file size, and last modified date","NodeHfs creates nested directories and recursively walks directory entries","NodeHfs performs copy, move, and recursive delete operations on files and directories"],"goal":"verify @humanfs/node.NodeHfs in pkg:npm/%40humanfs/node@0.16.8","kind":"HOW","packages":["pkg:npm/%40humanfs/node@0.16.8"],"schemaVersion":1,"symbols":["@humanfs/node.NodeHfs"]},"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":["@humanfs/node.NodeHfs"],"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.NodeHfs",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@humanfs/node": "0.16.8"
  }
}

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

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

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

/**
 * 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);
}

module.exports = {
  loadHumanfsNode,
  createNodeHfs
};

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 { NodeHfs } from '@humanfs/node';

const require = createRequire(import.meta.url);
const { loadHumanfsNode, createNodeHfs } = 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. NodeHfs instances can be constructed with default or custom file system options
  {
    assert.equal(typeof NodeHfs, 'function', 'NodeHfs must be a class constructor');
    assert.equal(typeof createNodeHfs, 'function', 'createNodeHfs helper must be a function');
    assert.equal(typeof loadHumanfsNode, 'function', 'loadHumanfsNode helper must be a function');

    const mod = await loadHumanfsNode();
    assert.equal(mod.NodeHfs, NodeHfs, 'loadHumanfsNode must export NodeHfs');

    const defaultHfs = new NodeHfs();
    assert.ok(defaultHfs instanceof NodeHfs, 'default constructor must create a NodeHfs instance');

    const customHfs = await createNodeHfs({ fsp });
    assert.ok(customHfs instanceof NodeHfs, 'createNodeHfs with options must create a NodeHfs instance');
  }

  // 2. NodeHfs provides asynchronous methods to write and read text and parsed JSON files
  {
    const hfs = new NodeHfs();
    const textFile = path.join(testDir, 'contract_sample.txt');
    await hfs.write(textFile, 'Humanfs Node Contract Text');
    const content = await hfs.text(textFile);
    assert.equal(content, 'Humanfs Node Contract Text', 'text() must return written string content');

    const jsonFile = path.join(testDir, 'contract_config.json');
    const payload = { service: 'storage', active: true, retries: 3 };
    await hfs.write(jsonFile, JSON.stringify(payload));
    const parsed = await hfs.json(jsonFile);
    assert.deepEqual(parsed, payload, 'json() must parse and return stored JSON object');
  }

  // 3. NodeHfs reads and writes binary data via Uint8Array and appends text to files
  {
    const hfs = new NodeHfs();
    const binFile = path.join(testDir, 'contract_binary.dat');
    const binaryData = new Uint8Array([0x4e, 0x4f, 0x44, 0x45, 0x48, 0x46, 0x53]);
    await hfs.write(binFile, binaryData);
    const readBytes = await hfs.bytes(binFile);
    assert.deepEqual(readBytes, binaryData, 'bytes() must return exact written byte array');

    const appendFile = path.join(testDir, 'contract_append.txt');
    await hfs.write(appendFile, 'Part1');
    await hfs.append(appendFile, '-Part2');
    const fullText = await hfs.text(appendFile);
    assert.equal(fullText, 'Part1-Part2', 'append() must append text to the file');
  }

  // 4. NodeHfs inspects file and directory existence, file size, and last modified date
  {
    const hfs = new NodeHfs();
    const sampleFile = path.join(testDir, 'contract_sample.txt');
    assert.equal(await hfs.isFile(sampleFile), true, 'isFile() must return true for regular file');
    assert.equal(await hfs.isDirectory(sampleFile), false, 'isDirectory() must return false for regular file');
    assert.equal(await hfs.isDirectory(testDir), true, 'isDirectory() must return true for directory');
    assert.equal(await hfs.isFile(testDir), false, 'isFile() must return false for directory');

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

    const fileSize = await hfs.size(sampleFile);
    assert.equal(fileSize, Buffer.byteLength('Humanfs Node Contract Text'), 'size() must return correct file byte count');

    const mtime = await hfs.lastModified(sampleFile);
    assert.ok(mtime instanceof Date, 'lastModified() must return a Date instance');
  }

  // 5. NodeHfs creates nested directories and recursively walks directory entries
  {
    const hfs = new NodeHfs();
    const subFolder = path.join(testDir, 'level1', 'level2');
    await hfs.createDirectory(subFolder);
    assert.equal(await hfs.isDirectory(subFolder), true, 'createDirectory() must create nested folders');

    const nestedFile = path.join(subFolder, 'nested.txt');
    await hfs.write(nestedFile, 'nested file content');

    const walkedNames = [];
    for await (const entry of hfs.walk(testDir)) {
      walkedNames.push(entry.name);
    }
    assert.ok(walkedNames.includes('nested.txt'), 'walk() must discover deeply nested files');
    assert.ok(walkedNames.includes('level1'), 'walk() must discover intermediate directories');
  }

  // 6. NodeHfs performs copy, move, and recursive delete operations on files and directories
  {
    const hfs = new NodeHfs();
    const origFile = path.join(testDir, 'to_copy.txt');
    const destFile = path.join(testDir, 'copied.txt');
    const movedFile = path.join(testDir, 'moved.txt');

    await hfs.write(origFile, 'Data to move and copy');
    await hfs.copy(origFile, destFile);
    assert.equal(await hfs.isFile(destFile), true, 'copy() must create destination copy');

    await hfs.move(destFile, movedFile);
    assert.equal(await hfs.isFile(destFile), false, 'move() must remove old file');
    assert.equal(await hfs.isFile(movedFile), true, 'move() must create file at destination');

    const deleted = await hfs.delete(movedFile);
    assert.equal(deleted, true, 'delete() must return true when removing a file');
    assert.equal(await hfs.isFile(movedFile), false, 'deleted file must no longer exist');

    const treeDir = path.join(testDir, 'level1');
    const deletedAll = await hfs.deleteAll(treeDir);
    assert.equal(deletedAll, true, 'deleteAll() must return true when deleting directory tree');
    assert.equal(await hfs.isDirectory(treeDir), false, 'deleteAll() must remove full folder structure');
  }

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