petbox-wire 0.1.0-ci.1206

package/src/truthfulness.ts

@@ -0,0 +1,164 @@
+// Definition truthfulness gate (definition-truthfulness).
+//
+// Two claims are gated, with the SAME contract (list violations → callers fail loud,
+// never silently emit a role that carries one):
+//
+//   1. capability — a role may only require capabilities the target harness declares
+//      (harness-capabilities.ts).
+//   2. model — a role's LOCAL model binding (~/.petbox/roles.json, passed in per role) is
+//      three-tier classified against the target harness (harness-models.ts): known/unknown
+//      never block, only a recognizably FOREIGN-harness id shape does (revised 2026-07-13,
+//      task `model-gate-revision-premise-falsified`, after a live measurement disproved the
+//      original premise — Claude Code does NOT silently inherit on an unresolvable frontmatter
+//      model, it fails LOUD at runtime with an API error; the gate now exists to catch a
+//      cross-harness id BEFORE that loud failure, not to prevent a silent one). Intake
+//      `wire-apply-writes-unresolvable-model-id`, 2026-07-12: a droid id landed in the
+//      claude-code block of roles.json.
+//      An ABSENT binding is not a violation — that is the harness's documented inherit
+//      behaviour and is surfaced as a warning by the caller, not a block. Neither is an
+//      "unknown" model (shape-valid, just not on the small known-alias list) — that is also
+//      surfaced as a warning, never a block (see modelShapeWarning below).
+//
+// NEVER silently drop a violation — callers must fail loud when the list is non-empty
+// (doctor / apply / tests).
+//
+// Plain TS for native node type-stripping: zero deps.
+
+import type { AgentDefinition, AgentRole } from "./agent-definition.ts";
+import { harnessCapabilities } from "./harness-capabilities.ts";
+import { allowedModels, classifyModel } from "./harness-models.ts";
+
+export type CapabilityViolation = {
+  readonly role: string;
+  readonly capability: string;
+  readonly harness: string;
+};
+
+export type ModelViolation = {
+  readonly role: string;
+  readonly harness: string;
+  /** The unresolvable id the local binding asked us to write. */
+  readonly model: string;
+  /** Ids this harness can resolve (never empty — a model violation implies a closed policy). */
+  readonly allowedModels: readonly string[];
+};
+
+export type TruthfulnessViolation = CapabilityViolation | ModelViolation;
+
+export function isModelViolation(v: TruthfulnessViolation): v is ModelViolation {
+  return "model" in v;
+}
+
+/**
+ * Effective required capabilities for a role.
+ * spawn.allowed === true implicitly requires spawn_subagents so spawn prose cannot
+ * bypass the capability gate by omitting it from requiredCapabilities.
+ */
+export function effectiveRequiredCapabilities(role: AgentRole): readonly string[] {
+  const caps = [...role.requiredCapabilities];
+  if (role.spawn?.allowed === true && !caps.includes("spawn_subagents")) {
+    caps.push("spawn_subagents");
+  }
+  return caps;
+}
+
+/**
+ * Pure model gate for one role + harness + its local binding.
+ * Unbound (undefined / blank) → no violation (inherit is legitimate; caller warns).
+ * Harness with an open model-id space → no violation (we make no claim).
+ * Only the "foreign" tier (harness-models.ts) blocks — a recognizably different harness's id
+ * shape (`custom:*`, `provider/model`) landing in this binding. The "unknown" tier (shape-valid
+ * for this harness, just not on its small known-alias list) is NOT a violation — see
+ * modelShapeWarning for its non-blocking notice.
+ */
+export function checkRoleModelTruthfulness(
+  role: AgentRole,
+  harness: string,
+  model: string | undefined,
+): readonly ModelViolation[] {
+  const m = (model ?? "").trim();
+  if (!m) return [];
+  if (classifyModel(harness, m) !== "foreign") return [];
+  return [
+    {
+      role: role.slug,
+      harness,
+      model: m,
+      allowedModels: allowedModels(harness) ?? [],
+    },
+  ];
+}
+
+/**
+ * Non-blocking notice for a role bound to a model that classifies "unknown": shape-valid for the
+ * target harness (e.g. `claude-*`) but not on its small known-alias list — plausibly a real,
+ * newer id this kit's list has not caught up with. Null when there is nothing to warn about
+ * (unbound, "known", "foreign" — foreign is a violation, not a warning — or an open-policy
+ * harness). Callers (apply-artifacts.ts) fold this into the same non-blocking warnings list used
+ * for an unbound model.
+ */
+export function modelShapeWarning(
+  role: AgentRole,
+  harness: string,
+  model: string | undefined,
+): string | null {
+  const m = (model ?? "").trim();
+  if (!m) return null;
+  if (classifyModel(harness, m) !== "unknown") return null;
+  return (
+    `role '${role.slug}' is bound to model '${m}' on harness '${harness}', which is not on the ` +
+    `harness's known-alias list but matches its id shape — writing it unverified. If '${harness}' ` +
+    `cannot actually resolve it, that fails LOUD at runtime (an API error), not silently.`
+  );
+}
+
+/**
+ * Pure gate for one role + harness (+ optional bound model) → violations (or empty).
+ * Unknown harness ids declare zero capabilities → every required cap is a violation.
+ */
+export function checkRoleTruthfulness(
+  role: AgentRole,
+  harness: string,
+  model?: string,
+): readonly TruthfulnessViolation[] {
+  const caps = harnessCapabilities(harness);
+  const out: TruthfulnessViolation[] = [];
+  for (const capability of effectiveRequiredCapabilities(role)) {
+    if (!caps.has(capability)) {
+      out.push({ role: role.slug, capability, harness });
+    }
+  }
+  out.push(...checkRoleModelTruthfulness(role, harness, model));
+  return out;
+}
+
+/**
+ * Pure gate: definition + harness (+ role→model binding map) → all role violations (or empty).
+ */
+export function checkTruthfulness(
+  definition: AgentDefinition,
+  harness: string,
+  roleModels: Readonly<Record<string, string>> = {},
+): readonly TruthfulnessViolation[] {
+  const out: TruthfulnessViolation[] = [];
+  for (const role of definition.roles) {
+    out.push(...checkRoleTruthfulness(role, harness, roleModels[role.slug]));
+  }
+  return out;
+}
+
+/** Human-readable multi-line report (empty string when no violations). */
+export function formatViolations(violations: readonly TruthfulnessViolation[]): string {
+  if (violations.length === 0) return "";
+  return violations
+    .map((v) =>
+      isModelViolation(v)
+        ? `  role '${v.role}' is bound to model '${v.model}', which looks like ANOTHER harness's ` +
+          `model id, not one harness '${v.harness}' would own — writing it would be either ` +
+          `rejected loudly at runtime or silently satisfy a different harness's config, not ` +
+          `this one. Known ${v.harness} aliases: ${v.allowedModels.join(", ")}. Fix the binding ` +
+          `in ~/.petbox/roles.json (profile → agents.${v.harness}.roles.${v.role}.model).`
+        : `  role '${v.role}' requires capability '${v.capability}' which harness '${v.harness}' does not declare`,
+    )
+    .join("\n");
+}

