getadvantage 0.1.0

package/checks-runner.mjs

@@ -0,0 +1,136 @@
+// Ship-Safe — runs the full check suite and renders the per-check + overall
+// verdict. Shared by both `ship-safe check` and `ship-safe deploy` so the gate
+// is identical in both paths.
+
+import { c, GLYPH, printResult, section } from "./util.mjs";
+import {
+  checkDirtyTree,
+  checkSecrets,
+  checkTypecheck,
+  checkBuild,
+  checkSchemaBump,
+} from "./checks.mjs";
+import {
+  overviewApiSurface,
+  overviewIntegrations,
+  overviewSchedules,
+} from "./overviews.mjs";
+import { briefStaleness } from "./brief.mjs";
+
+/**
+ * Run every check and print a clean summary.
+ * @param {object} o
+ * @param {string} o.cwd        repo root
+ * @param {boolean} o.runBuild   also run a full `npm run build` (slower)
+ * @param {string} [o.baseRef]   merge-base ref for the schema diff (default main)
+ * @param {boolean} [o.overview] run the v1.1 read-only overview scanners
+ *                               (API surface · integrations · schedules).
+ *                               Defaults to ON — they're fast, read-only maps.
+ * @param {boolean} [o.briefCheck] emit a NON-BLOCKING staleness warning if the
+ *                               PROJECT BRAIN (PROJECT-BRIEF.md) is missing or
+ *                               out of date. Defaults to ON. Never a fail.
+ * @returns {Promise<{ exitCode: number, results: any[] }>}  exitCode 0=GO, 1=NO-GO
+ */
+export async function runChecks(o) {
+  const cwd = o.cwd;
+  const results = [];
+
+  section("Checks");
+
+  // a. Dirty-tree guard
+  results.push(safe(() => checkDirtyTree(cwd), "Dirty-tree guard"));
+  printResult(results[results.length - 1]);
+
+  // b. Secret scan
+  results.push(safe(() => checkSecrets(cwd), "Secret scan"));
+  printResult(results[results.length - 1]);
+
+  // c. Typecheck (always) + optional full build
+  results.push(safe(() => checkTypecheck(cwd), "Typecheck (tsc --noEmit)"));
+  printResult(results[results.length - 1]);
+  if (o.runBuild) {
+    results.push(safe(() => checkBuild(cwd), "Production build (npm run build)"));
+    printResult(results[results.length - 1]);
+  }
+
+  // d. Schema-bump check
+  results.push(safe(() => checkSchemaBump(cwd, o.baseRef || "main"), "Schema-bump check"));
+  printResult(results[results.length - 1]);
+
+  // ---- v1.1 OVERVIEW SCANNERS (read-only maps) ----------------------------
+  // Default-on: three fast, read-only repo scans that give the builder a map of
+  // what their app actually has. They emit pass/warn only (never a blocking
+  // fail) — a surprising map is informational, the v1 safety checks own NO-GO.
+  // Disable with `--no-overview`.
+  const runOverview = o.overview !== false;
+  if (runOverview) {
+    section("Overview — what your app has (read-only)");
+
+    results.push(safe(() => overviewApiSurface(cwd), "API surface map"));
+    printResult(results[results.length - 1]);
+
+    results.push(safe(() => overviewIntegrations(cwd), "Agents & integrations map"));
+    printResult(results[results.length - 1]);
+
+    results.push(safe(() => overviewSchedules(cwd), "Schedules & jobs map"));
+    printResult(results[results.length - 1]);
+  }
+
+  // ---- PROJECT BRAIN staleness (non-blocking) -----------------------------
+  // Warn (never fail) if the repo-resident project brief is missing or stale,
+  // so the portable context any model/tool reads on start doesn't silently rot.
+  if (o.briefCheck !== false) {
+    results.push(
+      safe(() => {
+        const s = briefStaleness(cwd);
+        if (s.status === "ok") {
+          return { status: "pass", label: "Project brief", detail: s.reason, extra: [] };
+        }
+        return {
+          status: "warn",
+          label: "Project brief",
+          detail: s.reason,
+          extra: ["project brief is stale, run `ship-safe brief` to refresh."],
+        };
+      }, "Project brief"),
+    );
+    printResult(results[results.length - 1]);
+  }
+
+  // ---- Overall verdict ----------------------------------------------------
+  const fails = results.filter((r) => r.status === "fail").length;
+  const warns = results.filter((r) => r.status === "warn").length;
+  const passes = results.filter((r) => r.status === "pass").length;
+
+  section("Verdict");
+  console.log(`  ${GLYPH.pass} ${passes}   ${GLYPH.warn} ${warns}   ${GLYPH.fail} ${fails}`);
+
+  if (fails > 0) {
+    console.log(
+      "\n" + c.red(c.bold("  NO-GO")) + c.red(` — ${fails} blocking issue(s). Do not ship until these are clear.`),
+    );
+    return { exitCode: 1, results };
+  }
+  if (warns > 0) {
+    console.log(
+      "\n" + c.green(c.bold("  GO")) + c.yellow(` — with ${warns} warning(s) to eyeball first.`),
+    );
+    return { exitCode: 0, results };
+  }
+  console.log("\n" + c.green(c.bold("  GO")) + c.green(" — all checks clear. Safe to ship."));
+  return { exitCode: 0, results };
+}
+
+/** Never let one check throwing crash the whole gate — surface it as a fail. */
+function safe(fn, label) {
+  try {
+    return fn();
+  } catch (e) {
+    return {
+      status: "fail",
+      label,
+      detail: `Check errored: ${e.message || e}`,
+      extra: [],
+    };
+  }
+}

