@zhushanwen/pi-plan 0.2.0

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@zhushanwen/pi-plan",
+  "version": "0.2.0",
+  "description": "Lightweight plan mode for Pi coding agent",
+  "type": "module",
+  "main": "index.ts",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "keywords": [
+    "pi-package",
+    "extension"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.73.0",
+    "@sinclair/typebox": "*",
+    "@mariozechner/pi-ai": "*"
+  },
+  "peerDependenciesMeta": {
+    "@mariozechner/pi-ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "vitest": "^4.1.8"
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "templates/"
+  ],
+  "scripts": {
+    "typecheck": "npx tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/command.test.ts

@@ -0,0 +1,166 @@
+import { beforeEach,describe, expect, it, vi } from "vitest";
+
+// Mock dependencies before importing
+vi.mock("node:fs", () => ({
+  mkdirSync: vi.fn(),
+  readdirSync: vi.fn(() => []),
+  statSync: vi.fn(),
+  existsSync: vi.fn(() => false),
+}));
+
+vi.mock("../widget.js", () => ({
+  updatePlanWidget: vi.fn(),
+}));
+
+import * as fs from "node:fs";
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { registerPlanCommand } from "../command.js";
+
+const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "write", "edit"];
+
+function createMocks() {
+  let capturedHandler: (args: string, ctx: ExtensionContext) => Promise<void>;
+
+  const pi = {
+    registerCommand: vi.fn((_name: string, def: { handler: (args: string, ctx: ExtensionContext) => Promise<void> }) => {
+      capturedHandler = def.handler;
+    }),
+    appendEntry: vi.fn(),
+    setActiveTools: vi.fn(),
+    sendUserMessage: vi.fn(),
+    getAllTools: vi.fn(() => ALL_TOOL_NAMES.map((n) => ({ name: n }))),
+  } as unknown as ExtensionAPI;
+
+  const ctx = {
+    cwd: "/tmp/test-project",
+    sessionManager: {
+      getSessionId: () => "test-session",
+      getEntries: () => [] as unknown[],
+    },
+    ui: {
+      notify: vi.fn(),
+      setWidget: vi.fn(),
+      setStatus: vi.fn(),
+      theme: { fg: (_t: string, text: string) => text },
+    },
+  } as unknown as ExtensionContext;
+
+  return {
+    pi,
+    ctx,
+    getHandler: () => capturedHandler!,
+  };
+}
+
+describe("registerPlanCommand", () => {
+  let pi: ExtensionAPI;
+  let ctx: ExtensionContext;
+  let handler: (args: string, ctx: ExtensionContext) => Promise<void>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    const mocks = createMocks();
+    pi = mocks.pi;
+    ctx = mocks.ctx;
+    const sessions = new Map();
+    registerPlanCommand(pi, sessions);
+    handler = mocks.getHandler();
+  });
+
+  it("registers 'plan' command", () => {
+    expect(pi.registerCommand).toHaveBeenCalledWith("plan", expect.objectContaining({ handler: expect.any(Function) }));
+  });
+
+  // --- abort subcommand ---
+
+  it("abort: notifies 'No active plan mode' when idle", async () => {
+    await handler("abort", ctx);
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("No active plan mode.", "info");
+    expect(pi.setActiveTools).not.toHaveBeenCalled();
+  });
+
+  it("abort: resets state and restores tools when active", async () => {
+    // Enter plan mode first — handler uses the sessions map from registerPlanCommand closure
+    await handler("implement user auth", ctx);
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    vi.clearAllMocks();
+
+    // Now abort — state is active in the sessions map
+    await handler("abort", ctx);
+
+    expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("Plan mode aborted.", "info");
+  });
+
+  // --- status subcommand ---
+
+  it("status: notifies 'No active plan mode' when idle", async () => {
+    await handler("status", ctx);
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("No active plan mode.", "info");
+  });
+
+  // --- already active + new args ---
+
+  it("warns when already active and args provided", async () => {
+    // First enter plan mode
+    await handler("my feature", ctx);
+    vi.clearAllMocks();
+
+    // Try to enter again with different args
+    await handler("another feature", ctx);
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith(
+      "Plan mode is already active. Use /plan abort to cancel first.",
+      "warning",
+    );
+  });
+
+  // --- enter plan mode ---
+
+  it("enters plan mode with slugified path", async () => {
+    await handler("Implement User Auth", ctx);
+
+    expect(fs.mkdirSync).toHaveBeenCalledWith(
+      "/tmp/test-project/.xyz-harness/implement-user-auth",
+      { recursive: true },
+    );
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("[PLAN MODE]"));
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.stringContaining("Implement User Auth"));
+    expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", expect.objectContaining({
+      isActive: true,
+      phase: "brainstorming",
+    }));
+  });
+
+  it("handles special characters in requirement for slug", async () => {
+    await handler("Fix bug #123: 中文标题!", ctx);
+
+    expect(fs.mkdirSync).toHaveBeenCalledWith(
+      expect.stringContaining("/.xyz-harness/fix-bug-123"),
+      { recursive: true },
+    );
+  });
+
+  it("uses 'untitled' slug when no args", async () => {
+    // No existing plans (readdirSync returns [])
+    await handler("", ctx);
+
+    expect(fs.mkdirSync).toHaveBeenCalledWith(
+      "/tmp/test-project/.xyz-harness/untitled",
+      { recursive: true },
+    );
+  });
+
+  it("shows status when active with no args", async () => {
+    await handler("my feature", ctx);
+    vi.clearAllMocks();
+
+    await handler("", ctx);
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith(
+      expect.stringContaining("brainstorming"),
+      "info",
+    );
+  });
+});

