@humanfs/node 0.16.8: 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 @humanfs/node.hfs 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.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:04ace24d4b6017ce3ae2468c5982e7a915a8e8e75ef62bf8e0f0870f36625201","contract":["hfs is exported as a pre-configured instance of NodeHfs","hfs provides asynchronous methods to write and read text and parsed JSON files","hfs reads and writes binary data via Uint8Array and appends text to files","hfs inspects file and directory existence, file size, and last modified date","hfs creates nested directories and recursively walks directory entries","hfs performs copy, move, and recursive delete operations on files and directories"],"goal":"verify @humanfs/node.hfs in pkg:npm/%40humanfs/node@0.16.8","kind":"HOW","packages":["pkg:npm/%40humanfs/node@0.16.8"],"schemaVersion":1,"symbols":["@humanfs/node.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":["@humanfs/node.hfs"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-humanfs-node-hfs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-humanfs-node-hfs",
      "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-hfs",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of @humanfs/node.hfs",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "@humanfs/node": "0.16.8"
  }
}

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

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

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

/**
 * Retrieves the pre-configured hfs instance from @humanfs/node.
 * @returns {Promise<import('@humanfs/node').NodeHfs>}
 */
async function getHfsInstance() {
  const { hfs } = await import('@humanfs/node');
  return hfs;
}

module.exports = {
  loadHumanfsNode,
  getHfsInstance
};

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

const require = createRequire(import.meta.url);
const { loadHumanfsNode, getHfsInstance } = 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. hfs is exported as a pre-configured instance of NodeHfs
  {
    assert.ok(hfs, 'hfs must be exported');
    assert.ok(hfs instanceof NodeHfs, 'hfs must be an instance of NodeHfs');
    assert.equal(typeof loadHumanfsNode, 'function', 'loadHumanfsNode helper must be a function');
    assert.equal(typeof getHfsInstance, 'function', 'getHfsInstance helper must be a function');

    const mod = await loadHumanfsNode();
    assert.equal(mod.hfs, hfs, 'loadHumanfsNode must export the singleton hfs instance');

    const instance = await getHfsInstance();
    assert.equal(instance, hfs, 'getHfsInstance must return the singleton hfs instance');
  }

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

    const jsonFile = path.join(testDir, 'contract_config.json');
    const payload = { service: 'storage', symbol: 'hfs', active: true, count: 42 };
    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. hfs reads and writes binary data via Uint8Array and appends text to files
  {
    const binFile = path.join(testDir, 'contract_binary.dat');
    const binaryData = new Uint8Array([0x48, 0x46, 0x53, 0x5f, 0x42, 0x49, 0x4e]);
    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. hfs inspects file and directory existence, file size, and last modified date
  {
    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 Hfs 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. hfs creates nested directories and recursively walks directory entries
  {
    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. hfs performs copy, move, and recursive delete operations on files and directories
  {
    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('hfs contract assertions passed.');
} finally {
  await cleanup();
}