@rtrentjones/greenlight 0.2.15 → 0.2.17

package/assets/skills/deploy-verify-promote/SKILL.md

@@ -1,53 +1,72 @@
 ---
 name: deploy-verify-promote
-description: Ship a change through Greenlight's loop — deploy to preview/beta, verify with the shared harness, then gated-promote develop→main to prod. Use when making a change to a Greenlight tool or the blog and you want it shipped with confidence, or when explicitly asked to deploy/verify/promote.
+description: The one model for delivering a feature to ANY Greenlight tool — local-gate (preview) → add it to the verify loop → ship (gated on the tool's own tests) → verify prod. Same shape for blog (workers), web apps (vercel), and MCP servers (oci); only the matrix cells vary. Use when changing a Greenlight tool or the blog and you want it shipped with objective confidence, or when asked to deploy/verify/promote.
 ---
 
-# deploy-verify-promote
+# deploy-verify-promote — one loop for every tool
 
-The execution discipline for changing a Greenlight tool or the blog. The verify
-harness and promote guard are the **same code CI runs**, so passing locally means
-passing in CI. This is what lets a change (or a long string of changes) be shipped
-with objective confidence rather than vibes.
+The execution discipline for delivering a feature to **any** Greenlight tool. The verify harness and
+promote guard are the **same code CI runs**, so passing locally means passing in CI. This is what
+lets a change (or a long autonomous string of changes) ship with objective confidence, not vibes.
 
-## Input
+**One shape, every tool** — only the matrix cells differ (never the steps):
 
-- `<name>` — a manifest entry: `blog`, or a tool name from `greenlight.config.ts`.
+```
+branch → change → LOCAL GATE (greenlight preview) → ADD IT TO THE VERIFY LOOP (the tool's
+  verify.config) → SHIP (push; CI gates on the tool's own tests) → DEPLOY → VERIFY PROD
+```
 
-## Deterministic URL scheme (never scrape deploy logs)
+## Input
+- `<name>` — a manifest entry: `blog`, or a tool from `greenlight.config.ts`.
 
-| Subject | prod | beta |
-|---|---|---|
-| tool | `https://<name>.<domain>` | `https://beta.<name>.<domain>` |
-| blog (apex) | `https://<domain>` | `https://beta.<domain>` |
-| mcp connect | *(tool url)* `+ /mcp` | same `+ /mcp` |
+## The matrix (what varies by lane×target — look up your tool, then follow the one procedure)
 
-`preview` is per-target and comes from the adapter's `deploy()` result. Everything
-else is computed by `resolveUrl` in `@rtrentjones/greenlight-shared`.
+| lane×target | local gate (`preview`) | ship trigger | beta? / promote? | deploy | verify mode | verify config lives | code repo |
+|---|---|---|---|---|---|---|---|
+| astro/workers (blog) | build + `pnpm preview` | push `develop`/`main` | **yes / yes** | wrangler | api(+playwright) | `<dir>/verify.config.ts` | same repo |
+| next/vercel (web app) | `preview` descriptor / build | git push (Vercel) | **yes (preview) / yes** | Vercel git-integration | api/agent-web/test | tool repo `verify/<name>.config.ts` | cross-repo (submodule) |
+| mcp/oci (MCP server) | `preview` descriptor (docker `/mcp`) | push → build → dispatch | **no / no** (direct-to-prod) | restart instance | mcp(+eval) | wrapper `verify/<name>.config.ts` | cross-repo (submodule) |
+| mcp/workers (dev) | `pnpm start` `/mcp` | push | yes / yes | wrangler | mcp | `<dir>/verify.config.ts` | same repo |
 
-## Procedure
+Two axes cause all the variation:
+- **Standing beta + promote** (web: a cheap preview/beta exists → verify beta, then gated FF
+  `develop→main`) vs **direct-to-prod, verify-gated** (oci: no beta on the free tier → the
+  **local gate + the ship-gate are your pre-prod safety**; deploy restarts prod, then verify prod).
+- **Same-repo** vs **cross-repo adopted** (the tool's code is a `tools/<name>` submodule; its infra
+  + verify config live in the **wrapper**; you edit both and **bump the submodule pointer**).
 
-1. **Branch** — `git checkout -b <type>/<slug>` (e.g. `post/hello`, `fix/mcp-auth`).
-2. **Make the change.**
-3. **Preview** — push; the target's git integration produces a preview deploy. Verify it.
-   - Local/CI: `runLoop` (build → deploy → verify) from `@rtrentjones/greenlight-loop`.
-   - Standalone / local server: `pnpm greenlight verify <name> --url <preview-or-localhost-url>`.
-4. **Beta** — merge to `develop` → beta deploy. `pnpm greenlight verify <name> --env beta`.
-   Mode is chosen by lane: `api`/`playwright` for web, `mcp` for MCP servers.
-5. **Promote** — `pnpm greenlight promote <name>`. Checks the fast-forward guard
-   (`develop → main`). If it refuses (diverged `main`), reconcile and retry — never force-push.
-6. **Prod** — after promote, `pnpm greenlight verify <name> --env prod`.
+## Procedure (identical for every tool)
 
-## Rules
+1. **Branch** in the tool's code repo — `git checkout -b <type>/<slug>` (`feat/new-tool`, `fix/auth`).
+2. **Make the change** (+ the tool's own tests — they become the ship-gate in step 4).
+3. **LOCAL GATE** — `pnpm greenlight preview <name>`: spins the tool up locally (matching its prod
+   contract) and runs the verify harness against it. Green here = your pre-prod signal (essential for
+   direct-to-prod oci, which has no beta). `preview` sets `GREENLIGHT_PREVIEW=1` so a config can pick
+   a local-appropriate spec (e.g. skip an auth-rejection a local no-auth server can't satisfy).
+4. **ADD IT TO THE VERIFY LOOP** — edit the tool's `verify.config.ts` (location per the matrix) so
+   the new capability is asserted: add the tool to `expectTools` (mcp; `exactTools: true` makes a
+   forgotten entry fail the gate), a `check`/`renders`/`suite` (web), or an `eval` case (quality).
+5. **SHIP** — push. CI **gates on the tool's own tests** before anything deploys (container build
+   `needs: [test]`; vercel via `deployment_status`; workers via deploy→verify). A broken change never
+   reaches prod.
+6. **DEPLOY + VERIFY PROD** —
+   - **web (beta+promote):** merge to `develop` → beta; `greenlight verify <name> --env beta`; then
+     `greenlight promote <name>` (gated FF `develop→main` — never force-push); `verify --env prod`.
+   - **oci (direct-to-prod):** the push builds → dispatches → the wrapper restarts the instance →
+     `greenlight verify <name> --env prod` runs automatically as the deploy gate.
+7. **Watch** — `pnpm greenlight status <name>` shows the last build/deploy/verify run across repos.
 
-- `verify` exits non-zero if any check fails; the report lists each. **Never promote a
-  tool whose beta verify is failing.**
+## Rules
+- `verify` exits non-zero if any check fails; the report lists each. **Never promote/ship a tool
+  whose verify is failing.**
+- **Always run the local gate (step 3) before pushing a direct-to-prod (oci) tool** — there is no
+  beta to catch a bad image; the deploy restarts prod.
+- Cross-repo: commit the tool change in its submodule AND bump the submodule pointer in the wrapper;
+  the verify config + infra are the **wrapper's** to edit.
 - Connect URL for MCP tools is the tool URL + `/mcp`; `verify` handles this by lane.
-- Real per-target deploys are wired in phases (greenlight-v1.md §16); the loop, verify,
-  and promote guard are stable now.
+- `greenlight doctor` flags any tool drifting from this model (no verify spec, no local preview gate).
 
 ## Cross-repo note
-
-In standalone repos (BAMCP, ejected tools) this skill is delivered by the **Greenlight
-Claude Code plugin** (Phase 7), and the mechanics by the `@rtrentjones/greenlight*` npm
-deps; the per-repo parameters come from that repo's `greenlight.config.ts`.
+In adopted/standalone repos (BAMCP, ejected tools) this skill is delivered by the **Greenlight
+Claude Code plugin** and the mechanics by the `@rtrentjones/greenlight*` npm deps; the per-repo
+parameters come from that repo's (or the wrapper's) `greenlight.config.ts`.

package/dist/bin.js

@@ -5,8 +5,8 @@ import {
   loadConfig,
   resolveUrl,
   verifyAll
-} from "./chunk-AL6IKVZE.js";
-import "./chunk-ADS6BJJ5.js";
+} from "./chunk-6USV5AQV.js";
+import "./chunk-HX7VA25D.js";
 import "./chunk-N3IKUCSF.js";
 import "./chunk-KP3Y6WRU.js";
 import "./chunk-UXHHLEYO.js";
