premanmcp 0.7.0 → 0.8.0

package/bin/verify.js

@@ -0,0 +1,701 @@
+/**
+ * `preman verify` — run the endpoint suite against the developer's own app.
+ *
+ * This is the local half of the loop. Because the target is loopback and therefore
+ * disposable, mutating verbs are allowed here in a way they can never be against
+ * production. Results upload to the Pulse run store, which is the same store
+ * `preman status` reads, so a local run is visible to the whole team.
+ *
+ * There are two ways to run. When the files a push touches can be determined,
+ * the backend scans them, diffs them against the saved baseline, and returns
+ * real generated cases — so the push that changes an endpoint is the push that
+ * tests it, including the endpoint that is too new to be in the inventory. When
+ * that is not possible (not a git repo, no diff, backend older than this CLI)
+ * it falls back to an availability sweep of the saved inventory. Degrading is
+ * the point: a hook that tests less is fine, a hook that fails is not.
+ *
+ * In `--pre-push` mode this command is advisory: every failure path exits 0
+ * unless the repository has explicitly opted into blocking.
+ */
+
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { changedFilesForPush, readChangedFiles, readPushRefsFromStdin, repoRoot } from "./changed.js";
+import { resolveLocalTarget } from "./detect.js";
+import { createReporter } from "./progress.js";
+import { backendUrl, callBackendJson, cliInvocation, makeArgs, resolveApiKey } from "./shared.js";
+
+export const VERIFY_HELP = `
+Verify options:
+  --pre-push            Advisory mode: always exit 0, used by the git hook
+  --port <port>         Add an explicit candidate port for the local target
+  --allow-writes        Include mutating methods (default on for loopback targets)
+  --read-only           Never send a mutating request, even locally
+  --all                 Sweep the whole saved inventory instead of the push diff
+  --block-on-breaking   Exit non-zero when the push breaks a changed endpoint
+  --timeout <seconds>   Overall wall-clock budget. Defaults to 120
+  --json                Print the machine-readable result
+`;
+
+const DEFAULT_TIMEOUT_SECONDS = 120;
+const REQUEST_TIMEOUT_MS = 10_000;
+const CONCURRENCY = 6;
+const READ_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+// Never fired automatically even against loopback: a destructive verb that
+// happens to point at a real datastore is not made safe by the port being local.
+const DESTRUCTIVE_METHODS = new Set(["DELETE"]);
+
+// Team-level opt-in, committed to the repo so the decision travels with it.
+const REPO_CONFIG = ".preman.json";
+
+// A deliberate block, and nothing else, uses this code. Node exits 1 on an
+// uncaught exception, so reusing 1 would turn any CLI crash into a blocked
+// push — the exact failure the advisory guarantee exists to prevent.
+export const BLOCK_EXIT_CODE = 97;
+
+function nowMs() {
+  return Number(process.hrtime.bigint() / 1000000n);
+}
+
+function originLabel() {
+  const raw = `${os.hostname() || "local"}`.toLowerCase();
+  const cleaned = raw.replace(/[^a-z0-9._-]/g, "-").replace(/^[^a-z0-9]+/, "");
+  return (cleaned || "local").slice(0, 64);
+}
+
+function fillPath(template) {
+  return String(template || "/").replace(/\{[^}]*\}/g, "1");
+}
+
+/** Availability case per endpoint. Grading happens server-side; this records what
+ *  we observed and only classifies transport-level outcomes locally. */
+async function runCase(baseUrl, endpoint, { batchId }) {
+  const method = String(endpoint.method || "GET").toUpperCase();
+  const target = `${baseUrl}${fillPath(endpoint.path_template || endpoint.path || "/")}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  const startedAt = new Date().toISOString();
+  const t0 = nowMs();
+
+  try {
+    const resp = await fetch(target, {
+      method,
+      signal: controller.signal,
+      redirect: "manual",
+      headers: { Accept: "application/json" },
+    });
+    const body = await resp.text();
+    return {
+      client_run_id: `${batchId}:${method}:${endpoint.path_template || endpoint.path}`,
+      method,
+      url: target,
+      status: resp.status >= 500 ? "failed" : "passed",
+      http_status: resp.status,
+      latency_ms: nowMs() - t0,
+      response_body: body.slice(0, 4000) || null,
+      started_at: startedAt,
+    };
+  } catch (error) {
+    const aborted = error?.name === "AbortError";
+    return {
+      client_run_id: `${batchId}:${method}:${endpoint.path_template || endpoint.path}`,
+      method,
+      url: target,
+      status: "errored",
+      http_status: null,
+      latency_ms: nowMs() - t0,
+      error_message: aborted ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : String(error?.message || error),
+      started_at: startedAt,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Grade a response against the case's own expectation.
+ *
+ * The sweep can only ask "did it 5xx", which passes a breaking change that
+ * correctly answers 422 — the single most common shape of an API regression. A
+ * generated case states what it expects, so the same 422 fails on the happy
+ * path and passes on the missing-field case.
+ */
+export function gradeCase(expect, { status, bodyText }) {
+  if (!status) return { ok: false, why: "no response" };
+  const rules = expect || {};
+
+  if (Array.isArray(rules.status_in) && rules.status_in.length) {
+    const allowed = rules.status_in.map(Number);
+    if (!allowed.includes(status)) {
+      return { ok: false, why: `expected ${allowed.join("/")}, got ${status}` };
+    }
+  } else if (rules.status_not != null) {
+    if (status === Number(rules.status_not)) return { ok: false, why: `got ${status}` };
+  } else if (status >= 500) {
+    return { ok: false, why: `got ${status}` };
+  }
+
+  if (Array.isArray(rules.required_fields) && rules.required_fields.length) {
+    let parsed = null;
+    try {
+      parsed = JSON.parse(bodyText || "");
+    } catch {
+      return { ok: false, why: "response was not JSON" };
+    }
+    const subject = Array.isArray(parsed) ? parsed[0] : parsed;
+    const missing = rules.required_fields.filter(
+      (field) => !subject || !Object.prototype.hasOwnProperty.call(subject, field)
+    );
+    if (missing.length) return { ok: false, why: `missing ${missing.join(", ")}` };
+  }
+
+  return { ok: true, why: "" };
+}
+
+/** Send one generated case and grade it. */
+async function runGeneratedCase(testCase, { batchId, endpoint }) {
+  const method = String(testCase.method || "GET").toUpperCase();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  const startedAt = new Date().toISOString();
+  const t0 = nowMs();
+
+  const headers = { Accept: "application/json", ...(testCase.headers || {}) };
+  const body = testCase.body == null ? undefined : testCase.body;
+  if (body !== undefined && !Object.keys(headers).some((k) => k.toLowerCase() === "content-type")) {
+    headers["Content-Type"] = "application/json";
+  }
+
+  try {
+    const resp = await fetch(testCase.url, {
+      method,
+      headers,
+      body,
+      signal: controller.signal,
+      redirect: "manual",
+    });
+    const text = await resp.text();
+    const verdict = gradeCase(testCase.expect, { status: resp.status, bodyText: text });
+    return {
+      client_run_id: `${batchId}:${testCase.id || `${method}:${testCase.url}`}`,
+      case_kind: testCase.kind,
+      case_name: testCase.name,
+      endpoint: `${endpoint.method} ${endpoint.path}`,
+      method,
+      url: testCase.url,
+      status: verdict.ok ? "passed" : "failed",
+      http_status: resp.status,
+      latency_ms: nowMs() - t0,
+      response_body: text.slice(0, 4000) || null,
+      error_message: verdict.ok ? undefined : verdict.why,
+      started_at: startedAt,
+    };
+  } catch (error) {
+    const aborted = error?.name === "AbortError";
+    return {
+      client_run_id: `${batchId}:${testCase.id || `${method}:${testCase.url}`}`,
+      case_kind: testCase.kind,
+      case_name: testCase.name,
+      endpoint: `${endpoint.method} ${endpoint.path}`,
+      method,
+      url: testCase.url,
+      status: "errored",
+      http_status: null,
+      latency_ms: nowMs() - t0,
+      error_message: aborted ? `timed out after ${REQUEST_TIMEOUT_MS}ms` : String(error?.message || error),
+      started_at: startedAt,
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function runPool(items, worker, limit) {
+  const results = [];
+  let cursor = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      results[index] = await worker(items[index]);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
+/**
+ * `callBackendJson` rejects on transport failure rather than returning a result,
+ * so an offline backend would throw straight past the skip handling and exit
+ * non-zero. Every backend call in this command goes through here.
+ */
+async function safeCall(args, method, routePath, options) {
+  try {
+    return await callBackendJson(args, method, routePath, options);
+  } catch (error) {
+    return { ok: false, status_code: 0, detail: String(error?.message || error), transport_error: true };
+  }
+}
+
+async function fetchInventory(args, token) {
+  const result = await safeCall(args, "POST", "/mcp/call-tool", {
+    token,
+    json: { tool: "get_endpoints", arguments: { format: "json" } },
+  });
+  if (!result.ok) return { endpoints: [], error: result.detail || `status ${result.status_code}` };
+
+  const payload = result.result ?? result.data ?? result;
+  const endpoints =
+    payload?.endpoints ||
+    payload?.result?.endpoints ||
+    (Array.isArray(payload) ? payload : []) ||
+    [];
+  return { endpoints: Array.isArray(endpoints) ? endpoints : [] };
+}
+
+function selectMethods(args) {
+  if (args.has("--read-only")) return { writes: false, reason: "--read-only" };
+  return { writes: true, reason: args.has("--allow-writes") ? "--allow-writes" : "loopback target" };
+}
+
+/**
+ * Whether a broken contract should stop this push.
+ *
+ * Default is no. The repo-level file is the intended control: blocking is a
+ * team decision, so it belongs in a committed file rather than in one
+ * developer's environment. The environment variable switches it both ways
+ * regardless, because the alternative is incoherent -- a developer who needs
+ * out today can already set PREMAN_SKIP_HOOK=1, and that is the bigger hammer:
+ * it skips the checks entirely instead of running them and reporting.
+ */
+const BLOCKING_ON = ["1", "true", "yes", "on"];
+const BLOCKING_OFF = ["0", "false", "no", "off"];
+
+/** Whether the repository committed to blocking. */
+function repoOptedIn(root) {
+  if (!root) return false;
+  try {
+    const config = JSON.parse(readFileSync(path.join(root, REPO_CONFIG), "utf8"));
+    return config?.blockOnBreaking === true;
+  } catch {
+    // No repo config, or malformed. Advisory stands.
+    return false;
+  }
+}
+
+export function blockOnBreaking(args, root) {
+  if (args.has("--block-on-breaking")) return { blocking: true, from: "--block-on-breaking" };
+
+  // Trimmed because this arrives from a .env line or a CI YAML value as often
+  // as from a shell, and " off" meaning something other than "off" is a
+  // surprise nobody would debug quickly.
+  const env = String(process.env.PREMAN_BLOCK_ON_BREAKING || "").trim().toLowerCase();
+  if (BLOCKING_ON.includes(env)) return { blocking: true, from: "PREMAN_BLOCK_ON_BREAKING" };
+  if (BLOCKING_OFF.includes(env)) {
+    // `from` stays null because nothing ends up blocking. `overrode` carries
+    // the one thing worth saying out loud -- that a gate the team committed to
+    // was switched off from an environment -- and stays null when there was no
+    // gate to switch off, so the report does not warn about nothing.
+    return { blocking: false, from: null, overrode: repoOptedIn(root) ? REPO_CONFIG : null };
+  }
+  if (repoOptedIn(root)) return { blocking: true, from: REPO_CONFIG };
+  return { blocking: false, from: null };
+}
+
+/**
+ * Ask the backend what this push changed and which cases to run.
+ *
+ * Returns null whenever a plan cannot be produced, which the caller reads as
+ * "fall back to the sweep". A backend that predates this route answers 404, and
+ * that must not be fatal — the CLI updates independently of the API.
+ */
+async function fetchPlan(args, token, { root, refs }) {
+  const { files: changedNames, reason } = changedFilesForPush(refs, { cwd: root });
+  if (!changedNames.length) return { plan: null, reason: reason || "no_changed_files" };
+
+  const { files } = readChangedFiles(changedNames, { root });
+  if (!files.length) return { plan: null, reason: "no_scannable_files", changed: changedNames.length };
+
+  const result = await safeCall(args, "POST", "/cli/prepush-plan", { token, json: { files } });
+  if (!result.ok) {
+    return { plan: null, reason: result.status_code === 404 ? "plan_unsupported" : "plan_unavailable" };
+  }
+  return { plan: result, reason: null, changed: changedNames.length };
+}
+
+export async function verifyCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+  const advisory = args.has("--pre-push");
+  if (!advisory) return runVerify(args);
+
+  // The advisory guarantee cannot depend on having enumerated every failure mode,
+  // so an unexpected throw is caught here too.
+  try {
+    return await runVerify(args);
+  } catch (error) {
+    const message = `[preman] skipped: ${String(error?.message || error)}`;
+    if (args.has("--json")) {
+      process.stdout.write(`${JSON.stringify({ state: "skipped", reason: "unexpected_error", message, exitCode: 0 }, null, 2)}\n`);
+    } else {
+      process.stderr.write(`${message}\n`);
+    }
+    return { state: "skipped", reason: "unexpected_error", exitCode: 0 };
+  }
+}
+
+/** A worker pool that tells each worker which display line it owns. */
+async function runSlottedPool(items, worker, limit) {
+  const results = [];
+  let cursor = 0;
+  const runners = Array.from({ length: Math.min(limit, items.length) }, async (_unused, slot) => {
+    while (cursor < items.length) {
+      const index = cursor++;
+      results[index] = await worker(items[index], slot);
+    }
+  });
+  await Promise.all(runners);
+  return results;
+}
+
+/** Run the generated cases the backend planned for this push. */
+async function runPlan(
+  args,
+  { plan, target, policy, token, projectId, deadline, asJson, advisory, root, changedFiles }
+) {
+  const origin = String(plan.base_url || "");
+  const retarget = (url) =>
+    origin && String(url).startsWith(origin) ? target.url + String(url).slice(origin.length) : url;
+
+  const work = [];
+  let withheld = 0;
+  for (const entry of plan.selected) {
+    for (const testCase of entry.cases) {
+      const method = String(testCase.method || "GET").toUpperCase();
+      const mutating = !READ_METHODS.has(method) || testCase.effect === "mutating";
+      if (DESTRUCTIVE_METHODS.has(method) || (mutating && !policy.writes)) {
+        withheld += 1;
+        continue;
+      }
+      work.push({ entry, testCase: { ...testCase, url: retarget(testCase.url) } });
+    }
+  }
+
+  // `undefined` defers to TTY detection. Forcing it on would write cursor
+  // escapes into every piped hook log; forcing it off would lose the animation
+  // in the terminal, which is the one place it earns its keep. Under --json the
+  // per-case lines still print, so they go to stderr: stdout has to hold the
+  // result object and nothing else for a caller piping this into a parser.
+  const reporter = createReporter({
+    stream: asJson ? process.stderr : process.stdout,
+    live: asJson ? false : undefined,
+  });
+  const batchId = `prepush-${Date.now().toString(36)}`;
+  const changes = plan.changes || [];
+
+  if (!asJson) {
+    const touched = changes.filter((c) => c.change_type !== "unchanged").length;
+    reporter.line(
+      `[preman] ${changedFiles} changed file${changedFiles === 1 ? "" : "s"} → ` +
+        `${plan.scanned?.endpoints ?? 0} endpoint${plan.scanned?.endpoints === 1 ? "" : "s"} scanned, ` +
+        `${touched} changed`
+    );
+    // Silence here would read as "nothing broke" when the truth is "nothing was
+    // read". Say which files went unread, and say it loudest when they were the
+    // only thing in the push.
+    const unreadable = plan.scanned?.unreadable || [];
+    if (unreadable.length) {
+      const kinds = unreadable.join(", ");
+      reporter.line(
+        (plan.scanned?.endpoints ?? 0) === 0
+          ? `[preman] no endpoints read — ${kinds} ${unreadable.length === 1 ? "is" : "are"} not supported yet, so this push was not checked`
+          : `[preman] ${kinds} skipped — not supported yet, so any endpoints there went unchecked`
+      );
+    }
+    reporter.line(
+      `[preman] ${target.url} · ${plan.selected.length} endpoint${plan.selected.length === 1 ? "" : "s"}, ` +
+        `${work.length} case${work.length === 1 ? "" : "s"}${policy.writes ? "" : ", read-only"}` +
+        (plan.traffic?.available ? ", ranked by production traffic" : "")
+    );
+  }
+
+  const runs = await runSlottedPool(
+    work,
+    async ({ entry, testCase }, slot) => {
+      if (Date.now() > deadline) return null;
+      const label = `${entry.method} ${entry.path} · ${testCase.kind}`;
+      reporter.busy(slot, label);
+      const result = await runGeneratedCase(testCase, { batchId, endpoint: entry });
+      const traffic = entry.traffic?.observations
+        ? `${entry.traffic.observations} prod calls/7d`
+        : "";
+      reporter.done(slot, {
+        ok: result.status === "passed",
+        label,
+        detail: result.status === "passed" ? traffic : result.error_message || "",
+      });
+      return { ...result, change_type: entry.change_type, reason: entry.reason };
+    },
+    CONCURRENCY
+  );
+  reporter.stop();
+
+  const completed = runs.filter(Boolean);
+  const failed = completed.filter((r) => r.status !== "passed");
+  // Breaking means the contract broke, not merely that some probe was unhappy:
+  // the happy path of an endpoint this push actually changed.
+  const breaking = failed.filter(
+    (r) => r.case_kind === "happy_path" && r.reason === "changed_in_push"
+  );
+  const removed = changes.filter((c) => c.change_type === "removed");
+
+  let uploaded = 0;
+  if (projectId && completed.length) {
+    const upload = await safeCall(args, "POST", `/projects/${projectId}/api-runs`, {
+      token,
+      json: {
+        origin: "local",
+        origin_label: originLabel(),
+        source: "ci",
+        batch_id: batchId,
+        batch_label: "pre-push verify",
+        runs: completed,
+      },
+    });
+    if (upload.ok) uploaded = Number(upload.inserted || 0);
+  }
+
+  const gate = blockOnBreaking(args, root);
+  const shouldBlock = gate.blocking && (breaking.length > 0 || removed.length > 0);
+
+  if (!asJson) {
+    if (failed.length) {
+      reporter.line(`[preman] ${failed.length} of ${completed.length} cases failed`);
+    } else {
+      reporter.line(`[preman] all ${completed.length} cases passed`);
+    }
+    for (const change of removed.slice(0, 5)) {
+      reporter.line(`  ! ${change.method} ${change.path} was removed by this push`);
+    }
+    if (withheld) reporter.line(`[preman] ${withheld} mutating case${withheld === 1 ? "" : "s"} withheld`);
+    if (uploaded) reporter.line(`[preman] uploaded ${uploaded} run${uploaded === 1 ? "" : "s"}`);
+    if (shouldBlock) {
+      reporter.line(`[preman] blocking this push (${gate.from}). Set PREMAN_SKIP_HOOK=1 to override.`);
+    } else if (breaking.length || removed.length) {
+      // Tracks what the gate is armed against rather than the breaking count
+      // alone. A push that only removes an endpoint is one the gate would have
+      // stopped, so bypassing it there has to be as visible as anywhere else.
+      const found = [
+        breaking.length && `${breaking.length} breaking change${breaking.length === 1 ? "" : "s"}`,
+        removed.length && `${removed.length} removal${removed.length === 1 ? "" : "s"}`,
+      ]
+        .filter(Boolean)
+        .join(" and ");
+      const disarmed = gate.overrode
+        ? ` (${gate.overrode} asked to block; PREMAN_BLOCK_ON_BREAKING switched it off)`
+        : "";
+      reporter.line(`[preman] ${found} — advisory only${disarmed}`);
+    }
+  }
+
+  return {
+    state: failed.length ? "failed" : "passed",
+    mode: "plan",
+    target: target.url,
+    changed_files: changedFiles,
+    endpoints: plan.selected.length,
+    verified: completed.length,
+    skipped: work.length - completed.length,
+    withheld,
+    breaking: breaking.map((r) => ({ endpoint: r.endpoint, http_status: r.http_status, error: r.error_message })),
+    removed: removed.map((c) => ({ method: c.method, path: c.path })),
+    failures: failed.map((r) => ({
+      endpoint: r.endpoint,
+      case: r.case_kind,
+      method: r.method,
+      url: r.url,
+      http_status: r.http_status,
+      error: r.error_message || null,
+    })),
+    uploaded,
+    // Advisory unless the repository opted in. `advisory` only flattens an
+    // unexpected throw; a deliberate block has to survive it.
+    exitCode: shouldBlock ? BLOCK_EXIT_CODE : 0,
+    blocked: shouldBlock,
+    message: null,
+  };
+}
+
+async function runVerify(args) {
+  const advisory = args.has("--pre-push");
+  const asJson = args.has("--json");
+  const budgetMs =
+    Math.max(5, Number.parseInt(args.value("--timeout", String(DEFAULT_TIMEOUT_SECONDS)), 10) || DEFAULT_TIMEOUT_SECONDS) *
+    1000;
+  const deadline = Date.now() + budgetMs;
+
+  const finish = (outcome) => {
+    if (asJson) process.stdout.write(`${JSON.stringify(outcome, null, 2)}\n`);
+    else if (outcome.message) process.stdout.write(`${outcome.message}\n`);
+    // A deliberate block is the one non-zero code advisory mode does not flatten.
+    if ((!advisory || outcome.blocked) && outcome.exitCode) process.exitCode = outcome.exitCode;
+    return outcome;
+  };
+
+  const token = resolveApiKey(args);
+  if (!token) {
+    return finish({
+      state: "skipped",
+      reason: "no_credentials",
+      message: `[preman] skipped: no API key. Run \`${cliInvocation()} login\`.`,
+      exitCode: 0,
+    });
+  }
+
+  const status = await safeCall(args, "GET", "/cli/status", { token });
+  if (!status.ok) {
+    return finish({
+      state: "skipped",
+      reason: status.transport_error ? "backend_unreachable" : "status_unavailable",
+      message: `[preman] skipped: ${backendUrl(args)} ${
+        status.transport_error ? `unreachable (${status.detail})` : `returned ${status.status_code}`
+      }.`,
+      exitCode: 0,
+    });
+  }
+  const projectId = status.workspace?.project_id || null;
+
+  const root = repoRoot();
+  // The plan comes first so a brand-new endpoint — one this push introduces and
+  // the saved inventory has never heard of — can still confirm the local target.
+  const planned = args.has("--all")
+    ? { plan: null, reason: "--all" }
+    : await fetchPlan(args, token, { root, refs: advisory ? readPushRefsFromStdin() : [] });
+  const planEndpoints = (planned.plan?.selected || []).map((entry) => ({
+    method: entry.method,
+    path_template: entry.path,
+  }));
+
+  const { endpoints, error } = await fetchInventory(args, token);
+  if ((error || !endpoints.length) && !planEndpoints.length) {
+    return finish({
+      state: "skipped",
+      reason: "no_inventory",
+      message:
+        `[preman] skipped: no saved endpoints to verify` +
+        (error ? ` (${error})` : `. Run \`${cliInvocation()} endpoints discover\`.`),
+      exitCode: 0,
+    });
+  }
+
+  const extraPorts = args.value("--port", "") ? [args.value("--port", "")] : [];
+  const resolved = await resolveLocalTarget([...planEndpoints, ...endpoints], {
+    extraPorts,
+    timeoutMs: 2000,
+  });
+  if (!resolved.target) {
+    return finish({
+      state: "skipped",
+      reason: "no_local_target",
+      message: `[preman] skipped: ${resolved.reason}.`,
+      candidates: resolved.candidates?.map((c) => ({ url: c.url, reason: c.reason })) || [],
+      exitCode: 0,
+    });
+  }
+
+  const target = resolved.target;
+  const policy = selectMethods(args);
+
+  if (planned.plan?.selected?.length) {
+    return finish(
+      await runPlan(args, {
+        plan: planned.plan,
+        target,
+        policy,
+        token,
+        projectId,
+        deadline,
+        asJson,
+        advisory,
+        root,
+        changedFiles: planned.changed || 0,
+      })
+    );
+  }
+
+  const selected = endpoints.filter((ep) => {
+    const method = String(ep.method || "GET").toUpperCase();
+    if (READ_METHODS.has(method)) return true;
+    if (DESTRUCTIVE_METHODS.has(method)) return false;
+    return policy.writes;
+  });
+
+  if (!asJson) {
+    process.stdout.write(
+      `[preman] target ${target.url} (${target.confidence} match, ${target.matched}/${target.expected} routes via ${target.via})\n` +
+        `[preman] verifying ${selected.length} endpoint${selected.length === 1 ? "" : "s"}` +
+        `${policy.writes ? ", writes enabled" : ", read-only"}\n`
+    );
+  }
+
+  const batchId = `prepush-${Date.now().toString(36)}`;
+  const runs = await runPool(
+    selected,
+    (endpoint) =>
+      Date.now() > deadline
+        ? null
+        : runCase(target.url, endpoint, { batchId }),
+    CONCURRENCY
+  );
+  const completed = runs.filter(Boolean);
+  const failed = completed.filter((r) => r.status !== "passed");
+
+  let uploaded = 0;
+  if (projectId && completed.length) {
+    const upload = await safeCall(args, "POST", `/projects/${projectId}/api-runs`, {
+      token,
+      json: {
+        origin: "local",
+        origin_label: originLabel(),
+        source: "ci",
+        batch_id: batchId,
+        batch_label: "pre-push verify",
+        runs: completed,
+      },
+    });
+    if (upload.ok) uploaded = Number(upload.inserted || 0);
+  }
+
+  const outcome = {
+    state: failed.length ? "failed" : "passed",
+    target: target.url,
+    verified: completed.length,
+    skipped: selected.length - completed.length,
+    failures: failed.map((r) => ({
+      method: r.method,
+      url: r.url,
+      http_status: r.http_status,
+      error: r.error_message || null,
+    })),
+    uploaded,
+    // Advisory by construction: a real failure still reports zero so the push
+    // proceeds. The report is the product, not the gate.
+    exitCode: 0,
+  };
+
+  if (!asJson) {
+    if (failed.length) {
+      process.stdout.write(`[preman] ${failed.length} of ${completed.length} failed:\n`);
+      for (const failure of failed.slice(0, 10)) {
+        process.stdout.write(
+          `  ✗ ${failure.method} ${failure.url} ${failure.http_status || failure.error || ""}\n`
+        );
+      }
+    } else {
+      process.stdout.write(`[preman] all ${completed.length} endpoints healthy\n`);
+    }
+    if (uploaded) process.stdout.write(`[preman] uploaded ${uploaded} run${uploaded === 1 ? "" : "s"}\n`);
+  }
+
+  return finish({ ...outcome, message: null });
+}