@linzumi/cli 1.0.91 → 1.0.93

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "1.0.91",
+  "version": "1.0.93",
   "description": "Linzumi CLI \u2014 point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {

package/scripts/build-differential-entry.mjs

@@ -0,0 +1,160 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md (M2.5 + M2.6)
+// Relationship: Builds the TS-impl differential entry
+// (src/differentialCommanderEntry.ts) into a single runnable bundle at
+// .differential/impl-ts.mjs, mirroring the published dist/index.js build
+// configuration (same platform/target/format/externals/banner) so the
+// differential harness exercises the SAME bundling reality the shipped CLI
+// has - this is the M3 packaging seam's dist/impl-ts precursor: the M3
+// chooser design ships dist/impl-ts/ + dist/impl-res/ side by side, and the
+// M2.5 differential runner's impl parameter selects between them (impl-res
+// fails honestly until M3 cluster 1 lands).
+//
+// M2.6 mutation mode (`--mutation <name>`): applies ONE seeded behavior
+// delta from scripts/differentialMutations.mjs as a build-time source patch
+// and emits .differential/impl-ts.mutant-<name>.mjs instead. The harness's
+// anti-false-green mutation check builds each mutant and asserts the
+// differential suite goes RED on it. Every patch anchor must match the
+// current source EXACTLY ONCE - zero or multiple matches fail the build
+// loudly, so a commander refactor can never silently no-op a mutation.
+//
+// Unminified deliberately: the bundle is a local test artifact
+// (.differential/ is gitignored, never published), and readable output makes
+// differential findings debuggable.
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { differentialMutations } from './differentialMutations.mjs';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function parseArgs(argv) {
+  if (argv.length === 0) {
+    return { mutation: undefined };
+  }
+  if (argv[0] === '--mutation' && argv.length === 2) {
+    const mutation = differentialMutations.find(
+      (entry) => entry.name === argv[1]
+    );
+    if (mutation === undefined) {
+      const known = differentialMutations.map((entry) => entry.name);
+      throw new Error(
+        `unknown differential mutation ${JSON.stringify(argv[1])}; known mutations: ${known.join(', ')}`
+      );
+    }
+    return { mutation };
+  }
+  throw new Error(
+    'usage: node scripts/build-differential-entry.mjs [--mutation <name>]'
+  );
+}
+
+const { mutation } = parseArgs(process.argv.slice(2));
+
+// Count non-overlapping occurrences of `needle` in `haystack`. An empty
+// needle is a registry authoring error, refused loudly (indexOf('') matches
+// at every position, which would both loop forever here and make the
+// exactly-once rule meaningless); the harness registry conformance pins the
+// same rule at rest (Greptile finding on #3115).
+function occurrences(haystack, needle) {
+  if (needle.length === 0) {
+    throw new Error('mutation patch `find` must be a non-empty string');
+  }
+  let count = 0;
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) {
+      return count;
+    }
+    count += 1;
+    from = at + needle.length;
+  }
+}
+
+// esbuild onLoad plugin: apply the mutation's patches to their target
+// sources, enforcing the exactly-once anchor rule per patch. Also asserts
+// every patch was actually loaded by the bundle (a patched-but-unbundled
+// file would be a silent no-op mutation).
+function mutationPlugin(activeMutation) {
+  const patchesByFile = new Map();
+  for (const patch of activeMutation.patches) {
+    const absolute = join(packageRoot, patch.file);
+    const existing = patchesByFile.get(absolute) ?? [];
+    existing.push(patch);
+    patchesByFile.set(absolute, existing);
+  }
+  const applied = new Set();
+
+  return {
+    plugin: {
+      name: 'differential-mutation',
+      setup(pluginBuild) {
+        pluginBuild.onLoad({ filter: /\.ts$/ }, async (args) => {
+          const patches = patchesByFile.get(args.path);
+          if (patches === undefined) {
+            return undefined;
+          }
+          let contents = await readFile(args.path, 'utf8');
+          for (const patch of patches) {
+            const found = occurrences(contents, patch.find);
+            if (found !== 1) {
+              throw new Error(
+                `mutation ${activeMutation.name}: anchor in ${patch.file} matched ${found} times (must match exactly once); the commander source moved - re-anchor the patch in scripts/differentialMutations.mjs`
+              );
+            }
+            contents = contents.replace(patch.find, patch.replace);
+            applied.add(`${patch.file}:${patch.find.slice(0, 40)}`);
+          }
+          return { contents, loader: 'ts' };
+        });
+      },
+    },
+    assertAllApplied() {
+      const expected = activeMutation.patches.length;
+      if (applied.size !== expected) {
+        throw new Error(
+          `mutation ${activeMutation.name}: only ${applied.size} of ${expected} patches were loaded into the bundle - a patched file is not part of the differential entry`
+        );
+      }
+    },
+  };
+}
+
+// Renamed banner import: unlike the minified dist build, this bundle keeps
+// source-level identifiers, and the commander sources themselves import
+// createRequire - the published banner's bare name would collide.
+const banner = {
+  js: "import { createRequire as __differentialCreateRequire } from 'node:module';\nconst require = __differentialCreateRequire(import.meta.url);",
+};
+
+const outfile =
+  mutation === undefined
+    ? join(packageRoot, '.differential/impl-ts.mjs')
+    : join(packageRoot, `.differential/impl-ts.mutant-${mutation.name}.mjs`);
+
+const mutationHooks = mutation === undefined ? undefined : mutationPlugin(mutation);
+
+await build({
+  entryPoints: [join(packageRoot, 'src/differentialCommanderEntry.ts')],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile,
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+  banner,
+  plugins: mutationHooks === undefined ? [] : [mutationHooks.plugin],
+});
+
+mutationHooks?.assertAllApplied();
+
+// The runtime resolves assets/ relative to the bundle (same as dist/).
+await mkdir(join(packageRoot, '.differential/assets'), { recursive: true });
+await copyFile(
+  join(packageRoot, 'src/assets/linzumi-logo.svg'),
+  join(packageRoot, '.differential/assets/linzumi-logo.svg')
+);

