@dreki-gg/pi-plan-mode 0.6.3 → 0.7.2

package/extensions/plan-mode/plans-json.ts

@@ -45,8 +45,4 @@ export function serializePlansJson(manifest: PlansManifest): string {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-/** Extract the plan title from the first `# ...` heading in PLAN.md content. */
-export function extractPlanTitle(planContent: string): string {
-  const match = planContent.match(/^#\s+(.+)$/m);
-  return match ? match[1].trim() : 'Untitled plan';
-}
+

package/extensions/plan-mode/tools/submit-plan.ts

@@ -0,0 +1,144 @@
+/**
+ * submit_plan tool — available during the plan phase.
+ *
+ * The planner calls this to submit a structured plan with typed steps.
+ * Writes `.plans/<name>/plan.json` and updates the plans.json manifest.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { readPlansJson, serializePlansJson } from '../plans-json.js';
+import { toKebabCase } from '../utils.js';
+import type { PlanData, PlanStep } from '../types.js';
+
+export interface SubmitPlanCallbacks {
+  onPlanSubmitted: (planDir: string, plan: PlanData) => void;
+}
+
+export function registerSubmitPlanTool(pi: ExtensionAPI, callbacks: SubmitPlanCallbacks): void {
+  pi.registerTool({
+    name: 'submit_plan',
+    label: 'Submit Plan',
+    description:
+      'Submit a structured plan with a title, context, numbered steps, and risks. ' +
+      'Each step has a short description (for progress display) and detailed implementation instructions. ' +
+      'This finalizes the plan and writes it to .plans/<name>/plan.json.',
+    promptSnippet:
+      'Submit a structured plan with title, context, steps (description + details), and risks',
+    promptGuidelines: [
+      'Call submit_plan once when you have finished analyzing the codebase and are ready to finalize your plan.',
+      'Each submit_plan step description should be a short label (≤60 chars). Put full implementation instructions in the details field.',
+      'The submit_plan context field must include all codebase findings, relevant file paths, APIs, patterns, and constraints so an executor with zero prior context can implement the plan.',
+    ],
+    parameters: Type.Object({
+      name: Type.String({
+        description: 'Short kebab-case name for the plan (e.g. "add-auth-middleware")',
+      }),
+      title: Type.String({ description: 'Human-readable plan title' }),
+      context: Type.String({
+        description:
+          'Complete codebase context: relevant file paths, APIs, patterns, constraints, and gotchas',
+      }),
+      steps: Type.Array(
+        Type.Object({
+          description: Type.String({
+            description: 'Short step label for progress display (≤60 chars)',
+          }),
+          details: Type.String({
+            description: 'Full implementation instructions for this step',
+          }),
+        }),
+        { minItems: 1 },
+      ),
+      risks: Type.String({ description: 'Open questions, assumptions, and risks' }),
+    }),
+
+    async execute(_toolCallId, params) {
+      const planName = toKebabCase(params.name);
+      const planDir = `.plans/${planName}`;
+
+      const steps: PlanStep[] = params.steps.map((s) => ({
+        description: s.description.slice(0, 60),
+        details: s.details,
+        status: 'pending' as const,
+      }));
+
+      const plan: PlanData = {
+        title: params.title,
+        context: params.context,
+        steps,
+        risks: params.risks,
+      };
+
+      // Write plan.json
+      await mkdir(planDir, { recursive: true });
+      await writeFile(`${planDir}/plan.json`, JSON.stringify(plan, null, 2) + '\n', 'utf-8');
+
+      // Update plans.json manifest
+      const manifest = await readPlansJson();
+      const now = new Date().toISOString();
+      manifest[planName] = {
+        status: 'in-progress',
+        title: params.title,
+        created: manifest[planName]?.created ?? now,
+        completed: null,
+      };
+      await writeFile('.plans/plans.json', serializePlansJson(manifest), 'utf-8');
+
+      callbacks.onPlanSubmitted(planDir, plan);
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Plan "${params.title}" saved with ${steps.length} steps. Waiting for user to review and execute.`,
+          },
+        ],
+        details: { planDir, plan },
+        terminate: true,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { name?: string }).name ?? 'plan';
+      const title = (args as { title?: string }).title ?? '';
+      let content = theme.fg('toolTitle', theme.bold('submit_plan '));
+      content += theme.fg('accent', name);
+      if (title) {
+        content += ' ' + theme.fg('dim', `"${title}"`);
+      }
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as { plan?: PlanData } | undefined;
+      const plan = details?.plan;
+      if (!plan) {
+        return new Text(theme.fg('success', '✓ Plan saved'), 0, 0);
+      }
+
+      const lines: string[] = [];
+
+      // Title
+      lines.push(theme.fg('success', '✓ ') + theme.fg('accent', theme.bold(plan.title)));
+      lines.push('');
+
+      // Steps
+      for (let i = 0; i < plan.steps.length; i++) {
+        const step = plan.steps[i];
+        const num = theme.fg('muted', `${i + 1}.`);
+        lines.push(`  ${num} ${step.description}`);
+      }
+
+      // Risks
+      if (plan.risks) {
+        lines.push('');
+        lines.push(theme.fg('warning', '⚠ Risks: ') + theme.fg('dim', plan.risks));
+      }
+
+      return new Text(lines.join('\n'), 0, 0);
+    },
+  });
+}

package/extensions/plan-mode/tools/update-step.ts

@@ -0,0 +1,143 @@
+/**
+ * update_step tool — available during the execution phase.
+ *
+ * The executor calls this to mark a plan step as done, skipped, or blocked.
+ * On "blocked", returns a stop signal so the executor pauses for user intervention.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { PlanData } from '../types.js';
+
+export interface UpdateStepCallbacks {
+  getPlan: () => PlanData | undefined;
+  onStepUpdated: (step: number, status: 'done' | 'skipped' | 'blocked', notes?: string) => void;
+}
+
+export function registerUpdateStepTool(pi: ExtensionAPI, callbacks: UpdateStepCallbacks): void {
+  pi.registerTool({
+    name: 'update_step',
+    label: 'Update Step',
+    description:
+      'Mark a plan step as done, skipped, or blocked. ' +
+      'Call this after completing each step. ' +
+      'If a step is blocked, execution will pause for user intervention.',
+    promptSnippet: 'Mark a plan step as done, skipped, or blocked',
+    promptGuidelines: [
+      'Call update_step after completing each plan step to mark it done before moving to the next.',
+      'Use update_step with status "skipped" if a step is unnecessary after inspecting the code.',
+      'Use update_step with status "blocked" and explain the reason in notes if a step cannot be completed — execution will pause for user input.',
+    ],
+    parameters: Type.Object({
+      step: Type.Number({ description: 'Step number (1-indexed)' }),
+      status: StringEnum(['done', 'skipped', 'blocked'] as const),
+      notes: Type.Optional(
+        Type.String({ description: 'What was done, why skipped, or why blocked' }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const plan = callbacks.getPlan();
+      if (!plan) {
+        throw new Error('No active plan. Cannot update step.');
+      }
+
+      const stepIdx = params.step - 1;
+      if (stepIdx < 0 || stepIdx >= plan.steps.length) {
+        throw new Error(
+          `Invalid step number ${params.step}. Plan has ${plan.steps.length} steps.`,
+        );
+      }
+
+      const step = plan.steps[stepIdx];
+      if (step.status !== 'pending') {
+        throw new Error(
+          `Step ${params.step} is already "${step.status}". Only pending steps can be updated.`,
+        );
+      }
+
+      callbacks.onStepUpdated(params.step, params.status, params.notes);
+
+      const details = {
+        step: params.step,
+        status: params.status,
+        notes: params.notes,
+        description: step.description,
+      };
+
+      if (params.status === 'blocked') {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Step ${params.step} blocked. Execution paused — waiting for user input.`,
+            },
+          ],
+          details,
+          terminate: true,
+        };
+      }
+
+      // Build progress info
+      const done = plan.steps.filter((s) => s.status === 'done').length;
+      const skipped = plan.steps.filter((s) => s.status === 'skipped').length;
+      const resolved = done + skipped;
+
+      const statusEmoji = params.status === 'done' ? '✓' : '⊘';
+      let text = `${statusEmoji} Step ${params.step} ${params.status}. Progress: ${resolved}/${plan.steps.length}`;
+      if (params.notes) {
+        text += ` — ${params.notes}`;
+      }
+
+      // Find next pending step
+      const next = plan.steps.find((s) => s.status === 'pending');
+      if (next) {
+        const nextIdx = plan.steps.indexOf(next) + 1;
+        text += `\n\nNext step ${nextIdx}: ${next.description}`;
+      } else {
+        text += '\n\nAll steps resolved!';
+      }
+
+      return {
+        content: [{ type: 'text' as const, text }],
+        details,
+      };
+    },
+
+    renderCall(args, theme) {
+      const step = (args as { step?: number }).step ?? '?';
+      const status = (args as { status?: string }).status ?? '';
+      let content = theme.fg('toolTitle', theme.bold('update_step '));
+      content += theme.fg('muted', `#${step}`);
+      if (status) {
+        const color = status === 'done' ? 'success' : status === 'skipped' ? 'warning' : 'error';
+        content += ' ' + theme.fg(color, status);
+      }
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as {
+        step?: number;
+        status?: string;
+        description?: string;
+      } | undefined;
+
+      if (!details) {
+        return new Text(theme.fg('dim', 'Updated'), 0, 0);
+      }
+
+      const statusMap: Record<string, string> = {
+        done: theme.fg('success', '✓'),
+        skipped: theme.fg('warning', '⊘'),
+        blocked: theme.fg('error', '✗'),
+      };
+
+      const icon = statusMap[details.status ?? ''] ?? '';
+      const desc = details.description ?? '';
+      return new Text(`${icon} Step ${details.step}: ${desc}`, 0, 0);
+    },
+  });
+}

package/extensions/plan-mode/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared types for plan mode.
+ */
+
+export interface PlanStep {
+  description: string;
+  details: string;
+  status: 'pending' | 'done' | 'skipped' | 'blocked';
+  notes?: string;
+}
+
+export interface PlanData {
+  title: string;
+  context: string;
+  steps: PlanStep[];
+  risks: string;
+}
+
+export interface PersistedState {
+  planEnabled: boolean;
+  executing: boolean;
+  planDir: string | undefined;
+  plan: PlanData | undefined;
+  executionStartIdx: number | undefined;
+}

package/extensions/plan-mode/utils.test.ts

@@ -12,6 +12,12 @@ describe('isSafeCommand', () => {
       expect(isSafeCommand('mkdir .plans/my-plan')).toBe(true);
     });
 
+    test('command with 2>/dev/null stderr redirect', () => {
+      expect(
+        isSafeCommand('cat .release-please-manifest.json 2>/dev/null; echo "---"; cat release-please-config.json 2>/dev/null'),
+      ).toBe(true);
+    });
+
     test('curl with 2>/dev/null pipe chain', () => {
       expect(
         isSafeCommand(

package/extensions/plan-mode/utils.ts

@@ -6,12 +6,6 @@
 
 import { isSafeCommand as baseSafeCommand } from '@dreki-gg/pi-command-sandbox';
 
-export interface TodoItem {
-  step: number;
-  text: string;
-  completed: boolean;
-}
-
 /**
  * Check if a command is safe for plan mode.
  *
@@ -20,7 +14,7 @@ export interface TodoItem {
  */
 export function isSafeCommand(command: string): boolean {
   return baseSafeCommand(command, {
-    allowCommand: (cmd) => isMkdirPlans(cmd) || isCurlWithStderrRedirect(cmd),
+    allowCommand: (cmd) => isMkdirPlans(cmd),
   });
 }
 
@@ -29,81 +23,6 @@ function isMkdirPlans(command: string): boolean {
   return /^\s*mkdir\s+(-p\s+)?\.plans(\/|\\|\s|$)/.test(command);
 }
 
-/**
- * Allow curl commands that only redirect stderr to /dev/null.
- * shell-quote parses `2>/dev/null` as a stdout redirect, but it's
- * actually a stderr redirect which is safe for read-only mode.
- */
-function isCurlWithStderrRedirect(command: string): boolean {
-  return (
-    /^\s*curl\b/.test(command) &&
-    /2>\/dev\/null/.test(command) &&
-    !/>(?!\/dev\/null)/.test(command.replace(/2>\/dev\/null/g, ''))
-  );
-}
-
-// ── Plan extraction ─────────────────────────────────────────────────────────
-
-export function cleanStepText(text: string): string {
-  let cleaned = text
-    .replace(/\*{1,2}([^*]+)\*{1,2}/g, '$1')
-    .replace(/`([^`]+)`/g, '$1')
-    .replace(/\s+/g, ' ')
-    .trim();
-
-  if (cleaned.length > 0) {
-    cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
-  }
-  if (cleaned.length > 60) {
-    cleaned = `${cleaned.slice(0, 57)}...`;
-  }
-  return cleaned;
-}
-
-export function extractTodoItems(message: string): TodoItem[] {
-  const items: TodoItem[] = [];
-  const headerMatch = message.match(/\*{0,2}Plan:\*{0,2}\s*\n/i);
-  if (!headerMatch) return items;
-
-  const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length);
-  const numberedPattern = /^\s*(\d+)[.)]\s+\*{0,2}([^*\n]+)/gm;
-
-  for (const match of planSection.matchAll(numberedPattern)) {
-    const text = match[2]
-      .trim()
-      .replace(/\*{1,2}$/, '')
-      .trim();
-
-    if (text.length <= 5) continue;
-    if (text.startsWith('`') || text.startsWith('/') || text.startsWith('-')) continue;
-
-    const cleaned = cleanStepText(text);
-    if (cleaned.length <= 3) continue;
-
-    items.push({ step: items.length + 1, text: cleaned, completed: false });
-  }
-
-  return items;
-}
-
-export function extractDoneSteps(message: string): number[] {
-  const steps: number[] = [];
-  for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
-    const step = Number(match[1]);
-    if (Number.isFinite(step)) steps.push(step);
-  }
-  return steps;
-}
-
-export function markCompletedSteps(text: string, items: TodoItem[]): number {
-  const doneSteps = extractDoneSteps(text);
-  for (const step of doneSteps) {
-    const item = items.find((t) => t.step === step);
-    if (item) item.completed = true;
-  }
-  return doneSteps.length;
-}
-
 // ── Plan name utilities ─────────────────────────────────────────────────────
 
 export function toKebabCase(name: string): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.6.3",
+  "version": "0.7.2",
   "description": "Two-phase planning workflow for pi — plan with claude-opus-4-6:medium, execute with gpt-5.5:low, with .plans/ file-based handoff",
   "keywords": [
     "pi-package"
@@ -24,8 +24,6 @@
     "package.json"
   ],
   "scripts": {
-    "prepack": "node --experimental-strip-types scripts/prepack.js",
-    "postpack": "rm -rf node_modules/@dreki-gg",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint extensions bin",
     "format": "oxfmt --write extensions bin",
@@ -36,11 +34,8 @@
       "./extensions/plan-mode"
     ]
   },
-  "bundledDependencies": [
-    "@dreki-gg/pi-command-sandbox"
-  ],
   "dependencies": {
-    "@dreki-gg/pi-command-sandbox": "0.1.0"
+    "@dreki-gg/pi-command-sandbox": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "24",

package/node_modules/@dreki-gg/pi-command-sandbox/dist/index.d.mts

@@ -1,104 +0,0 @@
-//#region src/sandbox.d.ts
-/**
- * Core sandbox logic — determines whether a shell command is safe to execute.
- */
-interface SandboxOptions {
-  /**
-   * Extra patterns to allow beyond the built-in SAFE_PATTERNS.
-   * Checked against the reconstructed command string for each segment.
-   */
-  extraSafe?: RegExp[];
-  /**
-   * Extra patterns to block beyond the built-in DESTRUCTIVE_PATTERNS.
-   * Checked against the reconstructed command string for each segment.
-   */
-  extraDestructive?: RegExp[];
-  /**
-   * Custom predicate to allow specific full commands before normal checks.
-   * Return `true` to allow the command, `false` to continue with normal checks.
-   */
-  allowCommand?: (command: string) => boolean;
-  /**
-   * Whether to allow stdout redirects (`>`, `>>`).
-   * Default: false (blocked).
-   */
-  allowRedirects?: boolean;
-  /**
-   * Whether to allow command substitution ($(...) and backticks).
-   * Default: false (blocked).
-   */
-  allowCommandSubstitution?: boolean;
-}
-/**
- * Check if a shell command is safe to execute in a sandboxed mode.
- *
- * The command is parsed into segments using shell-quote, and each segment
- * is checked independently against the destructive and safe pattern lists.
- * A command is safe only if ALL segments pass.
- *
- * For a segment to pass:
- * 1. It must NOT match any destructive pattern
- * 2. It MUST match at least one safe pattern
- * 3. It must NOT contain redirects (unless explicitly allowed)
- *
- * Additionally, command substitution ($() and backticks) is blocked by default.
- */
-declare function isSafeCommand(command: string, options?: SandboxOptions): boolean;
-//#endregion
-//#region src/parser.d.ts
-/**
- * Shell command parser using shell-quote.
- *
- * Splits a full shell command string into individual command segments,
- * properly handling &&, ||, ;, |, pipes, quotes, and subshells.
- */
-interface ParsedSegment {
-  /** The reconstructed command string for this segment. */
-  command: string;
-  /** Whether this segment contains a redirect operator. */
-  hasRedirect: boolean;
-}
-/**
- * Parse a shell command into individual command segments.
- *
- * Uses shell-quote to properly tokenize the input, then splits on
- * command separators (&&, ||, ;, |). Each segment is returned as a
- * reconstructed command string.
- *
- * Subshell grouping operators `(` and `)` are stripped — the inner
- * commands are still validated individually.
- *
- * @example
- * ```ts
- * parseCommandSegments('cd foo && ls -la')
- * // → [{ command: 'cd foo', hasRedirect: false },
- * //    { command: 'ls -la', hasRedirect: false }]
- *
- * parseCommandSegments('echo "hello && world"')
- * // → [{ command: 'echo "hello && world"', hasRedirect: false }]
- *
- * parseCommandSegments('curl -s url 2>/dev/null | head')
- * // → [{ command: 'curl -s url 2>/dev/null', hasRedirect: false },
- * //    { command: 'head', hasRedirect: false }]
- * ```
- */
-declare function parseCommandSegments(input: string): ParsedSegment[];
-/**
- * Check if the parsed tokens contain command substitution patterns.
- *
- * Command substitution ($(...) or `...`) can hide arbitrary commands
- * and should be blocked in sandboxed modes.
- */
-declare function hasCommandSubstitution(input: string): boolean;
-//#endregion
-//#region src/patterns.d.ts
-/**
- * Destructive and safe command patterns for shell sandboxing.
- *
- * DESTRUCTIVE_PATTERNS — if any segment matches, the command is blocked.
- * SAFE_PATTERNS — a segment must match at least one to be allowed.
- */
-declare const DESTRUCTIVE_PATTERNS: RegExp[];
-declare const SAFE_PATTERNS: RegExp[];
-//#endregion
-export { DESTRUCTIVE_PATTERNS, type ParsedSegment, SAFE_PATTERNS, type SandboxOptions, hasCommandSubstitution, isSafeCommand, parseCommandSegments };