gigaplan 0.1.0

package/dist/server.js

@@ -0,0 +1,160 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import express from "express";
+import chokidar from "chokidar";
+import { parseBlocks, reconcileBlocks } from "./markdown.js";
+import { renderSessionPage } from "./render.js";
+import * as sessionStore from "./session-store.js";
+import * as reviewStore from "./review-store.js";
+import { PORT, LONG_POLL_TIMEOUT_MS, IDLE_TIMEOUT_MS } from "./paths.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const watchers = new Map();
+const sseClients = new Map();
+function watchPlan(planPath) {
+    if (watchers.has(planPath))
+        return;
+    let debounceTimer;
+    const watcher = chokidar.watch(planPath, { ignoreInitial: true });
+    watcher.on("change", () => {
+        if (debounceTimer)
+            clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            try {
+                const source = fs.readFileSync(planPath, "utf8");
+                const freshBlocks = parseBlocks(source);
+                const oldBlocks = reviewStore.getBlocks(planPath);
+                const result = reconcileBlocks(oldBlocks, freshBlocks);
+                reviewStore.applyReconciliation(planPath, result);
+                notifySse(planPath);
+            }
+            catch {
+                // The plan file may be transiently unreadable mid-write (editors that
+                // truncate-then-write); the next change event will settle it.
+            }
+        }, 150);
+    });
+    watchers.set(planPath, watcher);
+}
+function notifySse(planPath) {
+    const clients = sseClients.get(planPath) ?? [];
+    for (const res of clients) {
+        res.write("event: changed\ndata: {}\n\n");
+    }
+}
+export function createApp() {
+    const app = express();
+    app.use(express.json());
+    app.use("/public", express.static(path.join(__dirname, "..", "public")));
+    let idleTimer;
+    const onIdleTimeout = () => {
+        sessionStore.clearServerLock();
+        process.exit(0);
+    };
+    app.use((_req, _res, next) => {
+        if (idleTimer)
+            clearTimeout(idleTimer);
+        idleTimer = setTimeout(onIdleTimeout, IDLE_TIMEOUT_MS);
+        next();
+    });
+    app.post("/api/sessions", (req, res) => {
+        const { planPath } = req.body;
+        if (!planPath) {
+            res.status(400).json({ error: "planPath is required" });
+            return;
+        }
+        if (!fs.existsSync(planPath)) {
+            res.status(404).json({ error: `plan file not found: ${planPath}` });
+            return;
+        }
+        sessionStore.createOrReopenSession(planPath);
+        const source = fs.readFileSync(planPath, "utf8");
+        reviewStore.setBlocks(planPath, parseBlocks(source));
+        watchPlan(planPath);
+        const sessionKey = encodeURIComponent(planPath);
+        res.json({ sessionKey: planPath, url: `http://127.0.0.1:${PORT}/session/${sessionKey}` });
+    });
+    app.get("/session/:key", (req, res) => {
+        const planPath = req.params.key;
+        const session = sessionStore.getSession(planPath);
+        if (!session) {
+            res
+                .status(404)
+                .send("No gigaplan session for this plan file. Run `gigaplan review <path>` first.");
+            return;
+        }
+        const blocks = reviewStore.getBlocks(planPath);
+        res.type("html").send(renderSessionPage(planPath, planPath, blocks));
+    });
+    app.get("/api/sessions/:key/blocks", (req, res) => {
+        const planPath = req.params.key;
+        const blocks = reviewStore.getBlocks(planPath);
+        const recon = reviewStore.getLastReconciliation(planPath);
+        res.json({
+            blocks,
+            stale: Array.from(recon.stale.entries()).map(([id, previousExcerpt]) => ({
+                id,
+                previousExcerpt,
+            })),
+            orphaned: recon.orphaned,
+        });
+    });
+    app.get("/api/sessions/:key/events", (req, res) => {
+        const planPath = req.params.key;
+        res.writeHead(200, {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            Connection: "keep-alive",
+        });
+        res.write("\n");
+        const list = sseClients.get(planPath) ?? [];
+        list.push(res);
+        sseClients.set(planPath, list);
+        req.on("close", () => {
+            const arr = sseClients.get(planPath) ?? [];
+            const idx = arr.indexOf(res);
+            if (idx !== -1)
+                arr.splice(idx, 1);
+        });
+    });
+    app.post("/api/sessions/:key/submit", (req, res) => {
+        const planPath = req.params.key;
+        const { verdict, globalComment, comments } = req.body;
+        const review = reviewStore.submitReview(planPath, verdict, globalComment ?? "", comments ?? []);
+        res.json({ ok: true, reviewId: review.reviewId });
+    });
+    app.get("/api/sessions/:key/poll", async (req, res) => {
+        const planPath = req.params.key;
+        const since = Number(req.query.since) || 0;
+        const review = await reviewStore.pollReview(planPath, since, LONG_POLL_TIMEOUT_MS);
+        if (!review) {
+            res.status(204).end();
+            return;
+        }
+        res.json(review);
+    });
+    app.post("/api/sessions/:key/end", (req, res) => {
+        const planPath = req.params.key;
+        const session = sessionStore.endSession(planPath);
+        if (!session) {
+            res.status(404).json({ error: "no such session" });
+            return;
+        }
+        res.json({ ok: true });
+    });
+    return app;
+}
+function startServer() {
+    const app = createApp();
+    const server = app.listen(PORT, "127.0.0.1", () => {
+        sessionStore.writeServerLock({ pid: process.pid, port: PORT });
+    });
+    server.on("error", (err) => {
+        console.error(`gigaplan server failed to start: ${String(err)}`);
+        process.exit(1);
+    });
+}
+if (process.argv[1] === __filename) {
+    startServer();
+}

