petbox-wire 0.1.0-ci.543

package/src/wire.ts

@@ -0,0 +1,639 @@
+// Bootstrap CLI for the global agent-wiring kit — shipped as the `petbox-wire` npm package
+// (`npx petbox-wire <dir> <projectKey> …`), so a project can be wired without cloning the repo.
+//
+//   npx petbox-wire <dir> <projectKey> [--env VAR] [--key KEY] [--workspace WS] [--cleanup-legacy]
+//   (dev, from a checkout: node <pkg>/src/wire.ts <dir> <projectKey> …)
+//
+// Idempotently wires a project to PetBox:
+//    1. derive the env-var name for the API key
+//    2. obtain the key (--key, else env var / ~/.petbox/keys.json)  — minting keys is OUT OF SCOPE
+//    3. validate the key against /api/auth/validate
+//    4. persist the key everywhere agents look: ~/.petbox/keys.json (kit hooks) + user-scope
+//       env on Windows / ~/.petbox/env.sh sourced from login profiles on POSIX (the per-project
+//       MCP configs reference ${ENV_VAR}, so a real environment variable must exist)
+//    5. copy the kit to a stable location (~/.petbox/wire/) so global hooks survive npx eviction
+//    6. upsert the registry entry (prefix → project, envVar)
+//    7. (re)generate per-project config files:
+//        - .mcp.json                         (Claude Code MCP)
+//        - .opencode/opencode.json           (opencode MCP)
+//        - .factory/mcp.json                 (Factory Droid MCP — idempotent merge)
+//        - .claude/skills/petbox/SKILL.md    (Claude Code skill; opencode reads it via its
+//                                             Claude-compatible skills discovery path)
+//        - .factory/skills/petbox/SKILL.md   (Factory Droid skill)
+//    8. install the global Claude + Droid hooks + opencode plugin (merge, never clobber live files);
+//       all links point at the stable copy (~/.petbox/wire/)
+//    9. (--cleanup-legacy) remove the project's old per-project hook/plugin copies
+//   10. self-smoke: POST a tiny session and assert the server applied it
+//
+// Unlike the hooks, this is a CLI: step failures surface loudly (no silent swallow).
+
+import { execFileSync } from "node:child_process";
+import { appendFileSync, chmodSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_BASE_URL = "https://petbox.3po.su";
+// Where THIS run's kit lives (npx cache or a checkout's src dir).
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Stable install location: the kit is copied here and every global hook/plugin link points at
+// it, so wiring survives npx cache eviction and does not depend on any checkout.
+const STABLE = join(homedir(), ".petbox", "wire");
+
+// ---- arg parsing -----------------------------------------------------------
+
+type Args = {
+  dir: string;
+  projectKey: string;
+  env?: string;
+  key?: string;
+  workspace?: string;
+  cleanupLegacy: boolean;
+};
+
+function usage(): never {
+  console.error(
+    "usage: npx petbox-wire <dir> <projectKey> [--env VAR] [--key KEY] [--workspace WS] [--cleanup-legacy]",
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv: string[]): Args {
+  const positionals: string[] = [];
+  let env: string | undefined;
+  let key: string | undefined;
+  let workspace: string | undefined;
+  let cleanupLegacy = false;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--env") env = argv[++i];
+    else if (a === "--key") key = argv[++i];
+    else if (a === "--workspace") workspace = argv[++i];
+    else if (a === "--cleanup-legacy") cleanupLegacy = true;
+    else if (a.startsWith("--")) {
+      console.error(`unknown flag: ${a}`);
+      usage();
+    } else positionals.push(a);
+  }
+  if (positionals.length < 2) usage();
+  return { dir: positionals[0], projectKey: positionals[1], env, key, workspace, cleanupLegacy };
+}
+
+// ---- small helpers ---------------------------------------------------------
+
+const log = (msg: string) => console.log(msg);
+
+function deriveEnvVar(projectKey: string): string {
+  return projectKey.toUpperCase().replace(/[^A-Z0-9]/g, "_") + "_API_KEY";
+}
+
+// Cross-platform key store (~/.petbox/keys.json): a flat JSON map { "<ENV_VAR>": "<key>" }.
+// The kit's own hooks read it (via registry.ts) with no env var required. The per-project MCP
+// configs still reference ${ENV_VAR}, so persistKeyForAgents() additionally materializes a real
+// environment variable per platform.
+function keysStorePath(): string {
+  return join(homedir(), ".petbox", "keys.json");
+}
+
+// Read a key from the store. Returns "" if the file/entry is missing.
+function readKeyFromStore(name: string): string {
+  const store = readJson(keysStorePath());
+  const v = store && typeof store === "object" ? store[name] : undefined;
+  return typeof v === "string" ? v : "";
+}
+
+// Merge (never clobber) a key into the store. On POSIX tighten the file to 0600 (best-effort;
+// skipped on Windows, where chmod is a no-op / can throw).
+function writeKeyToStore(name: string, value: string): void {
+  const path = keysStorePath();
+  const store = readJson(path) ?? {};
+  store[name] = value;
+  writeJson(path, store);
+  if (process.platform !== "win32") {
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      /* best-effort */
+    }
+  }
+}
+
+// The agent MCP configs (.mcp.json `${VAR}`, opencode `{env:VAR}`, droid `${VAR}`) resolve the
+// key from a REAL environment variable — keys.json alone only covers the kit hooks. Persist it:
+//  - Windows: user-scope env via PowerShell (visible to NEW terminals);
+//  - POSIX: regenerate ~/.petbox/env.sh from the whole key store and make sure the login
+//    profiles source it (marker-guarded, idempotent).
+function persistKeyForAgents(envVar: string): void {
+  if (process.platform === "win32") {
+    const value = readKeyFromStore(envVar);
+    try {
+      execFileSync(
+        "powershell",
+        [
+          "-NoProfile",
+          "-NonInteractive",
+          "-Command",
+          `[Environment]::SetEnvironmentVariable('${envVar}', $env:WIRE_KEY_VALUE, 'User')`,
+        ],
+        { encoding: "utf8", env: { ...process.env, WIRE_KEY_VALUE: value } },
+      );
+      log(`[4/10] persisted ${envVar} to user-scope env (MCP configs read it; NEW terminals see it).`);
+    } catch (e) {
+      console.error(`[4/10] failed to persist ${envVar} to user-scope env — ${(e as Error).message}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  const store = readJson(keysStorePath()) ?? {};
+  const lines = Object.entries(store)
+    .filter(([, v]) => typeof v === "string")
+    .map(([k, v]) => `export ${k}=${JSON.stringify(v)}`);
+  const envShPath = join(homedir(), ".petbox", "env.sh");
+  writeFileSync(envShPath, "# Generated by petbox-wire from ~/.petbox/keys.json — do not edit.\n" + lines.join("\n") + "\n", "utf8");
+  try {
+    chmodSync(envShPath, 0o600);
+  } catch {
+    /* best-effort */
+  }
+
+  const marker = "# petbox-wire";
+  const sourceLine = `[ -f "$HOME/.petbox/env.sh" ] && . "$HOME/.petbox/env.sh" ${marker}`;
+  const profiles = [".profile", ".bashrc", ".zshenv"].map((f) => join(homedir(), f));
+  let sourced = false;
+  for (const p of profiles) {
+    if (!existsSync(p)) continue;
+    const content = readFileSync(p, "utf8");
+    if (!content.includes(marker)) appendFileSync(p, `\n${sourceLine}\n`, "utf8");
+    sourced = true;
+  }
+  if (!sourced) writeFileSync(profiles[0], sourceLine + "\n", "utf8");
+  log(`[4/10] wrote ${envShPath} and ensured login profiles source it (MCP configs read ${envVar}; new login shells see it).`);
+}
+
+function readJson(path: string): any {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(path: string, obj: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(obj, null, 2) + "\n", "utf8");
+}
+
+function toFileUrl(absPath: string): string {
+  // Build a file:/// URL the way Node does (handles Windows drive letters / backslashes).
+  return new URL("file://" + (process.platform === "win32" ? "/" : "") + absPath.replace(/\\/g, "/")).href;
+}
+
+// ---- step 4: validate ------------------------------------------------------
+
+async function validateKey(baseUrl: string, key: string, projectKey: string): Promise<void> {
+  const uri = `${baseUrl}/api/auth/validate`;
+  let resp: Response;
+  try {
+    resp = await fetch(uri, {
+      method: "GET",
+      headers: { "X-Api-Key": key },
+      signal: AbortSignal.timeout(12000),
+    });
+  } catch (e) {
+    console.error(`[3/10] validate: could not reach ${uri} — ${(e as Error).message}. Aborting.`);
+    process.exit(1);
+  }
+
+  if (resp.status === 401) {
+    console.error(`[3/10] validate: server rejected the API key (401). Aborting.`);
+    process.exit(1);
+  }
+  if (!resp.ok) {
+    // Non-standard / endpoint missing → warn and continue.
+    log(`[3/10] validate: unexpected status ${resp.status} (endpoint missing?); continuing with a warning.`);
+    return;
+  }
+  let body: any = null;
+  try {
+    body = await resp.json();
+  } catch {
+    log(`[3/10] validate: 200 but non-JSON body; continuing with a warning.`);
+    return;
+  }
+  // Contract (AuthApi.cs): 200 => { project, scopes } (camelCase, ASP.NET web defaults).
+  const proj = body?.project ?? body?.Project;
+  if (typeof proj === "string" && proj.length > 0) {
+    if (proj !== projectKey) {
+      console.error(
+        `[3/10] validate: key belongs to project '${proj}', not '${projectKey}'. Aborting.`,
+      );
+      process.exit(1);
+    }
+    log(`[3/10] validate: OK — key scoped to '${proj}'.`);
+  } else {
+    log(`[3/10] validate: 200 without a project field; continuing with a warning.`);
+  }
+}
+
+// ---- step 5: stable kit copy -----------------------------------------------
+
+// Copy the running kit (HERE — an npx cache dir or a checkout's src/) into the stable location
+// (~/.petbox/wire/), overwriting. Every global hook/plugin link is computed from STABLE, so the
+// wiring keeps working after npx evicts its cache or a checkout moves. Copies the whole src dir
+// (all .ts files + templates/SKILL.md). No-op when already running the installed copy.
+function copyKitToStable(): void {
+  if (resolve(HERE) === resolve(STABLE)) {
+    log(`[5/10] stable copy: already running the installed kit at ${STABLE} — skipped.`);
+    return;
+  }
+  mkdirSync(STABLE, { recursive: true });
+  cpSync(HERE, STABLE, { recursive: true, force: true });
+  log(`[5/10] stable copy: kit installed to ${STABLE} (from ${HERE}).`);
+}
+
+// ---- step 6: registry ------------------------------------------------------
+
+// Reuse the envVar of an existing registry entry for this exact prefix, so a plain re-run
+// stays idempotent even when the var name was customized via --env in the past.
+function registryEnvVar(prefix: string): string | undefined {
+  const data = readJson(join(homedir(), ".petbox", "projects.json"));
+  const entries: any[] = Array.isArray(data?.entries) ? data.entries : [];
+  const norm = (p: string) => p.replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+  const hit = entries.find((e) => norm(String(e?.prefix ?? "")) === norm(prefix));
+  const v = hit?.envVar;
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+
+function upsertRegistry(prefix: string, project: string, envVar: string, baseUrl: string): void {
+  const path = join(homedir(), ".petbox", "projects.json");
+  const data = readJson(path) ?? {};
+  const entries: any[] = Array.isArray(data.entries) ? data.entries : [];
+  const norm = (p: string) => p.replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+  const np = norm(prefix);
+  const next = entries.filter((e) => norm(String(e?.prefix ?? "")) !== np);
+  const entry: any = { prefix, project, envVar };
+  if (baseUrl !== DEFAULT_BASE_URL) entry.baseUrl = baseUrl;
+  next.push(entry);
+  writeJson(path, { entries: next });
+  log(`[6/10] registry: upserted ${prefix} → ${project} (${envVar}) in ${path}`);
+}
+
+// ---- step 7: per-project files --------------------------------------------
+
+// Merge one MCP server into a possibly-shared JSON config (Droid's .factory/mcp.json can hold
+// team servers), preserving every other server and top-level key. Idempotent: re-running with
+// the same inputs yields byte-identical output. Only the `petbox` entry is (re)generated.
+function mergeMcpServer(path: string, name: string, server: unknown): void {
+  const data = readJson(path) ?? {};
+  if (!data.mcpServers || typeof data.mcpServers !== "object") data.mcpServers = {};
+  data.mcpServers[name] = server;
+  writeJson(path, data);
+}
+
+// Skill surfaces wire.ts writes the rendered petbox SKILL.md into. opencode is intentionally
+// absent: it discovers the skill through its Claude-compatible path (`.claude/skills/…`), and a
+// second same-name copy under `.opencode/skills/` would be a duplicate whose resolution opencode
+// does not document. Droid reads its own `.factory/skills/` root (its compat path is
+// `.agent/skills/`, NOT `.claude/skills/`), so it needs a dedicated copy.
+const SKILL_SURFACES: string[][] = [
+  [".claude", "skills"], // Claude Code (native) + opencode (Claude-compatible discovery)
+  [".factory", "skills"], // Factory Droid (native)
+];
+
+function writeProjectFiles(dir: string, project: string, envVar: string, workspace: string): void {
+  // .mcp.json (Claude Code) — petbox-only file owned by wire.ts, regenerated whole.
+  const mcp = {
+    mcpServers: {
+      petbox: {
+        type: "http",
+        url: `${DEFAULT_BASE_URL}/mcp`,
+        headers: { "X-Api-Key": `\${${envVar}}` },
+      },
+    },
+  };
+  writeJson(join(dir, ".mcp.json"), mcp);
+  log(`[7/10] wrote ${join(dir, ".mcp.json")}`);
+
+  // .opencode/opencode.json (opencode) — petbox-only file owned by wire.ts, regenerated whole.
+  const oc = {
+    $schema: "https://opencode.ai/config.json",
+    mcp: {
+      petbox: {
+        type: "remote",
+        url: `${DEFAULT_BASE_URL}/mcp`,
+        enabled: true,
+        headers: { "X-Api-Key": `{env:${envVar}}` },
+      },
+    },
+  };
+  writeJson(join(dir, ".opencode", "opencode.json"), oc);
+  log(`[7/10] wrote ${join(dir, ".opencode", "opencode.json")}`);
+
+  // .factory/mcp.json (Factory Droid) — a project-level MCP config that may be shared with team
+  // servers, so merge (never clobber) rather than regenerate whole. Droid supports `${VAR}`
+  // env-var expansion in header values, so the key stays out of the file (no secret committed).
+  const droidMcpPath = join(dir, ".factory", "mcp.json");
+  mergeMcpServer(droidMcpPath, "petbox", {
+    type: "http",
+    url: `${DEFAULT_BASE_URL}/mcp`,
+    headers: { "X-Api-Key": `\${${envVar}}` },
+    disabled: false,
+  });
+  log(`[7/10] merged petbox MCP server into ${droidMcpPath}`);
+
+  // SKILL.md — render once from the template, then drop a copy into every native skill surface.
+  const tpl = readFileSync(join(HERE, "templates", "SKILL.md"), "utf8");
+  const skill = tpl
+    .replace(/\{\{PROJECT\}\}/g, project)
+    .replace(/\{\{WORKSPACE\}\}/g, workspace);
+  for (const surface of SKILL_SURFACES) {
+    const skillPath = join(dir, ...surface, "petbox", "SKILL.md");
+    mkdirSync(dirname(skillPath), { recursive: true });
+    writeFileSync(skillPath, skill, "utf8");
+    log(`[7/10] wrote ${skillPath}`);
+  }
+}
+
+// ---- step 8: global install ------------------------------------------------
+
+// Hook commands are `node "<STABLE>/<file>.ts"`. Older wirings (this repo's own owner box
+// included) left commands pointing at a checkout — e.g. `node "D:\…\agents\wiring\push-session.ts"`.
+// Recognize a kit hook by these command suffixes so we can prune the stale ones (any that don't
+// equal one of this run's stable commands).
+const KIT_HOOK_SUFFIXES = [
+  'push-session.ts"',
+  'pull-memory.ts"',
+  'droid-push-session.ts"',
+  'droid-pull-memory.ts"',
+];
+
+// Remove kit hook entries whose command is NOT one of the current stable commands (validCmds),
+// then drop any now-empty groups. Mutates hooksObj in place; returns the count pruned.
+function pruneStaleKitHooks(hooksObj: any, validCmds: Set<string>): number {
+  let removed = 0;
+  for (const event of Object.keys(hooksObj)) {
+    const groups: any[] = Array.isArray(hooksObj[event]) ? hooksObj[event] : [];
+    for (const g of groups) {
+      if (!g || !Array.isArray(g.hooks)) continue;
+      const before = g.hooks.length;
+      g.hooks = g.hooks.filter((h: any) => {
+        const c = typeof h?.command === "string" ? h.command : "";
+        const isKit = KIT_HOOK_SUFFIXES.some((s) => c.endsWith(s));
+        return !(isKit && !validCmds.has(c));
+      });
+      removed += before - g.hooks.length;
+    }
+    hooksObj[event] = groups.filter((g) => !(g && Array.isArray(g.hooks) && g.hooks.length === 0));
+  }
+  return removed;
+}
+
+function installGlobalHooks(): void {
+  const pushCmd = `node "${join(STABLE, "push-session.ts")}"`;
+  const pullCmd = `node "${join(STABLE, "pull-memory.ts")}"`;
+  const droidPushCmd = `node "${join(STABLE, "droid-push-session.ts")}"`;
+  const droidPullCmd = `node "${join(STABLE, "droid-pull-memory.ts")}"`;
+  // Every kit hook command this run considers current — the prune keeps these, drops the rest.
+  const validCmds = new Set([pushCmd, pullCmd, droidPushCmd, droidPullCmd]);
+
+  const settingsPath = join(homedir(), ".claude", "settings.json");
+  const settings = readJson(settingsPath) ?? {};
+  if (!settings.hooks || typeof settings.hooks !== "object") settings.hooks = {};
+  const prunedClaude = pruneStaleKitHooks(settings.hooks, validCmds);
+  if (prunedClaude > 0) log(`[8/10] pruned ${prunedClaude} stale claude kit hook(s) not pointing at ${STABLE}.`);
+
+  // Claude Code hooks shape: settings.hooks[event] = [{ matcher?, hooks: [{type, command}] }]
+  const ensureHook = (event: string, command: string) => {
+    const groups: any[] = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+    const already = groups.some(
+      (g) => Array.isArray(g?.hooks) && g.hooks.some((h: any) => h?.command === command),
+    );
+    if (already) {
+      log(`[8/10] claude hook ${event} already present — skipped.`);
+      return;
+    }
+    groups.push({ hooks: [{ type: "command", command }] });
+    settings.hooks[event] = groups;
+    log(`[8/10] claude hook ${event} added.`);
+  };
+
+  ensureHook("Stop", pushCmd);
+  ensureHook("SessionStart", pullCmd);
+  writeJson(settingsPath, settings);
+  log(`[8/10] merged hooks into ${settingsPath}`);
+
+  // Factory Droid hooks: same JSON shape as Claude Code, merged into ~/.factory/settings.json
+  // under the `hooks` key (a documented fallback location). Droid exposes petbox tools as
+  // `mcp__petbox__*` and delivers Claude-Code-compatible snake_case payloads, so it reuses the
+  // shared protocol/append flow via its own thin hooks. No `enableHooks` flag is set: the droid
+  // hooks reference does not document one gating hook execution.
+  const droidSettingsPath = join(homedir(), ".factory", "settings.json");
+  const droidSettings = readJson(droidSettingsPath) ?? {};
+  if (!droidSettings.hooks || typeof droidSettings.hooks !== "object") droidSettings.hooks = {};
+  const prunedDroid = pruneStaleKitHooks(droidSettings.hooks, validCmds);
+  if (prunedDroid > 0) log(`[8/10] pruned ${prunedDroid} stale droid kit hook(s) not pointing at ${STABLE}.`);
+
+  const ensureDroidHook = (event: string, command: string) => {
+    const groups: any[] = Array.isArray(droidSettings.hooks[event]) ? droidSettings.hooks[event] : [];
+    const already = groups.some(
+      (g) => Array.isArray(g?.hooks) && g.hooks.some((h: any) => h?.command === command),
+    );
+    if (already) {
+      log(`[8/10] droid hook ${event} already present — skipped.`);
+      return;
+    }
+    groups.push({ hooks: [{ type: "command", command }] });
+    droidSettings.hooks[event] = groups;
+    log(`[8/10] droid hook ${event} added.`);
+  };
+
+  ensureDroidHook("Stop", droidPushCmd);
+  ensureDroidHook("SessionStart", droidPullCmd);
+  writeJson(droidSettingsPath, droidSettings);
+  log(`[8/10] merged droid hooks into ${droidSettingsPath}`);
+
+  // Global opencode plugin: thin shim re-exporting the kit plugin from the stable copy's file
+  // URL (overwritten each run, so an old shim pointing at a checkout is replaced).
+  const pluginAbs = join(STABLE, "opencode-plugin.ts");
+  const pluginUrl = toFileUrl(pluginAbs);
+  const shimDir = join(homedir(), ".config", "opencode", "plugins");
+  mkdirSync(shimDir, { recursive: true });
+  const shimPath = join(shimDir, "petbox.ts");
+  const shim = `// Auto-generated by wire.ts — global PetBox opencode plugin shim.
+// Re-exports the kit plugin from its absolute path so a single source of truth serves
+// every project (the active project is resolved from cwd via the shared registry).
+export { PetboxPlugin, default } from "${pluginUrl}";
+`;
+  writeFileSync(shimPath, shim, "utf8");
+  log(`[8/10] wrote global opencode plugin shim ${shimPath} → ${pluginUrl}`);
+}
+
+// ---- step 9: cleanup legacy ------------------------------------------------
+
+function cleanupLegacy(dir: string): void {
+  // .claude/hooks/ — drop the whole per-project hooks folder.
+  const hooksDir = join(dir, ".claude", "hooks");
+  if (existsSync(hooksDir)) {
+    rmSync(hooksDir, { recursive: true, force: true });
+    log(`[9/10] removed ${hooksDir}`);
+  }
+
+  // .claude/settings.local.json — drop ONLY the hooks key, keep permissions etc.
+  const localPath = join(dir, ".claude", "settings.local.json");
+  const local = readJson(localPath);
+  if (local && typeof local === "object" && "hooks" in local) {
+    delete local.hooks;
+    writeJson(localPath, local);
+    log(`[9/10] removed 'hooks' key from ${localPath}`);
+  }
+
+  // .opencode/plugin/ — drop the per-project plugin folder.
+  const pluginDir = join(dir, ".opencode", "plugin");
+  if (existsSync(pluginDir)) {
+    rmSync(pluginDir, { recursive: true, force: true });
+    log(`[9/10] removed ${pluginDir}`);
+  }
+
+  // .opencode node deps — only if package.json depends solely on @opencode-ai/plugin.
+  const ocPkgPath = join(dir, ".opencode", "package.json");
+  const ocPkg = readJson(ocPkgPath);
+  if (ocPkg) {
+    const deps = { ...(ocPkg.dependencies ?? {}), ...(ocPkg.devDependencies ?? {}) };
+    const keys = Object.keys(deps);
+    const onlyPlugin = keys.length > 0 && keys.every((k) => k === "@opencode-ai/plugin");
+    const noDeps = keys.length === 0;
+    if (onlyPlugin || noDeps) {
+      for (const f of ["package.json", "bun.lock", "node_modules"]) {
+        const p = join(dir, ".opencode", f);
+        if (existsSync(p)) {
+          rmSync(p, { recursive: true, force: true });
+          log(`[9/10] removed ${p}`);
+        }
+      }
+    } else {
+      log(`[9/10] kept .opencode deps — package.json has non-plugin deps: ${keys.join(", ")}`);
+    }
+  }
+}
+
+// ---- step 10: self-smoke ---------------------------------------------------
+
+async function selfSmoke(baseUrl: string, project: string, key: string): Promise<void> {
+  const uri = `${baseUrl}/api/sessions/${project}/wire-smoke?agent=wire`;
+  const body = JSON.stringify({ role: "user", content: "wire.ts self-smoke — verifying the session push pipeline." });
+  let resp: Response;
+  try {
+    resp = await fetch(uri, {
+      method: "POST",
+      headers: { "X-Api-Key": key, "Content-Type": "application/x-ndjson; charset=utf-8" },
+      body,
+      signal: AbortSignal.timeout(12000),
+    });
+  } catch (e) {
+    console.error(`[10/10] self-smoke: POST failed — ${(e as Error).message}`);
+    process.exitCode = 1;
+    return;
+  }
+  const text = await resp.text();
+  if (!resp.ok) {
+    console.error(`[10/10] self-smoke: HTTP ${resp.status} — ${text}`);
+    process.exitCode = 1;
+    return;
+  }
+  let parsed: any = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    /* keep raw */
+  }
+  if (typeof parsed?.version === "number") {
+    log(`[10/10] self-smoke: OK — sessionId=${parsed.sessionId}, version=${parsed.version}, messages=${parsed.messageCount}`);
+  } else {
+    console.error(`[10/10] self-smoke: server did not return a numeric version — ${text}`);
+    process.exitCode = 1;
+  }
+}
+
+// ---- main ------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  const dir = resolve(args.dir);
+  const project = args.projectKey;
+  const baseUrl = DEFAULT_BASE_URL;
+  const workspace = args.workspace ?? "stdray";
+
+  if (!existsSync(dir)) {
+    console.error(`directory does not exist: ${dir}`);
+    process.exit(1);
+  }
+
+  // 1. env var — explicit --env wins; else reuse the existing registry entry (idempotent
+  // re-run with a customized var name); else derive from the project key.
+  const envVar = args.env ?? registryEnvVar(dir) ?? deriveEnvVar(project);
+  log(`[1/10] envVar = ${envVar}`);
+
+  // 2. key — --key wins, else process env (owner's inherited user-scope var still works),
+  // else the cross-platform key store (~/.petbox/keys.json).
+  let key = args.key;
+  if (key) {
+    log(`[2/10] using --key from the command line.`);
+  } else {
+    key = process.env[envVar] || readKeyFromStore(envVar) || "";
+    if (!key) {
+      console.error(
+        `[2/10] no API key found.\n` +
+          `  Provide one with --key <KEY>, or set ${envVar} (env or ~/.petbox/keys.json) first.\n` +
+          `  Mint a key from a Claude session on the $system project:\n` +
+          `    mcp__petbox__apikey_create  (project='${project}')\n` +
+          `  Then re-run with --key <KEY>. (Minting keys is out of scope for wire.ts.)`,
+      );
+      process.exit(1);
+    }
+    log(`[2/10] using existing ${envVar} (env or key store).`);
+  }
+
+  // 3. validate — BEFORE persisting anything, so a bad key never lands in the stores.
+  await validateKey(baseUrl, key, project);
+
+  // 4. persist everywhere agents look: keys.json (kit hooks read it immediately) + a real
+  // env var per platform (the per-project MCP configs reference ${envVar}). Idempotent, so
+  // re-runs self-heal a machine where only one of the two exists.
+  writeKeyToStore(envVar, key);
+  log(`[4/10] persisted ${envVar} to ${keysStorePath()}.`);
+  persistKeyForAgents(envVar);
+
+  // 5. stable kit copy
+  copyKitToStable();
+
+  // 6. registry
+  upsertRegistry(dir, project, envVar, baseUrl);
+
+  // 7. project files
+  writeProjectFiles(dir, project, envVar, workspace);
+
+  // 8. global install
+  installGlobalHooks();
+
+  // 9. cleanup legacy
+  if (args.cleanupLegacy) cleanupLegacy(dir);
+  else log(`[9/10] cleanup-legacy not requested — skipped.`);
+
+  // 10. self-smoke
+  await selfSmoke(baseUrl, project, key);
+
+  if (process.env[envVar]) {
+    log(`done.`);
+  } else {
+    log(
+      `done. NOTE: start a NEW terminal${process.platform === "win32" ? "" : " (login shell)"} before launching agents — ` +
+        `their MCP configs read ${envVar} from the environment. The kit hooks work immediately (keys.json).`,
+    );
+  }
+}
+
+main().catch((e) => {
+  console.error(e?.stack ?? String(e));
+  process.exit(1);
+});