fs-extra 9.1.0: copy

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 fs-extra.copy in pkg:npm/fs-extra@9.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fs-extra@9.1.0
Demonstrate these symbols/APIs:
  - fs-extra.copy
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - 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:ad2a7bf5932eefdd5638e12cd481ebf928a8187d87d51572229ac67f26f51c5f","constraints":{"executionContext":"node"},"contract":["fs.copy asynchronously copies a single file to a target destination, creating parent directories if needed","fs.copy recursively copies an entire directory hierarchy preserving structure and content","fs.copy supports a filter function to selectively copy files and directories","fs.copy rejects with an error when overwrite is false and errorOnExist is true if destination exists","fs.copy preserves timestamps when preserveTimestamps option is true","fs.copySync synchronously copies directory structures and contents"],"goal":"verify fs-extra.copy in pkg:npm/fs-extra@9.1.0","kind":"HOW","packages":["pkg:npm/fs-extra@9.1.0"],"schemaVersion":1,"symbols":["fs-extra.copy"]},"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/fs-extra@9.1.0"],"schemaVersion":1,"subject":"pkg:npm/fs-extra@9.1.0","symbols":["fs-extra.copy"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-fs-extra-copy",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-fs-extra-copy",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "fs-extra": "9.1.0"
      }
    },
    "node_modules/at-least-node": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz",
      "integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==",
      "license": "ISC",
      "engines": {
        "node": ">= 4.0.0"
      }
    },
    "node_modules/fs-extra": {
      "version": "9.1.0",
      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.1.0.tgz",
      "integrity": "sha512-hcg3ZmepS30/7BSFqRvoo3DOMQu7IjqxO5nCDt+zM9XWjb33Wg7ziNT+Qvqbuc3+gWpzO02JubVyk2G4Zvo1OQ==",
      "license": "MIT",
      "dependencies": {
        "at-least-node": "^1.0.0",
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
        "universalify": "^2.0.0"
      },
      "engines": {
        "node": ">=10"
      }
    },
    "node_modules/graceful-fs": {
      "version": "4.2.11",
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
      "integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
      "license": "ISC"
    },
    "node_modules/jsonfile": {
      "version": "6.2.1",
      "resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.2.1.tgz",
      "integrity": "sha512-zwOTdL3rFQ/lRdBnntKVOX6k5cKJwEc1HdilT71BWEu7J41gXIB2MRp+vxduPSwZJPWBxEzv4yH1wYLJGUHX4Q==",
      "license": "MIT",
      "dependencies": {
        "universalify": "^2.0.0"
      },
      "optionalDependencies": {
        "graceful-fs": "^4.1.6"
      }
    },
    "node_modules/universalify": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.1.tgz",
      "integrity": "sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==",
      "license": "MIT",
      "engines": {
        "node": ">= 10.0.0"
      }
    }
  }
}

