@linzumi/cli 1.0.118 → 1.0.119

package/scripts/build-mcp-parity-oracle.mjs

@@ -0,0 +1,357 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 14, mcp).
+// Relationship: Builds the TS-side PARITY ORACLE for the mcp cluster of the
+// ReScript commander port. Two artifacts:
+//
+//   1. .differential/mcp-parity-oracle.mjs - the REAL TS mcp modules
+//      (mcpConfig.ts, mcpServer.ts, mcpServerEntry.ts, linzumiApiClient.ts,
+//      devServiceRegistry.ts, mediaGuidance.ts) behind a one-shot stdin/stdout
+//      JSON batch driver. The ReScript parity conformance
+//      (packages/linzumi-cli-rescript/src/parity/McpParityConformance.res)
+//      drives the SAME inputs through the ported modules and compares
+//      serialized results byte for byte. The `toolSurface` op runs the REAL
+//      registerLinzumiMcpTools against a capturing fake server + a recording
+//      fetch, so tool names/descriptions/schema verdicts/handler request
+//      mappings are all differential.
+//
+//   2. .differential/mcp-server-oracle-entry.mjs - a runnable bundle of the
+//      REAL src/mcpServerEntry.ts, so the flow suite
+//      (McpLawsConformance.res) can spawn the TS MCP server as a stdio child
+//      next to the ReScript entry and assert byte-equal JSON-RPC traffic,
+//      stdout/stderr, and scripted-backend requests.
+//
+// Like the sibling oracles, both outputs are local test artifacts
+// (.differential/ is gitignored, never published) and stay 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 {
+  claudeCodeMcpConfigJson,
+  codexMcpConfigArgs,
+  codexMcpConfigToml,
+  linzumiMcpCommandForProcess,
+  linzumiMcpServerConfig,
+} from './src/mcpConfig';
+import {
+  absolutizeAttachmentUrls,
+  customEmojiNameSchema,
+  devServiceStatusJson,
+  devServicesOptionsFromEnv,
+  mcpHelpText,
+  mcpJsonResult,
+  mcpOperatingMode,
+  mcpToolScope,
+  normalizeCustomEmojiNameForSchema,
+  paramsWithDefaultThread,
+  registerLinzumiMcpTools,
+  resolveLinzumiUploadUrl,
+  strictFlagValues,
+  targetWithDefaultThread,
+  textModeGatedMessagePostingMcpTools,
+  uiControlToolResult,
+  withUploadChannelRemediation,
+} from './src/mcpServer';
+import { createLinzumiMcpApiClient } from './src/linzumiApiClient';
+import {
+  devServiceLogPath,
+  devServiceWatchdogProgram,
+  devServiceWatchdogSpawn,
+  devServicesScopeDir,
+  normalizeDevServiceName,
+  parseDevServiceRecord,
+} from './src/devServiceRegistry';
+import { linzumiMarkdownMediaGuidance } from './src/mediaGuidance';
+import { z } from 'zod/v3';
+
+// mcpServerEntry.ts auto-runs when import.meta.url matches argv[1] - true for
+// this bundle when node runs it directly. Import it DYNAMICALLY behind an
+// argv[1] guard so the real module's direct-invocation gate stays untouched
+// but cannot fire inside the oracle.
+const argv1ForEntryImport = process.argv[1];
+process.argv[1] = '/linzumi-mcp-parity-oracle-guard';
+const { mcpServerEntryArgs } = await import('./src/mcpServerEntry');
+process.argv[1] = argv1ForEntryImport;
+
+// Encode a call outcome so undefined stays distinguishable from null after
+// JSON serialization.
+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) };
+  }
+}
+
+async function asyncOutcome(run) {
+  try {
+    const value = await run();
+    return value === undefined ? { defined: false } : { defined: true, value };
+  } catch (error) {
+    return { threw: true, message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function safeParseVerdict(schema, input) {
+  const parsed = schema.safeParse(input);
+  return parsed.success
+    ? { success: true, data: parsed.data === undefined ? null : parsed.data }
+    : {
+        success: false,
+        issues: JSON.parse(JSON.stringify(parsed.error.issues)),
+      };
+}
+
+// A recording fetch for the api-client seam: every request is captured and
+// answered from the scripted queue (default {ok: true}).
+function recordingFetch(script) {
+  const requests = [];
+  const responses = [...(script?.responses ?? [])];
+  const fetchImpl = async (url, init) => {
+    requests.push({
+      url: String(url),
+      method: init?.method ?? 'GET',
+      authorization: init?.headers?.authorization ?? null,
+      contentType: init?.headers?.['content-type'] ?? null,
+      body: typeof init?.body === 'string' ? init.body : null,
+    });
+    const next = responses.shift() ?? { status: 200, body: { ok: true } };
+    return new Response(JSON.stringify(next.body), {
+      status: next.status ?? 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  };
+  return { requests, fetchImpl };
+}
+
+async function toolSurface(testCase) {
+  const captured = [];
+  const handlers = new Map();
+  const fakeServer = {
+    tool(name, description, shape, handler) {
+      captured.push({ name, description, schemaKeys: Object.keys(shape) });
+      handlers.set(name, { shape, handler });
+    },
+  };
+  const { requests, fetchImpl } = recordingFetch(testCase.script);
+  const client = createLinzumiMcpApiClient({
+    kandanUrl: testCase.options.apiUrl,
+    accessToken: 'synthetic-parity-token',
+    authMode: testCase.options.authMode,
+    operatingMode: testCase.options.operatingMode,
+    fetchImpl,
+  });
+  registerLinzumiMcpTools(fakeServer, {
+    client,
+    toolScope: testCase.options.toolScope,
+    operatingMode: testCase.options.operatingMode,
+    cwd: testCase.options.cwd,
+    kandanUrl: testCase.options.apiUrl,
+    defaultThreadId: testCase.options.defaultThreadId ?? undefined,
+    ownerUsername: testCase.options.ownerUsername ?? undefined,
+    agentSession: testCase.options.agentSession === true,
+    devServices:
+      testCase.options.devServices === undefined || testCase.options.devServices === null
+        ? undefined
+        : testCase.options.devServices,
+  });
+
+  const probes = [];
+  for (const probe of testCase.probes ?? []) {
+    const entry = handlers.get(probe.tool);
+    probes.push(
+      entry === undefined
+        ? { tool: probe.tool, missing: true }
+        : { tool: probe.tool, verdict: safeParseVerdict(z.object(entry.shape), probe.input) }
+    );
+  }
+
+  const calls = [];
+  for (const call of testCase.calls ?? []) {
+    const entry = handlers.get(call.tool);
+    if (entry === undefined) {
+      calls.push({ tool: call.tool, missing: true });
+      continue;
+    }
+    const before = requests.length;
+    const result = await asyncOutcome(() => entry.handler(call.params));
+    calls.push({ tool: call.tool, result, requests: requests.slice(before) });
+  }
+
+  return { tools: captured, probes, calls };
+}
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'serverConfig': {
+      const config = outcome(() => linzumiMcpServerConfig(testCase.options));
+      if (config.threw === true || config.defined !== true) {
+        return { config };
+      }
+      return {
+        config,
+        codexArgs: outcome(() => codexMcpConfigArgs(config.value)),
+        codexToml: outcome(() => codexMcpConfigToml(config.value)),
+        claudeCodeJson: outcome(() => claudeCodeMcpConfigJson(config.value)),
+      };
+    }
+    case 'commandForProcess':
+      return outcome(() =>
+        linzumiMcpCommandForProcess(
+          testCase.processExecPath,
+          testCase.scriptPath ?? undefined,
+          testCase.execArgv ?? []
+        )
+      );
+    case 'strictFlags':
+      return outcome(() => [...strictFlagValues(testCase.args).entries()]);
+    case 'helpText':
+      return mcpHelpText();
+    case 'mediaGuidance':
+      return linzumiMarkdownMediaGuidance;
+    case 'entryArgs':
+      return mcpServerEntryArgs(testCase.argv);
+    case 'operatingMode':
+      return outcome(() => mcpOperatingMode(testCase.value ?? undefined));
+    case 'toolScope':
+      return outcome(() => mcpToolScope(testCase.value ?? undefined));
+    case 'textModeGatedTools':
+      return [...textModeGatedMessagePostingMcpTools];
+    case 'mcpJsonResult':
+      return mcpJsonResult(testCase.value);
+    case 'uiControlResult':
+      return await asyncOutcome(() =>
+        uiControlToolResult(
+          testCase.throwMessage === undefined || testCase.throwMessage === null
+            ? Promise.resolve(testCase.value)
+            : Promise.reject(new Error(testCase.throwMessage))
+        )
+      );
+    case 'uploadRemediation': {
+      const mapped = withUploadChannelRemediation(new Error(testCase.message));
+      return {
+        message: mapped instanceof Error ? mapped.message : String(mapped),
+        causeMessage:
+          mapped instanceof Error && mapped.cause instanceof Error
+            ? mapped.cause.message
+            : null,
+      };
+    }
+    case 'targetWithDefaultThread':
+      return targetWithDefaultThread(testCase.target, testCase.defaultThreadId ?? undefined);
+    case 'paramsWithDefaultThread':
+      return paramsWithDefaultThread(testCase.params, testCase.defaultThreadId ?? undefined);
+    case 'resolveUploadUrl':
+      return outcome(() => resolveLinzumiUploadUrl(testCase.apiUrl, testCase.uploadUrl));
+    case 'absolutize':
+      return outcome(() => absolutizeAttachmentUrls(testCase.apiUrl, testCase.result));
+    case 'emojiNormalize':
+      return normalizeCustomEmojiNameForSchema(testCase.value);
+    case 'emojiSchemaVerdict':
+      return safeParseVerdict(customEmojiNameSchema, testCase.value);
+    case 'devServicesOptionsFromEnv':
+      return outcome(() => devServicesOptionsFromEnv(testCase.env));
+    case 'devServicesScopeDir':
+      return devServicesScopeDir(testCase.scope);
+    case 'normalizeDevServiceName':
+      return outcome(() => normalizeDevServiceName(testCase.name));
+    case 'devServiceLogPath':
+      return devServiceLogPath(testCase.scopeDir, testCase.name);
+    case 'parseDevServiceRecord':
+      return outcome(() => parseDevServiceRecord(testCase.value));
+    case 'watchdogProgram':
+      return devServiceWatchdogProgram();
+    case 'watchdogSpawn':
+      return devServiceWatchdogSpawn(testCase.nodeExecPath, testCase.config);
+    case 'devServiceStatusJson':
+      return devServiceStatusJson({
+        record: testCase.status.record,
+        liveness: testCase.status.liveness,
+        portProbes: testCase.status.portProbes,
+        lastExit: testCase.status.lastExit ?? undefined,
+      });
+    case 'toolSurface':
+      return await toolSurface(testCase);
+    case 'clientCall': {
+      // One api-client method driven directly (the full method->endpoint
+      // map, including the runner-internal endpoints no MCP tool calls).
+      const { requests, fetchImpl } = recordingFetch(testCase.script);
+      const client = createLinzumiMcpApiClient({
+        kandanUrl: testCase.apiUrl,
+        accessToken: 'synthetic-parity-token',
+        authMode: testCase.authMode ?? undefined,
+        operatingMode: testCase.operatingMode ?? undefined,
+        fetchImpl,
+      });
+      const method = client[testCase.method];
+      if (typeof method !== 'function') {
+        return { threw: true, message: 'unknown client method ' + testCase.method };
+      }
+      const result = await asyncOutcome(() => method(testCase.params));
+      return { result, requests };
+    }
+    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 });
+
+const banner = {
+  js: "import { createRequire } from 'node:module';\nconst require = createRequire(import.meta.url);",
+};
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'mcp-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/mcp-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+  banner,
+});
+
+// The runnable REAL TS MCP server entry, for the flow-parity legs: same code
+// path as `linzumi mcp ...` (mcpServerEntry strips the leading 'mcp' and
+// dispatches through runMcpCommand), bundled unminified like the driver.
+await build({
+  entryPoints: [join(packageRoot, 'src/mcpServerEntry.ts')],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/mcp-server-oracle-entry.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+  banner,
+});

package/scripts/build-mcp-selector-parity-oracle.mjs

@@ -0,0 +1,65 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 14, mcp-editor-forwarding-vm-sandbox - the explicit
+// mcp-server.mjs selector story).
+// Relationship: Builds the TS-side PARITY ORACLE for the mcp-server.mjs
+// dual-impl selector seam. The oracle bundles the REAL
+// mcpServerBundleCandidates ladder (src/vmSandbox/startVmCodexAppServer.ts,
+// the guest-injection selection-by-co-location seam) behind a one-shot
+// batch driver: a JSON array of cases on stdin, a JSON array of results on
+// stdout. The ReScript package's selector conformance
+// (packages/linzumi-cli-rescript/src/parity/McpSelectorConformance.res)
+// drives the SAME cases through CommanderMcpBundleSelection and asserts
+// the candidate ladders byte-equal - the two impls' selectors cannot
+// drift while both ship. Post-M4.3 the ladder collapses to its bare
+// ['mcp-server.mjs'] tail and this oracle retires with the TS impl.
+//
+// Like the other parity oracles, 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 { mcpServerBundleCandidates } from './src/vmSandbox/startVmCodexAppServer';
+
+function handle(testCase) {
+  switch (testCase.op) {
+    case 'candidates':
+      return { candidates: mcpServerBundleCandidates(testCase.impl) };
+    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);
+process.stdout.write(JSON.stringify(cases.map(handle)));
+`;
+
+await mkdir(join(packageRoot, '.differential'), { recursive: true });
+
+await build({
+  stdin: {
+    contents: driverSource,
+    resolveDir: packageRoot,
+    sourcefile: 'mcp-selector-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/mcp-selector-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});