@zhushanwen/pi-plan 0.3.15 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-plan",
-  "version": "0.3.15",
+  "version": "0.4.1",
   "description": "Lightweight plan mode for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -21,7 +21,7 @@
     "@earendil-works/pi-coding-agent": ">=0.73.0",
     "typebox": "*",
     "@earendil-works/pi-ai": "^0.84.4",
-    "@zhushanwen/pi-goal": "0.11.1"
+    "@zhushanwen/pi-goal": "0.12.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {
@@ -38,7 +38,7 @@
     "templates/"
   ],
   "dependencies": {
-    "@zhushanwen/pi-extension-logger": "0.3.1"
+    "@zhushanwen/pi-extension-logger": "0.4.1"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/command.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-import type { PlanSessionMap } from "./state.js";
+import type { PlanSessionMap, PlanState } from "./state.js";
 import { getPlanState, persistPlanState, resetPlanState } from "./state.js";
 import { updatePlanWidget } from "./widget.js";
 
@@ -88,7 +88,7 @@ async function handleAbort(
   sessions: PlanSessionMap,
   sessionId: string,
   ctx: ExtensionContext,
-  state: PlanSessionMap extends Map<string, infer V> ? V : never,
+  state: PlanState,
 ): Promise<void> {
   if (!state.isActive) {
     ctx.ui.notify("No active plan mode.", "info");
@@ -104,7 +104,7 @@ async function handleAbort(
 /** Handle /plan status subcommand */
 function handleStatus(
   ctx: ExtensionContext,
-  state: PlanSessionMap extends Map<string, infer V> ? V : never,
+  state: PlanState,
 ): void {
   if (!state.isActive) {
     ctx.ui.notify("No active plan mode.", "info");
@@ -136,7 +136,7 @@ function handleEnterPlanMode(
   sessions: PlanSessionMap,
   sessionId: string,
   ctx: ExtensionContext,
-  state: PlanSessionMap extends Map<string, infer V> ? V : never,
+  state: PlanState,
   requirement: string,
 ): void {
   const slug = requirement
@@ -157,7 +157,7 @@ function handleEnterPlanMode(
   persistPlanState(pi, state);
   updatePlanWidget(ctx, state);
 
-  // Restrict tools to read-only set during plan mode
+  // Restrict tools to the plan-mode set (includes bash — file-write constraints come from the injected plan mode prompt below)
   pi.setActiveTools(["read", "bash", "grep", "find", "ls", "plan"]);
 
   // Inject plan mode system prompt inline
@@ -183,27 +183,6 @@ function handleEnterPlanMode(
     `## Phase D: Completion\n` +
     `1. Ask user to review the complete plan.\n` +
     `2. Call plan tool (complete) with isolation method (compact/tree/direct).\n` +
-    `3. After plan complete: check subagent capability → suggest goal + wave or single-agent execution.`,
+    `3. After plan complete: the user picks an execution path (subagent-driven / goal-driven / single-agent) via the completion dialog.`,
   );
 }
-
-/**
- * Programmatic entry to start plan mode (for `pi.__planStart`).
- *
- * Mirrors the `/plan` command's enter logic. Returns false if plan mode is
- * already active (caller can then surface a message or wait).
- *
- * @returns true if plan mode started; false if already active
- */
-export function startPlanMode(
-  pi: ExtensionAPI,
-  sessions: PlanSessionMap,
-  ctx: ExtensionContext,
-  requirement: string,
-): boolean {
-  const sessionId = ctx.sessionManager.getSessionId();
-  const state = getPlanState(sessions, sessionId, ctx);
-  if (state.isActive) return false;
-  handleEnterPlanMode(pi, sessions, sessionId, ctx, state, requirement);
-  return true;
-}

package/src/index.ts

@@ -1,7 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 
-import { registerPlanCommand, startPlanMode } from "./command.js";
+import { registerPlanCommand } from "./command.js";
 import { type PlanSessionMap, reconstructPlanState } from "./state.js";
 import { registerPlanTool } from "./tool.js";
 import { updatePlanWidget } from "./widget.js";
@@ -16,13 +16,6 @@ export default function planExtension(pi: ExtensionAPI) {
   registerPlanTool(pi, sessions);
   registerPlanCommand(pi, sessions);
 
-  // External API: __planStart（allow other extensions to start plan mode programmatically, #9）
-  // 交叉类型单步断言（ExtensionAPI 可赋给 ExtensionAPI & { __planStart? }，无需 unknown 中转）
-  const api = pi as ExtensionAPI & { __planStart?: (requirement: string, ctx: ExtensionContext) => boolean };
-  api.__planStart = (requirement: string, ctx: ExtensionContext): boolean => {
-    return startPlanMode(pi, sessions, ctx, requirement);
-  };
-
   // Dynamic import compact handlers — avoids cross-group static import
   import("./compact.js").then(({ registerPlanEventHandlers }) => {
     registerPlanEventHandlers(pi, sessions);
@@ -36,7 +29,7 @@ export default function planExtension(pi: ExtensionAPI) {
     const state = reconstructPlanState(ctx);
     sessions.set(sessionId, state);
     updatePlanWidget(ctx, state);
-    // If plan mode was active, re-restrict tools to read-only set
+    // If plan mode was active, re-restrict tools to the plan-mode set (includes bash — file-write constraints come from the injected plan mode prompt)
     if (state.isActive) {
       pi.setActiveTools(["read", "bash", "grep", "find", "ls", "plan"]);
     }

package/src/tool.ts

@@ -6,7 +6,7 @@ import type { ExtensionAPI, ExtensionContext, Theme, ThemeColor } from "@earendi
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import type { PlanSessionMap } from "./state.js";
+import type { PlanSessionMap, PlanState } from "./state.js";
 import { getPlanState, persistPlanState, resetPlanState } from "./state.js";
 import { listTemplates, loadTemplate } from "./templates.js";
 import { updatePlanWidget } from "./widget.js";
@@ -171,6 +171,172 @@ function renderPlanResult(
   }
 }
 
+// ── Action executors (one per switch case) ─────────────────────────
+
+/** Execute result envelope (shared shape returned by every action). */
+interface ActionResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: PlanDetails;
+}
+
+function executeListTemplate(projectDir: string): ActionResult {
+  const templates = listTemplates(projectDir);
+  return {
+    content: [{ type: "text" as const, text: `${templates.length} templates available` }],
+    details: { action: "list-template", templates },
+  };
+}
+
+function executeSelectTemplate(
+  pi: ExtensionAPI,
+  params: Record<string, unknown>,
+  state: PlanState,
+  projectDir: string,
+): ActionResult {
+  const templateName = params.templateName as string;
+  if (!templateName) {
+    throw new Error("templateName is required for select-template");
+  }
+  const content = loadTemplate(templateName, projectDir);
+  if (!content) {
+    throw new Error(`Template not found: ${templateName}`);
+  }
+  state.templateName = templateName;
+  state.phase = "writing";
+  persistPlanState(pi, state);
+  return {
+    content: [{ type: "text" as const, text: `Template selected: ${templateName}` }],
+    details: { action: "select-template", templateName, content, phase: state.phase },
+  };
+}
+
+function executeCreateTemplate(params: Record<string, unknown>, projectDir: string): ActionResult {
+  const templateName = params.templateName as string;
+  const templateContent = params.templateContent as string;
+  if (!templateName || !templateContent) {
+    throw new Error("templateName and templateContent are required for create-template");
+  }
+  const sanitizedName = templateName.replace(/[^a-zA-Z0-9_-]/g, "");
+  if (!sanitizedName) {
+    throw new Error("Invalid template name: must contain alphanumeric characters");
+  }
+  const templateDir = path.join(projectDir, ".pi", "plan-templates");
+  fs.mkdirSync(templateDir, { recursive: true });
+  const filePath = path.join(templateDir, `${sanitizedName}.md`);
+  fs.writeFileSync(filePath, templateContent);
+  return {
+    content: [{ type: "text" as const, text: `Template created: ${sanitizedName}` }],
+    details: {
+      action: "create-template",
+      templateName: sanitizedName,
+      templateDir: relativePath(filePath, projectDir),
+    },
+  };
+}
+
+function executeAbort(
+  pi: ExtensionAPI,
+  sessions: PlanSessionMap,
+  sessionId: string,
+  ctx: ExtensionContext,
+): ActionResult {
+  const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
+  updatePlanWidget(ctx, updatedState);
+  restoreFullToolSet(pi);
+  return {
+    content: [{ type: "text" as const, text: "Plan mode aborted. Full tool access restored." }],
+    details: { action: "abort" },
+  };
+}
+
+/** Build execution options filtered by available capabilities. */
+async function buildExecOptions(pi: ExtensionAPI): Promise<string[]> {
+  const execOptions = ["Subagent-driven execution"];
+  const hasGoal = (await import("./compact.js")).detectGoalCapability(pi);
+  if (hasGoal) execOptions.push("Goal-driven execution (/goal)");
+  execOptions.push("Single-agent (current session)");
+  execOptions.push("Modify the plan first", "Save for later");
+  return execOptions;
+}
+
+/** Map the user's execution-method choice to the chosenMode string. */
+function chosenModeFromChoice(choice: string): string {
+  if (choice === "Subagent-driven execution") return "subagent";
+  if (choice === "Goal-driven execution (/goal)") return "goal";
+  return "single-agent";
+}
+
+/** Outcome of the complete-action execution-method prompt. */
+type CompleteChoiceOutcome =
+  | { kind: "cancelled"; result: ActionResult }
+  | { kind: "mode"; chosenMode: string };
+
+/**
+ * Prompt the user for an execution method (no-op selection when headless).
+ * Cancel / "Modify the plan first" / "Save for later" → cancelled with a
+ * complete-cancelled result; otherwise the mapped chosenMode.
+ */
+async function resolveCompleteChoice(ctx: ExtensionContext, pi: ExtensionAPI): Promise<CompleteChoiceOutcome> {
+  const execOptions = await buildExecOptions(pi);
+
+  if (typeof ctx.ui.select !== "function") {
+    return { kind: "mode", chosenMode: "single-agent" };
+  }
+  const choice = await ctx.ui.select("Plan is ready. Choose execution method:", execOptions);
+  if (!choice || choice === "Modify the plan first" || choice === "Save for later") {
+    return {
+      kind: "cancelled",
+      result: {
+        content: [
+          { type: "text" as const, text: `User chose: ${choice ?? "cancelled"}. Staying in plan mode.` },
+        ],
+        details: { action: "complete-cancelled", reason: choice ?? "cancelled" },
+      },
+    };
+  }
+  return { kind: "mode", chosenMode: chosenModeFromChoice(choice) };
+}
+
+/** complete action: prompt for execution mode, persist final phase, restore tools, reset state. */
+async function executeComplete(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  params: Record<string, unknown>,
+  state: PlanState,
+  sessions: PlanSessionMap,
+  sessionId: string,
+  projectDir: string,
+): Promise<ActionResult> {
+  const choice = await resolveCompleteChoice(ctx, pi);
+  if (choice.kind === "cancelled") {
+    return choice.result;
+  }
+  const chosenMode = choice.chosenMode;
+
+  // Persist final phase before cleanup
+  const planFilePath = state.planFilePath;
+  const isolation = (params.isolation as string) ?? "direct";
+  state.phase = "complete";
+  persistPlanState(pi, state);
+
+  // Restore full tool set
+  restoreFullToolSet(pi);
+
+  // Execute completion handler (compact/tree setup)
+  const { handlePlanComplete } = await import("./compact.js");
+  handlePlanComplete(pi, ctx, state, isolation, chosenMode);
+
+  // Reset state and clear widget — same as abort
+  const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
+  updatePlanWidget(ctx, updatedState);
+
+  const displayPath = relativePath(planFilePath, projectDir);
+  return {
+    content: [{ type: "text" as const, text: `Plan approved. File: ${displayPath}` }],
+    details: { action: "complete", planFilePath: displayPath, isolation, execMode: chosenMode },
+  };
+}
+
 // ── Register tool ──────────────────────────────────────────────────
 
 export function registerPlanTool(
@@ -182,7 +348,7 @@ export function registerPlanTool(
     label: "Plan Mode",
     description:
       "Manages plan mode lifecycle (template selection, state transitions, completion). " +
-      "NOT for writing plan content — use the 'write' tool to write plan.md. " +
+      "NOT for writing plan content — write plan.md via the bash tool (e.g. cat heredoc). " +
       "Actions: list-template, select-template, create-template, complete, abort.",
     parameters: Type.Object({
       action: StringEnum(PLAN_ACTIONS, { description: "Action to perform" }),
@@ -195,25 +361,25 @@ export function registerPlanTool(
       ),
     }),
     promptSnippet:
-      "## When to use this tool vs 'write'\n" +
+      "## When to use this tool vs the bash tool\n" +
       "Use 'plan' tool ONLY for plan mode state management:\n" +
       "- list-template / select-template / create-template — template operations\n" +
       "- complete — user approved plan, exit plan mode\n" +
       "- abort — cancel plan mode\n" +
       "\n" +
-      "Use 'write' tool for ALL plan content: writing plan.md, updating plan chapters.\n" +
+      "Use the bash tool for ALL plan content: writing plan.md, updating plan chapters (e.g. cat heredoc).\n" +
       "\n" +
       "## End-to-end workflow example\n" +
       "1. /plan 'add dark mode' — user enters plan mode\n" +
       "2. AI explores codebase (read, grep, bash) — brainstorming\n" +
       "3. plan(action='list-template') — show available templates\n" +
       "4. User picks template → plan(action='select-template', templateName='feature-plan')\n" +
-      "5. write({path: planFilePath, content: '...filled template...'}) — write plan content\n" +
+      "5. bash: cat > \"$PLAN_FILE\" <<'EOF' ... EOF — write plan content\n" +
       "6. User reviews → plan(action='complete', isolation='compact') — exit plan mode\n" +
       "\n" +
       "## Common mistakes\n" +
-      "❌ plan(action='complete') to 'write the plan' — WRONG, use write tool\n" +
-      "❌ Calling plan tool when user says 'write plan to file' — use write tool\n" +
+      "❌ plan(action='complete') to 'write the plan' — WRONG, write plan.md via the bash tool\n" +
+      "❌ Calling plan tool when user says 'write plan to file' — use the bash tool\n" +
       "✅ plan(action='list-template') to discover templates\n" +
       "✅ plan(action='complete') AFTER plan.md is written AND user approves",
     renderResult(
@@ -240,113 +406,20 @@ export function registerPlanTool(
       const projectDir = ctx.cwd;
 
       switch (action) {
-        case "list-template": {
-          const templates = listTemplates(projectDir);
-          return {
-            content: [{ type: "text" as const, text: `${templates.length} templates available` }],
-            details: { action: "list-template", templates },
-          };
-        }
-
-        case "select-template": {
-          const templateName = params.templateName as string;
-          if (!templateName) {
-            throw new Error("templateName is required for select-template");
-          }
-          const content = loadTemplate(templateName, projectDir);
-          if (!content) {
-            throw new Error(`Template not found: ${templateName}`);
-          }
-          state.templateName = templateName;
-          state.phase = "writing";
-          persistPlanState(pi, state);
-          return {
-            content: [{ type: "text" as const, text: `Template selected: ${templateName}` }],
-            details: { action: "select-template", templateName, content, phase: state.phase },
-          };
-        }
-
-        case "create-template": {
-          const templateName = params.templateName as string;
-          const templateContent = params.templateContent as string;
-          if (!templateName || !templateContent) {
-            throw new Error("templateName and templateContent are required for create-template");
-          }
-          const sanitizedName = templateName.replace(/[^a-zA-Z0-9_-]/g, "");
-          if (!sanitizedName) {
-            throw new Error("Invalid template name: must contain alphanumeric characters");
-          }
-          const templateDir = path.join(projectDir, ".pi", "plan-templates");
-          fs.mkdirSync(templateDir, { recursive: true });
-          const filePath = path.join(templateDir, `${sanitizedName}.md`);
-          fs.writeFileSync(filePath, templateContent);
-          return {
-            content: [{ type: "text" as const, text: `Template created: ${sanitizedName}` }],
-            details: {
-              action: "create-template",
-              templateName: sanitizedName,
-              templateDir: relativePath(filePath, projectDir),
-            },
-          };
-        }
-
-        case "complete": {
-          // Build execution options filtered by available capabilities
-          const execOptions = ["Subagent-driven execution"];
-          const hasGoal = (await import("./compact.js")).detectGoalCapability(pi);
-          if (hasGoal) execOptions.push("Goal-driven execution (/goal)");
-          execOptions.push("Single-agent (current session)");
-          execOptions.push("Modify the plan first", "Save for later");
-
-          let chosenMode = "single-agent";
-          if (typeof ctx.ui.select === "function") {
-            const choice = await ctx.ui.select("Plan is ready. Choose execution method:", execOptions);
-            if (!choice || choice === "Modify the plan first" || choice === "Save for later") {
-              return {
-                content: [
-                  { type: "text" as const, text: `User chose: ${choice ?? "cancelled"}. Staying in plan mode.` },
-                ],
-                details: { action: "complete-cancelled", reason: choice ?? "cancelled" },
-              };
-            }
-            if (choice === "Subagent-driven execution") chosenMode = "subagent";
-            else if (choice === "Goal-driven execution (/goal)") chosenMode = "goal";
-            else chosenMode = "single-agent";
-          }
-
-          // Persist final phase before cleanup
-          const planFilePath = state.planFilePath;
-          const isolation = (params.isolation as string) ?? "direct";
-          state.phase = "complete";
-          persistPlanState(pi, state);
-
-          // Restore full tool set
-          restoreFullToolSet(pi);
-
-          // Execute completion handler (compact/tree setup)
-          const { handlePlanComplete } = await import("./compact.js");
-          handlePlanComplete(pi, ctx, state, isolation, chosenMode);
-
-          // Reset state and clear widget — same as abort
-          const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
-          updatePlanWidget(ctx, updatedState);
-
-          const displayPath = relativePath(planFilePath, projectDir);
-          return {
-            content: [{ type: "text" as const, text: `Plan approved. File: ${displayPath}` }],
-            details: { action: "complete", planFilePath: displayPath, isolation, execMode: chosenMode },
-          };
-        }
-
-        case "abort": {
-          const updatedState = resetPlanState(pi, sessions, sessionId, ctx);
-          updatePlanWidget(ctx, updatedState);
-          restoreFullToolSet(pi);
-          return {
-            content: [{ type: "text" as const, text: "Plan mode aborted. Full tool access restored." }],
-            details: { action: "abort" },
-          };
-        }
+        case "list-template":
+          return executeListTemplate(projectDir);
+
+        case "select-template":
+          return executeSelectTemplate(pi, params, state, projectDir);
+
+        case "create-template":
+          return executeCreateTemplate(params, projectDir);
+
+        case "complete":
+          return await executeComplete(pi, ctx, params, state, sessions, sessionId, projectDir);
+
+        case "abort":
+          return executeAbort(pi, sessions, sessionId, ctx);
       }
     },
   });