plan-review 0.1.1 → 1.0.0

package/dist/session.js

@@ -0,0 +1,133 @@
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, unlinkSync, readdirSync, existsSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+// ── Internal helpers (not exported) ────────────────────────────────
+function pathHash(planPath) {
+    const abs = resolve(planPath);
+    const hash = createHash('sha256').update(abs).digest('hex');
+    return hash.slice(0, 16);
+}
+function sessionFilePath(planPath) {
+    return join(getSessionDir(), pathHash(planPath) + '.json');
+}
+// ── Exported functions ─────────────────────────────────────────────
+export function getSessionDir() {
+    const dir = join(homedir(), '.plan-review', 'sessions');
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function computeContentHash(content) {
+    const hex = createHash('sha256').update(content).digest('hex');
+    return `sha256:${hex}`;
+}
+export function saveSession(planPath, contentHash, comments, activeSection) {
+    try {
+        const data = {
+            version: 1,
+            planPath,
+            contentHash,
+            comments,
+            activeSection,
+            lastModified: new Date().toISOString(),
+        };
+        const filePath = sessionFilePath(planPath);
+        writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch (err) {
+        console.warn(`[plan-review] Failed to save session: ${err.message}`);
+    }
+}
+export function loadSession(planPath, currentContentHash) {
+    const filePath = sessionFilePath(planPath);
+    if (!existsSync(filePath)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        console.warn(`[plan-review] Corrupt session file, removing: ${filePath}`);
+        try {
+            unlinkSync(filePath);
+        }
+        catch {
+            // ignore
+        }
+        return null;
+    }
+    // Restore Date objects in comment timestamps
+    const comments = data.comments.map((c) => ({
+        ...c,
+        timestamp: new Date(c.timestamp),
+    }));
+    return {
+        comments,
+        activeSection: data.activeSection,
+        stale: data.contentHash !== currentContentHash,
+    };
+}
+export function clearSession(planPath) {
+    const filePath = sessionFilePath(planPath);
+    try {
+        unlinkSync(filePath);
+    }
+    catch {
+        // No error if missing
+    }
+}
+export function listSessions() {
+    const dir = getSessionDir();
+    let files;
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        const filePath = join(dir, file);
+        let data;
+        try {
+            const raw = readFileSync(filePath, 'utf-8');
+            data = JSON.parse(raw);
+        }
+        catch {
+            console.warn(`[plan-review] Skipping corrupt session file: ${filePath}`);
+            continue;
+        }
+        let stale;
+        if (!existsSync(data.planPath)) {
+            stale = null;
+        }
+        else {
+            try {
+                const currentContent = readFileSync(data.planPath, 'utf-8');
+                const currentHash = computeContentHash(currentContent);
+                stale = currentHash !== data.contentHash;
+            }
+            catch {
+                stale = null;
+            }
+        }
+        results.push({
+            planPath: data.planPath,
+            commentCount: data.comments.length,
+            lastModified: data.lastModified,
+            stale,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,22 @@
+import type { PlanDocument, ReviewComment } from './types.js';
+export interface Transport {
+    sendDocument(doc: PlanDocument): void;
+    onReviewSubmit(handler: (comments: ReviewComment[]) => void): void;
+    start(port: number): Promise<{
+        url: string;
+    }>;
+    stop(): Promise<void>;
+}
+export declare class HttpTransport implements Transport {
+    private doc;
+    private submitHandler;
+    private sessionSaveHandler;
+    private server;
+    sendDocument(doc: PlanDocument): void;
+    onReviewSubmit(handler: (comments: ReviewComment[]) => void): void;
+    onSessionSave(handler: (comments: ReviewComment[], activeSection: string | null) => void): void;
+    start(port: number): Promise<{
+        url: string;
+    }>;
+    stop(): Promise<void>;
+}

package/dist/transport.js

@@ -0,0 +1,35 @@
+import { createReviewServer, startServer, stopServer } from './server/server.js';
+import { getAssetHtml } from './server/assets.js';
+export class HttpTransport {
+    doc = null;
+    submitHandler = null;
+    sessionSaveHandler = null;
+    server = null;
+    sendDocument(doc) {
+        this.doc = doc;
+    }
+    onReviewSubmit(handler) {
+        this.submitHandler = handler;
+    }
+    onSessionSave(handler) {
+        this.sessionSaveHandler = handler;
+    }
+    async start(port) {
+        if (!this.doc)
+            throw new Error('No document set');
+        this.server = createReviewServer({
+            getDocument: () => this.doc,
+            onSubmit: (comments) => this.submitHandler?.(comments),
+            getAssetHtml: () => getAssetHtml(),
+            onSessionSave: (comments, activeSection) => this.sessionSaveHandler?.(comments, activeSection),
+        });
+        return startServer(this.server, port);
+    }
+    async stop() {
+        if (this.server && this.server.listening) {
+            await stopServer(this.server);
+            this.server = null;
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AASlD,MAAM,OAAO,aAAa;IAChB,GAAG,GAAwB,IAAI,CAAC;IAChC,aAAa,GAAiD,IAAI,CAAC;IACnE,kBAAkB,GAA+E,IAAI,CAAC;IACtG,MAAM,GAAkB,IAAI,CAAC;IAErC,YAAY,CAAC,GAAiB;QAC5B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED,cAAc,CAAC,OAA4C;QACzD,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;IAC/B,CAAC;IAED,aAAa,CAAC,OAA0E;QACtF,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,IAAI,CAAC,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAElD,IAAI,CAAC,MAAM,GAAG,kBAAkB,CAAC;YAC/B,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAI;YAC5B,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC,QAAQ,CAAC;YACtD,YAAY,EAAE,GAAG,EAAE,CAAC,YAAY,EAAE;YAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,QAAQ,EAAE,aAAa,CAAC;SAC/F,CAAC,CAAC;QAEH,OAAO,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACzC,MAAM,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}

package/dist/types.d.ts

@@ -18,10 +18,17 @@ export interface Section {
     relatedFiles?: string[];
     verification?: string;
 }
+export interface LineAnchor {
+    type: 'lines';
+    startLine: number;
+    endLine: number;
+    lineTexts: string[];
+}
 export interface ReviewComment {
     sectionId: string;
     text: string;
     timestamp: Date;
+    anchor?: LineAnchor;
 }
 export type OutputTarget = 'stdout' | 'clipboard' | 'file' | 'claude';
 export type SplitStrategy = 'heading' | 'separator' | 'auto';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan-review",
-  "version": "0.1.1",
+  "version": "1.0.0",
   "description": "Interactive CLI for reviewing AI-generated markdown plans",
   "type": "module",
   "main": "dist/index.js",
@@ -8,10 +8,13 @@
     "plan-review": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc --project tsconfig.browser.json --noEmit && node scripts/build-browser.js",
+    "build:browser": "node scripts/build-browser.js",
+    "dev:browser": "node scripts/build-browser.js --watch",
     "dev": "tsx src/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -32,8 +35,12 @@
     "marked-terminal": "^7.3.0"
   },
   "devDependencies": {
+    "@testing-library/preact": "^3.2.4",
+    "preact": "^10.29.1",
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
+    "esbuild": "^0.28.0",
+    "jsdom": "^29.0.2",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.4"

package/skills/plan-review/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: plan-review
+description: Use when the user asks to review a plan, start plan review, or says "I want to review this plan". Triggers on plan review requests for markdown implementation plans, specs, or design docs. Builds and runs the plan-review browser UI, feeds review output back into the conversation.
+---
+
+# Plan Review
+
+Launch the plan-review browser UI for interactive review of markdown plans, then feed the structured review output back into this session.
+
+## Prerequisites
+
+The `plan-review` CLI must be installed or available at `~/desenv/personal/plan-review/`. If not built, run `npm run build` first.
+
+## Process
+
+1. **Identify the plan file.** If the user specified a file, use it. If not, look for the most recent file matching `docs/superpowers/plans/*.md` in the current working directory. If multiple candidates exist, ask which one.
+
+2. **Build if needed.** Check if `dist/index.js` exists in the plan-review project. If not:
+   ```bash
+   cd ~/desenv/personal/plan-review && npm run build
+   ```
+
+3. **Run the review.** Launch in browser mode with stdout output:
+   ```bash
+   node ~/desenv/personal/plan-review/dist/index.js <plan-file> --browser -o stdout
+   ```
+   This opens the browser review UI. The command blocks until the user submits their review, then prints structured review output to stdout.
+
+4. **Read the output.** The review output is structured markdown with the user's comments anchored to specific sections. Read it and present a summary to the user.
+
+5. **Act on feedback.** Ask the user what they want to do with the review:
+   - Address the comments (modify the plan or code)
+   - Save the review to a file
+   - Continue discussion about specific comments
+
+## Important
+
+- The `--browser` flag opens a three-panel review UI (TOC + content + comments).
+- The `-o stdout` flag ensures the review output comes back to this session.
+- The command will block until the user clicks "Submit Review" in the browser.
+- If the user has an existing session for this plan, they'll be prompted to resume.
+- Use `--fresh` flag if the user explicitly wants to start a clean review.