patchwarden 0.6.4 → 1.5.0

package/src/goal/goalStore.ts

@@ -0,0 +1,306 @@
+/**
+ * v0.8.0: Goal Session 目录 CRUD — 在 workspaceRoot 下管理 .patchwarden/goals/ 目录。
+ *
+ * 目录结构：
+ *   {workspaceRoot}/.patchwarden/goals/{goal_id}/
+ *     ├── GOAL.md              人类可读的 goal 描述
+ *     ├── GOALS.md             子目标列表（人类可读）
+ *     ├── goal_status.json     机器可读的状态文件（原子写）
+ *     ├── tasks/               任务产物
+ *     └── artifacts/           其他产物
+ *
+ * 所有文件系统函数都接受可选的 workspaceRoot 参数用于测试；
+ * 默认从 getConfig().workspaceRoot 读取。
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+  statSync,
+} from "node:fs";
+import { join } from "node:path";
+import { getConfig } from "../config.js";
+import { guardWorkspacePath } from "../security/pathGuard.js";
+import { PatchWardenError } from "../errors.js";
+import {
+  type GoalStatus,
+  type Subgoal,
+  createInitialGoalStatus,
+} from "./goalStatus.js";
+
+// ── 辅助：解析 workspaceRoot ──────────────────────────────────────
+
+function resolveWorkspaceRoot(workspaceRoot?: string): string {
+  return workspaceRoot ?? getConfig().workspaceRoot;
+}
+
+// ── Goal ID 生成 ──────────────────────────────────────────────────
+
+/**
+ * 从 title 生成 slug：小写、非字母数字字符替换为 `_`、合并连续 `_`、去除首尾 `_`、截断到 30 字符。
+ * 如果 slug 为空（title 全是符号），用 `untitled` 代替。
+ */
+function titleToSlug(title: string): string {
+  const slug = title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 30);
+  return slug === "" ? "untitled" : slug;
+}
+
+/**
+ * 生成 `goal_{YYYYMMDD}_{slug}` 格式的 goal id。
+ * 冲突时追加 `_2`、`_3`... 直到唯一。
+ * 日期用本地时区（new Date()）。
+ */
+export function generateGoalId(title: string, existingIds: string[]): string {
+  const now = new Date();
+  const y = now.getFullYear();
+  const m = String(now.getMonth() + 1).padStart(2, "0");
+  const d = String(now.getDate()).padStart(2, "0");
+  const datePart = `${y}${m}${d}`;
+  const slug = titleToSlug(title);
+
+  const existing = new Set(existingIds);
+  const base = `goal_${datePart}_${slug}`;
+  if (!existing.has(base)) {
+    return base;
+  }
+
+  let counter = 2;
+  while (existing.has(`${base}_${counter}`)) {
+    counter++;
+  }
+  return `${base}_${counter}`;
+}
+
+// ── 目录路径解析 ──────────────────────────────────────────────────
+
+/**
+ * 返回 `.patchwarden/goals/` 目录路径（相对于 workspaceRoot）。
+ * 不自动创建目录。
+ */
+export function getGoalsDir(workspaceRoot?: string): string {
+  return join(resolveWorkspaceRoot(workspaceRoot), ".patchwarden", "goals");
+}
+
+/**
+ * 返回 `{getGoalsDir()}/{goalId}` 路径。
+ */
+export function getGoalDir(goalId: string, workspaceRoot?: string): string {
+  return join(getGoalsDir(workspaceRoot), goalId);
+}
+
+// ── CRUD ──────────────────────────────────────────────────────────
+
+/**
+ * 创建一个新的 Goal Session。
+ * - 用 guardWorkspacePath 校验 repoPath 在 workspaceRoot 内
+ * - 扫描现有 goal 目录获取 existingIds，调用 generateGoalId
+ * - 创建目录结构：goal_dir/、tasks/、artifacts/
+ * - 写入 GOAL.md、GOALS.md、goal_status.json
+ * 返回 { goal_id, goal_dir }。
+ */
+export function createGoal(
+  repoPath: string,
+  title: string,
+  description: string,
+  workspaceRoot?: string
+): { goal_id: string; goal_dir: string } {
+  const wsRoot = resolveWorkspaceRoot(workspaceRoot);
+  const guardedRepo = guardWorkspacePath(repoPath, wsRoot);
+
+  const goalsDir = getGoalsDir(workspaceRoot);
+  const existingIds: string[] = [];
+  if (existsSync(goalsDir)) {
+    for (const entry of readdirSync(goalsDir)) {
+      const entryPath = join(goalsDir, entry);
+      try {
+        if (statSync(entryPath).isDirectory()) {
+          existingIds.push(entry);
+        }
+      } catch {
+        // 跳过无法 stat 的条目
+      }
+    }
+  }
+
+  const goalId = generateGoalId(title, existingIds);
+  const goalDir = join(goalsDir, goalId);
+
+  // 创建目录结构
+  mkdirSync(join(goalDir, "tasks"), { recursive: true });
+  mkdirSync(join(goalDir, "artifacts"), { recursive: true });
+
+  // 写入 GOAL.md
+  const now = new Date().toISOString();
+  const goalMd = [
+    `# ${title}`,
+    "",
+    description,
+    "",
+    `- Created: ${now}`,
+    `- Repo: ${guardedRepo}`,
+    "- Status: active",
+    "",
+  ].join("\n");
+  writeFileSync(join(goalDir, "GOAL.md"), goalMd, "utf-8");
+
+  // 写入 GOALS.md
+  const goalsMd = `# Subgoals: ${title}\n\n_No subgoals yet._\n`;
+  writeFileSync(join(goalDir, "GOALS.md"), goalsMd, "utf-8");
+
+  // 写入 goal_status.json
+  const status = createInitialGoalStatus(goalId, title, guardedRepo);
+  writeFileSync(
+    join(goalDir, "goal_status.json"),
+    JSON.stringify(status, null, 2) + "\n",
+    "utf-8"
+  );
+
+  return { goal_id: goalId, goal_dir: goalDir };
+}
+
+/**
+ * 列出所有 goal 的摘要信息，按 updated_at 降序排列。
+ * 无法解析的目录会被跳过。
+ */
+export function listGoals(
+  workspaceRoot?: string
+): Array<{
+  goal_id: string;
+  title: string;
+  status: string;
+  subgoal_total: number;
+  subgoal_accepted: number;
+  subgoal_running: number;
+  updated_at: string;
+}> {
+  const goalsDir = getGoalsDir(workspaceRoot);
+  if (!existsSync(goalsDir)) {
+    return [];
+  }
+
+  const results: Array<{
+    goal_id: string;
+    title: string;
+    status: string;
+    subgoal_total: number;
+    subgoal_accepted: number;
+    subgoal_running: number;
+    updated_at: string;
+  }> = [];
+
+  for (const entry of readdirSync(goalsDir)) {
+    const entryPath = join(goalsDir, entry);
+    try {
+      if (!statSync(entryPath).isDirectory()) {
+        continue;
+      }
+      const status = readGoalStatus(entry, workspaceRoot);
+      results.push({
+        goal_id: status.goal_id,
+        title: status.title,
+        status: status.status,
+        subgoal_total: status.subgoals.length,
+        subgoal_accepted: status.subgoals.filter((s) => s.status === "accepted").length,
+        subgoal_running: status.subgoals.filter((s) => s.status === "running").length,
+        updated_at: status.updated_at,
+      });
+    } catch {
+      // 跳过无法解析的目录
+    }
+  }
+
+  results.sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
+  return results;
+}
+
+/**
+ * 读取 goal 的完整详情：goal_status.json + GOAL.md 内容。
+ * 如果 goal 目录不存在或 goal_status.json 不存在，抛出 PatchWardenError("goal_not_found")。
+ */
+export function readGoal(
+  goalId: string,
+  workspaceRoot?: string
+): {
+  goal_id: string;
+  title: string;
+  status: string;
+  repo_path: string;
+  created_at: string;
+  updated_at: string;
+  goal_description: string;
+  subgoals: Subgoal[];
+} {
+  const goalDir = getGoalDir(goalId, workspaceRoot);
+  if (!existsSync(goalDir)) {
+    throw new PatchWardenError(
+      "goal_not_found",
+      `Goal directory not found: "${goalDir}"`,
+      "Ensure the goal id exists before reading.",
+      true,
+      { goal_id: goalId, goal_dir: goalDir }
+    );
+  }
+
+  const status = readGoalStatus(goalId, workspaceRoot);
+
+  let goalDescription = "";
+  const goalMdPath = join(goalDir, "GOAL.md");
+  if (existsSync(goalMdPath)) {
+    goalDescription = readFileSync(goalMdPath, "utf-8");
+  }
+
+  return {
+    goal_id: status.goal_id,
+    title: status.title,
+    status: status.status,
+    repo_path: status.repo_path,
+    created_at: status.created_at,
+    updated_at: status.updated_at,
+    goal_description: goalDescription,
+    subgoals: status.subgoals,
+  };
+}
+
+/**
+ * 原子写入 goal_status.json：先写到 .tmp 文件，再 renameSync。
+ * JSON 序列化用 JSON.stringify(status, null, 2) + 末尾换行。
+ */
+export function writeGoalStatus(
+  goalId: string,
+  status: GoalStatus,
+  workspaceRoot?: string
+): void {
+  const goalDir = getGoalDir(goalId, workspaceRoot);
+  const finalPath = join(goalDir, "goal_status.json");
+  const tmpPath = join(goalDir, "goal_status.json.tmp");
+  writeFileSync(tmpPath, JSON.stringify(status, null, 2) + "\n", "utf-8");
+  renameSync(tmpPath, finalPath);
+}
+
+/**
+ * 读取 goal_status.json 并 JSON.parse。
+ * 如果文件不存在，抛出 PatchWardenError("goal_not_found")。
+ */
+export function readGoalStatus(goalId: string, workspaceRoot?: string): GoalStatus {
+  const goalDir = getGoalDir(goalId, workspaceRoot);
+  const statusPath = join(goalDir, "goal_status.json");
+  if (!existsSync(statusPath)) {
+    throw new PatchWardenError(
+      "goal_not_found",
+      `goal_status.json not found for goal "${goalId}" at "${statusPath}"`,
+      "Ensure the goal has been created via createGoal before reading its status.",
+      true,
+      { goal_id: goalId, status_path: statusPath }
+    );
+  }
+  const raw = readFileSync(statusPath, "utf-8");
+  return JSON.parse(raw) as GoalStatus;
+}

