create-wxl 0.0.0-stage → 3.1.0

package/src/run.mjs

@@ -0,0 +1,437 @@
+import { dirname, resolve as resolvePath } from 'node:path'
+import { createHash } from 'node:crypto'
+import { messages, cwE12FinishingCommandsList } from './messages.mjs'
+import { jsonValue } from './text.mjs'
+import { selectLanguage } from './language.mjs'
+import { parseArgvStrict, ArgvError, SETUP_FLAG_NAMES } from './argv.mjs'
+import { checkTarget, moveIntoPlace, MoveIntoPlaceError } from './fsops.mjs'
+import { isNodeVersionOk, MINIMUM_NODE_VERSION } from './node-version.mjs'
+import { makeQuestioner, QuestionEofError, buildEngineArgv, missingRequiredFlags, collectInteractiveAnswers } from './questions.mjs'
+import { runGitSteps, orderedPrintedForms } from './git-steps.mjs'
+import { buildNextSteps } from './next-steps.mjs'
+import { createSignalGuard, SignalAbort } from './signals.mjs'
+import { VERSION_RE, COMMIT_RE } from './patterns.mjs'
+import { removeTmpDir, downloadArchive, readArchiveEntries, makeTmpDir, extractInto, applyPristine } from './run-shared.mjs'
+import { runUpgrade } from './upgrade.mjs'
+
+/** Step 2's package source record check (D2): `deps.engineFile` is read through `deps.fs` and its
+ * SHA-256 compared with `source.engineSha256`. */
+async function validateSourceRecord(deps) {
+  const source = deps.source
+  if (!source || typeof source !== 'object') return false
+  if (source.repository !== deps.engine.UPSTREAM_SLUG) return false
+  if (typeof source.version !== 'string' || source.version !== deps.packageVersion) return false
+  if (!VERSION_RE.test(source.version)) return false
+  if (typeof source.commit !== 'string' || !COMMIT_RE.test(source.commit)) return false
+
+  let engineBytes
+  try {
+    engineBytes = await deps.fs.readFile(deps.engineFile)
+  } catch {
+    return false
+  }
+  const actualSha256 = createHash('sha256').update(engineBytes).digest('hex')
+  return actualSha256 === source.engineSha256
+}
+
+/**
+ * create-wxl's one exported seam (0005-S1): the Step order table's steps 1-13, every signal
+ * window (traceability.md "Signals"), and the full set of failure-path messages (CW-E09,
+ * CW-E11, CW-E14, CW-W05). An argv whose first positional is `upgrade` is dispatched to
+ * 0006's upgrade path instead (0006-S1, `runUpgrade` in upgrade.mjs).
+ */
+export async function run(argv, io, deps) {
+  // traceability.md "Signals": "errors writing the messages are ignored". Without a listener, a
+  // `Writable`'s own `write` error is an unhandled `'error'` event (an uncaught exception), not a
+  // rejection any `await` here could catch; a no-op listener is the only way to ignore it.
+  // S-30: removed in `finally` below, so a run never leaves a listener behind on `io`'s streams.
+  const ignoreWriteError = () => {}
+  io.stdout.on('error', ignoreWriteError)
+  io.stderr.on('error', ignoreWriteError)
+  try {
+    return await runBody(argv, io, deps)
+  } finally {
+    // A `Writable`'s own `write` error is emitted on a later tick (`process.nextTick`), not
+    // synchronously from `write()` -- removing the listener right away could drop it before it
+    // fires, turning the very error this listener exists to ignore back into an uncaught
+    // exception. One `setImmediate` tick runs after any already-scheduled `nextTick` callback.
+    await new Promise((resolve) => setImmediate(resolve))
+    io.stdout.removeListener('error', ignoreWriteError)
+    io.stderr.removeListener('error', ignoreWriteError)
+  }
+}
+
+async function runBody(argv, io, deps) {
+  // CW-E01 and CW-E02 use the environment language rule only (traceability.md "Language"): they
+  // happen before or during parsing, so a `--lang` flag cannot select their table yet.
+  const envLang = selectLanguage(deps)
+  const t = messages[envLang]
+
+  // Step 1: Node version, before anything else (including argv parsing).
+  if (!isNodeVersionOk(deps.nodeVersion)) {
+    io.stderr.write(t['CW-E01']({ running: deps.nodeVersion, minimum: MINIMUM_NODE_VERSION }) + '\n')
+    return 1
+  }
+
+  // traceability.md "Signals": "an error that is none of the CW codes (a bug) ... is printed as
+  // CW-E14 ... and exits 1" -- steps 1-2 (before `runSteps`, which has its own such catch) need
+  // the same fallback, in the environment language (no `--lang` is parsed yet).
+  let parsed
+  try {
+    parsed = parseArgvStrict(argv)
+  } catch (err) {
+    if (err instanceof ArgvError) {
+      io.stderr.write(t['CW-E02']({ value: err.token, usage: err.usage, reason: err.reason }) + '\n')
+      return 1
+    }
+    io.stderr.write(t['CW-E14']({ message: err?.message ?? String(err) }) + '\n')
+    return 1
+  }
+  if (parsed.noSetup) {
+    const presentSetupFlag = SETUP_FLAG_NAMES.find((name) => name in parsed.flags)
+    if (presentSetupFlag) {
+      io.stderr.write(
+        t['CW-E02']({ value: `--${presentSetupFlag}`, usage: false, reason: 'conflicts-with-no-setup' }) + '\n',
+      )
+      return 1
+    }
+  }
+
+  const overrideRaw = deps.env.CREATE_WXL_COMMIT
+  const hasOverride = typeof overrideRaw === 'string' && overrideRaw !== ''
+  if (hasOverride && !COMMIT_RE.test(overrideRaw)) {
+    io.stderr.write(t['CW-E02']({ value: 'CREATE_WXL_COMMIT', usage: false, reason: 'bad-env', badValue: overrideRaw }) + '\n')
+    return 1
+  }
+
+  if (!(await validateSourceRecord(deps))) {
+    io.stderr.write(t['CW-E13']() + '\n')
+    return 1
+  }
+
+  // From here on, a valid `--lang` (now that argv has parsed) selects the table.
+  const lang2 = selectLanguage(deps, parsed.lang)
+  const t2 = messages[lang2]
+
+  // The guard is created here and passed down (T-0024 ticket Comments, "increment plan
+  // confirmed"), so every window below throwing/catching `SignalAbort` shares the same one, and
+  // its listeners come off `deps.signals` exactly once, however `runSteps` returns.
+  const guard = createSignalGuard(deps.signals, ['SIGINT', 'SIGTERM', 'SIGHUP'])
+  const questioner = makeQuestioner(io, deps, guard)
+  try {
+    if (parsed.mode === 'upgrade') {
+      return await runUpgrade(parsed, io, deps, t2, lang2, guard, { hasOverride, overrideRaw })
+    }
+    return await runSteps(parsed, io, deps, t2, lang2, questioner, guard, { hasOverride, overrideRaw })
+  } catch (err) {
+    if (err instanceof QuestionEofError) {
+      io.stderr.write(t2['CW-E15']() + '\n')
+      return 1
+    }
+    throw err
+  } finally {
+    questioner.close()
+    guard.off()
+  }
+}
+
+/** Step 3/4's directory question (S-12): asks once, re-asking on its own (printing the `~` reason,
+ * traceability.md "Step order" row 3) until it has an answer that does not begin with `~`. Never
+ * touches `checkTarget`, so the step-4 re-ask loop that calls this only prints CW-E04 for a
+ * rejection `checkTarget` itself returned, never for a stale one left over from a `~` answer
+ * (S-13/P-17/C-06). */
+async function askDirectory(io, t2, questioner) {
+  while (true) {
+    io.stdout.write(t2['Q-DIRECTORY']() + '\n')
+    const raw = await questioner.ask()
+    const answer = raw.trim() === '' ? 'wxl-range' : raw.trim()
+    if (answer.startsWith('~')) {
+      io.stdout.write(t2['Q-DIRECTORY-TILDE']() + '\n')
+      continue
+    }
+    return answer
+  }
+}
+
+async function runSteps(parsed, io, deps, t2, lang2, questioner, guard, { hasOverride, overrideRaw }) {
+  // `tmpDir`, once step 8 creates it, is this function's one piece of cleanup state: a signal or a
+  // "bug" (an error that is none of the expected CW conditions) caught below removes it, both
+  // handled alike (traceability.md "Signals": "an error that is none of the CW codes ... is
+  // handled like a signal in its window"). `remainingCommandsFn`, once step 11 starts, tells the
+  // catch below which commands a bug in steps 11-13 still has to list (C-07/P-04/S-04: the same
+  // decision (3) CW-W05 already follows for a signal in that window).
+  let tmpDir = null
+  let remainingCommandsFn = null
+  try {
+    return await runStepsBody(
+      parsed,
+      io,
+      deps,
+      t2,
+      lang2,
+      questioner,
+      guard,
+      { hasOverride, overrideRaw },
+      (dir) => {
+        tmpDir = dir
+      },
+      (fn) => {
+        remainingCommandsFn = fn
+      },
+    )
+  } catch (err) {
+    if (err instanceof QuestionEofError) throw err
+    if (tmpDir) await removeTmpDir(deps, tmpDir)
+    if (err instanceof SignalAbort) return 130
+    const remainingCommands = remainingCommandsFn ? remainingCommandsFn() : undefined
+    io.stderr.write(t2['CW-E14']({ message: err?.message ?? String(err), remainingCommands }) + '\n')
+    return 1
+  }
+}
+
+async function runStepsBody(
+  parsed,
+  io,
+  deps,
+  t2,
+  lang2,
+  questioner,
+  guard,
+  { hasOverride, overrideRaw },
+  setTmpDir,
+  setRemainingCommandsFn,
+) {
+  deps.checkpoint('step-3')
+  let directory = parsed.directory
+  let askedDirectory = false
+  if (directory === undefined) {
+    if (io.interactive) {
+      askedDirectory = true
+      directory = await askDirectory(io, t2, questioner)
+    } else {
+      io.stderr.write(t2['CW-E03']() + '\n')
+      return 1
+    }
+  }
+  let target = resolvePath(deps.cwd, directory)
+
+  deps.checkpoint('step-4')
+  guard.throwIfRaised()
+
+  const printCwE04 = (rejectionToPrint) =>
+    io.stderr.write(t2['CW-E04']({ path: target, conditionId: rejectionToPrint.id, detail: rejectionToPrint.detail }) + '\n')
+
+  let rejection = await checkTarget(deps, target)
+  guard.throwIfRaised() // P-17/C-14: a signal already received wins over a rejection found after
+  while (rejection && askedDirectory) {
+    printCwE04(rejection)
+    directory = await askDirectory(io, t2, questioner)
+    target = resolvePath(deps.cwd, directory)
+    rejection = await checkTarget(deps, target)
+    guard.throwIfRaised()
+  }
+  if (rejection) {
+    printCwE04(rejection)
+    return 1
+  }
+
+  let setupArgs = null
+  let setupArgv = null
+  if (!parsed.noSetup) {
+    deps.checkpoint('step-5')
+    guard.throwIfRaised()
+    if (!io.interactive) {
+      const missing = missingRequiredFlags(parsed.flags)
+      if (missing.length > 0) {
+        io.stderr.write(t2['CW-E05']({ missing }) + '\n')
+        return 1
+      }
+      setupArgv = buildEngineArgv(parsed.flags)
+      try {
+        setupArgs = deps.engine.parseForkInitArgs(setupArgv)
+      } catch (err) {
+        if (err instanceof deps.engine.ForkInitArgError) {
+          io.stderr.write(t2['CW-E06']({ message: err.message }) + '\n')
+          return 1
+        }
+        throw err
+      }
+    } else {
+      ;({ parsedArgs: setupArgs, argv: setupArgv } = await collectInteractiveAnswers(io, deps, t2, parsed.flags, questioner))
+    }
+  }
+
+  const commit = hasOverride ? overrideRaw : deps.source.commit
+
+  deps.checkpoint('step-6')
+  guard.throwIfRaised()
+  if (hasOverride) {
+    io.stderr.write(t2['CW-W04']({ commit }) + '\n')
+  }
+  // The URL/AbortController/timeout/race/CW-E07 window lives in `run-shared.mjs`'s
+  // `downloadArchive`, shared with the upgrade path (traceability.md "Step order" row 7); this
+  // call site's own checkpoints and CW-W04 are unchanged.
+  const downloaded = await downloadArchive({ io, deps, t2, guard, repository: deps.source.repository, ref: commit })
+  if (!downloaded) return 1
+  const { body } = downloaded
+
+  deps.checkpoint('step-7')
+  guard.throwIfRaised()
+  // Parsing, entry-rule validation, mkdtemp, extraction and P1-P4 live in `run-shared.mjs`,
+  // shared with the upgrade path; this call site's own checkpoints, `setTmpDir` and argument
+  // shape are unchanged.
+  const validatedEntries = await readArchiveEntries({ io, t2, body, commit })
+  if (!validatedEntries) return 1
+
+  deps.checkpoint('step-8')
+  guard.throwIfRaised()
+  const parentDir = dirname(target)
+  const tmpDir = await makeTmpDir({ io, deps, t2, parent: parentDir, prefix: '.create-wxl-' })
+  if (!tmpDir) return 1 // mkdtemp itself failed: nothing was created, nothing to clean up
+  setTmpDir(tmpDir)
+  if (!(await extractInto({ io, deps, t2, guard, entries: validatedEntries, tmpDir }))) return 1
+
+  deps.checkpoint('step-9')
+  guard.throwIfRaised()
+  if (
+    !(await applyPristine({
+      io,
+      deps,
+      t2,
+      guard,
+      tmpDir,
+      record: { repository: deps.source.repository, version: deps.source.version, commit },
+    }))
+  ) {
+    return 1
+  }
+
+  deps.checkpoint('step-10')
+  guard.throwIfRaised() // P-02/C-01
+  // Step 10's own re-check (traceability.md "Step order" row 10): another process may have created
+  // something at the target since step 4. An empty directory is still accepted (moveIntoPlace's
+  // existing-target branch handles it); anything else cleans up the temporary directory and reports
+  // CW-E04 as step 4 would, instead of letting `rename` itself fail with an opaque ENOTDIR/ENOTEMPTY.
+  const recheck = await checkTarget(deps, target)
+  guard.throwIfRaised()
+  if (recheck) {
+    await removeTmpDir(deps, tmpDir)
+    printCwE04(recheck)
+    return 1
+  }
+  try {
+    await moveIntoPlace(deps, tmpDir, target, { shouldStop: () => guard.isRaised() })
+  } catch (err) {
+    if (err instanceof MoveIntoPlaceError) {
+      if (err.signaled) {
+        // C-02/P-03/S-23: a stranded entry still keeps and names the temporary directory (the
+        // same "kept and named" guarantee a non-signaled CW-E11 has); the signal still decides
+        // the exit code (130), and `setTmpDir(null)` here stops the outer catch from deleting a
+        // temporary directory `moveIntoPlace` deliberately kept.
+        if (err.stranded.length > 0) {
+          io.stderr.write(
+            t2['CW-E11']({ target, detail: err.message, stranded: err.stranded, tmpDir: err.tmpDir }) + '\n',
+          )
+          setTmpDir(null)
+          return 130
+        }
+        throw new SignalAbort(guard.raised())
+      }
+      io.stderr.write(
+        t2['CW-E11']({ target, detail: err.message, stranded: err.stranded, tmpDir: err.tmpDir }) + '\n',
+      )
+      return 1
+    }
+    throw err
+  }
+  setTmpDir(null) // step 10 succeeded: the range stays on disk whatever happens from here on
+
+  // Steps 11-13 (traceability.md "Signals"): a signal here is printed directly, inline (CW-W05),
+  // instead of being thrown and routed through the generic `SignalAbort` catch above -- there is
+  // no tmpDir cleanup left to do, and each of the three steps' CW-W05 names a different set of
+  // remaining commands.
+  // S-21: `lang2` is the language `selectLanguage` already picked in `run()`; reusing it here
+  // avoids re-deriving the same answer from `t2`'s own object identity.
+  const lang = lang2
+
+  if (!parsed.noSetup) {
+    deps.checkpoint('step-11')
+    setRemainingCommandsFn(() =>
+      cwE12FinishingCommandsList({ directory, argv: setupArgv, version: deps.source.version, lang }),
+    )
+    if (guard.raised()) {
+      io.stderr.write(
+        t2['CW-W05']({
+          remainingCommands: cwE12FinishingCommandsList({
+            directory,
+            argv: setupArgv,
+            version: deps.source.version,
+            lang,
+          }),
+        }) +
+          '\n',
+      )
+      return 130
+    }
+    // S-12: both CW-E12 call sites (the thrown-error and the non-zero-exitCode path) otherwise
+    // repeat the same `{ directory, argv: setupArgv, version: deps.source.version }`.
+    const printCwE12 = (message) =>
+      io.stderr.write(t2['CW-E12']({ message, directory, argv: setupArgv, version: deps.source.version }) + '\n')
+    let result
+    try {
+      result = deps.engine.runForkInit(setupArgs, { projectRoot: target })
+    } catch (err) {
+      printCwE12(err?.message ?? String(err))
+      return 1
+    }
+    if (result.exitCode !== 0) {
+      printCwE12(result.message)
+      return 1
+    }
+    for (const warning of result.warnings) {
+      io.stdout.write(jsonValue(warning) + '\n')
+    }
+  }
+
+  let gitResult = { warningId: null }
+  if (!parsed.noSetup) {
+    deps.checkpoint('step-12')
+    setRemainingCommandsFn(() => orderedPrintedForms(deps.source.version))
+    if (guard.raised()) {
+      io.stderr.write(t2['CW-W05']({ remainingCommands: orderedPrintedForms(deps.source.version) }) + '\n')
+      return 130
+    }
+    gitResult = await runGitSteps({
+      runGit: deps.runGit,
+      cwd: target,
+      env: deps.env,
+      version: deps.source.version,
+      shouldStop: () => guard.isRaised(),
+    })
+    if (gitResult.signal) {
+      io.stderr.write(t2['CW-W05']({ remainingCommands: gitResult.remainingCommands }) + '\n')
+      return 130
+    }
+  }
+  if (gitResult.warningId) {
+    io.stderr.write(t2[gitResult.warningId](gitResult) + '\n')
+  }
+
+  deps.checkpoint('step-13')
+  setRemainingCommandsFn(() => [])
+  if (guard.raised()) {
+    io.stderr.write(t2['CW-W05']({ remainingCommands: [] }) + '\n')
+    return 130
+  }
+  const nextSteps = buildNextSteps({
+    t: t2,
+    directory,
+    noSetup: parsed.noSetup,
+    parsedArgs: setupArgs,
+    gitResult,
+  })
+  for (const line of nextSteps) {
+    io.stdout.write(line + '\n')
+  }
+  return 0
+}

