@dreki-gg/pi-plan-mode 0.15.1 → 0.17.0

package/extensions/plan-mode/__tests__/task-storage.test.ts

@@ -1,10 +1,26 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Cause, Effect, Exit, Option } from 'effect';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
 import { readTasksJsonl, updateTask, writeTasksJsonl } from '../storage/task-storage.js';
 import type { TaskMeta, TaskRecord } from '../types.js';
 
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const runExit = <A, E>(program: Effect.Effect<A, E, FileSystem>) =>
+  Effect.runPromiseExit(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const failureTag = <A, E>(exit: Exit.Exit<A, E>): string | undefined => {
+  if (!Exit.isFailure(exit)) return undefined;
+  const error = Option.getOrUndefined(Cause.failureOption(exit.cause)) as
+    | { _tag?: string }
+    | undefined;
+  return error?._tag;
+};
+
 let dir: string;
 const now = '2026-05-27T12:00:00.000Z';
 const meta: TaskMeta = { _type: 'meta', title: 'Plan', plan_name: 'plan', created_at: now };
@@ -27,8 +43,8 @@ afterEach(async () => {
 
 describe('tasks.jsonl storage', () => {
   test('round trips meta and tasks', async () => {
-    await writeTasksJsonl(dir, meta, [task]);
-    await expect(readTasksJsonl(dir)).resolves.toEqual({ meta, tasks: [task] });
+    await run(writeTasksJsonl(dir, meta, [task]));
+    await expect(run(readTasksJsonl(dir))).resolves.toEqual({ meta, tasks: [task] });
   });
 
   test('round trips tasks without details (lightweight checklist)', async () => {
@@ -40,32 +56,39 @@ describe('tasks.jsonl storage', () => {
       created_at: now,
       updated_at: now,
     };
-    await writeTasksJsonl(dir, meta, [lightweight]);
-    const result = await readTasksJsonl(dir);
+    await run(writeTasksJsonl(dir, meta, [lightweight]));
+    const result = await run(readTasksJsonl(dir));
     expect(result?.tasks[0]?.id).toBe('t-002');
     expect(result?.tasks[0]?.details).toBeUndefined();
   });
 
   test('missing file returns undefined', async () => {
-    await expect(readTasksJsonl(dir)).resolves.toBeUndefined();
+    await expect(run(readTasksJsonl(dir))).resolves.toBeUndefined();
   });
 
-  test('rejects corrupt lines', async () => {
+  test('rejects corrupt lines with JsonlParseError', async () => {
     await Bun.write(join(dir, 'tasks.jsonl'), `${JSON.stringify(meta)}\nnot-json\n`);
-    await expect(readTasksJsonl(dir)).rejects.toThrow(/Invalid JSONL/);
+    expect(failureTag(await runExit(readTasksJsonl(dir)))).toBe('JsonlParseError');
   });
 
-  test('rejects empty files', async () => {
+  test('rejects empty files with MissingMetaRecord', async () => {
     await Bun.write(join(dir, 'tasks.jsonl'), '');
-    await expect(readTasksJsonl(dir)).rejects.toThrow(/meta/);
+    expect(failureTag(await runExit(readTasksJsonl(dir)))).toBe('MissingMetaRecord');
   });
 
   test('updates a task by id and rewrites the snapshot', async () => {
-    await writeTasksJsonl(dir, meta, [task]);
-    const updated = await updateTask(dir, 't-001', { status: 'done', notes: 'finished' });
+    await run(writeTasksJsonl(dir, meta, [task]));
+    const updated = await run(updateTask(dir, 't-001', { status: 'done', notes: 'finished' }));
 
     expect(updated.status).toBe('done');
     expect(updated.notes).toBe('finished');
-    expect((await readTasksJsonl(dir))?.tasks[0]?.status).toBe('done');
+    expect((await run(readTasksJsonl(dir)))?.tasks[0]?.status).toBe('done');
+  });
+
+  test('fails with TaskNotFound for an unknown task id', async () => {
+    await run(writeTasksJsonl(dir, meta, [task]));
+    expect(failureTag(await runExit(updateTask(dir, 't-999', { status: 'done' })))).toBe(
+      'TaskNotFound',
+    );
   });
 });

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

@@ -1,5 +1,23 @@
 import { describe, expect, test } from 'bun:test';
-import { isSafeCommand, isPlanPath } from '../utils.js';
+import { isSafeCommand, isPlanPath, nextTaskId } from '../utils.js';
+
+describe('nextTaskId', () => {
+  test('increments the max numeric suffix', () => {
+    expect(nextTaskId(['t-001', 't-002', 't-003'])).toBe('t-004');
+  });
+
+  test('uses the max even when ids are unordered or sparse', () => {
+    expect(nextTaskId(['t-003', 't-001', 't-010'])).toBe('t-011');
+  });
+
+  test('starts at t-001 for an empty plan', () => {
+    expect(nextTaskId([])).toBe('t-001');
+  });
+
+  test('falls back to count+1 when no ids match the pattern', () => {
+    expect(nextTaskId(['setup', 'cleanup'])).toBe('t-003');
+  });
+});
 
 describe('isSafeCommand', () => {
   // ── Commands that SHOULD be allowed ──────────────────────────────────────

package/extensions/plan-mode/constants.ts

@@ -10,13 +10,14 @@ export const PLAN_TOOLS = [
   'find',
   'ls',
   'submit_plan',
+  'preview_prototype',
   'write',
   'questionnaire',
   'search_skills',
   'subagent',
 ];
 
-export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_task'];
+export const EXEC_TOOLS = ['read', 'bash', 'edit', 'write', 'update_task', 'add_task'];
 
 // ── Model + thinking presets ─────────────────────────────────────────────────
 export const PLAN_MODEL = { provider: 'anthropic', id: 'claude-opus-4-6' } as const;

package/extensions/plan-mode/effects/filesystem.ts

@@ -0,0 +1,65 @@
+/**
+ * FileSystem service — the single seam for plan-mode disk I/O.
+ *
+ * Storage programs depend on this `Context.Tag` rather than touching
+ * `node:fs/promises` directly, which makes them trivially testable and keeps
+ * all failure modes typed (`PlanReadError` / `PlanWriteError`).
+ */
+
+import { Context, Effect } from 'effect';
+import { mkdir, readFile, readdir, unlink, writeFile } from 'node:fs/promises';
+import { PlanReadError, PlanWriteError } from '../errors.js';
+import { writeFileAtomic } from '../storage/atomic-write.js';
+
+export interface FileSystemService {
+  readonly readFileString: (path: string) => Effect.Effect<string, PlanReadError>;
+  readonly writeFileString: (path: string, data: string) => Effect.Effect<void, PlanWriteError>;
+  readonly writeFileAtomic: (path: string, data: string) => Effect.Effect<void, PlanWriteError>;
+  readonly makeDir: (path: string) => Effect.Effect<void, PlanWriteError>;
+  readonly listDirectories: (path: string) => Effect.Effect<string[], PlanReadError>;
+  readonly removeFile: (path: string) => Effect.Effect<void, PlanWriteError>;
+}
+
+export class FileSystem extends Context.Tag('PlanMode/FileSystem')<
+  FileSystem,
+  FileSystemService
+>() {}
+
+export const nodeFileSystemService: FileSystemService = {
+  readFileString: (path) =>
+    Effect.tryPromise({
+      try: () => readFile(path, 'utf-8'),
+      catch: (cause) => new PlanReadError({ path, cause }),
+    }),
+
+  writeFileString: (path, data) =>
+    Effect.tryPromise({
+      try: () => writeFile(path, data, 'utf-8'),
+      catch: (cause) => new PlanWriteError({ path, cause }),
+    }),
+
+  writeFileAtomic: (path, data) => writeFileAtomic(path, data),
+
+  makeDir: (path) =>
+    Effect.tryPromise({
+      try: async () => {
+        await mkdir(path, { recursive: true });
+      },
+      catch: (cause) => new PlanWriteError({ path, cause }),
+    }),
+
+  listDirectories: (path) =>
+    Effect.tryPromise({
+      try: async () => {
+        const entries = await readdir(path, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+      },
+      catch: (cause) => new PlanReadError({ path, cause }),
+    }),
+
+  removeFile: (path) =>
+    Effect.tryPromise({
+      try: () => unlink(path),
+      catch: (cause) => new PlanWriteError({ path, cause }),
+    }),
+};

package/extensions/plan-mode/effects/runtime.ts

@@ -0,0 +1,24 @@
+/**
+ * Live Effect runtime for the plan-mode extension.
+ *
+ * Build the layer once inside the extension entry and run storage programs
+ * through the `runPlanIO` bridge so the imperative pi event handlers keep their
+ * `await fn(...)` shape.
+ */
+
+import { Effect, Layer } from 'effect';
+import { FileSystem, nodeFileSystemService } from './filesystem.js';
+
+export function makeRuntimeLayer(): Layer.Layer<FileSystem> {
+  return Layer.succeed(FileSystem, nodeFileSystemService);
+}
+
+/** Build a bridge that runs storage programs against the live filesystem layer. */
+export function makePlanRuntime() {
+  const layer = makeRuntimeLayer();
+  return function runPlanIO<A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> {
+    return Effect.runPromise(program.pipe(Effect.provide(layer)));
+  };
+}
+
+export type RunPlanIO = ReturnType<typeof makePlanRuntime>;

package/extensions/plan-mode/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Tagged errors for plan-mode disk I/O and JSONL validation.
+ *
+ * These replace ad-hoc `throw new Error(...)` so storage programs surface
+ * typed, inspectable failures. They are mapped back to user-facing strings at
+ * the tool boundary via `errorMessage`.
+ */
+
+import { Data } from 'effect';
+
+export class PlanReadError extends Data.TaggedError('PlanReadError')<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Failed to read ${this.path}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class PlanWriteError extends Data.TaggedError('PlanWriteError')<{
+  readonly path: string;
+  readonly cause: unknown;
+}> {
+  get message(): string {
+    return `Failed to write ${this.path}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class JsonlParseError extends Data.TaggedError('JsonlParseError')<{
+  readonly path: string;
+  readonly line: number;
+  readonly cause?: unknown;
+}> {
+  get message(): string {
+    return `Invalid JSONL in ${this.path} at line ${this.line}: ${causeMessage(this.cause)}`;
+  }
+}
+
+export class JsonlValidationError extends Data.TaggedError('JsonlValidationError')<{
+  readonly path: string;
+  readonly line: number;
+  readonly reason: string;
+}> {
+  get message(): string {
+    return `Invalid record in ${this.path} at line ${this.line}: ${this.reason}`;
+  }
+}
+
+export class MissingMetaRecord extends Data.TaggedError('MissingMetaRecord')<{
+  readonly path: string;
+}> {
+  get message(): string {
+    return `${this.path} is missing meta record`;
+  }
+}
+
+export class TaskNotFound extends Data.TaggedError('TaskNotFound')<{
+  readonly planDir: string;
+  readonly taskId: string;
+}> {
+  get message(): string {
+    return `Task not found: ${this.taskId}`;
+  }
+}
+
+export class TasksFileNotFound extends Data.TaggedError('TasksFileNotFound')<{
+  readonly planDir: string;
+}> {
+  get message(): string {
+    return `No tasks.jsonl found in ${this.planDir}`;
+  }
+}
+
+export type PlanStorageError =
+  | PlanReadError
+  | PlanWriteError
+  | JsonlParseError
+  | JsonlValidationError
+  | MissingMetaRecord
+  | TaskNotFound
+  | TasksFileNotFound;
+
+export function causeMessage(cause: unknown): string {
+  if (cause instanceof Error) return cause.message;
+  return String(cause);
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string') return message;
+  }
+  return String(error);
+}
+
+/** Convert any error (including tagged errors) into a native Error for the tool boundary. */
+export function toNativeError(error: unknown): Error {
+  if (error instanceof Error) return error;
+  const native = new Error(errorMessage(error));
+  if (typeof error === 'object' && error !== null && '_tag' in error) {
+    native.name = String((error as { _tag: unknown })._tag);
+  }
+  return native;
+}

package/extensions/plan-mode/html/render.ts

@@ -2,127 +2,23 @@ import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import pug from 'pug';
-import type { PlanData } from '../types.js';
 
-const templatePath = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'plan.pug');
+const templatePath = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'prototype.pug');
 
-export function renderPlanHtml(plan: PlanData, prototype?: string): string {
+/**
+ * Renders a standalone prototype preview: a minimal header (title + one-line
+ * intent) wrapping the rendered Pug body. This is a planning-phase visual aid,
+ * not a plan dump — no tasks, no handoff.
+ */
+export function renderPrototypeHtml(title: string, intent: string, pugBody: string): string {
   const template = readFileSync(templatePath, 'utf8');
-  const prototypeHtml = prototype?.trim() ? pug.render(prototype) : undefined;
+  const prototypeHtml = pugBody.trim() ? pug.render(pugBody) : '';
 
   return pug.render(template, {
     filename: templatePath,
-    plan,
+    title,
+    intent,
     prototypeHtml,
-    handoffHtml: markdownToHtml(plan.handoff),
-    taskCountLabel: `${plan.tasks.length} ${plan.tasks.length === 1 ? 'task' : 'tasks'}`,
     generatedAt: new Date().toISOString(),
   });
 }
-
-function markdownToHtml(markdown: string): string {
-  const lines = markdown.split(/\r?\n/);
-  const html: string[] = [];
-  let inList = false;
-  let inCode = false;
-  let codeLang = '';
-  const codeLines: string[] = [];
-
-  for (const line of lines) {
-    // Fenced code blocks
-    if (line.startsWith('```')) {
-      if (!inCode) {
-        if (inList) {
-          html.push('</ul>');
-          inList = false;
-        }
-        inCode = true;
-        codeLang = line.slice(3).trim();
-        codeLines.length = 0;
-      } else {
-        const langAttr = codeLang ? ` class="language-${escapeHtml(codeLang)}"` : '';
-        html.push(`<pre><code${langAttr}>${codeLines.map(escapeHtml).join('\n')}</code></pre>`);
-        inCode = false;
-        codeLang = '';
-      }
-      continue;
-    }
-
-    if (inCode) {
-      codeLines.push(line);
-      continue;
-    }
-
-    // Headings
-    const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
-    if (headingMatch) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
-      }
-      const level = headingMatch[1].length;
-      html.push(`<h${level}>${inlineMarkdown(escapeHtml(headingMatch[2]))}</h${level}>`);
-      continue;
-    }
-
-    // List items (- or *)
-    const listMatch = line.match(/^\s*[-*]\s+(.*)$/);
-    if (listMatch) {
-      if (!inList) {
-        html.push('<ul>');
-        inList = true;
-      }
-      html.push(`<li>${inlineMarkdown(escapeHtml(listMatch[1]))}</li>`);
-      continue;
-    }
-
-    // Blank line
-    if (!line.trim()) {
-      if (inList) {
-        html.push('</ul>');
-        inList = false;
-      }
-      continue;
-    }
-
-    // Paragraph
-    if (inList) {
-      html.push('</ul>');
-      inList = false;
-    }
-    html.push(`<p>${inlineMarkdown(escapeHtml(line))}</p>`);
-  }
-
-  // Close unclosed blocks
-  if (inCode) {
-    html.push(`<pre><code>${codeLines.map(escapeHtml).join('\n')}</code></pre>`);
-  }
-  if (inList) html.push('</ul>');
-  return html.join('\n');
-}
-
-/** Converts inline markdown (bold, italic, inline code, links) in already-escaped HTML. */
-function inlineMarkdown(text: string): string {
-  return (
-    text
-      // Inline code: `code`
-      .replace(/`([^`]+)`/g, '<code>$1</code>')
-      // Bold: **text** or __text__
-      .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
-      .replace(/__(.+?)__/g, '<strong>$1</strong>')
-      // Italic: *text* or _text_
-      .replace(/\*(.+?)\*/g, '<em>$1</em>')
-      .replace(/_(.+?)_/g, '<em>$1</em>')
-      // Links: [text](url)
-      .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>')
-  );
-}
-
-function escapeHtml(value: string): string {
-  return value
-    .replaceAll('&', '&amp;')
-    .replaceAll('<', '&lt;')
-    .replaceAll('>', '&gt;')
-    .replaceAll('"', '&quot;')
-    .replaceAll("'", '&#39;');
-}

package/extensions/plan-mode/html/templates/prototype.pug

@@ -0,0 +1,25 @@
+doctype html
+html(lang="en")
+  head
+    meta(charset="utf-8")
+    meta(name="viewport" content="width=device-width, initial-scale=1")
+    title= title
+    style.
+      :root { color-scheme: dark; --bg:#0b0d12; --panel:#11141b; --muted:#8b93a7; --text:#eef1f7; --line:#242936; --accent:#8b5cf6; }
+      * { box-sizing: border-box; }
+      body { margin:0; background:radial-gradient(circle at top left,#1c1730,transparent 34rem),var(--bg); color:var(--text); font:14px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+      main { width:min(1040px, calc(100% - 48px)); margin:48px auto; }
+      header { margin-bottom:24px; }
+      h1 { font-size:30px; line-height:1.1; margin:0 0 8px; letter-spacing:-0.04em; }
+      .intent { color:var(--muted); margin:0; }
+      .badge { display:inline-block; border:1px solid var(--line); border-radius:999px; padding:5px 10px; background:rgba(255,255,255,0.03); color:var(--muted); font-size:12px; margin-bottom:14px; }
+      .prototype { background:rgba(17,20,27,0.82); border:1px solid var(--line); border-radius:18px; padding:22px; box-shadow:0 24px 80px rgba(0,0,0,0.24); }
+  body
+    main
+      header
+        span.badge Prototype · #{generatedAt}
+        h1= title
+        if intent
+          p.intent= intent
+      section.prototype
+        != prototypeHtml