package/src/__tests__/compact-handler.test.ts

@@ -0,0 +1,179 @@
+import { beforeEach,describe, expect, it, vi } from "vitest";
+
+import type { PlanState } from "../state.js";
+
+// Mock fs before importing compact.ts (ESM namespace is not configurable)
+vi.mock("node:fs", () => ({
+  readFileSync: vi.fn(),
+}));
+
+// Import after mock setup
+import { handlePlanComplete, registerPlanEventHandlers } from "../compact.js";
+
+const fsMock = vi.mocked(await import("node:fs"));
+
+// --- Shared mock factories ---
+
+function makePi() {
+  return {
+    on: vi.fn(),
+    appendEntry: vi.fn(),
+    sendUserMessage: vi.fn(),
+  };
+}
+
+type CtxMock = ReturnType<typeof makeCtx>;
+function makeCtx() {
+  const onCompleteFns: Array<() => void> = [];
+  const onErrorFns: Array<(e: Error) => void> = [];
+
+  return {
+    sessionManager: { getSessionId: () => "test-session", getEntries: () => [] as unknown[] },
+    ui: { notify: vi.fn() },
+    compact: vi.fn((opts: { onComplete?: () => void; onError?: (e: Error) => void }) => {
+      if (opts.onComplete) onCompleteFns.push(opts.onComplete);
+      if (opts.onError) onErrorFns.push(opts.onError);
+    }),
+    _onCompleteFns: onCompleteFns,
+    _onErrorFns: onErrorFns,
+  };
+}
+
+function makeActiveState(): PlanState {
+  return {
+    isActive: true,
+    phase: "complete",
+    planFilePath: "/tmp/plan.md",
+    requirement: "Add login page",
+    templateName: "default",
+  };
+}
+
+function setupFsMock(content: string) {
+  fsMock.readFileSync.mockReturnValue(content);
+}
+
+// --- handlePlanComplete tests ---
+
+describe("handlePlanComplete", () => {
+  let pi: ReturnType<typeof makePi>;
+  let ctx: CtxMock;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    pi = makePi();
+    ctx = makeCtx();
+    setupFsMock("## 实现步骤\n1. Step one\n2. Step two");
+  });
+
+  it("compact isolation: calls compact, onComplete sends steer + tryGoalInit", () => {
+    (pi as unknown as Record<string, unknown>).__goalInit = vi.fn().mockReturnValue(true);
+
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact");
+
+    expect(ctx.compact).toHaveBeenCalledOnce();
+    ctx._onCompleteFns[0]();
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.any(String), { deliverAs: "steer" });
+    expect((pi as unknown as Record<string, unknown>).__goalInit).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.arrayContaining([expect.any(String)]),
+      undefined,
+      ctx,
+    );
+  });
+
+  it("compact onError: falls back to notify + steer", () => {
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "compact");
+
+    ctx._onErrorFns[0](new Error("compact failed"));
+    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.any(String), "warning");
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.any(String), { deliverAs: "steer" });
+  });
+
+  it("tree isolation: only notify, no compact or steer", () => {
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "tree");
+
+    expect(ctx.ui.notify).toHaveBeenCalledWith(expect.stringContaining("/tmp/plan.md"), "info");
+    expect(ctx.compact).not.toHaveBeenCalled();
+    expect(pi.sendUserMessage).not.toHaveBeenCalled();
+  });
+
+  it("direct isolation: directly sends steer", () => {
+    (pi as unknown as Record<string, unknown>).__goalInit = vi.fn().mockReturnValue(true);
+    handlePlanComplete(pi as never, ctx as never, makeActiveState(), "direct");
+
+    expect(pi.sendUserMessage).toHaveBeenCalledWith(expect.any(String), { deliverAs: "steer" });
+    expect(ctx.compact).not.toHaveBeenCalled();
+    expect(ctx.ui.notify).not.toHaveBeenCalled();
+    expect((pi as unknown as Record<string, unknown>).__goalInit).toHaveBeenCalledWith(
+      expect.any(String),
+      expect.arrayContaining([expect.any(String)]),
+      undefined,
+      ctx,
+    );
+  });
+});
+
+// --- registerPlanEventHandlers tests ---
+
+describe("registerPlanEventHandlers", () => {
+  let pi: ReturnType<typeof makePi>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    pi = makePi();
+    setupFsMock("Plan content here");
+  });
+
+  function captureHandlers(): Record<string, (...args: unknown[]) => Promise<unknown>> {
+    const handlers: Record<string, (...args: unknown[]) => Promise<unknown>> = {};
+    for (const call of pi.on.mock.calls) {
+      handlers[call[0] as string] = call[1];
+    }
+    return handlers;
+  }
+
+  it("session_before_compact (active): returns compaction summary with plan content", async () => {
+    const sessions = new Map();
+    sessions.set("test-session", makeActiveState());
+
+    registerPlanEventHandlers(pi as never, sessions);
+    const handlers = captureHandlers();
+
+    const result = await handlers["session_before_compact"]({}, makeCtx() as never);
+    const r = result as { compaction: { summary: string } };
+
+    expect(r.compaction.summary).toContain("Plan content here");
+    expect(r.compaction.summary).toContain("Add login page");
+  });
+
+  it("session_before_compact (inactive): returns empty object {}", async () => {
+    registerPlanEventHandlers(pi as never, new Map());
+    const handlers = captureHandlers();
+
+    const result = await handlers["session_before_compact"]({}, makeCtx() as never);
+    expect(result).toEqual({});
+  });
+
+  it("session_before_tree (active): returns summary with plan content", async () => {
+    const sessions = new Map();
+    sessions.set("test-session", makeActiveState());
+
+    registerPlanEventHandlers(pi as never, sessions);
+    const handlers = captureHandlers();
+
+    const result = await handlers["session_before_tree"]({}, makeCtx() as never);
+    const r = result as { summary: { summary: string } };
+
+    expect(r.summary.summary).toContain("Plan content here");
+    expect(r.summary.summary).toContain("/tmp/plan.md");
+  });
+
+  it("session_before_tree (inactive): returns empty object {}", async () => {
+    registerPlanEventHandlers(pi as never, new Map());
+    const handlers = captureHandlers();
+
+    const result = await handlers["session_before_tree"]({}, makeCtx() as never);
+    expect(result).toEqual({});
+  });
+});

