huddle-cli 0.0.0-stage → 0.1.1

package/dist/attach/connect.js

@@ -0,0 +1,412 @@
+// Attach mode, the wiring: `huddle connect` puts the Plug into each installed
+// agent's PROJECT-scoped config for this repo, so the claude / codex / cursor
+// sessions you start yourself all join the same live room. Nothing global is
+// touched (~/.claude, ~/.codex, ~/.cursor stay as they are), every file is
+// shown before it's written, and every file goes into .git/info/exclude so it
+// is never committed. `huddle disconnect` takes out exactly what we put in.
+//
+//   claude       .mcp.json                     (Claude asks you to approve it once)
+//                .claude/settings.local.json   PreToolUse guard → `huddle guard`
+//   codex        .codex/config.toml            (Codex loads .codex/ only in trusted projects)
+//   cursor       .cursor/mcp.json + .cursor/rules/huddle.mdc
+//   gemini       .gemini/settings.json
+//   antigravity  .agents/mcp_config.json       (community-documented; unverified)
+//   any other adapter whose Plug wiring is a project file (adapter.plug.file.in = "worktree")
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { ADAPTERS } from "../adapters/index.js";
+import { C } from "../ui/term.js";
+import { CLI_PATH, ensureLive, liveFiles, mainRoot } from "./live.js";
+import { LIVE_INSTRUCTIONS } from "./plug.js";
+const TOML_START = "# >>> huddle connect (remove with `huddle disconnect`) >>>";
+const TOML_END = "# <<< huddle connect <<<";
+// Codex's top-level keys must come before any [table], so the instructions get
+// their own block at the top of the file.
+const TOML_TOP_START = "# >>> huddle connect: instructions (remove with `huddle disconnect`) >>>";
+const TOML_TOP_END = "# <<< huddle connect: instructions <<<";
+const EXCLUDE_START = "# >>> huddle connect >>>";
+const EXCLUDE_END = "# <<< huddle connect <<<";
+const HOOK_MATCHER = "Edit|Write|MultiEdit|NotebookEdit";
+/** Claude permission rule for every tool of the `huddle` MCP server. */
+const CLAUDE_ALLOW = "mcp__huddle";
+/** The Plug in live mode. `repo` = the main checkout (where the room lives). */
+export function livePlug(repo, agent) {
+    return { command: process.execPath, args: [CLI_PATH, "plug"], env: { HUDDLE_LIVE: "1", HUDDLE_AGENT_ID: agent, HUDDLE_REPO: repo } };
+}
+// Quoted (paths with spaces: C:\Users\Some Name\…) and with forward slashes on
+// Windows, which node accepts and which survive both bash and cmd/PowerShell.
+const hookPath = (p) => (process.platform === "win32" ? p.replace(/\\/g, "/") : p);
+export const guardCommand = () => `"${hookPath(process.execPath)}" "${hookPath(CLI_PATH)}" guard`;
+/** What `huddle connect` would write for one agent. */
+export function wiresFor(adapter, repo, opts = {}) {
+    const plug = livePlug(repo, adapter.id);
+    if (adapter.id === "claude")
+        return [
+            { agent: "claude", file: ".mcp.json", kind: "mcp-json", why: "the Plug (Claude asks you to approve it once)", entry: { mcpServers: { huddle: { type: "stdio", ...plug } } } },
+            {
+                agent: "claude",
+                file: ".claude/settings.local.json",
+                kind: "claude-hook",
+                guard: opts.guard !== false,
+                why: opts.guard === false
+                    ? "lets Claude use Huddle's tools without asking each time (they only talk to the local room)"
+                    : "lets Claude use Huddle's tools without asking each time + pre-edit guard: asks you before Claude edits a file another session holds",
+            },
+        ];
+    if (adapter.id === "codex")
+        return [{ agent: "codex", file: ".codex/config.toml", kind: "codex-toml", why: "the Plug (Codex reads .codex/ only in projects you trust)" }];
+    if (adapter.plug.file?.in === "worktree" && adapter.plug.entry) {
+        const out = [
+            {
+                agent: adapter.id,
+                file: adapter.plug.file.path,
+                kind: "mcp-json",
+                why: adapter.id === "antigravity" ? "the Plug (path from community docs — unverified)" : "the Plug",
+                entry: adapter.plug.entry(plug),
+            },
+        ];
+        if (adapter.id === "cursor")
+            out.push({
+                agent: "cursor",
+                file: ".cursor/rules/huddle.mdc",
+                kind: "rule",
+                why: "tells Cursor to check in with Huddle before editing",
+                content: `---\ndescription: Coordinate with the other AI sessions in this repo through Huddle\nalwaysApply: true\n---\n\n${LIVE_INSTRUCTIONS}\n`,
+            });
+        return out;
+    }
+    return [];
+}
+function git(cwd, args) {
+    try {
+        return { ok: true, out: execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() };
+    }
+    catch {
+        return { ok: false, out: "" };
+    }
+}
+const tracked = (root, file) => git(root, ["ls-files", "--error-unmatch", "--", file]).ok;
+function onPath(bin) {
+    if (path.isAbsolute(bin))
+        return fs.existsSync(bin);
+    try {
+        execFileSync(process.platform === "win32" ? "where" : "which", [bin], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---- pure edits (string in → string out), so tests can check them directly --
+function readJson(text) {
+    if (!text?.trim())
+        return {};
+    return JSON.parse(text);
+}
+function deepMerge(a, b) {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b))
+        out[k] = v && typeof v === "object" && !Array.isArray(v) ? deepMerge(a[k] ?? {}, v) : v;
+    return out;
+}
+const tomlStr = (v) => JSON.stringify(v); // JSON strings/arrays are valid TOML
+export function codexBlock(plug) {
+    return [
+        TOML_START,
+        "[mcp_servers.huddle]",
+        `command = ${tomlStr(plug.command)}`,
+        `args = ${tomlStr(plug.args)}`,
+        // Huddle's tools only talk to the local room — no files, no shell.
+        `default_tools_approval_mode = "approve"`,
+        "",
+        "[mcp_servers.huddle.env]",
+        ...Object.entries(plug.env).map(([k, v]) => `${k} = ${tomlStr(v)}`),
+        TOML_END,
+    ].join("\n");
+}
+const stripBlock = (text, start, end) => {
+    const i = text.indexOf(start);
+    const j = text.indexOf(end);
+    if (i < 0 || j < i)
+        return text;
+    return (text.slice(0, i).replace(/\n+$/, "") + "\n" + text.slice(j + end.length).replace(/^\n+/, "")).replace(/^\n+/, "");
+};
+/** The new content of `w`'s file, or null if it must be skipped (with why). */
+export function applyWire(w, current, repo) {
+    switch (w.kind) {
+        case "mcp-json":
+            return { text: JSON.stringify(deepMerge(readJson(current), w.entry ?? {}), null, 2) + "\n" };
+        case "rule":
+            return { text: w.content ?? "" };
+        case "codex-toml": {
+            const base = stripBlock(stripBlock(current ?? "", TOML_TOP_START, TOML_TOP_END), TOML_START, TOML_END);
+            if (/^\s*\[mcp_servers\.huddle(\.|\])/m.test(base))
+                return { skip: "already has its own [mcp_servers.huddle]" };
+            // Found live (live-2): with only the Plug, a plain `codex exec` in a repo
+            // where claude and cursor were working never called a huddle_* tool —
+            // Codex doesn't surface an MCP server's `instructions`, which is how
+            // Claude and Cursor learn to check in. `developer_instructions` is
+            // documented in Codex's config reference (learn.chatgpt.com/docs/config-file/
+            // config-reference). A user's own top-level value wins (TOML forbids two).
+            const top = base.split(/^\s*\[/m)[0];
+            const own = /^\s*developer_instructions\s*=/m.test(top);
+            const head = own ? "" : `${TOML_TOP_START}\ndeveloper_instructions = ${tomlStr(LIVE_INSTRUCTIONS)}\n${TOML_TOP_END}\n\n`;
+            return { text: head + (base.trim() ? base.replace(/\n*$/, "\n\n") : "") + codexBlock(livePlug(repo, w.agent)) + "\n" };
+        }
+        case "claude-hook": {
+            const cfg = readJson(current);
+            // Found live: without an allow rule every huddle_* call is a permission
+            // prompt (and in `claude -p` a flat denial — the session then refuses to
+            // edit, as the instructions say). `mcp__huddle` = every tool of the
+            // `huddle` server (code.claude.com/docs/en/permissions). The tools only
+            // reach the local room: no files, no shell.
+            // `enabledMcpjsonServers` approves the project .mcp.json server the user
+            // just agreed to in `huddle connect` (code.claude.com/docs/en/mcp).
+            const allow = [...new Set([...(cfg.permissions?.allow ?? []), CLAUDE_ALLOW])];
+            const enabled = [...new Set([...(cfg.enabledMcpjsonServers ?? []), "huddle"])];
+            const out = { ...cfg, permissions: { ...(cfg.permissions ?? {}), allow }, enabledMcpjsonServers: enabled };
+            if (w.guard !== false) {
+                const pre = (cfg.hooks?.PreToolUse ?? []).filter((m) => !isOurHook(m));
+                pre.push({ matcher: HOOK_MATCHER, hooks: [{ type: "command", command: guardCommand(), timeout: 5 }] });
+                out.hooks = { ...(cfg.hooks ?? {}), PreToolUse: pre };
+            }
+            return { text: JSON.stringify(out, null, 2) + "\n" };
+        }
+    }
+}
+const isOurHook = (m) => (m?.hooks ?? []).some((h) => typeof h?.command === "string" && /cli\.js"? guard$/.test(h.command));
+/** `text` with our part taken out. "" = nothing of the user's is left. */
+export function unapplyWire(kind, current) {
+    switch (kind) {
+        case "mcp-json": {
+            const cfg = readJson(current);
+            if (cfg.mcpServers) {
+                delete cfg.mcpServers.huddle;
+                if (!Object.keys(cfg.mcpServers).length)
+                    delete cfg.mcpServers;
+            }
+            return Object.keys(cfg).length ? JSON.stringify(cfg, null, 2) + "\n" : "";
+        }
+        case "rule":
+            return "";
+        case "codex-toml": {
+            const t = stripBlock(stripBlock(current, TOML_TOP_START, TOML_TOP_END), TOML_START, TOML_END);
+            return t.trim() ? t : "";
+        }
+        case "claude-hook": {
+            const cfg = readJson(current);
+            if (cfg.hooks?.PreToolUse) {
+                cfg.hooks.PreToolUse = cfg.hooks.PreToolUse.filter((m) => !isOurHook(m));
+                if (!cfg.hooks.PreToolUse.length)
+                    delete cfg.hooks.PreToolUse;
+                if (!Object.keys(cfg.hooks).length)
+                    delete cfg.hooks;
+            }
+            // Both entries only name Huddle's server, so they go with it.
+            if (Array.isArray(cfg.permissions?.allow)) {
+                cfg.permissions.allow = cfg.permissions.allow.filter((r) => r !== CLAUDE_ALLOW);
+                if (!cfg.permissions.allow.length)
+                    delete cfg.permissions.allow;
+                if (!Object.keys(cfg.permissions).length)
+                    delete cfg.permissions;
+            }
+            if (Array.isArray(cfg.enabledMcpjsonServers)) {
+                cfg.enabledMcpjsonServers = cfg.enabledMcpjsonServers.filter((n) => n !== "huddle");
+                if (!cfg.enabledMcpjsonServers.length)
+                    delete cfg.enabledMcpjsonServers;
+            }
+            return Object.keys(cfg).length ? JSON.stringify(cfg, null, 2) + "\n" : "";
+        }
+    }
+}
+// ---- plan / apply / undo -------------------------------------------------------
+export function planConnect(root, opts = {}) {
+    const repo = opts.repo ?? root;
+    const adapters = (opts.adapters ?? ADAPTERS).filter((a) => (opts.agents?.length ? opts.agents.includes(a.id) : onPath(a.bin)));
+    const out = [];
+    for (const a of adapters)
+        for (const w of wiresFor(a, repo, opts)) {
+            const abs = path.join(root, w.file);
+            if (tracked(root, w.file)) {
+                out.push({ ...w, action: "skip", reason: "tracked in git — Huddle won't edit a committed file" });
+                continue;
+            }
+            let current = null;
+            try {
+                current = fs.readFileSync(abs, "utf8");
+            }
+            catch {
+                /* new file */
+            }
+            let r;
+            try {
+                r = applyWire(w, current, repo);
+            }
+            catch (e) {
+                out.push({ ...w, action: "skip", reason: `can't parse it (${String(e?.message ?? e).slice(0, 60)})` });
+                continue;
+            }
+            if ("skip" in r)
+                out.push({ ...w, action: "skip", reason: r.skip });
+            else
+                out.push({ ...w, action: current === null ? "create" : "update" });
+        }
+    return out;
+}
+function excludeFile(root) {
+    const p = git(root, ["rev-parse", "--git-path", "info/exclude"]).out || ".git/info/exclude";
+    return path.isAbsolute(p) ? p : path.join(root, p);
+}
+/** Make the marked block in .git/info/exclude list exactly `files` (shared by every worktree). */
+export function setExcludes(root, files) {
+    const ex = excludeFile(root);
+    const cur = fs.existsSync(ex) ? fs.readFileSync(ex, "utf8") : "";
+    const keep = [...new Set(files.map((f) => "/" + f.replace(/^\/+/, "")))].sort();
+    const base = stripBlock(cur, EXCLUDE_START, EXCLUDE_END).replace(/\n*$/, "\n");
+    const head = base.trim() ? base : "";
+    fs.mkdirSync(path.dirname(ex), { recursive: true });
+    fs.writeFileSync(ex, keep.length ? `${head}${EXCLUDE_START}\n${keep.join("\n")}\n${EXCLUDE_END}\n` : head);
+}
+const allFiles = (r) => Object.values(r).flat().map((m) => m.file);
+const recordsPath = (repo) => path.join(liveFiles(repo).dir, "connect.json");
+function readRecords(repo) {
+    try {
+        return JSON.parse(fs.readFileSync(recordsPath(repo), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeRecords(repo, r) {
+    fs.mkdirSync(path.dirname(recordsPath(repo)), { recursive: true });
+    fs.writeFileSync(recordsPath(repo), JSON.stringify(r, null, 2));
+}
+/** Write the planned files. `root` = the checkout; records live in the main repo. */
+export function applyConnect(root, plan, repo = root) {
+    const records = readRecords(repo);
+    const mine = records[root] ?? [];
+    const written = [];
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    for (const w of plan) {
+        if (w.action === "skip")
+            continue;
+        const abs = path.join(root, w.file);
+        const current = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : null;
+        const r = applyWire(w, current, repo);
+        if ("skip" in r)
+            continue;
+        let backup;
+        const known = mine.find((m) => m.file === w.file && m.kind === w.kind);
+        if (current !== null && !known) {
+            backup = path.join(liveFiles(repo).dir, "backup", stamp, w.file);
+            fs.mkdirSync(path.dirname(backup), { recursive: true });
+            fs.writeFileSync(backup, current);
+        }
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, r.text);
+        if (!known)
+            mine.push({ file: w.file, kind: w.kind, agent: w.agent, created: current === null, backup });
+        written.push(w.file);
+    }
+    records[root] = mine;
+    writeRecords(repo, records);
+    setExcludes(root, allFiles(records));
+    return written;
+}
+/** Take out what applyConnect put in. Returns the files touched. */
+export function disconnect(root, repo = root) {
+    const records = readRecords(repo);
+    const mine = records[root] ?? [];
+    const touched = [];
+    for (const m of mine) {
+        const abs = path.join(root, m.file);
+        if (!fs.existsSync(abs))
+            continue;
+        let left;
+        try {
+            left = unapplyWire(m.kind, fs.readFileSync(abs, "utf8"));
+        }
+        catch {
+            continue; // the user rewrote it into something we can't parse — leave it
+        }
+        if (!left && m.created) {
+            fs.rmSync(abs);
+            // Tidy dirs we may have created (.cursor/rules, .codex …) if now empty.
+            for (let d = path.dirname(abs); d !== root && d.startsWith(root); d = path.dirname(d)) {
+                try {
+                    fs.rmdirSync(d);
+                }
+                catch {
+                    break;
+                }
+            }
+        }
+        else
+            fs.writeFileSync(abs, left);
+        touched.push(m.file);
+    }
+    delete records[root];
+    writeRecords(repo, records);
+    // Other checkouts (attach worktrees) that are still connected keep theirs.
+    setExcludes(root, allFiles(records));
+    return touched;
+}
+// ---- CLI -------------------------------------------------------------------
+export async function confirm(q, def = false) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const a = await new Promise((r) => rl.question(`${q} ${def ? "[Y/n]" : "[y/N]"} `, r));
+    rl.close();
+    return a.trim() ? /^y/i.test(a.trim()) : def;
+}
+const flagList = (args, name) => args.find((a) => a.startsWith(`--${name}=`))?.split("=")[1]?.split(",").map((s) => s.trim()).filter(Boolean);
+export async function runConnect(args) {
+    const root = mainRoot();
+    if (!root) {
+        console.log(C.red("✗ Not a git repo.") + " Run this inside the repo your agents work in.");
+        process.exit(1);
+    }
+    const plan = planConnect(root, { agents: flagList(args, "agents"), guard: !args.includes("--no-guard") });
+    console.log(`${C.violet("huddle connect")} — your own claude / codex / cursor sessions in ${C.bold(path.basename(root))} will see each other\n`);
+    if (!plan.length) {
+        console.log(C.yellow("No supported agent CLI found on PATH.") + " Install claude, codex or cursor-agent first.");
+        return;
+    }
+    for (const w of plan) {
+        const act = w.action === "skip" ? C.yellow("skip  ") : w.action === "create" ? C.green("create") : C.green("update");
+        console.log(`  ${w.agent.padEnd(12)} ${act}  ${w.file.padEnd(30)} ${C.faint(w.action === "skip" ? w.reason : w.why)}`);
+    }
+    const todo = plan.filter((w) => w.action !== "skip");
+    console.log(`\n  ${C.faint("Project files only — your global agent configs aren't touched. All go in .git/info/exclude, so")}`);
+    console.log(`  ${C.faint("they're never committed; existing files are backed up to .huddle/backup/. Undo: huddle disconnect")}\n`);
+    if (!todo.length)
+        return;
+    if (args.includes("--dry-run"))
+        return;
+    const ok = args.includes("--yes") || args.includes("-y") || (await confirm(`Write ${todo.length === 1 ? "this file" : `these ${todo.length} files`}?`));
+    if (!ok) {
+        console.log(process.stdin.isTTY ? "Nothing written." : "Nothing written — not a terminal, so run again with --yes to confirm.");
+        return;
+    }
+    const written = applyConnect(root, plan);
+    console.log(`${C.green("✓")} wrote ${written.join(", ")}`);
+    try {
+        const { state, started } = await ensureLive(root);
+        console.log(`${C.green("✓")} live room ${started ? "started" : "running"} ${C.faint(`(${state.url}, pid ${state.pid}) · stop it with huddle down`)}`);
+    }
+    catch (e) {
+        console.log(C.yellow(`! couldn't start the live room: ${e?.message ?? e}`) + " — agents start it themselves when they connect.");
+    }
+    console.log(`\nNow open your agents in this repo as usual. ${C.bold("huddle peers")} shows who's in and what they hold.`);
+}
+export async function runDisconnect() {
+    const root = mainRoot();
+    if (!root)
+        return void console.log(C.red("✗ Not a git repo."));
+    const touched = disconnect(root);
+    console.log(touched.length ? `${C.green("✓")} removed Huddle from ${touched.join(", ")}` : "Nothing to undo — this repo wasn't connected.");
+}
+//# sourceMappingURL=connect.js.map

package/dist/attach/guard.js

@@ -0,0 +1,83 @@
+// Attach mode, the pre-edit guard: `huddle guard` is a Claude Code PreToolUse
+// hook on Edit/Write/MultiEdit/NotebookEdit (wired by `huddle connect`). It
+// doesn't rely on the model remembering to check in:
+//
+//   another live session holds the file  → "ask": Claude's own permission
+//                                          prompt shows who holds it and why
+//   nobody does                          → lease it to this session, silently
+//   no live room / anything goes wrong   → allow; Huddle never blocks your agent
+//
+// Hook I/O per https://code.claude.com/docs/en/hooks: JSON on stdin
+// (tool_name, tool_input, cwd, session_id); on stdout
+// {hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision,permissionDecisionReason}}.
+// tool_input.file_path / notebook_path are the Edit/Write/NotebookEdit fields.
+import { execFileSync } from "node:child_process";
+import { liveCall, mainRoot, readLive } from "./live.js";
+/** This process's ancestors (the hook's shell, then Claude itself, …). */
+export function ancestors(max = 8, platform = process.platform) {
+    const out = [];
+    // Windows has no `ps`: one PowerShell call lists every process's parent.
+    const parents = platform === "win32" ? windowsParents() : null;
+    let pid = process.ppid;
+    for (let i = 0; i < max && pid > 1; i++) {
+        out.push(pid);
+        try {
+            pid = parents
+                ? (parents.get(pid) ?? 0)
+                : Number(execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim());
+        }
+        catch {
+            break;
+        }
+    }
+    return out;
+}
+/** pid → parent pid, from `Get-CimInstance Win32_Process`. Empty if that fails. */
+export function windowsParents(run = () => execFileSync("powershell.exe", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId) $($_.ParentProcessId)\" }"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 4000, windowsHide: true })) {
+    const m = new Map();
+    try {
+        for (const l of run().split(/\r?\n/)) {
+            const [a, b] = l.trim().split(/\s+/).map(Number);
+            if (a > 0 && b >= 0)
+                m.set(a, b);
+        }
+    }
+    catch {
+        /* no PowerShell: the guard still works, just without pid matching */
+    }
+    return m;
+}
+async function readStdin() {
+    let s = "";
+    for await (const c of process.stdin)
+        s += c;
+    return s;
+}
+/** Decide for one hook payload. Exported for tests. */
+export async function guardDecision(input, pids) {
+    const ti = input?.tool_input ?? {};
+    const file = ti.file_path ?? ti.notebook_path ?? ti.path;
+    if (!file)
+        return { decision: "allow" };
+    const root = process.env.HUDDLE_REPO || mainRoot(process.env.CLAUDE_PROJECT_DIR || input?.cwd || process.cwd());
+    if (!root)
+        return { decision: "allow" };
+    const st = readLive(root);
+    if (!st)
+        return { decision: "allow" };
+    const r = await liveCall(st, "guard", { path: String(file), pids }, "", 2500);
+    return r.body?.decision === "ask" ? { decision: "ask", reason: String(r.body.reason) } : { decision: "allow" };
+}
+export async function runGuard() {
+    try {
+        const input = JSON.parse((await readStdin()) || "{}");
+        const d = await guardDecision(input, ancestors());
+        if (d.decision === "ask")
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "ask", permissionDecisionReason: d.reason } }) + "\n");
+    }
+    catch {
+        /* allow */
+    }
+    process.exit(0);
+}
+//# sourceMappingURL=guard.js.map