petbox-wire 0.1.0-ci.1206

package/README.md

@@ -0,0 +1,119 @@
+# petbox-wire
+
+Wire any project to [PetBox](https://petbox.3po.su) for **Claude Code**, **opencode** and
+**Factory Droid** — one command, no repo clone:
+
+```bash
+npx petbox-wire <dir> <project> --key <KEY>
+```
+
+Full documentation: <https://petbox.3po.su/doc/wire>.
+
+## Requirements
+
+**Node >= 23.6** — the kit is plain TypeScript run through Node's native type-stripping
+(no build, zero runtime dependencies). Older Node exits with a clear version error.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `petbox-wire <dir> <project>` | Full wire: validate the key → persist it → copy the kit → register the directory → write per-project MCP configs and skills → install the global hooks → self-smoke. Idempotent. |
+| `petbox-wire update` | Refresh only the stable kit under `~/.petbox/wire/` (exact mirror + orphan cleanup, content hash before → after). No keys, no registry, no hook reinstall, no MCP/skills, no sticky-flag reset. Does **not** compile agent files. |
+| `petbox-wire apply [--definition <key>] [--offline]` | Compile the per-harness agent role files from the portable agent definition + your local role→model binding. |
+| `petbox-wire doctor` | Offline gate: check the default agent definition against every known harness; print OK or each violation. |
+| `petbox-wire roles` | Print the active profile and its role→model bindings (`~/.petbox/roles.json`). Offline; an empty store exits 0 — no model is ever invented. |
+| `petbox-wire roles export` | Write a bootstrap copy of `roles.json` to stdout (no secrets). Pipe it to a file on a new machine. |
+| `petbox-wire profile use <name>` | Set `activeProfile` in `~/.petbox/roles.json`. Compiles nothing — re-run `apply`. |
+
+`update`, `apply`, `doctor`, `roles` and `profile` take no `<dir> <project>`.
+
+## Flags (full wire)
+
+| Flag | Effect |
+| --- | --- |
+| `--key <KEY>` | The project's API key. Mint it on the project's **Connect agent** page in the UI — key minting is out of scope for this tool. Omitted → taken from the env var, then from `~/.petbox/keys.json`. |
+| `--env <VAR>` | Override the env-var name holding the key. |
+| `--workspace <WS>` | Workspace stamped into the generated `SKILL.md`. Omitted → the workspace the server reports for your key; if neither is available the wire stops with a usage error (exit 2). |
+| `--cleanup-legacy` | Remove a project's old per-project hook/plugin copies. |
+| `--telemetry` | Wire Claude Code OTLP export into the project (off by default; Claude Code only). |
+| `--telemetry-log <name>` | Target named log for telemetry (default `cc-telemetry`; created if missing). |
+| `--help`, `-h` | Usage banner, exit 0. |
+
+The API key is validated against the server **before** anything is persisted, so a bad key never
+lands in your stores.
+
+## The env-var name
+
+The key is held in `PETBOX_<PROJECT>_API_KEY` — the project key upper-cased, runs of
+non-alphanumeric characters collapsed to `_`, leading/trailing `_` trimmed, `PETBOX_` prefixed
+(`kpvotes` → `PETBOX_KPVOTES_API_KEY`). Same name the UI's Connect page shows you. `--env` overrides
+it, and a re-run reuses whatever name is already recorded for that directory — so a machine wired
+before this scheme keeps its older variable. `~/.petbox/keys.json` is the ground truth for the name
+your machine actually has.
+
+## What it installs
+
+- **Global hooks** for Claude Code (`~/.claude/settings.json`) and Factory Droid
+  (`~/.factory/settings.json`): a `Stop` hook that mirrors each session into PetBox and a
+  `SessionStart` hook that injects the memory protocol + canon — the only context the wiring
+  injects; there is no per-prompt injection. Merged, never clobbered.
+- **A global opencode plugin** (`~/.config/opencode/plugins/petbox.ts`) with the same two behaviors.
+- **Per-project config** in `<dir>`: `.mcp.json` (Claude Code MCP), `.opencode/opencode.json`
+  (opencode MCP), `.factory/mcp.json` (Droid MCP — **merged**, so team servers survive), the rendered
+  `SKILL.md` under `.claude/skills/petbox/` and `.factory/skills/petbox/`, and the on-demand
+  **agent-factory** skill under `.claude/skills/petbox-agent-factory/` and
+  `.factory/skills/petbox-agent-factory/` (`roles` / `profile` / `doctor` / `apply`).
+- **Optional**, per flag: the Claude Code OTLP export env (`--telemetry`).
+
+All MCP configs reference the key as `${VAR}` / `{env:VAR}` — the key itself is never written into a
+project file.
+
+## `apply` — generated agent files
+
+`apply` resolves the project root by the longest registry prefix covering cwd, fetches the portable
+agent definition (`GET /api/{project}/agent-defs/{key}`, scope **`agents:read`** — a read-only key is
+enough), and compiles one file per role:
+
+| Harness | Path |
+| --- | --- |
+| Claude Code | `.claude/agents/<role>.md` |
+| opencode | `.opencode/agent/<role>.md` |
+| Factory Droid | `.factory/droids/<name>.md` |
+
+These are **overwritten** — don't hand-edit them. Models come from your local `~/.petbox/roles.json`
+binding only; an unbound role gets no `model:` line (droid: `model: inherit`). A role that requires a
+capability the target harness does not declare is **skipped and reported**, never silently written
+without it.
+
+Every successful definition fetch is cached to `~/.petbox/cache/<project>.agent-def.json` (LKG). When
+the server is unreachable — or you pass `--offline` — `apply` uses that cache and marks the result
+stale; only with no cache at all does it fall back to the built-in default definition.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Success. |
+| `1` | Hard failure — invalid definition, unexpected throw. |
+| `2` | Usage / bad arguments. |
+| `3` | Truthfulness policy block — some roles/harnesses were refused. **A partial write is possible.** |
+
+Only `apply` and `doctor` use the full taxonomy. The **full wire** exits `2` for usage errors and `1`
+for *any* other failure — do not script against `3` there.
+
+## Where things live
+
+| Path | Contents |
+| --- | --- |
+| `~/.petbox/wire/` | The stable kit copy. Every hook and plugin points here, so wiring survives `npx` cache eviction. Refresh with `update`. |
+| `~/.petbox/projects.json` | Registry: directory prefix → project, env-var name, base URL. |
+| `~/.petbox/keys.json` | `{ "<ENV_VAR>": "<key>" }` (POSIX: `chmod 0600`). The kit hooks read `process.env[<ENV_VAR>]` first, then this file. |
+| `~/.petbox/env.sh` | POSIX only — generated from the key store, sourced from your login profiles. |
+| `~/.petbox/roles.json` | Local role→model bindings + `activeProfile`. Never uploaded. |
+| `~/.petbox/cache/` | LKG agent definition + memory canon per project. |
+
+The per-project MCP configs resolve `${<ENV_VAR>}` from the **real** environment, so wire also
+persists it (Windows: user-scope env; POSIX: `env.sh` + profile source). Start a **new terminal**
+before launching agents after the first wiring — the kit's own hooks work immediately, because they
+read `~/.petbox/keys.json` directly.

package/bin/petbox-wire.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Thin launcher for the PetBox agent-wiring kit.
+//
+// Plain JS (no TypeScript) so it still starts on an old Node and can print a clear
+// version error. The kit itself is plain TypeScript executed by Node's native
+// type-stripping, which needs Node >= 23.6.
+
+const [maj, min] = process.versions.node.split(".").map((n) => parseInt(n, 10));
+if (maj < 23 || (maj === 23 && min < 6)) {
+  console.error(
+    `petbox-wire needs Node >= 23.6 (native TypeScript type-stripping); you have ${process.versions.node}`,
+  );
+  process.exit(1);
+}
+
+// Node deliberately refuses to type-strip .ts files under node_modules
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), and the npx cache is exactly that — so the
+// kit cannot run in place. Copy it out to a temp dir and import from there; wire.ts then
+// installs the stable copy (~/.petbox/wire/) itself after validating the key.
+const { cpSync, mkdtempSync } = await import("node:fs");
+const { tmpdir } = await import("node:os");
+const { join, dirname } = await import("node:path");
+const { fileURLToPath, pathToFileURL } = await import("node:url");
+
+const srcDir = join(dirname(fileURLToPath(import.meta.url)), "..", "src");
+const runDir = mkdtempSync(join(tmpdir(), "petbox-wire-"));
+cpSync(srcDir, runDir, { recursive: true });
+
+// wire.ts runs main() at module top level, so importing it executes the CLI.
+await import(pathToFileURL(join(runDir, "wire.ts")).href);

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "petbox-wire",
+	"version": "0.1.0-ci.1206",
+	"description": "Wire any project to PetBox (Claude Code, opencode, Factory Droid) — global hooks, MCP configs and skills — with a single npx command, no repo clone.",
+	"type": "module",
+	"bin": {
+		"petbox-wire": "bin/petbox-wire.js"
+	},
+	"files": [
+		"bin",
+		"src",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=23.6.0"
+	},
+	"scripts": {
+		"test": "node --test src/*.test.ts",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@opencode-ai/plugin": "^1.17.20",
+		"@types/node": "^22.10.2",
+		"typescript": "5.7.3"
+	},
+	"keywords": [
+		"petbox",
+		"wiring",
+		"claude-code",
+		"opencode",
+		"factory-droid",
+		"mcp"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/stdray/petbox.git",
+		"directory": "src/clients-ts/petbox-wire"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	}
+}

