huddle-cli 0.0.0-stage → 0.1.0

package/dist/room/sqlite.js

@@ -0,0 +1,156 @@
+// The Room's SQLite driver, with a fallback so a fresh machine never dead-ends
+// on a native build. Preferred: better-sqlite3 (fast, proven, but a native
+// addon — it needs a prebuilt binary for this Node, or a C++ toolchain). If it
+// didn't install or was built for another Node version, Huddle uses Node's
+// built-in `node:sqlite` (Node 22.13+ without flags). Neither → one clear,
+// actionable message instead of a stack trace.
+//
+// Only the slice of the API RoomDB uses is wrapped: exec / prepare().run|get|all
+// (positional or @named params) / pragma / transaction / close.
+//
+//   HUDDLE_SQLITE=node     force node:sqlite (tests, or to skip a broken addon)
+//   HUDDLE_SQLITE=better   force better-sqlite3 (no fallback)
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+/** A message meant for the user, printed as-is by the CLI (no stack). */
+export class SqliteUnavailableError extends Error {
+}
+function short(e) {
+    let m = String(e?.message ?? e).split("\n")[0];
+    // Say what the usual addon failures mean instead of echoing their internals.
+    if (/Could not locate the bindings file/i.test(m))
+        m = "its native binary isn't built for this machine";
+    else if (/NODE_MODULE_VERSION|compiled against a different Node/i.test(m))
+        m = "its native binary was built for a different Node version";
+    else if (/Cannot find (module|package) 'better-sqlite3'/i.test(m))
+        m = "not installed (it's optional, and its build was skipped or failed)";
+    return m.length > 160 ? m.slice(0, 159) + "…" : m;
+}
+function openBetter(path) {
+    const Database = require("better-sqlite3");
+    const db = new Database(path); // loads the native addon; throws if it's missing/mismatched
+    return {
+        driver: "better-sqlite3",
+        exec: (sql) => void db.exec(sql),
+        prepare: (sql) => db.prepare(sql),
+        pragma: (sql) => void db.pragma(sql),
+        transaction: (fn) => db.transaction(fn),
+        close: () => db.close(),
+    };
+}
+/** node:sqlite, loaded synchronously, with its one-time ExperimentalWarning muted. */
+function loadNodeSqlite() {
+    const emit = process.emitWarning;
+    process.emitWarning = ((w, ...rest) => {
+        const text = String(w?.message ?? w);
+        const type = typeof rest[0] === "string" ? rest[0] : rest[0]?.type ?? w?.name;
+        if (type === "ExperimentalWarning" && /sqlite/i.test(text))
+            return;
+        return emit.call(process, w, ...rest);
+    });
+    try {
+        return require("node:sqlite");
+    }
+    finally {
+        process.emitWarning = emit;
+    }
+}
+// node:sqlite rows have a null prototype; hand back plain objects like better-sqlite3.
+const plain = (row) => (row && typeof row === "object" ? { ...row } : row);
+function openNode(path) {
+    const { DatabaseSync } = loadNodeSqlite();
+    const db = new DatabaseSync(path);
+    // better-sqlite3 waits up to 5s on a locked db; node:sqlite defaults to 0.
+    db.exec("PRAGMA busy_timeout = 5000");
+    let depth = 0;
+    return {
+        driver: "node:sqlite",
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.prepare(sql);
+            return {
+                run: (...p) => st.run(...p),
+                get: (...p) => plain(st.get(...p)) ?? undefined,
+                all: (...p) => st.all(...p).map(plain),
+            };
+        },
+        pragma: (sql) => db.exec(`PRAGMA ${sql}`),
+        transaction: (fn) => () => {
+            // Nested calls run inside the outer transaction (better-sqlite3 uses savepoints; we don't nest).
+            if (depth > 0)
+                return fn();
+            db.exec("BEGIN");
+            depth++;
+            try {
+                const r = fn();
+                db.exec("COMMIT");
+                return r;
+            }
+            catch (e) {
+                db.exec("ROLLBACK");
+                throw e;
+            }
+            finally {
+                depth--;
+            }
+        },
+        close: () => db.close(),
+    };
+}
+/** Open the Room db with the best driver available on this machine. */
+export function openDatabase(path) {
+    const want = process.env.HUDDLE_SQLITE;
+    if (want === "node")
+        return openNodeOrExplain(path, null);
+    try {
+        return openBetter(path);
+    }
+    catch (e) {
+        // A bad path / permissions isn't a driver problem — don't mask it.
+        if (e?.code === "SQLITE_CANTOPEN" || /unable to open database/i.test(short(e)))
+            throw e;
+        if (want === "better")
+            throw explain(e, null);
+        return openNodeOrExplain(path, e);
+    }
+}
+function openNodeOrExplain(path, betterErr) {
+    try {
+        return openNode(path);
+    }
+    catch (e) {
+        // node:sqlite exists but the db itself failed (path, permissions) — show that.
+        if (/unable to open|SQLITE_CANTOPEN/i.test(short(e)))
+            throw e;
+        throw explain(betterErr, e);
+    }
+}
+function explain(betterErr, nodeErr) {
+    const v = process.versions.node;
+    const major = Number(v.split(".")[0]);
+    const minor = Number(v.split(".")[1]);
+    const builtin = major > 22 || (major === 22 && minor >= 13);
+    const lines = [`Huddle couldn't open its room database (SQLite) on Node ${v}.`];
+    if (betterErr)
+        lines.push(`  better-sqlite3: ${short(betterErr)}`);
+    if (nodeErr)
+        lines.push(`  node:sqlite:    ${short(nodeErr)}`);
+    lines.push("", "Fix it with one of these:", "  • reinstall, so the native module is built for this Node:  npm install -g huddle-cli");
+    // On 22.13+ node:sqlite was already tried (and its error is above), so only suggest it to older Nodes.
+    if (!builtin)
+        lines.push("  • or use Node 22.13+ — Huddle then falls back to Node's built-in SQLite, nothing to build");
+    lines.push("  • building it needs a C++ toolchain: macOS `xcode-select --install` · Debian/Ubuntu `sudo apt install build-essential python3`");
+    return new SqliteUnavailableError(lines.join("\n"));
+}
+/** Which driver works here, or why none does — for `huddle doctor`. Opens nothing on disk. */
+export function sqliteStatus() {
+    try {
+        const db = openDatabase(":memory:");
+        db.close();
+        return { ok: true, driver: db.driver };
+    }
+    catch (e) {
+        return { ok: false, message: String(e?.message ?? e) };
+    }
+}
+//# sourceMappingURL=sqlite.js.map

