@openprd/cli 0.1.0

package/src/openspec/change-lifecycle.js

@@ -0,0 +1,359 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { validateOpenSpecChangeWorkspace, resolveOpenSpecChangeId } from './change-validate.js';
+import { listOpenSpecStructuredTasks } from './tasks.js';
+import { timestamp } from '../time.js';
+import {
+  cjoin,
+  exists,
+  listChangeDirs,
+  openPrdAcceptedSpecRoot,
+  openPrdArchiveChangeRoot,
+  openPrdDiscoveryConfigPath,
+  readDiscoveryConfig,
+  resolveChangeDir,
+} from './paths.js';
+
+async function readText(filePath) {
+  return fs.readFile(filePath, 'utf8');
+}
+
+async function readJson(filePath) {
+  const text = await readText(filePath);
+  return JSON.parse(text);
+}
+
+async function writeText(filePath, text) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  await fs.writeFile(filePath, text, 'utf8');
+}
+
+async function writeJson(filePath, value) {
+  await writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function changesStatePath(projectRoot) {
+  return cjoin(projectRoot, '.openprd', 'state', 'changes.json');
+}
+
+async function readChangesState(projectRoot) {
+  return (await readJson(changesStatePath(projectRoot)).catch(() => null)) ?? {
+    version: 1,
+    activeChange: null,
+    changes: {},
+  };
+}
+
+async function writeChangesState(projectRoot, state) {
+  await writeJson(changesStatePath(projectRoot), {
+    version: 1,
+    activeChange: state.activeChange ?? null,
+    updatedAt: timestamp(),
+    changes: state.changes ?? {},
+  });
+}
+
+async function writeActiveChange(projectRoot, changeId) {
+  const state = await readChangesState(projectRoot);
+  state.activeChange = changeId;
+  state.changes[changeId] = {
+    ...(state.changes[changeId] ?? {}),
+    id: changeId,
+    status: 'active',
+    activatedAt: timestamp(),
+  };
+  await writeChangesState(projectRoot, state);
+
+  const config = await readDiscoveryConfig(projectRoot, readJson);
+  await writeJson(openPrdDiscoveryConfigPath(projectRoot), {
+    ...config,
+    activeChange: changeId,
+  });
+
+  return state;
+}
+
+async function readAcceptedIndex(projectRoot) {
+  const indexPath = cjoin(openPrdAcceptedSpecRoot(projectRoot), 'index.json');
+  return (await readJson(indexPath).catch(() => null)) ?? {
+    version: 1,
+    updatedAt: null,
+    capabilities: {},
+    appliedChanges: [],
+  };
+}
+
+async function writeAcceptedIndex(projectRoot, index) {
+  await writeJson(cjoin(openPrdAcceptedSpecRoot(projectRoot), 'index.json'), {
+    version: 1,
+    updatedAt: timestamp(),
+    capabilities: index.capabilities ?? {},
+    appliedChanges: index.appliedChanges ?? [],
+  });
+}
+
+async function collectChangeSpecs(changeDir) {
+  const specsRoot = cjoin(changeDir, 'specs');
+  const specs = [];
+  let entries = [];
+  try {
+    entries = await fs.readdir(specsRoot, { withFileTypes: true });
+  } catch {
+    return specs;
+  }
+
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) {
+      continue;
+    }
+    const sourcePath = cjoin(specsRoot, entry.name, 'spec.md');
+    if (await exists(sourcePath)) {
+      specs.push({
+        capability: entry.name,
+        sourcePath,
+      });
+    }
+  }
+
+  return specs;
+}
+
+async function allStructuredTasksComplete(projectRoot, changeId) {
+  const { tasks } = await listOpenSpecStructuredTasks(projectRoot, { changeId });
+  if (tasks.length === 0) {
+    return { complete: true, total: 0, incomplete: [] };
+  }
+  const incomplete = tasks.filter((task) => !task.checked);
+  return {
+    complete: incomplete.length === 0,
+    total: tasks.length,
+    incomplete: incomplete.map((task) => task.id),
+  };
+}
+
+async function updateChangeStatus(projectRoot, changeId, status, extra = {}) {
+  const state = await readChangesState(projectRoot);
+  state.changes[changeId] = {
+    ...(state.changes[changeId] ?? {}),
+    id: changeId,
+    status,
+    updatedAt: timestamp(),
+    ...extra,
+  };
+  if (status === 'active') {
+    state.activeChange = changeId;
+  }
+  if ((status === 'closed' || status === 'archived' || status === 'applied') && state.activeChange === changeId) {
+    state.activeChange = null;
+  }
+  await writeChangesState(projectRoot, state);
+  return state;
+}
+
+export async function listOpenPrdChangesWorkspace(projectRoot) {
+  const state = await readChangesState(projectRoot);
+  const discoveryConfig = await readDiscoveryConfig(projectRoot, readJson);
+  const activeChange = state.activeChange ?? discoveryConfig.activeChange ?? null;
+  const changes = await listChangeDirs(projectRoot);
+  const rows = [];
+
+  for (const change of changes) {
+    const taskState = await allStructuredTasksComplete(projectRoot, change.id).catch(() => ({ total: 0, incomplete: [] }));
+    rows.push({
+      id: change.id,
+      source: change.source,
+      status: state.changes?.[change.id]?.status ?? (change.archived ? 'archived' : 'draft'),
+      active: change.id === activeChange,
+      archived: change.archived,
+      changeDir: change.changeDir,
+      taskTotal: taskState.total,
+      taskIncomplete: taskState.incomplete.length,
+    });
+  }
+
+  return {
+    ok: true,
+    action: 'list',
+    projectRoot,
+    activeChange,
+    changes: rows,
+  };
+}
+
+export async function activateOpenPrdChangeWorkspace(projectRoot, options = {}) {
+  const changeId = await resolveOpenSpecChangeId(projectRoot, options.change);
+  const changeDir = await resolveChangeDir(projectRoot, changeId);
+  if (!(await exists(changeDir))) {
+    throw new Error(`Missing OpenPrd change directory: ${path.relative(projectRoot, changeDir)}`);
+  }
+  await writeActiveChange(projectRoot, changeId);
+  return {
+    ok: true,
+    action: 'activate',
+    projectRoot,
+    changeId,
+    changeDir,
+  };
+}
+
+export async function closeOpenPrdChangeWorkspace(projectRoot, options = {}) {
+  const changeId = await resolveOpenSpecChangeId(projectRoot, options.change);
+  const state = await updateChangeStatus(projectRoot, changeId, 'closed', {
+    closedAt: timestamp(),
+    reason: options.notes ?? null,
+  });
+  return {
+    ok: true,
+    action: 'close',
+    projectRoot,
+    changeId,
+    activeChange: state.activeChange,
+  };
+}
+
+export async function applyOpenPrdChangeWorkspace(projectRoot, options = {}) {
+  const changeId = await resolveOpenSpecChangeId(projectRoot, options.change);
+  const validation = await validateOpenSpecChangeWorkspace(projectRoot, { change: changeId });
+  if (!validation.ok) {
+    return {
+      ok: false,
+      action: 'apply',
+      projectRoot,
+      changeId,
+      validation,
+      appliedSpecs: [],
+      errors: validation.errors,
+    };
+  }
+
+  const taskState = await allStructuredTasksComplete(projectRoot, changeId);
+  if (!taskState.complete && !options.force) {
+    return {
+      ok: false,
+      action: 'apply',
+      projectRoot,
+      changeId,
+      validation,
+      appliedSpecs: [],
+      errors: [`Change ${changeId} 仍有未完成任务: ${taskState.incomplete.join(', ')}。如需强制应用，请使用 --force。`],
+    };
+  }
+
+  const changeDir = await resolveChangeDir(projectRoot, changeId);
+  const specs = await collectChangeSpecs(changeDir);
+  const acceptedRoot = openPrdAcceptedSpecRoot(projectRoot);
+  const acceptedIndex = await readAcceptedIndex(projectRoot);
+  const appliedSpecs = [];
+  const now = timestamp();
+
+  for (const spec of specs) {
+    const targetPath = cjoin(acceptedRoot, spec.capability, 'spec.md');
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.copyFile(spec.sourcePath, targetPath);
+    acceptedIndex.capabilities[spec.capability] = {
+      capability: spec.capability,
+      specPath: path.relative(projectRoot, targetPath),
+      sourceChange: changeId,
+      appliedAt: now,
+    };
+    appliedSpecs.push({
+      capability: spec.capability,
+      specPath: targetPath,
+    });
+  }
+
+  acceptedIndex.appliedChanges.push({
+    changeId,
+    appliedAt: now,
+    forced: Boolean(options.force),
+    capabilities: appliedSpecs.map((spec) => spec.capability),
+  });
+  await writeAcceptedIndex(projectRoot, acceptedIndex);
+  await updateChangeStatus(projectRoot, changeId, 'applied', {
+    appliedAt: now,
+    forced: Boolean(options.force),
+    acceptedSpecCount: appliedSpecs.length,
+  });
+
+  return {
+    ok: true,
+    action: 'apply',
+    projectRoot,
+    changeId,
+    validation,
+    appliedSpecs,
+    acceptedRoot,
+    taskState,
+  };
+}
+
+export async function archiveOpenPrdChangeWorkspace(projectRoot, options = {}) {
+  const changeId = await resolveOpenSpecChangeId(projectRoot, options.change);
+  const changeDir = await resolveChangeDir(projectRoot, changeId);
+  if (!(await exists(changeDir))) {
+    throw new Error(`Missing OpenPrd change directory: ${path.relative(projectRoot, changeDir)}`);
+  }
+  const archiveDir = cjoin(openPrdArchiveChangeRoot(projectRoot), changeId);
+  if (await exists(archiveDir)) {
+    if (!options.force) {
+      throw new Error(`Archived change already exists: ${path.relative(projectRoot, archiveDir)}. Use --force to overwrite.`);
+    }
+    await fs.rm(archiveDir, { recursive: true, force: true });
+  }
+  await fs.mkdir(path.dirname(archiveDir), { recursive: true });
+  await fs.cp(changeDir, archiveDir, { recursive: true });
+  if (!options.keep) {
+    await fs.rm(changeDir, { recursive: true, force: true });
+  }
+  await updateChangeStatus(projectRoot, changeId, 'archived', {
+    archivedAt: timestamp(),
+    archiveDir: path.relative(projectRoot, archiveDir),
+    sourceDir: path.relative(projectRoot, changeDir),
+    keptSource: Boolean(options.keep),
+  });
+
+  return {
+    ok: true,
+    action: 'archive',
+    projectRoot,
+    changeId,
+    archiveDir,
+    removedSource: !options.keep,
+  };
+}
+
+export async function listAcceptedSpecsWorkspace(projectRoot) {
+  const acceptedRoot = openPrdAcceptedSpecRoot(projectRoot);
+  const index = await readAcceptedIndex(projectRoot);
+  const specs = [];
+
+  let entries = [];
+  try {
+    entries = await fs.readdir(acceptedRoot, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) {
+      continue;
+    }
+    const specPath = cjoin(acceptedRoot, entry.name, 'spec.md');
+    if (await exists(specPath)) {
+      specs.push({
+        capability: entry.name,
+        specPath,
+        metadata: index.capabilities?.[entry.name] ?? null,
+      });
+    }
+  }
+
+  return {
+    ok: true,
+    action: 'specs',
+    projectRoot,
+    acceptedRoot,
+    specs,
+    appliedChanges: index.appliedChanges ?? [],
+  };
+}

