heedvane 0.2.0 → 0.2.1

package/README.md

@@ -49,7 +49,7 @@ own lines go to stderr and `~/.heed/listener.log`.
 
 - Claude Code runs the hooks in print mode (`claude -p`), but not with `--bare`.
 - Codex runs hooks only after they are trusted.
-- Pi and Flue agents cannot be connected yet.
+- The installer does not set up Pi or Flue. Connect them with a hook of your own that sends each action to `POST /api/agent/steering` with the organization key; Heedvane answers whether to refuse it.
 
 ## Everyday commands
 

package/dist/cli.js

@@ -98,17 +98,63 @@ function parseInvocation(args) {
         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"]),
+        positional: positionalArgs(args, VALUE_FLAGS),
     };
 }
+/** Flags without a value. */
+const SWITCH_FLAGS = ["--dry-run", "--yes", "--json", "--purge-config", "--project", "--help", "-h"];
+/** Flags followed by a value. */
+const VALUE_FLAGS = ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--token"];
+/** Heedvane's own arguments: everything before `--`, after which `run` passes the rest to the agent. */
+function ownArgs(args) {
+    const separator = args.indexOf("--");
+    return separator < 0 ? args : args.slice(0, separator);
+}
+/** The first argument that looks like a flag but is not one of ours (values of value flags skipped). */
+function unknownFlag(args) {
+    for (let i = 0; i < args.length; i++) {
+        if (VALUE_FLAGS.includes(args[i]))
+            i += 1;
+        else if (args[i].startsWith("-") && !SWITCH_FLAGS.includes(args[i]))
+            return args[i];
+    }
+    return undefined;
+}
+/** One command's usage line from USAGE plus the flags, or the whole USAGE for no or an unknown command. */
+function helpFor(command) {
+    const lines = USAGE.split("\n");
+    const own = command === undefined ? [] : lines.filter((line) => line.trim().startsWith(`${command} `));
+    if (own.length === 0)
+        return USAGE;
+    const flags = lines.slice(lines.findIndex((line) => line.trim().startsWith("Flags:")));
+    return [`  Usage: npx heedvane ${command} [flags]`, "", ...own, "", ...flags].join("\n");
+}
+/** The command help is asked about: `help <command>`, `<command> --help`, or none for `-h` alone. */
+function helpTopic([first, second]) {
+    if (first === "help")
+        return second;
+    return first === "-h" ? undefined : first;
+}
 async function main(argv, opts = {}) {
     const ctx = commandContext(argv, opts);
     const command = ctx.positional[0];
+    const own = ownArgs(ctx.args);
+    // Help never runs anything: `uninstall --help` must not uninstall.
+    if (command === "help" || own.includes("--help") || own.includes("-h")) {
+        ctx.out(helpFor(helpTopic(ctx.positional)));
+        return 0;
+    }
+    const unknown = unknownFlag(own);
+    if (unknown !== undefined) {
+        ctx.out(`  ✗ unknown flag: ${unknown} (nothing was changed)`);
+        ctx.out(helpFor(command));
+        return 2;
+    }
     if (command === undefined && takesInstaller(ctx))
         return cmdInstall(ctx);
-    if (!command || command === "help" || command === "--help") {
+    if (!command) {
         ctx.out(USAGE);
-        return command ? 0 : 2;
+        return 2;
     }
     return routeCommand(command, ctx);
 }
@@ -351,9 +397,9 @@ async function cmdSetup(ctx) {
     }
     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. */
+/** A person at a terminal who did not ask for the one-shot path (`--yes`, `--dry-run`, `--json`). */
 function takesInstaller(ctx) {
-    return ctx.interactive && !ctx.flags.yes && !ctx.flags.dryRun && !ctx.flags.json && !ctx.args.includes("--help");
+    return ctx.interactive && !ctx.flags.yes && !ctx.flags.dryRun && !ctx.flags.json;
 }
 /** heed.yaml's text, or the template when there is none yet. */
 function heedText(home, existed) {
@@ -569,10 +615,10 @@ async function cmdListener(ctx) {
     }
     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)`);
+    // Ends on Ctrl-C, or when uninstall asks it to stop (POST /shutdown).
     await new Promise((resolve) => {
-        process.on("SIGINT", () => {
-            started.server.close(() => resolve());
-        });
+        started.server.on("close", resolve);
+        process.on("SIGINT", () => started.server.close());
     });
     return 0;
 }

package/dist/listener/server.d.ts

@@ -39,6 +39,8 @@ export interface StartedListener {
  * length-leaking early return would defeat the point).
  */
 export declare function safeTokenEqual(a: string, b: string): boolean;
+/** `POST /shutdown` with the token: uninstall stops the listener it no longer has hooks for. */
+export declare const SHUTDOWN_ROUTE = "/shutdown";
 /**
  * Start the loopback hook listener: binds 127.0.0.1 only (never 0.0.0.0),
  * serves POST /hook/<agentId>, auths via x-heed-agent-hook-token against

package/dist/listener/server.js

@@ -71,6 +71,20 @@ function sendJson(res, status, body) {
     res.end(JSON.stringify(body));
 }
 const ROUTE_PATTERN = /^\/hook\/([A-Za-z0-9_-]+)$/;
+/** `POST /shutdown` with the token: uninstall stops the listener it no longer has hooks for. */
+export const SHUTDOWN_ROUTE = "/shutdown";
+/** True after answering a token-carrying `POST /shutdown`; the listener closes once the answer is sent. */
+function handledShutdown(req, res, deps) {
+    if (req.method !== "POST" || new URL(req.url ?? "/", "http://127.0.0.1").pathname !== SHUTDOWN_ROUTE)
+        return false;
+    if (!hasValidToken(req, deps.token)) {
+        sendJson(res, 401, { error: "invalid or missing x-heed-agent-hook-token" });
+        return true;
+    }
+    res.on("finish", deps.stop);
+    sendJson(res, 200, { stopping: true });
+    return true;
+}
 /** The route's agent id, or null after answering 404/405. */
 function routeAgent(req, res, agents) {
     const route = ROUTE_PATTERN.exec(new URL(req.url ?? "/", "http://127.0.0.1").pathname);
@@ -150,6 +164,8 @@ function internalErrorResponder(res) {
     };
 }
 async function handleRequest(req, res, deps) {
+    if (handledShutdown(req, res, deps))
+        return;
     const agent = routeAgent(req, res, deps.agents);
     if (agent === null)
         return;
@@ -194,16 +210,20 @@ export async function startListener(options) {
     }
     const log = options.log ?? ((message) => console.log(message));
     const agents = options.knownAgents ?? KNOWN_AGENTS;
+    const server = createServer((req, res) => {
+        handleRequest(req, res, deps).catch(internalErrorResponder(res));
+    });
     const deps = {
         agents,
         token: endpoint.token,
         onEvent: options.onEvent,
         log,
         warned: new Set(),
+        stop: () => {
+            server.close();
+            server.closeAllConnections();
+        },
     };
-    const server = createServer((req, res) => {
-        handleRequest(req, res, deps).catch(internalErrorResponder(res));
-    });
     // Node-level slowloris hardening (covers stalls before the request handler
     // fires); requestTimeout must be larger than headersTimeout.
     server.requestTimeout = REQUEST_TIMEOUT_MS;

package/dist/uninstall.js

@@ -16,6 +16,9 @@ import { hooksTarget, isClientDetected } from "./plan.js";
 import { skillInstallDir } from "./skill/bundle.js";
 import { statePath } from "./state.js";
 import { unlinkOptional } from "./best-effort.js";
+import { pingListener, readEndpoint } from "./listener/endpoint.js";
+import { SHUTDOWN_ROUTE } from "./listener/server.js";
+import { setTimeout as delay } from "node:timers/promises";
 /** Hook events carrying one of our groups, with the user's own groups that must survive. */
 function ourHookEvents(doc) {
     const hooks = doc["hooks"];
@@ -150,10 +153,34 @@ async function removeSharedFiles(home, scoped) {
     await rm(skillDir, { recursive: true, force: true });
     await unlinkOptional(statePath(join(home, ".heed")));
     return [
+        await stopListener(join(home, ".heed")),
         { clientId: "*", name: "skill bundle", path: skillDir, status: "removed" },
         { clientId: "*", name: "state.json", path: statePath(join(home, ".heed")), status: "removed" },
     ];
 }
+/** How long uninstall waits for the listener to stop answering after asking it to stop. */
+const STOP_WAIT_MS = 3_000;
+const STOP_POLL_MS = 100;
+/** The background listener answers hooks that are gone now: ask it to stop (POST /shutdown) and wait until it has. */
+async function stopListener(root) {
+    const endpoint = await readEndpoint(root).catch(() => null);
+    const item = { clientId: "*", name: "listener", path: `127.0.0.1:${endpoint?.port ?? 0}` };
+    if (endpoint === null || !(await pingListener(endpoint)))
+        return { ...item, status: "absent" };
+    const asked = await fetch(`http://127.0.0.1:${endpoint.port}${SHUTDOWN_ROUTE}`, {
+        method: "POST",
+        headers: { "x-heed-agent-hook-token": endpoint.token },
+        signal: AbortSignal.timeout(STOP_WAIT_MS),
+    }).catch(() => null);
+    for (let waited = 0; waited < STOP_WAIT_MS; waited += STOP_POLL_MS) {
+        if (!(await pingListener(endpoint)))
+            return { ...item, status: "removed" };
+        await delay(STOP_POLL_MS);
+    }
+    // A listener from 0.2.0 or earlier has no stop route (404); it ends at logout or restart.
+    const detail = asked?.status === 404 ? "an older listener is still running; it stops at logout or restart" : "the listener did not stop; it stops at logout or restart";
+    return { ...item, status: "failed", detail };
+}
 function existsMarker(client) {
     return isClientDetected(client);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heedvane",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Heedvane for coding agents: one command installs steering, guardrails, team memory and skill checks into Claude Code, Codex, Cursor, Gemini CLI and more.",
   "private": false,
   "type": "module",