@dreki-gg/pi-plan-mode 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.5.0
+
+### Minor Changes
+
+- [`32797ff`](https://github.com/dreki-gg/pi-extensions/commit/32797ff18d968e22c6c44e95c46e3393d8928cef) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(plan-mode): add Windows compatibility — replace Unix shell commands with cross-platform Bun/Node APIs
+
+  Plan-mode no longer shells out to `cat`, `bash`, or `mkdir` via `pi.exec()`. File I/O now uses `Bun.file()` / `Bun.write()` and `node:fs/promises` `mkdir`, making the extension fully cross-platform. Destructive and safe command pattern lists now include Windows equivalents (`del`, `rd`, `copy`, `move`, `powershell`, `dir`, `where`, `tasklist`, etc.).
+
+  Also fixes Windows compatibility in three other packages:
+
+  - **browser-tools**: `spawn` now uses `shell: true` on Windows so `.cmd` wrappers resolve correctly; `shellEscape` uses double-quote style on Windows; install guidance is platform-aware (Homebrew shown only on macOS).
+  - **subagent**: `spawn` uses `shell: true` on Windows when the command is bare `pi`, allowing `pi.cmd` resolution.
+  - **lsp**: `globalConfigPath()` now uses `os.homedir()` on Windows instead of the unreliable `process.env.HOME`.
+
+## 0.4.0
+
+### Minor Changes
+
+- [`c86c935`](https://github.com/dreki-gg/pi-extensions/commit/c86c9352150a5bed61602243c8164bdd5d679745) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Add plans.json lifecycle tracking and CLI for cleaning completed plans
+
+  - Extension now writes `.plans/plans.json` to track plan status (`in-progress` / `done`) with timestamps and titles
+  - Plans are recorded as `in-progress` when created, marked `done` when all execution steps complete
+  - New `pi-plan-mode clean` CLI (`npx @dreki-gg/pi-plan-mode clean [--dry-run]`) removes completed plan directories while preserving in-flight plans
+  - Cleanup step added to publish.yml workflow to auto-clean done plans on merge to main
+  - Removed stale `docs/plans/` from browser-tools and subagent packages
+
 ## 0.3.1
 
 ### Patch Changes

package/README.md

@@ -67,12 +67,84 @@ When **Execute Plan** is selected:
 
 ```
 .plans/
+├── plans.json                # Tracking manifest — plan status lifecycle
 └── add-auth-middleware/
-    ├── PLAN.md           # Numbered plan with context
-    ├── START-PROMPT.md   # Self-contained executor handoff prompt
-    └── ...               # Optional supporting files
+    ├── PLAN.md               # Numbered plan with context
+    ├── START-PROMPT.md       # Self-contained executor handoff prompt
+    └── ...                   # Optional supporting files
 ```
 
+### plans.json
+
+The extension automatically maintains `.plans/plans.json` to track plan lifecycle:
+
+```json
+{
+  "add-auth-middleware": {
+    "status": "in-progress",
+    "title": "Add Authentication Middleware with JWT Support",
+    "created": "2026-05-08T12:00:00.000Z",
+    "completed": null
+  },
+  "fix-ci-flakes": {
+    "status": "done",
+    "title": "Fix CI Flaky Tests",
+    "created": "2026-05-07T10:00:00.000Z",
+    "completed": "2026-05-07T14:30:00.000Z"
+  }
+}
+```
+
+Plans start as `"in-progress"` when created and are marked `"done"` when all execution steps complete. This prevents accidental deletion of in-flight plans.
+
+## Cleaning completed plans
+
+Use the CLI to remove completed plan directories:
+
+```bash
+# Preview what would be deleted
+npx @dreki-gg/pi-plan-mode clean --dry-run
+
+# Delete completed plans and update plans.json
+npx @dreki-gg/pi-plan-mode clean
+```
+
+In-flight plans (`"status": "in-progress"`) are never touched.
+
+### GitHub Actions
+
+Clean done plans automatically after merge — similar to changesets:
+
+```yaml
+name: Clean Plans
+
+on:
+  push:
+    branches: [main]
+    paths: ['.plans/**']
+
+jobs:
+  clean:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: npx @dreki-gg/pi-plan-mode clean
+      - name: Commit cleanup
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .plans/
+          git diff --cached --quiet || git commit -m "chore: clean completed plans"
+          git push
+```
+
+### Should you gitignore `.plans/`?
+
+**No.** Commit your plans — they provide decision history and execution context. Use the `clean` CLI to remove done plans after merge, keeping the directory lean. Plans are execution blueprints, not permanent documentation; for lasting decisions, use ADRs.
+
 ## Footer indicators
 
 - `📝 plan` — plan mode active (opus-4-6:medium, strict bash)
@@ -81,3 +153,14 @@ When **Execute Plan** is selected:
 ## Bash safety
 
 In plan mode, bash is restricted to read-only commands (ls, grep, git status, cat, rg, etc.). Destructive commands (rm, mv, git commit, etc.) are blocked.
+
+## CLI reference
+
+```
+pi-plan-mode clean [--dry-run]
+```
+
+| Option      | Description                                      |
+| ----------- | ------------------------------------------------ |
+| `clean`     | Remove completed plan directories, update manifest |
+| `--dry-run` | Show what would be deleted without deleting      |

package/bin/clean-plans.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * CLI to clean completed plans from `.plans/`.
+ *
+ * Usage:
+ *   npx @dreki-gg/pi-plan-mode clean [--dry-run]
+ *
+ * Reads `.plans/plans.json`, deletes directories for plans with status "done",
+ * and updates `plans.json` to remove them.
+ *
+ * Designed for use in GitHub Actions after merge — similar to changesets.
+ */
+
+import { readFileSync, writeFileSync, rmSync, readdirSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const PLANS_DIR = '.plans';
+const PLANS_JSON = join(PLANS_DIR, 'plans.json');
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command !== 'clean') {
+    console.error('Usage: pi-plan-mode clean [--dry-run]\n');
+    console.error('Commands:');
+    console.error('  clean       Remove completed plan directories and update plans.json\n');
+    console.error('Options:');
+    console.error('  --dry-run   Show what would be deleted without actually deleting');
+    process.exit(1);
+  }
+
+  const dryRun = args.includes('--dry-run');
+  const plansJsonPath = resolve(PLANS_JSON);
+
+  if (!existsSync(plansJsonPath)) {
+    console.log('No .plans/plans.json found — nothing to clean.');
+    process.exit(0);
+  }
+
+  /** @type {Record<string, { status: string; title: string; created: string; completed: string | null }>} */
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(plansJsonPath, 'utf-8'));
+  } catch (err) {
+    console.error(`Failed to parse ${PLANS_JSON}:`, err);
+    process.exit(1);
+  }
+
+  const donePlans = Object.entries(manifest).filter(([, entry]) => entry.status === 'done');
+  const inFlightPlans = Object.entries(manifest).filter(
+    ([, entry]) => entry.status === 'in-progress',
+  );
+
+  if (donePlans.length === 0) {
+    console.log('No completed plans to clean.');
+    if (inFlightPlans.length > 0) {
+      console.log(`\n${inFlightPlans.length} plan(s) still in progress:`);
+      for (const [name, entry] of inFlightPlans) {
+        console.log(`  ○ ${name} — ${entry.title}`);
+      }
+    }
+    process.exit(0);
+  }
+
+  console.log(dryRun ? 'Dry run — would clean:\n' : 'Cleaning completed plans:\n');
+
+  let cleaned = 0;
+  for (const [name, entry] of donePlans) {
+    const planPath = resolve(join(PLANS_DIR, name));
+    const exists = existsSync(planPath);
+
+    if (dryRun) {
+      console.log(`  ✓ ${name} — ${entry.title}${exists ? '' : ' (directory already missing)'}`);
+    } else {
+      if (exists) {
+        rmSync(planPath, { recursive: true, force: true });
+        console.log(`  ✓ Deleted ${PLANS_DIR}/${name} — ${entry.title}`);
+      } else {
+        console.log(`  ✓ ${name} — directory already missing, removing from manifest`);
+      }
+      delete manifest[name];
+      cleaned++;
+    }
+  }
+
+  if (!dryRun) {
+    const remaining = Object.keys(manifest).length;
+    if (remaining === 0) {
+      rmSync(plansJsonPath, { force: true });
+      // Remove .plans/ if completely empty
+      const plansDir = resolve(PLANS_DIR);
+      try {
+        if (existsSync(plansDir) && readdirSync(plansDir).length === 0) {
+          rmSync(plansDir, { recursive: true, force: true });
+          console.log(`\nRemoved empty ${PLANS_DIR}/`);
+        }
+      } catch {
+        // Directory might have other contents
+      }
+    } else {
+      writeFileSync(plansJsonPath, JSON.stringify(manifest, null, 2) + '\n');
+    }
+
+    console.log(`\nCleaned ${cleaned} plan(s).`);
+    if (remaining > 0) {
+      console.log(`${remaining} plan(s) still in progress.`);
+    }
+  } else {
+    console.log(`\n${donePlans.length} plan(s) would be cleaned.`);
+    if (inFlightPlans.length > 0) {
+      console.log(`${inFlightPlans.length} plan(s) still in progress (will be kept).`);
+    }
+  }
+}
+
+main();

