@openprd/cli 0.1.0 → 0.1.8

package/src/execution-strategy.js

@@ -0,0 +1,369 @@
+const EXECUTION_MODE_LABELS = {
+  serial: '主 Agent 串行',
+  'parallel-workers': '主 Agent 协调并行 Worker',
+  'parallel-workers-isolated': '独立隔离环境并行 Worker',
+};
+
+const PARALLEL_GROUP_LABELS = {
+  governance: '治理收口',
+  contracts: '契约与入口',
+  domain: '领域逻辑',
+  surface: '展示与界面',
+  implementation: '功能实现',
+  integration: '集成收口',
+  verification: '验证证据',
+  docs: '文档维护',
+  none: '无',
+};
+
+const OWNER_ROLE_LABELS = {
+  'main-agent': '主 Agent',
+  worker: 'Worker',
+};
+
+const INTEGRATION_OWNER_LABELS = {
+  'main-agent': '主 Agent',
+};
+
+export const EXECUTION_STRATEGY_METADATA_KEYS = [
+  'execution-mode',
+  'parallel-group',
+  'write-scope',
+  'owner-role',
+  'local-verify',
+  'integration-owner',
+];
+
+export const EXECUTION_MODE_VALUES = Object.keys(EXECUTION_MODE_LABELS);
+export const PARALLEL_GROUP_VALUES = Object.keys(PARALLEL_GROUP_LABELS);
+export const OWNER_ROLE_VALUES = Object.keys(OWNER_ROLE_LABELS);
+export const INTEGRATION_OWNER_VALUES = Object.keys(INTEGRATION_OWNER_LABELS);
+
+function normalizeToken(value) {
+  return String(value ?? '').trim().toLowerCase();
+}
+
+function splitValues(value) {
+  return String(value ?? '')
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function includesAny(text, patterns) {
+  return patterns.some((pattern) => pattern.test(text));
+}
+
+function firstKnown(values, allowed, fallback) {
+  return values.find((value) => allowed.includes(value)) ?? fallback;
+}
+
+function inferParallelGroup(text, type, phase) {
+  if (type === 'governance' || phase.includes('governance')) {
+    return 'governance';
+  }
+  if (type === 'documentation' || /docs\/basic|readme|文档|说明书|documentation|docs/i.test(text)) {
+    return 'docs';
+  }
+  if (type === 'verification' || phase.includes('verification') || /验证|回归|测试|验收|qa|verify|test/.test(text)) {
+    return 'verification';
+  }
+  if (phase.includes('integration') || /主流程|集成|闭环|联调|发布|integration|flow/.test(text)) {
+    return 'integration';
+  }
+  if (includesAny(text, [/contract|schema|api|hook|cli|ipc|preload|adapter|类型|契约|协议|接口|命令行|接线/])) {
+    return 'contracts';
+  }
+  if (includesAny(text, [/renderer|view|page|dialog|modal|surface|sidebar|route|navigation|界面|页面|弹窗|样式|组件|布局|入口|导航/])) {
+    return 'surface';
+  }
+  if (includesAny(text, [/domain|service|gateway|repository|storage|cache|backend|billing|order|entitlement|sync|状态|领域|服务|仓储|后端|数据/])) {
+    return 'domain';
+  }
+  return 'implementation';
+}
+
+function inferWriteScope(parallelGroup) {
+  const scopeByGroup = {
+    governance: ['openprd/changes/**', '.openprd/**'],
+    contracts: ['src/**', 'test/**', 'docs/basic/backend-structure.md'],
+    domain: ['src/**', 'test/**'],
+    surface: ['src/cli/**', 'src/**', 'test/**'],
+    implementation: ['src/**', 'test/**'],
+    integration: ['src/**', 'test/**', 'docs/basic/**'],
+    verification: ['test/**', '.openprd/harness/test-reports/**'],
+    docs: ['docs/basic/**', 'README*.md'],
+    none: ['src/**'],
+  };
+  return scopeByGroup[parallelGroup] ?? scopeByGroup.implementation;
+}
+
+function defaultLocalVerify(task = {}) {
+  return task.verify ?? task.metadata?.verify ?? 'openprd tasks . --change <change-id> --verify --item <task-id>';
+}
+
+export function normalizeWriteScopes(value) {
+  return [...new Set(splitValues(value))];
+}
+
+export function labelExecutionMode(mode) {
+  return EXECUTION_MODE_LABELS[normalizeToken(mode)] ?? mode ?? '未指定';
+}
+
+export function labelParallelGroup(group) {
+  return PARALLEL_GROUP_LABELS[normalizeToken(group)] ?? group ?? '未指定';
+}
+
+export function labelOwnerRole(role) {
+  return OWNER_ROLE_LABELS[normalizeToken(role)] ?? role ?? '未指定';
+}
+
+export function labelIntegrationOwner(owner) {
+  return INTEGRATION_OWNER_LABELS[normalizeToken(owner)] ?? owner ?? '未指定';
+}
+
+export function describeExecutionStrategy(strategy) {
+  const mode = labelExecutionMode(strategy.mode);
+  const group = labelParallelGroup(strategy.parallelGroup);
+  const ownerRole = labelOwnerRole(strategy.ownerRole);
+  const writeScope = (strategy.writeScope ?? []).join(', ') || '未指定';
+  const localVerify = strategy.localVerify || '未指定';
+  const integrationOwner = labelIntegrationOwner(strategy.integrationOwner);
+  return `${mode} / ${group} / ${ownerRole}；写入范围：${writeScope}；局部验证：${localVerify}；最终集成：${integrationOwner}`;
+}
+
+export function inferExecutionStrategyForTask(task = {}) {
+  const type = normalizeToken(task.type ?? task.metadata?.type ?? task.metadata?.category ?? task.metadata?.kind);
+  const phase = normalizeToken(task.phase);
+  const text = [
+    task.id,
+    task.title,
+    task.done,
+    task.verify,
+    task.metadata?.done,
+    task.metadata?.verify,
+  ].map((value) => String(value ?? '')).join('\n').toLowerCase();
+
+  if (type === 'governance' || phase.includes('governance')) {
+    return {
+      mode: 'serial',
+      parallelGroup: 'governance',
+      writeScope: inferWriteScope('governance'),
+      ownerRole: 'main-agent',
+      localVerify: defaultLocalVerify(task),
+      integrationOwner: 'main-agent',
+      inferred: true,
+    };
+  }
+
+  if (type === 'documentation' || /docs\/basic|readme|文档|说明书|documentation|docs/i.test(text)) {
+    return {
+      mode: 'parallel-workers',
+      parallelGroup: 'docs',
+      writeScope: inferWriteScope('docs'),
+      ownerRole: 'worker',
+      localVerify: defaultLocalVerify(task),
+      integrationOwner: 'main-agent',
+      inferred: true,
+    };
+  }
+
+  if (type === 'verification' || phase.includes('verification') || /验证|回归|测试|qa|verify|test/.test(text)) {
+    return {
+      mode: 'parallel-workers',
+      parallelGroup: 'verification',
+      writeScope: inferWriteScope('verification'),
+      ownerRole: 'worker',
+      localVerify: defaultLocalVerify(task),
+      integrationOwner: 'main-agent',
+      inferred: true,
+    };
+  }
+
+  if (phase.includes('integration') || /主流程|集成|闭环|联调|integration|flow/.test(text)) {
+    return {
+      mode: 'serial',
+      parallelGroup: 'integration',
+      writeScope: inferWriteScope('integration'),
+      ownerRole: 'main-agent',
+      localVerify: defaultLocalVerify(task),
+      integrationOwner: 'main-agent',
+      inferred: true,
+    };
+  }
+
+  const parallelGroup = inferParallelGroup(text, type, phase);
+  return {
+    mode: 'parallel-workers',
+    parallelGroup,
+    writeScope: inferWriteScope(parallelGroup),
+    ownerRole: 'worker',
+    localVerify: defaultLocalVerify(task),
+    integrationOwner: 'main-agent',
+    inferred: true,
+  };
+}
+
+export function taskExecutionStrategy(task = {}) {
+  const metadata = task.metadata ?? {};
+  const inferred = inferExecutionStrategyForTask(task);
+  const rawMode = normalizeToken(metadata['execution-mode']);
+  const rawGroup = normalizeToken(metadata['parallel-group']);
+  const rawOwnerRole = normalizeToken(metadata['owner-role']);
+  const rawIntegrationOwner = normalizeToken(metadata['integration-owner']);
+  const explicitWriteScope = normalizeWriteScopes(metadata['write-scope']);
+  const localVerify = String(metadata['local-verify'] ?? '').trim();
+
+  return {
+    mode: EXECUTION_MODE_VALUES.includes(rawMode) ? rawMode : inferred.mode,
+    parallelGroup: PARALLEL_GROUP_VALUES.includes(rawGroup) ? rawGroup : inferred.parallelGroup,
+    writeScope: explicitWriteScope.length > 0 ? explicitWriteScope : inferred.writeScope,
+    ownerRole: OWNER_ROLE_VALUES.includes(rawOwnerRole) ? rawOwnerRole : inferred.ownerRole,
+    localVerify: localVerify || inferred.localVerify,
+    integrationOwner: INTEGRATION_OWNER_VALUES.includes(rawIntegrationOwner) ? rawIntegrationOwner : inferred.integrationOwner,
+    inferred: !EXECUTION_MODE_VALUES.includes(rawMode)
+      || !PARALLEL_GROUP_VALUES.includes(rawGroup)
+      || explicitWriteScope.length === 0
+      || !OWNER_ROLE_VALUES.includes(rawOwnerRole)
+      || !localVerify
+      || !INTEGRATION_OWNER_VALUES.includes(rawIntegrationOwner),
+  };
+}
+
+export function formatTaskExecutionStrategyMetadata(task = {}) {
+  const strategy = inferExecutionStrategyForTask(task);
+  return [
+    `execution-mode: ${strategy.mode}`,
+    `parallel-group: ${strategy.parallelGroup}`,
+    `write-scope: ${strategy.writeScope.join(', ')}`,
+    `owner-role: ${strategy.ownerRole}`,
+    `local-verify: ${strategy.localVerify}`,
+    `integration-owner: ${strategy.integrationOwner}`,
+  ];
+}
+
+export function validateTaskExecutionStrategy(task = {}) {
+  const metadata = task.metadata ?? {};
+  const errors = [];
+  if (metadata['execution-mode']) {
+    const mode = normalizeToken(metadata['execution-mode']);
+    if (!EXECUTION_MODE_VALUES.includes(mode)) {
+      errors.push(`execution-mode 无效: ${metadata['execution-mode']}；允许值: ${EXECUTION_MODE_VALUES.join(', ')}`);
+    }
+  }
+  if (metadata['parallel-group']) {
+    const group = normalizeToken(metadata['parallel-group']);
+    if (!PARALLEL_GROUP_VALUES.includes(group)) {
+      errors.push(`parallel-group 无效: ${metadata['parallel-group']}；允许值: ${PARALLEL_GROUP_VALUES.join(', ')}`);
+    }
+  }
+  if (metadata['owner-role']) {
+    const role = normalizeToken(metadata['owner-role']);
+    if (!OWNER_ROLE_VALUES.includes(role)) {
+      errors.push(`owner-role 无效: ${metadata['owner-role']}；允许值: ${OWNER_ROLE_VALUES.join(', ')}`);
+    }
+  }
+  if (metadata['integration-owner']) {
+    const owner = normalizeToken(metadata['integration-owner']);
+    if (!INTEGRATION_OWNER_VALUES.includes(owner)) {
+      errors.push(`integration-owner 无效: ${metadata['integration-owner']}；允许值: ${INTEGRATION_OWNER_VALUES.join(', ')}`);
+    }
+  }
+
+  const hasExecutionMetadata = EXECUTION_STRATEGY_METADATA_KEYS.some((key) => Boolean(metadata[key]));
+  if (hasExecutionMetadata) {
+    if (normalizeWriteScopes(metadata['write-scope']).length === 0) {
+      errors.push('已声明执行策略，但缺少 write-scope。');
+    }
+    if (!String(metadata['local-verify'] ?? task.verify ?? '').trim()) {
+      errors.push('已声明执行策略，但缺少 local-verify 或 verify。');
+    }
+  }
+
+  const role = normalizeToken(metadata['owner-role']);
+  if (role === 'worker' && !String(metadata['integration-owner'] ?? '').trim()) {
+    errors.push('worker 任务必须声明 integration-owner。');
+  }
+  return errors;
+}
+
+export function summarizeTaskExecutionStrategies(tasks = []) {
+  const modeCounts = Object.fromEntries(EXECUTION_MODE_VALUES.map((mode) => [mode, 0]));
+  const groupCounts = Object.fromEntries(PARALLEL_GROUP_VALUES.map((group) => [group, 0]));
+  const ownerRoleCounts = Object.fromEntries(OWNER_ROLE_VALUES.map((role) => [role, 0]));
+  const taskStrategies = [];
+  let explicit = 0;
+  let inferred = 0;
+  let workerCount = 0;
+  let isolatedCount = 0;
+  let writeScopeDeclared = 0;
+
+  for (const task of tasks) {
+    const strategy = taskExecutionStrategy(task);
+    if (strategy.inferred) {
+      inferred += 1;
+    } else {
+      explicit += 1;
+    }
+    modeCounts[strategy.mode] = (modeCounts[strategy.mode] ?? 0) + 1;
+    groupCounts[strategy.parallelGroup] = (groupCounts[strategy.parallelGroup] ?? 0) + 1;
+    ownerRoleCounts[strategy.ownerRole] = (ownerRoleCounts[strategy.ownerRole] ?? 0) + 1;
+    if (strategy.ownerRole === 'worker') {
+      workerCount += 1;
+    }
+    if (strategy.mode === 'parallel-workers-isolated') {
+      isolatedCount += 1;
+    }
+    if ((strategy.writeScope ?? []).length > 0) {
+      writeScopeDeclared += 1;
+    }
+    taskStrategies.push({
+      id: task.id ?? null,
+      title: task.title ?? null,
+      mode: strategy.mode,
+      parallelGroup: strategy.parallelGroup,
+      ownerRole: strategy.ownerRole,
+      integrationOwner: strategy.integrationOwner,
+      writeScope: strategy.writeScope,
+      localVerify: strategy.localVerify,
+      inferred: strategy.inferred,
+      description: describeExecutionStrategy(strategy),
+    });
+  }
+
+  const total = taskStrategies.length;
+  const warnings = [];
+  if (total > 0 && explicit === 0) {
+    warnings.push('当前任务尚未显式声明执行策略，run/loop 将使用结构推导结果。');
+  }
+  if (workerCount > 0 && writeScopeDeclared < workerCount) {
+    warnings.push('部分 worker 任务缺少明确 write-scope，主 Agent 分片时需要先补边界。');
+  }
+  if (isolatedCount > 0 && ownerRoleCounts.worker === 0) {
+    warnings.push('声明了 isolated 执行模式，但没有 worker 角色任务。');
+  }
+
+  return {
+    total,
+    explicit,
+    inferred,
+    workerCount,
+    isolatedCount,
+    writeScopeDeclared,
+    modeCounts,
+    groupCounts,
+    ownerRoleCounts,
+    tasks: taskStrategies,
+    warnings,
+    recommendations: [
+      'L0 或小范围修正默认保持 serial，由主 Agent 直接收口。',
+      'L1/L2 中写入范围可切开的任务优先用 parallel-workers，让 worker 先做局部实现和局部验证。',
+      '高风险重构或大量实现任务再升级到 parallel-workers-isolated，由主 Agent 统一集成和总验证。',
+    ],
+  };
+}
+
+export function chooseExecutionMode(task = {}) {
+  const strategy = taskExecutionStrategy(task);
+  return firstKnown([strategy.mode], EXECUTION_MODE_VALUES, 'serial');
+}

package/src/fleet.js

@@ -297,12 +297,16 @@ async function collectFleetProjectHealth(projectPath, options, doctorWorkspace)
     return { ok: true, errors: [] };
   }
   try {
+    // Batch refresh should focus on generated guidance and workspace skeleton health.
+    // Legacy content-doc debt remains available in direct doctor/standards checks.
     const doctor = await doctorWorkspace(projectPath, {
       tools: options.tools ?? 'all',
       hookProfile: options.hookProfile,
       enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
       codexHome: options.codexHome,
       openprdHome: options.openprdHome,
+      docsContent: false,
+      sourceManuals: false,
     });
     return {
       ok: doctor.ok,

package/src/github-release.js

@@ -0,0 +1,156 @@
+/*
+ * 核心功能
+ * 从 package.json 与项目级 release-ledger 生成 GitHub Release 标题和正文。
+ *
+ * 输入
+ * 接收项目根目录、目标版本号、tag 和可选标题覆盖。
+ *
+ * 输出
+ * 返回结构化 GitHub Release payload，或把正文写入指定 Markdown 文件。
+ *
+ * 定位
+ * 位于 OpenPrd 的开源发布表达层，保证 GitHub Release 与 release-ledger 共用同一份版本事实。
+ *
+ * 依赖
+ * 仅依赖 Node 内置文件系统和 change-summary，不要求安装额外 node_modules。
+ *
+ * 维护规则
+ * 发现 package version、tag 或 release-ledger 条目不一致时必须显式失败，避免出现有版本但没有对应 Release 的发布。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { buildChangeSummaryFromEntries } from './change-summary.js';
+
+function cjoin(...parts) {
+  return path.join(...parts);
+}
+
+async function readJson(filePath) {
+  const text = await fs.readFile(filePath, 'utf8');
+  return JSON.parse(text);
+}
+
+function normalizeVersionInput(value) {
+  const text = String(value ?? '').trim();
+  if (!text) return '';
+  return text.startsWith('v') ? text.slice(1) : text;
+}
+
+function normalizeTagInput(value, fallbackVersion = '') {
+  const text = String(value ?? '').trim();
+  if (text) return text;
+  const version = normalizeVersionInput(fallbackVersion);
+  return version ? `v${version}` : '';
+}
+
+function renderReleaseMarkdown({ version, tag, changeSummary }) {
+  const bullets = changeSummary.items.map((item) => `- ${item.sentence}`);
+  return [
+    '## 安装',
+    '',
+    '```bash',
+    `npm install -g @openprd/cli@${version}`,
+    '```',
+    '',
+    '## 本次更新',
+    '',
+    ...bullets,
+    '',
+    '## 发布信息',
+    '',
+    `- 版本：${version}`,
+    `- Tag：${tag}`,
+    '- 来源：GitHub Release 文案由当前项目的 release-ledger 自动生成。',
+    '',
+  ].join('\n').trimEnd();
+}
+
+function errorResult(projectRoot, code, error) {
+  return {
+    ok: false,
+    projectRoot,
+    code,
+    error: error instanceof Error ? error.message : String(error),
+  };
+}
+
+export async function buildGitHubReleasePayload(projectRoot, options = {}) {
+  const resolvedRoot = path.resolve(projectRoot || '.');
+  const packageJsonPath = cjoin(resolvedRoot, 'package.json');
+  const ledgerPath = cjoin(resolvedRoot, '.openprd', 'state', 'release-ledger.json');
+
+  try {
+    const requestedVersion = normalizeVersionInput(options.version || options.tag || '');
+    const pkg = await readJson(packageJsonPath).catch((error) => {
+      throw new Error(`Missing package.json at ${packageJsonPath}: ${error.message}`);
+    });
+    const packageVersion = normalizeVersionInput(pkg.version);
+    if (!packageVersion) {
+      throw new Error(`Missing package version in ${packageJsonPath}.`);
+    }
+    if (requestedVersion && requestedVersion !== packageVersion) {
+      throw new Error(`Package version mismatch: package.json is ${packageVersion} but requested ${requestedVersion}.`);
+    }
+
+    const version = requestedVersion || packageVersion;
+    const tag = normalizeTagInput(options.tag, version);
+    const title = String(options.title || '').trim() || `OpenPrd ${version}`;
+
+    const ledger = await readJson(ledgerPath).catch((error) => {
+      throw new Error(`Missing release ledger at ${ledgerPath}: ${error.message}`);
+    });
+    const versions = Array.isArray(ledger.versions) ? ledger.versions : [];
+    const releaseEntry = versions.find((entry) => normalizeVersionInput(entry?.version) === version);
+    if (!releaseEntry) {
+      throw new Error([
+        `Missing release-ledger entry for version ${version}.`,
+        `Run: openprd release ${resolvedRoot} --set ${version}`,
+        'Then add user-visible notes with `openprd release <path> --notes "..."` before publishing.',
+      ].join(' '));
+    }
+
+    const changeSummary = buildChangeSummaryFromEntries(releaseEntry.items ?? [], {
+      title: `${version} 变化摘要`,
+      limit: null,
+      fallbackType: '调整',
+    });
+    if (changeSummary.items.length === 0) {
+      throw new Error([
+        `Release-ledger entry for version ${version} has no release items.`,
+        `Run: openprd release ${resolvedRoot} --notes "新增 / 修复 / 优化 ..."`,
+      ].join(' '));
+    }
+
+    const markdown = renderReleaseMarkdown({ version, tag, changeSummary });
+    return {
+      ok: true,
+      projectRoot: resolvedRoot,
+      version,
+      tag,
+      title,
+      packageName: typeof pkg.name === 'string' ? pkg.name : null,
+      packageJsonPath,
+      ledgerPath,
+      itemCount: changeSummary.items.length,
+      changeSummary,
+      markdown,
+    };
+  } catch (error) {
+    return errorResult(resolvedRoot, 'github-release-build-failed', error);
+  }
+}
+
+export async function writeGitHubReleaseNotes(projectRoot, options = {}) {
+  const payload = await buildGitHubReleasePayload(projectRoot, options);
+  if (!payload.ok) {
+    return payload;
+  }
+
+  const out = path.resolve(options.out || cjoin(payload.projectRoot, 'release-notes.md'));
+  await fs.mkdir(path.dirname(out), { recursive: true });
+  await fs.writeFile(out, `${payload.markdown.trimEnd()}\n`, 'utf8');
+  return {
+    ...payload,
+    out,
+  };
+}