package/src/signals.mjs

@@ -0,0 +1,88 @@
+// Signal handling (traceability.md "Signals"): `SIGINT`, `SIGTERM` and `SIGHUP` are handled
+// alike, from step 3 on. `createSignalGuard` listens on `deps.signals` and remembers only the
+// FIRST signal received (further signals during cleanup are ignored, traceability.md "Signals").
+// A pending question's `ask()` can register itself to be rejected the moment a signal arrives
+// (questions.mjs), instead of only being checked at the next `checkpoint`.
+
+export class SignalAbort extends Error {
+  constructor(signal) {
+    super(`aborted by ${signal}`)
+    this.name = 'SignalAbort'
+    this.signal = signal
+  }
+}
+
+/** `signals`: the `EventEmitter` this run's `deps.signals` is. `names`: which signal names to
+ * listen for; defaults to all three traceability.md "Signals" handles alike. */
+export function createSignalGuard(signals, names = ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  let raised = null
+  let pendingReject = null
+  const onRaiseCallbacks = []
+  const handlers = new Map()
+
+  function onSignal(name) {
+    if (raised) return // one-time: a second signal during cleanup is ignored
+    raised = name
+    for (const cb of onRaiseCallbacks) cb(name)
+    if (pendingReject) {
+      const reject = pendingReject
+      pendingReject = null
+      reject(new SignalAbort(name))
+    }
+  }
+
+  for (const name of names) {
+    const handler = () => onSignal(name)
+    handlers.set(name, handler)
+    signals.on(name, handler)
+  }
+
+  return {
+    raised() {
+      return raised
+    },
+    // S-18: one name for "has a signal arrived" wherever a caller needs a plain boolean (the
+    // `shouldStop` callback `fsops.mjs`/`git-steps.mjs` are given), instead of each call site
+    // re-writing `guard.raised() !== null` for itself.
+    isRaised() {
+      return raised !== null
+    },
+    throwIfRaised() {
+      if (raised) throw new SignalAbort(raised)
+    },
+    /** Registers `reject` to be called the moment a signal arrives while something else is
+     * waiting (a pending question's `ask()`). The caller clears this itself (`clearWait()`) once
+     * settled any other way (a line arrived, EOF) -- `waitForSignal` only knows about the signal
+     * side of that race, not the other one. */
+    waitForSignal(reject) {
+      if (raised) {
+        reject(new SignalAbort(raised))
+        return
+      }
+      pendingReject = reject
+    },
+    clearWait() {
+      pendingReject = null
+    },
+    /** Registers `cb` to run once, synchronously, the moment a signal is first raised --
+     * immediately when one already has been. Independent of `waitForSignal`'s single pending
+     * slot (decision 6: step 6's download aborts its own `AbortController` this way). Returns an
+     * unsubscribe function, so a caller whose own window has already closed (step 6 finishing)
+     * does not leave a stale callback registered for the rest of the run. */
+    onRaise(cb) {
+      if (raised) {
+        cb(raised)
+        return () => {}
+      }
+      onRaiseCallbacks.push(cb)
+      return () => {
+        const i = onRaiseCallbacks.indexOf(cb)
+        if (i !== -1) onRaiseCallbacks.splice(i, 1)
+      }
+    },
+    off() {
+      for (const [name, handler] of handlers) signals.removeListener(name, handler)
+      handlers.clear()
+    },
+  }
+}

