sealcode 0.1.0

package/src/seal.js

@@ -0,0 +1,174 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const fg = require('fast-glob');
+const { seal, opaqueName, sha256Hex } = require('./crypto');
+const { writeManifest } = require('./manifest');
+const {
+  SALT_NAME,
+  WRAP_PASS_NAME,
+  WRAP_RECOVERY_NAME,
+  MANIFEST_NAME,
+  persistBootstrap,
+} = require('./keystore');
+const {
+  ensureDir,
+  rmIfExists,
+  pruneEmptyDirs,
+  writeFileEnsuringDir,
+  nowIso,
+  normPath,
+} = require('./util');
+
+async function collectFiles(projectRoot, cfg) {
+  const matches = await fg(cfg.include, {
+    cwd: projectRoot,
+    ignore: cfg.exclude,
+    dot: true,
+    onlyFiles: true,
+    followSymbolicLinks: false,
+    suppressErrors: true,
+  });
+  return matches.map(normPath).sort();
+}
+
+function applyStubs(projectRoot, stubs) {
+  const written = {};
+  for (const [relPath, value] of Object.entries(stubs || {})) {
+    const target = path.join(projectRoot, relPath);
+    let contents;
+    let mode;
+    if (typeof value === 'string') {
+      contents = value;
+    } else if (value && typeof value === 'object' && typeof value.contents === 'string') {
+      contents = value.contents;
+      mode = value.mode;
+    } else {
+      throw new Error(`stub for ${relPath} must be string or { contents, mode? }`);
+    }
+    writeFileEnsuringDir(target, contents, mode);
+    written[relPath] = true;
+  }
+  return written;
+}
+
+/**
+ * Run lock (a.k.a. seal). Removes plaintext after writing the locked dir.
+ *
+ * @param {Object} opts
+ * @param {string} opts.projectRoot
+ * @param {Object} opts.config
+ * @param {Buffer} opts.K
+ * @param {Object} [opts.bootstrapOutput] - first-time init: { salt, wrappedPass, wrappedRecovery }
+ * @param {boolean} [opts.keepOriginals=false]
+ * @param {(msg:string)=>void} [opts.log]
+ */
+async function runLock({
+  projectRoot,
+  config,
+  K,
+  bootstrapOutput,
+  keepOriginals = false,
+  log = () => {},
+}) {
+  const lockedDir = config.lockedDir;
+  const lockedRoot = path.join(projectRoot, lockedDir);
+
+  const files = await collectFiles(projectRoot, config);
+  if (files.length === 0) {
+    throw new Error('SEALCODE_NOTHING_TO_LOCK');
+  }
+
+  // Preserve any existing keystore files when re-locking. On first init we
+  // wipe and persist the bootstrap output fresh.
+  const existingSalt = !bootstrapOutput && fs.existsSync(path.join(lockedRoot, SALT_NAME));
+  const existingPassWrap = !bootstrapOutput && fs.existsSync(path.join(lockedRoot, WRAP_PASS_NAME));
+  const existingRecoveryWrap =
+    !bootstrapOutput && fs.existsSync(path.join(lockedRoot, WRAP_RECOVERY_NAME));
+
+  const saved = {};
+  if (existingSalt) saved[SALT_NAME] = fs.readFileSync(path.join(lockedRoot, SALT_NAME));
+  if (existingPassWrap) saved[WRAP_PASS_NAME] = fs.readFileSync(path.join(lockedRoot, WRAP_PASS_NAME));
+  if (existingRecoveryWrap)
+    saved[WRAP_RECOVERY_NAME] = fs.readFileSync(path.join(lockedRoot, WRAP_RECOVERY_NAME));
+
+  rmIfExists(lockedRoot);
+  ensureDir(lockedRoot);
+
+  // Restore the keystore so the passphrase keeps working across re-locks.
+  for (const [name, buf] of Object.entries(saved)) {
+    const p = path.join(lockedRoot, name);
+    ensureDir(path.dirname(p));
+    fs.writeFileSync(p, buf);
+  }
+  if (bootstrapOutput) {
+    persistBootstrap(projectRoot, lockedDir, bootstrapOutput);
+  }
+
+  const manifestFiles = [];
+  const usedLockedNames = new Map();
+  const reservedNames = new Set([SALT_NAME, WRAP_PASS_NAME, WRAP_RECOVERY_NAME, MANIFEST_NAME]);
+
+  for (const rel of files) {
+    const abs = path.join(projectRoot, rel);
+    const stat = fs.statSync(abs);
+    const bytes = fs.readFileSync(abs);
+
+    const lockedRel = opaqueName(rel, K);
+    if (reservedNames.has(lockedRel)) {
+      // Astronomically unlikely (HMAC collision with public sentinel), but bail safely.
+      throw new Error(`opaque name collision with keystore sentinel for ${rel}`);
+    }
+    if (usedLockedNames.has(lockedRel) && usedLockedNames.get(lockedRel) !== rel) {
+      throw new Error(
+        `opaque-name collision for ${rel} vs ${usedLockedNames.get(lockedRel)} — please file a bug`
+      );
+    }
+    usedLockedNames.set(lockedRel, rel);
+
+    const lockedAbs = path.join(lockedRoot, lockedRel);
+    ensureDir(path.dirname(lockedAbs));
+    fs.writeFileSync(lockedAbs, seal(bytes, K));
+
+    manifestFiles.push({
+      p: rel,
+      l: lockedRel,
+      h: sha256Hex(bytes),
+      m: stat.mode & 0o777,
+      s: bytes.length,
+    });
+    log(`  locked ${rel}`);
+  }
+
+  const stubsApplied = applyStubs(projectRoot, config.stubs);
+
+  const manifest = {
+    v: 1,
+    sealedAt: nowIso(),
+    files: manifestFiles,
+    stubs: stubsApplied,
+    lockedDir,
+  };
+  writeManifest(projectRoot, lockedDir, manifest, K);
+
+  if (!keepOriginals) {
+    const stubSet = new Set(Object.keys(stubsApplied));
+    const dirsTouched = new Set();
+    for (const rel of files) {
+      if (stubSet.has(rel)) continue;
+      const abs = path.join(projectRoot, rel);
+      try {
+        fs.unlinkSync(abs);
+        dirsTouched.add(path.dirname(abs));
+      } catch (_) {
+        /* manifest is authoritative */
+      }
+    }
+    for (const d of dirsTouched) pruneEmptyDirs(d, projectRoot);
+  }
+
+  return { count: manifestFiles.length, lockedRoot, stubs: stubsApplied };
+}
+
+module.exports = { runLock, collectFiles };