@@ -49,6 +49,15 @@ function serializeTool(t) {
   if (t.dir !== void 0) parts.push(`dir: ${q(t.dir)}`);
   if (t.adopted) parts.push("adopted: true");
   if (t.external) parts.push("external: true");
+  if (t.port !== void 0) parts.push(`port: ${t.port}`);
+  if (t.preview) {
+    const pv = t.preview;
+    const pvParts = [`command: ${q(pv.command)}`];
+    if (pv.teardown !== void 0) pvParts.push(`teardown: ${q(pv.teardown)}`);
+    if (pv.port !== void 0) pvParts.push(`port: ${pv.port}`);
+    if (pv.path !== void 0) pvParts.push(`path: ${q(pv.path)}`);
+    parts.push(`preview: { ${pvParts.join(", ")} }`);
+  }
   return `    { ${parts.join(", ")} },`;
 }
 function serializeConfig(c) {
@@ -93,7 +102,8 @@ function addTool(config, t) {
         ...t.dir !== void 0 ? { dir: t.dir } : {},
         ...t.adopted ? { adopted: true } : {},
         ...t.external ? { external: true } : {},
-        ...t.port !== void 0 ? { port: t.port } : {}
+        ...t.port !== void 0 ? { port: t.port } : {},
+        ...t.preview ? { preview: t.preview } : {}
       }
     ]
   };
