@popoverinstall/cli 0.4.0

package/dist/setup.js

@@ -0,0 +1,113 @@
+import { execFile } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { daemonEntryPointerPath, popoverHome } from "@popoverinstall/shared";
+import { resolveDaemonEntry } from "./daemon-entry.js";
+import { MIN_CLAUDE_VERSION, claudeVersion, versionAtLeast } from "./doctor.js";
+import { bad, dim, info, ok } from "./ui.js";
+const execFileAsync = promisify(execFile);
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Connect this npm install to Claude Code.
+ *
+ * `npm install -g` can place files, but it cannot register a Claude Code plugin or tell the
+ * plugin's hooks where the daemon ended up. Those are the two things this does, and they
+ * are why installing is two commands rather than one. A `postinstall` script would hide it,
+ * but `--ignore-scripts` is common, corporate registries strip scripts, and writing to
+ * `~/.claude` from an install hook is not something a package should do unannounced.
+ *
+ * Safe to re-run: every step is idempotent, and `update` re-runs it on every upgrade.
+ */
+export async function setup({ force = false } = {}) {
+    const version = await claudeVersion();
+    if (!version) {
+        bad("claude CLI not found on PATH.");
+        dim("Install Claude Code first, or set POPOVER_CLAUDE_BIN to point at it.");
+        return 1;
+    }
+    if (!versionAtLeast(version, MIN_CLAUDE_VERSION)) {
+        bad(`claude ${version} is too old (need ${MIN_CLAUDE_VERSION.join(".")}+).`);
+        dim("Earlier versions lack `claude agents --json` and the fork flags popover relies on.");
+        return 1;
+    }
+    const marketplace = resolveMarketplaceRoot();
+    if (!marketplace) {
+        bad("Could not find the bundled Claude Code plugin.");
+        dim("This install looks incomplete — reinstall with: npm install -g @popoverinstall/cli");
+        return 1;
+    }
+    if (!force && (await pluginRegistered())) {
+        ok("Claude Code plugin already registered.");
+        return writePointer();
+    }
+    // Remove before add so a re-run replaces a stale registration rather than failing on a
+    // name that already exists. Both are best-effort: a first run has nothing to remove.
+    info("Registering the Claude Code plugin…");
+    await claude(["plugin", "marketplace", "remove", "popover"]).catch(() => { });
+    try {
+        await claude(["plugin", "marketplace", "add", marketplace]);
+        await claude(["plugin", "install", "popover@popoverinstall", "--scope", "user", "-y"]);
+    }
+    catch (err) {
+        bad(`Could not register the plugin: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    ok("Claude Code plugin registered.");
+    return writePointer();
+}
+/**
+ * Record where the daemon lives, for the plugin's SessionStart hook.
+ *
+ * Claude Code installs a plugin by *copying* it into its own cache, so nothing the hook can
+ * compute from its own location points back at the npm tree. This file is the only link
+ * between the two, and a missing one means sessions silently never publish — so failing to
+ * write it is a hard failure, not a warning.
+ */
+function writePointer() {
+    const entry = resolveDaemonEntry();
+    if (!entry) {
+        bad("Could not find the daemon build.");
+        dim("Reinstall with: npm install -g @popoverinstall/cli");
+        return 1;
+    }
+    mkdirSync(popoverHome(), { recursive: true });
+    writeFileSync(daemonEntryPointerPath(), `${entry}\n`);
+    ok(`daemon → ${entry}`);
+    dim("Run `popover login` to connect this machine, then `/team` inside Claude Code.");
+    return 0;
+}
+/**
+ * The directory holding `.claude-plugin/marketplace.json`.
+ *
+ * Published, that is this package's own root: `scripts/stage-plugin.mjs` copies the plugin
+ * to `<pkg>/plugin` and writes the manifest beside it at pack time. In a dev checkout
+ * neither exists, so fall back to the repo root, whose manifest sources `./packages/plugin`
+ * directly.
+ */
+function resolveMarketplaceRoot() {
+    const candidates = [
+        path.join(HERE, ".."), // <pkg>/ — published layout
+        path.join(HERE, "..", "..", ".."), // repo root — dev checkout
+    ];
+    return candidates.find((d) => existsSync(path.join(d, ".claude-plugin", "marketplace.json"))) ?? null;
+}
+async function pluginRegistered() {
+    try {
+        const { stdout } = await claude(["plugin", "list"]);
+        return /\bpopover\b/.test(stdout);
+    }
+    catch {
+        return false;
+    }
+}
+function claude(args) {
+    const bin = process.env.POPOVER_CLAUDE_BIN ?? "claude";
+    return execFileAsync(bin, args, {
+        timeout: 60_000,
+        windowsHide: true,
+        shell: process.platform === "win32",
+    });
+}
+//# sourceMappingURL=setup.js.map

package/dist/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../src/setup.ts"],"names":[],"mappings":"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"}

package/dist/ui.d.ts

@@ -0,0 +1,16 @@
+export declare const c: {
+    green: (s: string) => string;
+    red: (s: string) => string;
+    yellow: (s: string) => string;
+    dim: (s: string) => string;
+    bold: (s: string) => string;
+    cyan: (s: string) => string;
+};
+export declare const ok: (s: string) => void;
+export declare const bad: (s: string) => void;
+export declare const warn: (s: string) => void;
+export declare const info: (s: string) => void;
+export declare const dim: (s: string) => void;
+/** Open a URL in the user's browser. Best effort — we always print it too. */
+export declare function openBrowser(url: string): Promise<void>;
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,CAAC;eAFqB,MAAM;aAAN,MAAM;gBAAN,MAAM;aAAN,MAAM;cAAN,MAAM;cAAN,MAAM;CASxC,CAAC;AAEF,eAAO,MAAM,EAAE,GAAI,GAAG,MAAM,SAAwC,CAAC;AACrE,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,SAAsC,CAAC;AACpE,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,SAAyC,CAAC;AACxE,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,SAA0B,CAAC;AACzD,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,SAAiC,CAAC;AAE/D,8EAA8E;AAC9E,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB5D"}

package/dist/ui.js

@@ -0,0 +1,39 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const c = {
+    green: wrap("32"),
+    red: wrap("31"),
+    yellow: wrap("33"),
+    dim: wrap("2"),
+    bold: wrap("1"),
+    cyan: wrap("36"),
+};
+export const ok = (s) => console.log(`${c.green("✓")} ${s}`);
+export const bad = (s) => console.log(`${c.red("✗")} ${s}`);
+export const warn = (s) => console.log(`${c.yellow("!")} ${s}`);
+export const info = (s) => console.log(`  ${s}`);
+export const dim = (s) => console.log(c.dim(`  ${s}`));
+/** Open a URL in the user's browser. Best effort — we always print it too. */
+export async function openBrowser(url) {
+    const { spawn } = await import("node:child_process");
+    const [command, args] = process.platform === "win32"
+        ? // `start` is a cmd builtin; the empty string is the window title, which cmd
+            // otherwise steals from a quoted URL.
+            ["cmd.exe", ["/c", "start", "", url]]
+        : process.platform === "darwin"
+            ? ["open", [url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(command, [...args], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* the printed URL is the fallback */
+    }
+}
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;AAE/D,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE1F,MAAM,CAAC,MAAM,CAAC,GAAG;IACf,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;IACjB,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC;IACf,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC;IAClB,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC;IACd,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;IACf,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;CACjB,CAAC;AAEF,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACrE,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACpE,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACxE,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AACzD,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;AAE/D,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,GAAW;IAC3C,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACrD,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,GACnB,OAAO,CAAC,QAAQ,KAAK,OAAO;QAC1B,CAAC,CAAC,4EAA4E;YAC5E,sCAAsC;YACrC,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,GAAG,CAAC,CAAW;QAClD,CAAC,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ;YAC7B,CAAC,CAAE,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAW;YAC5B,CAAC,CAAE,CAAC,UAAU,EAAE,CAAC,GAAG,CAAC,CAAW,CAAC;IAEvC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE;YACtC,QAAQ,EAAE,IAAI;YACd,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC5B,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;IACvC,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@popoverinstall/cli",
+  "version": "0.4.0",
+  "description": "See your teammates' active Claude Code agents and ask them questions.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agents",
+    "team",
+    "collaboration",
+    "cli"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/many-ideations/popover",
+  "bugs": "https://github.com/many-ideations/popover/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/many-ideations/popover.git",
+    "directory": "packages/cli"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "bin": {
+    "popover": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "plugin",
+    ".claude-plugin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "prepack": "node ../../scripts/stage-plugin.mjs && tsc -b"
+  },
+  "dependencies": {
+    "@popoverinstall/daemon": "0.4.0",
+    "@popoverinstall/shared": "0.4.0"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
+  "name": "popover",
+  "displayName": "Popover",
+  "description": "See your teammates' active Claude Code agents and ask them questions. A read-only fork answers from the agent's full context without interrupting your teammate.",
+  "version": "0.4.0",
+  "author": {
+    "name": "Quolabs"
+  },
+  "homepage": "https://github.com/many-ideations/popover",
+  "repository": "https://github.com/many-ideations/popover",
+  "license": "MIT",
+  "keywords": [
+    "team",
+    "collaboration",
+    "agents",
+    "mcp"
+  ]
+}

package/plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "popover": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/index.mjs"],
+      "timeout": 120000
+    }
+  }
+}

package/plugin/README.md

@@ -0,0 +1,58 @@
+# popover plugin
+
+Installed into Claude Code; see the repo root README for the whole system.
+
+```
+.claude-plugin/plugin.json   metadata only
+commands/team.md             the /team command
+hooks/hooks.json             status feed (auto-discovered)
+.mcp.json                    bundled MCP server (auto-discovered)
+mcp/index.mjs                team_list + team_ask, zero dependencies
+scripts/                     hook handlers, zero dependencies
+```
+
+## Three things that will bite you
+
+**Do not declare `hooks` or `mcpServers` in `plugin.json`.** Both `hooks/hooks.json` and
+`.mcp.json` at the plugin root are auto-discovered. Naming them in the manifest loads them
+twice and the plugin refuses to start with `Duplicate hooks file detected`. This is why no
+first-party plugin declares them either. `claude plugin validate --strict` does **not**
+catch it — only a real install does.
+
+**Quote any frontmatter value starting with `[`.** `argument-hint: [a] [b]` is invalid
+YAML, and the failure is silent: every frontmatter field is dropped, including
+`allowed-tools`. `claude plugin validate` does catch this one.
+
+**Installing copies the plugin into `~/.claude/plugins/cache/<mkt>/<plugin>/<version>/`.**
+It runs from there, severed from the tree it was built in, so *every path relative to a
+script in this directory resolves inside that cache directory*. This is why
+`resolveDaemonEntry()` in `scripts/ensure-daemon.mjs` tries `~/.popover/runtime` first: the
+relative candidates below it only ever match in a monorepo checkout, and on a real install
+they all miss. A daemon reachable only by relative path is a daemon that never starts, and
+the symptom is remote — `/popover:team` reporting an empty roster, with nothing in any log.
+It also means edits here do nothing until you reinstall.
+
+## Why the scripts have no dependencies
+
+The plugin is installed from a marketplace into a cache directory where dependency
+installation is conditional and can fail. A hook that cannot resolve an import would break
+every tool call in the session, and an MCP server that cannot start would take `/team`
+with it. So `scripts/*.mjs` and `mcp/index.mjs` import nothing outside Node's stdlib and
+duplicate ~15 lines of `@popoverinstall/shared` on purpose.
+
+## Local development
+
+```bash
+npm run build                                   # from the repo root
+claude plugin marketplace add "$(pwd)"          # absolute; a bare `.` is rejected
+claude plugin install popover@popoverinstall -y
+claude plugin uninstall popover                   # to undo
+```
+
+Teammates do not do this — they run the installer (`curl -fsSL <host>/install | sh`),
+which is the only path that also delivers the daemon. See the repo root README.
+
+The hook scripts *talk to* the daemon over `POPOVER_DAEMON_ADDR`, falling back to
+`\\.\pipe\popover-<user>` on Windows and `~/.popover/daemon.sock` elsewhere. They *launch* it
+from `POPOVER_DAEMON_ENTRY` or `~/.popover/runtime/daemon/dist/index.js` — see the third
+gotcha above.

package/plugin/commands/team.md

@@ -0,0 +1,63 @@
+---
+description: See your team's active Claude Code agents in this repo and ask one of them a question
+# Quoted because an unquoted value starting with `[` is parsed as a YAML flow sequence,
+# which fails and silently drops EVERY field here, allowed-tools included.
+argument-hint: "[agent-handle] [question]"
+allowed-tools: mcp__plugin_popover_popover__team_list, mcp__plugin_popover_popover__team_ask, AskUserQuestion
+---
+
+# Team agents
+
+The user ran `/popover:team`. Arguments, which may be empty: **$ARGUMENTS**
+
+Only agents working in **this repo** are visible. A teammate running Claude Code in a
+different repository is neither listed nor askable, so an empty roster means nobody else is
+working *here* — not that the team is idle. Say it that way if it comes up.
+
+Follow exactly one of these three paths.
+
+## 1. No arguments — show the roster
+
+Call `mcp__plugin_popover_popover__team_list`, then print what it returns **verbatim** in a
+fenced block. Do not reformat it, re-sort it, or add agents that are not in it.
+
+Then add one short line telling the user they can ask any of these agents a question, e.g.
+`/popover:team B1 why did you rule out redis?`
+
+Stop there. Do not ask a question on the user's behalf.
+
+## 2. A handle and a question — ask it
+
+If the arguments name an agent (a handle like `B1`, a person's name, or a repo) followed
+by a question, call `mcp__plugin_popover_popover__team_ask` with:
+
+- `target`: the handle or name they used, exactly as typed
+- `question`: the rest of their message, as a self-contained question — the answering
+  agent has none of this conversation's context, so expand pronouns and vague references
+  ("that bug" → "the token refresh bug in the auth service")
+
+When the answer comes back, show it clearly attributed:
+
+> **B1** (Bob Chen, api-server): …answer…
+
+Then say how it bears on what you are working on, if it does. If the tool returns an
+error, relay it plainly — do not retry a different agent unless the user asks.
+
+## 3. A question with no clear target — pick one
+
+Call `mcp__plugin_popover_popover__team_list` first. Then:
+
+- If exactly one agent plausibly fits, ask it and say which one you chose and why.
+- If several fit, call `AskUserQuestion` with up to 4 of them as options (label = the
+  handle, description = owner, repo, and what it is doing). Then ask the chosen one.
+- If none fit, say so and show the roster instead.
+
+## Rules
+
+- Never invent a handle. Only use ones `team_list` returned. A handle from earlier in this
+  conversation may since have gone out of scope; if `team_ask` says it does not match,
+  relay that rather than guessing at another agent.
+- Asking costs the *teammate* money and runs on *their* machine. One question per
+  request; do not fan out to several agents unless explicitly asked.
+- The answer comes from a read-only copy of their session. Their live session is not
+  interrupted and cannot be modified by this.

package/plugin/hooks/hooks.json

@@ -0,0 +1,99 @@
+{
+  "description": "Publishes this machine's Claude Code session activity to the popover daemon.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-daemon.mjs"],
+            "async": true,
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "agent_needs_input",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/emit-event.mjs"],
+            "async": true,
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}