@popoverinstall/cli 0.8.0 → 0.9.0

package/plugin/scripts/_ipc.mjs

@@ -1,146 +1,146 @@
-// Zero-dependency IPC helpers for the plugin's hook scripts.
-//
-// These deliberately duplicate a small amount of logic from @popoverinstall/shared. The plugin is
-// installed standalone from a marketplace, where there is no node_modules to import
-// from, and a hook that fails to resolve an import would break every tool call in the
-// session. Fifteen duplicated lines is the cheaper trade.
-//
-// Keep this file dependency-free and fast: a cold node spawn already costs ~50ms, and
-// PreToolUse runs on every tool call.
-
-import net from "node:net";
-import os from "node:os";
-import path from "node:path";
-import { appendFileSync, mkdirSync } from "node:fs";
-
-export function popoverHome() {
-  return process.env.POPOVER_HOME ?? path.join(os.homedir(), ".popover");
-}
-
-export function daemonAddress() {
-  if (process.env.POPOVER_DAEMON_ADDR) return process.env.POPOVER_DAEMON_ADDR;
-  if (process.platform === "win32") {
-    const user = process.env.USERNAME || process.env.USER || "default";
-    return `\\\\.\\pipe\\popover-${user.replace(/[^A-Za-z0-9_-]/g, "_")}`;
-  }
-  return path.join(popoverHome(), "daemon.sock");
-}
-
-/**
- * Send one message and do not wait for a reply.
- *
- * Used by the status hooks. Any failure falls back to the spool file, which the daemon
- * drains the next time it starts — so events survive the daemon being down.
- */
-export function sendFireAndForget(message, { timeoutMs = 400 } = {}) {
-  return new Promise((resolve) => {
-    let done = false;
-    const finish = (ok) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try {
-        socket.destroy();
-      } catch {}
-      if (!ok) spool(message);
-      resolve(ok);
-    };
-
-    const socket = net.createConnection(daemonAddress());
-    const timer = setTimeout(() => finish(false), timeoutMs);
-
-    socket.on("connect", () => {
-      socket.write(`${JSON.stringify(message)}\n`, () => finish(true));
-    });
-    socket.on("error", () => finish(false));
-  });
-}
-
-/** Send a request and wait for the matching reply. */
-export function request(message, { timeoutMs = 5000 } = {}) {
-  return new Promise((resolve) => {
-    let buffer = "";
-    let done = false;
-    const finish = (value) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try {
-        socket.destroy();
-      } catch {}
-      resolve(value);
-    };
-
-    const socket = net.createConnection(daemonAddress());
-    const timer = setTimeout(() => finish(null), timeoutMs);
-
-    socket.on("connect", () => socket.write(`${JSON.stringify(message)}\n`));
-    socket.on("data", (chunk) => {
-      buffer += chunk.toString();
-      let idx = buffer.indexOf("\n");
-      while (idx !== -1) {
-        const line = buffer.slice(0, idx).trim();
-        buffer = buffer.slice(idx + 1);
-        if (line) {
-          try {
-            return finish(JSON.parse(line));
-          } catch {
-            /* keep reading */
-          }
-        }
-        idx = buffer.indexOf("\n");
-      }
-    });
-    socket.on("error", () => finish(null));
-  });
-}
-
-function spool(message) {
-  try {
-    mkdirSync(popoverHome(), { recursive: true });
-    // Only status payloads are worth replaying; a stale roster request is meaningless.
-    if (message?.t !== "status") return;
-    appendFileSync(
-      path.join(popoverHome(), "spool.jsonl"),
-      `${JSON.stringify(message.payload)}\n`,
-      "utf8",
-    );
-  } catch {
-    /* never let a hook fail because of logging */
-  }
-}
-
-/** Read this hook's JSON payload from stdin. */
-export async function readStdin(timeoutMs = 2000) {
-  return new Promise((resolve) => {
-    let data = "";
-    const timer = setTimeout(() => resolve(data), timeoutMs);
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("data", (chunk) => {
-      data += chunk;
-    });
-    process.stdin.on("end", () => {
-      clearTimeout(timer);
-      resolve(data);
-    });
-    process.stdin.on("error", () => {
-      clearTimeout(timer);
-      resolve(data);
-    });
-  });
-}
-
-/**
- * The Claude session this process belongs to, or undefined outside one.
- *
- * Claude Code exports `CLAUDE_CODE_SESSION_ID`. This was previously read as
- * `CLAUDE_SESSION_ID`, which does not exist — so every ask recorded a null
- * `from_session_id` and the dashboard could never say which agent had asked. Verified
- * against a live session: the value is the same id the daemon publishes as
- * `cc_session_id`, so it joins directly to a roster entry.
- *
- * The older name is still consulted second, in case a future or older Claude Code uses it.
- */
-export function callerSessionId() {
-  return process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || undefined;
-}
+// Zero-dependency IPC helpers for the plugin's hook scripts.
+//
+// These deliberately duplicate a small amount of logic from @popoverinstall/shared. The plugin is
+// installed standalone from a marketplace, where there is no node_modules to import
+// from, and a hook that fails to resolve an import would break every tool call in the
+// session. Fifteen duplicated lines is the cheaper trade.
+//
+// Keep this file dependency-free and fast: a cold node spawn already costs ~50ms, and
+// PreToolUse runs on every tool call.
+
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { appendFileSync, mkdirSync } from "node:fs";
+
+export function popoverHome() {
+  return process.env.POPOVER_HOME ?? path.join(os.homedir(), ".popover");
+}
+
+export function daemonAddress() {
+  if (process.env.POPOVER_DAEMON_ADDR) return process.env.POPOVER_DAEMON_ADDR;
+  if (process.platform === "win32") {
+    const user = process.env.USERNAME || process.env.USER || "default";
+    return `\\\\.\\pipe\\popover-${user.replace(/[^A-Za-z0-9_-]/g, "_")}`;
+  }
+  return path.join(popoverHome(), "daemon.sock");
+}
+
+/**
+ * Send one message and do not wait for a reply.
+ *
+ * Used by the status hooks. Any failure falls back to the spool file, which the daemon
+ * drains the next time it starts — so events survive the daemon being down.
+ */
+export function sendFireAndForget(message, { timeoutMs = 400 } = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try {
+        socket.destroy();
+      } catch {}
+      if (!ok) spool(message);
+      resolve(ok);
+    };
+
+    const socket = net.createConnection(daemonAddress());
+    const timer = setTimeout(() => finish(false), timeoutMs);
+
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(message)}\n`, () => finish(true));
+    });
+    socket.on("error", () => finish(false));
+  });
+}
+
+/** Send a request and wait for the matching reply. */
+export function request(message, { timeoutMs = 5000 } = {}) {
+  return new Promise((resolve) => {
+    let buffer = "";
+    let done = false;
+    const finish = (value) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try {
+        socket.destroy();
+      } catch {}
+      resolve(value);
+    };
+
+    const socket = net.createConnection(daemonAddress());
+    const timer = setTimeout(() => finish(null), timeoutMs);
+
+    socket.on("connect", () => socket.write(`${JSON.stringify(message)}\n`));
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString();
+      let idx = buffer.indexOf("\n");
+      while (idx !== -1) {
+        const line = buffer.slice(0, idx).trim();
+        buffer = buffer.slice(idx + 1);
+        if (line) {
+          try {
+            return finish(JSON.parse(line));
+          } catch {
+            /* keep reading */
+          }
+        }
+        idx = buffer.indexOf("\n");
+      }
+    });
+    socket.on("error", () => finish(null));
+  });
+}
+
+function spool(message) {
+  try {
+    mkdirSync(popoverHome(), { recursive: true });
+    // Only status payloads are worth replaying; a stale roster request is meaningless.
+    if (message?.t !== "status") return;
+    appendFileSync(
+      path.join(popoverHome(), "spool.jsonl"),
+      `${JSON.stringify(message.payload)}\n`,
+      "utf8",
+    );
+  } catch {
+    /* never let a hook fail because of logging */
+  }
+}
+
+/** Read this hook's JSON payload from stdin. */
+export async function readStdin(timeoutMs = 2000) {
+  return new Promise((resolve) => {
+    let data = "";
+    const timer = setTimeout(() => resolve(data), timeoutMs);
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+    process.stdin.on("error", () => {
+      clearTimeout(timer);
+      resolve(data);
+    });
+  });
+}
+
+/**
+ * The Claude session this process belongs to, or undefined outside one.
+ *
+ * Claude Code exports `CLAUDE_CODE_SESSION_ID`. This was previously read as
+ * `CLAUDE_SESSION_ID`, which does not exist — so every ask recorded a null
+ * `from_session_id` and the dashboard could never say which agent had asked. Verified
+ * against a live session: the value is the same id the daemon publishes as
+ * `cc_session_id`, so it joins directly to a roster entry.
+ *
+ * The older name is still consulted second, in case a future or older Claude Code uses it.
+ */
+export function callerSessionId() {
+  return process.env.CLAUDE_CODE_SESSION_ID || process.env.CLAUDE_SESSION_ID || undefined;
+}

package/plugin/scripts/announce-roster.mjs

@@ -1,131 +1,141 @@
-#!/usr/bin/env node
-// Announces which teammate agents are here, once per change in the cast.
-//
-// The skill file tells an agent that popover exists. This tells it who is present *right
-// now* — the part doctrine cannot reliably produce. An agent acts on a fact sitting in its
-// context long before it remembers to go looking for one, and the case that pays for this
-// hook is the cheap one: it is about to edit a file a teammate's agent is already in, and
-// the roster line is what makes the overlap visible before the edit rather than at merge.
-//
-// Registered synchronously on UserPromptSubmit, because that is the one event whose stdout
-// is injected into the model's context. That makes this the second hook here allowed to
-// print — see the header of deliver-messages.mjs — and it inherits every constraint that
-// one documents: it runs before every prompt, so it must be fast and must fail open.
-//
-// It announces on change rather than on every prompt. A line repeated ahead of all fifty
-// prompts in a session stops being information and becomes wallpaper: the model habituates,
-// the user pays for it every turn, and the one turn where it mattered looks like the other
-// forty-nine. So the cast last announced is remembered on disk and nothing is printed until
-// it differs.
-
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { callerSessionId, popoverHome, request } from "./_ipc.mjs";
-
-// A fork answering a teammate's question must not be handed this. Its output goes back to
-// whoever asked, and the cast of the machine it happens to run on is not theirs.
-if (process.env.CLAUDE_CODE_ENTRYPOINT === "popover-fork") process.exit(0);
-
-const sessionId = callerSessionId();
-
-try {
-  // No stdin read at all. deliver-messages.mjs spends 150ms on the payload because a missed
-  // tell is a real loss; here the environment variable is enough, and 150ms would be a
-  // sixth of the whole budget.
-  if (!sessionId) process.exit(0);
-
-  // `refresh: false` is what makes the tight timeout survivable — this reads whatever the
-  // daemon already has, so it costs one socket round trip and no network. A hook sitting
-  // between a keystroke and the model must never be the thing that calls the cloud.
-  // `cwd` matters most here of anywhere: this fires on the first prompt of a session, which
-  // is exactly when the daemon may not yet have resolved that session's repo — and the line
-  // it prints claims the agents are "in this repo". Without the hint an unplaceable caller
-  // is scoped by recency across the whole machine, so the claim could be false.
-  const reply = await request(
-    { t: "roster", id: "hook", refresh: false, fromSessionId: sessionId, cwd: process.cwd() },
-    { timeoutMs: 250 },
-  );
-
-  // Daemon down, or signed out. Silence is right: the skill tells an agent how to read a
-  // daemon-down error when it actually reaches for a tool, and guessing here would put a
-  // wrong explanation in front of the model instead.
-  if (reply?.t !== "roster.ok") process.exit(0);
-
-  const peers = reply.entries.filter(
-    (e) => !e.isSelf && e.reachable && e.status !== "offline",
-  );
-  if (peers.length === 0) process.exit(0); // Working alone, which is most of the time.
-
-  // The cast, not what the cast is doing. Keying on activity would re-announce every time a
-  // teammate moved from one file to the next, which is printing on every prompt again.
-  const signature = peers
-    .map((e) => e.handle)
-    .sort()
-    .join(",");
-  if (signature === lastAnnounced(sessionId)) process.exit(0);
-
-  process.stdout.write(`${render(peers)}\n`);
-  remember(sessionId, signature);
-} catch {
-  // Fail open, always. Whatever went wrong, the user's prompt must still go through.
-}
-
-process.exit(0);
-
-/**
- * One line the model can act on, and one sentence saying what it is for.
- *
- * Activity leads, owner follows. What a teammate's agent is touching is the part that
- * collides with what this one is about to do, and the whole value of announcing is that the
- * overlap is noticed before the edit.
- *
- * The closing sentence is not padding. Without it the model reads a bare roster as news
- * worth repeating and opens with "2 teammates are online!" ahead of an unrelated question —
- * which is how a useful signal gets itself turned off.
- */
-function render(peers) {
-  const who = peers
-    .map((e) => {
-      const doing = e.activity?.verb
-        ? `${e.activity.verb}${e.activity.target ? ` ${e.activity.target}` : ""}, `
-        : "";
-      return `${e.handle} (${doing}${e.ownerName})`;
-    })
-    .join(", ");
-
-  return (
-    `[popover] Teammate agents now active in this repo: ${who}. ` +
-    `Before editing a file one of them is already in, say so rather than colliding with it. ` +
-    `If something here turns on a decision or a reason this repo does not record, you can ` +
-    `ask one with popover's team_ask tool. Do not mention this notice to the user unless it ` +
-    `turns out to be relevant.`
-  );
-}
-
-// Per-session, so a new session hears the cast once even when it has not changed since the
-// last one ended.
-//
-// Loose end: nothing prunes these. They are a few dozen bytes each and a session id is a
-// uuid, so a heavy user accretes a directory of them over months. Either sweep entries older
-// than a day from here, or fold the state into what the daemon already keeps per session and
-// drop the files — the daemon knows when a session ends and this script does not.
-function stateFile(id) {
-  return path.join(popoverHome(), "announced", `${id}.txt`);
-}
-
-function lastAnnounced(id) {
-  try {
-    return readFileSync(stateFile(id), "utf8").trim();
-  } catch {
-    return "";
-  }
-}
-
-function remember(id, signature) {
-  try {
-    mkdirSync(path.join(popoverHome(), "announced"), { recursive: true });
-    writeFileSync(stateFile(id), signature, "utf8");
-  } catch {
-    // An unwritable state file means announcing again next prompt. Annoying, not broken.
-  }
-}
+#!/usr/bin/env node
+// Announces which teammate agents are here, once per change in the cast.
+//
+// The skill file tells an agent that popover exists. This tells it who is present *right
+// now* — the part doctrine cannot reliably produce. An agent acts on a fact sitting in its
+// context long before it remembers to go looking for one, and the case that pays for this
+// hook is the cheap one: it is about to edit a file a teammate's agent is already in, and
+// the roster line is what makes the overlap visible before the edit rather than at merge.
+//
+// Registered synchronously on UserPromptSubmit, because that is the one event whose stdout
+// is injected into the model's context. That makes this the second hook here allowed to
+// print — see the header of deliver-messages.mjs — and it inherits every constraint that
+// one documents: it runs before every prompt, so it must be fast and must fail open.
+//
+// It announces on change rather than on every prompt. A line repeated ahead of all fifty
+// prompts in a session stops being information and becomes wallpaper: the model habituates,
+// the user pays for it every turn, and the one turn where it mattered looks like the other
+// forty-nine. So the cast last announced is remembered on disk and nothing is printed until
+// it differs.
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { callerSessionId, popoverHome, request } from "./_ipc.mjs";
+
+// A fork answering a teammate's question must not be handed this. Its output goes back to
+// whoever asked, and the cast of the machine it happens to run on is not theirs.
+if (process.env.CLAUDE_CODE_ENTRYPOINT === "popover-fork") process.exit(0);
+
+const sessionId = callerSessionId();
+
+try {
+  // No stdin read at all. deliver-messages.mjs spends 150ms on the payload because a missed
+  // tell is a real loss; here the environment variable is enough, and 150ms of latency the
+  // user pays on every prompt buys nothing this cannot get for free.
+  if (!sessionId) process.exit(0);
+
+  // `refresh: false` means "do not force a refresh". It does NOT mean "do not use the
+  // network", which is what a comment here used to claim: the daemon caches a roster for 5s,
+  // and past that this call awaits a cloud fetch measuring ~355ms. Since a human types
+  // prompts minutes apart, nearly every one of these went to the cloud — so the 250ms budget
+  // this used to carry lost the race almost every time, failed open, and printed nothing. A
+  // hook that silently does not fire is indistinguishable from having no teammates, which is
+  // why it went unnoticed for a release.
+  //
+  // 2000ms is a ceiling on how long a *degraded* backend may hold up a prompt, not a target:
+  // the happy path is 2ms cached or ~355ms fetched. It must stay in step with
+  // ROSTER_HOOK_TIMEOUT_MS in @popoverinstall/shared, which this dependency-free script
+  // cannot import — packages/shared/test/roster-cache.test.ts fails if they drift.
+  //
+  // `cwd` matters most here of anywhere: this fires on the first prompt of a session, which
+  // is exactly when the daemon may not yet have resolved that session's repo — and the line
+  // it prints claims the agents are "in this repo". Without the hint an unplaceable caller
+  // is scoped by recency across the whole machine, so the claim could be false.
+  const reply = await request(
+    { t: "roster", id: "hook", refresh: false, fromSessionId: sessionId, cwd: process.cwd() },
+    { timeoutMs: 2000 },
+  );
+
+  // Daemon down, or signed out. Silence is right: the skill tells an agent how to read a
+  // daemon-down error when it actually reaches for a tool, and guessing here would put a
+  // wrong explanation in front of the model instead.
+  if (reply?.t !== "roster.ok") process.exit(0);
+
+  const peers = reply.entries.filter(
+    (e) => !e.isSelf && e.reachable && e.status !== "offline",
+  );
+  if (peers.length === 0) process.exit(0); // Working alone, which is most of the time.
+
+  // The cast, not what the cast is doing. Keying on activity would re-announce every time a
+  // teammate moved from one file to the next, which is printing on every prompt again.
+  const signature = peers
+    .map((e) => e.handle)
+    .sort()
+    .join(",");
+  if (signature === lastAnnounced(sessionId)) process.exit(0);
+
+  process.stdout.write(`${render(peers)}\n`);
+  remember(sessionId, signature);
+} catch {
+  // Fail open, always. Whatever went wrong, the user's prompt must still go through.
+}
+
+process.exit(0);
+
+/**
+ * One line the model can act on, and one sentence saying what it is for.
+ *
+ * Activity leads, owner follows. What a teammate's agent is touching is the part that
+ * collides with what this one is about to do, and the whole value of announcing is that the
+ * overlap is noticed before the edit.
+ *
+ * The closing sentence is not padding. Without it the model reads a bare roster as news
+ * worth repeating and opens with "2 teammates are online!" ahead of an unrelated question —
+ * which is how a useful signal gets itself turned off.
+ */
+function render(peers) {
+  const who = peers
+    .map((e) => {
+      const doing = e.activity?.verb
+        ? `${e.activity.verb}${e.activity.target ? ` ${e.activity.target}` : ""}, `
+        : "";
+      return `${e.handle} (${doing}${e.ownerName})`;
+    })
+    .join(", ");
+
+  return (
+    `[popover] Teammate agents now active in this repo: ${who}. ` +
+    `Before editing a file one of them is already in, say so rather than colliding with it. ` +
+    `If something here turns on a decision or a reason this repo does not record, you can ` +
+    `ask one with popover's team_ask tool. Do not mention this notice to the user unless it ` +
+    `turns out to be relevant.`
+  );
+}
+
+// Per-session, so a new session hears the cast once even when it has not changed since the
+// last one ended.
+//
+// Loose end: nothing prunes these. They are a few dozen bytes each and a session id is a
+// uuid, so a heavy user accretes a directory of them over months. Either sweep entries older
+// than a day from here, or fold the state into what the daemon already keeps per session and
+// drop the files — the daemon knows when a session ends and this script does not.
+function stateFile(id) {
+  return path.join(popoverHome(), "announced", `${id}.txt`);
+}
+
+function lastAnnounced(id) {
+  try {
+    return readFileSync(stateFile(id), "utf8").trim();
+  } catch {
+    return "";
+  }
+}
+
+function remember(id, signature) {
+  try {
+    mkdirSync(path.join(popoverHome(), "announced"), { recursive: true });
+    writeFileSync(stateFile(id), signature, "utf8");
+  } catch {
+    // An unwritable state file means announcing again next prompt. Annoying, not broken.
+  }
+}