huddle-cli 0.0.0-stage → 0.1.1

package/dist/attach/live.js

@@ -0,0 +1,226 @@
+// Attach mode, the daemon: one long-lived Room per repo for the sessions you
+// run yourself. `huddle up` starts it in the background (or finds the one
+// already running), `huddle down` stops it. Everything it needs is under
+// .huddle/ (never committed):
+//
+//   .huddle/live.json   pid · port · secret (0600) — how Plugs and hooks find it
+//   .huddle/live.db     its board: leases, notes, shared memory
+//   .huddle/logs/live.log
+//
+// The Plug reads live.json on every connect, so a restarted room (new port,
+// new secret) is picked up without rewriting anyone's MCP config.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RoomDB } from "../room/db.js";
+import { liveRoom } from "../room/live.js";
+import { startRoom } from "../room/server.js";
+// dist/attach/live.js -> dist/cli.js
+export const CLI_PATH = fileURLToPath(new URL("../cli.js", import.meta.url));
+/**
+ * The main checkout's root for wherever we are — also from inside a worktree
+ * (git-common-dir is the main repo's .git). null outside git.
+ */
+export function mainRoot(cwd = process.cwd()) {
+    try {
+        const common = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return fs.realpathSync(path.dirname(common));
+    }
+    catch {
+        return null;
+    }
+}
+/** This checkout's root (a worktree's own root when inside one). */
+export function checkoutRoot(cwd = process.cwd()) {
+    try {
+        return fs.realpathSync(execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+    }
+    catch {
+        return null;
+    }
+}
+export const liveFiles = (root) => {
+    const dir = path.join(root, ".huddle");
+    return {
+        dir,
+        state: path.join(dir, "live.json"),
+        db: path.join(dir, "live.db"),
+        lock: path.join(dir, "live.lock"),
+        log: path.join(dir, "logs", "live.log"),
+    };
+};
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === "EPERM";
+    }
+}
+/** The running room's state, if its process is still alive. */
+export function readLive(root) {
+    try {
+        const st = JSON.parse(fs.readFileSync(liveFiles(root).state, "utf8"));
+        return st.pid && alive(st.pid) ? st : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Call the live room as `as` (a session id; "" for anonymous verbs). */
+export async function liveCall(st, verb, body = {}, as = "", timeoutMs = 4000) {
+    const res = await fetch(`${st.url}/live/${verb}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-huddle-secret": st.secret, "x-huddle-agent": as },
+        body: JSON.stringify(body ?? {}),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+/** Same as liveCall, for the Room's ordinary agent verbs (/recall, /remember, …). */
+export async function roomCall(st, method, p, body, as) {
+    const res = await fetch(`${st.url}${p}`, {
+        method,
+        headers: { "content-type": "application/json", "x-huddle-secret": st.secret, "x-huddle-agent": as },
+        body: method === "POST" ? JSON.stringify({ agent_id: as, ...body }) : undefined,
+        signal: AbortSignal.timeout(8000),
+    });
+    return res.json();
+}
+export async function pingLive(st) {
+    if (!st)
+        return false;
+    try {
+        return (await liveCall(st, "ping", {}, "", 1500)).status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+export function ensureHuddleDir(root) {
+    const f = liveFiles(root);
+    fs.mkdirSync(path.dirname(f.log), { recursive: true });
+    const gi = path.join(f.dir, ".gitignore");
+    if (!fs.existsSync(gi))
+        fs.writeFileSync(gi, "*\n"); // keep .huddle/ out of commits
+}
+/**
+ * Find the repo's live room, or start it in the background. Safe to call from
+ * several Plugs at once: a lock file makes sure only one daemon starts.
+ */
+export async function ensureLive(root, timeoutMs = 8000) {
+    const st = readLive(root);
+    if (st && (await pingLive(st)))
+        return { state: st, started: false };
+    ensureHuddleDir(root);
+    const f = liveFiles(root);
+    let mine = false;
+    try {
+        fs.writeFileSync(f.lock, String(process.pid), { flag: "wx" });
+        mine = true;
+    }
+    catch {
+        // Someone else is starting it — unless their lock is stale.
+        try {
+            if (Date.now() - fs.statSync(f.lock).mtimeMs > 10_000) {
+                fs.writeFileSync(f.lock, String(process.pid));
+                mine = true;
+            }
+        }
+        catch {
+            /* lock vanished: they finished */
+        }
+    }
+    if (mine) {
+        const out = fs.openSync(f.log, "a");
+        const child = spawn(process.execPath, [CLI_PATH, "up", "--serve"], {
+            cwd: root,
+            detached: true,
+            windowsHide: true, // detached on Windows = a new console window, unless hidden
+            stdio: ["ignore", out, out],
+            env: { ...process.env, HUDDLE_LIVE_ROOT: root },
+        });
+        child.unref();
+        fs.closeSync(out);
+    }
+    const deadline = Date.now() + timeoutMs;
+    try {
+        while (Date.now() < deadline) {
+            const s = readLive(root);
+            if (s && (await pingLive(s)))
+                return { state: s, started: mine };
+            await new Promise((r) => setTimeout(r, 100));
+        }
+    }
+    finally {
+        if (mine)
+            fs.rmSync(f.lock, { force: true });
+    }
+    throw new Error(`the live room didn't start — see ${path.relative(root, f.log)}`);
+}
+/** The daemon itself (`huddle up --serve`). Runs until `huddle down` or idle. */
+export async function serveLive(root) {
+    ensureHuddleDir(root);
+    const f = liveFiles(root);
+    const other = readLive(root);
+    if (other && other.pid !== process.pid && (await pingLive(other))) {
+        console.log(`live room already running (pid ${other.pid})`);
+        return;
+    }
+    const db = new RoomDB(f.db);
+    const room = await startRoom(db, Number(process.env.HUDDLE_LIVE_PORT ?? 0), { host: "live" });
+    room.live = liveRoom(db, { repoRoot: root, staleMs: Number(process.env.HUDDLE_LIVE_STALE_MS ?? 60_000) });
+    const st = { pid: process.pid, port: room.port, url: room.url, secret: room.secret, root, started_at: Date.now() };
+    const tmp = `${f.state}.${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(st, null, 2), { mode: 0o600 });
+    fs.renameSync(tmp, f.state);
+    console.log(`${new Date().toISOString()} live room up on ${room.url} (pid ${process.pid})`);
+    let lastBusy = Date.now();
+    const IDLE_MS = Number(process.env.HUDDLE_LIVE_IDLE_MS ?? 6 * 3600_000);
+    const stop = (why) => {
+        console.log(`${new Date().toISOString()} live room stopping: ${why}`);
+        try {
+            const cur = JSON.parse(fs.readFileSync(f.state, "utf8"));
+            if (cur.pid === process.pid)
+                fs.rmSync(f.state, { force: true });
+        }
+        catch {
+            /* already gone */
+        }
+        room.live?.close();
+        room.close();
+        db.close();
+        process.exit(0);
+    };
+    process.on("SIGTERM", () => stop("huddle down"));
+    process.on("SIGINT", () => stop("interrupted"));
+    // No live sessions for IDLE_MS (default 6h) = nobody needs it; leave quietly.
+    setInterval(() => {
+        if (room.live.sessions().length)
+            lastBusy = Date.now();
+        else if (Date.now() - lastBusy > IDLE_MS)
+            stop("idle");
+    }, Math.min(IDLE_MS, 60_000));
+}
+/** `huddle down`. True if a room was running. */
+export async function stopLive(root) {
+    const st = readLive(root);
+    if (!st) {
+        fs.rmSync(liveFiles(root).state, { force: true });
+        return false;
+    }
+    process.kill(st.pid, "SIGTERM");
+    for (let i = 0; i < 50 && alive(st.pid); i++)
+        await new Promise((r) => setTimeout(r, 100));
+    // On Windows "SIGTERM" is TerminateProcess: the daemon's handler never runs, so tidy up for it.
+    if (!alive(st.pid))
+        fs.rmSync(liveFiles(root).state, { force: true });
+    return true;
+}
+//# sourceMappingURL=live.js.map

package/dist/attach/plug.js

@@ -0,0 +1,185 @@
+// Attach mode, the agent side: the Plug as seen by a session YOU started
+// (claude / codex / cursor in your own terminal). `huddle connect` puts this in
+// each agent's project MCP config with HUDDLE_LIVE=1. There's no scheduler and
+// no task id: the session says hello to the repo's live room (starting it if
+// needed), and its tools are about sharing the repo safely with the others.
+import { execFileSync } from "node:child_process";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { contextTools, toContent } from "../mcp/context-tools.js";
+import { packageInfo } from "../preflight.js";
+import { checkoutRoot, ensureLive, liveCall, mainRoot, roomCall } from "./live.js";
+/** What every attached agent is told, via the MCP `instructions` field. */
+export const LIVE_INSTRUCTIONS = `
+You are one of several AI coding sessions (e.g. claude, codex, cursor) working in this same repo at the same time, coordinated by Huddle.
+Before you edit ANY file:
+1. huddle_peers — see who else is live, what they're doing, which files they hold.
+2. huddle_announce_plan(intent, touches) with every file (or "dir/") you'll change. If it returns conflicts, DO NOT edit those files: huddle_note the holder or pick other work, and tell your user.
+3. When you finish a change, huddle_release so the others can proceed.
+Notes from other sessions arrive in "notes_for_you" on any huddle_* reply — read them and answer with huddle_note. Record lasting decisions with huddle_remember.
+The shared screen holds what your user put up for everyone (logs, docs, screenshots): huddle_context lists it, huddle_context_read / huddle_context_search open it, huddle_context_note pins what you found.
+`.trim();
+const tools = [
+    {
+        name: "huddle_peers",
+        description: "See every OTHER live AI session in this repo right now (claude, codex, cursor…): what each is doing, which files it holds, recent notes. Call this before you start editing.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "huddle_announce_plan",
+        description: "BEFORE editing: say what you're about to do and every file you'll touch ('path', 'dir/' or 'path::symbol'). Leases the free ones to you; returns conflicts for any another live session holds — don't edit those.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                intent: { type: "string", description: "one line: what you're changing and why" },
+                touches: { type: "array", items: { type: "string" } },
+            },
+            required: ["intent", "touches"],
+        },
+    },
+    {
+        name: "huddle_check_overlap",
+        description: "Is anyone else holding these files? ('path', 'dir/', 'path::symbol'). Read-only — takes no lease.",
+        inputSchema: { type: "object", properties: { touches: { type: "array", items: { type: "string" } } }, required: ["touches"] },
+    },
+    {
+        name: "huddle_release",
+        description: "You're done with these files (omit `touches` = all of yours). Others waiting on them can go ahead.",
+        inputSchema: { type: "object", properties: { touches: { type: "array", items: { type: "string" } } } },
+    },
+    {
+        name: "huddle_note",
+        description: "Leave a note for the other sessions — everyone, or one by id/agent ('codex', 'claude#2'). E.g. 'I renamed User.email to User.mail, update your callers'. They see it on their next huddle_* call.",
+        inputSchema: {
+            type: "object",
+            properties: { body: { type: "string" }, to: { type: "string", description: "optional: a session id or agent name; default everyone" } },
+            required: ["body"],
+        },
+    },
+    {
+        name: "huddle_remember",
+        description: "Write to the repo's SHARED MEMORY (kind = decision | fact | gotcha) so every session, now and later, inherits it. Include 'why'.",
+        inputSchema: {
+            type: "object",
+            properties: { kind: { type: "string", enum: ["decision", "fact", "gotcha"] }, body: { type: "string" }, why: { type: "string" } },
+            required: ["kind", "body"],
+        },
+    },
+    {
+        name: "huddle_recall",
+        description: "Read shared memory: decisions, facts and gotchas other sessions recorded. Optional text filter.",
+        inputSchema: { type: "object", properties: { query: { type: "string" } } },
+    },
+];
+function branchOf(dir) {
+    try {
+        return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+export async function runLivePlug() {
+    const agent = process.env.HUDDLE_AGENT_ID ?? "agent";
+    // Claude sets CLAUDE_PROJECT_DIR for its MCP servers; others start us in the project.
+    const here = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const sessionRoot = checkoutRoot(here) ?? here;
+    const repo = process.env.HUDDLE_REPO || mainRoot(here) || sessionRoot;
+    let st = null;
+    let sid = "";
+    let hello = null;
+    const sayHello = () => (hello ??= (async () => {
+        st = (await ensureLive(repo)).state;
+        const r = await liveCall(st, "hello", { agent, pid: process.ppid, root: sessionRoot, branch: branchOf(sessionRoot) });
+        if (r.status !== 200)
+            throw new Error(r.body?.error ?? "hello failed");
+        sid = r.body.id;
+    })().finally(() => (hello = null)));
+    /** One live verb, re-saying hello if the room restarted or forgot us. */
+    const live = async (verb, body) => {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                if (!sid || !st)
+                    await sayHello();
+                const r = await liveCall(st, verb, body, sid);
+                if (r.status === 409 && r.body?.rehello) {
+                    sid = "";
+                    continue;
+                }
+                return r.body;
+            }
+            catch (e) {
+                st = null;
+                sid = "";
+                if (attempt)
+                    throw e;
+            }
+        }
+    };
+    const plain = async (method, p, body) => {
+        if (!sid || !st)
+            await sayHello();
+        return roomCall(st, method, p, body, sid);
+    };
+    // The shared screen: the same tools (and Room routes) as a `huddle join` agent's Plug.
+    const screen = contextTools((p, method, body) => plain(method, p, body ?? {}));
+    const call = (name, a) => {
+        const ctx = screen.find((t) => t.name === name);
+        if (ctx)
+            return ctx.handler(a);
+        switch (name) {
+            case "huddle_peers":
+                return live("peers", {});
+            case "huddle_announce_plan":
+                return live("announce", { intent: a.intent, touches: a.touches ?? [] });
+            case "huddle_check_overlap":
+                return live("check", { touches: a.touches ?? [] });
+            case "huddle_release":
+                return live("release", { touches: a.touches });
+            case "huddle_note":
+                // Models sometimes name it message/text (seen live with claude -p): accept those.
+                return live("note", { body: a.body ?? a.message ?? a.text ?? a.note, to: a.to });
+            case "huddle_remember":
+                return plain("POST", "/remember", { kind: a.kind, body: a.body, why: a.why ?? "" });
+            case "huddle_recall":
+                return plain("GET", `/recall${a.query ? `?q=${encodeURIComponent(a.query)}` : ""}`, {});
+        }
+        throw new Error(`unknown tool: ${name}`);
+    };
+    const server = new Server({ name: "huddle", version: packageInfo().version }, { capabilities: { tools: {} }, instructions: LIVE_INSTRUCTIONS });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...tools.map((t) => ({ ...t })), ...screen.map(({ handler: _h, ...t }) => t)],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        try {
+            const result = await call(req.params.name, req.params.arguments ?? {});
+            // toContent: JSON text, plus an MCP image block for a screenshot.
+            return { content: toContent(result) };
+        }
+        catch (e) {
+            // Never wedge the agent: say what's wrong and let it carry on.
+            return { isError: true, content: [{ type: "text", text: `Huddle live room unavailable (${e?.message ?? e}). Tell your user to run \`huddle up\`.` }] };
+        }
+    });
+    // Be visible to the other sessions from the moment this one opens.
+    sayHello().catch(() => { });
+    const beat = setInterval(() => void live("heartbeat", {}).catch(() => { }), Number(process.env.HUDDLE_LIVE_BEAT_MS ?? 15_000));
+    beat.unref();
+    let closing = false;
+    const goodbye = async () => {
+        if (closing)
+            return;
+        closing = true;
+        clearInterval(beat);
+        if (st && sid)
+            await liveCall(st, "bye", {}, sid, 1500).catch(() => { });
+        process.exit(0);
+    };
+    process.stdin.on("end", goodbye);
+    process.stdin.on("close", goodbye);
+    process.on("SIGTERM", goodbye);
+    process.on("SIGINT", goodbye);
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=plug.js.map

