@humanfs/types 0.15.0

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/types@0.15.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40humanfs/types@0.15.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - runtime: node@22.23.2

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:383be53581cf08a694d96011e4bd5d626febf230ec6b6fa4549e9c0ad487bb89","constraints":{"executionContext":"node"},"contract":["package manifest declares src/hfs-types.ts types entrypoint, module type, and node engine requirements","declares HfsImpl interface with asynchronous bytes, write, append, isFile, and isDirectory file operations","declares HfsImpl directory management methods including createDirectory, delete, deleteAll, and async iterable list","declares HfsImpl metadata inspection and file transfer methods including size, lastModified, copy, copyAll, move, and moveAll","declares HfsDirectoryEntry and HfsWalkEntry interfaces with path, depth, name, isDirectory, isFile, and isSymlink properties","runtime implementations conforming to HfsImpl contract fulfill in-memory file lifecycle, directory traversal, and entry hierarchy semantics"],"goal":"verify pkg:npm/%40humanfs/types@0.15.0","kind":"HOW","packages":["pkg:npm/%40humanfs/types@0.15.0"],"schemaVersion":1},"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","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40humanfs/types@0.15.0"],"schemaVersion":1,"subject":"pkg:npm/%40humanfs/types@0.15.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-humanfs-types",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-humanfs-types",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@humanfs/types": "0.15.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-types",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "@humanfs/types": "0.15.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40humanfs/types@0.15.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40humanfs/types@0.15.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "runtime": "node@22.23.2"
  }
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';

const require = createRequire(import.meta.url);

// 1. Resolve @humanfs/types package manifest and verify type declaration entry points
const pkgPath = require.resolve('@humanfs/types/package.json');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, '@humanfs/types', 'Package name must be @humanfs/types');
assert.equal(pkg.version, '0.15.0', 'Package version must be 0.15.0');
assert.equal(pkg.type, 'module', 'Package module type must be module');
assert.equal(pkg.types, 'src/hfs-types.ts', 'Package types entry must point to src/hfs-types.ts');
assert.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(
  pkg.exports?.['.']?.types,
  './src/hfs-types.ts',
  'Package exports types must point to ./src/hfs-types.ts'
);
assert.equal(pkg.engines?.node, '>=18.18.0', 'Package node engine must require >=18.18.0');

const pkgRoot = path.dirname(pkgPath);
const typesFilePath = path.join(pkgRoot, pkg.types);
const dtsContent = fs.readFileSync(typesFilePath, 'utf8');

// 2. Verify HfsImpl interface and core file operation method signatures
assert.ok(
  dtsContent.includes('export interface HfsImpl {'),
  'HfsImpl interface declaration must be exported'
);
assert.ok(
  dtsContent.includes('bytes?(filePath: string|URL): Promise<Uint8Array|undefined>;'),
  'HfsImpl must declare optional bytes method returning Promise<Uint8Array|undefined>'
);
assert.ok(
  dtsContent.includes('write?(filePath: string|URL, data: Uint8Array): Promise<void>;'),
  'HfsImpl must declare optional write method accepting Uint8Array data'
);
assert.ok(
  dtsContent.includes('append?(filePath: string|URL, data: Uint8Array): Promise<void>;'),
  'HfsImpl must declare optional append method accepting Uint8Array data'
);
assert.ok(
  dtsContent.includes('isFile?(filePath: string|URL): Promise<boolean>;'),
  'HfsImpl must declare optional isFile method returning Promise<boolean>'
);
assert.ok(
  dtsContent.includes('isDirectory?(dirPath: string|URL): Promise<boolean>;'),
  'HfsImpl must declare optional isDirectory method returning Promise<boolean>'
);

// 3. Verify HfsImpl directory, delete, and list operations
assert.ok(
  dtsContent.includes('createDirectory?(dirPath: string|URL): Promise<void>;'),
  'HfsImpl must declare optional createDirectory method'
);
assert.ok(
  dtsContent.includes('delete?(fileOrDirPath: string|URL): Promise<boolean>;'),
  'HfsImpl must declare optional delete method returning Promise<boolean>'
);
assert.ok(
  dtsContent.includes('deleteAll?(fileOrDirPath: string|URL): Promise<boolean>;'),
  'HfsImpl must declare optional deleteAll method returning Promise<boolean>'
);
assert.ok(
  dtsContent.includes('list?(dirPath: string|URL): AsyncIterable<HfsDirectoryEntry>;'),
  'HfsImpl must declare optional list method returning AsyncIterable<HfsDirectoryEntry>'
);

// 4. Verify HfsImpl metadata and transfer method signatures
assert.ok(
  dtsContent.includes('size?(filePath: string|URL): Promise<number|undefined>;'),
  'HfsImpl must declare optional size method returning Promise<number|undefined>'
);
assert.ok(
  dtsContent.includes('lastModified?(fileOrDirPath: string|URL): Promise<Date|undefined>;'),
  'HfsImpl must declare optional lastModified method returning Promise<Date|undefined>'
);
assert.ok(
  dtsContent.includes('copy?(source: string|URL, destination: string|URL): Promise<void>;'),
  'HfsImpl must declare optional copy method'
);
assert.ok(
  dtsContent.includes('copyAll?(source: string|URL, destination: string|URL): Promise<void>;'),
  'HfsImpl must declare optional copyAll method'
);
assert.ok(
  dtsContent.includes('move?(source: string|URL, destination: string|URL): Promise<void>;'),
  'HfsImpl must declare optional move method'
);
assert.ok(
  dtsContent.includes('moveAll?(source: string|URL, destination: string|URL): Promise<void>;'),
  'HfsImpl must declare optional moveAll method'
);

