@zuzuucodes/cli 1.1.0 → 1.2.0

package/README.md

@@ -18,6 +18,8 @@ npm install -g @zuzuucodes/cli   # zero dependencies — installs the `zuzuu` co
 # no coding agent yet? one command gives you a fully faculty-equipped one:
 zuzuu code        # scaffold the faculty home, install + wire OpenCode, launch it (capture + gate + grounding)
 
+zuzuu web         # prefer a visual app? the workbench: Home → review ceremony → embedded-terminal agent sessions
+
 # already run Claude Code / Gemini / Codex / OpenCode / pi? wrap the one you have:
 zuzuu init        # scaffold your project's agent home (.zuzuu/) — git-style, hidden like .git
 zuzuu explain     # the 5 faculties + how graduation works (you're always in the loop)

package/bin/zuzuu-web.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Direct entry to the bundled workbench daemon (the `zuzuu web` command is the
+// porcelain; this bin exists for people who want the daemon itself).
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const entry = join(dirname(fileURLToPath(import.meta.url)), '..', 'web-app', 'dist', 'index.js');
+if (!existsSync(entry)) {
+  console.error('zuzuu-web: the bundled workbench is not staged.');
+  console.error('  installed package → reinstall: npm i -g @zuzuucodes/cli (without --omit=optional)');
+  console.error('  repo checkout     → build it:  npm run build:web');
+  process.exit(1);
+}
+await import(entry);

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "Give the coding agent you already run (Claude Code, Codex, Gemini CLI, OpenCode) evolving faculties — knowledge, memory, actions, instructions, guardrails — with host-agnostic OpenTelemetry session tracing. Zero dependencies.",
+  "description": "Give the coding agent you already run (Claude Code, Codex, Gemini CLI, OpenCode) evolving faculties \u2014 knowledge, memory, actions, instructions, guardrails \u2014 with host-agnostic OpenTelemetry session tracing. Zero dependencies.",
   "keywords": [
     "ai-agents",
     "claude-code",
@@ -35,11 +35,13 @@
   },
   "bin": {
     "zz": "bin/zuzuu.mjs",
-    "zuzuu": "bin/zuzuu.mjs"
+    "zuzuu": "bin/zuzuu.mjs",
+    "zuzuu-web": "bin/zuzuu-web.mjs"
   },
   "files": [
     "bin/",
     "zuzuu/",
+    "web-app/",
     "experiments/experiment-1-trace-capture/core/",
     "experiments/experiment-1-trace-capture/adapters/",
     "LICENSE",
@@ -51,6 +53,17 @@
     "inspect": "node experiments/experiment-1-trace-capture/bin/inspect-trace.mjs",
     "test": "node --test 'tests/**/*.test.mjs'",
     "playground": "node tests/playground/run.mjs",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "build:web": "node scripts/build-web.mjs"
+  },
+  "optionalDependencies": {
+    "@hono/node-server": "^2.0.4",
+    "@lydell/node-pty": "^1.2.0-beta.12",
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/headless": "^6.0.0",
+    "archiver": "^8.0.0",
+    "chokidar": "^5.0.0",
+    "hono": "^4.12.25",
+    "ws": "^8.21.0"
   }
 }

package/web-app/dist/browse.js

