patchwarden 1.5.0 → 1.6.1

package/src/tools/dispatch/goalDispatch.ts

@@ -0,0 +1,128 @@
+/**
+ * Dispatch handlers for Goal Session tools (v0.8.0+).
+ *
+ * Covers goal lifecycle, subgoal management, Spec Kit import,
+ * worktree merge/discard, and goal reporting.
+ */
+
+import { createGoal, listGoals, readGoal, readGoalStatus } from "../../goal/goalStore.js";
+import { suggestNextSubgoal } from "../../goal/goalGraph.js";
+import { exportHandoff } from "../../goal/handoffExport.js";
+import { acceptSubgoal, rejectSubgoal, summarizeGoalProgress } from "../../goal/goalProgress.js";
+import { exportGoalReport } from "../../goal/goalReport.js";
+import { importSpecKitTasks, parseSpecKitJson } from "../../goal/specKitImport.js";
+import { createSubgoalTask } from "../goals/goalSubgoalTask.js";
+import { mergeWorktreeTool } from "../workspace/mergeWorktree.js";
+import { discardWorktreeTool } from "../workspace/discardWorktree.js";
+import type { ToolHandlerMap } from "./types.js";
+import { toResult } from "./types.js";
+import { parseOptionalTaskTemplate } from "./validation.js";
+
+export const goalHandlers: ToolHandlerMap = {
+  create_goal: async (args) => {
+    return toResult(
+      createGoal(
+        String(args?.repo_path ?? ""),
+        String(args?.title ?? ""),
+        String(args?.goal_description ?? ""),
+      ),
+    );
+  },
+
+  list_goals: async () => {
+    return toResult({ goals: listGoals() });
+  },
+
+  read_goal: async (args) => {
+    return toResult(readGoal(String(args?.goal_id ?? "")));
+  },
+
+  create_subgoal_task: async (args) => {
+    return toResult(
+      await createSubgoalTask({
+        goal_id: String(args?.goal_id ?? ""),
+        subgoal_title: String(args?.subgoal_title ?? ""),
+        depends_on: Array.isArray(args?.depends_on) ? args.depends_on.map(String) : undefined,
+        plan_id: args?.plan_id ? String(args.plan_id) : undefined,
+        inline_plan: args?.inline_plan ? String(args.inline_plan) : undefined,
+        plan_title: args?.plan_title ? String(args.plan_title) : undefined,
+        template: parseOptionalTaskTemplate(args?.template),
+        goal: args?.goal ? String(args.goal) : undefined,
+        agent: args?.agent ? String(args.agent) : undefined,
+        repo_path: String(args?.repo_path ?? ""),
+        test_command: args?.test_command ? String(args.test_command) : undefined,
+        verify_commands: Array.isArray(args?.verify_commands)
+          ? args.verify_commands.map(String)
+          : undefined,
+        timeout_seconds: args?.timeout_seconds ? Number(args.timeout_seconds) : undefined,
+        scope: Array.isArray(args?.scope) ? args.scope.map(String) : undefined,
+        forbidden: Array.isArray(args?.forbidden) ? args.forbidden.map(String) : undefined,
+        verification: Array.isArray(args?.verification) ? args.verification.map(String) : undefined,
+        done_evidence: Array.isArray(args?.done_evidence) ? args.done_evidence.map(String) : undefined,
+        isolate_worktree:
+          args?.isolate_worktree === undefined ? undefined : Boolean(args.isolate_worktree),
+      }),
+    );
+  },
+
+  accept_subgoal: async (args) => {
+    return toResult(
+      acceptSubgoal(String(args?.goal_id ?? ""), String(args?.subgoal_id ?? "")),
+    );
+  },
+
+  reject_subgoal: async (args) => {
+    return toResult(
+      rejectSubgoal(
+        String(args?.goal_id ?? ""),
+        String(args?.subgoal_id ?? ""),
+        String(args?.reason ?? ""),
+      ),
+    );
+  },
+
+  suggest_next_subgoal: async (args) => {
+    const goalStatus = readGoalStatus(String(args?.goal_id ?? ""));
+    return toResult(suggestNextSubgoal(goalStatus));
+  },
+
+  summarize_goal_progress: async (args) => {
+    return toResult(summarizeGoalProgress(String(args?.goal_id ?? "")));
+  },
+
+  export_handoff: async (args) => {
+    const goalId = String(args?.goal_id ?? "");
+    const goalStatus = readGoalStatus(goalId);
+    return toResult(exportHandoff(goalId, goalStatus));
+  },
+
+  export_goal_report: async (args) => {
+    const goalId = String(args?.goal_id ?? "");
+    return toResult(exportGoalReport(goalId));
+  },
+
+  import_speckit_tasks: async (args) => {
+    const goalId = String(args?.goal_id ?? "");
+    const jsonText = String(args?.spec_kit_json ?? "");
+    const input = parseSpecKitJson(jsonText);
+    return toResult(importSpecKitTasks(goalId, input));
+  },
+
+  merge_worktree: async (args) => {
+    return toResult(
+      mergeWorktreeTool({
+        worktree_id: String(args?.worktree_id ?? ""),
+        repo_path: String(args?.repo_path ?? ""),
+      }),
+    );
+  },
+
+  discard_worktree: async (args) => {
+    return toResult(
+      discardWorktreeTool({
+        worktree_id: String(args?.worktree_id ?? ""),
+        repo_path: String(args?.repo_path ?? ""),
+      }),
+    );
+  },
+};

