huddle-cli 0.1.0 → 0.1.1

package/dist/orchestrator/takeover.js

@@ -82,4 +82,159 @@ WHAT ${o.from} POSTED:
 ${left.length ? left.join("\n") : "  (nothing — it never called huddle_progress / huddle_remember)"}
 ${o.testOutput !== undefined ? `\nLAST TEST OUTPUT (tail):\n${cap(o.testOutput || "(no output)", 3000)}\n` : ""}${log ? `\nEND OF ${o.from}'S LOG (tail):\n${log}\n` : ""}`;
 }
+// --- buddy checks and pairing ---------------------------------------------
+//
+// Found live (3 capstone runs): no takeover or split ever happened — every
+// help offer was declined — and the only reviews came after huddle_done
+// (~9s rubber-stamp APPROVEs). So Huddle now acts on its own, mid-task:
+// a buddy check (another agent reads the work in progress at ~40% and the
+// author gets its notes right away), and pairing (a free agent takes a part
+// of the slowest task unless its author says no).
+/** Progress at which a task's work in progress gets a buddy check; the second only if the first had notes. */
+export const BUDDY_AT = [40, 75];
+/** Pairing only helps a task that is this far behind. */
+export const PAIR_MAX_PCT = 50;
+/**
+ * Can pairing help this task? One that reports progress: while it is under
+ * PAIR_MAX_PCT. One that never reported has no percentage at all (it is not
+ * 0%: it may be nearly done), so only when it has run over twice the help
+ * threshold AND its work so far touches under half of its planned files.
+ * `touched` is lazy: it reads the worktree, only needed for a quiet task.
+ */
+export function pairEligible(t) {
+    if (t.reported)
+        return t.pct < PAIR_MAX_PCT;
+    if (t.ranMs <= 2 * t.helpAfterMs)
+        return false;
+    return t.touched() * 2 < Math.max(t.planned, 1);
+}
+/** How long an author has to say no to a pairing. HUDDLE_PAIR_WAIT_SEC overrides. */
+export const DEFAULT_PAIR_WAIT_MS = 60_000;
+/** First buddy check for a task that never reports progress. HUDDLE_BUDDY_AFTER_SEC overrides; "off" = never. */
+export const DEFAULT_BUDDY_AFTER_MS = 120_000;
+export function buddyAfterMsFromEnv() {
+    const raw = process.env.HUDDLE_BUDDY_AFTER_SEC;
+    if (raw === undefined || raw === "")
+        return DEFAULT_BUDDY_AFTER_MS;
+    if (/^(off|never|no)$/i.test(raw))
+        return null;
+    const v = Number(raw);
+    return Number.isFinite(v) && v >= 0 ? v * 1000 : DEFAULT_BUDDY_AFTER_MS;
+}
+export function pairWaitMsFromEnv() {
+    const v = Number(process.env.HUDDLE_PAIR_WAIT_SEC);
+    return process.env.HUDDLE_PAIR_WAIT_SEC !== undefined && Number.isFinite(v) && v >= 0 ? v * 1000 : DEFAULT_PAIR_WAIT_MS;
+}
+/** QA rounds, QA bug fixes and conflict resolutions are never buddy-checked or paired. */
+export function isSpecialTask(t) {
+    return /^(QA round \d+:|Fix: |Resolve merge conflict)/.test(t.title) || /"(qa|quickfix)"/.test(t.prefers ?? "");
+}
+const stripMd = (l) => l.replace(/[*`#_>]/g, "").trim();
+export function buddyPrompt(o) {
+    return `You're a teammate looking over ${o.author}'s shoulder ${o.when} into their task. Another AI agent is still writing it; nothing is merged.
+
+TASK: ${o.title}
+${cap(o.spec, 1500)}
+${o.contract ? `\n${cap(o.contract, 2500)}\n` : ""}
+OTHER TASKS IN FLIGHT (their work so far):
+${o.others || "(none)"}
+
+${o.author.toUpperCase()}'S WORK SO FAR (diff against main, uncommitted included):
+${o.diff || "(nothing yet)"}
+
+You have NO tools and don't need them. Reply with up to 5 short concrete lines: what will break, what contradicts the task/contract or another in-flight task (name it: function, field, file), what they should do differently.
+Nothing worth changing? Reply exactly LOOKS GOOD. Do not edit anything.`;
+}
+/** Replies that mean "nothing to change", however a model words or decorates them. */
+const ALL_CLEAR = /^(LOOKS (GOOD|FINE)|LGTM|APPROVED?|NO (ISSUES|PROBLEMS|CONCERNS|NOTES)( FOUND)?|NOTHING (TO CHANGE|WORTH CHANGING))( (SO FAR|OVERALL|TO ME))?\b[\s.!:]*$/i;
+/** The buddy's notes, or null for LOOKS GOOD / nothing usable. */
+export function parseBuddy(text) {
+    const lines = String(text ?? "")
+        .split("\n")
+        .map((l) => stripMd(l).replace(/^(?:[-•]|\d+[.)])\s+/, "").trim())
+        .filter(Boolean);
+    // Only a pure all-clear: "Looks good, but cli.js calls listItems" is a note
+    // (real models open with praise, then name the mismatch the check is for).
+    if (!lines.length || ALL_CLEAR.test(lines[0]))
+        return null;
+    // "Here's my take:\nLOOKS GOOD" — a preamble and the all-clear is still the all-clear.
+    if (lines.length <= 2 && lines.some((l) => ALL_CLEAR.test(l)))
+        return null;
+    return lines
+        .slice(0, 5)
+        .map((l) => cap(l, 300))
+        .join("\n");
+}
+export function pairPrompt(o) {
+    return `${o.author} is behind on a task and you (${o.helper}) are free. Propose ONE part of it you could do alongside them, in files they won't edit.
+
+TASK: ${o.title}
+${cap(o.spec, 1500)}
+FILES: ${o.files.join(", ") || "(none listed)"}
+${o.contract ? `\n${cap(o.contract, 2000)}\n` : ""}
+THEIR WORK SO FAR:
+${o.diff || "(nothing yet)"}
+
+You have NO tools. Reply in exactly this form:
+PART: <short title>
+FILES: <comma-separated files you'd own — none they've already edited>
+SPEC: <2-4 lines: what to build, the names/shapes it must match>
+If nothing is cleanly separable, reply exactly NONE.`;
+}
+/** A FILES list as models write it: commas, spaces, backticks or quotes (a quoted name may hold spaces). */
+function fileList(raw) {
+    const out = [];
+    for (const piece of raw.split(/[,;]/)) {
+        const quoted = /^\s*[`'"](.+)[`'"]\s*$/.exec(piece);
+        if (quoted)
+            out.push(quoted[1].trim());
+        else
+            out.push(...piece.split(/\s+/).map((f) => f.replace(/[`'"]/g, "")));
+    }
+    return out.map((f) => f.trim().replace(/^\.\//, "")).filter((f) => f && !/^(none|n\/a|-)$/i.test(f));
+}
+/**
+ * The helper's proposal, or null: NONE, unparseable, a path outside the repo,
+ * a file the author already edited, or the whole of the task's file list
+ * (that isn't a part, it's the task).
+ */
+export function parsePart(text, authorFiles, taskFiles = []) {
+    text = String(text ?? "");
+    const get = (k) => new RegExp(`^\\s*[*_]*${k}[*_]*\\s*:[*_]*\\s*(.+)$`, "im").exec(text)?.[1]?.replace(/[*_]+$/, "").trim();
+    const title = get("PART");
+    if (!title || /^NONE\b/i.test(stripMd(title)))
+        return null;
+    const files = fileList(get("FILES") ?? "");
+    const specAt = text.search(/^\s*[*_]*SPEC[*_]*\s*:/im);
+    const spec = specAt >= 0 ? text.slice(specAt).replace(/^\s*[*_]*SPEC[*_]*\s*:[*_]*\s*/i, "").trim() : "";
+    if (!files.length || !spec)
+        return null;
+    if (files.some((f) => f.startsWith("/") || /^[a-z]:[\\/]/i.test(f) || f.split(/[\\/]/).includes("..")))
+        return null;
+    const norm = (p) => p.replace(/^\.\//, "").replace(/\/+$/, "");
+    const covers = (a, f) => norm(a) === norm(f) || norm(a).startsWith(norm(f) + "/");
+    if (files.some((f) => authorFiles.some((a) => covers(a, f))))
+        return null;
+    if (taskFiles.length && taskFiles.every((t) => files.some((f) => covers(t, f))))
+        return null;
+    return { title: cap(stripMd(title), 120), spec: cap(spec, 2000), files: files.slice(0, 12), tests: false };
+}
+/** Always separable: tests/verification of the task against its spec (+ contract), in a test file of the helper's own. */
+export function testsPart(title, spec) {
+    return {
+        title: cap(`Tests for: ${title}`, 120),
+        spec: `Write the tests / verification for this task against its spec, in a NEW test file of your own (follow the repo's test layout and runner) — ` +
+            `don't edit the task's own files. Test what the spec promises (acceptance points, error paths), not the implementation's internals. ` +
+            `Your tests run against the task's code once it lands.\n\nTHE TASK'S SPEC: ${title}\n${cap(spec, 1500)}`,
+        files: [],
+        tests: true,
+    };
+}
+/** What the author is told: who takes which part, and how to say no. */
+export function pairNote(helper, part, waitMs) {
+    const secs = Math.round(waitMs / 1000);
+    const files = part.files.length ? part.files.join(", ") : "a new test file";
+    return (`${helper} is taking “${part.title}” (files ${files}) in ${secs}s unless you reply huddle_send(to="huddle", message="no: <why>"). ` +
+        (part.files.length ? `Don't edit ${files}; ${helper} owns ${part.files.length > 1 ? "them" : "it"}.` : `Keep building; ${helper} writes the tests against your spec.`));
+}
 //# sourceMappingURL=takeover.js.map

package/dist/platform.js

@@ -0,0 +1,273 @@
+// Running other programs on every OS. Huddle drives CLIs it didn't write, and
+// on Windows most of them aren't .exe files: npm installs `codex` as a
+// `codex.cmd` batch shim, which child_process.spawn can't find without a shell
+// (ENOENT) and refuses to run without one (EINVAL, Node's 2024 fix for
+// CVE-2024-27980). A shell is no answer either: cmd.exe re-parses the whole
+// command line, and prompts are full of quotes, &, %, ^ and newlines.
+//
+// So every agent/tool spawn goes through toolCommand():
+//   macOS / Linux       unchanged — spawn(cmd[0], args), no shell
+//   Windows .exe/.com   the resolved path, no shell
+//   Windows npm shim    node <the shim's script> args — exact argv, no cmd.exe
+//   other .cmd/.bat     cmd.exe /d /s /c with every argument escaped for cmd
+//   .ps1                powershell -File
+// The Windows paths are pure functions of a Host, so tests run them on macOS.
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+export function host() {
+    return {
+        platform: process.platform,
+        env: process.env,
+        isFile: (p) => {
+            try {
+                return fs.statSync(p).isFile();
+            }
+            catch {
+                return false;
+            }
+        },
+        read: (p) => fs.readFileSync(p, "utf8"),
+        execPath: process.execPath,
+    };
+}
+export const isWindows = (h = process) => h.platform === "win32";
+/** An env var by name, case-insensitively — Windows env names are ("Path" vs "PATH"). */
+function envGet(env, name) {
+    if (env[name] !== undefined)
+        return env[name];
+    const k = Object.keys(env).find((x) => x.toUpperCase() === name);
+    return k ? env[k] : undefined;
+}
+/**
+ * Where Windows would find `bin`: each PATH dir, trying each PATHEXT
+ * extension — what `where` does. The current directory is NOT searched (cmd
+ * does that; a repo could plant a codex.cmd). null = not found.
+ */
+export function findOnWindowsPath(bin, h = host()) {
+    const P = path.win32;
+    const exts = (envGet(h.env, "PATHEXT") || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    const hasExt = exts.some((e) => bin.toLowerCase().endsWith(e.toLowerCase()));
+    const tries = (base) => (hasExt ? [base] : exts.map((e) => base + e.toLowerCase()));
+    if (/[\\/]/.test(bin))
+        return tries(bin).find(h.isFile) ?? null;
+    for (const raw of (envGet(h.env, "PATH") ?? "").split(";")) {
+        const dir = raw.trim().replace(/^"(.*)"$/, "$1");
+        if (!dir)
+            continue;
+        const hit = tries(P.join(dir, bin)).find(h.isFile);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+// Cursor's docs now name the CLI `agent` (https://cursor.com/docs/cli/installation);
+// macOS/Linux installs still add `cursor-agent`. If a Windows install only has
+// `agent`, use that.
+const WINDOWS_ALIASES = { "cursor-agent": ["agent"] };
+/** findOnWindowsPath, plus the known alternate names of a CLI. */
+export function resolveWindowsBin(bin, h = host()) {
+    for (const b of [bin, ...(WINDOWS_ALIASES[bin] ?? [])]) {
+        const hit = findOnWindowsPath(b, h);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/**
+ * The JS file an npm/cmd-shim batch file runs, if it is one: the shim's
+ * last line is `"%_prog%"  "%dp0%\node_modules\@openai\codex\bin\codex.js" %*`
+ * (older shims: `"%~dp0\node.exe" "%~dp0\..\x.js" %*`).
+ */
+export function npmShimTarget(shim, h = host()) {
+    let text = "";
+    try {
+        text = h.read(shim);
+    }
+    catch {
+        return null;
+    }
+    const m = /"%~?dp0%?\\?([^"%]+\.[cm]?js)"\s+%\*/i.exec(text);
+    if (!m)
+        return null;
+    const target = path.win32.join(path.win32.dirname(shim), m[1]);
+    return h.isFile(target) ? target : null;
+}
+// cmd.exe's special characters. Escaping every one with ^ (the quote too) keeps
+// cmd's quote state from ever toggling, so it sees no operators anywhere.
+const CMD_META = /([()\][%!^"`<>&|;, *?])/g;
+/**
+ * One argument for a cmd.exe command line that runs a batch file. First the
+ * MSVCRT quoting every Windows program parses argv with (backslashes are only
+ * special before a quote), then ^-escape for cmd — twice, because cmd parses
+ * the line once and the batch file's %* expansion parses it again.
+ */
+export function quoteCmdArg(arg) {
+    // cmd can't carry a line break inside a command: it ends the command there.
+    // Only reached for batch files that aren't npm shims, and only a prompt has
+    // newlines, so they become spaces (adapters that can take the prompt on
+    // stdin avoid this path entirely).
+    let a = arg.replace(/\r?\n/g, " ");
+    a = a.replace(/(\\*)"/g, (_m, bs) => bs + bs + '\\"').replace(/(\\*)$/, (_m, bs) => bs + bs);
+    a = `"${a}"`;
+    return a.replace(CMD_META, "^$1").replace(CMD_META, "^$1");
+}
+/** The program itself on that command line (it is never re-parsed by %*). */
+export function quoteCmdProgram(file) {
+    return file.replace(CMD_META, "^$1");
+}
+/** How to spawn `cmd` (argv form) on this platform — see the header comment. */
+export function toolCommand(cmd, h = host()) {
+    const [bin, ...args] = cmd;
+    if (!isWindows(h))
+        return { file: bin, args };
+    const resolved = resolveWindowsBin(bin, h);
+    if (!resolved)
+        return { file: bin, args }; // spawn reports ENOENT, as it should
+    const ext = path.win32.extname(resolved).toLowerCase();
+    if (ext === ".cmd" || ext === ".bat") {
+        const script = npmShimTarget(resolved, h);
+        if (script) {
+            // The shim prefers a node.exe next to it, else node on PATH; Huddle's own node is that.
+            const local = path.win32.join(path.win32.dirname(resolved), "node.exe");
+            return { file: h.isFile(local) ? local : h.execPath, args: [script, ...args] };
+        }
+        const line = [quoteCmdProgram(resolved), ...args.map(quoteCmdArg)].join(" ");
+        return { file: envGet(h.env, "COMSPEC") || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+    }
+    if (ext === ".ps1")
+        return { file: "powershell.exe", args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolved, ...args] };
+    return { file: resolved, args };
+}
+/**
+ * Some CLIs read the prompt from stdin when it's left off the command line
+ * (`stdinPrompt`: what goes in its place — "" drops it, "-" for codex). On
+ * Windows Huddle always does that: no quoting, no 32K command-line limit.
+ */
+export function promptOnStdin(cmd, prompt, stdinPrompt, h = process) {
+    if (!isWindows(h) || prompt === undefined || stdinPrompt === undefined)
+        return { cmd };
+    const i = cmd.lastIndexOf(prompt);
+    if (i <= 0)
+        return { cmd };
+    const out = [...cmd];
+    if (stdinPrompt === "")
+        out.splice(i, 1);
+    else
+        out[i] = stdinPrompt;
+    return { cmd: out, stdin: prompt };
+}
+/** spawn() for an agent or tool CLI. `plan` lets the prompt travel on stdin (Windows). */
+export function spawnTool(cmd, opts = {}, plan = {}) {
+    const p = promptOnStdin(cmd, plan.prompt, plan.stdinPrompt);
+    const t = toolCommand(p.cmd);
+    const stdio = p.stdin === undefined ? opts.stdio : withStdinPipe(opts.stdio);
+    const child = spawn(t.file, t.args, { ...opts, stdio, windowsVerbatimArguments: t.verbatim || opts.windowsVerbatimArguments });
+    if (p.stdin !== undefined && child.stdin) {
+        child.stdin.on("error", () => { }); // the CLI may exit before reading it all
+        child.stdin.end(p.stdin);
+    }
+    return child;
+}
+function withStdinPipe(stdio) {
+    if (Array.isArray(stdio))
+        return ["pipe", ...stdio.slice(1)];
+    if (stdio === "inherit")
+        return ["pipe", "inherit", "inherit"];
+    return ["pipe", "pipe", "pipe"];
+}
+export function spawnToolSync(cmd, opts = {}) {
+    const t = toolCommand(cmd);
+    return spawnSync(t.file, t.args, { ...opts, windowsVerbatimArguments: t.verbatim || opts.windowsVerbatimArguments });
+}
+/** Is `bin` on PATH? (`which`, or the PATHEXT search on Windows.) */
+export function onPath(bin, h = host()) {
+    if (isWindows(h))
+        return resolveWindowsBin(bin, h) !== null;
+    return spawnSync("which", [bin], { stdio: "ignore" }).status === 0;
+}
+/**
+ * A shell command line, as [file, args, verbatim]. Installers are written for
+ * the platform's shell: sh on macOS/Linux, PowerShell on Windows
+ * (`irm … | iex`). `cmd.exe` is for project commands like `npm test`.
+ */
+export function shellCommand(line, shell = "default", h = process) {
+    if (!isWindows(h))
+        return { file: "sh", args: ["-c", line] };
+    if (shell === "cmd")
+        return { file: envGet(h.env, "COMSPEC") || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], verbatim: true };
+    // Bypass: npm's own npm.ps1 is blocked under the default Restricted policy.
+    return { file: "powershell.exe", args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", line] };
+}
+/** Run a shell command line with the terminal handed over. */
+export function runShell(line, opts = { stdio: "inherit" }, shell = "default") {
+    const t = shellCommand(line, shell);
+    return spawnSync(t.file, t.args, { ...opts, windowsVerbatimArguments: t.verbatim });
+}
+/**
+ * Stop a process and everything it started. POSIX: SIGTERM (the caller
+ * escalates to SIGKILL). Windows has no signals for a process tree —
+ * child.kill() would end only the node shim and orphan the real agent — so
+ * taskkill /T /F ends the whole tree at once.
+ */
+export function killTree(child, h = process, run = spawnSync) {
+    if (isWindows(h) && child.pid) {
+        const r = run("taskkill", ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore", windowsHide: true });
+        if (r.status === 0)
+            return;
+    }
+    child.kill("SIGTERM");
+}
+/** How long after 'exit' a child's pipes get to drain before we stop waiting for 'close'. */
+export const DRAIN_MS = 2000;
+/**
+ * Call `done` once, when `child` has exited AND its output is in. 'exit' can
+ * come before the last of stdout has been read — when our event loop is busy
+ * (a merge's test run blocks it) an agent's final lines (its token usage, the
+ * log's tail) were lost. So: on 'close' (every pipe drained), but at most
+ * `drainMs` after 'exit', since a CLI's leftover grandchild can hold the pipes
+ * open forever. 'error' (it never ran) is code -1.
+ */
+export function onFinished(child, done, drainMs = DRAIN_MS) {
+    let over = false;
+    const finish = (code) => {
+        if (over)
+            return;
+        over = true;
+        done(code);
+    };
+    child.once("close", (code) => finish(code));
+    child.once("exit", (code) => void setTimeout(() => finish(code), drainMs).unref());
+    child.once("error", () => finish(-1));
+}
+/** Repo-relative path with forward slashes, whatever the OS gave us ("src\\a.ts" → "src/a.ts"). */
+export const slash = (p) => p.replace(/\\/g, "/");
+/**
+ * A hook command line an agent CLI runs through its shell (Claude's
+ * PostToolUse mail hook). sh: single quotes, nothing expands. Windows: the
+ * hook may run under Git Bash, cmd or PowerShell, so every part is
+ * double-quoted with forward slashes (node takes them; C:\Users\Some Name\…
+ * survives all three) — what `huddle connect`'s guard hook does too.
+ */
+export function hookCommand(argv, h = process) {
+    if (!isWindows(h))
+        return argv.map((a) => `'${a.replace(/'/g, `'\\''`)}'`).join(" ");
+    return argv.map((a) => `"${slash(a)}"`).join(" ");
+}
+/** How to install git here, as one line for a message. */
+export function gitFix(platform = process.platform) {
+    if (platform === "win32")
+        return "winget install --id Git.Git -e --source winget  ·  https://git-scm.com/install/windows";
+    if (platform === "darwin")
+        return "xcode-select --install  ·  https://git-scm.com";
+    return "sudo apt install git (Debian/Ubuntu), or your package manager  ·  https://git-scm.com";
+}
+/** How to install (or upgrade to) Node.js LTS here. */
+export function nodeFix(platform = process.platform) {
+    if (platform === "win32")
+        return "winget install OpenJS.NodeJS.LTS  ·  https://nodejs.org";
+    if (platform === "darwin")
+        return "brew install node  ·  https://nodejs.org";
+    return "https://nodejs.org (or your package manager / nvm)";
+}
+//# sourceMappingURL=platform.js.map