@openprd/cli 0.1.0

package/src/openprd.js

@@ -0,0 +1,1136 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { analyzePrdSnapshot, buildPrdSnapshot, formatVersionId } from './prd-core.js';
+import { validateOpenSpecChangeWorkspace } from './openspec/change-validate.js';
+import { generateOpenSpecChangeWorkspace as writeOpenSpecChangeWorkspace } from './openspec/generate.js';
+import { advanceOpenSpecTaskWorkspace, listOpenSpecTaskWorkspace, verifyOpenSpecTaskWorkspace } from './openspec/execute.js';
+import { activateOpenPrdChangeWorkspace, applyOpenPrdChangeWorkspace, archiveOpenPrdChangeWorkspace, closeOpenPrdChangeWorkspace, listAcceptedSpecsWorkspace, listOpenPrdChangesWorkspace } from './openspec/change-lifecycle.js';
+import { checkStandardsWorkspace, classifyExternalReferenceWorkspace, initStandardsWorkspace } from './standards.js';
+import { doctorOpenPrdAgentIntegration, setupOpenPrdAgentIntegration, updateOpenPrdAgentIntegration } from './agent-integration.js';
+import { finishLoopWorkspace, initLoopWorkspace, nextLoopWorkspace, planLoopWorkspace, promptLoopWorkspace, runLoopWorkspace, statusLoopWorkspace, verifyLoopWorkspace } from './loop.js';
+import { timestamp } from './time.js';
+import { parseCommandArgs, usage } from './cli/args.js';
+import { printAcceptedSpecsResult, printAgentIntegrationResult, printBenchmarkResult, printCaptureResult, printClarifyResult, printClassifyResult, printDevelopmentStandardsResult, printDiagramResult, printDiffResult, printDoctorResult, printFleetResult, printFreezeResult, printGrowthResult, printHandoffResult, printHistoryResult, printInitResult, printInterviewResult, printLearningResult, printLoopResult, printNextResult, printOpenPrdChangeActionResult, printOpenPrdChangesResult, printOpenSpecChangeValidationResult, printOpenSpecDiscoveryResult, printOpenSpecGenerateResult, printOpenSpecTaskResult, printPlaygroundResult, printQualityResult, printReviewResult, printRunResult, printSelfUpdateResult, printStandardsResult, printStatus, printSynthesizeResult, printUpgradeResult, printValidation, printVisualCompareResult } from './cli/print.js';
+import { cjoin, exists, writeJson, writeText, writeYaml } from './fs-utils.js';
+import { diagramWorkspace } from './diagram-workspace.js';
+import { createOpenSpecDiscoveryWorkspace } from './discovery.js';
+import { createFleetWorkspace } from './fleet.js';
+import { selfUpdateWorkspace, upgradeWorkspace } from './self-update.js';
+import { backfillWorkUnitsWorkspace } from './work-unit-migration.js';
+import { generateLearningReviewWorkspace, setLearningReviewModeWorkspace } from './learning-review.js';
+import { addBenchmarkWorkspace, approveBenchmarkWorkspace, benchmarkWorkspace, listBenchmarkWorkspace, verifyBenchmarkWorkspace } from './benchmark.js';
+import { initQualityWorkspace, qualityWorkspace, verifyQualityWorkspace, learnQualityWorkspace } from './quality.js';
+import { createRunWorkspace } from './run-harness.js';
+import { checkDevelopmentStandardsWorkspace } from './dev-standards.js';
+import { applyGrowthCandidateWorkspace, checkGrowthWorkspace, initGrowthWorkspace, rejectGrowthCandidateWorkspace, reviewGrowthWorkspace } from './growth.js';
+import { buildReviewPresentationTemplatePayload, reviewPresentationWorkspace } from './review-presentation.js';
+import { syncSessionBindingFromChange } from './session-binding.js';
+import { visualCompareWorkspace } from './visual-compare.js';
+import { captureWorkspace, clarifyWorkspace, classifyWorkspace, computeWorkspaceGuidance, diffWorkspace, historyWorkspace, interviewWorkspace, nextWorkspace, playgroundWorkspace, reviewWorkspace, synthesizeWorkspace } from './workspace-workflow.js';
+import { appendDecision, appendProgress, appendVerification, appendWorkflowEvent, buildWorkflowTaskGraph, computeWorkspaceDigest, CORE_TEMPLATE_FILES, ensureWorkspaceSkeleton, isSupportedProductType, loadLatestVersionSnapshot, loadWorkspace, migrateWorkspaceSkeleton, normalizeVersionId, readVersionIndex, resolveActiveTemplatePack, resolveCurrentProductType, validateWorkspace } from './workspace-core.js';
+
+async function initWorkspace(projectRoot, options) {
+  const ws = await ensureWorkspaceSkeleton(projectRoot, options);
+  const workspace = await loadWorkspace(projectRoot);
+  const standards = await initStandardsWorkspace(projectRoot, { force: Boolean(options.force) });
+  const quality = await initQualityWorkspace(projectRoot, { force: Boolean(options.force) });
+  const growth = await initGrowthWorkspace(projectRoot);
+  const agentIntegration = await setupOpenPrdAgentIntegration(projectRoot, {
+    tools: options.tools ?? 'all',
+    force: Boolean(options.force),
+    action: 'init',
+    enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
+    codexHome: options.codexHome,
+    openprdHome: options.openprdHome,
+    hookProfile: options.hookProfile,
+  });
+  const config = workspace.data.config ?? {};
+  if (options.templatePack) {
+    config.activeTemplatePack = options.templatePack;
+  }
+  if (!config.activeTemplatePack) {
+    config.activeTemplatePack = 'base';
+  }
+  config.learningReview = {
+    enabled: config.learningReview?.enabled !== false,
+    autoOpen: config.learningReview?.autoOpen !== false,
+    defaultGenre: config.learningReview?.defaultGenre ?? 'internet-product',
+    sourceScope: config.learningReview?.sourceScope ?? 'workspace',
+    ...config.learningReview,
+  };
+  config.quality = {
+    enabled: config.quality?.enabled !== false,
+    command: config.quality?.command ?? 'openprd quality . --verify',
+    reportFormat: config.quality?.reportFormat ?? 'html',
+    ...config.quality,
+  };
+  await writeYaml(workspace.paths.config, config);
+
+  const currentState = {
+    version: 1,
+    status: 'initialized',
+    activeEngagement: 'active',
+    prdVersion: 0,
+    productType: isSupportedProductType(config.activeTemplatePack) ? config.activeTemplatePack : null,
+    templatePack: config.activeTemplatePack,
+    captureMeta: {},
+    projectRoot,
+    workspaceRoot: workspace.workspaceRoot,
+    createdAt: timestamp(),
+  };
+  await writeJson(workspace.paths.currentState, currentState);
+  await writeJson(workspace.paths.taskGraph, buildWorkflowTaskGraph(currentState));
+  await appendWorkflowEvent(workspace, 'initialized', {
+    templatePack: currentState.templatePack,
+    projectRoot,
+  });
+  await appendProgress(workspace, [
+    `已初始化工作区: ${workspace.workspaceRoot}。`,
+    `模板包: ${currentState.templatePack}。`,
+  ]);
+
+  return { ws: workspace, created: ws.created, currentState, standards, quality, growth, agentIntegration };
+}
+
+async function setupAgentIntegrationWorkspace(projectRoot, options = {}) {
+  if (!(await exists(cjoin(projectRoot, '.openprd')))) {
+    const initResult = await initWorkspace(projectRoot, options);
+    return {
+      ...initResult.agentIntegration,
+      initialized: true,
+      standards: initResult.standards,
+      quality: initResult.quality,
+      init: {
+        workspaceRoot: initResult.ws.workspaceRoot,
+        created: initResult.created,
+        templatePack: initResult.currentState.templatePack,
+      },
+      growth: initResult.growth,
+    };
+  }
+
+  const migration = await migrateWorkspaceSkeleton(projectRoot, { recordEvent: true });
+  const standards = await initStandardsWorkspace(projectRoot, { force: Boolean(options.force) });
+  const quality = await initQualityWorkspace(projectRoot, { force: false });
+  const growth = await initGrowthWorkspace(projectRoot);
+  const agentIntegration = await setupOpenPrdAgentIntegration(projectRoot, {
+    tools: options.tools ?? 'all',
+    force: Boolean(options.force),
+    action: 'setup',
+    enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
+    codexHome: options.codexHome,
+    openprdHome: options.openprdHome,
+    hookProfile: options.hookProfile,
+  });
+  return { ...agentIntegration, initialized: false, migration, standards, quality, growth };
+}
+
+async function updateAgentIntegrationWorkspace(projectRoot, options = {}) {
+  const migration = await migrateWorkspaceSkeleton(projectRoot, { recordEvent: true });
+  const standards = await initStandardsWorkspace(projectRoot, { force: false });
+  const quality = await initQualityWorkspace(projectRoot, { force: false });
+  const growth = await initGrowthWorkspace(projectRoot);
+  const agentIntegration = await updateOpenPrdAgentIntegration(projectRoot, {
+    tools: options.tools ?? 'all',
+    force: Boolean(options.force),
+    enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
+    codexHome: options.codexHome,
+    openprdHome: options.openprdHome,
+    hookProfile: options.hookProfile,
+  });
+  return { ...agentIntegration, migration, standards, quality, growth };
+}
+
+async function doctorWorkspace(projectRoot, options = {}) {
+  const agentIntegration = await doctorOpenPrdAgentIntegration(projectRoot, {
+    tools: options.tools ?? 'all',
+    enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
+    codexHome: options.codexHome,
+    hookProfile: options.hookProfile,
+  });
+  const standards = await checkStandardsWorkspace(projectRoot).catch((error) => ({
+    ok: false,
+    errors: [error instanceof Error ? error.message : String(error)],
+    warnings: [],
+    checks: [],
+    docsRoot: path.join('docs', 'basic'),
+  }));
+  const validation = await validateWorkspace(projectRoot)
+    .then(({ report }) => report)
+    .catch((error) => ({
+      valid: false,
+      errors: [error instanceof Error ? error.message : String(error)],
+      warnings: [],
+      checks: [],
+    }));
+
+  return {
+    ok: agentIntegration.ok && standards.ok && validation.valid,
+    action: 'doctor',
+    projectRoot,
+    tools: agentIntegration.tools,
+    agentIntegration,
+    standards,
+    validation,
+    errors: [
+      ...agentIntegration.errors,
+      ...(standards.errors ?? []).map((error) => `standards: ${error}`),
+      ...(validation.errors ?? []).map((error) => `validate: ${error}`),
+    ],
+  };
+}
+
+async function readCliPackageInfo() {
+  const raw = await fs.readFile(new URL('../package.json', import.meta.url), 'utf8');
+  const packageJson = JSON.parse(raw);
+  return {
+    name: packageJson.name ?? '@openprd/cli',
+    version: packageJson.version ?? '0.0.0',
+  };
+}
+
+const {
+  openspecDiscoveryWorkspace,
+  resumeOpenSpecDiscoveryWorkspace,
+  verifyOpenSpecDiscoveryWorkspace,
+} = createOpenSpecDiscoveryWorkspace({
+  appendProgress,
+  appendWorkflowEvent,
+  checkStandardsWorkspace,
+  loadLatestVersionSnapshot,
+  loadWorkspace,
+  readVersionIndex,
+  resolveActiveTemplatePack,
+  resolveCurrentProductType,
+  validateOpenSpecChangeWorkspace,
+});
+
+const runWorkspace = createRunWorkspace({
+  checkStandardsWorkspace,
+  listOpenPrdChangesWorkspace,
+  listOpenSpecTaskWorkspace,
+  nextWorkspace,
+  resumeOpenSpecDiscoveryWorkspace,
+  validateOpenSpecChangeWorkspace,
+  validateWorkspace,
+  verifyOpenSpecDiscoveryWorkspace,
+  verifyQualityWorkspace,
+});
+
+const fleetWorkspace = createFleetWorkspace({ setupAgentIntegrationWorkspace, updateAgentIntegrationWorkspace, doctorWorkspace, backfillWorkUnitsWorkspace });
+
+async function freezeWorkspace(projectRoot) {
+  const validation = await validateWorkspace(projectRoot);
+  const { report } = validation;
+  if (!report.valid) {
+    await appendWorkflowEvent(validation.ws, 'freeze_failed', {
+      errors: report.errors,
+      warnings: report.warnings,
+    });
+    await appendVerification(validation.ws, [
+      'Freeze 验证失败。',
+      ...report.errors.map((error) => `错误: ${error}`),
+      ...report.warnings.map((warning) => `警告: ${warning}`),
+    ]);
+    return { ok: false, report, ws: validation.ws };
+  }
+
+  let ws = validation.ws;
+  let latest = await loadLatestVersionSnapshot(ws);
+  if (!latest) {
+    const synthesized = await synthesizeWorkspace(projectRoot, {});
+    ws = synthesized.ws;
+    latest = { indexEntry: synthesized.indexEntry, snapshot: synthesized.snapshot };
+  }
+
+  const guidance = await computeWorkspaceGuidance(ws, { questionLimit: 5 });
+  if (guidance.nextAction !== 'freeze' && (ws.data.currentState?.status ?? null) !== 'frozen') {
+    const gateReport = {
+      ...report,
+      valid: false,
+      errors: [
+        ...(report.errors ?? []),
+        `Freeze blocked by ${guidance.gates.currentGate}: ${guidance.reason}`,
+      ],
+    };
+    await appendWorkflowEvent(ws, 'freeze_failed', {
+      errors: gateReport.errors,
+      warnings: gateReport.warnings,
+      gate: guidance.gates.currentGate,
+      nextAction: guidance.nextAction,
+    });
+    await appendVerification(ws, [
+      'Freeze 门禁失败。',
+      `当前门禁: ${guidance.gates.currentGate}`,
+      `原因: ${guidance.reason}`,
+      `建议命令: ${guidance.suggestedCommand}`,
+    ]);
+    return { ok: false, report: gateReport, ws, guidance };
+  }
+
+  const digest = await computeWorkspaceDigest(ws);
+  const snapshot = {
+    version: 1,
+    frozenAt: timestamp(),
+    projectRoot: ws.projectRoot,
+    workspaceRoot: ws.workspaceRoot,
+    schema: ws.data.schema?.name ?? null,
+    templatePack: resolveActiveTemplatePack(ws),
+    productTypes: ws.data.config?.supportedProductTypes ?? [],
+    prdVersion: latest.snapshot.versionNumber,
+    latestVersionId: latest.snapshot.versionId,
+    digest,
+    status: 'frozen',
+  };
+  await writeJson(ws.paths.freezeState, snapshot);
+  await writeJson(ws.paths.taskGraph, buildWorkflowTaskGraph(null));
+
+  const currentState = {
+    ...(ws.data.currentState ?? {}),
+    status: 'frozen',
+    prdVersion: latest.snapshot.versionNumber,
+    latestVersionId: latest.snapshot.versionId,
+    templatePack: resolveActiveTemplatePack(ws),
+    frozenAt: snapshot.frozenAt,
+    digest,
+  };
+  await writeJson(ws.paths.currentState, currentState);
+  await appendWorkflowEvent(ws, 'frozen', {
+    versionId: snapshot.latestVersionId,
+    digest,
+  });
+  await appendVerification(ws, [
+    'Freeze 验证通过。',
+    `版本: ${snapshot.latestVersionId}`,
+    `Digest: ${digest}`,
+    `PRD 版本: ${snapshot.prdVersion}`,
+  ]);
+  await appendProgress(ws, [
+    `已 freeze PRD 版本 ${snapshot.latestVersionId}。`,
+    `Digest: ${digest}`,
+  ]);
+  await appendDecision(ws, [
+    `已 freeze 版本 ${snapshot.latestVersionId}。`,
+    `已准备好交接给 ${resolveActiveTemplatePack(ws) === 'base' ? '下游执行方' : '执行系统'}。`,
+  ]);
+  await writeJson(ws.paths.taskGraph, buildWorkflowTaskGraph(currentState));
+
+  return { ok: true, ws, report, snapshot, latest };
+}
+
+async function handoffWorkspace(projectRoot, target) {
+  const freeze = await freezeWorkspace(projectRoot);
+  if (!freeze.ok) {
+    return freeze;
+  }
+
+  const { ws, snapshot } = freeze;
+  const exportDir = cjoin(ws.paths.exportsDir, target);
+  await fs.mkdir(exportDir, { recursive: true });
+
+  const handoff = {
+    version: 1,
+    versionId: snapshot.latestVersionId,
+    versionNumber: snapshot.prdVersion,
+    target,
+    generatedAt: timestamp(),
+    workspaceRoot: ws.workspaceRoot,
+    projectRoot: ws.projectRoot,
+    schema: ws.data.schema?.name ?? null,
+    templatePack: resolveActiveTemplatePack(ws),
+    productTypes: ws.data.config?.supportedProductTypes ?? [],
+    productType: resolveCurrentProductType(ws),
+    digest: snapshot.digest,
+    sourceFiles: [
+      ...CORE_TEMPLATE_FILES,
+      ...((await exists(ws.paths.activeArchitectureDiagramHtml)) ? ['engagements/active/architecture-diagram.html'] : []),
+      ...((await exists(ws.paths.activeArchitectureDiagramJson)) ? ['engagements/active/architecture-diagram.json'] : []),
+      ...((await exists(ws.paths.activeArchitectureDiagramMermaid)) ? ['engagements/active/architecture-diagram.mmd'] : []),
+      ...((await exists(ws.paths.activeProductFlowDiagramHtml)) ? ['engagements/active/product-flow-diagram.html'] : []),
+      ...((await exists(ws.paths.activeProductFlowDiagramJson)) ? ['engagements/active/product-flow-diagram.json'] : []),
+      ...((await exists(ws.paths.activeProductFlowDiagramMermaid)) ? ['engagements/active/product-flow-diagram.mmd'] : []),
+    ],
+    nextStep: target === 'openprd' || target === 'openspec'
+      ? 'Generate an OpenPrd change and continue with specs/design/tasks.'
+      : 'Consume the handoff bundle in the downstream system.',
+  };
+
+  await writeJson(cjoin(exportDir, 'handoff.json'), handoff);
+  await writeText(cjoin(exportDir, 'handoff.md'), `# 交接\n\n- 目标: ${target}\n- 版本: ${handoff.versionId}\n- Schema: ${handoff.schema}\n- 模板包: ${handoff.templatePack}\n- Digest: ${handoff.digest}\n- 下一步: ${handoff.nextStep}\n`);
+  if (await exists(ws.paths.activeArchitectureDiagramHtml)) {
+    await fs.copyFile(ws.paths.activeArchitectureDiagramHtml, cjoin(exportDir, 'architecture-diagram.html'));
+  }
+  if (await exists(ws.paths.activeArchitectureDiagramJson)) {
+    await fs.copyFile(ws.paths.activeArchitectureDiagramJson, cjoin(exportDir, 'architecture-diagram.json'));
+  }
+  if (await exists(ws.paths.activeArchitectureDiagramMermaid)) {
+    await fs.copyFile(ws.paths.activeArchitectureDiagramMermaid, cjoin(exportDir, 'architecture-diagram.mmd'));
+  }
+  if (await exists(ws.paths.activeProductFlowDiagramHtml)) {
+    await fs.copyFile(ws.paths.activeProductFlowDiagramHtml, cjoin(exportDir, 'product-flow-diagram.html'));
+  }
+  if (await exists(ws.paths.activeProductFlowDiagramJson)) {
+    await fs.copyFile(ws.paths.activeProductFlowDiagramJson, cjoin(exportDir, 'product-flow-diagram.json'));
+  }
+  if (await exists(ws.paths.activeProductFlowDiagramMermaid)) {
+    await fs.copyFile(ws.paths.activeProductFlowDiagramMermaid, cjoin(exportDir, 'product-flow-diagram.mmd'));
+  }
+  await appendWorkflowEvent(ws, 'handoff', {
+    target,
+    versionId: handoff.versionId,
+  });
+  await appendProgress(ws, [
+    `已生成面向 ${target} 的交接包。`,
+    `版本: ${handoff.versionId}`,
+  ]);
+  await appendDecision(ws, [
+    `交接目标已设置为 ${target}。`,
+    `版本 ${handoff.versionId} 已导出到 ${exportDir}。`,
+  ]);
+
+  const currentState = {
+    ...(ws.data.currentState ?? {}),
+    status: 'handed_off',
+    handedOffAt: handoff.generatedAt,
+    handoffTarget: target,
+  };
+  await writeJson(ws.paths.currentState, currentState);
+  await writeJson(ws.paths.taskGraph, buildWorkflowTaskGraph(currentState));
+
+  return { ok: true, ws, report: freeze.report, snapshot, handoff, exportDir };
+}
+
+function reviewConfirmationCommand(snapshot) {
+  if (!snapshot?.versionId || !snapshot?.digest) {
+    return 'openprd review . --open，然后 openprd review . --mark confirmed';
+  }
+  let command = `openprd review . --open，然后 openprd review . --mark confirmed --version ${snapshot.versionId} --digest ${snapshot.digest}`;
+  if (snapshot.workUnitId) {
+    command = `${command} --work-unit ${snapshot.workUnitId}`;
+  }
+  return command;
+}
+
+function assertPrdReviewConfirmedForChange(currentState, snapshot) {
+  if (['frozen', 'handed_off'].includes(snapshot?.status)) {
+    return;
+  }
+  const review = currentState?.reviewStatus ?? null;
+  const confirmed = review?.versionId === snapshot?.versionId && review?.status === 'confirmed';
+  if (confirmed) {
+    return;
+  }
+  throw new Error([
+    '生成 OpenPrd change 前需要先确认最新 PRD review.html。',
+    `当前版本: ${snapshot?.versionId ?? '未知'}。`,
+    `当前评审状态: ${review?.status ?? 'missing'}。`,
+    `建议: ${reviewConfirmationCommand(snapshot)}。`,
+  ].join('\n'));
+}
+
+async function generateOpenSpecChangeWorkspace(projectRoot, options = {}) {
+  const ws = await loadWorkspace(projectRoot);
+  const versionIndex = await readVersionIndex(ws);
+  const latest = await loadLatestVersionSnapshot(ws);
+  const currentState = ws.data.currentState ?? {};
+  const snapshot = latest?.snapshot ?? buildPrdSnapshot(ws, {
+    ...currentState,
+    versionNumber: currentState.prdVersion ?? (versionIndex.at(-1)?.versionNumber ?? 0),
+    versionId: currentState.prdVersion > 0
+      ? formatVersionId(currentState.prdVersion)
+      : (versionIndex.at(-1)?.versionId ?? 'v0000'),
+    productType: resolveCurrentProductType(ws),
+    templatePack: resolveActiveTemplatePack(ws),
+  });
+  assertPrdReviewConfirmedForChange(currentState, snapshot);
+  const analysis = analyzePrdSnapshot(snapshot);
+  const result = await writeOpenSpecChangeWorkspace(projectRoot, {
+    ...options,
+    snapshot,
+    analysis,
+  });
+  const validation = await validateOpenSpecChangeWorkspace(projectRoot, { change: result.changeId });
+  await activateOpenPrdChangeWorkspace(projectRoot, { change: result.changeId });
+
+  await appendWorkflowEvent(ws, 'openprd_change_generated', {
+    changeId: result.changeId,
+    taskCount: result.taskCount,
+    valid: validation.valid,
+  });
+  await appendProgress(ws, [
+    `已生成 OpenPrd change ${result.changeId}。`,
+    `任务数: ${result.taskCount}。`,
+    `验证: ${validation.valid ? '通过' : '失败'}。`,
+  ]);
+  await syncSessionBindingFromChange(projectRoot, result.changeId, {
+    title: snapshot.title ?? null,
+    versionId: snapshot.versionId ?? null,
+    digest: snapshot.digest ?? null,
+    workUnitId: snapshot.workUnitId ?? null,
+    targetRoot: snapshot.targetRoot ?? null,
+    reviewStatus: currentState.reviewStatus?.status ?? null,
+    reviewPath: currentState.reviewStatus?.reviewPath ?? currentState.reviewStatus?.stableArtifact ?? null,
+    activeReviewPath: currentState.reviewStatus?.entryPath ?? currentState.reviewStatus?.artifact ?? null,
+  });
+
+  return {
+    ...result,
+    ws,
+    snapshot,
+    analysis,
+    validation,
+    ok: result.ok && validation.ok,
+  };
+}
+
+async function isDirectoryPath(candidate) {
+  const stat = await fs.stat(path.resolve(candidate)).catch(() => null);
+  return Boolean(stat?.isDirectory());
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const [command = 'help', ...rest] = argv;
+
+  if (command === 'version' || command === '--version' || command === '-v') {
+    const packageInfo = await readCliPackageInfo();
+    console.log(packageInfo.version);
+    return 0;
+  }
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(usage());
+    return 0;
+  }
+
+  const { flags, positionals } = parseCommandArgs(rest);
+  if (positionals.includes('--help') || positionals.includes('-h')) {
+    console.log(usage());
+    return 0;
+  }
+  const projectPath = path.resolve(flags.path ?? positionals[0] ?? process.cwd());
+
+  try {
+    if (command === 'init') {
+      const result = await initWorkspace(projectPath, {
+        force: flags.force,
+        templatePack: flags.templatePack,
+        tools: flags.tools,
+        hookProfile: flags.hookProfile,
+        enableUserCodexConfig: true,
+      });
+      printInitResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'setup') {
+      const result = await setupAgentIntegrationWorkspace(projectPath, {
+        force: flags.force,
+        templatePack: flags.templatePack,
+        tools: flags.tools,
+        hookProfile: flags.hookProfile,
+        enableUserCodexConfig: true,
+      });
+      printAgentIntegrationResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'update') {
+      const result = await updateAgentIntegrationWorkspace(projectPath, {
+        force: flags.force,
+        tools: flags.tools,
+        hookProfile: flags.hookProfile,
+        enableUserCodexConfig: true,
+      });
+      printAgentIntegrationResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'self-update') {
+      const result = await selfUpdateWorkspace({
+        dryRun: flags.dryRun,
+        json: flags.json,
+      });
+      printSelfUpdateResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'upgrade') {
+      const result = await upgradeWorkspace(projectPath, {
+        dryRun: flags.dryRun,
+        json: flags.json,
+        fleet: flags.fleet,
+        tools: flags.tools,
+        hookProfile: flags.hookProfile,
+        force: flags.force,
+        maxDepth: flags.maxDepth,
+        include: flags.include,
+        exclude: flags.exclude,
+        report: flags.report,
+      });
+      printUpgradeResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'doctor') {
+      const result = await doctorWorkspace(projectPath, { tools: flags.tools, hookProfile: flags.hookProfile, enableUserCodexConfig: true });
+      printDoctorResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'fleet') {
+      const result = await fleetWorkspace(projectPath, {
+        tools: flags.tools,
+        hookProfile: flags.hookProfile,
+        force: flags.force,
+        dryRun: flags.dryRun,
+        updateOpenprd: flags.updateOpenprd,
+        backfillWorkUnits: flags.backfillWorkUnits,
+        syncRegistry: flags.syncRegistry,
+        setupMissing: flags.setupMissing,
+        doctor: flags.doctor,
+        maxDepth: flags.maxDepth,
+        include: flags.include,
+        exclude: flags.exclude,
+        report: flags.report,
+        enableUserCodexConfig: true,
+        openprdHome: flags.openprdHome,
+      });
+      printFleetResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'run') {
+      const result = await runWorkspace(projectPath, {
+        context: flags.context,
+        verify: flags.verify,
+        recordHook: flags.recordHook,
+        event: flags.event,
+        risk: flags.risk,
+        outcome: flags.outcome,
+        preview: flags.preview,
+        learn: flags.learn,
+        message: flags.message,
+      });
+      printRunResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'loop') {
+      let result;
+      const options = {
+        change: flags.change,
+        item: flags.item,
+        agent: flags.agent,
+        agentCommand: flags.agentCommand,
+        dryRun: flags.dryRun,
+        commit: flags.commit,
+        message: flags.message,
+        evidence: flags.evidence,
+        notes: flags.notes,
+      };
+      if (flags.init) {
+        result = await initLoopWorkspace(projectPath, options);
+      } else if (flags.plan) {
+        result = await planLoopWorkspace(projectPath, options);
+      } else if (flags.prompt) {
+        result = await promptLoopWorkspace(projectPath, options);
+      } else if (flags.loopRun) {
+        result = await runLoopWorkspace(projectPath, options);
+      } else if (flags.verify) {
+        result = await verifyLoopWorkspace(projectPath, options);
+      } else if (flags.finish) {
+        result = await finishLoopWorkspace(projectPath, options);
+      } else if (flags.next) {
+        result = await nextLoopWorkspace(projectPath, options);
+      } else {
+        result = await statusLoopWorkspace(projectPath);
+      }
+      printLoopResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'standards') {
+      const result = flags.init
+        ? await initStandardsWorkspace(projectPath, { force: flags.force })
+        : flags.classifyExternal !== null
+          ? await classifyExternalReferenceWorkspace(projectPath, { externalReference: flags.classifyExternal })
+          : await checkStandardsWorkspace(projectPath);
+      printStandardsResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'quality') {
+      const result = await qualityWorkspace(projectPath, {
+        init: flags.init,
+        verify: flags.verify,
+        report: flags.report,
+        html: flags.html,
+        learn: Boolean(flags.learn),
+        review: flags.review,
+        from: flags.from,
+        force: flags.force,
+      });
+      printQualityResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'visual-compare') {
+      const result = await visualCompareWorkspace(projectPath, {
+        reference: flags.reference,
+        actual: flags.actual,
+        out: flags.out,
+        format: flags.format,
+        quality: flags.quality,
+        maxPanelWidth: flags.maxPanelWidth,
+        referenceLabel: flags.referenceLabel,
+        actualLabel: flags.actualLabel,
+      });
+      printVisualCompareResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'grow') {
+      const firstArgIsProjectPath = !flags.path && positionals.length > 0 && await isDirectoryPath(positionals[0]);
+      const growthProjectPath = path.resolve(flags.path ?? (firstArgIsProjectPath ? positionals[0] : process.cwd()));
+      let result;
+      if (flags.init) {
+        result = await initGrowthWorkspace(growthProjectPath);
+      } else if (flags.apply) {
+        result = await applyGrowthCandidateWorkspace(growthProjectPath, { id: flags.id });
+      } else if (flags.reject) {
+        result = await rejectGrowthCandidateWorkspace(growthProjectPath, { id: flags.id, notes: flags.notes });
+      } else if (flags.check) {
+        result = await checkGrowthWorkspace(growthProjectPath);
+      } else {
+        result = await reviewGrowthWorkspace(growthProjectPath);
+      }
+      printGrowthResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'dev-check') {
+      const firstArgIsProjectPath = !flags.path && positionals.length > 1 && await isDirectoryPath(positionals[0]);
+      const devProjectPath = path.resolve(flags.path ?? (firstArgIsProjectPath ? positionals[0] : process.cwd()));
+      const files = flags.path
+        ? positionals
+        : (firstArgIsProjectPath ? positionals.slice(1) : positionals);
+      const result = await checkDevelopmentStandardsWorkspace(devProjectPath, { files });
+      printDevelopmentStandardsResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'benchmark') {
+      const subcommand = positionals[0] ?? 'list';
+      const benchmarkProjectPath = path.resolve(
+        flags.path
+          ?? ((subcommand === 'list' || subcommand === 'verify') ? positionals[1] : null)
+          ?? process.cwd(),
+      );
+      const target = positionals[1] ?? null;
+      let result;
+      if (subcommand === 'add') {
+        result = await addBenchmarkWorkspace(benchmarkProjectPath, {
+          source: target ?? flags.source,
+          notes: flags.notes,
+        });
+      } else if (subcommand === 'approve') {
+        result = await approveBenchmarkWorkspace(benchmarkProjectPath, {
+          id: flags.id ?? target,
+        });
+      } else if (subcommand === 'verify') {
+        result = await verifyBenchmarkWorkspace(benchmarkProjectPath);
+      } else if (subcommand === 'list') {
+        result = await listBenchmarkWorkspace(benchmarkProjectPath);
+      } else {
+        console.log('Usage: openprd benchmark <add|list|approve|verify> [target-or-id] [path-for-list-or-verify] [--path <project>] [--notes <text>] [--id <benchmark-id>]');
+        return 1;
+      }
+      printBenchmarkResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'classify') {
+      const productType = flags.productType ?? positionals[1] ?? positionals[0];
+      if (!productType) {
+        console.log('Usage: openprd classify [path] <consumer|b2b|agent>');
+        return 1;
+      }
+      const result = await classifyWorkspace(projectPath, productType);
+      printClassifyResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'clarify') {
+      const result = await clarifyWorkspace(projectPath, { open: flags.open || !flags.json, mode: flags.mode });
+      printClarifyResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'capture') {
+      const result = await captureWorkspace(projectPath, {
+        field: flags.field,
+        value: flags.value,
+        jsonFile: flags.jsonFile,
+        artifactMarkdown: flags.artifactMarkdown,
+        source: flags.source,
+        append: flags.append,
+      });
+      printCaptureResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'interview') {
+      const requestedType = flags.productType ?? positionals[1] ?? null;
+      const result = await interviewWorkspace(projectPath, requestedType);
+      printInterviewResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'playground') {
+      const result = await playgroundWorkspace(projectPath, { open: flags.open });
+      printPlaygroundResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'learn') {
+      if (flags.enable || flags.disable) {
+        const enabled = flags.enable ? true : false;
+        if (flags.enable && flags.disable) {
+          throw new Error('Cannot use --enable and --disable together.');
+        }
+        const result = await setLearningReviewModeWorkspace(projectPath, enabled);
+        printLearningResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+
+      const result = await generateLearningReviewWorkspace(projectPath, {
+        topic: flags.topic,
+        genre: flags.genre,
+        style: flags.style,
+        sourceScope: flags.source,
+        contentJson: flags.contentJson,
+        open: flags.open || !flags.json,
+        trigger: 'manual',
+        respectConfig: false,
+      });
+      printLearningResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'synthesize') {
+      const result = await synthesizeWorkspace(projectPath, {
+        title: flags.title,
+        owner: flags.owner,
+        problemStatement: flags.problem,
+        whyNow: flags.whyNow,
+        evidence: flags.evidence,
+        productType: flags.productType,
+        workUnit: flags.workUnit,
+        targetRoot: flags.targetRoot,
+        open: flags.open || !flags.json,
+      });
+      printSynthesizeResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'review') {
+      const result = await reviewWorkspace(projectPath, {
+        open: flags.open,
+        mark: flags.mark,
+        notes: flags.notes,
+        version: flags.version,
+        digest: flags.digest,
+        workUnit: flags.workUnit,
+      });
+      printReviewResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'review-presentation') {
+      if (flags.template) {
+        console.log(JSON.stringify(buildReviewPresentationTemplatePayload(), null, 2));
+        return 0;
+      }
+      const result = await reviewPresentationWorkspace(projectPath, {
+        version: flags.version,
+        presentationPath: flags.presentation,
+        write: flags.write,
+      });
+      if (flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`展示文案校验: ${result.ok ? '通过' : '需要重写'}`);
+        console.log(`版本: ${result.versionId}`);
+        console.log(`超限或格式问题: ${result.presentationFeedback.length}`);
+        if (result.presentationFeedback.length > 0) {
+          for (const item of result.presentationFeedback.slice(0, 6)) {
+            const pathHint = item.jsonPath ? `${item.jsonPath}: ` : '';
+            const sizeHint = item.maxChars ? ` 当前 ${item.currentChars} 字，限制 ${item.maxChars} 字。` : '';
+            console.log(`- ${item.area} / ${item.target}: ${pathHint}${item.action}${sizeHint}`);
+          }
+        }
+        if (result.written) {
+          console.log(`已写入: ${result.written}`);
+        }
+        if (result.reviewPath) {
+          console.log(`已生成评审面板: ${result.reviewPath}`);
+        }
+        if (result.reviewEntryPath) {
+          console.log(`已更新固定入口: ${result.reviewEntryPath}`);
+        }
+      }
+      return flags.failOnViolation && !result.ok ? 1 : 0;
+    }
+
+    if (command === 'diagram') {
+      const result = await diagramWorkspace(projectPath, { open: flags.open, type: flags.type, input: flags.input, mark: flags.mark });
+      printDiagramResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'next') {
+      const result = await nextWorkspace(projectPath);
+      printNextResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'diff') {
+      const result = await diffWorkspace(projectPath, { from: flags.from, to: flags.to });
+      printDiffResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'history') {
+      const result = await historyWorkspace(projectPath);
+      printHistoryResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'validate') {
+      const { report } = await validateWorkspace(projectPath);
+      printValidation(report, flags.json);
+      return report.valid ? 0 : 1;
+    }
+
+    if (command === 'status') {
+      const { report, ws } = await validateWorkspace(projectPath);
+      const guidance = await computeWorkspaceGuidance(ws, { questionLimit: 5 });
+      printStatus(ws, report, guidance, flags.json);
+      return report.valid ? 0 : 1;
+    }
+
+    if (command === 'freeze') {
+      const result = await freezeWorkspace(projectPath);
+      if (!result.ok) {
+        printValidation(result.report, flags.json);
+        return 1;
+      }
+      printFreezeResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'handoff') {
+      const result = await handoffWorkspace(projectPath, flags.target);
+      if (!result.ok) {
+        printValidation(result.report, flags.json);
+        return 1;
+      }
+      printHandoffResult(result, flags.json);
+      return 0;
+    }
+
+    if (command === 'changes') {
+      const result = await listOpenPrdChangesWorkspace(projectPath);
+      printOpenPrdChangesResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'specs') {
+      const result = await listAcceptedSpecsWorkspace(projectPath);
+      printAcceptedSpecsResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'change') {
+      if (flags.generate) {
+        const result = await generateOpenSpecChangeWorkspace(projectPath, {
+          change: flags.change ?? positionals[1] ?? null,
+          force: flags.force,
+        });
+        printOpenSpecGenerateResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+      if (flags.validate) {
+        const result = await validateOpenSpecChangeWorkspace(projectPath, {
+          change: flags.change ?? positionals[1] ?? null,
+        });
+        printOpenSpecChangeValidationResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+      if (flags.apply) {
+        const result = await applyOpenPrdChangeWorkspace(projectPath, {
+          change: flags.change ?? positionals[1] ?? null,
+          force: flags.force,
+        });
+        printOpenPrdChangeActionResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+      if (flags.archive) {
+        const result = await archiveOpenPrdChangeWorkspace(projectPath, {
+          change: flags.change ?? positionals[1] ?? null,
+          force: flags.force,
+          keep: flags.keep,
+        });
+        printOpenPrdChangeActionResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+      if (flags.activate) {
+        const result = await activateOpenPrdChangeWorkspace(projectPath, {
+          change: flags.change ?? positionals[1] ?? null,
+        });
+        printOpenPrdChangeActionResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+      if (flags.close) {
+        const result = await closeOpenPrdChangeWorkspace(projectPath, {
+          change: flags.change ?? positionals[1] ?? null,
+          notes: flags.notes,
+        });
+        printOpenPrdChangeActionResult(result, flags.json);
+        return result.ok ? 0 : 1;
+      }
+      const result = await listOpenPrdChangesWorkspace(projectPath);
+      printOpenPrdChangesResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'tasks' || command === 'openspec-tasks') {
+      const taskOptions = {
+        change: flags.change ?? null,
+        item: flags.item ?? flags.id ?? positionals[1] ?? null,
+        verify: flags.verify,
+        evidence: flags.evidence,
+        notes: flags.notes,
+      };
+      const result = flags.advance
+        ? await advanceOpenSpecTaskWorkspace(projectPath, taskOptions)
+        : flags.verify
+          ? await verifyOpenSpecTaskWorkspace(projectPath, taskOptions)
+          : await listOpenSpecTaskWorkspace(projectPath, taskOptions);
+      printOpenSpecTaskResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'openspec-generate') {
+      const result = await generateOpenSpecChangeWorkspace(projectPath, {
+        change: flags.change ?? positionals[1] ?? null,
+        force: flags.force,
+      });
+      printOpenSpecGenerateResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'openspec-validate') {
+      const result = await validateOpenSpecChangeWorkspace(projectPath, {
+        change: flags.change ?? positionals[1] ?? null,
+      });
+      printOpenSpecChangeValidationResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    if (command === 'discovery' || command === 'openspec-discovery') {
+      const result = await openspecDiscoveryWorkspace(projectPath, {
+        mode: flags.mode,
+        reference: flags.reference,
+        maxIterations: flags.maxIterations,
+        resume: flags.resume,
+        advance: flags.advance,
+        verify: flags.verify,
+        item: flags.item,
+        status: flags.status,
+        claim: flags.claim,
+        evidence: flags.evidence,
+        notes: flags.notes,
+        confidence: flags.confidence,
+        source: flags.source,
+      });
+      printOpenSpecDiscoveryResult(result, flags.json);
+      return result.ok ? 0 : 1;
+    }
+
+    console.log(usage());
+    return 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}
+
+export {
+  validateWorkspace,
+  initWorkspace,
+  setupAgentIntegrationWorkspace,
+  updateAgentIntegrationWorkspace,
+  selfUpdateWorkspace,
+  upgradeWorkspace,
+  doctorWorkspace,
+  fleetWorkspace,
+  backfillWorkUnitsWorkspace,
+  runWorkspace,
+  initLoopWorkspace,
+  planLoopWorkspace,
+  statusLoopWorkspace,
+  nextLoopWorkspace,
+  promptLoopWorkspace,
+  runLoopWorkspace,
+  verifyLoopWorkspace,
+  finishLoopWorkspace,
+  clarifyWorkspace,
+  captureWorkspace,
+  playgroundWorkspace,
+  generateLearningReviewWorkspace,
+  setLearningReviewModeWorkspace,
+  synthesizeWorkspace,
+  nextWorkspace,
+  diffWorkspace,
+  historyWorkspace,
+  reviewWorkspace,
+  reviewPresentationWorkspace,
+  freezeWorkspace,
+  handoffWorkspace,
+  generateOpenSpecChangeWorkspace,
+  validateOpenSpecChangeWorkspace,
+  openspecDiscoveryWorkspace,
+  listOpenSpecTaskWorkspace,
+  advanceOpenSpecTaskWorkspace,
+  verifyOpenSpecTaskWorkspace,
+  listOpenPrdChangesWorkspace,
+  activateOpenPrdChangeWorkspace,
+  closeOpenPrdChangeWorkspace,
+  applyOpenPrdChangeWorkspace,
+  archiveOpenPrdChangeWorkspace,
+  listAcceptedSpecsWorkspace,
+  diagramWorkspace,
+  classifyWorkspace,
+  interviewWorkspace,
+  loadWorkspace,
+  initStandardsWorkspace,
+  checkStandardsWorkspace,
+  classifyExternalReferenceWorkspace,
+  initQualityWorkspace,
+  verifyQualityWorkspace,
+  learnQualityWorkspace,
+  qualityWorkspace,
+  visualCompareWorkspace,
+  checkDevelopmentStandardsWorkspace,
+  initGrowthWorkspace,
+  checkGrowthWorkspace,
+  reviewGrowthWorkspace,
+  applyGrowthCandidateWorkspace,
+  rejectGrowthCandidateWorkspace,
+  benchmarkWorkspace,
+  addBenchmarkWorkspace,
+  listBenchmarkWorkspace,
+  approveBenchmarkWorkspace,
+  verifyBenchmarkWorkspace,
+};