package/extensions/plan-mode/index.ts

@@ -22,12 +22,19 @@ import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { AssistantMessage, TextContent } from '@earendil-works/pi-ai';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { Key } from '@earendil-works/pi-tui';
+import { mkdir } from 'node:fs/promises';
 import {
   extractTodoItems,
   isSafeCommand,
   markCompletedSteps,
   type TodoItem,
 } from './utils.js';
+import {
+  extractPlanTitle,
+  readPlansJson,
+  serializePlansJson,
+  type PlansManifest,
+} from './plans-json.js';
 
 // ── Tool sets ────────────────────────────────────────────────────────────────
 // Plan phase: read-only + edit/write (for .plans/ files only, enforced by prompt)
@@ -99,6 +106,28 @@ export default function planMode(pi: ExtensionAPI): void {
     });
   }
 
+  // ── plans.json tracking ───────────────────────────────────────────────────
+  async function updatePlansManifest(
+    planName: string,
+    status: 'in-progress' | 'done',
+    title?: string,
+  ): Promise<void> {
+    const manifest = await readPlansJson();
+    const existing = manifest[planName];
+    const now = new Date().toISOString();
+
+    manifest[planName] = {
+      status,
+      title: title ?? existing?.title ?? 'Untitled plan',
+      created: existing?.created ?? now,
+      completed: status === 'done' ? now : null,
+    };
+
+    await mkdir('.plans', { recursive: true });
+    const content = serializePlansJson(manifest);
+    await Bun.write('.plans/plans.json', content);
+  }
+
   // ── UI updates ────────────────────────────────────────────────────────────
   function updateUI(ctx: ExtensionContext): void {
     const { theme } = ctx.ui;
@@ -384,7 +413,29 @@ Execute each step in order. You MUST include [DONE:n] in your response after com
     const match = path.match(/\.plans\/([^/]+)\//);
     if (match && !planDir) {
       planDir = `.plans/${match[1]}`;
+      const planName = match[1];
+
+      // Read PLAN.md to extract the title for plans.json
+      let title = 'Untitled plan';
+      if (path.endsWith('PLAN.md')) {
+        try {
+          const content = await Bun.file(path).text();
+          title = extractPlanTitle(content);
+        } catch {
+          // Fall through
+        }
+      }
+      await updatePlansManifest(planName, 'in-progress', title);
       persist();
+    } else if (match && planDir && path.endsWith('PLAN.md')) {
+      // planDir already set but PLAN.md just written — update title
+      try {
+        const content = await Bun.file(path).text();
+        const title = extractPlanTitle(content);
+        await updatePlansManifest(match[1], 'in-progress', title);
+      } catch {
+        // Fall through
+      }
     }
   });
 
