getadvantage 0.1.0 → 0.2.0

package/index.mjs

@@ -1,181 +1,206 @@
-#!/usr/bin/env node
-// Ship-Safe — "is this safe to ship?"
-//
-// A local, dependency-free pre-deploy auditor for AI-built apps. Run it in your
-// repo BEFORE you deploy and it gives a plain-language GO / NO-GO:
-//
-//   • dirty-tree guard   — `vercel --prod` ships the working tree, so a dirty
-//                          tree (or another session's work) would ship live
-//   • secret scan        — leaked keys in committed/staged files
-//   • build + typecheck  — `tsc --noEmit` (and `--build` for a full build)
-//   • schema-bump check  — DDL changed without a SCHEMA_VERSION bump
-//
-// Plus v1.1 read-only OVERVIEW MAPS (default-on; `--no-overview` to skip) —
-// "understand what you built":
-//   • API surface map    — every route, its methods, and whether it's auth-gated
-//                          (⚠ mutating routes with no auth check)
-//   • integrations map    — external/LLM/3rd-party calls + the env keys behind them
-//                          (⚠ a secret reachable from the client bundle)
-//   • schedules & jobs map — vercel.json crons + cron routes + their gating
-//                          (⚠ an ungated, publicly-triggerable cron)
-//
-// Node built-ins only. ESM. Nothing here mutates your repo (`check`); only the
-// explicit `deploy` subcommand performs an action, and it deploys from a clean
-// detached worktree of the target commit.
-//
-// Usage:
-//   node cli/ship-safe/index.mjs [check] [--build]
-//   node cli/ship-safe/index.mjs deploy [--expect-prefix getadvantage-] [--scope <s>]
-//                                       [--commit <ref>] [--token-env VERCEL_TOKEN]
-//                                       [--build] [--force]
-
-import { c } from "./util.mjs";
-import { repoRoot } from "./util.mjs";
-import { runChecks } from "./checks-runner.mjs";
-import { deploy } from "./deploy.mjs";
-import { runBrief } from "./brief.mjs";
-import { runHandoff } from "./handoff.mjs";
-
-function parseArgs(argv) {
-  // First non-flag token is the subcommand; default to "check".
-  const flags = {};
-  const positional = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
-      // value-taking flags vs boolean flags
-      const valueFlags = new Set(["expect-prefix", "scope", "commit", "token-env", "base-ref", "out"]);
-      if (valueFlags.has(key)) {
-        flags[key] = argv[++i];
-      } else {
-        flags[key] = true;
-      }
-    } else {
-      positional.push(a);
-    }
-  }
-  return { cmd: positional[0] || "check", flags };
-}
-
-function header() {
-  console.log(c.bold("┌──────────────────────────────────────────┐"));
-  console.log(c.bold("│  Ship-Safe — is this safe to ship?        │"));
-  console.log(c.bold("└──────────────────────────────────────────┘"));
-}
-
-function printHelp() {
-  header();
-  console.log(`
-${c.bold("Commands")}
-  ${c.cyan("check")}    Run all read-only pre-deploy checks (default). Exits 0 on GO, 1 on NO-GO.
-  ${c.cyan("brief")}    Generate / refresh the PROJECT BRAIN — a portable, repo-resident project
-           brief (default ${c.bold("PROJECT-BRIEF.md")}) that ANY model/session/tool reads on start,
-           so you can switch tools without re-explaining the project. ${c.bold("--check")} only warns
-           if the brief is missing or stale (never blocks).
-  ${c.cyan("handoff")}  Refresh the brief AND write ${c.bold("HANDOFF.md")} — the HOT "where we left off"
-           layer (what you were doing · next steps · open threads), so you can drop a long,
-           slow session and start a fresh, fast one with no loss. Your notes are preserved
-           across refreshes.
-  ${c.cyan("deploy")}   Run check, then deploy from a clean detached worktree and confirm the
-           deployment URL prefix. Performs a real ${c.bold("vercel --prod")}.
-
-${c.bold("Flags")}
-  --build                 Also run a full ${c.bold("npm run build")} (default: tsc --noEmit only).
-  --base-ref <ref>        Merge-base ref for the schema-bump diff (default: main).
-  --no-overview           Skip the read-only overview maps (API surface, integrations, schedules).
-  --no-brief-check        Skip the (non-blocking) brief-staleness warning in ${c.cyan("check")}.
-
-  ${c.dim("brief only:")}
-  --out <path>            Where to write the brief (default: PROJECT-BRIEF.md at repo root).
-  --check                 Report staleness only (no write); warns if missing/stale.
-
-  ${c.dim("deploy only:")}
-  --expect-prefix <p>     Required deployment-host prefix (default: derived from your linked .vercel project; guard skipped if none).
-  --scope <scope>         Vercel team scope, passed through to vercel.
-  --commit <ref>          Commit-ish to deploy (default: HEAD).
-  --token-env <NAME>      Env var NAME holding the Vercel token (default: VERCEL_TOKEN).
-  --force                 Deploy even if checks return NO-GO (use with care).
-
-${c.bold("Examples")}
-  ship-safe                        run the pre-deploy checks (GO / NO-GO)
-  ship-safe --build                checks + a full build
-  ship-safe brief                  generate / refresh the project brain
-  ship-safe handoff                save your place for the next session
-  ship-safe deploy --expect-prefix myproject-
-`);
-}
-
-async function main() {
-  const { cmd, flags } = parseArgs(process.argv.slice(2));
-
-  if (cmd === "help" || flags.help) {
-    printHelp();
-    process.exit(0);
-  }
-
-  let cwd;
-  try {
-    cwd = repoRoot();
-  } catch {
-    console.error(c.red("✗ Not inside a git repository. Ship-Safe must run in your project's repo."));
-    process.exit(1);
-  }
-
-  if (cmd === "check") {
-    header();
-    const { exitCode } = await runChecks({
-      cwd,
-      runBuild: !!flags.build,
-      baseRef: flags["base-ref"],
-      // Overviews are default-on; `--no-overview` turns them off.
-      overview: !flags["no-overview"],
-      // Brief-staleness warning is default-on; `--no-brief-check` turns it off.
-      briefCheck: !flags["no-brief-check"],
-    });
-    process.exit(exitCode);
-  }
-
-  if (cmd === "brief") {
-    header();
-    const code = runBrief({
-      cwd,
-      out: flags.out,
-      check: !!flags.check,
-    });
-    process.exit(code);
-  }
-
-  if (cmd === "handoff") {
-    header();
-    const code = runHandoff({
-      cwd,
-      out: flags.out,
-      noBrief: !!flags["no-brief"],
-    });
-    process.exit(code);
-  }
-
-  if (cmd === "deploy") {
-    header();
-    const code = await deploy({
-      cwd,
-      commit: flags.commit,
-      expectPrefix: flags["expect-prefix"],
-      scope: flags.scope,
-      tokenEnv: flags["token-env"],
-      force: !!flags.force,
-      runBuild: !!flags.build,
-    });
-    process.exit(code);
-  }
-
-  console.error(c.red(`✗ Unknown command: ${cmd}`));
-  printHelp();
-  process.exit(1);
-}
-
-main().catch((e) => {
-  console.error(c.red(`✗ Ship-Safe crashed: ${e?.stack || e}`));
-  process.exit(1);
-});
+#!/usr/bin/env node
+// Ship-Safe — "is this safe to ship?"
+//
+// A local, dependency-free pre-deploy auditor for AI-built apps. Run it in your
+// repo BEFORE you deploy and it gives a plain-language GO / NO-GO:
+//
+//   • dirty-tree guard   — `vercel --prod` ships the working tree, so a dirty
+//                          tree (or another session's work) would ship live
+//   • secret scan        — leaked keys in committed/staged files
+//   • build + typecheck  — `tsc --noEmit` (and `--build` for a full build)
+//   • schema-bump check  — DDL changed without a SCHEMA_VERSION bump
+//
+// Plus v1.1 read-only OVERVIEW MAPS (default-on; `--no-overview` to skip) —
+// "understand what you built":
+//   • API surface map    — every route, its methods, and whether it's auth-gated
+//                          (⚠ mutating routes with no auth check)
+//   • integrations map    — external/LLM/3rd-party calls + the env keys behind them
+//                          (⚠ a secret reachable from the client bundle)
+//   • schedules & jobs map — vercel.json crons + cron routes + their gating
+//                          (⚠ an ungated, publicly-triggerable cron)
+//
+// Node built-ins only. ESM. Nothing here mutates your repo (`check`); only the
+// explicit `deploy` subcommand performs an action, and it deploys from a clean
+// detached worktree of the target commit.
+//
+// Usage:
+//   node cli/ship-safe/index.mjs [check] [--build]
+//   node cli/ship-safe/index.mjs deploy [--expect-prefix getadvantage-] [--scope <s>]
+//                                       [--commit <ref>] [--token-env VERCEL_TOKEN]
+//                                       [--build] [--force]
+
+import { c } from "./util.mjs";
+import { repoRoot } from "./util.mjs";
+import { runChecks } from "./checks-runner.mjs";
+import { deploy } from "./deploy.mjs";
+import { runBrief } from "./brief.mjs";
+import { runHandoff } from "./handoff.mjs";
+import { runLedger } from "./ledger.mjs";
+import { runGauge } from "./gauge.mjs";
+import { runInit } from "./init.mjs";
+
+function parseArgs(argv) {
+  // First non-flag token is the subcommand; default to "check".
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      // value-taking flags vs boolean flags
+      const valueFlags = new Set(["expect-prefix", "scope", "commit", "token-env", "base-ref", "out"]);
+      if (valueFlags.has(key)) {
+        flags[key] = argv[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { cmd: positional[0] || "check", flags };
+}
+
+function header() {
+  console.log(c.bold("┌──────────────────────────────────────────┐"));
+  console.log(c.bold("│  Ship-Safe — is this safe to ship?        │"));
+  console.log(c.bold("└──────────────────────────────────────────┘"));
+}
+
+function printHelp() {
+  header();
+  console.log(`
+${c.bold("Commands")}
+  ${c.cyan("check")}    Run all read-only pre-deploy checks (default). Exits 0 on GO, 1 on NO-GO.
+  ${c.cyan("brief")}    Generate / refresh the PROJECT BRAIN — a portable, repo-resident project
+           brief (default ${c.bold("PROJECT-BRIEF.md")}) that ANY model/session/tool reads on start,
+           so you can switch tools without re-explaining the project. ${c.bold("--check")} only warns
+           if the brief is missing or stale (never blocks).
+  ${c.cyan("handoff")}  Refresh the brief AND write ${c.bold("HANDOFF.md")} — the HOT "where we left off"
+           layer (what you were doing · next steps · open threads), so you can drop a long,
+           slow session and start a fresh, fast one with no loss. Your notes are preserved
+           across refreshes.
+  ${c.cyan("gauge")}    Is this session getting heavy? A quick freshness read (repo activity since
+           your last handoff) that nudges you to reset before things get slow.
+  ${c.cyan("ledger")}   Show the session ledger — the running log of save-points (the project's
+           history); each ${c.bold("handoff")} adds an entry.
+  ${c.cyan("init")}     Wire the brain into your agent's instructions file (CLAUDE.md / AGENTS.md /
+           .cursorrules) so the brief + handoff load automatically at session start.
+  ${c.cyan("deploy")}   Run check, then deploy from a clean detached worktree and confirm the
+           deployment URL prefix. Performs a real ${c.bold("vercel --prod")}.
+
+${c.bold("Flags")}
+  --build                 Also run a full ${c.bold("npm run build")} (default: tsc --noEmit only).
+  --base-ref <ref>        Merge-base ref for the schema-bump diff (default: main).
+  --no-overview           Skip the read-only overview maps (API surface, integrations, schedules).
+  --no-brief-check        Skip the (non-blocking) brief-staleness warning in ${c.cyan("check")}.
+
+  ${c.dim("brief only:")}
+  --out <path>            Where to write the brief (default: PROJECT-BRIEF.md at repo root).
+  --check                 Report staleness only (no write); warns if missing/stale.
+
+  ${c.dim("deploy only:")}
+  --expect-prefix <p>     Required deployment-host prefix (default: derived from your linked .vercel project; guard skipped if none).
+  --scope <scope>         Vercel team scope, passed through to vercel.
+  --commit <ref>          Commit-ish to deploy (default: HEAD).
+  --token-env <NAME>      Env var NAME holding the Vercel token (default: VERCEL_TOKEN).
+  --force                 Deploy even if checks return NO-GO (use with care).
+
+${c.bold("Examples")}
+  ship-safe                        run the pre-deploy checks (GO / NO-GO)
+  ship-safe brief                  generate / refresh the project brain
+  ship-safe init                   auto-load the brain at every session start
+  ship-safe handoff                save your place for the next session
+  ship-safe gauge                  is this session getting heavy?
+  ship-safe deploy --expect-prefix myproject-
+`);
+}
+
+async function main() {
+  const { cmd, flags } = parseArgs(process.argv.slice(2));
+
+  if (cmd === "help" || flags.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  let cwd;
+  try {
+    cwd = repoRoot();
+  } catch {
+    console.error(c.red("✗ Not inside a git repository. Ship-Safe must run in your project's repo."));
+    process.exit(1);
+  }
+
+  if (cmd === "check") {
+    header();
+    const { exitCode } = await runChecks({
+      cwd,
+      runBuild: !!flags.build,
+      baseRef: flags["base-ref"],
+      // Overviews are default-on; `--no-overview` turns them off.
+      overview: !flags["no-overview"],
+      // Brief-staleness warning is default-on; `--no-brief-check` turns it off.
+      briefCheck: !flags["no-brief-check"],
+    });
+    process.exit(exitCode);
+  }
+
+  if (cmd === "brief") {
+    header();
+    const code = runBrief({
+      cwd,
+      out: flags.out,
+      check: !!flags.check,
+    });
+    process.exit(code);
+  }
+
+  if (cmd === "handoff") {
+    header();
+    const code = runHandoff({
+      cwd,
+      out: flags.out,
+      noBrief: !!flags["no-brief"],
+    });
+    process.exit(code);
+  }
+
+  if (cmd === "gauge") {
+    header();
+    process.exit(runGauge({ cwd }));
+  }
+
+  if (cmd === "ledger") {
+    header();
+    process.exit(runLedger({ cwd }));
+  }
+
+  if (cmd === "init") {
+    header();
+    process.exit(runInit({ cwd }));
+  }
+
+  if (cmd === "deploy") {
+    header();
+    const code = await deploy({
+      cwd,
+      commit: flags.commit,
+      expectPrefix: flags["expect-prefix"],
+      scope: flags.scope,
+      tokenEnv: flags["token-env"],
+      force: !!flags.force,
+      runBuild: !!flags.build,
+    });
+    process.exit(code);
+  }
+
+  console.error(c.red(`✗ Unknown command: ${cmd}`));
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((e) => {
+  console.error(c.red(`✗ Ship-Safe crashed: ${e?.stack || e}`));
+  process.exit(1);
+});

package/init.mjs

@@ -0,0 +1,79 @@
+// Ship-Safe — AUTO-LOAD HOOK (`ship-safe init`).
+//
+// Kills the discipline tax. AI coding tools read a conventional instructions file
+// at the START of every session — `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex
+// and a growing set of tools), `.cursorrules` (Cursor), GitHub Copilot's
+// instructions file. `init` ensures each present file has a small MANAGED block
+// telling the agent to read PROJECT-BRIEF.md + HANDOFF.md first — so the brain
+// loads itself and you never have to remember to point at it.
+//
+// Idempotent: it upserts its own marked block (never duplicates), so re-running
+// after the brief changes is safe. If NO entry file exists, it creates AGENTS.md
+// (the emerging cross-tool standard). Node built-ins only. ESM.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { c, relPath } from "./util.mjs";
+
+const START = "<!-- ship-safe:auto-load -->";
+const END = "<!-- /ship-safe:auto-load -->";
+
+const BLOCK = [
+  START,
+  "## Project brain — read first",
+  "Before anything else, read **`PROJECT-BRIEF.md`** (what this project is) and,",
+  "if present, **`HANDOFF.md`** (where work left off). Refresh them with",
+  "`ship-safe handoff` (or `npx getadvantage handoff`) before switching sessions",
+  "or models — your context lives in the repo, not the tool.",
+  END,
+].join("\n");
+
+// Files an AI coding tool auto-reads at session start. We touch existing ones;
+// if none exist we create AGENTS.md (the cross-tool convention).
+const TARGETS = [
+  "CLAUDE.md",
+  "AGENTS.md",
+  ".cursorrules",
+  ".github/copilot-instructions.md",
+];
+
+function upsertBlock(abs) {
+  let body = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+  const i = body.indexOf(START);
+  const j = body.indexOf(END);
+  let action;
+  if (i !== -1 && j !== -1 && j > i) {
+    body = body.slice(0, i) + BLOCK + body.slice(j + END.length);
+    action = "updated";
+  } else {
+    body = (body ? body.replace(/\n*$/, "") + "\n\n" : "") + BLOCK + "\n";
+    action = body && existsSync(abs) ? "appended to" : "created";
+  }
+  const dir = path.dirname(abs);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(abs, body, "utf8");
+  return action;
+}
+
+export function runInit(o) {
+  const cwd = o.cwd;
+  const present = TARGETS.filter((t) => existsSync(path.join(cwd, t)));
+  const done = [];
+
+  if (present.length === 0) {
+    const abs = path.join(cwd, "AGENTS.md");
+    writeFileSync(abs, `# Agent instructions\n\n${BLOCK}\n`, "utf8");
+    done.push(`AGENTS.md (created)`);
+  } else {
+    for (const t of present) {
+      const action = upsertBlock(path.join(cwd, t));
+      done.push(`${t} (${action})`);
+    }
+  }
+
+  console.log(c.green(`✓ Wired the project brain in: ${done.join(", ")}`));
+  console.log(c.gray("  Your AI reads these at session start — so PROJECT-BRIEF.md + HANDOFF.md load automatically."));
+  console.log(c.gray("  Re-run anytime; it updates its own marked block and never duplicates."));
+  console.log(c.gray("  (Don't forget to run `ship-safe brief` once so the brain file exists.)"));
+  return 0;
+}

package/ledger.mjs

@@ -0,0 +1,110 @@
+// Ship-Safe — SESSION LEDGER (`ship-safe ledger`).
+//
+// The append-only continuity changelog. Every `ship-safe handoff` adds (or, if
+// you re-run it in the same session, updates) one compact entry to
+// `.ship-safe/ledger.md`: date · branch @ sha · commits since last · next step.
+// Over time it becomes the project's session history — the thread that lets any
+// model/session see not just WHERE the project is, but HOW it got there.
+//
+// Node built-ins only. ESM. Writes one repo-resident file.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { c, gitSafe, relPath } from "./util.mjs";
+
+const HEAD_MARK = "<!-- ship-safe:ledger -->";
+
+function ledgerPath(cwd) {
+  return path.join(cwd, ".ship-safe", "ledger.md");
+}
+
+/** Pull the first real "next step" line out of a handoff notes block. Returns
+ *  "—" when it's still the placeholder or empty. */
+function extractNext(notes) {
+  if (!notes) return "—";
+  const lines = notes.split("\n");
+  let inNext = false;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (/^##\s+next steps/i.test(line)) { inNext = true; continue; }
+    if (inNext) {
+      if (/^##\s/.test(line)) break; // next heading
+      if (!line) continue;
+      const text = line.replace(/^(\d+\.|[-*])\s*/, "").trim();
+      if (!text || text.startsWith("_(")) return "—"; // untouched placeholder
+      return text.replace(/\s+/g, " ").slice(0, 140);
+    }
+  }
+  return "—";
+}
+
+/**
+ * Append (or update the latest same-sha) ledger entry. Called by `handoff`.
+ * @returns {string} repo-relative ledger path (for the caller to mention).
+ */
+export function appendLedger(cwd, { headSha, branch, lastHead, notes, now }) {
+  const abs = ledgerPath(cwd);
+  const dir = path.dirname(abs);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  let body = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+  if (!body.includes(HEAD_MARK)) {
+    body =
+      `${HEAD_MARK}\n# Session ledger\n\n` +
+      `_A running log of save-points (\`ship-safe handoff\`), newest at the bottom — ` +
+      `the project's session history._\n`;
+  }
+
+  // commits since the last handoff (best-effort; 0 if range invalid/first run)
+  let commitCount = 0;
+  if (lastHead) {
+    const cnt = gitSafe(["rev-list", "--count", `${lastHead}..HEAD`], { cwd });
+    if (cnt) commitCount = parseInt(cnt, 10) || 0;
+  }
+
+  const shortSha = headSha ? headSha.slice(0, 10) : "(none)";
+  const date = now.slice(0, 16).replace("T", " "); // YYYY-MM-DD HH:MM (UTC)
+  const next = extractNext(notes);
+  const entry =
+    `- **${date}** · \`${branch}\` @ \`${shortSha}\` · ${commitCount} commit(s) since last · next: ${next}`;
+
+  // If the most recent entry is for THIS head sha, update it in place (re-running
+  // handoff in one session shouldn't duplicate the save-point).
+  const lines = body.split("\n");
+  let lastIdx = -1;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].startsWith("- **")) { lastIdx = i; break; }
+  }
+  if (lastIdx >= 0 && lines[lastIdx].includes(`@ \`${shortSha}\``)) {
+    lines[lastIdx] = entry;
+    body = lines.join("\n");
+  } else {
+    body = body.replace(/\n*$/, "") + "\n" + entry + "\n";
+  }
+
+  writeFileSync(abs, body, "utf8");
+  return relPath(abs, cwd);
+}
+
+/** `ship-safe ledger` — print the recent session history. */
+export function runLedger(o) {
+  const cwd = o.cwd;
+  const abs = ledgerPath(cwd);
+  if (!existsSync(abs)) {
+    console.log(`  ${c.yellow("⚠")} No session ledger yet — run ${c.cyan("ship-safe handoff")} to start one.`);
+    return 0;
+  }
+  const body = readFileSync(abs, "utf8");
+  const entries = body.split("\n").filter((l) => l.startsWith("- **"));
+  console.log(c.bold(`\n  Session ledger — ${entries.length} save-point(s)  ${c.gray(`(${relPath(abs, cwd)})`)}\n`));
+  const tail = entries.slice(-15);
+  for (const e of tail) {
+    console.log("  " + e.replace(/^- /, "").replace(/\*\*/g, "").replace(/`/g, ""));
+  }
+  if (entries.length > tail.length) {
+    console.log(c.gray(`  …and ${entries.length - tail.length} older — see ${relPath(abs, cwd)}`));
+  }
+  return 0;
+}
+
+export { ledgerPath };