package/scripts/differentialMutations.mjs

@@ -0,0 +1,113 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md (M2.6)
+// Relationship: The maintained seeded-mutation set for the differential
+// harness's anti-false-green mutation check. Each entry is a deliberate
+// behavior delta patched into the TS commander AT BUILD TIME
+// (scripts/build-differential-entry.mjs --mutation <name>); the harness's
+// MutationCheckConformance then asserts the differential suite goes RED on
+// the mutant (transcript diff for the shape/ordering classes, a named
+// ported-invariant violation for the invariant class). A seeded delta the
+// suite stays green on means the gate is lying - that conformance leg fails.
+//
+// This registry is the SINGLE source (derive, don't duplicate): the build
+// script applies `patches`, and the harness conformance imports this exact
+// module to drive and pin the set (closed classes, one mutation per class).
+//
+// MAINTENANCE RULES:
+//   - The set stays small (one mutation per class below) - every entry is a
+//     permanent CI cost, so each must earn its place by proving a DISTINCT
+//     sensitivity class of the differential canonical transcript.
+//   - `find` strings must match the current source EXACTLY ONCE; the build
+//     fails loudly on zero or multiple matches, so a refactor can never
+//     silently no-op a mutation (the anchor rot the exactly-once rule
+//     exists for).
+//   - Mutations must never remove an event a differential scenario AWAITS
+//     (the choreography synchronizes on milestones; deleting one turns a
+//     fast red into a slow timeout red).
+//   - No current-version literals (the commander-harness package rule).
+//
+// Classes (the M2.6 task's closed vocabulary):
+//   - transcript-shape: an event the commander silently stops emitting must
+//     change the canonical transcript bytes.
+//   - invariant: a behavior delta violating a ported ordering invariant
+//     must surface as that invariant's named violation.
+//   - ordering: a pure reorder of the commander's own send order (same
+//     event multiset) must change the canonical transcript bytes.
+
+export const differentialMutations = [
+  {
+    name: 'message-state-processing-drop',
+    class: 'transcript-shape',
+    scenario: 'harness-session-rebuild',
+    proves:
+      'a silently dropped message-state publish (the msg-state ladder silent-drop class: the user-visible "processing / starting turn" paint never reaches the server) changes the canonical transcript - the differential diff can see a suppressed notification type',
+    patches: [
+      {
+        file: 'src/channelSession.ts',
+        find: `  await publishQueuedMessageState(
+    args,
+    state,
+    next,
+    {
+      status: 'processing',
+      reason: 'starting turn',
+    },
+    'sent'
+  );`,
+        replace: `  // [seeded differential mutation: message-state-processing-drop] the
+  // starting-turn processing paint is silently dropped.`,
+      },
+    ],
+  },
+  {
+    name: 'join-roster-drop',
+    class: 'invariant',
+    expectInvariant: 'I319',
+    scenario: 'full-join-surfaces',
+    proves:
+      'a commander that silently drops the join-reply roster (the Commander-boots-into-empty-onboarding regression class the compute-nodes program exists to kill) under-delivers the display page and goes red as an I319 violation, not just a byte diff',
+    patches: [
+      {
+        file: 'src/runner.ts',
+        find: `  seedDashboardRosterFromReply(joinResponse, 'join');`,
+        replace: `  // [seeded differential mutation: join-roster-drop] the join-reply
+  // roster seed is silently dropped.`,
+      },
+    ],
+  },
+  {
+    name: 'handshake-initialized-reorder',
+    class: 'ordering',
+    scenario: 'harness-clean-turn',
+    proves:
+      'a pure reorder of the commander\'s own send order (the codex app-server handshake: `initialized` notified BEFORE the `initialize` request instead of after its result) changes the canonical transcript even though the event multiset is identical - per-party send order is preserved evidence, not normalized away',
+    patches: [
+      {
+        file: 'src/codexAppServer.ts',
+        // The early frame below is byte-for-byte the wire shape of the
+        // pristine `initialized` literal in codexAppServer.ts, so this
+        // mutation stays a PURE reorder. Drift teeth (Greptile finding on
+        // #3115): if the real notification ever gains fields, the early
+        // frame's content diverges and MutationCheckConformance's
+        // ordering-class assertion (equal sorted-line multiset) goes red
+        // until this patch is re-synced - the payload cannot silently rot.
+        find: `  const response = await sendRequest(websocket, pending, {
+    jsonrpc: '2.0',
+    id: 'initialize',
+    method: 'initialize',`,
+        replace: `  // [seeded differential mutation: handshake-initialized-reorder] the
+  // initialized notification jumps AHEAD of the initialize request.
+  websocket.send(JSON.stringify({ jsonrpc: '2.0', method: 'initialized' }));
+  const response = await sendRequest(websocket, pending, {
+    jsonrpc: '2.0',
+    id: 'initialize',
+    method: 'initialize',`,
+      },
+      {
+        file: 'src/codexAppServer.ts',
+        find: `  websocket.send(JSON.stringify(initialized));`,
+        replace: `  // [seeded differential mutation: handshake-initialized-reorder] the
+  // post-result send is suppressed (it already went out early above).`,
+      },
+    ],
+  },
+];