@linzumi/cli 1.0.18 → 1.0.20

package/scripts/promote-gstack-claude-smoke-fixture.ts

@@ -0,0 +1,891 @@
+/*
+- Date: 2026-06-30
+  Spec: plans/2026-06-29-gstack-claude-code-support-requirements.md
+  Relationship: One-command candidate promotion path for the first real gstack
+  Claude Code smoke fixture. It fails fast on missing local gstack setup, then
+  records exact raw provider data, normalizes the fixture, writes a candidate
+  manifest, and runs replay proofs that can be repeated locally.
+*/
+import { spawnSync } from 'node:child_process';
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scanAgentReplayInstallFiles } from '../src/agentReplayInstallSafety';
+import { agentReplayManifestPathForFixture } from '../src/agentReplayManifest';
+import { isJsonObject, type JsonObject } from '../src/protocol';
+import { normalizeAgentReplayText } from './normalize-agent-replay-fixture';
+
+type PromoteOptions = {
+  readonly outDir: string;
+  readonly rawDir: string;
+  readonly existingRawFixture: string | undefined;
+  readonly fixtureDir: string;
+  readonly providerReplayOutDir: string;
+  readonly backendReplayOutDir: string;
+  readonly browserReplayOutDir: string;
+  readonly installFixtureDir: string | undefined;
+  readonly speed: string | undefined;
+  readonly preflightOnly: boolean;
+  readonly keepWorkdirs: boolean;
+  readonly claudePermissionMode: string | undefined;
+  readonly claudeModel: string | undefined;
+  readonly gstackSkillDir: string | undefined;
+  readonly gstackCli: string | undefined;
+  readonly skipBackend: boolean;
+  readonly browserProof: boolean;
+  readonly localBrowserProof: boolean;
+  readonly backendUrl: string | undefined;
+  readonly setupFixture: boolean;
+  readonly sessionToken: string | undefined;
+  readonly workspace: string | undefined;
+  readonly channel: string | undefined;
+  readonly threadId: string | undefined;
+};
+
+type CommandResult = {
+  readonly status: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+type BackendReplayPromotionResult =
+  | { readonly type: 'skipped'; readonly reason: string }
+  | {
+      readonly type: 'ran';
+      readonly proofMode: 'backend' | 'backend-browser';
+      readonly result: CommandResult;
+    };
+
+type PromotionStatus =
+  | 'blocked'
+  | 'preflight-ok'
+  | 'provider-ready'
+  | 'backend-ready'
+  | 'browser-ready'
+  | 'failed';
+
+const thisFile = fileURLToPath(import.meta.url);
+const packageRoot = resolve(dirname(thisFile), '..');
+const repoRoot = resolve(packageRoot, '..', '..');
+const webRoot = join(repoRoot, 'kandan', 'server_v2', 'web');
+const tsxLoader = join(repoRoot, 'node_modules', 'tsx', 'dist', 'loader.mjs');
+const provider = 'gstack-claude-smoke';
+const featureId = 'gstack-claude-smoke';
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  const options = parseArgs(args);
+
+  if (options.localBrowserProof && options.backendUrl !== undefined) {
+    throw new Error(
+      'use either --local-browser-proof or --backend-url, not both'
+    );
+  }
+
+  await mkdir(options.outDir, { recursive: true });
+
+  const preflight =
+    options.existingRawFixture === undefined
+      ? runScript('record-agent-replay-fixtures.ts', [
+          '--provider',
+          provider,
+          '--preflight-only',
+          '--preflight-json',
+          '--out-dir',
+          options.rawDir,
+          ...(options.gstackSkillDir === undefined
+            ? []
+            : ['--gstack-skill-dir', options.gstackSkillDir]),
+          ...(options.gstackCli === undefined
+            ? []
+            : ['--gstack-cli', options.gstackCli]),
+        ])
+      : skippedPreflightForExistingRaw(options.existingRawFixture);
+  const preflightJson = parseJsonObjectFromCommandOutput(preflight.stdout);
+
+  if (preflight.status !== 0) {
+    const status = 'blocked';
+    await emitSummary(options, {
+      status,
+      reason: 'gstack preflight failed before fixture capture',
+      preflight: preflightJson,
+      proofPacket: proofPacket({
+        options,
+        status,
+        preflight,
+      }),
+      commands: { preflight: commandSummary(preflight) },
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.preflightOnly && options.existingRawFixture === undefined) {
+    const status = 'preflight-ok';
+    await emitSummary(options, {
+      status,
+      preflight: preflightJson,
+      proofPacket: proofPacket({
+        options,
+        status,
+        preflight,
+      }),
+      commands: { preflight: commandSummary(preflight) },
+    });
+    return;
+  }
+
+  const record =
+    options.existingRawFixture === undefined
+      ? runScript('record-agent-replay-fixtures.ts', [
+          '--provider',
+          provider,
+          '--exact-raw',
+          '--out-dir',
+          options.rawDir,
+          ...(options.keepWorkdirs ? ['--keep-workdirs'] : []),
+          ...(options.claudePermissionMode === undefined
+            ? []
+            : ['--claude-permission-mode', options.claudePermissionMode]),
+          ...(options.claudeModel === undefined
+            ? []
+            : ['--claude-model', options.claudeModel]),
+          ...(options.gstackSkillDir === undefined
+            ? []
+            : ['--gstack-skill-dir', options.gstackSkillDir]),
+          ...(options.gstackCli === undefined
+            ? []
+            : ['--gstack-cli', options.gstackCli]),
+        ])
+      : existingRawCaptureResult(options.existingRawFixture);
+
+  if (record.status !== 0) {
+    const status = 'failed';
+    await emitSummary(options, {
+      status,
+      reason: 'gstack raw fixture recording failed',
+      preflight: preflightJson,
+      proofPacket: proofPacket({
+        options,
+        status,
+        preflight,
+        record,
+      }),
+      commands: {
+        preflight: commandSummary(preflight),
+        record: commandSummary(record),
+      },
+    });
+    process.exitCode = 1;
+    return;
+  }
+
+  const rawFixturePath =
+    options.existingRawFixture ?? join(options.rawDir, `${provider}.ndjson`);
+  const normalizedFixturePath = join(options.fixtureDir, `${provider}.ndjson`);
+  const normalizedText = normalizeAgentReplayText(
+    await readFile(rawFixturePath, 'utf8')
+  );
+  await mkdir(options.fixtureDir, { recursive: true });
+  await writeFile(normalizedFixturePath, normalizedText, 'utf8');
+  await writeCandidateManifest(
+    normalizedFixturePath,
+    {
+      providerReplay: 'pending',
+      backendReplay: 'pending',
+      browserAutomation: 'pending',
+      oracle: 'pending',
+    },
+    preflightJson,
+    options
+  );
+
+  const providerReplay = runScript('replay-agent-fixture.ts', [
+    '--fixture',
+    normalizedFixturePath,
+    '--coverage',
+    'none',
+    '--no-html',
+    '--out-dir',
+    options.providerReplayOutDir,
+  ]);
+  const providerReplayJson = parseJsonObjectFromCommandOutput(
+    providerReplay.stdout
+  );
+
+  if (providerReplay.status === 0) {
+    await writeCandidateManifest(
+      normalizedFixturePath,
+      {
+        providerReplay: 'covered',
+        backendReplay: 'pending',
+        browserAutomation: 'pending',
+        oracle: 'pending',
+      },
+      preflightJson,
+      options
+    );
+  }
+
+  const backendReplay = backendReplayCommand(options, normalizedFixturePath);
+  const backendReplayJson =
+    backendReplay.type === 'skipped' ||
+    backendReplay.proofMode === 'backend-browser'
+      ? undefined
+      : parseJsonObjectFromCommandOutput(backendReplay.result.stdout);
+
+  if (
+    providerReplay.status === 0 &&
+    backendReplay.type === 'ran' &&
+    backendReplay.result.status === 0
+  ) {
+    await writeCandidateManifest(
+      normalizedFixturePath,
+      {
+        providerReplay: 'covered',
+        backendReplay: 'covered',
+        browserAutomation:
+          backendReplay.proofMode === 'backend-browser' ? 'covered' : 'pending',
+        oracle: 'covered',
+      },
+      preflightJson,
+      options
+    );
+  }
+
+  const status = promotionStatus(providerReplay, backendReplay);
+  const install = await maybeInstallCandidateFixture({
+    options,
+    status,
+    normalizedFixturePath,
+  });
+  await emitSummary(options, {
+    status,
+    rawFixturePath,
+    normalizedFixturePath,
+    manifestPath: agentReplayManifestPathForFixture(normalizedFixturePath),
+    preflight: preflightJson,
+    providerReplay: providerReplayJson,
+    backendReplay: backendReplayJson,
+    install,
+    proofPacket: proofPacket({
+      options,
+      status,
+      preflight,
+      record,
+      rawFixturePath,
+      normalizedFixturePath,
+      providerReplay,
+      backendReplay,
+    }),
+    commands: {
+      preflight: commandSummary(preflight),
+      record: commandSummary(record),
+      providerReplay: commandSummary(providerReplay),
+      ...(backendReplay.type === 'skipped'
+        ? { backendReplay: { status: 'skipped', reason: backendReplay.reason } }
+        : { backendReplay: commandSummary(backendReplay.result) }),
+    },
+  });
+
+  if (status === 'failed' || install.status === 'blocked') {
+    process.exitCode = 1;
+  }
+}
+
+async function maybeInstallCandidateFixture(args: {
+  readonly options: PromoteOptions;
+  readonly status: PromotionStatus;
+  readonly normalizedFixturePath: string;
+}): Promise<JsonObject> {
+  const { options, status, normalizedFixturePath } = args;
+
+  if (options.installFixtureDir === undefined) {
+    return { status: 'not-requested' };
+  }
+
+  if (status !== 'browser-ready') {
+    return {
+      status: 'blocked',
+      reason: '--install-fixture-dir requires a browser-ready candidate',
+      targetDir: options.installFixtureDir,
+    };
+  }
+
+  const sourceManifestPath = agentReplayManifestPathForFixture(
+    normalizedFixturePath
+  );
+  const safetyFindings = await scanAgentReplayInstallFiles([
+    normalizedFixturePath,
+    sourceManifestPath,
+  ]);
+
+  if (safetyFindings.length > 0) {
+    return {
+      status: 'blocked',
+      reason: 'candidate fixture safety scan failed',
+      targetDir: options.installFixtureDir,
+      findings: safetyFindings,
+    };
+  }
+
+  const targetFixturePath = join(
+    options.installFixtureDir,
+    `${provider}.ndjson`
+  );
+  const targetManifestPath =
+    agentReplayManifestPathForFixture(targetFixturePath);
+  await mkdir(options.installFixtureDir, { recursive: true });
+  await copyFile(normalizedFixturePath, targetFixturePath);
+  await copyFile(sourceManifestPath, targetManifestPath);
+
+  return {
+    status: 'installed',
+    fixturePath: targetFixturePath,
+    manifestPath: targetManifestPath,
+  };
+}
+
+function skippedPreflightForExistingRaw(rawFixturePath: string): CommandResult {
+  return {
+    status: 0,
+    stdout: `${JSON.stringify(
+      {
+        provider,
+        status: 'skipped',
+        reason: 'using previously captured real raw fixture',
+        rawFixturePath,
+      },
+      null,
+      2
+    )}
+`,
+    stderr: '',
+  };
+}
+
+function existingRawCaptureResult(rawFixturePath: string): CommandResult {
+  return {
+    status: 0,
+    stdout: `using previously captured real raw fixture ${rawFixturePath}
+`,
+    stderr: '',
+  };
+}
+
+function backendReplayCommand(
+  options: PromoteOptions,
+  fixturePath: string
+): BackendReplayPromotionResult {
+  if (options.skipBackend) {
+    return { type: 'skipped', reason: '--skip-backend was provided' };
+  }
+
+  if (options.localBrowserProof) {
+    return {
+      type: 'ran',
+      proofMode: 'backend-browser',
+      result: runCommand(
+        'bun',
+        [
+          'run',
+          'replay-harness:agent-backend-live',
+          '--',
+          '--fixture',
+          fixturePath,
+          '--provider',
+          'claude-code',
+          '--setup-fixture',
+          '--oracle-feature',
+          featureId,
+          '--out-dir',
+          options.browserReplayOutDir,
+          ...(options.speed === undefined ? [] : ['--speed', options.speed]),
+        ],
+        webRoot
+      ),
+    };
+  }
+
+  if (options.backendUrl === undefined) {
+    return {
+      type: 'skipped',
+      reason:
+        '--backend-url or --local-browser-proof was not provided; backend replay was not attempted',
+    };
+  }
+
+  const backendArgs = [
+    '--fixture',
+    fixturePath,
+    '--provider',
+    'claude-code',
+    '--backend-url',
+    options.backendUrl,
+    '--oracle-feature',
+    featureId,
+    '--out-dir',
+    options.browserProof
+      ? options.browserReplayOutDir
+      : options.backendReplayOutDir,
+    ...(options.speed === undefined ? [] : ['--speed', options.speed]),
+    ...(options.setupFixture ? ['--setup-fixture'] : []),
+    ...(options.sessionToken === undefined
+      ? []
+      : ['--session-token', options.sessionToken]),
+    ...(options.workspace === undefined
+      ? []
+      : ['--workspace', options.workspace]),
+    ...(options.channel === undefined ? [] : ['--channel', options.channel]),
+    ...(options.threadId === undefined
+      ? []
+      : ['--thread-id', options.threadId]),
+  ];
+
+  return {
+    type: 'ran',
+    proofMode: options.browserProof ? 'backend-browser' : 'backend',
+    result: runScript(
+      options.browserProof
+        ? 'replay-agent-backend-browser.ts'
+        : 'replay-agent-backend.ts',
+      backendArgs
+    ),
+  };
+}
+
+function promotionStatus(
+  providerReplay: CommandResult,
+  backendReplay: BackendReplayPromotionResult
+): PromotionStatus {
+  if (providerReplay.status !== 0) {
+    return 'failed';
+  }
+
+  switch (backendReplay.type) {
+    case 'skipped':
+      return 'provider-ready';
+    case 'ran':
+      if (backendReplay.result.status !== 0) {
+        return 'failed';
+      }
+
+      return backendReplay.proofMode === 'backend-browser'
+        ? 'browser-ready'
+        : 'backend-ready';
+  }
+}
+
+function proofPacket(args: {
+  readonly options: PromoteOptions;
+  readonly status: PromotionStatus;
+  readonly preflight: CommandResult;
+  readonly record?: CommandResult | undefined;
+  readonly rawFixturePath?: string | undefined;
+  readonly normalizedFixturePath?: string | undefined;
+  readonly providerReplay?: CommandResult | undefined;
+  readonly backendReplay?: BackendReplayPromotionResult | undefined;
+}): JsonObject {
+  const manifestPath =
+    args.normalizedFixturePath === undefined
+      ? undefined
+      : agentReplayManifestPathForFixture(args.normalizedFixturePath);
+  const backendSummaryPath =
+    args.backendReplay === undefined || args.backendReplay.type === 'skipped'
+      ? undefined
+      : join(
+          args.backendReplay.proofMode === 'backend-browser'
+            ? args.options.browserReplayOutDir
+            : args.options.backendReplayOutDir,
+          'summary.json'
+        );
+
+  return {
+    featureId,
+    lane: provider,
+    status: args.status,
+    artifacts: {
+      summaryPath: join(args.options.outDir, 'summary.json'),
+      rawDir: args.options.rawDir,
+      rawFixturePath: args.rawFixturePath,
+      normalizedFixturePath: args.normalizedFixturePath,
+      manifestPath,
+      providerReplaySummaryPath:
+        args.providerReplay === undefined
+          ? undefined
+          : join(args.options.providerReplayOutDir, 'summary.json'),
+      backendReplaySummaryPath: backendSummaryPath,
+      browserReplaySummaryPath:
+        args.backendReplay?.type === 'ran' &&
+        args.backendReplay.proofMode === 'backend-browser'
+          ? join(args.options.browserReplayOutDir, 'summary.json')
+          : undefined,
+    },
+    proof: {
+      preflight: proofStatusForCommand(args.preflight, 'blocked'),
+      rawCapture: proofStatusForOptionalCommand(args.record),
+      normalization:
+        args.normalizedFixturePath === undefined ? 'pending' : 'covered',
+      manifest: manifestPath === undefined ? 'pending' : 'covered',
+      providerReplay: proofStatusForOptionalCommand(args.providerReplay),
+      backendReplay: proofStatusForBackendReplay(args.backendReplay),
+      oracle: proofStatusForBackendReplay(args.backendReplay),
+      frontendStorybook:
+        args.normalizedFixturePath === undefined ? 'pending' : 'not-applicable',
+      browserAutomation: proofStatusForBrowserReplay(args.backendReplay),
+    },
+    nextCommands: nextPromotionCommands(args.options, args.status),
+  };
+}
+
+function proofStatusForOptionalCommand(
+  result: CommandResult | undefined
+): string {
+  if (result === undefined) {
+    return 'pending';
+  }
+
+  return proofStatusForCommand(result, 'failed');
+}
+
+function proofStatusForCommand(
+  result: CommandResult,
+  failedStatus: 'blocked' | 'failed'
+): string {
+  return result.status === 0 ? 'covered' : failedStatus;
+}
+
+function proofStatusForBackendReplay(
+  result: BackendReplayPromotionResult | undefined
+): string {
+  if (result === undefined || result.type === 'skipped') {
+    return 'pending';
+  }
+
+  return result.result.status === 0 ? 'covered' : 'failed';
+}
+
+function proofStatusForBrowserReplay(
+  result: BackendReplayPromotionResult | undefined
+): string {
+  if (result === undefined || result.type === 'skipped') {
+    return 'pending';
+  }
+
+  if (result.proofMode !== 'backend-browser') {
+    return 'pending';
+  }
+
+  return result.result.status === 0 ? 'covered' : 'failed';
+}
+
+function promotionCommandBase(options: PromoteOptions): string {
+  const optionArgs = [
+    '--out-dir',
+    options.outDir,
+    ...(options.existingRawFixture === undefined
+      ? []
+      : ['--existing-raw-fixture', options.existingRawFixture]),
+    ...(options.claudeModel === undefined
+      ? []
+      : ['--claude-model', options.claudeModel]),
+    ...(options.claudePermissionMode === undefined
+      ? []
+      : ['--claude-permission-mode', options.claudePermissionMode]),
+    ...(options.speed === undefined ? [] : ['--speed', options.speed]),
+    ...(options.gstackSkillDir === undefined
+      ? []
+      : ['--gstack-skill-dir', options.gstackSkillDir]),
+    ...(options.gstackCli === undefined
+      ? []
+      : ['--gstack-cli', options.gstackCli]),
+    ...(options.keepWorkdirs ? ['--keep-workdirs'] : []),
+  ];
+
+  return `pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- ${optionArgs.map(shellArg).join(' ')}`;
+}
+
+function shellArg(value: string): string {
+  if (/^[A-Za-z0-9_./:=@+-]+$/u.test(value)) {
+    return value;
+  }
+
+  return `'${value.replace(/'/gu, `'"'"'`)}'`;
+}
+
+function nextPromotionCommands(
+  options: PromoteOptions,
+  status: PromotionStatus
+): readonly string[] {
+  const base = promotionCommandBase(options);
+  const preflight = `${base} --preflight-only`;
+  const providerOnly = `${base} --skip-backend`;
+  const backend =
+    options.backendUrl === undefined
+      ? `${base} --backend-url http://127.0.0.1:4140 --setup-fixture`
+      : `${base} --backend-url ${shellArg(options.backendUrl)}${options.setupFixture ? ' --setup-fixture' : ''}`;
+  const browser = `${backend} --browser-proof`;
+  const localBrowser = `${base} --local-browser-proof`;
+
+  switch (status) {
+    case 'blocked':
+      return [preflight, providerOnly];
+    case 'preflight-ok':
+      return [providerOnly, backend];
+    case 'provider-ready':
+      return [localBrowser, backend, browser];
+    case 'backend-ready':
+      return [localBrowser, browser];
+    case 'browser-ready':
+      return [
+        `pnpm --filter @linzumi/cli run replay:agent-fixture -- --fixture ${join(options.fixtureDir, `${provider}.ndjson`)} --coverage none --require-feature ${featureId} --out-dir ${join(options.outDir, 'final-readiness')}`,
+      ];
+    case 'failed':
+      return [preflight, providerOnly, backend];
+  }
+}
+
+async function writeCandidateManifest(
+  fixturePath: string,
+  proof: {
+    readonly providerReplay: 'covered' | 'pending';
+    readonly backendReplay: 'covered' | 'pending';
+    readonly browserAutomation: 'covered' | 'pending';
+    readonly oracle: 'covered' | 'pending';
+  },
+  preflight: JsonObject,
+  options: PromoteOptions
+): Promise<void> {
+  const manifestPath = agentReplayManifestPathForFixture(fixturePath);
+  const manifest = {
+    schemaVersion: 1,
+    fixtureId: 'gstack-claude-smoke',
+    lane: 'gstack-claude-smoke',
+    provider: 'claude-code-sdk',
+    fixturePath: 'gstack-claude-smoke.ndjson',
+    capture: {
+      promptId: 'agent-fixture-playground/gstack-claude-smoke-prompt',
+      runtimeProfile: 'gstack-claude-code',
+      source: 'real Claude Code SDK capture with user-installed gstack',
+      ...(options.claudeModel === undefined
+        ? {}
+        : { model: options.claudeModel }),
+      ...candidateManifestPreflightCapture(preflight),
+    },
+    features: [
+      {
+        featureId,
+        title: 'Gstack skill discovery and local review smoke',
+        autonomyStatus:
+          proof.backendReplay === 'covered' &&
+          proof.oracle === 'covered' &&
+          proof.browserAutomation === 'covered'
+            ? 'ready-to-implement'
+            : 'needs-oracle',
+        expectedProof: {
+          realFixture: 'covered',
+          providerReplay: proof.providerReplay,
+          backendReplay: proof.backendReplay,
+          frontendStorybook: 'not-applicable',
+          browserAutomation: proof.browserAutomation,
+          oracle: proof.oracle,
+        },
+        notes:
+          'Candidate manifest generated by promote:gstack-claude-smoke-fixture. The gstack smoke lane uses real backend/browser proof, so frontendStorybook is not applicable for this candidate. Keep pending replay/oracle rows until the matching proof command has passed for this exact fixture.',
+      },
+    ],
+  };
+
+  await mkdir(dirname(manifestPath), { recursive: true });
+  await writeFile(
+    manifestPath,
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    'utf8'
+  );
+}
+
+function candidateManifestPreflightCapture(preflight: JsonObject): JsonObject {
+  const setup = preflight.setup;
+
+  if (!isJsonObject(setup)) {
+    return {};
+  }
+
+  return {
+    gstackSkillDir:
+      typeof setup.skillDir === 'string' ? setup.skillDir : undefined,
+    gstackCliPath:
+      typeof setup.cliPath === 'string' ? setup.cliPath : undefined,
+    checkedSkillDirs: Array.isArray(setup.checkedSkillDirs)
+      ? setup.checkedSkillDirs
+      : undefined,
+    checkedCliNames: Array.isArray(setup.checkedCliNames)
+      ? setup.checkedCliNames
+      : undefined,
+    includeHookEvents: setup.includeHookEvents,
+    preservesClaudeTasks: setup.preservesClaudeTasks,
+  };
+}
+
+async function emitSummary(
+  options: PromoteOptions,
+  summary: JsonObject
+): Promise<void> {
+  await mkdir(options.outDir, { recursive: true });
+  await writeFile(
+    join(options.outDir, 'summary.json'),
+    `${JSON.stringify(summary, null, 2)}\n`,
+    'utf8'
+  );
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+function runScript(scriptName: string, args: readonly string[]): CommandResult {
+  const result = spawnSync(
+    process.execPath,
+    ['--import', tsxLoader, join('scripts', scriptName), ...args],
+    {
+      cwd: packageRoot,
+      env: process.env,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024 * 20,
+    }
+  );
+
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+function runCommand(
+  command: string,
+  args: readonly string[],
+  cwd: string
+): CommandResult {
+  const result = spawnSync(command, args, {
+    cwd,
+    env: process.env,
+    encoding: 'utf8',
+    maxBuffer: 1024 * 1024 * 20,
+  });
+
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+}
+
+function commandSummary(result: CommandResult): JsonObject {
+  return {
+    status: result.status,
+    stdout: result.stdout.slice(0, 20_000),
+    stderr: result.stderr.slice(0, 20_000),
+  };
+}
+
+function parseJsonObjectFromCommandOutput(output: string): JsonObject {
+  const start = output.indexOf('{');
+  const end = output.lastIndexOf('}');
+
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`command output did not contain a JSON object: ${output}`);
+  }
+
+  const parsed: unknown = JSON.parse(output.slice(start, end + 1));
+
+  if (!isJsonObject(parsed)) {
+    throw new Error('command output JSON was not an object');
+  }
+
+  return parsed;
+}
+
+function parseArgs(args: readonly string[]): PromoteOptions {
+  const outDir = resolve(
+    argValue(args, '--out-dir') ??
+      join(tmpdir(), `linzumi-gstack-claude-smoke-promotion-${Date.now()}`)
+  );
+
+  return {
+    outDir,
+    rawDir: resolve(argValue(args, '--raw-dir') ?? join(outDir, 'raw')),
+    existingRawFixture:
+      argValue(args, '--existing-raw-fixture') === undefined
+        ? undefined
+        : resolve(argValue(args, '--existing-raw-fixture') ?? ''),
+    fixtureDir: resolve(
+      argValue(args, '--fixture-dir') ?? join(outDir, 'fixtures')
+    ),
+    providerReplayOutDir: resolve(
+      argValue(args, '--provider-replay-out-dir') ??
+        join(outDir, 'provider-replay')
+    ),
+    backendReplayOutDir: resolve(
+      argValue(args, '--backend-replay-out-dir') ??
+        join(outDir, 'backend-replay')
+    ),
+    browserReplayOutDir: resolve(
+      argValue(args, '--browser-replay-out-dir') ??
+        join(outDir, 'backend-browser')
+    ),
+    installFixtureDir:
+      argValue(args, '--install-fixture-dir') === undefined
+        ? undefined
+        : resolve(argValue(args, '--install-fixture-dir') ?? ''),
+    speed: argValue(args, '--speed'),
+    preflightOnly: args.includes('--preflight-only'),
+    keepWorkdirs: args.includes('--keep-workdirs'),
+    claudePermissionMode: argValue(args, '--claude-permission-mode'),
+    claudeModel: argValue(args, '--claude-model'),
+    gstackSkillDir: argValue(args, '--gstack-skill-dir'),
+    gstackCli: argValue(args, '--gstack-cli'),
+    skipBackend: args.includes('--skip-backend'),
+    browserProof: args.includes('--browser-proof'),
+    localBrowserProof: args.includes('--local-browser-proof'),
+    backendUrl: argValue(args, '--backend-url'),
+    setupFixture: args.includes('--setup-fixture'),
+    sessionToken: argValue(args, '--session-token'),
+    workspace: argValue(args, '--workspace'),
+    channel: argValue(args, '--channel'),
+    threadId: argValue(args, '--thread-id'),
+  };
+}
+
+function argValue(args: readonly string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+
+  if (index === -1) {
+    return undefined;
+  }
+
+  const value = args[index + 1];
+
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${name} requires a value`);
+  }
+
+  return value;
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    `Usage: pnpm run promote:gstack-claude-smoke-fixture -- [options]\n\nOptions:\n  --preflight-only                  Only check local gstack readiness and write summary.json\n  --out-dir <path>                  Promotion artifact root. Default: /tmp/linzumi-gstack-claude-smoke-promotion-*\n  --raw-dir <path>                  Exact raw capture directory. Default: <out-dir>/raw\n  --existing-raw-fixture <path>     Reuse a previously captured real raw NDJSON fixture without starting Claude\n  --fixture-dir <path>              Normalized candidate fixture directory. Default: <out-dir>/fixtures\n  --provider-replay-out-dir <path>  Provider replay artifact directory. Default: <out-dir>/provider-replay\n  --backend-replay-out-dir <path>   Backend replay artifact directory. Default: <out-dir>/backend-replay\n  --browser-replay-out-dir <path>   Backend-browser replay artifact directory. Default: <out-dir>/backend-browser\n  --speed immediate|realtime|<n>x|<n>ms\n                                      Forwarded to backend replay proof commands. Default: immediate\n  --install-fixture-dir <path>      Copy browser-ready candidate fixture and manifest into this directory\n  --keep-workdirs                   Forwarded to record:agent-fixtures\n  --claude-permission-mode <value>  Forwarded to record:agent-fixtures\n  --claude-model <model>             Forwarded to record:agent-fixtures for cheap-model fixture rerolls\n  --gstack-skill-dir <path>          Forwarded to record:agent-fixtures for explicit preflight setup\n  --gstack-cli <path>                Forwarded to record:agent-fixtures for explicit preflight setup\n  --skip-backend                    Do not attempt backend replay after provider replay\n  --browser-proof                   Run backend replay plus browser proof through replay:agent-backend-browser\n  --local-browser-proof             Boot an isolated local backend, then run backend plus browser proof\n  --backend-url <url>               If provided, run replay:agent-backend with --oracle-feature gstack-claude-smoke\n  --setup-fixture                   Forwarded to replay:agent-backend\n  --session-token <token>           Forwarded to replay:agent-backend\n  --workspace <slug>                Forwarded to replay:agent-backend\n  --channel <slug>                  Forwarded to replay:agent-backend\n  --thread-id <id>                  Forwarded to replay:agent-backend\n\nExamples:\n  pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- --preflight-only\n  pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- --skip-backend --claude-permission-mode bypassPermissions --claude-model claude-haiku-4-5-20251001\n  pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- --existing-raw-fixture /tmp/gstack-raw/gstack-claude-smoke.ndjson --skip-backend\n  pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- --backend-url http://127.0.0.1:4140 --setup-fixture\n  pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- --backend-url http://127.0.0.1:4140 --setup-fixture --browser-proof\n  pnpm --filter @linzumi/cli run promote:gstack-claude-smoke-fixture -- --local-browser-proof --speed 2x --install-fixture-dir packages/linzumi-cli/test/fixtures/agent-raw-replay/gstack\n`
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(
+    `${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`
+  );
+  process.exitCode = 1;
+});