package/src/tools/dispatch/releaseDispatch.ts

@@ -0,0 +1,66 @@
+/**
+ * Dispatch handlers for release-mode tools (v1.3.0+).
+ *
+ * Wraps releaseCheck, releasePrepare, releaseVerify, and releaseCleanup
+ * from releaseMode.ts.
+ */
+
+import {
+  releaseCheck,
+  releasePrepare,
+  releaseVerify,
+  releaseCleanup,
+} from "../release/releaseMode.js";
+import type { ToolHandlerMap } from "./types.js";
+import { toResult } from "./types.js";
+import { parseReleaseStage } from "./validation.js";
+
+export const releaseHandlers: ToolHandlerMap = {
+  release_check: async (args) => {
+    return toResult(
+      await releaseCheck({
+        repo_path: String(args?.repo_path ?? ""),
+        target_stage: parseReleaseStage(args?.target_stage),
+        package_name: args?.package_name ? String(args.package_name) : undefined,
+        version: args?.version ? String(args.version) : undefined,
+        github_repo: args?.github_repo ? String(args.github_repo) : undefined,
+        branch: args?.branch ? String(args.branch) : undefined,
+      }),
+    );
+  },
+
+  release_prepare: async (args) => {
+    return toResult(
+      releasePrepare({
+        repo_path: String(args?.repo_path ?? ""),
+        required_commands: Array.isArray(args?.required_commands)
+          ? args.required_commands.map(String)
+          : undefined,
+        timeout_seconds:
+          args?.timeout_seconds !== undefined ? Number(args.timeout_seconds) : undefined,
+      }),
+    );
+  },
+
+  release_verify: async (args) => {
+    return toResult(
+      await releaseVerify({
+        repo_path: String(args?.repo_path ?? ""),
+        package_name: args?.package_name ? String(args.package_name) : undefined,
+        version: args?.version ? String(args.version) : undefined,
+        github_repo: args?.github_repo ? String(args.github_repo) : undefined,
+        branch: args?.branch ? String(args.branch) : undefined,
+      }),
+    );
+  },
+
+  release_cleanup: async (args) => {
+    return toResult(
+      releaseCleanup({
+        repo_path: String(args?.repo_path ?? ""),
+        dry_run: args?.dry_run !== undefined ? Boolean(args.dry_run) : undefined,
+        patterns: Array.isArray(args?.patterns) ? args.patterns.map(String) : undefined,
+      }),
+    );
+  },
+};

package/src/tools/dispatch/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared types and helpers for the dispatch map.
+ *
+ * Each domain dispatch file exports a `ToolHandlerMap` whose handlers
+ * directly call the existing tool functions — no logic is rewritten.
+ */
+
+export type ToolHandler = (
+  args: Record<string, unknown> | undefined,
+) => Promise<{ content: Array<{ type: string; text: string }> }>;
+
+export type ToolHandlerMap = Record<string, ToolHandler>;
+
+/**
+ * Wrap a plain data value into the MCP CallToolResult content envelope.
+ * Mirrors the original `toResult` helper from registry.ts.
+ */
+export function toResult(data: unknown): {
+  content: Array<{ type: string; text: string }>;
+} {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+  };
+}

package/src/tools/dispatch/validation.ts

