@zuzuucodes/cli 1.1.0 → 1.2.0

package/web-app/dist/index.js

@@ -0,0 +1,160 @@
+import fsp from "node:fs/promises";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import crypto from "node:crypto";
+import { WebcodeServer } from "./server.js";
+import { addRecent } from "./config.js";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PORT = 7770;
+function parseArgs(argv) {
+    const args = {
+        dir: process.cwd(),
+        port: DEFAULT_PORT,
+        host: "127.0.0.1",
+        open: true,
+        token: null,
+        dev: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        switch (a) {
+            case "--port":
+            case "-p":
+                args.port = Number(argv[++i]);
+                break;
+            case "--host":
+                args.host = argv[++i] ?? args.host;
+                break;
+            case "--no-open":
+                args.open = false;
+                break;
+            case "--token":
+                args.token = argv[++i] ?? null;
+                break;
+            case "--dev":
+                args.dev = true;
+                break;
+            case "--help":
+            case "-h":
+                console.log(`zuzuu-web — native terminal + file explorer in your browser
+
+Usage: zuzuu-web [dir] [options]
+
+Options:
+  -p, --port <n>   port to listen on (default ${DEFAULT_PORT}, scans up if busy)
+      --host <h>   bind address (default 127.0.0.1 — do not expose without care)
+      --no-open    don't open the browser
+      --token <t>  fixed auth token (default: random per run)
+      --dev        allow the Vite dev server origin (development only)
+  -h, --help       show this help`);
+                process.exit(0);
+                break;
+            default:
+                if (!a.startsWith("-"))
+                    args.dir = a;
+        }
+    }
+    if (!Number.isInteger(args.port) || args.port < 1 || args.port > 65535) {
+        console.error(`invalid port`);
+        process.exit(1);
+    }
+    return args;
+}
+function findFreePort(start, host) {
+    return new Promise((resolve, reject) => {
+        const tryPort = (port, left) => {
+            const probe = net.createServer();
+            probe.once("error", (err) => {
+                probe.close();
+                if (err.code === "EADDRINUSE" && left > 0)
+                    tryPort(port + 1, left - 1);
+                else
+                    reject(err);
+            });
+            probe.once("listening", () => probe.close(() => resolve(port)));
+            probe.listen(port, host);
+        };
+        tryPort(start, 20);
+    });
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // ── hosted mode (cloud sandbox) ────────────────────────────────────
+    // Driven entirely by env so local behaviour is unchanged. In a per-user
+    // micro-VM the VM boundary is the security model; we still keep the
+    // token + Host/Origin gates, just widened to the public hostname.
+    const hosted = process.env.WEBCODE_HOSTED === "1";
+    if (hosted) {
+        args.dir = process.env.WEBCODE_ROOT ?? args.dir;
+        args.host = "0.0.0.0";
+        args.port = Number(process.env.PORT) || 8080;
+        args.token = process.env.WEBCODE_TOKEN ?? args.token;
+        args.open = false;
+    }
+    let root;
+    try {
+        root = await fsp.realpath(path.resolve(args.dir));
+    }
+    catch {
+        console.error(`zuzuu-web: no such directory: ${args.dir}`);
+        process.exit(1);
+    }
+    if (!hosted && args.host !== "127.0.0.1" && args.host !== "localhost" && args.host !== "::1") {
+        console.error("zuzuu-web: refusing to bind a non-loopback address — the daemon exposes your filesystem and shell.\n" +
+            "  (set WEBCODE_HOSTED=1 only inside an isolated per-user sandbox VM.)");
+        process.exit(1);
+    }
+    const pkg = JSON.parse(await fsp.readFile(path.resolve(HERE, "..", "package.json"), "utf8"));
+    const token = args.token ?? crypto.randomBytes(24).toString("base64url");
+    if (!hosted)
+        await addRecent(root).catch(() => { }); // remember this workspace
+    const port = hosted ? args.port : await findFreePort(args.port, args.host);
+    // Web SPA assets: the published package carries them in web-dist/ (copied
+    // at build time); in the dev workspace fall back to the sibling web package.
+    const packagedWebDist = path.resolve(HERE, "..", "web-dist");
+    const workspaceWebDist = path.resolve(HERE, "..", "..", "web", "dist");
+    const webDist = existsSync(path.join(packagedWebDist, "index.html"))
+        ? packagedWebDist
+        : workspaceWebDist;
+    // public origin(s) allowed in hosted mode (the <app>.fly.dev / custom host)
+    const publicHost = process.env.WEBCODE_PUBLIC_HOST; // e.g. "myapp.fly.dev"
+    const extraOrigins = [
+        ...(args.dev ? ["http://localhost:5173", "http://127.0.0.1:5173"] : []),
+        ...(publicHost ? [`https://${publicHost}`, `http://${publicHost}`] : []),
+    ];
+    const server = new WebcodeServer({
+        root,
+        port,
+        host: args.host,
+        token,
+        webDist,
+        version: pkg.version,
+        hosted,
+        publicHost,
+        extraOrigins: extraOrigins.length ? extraOrigins : undefined,
+    });
+    server.start((boundPort) => {
+        const url = hosted
+            ? `(hosted) listening on :${boundPort}`
+            : `http://127.0.0.1:${boundPort}/?token=${token}`;
+        console.log(`\n  zuzuu-web v${pkg.version}`);
+        console.log(`  workspace  ${root}`);
+        console.log(`  url        ${url}\n`);
+        if (args.open)
+            openBrowser(url);
+    });
+    const shutdown = () => {
+        server.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+void main();

package/web-app/dist/protocol/index.js

@@ -0,0 +1,53 @@
+/**
+ * Shared wire protocol between the webcode daemon and the web UI.
+ *
+ * Terminal WebSocket (`/ws/term/:sessionId`) uses binary frames with a
+ * 1-byte opcode prefix (ttyd-style). Everything after the opcode byte is
+ * the payload: raw bytes for I/O, UTF-8 JSON for control frames.
+ */
+// ── Terminal WS: client → server ────────────────────────────────────────
+export const ClientOp = {
+    /** payload: raw UTF-8 keystrokes / pasted data */
+    Input: 0x00,
+    /** payload: JSON ResizePayload */
+    Resize: 0x01,
+    /**
+     * payload: JSON AckPayload — client reports bytes fully written to
+     * xterm.js (via term.write callback). Drives server-side flow control.
+     */
+    Ack: 0x02,
+};
+// ── Terminal WS: server → client ────────────────────────────────────────
+export const ServerOp = {
+    /** payload: raw PTY output bytes */
+    Output: 0x00,
+    /** payload: JSON ExitPayload — PTY exited */
+    Exit: 0x01,
+    /**
+     * payload: raw bytes — serialized terminal state replayed on attach.
+     * Rendered like Output but excluded from flow-control accounting.
+     */
+    Replay: 0x02,
+    /** payload: JSON TitlePayload */
+    Title: 0x03,
+    /** payload: JSON CwdPayload — the shell's working directory changed */
+    Cwd: 0x04,
+};
+/** Flow control watermarks (bytes in flight, i.e. sent but not yet acked). */
+export const FLOW_HIGH_WATER = 128 * 1024;
+export const FLOW_LOW_WATER = 16 * 1024;
+/** Client sends an ack at least every this-many written bytes. */
+export const ACK_INTERVAL = 32 * 1024;
+/**
+ * POSIX single-quote escaping for paths injected into the terminal
+ * (e.g. the tree's "cd here" action): wraps in single quotes, with embedded
+ * single quotes as '\'' so the shell never interprets the content.
+ */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** Substitute {{arg}} placeholders in a workflow command. */
+export function applyWorkflow(command, values) {
+    return command.replace(/\{\{\s*(\w+)\s*\}\}/g, (_m, name) => values[name] ?? "");
+}
+export * from "./zuzuu.js";

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

@@ -0,0 +1,2 @@
+// Shared types for the zuzuu faculties dashboard (the /api/zuzuu/* contract).
+export {};

package/web-app/dist/safe-path.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+/**
+ * Every filesystem path the browser sends goes through this module before
+ * touching disk. The daemon runs with the user's full filesystem rights, so
+ * this is the security choke point: it must reject `..` traversal, absolute
+ * escapes, and symlinks that point outside the workspace root.
+ */
+export class PathError extends Error {
+    status = 403;
+}
+/**
+ * Resolve a workspace-relative input against the root and reject anything
+ * that lexically escapes it. Pure string logic — no filesystem access.
+ * A leading `/` in the input is treated as "relative to the workspace root".
+ */
+export function safeJoin(root, input) {
+    if (input.includes("\0"))
+        throw new PathError("invalid path");
+    const rel = input.replace(/^[/\\]+/, "");
+    const resolved = path.resolve(root, rel);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new PathError(`path escapes workspace: ${input}`);
+    }
+    return resolved;
+}
+/**
+ * `safeJoin` plus symlink defense: the deepest existing ancestor of the
+ * resolved path is realpath'd and must still live inside the (already
+ * realpath'd) root. Defends against both a symlink at the target itself and
+ * symlinked intermediate directories pointing out of the workspace.
+ *
+ * `realRoot` MUST be the result of `fs.realpath` (done once at startup).
+ */
+export async function resolveSafe(realRoot, input) {
+    const abs = safeJoin(realRoot, input);
+    let probe = abs;
+    for (;;) {
+        let real;
+        try {
+            real = await fs.realpath(probe);
+        }
+        catch {
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                break; // hit fs root without finding anything
+            probe = parent;
+            continue;
+        }
+        if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+            throw new PathError(`path resolves outside workspace: ${input}`);
+        }
+        break;
+    }
+    return abs;
+}
+/** Workspace-relative display path with forward slashes ("" for the root). */
+export function toRel(root, abs) {
+    return path.relative(root, abs).split(path.sep).join("/");
+}