package/dist/room/transport.js

@@ -0,0 +1,107 @@
+// How a teammate's Huddle reaches a room. Two ways, same shared API:
+//   direct  http(s)://host:port   — Wi-Fi, Tailscale, or a tunnel
+//   relay   wss://relay/r/<room>  — both sides dial out to a relay; works across any networks
+// Either way the host's Room enforces everything; transports just carry bytes.
+import { WebSocket } from "ws";
+export function transportFor(address) {
+    const a = address.trim().replace(/\/+$/, "");
+    if (/^wss?:\/\//.test(a))
+        return relayTransport(a);
+    return directTransport(/^https?:\/\//.test(a) ? a : `http://${a}`);
+}
+function directTransport(base) {
+    let ws = null;
+    return {
+        describe: base,
+        async request(method, path, body, token) {
+            const r = await fetch(`${base}${path}`, {
+                method,
+                headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+                body: method === "POST" ? JSON.stringify(body ?? {}) : undefined,
+                signal: AbortSignal.timeout(20_000),
+            });
+            return { status: r.status, body: await r.json().catch(() => ({})) };
+        },
+        events(token, onEvent, onClose) {
+            ws = new WebSocket(`${base.replace(/^http/, "ws")}/?token=${encodeURIComponent(token)}`);
+            ws.on("message", (raw) => {
+                try {
+                    onEvent(JSON.parse(String(raw)));
+                }
+                catch {
+                    /* ignore */
+                }
+            });
+            ws.on("close", (code) => onClose(code));
+            ws.on("error", () => { });
+        },
+        close() {
+            ws?.close();
+        },
+    };
+}
+/**
+ * Relay: one WebSocket to the relay carries both request/response and events.
+ * Frames: {t:"req", id, method, path, body, token} → {t:"res", id, status, body}
+ *         {t:"sub", token} → {t:"event", e} …   and {t:"closed", code}
+ */
+function relayTransport(url) {
+    const ws = new WebSocket(url.includes("/r/") ? url.replace("/r/", "/join/") : url);
+    const ready = new Promise((resolve, reject) => {
+        ws.once("open", () => resolve());
+        ws.once("error", (e) => reject(e));
+    });
+    let n = 0;
+    const pending = new Map();
+    let onEvent = null;
+    let onClose = null;
+    ws.on("message", (raw) => {
+        let f;
+        try {
+            f = JSON.parse(String(raw));
+        }
+        catch {
+            return;
+        }
+        if (f.t === "res")
+            pending.get(f.id)?.({ status: f.status, body: f.body }), pending.delete(f.id);
+        else if (f.t === "event")
+            onEvent?.(f.e);
+        else if (f.t === "closed")
+            onClose?.(f.code ?? 1000);
+    });
+    ws.on("close", (code) => {
+        for (const r of pending.values())
+            r({ status: 503, body: { error: "relay connection closed" } });
+        pending.clear();
+        onClose?.(code === 1000 ? 1000 : 4500);
+    });
+    ws.on("error", () => { });
+    return {
+        describe: url,
+        async request(method, path, body, token) {
+            await ready;
+            const id = ++n;
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    resolve({ status: 504, body: { error: "room didn't answer through the relay (is the host's Huddle open?)" } });
+                }, 20_000);
+                pending.set(id, (r) => {
+                    clearTimeout(timer);
+                    resolve(r);
+                });
+                ws.send(JSON.stringify({ t: "req", id, method, path, body: body ?? {}, token }));
+            });
+        },
+        events(token, ev, close) {
+            onEvent = ev;
+            onClose = close;
+            void ready.then(() => ws.send(JSON.stringify({ t: "sub", token })));
+        },
+        close() {
+            ws.close(1000);
+        },
+    };
+}
+//# sourceMappingURL=transport.js.map