package/src/openspec/change-validate.js

@@ -0,0 +1,248 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import YAML from 'yaml';
+import { listChangeDirs, readDiscoveryConfig, resolveChangeDir } from './paths.js';
+import { analyzeOpenSpecTaskVolumes } from './tasks.js';
+import { checkStandardsWorkspace } from '../standards.js';
+import { findOpenPrdSpecLanguageViolations } from '../language-policy.js';
+
+function cjoin(...parts) {
+  return path.join(...parts);
+}
+
+function exists(filePath) {
+  return fs.access(filePath).then(() => true).catch(() => false);
+}
+
+async function readText(filePath) {
+  return fs.readFile(filePath, 'utf8');
+}
+
+async function readYaml(filePath) {
+  const text = await readText(filePath);
+  const parsed = YAML.parse(text);
+  return parsed ?? {};
+}
+
+async function readJson(filePath) {
+  const text = await readText(filePath);
+  return JSON.parse(text);
+}
+
+export async function resolveOpenSpecChangeId(projectRoot, requestedChange) {
+  if (requestedChange) {
+    return requestedChange;
+  }
+
+  const discoveryConfig = await readDiscoveryConfig(projectRoot, readJson);
+  if (discoveryConfig?.activeChange) {
+    return discoveryConfig.activeChange;
+  }
+
+  const changeDirs = [...new Set((await listChangeDirs(projectRoot))
+    .filter((change) => !change.archived)
+    .map((change) => change.id))]
+    .sort();
+
+  if (changeDirs.length === 1) {
+    return changeDirs[0];
+  }
+  if (changeDirs.length === 0) {
+    throw new Error('openprd/changes 下没有找到 OpenPrd change。');
+  }
+  throw new Error(`找到多个 OpenPrd change；请传入 --change <id>。已找到: ${changeDirs.join(', ')}`);
+}
+
+function extractProposalCapabilities(text) {
+  const capabilities = [];
+  for (const match of text.matchAll(/^- `([^`]+)`:/gm)) {
+    capabilities.push(match[1]);
+  }
+  return capabilities;
+}
+
+const SPEC_SECTION_HEADING_RE = /^##\s+(?:(ADDED|MODIFIED|REMOVED)\s+Requirements|(?:新增|修改|移除)需求)\s*$/gim;
+const REQUIREMENT_HEADING_RE = /^###\s+(?:Requirement|需求)[：:]\s*(.+)$/gm;
+const SCENARIO_HEADING_RE = /^####\s+(?:Scenario|场景)[：:]\s*(.+)$/gm;
+const WHEN_STEP_RE = /^-\s+\*\*(?:WHEN|当)\*\*/im;
+const THEN_STEP_RE = /^-\s+\*\*(?:THEN|则|那么)\*\*/im;
+
+function validateOpenSpecSpecText(relativePath, text, errors, checks) {
+  const requirementMatches = [...text.matchAll(REQUIREMENT_HEADING_RE)];
+  const sectionMatches = [...text.matchAll(SPEC_SECTION_HEADING_RE)];
+  const languageViolations = findOpenPrdSpecLanguageViolations(text);
+
+  if (sectionMatches.length === 0) {
+    errors.push(`${relativePath} 必须包含“新增需求”“修改需求”或“移除需求”章节。`);
+  }
+  if (requirementMatches.length === 0) {
+    errors.push(`${relativePath} 必须至少包含一个 "### 需求：" 块。`);
+  }
+
+  for (let index = 0; index < requirementMatches.length; index += 1) {
+    const match = requirementMatches[index];
+    const title = match[1].trim();
+    const start = match.index ?? 0;
+    const end = requirementMatches[index + 1]?.index ?? text.length;
+    const block = text.slice(start, end);
+    const scenarioMatches = [...block.matchAll(SCENARIO_HEADING_RE)];
+    if (scenarioMatches.length === 0) {
+      errors.push(`${relativePath} 的需求 "${title}" 必须至少包含一个场景。`);
+      continue;
+    }
+
+    for (const scenarioMatch of scenarioMatches) {
+      const scenarioStart = scenarioMatch.index ?? 0;
+      const nextScenario = scenarioMatches.find((candidate) => (candidate.index ?? 0) > scenarioStart);
+      const scenarioBlock = block.slice(scenarioStart, nextScenario?.index ?? block.length);
+      if (!WHEN_STEP_RE.test(scenarioBlock)) {
+        errors.push(`${relativePath} 的场景 "${scenarioMatch[1].trim()}" 缺少“当”。`);
+      }
+      if (!THEN_STEP_RE.test(scenarioBlock)) {
+        errors.push(`${relativePath} 的场景 "${scenarioMatch[1].trim()}" 缺少“则”。`);
+      }
+    }
+  }
+
+  for (const violation of languageViolations.slice(0, 5)) {
+    errors.push(`${relativePath}:${violation.line} 不符合简体中文规则: ${violation.reason}。除必要专业字段、命令、文件名或英文产品名外，spec.md 正文必须使用简体中文。`);
+  }
+  if (languageViolations.length > 5) {
+    errors.push(`${relativePath} 还有 ${languageViolations.length - 5} 处简体中文规则问题。`);
+  }
+
+  checks.push(`${relativePath}: ${requirementMatches.length} 个需求。`);
+}
+
+export async function validateOpenSpecChangeWorkspace(projectRoot, options = {}) {
+  const changeId = await resolveOpenSpecChangeId(projectRoot, options.change);
+  const changeDir = await resolveChangeDir(projectRoot, changeId);
+  const errors = [];
+  const warnings = [];
+  const checks = [];
+
+  if (!(await exists(changeDir))) {
+    errors.push(`缺少 OpenPrd change 目录: ${path.relative(projectRoot, changeDir)}`);
+    return {
+      ok: false,
+      valid: false,
+      projectRoot,
+      changeId,
+      changeDir,
+      errors,
+      warnings,
+      checks,
+      specs: [],
+      taskVolume: { errors: [], checks: [], files: [] },
+    };
+  }
+
+  const metadataPaths = [cjoin(changeDir, '.openprd.yaml'), cjoin(changeDir, '.openspec.yaml')];
+  for (const metadataPath of metadataPaths) {
+    if (await exists(metadataPath)) {
+      await readYaml(metadataPath).catch((error) => {
+        errors.push(`${path.relative(projectRoot, metadataPath)} 无效: ${error.message}`);
+      });
+      break;
+    }
+  }
+
+  const proposalPath = cjoin(changeDir, 'proposal.md');
+  let proposalText = '';
+  if (!(await exists(proposalPath))) {
+    errors.push(`${path.relative(projectRoot, proposalPath)} 是必需文件。`);
+  } else {
+    proposalText = await readText(proposalPath);
+    if (!proposalText.trim()) {
+      errors.push(`${path.relative(projectRoot, proposalPath)} 不能为空。`);
+    }
+    const requiredHeadingGroups = [
+      ['## 背景与原因', '## Why', '## 为什么'],
+      ['## 变更内容', '## What Changes'],
+      ['## 影响范围', '## Impact', '## 影响'],
+    ];
+    for (const headings of requiredHeadingGroups) {
+      if (!headings.some((heading) => proposalText.includes(heading))) {
+        warnings.push(`${path.relative(projectRoot, proposalPath)} 缺少章节: ${headings[0]}`);
+      }
+    }
+  }
+
+  const designPath = cjoin(changeDir, 'design.md');
+  if (!(await exists(designPath))) {
+    warnings.push(`${path.relative(projectRoot, designPath)} 缺失；复杂变更建议补充设计依据。`);
+  }
+
+  const specsRoot = cjoin(changeDir, 'specs');
+  const specs = [];
+  if (!(await exists(specsRoot))) {
+    errors.push(`${path.relative(projectRoot, specsRoot)} 是必需目录。`);
+  } else {
+    const specEntries = await fs.readdir(specsRoot, { withFileTypes: true }).catch(() => []);
+    for (const entry of specEntries.sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) {
+        continue;
+      }
+      const specPath = cjoin(specsRoot, entry.name, 'spec.md');
+      const relativePath = path.relative(projectRoot, specPath);
+      if (!(await exists(specPath))) {
+        errors.push(`${relativePath} 是必需文件。`);
+        continue;
+      }
+      const text = await readText(specPath);
+      specs.push({ capability: entry.name, path: specPath, relativePath });
+      validateOpenSpecSpecText(relativePath, text, errors, checks);
+    }
+  }
+
+  if (specs.length === 0) {
+    errors.push(`${path.relative(projectRoot, specsRoot)} 必须至少包含一个 capability spec。`);
+  }
+
+  const proposalCapabilities = extractProposalCapabilities(proposalText);
+  for (const capability of proposalCapabilities) {
+    if (!specs.some((spec) => spec.capability === capability)) {
+      warnings.push(`proposal.md 中的 capability ${capability} 没有对应的 specs/${capability}/spec.md。`);
+    }
+  }
+  for (const spec of specs) {
+    if (proposalCapabilities.length > 0 && !proposalCapabilities.includes(spec.capability)) {
+      warnings.push(`spec capability ${spec.capability} 未列入 proposal.md 的能力范围。`);
+    }
+  }
+
+  const taskVolume = await analyzeOpenSpecTaskVolumes(projectRoot, { changeId });
+  errors.push(...taskVolume.errors);
+  checks.push(...taskVolume.checks);
+
+  const standards = await checkStandardsWorkspace(projectRoot, {
+    optional: !(await exists(cjoin(projectRoot, '.openprd'))),
+    sourceManuals: options.sourceManuals,
+    docsContent: options.docsContent,
+  });
+  if (!standards.skipped) {
+    errors.push(...standards.errors);
+    warnings.push(...standards.warnings);
+    checks.push(...standards.checks);
+    const hasStandardsTask = taskVolume.files.some((file) => file.text.includes('openprd standards') && file.text.includes('docs/basic'));
+    if (!hasStandardsTask) {
+      warnings.push(`${path.relative(projectRoot, changeDir)} 应包含 docs/basic 标准文档维护任务。`);
+    }
+  }
+
+  checks.unshift(`OpenPrd change ${changeId}: ${specs.length} 个 spec delta。`);
+
+  return {
+    ok: errors.length === 0,
+    valid: errors.length === 0,
+    projectRoot,
+    changeId,
+    changeDir,
+    errors,
+    warnings,
+    checks,
+    specs,
+    taskVolume,
+    standards,
+  };
+}

package/src/openspec/constants.js

@@ -0,0 +1,12 @@
+export const OPENPRD_DISCOVERY_DIR = ['.openprd', 'discovery'];
+export const OPENPRD_DISCOVERY_CONFIG_PATH = ['.openprd', 'discovery', 'config.json'];
+export const LEGACY_OPENSPEC_DISCOVERY_DIR = ['.openspec', 'discovery'];
+export const LEGACY_OPENSPEC_DISCOVERY_CONFIG_PATH = ['.openspec', 'discovery', 'config.json'];
+export const OPENSPEC_DISCOVERY_CONFIG_PATH = LEGACY_OPENSPEC_DISCOVERY_CONFIG_PATH;
+export const OPENPRD_CHANGE_ROOT = ['openprd', 'changes'];
+export const LEGACY_OPENSPEC_CHANGE_ROOT = ['openspec', 'changes'];
+export const OPENPRD_ACCEPTED_SPEC_ROOT = ['openprd', 'specs'];
+export const OPENPRD_ARCHIVE_CHANGE_ROOT = ['openprd', 'archive', 'changes'];
+export const OPENSPEC_TASK_MAX_ITEMS_PER_FILE = 25;
+export const OPENSPEC_TASK_FILE_PATTERN = /^tasks(?:-\d{3})?\.md$/;
+export const OPENSPEC_TASK_ID_PATTERN = /^T\d{3}\.\d+$/;