package/src/agent-def-fetch.test.ts

@@ -0,0 +1,317 @@
+// Unit tests for agent-def-fetch (parser + fetch + LKG cache resolution).
+//
+// Run: node --test src/agent-def-fetch.test.ts   (Node >= 23.6 native TS)
+
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import {
+  AGENT_DEF_STALE_MARKER,
+  agentDefCacheDir,
+  agentDefCachePath,
+  DEFAULT_DEFINITION_KEY,
+  fetchAgentDefinition,
+  parseAgentDefinitionResponse,
+  readAgentDefCache,
+  resolveAgentDefinitionWithLkg,
+  writeAgentDefCache,
+} from "./agent-def-fetch.ts";
+import { DEFAULT_AGENT_DEFINITION, validateAgentDefinition } from "./agent-definition.ts";
+import { planOpencodeApply } from "./apply-artifacts.ts";
+
+const VALID_BODY = {
+  key: "default",
+  version: 3,
+  created: "2026-01-01T00:00:00Z",
+  updated: "2026-01-02T00:00:00Z",
+  definition: {
+    name: "proj-default",
+    roles: [
+      {
+        slug: "orchestrator",
+        tier: "orchestrator",
+        requiredCapabilities: ["mcp_main_session"],
+        spawn: { allowed: true, allowedRoles: ["worker"] },
+        escalation: { available: true, targets: ["reserve"] },
+        notes: "main loop",
+      },
+      {
+        slug: "worker",
+        tier: "worker",
+        requiredCapabilities: [],
+        spawn: { allowed: false },
+        escalation: { available: false },
+      },
+    ],
+  },
+  extraServerField: true,
+};
+
+function freshHome(): string {
+  return mkdtempSync(join(tmpdir(), "petbox-adef-"));
+}
+
+test("parseAgentDefinitionResponse maps camelCase envelope + definition", () => {
+  const got = parseAgentDefinitionResponse(VALID_BODY);
+  assert.ok(got);
+  assert.equal(got.key, "default");
+  assert.equal(got.version, 3);
+  assert.equal(got.definition.name, "proj-default");
+  assert.equal(got.definition.roles.length, 2);
+  const [firstRole] = got.definition.roles;
+  assert.ok(firstRole);
+  assert.equal(firstRole.slug, "orchestrator");
+  validateAgentDefinition(got.definition);
+});
+
+test("parseAgentDefinitionResponse rejects role.model", () => {
+  const bad = structuredClone(VALID_BODY);
+  (bad.definition.roles[0] as { model?: string }).model = "claude-opus";
+  assert.equal(parseAgentDefinitionResponse(bad), null);
+});
+
+test("parseAgentDefinitionResponse rejects missing roles / name / version", () => {
+  assert.equal(parseAgentDefinitionResponse(null), null);
+  assert.equal(parseAgentDefinitionResponse({}), null);
+  assert.equal(
+    parseAgentDefinitionResponse({ key: "default", version: 1, definition: { name: "x", roles: [] } }),
+    null,
+  );
+});
+
+test("fetchAgentDefinition returns mapped definition on 200", async () => {
+  const calls: Array<{ url: string; headers: RequestInit["headers"] }> = [];
+  const fetchImpl: typeof fetch = async (input, init) => {
+    calls.push({ url: String(input), headers: init?.headers });
+    return new Response(JSON.stringify(VALID_BODY), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  const got = await fetchAgentDefinition({
+    baseUrl: "https://petbox.example/",
+    projectKey: "$system",
+    apiKey: "k",
+    definitionKey: DEFAULT_DEFINITION_KEY,
+    fetchImpl,
+  });
+  assert.ok(got);
+  assert.equal(got.key, "default");
+  assert.equal(got.version, 3);
+  assert.equal(calls.length, 1);
+  const [call] = calls;
+  assert.ok(call);
+  assert.equal(call.url, "https://petbox.example/api/%24system/agent-defs/default");
+});
+
+test("fetchAgentDefinition returns null on 404 / network / bad body (never throws)", async () => {
+  assert.equal(
+    await fetchAgentDefinition({
+      baseUrl: "https://petbox.example",
+      projectKey: "p",
+      apiKey: "k",
+      fetchImpl: async () => new Response("nope", { status: 404 }),
+    }),
+    null,
+  );
+  assert.equal(
+    await fetchAgentDefinition({
+      baseUrl: "https://petbox.example",
+      projectKey: "p",
+      apiKey: "k",
+      fetchImpl: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+    }),
+    null,
+  );
+});
+
+test("successful fetch path writeAgentDefCache leaves ~/.petbox/cache/<project>.agent-def.json", () => {
+  const home = freshHome();
+  try {
+    const fetched = parseAgentDefinitionResponse(VALID_BODY)!;
+    writeAgentDefCache("$system", fetched, home, () => "2026-07-10T00:00:00.000Z");
+    const path = agentDefCachePath("$system", home);
+    assert.equal(existsSync(path), true);
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    assert.equal(raw.key, "default");
+    assert.equal(raw.version, 3);
+    assert.equal(raw.fetchedAt, "2026-07-10T00:00:00.000Z");
+    assert.equal(raw.definition.name, "proj-default");
+    const round = readAgentDefCache("$system", home);
+    assert.ok(round);
+    assert.equal(round.definition.name, "proj-default");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("resolve: fetch null + LKG present → uses cache with stale marker (not DEFAULT)", async () => {
+  const home = freshHome();
+  try {
+    const fetched = parseAgentDefinitionResponse(VALID_BODY)!;
+    writeAgentDefCache("proj", fetched, home);
+
+    const got = await resolveAgentDefinitionWithLkg({
+      offline: false,
+      definitionKey: "default",
+      projectKey: "proj",
+      baseUrl: "https://petbox.example",
+      apiKey: "k",
+      homeDir: home,
+      fetchImpl: async () => new Response("down", { status: 503 }),
+    });
+
+    assert.equal(got.source, "lkg");
+    assert.equal(got.stale, true);
+    assert.equal(got.staleMarker, AGENT_DEF_STALE_MARKER);
+    assert.equal(got.definition.name, "proj-default");
+    assert.notEqual(got.definition.name, DEFAULT_AGENT_DEFINITION.name);
+    assert.match(got.staleMarker!, /LKG cache|stale/i);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("resolve: fetch null + no LKG → DEFAULT", async () => {
+  const home = freshHome();
+  try {
+    const got = await resolveAgentDefinitionWithLkg({
+      offline: false,
+      definitionKey: "default",
+      projectKey: "proj",
+      baseUrl: "https://petbox.example",
+      apiKey: "k",
+      homeDir: home,
+      fetchImpl: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+    });
+    assert.equal(got.source, "default");
+    assert.equal(got.stale, false);
+    assert.equal(got.definition, DEFAULT_AGENT_DEFINITION);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("resolve: --offline with LKG uses cache (no network)", async () => {
+  const home = freshHome();
+  try {
+    const fetched = parseAgentDefinitionResponse(VALID_BODY)!;
+    writeAgentDefCache("proj", fetched, home);
+
+    let fetchCalls = 0;
+    const got = await resolveAgentDefinitionWithLkg({
+      offline: true,
+      definitionKey: "default",
+      projectKey: "proj",
+      baseUrl: "https://petbox.example",
+      apiKey: "k",
+      homeDir: home,
+      fetchImpl: async () => {
+        fetchCalls++;
+        throw new Error("should not be called");
+      },
+    });
+
+    assert.equal(fetchCalls, 0);
+    assert.equal(got.source, "lkg");
+    assert.equal(got.stale, true);
+    assert.equal(got.definition.name, "proj-default");
+    assert.ok(got.staleMarker);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("resolve: live fetch writes LKG then returns server source", async () => {
+  const home = freshHome();
+  try {
+    const got = await resolveAgentDefinitionWithLkg({
+      offline: false,
+      definitionKey: "default",
+      projectKey: "proj",
+      baseUrl: "https://petbox.example",
+      apiKey: "k",
+      homeDir: home,
+      fetchImpl: async () =>
+        new Response(JSON.stringify(VALID_BODY), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        }),
+    });
+    assert.equal(got.source, "server");
+    assert.equal(got.stale, false);
+    assert.equal(existsSync(agentDefCachePath("proj", home)), true);
+    assert.equal(readAgentDefCache("proj", home)?.version, 3);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("offline DEFAULT_AGENT_DEFINITION still compiles (truthfulness + plan green)", () => {
+  validateAgentDefinition(DEFAULT_AGENT_DEFINITION);
+  const plan = planOpencodeApply(DEFAULT_AGENT_DEFINITION, {});
+  assert.equal(plan.violations.length, 0);
+  assert.ok(plan.files.length >= 1);
+});
+
+test("readAgentDefCache: corrupt JSON → null (treated as no cache)", () => {
+  const home = freshHome();
+  try {
+    mkdirSync(agentDefCacheDir(home), { recursive: true });
+    writeFileSync(agentDefCachePath("proj", home), "{ not valid json", "utf8");
+    assert.equal(readAgentDefCache("proj", home), null);
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test("resolve: tampered cache (role.model injected) is rejected → DEFAULT, no injection", async () => {
+  const home = freshHome();
+  try {
+    // Well-formed envelope but a poisoned role carrying a model binding — a portable
+    // definition must never carry model. The read path must reject it, and resolve must
+    // fall through to DEFAULT rather than compile the attacker's roster.
+    mkdirSync(agentDefCacheDir(home), { recursive: true });
+    const poisoned = {
+      key: "default",
+      version: 9,
+      fetchedAt: "2026-07-10T00:00:00.000Z",
+      definition: {
+        name: "attacker-roster",
+        roles: [
+          {
+            slug: "orchestrator",
+            tier: "orchestrator",
+            requiredCapabilities: [],
+            model: "attacker/evil-model",
+          },
+        ],
+      },
+    };
+    writeFileSync(agentDefCachePath("proj", home), JSON.stringify(poisoned), "utf8");
+
+    // Direct read rejects the tampered record.
+    assert.equal(readAgentDefCache("proj", home), null);
+
+    // And resolve (offline, so cache is the only non-DEFAULT source) falls to DEFAULT,
+    // never the attacker roster.
+    const got = await resolveAgentDefinitionWithLkg({
+      offline: true,
+      definitionKey: "default",
+      projectKey: "proj",
+      homeDir: home,
+    });
+    assert.equal(got.source, "default");
+    assert.equal(got.definition, DEFAULT_AGENT_DEFINITION);
+    assert.notEqual(got.definition.name, "attacker-roster");
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+  }
+});