@zuzuucodes/cli 1.4.0 → 1.6.0

package/bin/zuzuu.mjs

@@ -21,11 +21,12 @@ import { doctor } from '../zuzuu/commands/doctor.mjs';
 import { enable, disable } from '../zuzuu/commands/enable.mjs';
 import { runHook } from '../zuzuu/commands/hook.mjs';
 import { remember, recall, knowledge } from '../zuzuu/commands/knowledge.mjs';
-import { review, proposals } from '../zuzuu/commands/review.mjs';
+import { review } from '../zuzuu/commands/review.mjs';
+import { proposals } from '../zuzuu/commands/proposals.mjs';
 import { distill } from '../zuzuu/commands/distill.mjs';
 import { digest } from '../zuzuu/commands/digest.mjs';
 import { act } from '../zuzuu/commands/act.mjs';
-import { migrate } from '../zuzuu/commands/migrate.mjs';
+import { migrate } from '../zuzuu/commands/migrations/index.mjs';
 import { generation } from '../zuzuu/commands/generation.mjs';
 import { evalCmd } from '../zuzuu/commands/eval.mjs';
 import { code } from '../zuzuu/commands/code.mjs';
@@ -33,6 +34,8 @@ import { web } from '../zuzuu/commands/web.mjs';
 import { explain } from '../zuzuu/commands/explain.mjs';
 import { inbox } from '../zuzuu/commands/inbox.mjs';
 import { session } from '../zuzuu/commands/session.mjs';
