@luuthuong/devboard 0.0.0-stage → 1.0.1

package/server-dist/server/hooks.js

@@ -0,0 +1,222 @@
+// Claude Code hook plumbing: installs `~/.devboard/hook.sh` (on Windows,
+// inside WSL) and wires it into `~/.claude/settings.json`, then tails the
+// events file the script appends to. Ports hook_manager.rs and
+// hook_event_store.rs.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { IS_WINDOWS, devboardDataDir, log, run } from "./util.js";
+import { windowsPathToWsl } from "./tmux.js";
+const HOOK_EVENTS = [
+    "Stop",
+    "Notification",
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "PreCompact",
+    "SubagentStop",
+];
+export const eventsFilePath = () => path.join(devboardDataDir(), "hook-events.jsonl");
+/** Bash script Claude runs per hook event; the events path is baked in. */
+function hookScriptContent(eventsPath) {
+    return [
+        "#!/usr/bin/env bash",
+        "# Managed by DevBoard. Edits here will be overwritten.",
+        "set -u",
+        `EVENTS_FILE='${eventsPath.replaceAll("'", "'\\''")}'`,
+        'mkdir -p "$(dirname "$EVENTS_FILE")" 2>/dev/null || true',
+        "PAYLOAD=$(cat)",
+        "TS=$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)",
+        "# Single-line JSON envelope so the server can parse line-by-line.",
+        `printf '{"timestamp":"%s","payload":%s}\\n' "$TS" "$PAYLOAD" >> "$EVENTS_FILE"`,
+        "",
+    ].join("\n");
+}
+/** Merge our hook command into a Claude settings object, idempotently. */
+export function mergeHooksIntoSettings(data, hookCmd) {
+    data ??= {};
+    const hooks = (data.hooks ??= {});
+    for (const ev of HOOK_EVENTS) {
+        const groups = (hooks[ev] ??= []);
+        if (groups.length === 0)
+            groups.push({ hooks: [] });
+        const inner = (groups[0].hooks ??= []);
+        if (!inner.some((h) => h?.command === hookCmd))
+            inner.push({ type: "command", command: hookCmd });
+    }
+    return data;
+}
+// The merge, run inside WSL where $HOME is the user's Linux home. python3 is
+// present on every modern distro; if it's missing we warn instead of failing.
+const WSL_MERGE_PY = `
+import json, os
+events = ${JSON.stringify(HOOK_EVENTS)}
+hook_cmd = os.path.expanduser('~/.devboard/hook.sh')
+path = os.path.join(os.path.expanduser('~'), '.claude', 'settings.json')
+os.makedirs(os.path.dirname(path), exist_ok=True)
+try:
+    with open(path) as f:
+        data = json.load(f)
+except FileNotFoundError:
+    data = {}
+except json.JSONDecodeError:
+    os.rename(path, path + '.bak')
+    data = {}
+hooks = data.setdefault('hooks', {})
+for ev in events:
+    groups = hooks.setdefault(ev, [])
+    if not groups:
+        groups.append({'hooks': []})
+    inner = groups[0].setdefault('hooks', [])
+    if not any(h.get('command') == hook_cmd for h in inner):
+        inner.append({'type': 'command', 'command': hook_cmd})
+with open(path, 'w') as f:
+    json.dump(data, f, indent=2)
+print('ok')
+`;
+/** Native install: script + settings.json on this machine's own filesystem. */
+async function installNative() {
+    // Claude Code on Windows runs hook commands through Git Bash, which wants forward slashes.
+    const fwd = (p) => (IS_WINDOWS ? p.replaceAll("\\", "/") : p);
+    const dir = path.join(os.homedir(), ".devboard");
+    const script = path.join(dir, "hook.sh");
+    await fs.promises.mkdir(dir, { recursive: true });
+    await fs.promises.writeFile(script, hookScriptContent(fwd(eventsFilePath())), { mode: 0o755 });
+    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    await fs.promises.mkdir(path.dirname(settingsPath), { recursive: true });
+    let data = {};
+    try {
+        data = JSON.parse(await fs.promises.readFile(settingsPath, "utf8"));
+    }
+    catch (e) {
+        if (e?.code !== "ENOENT")
+            await fs.promises.rename(settingsPath, `${settingsPath}.bak`).catch(() => { });
+    }
+    await fs.promises.writeFile(settingsPath, JSON.stringify(mergeHooksIntoSettings(data, fwd(script)), null, 2));
+    log.info("hooks", `installed hook.sh + settings.json entries — events → ${eventsFilePath()}`);
+}
+/** WSL install (Windows only): the same script inside the distro. Resolves false when WSL isn't reachable. */
+async function installWsl() {
+    if (!(await run("wsl.exe", ["--", "bash", "-lc", "true"], { timeoutMs: 20_000 })).ok) {
+        log.warn("hooks", "wsl.exe is not responding — skipping WSL hook install; will retry on next launch");
+        return false;
+    }
+    const eventsWsl = await windowsPathToWsl(eventsFilePath());
+    if (!eventsWsl)
+        throw new Error("could not translate events path to WSL");
+    const write = await run("wsl.exe", ["--", "bash", "-lc", "mkdir -p ~/.devboard && cat > ~/.devboard/hook.sh && chmod +x ~/.devboard/hook.sh"], { input: hookScriptContent(eventsWsl) });
+    if (!write.ok)
+        throw new Error(`hook.sh install failed: ${write.stderr.trim()}`);
+    const merge = await run("wsl.exe", ["--", "python3", "-"], { input: WSL_MERGE_PY });
+    if (!merge.ok) {
+        throw new Error(`settings.json merge failed (is python3 installed in WSL?): ${merge.stderr.trim()}`);
+    }
+    log.info("hooks", `installed hook.sh + settings.json entries in WSL — events → ${eventsWsl}`);
+    return true;
+}
+/** Install (or refresh) the hook script + settings entries. On Windows this covers both the Windows
+ *  runtime (native) and WSL; resolves `false` only when nothing could be installed. */
+export async function installIfNeeded() {
+    if (!IS_WINDOWS) {
+        await installNative();
+        return true;
+    }
+    let ok = false;
+    try {
+        await installNative();
+        ok = true;
+    }
+    catch (e) {
+        log.warn("hooks", `native hook install failed: ${e instanceof Error ? e.message : e}`);
+    }
+    try {
+        if (await installWsl())
+            ok = true;
+    }
+    catch (e) {
+        log.warn("hooks", `WSL hook install failed: ${e instanceof Error ? e.message : e}`);
+    }
+    return ok;
+}
+export function parseHookLine(line) {
+    let env;
+    try {
+        env = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const payload = env?.payload;
+    if (!payload || typeof payload !== "object")
+        return null;
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    const sessionId = str(payload.session_id) ?? str(payload.sessionId) ?? "";
+    const eventName = str(payload.hook_event_name) ?? str(payload.event_name) ?? "";
+    if (!sessionId && !eventName)
+        return null;
+    const ts = str(env.timestamp);
+    const parsed = ts ? Date.parse(ts) : NaN;
+    return {
+        sessionId,
+        eventName,
+        transcriptPath: str(payload.transcript_path),
+        notificationType: str(payload.notification_type) ?? str(payload.type),
+        timestamp: Number.isNaN(parsed) ? new Date().toISOString() : new Date(parsed).toISOString(),
+    };
+}
+/** Tails the events file from a persistent byte offset; never re-emits. */
+export class HookEventStore {
+    offset = 0;
+    path = eventsFilePath();
+    touch() {
+        fs.mkdirSync(path.dirname(this.path), { recursive: true });
+        fs.closeSync(fs.openSync(this.path, "a"));
+    }
+    /** Jump to EOF so events from previous runs aren't replayed. */
+    skipToTail() {
+        try {
+            this.offset = fs.statSync(this.path).size;
+        }
+        catch {
+            // no file yet
+        }
+    }
+    async readNewEvents() {
+        let handle;
+        try {
+            handle = await fs.promises.open(this.path, "r");
+        }
+        catch {
+            return [];
+        }
+        try {
+            const { size } = await handle.stat();
+            if (size < this.offset)
+                this.offset = 0; // truncated
+            if (size === this.offset)
+                return [];
+            const buf = Buffer.alloc(size - this.offset);
+            await handle.read(buf, 0, buf.length, this.offset);
+            // Only consume complete lines; a half-written tail waits for the next tick.
+            const lastNl = buf.lastIndexOf(0x0a);
+            if (lastNl < 0)
+                return [];
+            this.offset += lastNl + 1;
+            const events = [];
+            for (const line of buf
+                .subarray(0, lastNl + 1)
+                .toString("utf8")
+                .split("\n")) {
+                if (!line.trim())
+                    continue;
+                const ev = parseHookLine(line);
+                if (ev)
+                    events.push(ev);
+            }
+            return events;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+}

package/server-dist/server/http.js

@@ -0,0 +1,266 @@
+// HTTP + WebSocket front door: static UI, JSON-RPC (`/api/invoke/:cmd`),
+// binary uploads, image serving, the event stream (`/ws`) and terminals (`/pty`).
+//
+// This server can spawn processes (PTY) and read files, so it is locked down:
+// loopback-only by default, Host/Origin checks against DNS-rebinding and
+// cross-site requests, and an optional shared token.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { WebSocketServer } from "ws";
+import { buildCommands, uploads } from "./commands.js";
+import { subscribe } from "./events.js";
+import { allowedImageRoots } from "./integrations.js";
+import { handlePtySocket } from "./pty.js";
+import { errorMessage, log } from "./util.js";
+const MIME = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".ico": "image/x-icon",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".map": "application/json",
+};
+const IMAGE_EXTS = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"]);
+const MAX_JSON_BYTES = 10 * 1024 * 1024;
+const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+const hostnameOf = (hostHeader) => {
+    if (!hostHeader)
+        return "";
+    // [::1]:1421 → [::1]; localhost:1421 → localhost
+    const m = hostHeader.match(/^(\[[^\]]+\]|[^:]+)/);
+    return (m?.[1] ?? "").toLowerCase();
+};
+function readBody(req, limit) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > limit) {
+                reject(new Error("request body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function sendJson(res, status, body) {
+    const data = JSON.stringify(body ?? null);
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+    res.end(data);
+}
+const isUnder = (child, root) => {
+    const rel = path.relative(root, child);
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+};
+export function startServer(ctx, opts) {
+    const commands = buildCommands(ctx);
+    const allowed = new Set([...LOOPBACK, ...opts.allowedHosts.map((h) => h.toLowerCase())]);
+    const tokenOk = (req, url) => {
+        if (!opts.token)
+            return true;
+        const expected = Buffer.from(opts.token);
+        const candidates = [
+            req.headers.authorization?.replace(/^Bearer\s+/i, ""),
+            /(?:^|;\s*)devboard_token=([^;]+)/.exec(req.headers.cookie ?? "")?.[1],
+            url.searchParams.get("token") ?? undefined,
+        ];
+        return candidates.some((c) => {
+            if (!c)
+                return false;
+            const got = Buffer.from(decodeURIComponent(c));
+            return got.length === expected.length && crypto.timingSafeEqual(got, expected);
+        });
+    };
+    /** Host must be ours (anti DNS-rebinding); a present Origin must match Host. */
+    const originOk = (req) => {
+        if (!allowed.has(hostnameOf(req.headers.host)))
+            return false;
+        const origin = req.headers.origin;
+        if (!origin)
+            return true;
+        try {
+            return new URL(origin).host.toLowerCase() === (req.headers.host ?? "").toLowerCase();
+        }
+        catch {
+            return false;
+        }
+    };
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        try {
+            if (!originOk(req)) {
+                sendJson(res, 403, { error: "forbidden origin" });
+                return;
+            }
+            if (!tokenOk(req, url)) {
+                res.writeHead(401, { "content-type": "text/plain" });
+                res.end("Unauthorized — open the URL printed at startup (it carries ?token=…).");
+                return;
+            }
+            // A valid ?token= sets a cookie so the SPA's own requests are authorised.
+            if (opts.token && url.searchParams.get("token")) {
+                res.setHeader("set-cookie", `devboard_token=${encodeURIComponent(opts.token)}; Path=/; HttpOnly; SameSite=Strict`);
+            }
+            if (url.pathname.startsWith("/api/")) {
+                await handleApi(req, res, url);
+                return;
+            }
+            serveStatic(res, url);
+        }
+        catch (e) {
+            log.warn("http", `${req.method} ${url.pathname} failed: ${errorMessage(e)}`);
+            if (!res.headersSent)
+                sendJson(res, 500, { error: errorMessage(e) });
+            else
+                res.end();
+        }
+    });
+    async function handleApi(req, res, url) {
+        // JSON-RPC: POST /api/invoke/<command>
+        if (req.method === "POST" && url.pathname.startsWith("/api/invoke/")) {
+            // Requiring JSON forces a CORS preflight for cross-origin callers.
+            if (!(req.headers["content-type"] ?? "").includes("application/json")) {
+                sendJson(res, 415, { error: "content-type must be application/json" });
+                return;
+            }
+            const name = decodeURIComponent(url.pathname.slice("/api/invoke/".length));
+            const cmd = Object.hasOwn(commands, name) ? commands[name] : undefined;
+            if (!cmd) {
+                sendJson(res, 404, { error: `unknown command: ${name}` });
+                return;
+            }
+            const raw = (await readBody(req, MAX_JSON_BYTES)).toString("utf8");
+            const args = raw ? JSON.parse(raw) : {};
+            try {
+                sendJson(res, 200, { result: (await cmd(args ?? {})) ?? null });
+            }
+            catch (e) {
+                log.debug("rpc", `${name} failed: ${errorMessage(e)}`);
+                sendJson(res, 500, { error: errorMessage(e) });
+            }
+            return;
+        }
+        // Binary uploads (pasted / picked images)
+        if (req.method === "POST" && url.pathname === "/api/upload/image") {
+            const bytes = await readBody(req, MAX_UPLOAD_BYTES);
+            sendJson(res, 200, { path: await uploads.image(bytes) });
+            return;
+        }
+        if (req.method === "POST" && url.pathname === "/api/upload/file") {
+            const bytes = await readBody(req, MAX_UPLOAD_BYTES);
+            sendJson(res, 200, { path: await uploads.file(bytes, url.searchParams.get("name") ?? "file") });
+            return;
+        }
+        // Image bytes for previews. Only image files under our own directories.
+        if (req.method === "GET" && url.pathname === "/api/file") {
+            const p = path.resolve(url.searchParams.get("path") ?? "");
+            const ext = path.extname(p).toLowerCase();
+            const ok = IMAGE_EXTS.has(ext) && allowedImageRoots().some((root) => isUnder(p, path.resolve(root)));
+            if (!ok) {
+                sendJson(res, 403, { error: "path not allowed" });
+                return;
+            }
+            const st = await fs.promises.stat(p).catch(() => null);
+            if (!st?.isFile() || st.size > MAX_UPLOAD_BYTES) {
+                sendJson(res, 404, { error: "not found" });
+                return;
+            }
+            res.writeHead(200, {
+                "content-type": MIME[ext] ?? "application/octet-stream",
+                "content-length": st.size,
+                "cache-control": "private, max-age=3600",
+                // SVGs can carry script; render them inert.
+                "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
+            });
+            fs.createReadStream(p).pipe(res);
+            return;
+        }
+        sendJson(res, 404, { error: "not found" });
+    }
+    function serveStatic(res, url) {
+        const root = path.resolve(opts.distDir);
+        let rel = decodeURIComponent(url.pathname);
+        if (rel === "/")
+            rel = "/index.html";
+        let file = path.join(root, rel);
+        // Contain to dist/, and SPA-fallback for client-routed paths without an extension.
+        if (!isUnder(file, root) && file !== root) {
+            sendJson(res, 403, { error: "forbidden" });
+            return;
+        }
+        if (!fs.existsSync(file) || fs.statSync(file).isDirectory()) {
+            if (path.extname(rel)) {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("Not found");
+                return;
+            }
+            file = path.join(root, "index.html");
+        }
+        if (!fs.existsSync(file)) {
+            res.writeHead(503, { "content-type": "text/plain" });
+            res.end("UI not built yet — run `npm run build` (or use `npm run dev`).");
+            return;
+        }
+        const ext = path.extname(file).toLowerCase();
+        res.writeHead(200, {
+            "content-type": MIME[ext] ?? "application/octet-stream",
+            // Hashed assets are immutable; the HTML shell must always revalidate.
+            "cache-control": rel.startsWith("/assets/") ? "public, max-age=31536000, immutable" : "no-cache",
+        });
+        fs.createReadStream(file).pipe(res);
+    }
+    // ── WebSockets ─────────────────────────────────────────────────────────────
+    const events = new WebSocketServer({ noServer: true });
+    const ptys = new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 });
+    const sockets = new Set();
+    subscribe((event, payload) => {
+        if (sockets.size === 0)
+            return;
+        const msg = JSON.stringify({ event, payload });
+        for (const ws of sockets)
+            if (ws.readyState === ws.OPEN)
+                ws.send(msg);
+    });
+    events.on("connection", (ws) => {
+        sockets.add(ws);
+        ws.on("close", () => sockets.delete(ws));
+        ws.on("error", () => sockets.delete(ws));
+    });
+    ptys.on("connection", handlePtySocket);
+    server.on("upgrade", (req, socket, head) => {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        // Browsers always send Origin on WebSocket handshakes, so a missing or
+        // foreign one is rejected outright.
+        if (!req.headers.origin || !originOk(req) || !tokenOk(req, url)) {
+            socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        const target = url.pathname === "/ws" ? events : url.pathname === "/pty" ? ptys : null;
+        if (!target) {
+            socket.destroy();
+            return;
+        }
+        target.handleUpgrade(req, socket, head, (ws) => target.emit("connection", ws, req));
+    });
+    server.listen(opts.port, opts.host, () => {
+        const shown = opts.host === "0.0.0.0" || opts.host === "::" ? "localhost" : opts.host;
+        log.info("http", `DevBoard listening on http://${shown}:${opts.port}${opts.token ? "/?token=…" : ""}`);
+    });
+    return server;
+}

