huddle-cli 0.1.3 → 0.1.5

package/dist/app/server.js

@@ -8,10 +8,16 @@
 // Local only: it listens on 127.0.0.1, every API call needs the token from
 // the URL it prints, and a Host other than localhost is refused (so a web
 // page you visit can't reach it through DNS rebinding).
+//
+// `--phone` opens it to your Wi-Fi too, to run things from your phone: it
+// also listens on this machine's network addresses, and accepts those as the
+// Host (plus the tunnel's name with `--anywhere`). The token is still needed
+// for everything, and it's longer then, since the network can see the door.
 import { spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import http from "node:http";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { ADAPTERS, LEGACY, applySkips, probeAsync } from "../adapters/index.js";
@@ -19,9 +25,32 @@ import { RoomDB } from "../room/db.js";
 import { splitRuns } from "../ui/story.js";
 import { buildExport, findRun, renderExport, runRows, EXPORT_FORMATS, EXPORT_LEVELS } from "../ui/export.js";
 import { packageInfo } from "../preflight.js";
+import { readConfig, githubReady } from "../connectors/hub.js";
+import { runAsync } from "../connectors/github.js";
+import { undoPlan, undoRun } from "../ui/undo.js";
 import { clearAppInfo, postCommand, readLive, readReport, writeAppInfo } from "./live.js";
 import { appPage } from "./page.js";
+import { qrLines } from "./qr.js";
+import { C } from "../ui/term.js";
 const CLI = fileURLToPath(new URL("../cli.js", import.meta.url));
+/**
+ * This machine's IPv4 addresses on its networks, the likeliest one for a
+ * phone first: Wi-Fi and Ethernet before VPNs and virtual machines' bridges
+ * (a Mac running a VM has a 192.168.x bridge no phone can reach).
+ */
+export function lanAddresses() {
+    const out = [];
+    for (const [name, list] of Object.entries(os.networkInterfaces())) {
+        const rank = /^(en|eth|wl|wlan|wi-?fi|ethernet)/i.test(name) ? 0 : /^(bridge|vmnet|vboxnet|virbr|docker|br-|veth|utun|tun|tap|tailscale|zt|ham|vethernet)/i.test(name) ? 2 : 1;
+        for (const a of list ?? []) {
+            if ((a.family === "IPv4" || a.family === 4) && !a.internal && !a.address.startsWith("169.254."))
+                out.push({ ip: a.address, rank });
+        }
+    }
+    const home = (ip) => /^(192\.168\.|10\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip);
+    out.sort((a, b) => a.rank - b.rank || Number(home(b.ip)) - Number(home(a.ip)));
+    return [...new Set(out.map((a) => a.ip))];
+}
 const json = (res, status, body) => {
     res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" });
     res.end(JSON.stringify(body));
@@ -71,7 +100,12 @@ export async function startApp(opts) {
     const dbFile = path.join(root, ".huddle", "huddle.db");
     fs.mkdirSync(path.dirname(dbFile), { recursive: true });
     const db = new RoomDB(dbFile);
-    const token = crypto.randomBytes(18).toString("base64url");
+    // On the network, a longer key: 192 bits, still short enough for a small QR code.
+    const token = crypto.randomBytes(opts.phone ? 24 : 18).toString("base64url");
+    const tokenBuf = Buffer.from(token);
+    const keyOk = (given) => typeof given === "string" && given.length === token.length && crypto.timingSafeEqual(Buffer.from(given), tokenBuf);
+    const addresses = opts.addresses ?? lanAddresses;
+    const extraHosts = new Set();
     const startRun = opts.startRun ?? ((goal) => spawnRun(root, goal));
     let agents = opts.agents ?? null;
     let probing = null;
@@ -107,8 +141,51 @@ export async function startApp(opts) {
             probing: !agents,
             live,
             runs: runRows(runs).reverse(),
+            // Changes when a run is undone (from here or `huddle undo`), so its view refetches.
+            undone: runs.reduce((n, r) => n + r.events.filter((e) => e.type === "git.undone").length, 0),
+            connectors: connectorsNow(),
+        };
+    };
+    /** What's configured, from ~/.huddle/connectors.json: shown, not started. */
+    const connectorsNow = () => {
+        const cfg = readConfig();
+        return {
+            github: cfg.github?.off ? "off" : cfg.github?.write ? "write" : "read",
+            others: Object.entries(cfg.connectors ?? {})
+                .filter(([, c]) => !c?.off)
+                .map(([name, c]) => ({ name, write: !!c?.write })),
         };
     };
+    // Open issues for the start screen. gh is slow (a network call), so the
+    // answer is kept a minute, and every page asking at once shares one call.
+    let github = null;
+    const githubView = () => {
+        if (github && Date.now() - github.at < 60_000)
+            return github.view;
+        const view = (async () => {
+            if (readConfig().github?.off)
+                return { ready: false, note: "GitHub is off (huddle connectors github on)", issues: [] };
+            const g = await githubReady(root);
+            if (!g.ok)
+                return { ready: false, note: g.note, issues: [] };
+            const r = await runAsync(["gh", "issue", "list", "--state", "open", "--limit", "20", "--json", "number,title"], { cwd: root, timeoutMs: 20_000 });
+            if (r.code !== 0)
+                return { ready: false, note: (r.stderr || r.stdout).trim().split("\n")[0].slice(0, 160) || "gh failed", issues: [] };
+            try {
+                const list = JSON.parse(r.stdout);
+                const issues = list
+                    .map((i) => ({ number: Number(i.number), title: String(i.title ?? "").slice(0, 200) }))
+                    .filter((i) => Number.isInteger(i.number) && i.number > 0)
+                    .slice(0, 20);
+                return { ready: true, note: g.note, issues };
+            }
+            catch {
+                return { ready: false, note: "couldn't read gh's answer", issues: [] };
+            }
+        })();
+        github = { at: Date.now(), view };
+        return view;
+    };
     const runDoc = (which) => {
         const runs = runsNow();
         const run = findRun(runs, which ?? undefined);
@@ -117,9 +194,18 @@ export async function startApp(opts) {
         const doc = buildExport(run, runs.length, { level: "chat", logsDir: path.join(root, ".huddle", "logs"), repoRoot: root });
         const made = run.events.find((e) => e.type === "plan.made");
         const plain = made?.p?.plain && typeof made.p.plain === "object" ? made.p.plain : null;
-        return { ...doc, plain, report: readReport(root, run.id) };
+        // Whether this run can be taken back, and what that would revert (ui/undo.ts).
+        const undo = undoPlan(root, db.allEvents(), String(run.index));
+        return { ...doc, plain, report: readReport(root, run.id), undo: { ok: undo.ok, why: undo.why ?? "", commits: undo.commits ?? [], end: undo.end ?? "" } };
+    };
+    const allowedHost = (h, port) => {
+        if (h === `127.0.0.1:${port}` || h === `localhost:${port}`)
+            return true;
+        if (!opts.phone || !h)
+            return false;
+        // Checked on every request: the Wi-Fi can change while the dashboard is open.
+        return extraHosts.has(h.toLowerCase()) || addresses().some((ip) => h === `${ip}:${port}`);
     };
-    const allowedHost = (h, port) => h === `127.0.0.1:${port}` || h === `localhost:${port}`;
     const server = http.createServer(async (req, res) => {
         const url = new URL(req.url ?? "/", "http://local");
         const port = server.address().port;
@@ -127,7 +213,7 @@ export async function startApp(opts) {
             return json(res, 403, { error: "local only" });
         try {
             if (req.method === "GET" && url.pathname === "/") {
-                if (url.searchParams.get("t") !== token) {
+                if (!keyOk(url.searchParams.get("t"))) {
                     res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
                     return res.end("Open the link `huddle app` printed (it carries a key for this session).");
                 }
@@ -138,7 +224,7 @@ export async function startApp(opts) {
                 return json(res, 404, { error: "not found" });
             // The token: a header for fetches, ?t= for the event stream and downloads.
             const given = req.headers["x-huddle-token"] ?? url.searchParams.get("t");
-            if (given !== token)
+            if (!keyOk(given))
                 return json(res, 401, { error: "no key" });
             const route = `${req.method} ${url.pathname}`;
             if (route === "GET /api/state")
@@ -177,6 +263,22 @@ export async function startApp(opts) {
                 req.on("close", () => clearInterval(t));
                 return;
             }
+            if (route === "GET /api/github")
+                return json(res, 200, await githubView());
+            if (route === "POST /api/undo") {
+                const body = await readBody(req);
+                // Never while a run is going: it's merging onto the branch this would revert on.
+                if (readLive(root))
+                    return json(res, 409, { error: "a run is going — undo once it's finished" });
+                const plan = undoPlan(root, db.allEvents(), String(body.n ?? ""));
+                if (!plan.ok)
+                    return json(res, 409, { error: plan.why });
+                // The commits you were shown are the ones reverted, or nothing is.
+                if (body.end && body.end !== plan.end)
+                    return json(res, 409, { error: "this run changed since you looked — look again" });
+                const done = undoRun(root, db, plan);
+                return done.ok ? json(res, 200, done) : json(res, 409, { error: done.why });
+            }
             if (route === "POST /api/agents") {
                 agents = null;
                 await probe();
@@ -214,7 +316,7 @@ export async function startApp(opts) {
     });
     const port = await new Promise((resolve, reject) => {
         server.once("error", reject);
-        server.listen(opts.port ?? 0, "127.0.0.1", () => resolve(server.address().port));
+        server.listen(opts.port ?? 0, opts.phone ? "0.0.0.0" : "127.0.0.1", () => resolve(server.address().port));
     });
     const url = `http://127.0.0.1:${port}/?t=${token}`;
     writeAppInfo(root, { pid: process.pid, url });
@@ -224,11 +326,26 @@ export async function startApp(opts) {
         clearAppInfo(root);
         db.close();
     };
-    return { url, port, token, close };
+    const lanUrls = () => (opts.phone ? addresses().map((ip) => `http://${ip}:${port}/?t=${token}`) : []);
+    const allowHost = (h) => void extraHosts.add(h.toLowerCase());
+    return { url, port, token, lanUrls, allowHost, close };
 }
 /** `huddle app [--port n] [--no-open]` */
 export async function runApp(args) {
-    const { C } = await import("../ui/term.js");
+    // Found live (0.1.5): `huddle app --help` opened a dashboard. A flag it doesn't know prints this instead.
+    const known = new Set(["--port", "--no-open", "--phone", "--anywhere"]);
+    const odd = args.find((a, k) => a.startsWith("-") && !known.has(a) && args[k - 1] !== "--port");
+    if (odd) {
+        console.log(`${C.bold("huddle app")}              the dashboard in your browser, for the repo you're in
+  --phone               open it on your phone too (same Wi-Fi): scan the QR code
+  --anywhere            on your phone from any network (needs cloudflared)
+  --no-open             don't open the browser   --port <n>  pick the port`);
+        if (odd !== "--help" && odd !== "-h") {
+            console.log(C.red(`✗ unknown: ${odd}`));
+            process.exitCode = 1;
+        }
+        return;
+    }
     const { isGitRepo } = await import("../sandbox/worktree.js");
     const { ensureInit, repoRoot } = await import("../ui/app.js");
     if (!isGitRepo(process.cwd()) || !ensureInit()) {
@@ -238,18 +355,72 @@ export async function runApp(args) {
     }
     const i = args.indexOf("--port");
     const port = i >= 0 ? Number(args[i + 1]) : undefined;
-    const app = await startApp({ root: repoRoot(), port });
+    const anywhere = args.includes("--anywhere");
+    const phone = anywhere || args.includes("--phone");
+    const app = await startApp({ root: repoRoot(), port, phone });
     console.log(`${C.green("✓")} Huddle is open at ${C.bold(app.url)}`);
     console.log(C.faint("  runs keep going if you close the page · ctrl-c closes the dashboard"));
+    let tunnel = null;
+    if (phone) {
+        let link = app.lanUrls()[0] ?? null;
+        let how = "on the same Wi-Fi as this computer";
+        if (anywhere) {
+            const { hasCloudflared, openTunnel } = await import("../room/tunnel.js");
+            if (!hasCloudflared()) {
+                console.log(`  ${C.yellow("!")} --anywhere needs cloudflared (free, no account): ${cloudflaredHint()}`);
+                console.log(C.faint("    using your Wi-Fi for now"));
+            }
+            else {
+                const t = await openTunnel(app.port, (l) => console.log(C.faint(l)));
+                if (t) {
+                    tunnel = t;
+                    app.allowHost(new URL(t.url).host);
+                    link = `${t.url}/?t=${app.token}`;
+                    how = "from anywhere";
+                }
+            }
+        }
+        console.log("");
+        const also = link === app.lanUrls()[0] ? app.lanUrls().slice(1).map((u) => new URL(u).hostname) : [];
+        for (const l of phoneLines(link, how, process.stdout.isTTY === true && !process.env.NO_COLOR, also))
+            console.log(l);
+    }
     if (!args.includes("--no-open"))
         openBrowser(app.url);
     const bye = () => {
+        tunnel?.close();
         app.close();
         process.exit(0);
     };
     process.on("SIGINT", bye);
     process.on("SIGTERM", bye);
 }
+/**
+ * What `huddle app --phone` prints: the code to scan, the link under it, and
+ * what sharing it means. `link` is null when this machine has no network.
+ */
+export function phoneLines(link, how, color, also = []) {
+    if (!link)
+        return [`  ${C.yellow("!")} This computer is on no network, so a phone can't reach it. Join Wi-Fi, try again.`];
+    return [
+        `  ${C.bold("On your phone")} ${C.faint(`(${how})`)}: point the camera at this code`,
+        "",
+        ...qrLines(link, { color }).map((l) => "  " + l),
+        "",
+        `  or open ${C.bold(link)}`,
+        ...(also.length ? [C.faint(`    not working? try the same link with ${also.slice(0, 3).join(" or ")} in it`)] : []),
+        `  ${C.yellow("!")} Anyone with this link can control this run. Ctrl-C stops sharing.`,
+        ...(link.startsWith("http:") ? [C.faint("    Plain http on your Wi-Fi: fine on a network you trust. --anywhere is https.")] : []),
+    ];
+}
+/** How to get cloudflared here, in one line. */
+function cloudflaredHint() {
+    if (process.platform === "darwin")
+        return "brew install cloudflared";
+    if (process.platform === "win32")
+        return "winget install --id Cloudflare.cloudflared";
+    return "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/";
+}
 function openBrowser(url) {
     const [cmd, ...a] = process.platform === "darwin" ? ["open", url] : process.platform === "win32" ? ["cmd", "/c", "start", "", url] : ["xdg-open", url];
     try {

package/dist/args.js

@@ -1,5 +1,5 @@
 // What `huddle <words>` means.
-const COMMANDS = new Set("app dashboard plug init setup agents doctor join board view watch story brief runs export lessons up down peers add ctx context attach land connect disconnect guard mail relay version help".split(" "));
+const COMMANDS = new Set("app dashboard plug init setup agents doctor join board view watch story brief runs export lessons up down peers add ctx context attach land connect disconnect guard mail relay version update upgrade connectors connector undo help".split(" "));
 /**
  * `huddle build a temperature converter` / `huddle "fix the login bug"`: a goal
  * in plain words, without `join` or quotes. Found live (0.1.2 test): "as a
@@ -11,7 +11,7 @@ export function asGoal(args) {
     if (!cmd || cmd.startsWith("-") || COMMANDS.has(cmd))
         return null;
     const words = [cmd, ...rest.filter((a) => !a.startsWith("--"))].join(" ").trim().split(/\s+/);
-    if (cmd === "build" || cmd === "make" || words.length >= 3 || /\s/.test(cmd))
+    if (cmd === "build" || cmd === "make" || (cmd === "fix" && rest.length > 0) || words.length >= 3 || /\s/.test(cmd))
         return ["join", ...(cmd === "build" ? rest : args)];
     return null;
 }

package/dist/cli.js

@@ -15,7 +15,8 @@
 //   huddle agents               your agents: ready / not signed in / not installed, used or skipped
 //   huddle agents use|skip <ids>  choose who works with you (remembered)
 //   huddle --version            print the version
-//   huddle agents --all         every connector (built in + agents.json) and how to get it
+//   huddle update               install the newest huddle-cli from npm (--update too)
+//   huddle agents --all         every agent (built in + agents.json) and how to get it
 //   huddle agents install <id>  install one connector's CLI, after asking
 //   huddle board                print the board + shared memory
 //   huddle view [repo]          the live view (ctrl-t) from another terminal, read-only
@@ -57,7 +58,10 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
     ${B("--budget=5M")}                tokens it may use ${F("(stops new work at 90%)")}
     ${B("--with <file>")}              put a file, folder or glob on the shared screen
                                ${F("(repeatable; or pipe: cat log | huddle join …)")}
+  ${B("huddle fix issue 12")}          GitHub issue 12 is the goal ${F("(also: fix #12)")}
   ${B("huddle app")}                   the dashboard: live run, history, talk to agents
+    ${B("--phone")}                    on your phone too: scan the QR code it prints
+                               ${F("(--anywhere: off your Wi-Fi, needs cloudflared)")}
   ${B("huddle join <address> <CODE>")} join someone's room from an invite
 
   ${F("watch and replay")}
@@ -70,6 +74,7 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
   ${B("huddle export")} ${F("[run]")}         a run as a chat you can read or share
                                ${F("(--level summary|chat|full, --out <path>,")}
                                ${F(" --format md|html|json, --no-redact)")}
+  ${B("huddle undo")} ${F("[--run n]")}        take back what a run merged ${F("(one revert commit)")}
   ${B("huddle board")}                 print the board
   ${B("huddle lessons")} ${F("[--forget id]")} what earlier runs taught your agents ${F("(--clear)")}
 
@@ -78,10 +83,12 @@ const USAGE = `${C.violet("huddle")} — your agents, in the same room
   ${B("huddle doctor")}                check this machine: node, git, your agents
   ${B("huddle agents")}                your agents: ready or not, used or skipped
   ${B("huddle agents use|skip <ids>")} choose who works with you ${F("(e.g. skip cursor)")}
-  ${B("huddle agents --all")}          every connector Huddle knows, installed or not
+  ${B("huddle agents --all")}          every agent Huddle knows, installed or not
   ${B("huddle agents install <id>")}   install one ${F("(asks first)")}
+  ${B("huddle connectors")}            GitHub, Jira, Linear… for every agent
   ${B("huddle relay")} ${F("[--port 8080]")}   run a relay so rooms work across networks
   ${B("huddle --version")}             print the version
+  ${B("huddle update")}                get the newest Huddle from npm
 
   ${F("run claude, codex and cursor yourself — in one repo, safely")}
   ${B("huddle connect")}               wire your agents into this repo's live room
@@ -241,6 +248,17 @@ async function main() {
             console.log(`${C.violet("huddle relay")} listening on :${r.port} ${C.faint("· people use it with: relay ws://<this-host>:" + r.port)}`);
             return;
         }
+        case "undo":
+            return void (process.exitCode = await (await import("./ui/undo.js")).runUndo(rest));
+        case "connectors":
+        case "connector": {
+            const { repoRoot } = await app();
+            return void (process.exitCode = await (await import("./connectors/cli.js")).runConnectors(rest, repoRoot()));
+        }
+        case "update":
+        case "upgrade":
+        case "--update":
+            return void process.exit((await import("./update.js")).runUpdate());
         case "--version":
         case "-v":
         case "-V":

package/dist/connectors/cli.js

@@ -0,0 +1,121 @@
+// `huddle connectors`: which outside tools your agents get, and adding more.
+//
+//   huddle connectors                       what's on, with each one's tool count
+//   huddle connectors add atlassian         Jira + Confluence (signs in in your browser, once)
+//   huddle connectors add <name> <https-url>        any remote MCP server
+//   huddle connectors add <name> -- <command…>      any local MCP server
+//   huddle connectors add … --write         let agents use the tools that post or change things
+//   huddle connectors remove <name>
+//   huddle connectors github on|off|write|read
+import { C } from "../ui/term.js";
+import { configFile, PRESETS, presetName, readConfig, remoteCommand, startHub, statusLine, writeConfig } from "./hub.js";
+const USAGE = `${C.bold("huddle connectors")}                     what your agents can reach, and how many tools each gives
+${C.bold("huddle connectors add")} ${C.faint("<service>")}       a service your team uses:
+${Object.entries(PRESETS)
+    .map(([n, p]) => `    ${n.padEnd(34)}${C.faint(p.what)}`)
+    .join("\n")}
+${C.bold("huddle connectors add")} ${C.faint("<name> <url>")}    any remote MCP server (signs in through mcp-remote)
+${C.bold("huddle connectors add")} ${C.faint("<name> -- <cmd…>")} any local MCP server
+                                      ${C.faint("add --write to let agents use the tools that post or change things")}
+${C.bold("huddle connectors remove")} ${C.faint("<name>")}
+${C.bold("huddle connectors github")} ${C.faint("on|off|write|read")}
+                                      ${C.faint("GitHub (through the gh CLI) is on by default, read-only")}`;
+async function check(root, cfg, only) {
+    const one = only
+        ? only === "github"
+            ? { github: cfg.github }
+            : { github: { off: true }, connectors: { [only]: cfg.connectors[only] } }
+        : cfg;
+    if (only && only !== "github")
+        console.log(C.faint(`  connecting to ${only}… (the first time, it may open your browser to sign in)`));
+    const hub = startHub({ root, config: one, connectMs: 180_000 });
+    await hub.ready;
+    let ok = true;
+    for (const s of hub.status()) {
+        ok &&= s.ok;
+        console.log(`  ${s.ok ? C.green("✓") : C.red("✗")} ${statusLine(s)}`);
+    }
+    if (!hub.status().length)
+        console.log(C.faint("  (none on)"));
+    hub.close();
+    return ok;
+}
+export async function runConnectors(args, root) {
+    const [sub, ...rest] = args;
+    const cfg = readConfig();
+    cfg.connectors ??= {};
+    // --write is Huddle's flag only before `--`; after it, everything is the server's command.
+    const cut = rest.indexOf("--");
+    const own = cut < 0 ? rest : rest.slice(0, cut);
+    const write = own.includes("--write");
+    const words = [...own.filter((a) => a !== "--write"), ...(cut < 0 ? [] : rest.slice(cut))];
+    if (!sub || sub === "list" || sub === "status") {
+        console.log(C.bold("Connectors") + C.faint(` · every agent in a run gets these tools · ${configFile()}`));
+        await check(root, cfg);
+        console.log();
+        console.log(USAGE);
+        return 0;
+    }
+    if (sub === "help" || sub === "--help")
+        return void console.log(USAGE), 0;
+    if (sub === "github") {
+        const how = words[0];
+        if (!how)
+            return (await check(root, cfg, "github")) ? 0 : 1;
+        if (!["on", "off", "write", "read"].includes(how)) {
+            console.log(C.red("✗ ") + "huddle connectors github on|off|write|read");
+            return 1;
+        }
+        cfg.github = how === "off" ? { ...cfg.github, off: true } : { off: false, write: how === "write" ? true : how === "read" ? false : !!cfg.github?.write };
+        writeConfig(cfg);
+        console.log(`${C.green("✓")} github ${how === "off" ? "off" : cfg.github.write ? "on — agents may comment and open issues, as you" : "on, read-only"}`);
+        return how === "off" ? 0 : (await check(root, cfg, "github")) ? 0 : 1;
+    }
+    if (sub === "add") {
+        const dash = words.indexOf("--");
+        const name = presetName(words[0] ?? "");
+        if (!/^[a-z][a-z0-9-]{0,30}$/.test(name) || name === "github") {
+            console.log(C.red("✗ ") + (name === "github" ? "GitHub is built in: huddle connectors github on" : "give it a short name (letters, digits, -): huddle connectors add jira"));
+            return 1;
+        }
+        let command;
+        if (dash >= 0)
+            command = words.slice(dash + 1);
+        else if (words[1] && /^https?:\/\//.test(words[1]))
+            command = remoteCommand(words[1]);
+        else if (PRESETS[name])
+            command = remoteCommand(PRESETS[name].url);
+        else {
+            console.log(C.red(`✗ no known service called "${name}".`) + ` Give its MCP URL (huddle connectors add ${name} https://…) or a command (huddle connectors add ${name} -- npx -y some-mcp-server).`);
+            return 1;
+        }
+        if (!command.length) {
+            console.log(C.red("✗ ") + "nothing after --");
+            return 1;
+        }
+        cfg.connectors[name] = { command, ...(write ? { write: true } : {}) };
+        writeConfig(cfg);
+        console.log(`${C.green("✓")} added ${C.bold(name)}${PRESETS[name] ? C.faint(` (${PRESETS[name].what})`) : ""}: ${C.faint(command.join(" "))}`);
+        const ok = await check(root, cfg, name);
+        if (!ok)
+            console.log(C.faint(`  it stays saved; fix it and check with: huddle connectors · or: huddle connectors remove ${name}`));
+        else if (!write)
+            console.log(C.faint(`  read-only: agents see the tools that read. To let them post or change things: huddle connectors add --write ${words.join(" ")}`));
+        return ok ? 0 : 1;
+    }
+    if (sub === "remove" || sub === "rm") {
+        const name = presetName(words[0] ?? "");
+        if (!cfg.connectors[name]) {
+            console.log(C.red(`✗ no connector "${name}".`) + ` On: ${Object.keys(cfg.connectors).join(", ") || "(none added)"}`);
+            return 1;
+        }
+        delete cfg.connectors[name];
+        writeConfig(cfg);
+        console.log(`${C.green("✓")} removed ${name}`);
+        return 0;
+    }
+    console.log(C.red(`✗ unknown: connectors ${sub}`));
+    console.log(USAGE);
+    return 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/connectors/github.js

@@ -0,0 +1,162 @@
+// The GitHub connector: issues, pull requests and CI for the repo you're in,
+// through the `gh` CLI you already signed in to. Huddle holds no GitHub token;
+// `gh` does, the same way each agent CLI holds its own login.
+//
+// Read tools are on whenever `gh` is signed in and the repo has a GitHub
+// remote. The two that write (a comment, a new issue) post as you, so they
+// show only after `huddle connectors github write`.
+import { spawnTool } from "../platform.js";
+const MAX_OUT = 60_000;
+/** Runs a command to completion, without blocking the Room's event loop. */
+export function runAsync(cmd, opts) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(r);
+        };
+        let child;
+        try {
+            child = spawnTool(cmd, { cwd: opts.cwd, stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, GH_PROMPT_DISABLED: "1", NO_COLOR: "1" } });
+        }
+        catch (e) {
+            return resolve({ code: 127, stdout: "", stderr: String(e?.message ?? e) });
+        }
+        const timer = setTimeout(() => {
+            child.kill();
+            finish({ code: 124, stdout, stderr: stderr + `\n(timed out after ${Math.round((opts.timeoutMs ?? 30_000) / 1000)}s)` });
+        }, opts.timeoutMs ?? 30_000);
+        child.stdout.on("data", (d) => (stdout += d));
+        child.stderr.on("data", (d) => (stderr += d));
+        child.on("error", (e) => finish({ code: 127, stdout, stderr: String(e.message) }));
+        child.on("close", (code) => finish({ code: code ?? 1, stdout, stderr }));
+        child.stdin.on("error", () => { }); // it may exit before reading it all
+        child.stdin.end(opts.input ?? "");
+    });
+}
+export const clipOut = (s, n = MAX_OUT) => (s.length > n ? s.slice(0, n) + `\n… (cut at ${n} characters)` : s);
+const num = (v) => {
+    const n = Number(String(v ?? "").replace(/^#/, ""));
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`not an issue or PR number: ${JSON.stringify(v)}`);
+    return String(n);
+};
+const limit = (v, def = 20) => String(Math.min(100, Math.max(1, Number(v) || def)));
+const state = (v) => (["open", "closed", "merged", "all"].includes(String(v)) ? String(v) : "open");
+/** One tool's result: gh's JSON (or text) when it worked, its error when not. */
+async function out(r) {
+    const x = await r;
+    if (x.code !== 0)
+        return { error: (x.stderr || x.stdout).trim().slice(0, 2000) || `gh exited ${x.code}` };
+    const t = x.stdout.trim();
+    try {
+        return JSON.parse(t);
+    }
+    catch {
+        return clipOut(t);
+    }
+}
+export function githubTools(gh, opts) {
+    const tools = [
+        {
+            name: "github_issues",
+            description: "List this repo's GitHub issues (number, title, state, labels, author). Filter with state, label or a search query.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    state: { type: "string", enum: ["open", "closed", "all"] },
+                    label: { type: "string" },
+                    search: { type: "string", description: "GitHub search syntax, e.g. 'login in:title'" },
+                    limit: { type: "number" },
+                },
+            },
+            call: (a) => out(gh([
+                "issue", "list", "--state", state(a.state), "--limit", limit(a.limit),
+                ...(a.label ? ["--label", String(a.label)] : []),
+                ...(a.search ? ["--search", String(a.search)] : []),
+                "--json", "number,title,state,labels,author,updatedAt",
+            ])),
+        },
+        {
+            name: "github_issue",
+            description: "Read one GitHub issue in full: its body, labels and every comment.",
+            inputSchema: { type: "object", properties: { number: { type: "number" } }, required: ["number"] },
+            call: (a) => out(gh(["issue", "view", num(a.number), "--json", "number,title,body,state,labels,author,comments,url"])),
+        },
+        {
+            name: "github_prs",
+            description: "List this repo's pull requests (number, title, branch, author, state).",
+            inputSchema: { type: "object", properties: { state: { type: "string", enum: ["open", "closed", "merged", "all"] }, limit: { type: "number" } } },
+            call: (a) => out(gh(["pr", "list", "--state", state(a.state), "--limit", limit(a.limit), "--json", "number,title,state,headRefName,author,url"])),
+        },
+        {
+            name: "github_pr",
+            description: "Read one pull request: description, changed files, comments and reviews. Pass diff: true for the diff too (cut at 60k characters).",
+            inputSchema: { type: "object", properties: { number: { type: "number" }, diff: { type: "boolean" } }, required: ["number"] },
+            call: async (a) => {
+                const n = num(a.number);
+                const view = await out(gh(["pr", "view", n, "--json", "number,title,body,state,headRefName,baseRefName,files,comments,reviews,url"]));
+                if (!a.diff)
+                    return view;
+                const d = await gh(["pr", "diff", n]);
+                return { pr: view, diff: d.code === 0 ? clipOut(d.stdout) : `(no diff: ${d.stderr.trim().slice(0, 300)})` };
+            },
+        },
+        {
+            name: "github_ci",
+            description: "The latest GitHub Actions runs (workflow, branch, status, conclusion), so you can see whether CI is green or what broke.",
+            inputSchema: { type: "object", properties: { branch: { type: "string" }, limit: { type: "number" } } },
+            call: (a) => out(gh(["run", "list", "--limit", limit(a.limit, 8), ...(a.branch ? ["--branch", String(a.branch)] : []), "--json", "databaseId,workflowName,headBranch,status,conclusion,createdAt,url"])),
+        },
+    ];
+    const writes = !opts.write ? [] : [
+        {
+            name: "github_comment",
+            description: "Post a comment on a GitHub issue or pull request, as the person running Huddle. Use it for what they'd want posted (a fix summary, a question), not chatter.",
+            inputSchema: { type: "object", properties: { number: { type: "number" }, body: { type: "string" } }, required: ["number", "body"] },
+            write: true,
+            call: (a, agent) => out(gh(["issue", "comment", num(a.number), "--body-file", "-"], `${String(a.body ?? "").trim()}\n\n${opts.signature(agent)}`)),
+        },
+        {
+            name: "github_new_issue",
+            description: "Open a new GitHub issue, as the person running Huddle: for a real bug or follow-up found while working that this run won't fix.",
+            inputSchema: { type: "object", properties: { title: { type: "string" }, body: { type: "string" } }, required: ["title", "body"] },
+            write: true,
+            call: (a, agent) => out(gh(["issue", "create", "--title", String(a.title ?? "").slice(0, 250), "--body-file", "-"], `${String(a.body ?? "").trim()}\n\n${opts.signature(agent)}`)),
+        },
+    ];
+    // A bad argument rejects (never throws mid-call), like every other tool.
+    return [...tools, ...writes].map((t) => ({ ...t, call: async (a, agent) => t.call(a, agent) }));
+}
+/** "#12", "issue 12", "fix #12", "github issue #12": the issue number, else null. */
+export function issueRef(goal) {
+    const m = /^\s*(?:(?:fix|close|solve|do|work on|build)\s+)?(?:(?:github|gh)\s+)?(?:issue\s*)?#(\d+)\s*$/i.exec(goal) ?? /^\s*(?:(?:fix|close|solve)\s+)?(?:github\s+)?issue\s+(\d+)\s*$/i.exec(goal);
+    return m ? Number(m[1]) : null;
+}
+/** The goal a run gets for a GitHub issue: its title, body and comments, verbatim. */
+export function issueGoal(issue) {
+    const comments = (issue.comments ?? [])
+        .slice(-8)
+        .map((c) => `- ${c.author?.login ?? "someone"}: ${String(c.body ?? "").trim().slice(0, 800)}`)
+        .join("\n");
+    return [
+        `Resolve GitHub issue #${issue.number}: ${issue.title}`,
+        issue.url ? `(${issue.url})` : "",
+        "",
+        String(issue.body ?? "").trim().slice(0, 6000) || "(the issue has no description)",
+        comments ? `\nComments on the issue:\n${comments}` : "",
+    ]
+        .filter((l, i) => l || i === 2)
+        .join("\n")
+        .trim();
+}
+/** Issues a longer goal mentions ("fix #12 and add a test"): up to 3 numbers. */
+export function issueMentions(goal) {
+    return [...new Set([...goal.matchAll(/(?:^|[\s(])#(\d{1,6})\b/g)].map((m) => Number(m[1])))].slice(0, 3);
+}
+//# sourceMappingURL=github.js.map