fs-extra 11.3.1

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/fs-extra@11.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/fs-extra@11.3.1
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:5a09c09aa4cc7acff09cfaae4d06c5ad57925336feb088af7c2c3f06ffe4e54e","constraints":{"executionContext":"node"},"contract":["ensureDir creates nested directory structures if they do not exist","outputJson and readJson write and read JSON documents while automatically creating parent directories","outputFile writes string data creating parent directories automatically and readFile retrieves the written content","copy recursively copies directory hierarchies and supports custom filter functions","emptyDir deletes all contents within a directory while leaving the directory itself intact","pathExists accurately checks the existence of files and directories","remove recursively removes directories and files without throwing if the target does not exist","move moves files and directories across paths with optional overwrite","ensureFile creates an empty file and its parent directories if it does not already exist"],"goal":"verify pkg:npm/fs-extra@11.3.1","kind":"HOW","packages":["pkg:npm/fs-extra@11.3.1"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"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@11.3.1"],"schemaVersion":1,"verifierAdapter":"node-typescript@1"}

{
  "name": "fs-extra-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "fs-extra-sample",
      "version": "1.0.0",
      "dependencies": {
        "fs-extra": "11.3.1"
      }
    },
    "node_modules/fs-extra": {
      "version": "11.3.1",
      "resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-11.3.1.tgz",
      "integrity": "sha512-eXvGGwZ5CL17ZSwHWd3bbgk7UUpF6IFHtP57NYYakPvHOs8GDgDe5KJI36jIJzDkJ6eJjuzRA8eBQb6SkKue0g==",
      "license": "MIT",
      "dependencies": {
        "graceful-fs": "^4.2.0",
        "jsonfile": "^6.0.1",
        "universalify": "^2.0.0"
      },
      "engines": {
        "node": ">=14.14"
      }
    },
    "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": "fs-extra-sample",
  "version": "1.0.0",
  "dependencies": {
    "fs-extra": "11.3.1"
  }
}

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

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

/**
 * Ensures that the directory exists. If the directory structure does not exist, it is created.
 *
 * @param {string} dirPath - Directory path to ensure.
 * @returns {Promise<void>}
 */
async function ensureDirectory(dirPath) {
  await fse.ensureDir(dirPath);
}

/**
 * Writes an object to a JSON file, creating directories if necessary.
 *
 * @param {string} filePath - Path of JSON file.
 * @param {object} data - Object to serialize.
 * @param {object} [options] - Pass-through options for jsonfile / fs-extra.
 * @returns {Promise<void>}
 */
async function outputJsonFile(filePath, data, options) {
  await fse.outputJson(filePath, data, options);
}

/**
 * Reads a JSON file and then parses it into an object.
 *
 * @param {string} filePath - Path of JSON file.
 * @returns {Promise<any>}
 */
async function readJsonFile(filePath) {
  return await fse.readJson(filePath);
}

/**
 * Writes data to a file, creating directories if necessary.
 *
 * @param {string} filePath - Path of file.
 * @param {string|Buffer} data - Data to write.
 * @returns {Promise<void>}
 */
async function outputFileContent(filePath, data) {
  await fse.outputFile(filePath, data);
}

/**
 * Reads data from a file using UTF-8 encoding.
 *
 * @param {string} filePath - Path of file.
 * @returns {Promise<string>}
 */
async function readFileContent(filePath) {
  return await fse.readFile(filePath, 'utf8');
}

/**
 * Copies a file or directory recursively.
 *
 * @param {string} src - Source file or directory path.
 * @param {string} dest - Destination file or directory path.
 * @param {object} [options] - Copy options such as overwrite and filter.
 * @returns {Promise<void>}
 */
async function copyDirectory(src, dest, options) {
  await fse.copy(src, dest, options);
}

/**
 * Ensures that a directory is empty by deleting all items inside it while preserving the directory itself.
 *
 * @param {string} dirPath - Directory path to empty.
 * @returns {Promise<void>}
 */
async function emptyDirectory(dirPath) {
  await fse.emptyDir(dirPath);
}