{
  "name": "sample-fs-extra-copy",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of fs-extra copy",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "fs-extra": "9.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify fs-extra.copy in pkg:npm/fs-extra@9.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/fs-extra@9.1.0"
  ],
  "symbols": [
    "fs-extra.copy"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const fs = require('fs-extra');

/**
 * Asynchronously copies a source file or directory to a destination path.
 */
async function copyPath(src, dest, options = {}) {
  await fs.copy(src, dest, options);
}

/**
 * Synchronously copies a source file or directory to a destination path.
 */
function copyPathSync(src, dest, options = {}) {
  fs.copySync(src, dest, options);
}

module.exports = {
  fs,
  copyPath,
  copyPathSync
};

import assert from 'node:assert';
import path from 'node:path';
import os from 'node:os';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const { fs, copyPath, copyPathSync } = require('../src/index.js');

async function runContract() {
  const tmpBase = path.join(os.tmpdir(), `csx-contract-fs-copy-${Date.now()}-${Math.random().toString(36).slice(2)}`);
  await fs.ensureDir(tmpBase);

  try {
    // 1. fs.copy asynchronously copies a single file to a target destination, creating parent directories if needed
    const singleSrc = path.join(tmpBase, 'single-source.txt');
    const singleDest = path.join(tmpBase, 'nested', 'target', 'single-dest.txt');
    const contentSingle = 'single file test content';
    await fs.outputFile(singleSrc, contentSingle, 'utf8');

    assert.strictEqual(await fs.pathExists(singleDest), false, 'Dest should not exist before copy');
    await copyPath(singleSrc, singleDest);
    assert.strictEqual(await fs.pathExists(singleDest), true, 'Dest must exist after copy');
    assert.strictEqual(await fs.readFile(singleDest, 'utf8'), contentSingle, 'Dest content must match source');

    // 2. fs.copy recursively copies an entire directory hierarchy preserving structure and content
    const treeSrc = path.join(tmpBase, 'tree-src');
    const treeDest = path.join(tmpBase, 'tree-dest');
    await fs.outputFile(path.join(treeSrc, 'root.txt'), 'root content', 'utf8');
    await fs.outputFile(path.join(treeSrc, 'level1', 'level1.txt'), 'level1 content', 'utf8');
    await fs.outputFile(path.join(treeSrc, 'level1', 'level2', 'level2.txt'), 'level2 content', 'utf8');

    await copyPath(treeSrc, treeDest);
    assert.strictEqual(await fs.readFile(path.join(treeDest, 'root.txt'), 'utf8'), 'root content');
    assert.strictEqual(await fs.readFile(path.join(treeDest, 'level1', 'level1.txt'), 'utf8'), 'level1 content');
    assert.strictEqual(await fs.readFile(path.join(treeDest, 'level1', 'level2', 'level2.txt'), 'utf8'), 'level2 content');

    // 3. fs.copy supports a filter function to selectively copy files and directories
    const filterSrc = path.join(tmpBase, 'filter-src');
    const filterDest = path.join(tmpBase, 'filter-dest');
    await fs.outputFile(path.join(filterSrc, 'keep.js'), 'console.log("keep");', 'utf8');
    await fs.outputFile(path.join(filterSrc, 'ignore.tmp'), 'ignore this', 'utf8');
    await fs.outputFile(path.join(filterSrc, 'sub', 'keep2.js'), 'console.log("keep2");', 'utf8');
    await fs.outputFile(path.join(filterSrc, 'sub', 'ignore2.tmp'), 'ignore this too', 'utf8');

    const filterFn = (src) => !src.endsWith('.tmp');
    await copyPath(filterSrc, filterDest, { filter: filterFn });

    assert.strictEqual(await fs.pathExists(path.join(filterDest, 'keep.js')), true, 'keep.js should exist');
    assert.strictEqual(await fs.pathExists(path.join(filterDest, 'sub', 'keep2.js')), true, 'keep2.js should exist');
    assert.strictEqual(await fs.pathExists(path.join(filterDest, 'ignore.tmp')), false, 'ignore.tmp should not exist');
    assert.strictEqual(await fs.pathExists(path.join(filterDest, 'sub', 'ignore2.tmp')), false, 'ignore2.tmp should not exist');

    // 4. fs.copy rejects with an error when overwrite is false and errorOnExist is true if destination exists
    const conflictSrc = path.join(tmpBase, 'conflict-src.txt');
    const conflictDest = path.join(tmpBase, 'conflict-dest.txt');
    await fs.outputFile(conflictSrc, 'conflict source', 'utf8');
    await fs.outputFile(conflictDest, 'conflict dest', 'utf8');

    await assert.rejects(
      async () => {
        await copyPath(conflictSrc, conflictDest, { overwrite: false, errorOnExist: true });
      },
      (err) => {
        assert.ok(err, 'Expected an error when destination already exists with errorOnExist=true');
        return true;
      }
    );

    // 5. fs.copy preserves timestamps when preserveTimestamps option is true
    const tsSrc = path.join(tmpBase, 'timestamp-src.txt');
    const tsDest = path.join(tmpBase, 'timestamp-dest.txt');
    await fs.outputFile(tsSrc, 'timestamp content', 'utf8');
    const pastTime = new Date('2021-06-15T10:00:00Z');
    await fs.utimes(tsSrc, pastTime, pastTime);

    await copyPath(tsSrc, tsDest, { preserveTimestamps: true });
    const statDest = await fs.stat(tsDest);
    const mtimeSec = Math.floor(statDest.mtimeMs / 1000);
    const expectedSec = Math.floor(pastTime.getTime() / 1000);
    assert.strictEqual(mtimeSec, expectedSec, 'Destination mtime must match source mtime when preserveTimestamps is true');

    // 6. fs.copySync synchronously copies directory structures and contents
    const syncSrc = path.join(tmpBase, 'sync-src');
    const syncDest = path.join(tmpBase, 'sync-dest');
    await fs.outputFile(path.join(syncSrc, 'data.txt'), 'sync content', 'utf8');

    copyPathSync(syncSrc, syncDest);
    assert.strictEqual(await fs.pathExists(path.join(syncDest, 'data.txt')), true, 'Sync copied file must exist immediately');
    assert.strictEqual(await fs.readFile(path.join(syncDest, 'data.txt'), 'utf8'), 'sync content');

    console.log('Contract tests passed successfully.');
  } finally {
    await fs.remove(tmpBase);
  }
}

runContract().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});