@zuzuucodes/cli 1.0.1 → 1.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 Your host agent — Claude Code, Codex, Gemini CLI, OpenCode — supplies the *brain* (the reasoning loop + the model). zuzuu wraps the host you already pay for: it **serves** faculties to it, **observes** every session as an OpenTelemetry trace, and (the end-game) **evolves** the faculties from those traces — human-gated, across versioned generations. We never run a competing agent loop and never drive the host headlessly.
 
-> The CLI is `zuzuu` (package `zuzuu`, v1.0.0).
+> Install `npm i -g @zuzuucodes/cli` — the command is **`zz`** (or `zuzuu`). Published with provenance; releases auto-publish from `main` via GitHub OIDC.
 
 > **Status (honest):** early build, moving fast. **Observe** works (5 real hosts, verified). **Serve** delivers the faculty home (`zuzuu init`), a session digest to every host, an **enforced guardrails gate** on all 5, and five faculties sharing one proposal/review spine. **Evolve** is now **wired and tested** — trace miners → a mechanical eval lens → human-gated `zuzuu review` → versioned **generations** (mint / rollback / drift-check) — but **not yet proven on a real graduation corpus** (the loop runs + passes hermetic tests; it hasn't yet improved an agent from real sessions end-to-end). Full design: [`docs/DESIGN.md`](docs/DESIGN.md).
 
@@ -18,8 +18,10 @@ 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 (agent/) — git-style, open
+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)
 zuzuu inbox       # what's pending your approval · zuzuu review to approve/reject
 zuzuu capture     # turn your latest agent session into an OpenTelemetry trace
@@ -42,11 +44,11 @@ All five verified against **real sessions** — never fixtures; every host's liv
 
 **Prerequisites:** Node ≥ 22 — that's it. You need at least one supported agent you've already used, so a session exists to capture. (Hacking on zuzuu itself? `git clone https://github.com/h1902y/zuzuu && cd zuzuu && npm link`.)
 
-**`zuzuu init`** behaves like `git init`: empty dir → scaffolds the agent home + `AGENTS.md`/`CLAUDE.md`; existing project → adds `agent/` and injects a small delimiter-marked block into your existing instruction files (your text is never touched); already initialized → restores missing pieces only. The home is **open and self-explaining** — a visible `agent/` dir you can read and version in git: `agent/README.md` (the explainer) · `knowledge/` (verified facts) · `memory/` (curated episodes) · `actions/` (runbooks) · `instructions/` (steering) · `guardrails/` (enforced rules), plus `generations/` (your checkpoints). Machine internals are dot-prefixed + git-ignored (`agent/.traces/`, `agent/.live/`).
+**`zuzuu init`** behaves like `git init`: empty dir → scaffolds the agent home + `AGENTS.md`/`CLAUDE.md`; existing project → adds the home and injects a small delimiter-marked block into your existing instruction files (your text is never touched); already initialized → restores missing pieces only. The home is **hidden like `.git` and self-explaining** — a `.zuzuu/` dir you can read and version in git (the only visible footprint is the managed block + three `.gitignore` lines; transparency lives in `zuzuu status` / `explain` / `digest`): `.zuzuu/README.md` (the explainer) · `knowledge/` (verified facts) · `memory/` (curated episodes) · `actions/` (runbooks) · `instructions/` (steering) · `guardrails/` (enforced rules), plus `generations/` (your checkpoints). Machine internals are dot-prefixed + git-ignored (`.zuzuu/.traces/`, `.zuzuu/.live/`). *(Pre-2026-06-12 homes at `agent/` migrate automatically on `zuzuu init`, or via `zuzuu migrate --home`.)*
 
 **Live capture** (`zuzuu enable`) is invisible by design: a minimal lifecycle hook set (Claude Code, Gemini CLI, Codex), a bus plugin (OpenCode), or an extension (pi) — each wrapped so it **always exits 0 / fails open — it can never break your agent**. The same hook carries the guardrails gate, applied in each host's own idiom (Claude/Codex `hookSpecificOutput`, Gemini `{decision:"deny"}`, OpenCode throws from `tool.execute.before`, pi returns `{block:true}` from `tool_call`). Most hosts emit no clean end-signal when a terminal is killed, so `zuzuu doctor` *reconciles* lost sessions afterward from the transcript still on disk (nothing lost).
 
-**Where your data lives:** transcripts are read **read-only**; output is git-native in your repo — `agent/sessions.json` (small tracked index, each session linked to a commit) + `agent/.traces/*.otlp.jsonl` (local, git-ignored). **Nothing is uploaded**; no raw tool input/output on the trace (byte sizes only).
+**Where your data lives:** transcripts are read **read-only**; output is git-native in your repo — `.zuzuu/sessions.json` (small tracked index, each session linked to a commit) + `.zuzuu/.traces/*.otlp.jsonl` (local, git-ignored). **Nothing is uploaded**; no raw tool input/output on the trace (byte sizes only).
 
 **Verify / troubleshoot:** `npm test` (hermetic) · `npm run playground` (⏭️ skip = that host isn't on *your* machine, not a failure) · `zuzuu doctor` (env + session health). "No host detected" → use a supported agent once in the repo, then retry.
 

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/bin/zuzuu.mjs

@@ -29,6 +29,7 @@ import { migrate } from '../zuzuu/commands/migrate.mjs';
 import { generation } from '../zuzuu/commands/generation.mjs';
 import { evalCmd } from '../zuzuu/commands/eval.mjs';
 import { code } from '../zuzuu/commands/code.mjs';
+import { web } from '../zuzuu/commands/web.mjs';
 import { explain } from '../zuzuu/commands/explain.mjs';
 import { inbox } from '../zuzuu/commands/inbox.mjs';
 
@@ -59,9 +60,10 @@ function help() {
 usage: zuzuu <command> [options]
 
   code [dir]                launch OpenCode as the bundled default host (faculty home + capture + gate + digest)
-  init                      scaffold the faculty home (agent/) — git-style, idempotent
+  web [dir]                 launch the visual workbench (installs @zuzuucodes/web on demand)
+  init                      scaffold the faculty home (.zuzuu/) — git-style, idempotent
   status                    detected hosts + recorded sessions
-  capture [--host NAME]     capture a session → agent/.traces + agent/sessions.json
+  capture [--host NAME]     capture a session → .zuzuu/.traces + .zuzuu/sessions.json
           [--session ID] [--file PATH]
   trace [--last | FILE]     print a captured trace's span tree
   remember "fact" [--type t] [--attr k=v] [--rel type=target]
@@ -88,7 +90,7 @@ usage: zuzuu <command> [options]
   enable                    background hooks: invisible live capture + guardrails gate
   disable                   remove the background hooks
   eval [--faculty f]        rank pending proposals by eval score, highest first
-  migrate                   one-time migrator: rewrite legacy candidate/er proposals to new shape
+  migrate [--home]          one-time migrators: proposal schema · --home moves agent/ → .zuzuu/
   doctor                    environment + session health (reconciles lost sessions)
   explain [topic]           the 5 faculties + how graduation works
   version                   print version
@@ -103,6 +105,7 @@ const args = parseArgs(rest);
 
 switch (cmd) {
   case 'code': process.exit(code(args)); break;
+  case 'web': web(args); break;
   case 'init': init(args); break;
   case 'remember': remember(args); break;
   case 'recall': await recall(args); break;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@zuzuucodes/cli",
-  "version": "1.0.1",
+  "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]);
+}