package/dist/session-store.js

@@ -0,0 +1,92 @@
+import * as fs from "node:fs";
+import { STATE_DIR, STATE_FILE, SERVER_LOCK_FILE } from "./paths.js";
+function ensureStateDir() {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+}
+function readState() {
+    ensureStateDir();
+    try {
+        const raw = fs.readFileSync(STATE_FILE, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { sessions: {} };
+    }
+}
+function writeState(state) {
+    ensureStateDir();
+    fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), "utf8");
+}
+export function getSession(planPath) {
+    return readState().sessions[planPath];
+}
+export function createOrReopenSession(planPath) {
+    const state = readState();
+    const existing = state.sessions[planPath];
+    if (existing) {
+        existing.ended = false;
+        writeState(state);
+        return existing;
+    }
+    const record = {
+        planPath,
+        createdAt: new Date().toISOString(),
+        ended: false,
+        reopenable: true,
+        lastPolledReviewId: 0,
+    };
+    state.sessions[planPath] = record;
+    writeState(state);
+    return record;
+}
+export function endSession(planPath) {
+    const state = readState();
+    const existing = state.sessions[planPath];
+    if (!existing)
+        return undefined;
+    existing.ended = true;
+    existing.reopenable = true;
+    writeState(state);
+    return existing;
+}
+export function bumpLastPolledReviewId(planPath, reviewId) {
+    const state = readState();
+    const existing = state.sessions[planPath];
+    if (!existing)
+        return;
+    existing.lastPolledReviewId = reviewId;
+    writeState(state);
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function readServerLock() {
+    try {
+        const raw = fs.readFileSync(SERVER_LOCK_FILE, "utf8");
+        const lock = JSON.parse(raw);
+        if (isProcessAlive(lock.pid))
+            return lock;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeServerLock(lock) {
+    ensureStateDir();
+    fs.writeFileSync(SERVER_LOCK_FILE, JSON.stringify(lock, null, 2), "utf8");
+}
+export function clearServerLock() {
+    try {
+        fs.unlinkSync(SERVER_LOCK_FILE);
+    }
+    catch {
+        // already gone
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "gigaplan",
+  "version": "0.1.0",
+  "description": "Review agent-authored implementation plans in a GitHub-PR-style browser UI. Agents write plain Markdown; gigaplan renders, themes, and collects structured feedback.",
+  "type": "module",
+  "bin": {
+    "gigaplan": "bin/gigaplan.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "public",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.server.json && tsc -p tsconfig.client.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit -p tsconfig.server.json && tsc --noEmit -p tsconfig.client.json",
+    "test": "node --import tsx --test test/**/*.test.ts"
+  },
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "express": "^5.2.1",
+    "markdown-it": "^14.3.0",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^24.13.3",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  },
+  "keywords": [
+    "plan-review",
+    "code-review",
+    "claude-code",
+    "cli"
+  ],
+  "license": "MIT"
+}