@openprd/cli 0.1.0 → 0.1.8

package/src/cli/shared-print.js

@@ -0,0 +1,127 @@
+/*
+ * 核心功能
+ * 提供多个 CLI 输出模块共享的轻量打印 helper。
+ *
+ * 输入
+ * 接收知识回顾等横向复用的结构化子对象。
+ *
+ * 输出
+ * 输出统一格式的辅助文本片段，供 run、quality、growth 等模块复用。
+ *
+ * 定位
+ * 位于 CLI 表现层的共享工具模块，只承载跨模块复用的打印逻辑。
+ *
+ * 依赖
+ * 仅依赖终端输出，不依赖其他业务模块。
+ *
+ * 维护规则
+ * 共享 helper 只放稳定、无副作用的格式化逻辑，避免再次把大型输出文件堆回一起。
+ */
+function printKnowledgeReview(knowledgeReview) {
+  if (!knowledgeReview) {
+    return;
+  }
+  if (knowledgeReview.skipped) {
+    console.log(`项目经验回顾: 已跳过 (${knowledgeReview.reason})`);
+    return;
+  }
+  if (knowledgeReview.ok === false) {
+    console.log(`项目经验回顾: 失败 (${knowledgeReview.errors?.[0] ?? 'unknown'})`);
+    return;
+  }
+  console.log(`项目经验草案: ${knowledgeReview.candidateId}`);
+  if (knowledgeReview.summary) {
+    console.log(`摘要: ${knowledgeReview.summary}`);
+  }
+  if (Array.isArray(knowledgeReview.categories) && knowledgeReview.categories.length > 0) {
+    console.log(`类别: ${knowledgeReview.categories.join(', ')}`);
+  }
+  if (knowledgeReview.files?.draftSkill) {
+    console.log(`Draft Skill: ${knowledgeReview.files.draftSkill}`);
+  }
+  if (knowledgeReview.files?.candidateDir) {
+    console.log(`诊断候选: ${knowledgeReview.files.candidateDir}`);
+  }
+  if (knowledgeReview.suggestedLearnCommand) {
+    console.log(`Promote: ${knowledgeReview.suggestedLearnCommand}`);
+  }
+}
+
+function knowledgeAdoptionLabel(adoption = {}) {
+  return `命中 ${adoption.hitCount ?? 0} / 引用 ${adoption.referencedCount ?? 0} / 注入 ${adoption.injectedCount ?? 0}`;
+}
+
+function printKnowledgeSkillMatches(knowledgeSkills) {
+  const matched = Array.isArray(knowledgeSkills?.matched) ? knowledgeSkills.matched : [];
+  if (matched.length === 0) {
+    return;
+  }
+  const summary = knowledgeSkills?.summary ?? {};
+  console.log(`项目级 Skill: 命中 ${matched.length} 个${summary.hookInjected ? '，已自动注入当前上下文' : ''}`);
+  for (const skill of matched.slice(0, 3)) {
+    console.log(`- ${skill.skillName}: ${skill.matchSummary ?? '命中当前上下文'}`);
+    if (skill.description) {
+      console.log(`  说明: ${skill.description}`);
+    }
+    if (Array.isArray(skill.touchedFiles) && skill.touchedFiles.length > 0) {
+      console.log(`  相关文件: ${skill.touchedFiles.slice(0, 4).join('；')}`);
+    }
+    console.log(`  复用指标: ${knowledgeAdoptionLabel(skill.adoption ?? {})}`);
+  }
+}
+
+function optionalCapabilityLocationLabel(location) {
+  const clientLabels = {
+    codex: 'Codex',
+    cursor: 'Cursor',
+    claude: 'Claude Code',
+  };
+  const scopeLabel = location.scope === 'user' ? '用户级' : '项目级';
+  return `${clientLabels[location.client] ?? location.client} ${scopeLabel} (${location.path})`;
+}
+
+function printOptionalCapabilitySuggestions(optionalCapabilities) {
+  if (!Array.isArray(optionalCapabilities) || optionalCapabilities.length === 0) {
+    return;
+  }
+  const configured = optionalCapabilities.filter((capability) => capability.configured);
+  const recommended = optionalCapabilities.filter((capability) => !capability.configured);
+  if (configured.length === 0 && recommended.length === 0) {
+    return;
+  }
+
+  if (configured.length > 0) {
+    const configuredSummary = configured
+      .map((capability) => {
+        const locations = capability.configuredLocations.map(optionalCapabilityLocationLabel).join('；');
+        return locations ? `${capability.name}（${locations}）` : capability.name;
+      })
+      .join('，');
+    console.log(`已检测可选增强能力: ${configuredSummary}`);
+  }
+
+  if (recommended.length === 0) {
+    return;
+  }
+
+  console.log('可选增强建议:');
+  for (const capability of recommended) {
+    console.log(`- ${capability.name}: ${capability.summary}`);
+    if (capability.recommendedFor) {
+      console.log(`  适合场景: ${capability.recommendedFor}`);
+    }
+    if (Array.isArray(capability.checkedLocations) && capability.checkedLocations.length > 0) {
+      console.log(`  建议检查位置: ${capability.checkedLocations.map(optionalCapabilityLocationLabel).join('；')}`);
+    }
+    console.log(`  文档: ${capability.docsUrl}`);
+    console.log(`  GitHub: ${capability.repoUrl}`);
+    console.log(`  MCP: ${capability.serverUrl}`);
+  }
+}
+
+export {
+  knowledgeAdoptionLabel,
+  printKnowledgeReview,
+  printKnowledgeSkillMatches,
+  printOptionalCapabilitySuggestions,
+};