/**
 * Tests whether or not the given path exists.
 *
 * @param {string} targetPath - Path to test.
 * @returns {Promise<boolean>}
 */
async function checkPathExists(targetPath) {
  return await fse.pathExists(targetPath);
}

/**
 * Removes a file or directory recursively.
 *
 * @param {string} targetPath - Path to remove.
 * @returns {Promise<void>}
 */
async function removePath(targetPath) {
  await fse.remove(targetPath);
}

/**
 * Moves a file or directory, even across devices.
 *
 * @param {string} src - Source path.
 * @param {string} dest - Destination path.
 * @param {object} [options] - Move options (e.g. { overwrite: true }).
 * @returns {Promise<void>}
 */
async function movePath(src, dest, options) {
  await fse.move(src, dest, options);
}

/**
 * Ensures that a file exists. If the file that is requested to be created is in directories that do not exist,
 * these directories are created. If the file already exists, it is not modified.
 *
 * @param {string} filePath - Path of file to ensure.
 * @returns {Promise<void>}
 */
async function ensureFileExists(filePath) {
  await fse.ensureFile(filePath);
}

module.exports = {
  ensureDirectory,
  outputJsonFile,
  readJsonFile,
  outputFileContent,
  readFileContent,
  copyDirectory,
  emptyDirectory,
  checkPathExists,
  removePath,
  movePath,
  ensureFileExists,
  fse,
};

const assert = require('node:assert/strict');
const path = require('node:path');
const os = require('node:os');
const fs = require('node:fs');
const {
  ensureDirectory,
  outputJsonFile,
  readJsonFile,
  outputFileContent,
  readFileContent,
  copyDirectory,
  emptyDirectory,
  checkPathExists,
  removePath,
  movePath,
  ensureFileExists,
} = require('../src/index.js');