package/dist/attach/screen.js

@@ -0,0 +1,150 @@
+// Attach mode, the human's side of the shared screen: `huddle add` and
+// `huddle ctx`, typed in any terminal while your own claude / codex / cursor
+// sessions run in theirs.
+//
+//   huddle add err.log src/auth/ "*.png"   files, folders (one bundle), globs
+//   cat err.log | huddle add -              stdin (pbpaste | huddle add - too)
+//   huddle ctx [show <id>|rm <id>|note <id> <text>|clear]
+//
+// Same store, same commands as the `huddle` prompt (src/ui/paste.ts on
+// src/room/context.ts) — only the db differs: the live room's .huddle/live.db.
+// The room reads that db on every call, so writing it here is the same whether
+// the room is up or not; when it's up, each session hears about a new item (or
+// a pinned note) in notes_for_you on its next huddle_* call — the path
+// huddle_note takes (src/room/live.ts, inbox).
+import fs from "node:fs";
+import path from "node:path";
+import { getAdapter } from "../adapters/index.js";
+import { ContextStore, normalizePathToken } from "../room/context.js";
+import { RoomDB } from "../room/db.js";
+import { addPaths, addPiped, ctxCommand } from "../ui/paste.js";
+import { C } from "../ui/term.js";
+import { confirm } from "./connect.js";
+import { ensureHuddleDir, liveCall, liveFiles, mainRoot, pingLive, readLive } from "./live.js";
+/** The sessions in the live room right now (agent names), or null when it's down. */
+async function liveAgents(repo) {
+    const st = readLive(repo);
+    if (!st || !(await pingLive(st)))
+        return null;
+    try {
+        const r = await liveCall(st, "peers", {}, "", 2000);
+        return (r.body.sessions ?? []).map((s) => String(s.agent));
+    }
+    catch {
+        return null;
+    }
+}
+/** A ScreenUI on the live room's store. `interactive` = a person can answer the secrets question. */
+function screenUI(repo, agents, interactive) {
+    let db = null;
+    const ui = {
+        print: (l = "") => console.log(l),
+        yes: (q, def = true) => confirm(q, def),
+        db: async () => {
+            if (!db) {
+                ensureHuddleDir(repo); // .huddle/ with its own .gitignore
+                db = new RoomDB(liveFiles(repo).db);
+            }
+            return db;
+        },
+        audience: () => {
+            const list = [...new Set(agents ?? [])];
+            return { agents: list, companies: new Set(list.map((a) => getAdapter(a)?.vendor ?? a)).size };
+        },
+        root: () => repo,
+        interactive,
+        announce: false, // the live room delivers it with each session's notes
+    };
+    return { ui, close: () => db?.close() };
+}
+function needRepo() {
+    const repo = mainRoot();
+    if (!repo)
+        console.log(C.red("✗ Not a git repo.") + " The shared screen belongs to a repo — cd into the one your agents work in.");
+    return repo;
+}
+/**
+ * A path as typed: file:// URLs and ~ resolved (cmd.exe expands neither), and
+ * Windows separators read as "/" where "\" isn't one (logs\err.log on macOS).
+ */
+export function cliPath(arg, cwd = process.cwd()) {
+    const p = normalizePathToken(arg);
+    if (path.sep === "\\" || !p.includes("\\") || fs.existsSync(path.resolve(cwd, p)))
+        return p;
+    return p.replace(/\\/g, "/");
+}
+async function readAllStdin(stdin = process.stdin) {
+    let s = "";
+    for await (const c of stdin)
+        s += c.toString();
+    return s;
+}
+/** `huddle add <file|folder|glob|->…` — `--title <t>` names a stdin item. */
+export async function runAdd(args) {
+    const repo = needRepo();
+    if (!repo)
+        return void (process.exitCode = 1);
+    let title;
+    const paths = [];
+    let piped = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--title" && i + 1 < args.length)
+            title = args[++i];
+        else if (a.startsWith("--title="))
+            title = a.slice(8);
+        else if (a === "-")
+            piped = true;
+        else
+            paths.push(cliPath(a));
+    }
+    if (!paths.length && !piped) {
+        console.log(`usage: ${C.bold("huddle add <file|folder|glob>")} … ${C.faint("· or pipe it:")} ${C.bold("cat err.log | huddle add -")}`);
+        return void (process.exitCode = 1);
+    }
+    if (piped && process.stdin.isTTY) {
+        console.log(C.red("  ✗ nothing piped in") + C.faint(" — e.g. pbpaste | huddle add -   ·   cat err.log | huddle add -"));
+        return void (process.exitCode = 1);
+    }
+    const agents = await liveAgents(repo);
+    // Stdin is the pipe with `-`, so nobody can answer: secrets are redacted.
+    const { ui, close } = screenUI(repo, agents, !piped && !!process.stdin.isTTY && !!process.stdout.isTTY);
+    let failed = 0;
+    let before = 0;
+    try {
+        const store = ContextStore.open((await ui.db()));
+        before = store.list().length;
+        if (piped && !(await addPiped(store, await readAllStdin(), ui, { title })))
+            failed++;
+        if (paths.length)
+            failed += await addPaths(paths, ui);
+        const added = store.list().length - before;
+        if (added > 0)
+            console.log(C.faint(agents === null
+                ? "     no live room right now — sessions find it with huddle_context when they're up"
+                : agents.length
+                    ? `     ${[...new Set(agents)].join(", ")} see it on their next huddle_* call`
+                    : "     live room is up; sessions that join find it with huddle_context"));
+    }
+    finally {
+        close();
+    }
+    if (failed)
+        process.exitCode = 1;
+}
+/** `huddle ctx [list|show <id>|rm <id…>|note <id> <text>|clear|add <path…>]` */
+export async function runCtx(args) {
+    const repo = needRepo();
+    if (!repo)
+        return void (process.exitCode = 1);
+    const { ui, close } = screenUI(repo, await liveAgents(repo), !!process.stdin.isTTY && !!process.stdout.isTTY);
+    try {
+        if (args[0] === "add")
+            return void (await addPaths(args.slice(1).map((a) => cliPath(a)), ui));
+        await ctxCommand(args.join(" "), ui);
+    }
+    finally {
+        close();
+    }
+}
+//# sourceMappingURL=screen.js.map