package/src/goal/handoffExport.ts

@@ -0,0 +1,211 @@
+/**
+ * v0.8.0: Goal Session 交接文档生成 — 将当前 goal 状态渲染为 Markdown 交接报告。
+ *
+ * generateHandoff 生成 Markdown 字符串；exportHandoff 将其落盘到
+ * {workspaceRoot}/.patchwarden/goals/{goalId}/handoff.md。
+ * exportHandoff 接受调用方传入的 goalStatus，不自行读取 goal_status.json，
+ * 以避免与 goalStore 形成循环依赖。
+ */
+
+import type { GoalStatus } from "./goalStatus.js";
+import { suggestNextSubgoal } from "./goalGraph.js";
+import { getConfig } from "../config.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+// ── Markdown 生成 ────────────────────────────────────────────────
+
+/**
+ * 生成 Goal Session 交接文档（Markdown 字符串）。
+ *
+ * 包含章节：当前 Goal、版本目标、已完成/未完成/已拒绝子目标、最近 diff 摘要、
+ * 最近测试结果、当前阻塞点、下一步建议、风险提醒、接手说明。
+ *
+ * @param goalId          Goal 标识（用于接手说明中的引用）
+ * @param goalStatus      当前 GoalStatus 快照
+ * @param recentDiff      最近一次 git diff 摘要（可选）
+ * @param recentTestResult 最近一次测试结果（可选）
+ * @returns Markdown 格式的交接文档
+ */
+export function generateHandoff(
+  goalId: string,
+  goalStatus: GoalStatus,
+  recentDiff?: string,
+  recentTestResult?: string
+): string {
+  const lines: string[] = [];
+  const now = new Date().toISOString();
+
+  lines.push("# Goal Session Handoff");
+  lines.push("");
+  lines.push("Generated: " + now);
+  lines.push("");
+
+  // ── 当前 Goal ───────────────────────────────────────────
+  lines.push("## 当前 Goal");
+  lines.push("");
+  lines.push("- **goal_id**: " + goalStatus.goal_id);
+  lines.push("- **title**: " + goalStatus.title);
+  lines.push("- **status**: " + goalStatus.status);
+  lines.push("- **repo_path**: " + goalStatus.repo_path);
+  lines.push("");
+
+  // ── 版本目标 ────────────────────────────────────────────
+  lines.push("## 版本目标");
+  lines.push("");
+  lines.push(goalStatus.title);
+  lines.push("");
+
+  // ── 已完成子目标 ────────────────────────────────────────
+  lines.push("## 已完成子目标");
+  lines.push("");
+  const accepted = goalStatus.subgoals.filter((s) => s.status === "accepted");
+  if (accepted.length === 0) {
+    lines.push("无");
+  } else {
+    for (const s of accepted) {
+      lines.push("- **" + s.id + "**: " + s.title + " (accepted_at: " + (s.accepted_at ?? "N/A") + ")");
+    }
+  }
+  lines.push("");
+
+  // ── 未完成子目标 ────────────────────────────────────────
+  lines.push("## 未完成子目标");
+  lines.push("");
+  const incomplete = goalStatus.subgoals.filter(
+    (s) => s.status !== "accepted" && s.status !== "rejected"
+  );
+  if (incomplete.length === 0) {
+    lines.push("无");
+  } else {
+    for (const s of incomplete) {
+      const deps = s.depends_on.length > 0 ? s.depends_on.join(", ") : "无";
+      lines.push("- **" + s.id + "**: " + s.title + " (status: " + s.status + ", depends_on: " + deps + ")");
+    }
+  }
+  lines.push("");
+
+  // ── 已拒绝子目标 ────────────────────────────────────────
+  lines.push("## 已拒绝子目标");
+  lines.push("");
+  const rejected = goalStatus.subgoals.filter((s) => s.status === "rejected");
+  if (rejected.length === 0) {
+    lines.push("无");
+  } else {
+    for (const s of rejected) {
+      lines.push("- **" + s.id + "**: " + s.title + " (rejected_reason: " + (s.rejected_reason ?? "N/A") + ")");
+    }
+  }
+  lines.push("");
+
+  // ── 最近一次 diff 摘要 ──────────────────────────────────
+  lines.push("## 最近一次 diff 摘要");
+  lines.push("");
+  if (recentDiff) {
+    lines.push(recentDiff);
+  } else {
+    lines.push("暂无");
+  }
+  lines.push("");
+
+  // ── 最近一次测试结果 ────────────────────────────────────
+  lines.push("## 最近一次测试结果");
+  lines.push("");
+  if (recentTestResult) {
+    lines.push(recentTestResult);
+  } else {
+    lines.push("暂无");
+  }
+  lines.push("");
+
+  // ── 当前阻塞点 ─────────────────────────────────────────
+  lines.push("## 当前阻塞点");
+  lines.push("");
+  const needsFix = goalStatus.subgoals.filter((s) => s.status === "needs_fix");
+  if (needsFix.length === 0) {
+    lines.push("无");
+  } else {
+    for (const s of needsFix) {
+      lines.push("- **" + s.id + "**: " + s.title);
+    }
+  }
+  lines.push("");
+
+  // ── 下一步建议 ─────────────────────────────────────────
+  lines.push("## 下一步建议");
+  lines.push("");
+  const suggestion = suggestNextSubgoal(goalStatus);
+  if (suggestion.subgoal_id) {
+    lines.push("建议执行子目标 **" + suggestion.subgoal_id + "**：" + (suggestion.title ?? ""));
+  } else if (suggestion.reason === "dependencies_not_met") {
+    lines.push("当前存在被阻塞的子目标，建议先处理以下依赖：");
+    const blockedList = suggestion.blocked_by ?? [];
+    for (const id of blockedList) {
+      lines.push("- " + id);
+    }
+  } else {
+    lines.push("当前无可执行的 ready 子目标，建议检查所有子目标状态或等待任务完成。");
+  }
+  lines.push("");
+
+  // ── 风险提醒 ───────────────────────────────────────────
+  lines.push("## 风险提醒");
+  lines.push("");
+  const risks = goalStatus.subgoals.filter(
+    (s) => s.status === "needs_fix" || s.status === "running"
+  );
+  if (risks.length === 0) {
+    lines.push("无");
+  } else {
+    for (const s of risks) {
+      if (s.status === "needs_fix") {
+        lines.push("- **" + s.id + "**: " + s.title + " (needs_fix — 需要修复)");
+      } else {
+        lines.push("- **" + s.id + "**: " + s.title + " (running — 长期运行中)");
+      }
+    }
+  }
+  lines.push("");
+
+  // ── 接手说明 ───────────────────────────────────────────
+  lines.push("## 接手说明");
+  lines.push("");
+  lines.push(
+    "新会话接手时，请先调用 read_goal 查看 " + goalId + " 的完整状态，然后调用 suggest_next_subgoal 获取下一个可执行子目标。"
+  );
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ── 落盘导出 ─────────────────────────────────────────────────────
+
+/**
+ * 生成交接文档并写入 {workspaceRoot}/.patchwarden/goals/{goalId}/handoff.md。
+ *
+ * @param goalId        Goal 标识
+ * @param goalStatus    当前 GoalStatus 快照（由调用方读取后传入）
+ * @param workspaceRoot 工作区根目录（可选，默认从 getConfig().workspaceRoot 获取）
+ * @returns handoff_path（绝对路径）和 content_preview（前 500 字符，超出则追加 "..."）
+ */
+export function exportHandoff(
+  goalId: string,
+  goalStatus: GoalStatus,
+  workspaceRoot?: string
+): { handoff_path: string; content_preview: string } {
+  const content = generateHandoff(goalId, goalStatus);
+
+  const root = workspaceRoot ?? getConfig().workspaceRoot;
+  const goalDir = resolve(root, ".patchwarden", "goals", goalId);
+  mkdirSync(goalDir, { recursive: true });
+
+  const handoffPath = join(goalDir, "handoff.md");
+  writeFileSync(handoffPath, content, "utf-8");
+
+  const preview = content.length > 500 ? content.slice(0, 500) + "..." : content;
+
+  return {
+    handoff_path: handoffPath,
+    content_preview: preview,
+  };
+}

package/src/goal/subgoalSync.ts

@@ -0,0 +1,82 @@
+/**
+ * v0.8.0: Subgoal 状态同步 — 当任务状态变为 done_by_agent 时回写关联 subgoal 状态。
+ *
+ * 设计原则：
+ *   - 向后兼容：无 goal_id/subgoal_id 关联的任务直接返回，不影响现有流程。
+ *   - 错误隔离：subgoal 同步失败只记录到 stderr，不阻断任务完成主流程。
+ *   - 仅同步 running → done_by_agent 转换；其他状态由 audit_task / 显式 API 处理。
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { readGoalStatus, writeGoalStatus } from "./goalStore.js";
+import { updateSubgoalStatus } from "./goalStatus.js";
+
+// ── 同步函数 ──────────────────────────────────────────────────────
+
+/**
+ * v0.8.0: 当任务状态变为 done_by_agent 时，同步更新关联的 subgoal 状态。
+ *
+ * 行为：
+ *   - 如果 taskMeta.subgoal_id 或 goal_id 为 null/undefined，直接返回（向后兼容）。
+ *   - 读取 goal_status.json，找到对应 subgoal。
+ *   - 仅当 subgoal 当前状态为 "running" 时，更新为 "done_by_agent"。
+ *   - 其他状态（ready/accepted/rejected/needs_fix/done_by_agent）保持不变。
+ *   - 所有操作用 try/catch 包裹，失败时只记录到 stderr 不阻断主流程。
+ *
+ * @param taskId 任务 id（仅用于日志）
+ * @param taskMeta 任务的 goal 关联元信息（goal_id / subgoal_id）
+ * @param workspaceRoot 可选的工作区根目录（测试用），默认从 getConfig() 读取
+ */
+export function syncSubgoalOnTaskDone(
+  taskId: string,
+  taskMeta: { goal_id?: string | null; subgoal_id?: string | null },
+  workspaceRoot?: string
+): void {
+  const goalId = taskMeta.goal_id;
+  const subgoalId = taskMeta.subgoal_id;
+  if (!goalId || !subgoalId) return;
+
+  try {
+    const goalStatus = readGoalStatus(goalId, workspaceRoot);
+    const subgoal = goalStatus.subgoals.find((s) => s.id === subgoalId);
+    if (!subgoal) return;
+    if (subgoal.status !== "running") return;
+
+    const updated = updateSubgoalStatus(goalStatus, subgoalId, "done_by_agent");
+    writeGoalStatus(goalId, updated, workspaceRoot);
+  } catch (err) {
+    // subgoal 同步失败不应影响任务完成流程，只记录到 stderr
+    console.error(
+      `[goal] syncSubgoalOnTaskDone failed for task ${taskId}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+// ── Task 元信息读取 ───────────────────────────────────────────────
+
+/**
+ * v0.8.0: 从 task 的 status.json 读取 goal_id/subgoal_id 关联信息。
+ *
+ * 行为：
+ *   - 读取 {taskDir}/status.json，解析其中的 goal_id / subgoal_id 字段。
+ *   - 任何错误（文件不存在、JSON 解析失败等）都返回 { goal_id: null, subgoal_id: null }，
+ *     不抛错，保证调用方流程不受影响。
+ *
+ * @param taskDir 任务目录路径（包含 status.json）
+ */
+export function readTaskGoalMeta(
+  taskDir: string
+): { goal_id: string | null; subgoal_id: string | null } {
+  try {
+    const statusFile = join(taskDir, "status.json");
+    const raw = readFileSync(statusFile, "utf-8");
+    const data = JSON.parse(raw) as Record<string, unknown>;
+    return {
+      goal_id: typeof data.goal_id === "string" ? data.goal_id : null,
+      subgoal_id: typeof data.subgoal_id === "string" ? data.subgoal_id : null,
+    };
+  } catch {
+    return { goal_id: null, subgoal_id: null };
+  }
+}