@aipper/aiws 0.0.24 → 0.0.25

package/src/commands/change-lifecycle.js

@@ -0,0 +1,219 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   changeDir: string
+ * }} input
+ * @param {{
+ *   appendMetricsEvent: (gitRoot: string, changeId: string, type: string, payload: any) => Promise<void>,
+ *   ensureDir: (path: string) => Promise<void>,
+ *   nowIsoUtc: () => string,
+ *   nowStampUtc: () => string,
+ *   nowUnixSeconds: () => number,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   readText: (path: string) => Promise<string>,
+ *   snapshotTruthFiles: (gitRoot: string) => Promise<any>,
+ *   writeText: (path: string, content: string) => Promise<void>
+ * }} deps
+ */
+export async function runChangeSyncWorkflow(input, deps) {
+  const { gitRoot, changeId, changeDir } = input;
+  const metaPath = path.join(changeDir, ".ws-change.json");
+  /** @type {any} */
+  let meta = null;
+  if (await deps.pathExists(metaPath)) {
+    try {
+      meta = JSON.parse(await deps.readText(metaPath));
+    } catch {
+      meta = null;
+    }
+  }
+
+  const truth = await deps.snapshotTruthFiles(gitRoot);
+  const nowIso = deps.nowIsoUtc();
+  const nowTs = deps.nowUnixSeconds();
+
+  if (!meta) {
+    meta = { ws_change_version: 1, id: changeId, title: changeId, created_at: nowIso, base_truth_files: truth };
+  }
+
+  const createdTruth = meta.base_truth_files && typeof meta.base_truth_files === "object" ? meta.base_truth_files : {};
+  const syncedTruth = meta.synced_truth_files && typeof meta.synced_truth_files === "object" ? meta.synced_truth_files : {};
+  const baseline = Object.keys(syncedTruth).length > 0 ? syncedTruth : createdTruth;
+  const baselineLabel = Object.keys(syncedTruth).length > 0 ? "last sync" : "creation";
+  const baselineAt = Object.keys(syncedTruth).length > 0 ? String(meta.synced_at || "") : String(meta.created_at || "");
+
+  /** @type {Array<{file: string, from: string | null, to: string | null}>} */
+  const changed = [];
+  for (const [rel, info] of Object.entries(truth)) {
+    const curSha = info && typeof info === "object" ? String(info.sha256 || "") : "";
+    const baseSha =
+      baseline && typeof baseline === "object" && baseline[rel] && typeof baseline[rel] === "object" ? String(baseline[rel].sha256 || "") : "";
+    if (baseSha && curSha && baseSha !== curSha) {
+      changed.push({ file: rel, from: baseSha, to: curSha });
+    } else if (!baseSha && curSha) {
+      changed.push({ file: rel, from: null, to: curSha });
+    }
+  }
+  if (baseline && typeof baseline === "object") {
+    for (const rel of Object.keys(baseline)) {
+      if (!truth[rel]) {
+        const fromSha = baseline[rel] && typeof baseline[rel] === "object" ? String(baseline[rel].sha256 || "") : null;
+        changed.push({ file: rel, from: fromSha || null, to: null });
+      }
+    }
+  }
+
+  meta.synced_at = nowIso;
+  meta.synced_truth_files = truth;
+  let events = meta.sync_events;
+  if (!Array.isArray(events)) events = [];
+  events.push({ synced_at: nowIso, baseline_from: baselineLabel, baseline_at: baselineAt, changed });
+  meta.sync_events = events.slice(-20);
+  await deps.writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
+
+  const stampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-sync");
+  await deps.ensureDir(stampDir);
+  const stampPath = path.join(stampDir, `${deps.nowStampUtc()}-${changeId}.json`);
+  await deps.writeText(
+    stampPath,
+    JSON.stringify(
+      {
+        timestamp: nowTs,
+        ws_root: gitRoot,
+        change_id: changeId,
+        change_dir: changeDir,
+        synced_at: nowIso,
+        previous_baseline: { label: baselineLabel, at: baselineAt, truth_files: baseline },
+        new_baseline: truth,
+        changed,
+        note: "aiws change sync stamp; does not contain secrets.",
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  await deps.appendMetricsEvent(gitRoot, changeId, "truth_sync", {
+    synced_at: nowIso,
+    baseline_from: baselineLabel,
+    baseline_at: baselineAt,
+    changed_files: changed.map((item) => item.file),
+  });
+
+  /** @type {string[]} */
+  const outputLines = [];
+  outputLines.push(`✓ aiws change sync: ${changeId}`);
+  outputLines.push(`meta: ${path.relative(gitRoot, metaPath)}`);
+  outputLines.push(`stamp: ${path.relative(gitRoot, stampPath)}`);
+  outputLines.push("");
+  if (changed.length > 0) {
+    outputLines.push("Changed files:");
+    for (const item of changed) outputLines.push(`- ${item.file}`);
+  } else {
+    outputLines.push("No changes detected vs baseline.");
+  }
+  return { output: outputLines.join("\n") + "\n" };
+}
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   changeDir: string,
+ *   datePrefix?: string,
+ *   force: boolean
+ * }} input
+ * @param {{
+ *   appendMetricsEvent: (gitRoot: string, changeId: string, type: string, payload: any) => Promise<void>,
+ *   changeValidateCommand: (options: { changeId: string, strict: boolean, allowTruthDrift: boolean }) => Promise<void>,
+ *   ensureDir: (path: string) => Promise<void>,
+ *   generateHandoffContent: (gitRoot: string, changeDir: string, changeId: string) => Promise<string>,
+ *   nowIsoUtc: () => string,
+ *   nowStampUtc: () => string,
+ *   nowUnixSeconds: () => number,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   readText: (path: string) => Promise<string>,
+ *   snapshotTruthFiles: (gitRoot: string) => Promise<any>,
+ *   todayLocal: () => string,
+ *   writeText: (path: string, content: string) => Promise<void>,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function runChangeArchiveWorkflow(input, deps) {
+  const { gitRoot, changeId, changeDir } = input;
+  await deps.changeValidateCommand({ changeId, strict: true, allowTruthDrift: input.force });
+
+  const tasksAbs = path.join(changeDir, "tasks.md");
+  if (await deps.pathExists(tasksAbs)) {
+    const tasksText = await deps.readText(tasksAbs);
+    if (/- \[ \]/.test(tasksText)) {
+      if (!input.force) {
+        throw new deps.UserError("tasks.md still has unchecked tasks; complete them or pass --force");
+      }
+      console.error("warn: tasks.md still has unchecked tasks; continuing due to --force");
+    }
+  }
+
+  const archiveRoot = path.join(gitRoot, "changes", "archive");
+  await deps.ensureDir(archiveRoot);
+
+  const prefix = (input.datePrefix ? String(input.datePrefix) : deps.todayLocal()).trim() || deps.todayLocal();
+  let dest = path.join(archiveRoot, `${prefix}-${changeId}`);
+  if (await deps.pathExists(dest)) {
+    dest = path.join(archiveRoot, `${prefix}-${changeId}-${deps.nowStampUtc()}`);
+  }
+
+  await deps.appendMetricsEvent(gitRoot, changeId, "archive", { archived_to: path.relative(gitRoot, dest) });
+  await fs.rename(changeDir, dest);
+
+  const handoffPath = path.join(dest, "handoff.md");
+  const handoffContent = await deps.generateHandoffContent(gitRoot, dest, changeId);
+  await deps.writeText(handoffPath, handoffContent);
+
+  const metaPath = path.join(dest, ".ws-change.json");
+  let metaUpdated = false;
+  if (await deps.pathExists(metaPath)) {
+    try {
+      const meta = JSON.parse(await deps.readText(metaPath));
+      const truth = await deps.snapshotTruthFiles(gitRoot);
+      meta.archived_at = deps.nowIsoUtc();
+      meta.archived_to = dest;
+      meta.archived_truth_files = truth;
+      await deps.writeText(metaPath, JSON.stringify(meta, null, 2) + "\n");
+      metaUpdated = true;
+    } catch {
+      metaUpdated = false;
+    }
+  }
+
+  const stampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-archive");
+  await deps.ensureDir(stampDir);
+  const stampPath = path.join(stampDir, `${deps.nowStampUtc()}-${changeId}.json`);
+  const truth = await deps.snapshotTruthFiles(gitRoot);
+  await deps.writeText(
+    stampPath,
+    JSON.stringify(
+      {
+        timestamp: deps.nowUnixSeconds(),
+        ws_root: gitRoot,
+        archived_to: dest,
+        truth_files: truth,
+        note: "aiws change archive stamp; does not contain secrets.",
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+
+  /** @type {string[]} */
+  const outputLines = [];
+  outputLines.push(`✓ aiws change archive: ${changeId}`);
+  outputLines.push(`archived_to: ${path.relative(gitRoot, dest)}`);
+  outputLines.push(`handoff: ${path.relative(gitRoot, handoffPath)}`);
+  if (metaUpdated) outputLines.push(`meta_updated: ${path.relative(gitRoot, metaPath)}`);
+  outputLines.push(`stamp: ${path.relative(gitRoot, stampPath)}`);
+  return { output: outputLines.join("\n") + "\n" };
+}

package/src/commands/change-metrics-command.js

@@ -0,0 +1,110 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   sinceRaw: string,
+ *   since: number
+ * }} input
+ * @param {{
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   readText: (path: string) => Promise<string>
+ * }} deps
+ */
+export async function renderMetricsSummaryOutput(input, deps) {
+  const { gitRoot, sinceRaw, since } = input;
+  const changesRoot = path.join(gitRoot, "changes");
+  if (!(await deps.pathExists(changesRoot))) {
+    return "(no changes dir)\n";
+  }
+
+  /** @type {Array<{ changeId: string, path: string, metrics: any }>} */
+  const all = [];
+  const scanDirs = [changesRoot, path.join(changesRoot, "archive")];
+  for (const base of scanDirs) {
+    if (!(await deps.pathExists(base))) continue;
+    const entries = await fs.readdir(base, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dir = path.join(base, entry.name);
+      const metricsAbs = path.join(dir, "metrics.json");
+      if (!(await deps.pathExists(metricsAbs))) continue;
+      try {
+        const metrics = JSON.parse(await deps.readText(metricsAbs));
+        const changeId = String(metrics?.change_id || "").trim() || entry.name;
+        all.push({ changeId, path: path.relative(gitRoot, metricsAbs), metrics });
+      } catch {
+        // ignore invalid
+      }
+    }
+  }
+
+  if (all.length === 0) {
+    return "(no metrics.json found)\n";
+  }
+
+  /** @type {Record<string, number>} */
+  const eventCounts = {};
+  let strictValidations = 0;
+  let strictPass = 0;
+  let evidenceRuns = 0;
+  let finishRuns = 0;
+  /** @type {number[]} */
+  const durations = [];
+
+  for (const row of all) {
+    const events = Array.isArray(row.metrics?.events) ? row.metrics.events : [];
+    const filtered = since
+      ? events.filter((event) => {
+          const timestamp = Date.parse(String(event?.timestamp || ""));
+          return Number.isFinite(timestamp) && timestamp >= since;
+        })
+      : events;
+
+    for (const event of filtered) {
+      const type = String(event?.type || "unknown");
+      eventCounts[type] = (eventCounts[type] || 0) + 1;
+      if (type === "validate") {
+        const payload = event?.payload || {};
+        if (payload.strict === true) {
+          strictValidations += 1;
+          if (payload.ok === true) strictPass += 1;
+        }
+      }
+      if (type === "evidence") evidenceRuns += 1;
+      if (type === "finish" || type === "finish_done") finishRuns += 1;
+    }
+
+    const startedAt = events.find((event) => event?.type === "change_new")?.timestamp;
+    const finishedAt = events.find((event) => event?.type === "finish_done")?.timestamp || events.find((event) => event?.type === "finish")?.timestamp;
+    if (startedAt && finishedAt) {
+      const startTime = Date.parse(String(startedAt));
+      const finishTime = Date.parse(String(finishedAt));
+      if (Number.isFinite(startTime) && Number.isFinite(finishTime) && finishTime >= startTime) {
+        durations.push(Math.floor((finishTime - startTime) / 1000));
+      }
+    }
+  }
+
+  const avgSec = durations.length > 0 ? Math.floor(durations.reduce((left, right) => left + right, 0) / durations.length) : 0;
+  const avgMin = avgSec ? Math.floor(avgSec / 60) : 0;
+
+  /** @type {string[]} */
+  const lines = [];
+  lines.push(`AIWS Metrics Summary${sinceRaw ? ` (since ${sinceRaw})` : ""}`);
+  lines.push("================================================");
+  lines.push(`Total metric files: ${all.length}`);
+  lines.push("");
+  lines.push("Event counts:");
+  for (const key of Object.keys(eventCounts).sort()) lines.push(`- ${key}: ${eventCounts[key]}`);
+  lines.push("");
+  lines.push("Quality:");
+  lines.push(`- Strict validate pass rate: ${strictValidations > 0 ? `${strictPass}/${strictValidations}` : "(no data)"}`);
+  lines.push(`- Evidence runs: ${evidenceRuns}`);
+  lines.push(`- Finish runs: ${finishRuns}`);
+  lines.push("");
+  lines.push("Cycle time (best-effort):");
+  lines.push(`- Avg change_new -> finish: ${durations.length > 0 ? `${avgMin} min` : "(no data)"}`);
+  return lines.join("\n") + "\n";
+}

package/src/commands/change-next-command.js

@@ -0,0 +1,127 @@
+import path from "node:path";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   changeDir: string,
+ *   status: any
+ * }} input
+ * @param {{
+ *   analyzeEvidencePaths: (gitRoot: string, changeId: string, evidencePaths: string[]) => Promise<any>,
+ *   computeChangeNextAdvice: (gitRoot: string, changeId: string) => Promise<any>,
+ *   extractId: (label: string, text: string) => string,
+ *   fileState: (changeDir: string, rel: string) => Promise<any>,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   planVerifyHint: (changeId: string) => string,
+ *   splitDeclaredValues: (value: string) => string[]
+ * }} deps
+ */
+export async function renderChangeNextOutput(input, deps) {
+  const { gitRoot, changeId, changeDir, status } = input;
+  const proposal = await deps.fileState(changeDir, "proposal.md");
+  const tasks = await deps.fileState(changeDir, "tasks.md");
+  const design = await deps.fileState(changeDir, "design.md");
+  const advice = await deps.computeChangeNextAdvice(gitRoot, changeId);
+
+  const actionSet = new Set(advice.actions);
+  const pushAction = (line) => {
+    const value = String(line || "").trim();
+    if (!value || actionSet.has(value)) return;
+    actionSet.add(value);
+    advice.actions.push(value);
+  };
+
+  if (proposal.state !== "ok" || proposal.wsTodo > 0 || proposal.placeholders > 0) {
+    pushAction(`完善 proposal：\`$EDITOR ${path.join(changeDir, "proposal.md")}\``);
+  }
+
+  if (design.state === "ok" && (design.wsTodo > 0 || design.placeholders > 0)) {
+    pushAction(`(可选) 完善 design：\`$EDITOR ${path.join(changeDir, "design.md")}\``);
+  }
+
+  if (tasks.state !== "ok" || tasks.wsTodo > 0 || tasks.placeholders > 0) {
+    pushAction(`完善 tasks：\`$EDITOR ${path.join(changeDir, "tasks.md")}\``);
+  }
+
+  if (proposal.state === "ok") {
+    const reqId = deps.extractId("Req_ID", proposal.text);
+    const probId = deps.extractId("Problem_ID", proposal.text);
+    if (!(reqId || probId)) {
+      pushAction("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
+    }
+
+    const contractRow = deps.extractId("Contract_Row", proposal.text) || deps.extractId("Contract_Row(s)", proposal.text);
+    if (!contractRow) pushAction("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
+
+    const planFile = deps.extractId("Plan_File", proposal.text) || deps.extractId("Plan file", proposal.text);
+    const planFiles = deps.splitDeclaredValues(planFile);
+    if (planFiles.length !== 1) {
+      pushAction("补齐绑定：proposal.md `Plan_File` 必须且只能包含 1 个 plan 路径（严格校验需要）");
+    } else {
+      const planRel = String(planFiles[0] || "").replace(/^\.\//, "");
+      if (path.isAbsolute(planRel)) {
+        pushAction("修正绑定：proposal.md `Plan_File` 必须是工作区相对路径（不要绝对路径）");
+      } else if (!(await deps.pathExists(path.join(gitRoot, planRel)))) {
+        pushAction(`补齐计划文件：缺少 ${planRel}（或修正 proposal.md 的 Plan_File）`);
+      }
+    }
+
+    const evidenceDecl = deps.extractId("Evidence_Path", proposal.text) || deps.extractId("Evidence_Path(s)", proposal.text);
+    const evidencePaths = deps.splitDeclaredValues(evidenceDecl);
+    if (evidencePaths.length === 0) {
+      pushAction("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
+    } else {
+      const evidence = await deps.analyzeEvidencePaths(gitRoot, changeId, evidencePaths);
+      if (evidence.counts.persistent === 0) {
+        pushAction("交付前建议生成持久证据：`changes/<id>/evidence/...`（并把路径回填到 Evidence_Path；`.agentdocs/tmp/...` 可作为原始证据引用）");
+      }
+      if (evidence.missing.length > 0) {
+        const show = evidence.missing.slice(0, 5);
+        pushAction(`补齐缺失证据文件（missing=${evidence.missing.length}）：${show.join(", ")}${evidence.missing.length > show.length ? ", ..." : ""}`);
+      }
+    }
+  }
+
+  const prog = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
+  if (!prog.hasCheckboxes) {
+    pushAction("tasks.md 需要至少一条 checkbox 任务（`- [ ]` / `- [x]`）");
+  }
+
+  /** @type {string[]} */
+  const lines = [];
+  if (advice.actions.length > 0) {
+    lines.push(`- ${deps.planVerifyHint(changeId)}`);
+    for (const action of advice.actions) lines.push(`- ${action}`);
+    if (status.blockersStrict.length > 0) {
+      lines.push(`- 修复后复跑质量门：\`aiws change validate ${changeId} --strict\``);
+      lines.push("- 质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`");
+    } else if (status.tasks.unchecked > 0) {
+      lines.push(`- 处理完上述事项后复跑质量门：\`aiws change validate ${changeId} --strict\``);
+      lines.push("- 质量门通过后继续开发：在 AI 工具中运行 `$ws-dev`");
+    } else {
+      for (const recommendation of advice.recommended) lines.push(`- ${recommendation}`);
+    }
+    return lines.join("\n") + "\n";
+  }
+
+  lines.push(`- ${deps.planVerifyHint(changeId)}`);
+  if (prog.unchecked > 0) {
+    lines.push("- 若仍需继续编码，先通过质量门，再在 AI 工具中运行 `$ws-dev`");
+  } else {
+    for (const recommendation of advice.recommended) lines.push(`- ${recommendation}`);
+  }
+  lines.push("- 审计与证据（推荐）：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
+  lines.push(`- 归档：\`aiws change archive ${changeId}\``);
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * @param {string} text
+ */
+function checkboxStats(text) {
+  const total = (text.match(/^- \[[ xX]\]/gm) || []).length;
+  const done = (text.match(/^- \[[xX]\]/gm) || []).length;
+  const unchecked = (text.match(/^- \[ \]/gm) || []).length;
+  return { total, done, unchecked, hasCheckboxes: total > 0 };
+}