@@ -0,0 +1,48 @@
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const MAX_ENTRIES = 1000;
+/**
+ * List the subdirectories of an absolute path, for the vault folder picker.
+ *
+ * SECURITY: this deliberately reads OUTSIDE the workspace sandbox — choosing
+ * a new vault means browsing the user's own machine. It is intentionally not
+ * routed through `safePath`. Mitigations: auth-gated + loopback-only at the
+ * server layer, and it returns DIRECTORY NAMES ONLY (never file contents).
+ */
+export async function listDirs(input) {
+    const abs = input && path.isAbsolute(input) ? path.resolve(input) : os.homedir();
+    const parent = path.dirname(abs);
+    const dirs = [];
+    const entries = await fsp.readdir(abs, { withFileTypes: true });
+    for (const e of entries) {
+        if (dirs.length >= MAX_ENTRIES)
+            break;
+        if (e.name.startsWith("."))
+            continue;
+        let isDir = e.isDirectory();
+        if (e.isSymbolicLink()) {
+            try {
+                isDir = (await fsp.stat(path.join(abs, e.name))).isDirectory();
+            }
+            catch {
+                isDir = false;
+            }
+        }
+        if (isDir)
+            dirs.push({ name: e.name, path: path.join(abs, e.name) });
+    }
+    dirs.sort((a, b) => a.name.localeCompare(b.name));
+    return { path: abs, parent: parent === abs ? null : parent, dirs };
+}
+/** Create a directory under an absolute parent, returning its absolute path. */
+export async function mkdirIn(parent, name) {
+    if (!path.isAbsolute(parent))
+        throw new Error("parent must be absolute");
+    if (!name || name.includes("/") || name.includes("\\") || name === "." || name === "..") {
+        throw new Error("invalid folder name");
+    }
+    const abs = path.join(parent, name);
+    await fsp.mkdir(abs, { recursive: false });
+    return abs;
+}

package/web-app/dist/config.js

@@ -0,0 +1,52 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const DIR = path.join(os.homedir(), ".webcode");
+const FILE = path.join(DIR, "config.json");
+const RECENT_MAX = 10;
+const DEFAULT = { recent: [], onboarded: false };
+/** Load persisted config, tolerating a missing/corrupt file. */
+export async function load() {
+    try {
+        const raw = await fsp.readFile(FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            recent: Array.isArray(parsed.recent) ? parsed.recent.filter((p) => typeof p === "string") : [],
+            onboarded: parsed.onboarded === true,
+        };
+    }
+    catch {
+        return { ...DEFAULT };
+    }
+}
+async function save(cfg) {
+    await fsp.mkdir(DIR, { recursive: true });
+    await fsp.writeFile(FILE, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/** Prepend a workspace to the recent list (deduped, most-recent-first, capped). */
+export async function addRecent(root) {
+    const cfg = await load();
+    cfg.recent = [root, ...cfg.recent.filter((p) => p !== root)].slice(0, RECENT_MAX);
+    await save(cfg);
+    return cfg;
+}
+export async function setOnboarded() {
+    const cfg = await load();
+    cfg.onboarded = true;
+    await save(cfg);
+    return cfg;
+}
+/** Pure helper (exported for tests): compute the next recent list. */
+export function nextRecent(recent, root) {
+    return [root, ...recent.filter((p) => p !== root)].slice(0, RECENT_MAX);
+}
+/** Synchronous best-effort load for startup paths that can't await. */
+export function loadSync() {
+    try {
+        return { ...DEFAULT, ...JSON.parse(fs.readFileSync(FILE, "utf8")) };
+    }
+    catch {
+        return { ...DEFAULT };
+    }
+}

package/web-app/dist/file-list.js

@@ -0,0 +1,87 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { toRel } from "./safe-path.js";
+const execFileAsync = promisify(execFile);
+const IGNORE = new Set([".git", "node_modules", "dist", ".next", ".cache"]);
+let rgAvailable = null;
+async function hasRg() {
+    if (rgAvailable === null) {
+        rgAvailable = await execFileAsync("rg", ["--version"], { timeout: 2000 })
+            .then(() => true)
+            .catch(() => false);
+    }
+    return rgAvailable;
+}
+/**
+ * Flat list of workspace files for the ⌘K palette. Prefers `rg --files`
+ * (honors .gitignore, fast); falls back to a bounded manual walk.
+ */
+export async function listFiles(root, limit = 5000) {
+    if (await hasRg())
+        return rgFiles(root, limit);
+    return walkFiles(root, limit);
+}
+function rgFiles(root, limit) {
+    return new Promise((resolve) => {
+        const proc = spawn("rg", ["--files", "--hidden", "-g", "!.git"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const files = [];
+        let buf = "";
+        let truncated = false;
+        proc.stdout.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            let nl;
+            while ((nl = buf.indexOf("\n")) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (line)
+                    files.push(line);
+                if (files.length >= limit) {
+                    truncated = true;
+                    proc.kill("SIGTERM");
+                    resolve({ files, truncated });
+                    return;
+                }
+            }
+        });
+        proc.on("close", () => resolve({ files, truncated }));
+        proc.on("error", () => resolve({ files, truncated }));
+    });
+}
+async function walkFiles(root, limit) {
+    const files = [];
+    let truncated = false;
+    const stack = [root];
+    while (stack.length > 0 && files.length < limit) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await fsp.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith(".") && e.name !== ".webcode")
+                continue;
+            if (IGNORE.has(e.name))
+                continue;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile()) {
+                files.push(toRel(root, full));
+                if (files.length >= limit) {
+                    truncated = true;
+                    break;
+                }
+            }
+        }
+    }
+    files.sort();
+    return { files, truncated };
+}