async function main() {
  const testRoot = path.join(
    os.tmpdir(),
    `fs-extra-v11-contract-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
  );

  try {
    // Contract 1: ensureDir creates nested directory structures if they do not exist
    {
      const nestedDir = path.join(testRoot, 'deep', 'nested', 'structure');
      assert.strictEqual(await checkPathExists(nestedDir), false);

      await ensureDirectory(nestedDir);
      assert.strictEqual(await checkPathExists(nestedDir), true);
      assert.strictEqual(fs.statSync(nestedDir).isDirectory(), true);

      // Calling ensureDir on an already existing directory should be a safe no-op
      await ensureDirectory(nestedDir);
      assert.strictEqual(await checkPathExists(nestedDir), true);
    }

    // Contract 2: outputJson and readJson write and read JSON documents while automatically creating parent directories
    {
      const jsonFile = path.join(testRoot, 'config', 'nested', 'settings.json');
      const payload = { name: 'codesamplex', version: 11, active: true, items: [1, 2, 3] };

      assert.strictEqual(await checkPathExists(jsonFile), false);
      await outputJsonFile(jsonFile, payload, { spaces: 2 });

      assert.strictEqual(await checkPathExists(jsonFile), true);
      const readBack = await readJsonFile(jsonFile);
      assert.deepStrictEqual(readBack, payload, 'readJson output must match written payload');
    }

    // Contract 3: outputFile writes string data creating parent directories automatically and readFile retrieves the written content
    {
      const textFile = path.join(testRoot, 'docs', 'auto-parent', 'readme.txt');
      const content = 'Clean-room public code sample for fs-extra 11.3.1';

      assert.strictEqual(await checkPathExists(textFile), false);
      await outputFileContent(textFile, content);

      assert.strictEqual(await checkPathExists(textFile), true);
      const retrieved = await readFileContent(textFile);
      assert.strictEqual(retrieved, content, 'readFile output must match written string');
    }

    // Contract 4: copy recursively copies directory hierarchies and supports custom filter functions
    {
      const srcDir = path.join(testRoot, 'source_tree');
      const destDir = path.join(testRoot, 'dest_tree');

      await outputFileContent(path.join(srcDir, 'included.txt'), 'keep');
      await outputFileContent(path.join(srcDir, 'excluded.tmp'), 'skip');
      await outputFileContent(path.join(srcDir, 'sub', 'nested.txt'), 'nested keep');

      await copyDirectory(srcDir, destDir, {
        filter: (src) => !src.endsWith('.tmp'),
      });

      assert.strictEqual(await checkPathExists(path.join(destDir, 'included.txt')), true);
      assert.strictEqual(await checkPathExists(path.join(destDir, 'sub', 'nested.txt')), true);
      assert.strictEqual(await checkPathExists(path.join(destDir, 'excluded.tmp')), false);

      const copiedContent = await readFileContent(path.join(destDir, 'sub', 'nested.txt'));
      assert.strictEqual(copiedContent, 'nested keep');
    }

    // Contract 5: emptyDir deletes all contents within a directory while leaving the directory itself intact
    {
      const emptyTarget = path.join(testRoot, 'empty_target');
      await outputFileContent(path.join(emptyTarget, 'f1.txt'), '1');
      await outputFileContent(path.join(emptyTarget, 'sub', 'f2.txt'), '2');

      assert.strictEqual(await checkPathExists(emptyTarget), true);
      assert.ok(fs.readdirSync(emptyTarget).length > 0);

      await emptyDirectory(emptyTarget);

      assert.strictEqual(await checkPathExists(emptyTarget), true);
      assert.strictEqual(fs.readdirSync(emptyTarget).length, 0);
    }

    // Contract 6: pathExists accurately checks the existence of files and directories
    {
      const missingPath = path.join(testRoot, `missing_${Date.now()}`);
      assert.strictEqual(await checkPathExists(missingPath), false);

      const existingPath = path.join(testRoot, 'existing_check.json');
      await outputJsonFile(existingPath, { exists: true });
      assert.strictEqual(await checkPathExists(existingPath), true);
    }

    // Contract 7: remove recursively removes directories and files without throwing if the target does not exist
    {
      const removeDir = path.join(testRoot, 'to_be_removed');
      await outputFileContent(path.join(removeDir, 'child.txt'), 'bye');
      assert.strictEqual(await checkPathExists(removeDir), true);

      await removePath(removeDir);
      assert.strictEqual(await checkPathExists(removeDir), false);

      // Removing non-existent path must succeed silently without throwing
      await removePath(removeDir);
      assert.strictEqual(await checkPathExists(removeDir), false);
    }

    // Contract 8: move moves files and directories across paths with optional overwrite
    {
      const originFile = path.join(testRoot, 'origin', 'move_me.txt');
      const targetFile = path.join(testRoot, 'target', 'moved.txt');

      await outputFileContent(originFile, 'moving payload');
      assert.strictEqual(await checkPathExists(originFile), true);
      assert.strictEqual(await checkPathExists(targetFile), false);

      await movePath(originFile, targetFile);

      assert.strictEqual(await checkPathExists(originFile), false);
      assert.strictEqual(await checkPathExists(targetFile), true);
      const movedContent = await readFileContent(targetFile);
      assert.strictEqual(movedContent, 'moving payload');
    }

    // Contract 9: ensureFile creates an empty file and its parent directories if it does not already exist
    {
      const targetFile = path.join(testRoot, 'deeply', 'nested', 'file', 'created.txt');
      assert.strictEqual(await checkPathExists(targetFile), false);

      await ensureFileExists(targetFile);
      assert.strictEqual(await checkPathExists(targetFile), true);
      assert.strictEqual(fs.statSync(targetFile).isFile(), true);
      assert.strictEqual(fs.readFileSync(targetFile, 'utf8'), '');

      // Calling ensureFile on an already existing file should not truncate it
      fs.writeFileSync(targetFile, 'existing content');
      await ensureFileExists(targetFile);
      assert.strictEqual(fs.readFileSync(targetFile, 'utf8'), 'existing content');
    }

    console.log('All pkg:npm/fs-extra@11.3.1 contracts passed successfully.');
  } finally {
    try {
      await removePath(testRoot);
    } catch (_) {}
  }
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});