@linzumi/cli 1.0.116 → 1.0.118

package/scripts/build-onboarding-support-parity-oracle.mjs

@@ -0,0 +1,484 @@
+// Spec: kandan/plans/2026-07-10-compute-nodes-rescript-commander-zero-ts-program.md
+// (M3 cluster 13, onboarding - the SUPPORT slice: the commander-side
+// starter-task suggestion engine and the hello-demo project materializer).
+// Relationship: Builds the TS-side PARITY ORACLE for the onboarding
+// support modules of the ReScript commander port, the sibling of
+// build-worker-entry-parity-oracle.mjs (cluster 12). The oracle bundles
+// the REAL signupTaskSuggestions.ts (suggestSignupTasksWithCodex /
+// signupTaskSuggestionProcessForTest + the tagged oracle exports of the
+// model/prompt/schema/parse internals), signupTaskSuggestionsProgress.ts
+// (progressLabelForCodexEvent / createTaskSuggestionProgressParser), and
+// helloLinzumiProject.ts (createHelloLinzumiProject + the default
+// constants) behind the cluster 1/2 one-shot BATCH driver (a JSON array
+// of cases on stdin, a JSON array of results on stdout).
+//
+// Determinism + normalization: fs cases run in realpath'd scratch dirs (or
+// a caller-provided externalRoot for the hello byte-tree law, so both
+// impls can build at the SAME root and compare without normalization);
+// paths normalize through the "$DIR" placeholder and the random
+// linzumi-signup-codex-tasks-* scratch roots through the "$TASKS"
+// placeholder. The suggestion flow's codex binary is a case-scripted
+// executable planted from the case tree, so both impls drive identical
+// bytes.
+//
+// helloLinzumiProject.ts reads its logo asset relative to the bundled
+// module, so the build copies src/assets/linzumi-logo.svg next to the
+// bundle (.differential/assets/).
+//
+// SECRETS: the oracle only ever sees the conformance suite's synthetic
+// trees and synthetic credentials. The output is a local test artifact
+// (.differential/ is gitignored, never published) and stays unminified
+// for debuggability.
+import { copyFile, 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 {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname as pathDirname, join, relative } from 'node:path';
+import {
+  parseTaskSuggestionResponseForTest,
+  resolveTaskSuggestionModelForTest,
+  signupTaskSuggestionProcessForTest,
+  suggestSignupTasksWithCodex,
+  taskSuggestionJsonSchemaForTest,
+  taskSuggestionPromptForTest,
+} from './src/signupTaskSuggestions';
+import {
+  createTaskSuggestionProgressParser,
+  progressLabelForCodexEvent,
+} from './src/signupTaskSuggestionsProgress';
+import {
+  createHelloLinzumiProject,
+  defaultHelloLinzumiHost,
+  defaultHelloLinzumiParentDir,
+  defaultHelloLinzumiPort,
+  defaultHelloLinzumiProjectDir,
+  defaultHelloLinzumiProjectName,
+} from './src/helloLinzumiProject';
+
+// --- 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-onboarding-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;
+}
+
+// The suggestion flow's per-attempt scratch roots are random mkdtemp dirs
+// under the OS tmpdir; normalize the WHOLE path through one placeholder.
+function normalizeTasksTemp(value) {
+  if (typeof value === 'string') {
+    return value.replace(/\\S*linzumi-signup-codex-tasks-[^/"'\\s]+/g, '$TASKS');
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => normalizeTasksTemp(entry));
+  }
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        normalizeTasksTemp(key),
+        normalizeTasksTemp(entry),
+      ])
+    );
+  }
+  return value;
+}
+
+function buildTree(root, files) {
+  for (const [relPath, spec] of Object.entries(files ?? {})) {
+    const full = join(root, relPath);
+    if (relPath.endsWith('/')) {
+      mkdirSync(full, { recursive: true });
+    } else {
+      mkdirSync(pathDirname(full), { recursive: true });
+      if (spec !== null && typeof spec === 'object') {
+        writeFileSync(full, String(spec.content), 'utf8');
+        if (spec.mode !== undefined) {
+          chmodSync(full, spec.mode);
+        }
+      } else {
+        writeFileSync(full, String(spec), 'utf8');
+      }
+    }
+  }
+}
+
+function snapshotFiles(dir) {
+  const files = {};
+  const walk = (current) => {
+    let names;
+    try {
+      names = readdirSync(current).sort();
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const full = join(current, name);
+      const stats = statSync(full);
+      if (stats.isDirectory()) {
+        files[relative(dir, full) + '/'] = '<dir>';
+        walk(full);
+      } else {
+        files[relative(dir, full)] = {
+          content: readFileSync(full, 'utf8'),
+          mode: stats.mode & 0o777,
+        };
+      }
+    }
+  };
+  walk(dir);
+  return files;
+}
+
+// Env manipulation is per-case and restored afterwards (the batch runs
+// sequentially in one process).
+function withEnv(overrides, run) {
+  const saved = {};
+  for (const [key, value] of Object.entries(overrides)) {
+    saved[key] = process.env[key];
+    if (value === null) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+  const restore = () => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  };
+  return { run, restore };
+}
+
+async function runWithEnv(overrides, run) {
+  const { restore } = withEnv(overrides, run);
+  try {
+    return await run();
+  } finally {
+    restore();
+  }
+}
+
+// --- Suggestion transforms ---------------------------------------------------------
+
+function handleResolveModel(testCase) {
+  return runWithEnv(
+    { LINZUMI_SIGNUP_TASK_MODEL: testCase.envModel ?? null },
+    () => ({
+      value: resolveTaskSuggestionModelForTest(
+        testCase.explicitModel ?? undefined,
+        testCase.wafer === true
+          ? {
+              config: {
+                id: 'linzumi',
+                name: 'Linzumi',
+                baseUrl: 'https://example.invalid/llm',
+                envKey: 'LINZUMI_LLM_PROXY_TOKEN',
+                wireApi: 'responses',
+              },
+              env: {},
+            }
+          : undefined
+      ),
+    })
+  );
+}
+
+function providerOfCase(spec) {
+  if (spec === undefined || spec === null) {
+    return undefined;
+  }
+  return {
+    config: {
+      id: spec.config.id,
+      name: spec.config.name,
+      baseUrl: spec.config.baseUrl,
+      envKey: spec.config.envKey,
+      wireApi: spec.config.wireApi,
+      ...(spec.config.httpHeaders === undefined ? {} : { httpHeaders: spec.config.httpHeaders }),
+      ...(spec.config.envHttpHeaders === undefined
+        ? {}
+        : { envHttpHeaders: spec.config.envHttpHeaders }),
+    },
+    env: spec.env ?? {},
+  };
+}
+
+function handleBuildProcess(testCase) {
+  const built = signupTaskSuggestionProcessForTest({
+    command: testCase.command,
+    model: testCase.model,
+    ...(testCase.modelProvider === undefined
+      ? {}
+      : { modelProvider: providerOfCase(testCase.modelProvider) }),
+    projectPath: testCase.projectPath,
+    schemaPath: testCase.schemaPath,
+    outputPath: testCase.outputPath,
+    prompt: testCase.prompt,
+    ...(testCase.timeoutMs === undefined ? {} : { timeoutMs: testCase.timeoutMs }),
+    codexHome: testCase.codexHome,
+    ...(testCase.forwardableOpenAiApiKey === undefined
+      ? {}
+      : { forwardableOpenAiApiKey: testCase.forwardableOpenAiApiKey }),
+  });
+  return {
+    value: {
+      command: built.command,
+      args: [...built.args],
+      cwd: built.cwd,
+      stdin: built.stdin,
+      env: built.env ?? null,
+      timeoutMs: built.timeoutMs,
+    },
+  };
+}
+
+function handleProgressChunks(testCase) {
+  const labels = [];
+  const throwOn = new Set(testCase.throwOnLabels ?? []);
+  const parser = createTaskSuggestionProgressParser((label) => {
+    labels.push(label);
+    if (throwOn.has(label)) {
+      throw new Error('scripted consumer failure');
+    }
+  });
+  for (const chunk of testCase.chunks ?? []) {
+    parser.push(chunk);
+  }
+  if (testCase.flush !== false) {
+    parser.flush();
+  }
+  return { labels };
+}
+
+// --- The suggestion flow -------------------------------------------------------------
+
+async function handleSuggestFlow(testCase) {
+  const dir = scratch();
+  const sub = (value) => substitute(value, dirPlaceholder, dir);
+  buildTree(dir, sub(testCase.files ?? {}));
+
+  const labels = [];
+  const onProgress =
+    testCase.withProgress === true ? (label) => labels.push(label) : undefined;
+
+  const outcome = await runWithEnv(
+    {
+      LINZUMI_CODEX_HOME: join(dir, 'isolated-home'),
+      CODEX_HOME: join(dir, 'user-codex'),
+      OPENAI_API_KEY: null,
+      LINZUMI_SIGNUP_TASK_MODEL: null,
+    },
+    async () => {
+      try {
+        const tasks = await suggestSignupTasksWithCodex({
+          projectPath: join(dir, testCase.projectRelDir ?? 'project'),
+          codexBin: sub(testCase.codexBin),
+          ...(testCase.model === undefined ? {} : { model: testCase.model }),
+          ...(testCase.modelProvider === undefined
+            ? {}
+            : { modelProvider: providerOfCase(sub(testCase.modelProvider)) }),
+          ...(onProgress === undefined ? {} : { onProgress }),
+        });
+        return { ok: true, tasks };
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  );
+
+  // Give any straggling stdout events a beat before reading labels (the
+  // scripted binary sleeps before exiting, so labels are ordinarily
+  // delivered pre-exit in both impls).
+  await new Promise((resolve) => setTimeout(resolve, 50));
+
+  const invocationsPath = join(dir, 'invocations.jsonl');
+  const invocations = existsSync(invocationsPath)
+    ? readFileSync(invocationsPath, 'utf8')
+        .split('\\n')
+        .filter((line) => line !== '')
+        .map((line) => JSON.parse(line))
+    : [];
+
+  // The per-attempt scratch roots must be gone after the flow (the TS
+  // finally); derive them from the recorded argv.
+  const tempRoots = new Set();
+  for (const invocation of invocations) {
+    const index = invocation.argv.indexOf('--output-schema');
+    if (index !== -1) {
+      tempRoots.add(pathDirname(invocation.argv[index + 1]));
+    }
+  }
+  const tempRootsGone = [...tempRoots].every((root) => !existsSync(root));
+
+  const result = {
+    outcome,
+    labels,
+    invocations,
+    isolatedHome: snapshotFiles(join(dir, 'isolated-home')),
+    tempRootsGone,
+  };
+  return normalizeTasksTemp(substitute(result, dir, dirPlaceholder));
+}
+
+// --- The hello-demo project ----------------------------------------------------------
+
+function handleHelloCreate(testCase) {
+  const externalRoot = testCase.externalRoot;
+  const dir = externalRoot ?? scratch();
+  const sub = (value) => substitute(value, dirPlaceholder, dir);
+  buildTree(dir, sub(testCase.files ?? {}));
+
+  let result;
+  try {
+    const input = sub(testCase.input);
+    const project = createHelloLinzumiProject(
+      typeof input === 'string'
+        ? input
+        : {
+            ...(input.rootPath === undefined ? {} : { rootPath: input.rootPath }),
+            ...(input.parentDir === undefined ? {} : { parentDir: input.parentDir }),
+            ...(input.name === undefined ? {} : { name: input.name }),
+            ...(input.port === undefined ? {} : { port: input.port }),
+            ...(input.host === undefined ? {} : { host: input.host }),
+            ...(input.reset === undefined ? {} : { reset: input.reset }),
+          }
+    );
+    result = { ok: project };
+  } catch (error) {
+    result = { threw: error instanceof Error ? error.message : String(error) };
+  }
+
+  return substitute(
+    {
+      result,
+      ...(externalRoot === undefined ? { tree: snapshotFiles(dir) } : {}),
+    },
+    dir,
+    dirPlaceholder
+  );
+}
+
+// --- Dispatch -----------------------------------------------------------------------
+
+async function handle(testCase) {
+  switch (testCase.op) {
+    case 'resolveModel':
+      return handleResolveModel(testCase);
+    case 'prompt':
+      return { value: taskSuggestionPromptForTest(testCase.previousResponse ?? undefined) };
+    case 'schemaFile':
+      return {
+        value: JSON.stringify(taskSuggestionJsonSchemaForTest(), null, 2) + '\\n',
+      };
+    case 'parseResponse': {
+      const parsed = parseTaskSuggestionResponseForTest(testCase.response);
+      return { value: parsed === undefined ? null : parsed };
+    }
+    case 'buildProcess':
+      return handleBuildProcess(testCase);
+    case 'progressEvent': {
+      const label = progressLabelForCodexEvent(testCase.event);
+      return { value: label === undefined ? null : label };
+    }
+    case 'progressChunks':
+      return handleProgressChunks(testCase);
+    case 'suggestFlow':
+      return handleSuggestFlow(testCase);
+    case 'helloCreate':
+      return handleHelloCreate(testCase);
+    case 'helloDefaults':
+      return {
+        value: {
+          projectDir: defaultHelloLinzumiProjectDir,
+          projectName: defaultHelloLinzumiProjectName,
+          parentDir: defaultHelloLinzumiParentDir,
+          port: defaultHelloLinzumiPort,
+          host: defaultHelloLinzumiHost,
+        },
+      };
+    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: 'onboarding-support-parity-driver.ts',
+    loader: 'ts',
+  },
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  outfile: join(packageRoot, '.differential/onboarding-support-parity-oracle.mjs'),
+  minify: false,
+  sourcemap: false,
+  legalComments: 'none',
+  external: ['ws', 'undici', 'blessed', '@anthropic-ai/claude-agent-sdk'],
+});
+
+// helloLinzumiProject.ts reads its logo relative to the executing module;
+// the bundle executes from .differential/, so mirror the asset beside it.
+await mkdir(join(packageRoot, '.differential/assets'), { recursive: true });
+await copyFile(
+  join(packageRoot, 'src/assets/linzumi-logo.svg'),
+  join(packageRoot, '.differential/assets/linzumi-logo.svg')
+);