package/web-app/dist/search.js

@@ -0,0 +1,145 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import { toRel } from "./safe-path.js";
+const execFileAsync = promisify(execFile);
+const MAX_MATCHES = 500;
+const MAX_LINE_LEN = 500;
+let rgAvailable = null;
+async function hasRg() {
+    if (rgAvailable === null) {
+        rgAvailable = await execFileAsync("rg", ["--version"], { timeout: 2000 })
+            .then(() => true)
+            .catch(() => false);
+    }
+    return rgAvailable;
+}
+export async function search(opts) {
+    return (await hasRg()) ? rgSearch(opts) : grepSearch(opts);
+}
+/** Run a process, collecting stdout until the match cap is hit, then kill. */
+function collectLines(cmd, args, cwd, onLine) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+        let buf = "";
+        let truncated = false;
+        let settled = false;
+        const finish = () => {
+            if (!settled) {
+                settled = true;
+                resolve({ truncated });
+            }
+        };
+        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 && !onLine(line)) {
+                    truncated = true;
+                    proc.kill("SIGTERM");
+                    finish();
+                    return;
+                }
+            }
+        });
+        proc.on("error", (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+        proc.on("close", () => {
+            if (buf.trim() && !settled)
+                onLine(buf.trim());
+            finish();
+        });
+    });
+}
+async function rgSearch(opts) {
+    const args = [
+        "--json",
+        "--max-filesize",
+        "1M",
+        "--max-columns",
+        String(MAX_LINE_LEN),
+        "--max-columns-preview",
+    ];
+    if (!opts.caseSensitive)
+        args.push("-i");
+    if (!opts.regex)
+        args.push("-F");
+    args.push("-e", opts.query, "--", ".");
+    const byFile = new Map();
+    let total = 0;
+    const { truncated } = await collectLines("rg", args, opts.searchRoot, (line) => {
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            return true;
+        }
+        if (ev.type !== "match" || !ev.data?.path?.text)
+            return true;
+        const abs = path.resolve(opts.searchRoot, ev.data.path.text);
+        const rel = toRel(opts.root, abs);
+        const text = (ev.data.lines?.text ?? "").replace(/\n$/, "").slice(0, MAX_LINE_LEN);
+        const match = {
+            line: ev.data.line_number ?? 0,
+            text,
+            ranges: (ev.data.submatches ?? [])
+                .filter((s) => s.start < MAX_LINE_LEN)
+                .map((s) => [s.start, Math.min(s.end, MAX_LINE_LEN)]),
+        };
+        const list = byFile.get(rel) ?? [];
+        list.push(match);
+        byFile.set(rel, list);
+        total += 1;
+        return total < MAX_MATCHES;
+    });
+    return { results: toResults(byFile), total, truncated, engine: "rg" };
+}
+async function grepSearch(opts) {
+    const args = [
+        "-rnI",
+        "--exclude-dir=.git",
+        "--exclude-dir=node_modules",
+        "--exclude-dir=dist",
+    ];
+    if (!opts.caseSensitive)
+        args.push("-i");
+    args.push(opts.regex ? "-E" : "-F", opts.query, ".");
+    const byFile = new Map();
+    let total = 0;
+    const { truncated } = await collectLines("grep", args, opts.searchRoot, (line) => {
+        // ./path:line:text  (filenames with ":" are rare; accept the ambiguity)
+        const m = /^(.+?):(\d+):(.*)$/.exec(line);
+        if (!m)
+            return true;
+        const abs = path.resolve(opts.searchRoot, m[1]);
+        const rel = toRel(opts.root, abs);
+        const text = m[3].slice(0, MAX_LINE_LEN);
+        // grep gives no offsets — compute first occurrence for highlighting
+        const ranges = [];
+        if (!opts.regex) {
+            const haystack = opts.caseSensitive ? text : text.toLowerCase();
+            const needle = opts.caseSensitive ? opts.query : opts.query.toLowerCase();
+            const idx = haystack.indexOf(needle);
+            if (idx >= 0)
+                ranges.push([idx, idx + needle.length]);
+        }
+        const list = byFile.get(rel) ?? [];
+        list.push({ line: Number(m[2]), text, ranges });
+        byFile.set(rel, list);
+        total += 1;
+        return total < MAX_MATCHES;
+    }).catch(() => ({ truncated: false })); // grep exits 1 on no matches via error? no — only spawn errors land here
+    return { results: toResults(byFile), total, truncated, engine: "grep" };
+}
+function toResults(byFile) {
+    return [...byFile.entries()]
+        .map(([p, matches]) => ({ path: p, matches }))
+        .sort((a, b) => a.path.localeCompare(b.path));
+}