@@ -393,6 +444,12 @@ Execute each step in order. You MUST include [DONE:n] in your response after com
     // Check execution completion
     if (executing && todos.length > 0) {
       if (todos.every((t) => t.completed)) {
+        // Mark plan as done in plans.json
+        if (planDir) {
+          const planName = planDir.replace(/^\.plans\//, '');
+          await updatePlansManifest(planName, 'done');
+        }
+
         const list = todos.map((t) => `~~${t.text}~~`).join('\n');
         pi.sendMessage(
           {
@@ -439,10 +496,7 @@ Execute each step in order. You MUST include [DONE:n] in your response after com
       // Read the plan to extract todos
       let planContent = '';
       try {
-        const result = await pi.exec('cat', [planMdPath]);
-        if (result.code === 0) {
-          planContent = result.stdout;
-        }
+        planContent = await Bun.file(planMdPath).text();
       } catch {
         // Fall through — will use empty plan content
       }
@@ -455,10 +509,7 @@ Execute each step in order. You MUST include [DONE:n] in your response after com
       // Read the start prompt for clean handoff
       let startPrompt = '';
       try {
-        const result = await pi.exec('cat', [startPromptPath]);
-        if (result.code === 0) {
-          startPrompt = result.stdout.trim();
-        }
+        startPrompt = (await Bun.file(startPromptPath).text()).trim();
       } catch {
         // Fall through
       }

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

@@ -0,0 +1,53 @@
+/**
+ * Reads and writes `.plans/plans.json` — the tracking manifest for plan lifecycle.
+ *
+ * Schema:
+ * ```json
+ * {
+ *   "<plan-name>": {
+ *     "status": "in-progress" | "done",
+ *     "title": "Human-readable plan title",
+ *     "created": "2026-05-08T12:00:00.000Z",
+ *     "completed": "2026-05-08T13:00:00.000Z" | null
+ *   }
+ * }
+ * ```
+ */
+
+export interface PlanEntry {
+  status: 'in-progress' | 'done';
+  title: string;
+  created: string;
+  completed: string | null;
+}
+
+export type PlansManifest = Record<string, PlanEntry>;
+
+const PLANS_JSON = '.plans/plans.json';
+
+/** Read plans.json, returning current manifest (empty object if missing). */
+export async function readPlansJson(): Promise<PlansManifest> {
+  try {
+    const file = Bun.file(PLANS_JSON);
+    if (await file.exists()) {
+      const text = await file.text();
+      if (text.trim()) {
+        return JSON.parse(text) as PlansManifest;
+      }
+    }
+  } catch {
+    // File doesn't exist or isn't valid JSON
+  }
+  return {};
+}
+
+/** Serialize the manifest to a formatted JSON string. */
+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/utils.ts

@@ -43,6 +43,17 @@ const DESTRUCTIVE_PATTERNS = [
   /\bsystemctl\s+(start|stop|restart|enable|disable)/i,
   /\bservice\s+\S+\s+(start|stop|restart)/i,
   /\b(vim?|nano|emacs|code|subl)\b/i,
+  // Windows equivalents
+  /\bdel\b/i,
+  /\brd\b/i,
+  /\bcopy\b/i,
+  /\bmove\b/i,
+  /\bren\b/i,
+  /\brename\b/i,
+  /\bicacls\b/i,
+  /\battrib\b/i,
+  /\bpowershell\b/i,
+  /\bpwsh\b/i,
 ];
 
 // ── Safe read-only bash patterns (allowed in plan mode) ─────────────────────
@@ -98,6 +109,12 @@ const SAFE_PATTERNS = [
   /^\s*fd\b/,
   /^\s*bat\b/,
   /^\s*eza\b/,
+  // Windows equivalents
+  /^\s*dir\b/,
+  /^\s*where\b/,
+  /^\s*set\b/,
+  /^\s*systeminfo\b/,
+  /^\s*tasklist\b/,
 ];
 
 export function isSafeCommand(command: string): boolean {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "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"
@@ -13,17 +13,21 @@
     "directory": "packages/plan-mode"
   },
   "type": "module",
+  "bin": {
+    "pi-plan-mode": "./bin/clean-plans.js"
+  },
   "files": [
     "extensions",
+    "bin",
     "README.md",
     "CHANGELOG.md",
     "package.json"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint extensions",
-    "format": "oxfmt --write extensions",
-    "format:check": "oxfmt --check extensions"
+    "lint": "oxlint extensions bin",
+    "format": "oxfmt --write extensions bin",
+    "format:check": "oxfmt --check extensions bin"
   },
   "pi": {
     "extensions": [
@@ -32,6 +36,7 @@
   },
   "devDependencies": {
     "@types/node": "24",
+    "bun-types": "latest",
     "oxfmt": "^0.43.0",
     "oxlint": "^1.58.0",
     "typescript": "^6.0.0"