@@ -0,0 +1,78 @@
+import type { PatchOperation, PatchOperationType } from "../../direct/directPatch.js";
+import type { ReleaseStage } from "../../release/releaseGate.js";
+import { TASK_TEMPLATE_NAMES, type TaskTemplateName } from "../taskTemplates.js";
+
+const RELEASE_STAGES: ReadonlySet<ReleaseStage> = new Set([
+  "local_ready",
+  "packed_ready",
+  "published_verified",
+  "github_release_verified",
+  "ci_verified",
+]);
+const PATCH_OPERATION_TYPES: ReadonlySet<PatchOperationType> = new Set([
+  "replace_exact",
+  "insert_before",
+  "insert_after",
+  "replace_whole_file",
+]);
+const PATCH_OCCURRENCES = new Set(["first", "all", "exactly_once"]);
+const TASK_LOG_FILES = new Set(["stdout", "stderr", "test", "verify"]);
+
+export function parseOptionalTaskTemplate(value: unknown): TaskTemplateName | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value !== "string" || !TASK_TEMPLATE_NAMES.includes(value as TaskTemplateName)) {
+    throw new Error(`template must be one of: ${TASK_TEMPLATE_NAMES.join(", ")}`);
+  }
+  return value as TaskTemplateName;
+}
+
+export function parseReleaseStage(value: unknown): ReleaseStage {
+  const stage = value === undefined || value === null || value === ""
+    ? "local_ready"
+    : String(value);
+  if (!RELEASE_STAGES.has(stage as ReleaseStage)) {
+    throw new Error(`target_stage must be one of: ${[...RELEASE_STAGES].join(", ")}`);
+  }
+  return stage as ReleaseStage;
+}
+
+export function parseTaskLogFile(value: unknown): "stdout" | "stderr" | "test" | "verify" {
+  const file = value === undefined || value === null || value === "" ? "stdout" : String(value);
+  if (!TASK_LOG_FILES.has(file)) {
+    throw new Error(`file must be one of: ${[...TASK_LOG_FILES].join(", ")}`);
+  }
+  return file as "stdout" | "stderr" | "test" | "verify";
+}
+
+export function parsePatchOperations(value: unknown): PatchOperation[] {
+  if (!Array.isArray(value)) throw new Error("operations must be an array");
+  return value.map((entry, index) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new Error(`operations[${index}] must be an object`);
+    }
+    const record = entry as Record<string, unknown>;
+    if (typeof record.type !== "string" || !PATCH_OPERATION_TYPES.has(record.type as PatchOperationType)) {
+      throw new Error(`operations[${index}].type is invalid`);
+    }
+    if (typeof record.new_text !== "string") {
+      throw new Error(`operations[${index}].new_text must be a string`);
+    }
+    if (record.old_text !== undefined && typeof record.old_text !== "string") {
+      throw new Error(`operations[${index}].old_text must be a string`);
+    }
+    if (
+      record.occurrence !== undefined
+      && (typeof record.occurrence !== "string" || !PATCH_OCCURRENCES.has(record.occurrence))
+    ) {
+      throw new Error(`operations[${index}].occurrence is invalid`);
+    }
+    return {
+      type: record.type as PatchOperationType,
+      new_text: record.new_text,
+      ...(record.old_text === undefined ? {} : { old_text: record.old_text }),
+      ...(record.occurrence === undefined
+        ? {}
+        : { occurrence: record.occurrence as PatchOperation["occurrence"] }),
+    };
+  });
+}

package/src/tools/{getPlan.ts → goals/getPlan.ts}