package/server-dist/server/index.js

@@ -0,0 +1,77 @@
+// DevBoard server entry point.
+//
+//   DEVBOARD_HOST           bind address            (default 127.0.0.1)
+//   DEVBOARD_PORT           listen port             (default 1421)
+//   DEVBOARD_TOKEN          shared secret           (required when not on loopback)
+//   DEVBOARD_ALLOWED_HOSTS  extra Host names, comma-separated (e.g. a LAN/VPN name)
+//   DEVBOARD_DATA_DIR       override the data directory
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { linkDevboardSkill } from "./skill.js";
+import { createContext } from "./context.js";
+import { deployRemoteShell } from "./remote.js";
+import { startServer } from "./http.js";
+import { startPollers } from "./pollers.js";
+import { errorMessage, devboardDataDir, log } from "./util.js";
+const here = path.dirname(fileURLToPath(import.meta.url));
+// Package root: the nearest ancestor with a package.json (works from `server/` and from the compiled `server-dist/server/`).
+const pkgRoot = (() => {
+    let dir = here;
+    while (!fs.existsSync(path.join(dir, "package.json")) && path.dirname(dir) !== dir)
+        dir = path.dirname(dir);
+    return dir;
+})();
+// Published package: the skill ships in `<pkg>/.claude`. In the repo it lives one level higher.
+const repoRoot = fs.existsSync(path.join(pkgRoot, ".claude")) ? pkgRoot : path.resolve(pkgRoot, "..");
+const host = process.env.DEVBOARD_HOST ?? "127.0.0.1";
+const port = Number(process.env.DEVBOARD_PORT ?? 1421);
+const token = process.env.DEVBOARD_TOKEN || undefined;
+const loopback = ["127.0.0.1", "::1", "localhost"].includes(host);
+if (!loopback && !token) {
+    console.error(`Refusing to listen on ${host} without DEVBOARD_TOKEN: this server can run commands and read files.\n` +
+        "Set DEVBOARD_TOKEN to a long random string, or bind to 127.0.0.1.");
+    process.exit(1);
+}
+process.on("unhandledRejection", (e) => log.error("process", `unhandled rejection: ${errorMessage(e)}`));
+process.on("uncaughtException", (e) => log.error("process", `uncaught exception: ${errorMessage(e)}`));
+log.info("startup", `DevBoard (web) starting; data dir: ${devboardDataDir()}`);
+// Hooks run on this machine: loopback, unless the server is bound to one
+// specific address (that address must then be in DEVBOARD_ALLOWED_HOSTS).
+const hookHost = loopback || host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host.includes(":") ? `[${host}]` : host;
+const ctx = createContext({ serverUrl: `http://${hookHost}:${port}`, token });
+linkDevboardSkill(repoRoot);
+void deployRemoteShell().catch((e) => log.warn("startup", `remote-shell deploy failed: ${errorMessage(e)}`));
+const server = startServer(ctx, {
+    host,
+    port,
+    token,
+    distDir: path.join(pkgRoot, "dist"),
+    allowedHosts: (process.env.DEVBOARD_ALLOWED_HOSTS ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean),
+});
+startPollers(ctx);
+// Close the knowledge-base SQLite handles (checkpoints the WAL) before exiting on Ctrl+C / kill.
+// Pollers are not stopped: the process is exiting, and each index write is one synchronous transaction.
+let shuttingDown = false;
+const shutdown = (signal) => {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    log.info("process", `${signal}: shutting down`);
+    // Hard stop in case a connection or the index refuses to close.
+    setTimeout(() => process.exit(1), 3000).unref();
+    server.close();
+    server.closeAllConnections();
+    try {
+        ctx.harness.index.close();
+    }
+    catch (e) {
+        log.warn("process", `index close failed: ${errorMessage(e)}`);
+    }
+    process.exit(0);
+};
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+    process.on(signal, () => shutdown(signal));