package/src/wire-exit.test.ts

@@ -0,0 +1,43 @@
+// Exit taxonomy: usage vs truthfulness must stay distinct (CI signal).
+//
+// Run: node --test src/wire-exit.test.ts
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { classifyApplyExit, WIRE_EXIT } from "./wire-exit.ts";
+
+test("WIRE_EXIT taxonomy is distinct", () => {
+  assert.equal(WIRE_EXIT.ok, 0);
+  assert.equal(WIRE_EXIT.hard, 1);
+  assert.equal(WIRE_EXIT.usage, 2);
+  assert.equal(WIRE_EXIT.truthfulness, 3);
+  const codes = new Set(Object.values(WIRE_EXIT));
+  assert.equal(codes.size, 4, "each exit class must have a unique code");
+});
+
+test("classifyApplyExit: usage errors are NOT truthfulness (different codes)", () => {
+  // Bad flags go through usage() → WIRE_EXIT.usage (2), never classifyApplyExit.
+  // This test locks the contract that truthfulness is 3 and usage is 2.
+  assert.notEqual(WIRE_EXIT.usage, WIRE_EXIT.truthfulness);
+  assert.equal(classifyApplyExit({ hadTruthfulnessBlock: true }), WIRE_EXIT.truthfulness);
+  assert.equal(classifyApplyExit({ hardError: true }), WIRE_EXIT.hard);
+  assert.equal(classifyApplyExit({ hardError: true, hadTruthfulnessBlock: true }), WIRE_EXIT.hard);
+  assert.equal(classifyApplyExit({}), WIRE_EXIT.ok);
+  assert.equal(classifyApplyExit({ hadTruthfulnessBlock: false }), WIRE_EXIT.ok);
+});
+
+test("usage code is 2 (convention) and truthfulness block is 3", () => {
+  // Simulated outcomes a CI script would branch on:
+  const usageTypo = WIRE_EXIT.usage; // e.g. `petbox-wire apply --definiton` → usage()
+  const policyBlock = classifyApplyExit({ hadTruthfulnessBlock: true });
+  assert.equal(usageTypo, 2);
+  assert.equal(policyBlock, 3);
+  assert.notEqual(usageTypo, policyBlock);
+});
+
+test("doctor and apply share truthfulness exit 3 (not hard 1)", () => {
+  // Both tools call classifyApplyExit({ hadTruthfulnessBlock: true }) for policy fails.
+  assert.equal(classifyApplyExit({ hadTruthfulnessBlock: true }), WIRE_EXIT.truthfulness);
+  assert.notEqual(WIRE_EXIT.truthfulness, WIRE_EXIT.hard);
+  assert.notEqual(WIRE_EXIT.truthfulness, WIRE_EXIT.usage);
+});