package/src/text.mjs

@@ -0,0 +1,127 @@
+// Shared text helpers: JSON string literals for named values (every C0, DEL and C1 character
+// escaped per traceability.md "Error and warning codes", D10), and POSIX quoting for commands
+// printed for copying (N1, N4, N5, N7, N8, CW-E12, CW-W05).
+
+/** S-20: the one definition of "C0, DEL or C1" (traceability.md "Error and warning codes" and
+ * AC-24's `hasControlChar`), shared with `escapeChar`'s own, wider "needs `\uXXXX`" rule below
+ * (which also covers lone surrogates, a separate reason to escape, review finding C-09 -- NOT a
+ * reason to withhold a copyable command, so `hasControlChar` does not call this with that range
+ * folded in). */
+function isControlCodePoint(code) {
+  return code < 0x20 || (code >= 0x7f && code <= 0x9f)
+}
+
+function isLoneSurrogate(code) {
+  return code >= 0xd800 && code <= 0xdfff
+}
+
+/** D10 (the user-approved reading; stage 6/7 correction P-01/S-02/C-11): a line feed inside a
+ * value is the JSON short escape `\n` (the matrix's own value, traceability.md C60); every other
+ * C0, DEL, C1 character and lone surrogate (review finding C-09: `JSON.stringify` has written
+ * U+D800-U+DFFF as `\uXXXX` since ES2019's well-formed `JSON.stringify`) is written `\uXXXX` --
+ * `JSON.stringify`'s own short escapes for tab/CR/backspace/form-feed are NOT used for those,
+ * and DEL/C1 (review finding C-05) would otherwise pass through `JSON.stringify` unescaped at
+ * all. */
+function escapeChar(ch) {
+  if (ch === '"') return '\\"'
+  if (ch === '\\') return '\\\\'
+  if (ch === '\n') return '\\n'
+  const code = ch.codePointAt(0)
+  if (isControlCodePoint(code) || isLoneSurrogate(code)) {
+    return `\\u${code.toString(16).padStart(4, '0')}`
+  }
+  return ch
+}
+
+/** Prints `value` as a JSON string literal, one code point at a time through `escapeChar` (full
+ * control over which escapes it uses, D10). S-35: a non-string value is converted with
+ * `String()` first, so one escaping rule applies to every call site -- a number, boolean, etc.
+ * never carries a control character in this codebase's actual call sites, but an array or object
+ * holding one (e.g. a warning list entry) now escapes the same way a plain string does. */
+export function jsonValue(value) {
+  const str = typeof value === 'string' ? value : String(value)
+  let out = '"'
+  for (const ch of str) out += escapeChar(ch)
+  return out + '"'
+}
+
+/** Candidate 22 (stage 7, security-T-0026): prints `value` through `JSON.stringify` -- unlike
+ * `jsonValue`, without wrapping the result in its own extra quotes, so an array or object prints
+ * as itself (`["3.1.0"]`, `{"toString":1}`), not through `String(value)` (which calls `toString`,
+ * throwing for a value whose own `toString` property is not callable, and collapsing an array
+ * like `["3.1.0"]` into the indistinguishable-from-a-real-version `"3.1.0"`). Any DEL/C1
+ * character or lone surrogate `JSON.stringify`'s own algorithm leaves unescaped (it already
+ * escapes every C0 character and lone surrogate itself, ES2019) is escaped the same way
+ * `escapeChar` would (D10). Returns `undefined` when `JSON.stringify` throws (a `BigInt`, a
+ * circular structure) or itself returns `undefined` (a bare `function` or `undefined` value) --
+ * the caller falls back to a type name in that case. */
+const SHORT_ESCAPE_CODES = { b: '0008', f: '000c', r: '000d', t: '0009' }
+
+export function jsonStringifyEscaped(value) {
+  let str
+  try {
+    str = JSON.stringify(value)
+  } catch {
+    return undefined
+  }
+  if (typeof str !== 'string') return undefined
+  // D10: JSON.stringify's own short escapes for backspace, form feed, CR and tab become `\uXXXX`
+  // (a line feed keeps `\n`); matching escape pairs left to right leaves `\\` followed by a
+  // letter untouched.
+  str = str.replace(/\\(.)/g, (pair, c) => (c in SHORT_ESCAPE_CODES ? `\\u${SHORT_ESCAPE_CODES[c]}` : pair))
+  let out = ''
+  for (const ch of str) {
+    const code = ch.codePointAt(0)
+    out += isControlCodePoint(code) || isLoneSurrogate(code) ? `\\u${code.toString(16).padStart(4, '0')}` : ch
+  }
+  return out
+}
+
+const BARE_RE = /^[A-Za-z0-9._\-/@%+=:,]+$/
+
+export function posixQuoteWord(word) {
+  if (BARE_RE.test(word)) return word
+  return `'${word.replace(/'/g, "'\\''")}'`
+}
+
+export function posixCommand(words) {
+  return words.map(posixQuoteWord).join(' ')
+}
+
+/** A directory beginning with `-` gets the `./` prefix before it is quoted. */
+export function formatDirectoryArg(directory) {
+  return directory.startsWith('-') ? `./${directory}` : directory
+}
+
+/** S-22: the one place every CW-E09 call site (fsops.mjs, pristine.mjs) tags a caught file-system
+ * error with the path `run.mjs` should report, without overwriting one an earlier catch already
+ * set (a write's own catch, re-thrown through another wrapper). */
+export function tagReportPath(err, path) {
+  if (err && typeof err.reportPath !== 'string') err.reportPath = path
+  return err
+}
+
+/** traceability.md "Error and warning codes": "When a value to be placed in such a command
+ * contains a C0, DEL or C1 character, the command is not printed". True when any code point in
+ * `str` is C0 (U+0000-U+001F), DEL (U+007F) or C1 (U+0080-U+009F). */
+export function hasControlChar(str) {
+  for (const ch of str) {
+    if (isControlCodePoint(ch.codePointAt(0))) return true
+  }
+  return false
+}
+
+/** `\` is Windows' own path separator; comparing after turning `\` into `/` (traceability.md
+ * "Step order" row 3, Vocabulary "name on disk") makes a path comparison platform-neutral. Shared
+ * by step 3 and P-9 since T-0062. */
+export function toSlash(value) {
+  return String(value).replace(/\\/g, '/')
+}
+
+/** ASCII-only case folding (`[A-Z]` to lowercase), the way git's own `tolower` and J5's repository
+ * comparison fold -- never JavaScript's Unicode-aware lowercasing. Shared by J5 and entry rule 3
+ * since T-0062. */
+export function foldAsciiCase(value) {
+  return value.replace(/[A-Z]/g, (c) => c.toLowerCase())
+}
+