+import { sessions } from '../zuzuu/commands/sessions.mjs';
+import { faculty } from '../zuzuu/commands/faculty.mjs';
 
 function parseArgs(argv) {
   const a = { _: [] };
@@ -74,6 +77,13 @@ usage: zuzuu <command> [options]
   recall "query" [--type t] [--attr k=v] [--related-to id] [--semantic]
                             search knowledge: lexical · graph · semantic
   knowledge reindex|audit   rebuild the search index · check registry/items health
+  faculty items <f> [--json|--jsonl]
+                            list a faculty's envelope items (one doc · one line per item)
+  faculty schema <f> [--json]
+                            print a faculty's payload schema (JSON-Schema subset)
+  faculty manifest <f> [--json]
+                            print a faculty's module manifest (faculty.json)
+  faculty overview [--json] every faculty in one shot: ui + counts + top items + pending
   digest [--json] [--budget N]
                             print the session-start grounding brief
   act [list|show <slug>|new <slug>|schema <slug>]
@@ -94,8 +104,12 @@ usage: zuzuu <command> [options]
   disable                   remove the background hooks
   session [status|merge|continue|discard]
                             the invisible session branch (one per agent session)
+  sessions [--json]         recorded sessions with lifecycle state labels
+  session inspect <id> [--json]
+                            one session: trace summary + per-faculty mined signals
   eval [--faculty f]        rank pending proposals by eval score, highest first
-  migrate [--home]          one-time migrators: proposal schema · --home moves agent/ → .zuzuu/
+  migrate [--home|--items]  one-time migrators: proposal schema · --home moves agent/ → .zuzuu/
+                            · --items rewrites legacy faculty shapes → the envelope standard
   doctor                    environment + session health (reconciles lost sessions)
   explain [topic]           the 5 faculties + how graduation works
   version                   print version
@@ -117,7 +131,7 @@ switch (cmd) {
   case 'knowledge': await knowledge(args); break;
   case 'digest': digest(args); break;
   case 'act': act(args); break;
-  case 'distill': distill(args); break;
+  case 'distill': await distill(args); break;
   case 'inbox': inbox(args); break;
   case 'review': await review(args); break;
   case 'proposals': proposals(args); break;
@@ -128,6 +142,8 @@ switch (cmd) {
   case 'disable': disable(args); break;
   case 'hook': runHook(args._[0], { host: args.host, session: args.session }); break;
   case 'session': session(args); break;
+  case 'sessions': sessions(args); break;
+  case 'faculty': faculty(args); break;
   case 'eval': evalCmd(args); break;
   case 'migrate': migrate(args); break;
   case 'generation': generation(args); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/web-app/dist/auth.js

@@ -0,0 +1,91 @@
+// The daemon's auth + request-origin gates, extracted from server.ts:
+// Host-header allowlist (DNS rebinding), Origin allowlist (cross-site WS
+// hijacking / CSRF), and token-in-URL → HttpOnly cookie auth. One AuthGate
+// instance guards both the Hono HTTP app and the WS upgrade path.
+import crypto from "node:crypto";
+import { getCookie, setCookie } from "hono/cookie";
+const AUTH_COOKIE = "webcode_auth";
+const COOKIE_MAX_AGE = 30 * 24 * 3600;
+export class AuthGate {
+    authSessions = new Set();
+    allowedHosts;
+    allowedOrigins;
+    token;
+    constructor(cfg) {
+        this.token = cfg.token;
+        const hostNames = ["127.0.0.1", "localhost", "[::1]"];
+        this.allowedHosts = new Set(hostNames.flatMap((h) => [h, `${h}:${cfg.port}`]));
+        this.allowedOrigins = new Set([
+            ...hostNames.map((h) => `http://${h}:${cfg.port}`),
+            ...(cfg.extraOrigins ?? []),
+        ]);
+        // hosted: also accept the public hostname (Fly's edge sets Host to it);
+        // Host/Origin defense stays on, just widened to the one public origin.
+        if (cfg.publicHost) {
+            this.allowedHosts.add(cfg.publicHost.toLowerCase());
+            this.allowedOrigins.add(`https://${cfg.publicHost}`);
+            this.allowedOrigins.add(`http://${cfg.publicHost}`);
+        }
+    }
+    /** Host allowlist defeats DNS rebinding: rebinding changes DNS, not the Host header. */
+    hostAllowed(host) {
+        return !!host && this.allowedHosts.has(host.toLowerCase());
+    }
+    /** Origin allowlist defeats cross-site WS hijacking / CSRF from arbitrary websites. */
+    originAllowed(origin) {
+        return origin === undefined || this.allowedOrigins.has(origin);
+    }
+    /** WS upgrade path: is the request's cookie an authenticated session? */
+    cookieAuthed(cookieHeader) {
+        if (!cookieHeader)
+            return false;
+        const match = /(?:^|;\s*)webcode_auth=([^;]+)/.exec(cookieHeader);
+        return !!match && this.authSessions.has(match[1]);
+    }
+    /** App-wide gate: Host/Origin allowlists + the ?token= → cookie exchange. */
+    gate() {
+        return async (c, next) => {
+            if (!this.hostAllowed(c.req.header("host"))) {
+                return c.text("forbidden host", 403);
+            }
+            if (!this.originAllowed(c.req.header("origin"))) {
+                return c.text("forbidden origin", 403);
+            }
+            // Token exchange: any page request carrying ?token= gets a cookie.
+            const token = c.req.query("token");
+            if (token && !c.req.path.startsWith("/api/")) {
+                if (!timingSafeEqualStr(token, this.token))
+                    return c.text("invalid token", 403);
+                const secret = crypto.randomBytes(24).toString("base64url");
+                this.authSessions.add(secret);
+                setCookie(c, AUTH_COOKIE, secret, {
+                    httpOnly: true,
+                    sameSite: "Strict",
+                    path: "/",
+                    maxAge: COOKIE_MAX_AGE,
+                });
+                const url = new URL(c.req.url);
+                url.searchParams.delete("token");
+                // /auth?token=… exists so the Vite dev server can proxy the
+                // exchange; land on the app root afterwards either way.
+                const dest = url.pathname === "/auth" ? "/" : url.pathname + url.search;
+                return c.redirect(dest);
+            }
+            await next();
+        };
+    }
+    /** /api/* gate: only cookie-authenticated sessions pass. */
+    requireAuth() {
+        return async (c, next) => {
+            if (!this.authSessions.has(getCookie(c, AUTH_COOKIE) ?? "")) {
+                return c.json({ error: "unauthorized" }, 401);
+            }
+            await next();
+        };
+    }
+}
+function timingSafeEqualStr(a, b) {
+    const ba = Buffer.from(a);
+    const bb = Buffer.from(b);
+    return ba.length === bb.length && crypto.timingSafeEqual(ba, bb);
+}

package/web-app/dist/server.js

@@ -1,17 +1,17 @@
-import crypto from "node:crypto";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import { Readable } from "node:stream";
 import { Hono } from "hono";
-import { getCookie, setCookie } from "hono/cookie";
 import { serve } from "@hono/node-server";
 import { WebSocketServer } from "ws";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { SessionManager } from "./sessions.js";
+import { AuthGate } from "./auth.js";
 import { createFsApi } from "./fs-api.js";
-import { createZuzuuApi, runZuzuuMut } from "./zuzuu-api.js";
+import { createZuzuuApi } from "./zuzuu-routes.js";
+import { runZuzuuMut } from "./zuzuu-cli.js";
 import { search } from "./search.js";
 import { listFiles } from "./file-list.js";
 import { listWorkflows, saveWorkflow } from "./workflows.js";
@@ -23,8 +23,6 @@ const execFileAsync = promisify(execFile);
 import { handleTermSocket } from "./ws-term.js";
 import { handleFsSocket } from "./ws-fs.js";
 import { PathError, resolveSafe, safeJoin } from "./safe-path.js";
-const AUTH_COOKIE = "webcode_auth";
-const COOKIE_MAX_AGE = 30 * 24 * 3600;
 /** Host CLIs an agent/command session may run. Argv-spawned, never a shell. */
 const DEFAULT_COMMAND_ALLOWLIST = ["claude", "gemini", "codex", "pi", "opencode", "zuzuu"];
 const STATIC_MIME = {
@@ -45,9 +43,7 @@ export class WebcodeServer {
     /** mutable workspace root — switchable at runtime via switchTo() */
     root;
     startedAt = Date.now();
-    authSessions = new Set();
-    allowedHosts;
-    allowedOrigins;
+    auth;
     commandAllowlist;
     server = null;
     constructor(cfg) {
@@ -55,19 +51,12 @@ export class WebcodeServer {
         this.root = cfg.root;
         this.commandAllowlist = new Set(cfg.commandAllowlist ?? DEFAULT_COMMAND_ALLOWLIST);
         this.sessions = new SessionManager(cfg.root);
-        const hostNames = ["127.0.0.1", "localhost", "[::1]"];
-        this.allowedHosts = new Set(hostNames.flatMap((h) => [h, `${h}:${cfg.port}`]));
-        this.allowedOrigins = new Set([
-            ...hostNames.map((h) => `http://${h}:${cfg.port}`),
-            ...(cfg.extraOrigins ?? []),
-        ]);
-        // hosted: also accept the public hostname (Fly's edge sets Host to it);
-        // Host/Origin defense stays on, just widened to the one public origin.
-        if (cfg.publicHost) {
-            this.allowedHosts.add(cfg.publicHost.toLowerCase());
-            this.allowedOrigins.add(`https://${cfg.publicHost}`);
-            this.allowedOrigins.add(`http://${cfg.publicHost}`);
-        }
+        this.auth = new AuthGate({
+            port: cfg.port,
+            token: cfg.token,
+            ...(cfg.extraOrigins !== undefined ? { extraOrigins: cfg.extraOrigins } : {}),
+            ...(cfg.publicHost !== undefined ? { publicHost: cfg.publicHost } : {}),
+        });
         this.app = this.buildApp();
     }
     /**
@@ -101,60 +90,13 @@ export class WebcodeServer {
             return { cliAbsent: true };
         return { ok: false, ...(r.stderr !== undefined ? { stderr: r.stderr } : {}), ...(r.data !== undefined ? { refusal: r.data } : {}) };
     }
-    // ── security gates ─────────────────────────────────────────────────
-    /** Host allowlist defeats DNS rebinding: rebinding changes DNS, not the Host header. */
-    hostAllowed(host) {
-        return !!host && this.allowedHosts.has(host.toLowerCase());
-    }
-    /** Origin allowlist defeats cross-site WS hijacking / CSRF from arbitrary websites. */
-    originAllowed(origin) {
-        return origin === undefined || this.allowedOrigins.has(origin);
-    }
-    cookieAuthed(cookieHeader) {
-        if (!cookieHeader)
-            return false;
-        const match = /(?:^|;\s*)webcode_auth=([^;]+)/.exec(cookieHeader);
-        return !!match && this.authSessions.has(match[1]);
-    }
     // ── HTTP app ───────────────────────────────────────────────────────
     buildApp() {
         const { cfg } = this;
         const app = new Hono();
-        app.use("*", async (c, next) => {
-            if (!this.hostAllowed(c.req.header("host"))) {
-                return c.text("forbidden host", 403);
-            }
-            if (!this.originAllowed(c.req.header("origin"))) {
-                return c.text("forbidden origin", 403);
-            }
-            // Token exchange: any page request carrying ?token= gets a cookie.
-            const token = c.req.query("token");
-            if (token && !c.req.path.startsWith("/api/")) {
-                if (!timingSafeEqualStr(token, cfg.token))
-                    return c.text("invalid token", 403);
-                const secret = crypto.randomBytes(24).toString("base64url");
-                this.authSessions.add(secret);
-                setCookie(c, AUTH_COOKIE, secret, {
-                    httpOnly: true,
-                    sameSite: "Strict",
-                    path: "/",
-                    maxAge: COOKIE_MAX_AGE,
-                });
-                const url = new URL(c.req.url);
-                url.searchParams.delete("token");
-                // /auth?token=… exists so the Vite dev server can proxy the
-                // exchange; land on the app root afterwards either way.
-                const dest = url.pathname === "/auth" ? "/" : url.pathname + url.search;
-                return c.redirect(dest);
-            }
-            await next();
-        });
-        app.use("/api/*", async (c, next) => {
-            if (!this.authSessions.has(getCookie(c, AUTH_COOKIE) ?? "")) {
-                return c.json({ error: "unauthorized" }, 401);
-            }
-            await next();
-        });
+        // security gates live in auth.ts: Host/Origin allowlists + token→cookie
+        app.use("*", this.auth.gate());
+        app.use("/api/*", this.auth.requireAuth());
         app.get("/api/workspace", (c) => {
             const body = {
                 root: this.root,
@@ -434,11 +376,11 @@ export class WebcodeServer {
                 socket.write(`HTTP/1.1 ${status} ${msg}\r\nConnection: close\r\n\r\n`);
                 socket.destroy();
             };
-            if (!this.hostAllowed(req.headers.host))
+            if (!this.auth.hostAllowed(req.headers.host))
                 return reject(403, "Forbidden");
-            if (!this.originAllowed(req.headers.origin))
+            if (!this.auth.originAllowed(req.headers.origin))
                 return reject(403, "Forbidden");
-            if (!this.cookieAuthed(req.headers.cookie))
+            if (!this.auth.cookieAuthed(req.headers.cookie))
                 return reject(401, "Unauthorized");
             const url = new URL(req.url ?? "/", "http://localhost");
             const termMatch = /^\/ws\/term\/([0-9a-f]+)$/.exec(url.pathname);
@@ -462,8 +404,3 @@ export class WebcodeServer {
         this.server?.close();
     }
 }
-function timingSafeEqualStr(a, b) {
-    const ba = Buffer.from(a);
-    const bb = Buffer.from(b);
-    return ba.length === bb.length && crypto.timingSafeEqual(ba, bb);
-}

package/web-app/dist/zuzuu-cli.js

@@ -0,0 +1,124 @@
+// The zuzuu CLI spawn layer — the ONLY place the daemon shells out to the
+// `zuzuu` binary. Two flavours:
+//   runZuzuu    — reads: any failure (absent, non-zero, unparseable) → null;
+//                 callers degrade to file-read fallbacks.
+//   runZuzuuMut — mutations + CLI-only reads: failures are distinguished
+//                 (binary absent vs command failed + stderr tail) so routes
+//                 can answer 503 vs 502.
+// Always argv arrays (never a shell), time-boxed, cwd-scoped to the workspace.
+import { spawn, spawnSync } from "node:child_process";
+/** Spawn `zuzuu <args> --json` in `root`. Returns parsed JSON, or null on any
+ *  failure (binary absent, non-zero exit, unparseable). Read-only + time-boxed. */
+export function runZuzuu(root, args, opts = {}) {
+    const binary = opts.binary ?? "zuzuu";
+    const timeoutMs = opts.timeoutMs ?? 5000;
+    return new Promise((resolve) => {
+        let out = "";
+        let done = false;
+        const finish = (v) => { if (!done) {
+            done = true;
+            resolve(v);
+        } };
+        let child;
+        try {
+            child = spawn(binary, [...args, "--json"], { cwd: root, stdio: ["ignore", "pipe", "ignore"] });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        const timer = setTimeout(() => { try {
+            child.kill();
+        }
+        catch { /* noop */ } finish(null); }, timeoutMs);
+        child.stdout?.on("data", (b) => { out += b.toString(); });
+        child.on("error", () => { clearTimeout(timer); finish(null); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0)
+                return finish(null);
+            try {
+                finish(JSON.parse(out));
+            }
+            catch {
+                finish(null);
+            }
+        });
+    });
+}
+const STDERR_TAIL = 2048;
+/** Spawn `zuzuu <args> --json` where the caller needs to distinguish failures
+ *  (mutations, and reads with no file fallback). Unlike runZuzuu: binary
+ *  absent vs command failed (with a stderr tail) are separate results, so
+ *  routes can answer 503 vs 502. Stdout must parse as JSON on success. */
+export function runZuzuuMut(root, args, opts = {}) {
+    const binary = opts.binary ?? "zuzuu";
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    return new Promise((resolve) => {
+        let out = "";
+        let err = "";
+        let done = false;
+        const finish = (v) => { if (!done) {
+            done = true;
+            resolve(v);
+        } };
+        let child;
+        try {
+            child = spawn(binary, [...args, "--json"], { cwd: root, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            finish({ ok: false, code: "absent" });
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch { /* noop */ }
+            finish({ ok: false, code: "failed", stderr: "zuzuu timed out" });
+        }, timeoutMs);
+        child.stdout?.on("data", (b) => { out += b.toString(); });
+        child.stderr?.on("data", (b) => {
+            err += b.toString();
+            if (err.length > STDERR_TAIL)
+                err = err.slice(-STDERR_TAIL);
+        });
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            if (e.code === "ENOENT")
+                finish({ ok: false, code: "absent" });
+            else
+                finish({ ok: false, code: "failed", stderr: e.message });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                // zuzuu prints structured JSON even on refusals (exit 1, e.g.
+                // empty-squash-with-checkpoints) — keep it so the UI can act on reason.
+                try {
+                    const parsed = JSON.parse(out);
+                    return finish({ ok: false, code: "failed", stderr: err.slice(-STDERR_TAIL), data: parsed });
+                }
+                catch {
+                    return finish({ ok: false, code: "failed", stderr: err.slice(-STDERR_TAIL) });
+                }
+            }
+            try {
+                finish({ ok: true, data: JSON.parse(out) });
+            }
+            catch {
+                finish({ ok: false, code: "failed", stderr: "unparseable JSON from zuzuu" });
+            }
+        });
+    });
+}
+/** Best-effort: is the zuzuu binary runnable? */
+export function binAvailable(binary) {
+    try {
+        const r = spawnSync(binary, ["version"], { stdio: "ignore", timeout: 3000 });
+        return !r.error && r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}