@humanfs/core 0.19.2: 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/core.Hfs in pkg:npm/%40humanfs/core@0.19.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40humanfs/core@0.19.2
Demonstrate these symbols/APIs:
  - @humanfs/core.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:72788e8c84245e74fef56d45187bd64eb8f2cb4d122047f7bf2855a1e503b71a","contract":["Hfs initializes with custom impl and reports isBaseImpl true","Hfs writes string data and reads back text and raw bytes","Hfs parses UTF-8 file contents into JSON objects with json","Hfs checks file and directory existence with isFile and isDirectory","Hfs deletes files and directories with delete","Hfs logStart records method invocations with arguments and logEnd returns log entries","Hfs setImpl replaces active implementation and resetImpl restores base implementation","Hfs throws TypeError when given an invalid or empty path"],"goal":"verify @humanfs/core.Hfs in pkg:npm/%40humanfs/core@0.19.2","kind":"HOW","packages":["pkg:npm/%40humanfs/core@0.19.2"],"schemaVersion":1,"symbols":["@humanfs/core.Hfs"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40humanfs/core@0.19.2"],"schemaVersion":1,"subject":"pkg:npm/%40humanfs/core@0.19.2","symbols":["@humanfs/core.Hfs"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-humanfs-core-hfs",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-humanfs-core-hfs",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@humanfs/core": "0.19.2"
      }
    },
    "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/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"
      }
    }
  }
}

{
  "name": "sample-humanfs-core-hfs",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@humanfs/core": "0.19.2"
  }
}

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

import { Hfs } from '@humanfs/core';

/**
 * Minimal in-memory file system implementation satisfying HfsImpl.
 */
export class InMemoryHfsImpl {
  constructor() {
    this.files = new Map();
    this.directories = new Set(['/']);
  }

  /**
   * Write byte contents to path.
   * @param {string} filePath
   * @param {Uint8Array} contents
   */
  async write(filePath, contents) {
    this.files.set(filePath, contents);
  }

  /**
   * Read byte contents of path.
   * @param {string} filePath
   * @returns {Promise<Uint8Array | undefined>}
   */
  async bytes(filePath) {
    return this.files.get(filePath);
  }

  /**
   * Check if file exists.
   * @param {string} filePath
   * @returns {Promise<boolean>}
   */
  async isFile(filePath) {
    return this.files.has(filePath);
  }

  /**
   * Check if directory exists.
   * @param {string} dirPath
   * @returns {Promise<boolean>}
   */
  async isDirectory(dirPath) {
    return this.directories.has(dirPath);
  }

  /**
   * Create directory.
   * @param {string} dirPath
   */
  async createDirectory(dirPath) {
    this.directories.add(dirPath);
  }

  /**
   * Delete file or directory.
   * @param {string} filePath
   * @returns {Promise<boolean>}
   */
  async delete(filePath) {
    const fileDeleted = this.files.delete(filePath);
    const dirDeleted = this.directories.delete(filePath);
    return fileDeleted || dirDeleted;
  }
}

/**
 * Create an Hfs instance backed by InMemoryHfsImpl.
 * @returns {Hfs}
 */
export function createMemoryHfs() {
  const impl = new InMemoryHfsImpl();
  return new Hfs({ impl });
}

export { Hfs };

import assert from 'node:assert/strict';
import { Hfs, InMemoryHfsImpl, createMemoryHfs } from '../src/index.mjs';

// 1. Hfs initializes with custom impl and reports isBaseImpl true
{
  const hfs = createMemoryHfs();
  assert.equal(typeof hfs, 'object');
  assert.equal(hfs.isBaseImpl(), true);

  const directHfs = new Hfs({ impl: new InMemoryHfsImpl() });
  assert.equal(directHfs.isBaseImpl(), true);
}

// 2. Hfs writes string data and reads back text and raw bytes
{
  const hfs = createMemoryHfs();
  await hfs.write('/docs/hello.txt', 'Hello HumanFS!');
  const text = await hfs.text('/docs/hello.txt');
  assert.equal(text, 'Hello HumanFS!');

  const rawBytes = await hfs.bytes('/docs/hello.txt');
  assert.equal(rawBytes instanceof Uint8Array, true);
  assert.equal(new TextDecoder().decode(rawBytes), 'Hello HumanFS!');
}

// 3. Hfs parses UTF-8 file contents into JSON objects with json
{
  const hfs = createMemoryHfs();
  const config = { name: 'app', version: 1, active: true };
  await hfs.write('/app/config.json', JSON.stringify(config));

  const parsed = await hfs.json('/app/config.json');
  assert.deepEqual(parsed, config);
}

// 4. Hfs checks file and directory existence with isFile and isDirectory
{
  const hfs = createMemoryHfs();
  await hfs.createDirectory('/data');
  await hfs.write('/data/items.txt', 'item1');

  assert.equal(await hfs.isDirectory('/data'), true);
  assert.equal(await hfs.isFile('/data'), false);
  assert.equal(await hfs.isFile('/data/items.txt'), true);
  assert.equal(await hfs.isDirectory('/data/items.txt'), false);
  assert.equal(await hfs.isFile('/data/nonexistent.txt'), false);
}

// 5. Hfs deletes files and directories with delete
{
  const hfs = createMemoryHfs();
  await hfs.write('/temp.txt', 'temp data');
  assert.equal(await hfs.isFile('/temp.txt'), true);

  const deleted = await hfs.delete('/temp.txt');
  assert.equal(deleted, true);
  assert.equal(await hfs.isFile('/temp.txt'), false);
}

// 6. Hfs logStart records method invocations with arguments and logEnd returns log entries
{
  const hfs = createMemoryHfs();
  hfs.logStart('opLog');

  await hfs.write('/logged.txt', 'logged content');
  await hfs.text('/logged.txt');

  const logs = hfs.logEnd('opLog');
  assert.equal(Array.isArray(logs), true);
  assert.equal(logs.length >= 2, true);

  const writeLog = logs.find(entry => entry.data?.methodName === 'write');
  assert.ok(writeLog);
  assert.equal(writeLog.data.args[0], '/logged.txt');

  const textLog = logs.find(entry => entry.data?.methodName === 'text');
  assert.ok(textLog);
  assert.equal(textLog.data.args[0], '/logged.txt');

  assert.throws(() => hfs.logEnd('opLog'), /Log "opLog" does not exist/);
}

// 7. Hfs setImpl replaces active implementation and resetImpl restores base implementation
{
  const hfs = createMemoryHfs();
  await hfs.write('/base.txt', 'base');

  const secondaryImpl = new InMemoryHfsImpl();
  await secondaryImpl.write('/secondary.txt', new TextEncoder().encode('secondary'));

  hfs.setImpl(secondaryImpl);
  assert.equal(hfs.isBaseImpl(), false);
  assert.equal(await hfs.text('/secondary.txt'), 'secondary');
  assert.equal(await hfs.text('/base.txt'), undefined);

  hfs.resetImpl();
  assert.equal(hfs.isBaseImpl(), true);
  assert.equal(await hfs.text('/base.txt'), 'base');
  assert.equal(await hfs.text('/secondary.txt'), undefined);
}

// 8. Hfs throws TypeError when given an invalid or empty path
{
  const hfs = createMemoryHfs();
  await assert.rejects(async () => hfs.write('', 'content'), TypeError);
  await assert.rejects(async () => hfs.text(''), TypeError);
  await assert.rejects(async () => hfs.isFile(null), TypeError);
  assert.throws(() => hfs.logStart(''), TypeError);
}

console.log('Contract assertions passed.');