external-editor 3.1.0: edit, editAsync, ExternalEditor

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/external-editor@3.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/external-editor@3.1.0

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:3ada17c9cddae6001a6f8bc19b4d36e6fa736920ae056e57cf236cae582ac9b6","contract":["assert ExternalEditor creates temporary file with custom options and captures modified content on run","assert edit synchronously opens configured editor and returns modified text","assert editAsync asynchronously opens configured editor and invokes callback with result","assert ExternalEditor throws CreateFileError when given invalid directory","assert ExternalEditor throws ReadFileError when temporary file is removed before reading","assert ExternalEditor throws RemoveFileError when temporary file cannot be cleaned up"],"goal":"verify pkg:npm/external-editor@3.1.0","kind":"HOW","packages":["pkg:npm/external-editor@3.1.0"],"schemaVersion":1,"symbols":["external-editor","external-editor.edit","external-editor.editAsync","external-editor.ExternalEditor"]},"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/external-editor@3.1.0"],"schemaVersion":1,"subject":"pkg:npm/external-editor@3.1.0","symbols":["external-editor","external-editor.edit","external-editor.editAsync","external-editor.ExternalEditor"],"verifierAdapter":"node-typescript@1"}

const {
  ExternalEditor,
  edit,
  editAsync,
  CreateFileError,
  LaunchEditorError,
  ReadFileError,
  RemoveFileError,
} = require('external-editor');

/**
 * Edit text synchronously using external-editor.
 *
 * @param {string} [text]
 * @param {object} [fileOptions]
 * @returns {string}
 */
function editText(text, fileOptions) {
  return edit(text, fileOptions);
}

/**
 * Edit text asynchronously using external-editor.
 *
 * @param {string} text
 * @param {function} callback
 * @param {object} [fileOptions]
 */
function editTextAsync(text, callback, fileOptions) {
  editAsync(text, callback, fileOptions);
}

module.exports = {
  ExternalEditor,
  edit,
  editAsync,
  editText,
  editTextAsync,
  CreateFileError,
  LaunchEditorError,
  ReadFileError,
  RemoveFileError,
};

{
  "name": "sample-external-editor",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-external-editor",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "external-editor": "3.1.0"
      }
    },
    "node_modules/chardet": {
      "version": "0.7.0",
      "resolved": "https://registry.npmjs.org/chardet/-/chardet-0.7.0.tgz",
      "integrity": "sha512-mT8iDcrh03qDGRRmoA2hmBJnxpllMR+0/0qlzjqZES6NdiWDcZkCNAk4rPFZ9Q85r27unkiNNg8ZOiwZXBHwcA==",
      "license": "MIT"
    },
    "node_modules/external-editor": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/external-editor/-/external-editor-3.1.0.tgz",
      "integrity": "sha512-hMQ4CX1p1izmuLYyZqLMO/qGNw10wSv9QDCPfzXfyFrOaCSSoRfqE1Kf1s5an66J5JZC62NewG+mK49jOCtQew==",
      "license": "MIT",
      "dependencies": {
        "chardet": "^0.7.0",
        "iconv-lite": "^0.4.24",
        "tmp": "^0.0.33"
      },
      "engines": {
        "node": ">=4"
      }
    },
    "node_modules/iconv-lite": {
      "version": "0.4.24",
      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.4.24.tgz",
      "integrity": "sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==",
      "license": "MIT",
      "dependencies": {
        "safer-buffer": ">= 2.1.2 < 3"
      },
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/os-tmpdir": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/os-tmpdir/-/os-tmpdir-1.0.2.tgz",
      "integrity": "sha512-D2FR03Vir7FIu45XBY20mTb+/ZSWB00sjU9jdQXt83gDrI4Ztz5Fs7/yy74g2N5SVQY4xY1qDr4rNddwYRVX0g==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/safer-buffer": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
      "license": "MIT"
    },
    "node_modules/tmp": {
      "version": "0.0.33",
      "resolved": "https://registry.npmjs.org/tmp/-/tmp-0.0.33.tgz",
      "integrity": "sha512-jRCJlojKnZ3addtTOjdIqoRuPEKBvNXcGYqzO6zWZX8KfKEpnGY5jfggJQ3EjKuu8D4bJRr0y+cYJFmYbImXGw==",
      "license": "MIT",
      "dependencies": {
        "os-tmpdir": "~1.0.2"
      },
      "engines": {
        "node": ">=0.6.0"
      }
    }
  }
}

{
  "name": "sample-external-editor",
  "version": "1.0.0",
  "description": "Clean-room sample verifying pkg:npm/external-editor@3.1.0 functionality",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "external-editor": "3.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/external-editor@3.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/external-editor@3.1.0"
  ]
}