package/src/__tests__/compact.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect,it } from "vitest";
+
+import { extractPlanSteps } from "../compact.js";
+
+describe("extractPlanSteps", () => {
+  it("extracts numbered steps from 实现步骤 section", () => {
+    const plan = `# Plan
+
+## 背景
+Some context
+
+## 实现步骤
+1. Create the user model
+2. Add validation logic
+3. Write unit tests
+
+## 验证
+Run tests`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual([
+      "Create the user model",
+      "Add validation logic",
+      "Write unit tests",
+    ]);
+  });
+
+  it("extracts numbered steps from 实施步骤 section", () => {
+    const plan = `## 实施步骤
+1. Step one
+2. Step two`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual(["Step one", "Step two"]);
+  });
+
+  it("extracts steps from English Steps section", () => {
+    const plan = `## Steps
+1. First step
+2. Second step`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual(["First step", "Second step"]);
+  });
+
+  it("extracts steps from Implementation section", () => {
+    const plan = `## Implementation Steps
+1. Create file
+2. Add exports`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual(["Create file", "Add exports"]);
+  });
+
+  it("stops at next ## header", () => {
+    const plan = `## 实现步骤
+1. Step in plan section
+
+## 验证
+1. Not a plan step
+2. Also not a plan step`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual(["Step in plan section"]);
+  });
+
+  it("extracts checkbox items from steps section", () => {
+    const plan = `## 实现步骤
+- [ ] Add auth middleware
+- [x] Create user model
+- [ ] Write integration test`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual([
+      "Add auth middleware",
+      "Create user model",
+      "Write integration test",
+    ]);
+  });
+
+  it("returns empty array when no steps section and no numbered items", () => {
+    const plan = `## 背景
+Some context
+
+## 方案
+Option A is preferred`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual([]);
+  });
+
+  it("fallback: collects numbered items when no steps section header", () => {
+    const plan = `# Plan
+1. First thing
+2. Second thing
+3. Third thing`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual(["First thing", "Second thing", "Third thing"]);
+  });
+
+  it("skips empty lines and whitespace-only items", () => {
+    const plan = `## 实现步骤
+1. Valid step
+
+2. Another valid step`;
+    const steps = extractPlanSteps(plan);
+    expect(steps).toEqual(["Valid step", "Another valid step"]);
+  });
+});

