@linzumi/cli 1.0.111 → 1.0.112

package/scripts/build-core-daemon-parity-oracle.mjs

@@ -0,0 +1,573 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 10, runner core / supervisor / daemon).
+// Relationship: Builds the TS-side PARITY ORACLE for the Commander daemon
+// start/status/wait/stop primitives of the ReScript commander port, the
+// sibling of build-core-commander-seams-parity-oracle.mjs. ONE bundle
+// imports the REAL './src/commanderDaemon' exports behind the one-shot
+// batch driver: a JSON array of cases on stdin, a JSON array of results on
+// stdout. The ReScript package's CoreDaemonParityConformance drives the
+// SAME inputs through src/core/CommanderDaemon.res and asserts
+// accept/reject/normalized-output equivalence AND byte-identical status
+// record files - the cross-impl contract that lets both commanders share
+// ~/.linzumi/commanders through M4.
+//
+// Determinism / seams per op:
+//   - paths: HOME is redirected to the case scratch dir for the whole
+//     derivation (os.homedir() reads $HOME per call on posix).
+//   - start: timestamps are pinned by a scoped global-Date override
+//     (startedAt is not injectable in the TS surface), process.cwd() is
+//     pinned by chdir into $DIR/cwdpin, the spawn rides the TS spawnImpl
+//     injection point as a scripted seam with a fixed pid, and the
+//     hard-wired readProcessIdentity probe runs the REAL `ps` against a
+//     pid that cannot exist (999999999 exceeds every platform pid space),
+//     so the probe deterministically reports no identity on both impls.
+//     The TS audit-log writer (called directly by the module) is redirected
+//     via LINZUMI_CLI_AUDIT_LOG to a scratch OUTSIDE the snapshot dir and
+//     its lines come back projected to the stable fields (ts dropped).
+//   - start with real:true: where the seam is bypassed, the REAL spawn runs
+//     `node -e` against the module's own command shape ('commander' is the
+//     evaluated script - a bare ReferenceError, the child exits instantly).
+//     MASKING (structural, mirrored by the conformance side): pid is
+//     replaced by '<PID>' after asserting it is a positive number,
+//     processStartedAt is dropped from records/key lists (the `ps` probe
+//     racing a dying child is the one genuinely unpinnable bit), and the
+//     log file's node error output is replaced by '<VOLATILE_LOG>'.
+//   - status/stop: process liveness is the REAL process.kill(pid, 0) - the
+//     conformance feeds both impls the SAME genuinely-live pid (its own)
+//     and genuinely-dead pid (a reaped spawnSync child), so classification
+//     compares real kernel answers. The identity reader rides the TS
+//     injection point (scripted, with a call counter) except in stop,
+//     where the TS surface hard-wires the default: the liveChild leg runs
+//     a REAL detached `node -e 'setInterval(...)'` child so the real `ps`
+//     probe classifies it and the real SIGINT terminates it (childExited
+//     reports the observed exit; the volatile pid is masked to '<PID>').
+//   - wait: `now`, readTextFile, and statusImpl all ride the TS injection
+//     points as scripted sequences with call counters (the counters are
+//     part of the parity contract - both impls must consume the seams in
+//     the same order); the hard-wired fs.watch leg is exercised for real
+//     via the realLog case (a scheduled append to a real file), and the
+//     scripted-clock cases drive its timeout path with remaining=0 so no
+//     leg depends on wall time.
+//
+// SECRETS: the oracle only ever sees the conformance suite's synthetic
+// ids/paths; nothing here logs case contents.
+//
+// The output is a local test artifact (.differential/ is gitignored, never
+// published) and stays unminified for debuggability.
+import { mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+const driverSource = `
+import {
+  appendFileSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { spawn } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import {
+  commanderDaemonStatus,
+  commanderStatusDir,
+  commanderStatusFile,
+  defaultCommanderLogFile,
+  startCommanderDaemon,
+  stopCommanderDaemon,
+  waitForCommanderDaemon,
+} from './src/commanderDaemon';
+
+// --- Placeholder + snapshot plumbing --------------------------------------------
+
+const dirPlaceholder = '$DIR';
+
+function scratch() {
+  // realpath so macOS /var -> /private/var never splits the two impls'
+  // placeholder substitution.
+  return realpathSync(mkdtempSync(join(tmpdir(), 'linzumi-core-daemon-oracle-')));
+}
+
+function substitute(value, from, to) {
+  if (typeof value === 'string') {
+    return value.split(from).join(to);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => substitute(entry, from, to));
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        substitute(key, from, to),
+        substitute(entry, from, to),
+      ])
+    );
+  }
+  return value;
+}
+
+function snapshotFiles(dir) {
+  const files = {};
+  const walk = (current) => {
+    for (const name of readdirSync(current).sort()) {
+      const full = join(current, name);
+      if (statSync(full).isDirectory()) {
+        walk(full);
+      } else {
+        files[relative(dir, full)] = readFileSync(full, 'utf8');
+      }
+    }
+  };
+  walk(dir);
+  return files;
+}
+
+function outcome(run) {
+  try {
+    const value = run();
+    return value === undefined ? { defined: false } : { defined: true, value };
+  } catch (error) {
+    return {
+      threw: true,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+const RealDate = Date;
+
+function withFixedNow(nowMs, run) {
+  if (nowMs === undefined) {
+    return run();
+  }
+  class FixedDate extends RealDate {
+    constructor(...args) {
+      if (args.length === 0) {
+        super(nowMs);
+      } else {
+        super(...args);
+      }
+    }
+    static now() {
+      return nowMs;
+    }
+  }
+  globalThis.Date = FixedDate;
+  try {
+    return run();
+  } finally {
+    globalThis.Date = RealDate;
+  }
+}
+
+function withEnv(key, value, run) {
+  const previous = process.env[key];
+  process.env[key] = value;
+  try {
+    return run();
+  } finally {
+    if (previous === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = previous;
+    }
+  }
+}
+
+// The daemon status normalizer shared by the status/stop ops.
+function statusJson(status) {
+  if (status.status === 'missing') {
+    return { status: 'missing', runnerId: status.runnerId, statusFile: status.statusFile };
+  }
+  return { status: status.status, record: status.record };
+}
+
+// --- paths -----------------------------------------------------------------------
+
+function handlePaths(testCase) {
+  const dir = scratch();
+  return withEnv('HOME', dir, () => {
+    const derived = {
+      statusDir: outcome(() => commanderStatusDir()),
+      statusFileDefault: outcome(() => commanderStatusFile(testCase.runnerId)),
+      statusFileScoped: outcome(() =>
+        commanderStatusFile(testCase.runnerId, join(dir, 'custom'))
+      ),
+      logFileDefault: outcome(() => defaultCommanderLogFile(testCase.runnerId)),
+    };
+    return substitute(derived, dir, dirPlaceholder);
+  });
+}
+
+// --- start -----------------------------------------------------------------------
+
+// Audit-line projection: ts is wall-clock noise (pinned only under the
+// scoped Date override, so dropped for uniformity); the compared surface is
+// the event vocabulary and the payload the module hands the writer.
+function projectAuditLine(line) {
+  const parsed = JSON.parse(line);
+  const projected = {};
+  for (const key of ['event', 'sessionId', 'command', 'args', 'cwd', 'pid', 'purpose']) {
+    if (parsed[key] !== undefined) {
+      projected[key] = parsed[key];
+    }
+  }
+  return projected;
+}
+
+function readAuditEvents(auditFile) {
+  let raw;
+  try {
+    raw = readFileSync(auditFile, 'utf8');
+  } catch {
+    return [];
+  }
+  return raw
+    .split('\\n')
+    .filter((line) => line.trim() !== '')
+    .map(projectAuditLine);
+}
+
+function maskRealSpawn(result, files, auditEvents) {
+  const masked = { result, statusKeys: null, logFilePresent: false };
+  if (result.defined === true) {
+    const record = { ...result.value };
+    record.pid = typeof record.pid === 'number' && record.pid > 0 ? '<PID>' : '<INVALID_PID>';
+    delete record.processStartedAt;
+    masked.result = { defined: true, value: record };
+  }
+  const fileEntries = {};
+  for (const [name, contents] of Object.entries(files)) {
+    if (name.endsWith('.log')) {
+      masked.logFilePresent = true;
+      continue;
+    }
+    const parsed = JSON.parse(contents);
+    masked.statusKeys = Object.keys(parsed).filter((key) => key !== 'processStartedAt');
+    parsed.pid = typeof parsed.pid === 'number' && parsed.pid > 0 ? '<PID>' : '<INVALID_PID>';
+    delete parsed.processStartedAt;
+    fileEntries[name] = parsed;
+  }
+  masked.files = fileEntries;
+  // The ps identity probe races the instantly-dying real child (present or
+  // absent exec_file_completed, live-vs-zombie command line), so only the
+  // spawn/spawned pair is compared for the real leg.
+  masked.auditEvents = auditEvents
+    .filter((event) => event.event === 'process.spawn' || event.event === 'process.spawned')
+    .map((event) =>
+      event.pid === undefined
+        ? event
+        : {
+            ...event,
+            pid: typeof event.pid === 'number' && event.pid > 0 ? '<PID>' : '<INVALID_PID>',
+          }
+    );
+  return masked;
+}
+
+function handleStart(testCase) {
+  const dir = scratch();
+  const auditDir = mkdtempSync(join(tmpdir(), 'linzumi-core-daemon-audit-'));
+  const auditFile = join(auditDir, 'audit.jsonl');
+  const spec = substitute(testCase, dirPlaceholder, dir);
+  const cwdPin = join(dir, 'cwdpin');
+  mkdirSync(cwdPin, { recursive: true });
+  const previousCwd = process.cwd();
+  const spawnCalls = [];
+  let realChildPid;
+  try {
+    process.chdir(cwdPin);
+    return withEnv('HOME', dir, () =>
+      withEnv('LINZUMI_CLI_AUDIT_LOG', auditFile, () => {
+        const spawnImpl =
+          spec.real === true
+            ? undefined
+            : (command, args, options) => {
+                spawnCalls.push({
+                  command,
+                  args,
+                  detached: options.detached === true,
+                  stdio: options.stdio.map((entry) =>
+                    typeof entry === 'number' ? '<fd>' : String(entry)
+                  ),
+                  envIsProcessEnv: options.env === process.env,
+                });
+                return {
+                  pid: spec.scriptedPid === null ? undefined : spec.scriptedPid,
+                  unref() {},
+                };
+              };
+        const result = withFixedNow(spec.nowMs, () =>
+          outcome(() => {
+            const record = startCommanderDaemon({
+              runnerId: spec.runnerId,
+              args: spec.args ?? [],
+              cwd: spec.cwd,
+              logFile: spec.logFile,
+              statusDir: spec.statusDir,
+              nodeBin: spec.real === true ? process.execPath : spec.nodeBin,
+              entrypoint: spec.real === true ? '-e' : spec.entrypoint,
+              spawnImpl,
+            });
+            realChildPid = spec.real === true ? record.pid : undefined;
+            return record;
+          })
+        );
+        const files = snapshotFiles(dir);
+        const auditEvents = readAuditEvents(auditFile);
+        const payload =
+          spec.real === true
+            ? maskRealSpawn(result, files, auditEvents)
+            : { result, files, spawnCalls, auditEvents };
+        return substitute(payload, dir, dirPlaceholder);
+      })
+    );
+  } finally {
+    process.chdir(previousCwd);
+    if (realChildPid !== undefined) {
+      try {
+        process.kill(realChildPid, 'SIGKILL');
+      } catch {
+        // already exited - the expected disposition.
+      }
+    }
+  }
+}
+
+// --- status ----------------------------------------------------------------------
+
+function handleStatus(testCase) {
+  const dir = scratch();
+  const spec = substitute(testCase, dirPlaceholder, dir);
+  if (spec.contents !== undefined) {
+    writeFileSync(commanderStatusFile(spec.recordId ?? spec.runnerId, dir), spec.contents);
+  }
+  let identityCalls = 0;
+  const reader =
+    spec.identity === undefined
+      ? undefined
+      : (pid) => {
+          identityCalls += 1;
+          if (spec.identity.mode === 'none') {
+            return undefined;
+          }
+          return {
+            command: spec.identity.command,
+            ...(spec.identity.startedAt === undefined
+              ? {}
+              : { startedAt: spec.identity.startedAt }),
+          };
+        };
+  const result = outcome(() => statusJson(commanderDaemonStatus(spec.runnerId, dir, reader)));
+  return substitute({ result, identityCalls }, dir, dirPlaceholder);
+}
+
+// --- wait ------------------------------------------------------------------------
+
+async function handleWait(testCase) {
+  const dir = scratch();
+  const spec = substitute(testCase, dirPlaceholder, dir);
+  let nowCalls = 0;
+  let statusCalls = 0;
+  let readCalls = 0;
+  const now =
+    spec.nows === undefined
+      ? undefined
+      : () => {
+          const value = spec.nows[Math.min(nowCalls, spec.nows.length - 1)];
+          nowCalls += 1;
+          return value;
+        };
+  const statusImpl =
+    spec.statuses === undefined
+      ? undefined
+      : () => {
+          const value = spec.statuses[Math.min(statusCalls, spec.statuses.length - 1)];
+          statusCalls += 1;
+          if (value.status === 'missing') {
+            return {
+              status: 'missing',
+              runnerId: spec.runnerId,
+              statusFile: value.statusFile,
+            };
+          }
+          return { status: value.status, record: value.record };
+        };
+  const readTextFile =
+    spec.logs === undefined
+      ? undefined
+      : () => {
+          const value = spec.logs[Math.min(readCalls, spec.logs.length - 1)];
+          readCalls += 1;
+          return value === null ? undefined : value;
+        };
+  if (spec.realLog !== undefined) {
+    writeFileSync(join(dir, 'daemon.log'), spec.realLog.initial);
+    if (spec.realLog.append !== undefined) {
+      setTimeout(() => {
+        try {
+          appendFileSync(join(dir, 'daemon.log'), spec.realLog.append);
+        } catch {
+          // the wait already settled and the scratch is being torn down.
+        }
+      }, spec.realLog.appendAfterMs);
+    }
+  }
+  let result;
+  try {
+    const value = await waitForCommanderDaemon({
+      runnerId: spec.runnerId,
+      timeoutMs: spec.timeoutMs,
+      statusDir: dir,
+      now,
+      readTextFile,
+      statusImpl,
+    });
+    result = { defined: true, value };
+  } catch (error) {
+    result = {
+      threw: true,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+  return substitute(
+    {
+      result,
+      nowCalls: spec.nows === undefined ? null : nowCalls,
+      statusCalls: spec.statuses === undefined ? null : statusCalls,
+      readCalls: spec.logs === undefined ? null : readCalls,
+    },
+    dir,
+    dirPlaceholder
+  );
+}
+
+// --- stop ------------------------------------------------------------------------
+
+function maskStatusPid(result, pid) {
+  if (result.defined !== true || pid === undefined) {
+    return result;
+  }
+  const value = result.value;
+  if (value.record === undefined || value.record.pid !== pid) {
+    return result;
+  }
+  return {
+    defined: true,
+    value: { ...value, record: { ...value.record, pid: '<PID>' } },
+  };
+}
+
+async function handleStop(testCase) {
+  const dir = scratch();
+  const spec = substitute(testCase, dirPlaceholder, dir);
+  let child;
+  let childExited = null;
+  if (spec.mode === 'liveChild') {
+    child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], {
+      stdio: 'ignore',
+    });
+    // Let the exec settle so the real ps probe sees the command line.
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    const record = {
+      runnerId: spec.runnerId,
+      pid: child.pid,
+      cwd: '/',
+      logFile: '/nonexistent-daemon.log',
+      startedAt: '2026-07-01T00:00:00.000Z',
+      command: [],
+    };
+    writeFileSync(
+      commanderStatusFile(spec.runnerId, dir),
+      JSON.stringify(record, null, 2) + '\\n'
+    );
+  } else if (spec.contents !== undefined) {
+    writeFileSync(commanderStatusFile(spec.runnerId, dir), spec.contents);
+  }
+  const result = outcome(() => statusJson(stopCommanderDaemon(spec.runnerId, dir)));
+  if (child !== undefined) {
+    childExited = await new Promise((resolve) => {
+      if (child.exitCode !== null || child.signalCode !== null) {
+        resolve(true);
+        return;
+      }
+      const timer = setTimeout(() => resolve(false), 5000);
+      child.on('exit', () => {
+        clearTimeout(timer);
+        resolve(true);
+      });
+    });
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      // already exited - the expected disposition.
+    }
+  }
+  return substitute(
+    { result: maskStatusPid(result, child?.pid), childExited },
+    dir,
+    dirPlaceholder
+  );
+}
+
+// --- Dispatch --------------------------------------------------------------------
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'paths':
+      return handlePaths(testCase);
+    case 'start':
+      return handleStart(testCase);
+    case 'status':
+      return handleStatus(testCase);
+    case 'wait':
+      return handleWait(testCase);
+    case 'stop':
+      return handleStop(testCase);
+    default:
+      return { threw: true, message: 'unknown op ' + String(testCase.op) };
+  }
+}
+
+let stdin = '';
+process.stdin.setEncoding('utf8');
+for await (const chunk of process.stdin) {
+  stdin += chunk;
+}
+const cases = JSON.parse(stdin);
+const results = [];
+for (const testCase of cases) {
+  results.push(await handle(testCase));
+}
+process.stdout.write(JSON.stringify(results));
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'core-daemon-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/core-daemon-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  // commanderDaemon.ts pulls only the runnerLogger/namingDualEmit slice of
+  // the commander graph; the runtime externals stay aligned with the other
+  // cluster oracles so a future graph widening cannot silently inline them.
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});