@@ -118,7 +128,8 @@ function upsertTool(config, t) {
     ...t.dir !== void 0 ? { dir: t.dir } : {},
     ...t.adopted ? { adopted: true } : {},
     ...t.external ? { external: true } : {},
-    ...t.port !== void 0 ? { port: t.port } : {}
+    ...t.port !== void 0 ? { port: t.port } : {},
+    ...t.preview ? { preview: t.preview } : {}
   };
   const tools = config.tools.some((x) => x.name === t.name) ? config.tools.map((x) => x.name === t.name ? entry : x) : [...config.tools, entry];
   const result = ConfigSchema.safeParse({ ...config, tools });
@@ -173,7 +184,9 @@ function resolveEntry(config, name) {
     target: tool.target,
     data: tool.data,
     dir: tool.dir ?? `tools/${tool.name}`,
-    external: tool.external
+    external: tool.external,
+    port: tool.port,
+    preview: tool.preview
   };
 }
 var VERIFY_MODES = /* @__PURE__ */ new Set(["api", "mcp", "playwright", "test", "agent-web", "eval"]);
@@ -413,7 +426,7 @@ function tokensForTool(tool) {
 }
 
 // src/version.ts
-var MODULE_REF = "v0.2.15";
+var MODULE_REF = "v0.2.17";
 var MODULE_SOURCE_BASE = "git::https://github.com/RTrentJones/greenlight.git//infra/modules";
 function moduleSource(module, ref = MODULE_REF) {
   return `${MODULE_SOURCE_BASE}/${module}?ref=${ref}`;
@@ -679,11 +692,15 @@ function mergeMcpServers(existing, add) {
 // src/commands/agent.ts
 var CLAUDE_BLOCK = `## Greenlight loop (deploy \u2192 verify \u2192 promote)
 
-This repo uses Greenlight. Ship changes through the deploy-verify-promote skill:
-branch \u2192 change \u2192 deploy preview \u2192 \`greenlight verify\` \u2192 beta \u2192 verify \u2192 \`greenlight promote\` \u2192 prod \u2192 verify.
+This repo uses Greenlight. Deliver every change through the ONE model (same shape for web + MCP
+tools \u2014 the deploy-verify-promote skill has the lane\xD7target matrix):
+branch \u2192 change \u2192 \`greenlight preview <name>\` (local gate) \u2192 add it to the tool's verify.config \u2192
+push (CI gates on the tool's own tests) \u2192 deploy \u2192 \`greenlight verify <name> --env prod\`.
+Web tools also get beta + \`greenlight promote\`; oci is direct-to-prod (the local gate is the
+pre-prod safety). \`greenlight status <name>\` shows the run chain; \`greenlight doctor\` flags drift.
 
 Agentic kit:
-- Skill: \`.claude/skills/deploy-verify-promote/SKILL.md\` (the loop).
+- Skill: \`.claude/skills/deploy-verify-promote/SKILL.md\` (the one model + the matrix).
 - MCP servers: \`.mcp.json\` recommends the relevant providers \u2014 run \`/mcp\` to authenticate.
     Vercel is OAuth; Supabase needs \`SUPABASE_ACCESS_TOKEN\` (+ \`SUPABASE_PROJECT_REF\`) in your env.
 - Best-practice skills (one-time, user scope):
@@ -1104,12 +1121,36 @@ function vendorDeps(vendorDir) {
   }
   return out;
 }
-function starterVerifyConfig(lane, target) {
-  const spec = lane === "mcp" ? "mode: 'mcp', expectTools: []" : "mode: 'api', checks: [{ path: '/', status: 200 }]";
-  const logHint = target === "vercel" ? 'vercel logs "$GREENLIGHT_VERIFY_URL" --token "$VERCEL_API_TOKEN" 2>&1 | head -40 || true' : 'curl -sS -i "$GREENLIGHT_VERIFY_URL" 2>&1 | head -30 || true';
+function starterVerifyConfig(lane, _target) {
+  const logHint = 'curl -sS -i "$GREENLIGHT_VERIFY_URL" 2>&1 | head -30 || true';
+  if (lane === "mcp") {
+    return `// Greenlight verify spec \u2014 edit to assert this tool's real contract.
+// \`greenlight preview\` sets GREENLIGHT_PREVIEW=1 (local run, usually no auth); prod runs the full gate.
+const preview = process.env.GREENLIGHT_PREVIEW === '1';
+
+export default [
+  {
+    mode: 'mcp',
+    // List the tools this server exposes. exactTools makes the gate FAIL if a tool is added in code
+    // but not here (or removed) \u2014 so "added to the verify loop" is enforced, not optional.
+    expectTools: [],
+    exactTools: true,
+    // Auth-gated server? Require an unauthenticated request to be rejected \u2014 but not under preview
+    // (a local no-auth server can't satisfy it). Add headers:{ Authorization: \`Bearer \${process.env.X}\` }
+    // to run authenticated tools/list against prod.
+    // requireAuthRejection: !preview,
+    // logsOnFailure: '${logHint}',
+  },
+  // Quality (optional): LLM-judged tool output. Runs only with ANTHROPIC_API_KEY (degrades to a
+  // failing check otherwise). Add cases:
+  // { mode: 'eval', cases: [{ name: 'sensible', tool: 'your_tool', rubric: 'what good looks like' }] },
+];
+`;
+  }
   return `// Greenlight verify spec \u2014 edit to assert this tool's real contract.
 export default {
-  ${spec},
+  mode: 'api',
+  checks: [{ path: '/', status: 200 }],
   // Telemetry-into-verify: a shell command run ONLY when this report FAILS; its last ~50 lines
   // attach to the report so the agent/CI sees the "why" in-loop. $GREENLIGHT_VERIFY_URL is the
   // failing URL (no hard-coding). Best-effort (never fails the gate). Uncomment + adjust:
@@ -1251,12 +1292,13 @@ var MISE_TOML = `# Toolchain, managed by mise. \`mise install\` to set up.
 node = "24"
 pnpm = "10.12.1"
 `;
-function containerBuildYml(name, wrapperRepo) {
+function containerBuildYml(name, wrapperRepo, testCommand = "make install && make test") {
   return `name: greenlight-build
 
-# Provider-agnostic: build the container -> push to GHCR -> notify the wrapper to deploy.
-# The wrapper owns the OCI infra + creds; this repo only needs GREENLIGHT_DISPATCH_TOKEN
-# (a fine-grained PAT with "Contents: write" on ${wrapperRepo}) to fire the dispatch.
+# Provider-agnostic: TEST -> build the container -> push to GHCR -> notify the wrapper to deploy.
+# The ship is GATED on the tool's own tests (build \`needs: [test]\`). The wrapper owns the OCI infra
+# + creds; this repo only needs GREENLIGHT_DISPATCH_TOKEN (a fine-grained PAT with "Contents: write"
+# on ${wrapperRepo}) to fire the dispatch.
 on:
   push:
     branches: [main]
@@ -1271,7 +1313,16 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  test:
+    # Ship-gate: the tool's own tests must pass before anything is built or deployed. Customize the
+    # command + add the toolchain setup your tests need (setup-node / setup-python / mise) here.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ${testCommand}
+
   build:
+    needs: [test]
     # Native arm64 runner \u2014 builds the arm64 image directly (no QEMU emulation, much faster).
     runs-on: ubuntu-24.04-arm
     steps:
@@ -1584,7 +1635,18 @@ async function adoptWrapper(ctx) {
     envs,
     dir: toolRel,
     external: true,
-    adopted: true
+    adopted: true,
+    // oci has no built-in local serve — scaffold a `preview` descriptor so the uniform local gate
+    // (`greenlight preview <name>`) works. Default: a docker `preview` profile matching the prod
+    // transport (the tool adds that profile to its compose). Edit the command/port/path to fit.
+    ...target === "oci" ? {
+      preview: {
+        command: "docker compose --profile preview up",
+        teardown: "docker compose --profile preview down -v",
+        port: 8e3,
+        path: lane === "mcp" ? "/mcp" : ""
+      }
+    } : {}
   });
   writeFileSync3(regPath, serializeConfig(nextReg));
   console.log(
@@ -1892,6 +1954,25 @@ import { join as join4 } from "path";
 function dirCheck(label, dir) {
   return existsSync7(dir) ? { name: `${label}: directory`, status: "ok" } : { name: `${label}: directory`, status: "fail", detail: `missing ${dir}` };
 }
+function conformanceChecks(t, root) {
+  const out = [];
+  const specRel = t.external ? `verify/${t.name}.config.ts` : join4(t.dir ?? join4("tools", t.name), "verify.config.ts");
+  const hasSpec = existsSync7(join4(root, specRel));
+  out.push({
+    name: `${t.name}: in the verify loop`,
+    status: hasSpec ? "ok" : "warn",
+    detail: hasSpec ? specRel : `no ${specRel} \u2014 verify falls back to the lane default`
+  });
+  const builtIn = !t.external && t.target === "workers";
+  const platformPreview = t.target === "vercel";
+  const gateable = Boolean(t.preview) || builtIn || platformPreview;
+  out.push({
+    name: `${t.name}: local preview gate`,
+    status: gateable ? "ok" : "warn",
+    detail: platformPreview ? "vercel per-PR preview + deployment_status verify" : gateable ? void 0 : `no built-in serve for ${t.external ? "an external " : ""}${t.target} tool \u2014 add preview:{ command, \u2026 } so \`greenlight preview ${t.name}\` works`
+  });
+  return out;
+}
 function runDoctor(config, root) {
   const checks = [];
   if (config.blog) checks.push(dirCheck("blog", join4(root, "apps/blog")));
@@ -1904,18 +1985,10 @@ function runDoctor(config, root) {
         mcp: t.lane === "mcp"
       });
       checks.push({ name: `${t.name}: external (registry)`, status: "ok", detail: url });
-      continue;
-    }
-    const dir = join4(root, t.dir ?? join4("tools", t.name));
-    checks.push(dirCheck(t.name, dir));
-    if (t.lane === "mcp") {
-      const vc = join4(dir, "verify.config.ts");
-      checks.push({
-        name: `${t.name}: verify.config.ts`,
-        status: existsSync7(vc) ? "ok" : "warn",
-        detail: existsSync7(vc) ? void 0 : "missing \u2014 verify will use the lane default"
-      });
+    } else {
+      checks.push(dirCheck(t.name, join4(root, t.dir ?? join4("tools", t.name))));
     }
+    checks.push(...conformanceChecks(t, root));
   }
   const needsKeepalive = config.tools.filter((t) => t.data === "supabase" || t.target === "oci");
   checks.push({
@@ -2356,18 +2429,57 @@ async function waitForServer(url, timeoutMs = 3e4) {
   }
   return false;
 }
-async function previewCommand(args) {
-  const name = args[0];
-  if (!name || name.startsWith("-")) {
-    throw new Error("usage: greenlight preview <name> [--port <n>]");
-  }
-  const portArg = flag7(args, "--port");
-  const { config } = await loadManifest();
-  const entry = resolveEntry(config, name);
-  if (entry.external) {
-    throw new Error(`"${name}" is external (registry pointer) \u2014 preview it from its own repo`);
+async function loadSpecs(entry) {
+  const loaded = (entry.external && entry.name ? await loadExternalVerifySpec(entry.name) : await loadVerifySpec(entry.dir)) ?? defaultSpec(entry.lane);
+  return Array.isArray(loaded) ? loaded : [loaded];
+}
+async function verifyLocal(entry, url) {
+  process.env.GREENLIGHT_PREVIEW = "1";
+  process.env.GREENLIGHT_VERIFY_URL = url;
+  const specs = await loadSpecs(entry);
+  const toolDir = resolve10(process.cwd(), entry.dir ?? ".");
+  const reports = await verifyAll(url, specs, { toolDir });
+  for (const report of reports) printReport(report);
+  return allPass(reports);
+}
+async function previewViaDescriptor(entry, name, portOverride) {
+  const pv = entry.preview;
+  const lane = servePlan(entry.lane);
+  const port = portOverride ?? pv.port ?? entry.port ?? lane.port;
+  const path = pv.path ?? lane.path;
+  const url = `http://localhost:${port}${path}`;
+  const toolDir = resolve10(process.cwd(), entry.dir ?? ".");
+  console.log(`preview ${name}: ${pv.command}  (\u2192 ${url})`);
+  const child = spawn(pv.command, {
+    cwd: toolDir,
+    shell: true,
+    stdio: "inherit",
+    detached: true,
+    env: { ...process.env, PORT: String(port), GREENLIGHT_PREVIEW: "1" }
+  });
+  try {
+    if (!await waitForServer(url, 12e4)) {
+      throw new Error(`preview server did not become reachable at ${url} (check: ${pv.command})`);
+    }
+    return await verifyLocal(entry, url);
+  } finally {
+    if (pv.teardown) {
+      try {
+        execFileSync4(pv.teardown, { cwd: toolDir, shell: true, stdio: "inherit" });
+      } catch {
+      }
+    }
+    if (child.pid) {
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {
+        child.kill("SIGTERM");
+      }
+    }
   }
-  const plan = servePlan(entry.lane, portArg ? Number(portArg) : void 0);
+}
+async function previewViaBuiltIn(entry, name, portOverride) {
+  const plan = servePlan(entry.lane, portOverride);
   if (plan.build) {
     console.log(`build ${name} (${entry.dir})`);
     execFileSync4("pnpm", ["-C", entry.dir, "run", "build"], { stdio: "inherit" });
@@ -2380,7 +2492,6 @@ async function previewCommand(args) {
     stdio: "ignore",
     detached: true
   });
-  let pass = false;
   try {
     const base = `http://localhost:${plan.port}`;
     if (!await waitForServer(base)) {
@@ -2388,12 +2499,7 @@ async function previewCommand(args) {
         `server did not start on :${plan.port} (check the tool's ${plan.script} script)`
       );
     }
-    const loaded = await loadVerifySpec(entry.dir) ?? defaultSpec(entry.lane);
-    const specs = Array.isArray(loaded) ? loaded : [loaded];
-    const toolDir = resolve10(process.cwd(), entry.dir ?? ".");
-    const reports = await verifyAll(base + plan.path, specs, { toolDir });
-    for (const report of reports) printReport(report);
-    pass = allPass(reports);
+    return await verifyLocal(entry, base + plan.path);
   } finally {
     if (child.pid) {
       try {
@@ -2403,6 +2509,26 @@ async function previewCommand(args) {
       }
     }
   }
+}
+async function previewCommand(args) {
+  const name = args[0];
+  if (!name || name.startsWith("-")) {
+    throw new Error("usage: greenlight preview <name> [--port <n>]");
+  }
+  const portArg = flag7(args, "--port");
+  const port = portArg ? Number(portArg) : void 0;
+  const { config } = await loadManifest();
+  const entry = resolveEntry(config, name);
+  let pass;
+  if (entry.preview) {
+    pass = await previewViaDescriptor(entry, name, port);
+  } else if (entry.external) {
+    throw new Error(
+      `"${name}" is external and has no preview descriptor \u2014 add preview:{ command, \u2026 } to its manifest entry (e.g. a docker command), or preview it from its own repo`
+    );
+  } else {
+    pass = await previewViaBuiltIn(entry, name, port);
+  }
   process.exit(pass ? 0 : 1);
 }
 
@@ -2482,6 +2608,86 @@ async function promoteCommand(args) {
   process.exit(result.promoted ? 0 : 1);
 }
 
+// src/commands/status.ts
+import { execFileSync as execFileSync6 } from "child_process";
+function repoSlug(dir) {
+  try {
+    const url = execFileSync6("git", ["-C", dir, "remote", "get-url", "origin"], {
+      encoding: "utf8"
+    }).trim();
+    const m = url.match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+    return m?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+function workflowsFor(entry, name, wrapper, toolRepo) {
+  if (!entry.external) {
+    return [{ repo: wrapper, workflow: "deploy.yml", label: "deploy + verify" }];
+  }
+  if (entry.target === "oci") {
+    return [
+      {
+        repo: toolRepo,
+        workflow: "greenlight-build.yml",
+        label: "build (test \u2192 image \u2192 dispatch)"
+      },
+      { repo: wrapper, workflow: `greenlight-deploy-${name}.yml`, label: "deploy + verify (prod)" },
+      { repo: wrapper, workflow: `greenlight-remediate-${name}.yml`, label: "self-heal" }
+    ];
+  }
+  if (entry.target === "vercel") {
+    return [
+      { repo: toolRepo, workflow: "greenlight-verify.yml", label: "verify (deployment_status)" }
+    ];
+  }
+  return [{ repo: toolRepo, workflow: "deploy.yml", label: "deploy + verify" }];
+}
+function lastRun(repo, workflow) {
+  try {
+    const out = execFileSync6(
+      "gh",
+      [
+        "run",
+        "list",
+        "--repo",
+        repo,
+        "--workflow",
+        workflow,
+        "--limit",
+        "1",
+        "--json",
+        "status,conclusion,displayTitle,url"
+      ],
+      { encoding: "utf8" }
+    );
+    const runs = JSON.parse(out);
+    const r = runs[0];
+    if (!r) return "no runs";
+    const state = r.status === "completed" ? r.conclusion : r.status;
+    const icon = state === "success" ? "\u2714" : state === "failure" ? "\u2718" : "\xB7";
+    return `${icon} ${state}  ${r.displayTitle}
+    ${r.url}`;
+  } catch (e) {
+    return `(gh unavailable \u2014 ${e instanceof Error ? e.message.split("\n")[0] : "error"})`;
+  }
+}
+async function statusCommand(args) {
+  const name = args[0];
+  if (!name || name.startsWith("-")) throw new Error("usage: greenlight status <name>");
+  const { config } = await loadManifest();
+  const entry = resolveEntry(config, name);
+  const wrapper = repoSlug(process.cwd()) ?? "(this repo)";
+  const toolRepo = entry.external ? repoSlug(entry.dir) ?? "(tool repo)" : wrapper;
+  console.log(`status: ${name} (${entry.lane}/${entry.target})
+`);
+  for (const w of workflowsFor(entry, name, wrapper, toolRepo)) {
+    console.log(`  ${w.label}  [${w.repo} \xB7 ${w.workflow}]`);
+    console.log(`    ${lastRun(w.repo, w.workflow)}
+`);
+  }
+}
+
 // src/bin.ts
 var HELP = `greenlight <command>
 
@@ -2492,6 +2698,7 @@ var HELP = `greenlight <command>
   preview <name> [--port <n>]                   build + serve locally + verify (one command)
   verify <name> [--env <env> | --url <url>]     run the verify harness against the URL
   promote <name> [--perform] [--push]           gated develop -> main fast-forward
+  status <name>                                 last ship/deploy/verify run for a tool (via gh)
   secrets gather <name> [--repo o/r] [--env e]  guided, link-first token prompts -> GitHub secrets (no disk/logs)
   secrets sync [--repo o/r] [--env <env>]       push .greenlight/secrets.env -> GitHub Actions secrets
   agent sync                                    write the loop skill + CLAUDE.md block into this repo
@@ -2523,6 +2730,8 @@ async function main() {
       return verifyCommand(args);
     case "promote":
       return promoteCommand(args);
+    case "status":
+      return statusCommand(args);
     case "secrets":
       return secretsCommand(args);
     case "agent":

package/dist/{chunk-AL6IKVZE.js → chunk-6USV5AQV.js}

@@ -42,7 +42,21 @@ var ToolSchema = z.object({
   dir: z.string().optional(),
   // The tool's code lives in another repo — this entry is a registry pointer only,
   // not built/deployed here (greenlight-v1.md §15.5 poly-repo).
-  external: z.boolean().default(false)
+  external: z.boolean().default(false),
+  // How `greenlight preview` spins the tool up LOCALLY for the pre-deploy gate. Optional — node
+  // lanes (astro/next/mcp→workers) use the built-in build+serve path. Set it for targets with no
+  // built-in serve (e.g. oci: a docker command that matches the prod transport). The harness polls
+  // the local URL (http://localhost:<port><path>), verifies, then runs `teardown`.
+  preview: z.object({
+    command: z.string(),
+    // spin up locally in the background (e.g. a `docker compose … up`)
+    teardown: z.string().optional(),
+    // tear down afterwards (e.g. `docker compose … down`)
+    port: z.number().int().positive().optional(),
+    // local port (default: tool.port ?? lane default)
+    path: z.string().optional()
+    // connect path (default: lane default, e.g. `/mcp`)
+  }).optional()
 }).superRefine((tool, ctx) => {
   const rule = MATRIX[tool.lane];
   if (!rule.targets.includes(tool.target)) {
@@ -229,7 +243,7 @@ async function verify(baseUrl, spec, opts) {
     case "api":
       return verifyApi(baseUrl, spec);
     case "mcp": {
-      const { verifyMcp: verifyMcp2 } = await import("./mcp-3L6HJ6BH.js");
+      const { verifyMcp: verifyMcp2 } = await import("./mcp-FFLOX4YP.js");
       return verifyMcp2(baseUrl, spec);
     }
     case "playwright": {

package/dist/{chunk-ADS6BJJ5.js → chunk-HX7VA25D.js}

@@ -32,6 +32,20 @@ async function verifyMcp(baseUrl, spec) {
         detail: has ? void 0 : `got [${names.join(", ")}]`
       });
     }
+    if (spec.exactTools) {
+      const expected = new Set(spec.expectTools);
+      const extra = names.filter((n) => !expected.has(n));
+      const missing = spec.expectTools.filter((t) => !names.includes(t));
+      const drift = [
+        extra.length ? `unexpected: [${extra.join(", ")}]` : "",
+        missing.length ? `missing: [${missing.join(", ")}]` : ""
+      ].filter(Boolean).join("; ");
+      checks.push({
+        name: "tools/list matches expectTools exactly",
+        pass: drift.length === 0,
+        detail: drift || void 0
+      });
+    }
   } catch (e) {
     checks.push({ name: "tools/list", pass: false, detail: msg(e) });
   }

package/dist/index.js

@@ -2,8 +2,8 @@ import {
   defineConfig,
   defineVerify,
   loadConfig
-} from "./chunk-AL6IKVZE.js";
-import "./chunk-ADS6BJJ5.js";
+} from "./chunk-6USV5AQV.js";
+import "./chunk-HX7VA25D.js";
 import "./chunk-N3IKUCSF.js";
 import "./chunk-KP3Y6WRU.js";
 import "./chunk-UXHHLEYO.js";

package/dist/{mcp-3L6HJ6BH.js → mcp-FFLOX4YP.js}

@@ -1,6 +1,6 @@
 import {
   verifyMcp
-} from "./chunk-ADS6BJJ5.js";
+} from "./chunk-HX7VA25D.js";
 import "./chunk-QFKE5JKC.js";
 export {
   verifyMcp

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtrentjones/greenlight",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Greenlight CLI — setup and lifecycle for the harness.",
   "license": "MIT",
   "repository": {
@@ -31,9 +31,9 @@
     "@anthropic-ai/sdk": "^0.69.0"
   },
   "devDependencies": {
-    "@rtrentjones/greenlight-shared": "0.2.4",
-    "@rtrentjones/greenlight-loop": "0.2.4",
     "@rtrentjones/greenlight-adapters": "0.2.4",
+    "@rtrentjones/greenlight-loop": "0.2.4",
+    "@rtrentjones/greenlight-shared": "0.2.4",
     "@rtrentjones/greenlight-verify": "0.2.4"
   },
   "scripts": {