import assert from 'node:assert';
import fs from 'node:fs';
import externalEditorPkg from 'external-editor';
const { ExternalEditor, edit, editAsync, CreateFileError, ReadFileError, RemoveFileError } = externalEditorPkg;
import indexPkg from '../index.js';
const { editText, editTextAsync } = indexPkg;

// Configure mock editor using node -e with inline command (no spaces in script arg)
process.env.VISUAL = 'node -e require("fs").appendFileSync(process.argv[1],"-edited")';
delete process.env.EDITOR;

// 1. Assert ExternalEditor creates temporary file with custom options and captures modified content on run
{
  const editor = new ExternalEditor('hello world', { prefix: 'test-', postfix: '.txt' });
  assert.strictEqual(editor.text, 'hello world', 'Initial text should match input');
  assert.ok(fs.existsSync(editor.tempFile), 'Temporary file should exist after initialization');
  assert.ok(editor.tempFile.endsWith('.txt'), 'Temporary file should respect postfix option');
  assert.strictEqual(fs.readFileSync(editor.tempFile, 'utf8'), 'hello world', 'Temporary file content should match initial text');

  const edited = editor.run();
  assert.strictEqual(edited, 'hello world-edited', 'run() should return edited file content');
  assert.strictEqual(editor.text, 'hello world-edited', 'editor.text property should reflect changes');
  assert.strictEqual(editor.lastExitStatus, 0, 'lastExitStatus should be 0 on clean exit');

  editor.cleanup();
  assert.ok(!fs.existsSync(editor.tempFile), 'Temporary file should be removed after cleanup');
}

// 2. Assert edit synchronously opens configured editor and returns modified text
{
  const directResult = edit('sync input text');
  assert.strictEqual(directResult, 'sync input text-edited', 'edit() should return modified text synchronously');

  const wrapperResult = editText('wrapper input text');
  assert.strictEqual(wrapperResult, 'wrapper input text-edited', 'editText() helper should return modified text');
}

// 3. Assert editAsync asynchronously opens configured editor and invokes callback with result
{
  await new Promise((resolve, reject) => {
    editAsync('async input text', (err, result) => {
      if (err) return reject(err);
      try {
        assert.strictEqual(result, 'async input text-edited', 'editAsync should return modified text to callback');
        resolve();
      } catch (assertionErr) {
        reject(assertionErr);
      }
    });
  });

  await new Promise((resolve, reject) => {
    editTextAsync('wrapper async input', (err, result) => {
      if (err) return reject(err);
      try {
        assert.strictEqual(result, 'wrapper async input-edited', 'editTextAsync helper should return modified text');
        resolve();
      } catch (assertionErr) {
        reject(assertionErr);
      }
    });
  });
}

// 4. Assert ExternalEditor throws CreateFileError when given invalid directory
{
  assert.throws(
    () => {
      new ExternalEditor('content', { dir: '/nonexistent_dir_cannot_create_tmp_file_12345' });
    },
    (err) => {
      assert.ok(err instanceof CreateFileError, 'Error should be an instance of CreateFileError');
      assert.ok(err.originalError, 'Error should include originalError');
      return true;
    },
    'Should throw CreateFileError for invalid directory'
  );
}

// 5. Assert ExternalEditor throws ReadFileError when temporary file is removed before reading
{
  process.env.VISUAL = 'node -e require("fs").unlinkSync(process.argv[1])';
  const editor = new ExternalEditor('text to unlink');
  assert.throws(
    () => {
      editor.run();
    },
    (err) => {
      assert.ok(err instanceof ReadFileError, 'Error should be an instance of ReadFileError');
      assert.ok(err.originalError, 'Error should include originalError');
      return true;
    },
    'Should throw ReadFileError when temp file is unreadable'
  );
  process.env.VISUAL = 'node -e require("fs").appendFileSync(process.argv[1],"-edited")';
}

// 6. Assert ExternalEditor throws RemoveFileError when temporary file cannot be cleaned up
{
  const editor = new ExternalEditor('text for cleanup error');
  fs.unlinkSync(editor.tempFile);
  assert.throws(
    () => {
      editor.cleanup();
    },
    (err) => {
      assert.ok(err instanceof RemoveFileError, 'Error should be an instance of RemoveFileError');
      assert.ok(err.originalError, 'Error should include originalError');
      return true;
    },
    'Should throw RemoveFileError when file is unlinked before cleanup'
  );
}

console.log('All external-editor contract assertions passed.');