package/web-app/dist/frames.js

@@ -0,0 +1,16 @@
+/**
+ * Binary WS framing: 1 opcode byte followed by the payload
+ * (raw bytes for I/O frames, UTF-8 JSON for control frames).
+ */
+export function encodeFrame(op, payload = "") {
+    const body = typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
+    const buf = Buffer.allocUnsafe(1 + body.length);
+    buf[0] = op;
+    buf.set(body, 1);
+    return buf;
+}
+export function decodeFrame(data) {
+    if (data.length === 0)
+        throw new Error("empty frame");
+    return { op: data[0], payload: data.subarray(1) };
+}

package/web-app/dist/fs-api.js

@@ -0,0 +1,226 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import { Hono } from "hono";
+import { ZipArchive } from "archiver";
+import { PathError, resolveSafe, toRel } from "./safe-path.js";
+const STAT_CONCURRENCY = 64;
+const MIME = {
+    ".txt": "text/plain; charset=utf-8",
+    ".md": "text/markdown; charset=utf-8",
+    ".json": "application/json",
+    ".js": "text/javascript",
+    ".ts": "text/plain; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+    ".zip": "application/zip",
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+    ".webm": "video/webm",
+    ".mov": "video/quicktime",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".m4a": "audio/mp4",
+    ".aac": "audio/aac",
+    ".flac": "audio/flac",
+    ".avif": "image/avif",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+};
+function contentType(file) {
+    return MIME[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+}
+function kindOf(dirent) {
+    if (dirent.isSymbolicLink())
+        return "symlink";
+    if (dirent.isDirectory())
+        return "dir";
+    if (dirent.isFile())
+        return "file";
+    return "other";
+}
+async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+export function createFsApi(getRoot) {
+    const app = new Hono();
+    // resolve the (mutable) workspace root once per request, so handlers below
+    // keep referencing a stable `root` while the daemon can re-root at runtime.
+    let root = getRoot();
+    app.use("*", async (_c, next) => {
+        root = getRoot();
+        await next();
+    });
+    app.onError((err, c) => {
+        if (err instanceof PathError)
+            return c.json({ error: err.message }, 403);
+        const code = err.code;
+        if (code === "ENOENT")
+            return c.json({ error: "not found" }, 404);
+        if (code === "EEXIST")
+            return c.json({ error: "already exists" }, 409);
+        console.error("[fs-api]", err);
+        return c.json({ error: "internal error" }, 500);
+    });
+    app.get("/list", async (c) => {
+        const abs = await resolveSafe(root, c.req.query("path") ?? "");
+        const dirents = await fsp.readdir(abs, { withFileTypes: true });
+        const entries = await mapLimit(dirents, STAT_CONCURRENCY, async (d) => {
+            const full = path.join(abs, d.name);
+            const kind = kindOf(d);
+            let size = 0;
+            let mtimeMs = 0;
+            let targetKind;
+            try {
+                const lst = await fsp.lstat(full);
+                size = lst.size;
+                mtimeMs = lst.mtimeMs;
+                if (kind === "symlink") {
+                    // Only report a resolvable target if it stays inside the workspace.
+                    await resolveSafe(root, toRel(root, full));
+                    const st = await fsp.stat(full);
+                    targetKind = st.isDirectory() ? "dir" : st.isFile() ? "file" : "other";
+                }
+            }
+            catch {
+                // broken symlink / vanished entry — report what we know
+            }
+            return { name: d.name, kind, targetKind, size, mtimeMs };
+        });
+        entries.sort((a, b) => {
+            const aDir = a.kind === "dir" || a.targetKind === "dir" ? 0 : 1;
+            const bDir = b.kind === "dir" || b.targetKind === "dir" ? 0 : 1;
+            return aDir - bDir || a.name.localeCompare(b.name);
+        });
+        const body = { path: toRel(root, abs), entries };
+        return c.json(body);
+    });
+    app.post("/mkdir", async (c) => {
+        const body = await c.req.json();
+        const abs = await resolveSafe(root, body.path ?? "");
+        if (abs === root)
+            return c.json({ error: "invalid path" }, 400);
+        await fsp.mkdir(abs, { recursive: true });
+        return c.json({ ok: true });
+    });
+    // Save an editor buffer to disk.
+    app.post("/write", async (c) => {
+        const body = await c.req.json();
+        const abs = await resolveSafe(root, body.path ?? "");
+        if (abs === root)
+            return c.json({ error: "invalid path" }, 400);
+        if (typeof body.content !== "string")
+            return c.json({ error: "content required" }, 400);
+        await fsp.mkdir(path.dirname(abs), { recursive: true });
+        await fsp.writeFile(abs, body.content, "utf8");
+        return c.json({ ok: true });
+    });
+    app.post("/rename", async (c) => {
+        const body = await c.req.json();
+        const from = await resolveSafe(root, body.from ?? "");
+        const to = await resolveSafe(root, body.to ?? "");
+        if (from === root || to === root)
+            return c.json({ error: "invalid path" }, 400);
+        await fsp.rename(from, to);
+        return c.json({ ok: true });
+    });
+    app.post("/delete", async (c) => {
+        const body = await c.req.json();
+        if (!Array.isArray(body.paths) || body.paths.length === 0) {
+            return c.json({ error: "paths required" }, 400);
+        }
+        for (const p of body.paths) {
+            const abs = await resolveSafe(root, p);
+            if (abs === root)
+                return c.json({ error: "cannot delete workspace root" }, 400);
+            await fsp.rm(abs, { recursive: true, force: true });
+        }
+        return c.json({ ok: true });
+    });
+    app.get("/download", async (c) => {
+        const abs = await resolveSafe(root, c.req.query("path") ?? "");
+        const st = await fsp.stat(abs);
+        const name = path.basename(abs) || "workspace";
+        if (st.isDirectory()) {
+            // store-only zip: local transfer, no point burning CPU on deflate
+            const archive = new ZipArchive({ store: true });
+            archive.on("error", (err) => console.error("[zip]", err));
+            archive.directory(abs, name);
+            void archive.finalize();
+            return new Response(Readable.toWeb(archive), {
+                headers: {
+                    "Content-Type": "application/zip",
+                    "Content-Disposition": `attachment; filename*=UTF-8''${encodeURIComponent(name)}.zip`,
+                },
+            });
+        }
+        const range = c.req.header("range");
+        const headers = {
+            "Content-Type": contentType(abs),
+            "Accept-Ranges": "bytes",
+            "Content-Disposition": c.req.query("inline") === "1"
+                ? "inline"
+                : `attachment; filename*=UTF-8''${encodeURIComponent(name)}`,
+        };
+        const match = range ? /^bytes=(\d*)-(\d*)$/.exec(range) : null;
+        if (match && (match[1] || match[2])) {
+            const start = match[1] ? Number(match[1]) : st.size - Number(match[2]);
+            const end = match[1] && match[2] ? Math.min(Number(match[2]), st.size - 1) : st.size - 1;
+            if (Number.isNaN(start) || start < 0 || start > end) {
+                return c.body(null, 416, { "Content-Range": `bytes */${st.size}` });
+            }
+            headers["Content-Range"] = `bytes ${start}-${end}/${st.size}`;
+            headers["Content-Length"] = String(end - start + 1);
+            const stream = Readable.toWeb(fs.createReadStream(abs, { start, end }));
+            return new Response(stream, { status: 206, headers });
+        }
+        headers["Content-Length"] = String(st.size);
+        return new Response(Readable.toWeb(fs.createReadStream(abs)), { headers });
+    });
+    // Open with the OS default app, or reveal in the system file manager —
+    // the local-native replacement for download/upload.
+    app.post("/open", async (c) => {
+        const body = await c.req.json();
+        const abs = await resolveSafe(root, body.path ?? "");
+        await fsp.access(abs); // 404 if missing
+        let cmd;
+        let args;
+        if (process.platform === "darwin") {
+            cmd = "open";
+            args = body.reveal ? ["-R", abs] : [abs];
+        }
+        else if (process.platform === "win32") {
+            cmd = "explorer";
+            args = body.reveal ? [`/select,${abs}`] : [abs];
+        }
+        else {
+            cmd = "xdg-open";
+            args = [body.reveal ? path.dirname(abs) : abs];
+        }
+        spawn(cmd, args, { stdio: "ignore", detached: true }).unref();
+        return c.json({ ok: true });
+    });
+    return app;
+}

package/web-app/dist/git.js

@@ -0,0 +1,73 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function git(root, args) {
+    const { stdout } = await execFileAsync("git", args, {
+        cwd: root,
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: 10_000,
+    });
+    return stdout;
+}
+async function isRepo(root) {
+    try {
+        const out = await git(root, ["rev-parse", "--is-inside-work-tree"]);
+        return out.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+export async function status(root) {
+    if (!(await isRepo(root)))
+        return { repo: false, branch: "", entries: [] };
+    let branch = "";
+    try {
+        branch = (await git(root, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+    }
+    catch {
+        branch = "(detached)";
+    }
+    // -z gives NUL-separated records; renames emit an extra NUL with the old path
+    const raw = await git(root, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]);
+    const entries = [];
+    const parts = raw.split("\0");
+    for (let i = 0; i < parts.length; i++) {
+        const rec = parts[i];
+        if (!rec || rec.length < 3)
+            continue;
+        const index = rec[0];
+        const worktree = rec[1];
+        const path = rec.slice(3);
+        // a rename/copy ("R"/"C") consumes the following NUL field (old path)
+        if (index === "R" || index === "C")
+            i++;
+        entries.push({ path, index, worktree });
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { repo: true, branch, entries };
+}
+/** HEAD/index content of a path for the diff editor's left side. */
+export async function diffOriginal(root, path) {
+    // staged content if present, else HEAD; empty for untracked/new files
+    for (const ref of [`:${path}`, `HEAD:${path}`]) {
+        try {
+            return await git(root, ["show", ref]);
+        }
+        catch {
+            // try next
+        }
+    }
+    return "";
+}
+export async function stage(root, paths) {
+    if (paths.length)
+        await git(root, ["add", "--", ...paths]);
+}
+export async function unstage(root, paths) {
+    if (paths.length)
+        await git(root, ["reset", "-q", "HEAD", "--", ...paths]);
+}
+export async function commit(root, message) {
+    await git(root, ["commit", "-m", message]);
+}

package/web-app/dist/history.js

@@ -0,0 +1,45 @@
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const MAX = 500;
+/**
+ * Read the user's shell history (zsh extended `: <ts>:<dur>;<cmd>` or plain),
+ * deduped, most-recent-first. Best-effort — returns [] if no file is found.
+ */
+export async function shellHistory() {
+    const home = os.homedir();
+    const candidates = [
+        process.env.HISTFILE,
+        path.join(home, ".zsh_history"),
+        path.join(home, ".bash_history"),
+    ].filter(Boolean);
+    for (const file of candidates) {
+        let raw;
+        try {
+            raw = await fsp.readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const cmds = [];
+        for (const line of raw.split("\n")) {
+            if (!line.trim())
+                continue;
+            // zsh extended: ": 1700000000:0;the command"
+            const m = /^: \d+:\d+;(.*)$/.exec(line);
+            cmds.push(m ? m[1] : line);
+        }
+        // most-recent-first, dedup keeping first occurrence
+        const seen = new Set();
+        const out = [];
+        for (let i = cmds.length - 1; i >= 0 && out.length < MAX; i--) {
+            const c = cmds[i].trim();
+            if (c && !seen.has(c)) {
+                seen.add(c);
+                out.push(c);
+            }
+        }
+        return out;
+    }
+    return [];
+}