package/checks.mjs

@@ -0,0 +1,327 @@
+// Ship-Safe — the read-only pre-deploy checks.
+//
+// Every check returns a `result(status, label, detail, extra)`:
+//   pass (✓) · warn (⚠) · fail (✗ → NO-GO).
+// Nothing here mutates the repo. The secret patterns + dirty-tree reasoning are
+// lifted from getAdvantage's own conventions (CLAUDE.md hard-rule #2 and
+// app/lib/safety.ts) so the gate matches what the project already enforces.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { result, fingerprint, git, gitRaw, gitSafe } from "./util.mjs";
+
+// ===========================================================================
+// a. DIRTY-TREE GUARD
+// ===========================================================================
+// `vercel --prod` ships the WORKING TREE, not a commit — so any tracked,
+// modified/staged file (possibly another concurrent session's uncommitted
+// work) would ship live. BLOCK on tracked changes; WARN on untracked (often
+// scratch). This is the single biggest known foot-gun in this repo.
+export function checkDirtyTree(cwd) {
+  // gitRaw (NOT git) — porcelain's leading status columns are space-significant,
+  // so we must not trim the output before parsing.
+  const porcelain = gitRaw(["status", "--porcelain"], { cwd });
+  if (!porcelain.trim()) {
+    return result("pass", "Dirty-tree guard", "Working tree is clean — nothing unintended would ship.");
+  }
+
+  const lines = porcelain.split("\n").filter((l) => l.length > 0);
+  const tracked = []; // modified / staged / renamed / deleted tracked files
+  const untracked = []; // ?? — new files git isn't tracking yet
+
+  for (const line of lines) {
+    // Porcelain v1: XY<space>path  (X=staged, Y=worktree). "??" = untracked.
+    const xy = line.slice(0, 2);
+    const file = line.slice(3);
+    if (xy === "??") untracked.push(file);
+    else tracked.push(`${xy.trim() || xy} ${file}`);
+  }
+
+  if (tracked.length > 0) {
+    return result(
+      "fail",
+      "Dirty-tree guard",
+      `${tracked.length} tracked file(s) modified/staged — a 'vercel --prod' would ship this unintended work.`,
+      [
+        ...tracked.slice(0, 20).map((t) => t),
+        ...(tracked.length > 20 ? [`…and ${tracked.length - 20} more`] : []),
+        "Commit, stash, or revert before shipping. Deploy from a clean detached worktree of the intended commit.",
+      ],
+    );
+  }
+
+  // Only untracked files → warn, list them (they're usually scratch/logs).
+  return result(
+    "warn",
+    "Dirty-tree guard",
+    `${untracked.length} untracked file(s) present (not tracked — likely scratch, but confirm they shouldn't ship).`,
+    [
+      ...untracked.slice(0, 20),
+      ...(untracked.length > 20 ? [`…and ${untracked.length - 20} more`] : []),
+    ],
+  );
+}
+
+// ===========================================================================
+// b. SECRET SCAN
+// ===========================================================================
+// Patterns reuse getAdvantage's own definitions:
+//   • CLAUDE.md hard-rule #2: sk-proj / sk-live / sk_live / whsec_ / vcp_ /
+//     KV_REST / "Bearer " / long token literals.
+//   • app/lib/safety.ts SECRET_PATTERNS: OpenAI sk-, Stripe sk_live_/rk_live_,
+//     AWS AKIA, GitHub PAT (classic + fine-grained), Google OAuth, Slack,
+//     SendGrid, private-key blocks.
+// A match BLOCKS (✗); we print the file + a masked FINGERPRINT, never the
+// full secret. Binary/lockfiles/node_modules/.git are skipped.
+
+const SECRET_PATTERNS = [
+  // --- from app/lib/safety.ts ---
+  { id: "openai", label: "OpenAI secret key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{20,}/ },
+  { id: "stripe-live", label: "Stripe live secret key", re: /\bsk_live_[A-Za-z0-9]{20,}/ },
+  { id: "stripe-restricted", label: "Stripe restricted key", re: /\brk_live_[A-Za-z0-9]{20,}/ },
+  { id: "aws", label: "AWS access key id", re: /\bAKIA[0-9A-Z]{16}\b/ },
+  { id: "github-pat", label: "GitHub personal access token", re: /\bghp_[A-Za-z0-9]{36}\b/ },
+  { id: "github-fine", label: "GitHub fine-grained token", re: /\bgithub_pat_[A-Za-z0-9_]{22,}\b/ },
+  { id: "google-oauth", label: "Google OAuth secret", re: /\bGOCSPX-[A-Za-z0-9_-]{20,}\b/ },
+  { id: "slack", label: "Slack token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+  { id: "private-key", label: "Private key block", re: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/ },
+  { id: "sendgrid", label: "SendGrid key", re: /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/ },
+  // --- from CLAUDE.md hard-rule #2 (the pre-commit scan literals) ---
+  { id: "stripe-webhook", label: "Stripe webhook secret (whsec_)", re: /\bwhsec_[A-Za-z0-9]{20,}/ },
+  { id: "vercel-token", label: "Vercel token (vcp_)", re: /\bvcp_[A-Za-z0-9]{20,}/ },
+  { id: "kv-rest", label: "KV/Redis REST credential", re: /\bKV_REST_API_(?:URL|TOKEN|READ_ONLY_TOKEN)\s*=\s*\S+/ },
+  // "Bearer <token>" literal. The CLAUDE.md pre-commit scan lists "Bearer " as a
+  // tell. We capture the token and only flag it if it LOOKS like a real
+  // credential (mixed case + a digit, ≥20 chars) — so legitimate test fixtures
+  // and placeholders like `Bearer test_cron_secret...` or `Bearer ${token}`
+  // don't trip a false NO-GO. The `validate` predicate runs on the captured group.
+  {
+    id: "bearer",
+    label: "Bearer auth token literal",
+    re: /\bBearer\s+([A-Za-z0-9_\-.]{20,})/,
+    validate: (tok) => /[a-z]/.test(tok) && /[A-Z]/.test(tok) && /[0-9]/.test(tok),
+  },
+];
+
+// Files we never scan (binary-ish, generated, vendored, or the env files that
+// are gitignored by design and legitimately hold secrets locally).
+const SKIP_DIR = new Set([".git", "node_modules", ".next", ".vercel", ".data", "dist", "build", "coverage"]);
+const SKIP_BASENAME = new Set([
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  ".env",
+  ".env.local",
+  ".env.development.local",
+  ".env.production.local",
+]);
+const SKIP_EXT = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".svg", ".pdf",
+  ".woff", ".woff2", ".ttf", ".eot", ".mp4", ".webm", ".zip", ".gz",
+  ".lock", ".map",
+]);
+
+const MAX_FILE_BYTES = 2_000_000; // skip very large files (same cap as safety.ts corpus)
+
+/** Heuristic: does this buffer look binary? (null byte in the first 4KB) */
+function looksBinary(buf) {
+  const n = Math.min(buf.length, 4096);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+/** Files to scan: tracked + staged + (added) untracked-but-not-ignored, deduped.
+ *  We deliberately DON'T scan gitignored files (the local .env lives there and
+ *  is supposed to hold secrets). */
+function filesToScan(cwd) {
+  const set = new Set();
+  // Tracked files.
+  for (const f of gitSafe(["ls-files"], { cwd }).split("\n")) if (f) set.add(f);
+  // Untracked-but-not-ignored (new files a dev created; --others honours .gitignore).
+  for (const f of gitSafe(["ls-files", "--others", "--exclude-standard"], { cwd }).split("\n")) if (f) set.add(f);
+  return [...set];
+}
+
+export function checkSecrets(cwd) {
+  const files = filesToScan(cwd);
+  const hits = []; // { file, label, fp }
+
+  for (const rel of files) {
+    const base = path.basename(rel);
+    const ext = path.extname(rel).toLowerCase();
+    if (SKIP_BASENAME.has(base)) continue;
+    if (SKIP_EXT.has(ext)) continue;
+    // Skip anything inside a skipped directory.
+    if (rel.split(/[\\/]/).some((seg) => SKIP_DIR.has(seg))) continue;
+
+    const abs = path.join(cwd, rel);
+    let buf;
+    try {
+      const st = statSync(abs);
+      if (!st.isFile() || st.size > MAX_FILE_BYTES) continue;
+      buf = readFileSync(abs);
+    } catch {
+      continue; // unreadable / deleted-but-staged etc.
+    }
+    if (looksBinary(buf)) continue;
+    const text = buf.toString("utf8");
+
+    for (const p of SECRET_PATTERNS) {
+      const m = text.match(p.re);
+      if (!m) continue;
+      // If the pattern has a capture group + validator (e.g. Bearer), apply the
+      // validator to the captured token so test fixtures/placeholders don't trip.
+      const token = m[1] ?? m[0];
+      if (p.validate && !p.validate(token)) continue;
+      hits.push({ file: rel, label: p.label, fp: fingerprint(token) });
+    }
+  }
+
+  if (hits.length === 0) {
+    return result(
+      "pass",
+      "Secret scan",
+      `Scanned ${files.length} tracked/staged file(s) — no leaked-secret patterns matched.`,
+    );
+  }
+
+  // De-dupe identical (file,label) pairs for a tidy report.
+  const seen = new Set();
+  const lines = [];
+  for (const h of hits) {
+    const k = `${h.file}::${h.label}`;
+    if (seen.has(k)) continue;
+    seen.add(k);
+    lines.push(`${h.file} → ${h.label}: ${h.fp}`);
+  }
+  return result(
+    "fail",
+    "Secret scan",
+    `${lines.length} possible secret(s) in committed/staged files — remove + rotate before shipping.`,
+    lines.slice(0, 30),
+  );
+}
+
+// ===========================================================================
+// c. BUILD + TYPECHECK
+// ===========================================================================
+// Default: `npx tsc --noEmit` (fast). `--build` also runs `npm run build`.
+// BLOCK on either failing; print the tail of the output so the founder sees
+// the actual error without scrollback.
+
+function runCapture(cmd, args, cwd) {
+  try {
+    const out = execFileSync(cmd, args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+      maxBuffer: 32 * 1024 * 1024,
+      // On Windows npx/tsc are .cmd shims — shell:true lets them resolve.
+      shell: process.platform === "win32",
+    });
+    return { ok: true, out };
+  } catch (e) {
+    const out = `${e.stdout || ""}${e.stderr || ""}`.trim();
+    return { ok: false, out: out || String(e.message || e) };
+  }
+}
+
+function tail(text, n = 25) {
+  const lines = text.split("\n").filter(Boolean);
+  return lines.slice(-n);
+}
+
+export function checkTypecheck(cwd) {
+  const r = runCapture("npx", ["--yes", "tsc", "--noEmit"], cwd);
+  if (r.ok) {
+    return result("pass", "Typecheck (tsc --noEmit)", "TypeScript compiled with no type errors.");
+  }
+  return result(
+    "fail",
+    "Typecheck (tsc --noEmit)",
+    "tsc reported type errors — fix them before shipping.",
+    tail(r.out, 25),
+  );
+}
+
+export function checkBuild(cwd) {
+  const r = runCapture("npm", ["run", "build"], cwd);
+  if (r.ok) {
+    return result("pass", "Production build (npm run build)", "Next build completed successfully.");
+  }
+  return result(
+    "fail",
+    "Production build (npm run build)",
+    "The production build failed — fix it before shipping.",
+    tail(r.out, 30),
+  );
+}
+
+// ===========================================================================
+// d. SCHEMA-BUMP CHECK
+// ===========================================================================
+// db.ts uses a SCHEMA_VERSION sentinel: additive DDL is SKIPPED on an existing
+// prod DB whose stored version is already >= SCHEMA_VERSION. So a DDL change
+// that forgets to bump SCHEMA_VERSION builds + passes every proof on a fresh
+// PGlite DB, then silently no-ops in prod. We diff db.ts (committed vs the
+// merge-base with main, PLUS any uncommitted edits): if DDL-ish lines changed
+// but the `const SCHEMA_VERSION = N;` line did NOT, WARN loudly.
+
+const DB_PATH = "app/lib/server/db.ts";
+const DDL_RE = /\b(CREATE\s+TABLE|ADD\s+COLUMN|ALTER\s+TABLE|CREATE\s+(?:UNIQUE\s+)?INDEX|DROP\s+(?:TABLE|COLUMN|INDEX))\b/i;
+const VERSION_RE = /SCHEMA_VERSION\s*=\s*\d+/;
+
+export function checkSchemaBump(cwd, baseRef = "main") {
+  // Combined diff = (merge-base…HEAD committed) + (working-tree uncommitted).
+  // Use `git diff base...HEAD` for the committed delta on this lane, then a
+  // plain `git diff HEAD` for anything not yet committed. We never EDIT db.ts —
+  // this only READS the diff.
+  const haveBase = !!gitSafe(["rev-parse", "--verify", "--quiet", baseRef], { cwd });
+  let committedDiff = "";
+  if (haveBase) {
+    // base...HEAD = changes on HEAD since it diverged from base (symmetric range).
+    committedDiff = gitSafe(["diff", `${baseRef}...HEAD`, "--", DB_PATH], { cwd });
+  }
+  const uncommittedDiff = gitSafe(["diff", "HEAD", "--", DB_PATH], { cwd });
+  const combined = `${committedDiff}\n${uncommittedDiff}`;
+
+  // Only consider ADDED/REMOVED lines (diff bodies, prefixed +/-), not context.
+  const changedLines = combined
+    .split("\n")
+    .filter((l) => /^[+-]/.test(l) && !/^[+-]{3}\s/.test(l)); // skip +++/--- headers
+
+  if (changedLines.length === 0) {
+    if (!haveBase) {
+      return result(
+        "pass",
+        "Schema-bump check",
+        `No changes to ${DB_PATH} in the working tree (base ref '${baseRef}' not found, so the committed lane delta was skipped).`,
+      );
+    }
+    return result("pass", "Schema-bump check", `No changes to ${DB_PATH} vs ${baseRef}.`);
+  }
+
+  const ddlChanged = changedLines.some((l) => DDL_RE.test(l));
+  const versionChanged = changedLines.some((l) => VERSION_RE.test(l));
+
+  if (ddlChanged && !versionChanged) {
+    return result(
+      "warn",
+      "Schema-bump check",
+      `${DB_PATH} has DDL-ish changes but SCHEMA_VERSION was NOT bumped.`,
+      [
+        "Additive DDL (CREATE TABLE / ADD COLUMN / ALTER / CREATE INDEX) is SKIPPED on an existing prod DB",
+        "whose stored version already matches — so it builds + passes proofs on fresh PGlite, then silently",
+        "no-ops in prod. Bump `const SCHEMA_VERSION` (and coordinate the migration). See the schema-version memory.",
+        ...changedLines.filter((l) => DDL_RE.test(l)).slice(0, 6).map((l) => l.trim()),
+      ],
+    );
+  }
+
+  if (ddlChanged && versionChanged) {
+    return result("pass", "Schema-bump check", `${DB_PATH} changed DDL and SCHEMA_VERSION was bumped alongside it.`);
+  }
+
+  return result("pass", "Schema-bump check", `${DB_PATH} changed but no DDL-shaped statements were touched.`);
+}