package/src/__tests__/state.test.ts

@@ -0,0 +1,117 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  DEFAULT_PLAN_STATE,
+  getPlanState,
+  persistPlanState,
+  type PlanPhase,
+  type PlanSessionMap,
+  type PlanState,
+  reconstructPlanState,
+} from "../state.js";
+
+describe("PlanState", () => {
+  it("DEFAULT_PLAN_STATE has correct defaults", () => {
+    expect(DEFAULT_PLAN_STATE.isActive).toBe(false);
+    expect(DEFAULT_PLAN_STATE.phase).toBe("idle");
+    expect(DEFAULT_PLAN_STATE.planFilePath).toBe("");
+    expect(DEFAULT_PLAN_STATE.requirement).toBe("");
+    expect(DEFAULT_PLAN_STATE.templateName).toBe("");
+  });
+
+  it("PlanPhase type includes all required phases", () => {
+    const phases: PlanPhase[] = ["idle", "brainstorming", "writing", "complete"];
+    expect(phases).toHaveLength(4);
+  });
+
+  it("getPlanState returns cached state if exists", () => {
+    const sessions: PlanSessionMap = new Map();
+    const cached: PlanState = { ...DEFAULT_PLAN_STATE, isActive: true, phase: "brainstorming" };
+    sessions.set("session-1", cached);
+
+    const mockCtx = {
+      sessionManager: { getEntries: () => [] },
+    } as unknown as ExtensionContext;
+
+    const result = getPlanState(sessions, "session-1", mockCtx);
+    expect(result).toBe(cached);
+  });
+
+  it("getPlanState reconstructs from sessionManager if not cached", () => {
+    const sessions: PlanSessionMap = new Map();
+    const mockCtx = {
+      sessionManager: {
+        getEntries: () => [
+          {
+            type: "custom",
+            customType: "plan-state",
+            data: { isActive: true, phase: "writing", planFilePath: ".xyz-harness/test/plan.md", requirement: "test", templateName: "feature-plan" },
+          },
+        ],
+      },
+    } as unknown as ExtensionContext;
+
+    const result = getPlanState(sessions, "session-2", mockCtx);
+    expect(result.isActive).toBe(true);
+    expect(result.phase).toBe("writing");
+    expect(sessions.get("session-2")).toBe(result);
+  });
+});
+
+describe("State persistence", () => {
+  it("persistPlanState calls appendEntry with correct data", () => {
+    const mockPi = { appendEntry: vi.fn() } as unknown as ExtensionAPI;
+    const state: PlanState = {
+      isActive: true,
+      phase: "brainstorming",
+      planFilePath: ".xyz-harness/test/plan.md",
+      requirement: "test requirement",
+      templateName: "feature-plan",
+    };
+
+    persistPlanState(mockPi, state);
+
+    expect(mockPi.appendEntry).toHaveBeenCalledWith("plan-state", {
+      isActive: true,
+      phase: "brainstorming",
+      planFilePath: ".xyz-harness/test/plan.md",
+      requirement: "test requirement",
+      templateName: "feature-plan",
+    });
+  });
+
+  it("reconstructPlanState returns DEFAULT_PLAN_STATE when no entries", () => {
+    const mockCtx = {
+      sessionManager: { getEntries: () => [] },
+    } as unknown as ExtensionContext;
+
+    const state = reconstructPlanState(mockCtx);
+    expect(state).toEqual(DEFAULT_PLAN_STATE);
+  });
+
+  it("reconstructPlanState restores state from entries", () => {
+    const mockCtx = {
+      sessionManager: {
+        getEntries: () => [
+          {
+            type: "custom",
+            customType: "plan-state",
+            data: {
+              isActive: true,
+              phase: "writing",
+              planFilePath: ".xyz-harness/test/plan.md",
+              requirement: "test",
+              templateName: "feature-plan",
+            },
+          },
+        ],
+      },
+    } as unknown as ExtensionContext;
+
+    const state = reconstructPlanState(mockCtx);
+    expect(state.isActive).toBe(true);
+    expect(state.phase).toBe("writing");
+    expect(state.planFilePath).toBe(".xyz-harness/test/plan.md");
+  });
+});

