@jamie-tam/forge 6.0.0

package/dist/verify.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { targets } from "./paths.js";
+/**
+ * Structural verification — checks that installed files are internally
+ * consistent. No AI needed, just file existence and JSON validity.
+ */
+export function verify(projectRoot) {
+    const t = targets(projectRoot);
+    const result = { passed: [], failed: [] };
+    // Check gate-requirements.json exists and is valid
+    const gateReqPath = join(t.rules, "..", "hooks", "config", "gate-requirements.json");
+    if (existsSync(gateReqPath)) {
+        try {
+            const gates = JSON.parse(readFileSync(gateReqPath, "utf-8"));
+            result.passed.push("gate-requirements.json is valid JSON");
+            // Check every referenced skill exists
+            for (const [gate, config] of Object.entries(gates)) {
+                if (gate === "_comment")
+                    continue;
+                const c = config;
+                const skill = c.skill;
+                if (skill) {
+                    const skillPath = join(t.skills, skill, "SKILL.md");
+                    if (existsSync(skillPath)) {
+                        result.passed.push(`gate ${gate} → skill ${skill} exists`);
+                    }
+                    else {
+                        result.failed.push(`gate ${gate} → skill ${skill} NOT FOUND at ${skillPath}`);
+                    }
+                }
+                // Check agent references
+                const agents = [];
+                if (c.agent && c.agent !== "null")
+                    agents.push(c.agent);
+                if (Array.isArray(c.agents))
+                    agents.push(...c.agents);
+                for (const agent of agents) {
+                    const agentPath = join(t.agents, `${agent}.md`);
+                    if (existsSync(agentPath)) {
+                        result.passed.push(`gate ${gate} → agent ${agent} exists`);
+                    }
+                    else {
+                        result.failed.push(`gate ${gate} → agent ${agent} NOT FOUND at ${agentPath}`);
+                    }
+                }
+            }
+        }
+        catch {
+            result.failed.push("gate-requirements.json is invalid JSON");
+        }
+    }
+    else {
+        result.failed.push("gate-requirements.json not found");
+    }
+    // Check hook scripts referenced in settings exist
+    const settingsPath = join(t.claude, "settings.local.json");
+    if (existsSync(settingsPath)) {
+        const settingsStr = readFileSync(settingsPath, "utf-8");
+        const scriptRefs = settingsStr.match(/\.claude\/hooks\/scripts\/[^"\\]+/g) ?? [];
+        for (const ref of new Set(scriptRefs)) {
+            const scriptPath = join(projectRoot, ref);
+            if (existsSync(scriptPath)) {
+                result.passed.push(`hook script ${ref} exists`);
+            }
+            else {
+                result.failed.push(`hook script ${ref} NOT FOUND`);
+            }
+        }
+    }
+    // Check manifest templates exist
+    for (const tpl of ["feature.yaml", "greenfield.yaml"]) {
+        const tplPath = join(t.templates, "manifests", tpl);
+        if (existsSync(tplPath)) {
+            result.passed.push(`manifest template ${tpl} exists`);
+        }
+        else {
+            result.failed.push(`manifest template ${tpl} MISSING at ${tplPath}`);
+        }
+    }
+    // Check core directories exist
+    for (const [name, path] of Object.entries({
+        agents: t.agents,
+        commands: t.commands,
+        skills: t.skills,
+        rules: t.rules,
+        protocols: t.protocols,
+        references: t.references,
+    })) {
+        if (existsSync(path)) {
+            result.passed.push(`${name}/ directory exists`);
+        }
+        else {
+            result.failed.push(`${name}/ directory MISSING`);
+        }
+    }
+    return result;
+}

package/dist/wiki-ui.js

@@ -0,0 +1,310 @@
+// Local web UI for reviewing pending wiki dreams. Reads markdown + manifests,
+// renders HTML templates with embedded state, exposes a small JSON API for
+// accept/reject. CSRF-resistant: 127.0.0.1 only, session token in cookie,
+// custom X-Forge-Action header required on mutating endpoints.
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { acceptDream, getDreamDetails, listDreams, rejectDream, } from "./wiki.js";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEMPLATES_DIR = path.resolve(__dirname, "..", "templates", "wiki-html");
+const DEFAULT_PORT = 8765;
+const SHUTDOWN_GRACE_MS = 5000;
+export async function wikiUi(opts = {}) {
+    const root = await findRepoRoot();
+    const stateDir = path.join(root, ".forge", "state");
+    fs.mkdirSync(stateDir, { recursive: true });
+    const pidFile = path.join(stateDir, "wiki-ui.pid");
+    const tokenFile = path.join(stateDir, "wiki-ui-token");
+    // Refuse if already running
+    if (fs.existsSync(pidFile)) {
+        const existingPid = Number(fs.readFileSync(pidFile, "utf8").trim());
+        if (Number.isFinite(existingPid) && isProcessAlive(existingPid)) {
+            console.error(`forge wiki ui already running (pid ${existingPid}). Stop it first or check the existing browser tab.`);
+            return 1;
+        }
+        // Stale PID file
+        fs.unlinkSync(pidFile);
+    }
+    const token = randomBytes(32).toString("hex");
+    fs.writeFileSync(tokenFile, token, { mode: 0o600 });
+    const port = await findAvailablePort(opts.port ?? DEFAULT_PORT);
+    const server = http.createServer((req, res) => {
+        handleRequest(req, res, { root, token }).catch((err) => {
+            console.error("Request handler error:", err);
+            if (!res.headersSent) {
+                res.writeHead(500, { "content-type": "text/plain" });
+                res.end("Internal server error");
+            }
+        });
+    });
+    await new Promise((resolve) => {
+        server.listen(port, "127.0.0.1", () => {
+            resolve();
+        });
+    });
+    fs.writeFileSync(pidFile, String(process.pid));
+    const url = `http://127.0.0.1:${port}/?token=${token}`;
+    console.log(`forge wiki ui running at http://127.0.0.1:${port}`);
+    console.log(`Press Ctrl-C to stop.`);
+    if (!opts.noOpen) {
+        openBrowser(url);
+    }
+    const cleanup = () => {
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { }
+        try {
+            fs.unlinkSync(tokenFile);
+        }
+        catch { }
+    };
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log("\nShutting down...");
+        cleanup();
+        const timer = setTimeout(() => {
+            process.exit(0);
+        }, SHUTDOWN_GRACE_MS);
+        server.close(() => {
+            clearTimeout(timer);
+            process.exit(0);
+        });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    // Block forever (until signal)
+    await new Promise(() => { });
+    return 0;
+}
+async function handleRequest(req, res, ctx) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const method = req.method ?? "GET";
+    // Auth: query token sets cookie + redirects; otherwise check cookie or header
+    const queryToken = url.searchParams.get("token");
+    const cookieToken = parseCookie(req.headers.cookie ?? "")["forge_token"];
+    const headerToken = req.headers["x-forge-token"];
+    if (queryToken && queryToken === ctx.token) {
+        // Initial open via auto-launched URL — set cookie + strip query param
+        const dest = url.pathname + (url.search ? url.search.replace(/[?&]token=[^&]*/, "").replace(/^&/, "?") : "");
+        res.writeHead(302, {
+            location: dest === "" ? "/" : dest,
+            "set-cookie": `forge_token=${ctx.token}; Path=/; HttpOnly; SameSite=Strict`,
+        });
+        res.end();
+        return;
+    }
+    const authed = cookieToken === ctx.token ||
+        (typeof headerToken === "string" && headerToken === ctx.token);
+    if (!authed) {
+        res.writeHead(401, { "content-type": "text/plain" });
+        res.end("Forge wiki ui: invalid or missing token. Re-launch via `forge wiki ui` to get a fresh URL.");
+        return;
+    }
+    // Mutating endpoints: require X-Forge-Action header (CSRF defense)
+    if (method === "POST") {
+        const actionHeader = req.headers["x-forge-action"];
+        if (actionHeader !== "1") {
+            res.writeHead(403, { "content-type": "text/plain" });
+            res.end("Forbidden: missing X-Forge-Action header");
+            return;
+        }
+    }
+    const route = `${method} ${url.pathname}`;
+    // Static HTML pages
+    if (method === "GET" && url.pathname === "/") {
+        await serveDreamsListPage(ctx, res);
+        return;
+    }
+    if (method === "GET" && url.pathname.startsWith("/dreams/")) {
+        const dreamId = decodeURIComponent(url.pathname.slice("/dreams/".length));
+        if (!dreamId) {
+            res.writeHead(404, { "content-type": "text/plain" });
+            res.end("Not found");
+            return;
+        }
+        await serveDreamDetailPage(ctx, dreamId, res);
+        return;
+    }
+    // JSON API
+    if (method === "GET" && url.pathname === "/api/state") {
+        const dreams = await listDreams(ctx.root);
+        respondJson(res, 200, { dreams });
+        return;
+    }
+    if (method === "GET" && url.pathname.startsWith("/api/dreams/")) {
+        const dreamId = decodeURIComponent(url.pathname.slice("/api/dreams/".length));
+        const detail = await getDreamDetails(dreamId, ctx.root);
+        if (!detail) {
+            respondJson(res, 404, { error: "dream_not_found" });
+            return;
+        }
+        respondJson(res, 200, detail);
+        return;
+    }
+    if (method === "POST" &&
+        url.pathname.match(/^\/api\/dreams\/[^/]+\/accept$/)) {
+        const dreamId = decodeURIComponent(url.pathname.split("/")[3] ?? "");
+        try {
+            const result = await acceptDream(dreamId, ctx.root);
+            respondJson(res, 200, result);
+        }
+        catch (err) {
+            respondJson(res, 400, { error: err.message });
+        }
+        return;
+    }
+    if (method === "POST" &&
+        url.pathname.match(/^\/api\/dreams\/[^/]+\/reject$/)) {
+        const dreamId = decodeURIComponent(url.pathname.split("/")[3] ?? "");
+        const body = await readBody(req);
+        let reason = "";
+        try {
+            reason = JSON.parse(body).reason ?? "";
+        }
+        catch {
+            respondJson(res, 400, { error: "invalid_body" });
+            return;
+        }
+        try {
+            const result = await rejectDream(dreamId, reason, ctx.root);
+            respondJson(res, 200, result);
+        }
+        catch (err) {
+            respondJson(res, 400, { error: err.message });
+        }
+        return;
+    }
+    res.writeHead(404, { "content-type": "text/plain" });
+    res.end(`Not found: ${route}`);
+}
+// ---- Page rendering --------------------------------------------------------
+async function serveDreamsListPage(ctx, res) {
+    const dreams = await listDreams(ctx.root);
+    const template = readTemplate("dreams-list.html");
+    const html = injectState(template, ctx.token, { dreams });
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(html);
+}
+async function serveDreamDetailPage(ctx, dreamId, res) {
+    const detail = await getDreamDetails(dreamId, ctx.root);
+    if (!detail) {
+        res.writeHead(404, { "content-type": "text/plain" });
+        res.end(`Dream not found: ${dreamId}`);
+        return;
+    }
+    const template = readTemplate("dream-detail.html");
+    const html = injectState(template, ctx.token, { dream: detail });
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    res.end(html);
+}
+function readTemplate(name) {
+    return fs.readFileSync(path.join(TEMPLATES_DIR, name), "utf8");
+}
+function injectState(template, token, state) {
+    const stateJson = JSON.stringify(state).replace(/</g, "\\u003c");
+    return template
+        .replace(/\{\{FORGE_TOKEN\}\}/g, escapeHtml(token))
+        .replace(/\{\{FORGE_STATE\}\}/g, stateJson);
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => {
+        const map = {
+            "&": "&amp;",
+            "<": "&lt;",
+            ">": "&gt;",
+            '"': "&quot;",
+            "'": "&#39;",
+        };
+        return map[c] ?? c;
+    });
+}
+function respondJson(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+async function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+function parseCookie(header) {
+    const out = {};
+    for (const part of header.split(";")) {
+        const eq = part.indexOf("=");
+        if (eq === -1)
+            continue;
+        const k = part.slice(0, eq).trim();
+        const v = part.slice(eq + 1).trim();
+        if (k)
+            out[k] = v;
+    }
+    return out;
+}
+// ---- Lifecycle helpers -----------------------------------------------------
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const e = err;
+        // EPERM means the process exists but we lack permission — still alive.
+        return e.code === "EPERM";
+    }
+}
+async function findAvailablePort(start) {
+    for (let port = start; port < start + 100; port++) {
+        if (await isPortFree(port))
+            return port;
+    }
+    throw new Error(`No free port found in range ${start}-${start + 100}; try --port`);
+}
+function isPortFree(port) {
+    return new Promise((resolve) => {
+        const tester = http.createServer();
+        tester.once("error", () => resolve(false));
+        tester.once("listening", () => {
+            tester.close(() => resolve(true));
+        });
+        tester.listen(port, "127.0.0.1");
+    });
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", '""', url] : [url];
+    try {
+        spawn(cmd, args, { detached: true, stdio: "ignore" }).unref();
+    }
+    catch (err) {
+        console.error(`Could not open browser automatically: ${err.message}`);
+        console.error(`Open this URL manually: ${url}`);
+    }
+}
+async function findRepoRoot() {
+    // Walk up from cwd until we find .git or aiwiki/
+    let dir = process.cwd();
+    for (let i = 0; i < 20; i++) {
+        if (fs.existsSync(path.join(dir, ".git")) ||
+            fs.existsSync(path.join(dir, "aiwiki"))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return process.cwd();
+}