@@ -1,9 +1,9 @@
 import { readFileSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
-import { getPlansDir, getConfig } from "../config.js";
-import { guardReadPath } from "../security/pathGuard.js";
-import { guardSensitivePath } from "../security/sensitiveGuard.js";
-import { redactSensitiveContent } from "../security/contentRedaction.js";
+import { getPlansDir, getConfig } from "../../config.js";
+import { guardReadPath } from "../../security/pathGuard.js";
+import { guardSensitivePath } from "../../security/sensitiveGuard.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
 
 export interface GetPlanInput {
   plan_id: string;

package/src/tools/{goalSubgoalTask.ts → goals/goalSubgoalTask.ts}

@@ -14,12 +14,14 @@
  *   - createTask 内部使用 getConfig()，因此 workspaceRoot 由全局配置决定。
  */
 
-import { readGoalStatus, writeGoalStatus } from "../goal/goalStore.js";
-import { addSubgoal, linkTaskToSubgoal, updateSubgoalStatus, type Subgoal } from "../goal/goalStatus.js";
-import { createTask, type CreateTaskInput } from "./createTask.js";
-import { createWorktree, discardWorktree } from "../goal/worktreeManager.js";
-import { getConfig } from "../config.js";
-import { PatchWardenError } from "../errors.js";
+import { mutateGoalStatusAsync } from "../../goal/goalStore.js";
+import { addSubgoal, linkTaskToSubgoal, updateSubgoalStatus, type Subgoal } from "../../goal/goalStatus.js";
+import { createTask, type CreateTaskInput } from "../tasks/createTask.js";
+import { createWorktree, discardWorktree } from "../../goal/worktreeManager.js";
+import { getConfig } from "../../config.js";
+import { PatchWardenError } from "../../errors.js";
+import { guardWorkspacePath } from "../../security/pathGuard.js";
+import { resolve } from "node:path";
 
 // ── 类型定义 ──────────────────────────────────────────────────────
 
@@ -64,7 +66,7 @@ export interface CreateSubgoalTaskOutput {
  * @throws PatchWardenError("invalid_dependency") 当 depends_on 引用不存在的 subgoal
  * @throws PatchWardenError("invalid_execution_mode") 当 execution_mode 为 "assess_only"
  */
-export function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalTaskOutput {
+export async function createSubgoalTask(input: CreateSubgoalTaskInput): Promise<CreateSubgoalTaskOutput> {
   // assess_only 不产生 task，无法关联到 subgoal
   if (input.execution_mode === "assess_only") {
     throw new PatchWardenError(
@@ -76,17 +78,30 @@ export function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalT
     );
   }
 
-  // 1. 读取 goal_status.json，如果不存在抛 goal_not_found
-  let goalStatus;
-  try {
-    goalStatus = readGoalStatus(input.goal_id);
-  } catch {
+  const config = getConfig();
+  return mutateGoalStatusAsync(input.goal_id, async (goalStatus) => {
+  if (goalStatus.status !== "active") {
+    throw new PatchWardenError(
+      "goal_not_active",
+      `Goal "${input.goal_id}" is ${goalStatus.status} and cannot accept new subgoals.`,
+      "Create a new Goal Session for additional work.",
+      true,
+      { goal_id: input.goal_id, status: goalStatus.status },
+    );
+  }
+
+  const goalRepoPath = guardWorkspacePath(goalStatus.repo_path, config.workspaceRoot);
+  const requestedRepoPath = guardWorkspacePath(input.repo_path, config.workspaceRoot);
+  const sameRepo = process.platform === "win32"
+    ? resolve(goalRepoPath).toLowerCase() === resolve(requestedRepoPath).toLowerCase()
+    : resolve(goalRepoPath) === resolve(requestedRepoPath);
+  if (!sameRepo) {
     throw new PatchWardenError(
-      "goal_not_found",
-      `Goal "${input.goal_id}" not found`,
-      "Call list_goals to see available goals.",
+      "goal_repo_mismatch",
+      `Subgoal repo_path does not match Goal "${input.goal_id}".`,
+      "Use the repo_path recorded on the Goal Session.",
       true,
-      { goal_id: input.goal_id }
+      { goal_id: input.goal_id },
     );
   }
 
@@ -101,11 +116,10 @@ export function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalT
   //     用 worktree 路径作为 createTask 的 repo_path，避免并发 task 互相污染。
   //     isolate_worktree === false 时退化为原行为（使用 input.repo_path）。
   const isolate = input.isolate_worktree !== false;
-  let repoPathForTask = input.repo_path;
+  let repoPathForTask = goalRepoPath;
   let worktreeId: string | null = null;
   if (isolate) {
-    const workspaceRoot = getConfig().workspaceRoot;
-    const wt = createWorktree(input.goal_id, subgoalId, workspaceRoot);
+    const wt = createWorktree(input.goal_id, subgoalId, goalRepoPath);
     repoPathForTask = wt.worktreePath;
     worktreeId = wt.worktreeId;
   }
@@ -113,7 +127,7 @@ export function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalT
   // 3. 调用 createTask 创建关联任务（强制 execute 模式，确保返回 CreateTaskOutput）
   let taskId: string;
   try {
-    const taskResult = createTask({
+    const taskResult = await createTask({
       plan_id: input.plan_id,
       inline_plan: input.inline_plan,
       plan_title: input.plan_title,
@@ -139,7 +153,7 @@ export function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalT
     // createTask 失败：清理已创建的隔离 worktree，避免遗留半成品（best effort）
     if (isolate && worktreeId) {
       try {
-        discardWorktree(worktreeId, getConfig().workspaceRoot);
+        discardWorktree(worktreeId, goalRepoPath);
       } catch { /* ignore cleanup failure，向上抛出原始 createTask 错误 */ }
     }
     throw createTaskErr;
@@ -153,18 +167,19 @@ export function createSubgoalTask(input: CreateSubgoalTaskInput): CreateSubgoalT
   if (isolate && worktreeId) {
     const newSubgoals: Subgoal[] = withRunning.subgoals.map((s) =>
       s.id === subgoalId
-        ? ({ ...s, worktree_id: worktreeId } as Subgoal)
+        ? { ...s, worktree_id: worktreeId }
         : s
     );
     withRunning = { ...withRunning, subgoals: newSubgoals };
   }
 
-  // 5. 写回 goal_status.json
-  writeGoalStatus(input.goal_id, withRunning);
-
   return {
-    subgoal_id: subgoalId,
-    task_id: taskId,
-    subgoal_status: "running",
+    next: withRunning,
+    result: {
+      subgoal_id: subgoalId,
+      task_id: taskId,
+      subgoal_status: "running" as const,
+    },
   };
+  });
 }

package/src/tools/goals/index.ts

@@ -0,0 +1,3 @@
+export * from "./getPlan.js";
+export * from "./goalSubgoalTask.js";
+export * from "./savePlan.js";

package/src/tools/{savePlan.ts → goals/savePlan.ts}

@@ -1,9 +1,15 @@
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { mkdirSync, existsSync, readFileSync, statSync } from "node:fs";
 import { resolve, join, relative } from "node:path";
-import { getPlansDir, getConfig } from "../config.js";
-import { guardPath } from "../security/pathGuard.js";
-import { guardPlanContent } from "../security/planGuard.js";
-import { PatchWardenError } from "../errors.js";
+import { randomBytes } from "node:crypto";
+import { getPlansDir, getConfig } from "../../config.js";
+import { guardPath } from "../../security/pathGuard.js";
+import { guardPlanContent } from "../../security/planGuard.js";
+import { PatchWardenError } from "../../errors.js";
+import { redactSensitiveContent } from "../../security/contentRedaction.js";
+import { atomicWriteFileSync } from "../../utils/atomicFile.js";
+
+const MAX_PLAN_BYTES = 1024 * 1024;
+const MAX_PLAN_TITLE_CHARS = 500;
 
 export interface SavePlanInput {
   title: string;
@@ -49,6 +55,14 @@ export function savePlan(input: SavePlanInput): SavePlanOutput {
         { plan_ref: input.plan_ref }
       );
     }
+    const planMetadata = statSync(targetPath);
+    if (!planMetadata.isFile() || planMetadata.size > MAX_PLAN_BYTES) {
+      throw new PatchWardenError(
+        "plan_content_too_large",
+        `plan_ref must point to a regular file no larger than ${MAX_PLAN_BYTES} bytes.`,
+        "Use a smaller plan file under .patchwarden/plans/.",
+      );
+    }
     content = readFileSync(targetPath, "utf-8");
     if (!title || title.trim() === "") {
       title = "Plan from file";
@@ -71,16 +85,32 @@ export function savePlan(input: SavePlanInput): SavePlanOutput {
 
   guardPlanContent(title, content);
 
-  const planId = `plan_${Date.now()}_${sanitizeTitle(title)}`;
+  if (Buffer.byteLength(content, "utf-8") > MAX_PLAN_BYTES) {
+    throw new PatchWardenError(
+      "plan_content_too_large",
+      `Plan content exceeds the ${MAX_PLAN_BYTES}-byte limit.`,
+      "Split the work into smaller plans.",
+    );
+  }
+  title = redactSensitiveContent(title)
+    .content
+    .replace(/[\r\n\t]+/g, " ")
+    .trim()
+    .slice(0, MAX_PLAN_TITLE_CHARS) || "Inline plan";
+  content = redactSensitiveContent(content).content;
+
+  const planId = `plan_${Date.now()}_${sanitizeTitle(title)}_${randomBytes(4).toString("hex")}`;
   const planDir = resolve(plansDir, planId);
 
   // Guards: plan dir & file must stay inside workspace
+  guardPath(plansDir, config.workspaceRoot, config.plansDir);
+  mkdirSync(plansDir, { recursive: true });
   guardPath(planDir, config.workspaceRoot, config.plansDir);
-  mkdirSync(planDir, { recursive: true });
+  mkdirSync(planDir);
 
   const planFile = join(planDir, "plan.md");
   const header = `# ${title}\n\n> Plan ID: ${planId}\n> Created: ${new Date().toISOString()}\n\n`;
-  writeFileSync(planFile, header + content, "utf-8");
+  atomicWriteFileSync(planFile, header + content);
 
   return {
     plan_id: planId,