heedvane 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,666 @@
+#!/usr/bin/env node
+/**
+ * heedvane-hook — command routing: init | setup | doctor | uninstall |
+ * listener | status | mcp. Plain argv parsing (no commander); all state
+ * mutations flow through plan → apply; --dry-run writes nothing.
+ */
+import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { constants as osConstants, homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { supportedClients } from "./clients/definitions.js";
+import { installHermesPlugin } from "./clients/hermes-plugin.js";
+import { applyEntry } from "./apply.js";
+import { DEFAULT_HEED_YAML_TEMPLATE, heedvaneConfigAt, loadHeedFile, loadHeedFileAt, withInstallChoices, withServerUrl } from "./heed-file.js";
+import { planActions, desiredEntriesFor, isClientDetected } from "./plan.js";
+import { appliedFailed, capabilitySummary, renderApplied, renderDetection, renderPlan, wouldInstallSummary } from "./render.js";
+import { runDoctor } from "./doctor.js";
+import { installSkill } from "./skill/bundle.js";
+import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
+import { emptyState, readState, writeStateAtomic } from "./state.js";
+import { writeDispatcherScript } from "./dispatchers/posix.js";
+import { removeDeferredHookGroups, removeStaleHookGroups, uninstall } from "./uninstall.js";
+import { statusText, runMcpStdio } from "./mcp-server.js";
+import { errorMessage } from "./guards.js";
+import { ensureEndpoint } from "./listener/endpoint.js";
+import { listenerLogPath, startListenerInBackground } from "./listener/background.js";
+import { serveHooks } from "./listener/serve.js";
+import { cmdAuth, cmdLogin, cmdSkills } from "./commands/heedvane.js";
+import { cmdMemory } from "./commands/memory.js";
+import { backendAt } from "./backend/credentials.js";
+import { readLogin } from "./backend/login.js";
+import { agentLines, askChoices, brandIntro, confirmInstall, installCancelled, installFinished, installWithSpinner, listenerStep, promptLine, showInstalled } from "./installer.js";
+const USAGE = `  heedvane-hook — cross-agent steering, guardrails & analysis
+
+  Usage: npx heedvane [command] [flags]   (installed: heedvane <command>)
+         npx heedvane on its own, at a terminal, opens the installer: tick agents and features, confirm.
+
+  Commands:
+    connect         set up this machine: the installer at a terminal; with --yes (or in a script) every detected agent at once
+    run -- <cmd>    CI, containers and software factories: Heedvane answers the hooks for the length of one agent run
+    init            write ~/.heed/heed.yaml (if missing), plan, apply
+    setup           plan + apply from an existing heed.yaml
+    doctor          scoped, remediation-carrying health check
+    uninstall       marker-verified removal (never touches heed.yaml)
+    listener        listener controls (start): answers hooks with skill checks, steering and memory
+    login           sign in to Heedvane in the browser (~/.heed/login.json, 0600; refreshed automatically)
+    auth org        CI/headless: store an organization API key read from stdin (~/.heed/credentials.json, 0600)
+    skills sync     install the organization's approved skills and cache the list hooks enforce
+    memory list|show|search   browse this repository's team memory (a folder, one memory, or a question)
+    status          quick state summary
+    mcp             run the MCP stdio server (what agents register)
+
+  Flags: --dry-run --yes --json --agent <id> (repeatable) --client <id> --purge-config --project
+         --server <url> (connect/init: the Heedvane app to use, saved as heedvane.url; --url also works)
+         --org <id> (connect/init: the organization the sign-in must belong to)`;
+function resolveHome(env) {
+    return env.HEED_HOME ?? homedir();
+}
+/** Repeated flag values, comma-split: `--agent a,b` and `--agent a --agent b` both feed the list. */
+function parseRepeatedFlag(args, flag) {
+    const values = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === flag) {
+            values.push(...(args[i + 1] ?? "").split(",").filter(Boolean));
+            i += 1;
+        }
+    }
+    return values;
+}
+/** The value after `name` in the raw arguments, if the flag is there. */
+function flagValue(args, name) {
+    const at = args.indexOf(name);
+    return at < 0 ? undefined : args[at + 1];
+}
+/** Positional (non-flag) arguments, skipping the values of the repeatable flags. */
+function positionalArgs(args, repeatableFlags) {
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        if (repeatableFlags.includes(args[i])) {
+            i += 1; // skip the value
+            continue;
+        }
+        if (!args[i].startsWith("--"))
+            positional.push(args[i]);
+    }
+    return positional;
+}
+/** The parsed argv: boolean flags, repeatable flag values, and positional command words. */
+function parseInvocation(args) {
+    return {
+        flags: {
+            dryRun: args.includes("--dry-run"),
+            yes: args.includes("--yes"),
+            json: args.includes("--json"),
+            purge: args.includes("--purge-config"),
+        },
+        agents: parseRepeatedFlag(args, "--agent"),
+        clients: parseRepeatedFlag(args, "--client"),
+        server: flagValue(args, "--server") ?? flagValue(args, "--url"),
+        org: flagValue(args, "--org"),
+        positional: positionalArgs(args, ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--token"]),
+    };
+}
+async function main(argv, opts = {}) {
+    const ctx = commandContext(argv, opts);
+    const command = ctx.positional[0];
+    if (command === undefined && takesInstaller(ctx))
+        return cmdInstall(ctx);
+    if (!command || command === "help" || command === "--help") {
+        ctx.out(USAGE);
+        return command ? 0 : 2;
+    }
+    return routeCommand(command, ctx);
+}
+function commandContext(argv, opts) {
+    const env = opts.env ?? process.env;
+    const args = [...argv];
+    return {
+        ...parseInvocation(args),
+        home: resolveHome(env),
+        env,
+        out: opts.write ?? ((line) => console.log(line)),
+        args,
+        readStdin: opts.readStdin ?? readProcessStdin,
+        openBrowser: opts.openBrowser ?? openSystemBrowser,
+        interactive: opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
+        cwd: opts.cwd ?? process.cwd(),
+        prompts: opts.prompts ?? {},
+        startListener: opts.startListener ?? ((home) => startListenerInBackground(home, fileURLToPath(import.meta.url), env)),
+    };
+}
+async function routeCommand(command, ctx) {
+    switch (command) {
+        case "connect":
+            return takesInstaller(ctx) ? cmdInstall(ctx) : cmdInit({ ...ctx, flags: { ...ctx.flags, yes: true } });
+        case "init":
+            return cmdInit(ctx);
+        case "setup":
+            return cmdSetup(ctx);
+        case "doctor":
+            return cmdDoctor(ctx);
+        case "uninstall":
+            return cmdUninstall({ home: ctx.home, env: ctx.env, out: ctx.out, agents: ctx.agents, purge: ctx.flags.purge });
+        default:
+            return routeServiceCommand(command, ctx);
+    }
+}
+async function routeServiceCommand(command, ctx) {
+    switch (command) {
+        case "status": {
+            ctx.out(await statusText());
+            return 0;
+        }
+        case "mcp": {
+            runMcpStdio({ write: (line) => ctx.out(line) });
+            return 0;
+        }
+        case "listener": {
+            return cmdListener({ home: ctx.home, out: ctx.out, rest: ctx.args.slice(ctx.args.indexOf("listener") + 1) });
+        }
+        case "run":
+            return cmdRun({ home: ctx.home, env: ctx.env, command: ctx.args.slice(ctx.args.indexOf("--") + 1), separated: ctx.args.includes("--") });
+        case "login":
+            return cmdLogin(backendCommandContext(ctx));
+        case "auth":
+        case "skills":
+            return (command === "auth" ? cmdAuth : cmdSkills)(backendCommandContext(ctx));
+        case "memory":
+            return cmdMemory({ home: ctx.home, out: ctx.out, words: ctx.positional.slice(1), flag: (name) => flagValue(ctx.args, name), cwd: ctx.cwd });
+        default:
+            ctx.out(`  ✗ unknown command: ${command}`);
+            ctx.out(USAGE);
+            return 2;
+    }
+}
+function banner(out) {
+    out("  Heedvane Agent Hooks — cross-agent steering, guardrails & analysis");
+    out("");
+}
+function detectionRows(home, env) {
+    return supportedClients({ home, platform: platform(), env }).map((client) => ({
+        client,
+        detected: isClientDetected(client),
+        markerRel: client.markerPath.replace(home, "~"),
+    }));
+}
+function loadOrTemplate(home) {
+    const path = join(home, ".heed", "heed.yaml");
+    if (!existsSync(path))
+        return { heedFile: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE), existed: false };
+    try {
+        return { heedFile: loadHeedFileAt(path), existed: true };
+    }
+    catch (err) {
+        return { heedFile: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE), existed: true, error: errorMessage(err) };
+    }
+}
+function planFor(plan) {
+    const effective = plan.agents.length > 0 ? { ...plan.heedFile, agents: [...plan.agents] } : plan.heedFile;
+    return planActions({ home: plan.home, platform: platform(), env: plan.env, heedFile: effective, forced: plan.agents, skillDigest: skillDigest(canonicalSkillFiles()) });
+}
+async function cmdInit(ctx) {
+    const { home, env, out, flags, agents } = ctx;
+    banner(out);
+    const rows = detectionRows(home, env);
+    for (const line of renderDetection(rows))
+        out(line);
+    const loaded = loadOrTemplate(home);
+    if (loaded.error) {
+        out("");
+        out(`  ✗ ~/.heed/heed.yaml does not parse: ${loaded.error}`);
+        out(`    remediation: fix or remove it, then run npx heedvane init`);
+        return 1;
+    }
+    let serverEdit;
+    try {
+        serverEdit = ctx.server === undefined ? null : withServer(home, loaded, ctx.server);
+    }
+    catch (err) {
+        out("");
+        out(`  ✗ --server ${ctx.server} cannot be used: ${errorMessage(err)}`);
+        return 1;
+    }
+    const { heedFile, existed } = serverEdit ?? loaded;
+    const actions = planFor({ home, env, heedFile, agents });
+    // Plain init (no --yes, no --dry-run): show the plan summary, write nothing.
+    if (!flags.yes && !flags.dryRun) {
+        out("");
+        out(wouldInstallSummary(actions));
+        out("  Re-run with --yes to apply, or --dry-run for the full file-by-file plan.");
+        return 0;
+    }
+    if (flags.dryRun) {
+        out("");
+        for (const line of renderPlan(actions))
+            out(line);
+        out("");
+        out(wouldInstallSummary(actions));
+        if (flags.json)
+            outJson(out, { status: "planned", plannedActions: actions, appliedActions: [] });
+        return 0; // zero writes — the fixture home is untouched
+    }
+    // --yes: first non-dry run has approval; proceed to write.
+    return applyAndReport(ctx, { heedFile, agents, existed, ...(serverEdit === null ? {} : { text: serverEdit.text }) });
+}
+/** heed.yaml (or the template) with `--server` as `heedvane.url`; null when it already names that server. Throws on an unusable URL. */
+function withServer(home, loaded, server) {
+    const text = withServerUrl(heedText(home, loaded.existed), server);
+    const heedFile = loadHeedFile(text);
+    if (loaded.existed && heedFile.heedvane.url === loaded.heedFile.heedvane.url)
+        return null;
+    return { heedFile, existed: loaded.existed, text };
+}
+async function applyAndReport(ctx, spec) {
+    const { out, flags } = ctx;
+    const { actions, applied } = await installPlan(ctx, spec);
+    for (const line of renderApplied(applied))
+        out(line);
+    if (!flags.dryRun)
+        await signInIfNeeded(ctx, spec.heedFile.heedvane.url);
+    out("");
+    out("  Next: open a new agent session and run /heedvane-status.");
+    out("  Re-run `npx heedvane doctor` after any heed.yaml edit.");
+    const failed = applied.some(appliedFailed);
+    if (flags.json)
+        outJson(out, { status: failed ? "failed" : "applied", plannedActions: actions, appliedActions: applied });
+    return failed ? 1 : 0;
+}
+/** Writes heed.yaml when it is missing, or when `--server` changed its URL. */
+function writeControlFile({ home, out }, { heedFile, existed, text }) {
+    if (existed && text === undefined)
+        return;
+    mkdirSync(join(home, ".heed"), { recursive: true, mode: 0o700 });
+    writeFileSync(join(home, ".heed", "heed.yaml"), text ?? DEFAULT_HEED_YAML_TEMPLATE, { mode: 0o600 });
+    out(existed ? `  ✓ Set heedvane.url in ~/.heed/heed.yaml to ${heedFile.heedvane.url}` : `  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
+}
+/** Without a sign-in to `url` (and to `--org`, when named), sign in now when a person is at the terminal, else say how. Never fails setup. */
+/** Writes heed.yaml, applies the plan, issues the listener endpoint and records the machine state. Prints only what applying prints. */
+async function installPlan(ctx, spec) {
+    const { home, env, out } = ctx;
+    const { heedFile, agents } = spec;
+    // The control file comes first (mock order): "✓ Wrote ~/.heed/heed.yaml".
+    writeControlFile(ctx, spec);
+    const actions = planFor({ home, env, heedFile, agents });
+    const dispatcher = {
+        denySkillsWhenUnchecked: heedFile.heedvane.skills.enforce && heedFile.heedvane.skills.whenUnknown === "deny",
+        gating: heedFile.gating.mode,
+        nodeDir: dirname(process.execPath),
+    };
+    const applied = await applyPlan(actions, { home, env, out, dispatcher });
+    // The listener port and token every dispatcher reads; kept once issued.
+    await ensureEndpoint(join(home, ".heed"));
+    // Machine state: CLI-owned; preserve an existing endpoint.
+    const root = join(home, ".heed");
+    const existing = await readState(root);
+    const state = existing ?? emptyState();
+    // Record the skill only when this run installed it (or found it current).
+    const skillInstalled = applied.some((a) => a.kind === "skill" && (a.status === "installed" || a.status === "unchanged"));
+    if (skillInstalled)
+        state.skill = { version: "1", digest: skillDigest(canonicalSkillFiles()) };
+    await writeStateAtomic(root, state);
+    return { actions, applied };
+}
+async function signInIfNeeded(ctx, url) {
+    const root = join(ctx.home, ".heed");
+    if ((await backendAt(root, url)) !== null && (await onRequestedOrg(root, ctx.org)))
+        return;
+    if (!ctx.interactive) {
+        ctx.out("  Next: sign in with `npx heedvane login` (CI and headless machines: npx heedvane auth org < key-file).");
+        return;
+    }
+    await cmdLogin({ home: ctx.home, out: ctx.out, words: [], project: false, readStdin: async () => "", openBrowser: ctx.openBrowser });
+    if (!(await onRequestedOrg(root, ctx.org))) {
+        ctx.out(`  ✗ This sign-in belongs to another organization than ${ctx.org}. Run \`npx heedvane login\` and pick that organization on the consent page.`);
+    }
+}
+/** True without `--org`; else whether the saved login was granted for that organization. */
+async function onRequestedOrg(root, org) {
+    if (org === undefined)
+        return true;
+    const saved = await readLogin(root).catch(() => null);
+    return saved?.organizationId === org;
+}
+async function cmdSetup(ctx) {
+    const { home, out } = ctx;
+    const path = join(home, ".heed", "heed.yaml");
+    if (!existsSync(path)) {
+        out("  ✗ ~/.heed/heed.yaml not found — setup compiles your control file into agent configs.");
+        out("    remediation: run npx heedvane init");
+        return 1;
+    }
+    let heedFile;
+    try {
+        heedFile = loadHeedFileAt(path, out);
+    }
+    catch (err) {
+        out(`  ✗ ~/.heed/heed.yaml does not parse: ${errorMessage(err)}`);
+        out("    remediation: fix it, then re-run npx heedvane setup");
+        return 1;
+    }
+    banner(out);
+    if (ctx.flags.dryRun) {
+        const actions = planFor({ home, env: ctx.env, heedFile, agents: ctx.agents });
+        for (const line of renderPlan(actions))
+            out(line);
+        out("");
+        out(wouldInstallSummary(actions));
+        if (ctx.flags.json)
+            outJson(out, { status: "planned", plannedActions: actions, appliedActions: [] });
+        return 0; // zero writes
+    }
+    return applyAndReport(ctx, { heedFile, agents: ctx.agents, existed: true });
+}
+/** A person at a terminal who did not ask for the one-shot path (`--yes`, `--dry-run`, `--json`) or for help. */
+function takesInstaller(ctx) {
+    return ctx.interactive && !ctx.flags.yes && !ctx.flags.dryRun && !ctx.flags.json && !ctx.args.includes("--help");
+}
+/** heed.yaml's text, or the template when there is none yet. */
+function heedText(home, existed) {
+    return existed ? readFileSync(join(home, ".heed", "heed.yaml"), "utf8") : DEFAULT_HEED_YAML_TEMPLATE;
+}
+/** The installer: pick agents, integrations and features, confirm, install, start the listener, sign in. */
+async function cmdInstall(ctx) {
+    const base = installerBase(ctx);
+    if (typeof base === "string") {
+        ctx.out(`  ✗ ${base}`);
+        return 1;
+    }
+    const { prompts } = ctx;
+    brandIntro(base.heedFile.heedvane.url, ctx.org, prompts);
+    const choices = await askChoices(agentOptions(ctx), base.heedFile, prompts);
+    if (choices === null)
+        return installCancelled(prompts);
+    const text = withInstallChoices(base.text, choices);
+    const spec = { heedFile: loadHeedFile(text), agents: choices.agents === "auto" ? [] : choices.agents, existed: base.existed, text };
+    const names = new Map(detectionRows(ctx.home, ctx.env).map((row) => [row.client.id, row.client.displayName]));
+    const planned = agentLines(planFor({ home: ctx.home, env: ctx.env, ...spec }), names);
+    if (!(await confirmInstall(planned, prompts)))
+        return installCancelled(prompts);
+    const notes = [];
+    const { actions, applied } = await installWithSpinner(planned.length, () => installPlan({ ...ctx, out: (line) => notes.push(line) }, spec), prompts);
+    notes.forEach(promptLine(prompts));
+    showInstalled(agentLines(actions, names, applied), prompts);
+    const listening = await listenerStep(() => ctx.startListener(ctx.home), listenerLogPath(join(ctx.home, ".heed")), prompts);
+    await signInIfNeeded({ ...ctx, out: promptLine(prompts) }, spec.heedFile.heedvane.url);
+    installFinished(nextSteps(listening, spec.heedFile.heedvane.url), prompts);
+    return applied.some(appliedFailed) ? 1 : 0;
+}
+/** heed.yaml's current text (or the template) with `--server` applied, parsed; a message when either cannot be used. */
+function installerBase({ home, server }) {
+    const loaded = loadOrTemplate(home);
+    if (loaded.error)
+        return `~/.heed/heed.yaml does not parse: ${loaded.error}`;
+    try {
+        const current = heedText(home, loaded.existed);
+        const text = server === undefined ? current : withServerUrl(current, server);
+        return { heedFile: loadHeedFile(text), existed: loaded.existed, text };
+    }
+    catch (err) {
+        return `--server ${server} cannot be used: ${errorMessage(err)}`;
+    }
+}
+function agentOptions({ home, env }) {
+    return detectionRows(home, env).map(({ client, detected }) => ({ id: client.id, name: client.displayName, detected, capability: capabilitySummary(client) }));
+}
+function nextSteps(listening, server) {
+    return [
+        "Open a new agent session: Heedvane joins it at session start.",
+        `Watch your sessions: ${server}`,
+        ...(listening ? [] : ["Heedvane starts by itself with your next agent session. To see why it did not start now: npx heedvane listener start"]),
+        "Check the install: npx heedvane doctor",
+        "Change your choices: npx heedvane",
+    ];
+}
+/** Hermes' hooks capability rides its native plugin; installHermesPlugin owns creation and ownership checks. */
+async function applyHermesPlugin(client, ctx) {
+    const path = join(ctx.home, ".hermes", "plugins", "heedvane-hooks", "plugin.yaml");
+    const status = await installHermesPlugin(ctx.home, ctx.dispatcher.gating);
+    if (status === "skipped") {
+        return { clientId: client.id, kind: "hooks", status: "skipped", path, reason: "another plugin owns ~/.hermes/plugins/heedvane-hooks — left untouched" };
+    }
+    return { clientId: client.id, kind: "hooks", status: status === "installed" ? "create" : "unchanged", path };
+}
+/** Drop our groups under event keys this client no longer installs; a failed removal becomes the result. */
+async function withoutStaleHookGroups(client, writes, result) {
+    let worst = result;
+    for (const { target, containerKey } of writes) {
+        if (containerKey !== "hooks")
+            continue;
+        for (const item of await removeStaleHookGroups(client, target)) {
+            if (item.status === "failed")
+                return { status: "failed", path: item.path, reason: item.detail };
+            if (worst.status === "unchanged")
+                worst = { status: "update", path: item.path };
+        }
+    }
+    return worst;
+}
+/** Patch every desired entry into the client's config files, then refresh the dispatcher script. */
+async function applyConfigEntries(action, client, ctx) {
+    const desireds = desiredEntriesFor(client, action.kind === "hooks" ? "hooks" : "mcp", { home: ctx.home, env: ctx.env });
+    // One write per file and container: every hook event lands (and is backed up) together.
+    const writes = new Map();
+    for (const d of desireds) {
+        const key = `${d.path}\0${d.containerKey}`;
+        const write = writes.get(key) ?? { target: { path: d.path, format: d.format }, containerKey: d.containerKey, entries: {} };
+        write.entries[d.entryName] = d.entry;
+        writes.set(key, write);
+    }
+    let worst = { status: "unchanged", path: action.path };
+    for (const { target, containerKey, entries } of writes.values()) {
+        const res = await applyEntry(target, { containerKey, entries });
+        if (res.status === "failed" || res.status === "invalid") {
+            worst = res;
+            break;
+        }
+        if (res.status !== "unchanged")
+            worst = res;
+    }
+    if (action.kind === "hooks" && worst.status !== "failed" && worst.status !== "invalid") {
+        worst = await withoutStaleHookGroups(client, writes.values(), worst);
+    }
+    // The dispatcher script the snippet delegates to.
+    await writeDispatcherScript(ctx.home, client.id, ctx.dispatcher);
+    return {
+        clientId: action.clientId,
+        kind: action.kind,
+        status: worst.status,
+        path: worst.path,
+        backupPath: worst.backupPath,
+        reason: worst.reason,
+        remediation: worst.remediation,
+    };
+}
+/** One planned action → one applied result. */
+async function applyAction(action, client, ctx) {
+    if (action.kind === "skill") {
+        const status = await installSkill(join(ctx.home, ".agents", "skills"));
+        return { clientId: action.clientId, kind: "skill", status, path: action.path };
+    }
+    if (client.id === "hermes" && action.kind === "hooks") {
+        return applyHermesPlugin(client, ctx);
+    }
+    return applyConfigEntries(action, client, ctx);
+}
+async function recordDeferredHookRemovals(client, results) {
+    if (!client)
+        return;
+    for (const item of await removeDeferredHookGroups(client)) {
+        if (item.status === "removed") {
+            results.push({ clientId: client.id, kind: "hooks", status: "update", path: item.path });
+        }
+        else if (item.status === "failed") {
+            results.push({ clientId: client.id, kind: "hooks", status: "failed", path: item.path, reason: item.detail });
+        }
+    }
+}
+async function applyPlan(actions, ctx) {
+    const results = [];
+    const done = new Set(); // unique (kind,path) — skill is shared across clients
+    const clients = supportedClients({ home: ctx.home, platform: platform(), env: ctx.env });
+    for (const action of actions) {
+        const client = clients.find((c) => c.id === action.clientId);
+        if (action.kind === "skip") {
+            await recordDeferredHookRemovals(client, results);
+            results.push({ clientId: action.clientId, kind: "skip", status: "skipped", path: action.path, reason: action.reason });
+            continue;
+        }
+        const key = `${action.kind}:${action.path}`;
+        if (done.has(key))
+            continue;
+        done.add(key);
+        if (!client)
+            continue;
+        results.push(await applyAction(action, client, ctx));
+    }
+    return results;
+}
+function outJson(out, envelope) {
+    out(JSON.stringify(envelope));
+}
+// ---------------------------------------------------------------------------
+// doctor / uninstall / listener
+// ---------------------------------------------------------------------------
+/** Glyph for a doctor check line: pass, warn-only, or fail. */
+function checkGlyph(check) {
+    if (check.ok)
+        return "✓";
+    return check.warnOnly ? "·" : "✗";
+}
+async function cmdDoctor(ctx) {
+    const report = await runDoctor({ home: ctx.home, env: ctx.env, clients: ctx.clients.length > 0 ? ctx.clients : undefined, json: ctx.flags.json });
+    if (ctx.flags.json) {
+        ctx.out(JSON.stringify({ status: report.healthy ? "healthy" : "unhealthy", ...report }));
+        return report.healthy ? 0 : 1;
+    }
+    ctx.out(`  Heedvane doctor — ${report.scopedTo ? `scoped to ${report.scopedTo.join(", ")}` : "all checks"}`);
+    ctx.out("");
+    for (const check of report.checks) {
+        ctx.out(`  ${checkGlyph(check)} ${check.name}: ${check.detail}`);
+        if (check.remediation)
+            ctx.out(`      remediation: ${check.remediation}`);
+    }
+    ctx.out("");
+    ctx.out(`  ${report.healthy ? "All scoped checks pass." : "Some checks failed — see remediations above."}`);
+    return report.healthy ? 0 : 1;
+}
+/** Glyph for an uninstall item line: removed, failed, or skipped/absent. */
+function uninstallGlyph(status) {
+    if (status === "removed")
+        return "✓";
+    return status === "failed" ? "✗" : "·";
+}
+async function cmdUninstall(ctx) {
+    const items = await uninstall({ home: ctx.home, env: ctx.env, agents: ctx.agents.length > 0 ? ctx.agents : undefined, purgeConfig: ctx.purge });
+    for (const item of items) {
+        ctx.out(`  ${uninstallGlyph(item.status)} ${item.name}  ${item.path}${item.detail ? ` (${item.detail})` : ""}`);
+    }
+    ctx.out("");
+    ctx.out("  heed.yaml was left untouched (your file). Pass --purge-config to delete it too.");
+    return 0;
+}
+async function cmdListener(ctx) {
+    const sub = ctx.rest[0] ?? "";
+    if (sub !== "start") {
+        ctx.out("  usage: npx heedvane listener start");
+        ctx.out("  v1 runs the listener in the foreground; service install (launchd/systemd) is opt-in later.");
+        return sub === "" ? 2 : 1;
+    }
+    const started = await serveHooks(ctx.home, ctx.out);
+    ctx.out(`  ✓ listener on 127.0.0.1:${started.port}, ${started.replayed} spooled event(s) replayed (Ctrl-C to stop)`);
+    await new Promise((resolve) => {
+        process.on("SIGINT", () => {
+            started.server.close(() => resolve());
+        });
+    });
+    return 0;
+}
+/**
+ * `run -- <agent command>`: a listener for exactly one agent run, for CI, containers and software
+ * factories where nothing stays running. The agent keeps stdin, stdout and stderr; the listener writes to
+ * ~/.heed/listener.log and Heedvane's own lines go to stderr, so an agent's JSON output stays parseable.
+ * Returns the agent's exit code (128 + signal number when a signal ended it).
+ */
+async function cmdRun(ctx) {
+    const say = (line) => void process.stderr.write(`heedvane: ${line}\n`);
+    if (!ctx.separated || ctx.command.length === 0) {
+        say('usage: npx heedvane run -- <agent command>, e.g. npx heedvane run -- claude -p "fix the failing tests"');
+        return 2;
+    }
+    const root = join(ctx.home, ".heed");
+    mkdirSync(root, { recursive: true, mode: 0o700 }); // a fresh container has no ~/.heed yet
+    const log = createWriteStream(listenerLogPath(root), { flags: "a", mode: 0o600 });
+    const started = await serveHooks(ctx.home, (line) => void log.write(`${line}\n`));
+    if ((await backendAt(root, heedvaneConfigAt(root).url)) === null)
+        say("not signed in, so guardrails are off: printf '%s' \"$HEEDVANE_ORG_KEY\" | npx heedvane auth org");
+    say(`listening on 127.0.0.1:${started.port}; log: ${listenerLogPath(root)}`);
+    try {
+        // The agent's hooks find this listener's endpoint through HEED_AGENT_HOOK_ROOT, also when HEED_HOME is not $HOME.
+        return await runAgent(ctx.command, { ...ctx.env, HEED_HOME: ctx.home, HEED_AGENT_HOOK_ROOT: root }, say);
+    }
+    finally {
+        await new Promise((resolve) => started.server.close(() => resolve()));
+        await new Promise((resolve) => log.end(resolve));
+    }
+}
+/** Runs the agent with this process's terminal, passes Ctrl-C and `docker stop` on to it, and resolves with its exit code. */
+function runAgent([program, ...args], env, say) {
+    return new Promise((resolve) => {
+        const child = spawn(program, args, { stdio: "inherit", env });
+        const forward = (signal) => void child.kill(signal);
+        process.on("SIGINT", forward).on("SIGTERM", forward);
+        const settle = (code) => {
+            process.off("SIGINT", forward).off("SIGTERM", forward);
+            resolve(code);
+        };
+        child.on("error", (err) => {
+            say(`could not start ${program}: ${errorMessage(err)}`);
+            settle(127);
+        });
+        child.on("exit", (code, signal) => settle(code ?? 128 + (signal === null ? 0 : osConstants.signals[signal])));
+    });
+}
+function backendCommandContext(ctx) {
+    return { home: ctx.home, out: ctx.out, words: ctx.positional.slice(1), project: ctx.args.includes("--project"), readStdin: ctx.readStdin, openBrowser: ctx.openBrowser };
+}
+/** All of stdin as text (where `auth` reads its key). */
+/** Open `url` in the system browser; the URL is printed too, so a failure here only costs a click. */
+/**
+ * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
+ * cmd would cut the sign-in URL at its first `&`.
+ */
+export function browserOpener(platform, url) {
+    const openers = { darwin: ["open", [url]], win32: ["rundll32", ["url.dll,FileProtocolHandler", url]] };
+    return openers[platform] ?? ["xdg-open", [url]];
+}
+function openSystemBrowser(url) {
+    const [command, args] = browserOpener(process.platform, url);
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => undefined); // no browser opener: the printed URL is the way in
+    child.unref();
+}
+async function readProcessStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export { main };
+// Bin entry: when executed directly (npx / ./dist/cli.js), run the CLI.
+// When imported (tests, programmatic use), main is just exported.
+import { fileURLToPath } from "node:url";
+import { argv } from "node:process";
+const invokedDirectly = (() => {
+    try {
+        return argv[1] !== undefined && realpathSync(argv[1]) === fileURLToPath(import.meta.url);
+    }
+    catch {
+        return false;
+    }
+})();
+if (invokedDirectly) {
+    void main(argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}