package/src/cli/workflow-print.js

@@ -0,0 +1,195 @@
+/*
+ * 核心功能
+ * 渲染 PRD 工作流中 synthesize、review、history、diff、next、freeze、diagram、handoff 等阶段输出。
+ *
+ * 输入
+ * 接收版本快照、评审状态、流程建议和图表 artifact 等结构化结果对象。
+ *
+ * 输出
+ * 向终端输出工作流摘要或 JSON，帮助用户理解当前阶段和下一步动作。
+ *
+ * 定位
+ * 位于 CLI 表现层的工作流输出模块，负责版本化 PRD 生命周期的呈现。
+ *
+ * 依赖
+ * 仅依赖终端输出和工作流 result 契约，不承担写入或规则计算。
+ *
+ * 维护规则
+ * 变更评审或交接相关字段时，必须同步维护普通输出与 JSON 输出的一致性。
+ */
+import { formatProductTypeDisplay } from '../product-type-copy.js';
+
+function printSynthesizeResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log('已整理出一版可评审的需求稿');
+  console.log(`标题: ${result.snapshot.title}`);
+  console.log(`产品场景: ${formatProductTypeDisplay(result.snapshot.productType, { fallback: '待确认' })}`);
+  if (!result.reviewPresentationRequired && (result.reviewPath ?? result.stableReviewArtifact)) {
+    console.log('确认页面: 已生成');
+  }
+  console.log(`已自动打开确认页面: ${result.opened ? '是' : '否'}`);
+  if (result.reviewPresentationRequired) {
+    console.log('确认页面: 还没到可以直接确认的状态');
+    console.log('下一步: 先把展示文案补齐，再重新生成确认页面。');
+    const feedback = result.reviewPresentationGate?.violations ?? [];
+    for (const item of feedback.slice(0, 6)) {
+      const pathHint = item.jsonPath ? `${item.jsonPath}: ` : '';
+      console.log(`- ${pathHint}${item.action}`);
+    }
+  } else if (result.reviewPath ?? result.stableReviewArtifact) {
+    console.log('请先让用户查看确认页面；用户认可后，再用页面提供的确认方式记录结果。');
+  }
+}
+
+function printReviewResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (!result.ok) {
+    console.log('PRD 评审状态不可用');
+    for (const error of result.errors ?? []) {
+      console.log(`- ${error}`);
+    }
+    if (result.requiredCommand) {
+      console.log(`下一步: ${result.requiredCommand}`);
+    }
+    for (const item of (result.presentationFeedback ?? []).slice(0, 6)) {
+      const pathHint = item.jsonPath ? `${item.jsonPath}: ` : '';
+      console.log(`- ${pathHint}${item.action}`);
+    }
+    return;
+  }
+
+  console.log(`确认结果: ${result.status}`);
+  console.log('确认页面: 已就绪');
+  if (result.marked) {
+    console.log(`状态已从 ${result.previousStatus} 更新为 ${result.status}`);
+  }
+  if (result.opened) {
+    console.log('已打开确认页面');
+  }
+}
+
+function printHistoryResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`版本历史: ${result.ws.workspaceRoot}`);
+  for (const entry of result.versions) {
+    console.log(`- ${entry.versionId} | ${entry.title} | ${formatProductTypeDisplay(entry.productType, { fallback: '待确认' })} | ${entry.createdAt}`);
+  }
+}
+
+function printDiffResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result.diff, null, 2));
+    return;
+  }
+
+  console.log(`差异 ${result.diff.fromVersionId} -> ${result.diff.toVersionId}`);
+  console.log(`变更章节: ${result.diff.changedSections.length > 0 ? result.diff.changedSections.join(', ') : '无'}`);
+  for (const change of result.diff.changes) {
+    console.log(`- ${change.path}: ${JSON.stringify(change.before)} -> ${JSON.stringify(change.after)}`);
+  }
+}
+
+function printNextResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  const { recommendation, analysis, workflow, taskGraph } = result;
+  console.log(`下一步动作: ${recommendation.nextAction}`);
+  if (recommendation.currentGate) {
+    console.log(`当前门禁: ${recommendation.currentGate}`);
+  }
+  if (recommendation.upcomingGate) {
+    console.log(`后续门禁: ${recommendation.upcomingGate}`);
+  }
+  console.log(`原因: ${recommendation.reason}`);
+  console.log(`建议命令: ${recommendation.suggestedCommand}`);
+  console.log(`完成度: ${analysis.completedRequiredFields}/${analysis.totalRequiredFields}`);
+  if (taskGraph?.nextReadyNode) {
+    console.log(`下一个就绪节点: ${taskGraph.nextReadyNode}`);
+  }
+  if (result.diagramState?.needed) {
+    console.log(`图表门禁: ${result.diagramState.shouldGateFreeze ? '激活' : '已满足'}`);
+    console.log(`建议图表: ${result.diagramState.preferredType}`);
+  }
+  console.log('工作流:');
+  console.log(`  ${workflow.join(' -> ')}`);
+  if (recommendation.suggestedQuestions.length > 0) {
+    console.log('建议问题:');
+    for (const question of recommendation.suggestedQuestions) {
+      console.log(`- ${question}`);
+    }
+  }
+}
+
+function printFreezeResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log('这版需求已经定稿，可以进入交接准备');
+  console.log(`定稿对象: ${result.snapshot.title ?? result.ws.workspaceRoot}`);
+}
+
+function printDiagramResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (result.snapshot) {
+    console.log(`已为 ${result.snapshot.title} 生成${result.type === 'product-flow' ? '产品流程' : '架构'}图`);
+  } else {
+    console.log(`已更新${result.type === 'product-flow' ? '产品流程' : '架构'}图`);
+  }
+  console.log(`HTML: ${result.htmlPath}`);
+  console.log(`JSON: ${result.jsonPath}`);
+  console.log(`Mermaid: ${result.mermaidPath}`);
+  if (result.inputPath) {
+    console.log(`输入 contract: ${result.inputPath}`);
+  }
+  if (result.marked) {
+    console.log(`评审状态: ${result.marked}`);
+  } else if (result.model?.metadata?.reviewStatus) {
+    console.log(`评审状态: ${result.model.metadata.reviewStatus}`);
+  }
+  console.log(`已打开: ${result.opened ? '是' : '否'}`);
+}
+
+function printHandoffResult(result, json) {
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log('交接资料已经生成');
+  console.log(`交接去向: ${result.handoff.target}`);
+  if (result.handoff.nextStep) {
+    console.log(`建议下一步: ${result.handoff.nextStep}`);
+  }
+}
+
+export {
+  printSynthesizeResult,
+  printReviewResult,
+  printHistoryResult,
+  printDiffResult,
+  printNextResult,
+  printFreezeResult,
+  printDiagramResult,
+  printHandoffResult,
+};