@codedology/code-forge 0.1.0

package/src/util/reaper.mjs

@@ -0,0 +1,300 @@
+/**
+ * Pid registry + orphan reaper (plan §9.6 rule 3, V12, `[A30]`).
+ *
+ * `exec` writes one `<pids-dir>/<pid>.json` = `{pid, start_time, argv0}` per child it spawns and
+ * removes it when the child is done. A run that is killed never removes its entries, so the next
+ * `run start` / `run gc` / test preload calls `sweep(pidsDir)` on the dead run's directory.
+ *
+ * Safety rule — the reaper can only ever kill what this package started:
+ *  - it only looks at pids listed in a registry directory it is handed;
+ *  - it kills a pid only when the process's LIVE start time (`ps -o lstart= -p <pid>`) equals the
+ *    start time recorded at spawn — a pid the OS has since reused for another program has a
+ *    different start time and is left alone;
+ *  - a start time it cannot read (recorded as `unknown`, or `ps` fails now) means NEVER kill
+ *    (fail closed, plan §0.6 item 11);
+ *  - a registered pid whose process is already gone is only un-registered; its process group is
+ *    not signalled, because the group's identity can no longer be checked.
+ * The kill goes to the process GROUP (every `exec` child is a group leader, `detached: true`):
+ * SIGTERM first, then SIGKILL after a grace period, so a child that traps SIGTERM still dies.
+ * Every signal is sent right after a synchronous start-time match, with no await in between; the
+ * bare pid is signalled only when its group does not exist (ESRCH); EPERM means "not ours to
+ * touch" (reported `unknown`, never retried). Once the leader is dead its pid is never signalled
+ * again: the other group members captured before the SIGTERM are SIGKILLed one by one, each only
+ * after its own start time still matches.
+ *
+ * `ps` is run with `execFileSync` and an argv array (never a shell) rather than through
+ * `./exec.mjs`: `exec` registers every child here, so going through it would recurse.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+/** Value stored in `start_time` when `ps` could not read it at spawn time. */
+export const UNKNOWN_START_TIME = 'unknown';
+
+/** Default grace between SIGTERM and SIGKILL, in milliseconds (same as `exec`). */
+const DEFAULT_GRACE_MS = 2000;
+
+/** Poll interval while waiting for a signalled process to die. */
+const POLL_MS = 25;
+
+/**
+ * @typedef {object} PidEntry
+ * @property {number} pid
+ * @property {string} start_time - `ps -o lstart=` text, or `UNKNOWN_START_TIME`.
+ * @property {string} argv0
+ */
+
+/**
+ * @typedef {object} SweepResult
+ * @property {{pid: number, signal: 'SIGTERM'|'SIGKILL'}[]} killed - matched and killed; `signal`
+ *   is the one that finished the process.
+ * @property {number[]} mismatched - alive, but the live start time differs: not ours, untouched.
+ * @property {number[]} unknown - alive, start time unreadable: never killed, entry kept.
+ * @property {number[]} stale - already dead: entry removed, nothing signalled.
+ */
+
+/** @param {unknown} pid @returns {pid is number} */
+function isValidPid(pid) {
+  return Number.isInteger(pid) && /** @type {number} */ (pid) > 1;
+}
+
+/**
+ * Whether a process with this pid exists. EPERM means it exists but belongs to someone else.
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isAlive(pid) {
+  if (!isValidPid(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return /** @type {NodeJS.ErrnoException} */ (err).code === 'EPERM';
+  }
+}
+
+/**
+ * The live start time of `pid` as `ps -o lstart=` prints it (C locale, trimmed), or `null` when
+ * it cannot be read (no such process, no `ps`, empty output).
+ * @param {number} pid
+ * @returns {string | null}
+ */
+export function readStartTime(pid) {
+  if (!isValidPid(pid)) return null;
+  try {
+    const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+      timeout: 5000,
+    });
+    const text = out.trim().replace(/\s+/g, ' ');
+    return text.length > 0 ? text : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write `<dir>/<pid>.json` for a child just spawned. Returns the entry path.
+ * @param {string} dir
+ * @param {number} pid
+ * @param {string} argv0
+ * @returns {string}
+ */
+export function registerPid(dir, pid, argv0) {
+  if (!isValidPid(pid)) throw new TypeError('reaper: pid must be an integer greater than 1');
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  /** @type {PidEntry} */
+  const entry = { pid, start_time: readStartTime(pid) ?? UNKNOWN_START_TIME, argv0: String(argv0) };
+  const file = path.join(dir, `${pid}.json`);
+  writeFileSync(file, `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+  return file;
+}
+
+/**
+ * Remove `<dir>/<pid>.json`; a missing entry is fine.
+ * @param {string} dir
+ * @param {number} pid
+ */
+export function unregisterPid(dir, pid) {
+  rmSync(path.join(dir, `${pid}.json`), { force: true });
+}
+
+/**
+ * Read every well-formed entry of a registry directory. Malformed files are skipped (never acted on).
+ * @param {string} dir
+ * @returns {PidEntry[]}
+ */
+export function listEntries(dir) {
+  /** @type {string[]} */
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  /** @type {PidEntry[]} */
+  const entries = [];
+  for (const name of names.sort()) {
+    const match = /^(\d+)\.json$/.exec(name);
+    if (!match) continue;
+    try {
+      const parsed = JSON.parse(readFileSync(path.join(dir, name), 'utf8'));
+      if (parsed && isValidPid(parsed.pid) && parsed.pid === Number(match[1]) && typeof parsed.start_time === 'string') {
+        entries.push({ pid: parsed.pid, start_time: parsed.start_time, argv0: String(parsed.argv0 ?? '') });
+      }
+    } catch {
+      // unreadable or not JSON: skipped, never killed
+    }
+  }
+  return entries;
+}
+
+/**
+ * Every OTHER live member of process group `pgid` with its start time, read in one `ps` call:
+ * `Map<pid, lstart>`. Empty when `ps` fails.
+ * @param {number} pgid
+ * @returns {Map<number, string>}
+ */
+export function groupMembers(pgid) {
+  /** @type {Map<number, string>} */
+  const members = new Map();
+  let out = '';
+  try {
+    out = execFileSync('ps', ['-A', '-o', 'pid=,pgid=,lstart='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, LC_ALL: 'C', LANG: 'C' },
+      timeout: 5000,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+  } catch {
+    return members;
+  }
+  for (const line of out.split('\n')) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    if (Number(match[2]) === pgid && pid !== pgid && pid !== process.pid) {
+      members.set(pid, match[3].replace(/\s+/g, ' '));
+    }
+  }
+  return members;
+}
+
+/**
+ * Send `signal` to `pid`'s group — only after a SYNCHRONOUS start-time match, with no await
+ * between the check and the kill. Falls back to the bare pid only when the group does not exist
+ * (ESRCH), still inside the same synchronous step.
+ * @param {number} pid
+ * @param {string} recorded - the start time recorded at spawn.
+ * @param {NodeJS.Signals} signal
+ * @returns {'sent'|'mismatch'|'eperm'|'gone'}
+ */
+function signalIfOurs(pid, recorded, signal) {
+  if (readStartTime(pid) !== recorded) return 'mismatch';
+  try {
+    process.kill(-pid, signal);
+    return 'sent';
+  } catch (err) {
+    const code = /** @type {NodeJS.ErrnoException} */ (err).code;
+    if (code === 'EPERM') return 'eperm';
+    if (code !== 'ESRCH') return 'gone';
+  }
+  try {
+    process.kill(pid, signal);
+    return 'sent';
+  } catch (err) {
+    return /** @type {NodeJS.ErrnoException} */ (err).code === 'EPERM' ? 'eperm' : 'gone';
+  }
+}
+
+/** @param {number} pid @param {number} withinMs @returns {Promise<boolean>} true once dead */
+async function waitForDeath(pid, withinMs) {
+  const deadline = Date.now() + withinMs;
+  while (Date.now() < deadline) {
+    if (!isAlive(pid)) return true;
+    await sleep(POLL_MS);
+  }
+  return !isAlive(pid);
+}
+
+/**
+ * Reap one registry directory: kill registered children whose live start time still matches,
+ * leave everything else alone. See the module comment for the rules.
+ * @param {string} dir
+ * @param {{graceMs?: number}} [opts]
+ * @returns {Promise<SweepResult>}
+ */
+export async function sweep(dir, opts = {}) {
+  const { graceMs = DEFAULT_GRACE_MS } = opts;
+  /** @type {SweepResult} */
+  const result = { killed: [], mismatched: [], unknown: [], stale: [] };
+
+  for (const entry of listEntries(dir)) {
+    const { pid } = entry;
+    if (pid === process.pid) continue;
+
+    if (!isAlive(pid)) {
+      unregisterPid(dir, pid);
+      result.stale.push(pid);
+      continue;
+    }
+    if (entry.start_time === UNKNOWN_START_TIME || readStartTime(pid) === null) {
+      result.unknown.push(pid);
+      continue;
+    }
+
+    // Other members of the leader's group, captured while the leader is alive and verified ours:
+    // after the leader dies they are only killed one by one, each after its own start-time match.
+    const members = groupMembers(pid);
+    const term = signalIfOurs(pid, entry.start_time, 'SIGTERM');
+    if (term === 'mismatch') {
+      // The pid now names a different process: not ours. Drop the stale entry, touch nothing.
+      unregisterPid(dir, pid);
+      result.mismatched.push(pid);
+      continue;
+    }
+    if (term === 'eperm') {
+      result.unknown.push(pid);
+      continue;
+    }
+
+    if (await waitForDeath(pid, graceMs)) {
+      // The leader died of SIGTERM. Its pid is never signalled again (it may be reused); a
+      // member that trapped SIGTERM gets SIGKILL only if its start time still matches.
+      for (const [member, started] of members) {
+        signalMemberIfOurs(member, started);
+      }
+      result.killed.push({ pid, signal: 'SIGTERM' });
+    } else {
+      const kill = signalIfOurs(pid, entry.start_time, 'SIGKILL');
+      if (kill !== 'sent') {
+        result.unknown.push(pid);
+        continue;
+      }
+      await waitForDeath(pid, graceMs);
+      result.killed.push({ pid, signal: 'SIGKILL' });
+    }
+    unregisterPid(dir, pid);
+  }
+  return result;
+}
+
+/**
+ * SIGKILL one former group member, only when its live start time equals the one captured before
+ * the leader was signalled (synchronous check, then the kill).
+ * @param {number} pid @param {string} started
+ */
+function signalMemberIfOurs(pid, started) {
+  if (readStartTime(pid) !== started) return;
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    // gone between the check and the kill
+  }
+}

package/src/util/redact.mjs

@@ -0,0 +1,212 @@
+/**
+ * Secret redaction — the one gate every output path must pass through before a resolved key
+ * can reach a log line, a raw stdout write, or a JSON dump (plan §8.2: "as v1 §8.2 — unit test
+ * feeds a fake key through every path, mutation-verified").
+ *
+ * Secrets are opt-in: whatever resolves a key (`src/keys/**`, a later block) calls
+ * `registerSecret(value)` once it has the plaintext. Nothing here guesses at what "looks like" a
+ * secret — that would either over-redact ordinary text or under-redact a key shaped unlike the
+ * guess. A registered secret is scrubbed everywhere, forever, until `clearSecrets()` (tests only).
+ */
+
+/** @type {Set<string>} */
+const secrets = new Set();
+
+const MASK = '[REDACTED]';
+
+/**
+ * Register a value that must never appear verbatim in any output. No-ops for empty/non-string
+ * input so an unresolved key can't accidentally register `undefined` as a literal string.
+ *
+ * @param {unknown} value
+ */
+export function registerSecret(value) {
+  if (typeof value === 'string' && value.length > 0) {
+    secrets.add(value);
+  }
+}
+
+/** Forget every registered secret. Exists for tests; production code never needs it. */
+export function clearSecrets() {
+  secrets.clear();
+}
+
+/**
+ * Redact every registered secret out of a string, or out of every string leaf (and every key) of
+ * an object/array. For a non-string input the result is a JSON-SAFE COPY, not a value of the
+ * input's type: `Map` becomes a plain object, `Set` an array, anything with `toJSON` (e.g. `Date`)
+ * its `toJSON()` result, and a cycle the string `'[Circular]'` — see `redactDeep`. A string in
+ * gives a string out.
+ *
+ * @overload
+ * @param {string} input
+ * @returns {string}
+ */
+/**
+ * @overload
+ * @param {unknown} input
+ * @returns {unknown}
+ */
+/**
+ * @param {unknown} input
+ * @returns {unknown}
+ */
+export function redact(input) {
+  if (typeof input === 'string') {
+    return redactString(input);
+  }
+  if (input !== null && typeof input === 'object') {
+    return redactDeep(input, new WeakSet());
+  }
+  return input;
+}
+
+/**
+ * Mask every character covered by any registered secret, in one pass over the ORIGINAL text:
+ * first record the [start, end) range of every occurrence of every secret, then merge
+ * overlapping/adjacent ranges and replace each merged range with one mask. Replacing secrets one
+ * after another instead would leak the tail of a secret that overlaps another without being
+ * nested in it ("abcd" + "cdef" in "abcdef" → "[REDACTED]ef"), and let a short secret match
+ * inside an earlier mask.
+ * @param {string} text
+ * @returns {string}
+ */
+function redactString(text) {
+  /** @type {[number, number][]} */
+  const ranges = [];
+  for (const secret of secrets) {
+    let at = text.indexOf(secret);
+    while (at !== -1) {
+      ranges.push([at, at + secret.length]);
+      at = text.indexOf(secret, at + 1);
+    }
+  }
+  if (ranges.length === 0) {
+    return text;
+  }
+  ranges.sort((a, b) => a[0] - b[0]);
+  let out = '';
+  let cursor = 0;
+  let [start, end] = ranges[0];
+  for (const [s, e] of ranges.slice(1)) {
+    if (s <= end) {
+      end = Math.max(end, e);
+      continue;
+    }
+    out += text.slice(cursor, start) + MASK;
+    cursor = end;
+    [start, end] = [s, e];
+  }
+  out += text.slice(cursor, start) + MASK + text.slice(end);
+  return out;
+}
+
+/**
+ * Write `value` under `key`, never overwriting: two different keys that redact to the same text
+ * (two secrets → `[REDACTED]`, or two non-string Map keys → `[object Object]`) get `#2`, `#3`, …
+ * suffixes so no entry is silently dropped.
+ * @param {Record<string, unknown>} out
+ * @param {string} key
+ * @param {unknown} value
+ */
+function putUnique(out, key, value) {
+  let candidate = key;
+  let n = 2;
+  while (Object.hasOwn(out, candidate)) {
+    candidate = `${key}#${n}`;
+    n += 1;
+  }
+  out[candidate] = value;
+}
+
+/**
+ * The structural half of `redact`/`redactJSON`. Deliberately NOT a bare `JSON.stringify`
+ * replacer: a replacer callback can rewrite a *value* but not the *key* it sits under, and a
+ * secret used as an object key (e.g. a map keyed by token) needs redacting too.
+ *
+ * - Calls `.toJSON()` when present (before recursing into its result) so `Date`, and anything
+ *   else that defines it, serializes as it would under a plain `JSON.stringify` — a raw
+ *   `Object.entries` walk over a `Date` sees no own enumerable properties and would otherwise
+ *   silently corrupt it to `{}`.
+ * - `Map`/`Set` get a JSON-safe shape (a plain object / array respectively) — `JSON.stringify`
+ *   has no built-in behavior for either (both would also come out as `{}` natively), so this is
+ *   strictly better, not just parity.
+ * - A `WeakSet` of objects currently being visited on the CURRENT path (not globally) catches a
+ *   circular reference and substitutes `'[Circular]'`, so a cycle degrades to a marker instead of
+ *   overflowing the stack — the same object appearing twice in unrelated, non-overlapping
+ *   branches (not a real cycle) is not flagged, because it's removed from the set once that
+ *   branch finishes.
+ *
+ * @param {unknown} value
+ * @param {WeakSet<object>} seen
+ * @returns {unknown}
+ */
+function redactDeep(value, seen) {
+  if (typeof value === 'string') {
+    return redactString(value);
+  }
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (typeof (/** @type {{toJSON?: unknown}} */ (value).toJSON) === 'function') {
+    return redactDeep(/** @type {{toJSON: () => unknown}} */ (value).toJSON(), seen);
+  }
+  if (seen.has(value)) {
+    return '[Circular]';
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return value.map((item) => redactDeep(item, seen));
+    }
+    if (value instanceof Map) {
+      /** @type {Record<string, unknown>} */
+      const out = {};
+      for (const [key, v] of value.entries()) {
+        putUnique(out, redactString(String(key)), redactDeep(v, seen));
+      }
+      return out;
+    }
+    if (value instanceof Set) {
+      return [...value].map((item) => redactDeep(item, seen));
+    }
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      putUnique(out, redactString(key), redactDeep(v, seen));
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/**
+ * Redact-then-serialize — the "JSON path": callers that dump a structured value (a ledger row,
+ * a `--json` CLI response) must go through this instead of a bare `JSON.stringify`.
+ *
+ * @param {unknown} value
+ * @param {number} [space]
+ * @returns {string}
+ */
+export function redactJSON(value, space) {
+  return JSON.stringify(redact(value), null, space);
+}
+
+/**
+ * Redact-then-write — the "stdout path": a raw write to a stream (e.g. a `--json` flag piping
+ * straight to `process.stdout`) that does not go through `./log.mjs`.
+ *
+ * Redacts each call's `text` independently — a secret split across two separate `write` calls
+ * (a chunk boundary landing mid-secret) will NOT be caught. Callers must pass complete messages,
+ * not partial chunks, the same way `./log.mjs` does (one full line per call).
+ *
+ * The parameter type is the minimal shape this function actually uses (just `.write`), not the
+ * full `NodeJS.WritableStream` — so a plain `{ write(text) {...} }` test double type-checks
+ * without needing to fake the other dozen `WritableStream` members.
+ * @param {{write: (chunk: string) => unknown}} stream
+ * @param {string} text
+ */
+export function writeSafe(stream, text) {
+  stream.write(redactString(text));
+}