// 5. Verify HfsDirectoryEntry and HfsWalkEntry interface definitions
assert.ok(
  dtsContent.includes('export interface HfsDirectoryEntry {'),
  'HfsDirectoryEntry interface must be exported'
);
assert.ok(
  dtsContent.includes('name: string;') &&
  dtsContent.includes('isDirectory: boolean;') &&
  dtsContent.includes('isFile: boolean;') &&
  dtsContent.includes('isSymlink: boolean;'),
  'HfsDirectoryEntry must declare name, isDirectory, isFile, and isSymlink properties'
);
assert.ok(
  dtsContent.includes('export interface HfsWalkEntry extends HfsDirectoryEntry {'),
  'HfsWalkEntry interface must extend HfsDirectoryEntry'
);
assert.ok(
  dtsContent.includes('path: string;') &&
  dtsContent.includes('depth: number;'),
  'HfsWalkEntry must declare path and depth properties'
);

// 6. Runtime behavioral contract verification with conforming HfsImpl implementation
class InMemoryHfsImpl {
  constructor() {
    this.files = new Map();
    this.dirs = new Set(['/']);
  }

  normalizePath(p) {
    if (p instanceof URL) {
      return p.pathname;
    }
    return String(p);
  }

  async isFile(filePath) {
    return this.files.has(this.normalizePath(filePath));
  }

  async isDirectory(dirPath) {
    return this.dirs.has(this.normalizePath(dirPath));
  }

  async createDirectory(dirPath) {
    this.dirs.add(this.normalizePath(dirPath));
  }

  async write(filePath, data) {
    assert.ok(data instanceof Uint8Array, 'data must be a Uint8Array');
    this.files.set(this.normalizePath(filePath), new Uint8Array(data));
  }

  async append(filePath, data) {
    assert.ok(data instanceof Uint8Array, 'data must be a Uint8Array');
    const norm = this.normalizePath(filePath);
    const existing = this.files.get(norm) || new Uint8Array(0);
    const combined = new Uint8Array(existing.length + data.length);
    combined.set(existing, 0);
    combined.set(data, existing.length);
    this.files.set(norm, combined);
  }

  async bytes(filePath) {
    const norm = this.normalizePath(filePath);
    if (!this.files.has(norm)) {
      return undefined;
    }
    return this.files.get(norm);
  }

  async size(filePath) {
    const content = await this.bytes(filePath);
    return content ? content.byteLength : undefined;
  }

  async lastModified(fileOrDirPath) {
    const norm = this.normalizePath(fileOrDirPath);
    if (this.files.has(norm) || this.dirs.has(norm)) {
      return new Date(1700000000000);
    }
    return undefined;
  }

  async delete(fileOrDirPath) {
    const norm = this.normalizePath(fileOrDirPath);
    if (this.files.has(norm)) {
      this.files.delete(norm);
      return true;
    }
    if (this.dirs.has(norm)) {
      this.dirs.delete(norm);
      return true;
    }
    return false;
  }

  async deleteAll(fileOrDirPath) {
    return await this.delete(fileOrDirPath);
  }

  async copy(source, destination) {
    const data = await this.bytes(source);
    if (data === undefined) {
      throw new Error(`Source not found: ${source}`);
    }
    await this.write(destination, data);
  }

  async copyAll(source, destination) {
    await this.copy(source, destination);
  }

  async move(source, destination) {
    await this.copy(source, destination);
    await this.delete(source);
  }

  async moveAll(source, destination) {
    await this.move(source, destination);
  }

  async *list(dirPath) {
    const norm = this.normalizePath(dirPath);
    for (const [key] of this.files.entries()) {
      if (key.startsWith(norm) && key !== norm) {
        const entry = {
          name: path.basename(key),
          isDirectory: false,
          isFile: true,
          isSymlink: false
        };
        yield entry;
      }
    }
  }
}

const impl = new InMemoryHfsImpl();
const testBytes = new TextEncoder().encode('HumanFS contract payload');
await impl.write('/test.txt', testBytes);
assert.equal(await impl.isFile('/test.txt'), true, 'isFile should return true');
assert.equal(await impl.isDirectory('/test.txt'), false, 'isDirectory should return false');
assert.equal(await impl.size('/test.txt'), testBytes.byteLength, 'size should match payload length');

const readBack = await impl.bytes('/test.txt');
assert.deepEqual(readBack, testBytes, 'bytes should return exact payload');

await impl.copy('/test.txt', '/copied.txt');
assert.equal(await impl.isFile('/copied.txt'), true, 'copied file should exist');

await impl.move('/copied.txt', '/moved.txt');
assert.equal(await impl.isFile('/copied.txt'), false, 'source after move should be removed');
assert.equal(await impl.isFile('/moved.txt'), true, 'destination after move should exist');

const entries = [];
for await (const entry of impl.list('/')) {
  entries.push(entry);
}
assert.ok(entries.length >= 2, 'list should yield directory entries conforming to HfsDirectoryEntry');
assert.ok(entries.every(e => typeof e.name === 'string' && typeof e.isFile === 'boolean'));

const walkEntry = {
  name: 'file.txt',
  isDirectory: false,
  isFile: true,
  isSymlink: false,
  path: 'sub/file.txt',
  depth: 2
};
assert.equal(walkEntry.path, 'sub/file.txt', 'HfsWalkEntry must contain path string');
assert.equal(walkEntry.depth, 2, 'HfsWalkEntry must contain depth number');

console.log('Contract tests passed successfully.');