package/src/status.js

@@ -0,0 +1,207 @@
+'use strict';
+
+/**
+ * `sealcode status` — answers two questions at a glance:
+ *   1. What state is this project in? (initialized? unlocked? locked?)
+ *   2. Has my local working tree drifted from the locked snapshot?
+ *
+ * Drift detection lets us warn: "You have 4 unsaved edits — run `sealcode
+ * lock` before committing." This is the single feature that prevents the
+ * most common footgun: committing a stale `vendor/` while plaintext sits
+ * one folder over.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readManifest } = require('./manifest');
+const { isInitialized, loadSession } = require('./keystore');
+const { sha256Hex } = require('./crypto');
+const { collectFiles } = require('./seal');
+
+/**
+ * Compute drift between the manifest on disk and plaintext files (unlocked tree).
+ * @param {string} projectRoot
+ * @param {object} config
+ * @param {Buffer} K
+ * @returns {Promise<{ added: string[], modified: string[], removed: string[] }>}
+ */
+async function computeDrift(projectRoot, config, K) {
+  const lockedDir = config.lockedDir;
+  const manifest = readManifest(projectRoot, lockedDir, K);
+  const stubKeys = new Set(Object.keys(manifest.stubs || {}));
+  const expected = new Map(manifest.files.map((f) => [f.p, f]));
+
+  const onDisk = await collectFiles(projectRoot, config);
+  const added = [];
+  const modified = [];
+  const removed = [];
+
+  for (const rel of onDisk) {
+    if (stubKeys.has(rel)) continue;
+    const entry = expected.get(rel);
+    if (!entry) {
+      added.push(rel);
+      continue;
+    }
+    const abs = path.join(projectRoot, rel);
+    const h = sha256Hex(fs.readFileSync(abs));
+    if (h !== entry.h) modified.push(rel);
+  }
+  for (const [rel] of expected) {
+    if (stubKeys.has(rel)) continue;
+    if (!onDisk.includes(rel)) removed.push(rel);
+  }
+  return { added, modified, removed };
+}
+
+async function runStatus({ projectRoot, config }) {
+  const lockedDir = config.lockedDir;
+  const lockedRoot = path.join(projectRoot, lockedDir);
+  const initialized = isInitialized(projectRoot, lockedDir);
+
+  const status = {
+    initialized,
+    lockedDir,
+    state: 'unknown',
+    lockedFileCount: 0,
+    onDiskFileCount: 0,
+    drift: null, // populated if we have K via session
+    sessionActive: false,
+  };
+
+  if (!initialized) {
+    status.state = 'uninitialized';
+    return status;
+  }
+
+  // Count locked blobs by reading the locked dir directly. We don't need K
+  // to do this — it's a quick file-system head count.
+  let locked = 0;
+  if (fs.existsSync(lockedRoot)) {
+    (function walk(dir) {
+      for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) walk(full);
+        else locked++;
+      }
+    })(lockedRoot);
+  }
+  status.lockedFileCount = locked;
+
+  const onDisk = await collectFiles(projectRoot, config);
+  status.onDiskFileCount = onDisk.length;
+
+  const K = loadSession(projectRoot);
+  status.sessionActive = K != null;
+
+  // For the locked/unlocked decision we discount any files that are explicitly
+  // declared as stubs in the config — those are placed BY the lock command and
+  // their presence doesn't mean the project is unlocked.
+  const stubSet = new Set(Object.keys(config.stubs || {}));
+  const nonStubOnDisk = onDisk.filter((p) => !stubSet.has(p));
+
+  if (nonStubOnDisk.length === 0) {
+    status.state = 'locked';
+  } else if (locked === 0) {
+    status.state = 'unlocked-no-vault';
+  } else {
+    status.state = 'unlocked';
+  }
+
+  // Drift only makes sense when the project is unlocked. In the locked state
+  // the manifest's `files` deliberately aren't on disk — reporting that as
+  // "removed" would be misleading.
+  if (K && status.state === 'unlocked') {
+    try {
+      status.drift = await computeDrift(projectRoot, config, K);
+    } catch (_) {
+      status.sessionActive = false;
+    }
+  }
+
+  return status;
+}
+
+function renderStatus(status) {
+  const lines = [];
+  if (!status.initialized) {
+    lines.push('  ⚠  No vault here yet.');
+    lines.push('     Run:  sealcode init');
+    return lines.join('\n');
+  }
+  const state = status.state;
+  const stateIcon =
+    state === 'locked' ? '🔒' : state === 'unlocked' ? '🔓' : state === 'unlocked-no-vault' ? '?' : '·';
+  lines.push(`  ${stateIcon}  ${state}`);
+  lines.push(`     locked blobs:    ${status.lockedFileCount}`);
+  if (status.state !== 'locked') {
+    lines.push(`     plaintext files: ${status.onDiskFileCount}`);
+  }
+  lines.push(`     session:         ${status.sessionActive ? 'active (no passphrase needed)' : 'idle'}`);
+  if (status.drift) {
+    const { added, modified, removed } = status.drift;
+    const total = added.length + modified.length + removed.length;
+    if (total === 0) {
+      lines.push('     drift:           none — locked snapshot matches working tree');
+    } else {
+      lines.push(`     drift:           ${total} change(s) vs last lock`);
+      if (added.length) lines.push(`       + ${added.length} added`);
+      if (modified.length) lines.push(`       ~ ${modified.length} modified`);
+      if (removed.length) lines.push(`       - ${removed.length} removed`);
+      lines.push('     →  run `sealcode lock` before committing');
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Pre-commit / CI gate: pass only if locked, or unlocked with no drift.
+ * Caller supplies `getK` — session load, env passphrase unwrap, or null.
+ * @param {( ) => Promise<Buffer|null>} getK
+ */
+async function runPrecommitCheck(projectRoot, config, getK) {
+  const s = await runStatus({ projectRoot, config });
+  if (!s.initialized) return { ok: true, message: '' };
+  if (s.state === 'locked') return { ok: true, message: '' };
+  if (s.state === 'unlocked-no-vault') {
+    return {
+      ok: false,
+      message:
+        'sealcode: locked directory is missing. Restore `vendor/` (or your preset folder) before committing.',
+    };
+  }
+
+  const K = await getK();
+  if (!K) {
+    return {
+      ok: false,
+      message:
+        'sealcode: project is unlocked but there is no session key.\n' +
+        '  Fix: run `sealcode unlock` once in this terminal, or set SEALCODE_PASSPHRASE,\n' +
+        '  or run `sealcode lock` to seal before you commit.',
+    };
+  }
+
+  let drift;
+  try {
+    drift = await computeDrift(projectRoot, config, K);
+  } catch (err) {
+    return {
+      ok: false,
+      message: `sealcode: cannot read manifest (${err.message}). Try \`sealcode logout\` then \`sealcode unlock\`.`,
+    };
+  }
+
+  const total = drift.added.length + drift.modified.length + drift.removed.length;
+  if (total > 0) {
+    return {
+      ok: false,
+      message:
+        `sealcode: working tree drift vs last lock (+${drift.added.length} ~${drift.modified.length} -${drift.removed.length}).\n` +
+        '  Run `sealcode lock` then stage the updated blobs, or discard changes.',
+    };
+  }
+  return { ok: true, message: '' };
+}
+
+module.exports = { runStatus, renderStatus, computeDrift, runPrecommitCheck };

package/src/ui.js

@@ -0,0 +1,270 @@
+'use strict';
+
+/**
+ * Tiny zero-dep UI helpers for the sealcode CLI.
+ *
+ * Design rules:
+ *   - Respect `NO_COLOR` and `!process.stdout.isTTY` — degrade to plain text.
+ *   - Spinners/progress write to stderr so `sealcode status | grep …` still works.
+ *   - Never throw from a UI helper; UI noise must not crash a real command.
+ *   - Use direct ANSI escapes; do not pull in chalk/ora/boxen/cli-progress.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const STDOUT_TTY = process.stdout.isTTY === true;
+const STDERR_TTY = process.stderr.isTTY === true;
+const USE_COLOR = STDOUT_TTY && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
+
+function wrap(code, str) {
+  return USE_COLOR ? `\x1b[${code}m${str}\x1b[0m` : String(str);
+}
+
+const c = {
+  dim:     (s) => wrap('2', s),
+  bold:    (s) => wrap('1', s),
+  green:   (s) => wrap('32', s),
+  red:     (s) => wrap('31', s),
+  yellow:  (s) => wrap('33', s),
+  cyan:    (s) => wrap('36', s),
+  magenta: (s) => wrap('35', s),
+  blue:    (s) => wrap('34', s),
+  gray:    (s) => wrap('90', s),
+};
+
+const sym = {
+  ok:     USE_COLOR ? c.green('✓') : 'OK ',
+  err:    USE_COLOR ? c.red('✗') : 'ERR',
+  warn:   USE_COLOR ? c.yellow('⚠') : '!  ',
+  arrow:  USE_COLOR ? c.cyan('→') : '->',
+  bullet: '•',
+  spin:   ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+};
+
+function say(line = '') { process.stdout.write(line + '\n'); }
+function ok(msg)   { say(`${sym.ok} ${msg}`); }
+function fail(msg) { say(`${sym.err} ${msg}`); }
+function warn(msg) { say(`${sym.warn} ${msg}`); }
+function hint(msg) { say(c.dim(msg)); }
+function step(msg) { say(`${sym.arrow} ${msg}`); }
+
+function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function visibleLen(s) {
+  return stripAnsi(s).length;
+}
+
+/** Animated spinner. No-op in non-TTY env (just prints a single line). */
+class Spinner {
+  constructor(label) {
+    this.label = label;
+    this.frame = 0;
+    this.timer = null;
+    this.startTime = 0;
+  }
+  start() {
+    if (!STDERR_TTY) {
+      process.stderr.write(`${this.label}...\n`);
+      return this;
+    }
+    this.startTime = Date.now();
+    process.stderr.write('\x1b[?25l'); // hide cursor
+    const tick = () => {
+      const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
+      const glyph = USE_COLOR ? c.cyan(sym.spin[this.frame % sym.spin.length]) : '*';
+      process.stderr.write(
+        `\r${glyph} ${this.label} ${c.dim(`${elapsed}s`)}\x1b[K`,
+      );
+      this.frame += 1;
+    };
+    tick();
+    this.timer = setInterval(tick, 80);
+    return this;
+  }
+  update(label) {
+    this.label = label;
+  }
+  succeed(msg) {
+    this._stop();
+    const finalText = msg || this.label;
+    if (STDERR_TTY) process.stderr.write(`\r${sym.ok} ${finalText}\x1b[K\n`);
+    else process.stderr.write(`${finalText} OK\n`);
+  }
+  fail(msg) {
+    this._stop();
+    const finalText = msg || this.label;
+    if (STDERR_TTY) process.stderr.write(`\r${sym.err} ${finalText}\x1b[K\n`);
+    else process.stderr.write(`${finalText} FAIL\n`);
+  }
+  stop() {
+    this._stop();
+    if (STDERR_TTY) process.stderr.write('\r\x1b[K');
+  }
+  _stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    if (STDERR_TTY) process.stderr.write('\x1b[?25h'); // show cursor
+  }
+}
+
+/**
+ * Run `fn` with a spinner; succeeds on resolve, fails on reject.
+ * `fn` receives the spinner so it can `sp.update("...")` mid-flight.
+ */
+async function withSpinner(label, fn) {
+  const sp = new Spinner(label).start();
+  try {
+    const v = await fn(sp);
+    sp.succeed();
+    return v;
+  } catch (e) {
+    sp.fail();
+    throw e;
+  }
+}
+
+/**
+ * Progress bar for file batches. No-op when not a TTY or for tiny batches.
+ *   const bar = makeProgress(files.length, 'Encrypting');
+ *   for (const f of files) { …; bar.tick(f); }
+ *   bar.done('Encrypted 47 files');
+ */
+function makeProgress(total, label = 'Working') {
+  if (!STDERR_TTY || total < 2) {
+    let n = 0;
+    return {
+      tick() { n += 1; },
+      done(msg) { if (msg) ok(msg); },
+    };
+  }
+  let n = 0;
+  const width = 24;
+  return {
+    tick(currentLabel) {
+      n += 1;
+      const filled = Math.max(0, Math.min(width, Math.round((n / total) * width)));
+      const bar = '█'.repeat(filled) + '░'.repeat(width - filled);
+      const pct = `${n}/${total}`.padStart(`${total}/${total}`.length);
+      const trail = currentLabel ? `  ${c.dim(truncatePath(String(currentLabel), 40))}` : '';
+      const head = USE_COLOR ? c.cyan(bar) : bar;
+      process.stderr.write(`\r${head} ${pct} ${c.dim(label)}${trail}\x1b[K`);
+    },
+    done(msg) {
+      process.stderr.write('\r\x1b[K');
+      if (msg) ok(msg);
+    },
+  };
+}
+
+function truncatePath(s, max) {
+  if (s.length <= max) return s;
+  return '…' + s.slice(-(max - 1));
+}
+
+/**
+ * Framed box for important blocks (welcome, access codes). Pass plain text or
+ * pre-colored strings; we measure visible length, not byte length.
+ */
+function box(title, lines, { tone = 'cyan' } = {}) {
+  if (!STDOUT_TTY) {
+    // No box in piped/CI output — just print contents flat.
+    say('');
+    if (title) say(title);
+    for (const l of lines) say(typeof l === 'string' ? stripAnsi(l) : '');
+    say('');
+    return;
+  }
+  const color = c[tone] || ((s) => s);
+  const allLines = Array.isArray(lines) ? lines : [lines];
+  const titleVis = title ? visibleLen(title) : 0;
+  const inner = Math.max(40, titleVis, ...allLines.map((l) => visibleLen(l)));
+  const horizontal = '─'.repeat(inner + 2);
+
+  say('');
+  say(color(`╭${horizontal}╮`));
+  if (title) {
+    const padded = ' '.repeat(inner - titleVis);
+    say(color('│ ') + c.bold(title) + padded + color(' │'));
+    say(color(`├${horizontal}┤`));
+  }
+  for (const line of allLines) {
+    const visible = visibleLen(line);
+    const padded = ' '.repeat(Math.max(0, inner - visible));
+    say(color('│ ') + line + padded + color(' │'));
+  }
+  say(color(`╰${horizontal}╯`));
+  say('');
+}
+
+/** Branded one-liner. Appears at the top of `--help`. */
+function banner(version) {
+  const left = c.bold(c.cyan('sealcode'));
+  const right = c.dim(`v${version}  ·  lock your source code`);
+  return `${left}  ${right}`;
+}
+
+/**
+ * Show a welcome box the first time the user invokes the CLI with no args
+ * (i.e. they just installed it and ran `sealcode`). After the first show,
+ * touch a sentinel so we never spam them again.
+ */
+function maybeShowWelcome(version) {
+  const dir = path.join(os.homedir(), '.sealcode');
+  const sentinel = path.join(dir, '.welcomed');
+  try {
+    if (fs.existsSync(sentinel)) return false;
+  } catch (_) {
+    return false;
+  }
+
+  box('Welcome to sealcode', [
+    c.dim('Lock the source files in your repo so AI agents,'),
+    c.dim("scrapers, and people without your passphrase can't read them."),
+    '',
+    `${sym.arrow} ${c.bold('sealcode init')}        ${c.dim('set up this project')}`,
+    `${sym.arrow} ${c.bold('sealcode lock')}        ${c.dim('encrypt your source')}`,
+    `${sym.arrow} ${c.bold('sealcode unlock')}      ${c.dim('decrypt it back')}`,
+    `${sym.arrow} ${c.bold('sealcode login')}       ${c.dim('pair with sealcode.dev (optional)')}`,
+    '',
+    c.dim(`docs: https://sealcode.dev/docs   ·   v${version}`),
+  ]);
+
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(sentinel, new Date().toISOString());
+  } catch (_) {
+    /* never fail because of the welcome marker */
+  }
+  return true;
+}
+
+module.exports = {
+  // primitives
+  c,
+  sym,
+  // output helpers
+  say,
+  ok,
+  fail,
+  warn,
+  hint,
+  step,
+  // components
+  Spinner,
+  withSpinner,
+  makeProgress,
+  box,
+  banner,
+  maybeShowWelcome,
+  // capability flags
+  STDOUT_TTY,
+  STDERR_TTY,
+  USE_COLOR,
+  // util
+  stripAnsi,
+  visibleLen,
+};

package/src/util.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function rmIfExists(p) {
+  if (fs.existsSync(p)) fs.rmSync(p, { recursive: true, force: true });
+}
+
+function pruneEmptyDirs(dir, root) {
+  if (!fs.existsSync(dir) || dir === root) return;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (_) {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry);
+    const stat = fs.lstatSync(full);
+    if (stat.isDirectory()) pruneEmptyDirs(full, root);
+  }
+  try {
+    if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir);
+  } catch (_) {
+    /* ignore */
+  }
+}
+
+function writeFileEnsuringDir(filePath, contents, mode) {
+  ensureDir(path.dirname(filePath));
+  const opts = mode != null ? { mode } : undefined;
+  fs.writeFileSync(filePath, contents, opts);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+/**
+ * Normalize any path to forward slashes so opaque-name derivation matches
+ * across OSes. Use whenever a path will be hashed or compared.
+ */
+function normPath(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+module.exports = {
+  ensureDir,
+  rmIfExists,
+  pruneEmptyDirs,
+  writeFileEnsuringDir,
+  nowIso,
+  normPath,
+};