package/src/wire-exit.ts

@@ -0,0 +1,25 @@
+// CLI exit taxonomy for petbox-wire apply / usage.
+//
+// Kept in a tiny module (not wire.ts) so unit tests can import without running wire main().
+//
+//   0 — full success (every known harness wrote every role)
+//   1 — hard failure (invalid definition, unexpected throw)
+//   2 — usage / bad arguments (convention)
+//   3 — truthfulness: policy blocked some roles/harnesses (partial write possible)
+
+export const WIRE_EXIT = {
+  ok: 0,
+  hard: 1,
+  usage: 2,
+  truthfulness: 3,
+} as const;
+
+/** Pure classifier for apply's process exit (testable without spawning). */
+export function classifyApplyExit(opts: {
+  hardError?: boolean;
+  hadTruthfulnessBlock?: boolean;
+}): number {
+  if (opts.hardError) return WIRE_EXIT.hard;
+  if (opts.hadTruthfulnessBlock) return WIRE_EXIT.truthfulness;
+  return WIRE_EXIT.ok;
+}

package/src/wire-identity.test.ts

@@ -0,0 +1,65 @@
+// Unit tests for the wire's identity resolution: the canonical per-project API-key env var name
+// and the workspace used by the skill template. Both live in wire-identity.ts specifically so
+// they're importable here — wire.ts runs main() at module top level and must never be imported
+// by a test (see posix-env.test.ts for the same note).
+//
+// Run: node --test src/wire-identity.test.ts   (Node >= 23.6 native TS type-stripping)
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { WIRE_EXIT } from "./wire-exit.ts";
+import { deriveEnvVar, resolveWorkspace } from "./wire-identity.ts";
+
+test("deriveEnvVar matches the server's EnvSlug (PETBOX_<PROJECT>_API_KEY)", () => {
+  // The Connect page (ProjectConnect.cshtml.cs EnvSlug) is the single source of truth for the
+  // name an operator is told to set — the CLI default must be byte-identical.
+  assert.equal(deriveEnvVar("$system"), "PETBOX_SYSTEM_API_KEY");
+  assert.equal(deriveEnvVar("kpvotes"), "PETBOX_KPVOTES_API_KEY");
+  assert.equal(deriveEnvVar("petbox"), "PETBOX_PETBOX_API_KEY");
+});
+
+test("deriveEnvVar collapses runs of punctuation and trims leading/trailing underscores", () => {
+  assert.equal(deriveEnvVar("my--weird..key"), "PETBOX_MY_WEIRD_KEY_API_KEY");
+  assert.equal(deriveEnvVar("$$foo-bar$$"), "PETBOX_FOO_BAR_API_KEY");
+  assert.equal(deriveEnvVar("a.b-c"), "PETBOX_A_B_C_API_KEY");
+  // Regression: the old scheme replaced 1:1 and never trimmed → "_SYSTEM_API_KEY".
+  assert.ok(!deriveEnvVar("$system").startsWith("_"));
+  assert.ok(!deriveEnvVar("$$foo-bar$$").includes("__"));
+});
+
+test("resolveWorkspace: --workspace flag wins over the server-reported workspace", () => {
+  const r = resolveWorkspace("acme", "server-ws");
+  assert.equal(r.ok, true);
+  assert.equal(r.ok && r.workspace, "acme");
+  assert.equal(r.ok && r.source, "flag");
+});
+
+test("resolveWorkspace: server-reported workspace is used when no flag is passed", () => {
+  const r = resolveWorkspace(undefined, "server-ws");
+  assert.equal(r.ok, true);
+  assert.equal(r.ok && r.workspace, "server-ws");
+  assert.equal(r.ok && r.source, "server");
+});
+
+test("resolveWorkspace: neither flag nor server value → usage error, exit 2 (no hardcoded default)", () => {
+  // An old server predating the `workspace` field on /api/auth/validate reports none.
+  const r = resolveWorkspace(undefined, undefined);
+  assert.equal(r.ok, false);
+  if (r.ok) return;
+  assert.equal(r.exitCode, WIRE_EXIT.usage);
+  assert.equal(r.exitCode, 2);
+  assert.match(r.message, /--workspace is required: this server did not report a workspace/);
+  // Never a personal workspace baked into the published CLI.
+  assert.doesNotMatch(r.message, /stdray/);
+});
+
+test("resolveWorkspace: blank strings count as absent (flag and server alike)", () => {
+  // Stored to one variable — two independent calls cannot be correlated by the type
+  // checker's control-flow narrowing (each is a fresh, unrelated WorkspaceResolution),
+  // and calling the function twice to check two different things was also wasteful.
+  const blank = resolveWorkspace("   ", "server-ws");
+  assert.equal(blank.ok && blank.workspace, "server-ws");
+  assert.equal(resolveWorkspace("", "  ").ok, false);
+  const trimmed = resolveWorkspace(" acme ", undefined);
+  assert.equal(trimmed.ok && trimmed.workspace, "acme");
+});