package/dist/room/tunnel.js

@@ -0,0 +1,85 @@
+// Making the shared door reachable from anywhere, not just your Wi-Fi.
+// Uses Cloudflare's free quick tunnels (`cloudflared tunnel --url …`): no
+// account, no config, a random https URL that dies when Huddle exits. Only the
+// shared door is exposed — your agents' local door stays on 127.0.0.1.
+import { spawn, spawnSync } from "node:child_process";
+export function hasCloudflared() {
+    return spawnSync(process.platform === "win32" ? "where" : "which", ["cloudflared"], { stdio: "pipe" }).status === 0;
+}
+export async function openTunnel(port, log, timeoutMs = 25_000) {
+    if (!hasCloudflared() || process.env.HUDDLE_NO_TUNNEL)
+        return null;
+    log("  opening a public tunnel (cloudflared)…");
+    const child = spawn("cloudflared", ["tunnel", "--no-autoupdate", "--url", `http://127.0.0.1:${port}`], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    const url = await new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(null), timeoutMs);
+        const scan = (d) => {
+            const m = /https:\/\/(?!api\.)[a-z0-9]+(?:-[a-z0-9]+)+\.trycloudflare\.com/.exec(d.toString()); // not api.trycloudflare.com
+            if (m) {
+                clearTimeout(timer);
+                resolve(m[0]);
+            }
+        };
+        child.stdout.on("data", scan);
+        child.stderr.on("data", scan);
+        child.on("exit", () => resolve(null));
+    });
+    if (!url) {
+        child.kill();
+        log("  couldn't open a tunnel — falling back to your local network");
+        return null;
+    }
+    const close = () => child.kill();
+    process.once("exit", close);
+    return { url, close };
+}
+/** Your Tailscale address, if Tailscale is running — reachable by anyone on your tailnet, from anywhere. */
+export function tailscaleIp() {
+    const r = spawnSync("tailscale", ["ip", "-4"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 3000 });
+    const ip = (r.stdout ?? "").trim().split("\n")[0];
+    return r.status === 0 && /^\d+\.\d+\.\d+\.\d+$/.test(ip) ? ip : null;
+}
+/**
+ * Tailscale Funnel: a public https://<machine>.<tailnet>.ts.net/huddle address
+ * for this room's shared door — no server, works from any network, uses your
+ * Tailscale account. Mounted at /huddle so it never touches your other serves.
+ */
+export function openFunnel(port) {
+    const st = spawnSync("tailscale", ["status", "--json"], { encoding: "utf8", timeout: 5000 });
+    if (st.error)
+        return { ok: false, reason: "Tailscale isn't installed" };
+    let dns = "";
+    try {
+        const j = JSON.parse(st.stdout);
+        if (j.BackendState !== "Running")
+            return { ok: false, reason: "Tailscale is stopped — run `tailscale up` (or open the Tailscale app) and sign in" };
+        dns = String(j.Self?.DNSName ?? "").replace(/\.$/, "");
+    }
+    catch {
+        return { ok: false, reason: "couldn't read Tailscale status" };
+    }
+    if (!dns)
+        return { ok: false, reason: "this machine has no Tailscale name yet" };
+    const r = spawnSync("tailscale", ["funnel", "--bg", "--yes", "--set-path", "/huddle", `http://127.0.0.1:${port}`], {
+        encoding: "utf8",
+        timeout: 20_000,
+    });
+    if (r.status !== 0) {
+        const err = `${r.stderr}${r.stdout}`.trim();
+        const link = /https:\/\/login\.tailscale\.com\S+/.exec(err)?.[0];
+        return {
+            ok: false,
+            reason: /not enabled|funnel.*(disabled|not allowed)|nodeAttr|policy/i.test(err)
+                ? `Funnel isn't enabled for your tailnet yet — turn it on once${link ? ": " + link : " in the Tailscale admin (Access controls → funnel)"}`
+                : err.split("\n")[0] || "tailscale funnel failed",
+        };
+    }
+    const close = () => {
+        spawnSync("tailscale", ["funnel", "--set-path", "/huddle", "off"], { stdio: "ignore", timeout: 10_000 });
+    };
+    process.once("exit", close);
+    return { ok: true, url: `https://${dns}/huddle`, close };
+}
+//# sourceMappingURL=tunnel.js.map