package/deploy.mjs

@@ -0,0 +1,203 @@
+// Ship-Safe — the safe-deploy ritual (`ship-safe deploy`).
+//
+// This productizes getAdvantage's hard-won deploy rules:
+//   1. `vercel --prod` ships the WORKING TREE, so we deploy from a CLEAN
+//      DETACHED worktree of the exact target commit — never the live, possibly
+//      dirty, shared checkout (a concurrent session's uncommitted work has
+//      shipped to prod this way before).
+//   2. We CONFIRM the resulting deployment URL starts with the expected project
+//      prefix (default "getadvantage-"); a different prefix (e.g. "plusxplus-")
+//      means we deployed the WRONG project — STOP, non-zero exit.
+//   3. The Vercel token is read from an ENV VAR by NAME — never hardcoded,
+//      never echoed/logged.
+//
+// IMPORTANT: this module is implemented but is only invoked when the founder
+// explicitly runs `ship-safe deploy`. It runs `vercel --prod` for real.
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { c, git, gitSafe, section } from "./util.mjs";
+import { runChecks } from "./checks-runner.mjs";
+
+/** Read the linked Vercel project (.vercel/project.json), or null. Used to derive
+ *  a sensible wrong-project guard prefix when --expect-prefix isn't given. */
+function readVercelProject(cwd) {
+  try {
+    return JSON.parse(readFileSync(path.join(cwd, ".vercel", "project.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.cwd           repo root
+ * @param {string} o.commit        target commit-ish (default HEAD)
+ * @param {string} o.expectPrefix  required deployment-URL prefix (default: derived from .vercel projectName; guard skipped if none)
+ * @param {string} o.scope         Vercel team scope (passed through to vercel)
+ * @param {string} o.tokenEnv      NAME of the env var holding the Vercel token
+ * @param {boolean} o.force        deploy even if `check` returns NO-GO
+ * @param {boolean} o.runBuild     whether `check` should run a full build too
+ */
+export async function deploy(o) {
+  const cwd = o.cwd;
+  const commit = o.commit || "HEAD";
+  const tokenEnv = o.tokenEnv || "VERCEL_TOKEN";
+  // The wrong-project guard. Prefer an explicit --expect-prefix; otherwise derive
+  // it from the linked Vercel project so the guard works in ANY repo (not just
+  // ours). If we can't derive one, the guard is disabled and we say so — we never
+  // silently assume a project.
+  let expectPrefix = o.expectPrefix;
+  if (!expectPrefix) {
+    const proj = readVercelProject(cwd);
+    if (proj && typeof proj.projectName === "string" && proj.projectName) {
+      expectPrefix = `${proj.projectName}-`;
+    }
+  }
+
+  console.log(c.bold("\nShip-Safe — safe deploy"));
+  console.log(
+    c.dim(`  target commit: ${commit}   expect prefix: ${expectPrefix || "(none — wrong-project guard disabled)"}\n`),
+  );
+
+  // ---- 0. Resolve the token by NAME, never echo it. -----------------------
+  const token = process.env[tokenEnv];
+  if (!token) {
+    console.error(c.red(`✗ Env var ${tokenEnv} is not set — can't authenticate to Vercel.`));
+    console.error(c.gray(`  Set it (e.g. from your User-scoped VERCEL_TOKEN) and retry; the value is never printed.`));
+    return 1;
+  }
+
+  // ---- 1. Gate on `check` first (unless --force). -------------------------
+  section("Pre-deploy checks");
+  const { exitCode } = await runChecks({ cwd, runBuild: o.runBuild });
+  if (exitCode !== 0) {
+    if (!o.force) {
+      console.error(c.red("\n✗ NO-GO — checks failed. Aborting deploy. (Re-run with --force to override at your own risk.)"));
+      return 1;
+    }
+    console.error(c.yellow("\n⚠ Checks failed but --force was passed — proceeding anyway."));
+  }
+
+  // ---- 2. Resolve the exact commit SHA we're shipping. --------------------
+  const sha = git(["rev-parse", commit], { cwd });
+
+  // ---- 3. Create a CLEAN DETACHED worktree of that commit. ----------------
+  // A detached worktree is a pristine checkout of the SHA — none of the live
+  // checkout's uncommitted work can ride along. We place it in the OS temp dir
+  // so we never disturb sibling repos / the shared folder.
+  const wtDir = mkdtempSync(path.join(tmpdir(), "ship-safe-deploy-"));
+  let deployed = false;
+  let deployUrl = "";
+  try {
+    section("Clean worktree");
+    console.log(c.gray(`  Creating detached worktree at ${wtDir} @ ${sha.slice(0, 10)}`));
+    // --detach: no branch, just the commit. The worktree is a clean tree.
+    git(["worktree", "add", "--detach", wtDir, sha], { cwd });
+
+    // ---- 4. Copy `.vercel` (project link) into the worktree. --------------
+    // The worktree is a fresh checkout and won't contain the gitignored .vercel
+    // dir, so vercel wouldn't know which project to target. Copy it over.
+    const srcVercel = path.join(cwd, ".vercel");
+    if (existsSync(srcVercel)) {
+      cpSync(srcVercel, path.join(wtDir, ".vercel"), { recursive: true });
+      console.log(c.gray("  Copied .vercel project link into the worktree."));
+    } else {
+      console.error(c.red("✗ No .vercel/ found in the repo — can't confirm the target project. Run `vercel link` first."));
+      return 1;
+    }
+
+    // ---- 5. Run `vercel --prod` FROM the worktree. ------------------------
+    // We pass the token via the --token flag value (read from env above) and the
+    // scope through --scope. The token value is never logged by us; we spawn
+    // with stdio inherited so vercel's own output streams to the founder.
+    section("Deploying");
+    const vercelArgs = ["--yes", "vercel", "--prod", "--yes"];
+    if (o.scope) vercelArgs.push("--scope", o.scope);
+    vercelArgs.push("--token", token); // value from env; not printed by us
+
+    // Print a redacted version of the command (token masked) for transparency.
+    const shown = vercelArgs.map((a) => (a === token ? "<token:hidden>" : a));
+    console.log(c.gray(`  npx ${shown.join(" ")}   (cwd=${wtDir})`));
+
+    // Capture stdout so we can read the deployment URL, but also echo it live.
+    const proc = spawnSync("npx", vercelArgs, {
+      cwd: wtDir,
+      encoding: "utf8",
+      shell: process.platform === "win32",
+      maxBuffer: 32 * 1024 * 1024,
+    });
+    deployed = true;
+    const stdout = proc.stdout || "";
+    const stderr = proc.stderr || "";
+    // Echo vercel's output (it normally prints the URL on stdout).
+    if (stdout) process.stdout.write(stdout);
+    if (stderr) process.stderr.write(stderr);
+
+    if (proc.status !== 0) {
+      console.error(c.red(`\n✗ vercel exited with code ${proc.status}. Deploy not confirmed.`));
+      return proc.status || 1;
+    }
+
+    // ---- 6. Extract + CONFIRM the deployment URL prefix. ------------------
+    // Vercel prints a https://<project>-<hash>-<scope>.vercel.app URL. Grab the
+    // last vercel.app URL in the output and check its host's prefix.
+    const urls = `${stdout}\n${stderr}`.match(/https:\/\/[a-z0-9-]+\.vercel\.app/gi) || [];
+    deployUrl = urls.length ? urls[urls.length - 1] : "";
+    if (!deployUrl) {
+      console.error(c.red("\n✗ Could not find a deployment URL in vercel's output — STOP and verify manually."));
+      return 1;
+    }
+
+    const host = deployUrl.replace(/^https:\/\//, "");
+    section("Confirm target");
+    if (expectPrefix) {
+      if (!host.startsWith(expectPrefix)) {
+        // WRONG PROJECT. This is the load-bearing guard — e.g. a "plusxplus-" host
+        // means we shipped to the wrong product. Hard stop.
+        console.error(
+          c.red(
+            `\n✗ STOP — deployment host "${host}" does NOT start with the expected "${expectPrefix}".`,
+          ),
+        );
+        console.error(
+          c.red(
+            "   You may have deployed the WRONG project. Verify in the Vercel dashboard and roll back if needed.",
+          ),
+        );
+        return 2;
+      }
+      console.log(c.green(`✓ Deployed to ${deployUrl} — host prefix "${expectPrefix}" confirmed.`));
+    } else {
+      console.log(
+        c.yellow(`⚠ Deployed to ${deployUrl} — no expected prefix set, so the wrong-project guard was skipped.`),
+      );
+      console.log(c.gray("   Pass --expect-prefix <project>- (or link a .vercel project) to enable the guard."));
+    }
+    return 0;
+  } catch (e) {
+    console.error(c.red(`\n✗ Deploy failed: ${e.message || e}`));
+    return 1;
+  } finally {
+    // ---- 7. Always clean up the temp worktree. ---------------------------
+    // Deregister it from git AND remove the dir, best-effort. We never touch
+    // the live checkout here.
+    try {
+      gitSafe(["worktree", "remove", "--force", wtDir], { cwd });
+    } catch {
+      /* ignore */
+    }
+    try {
+      if (existsSync(wtDir)) rmSync(wtDir, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+    // Prune any dangling worktree admin entry.
+    gitSafe(["worktree", "prune"], { cwd });
+    if (deployed && deployUrl) {
+      console.log(c.dim("  (temp worktree cleaned up.)"));
+    }
+  }
+}