package/src/__tests__/templates.test.ts

@@ -0,0 +1,34 @@
+import * as fs from "node:fs";
+
+import { describe, expect,it } from "vitest";
+
+import { getBuiltinTemplateDir,listTemplates, loadTemplate } from "../templates.js";
+
+describe("Template system", () => {
+  it("listTemplates returns builtin templates", () => {
+    const templates = listTemplates();
+    expect(templates.length).toBeGreaterThanOrEqual(5);
+    const names = templates.map((t) => t.name);
+    expect(names).toContain("feature-plan");
+    expect(names).toContain("bugfix-plan");
+    expect(names).toContain("refactor-plan");
+    expect(names).toContain("research-plan");
+    expect(names).toContain("implementation-plan");
+  });
+
+  it("loadTemplate returns content for existing builtin template", () => {
+    const content = loadTemplate("feature-plan");
+    expect(content).not.toBeNull();
+    expect(content).toContain("## ");
+  });
+
+  it("loadTemplate returns null for non-existent template", () => {
+    const content = loadTemplate("non-existent-template");
+    expect(content).toBeNull();
+  });
+
+  it("getBuiltinTemplateDir returns valid path", () => {
+    const dir = getBuiltinTemplateDir();
+    expect(fs.existsSync(dir)).toBe(true);
+  });
+});