package/src/wire-identity.ts

@@ -0,0 +1,64 @@
+// Pure identity resolution for the full wire: the per-project API-key env var name and the
+// workspace used in the skill template.
+//
+// Kept in a tiny side-effect-free module (not wire.ts) so unit tests can import it — wire.ts
+// runs main() at module top level and must never be imported by a test (see posix-env.ts /
+// bin/petbox-wire.js for the same reasoning).
+
+import { WIRE_EXIT } from "./wire-exit.ts";
+
+// Canonical env-var name for a project key. MUST stay byte-identical to the server's EnvSlug
+// (PetBox.Web/Pages/Admin/ProjectConnect.cshtml.cs), which is what the Connect page shows an
+// operator to paste: uppercase, every run of non-alphanumerics collapsed to a single "_",
+// leading/trailing "_" trimmed, wrapped in PETBOX_…_API_KEY.
+//
+//   "$system" → "PETBOX_SYSTEM_API_KEY"   (not "_SYSTEM_API_KEY": the leading "$" is trimmed)
+//   "kpvotes" → "PETBOX_KPVOTES_API_KEY"
+//
+// This is only the DEFAULT for a fresh wire. An already-wired directory keeps the env-var name
+// recorded in ~/.petbox/projects.json (registryEnvVar in wire.ts wins over this), and --env
+// overrides both — so changing this name never orphans an existing machine's keys.json entry.
+export function deriveEnvVar(projectKey: string): string {
+  // Same operation ORDER as EnvSlug: sanitise+trim first, uppercase last. Uppercasing first would
+  // diverge on non-ASCII letters that case-fold into ASCII (C#: "ı" → "_", uppercase-first: "I").
+  const slug = projectKey
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toUpperCase();
+  return `PETBOX_${slug}_API_KEY`;
+}
+
+export type WorkspaceResolution =
+  | { ok: true; workspace: string; source: "flag" | "server" }
+  | { ok: false; message: string; exitCode: number };
+
+const nonEmpty = (v: string | undefined | null): string | undefined => {
+  const s = typeof v === "string" ? v.trim() : "";
+  return s.length > 0 ? s : undefined;
+};
+
+// Workspace for the skill template's {{WORKSPACE}}. Resolution order:
+//   1. --workspace WS                       (explicit operator override)
+//   2. the `workspace` field of GET /api/auth/validate (the server owns this)
+//   3. hard fail, exit 2 (usage) — NEVER a hardcoded personal workspace.
+// An old server that predates the `workspace` field simply reports none → case 3, a clear
+// actionable usage error rather than a crash or a silent wrong default.
+export function resolveWorkspace(
+  flag: string | undefined,
+  serverWorkspace: string | undefined,
+): WorkspaceResolution {
+  const fromFlag = nonEmpty(flag);
+  if (fromFlag) return { ok: true, workspace: fromFlag, source: "flag" };
+
+  const fromServer = nonEmpty(serverWorkspace);
+  if (fromServer) return { ok: true, workspace: fromServer, source: "server" };
+
+  return {
+    ok: false,
+    exitCode: WIRE_EXIT.usage,
+    message:
+      "--workspace is required: this server did not report a workspace.\n" +
+      "  GET /api/auth/validate returned no `workspace` field (an older PetBox server).\n" +
+      "  Re-run with --workspace <WS> (the workspace the project belongs to), or upgrade the server.",
+  };
+}