package/dist/sandbox/sync.js

@@ -0,0 +1,104 @@
+// Git sync: the code layer between people. Huddle never moves code itself —
+// GitHub (or any git remote) does. Before a run we fast-forward to the latest
+// shared main; after a run we push everything that merged, in one go.
+//
+// Pushing reaches outside this machine, so it's opt-in per repo: the first
+// time a repo with a remote runs a goal, Huddle asks once and remembers it in
+// .huddle/config.json.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+function git(cwd, args, timeoutMs = 60_000) {
+    const r = spawnSync("git", args, { cwd, encoding: "utf8", timeout: timeoutMs, env: { ...process.env, GIT_TERMINAL_PROMPT: "0" } });
+    return { ok: r.status === 0, out: (r.stdout ?? "").trim(), err: (r.stderr ?? "").trim() };
+}
+const cfgPath = (root) => path.join(root, ".huddle", "config.json");
+export function readRepoConfig(root) {
+    try {
+        return JSON.parse(fs.readFileSync(cfgPath(root), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeRepoConfig(root, c) {
+    fs.mkdirSync(path.dirname(cfgPath(root)), { recursive: true });
+    fs.writeFileSync(cfgPath(root), JSON.stringify({ ...readRepoConfig(root), ...c }, null, 2));
+}
+/** The remote this repo shares through, e.g. "origin → github.com/Preet37/Huddle". */
+export function remoteInfo(root) {
+    const branch = git(root, ["symbolic-ref", "--short", "HEAD"]).out;
+    const upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    const name = upstream.ok ? upstream.out.split("/")[0] : "origin";
+    const url = git(root, ["remote", "get-url", name]);
+    if (!url.ok || !branch)
+        return null;
+    return { name, url: url.out, branch };
+}
+/** "git@github.com:Preet37/Huddle.git" → "github.com/Preet37/Huddle" — for matching clones. */
+export function canonicalRemote(url) {
+    return url
+        .trim()
+        .replace(/^git@([^:]+):/, "$1/")
+        .replace(/^[a-z+]+:\/\/([^@/]+@)?/, "")
+        .replace(/\.git$/, "")
+        .replace(/\/+$/, "")
+        .toLowerCase();
+}
+/** Bring local main up to the shared main before agents branch off it. */
+export function pullLatest(root) {
+    const r = remoteInfo(root);
+    if (!r)
+        return { ok: true, note: "no remote" };
+    const f = git(root, ["fetch", "--quiet", r.name, r.branch]);
+    if (!f.ok)
+        return { ok: false, note: `couldn't reach ${r.name}: ${f.err.split("\n")[0]}` };
+    const behind = Number(git(root, ["rev-list", "--count", `HEAD..${r.name}/${r.branch}`]).out || 0);
+    if (!behind)
+        return { ok: true, note: "up to date" };
+    const m = git(root, ["merge", "--ff-only", "--quiet", `${r.name}/${r.branch}`]);
+    if (!m.ok)
+        return { ok: false, note: `local ${r.branch} and ${r.name} have diverged — pull/rebase once by hand` };
+    return { ok: true, note: `pulled ${behind} new commit${behind > 1 ? "s" : ""}` };
+}
+/** Push everything that merged, in one go. Rebases once if someone pushed meanwhile. */
+export function pushMerged(root) {
+    const r = remoteInfo(root);
+    if (!r)
+        return { ok: false, note: "no remote to push to" };
+    let p = git(root, ["push", "--quiet", r.name, `HEAD:${r.branch}`], 120_000);
+    if (!p.ok && /rejected|fetch first|non-fast-forward/i.test(p.err)) {
+        const rb = git(root, ["pull", "--rebase", "--quiet", r.name, r.branch], 120_000);
+        if (!rb.ok) {
+            git(root, ["rebase", "--abort"]);
+            return { ok: false, note: `${r.name} moved and the rebase conflicts — resolve and push by hand` };
+        }
+        p = git(root, ["push", "--quiet", r.name, `HEAD:${r.branch}`], 120_000);
+    }
+    if (!p.ok)
+        return { ok: false, note: p.err.split("\n").slice(-1)[0] || "push failed" };
+    return { ok: true, note: `${r.name}/${r.branch}` };
+}
+/** Push a task branch so the room's merger can fetch it (delegated work). */
+export function pushBranch(root, branch) {
+    const r = remoteInfo(root);
+    if (!r)
+        return { ok: false, note: "no remote" };
+    const p = git(root, ["push", "--quiet", "--force-with-lease", r.name, `${branch}:${branch}`], 120_000);
+    return p.ok ? { ok: true, note: `${r.name}/${branch}` } : { ok: false, note: p.err.split("\n").slice(-1)[0] };
+}
+/** Fetch a teammate's task branch into a local branch of the same name. */
+export function fetchBranch(root, branch) {
+    const r = remoteInfo(root);
+    if (!r)
+        return { ok: false, note: "no remote" };
+    const f = git(root, ["fetch", "--quiet", r.name, `+${branch}:${branch}`], 120_000);
+    return f.ok ? { ok: true, note: branch } : { ok: false, note: f.err.split("\n").slice(-1)[0] };
+}
+/** Clean up a task branch on the remote after it merged. Best effort. */
+export function deleteRemoteBranch(root, branch) {
+    const r = remoteInfo(root);
+    if (r)
+        git(root, ["push", "--quiet", r.name, "--delete", branch]);
+}
+//# sourceMappingURL=sync.js.map