shipready 1.1.0 → 1.3.0

package/README.md

@@ -53,9 +53,27 @@ Scans the project and prints a report with a 0-100 score.
 | `-v, --verbose` | show file and line locations for every finding |
 | `--json` | output the raw structured report as JSON (great for CI) |
 | `--fix` | apply safe fixes, re-scan, and show the score before/after |
+| `--history` | also scan the **full git history** (all branches) for secrets that were committed and later removed |
+| `--verify` | check detected keys against provider APIs to see if they are **live right now** |
 
 Exits with code `1` when errors are found, so you can use it in CI pipelines.
 
+#### `--history`: secrets buried in old commits
+
+Deleting a leaked key from your code does not delete it from git history — anyone who clones the repo can still read it. `shipready check --history` scans every added line in every commit on every branch, dedupes findings, and skips anything still present in the working tree (the regular scan already covers those). Each finding shows the abbreviated commit hash so you know where to look.
+
+If something is found: rotate the key, then purge it with [git filter-repo](https://github.com/newren/git-filter-repo) or [BFG](https://rtyley.github.io/bfg-repo-cleaner/).
+
+#### `--verify`: is the key actually live?
+
+For 12+ providers (OpenAI, Anthropic, GitHub, GitLab, Stripe, SendGrid, Google, npm, Hugging Face, Figma, and more) shipready can make a single read-only "who am I" request to the provider's API:
+
+- `[VERIFIED ACTIVE]` — the key works right now; this upgrades the finding to an error and jumps to the top of next steps
+- `[not active - rotate anyway]` — the provider rejected it (revoked or fake)
+- no marker — the provider has no safe verification endpoint, or the network was unavailable
+
+Verification requests contain only the key itself, go directly to the provider's official API host, and never mutate remote state. Nothing is ever sent to any third party.
+
 ### `shipready init [path]`
 
 Generates AI-agent instruction files based on your detected framework, package manager, and scripts:
@@ -79,26 +97,28 @@ It never deletes user code and never overwrites files without `--force`. A summa
 ## Example output
 
 ```txt
-shipready report
-
-Project: Next.js
-Package manager: pnpm
-
-Summary:
-✓ package.json found
-✓ README.md found
-✗ .env.example missing
-✗ .env is not ignored
-⚠ 4 TODO/FIXME comments found
-⚠ 2 console.log calls found
-✓ No obvious secrets found
-
-Score: 72/100
-
-Recommended next steps:
-1. Add .env to .gitignore
-2. Create .env.example (run: shipready fix)
-3. Remove debug logs before shipping
+╭──────────────────────────────────────────────────────────╮
+│ shipready v1.3.0                                         │
+│ project Next.js  ·  pm pnpm                              │
+╰──────────────────────────────────────────────────────────╯
+
+  Score  ████████████████████░░░░░░░░  72/100  almost there
+
+  ✓ package.json  ok
+  ✓ README        ok
+  ✗ Env safety    .env.example missing (3 env vars used in code)
+  ✗                .env is not ignored by git
+  ✓ Secrets       No obvious secrets found
+  ✗ Git history   1 secret buried in git history (removed from code but still exposed)
+  ⚠ Code hygiene  4 TODO/FIXME comments found
+  ⚠                2 console.log calls found
+  ✓ .gitignore    ok
+
+  Next steps
+    1. Purge leaked secrets from git history (BFG or git filter-repo) and rotate them
+    2. Add .env to .gitignore
+    3. Create .env.example (run: shipready fix)
+    4. Remove debug logs and debugger statements before shipping
 ```
 
 ## What it checks
@@ -108,7 +128,7 @@ Recommended next steps:
 | **package.json** | Existence, package manager (lockfiles), framework, `dev`/`build`/`test`/`lint` scripts |
 | **README** | Existence, installation/usage/license sections, not-too-empty |
 | **Env safety** | `.env` gitignored, `.env.example` present and complete, no real values in examples |
-| **Secrets** | 18 token patterns, all masked in output (see table below) |
+| **Secrets** | 30+ token patterns with entropy analysis and confidence levels, all masked in output (see table below) |
 | **Debug leftovers** | `TODO`, `FIXME`, `HACK`, `XXX`, `console.log`, `debugger`, `throw new Error("Not implemented")` |
 | **.gitignore** | Existence and important entries (`.env`, `node_modules`, `dist`, `build`, `.next`) |
 
@@ -116,28 +136,65 @@ Ignored during scans: `node_modules`, `.git`, `dist`, `build`, `.next`, `out`, `
 
 ## Detected secrets
 
+The scanner combines provider-specific patterns with **Shannon entropy analysis** so that placeholders, examples, and templated values never pollute the report.
+
+**High confidence** (reported as errors):
+
 | Type | Recognized by |
 | --- | --- |
 | OpenAI | `sk-`, `sk-proj-` |
 | Anthropic | `sk-ant-` |
 | Google / Gemini | `AIza...` |
-| GitHub | `ghp_`, `github_pat_` |
-| Stripe (live) | `sk_live_`, `rk_live_` |
-| Slack | `xoxb-`, `xoxp-` |
-| AWS | `AKIA...` |
+| GitHub | `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_` |
+| GitLab | `glpat-...` |
+| Stripe (live) | `sk_live_`, `rk_live_`, `whsec_` |
+| Slack | `xoxb-`, `xoxp-`, `xapp-`, webhook URLs |
+| Discord | bot tokens, webhook URLs |
+| AWS | `AKIA...` key IDs, `aws_secret_access_key` assignments |
 | Supabase | `sbp_...` |
 | Vercel | `vercel_...` |
 | npm | `npm_...` |
 | SendGrid | `SG.xxx.xxx` |
 | Twilio | `AC` / `SK` + 32 hex |
 | Telegram bot | `123456789:AA...` |
+| DigitalOcean | `dop_v1_`, `doo_v1_`, `dor_v1_` |
+| Hugging Face | `hf_...` |
+| Shopify | `shpat_`, `shpss_`, `shpca_` |
+| Mailchimp | 32 hex + `-usNN` |
+| Airtable | `pat...` |
+| Fly.io | `fo1_...` |
+| Cloudflare | `CLOUDFLARE_API_TOKEN=` assignments |
+| Heroku | `HEROKU_API_KEY=` UUIDs |
 | Database URL with password | `postgres://user:pass@host` (also mysql, mongodb, redis, amqp) |
 | GCP service account | `"private_key_id"` in JSON |
 | Private key block | `-----BEGIN ... PRIVATE KEY-----` |
-| JWT | `eyJ...` |
-| Generic credential | `API_KEY=`, `SECRET=`, `PASSWORD=` assignments |
 
-Placeholders (`your-api-key`, `changeme`, `xxxx`, ...) are ignored. Matched values are always masked — shipready never prints a full secret.
+**Medium confidence** (reported as warnings, so real keys never hide among noise):
+
+| Type | Recognized by |
+| --- | --- |
+| Stripe (test) | `sk_test_`, `pk_test_` |
+| JWT | `eyJ...` with valid structure |
+| Generic credential | `API_KEY=`, `SECRET=`, `PASSWORD=` assignments — only when the value has high entropy |
+| Any finding in test/fixture/mock files | automatically downgraded |
+
+False-positive protection:
+
+- **Entropy gate**: generic assignments are only flagged when the value is statistically random (real keys are; `changeme` is not)
+- **Placeholder detection**: `your-api-key`, `xxxx`, `<token>`, `${VAR}`, `process.env.X`, and template literals are skipped
+- **Repeat/sequence filter**: `aaaa...`, `1234...` never match
+- **Bundle guard**: single-line minified blobs are skipped entirely
+- Matched values are always masked — shipready never prints a full secret
+
+### Suppressing a single finding
+
+If shipready flags a line you know is safe (a demo value, an already-revoked key in docs), add the `shipready-ignore` marker to that line:
+
+```js
+const DEMO_TOKEN = "ghp_thisIsADocumentationExample000000"; // shipready-ignore
+```
+
+The scanner skips any line containing `shipready-ignore`. For project-wide exceptions, prefer `secretAllowlist` in the config (see below) so the suppression is reviewable in one place.
 
 ## Configuration
 

package/dist/checks/history.js

@@ -0,0 +1,146 @@
+import { execFileSync } from "node:child_process";
+import { scanContentForSecrets } from "./secrets.js";
+/** Paths in history we never scan (vendor noise, lockfiles, build output). */
+const HISTORY_SKIP_RE = /(^|\/)(node_modules|vendor|dist|build|\.next|out|coverage)(\/|$)|\.(lock|min\.js|min\.css|map|png|jpg|jpeg|gif|webp|ico|pdf|zip|gz|woff2?)$|(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/i;
+/**
+ * Parses `git log -p --unified=0` output into added lines.
+ * Exported for testing.
+ */
+export function extractAddedLines(diffText) {
+    const added = [];
+    let commit = "";
+    let file = "";
+    for (const line of diffText.split("\n")) {
+        if (line.startsWith("commit ")) {
+            commit = line.slice(7, 14); // abbreviated hash
+            continue;
+        }
+        if (line.startsWith("+++ b/")) {
+            file = line.slice(6);
+            continue;
+        }
+        if (line.startsWith("+++")) {
+            // +++ /dev/null (file deletion)
+            file = "";
+            continue;
+        }
+        if (line.startsWith("+") && !line.startsWith("+++") && file) {
+            const content = line.slice(1);
+            // Skip empty lines and vendor/binary-ish paths early.
+            if (content.trim().length === 0)
+                continue;
+            if (HISTORY_SKIP_RE.test(file))
+                continue;
+            // Minified blobs are noise, mirroring the working-tree scanner.
+            if (content.length > 10000)
+                continue;
+            added.push({ commit, file, content });
+        }
+    }
+    return added;
+}
+/** True when the directory is inside a git repository. */
+export function isGitRepo(root) {
+    try {
+        execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Scans the entire git history (all branches) for secrets in added lines.
+ * Findings that still exist in the working tree are excluded - the regular
+ * scanner already reports those; this check surfaces the ones hiding only
+ * in old commits.
+ */
+export function scanGitHistory(root, allowlist = [], workingTreeSecrets = []) {
+    let diffText;
+    try {
+        diffText = execFileSync("git", ["log", "--all", "-p", "--unified=0", "--no-color", "--diff-filter=AM"], { cwd: root, maxBuffer: 512 * 1024 * 1024, encoding: "utf8" });
+    }
+    catch {
+        return [];
+    }
+    const addedLines = extractAddedLines(diffText);
+    const currentMasks = new Set(workingTreeSecrets.map((s) => `${s.file}::${s.masked}`));
+    const seen = new Set();
+    const found = [];
+    for (const { commit, file, content } of addedLines) {
+        const hits = scanContentForSecrets(content, file, allowlist);
+        for (const hit of hits) {
+            // Skip if the same secret is already reported from the working tree.
+            if (currentMasks.has(`${hit.file}::${hit.masked}`))
+                continue;
+            // Dedupe repeats across commits (same value in the same file).
+            const key = `${hit.file}::${hit.masked}::${hit.kind}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            found.push({
+                ...hit,
+                line: 0,
+                source: "history",
+                commit,
+            });
+        }
+    }
+    return found;
+}
+/** Builds the CheckResult for git-history findings. */
+export function checkHistory(historySecrets, scanned) {
+    const findings = [];
+    if (!scanned) {
+        findings.push({
+            severity: "info",
+            rule: "history.skipped",
+            message: "Not a git repository - history scan skipped",
+        });
+        return { name: "git-history", findings };
+    }
+    if (historySecrets.length === 0) {
+        findings.push({
+            severity: "success",
+            rule: "history.clean",
+            message: "No secrets found in git history",
+        });
+        return { name: "git-history", findings };
+    }
+    const high = historySecrets.filter((s) => s.confidence !== "medium");
+    const medium = historySecrets.filter((s) => s.confidence === "medium");
+    if (high.length > 0) {
+        findings.push({
+            severity: "error",
+            rule: "history.secret",
+            message: `${high.length} secret${high.length > 1 ? "s" : ""} buried in git history (removed from code but still exposed)`,
+        });
+        for (const s of high) {
+            findings.push({
+                severity: "error",
+                rule: "history.secret-item",
+                message: `${s.kind}: ${s.masked} (commit ${s.commit})`,
+                file: s.file,
+            });
+        }
+    }
+    if (medium.length > 0) {
+        findings.push({
+            severity: "warning",
+            rule: "history.possible",
+            message: `${medium.length} possible secret${medium.length > 1 ? "s" : ""} in git history (lower confidence)`,
+        });
+        for (const s of medium) {
+            findings.push({
+                severity: "warning",
+                rule: "history.possible-item",
+                message: `${s.kind}: ${s.masked} (commit ${s.commit})`,
+                file: s.file,
+            });
+        }
+    }
+    return { name: "git-history", findings };
+}

package/dist/checks/secrets.js

@@ -1,47 +1,263 @@
+import { hasLongRepeat, hasSequentialRun, shannonEntropy, } from "../utils/entropy.js";
+/**
+ * Ordered pattern list: most specific first. The first matching pattern
+ * wins for a given line.
+ */
 const PATTERNS = [
-    { kind: "Anthropic key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/ },
-    { kind: "OpenAI key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{16,}\b/ },
-    { kind: "Google/Gemini key", re: /\bAIza[A-Za-z0-9_-]{30,}\b/ },
-    { kind: "GitHub token", re: /\b(?:ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b/ },
-    { kind: "Stripe live key", re: /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b/ },
-    { kind: "Slack token", re: /\bxox[bp]-[A-Za-z0-9-]{10,}\b/ },
-    { kind: "AWS access key", re: /\bAKIA[A-Z0-9]{16}\b/ },
-    { kind: "Supabase personal token", re: /\bsbp_[a-f0-9]{40}\b/ },
-    { kind: "Vercel token", re: /\bvercel_[A-Za-z0-9]{24,}\b/ },
-    { kind: "npm token", re: /\bnpm_[A-Za-z0-9]{36}\b/ },
-    { kind: "SendGrid key", re: /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/ },
-    { kind: "Twilio credential", re: /\b(?:AC|SK)[a-f0-9]{32}\b/ },
-    { kind: "Telegram bot token", re: /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/ },
     {
-        kind: "Database URL with password",
-        re: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|rediss|amqp):\/\/[^:\s"'@/]+:[^@\s"']+@/,
+        kind: "Private key block",
+        re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP |ENCRYPTED )?PRIVATE KEY(?: BLOCK)?-----/,
+        confidence: "high",
+        skipValueChecks: true,
     },
     {
-        kind: "Private key block",
-        re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/,
+        kind: "AWS access key ID",
+        re: /\b(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "AWS secret access key",
+        re: /\baws_?secret_?access_?key\b.{0,10}[=:]\s*["']?([A-Za-z0-9/+=]{40})\b/i,
+        confidence: "high",
+        group: 1,
+        minEntropy: 3.5,
+    },
+    {
+        kind: "GitHub token",
+        re: /\b(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{20,})\b/,
+        confidence: "high",
+    },
+    {
+        kind: "GitLab token",
+        re: /\bglpat-[A-Za-z0-9_-]{20,}\b/,
+        confidence: "high",
+    },
+    { kind: "Anthropic key", re: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/, confidence: "high" },
+    {
+        kind: "OpenAI key",
+        re: /\bsk-(?:proj-|svcacct-|None-)?[A-Za-z0-9_-]{16,}\b/,
+        confidence: "high",
+        minEntropy: 3.2,
+    },
+    {
+        kind: "Google/Gemini key",
+        re: /\bAIza[A-Za-z0-9_-]{30,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Stripe live key",
+        re: /\b(?:sk|rk)_live_[A-Za-z0-9]{16,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Stripe webhook secret",
+        re: /\bwhsec_[A-Za-z0-9]{24,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Stripe test key",
+        re: /\b(?:sk|rk)_test_[A-Za-z0-9]{16,}\b/,
+        confidence: "medium",
+    },
+    {
+        kind: "Slack token",
+        re: /\bxox[abpsr]-[A-Za-z0-9-]{10,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Slack webhook URL",
+        re: /hooks\.slack\.com\/services\/T[A-Z0-9]{5,}\/B[A-Z0-9]{5,}\/[A-Za-z0-9]{18,}/,
+        confidence: "high",
+    },
+    {
+        kind: "SendGrid key",
+        re: /\bSG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Twilio credential",
+        re: /\b(?:AC|SK)[a-f0-9]{32}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Telegram bot token",
+        re: /\b\d{8,10}:[A-Za-z0-9_-]{35}\b/,
+        confidence: "high",
+    },
+    { kind: "npm token", re: /\bnpm_[A-Za-z0-9]{36}\b/, confidence: "high" },
+    {
+        kind: "Supabase personal token",
+        re: /\bsbp_[a-f0-9]{40}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Vercel token",
+        re: /\bvercel_[A-Za-z0-9]{24,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "DigitalOcean token",
+        re: /\bdo[pors]_v1_[a-f0-9]{64}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Shopify token",
+        re: /\bshp(?:at|ca|pa|ss)_[a-fA-F0-9]{32}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Mailchimp key",
+        re: /\b[a-f0-9]{32}-us\d{1,2}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Mailgun key",
+        re: /\bkey-[a-f0-9]{32}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Airtable token",
+        re: /\bpat[A-Za-z0-9]{14}\.[a-f0-9]{64}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Notion token",
+        re: /\b(?:secret_[A-Za-z0-9]{43}|ntn_[A-Za-z0-9]{40,})\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Linear key",
+        re: /\blin_api_[A-Za-z0-9]{40,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Figma token",
+        re: /\bfigd_[A-Za-z0-9_-]{40,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Hugging Face token",
+        re: /\bhf_[A-Za-z0-9]{30,}\b/,
+        confidence: "high",
+    },
+    { kind: "Groq key", re: /\bgsk_[A-Za-z0-9]{30,}\b/, confidence: "high" },
+    {
+        kind: "Replicate token",
+        re: /\br8_[A-Za-z0-9]{30,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Perplexity key",
+        re: /\bpplx-[A-Za-z0-9]{40,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Databricks token",
+        re: /\bdapi[a-f0-9]{32}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Doppler token",
+        re: /\bdp\.pt\.[A-Za-z0-9]{40,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Postman key",
+        re: /\bPMAK-[a-f0-9]{24}-[a-f0-9]{34}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "PyPI token",
+        re: /\bpypi-AgEIcHlwaS5vcmc[A-Za-z0-9_-]{50,}\b/,
+        confidence: "high",
+    },
+    {
+        kind: "Sentry token",
+        re: /\bsntrys_[A-Za-z0-9_+/=.-]{40,}\b/,
+        confidence: "high",
     },
     {
         kind: "GCP service account key",
         re: /"private_key_id"\s*:\s*"[a-f0-9]{20,}"/,
+        confidence: "high",
+        skipValueChecks: true,
+    },
+    {
+        kind: "Discord webhook URL",
+        re: /discord(?:app)?\.com\/api\/webhooks\/\d{15,20}\/[A-Za-z0-9_-]{60,}/,
+        confidence: "high",
+    },
+    {
+        kind: "Discord bot token",
+        re: /\b[MNO][A-Za-z\d_-]{23,25}\.[A-Za-z\d_-]{6}\.[A-Za-z\d_-]{27,}\b/,
+        confidence: "medium",
+        minEntropy: 4.0,
+    },
+    {
+        // Placeholder checks run against the password only (group 1), so
+        // documentation hosts like db.example.com don't suppress real leaks.
+        kind: "Database URL with password",
+        re: /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis|rediss|amqp):\/\/[^:\s"'@/]+:([^@\s"']+)@/,
+        confidence: "high",
+        group: 1,
+    },
+    {
+        kind: "Basic auth in URL",
+        re: /https?:\/\/[^:\s"'/@]{3,}:([^@\s"']{8,})@/,
+        confidence: "medium",
+        group: 1,
+        minEntropy: 3.0,
     },
     {
         kind: "JWT",
         re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+        confidence: "medium",
+        minEntropy: 4.0,
     },
     {
-        // Credential-style assignment with a long opaque value
+        kind: "Authorization header",
+        re: /\b(?:authorization|x-api-key)["']?\s*[:=]\s*["']?(?:Bearer|Basic|token)\s+([A-Za-z0-9+/_.=-]{20,})\b/i,
+        confidence: "medium",
+        group: 1,
+        minEntropy: 3.5,
+    },
+    {
+        // Credential-style assignment with a long opaque quoted value
         kind: "Hardcoded credential",
-        re: /\b(?:API_KEY|APIKEY|SECRET|SECRET_KEY|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD)\s*[=:]\s*["']?[A-Za-z0-9+/_-]{16,}["']?/i,
+        re: /\b[A-Z0-9_]*(?:API_?KEY|SECRET(?:_KEY)?|ACCESS_TOKEN|AUTH_TOKEN|PASSWORD|PASSWD|CREDENTIALS?)[A-Z0-9_]*\s*[=:]\s*["']([A-Za-z0-9+/_.=-]{16,})["']/i,
+        confidence: "medium",
+        group: 1,
+        minEntropy: 3.8,
     },
 ];
-/** Values that indicate a placeholder, not a real secret. */
-const PLACEHOLDER_RE = /your[-_ ]?|example|placeholder|changeme|change[-_ ]me|dummy|fake|test[-_ ]?key|<[^>]*>|x{4,}|\*{4,}|123456|abcdef/i;
-/** Masks a secret, keeping a short prefix and suffix. */
+/** Words and shapes that indicate a placeholder, not a real secret. */
+const PLACEHOLDER_VALUE_RE = /your[-_ ]?|example|sample|placeholder|change[-_ ]?me|dummy|fake|insert|replace|redacted|deadbeef|lorem|goes[-_ ]?here|test[-_ ]?key|x{4,}|\*{3,}|\.\.\.|123456|abcdef/i;
+/**
+ * Line-level markers for documentation/example lines. Deliberately narrow:
+ * broad words like "example" would hide real keys on lines that merely
+ * mention example.com. Value-level checks handle those instead.
+ */
+const PLACEHOLDER_LINE_RE = /\b(?:do not commit|for docs only|shipready-ignore)\b|<[A-Z_][A-Z0-9_ -]*>/i;
+/** Paths whose findings are downgraded to medium confidence. */
+const TEST_PATH_RE = /(^|[/\\])(tests?|__tests__|__mocks__|spec|specs|fixtures?|mocks?|examples?|samples?|docs?)([/\\]|$)|\.(test|spec)\.[a-z]+$/i;
+/** True when a matched value looks like a placeholder or templated string. */
+function isPlaceholderValue(value) {
+    if (PLACEHOLDER_VALUE_RE.test(value))
+        return true;
+    if (value.includes("${") || value.includes("{{") || value.includes("%s")) {
+        return true;
+    }
+    if (hasLongRepeat(value))
+        return true;
+    if (hasSequentialRun(value))
+        return true;
+    return false;
+}
+/** Masks a secret, keeping a short recognizable prefix and last 4 chars. */
 export function maskSecret(secret) {
     if (secret.length <= 8)
         return "*".repeat(secret.length);
-    // Keep a recognizable prefix (e.g. "sk-proj-ab") and last 4 chars.
-    const prefixMatch = secret.match(/^(sk-ant-|sk-proj-|sk-|sk_live_|rk_live_|ghp_|github_pat_|AIza|xoxb-|xoxp-|AKIA|sbp_|vercel_|npm_|SG\.|AC|SK|eyJ)/);
+    const prefixMatch = secret.match(/^(sk-ant-|sk-proj-|sk-svcacct-|sk-|sk_live_|sk_test_|rk_live_|rk_test_|whsec_|gh[pousr]_|github_pat_|glpat-|AIza|xox[abpsr]-|AKIA|ASIA|sbp_|vercel_|npm_|SG\.|dop_v1_|doo_v1_|dor_v1_|dos_v1_|shpat_|shpca_|shppa_|shpss_|hf_|gsk_|r8_|pplx-|lin_api_|figd_|secret_|ntn_|dapi|dp\.pt\.|PMAK-|pypi-|sntrys_|key-|glsa_|AC|SK|eyJ|pat)/);
     const prefixLen = (prefixMatch?.[0].length ?? 0) + 2;
     const prefix = secret.slice(0, Math.min(prefixLen, secret.length - 4));
     const suffix = secret.slice(-4);
@@ -51,26 +267,43 @@ export function maskSecret(secret) {
 export function scanContentForSecrets(content, file, allowlist = []) {
     const found = [];
     const lines = content.split("\n");
+    const isTestPath = TEST_PATH_RE.test(file);
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        // Skip obvious placeholder lines and comments about examples
-        if (PLACEHOLDER_RE.test(line))
+        // Bundled/minified single-line blobs are noise, not user code.
+        if (line.length > 10000)
+            continue;
+        // Documentation/example lines are not real leaks.
+        if (PLACEHOLDER_LINE_RE.test(line))
             continue;
-        for (const { kind, re } of PATTERNS) {
-            const match = line.match(re);
-            if (match) {
-                // User-configured false positives (substring match on the value or line)
-                if (allowlist.some((a) => match[0].includes(a) || line.includes(a))) {
+        for (const pattern of PATTERNS) {
+            const match = line.match(pattern.re);
+            if (!match)
+                continue;
+            const value = match[pattern.group ?? 0];
+            if (!pattern.skipValueChecks) {
+                if (isPlaceholderValue(value))
+                    continue;
+                if (pattern.minEntropy !== undefined &&
+                    shannonEntropy(value) < pattern.minEntropy) {
                     continue;
                 }
-                found.push({
-                    kind,
-                    file,
-                    line: i + 1,
-                    masked: maskSecret(match[0]),
-                });
-                break; // one finding per line is enough
             }
+            // User-configured false positives (substring match on the value or line)
+            if (allowlist.some((a) => match[0].includes(a) || line.includes(a))) {
+                continue;
+            }
+            const confidence = isTestPath ? "medium" : pattern.confidence;
+            found.push({
+                kind: pattern.kind,
+                file,
+                line: i + 1,
+                masked: maskSecret(value),
+                confidence,
+                // Raw value stays in memory only; used by --verify, never printed.
+                raw: value,
+            });
+            break; // one finding per line is enough
         }
     }
     return found;
@@ -78,24 +311,60 @@ export function scanContentForSecrets(content, file, allowlist = []) {
 /** Builds the CheckResult from all secret findings. */
 export function checkSecrets(secretFindings) {
     const findings = [];
+    const high = secretFindings.filter((s) => s.confidence !== "medium");
+    const medium = secretFindings.filter((s) => s.confidence === "medium");
     if (secretFindings.length === 0) {
         findings.push({
             severity: "success",
             rule: "secrets.none",
             message: "No obvious secrets found",
         });
+        return { name: "secrets", findings };
     }
-    else {
+    const verifiedActive = secretFindings.filter((s) => s.verified === "active");
+    if (verifiedActive.length > 0) {
+        findings.push({
+            severity: "error",
+            rule: "secrets.verified-active",
+            message: `${verifiedActive.length} key${verifiedActive.length > 1 ? "s" : ""} VERIFIED ACTIVE - rotate immediately`,
+        });
+    }
+    /** Suffix describing the live verification result, when available. */
+    const verifyNote = (s) => {
+        if (s.verified === "active")
+            return " [VERIFIED ACTIVE]";
+        if (s.verified === "inactive")
+            return " [not active - rotate anyway]";
+        return "";
+    };
+    if (high.length > 0) {
         findings.push({
             severity: "error",
             rule: "secrets.detected",
-            message: `${secretFindings.length} potential secret${secretFindings.length > 1 ? "s" : ""} detected`,
+            message: `${high.length} potential secret${high.length > 1 ? "s" : ""} detected`,
         });
-        for (const s of secretFindings) {
+        for (const s of high) {
             findings.push({
                 severity: "error",
                 rule: "secrets.detected-item",
-                message: `${s.kind}: ${s.masked}`,
+                message: `${s.kind}: ${s.masked}${verifyNote(s)}`,
+                file: s.file,
+                line: s.line,
+            });
+        }
+    }
+    if (medium.length > 0) {
+        findings.push({
+            severity: "warning",
+            rule: "secrets.possible",
+            message: `${medium.length} possible secret${medium.length > 1 ? "s" : ""} detected (lower confidence)`,
+        });
+        for (const s of medium) {
+            findings.push({
+                // A verified-active key is an error no matter the pattern confidence.
+                severity: s.verified === "active" ? "error" : "warning",
+                rule: s.verified === "active" ? "secrets.detected-item" : "secrets.possible-item",
+                message: `${s.kind}: ${s.masked}${verifyNote(s)}`,
                 file: s.file,
                 line: s.line,
             });

package/dist/checks/verify.js

@@ -0,0 +1,106 @@
+const TIMEOUT_MS = 6000;
+/** fetch with an AbortController timeout; never throws. */
+async function timedFetch(url, init) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        return await fetch(url, { ...init, signal: ctrl.signal });
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Maps an HTTP status to a verification result using a common convention:
+ * 401/403 => the key was understood but rejected (inactive/revoked),
+ * 2xx     => accepted (active),
+ * anything else (network, 404, 5xx, rate limit) => unknown.
+ */
+function statusToResult(res) {
+    if (!res)
+        return "unknown";
+    if (res.ok)
+        return "active";
+    if (res.status === 401 || res.status === 403)
+        return "inactive";
+    return "unknown";
+}
+/**
+ * Verifiers keyed by finding.kind. Only providers with a safe, well-known
+ * "who am I" endpoint are included. Everything else stays "unknown".
+ */
+const VERIFIERS = {
+    "OpenAI key": async (raw) => statusToResult(await timedFetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${raw}` },
+    })),
+    "Anthropic key": async (raw) => {
+        // /v1/models requires the key; 401 => bad key, 200 => good.
+        const res = await timedFetch("https://api.anthropic.com/v1/models", {
+            headers: { "x-api-key": raw, "anthropic-version": "2023-06-01" },
+        });
+        return statusToResult(res);
+    },
+    "GitHub token": async (raw) => statusToResult(await timedFetch("https://api.github.com/user", {
+        headers: {
+            Authorization: `Bearer ${raw}`,
+            "User-Agent": "shipready",
+            Accept: "application/vnd.github+json",
+        },
+    })),
+    "GitLab token": async (raw) => statusToResult(await timedFetch("https://gitlab.com/api/v4/user", {
+        headers: { "PRIVATE-TOKEN": raw },
+    })),
+    "Stripe live key": async (raw) => statusToResult(await timedFetch("https://api.stripe.com/v1/account", {
+        headers: { Authorization: `Bearer ${raw}` },
+    })),
+    "Stripe test key": async (raw) => statusToResult(await timedFetch("https://api.stripe.com/v1/account", {
+        headers: { Authorization: `Bearer ${raw}` },
+    })),
+    "SendGrid key": async (raw) => statusToResult(await timedFetch("https://api.sendgrid.com/v3/scopes", {
+        headers: { Authorization: `Bearer ${raw}` },
+    })),
+    "Google/Gemini key": async (raw) => statusToResult(await timedFetch(`https://generativelanguage.googleapis.com/v1beta/models?key=${encodeURIComponent(raw)}`, {})),
+    "npm token": async (raw) => statusToResult(await timedFetch("https://registry.npmjs.org/-/whoami", {
+        headers: { Authorization: `Bearer ${raw}` },
+    })),
+    "Hugging Face token": async (raw) => statusToResult(await timedFetch("https://huggingface.co/api/whoami-v2", {
+        headers: { Authorization: `Bearer ${raw}` },
+    })),
+    "Figma token": async (raw) => statusToResult(await timedFetch("https://api.figma.com/v1/me", {
+        headers: { "X-Figma-Token": raw },
+    })),
+    "GitHub fine-grained token": async (raw) => statusToResult(await timedFetch("https://api.github.com/user", {
+        headers: {
+            Authorization: `Bearer ${raw}`,
+            "User-Agent": "shipready",
+        },
+    })),
+};
+/** Number of providers shipready can actively verify. */
+export const VERIFIABLE_KINDS = Object.keys(VERIFIERS);
+/**
+ * Verifies findings against provider APIs, mutating each finding's
+ * `verified` field in place. Runs with limited concurrency and only for
+ * findings whose `kind` has a known verifier and whose `raw` value is present.
+ */
+export async function verifySecrets(findings, concurrency = 5) {
+    const targets = findings.filter((f) => f.raw && VERIFIERS[f.kind]);
+    let cursor = 0;
+    async function worker() {
+        while (cursor < targets.length) {
+            const finding = targets[cursor++];
+            try {
+                finding.verified = await VERIFIERS[finding.kind](finding.raw);
+            }
+            catch {
+                finding.verified = "unknown";
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, targets.length) }, worker));
+    // Findings we didn't verify stay undefined (rendered as no live info).
+    return findings;
+}

package/dist/cli.js

@@ -69,14 +69,20 @@ export function buildProgram() {
         .option("-v, --verbose", "show file locations for every finding")
         .option("--json", "output the raw report as JSON")
         .option("--fix", "apply safe fixes, then re-scan and show the improved report")
+        .option("--history", "also scan the full git history for leaked secrets")
+        .option("--verify", "check detected keys against provider APIs to see if they are live")
         .action(async (dir, opts) => {
         try {
             const root = resolveRoot(dir);
-            let report = await runScan(root);
+            const scanOpts = { history: opts.history, verify: opts.verify };
+            if (opts.verify && !opts.json) {
+                console.log(pc.dim("\n  Verifying detected keys against provider APIs..."));
+            }
+            let report = await runScan(root, scanOpts);
             if (opts.fix) {
                 const before = report.score;
                 const results = await applyFixes(root, false);
-                report = await runScan(root);
+                report = await runScan(root, scanOpts);
                 if (!opts.json) {
                     console.log("");
                     console.log(pc.bold(pc.magenta("shipready check --fix")));
@@ -92,7 +98,7 @@ export function buildProgram() {
                 console.log(JSON.stringify(report, null, 2));
             }
             else {
-                console.log(renderReport(report, opts.verbose ?? false));
+                console.log(renderReport(report, opts.verbose ?? false, ownVersion()));
             }
             // Non-zero exit when errors are present, useful for CI.
             const hasErrors = report.results.some((r) => r.findings.some((f) => f.severity === "error"));

package/dist/scanner.js

@@ -4,6 +4,8 @@ import { checkGitignore } from "./checks/gitignore.js";
 import { checkPackageJson } from "./checks/packageJson.js";
 import { checkReadme } from "./checks/readme.js";
 import { checkSecrets, scanContentForSecrets } from "./checks/secrets.js";
+import { checkHistory, isGitRepo, scanGitHistory } from "./checks/history.js";
+import { verifySecrets } from "./checks/verify.js";
 import { checkTodos, scanContentForTodos } from "./checks/todos.js";
 import { fileExists, findSourceFiles, isProbablyBinary, readJsonFile, readTextFile, } from "./utils/files.js";
 import { detectFramework, detectPackageManager } from "./utils/framework.js";
@@ -80,6 +82,8 @@ export function calculateScore(results) {
         score -= 15;
     const secretCount = count("secrets.detected-item");
     score -= Math.min(secretCount * 25, 50);
+    const historyCount = count("history.secret-item");
+    score -= Math.min(historyCount * 10, 30);
     const todoCount = count("todos.item");
     score -= Math.min(todoCount * 2, 15);
     return Math.max(0, score);
@@ -94,15 +98,27 @@ function applyDisabledRules(results, disableRules) {
     }));
 }
 /** Runs the full scan and returns a structured report. */
-export async function runScan(root) {
+export async function runScan(root, options = {}) {
     const config = loadConfig(root);
     const project = await detectProject(root, config);
     const { envUsages, secrets, todos } = scanFiles(root, project.sourceFiles, config.secretAllowlist);
+    let historySecrets = [];
+    let historyScanned = false;
+    if (options.history) {
+        historyScanned = isGitRepo(root);
+        if (historyScanned) {
+            historySecrets = scanGitHistory(root, config.secretAllowlist, secrets);
+        }
+    }
+    if (options.verify) {
+        await verifySecrets([...secrets, ...historySecrets]);
+    }
     const rawResults = [
         checkPackageJson(project),
         checkReadme(root),
         checkEnv(root, envUsages),
         checkSecrets(secrets),
+        ...(options.history ? [checkHistory(historySecrets, historyScanned)] : []),
         checkTodos(todos),
         checkGitignore(root),
     ];

package/dist/utils/entropy.js

@@ -0,0 +1,42 @@
+/**
+ * String randomness heuristics used by the secret scanner.
+ *
+ * Real credentials are generated by CSPRNGs, so they have high Shannon
+ * entropy and no human-friendly structure. Placeholders and dictionary
+ * words score much lower, which lets us separate the two without
+ * hardcoding every possible fake value.
+ */
+/** Shannon entropy of a string, in bits per character. */
+export function shannonEntropy(s) {
+    if (s.length === 0)
+        return 0;
+    const freq = new Map();
+    for (const ch of s)
+        freq.set(ch, (freq.get(ch) ?? 0) + 1);
+    let entropy = 0;
+    for (const count of freq.values()) {
+        const p = count / s.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+/** True when the string contains a run of 5+ identical characters (e.g. "aaaaa", "-----"). */
+export function hasLongRepeat(s) {
+    return /(.)\1{4,}/.test(s);
+}
+/**
+ * True when the string contains a long ascending or descending character
+ * run such as "abcdefgh" or "87654321" — a strong placeholder signal.
+ */
+export function hasSequentialRun(s, minRun = 8) {
+    let asc = 1;
+    let desc = 1;
+    for (let i = 1; i < s.length; i++) {
+        const d = s.charCodeAt(i) - s.charCodeAt(i - 1);
+        asc = d === 1 ? asc + 1 : 1;
+        desc = d === -1 ? desc + 1 : 1;
+        if (asc >= minRun || desc >= minRun)
+            return true;
+    }
+    return false;
+}

package/dist/utils/report.js

@@ -5,6 +5,59 @@ const ICONS = {
     warning: pc.yellow("\u26a0"),
     info: pc.cyan("\u2139"),
 };
+/** Inner width of the report layout (visible characters). */
+const WIDTH = 56;
+/** Visible length of a string, ignoring ANSI escape codes. */
+function visibleLength(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\u001b\[[0-9;]*m/g, "").length;
+}
+/** Pads a string (which may contain ANSI codes) to a visible width. */
+function padVisible(s, width) {
+    const len = visibleLength(s);
+    return len >= width ? s : s + " ".repeat(width - len);
+}
+/** Draws a rounded box around the given lines. */
+function box(lines) {
+    const top = pc.dim("\u256d" + "\u2500".repeat(WIDTH + 2) + "\u256e");
+    const bottom = pc.dim("\u2570" + "\u2500".repeat(WIDTH + 2) + "\u256f");
+    const body = lines.map((l) => `${pc.dim("\u2502")} ${padVisible(l, WIDTH)} ${pc.dim("\u2502")}`);
+    return [top, ...body, bottom];
+}
+/** Renders the score progress bar. */
+function scoreBar(score) {
+    const total = 28;
+    const filled = Math.max(0, Math.min(total, Math.round((score / 100) * total)));
+    const fill = "\u2588".repeat(filled);
+    const rest = "\u2591".repeat(total - filled);
+    const painted = score >= 85 ? pc.green(fill) : score >= 60 ? pc.yellow(fill) : pc.red(fill);
+    return painted + pc.dim(rest);
+}
+function scoreLabel(score) {
+    const label = `${score}/100`;
+    if (score >= 85)
+        return pc.bold(pc.green(label));
+    if (score >= 60)
+        return pc.bold(pc.yellow(label));
+    return pc.bold(pc.red(label));
+}
+function verdict(score) {
+    if (score >= 85)
+        return pc.green("ready to ship");
+    if (score >= 60)
+        return pc.yellow("almost there");
+    return pc.red("not ready to ship");
+}
+/** Human-friendly labels for check names. */
+const CHECK_LABELS = {
+    "package.json": "package.json",
+    README: "README",
+    env: "Env safety",
+    secrets: "Secrets",
+    todos: "Code hygiene",
+    gitignore: ".gitignore",
+    "git-history": "Git history",
+};
 function colorFor(severity, text) {
     switch (severity) {
         case "success":
@@ -17,23 +70,19 @@ function colorFor(severity, text) {
             return pc.cyan(text);
     }
 }
-function scoreColor(score) {
-    const label = `${score}/100`;
-    if (score >= 85)
-        return pc.green(label);
-    if (score >= 60)
-        return pc.yellow(label);
-    return pc.red(label);
-}
 /** Builds recommended next steps from findings, highest severity first. */
 export function nextSteps(report) {
     const steps = [];
     const all = report.results.flatMap((r) => r.findings);
     const has = (rule) => all.some((f) => f.rule === rule);
+    if (has("secrets.verified-active"))
+        steps.push("A key was VERIFIED ACTIVE - rotate it right now");
     if (has("package-json.missing"))
         steps.push("Add a package.json (npm init -y)");
     if (has("secrets.detected"))
         steps.push("Rotate and remove hardcoded secrets immediately");
+    if (has("history.secret"))
+        steps.push("Purge leaked secrets from git history (BFG or git filter-repo) and rotate them");
     if (has("env.not-ignored"))
         steps.push("Add .env to .gitignore");
     if (has("env.example-missing"))
@@ -56,21 +105,45 @@ export function nextSteps(report) {
         steps.push("Resolve TODO/FIXME comments or track them as issues");
     return steps;
 }
+/** Worst severity across a set of findings (error > warning > info > success). */
+function worst(findings) {
+    if (findings.some((f) => f.severity === "error"))
+        return "error";
+    if (findings.some((f) => f.severity === "warning"))
+        return "warning";
+    if (findings.some((f) => f.severity === "info"))
+        return "info";
+    return "success";
+}
 /** Renders the full report to a printable string. */
-export function renderReport(report, verbose = false) {
+export function renderReport(report, verbose = false, version) {
     const lines = [];
     const { project } = report;
+    const title = pc.bold(pc.magenta("shipready")) + (version ? pc.dim(` v${version}`) : "");
+    const meta = pc.dim("project ") +
+        project.framework +
+        pc.dim("  \u00b7  ") +
+        pc.dim("pm ") +
+        project.packageManager;
     lines.push("");
-    lines.push(pc.bold(pc.magenta("shipready report")));
+    lines.push(...box([title, meta]));
     lines.push("");
-    lines.push(`${pc.dim("Project:")} ${project.framework}`);
-    lines.push(`${pc.dim("Package manager:")} ${project.packageManager}`);
+    lines.push(`  ${pc.bold("Score")}  ${scoreBar(report.score)}  ${scoreLabel(report.score)}  ${verdict(report.score)}`);
     lines.push("");
-    lines.push(pc.bold("Summary:"));
+    // Aligned checks table: one row per check, then its top-level findings.
+    const labelWidth = Math.max(...report.results.map((r) => (CHECK_LABELS[r.name] ?? r.name).length));
     for (const result of report.results) {
-        for (const finding of summarize(result.findings)) {
-            lines.push(`${ICONS[finding.severity]} ${finding.message}`);
+        const label = CHECK_LABELS[result.name] ?? result.name;
+        const summaryFindings = result.findings.filter((f) => !f.file);
+        const status = worst(result.findings);
+        if (summaryFindings.length === 0) {
+            lines.push(`  ${ICONS[status]} ${pc.bold(padVisible(label, labelWidth))}  ${pc.dim("ok")}`);
+            continue;
         }
+        summaryFindings.forEach((finding, i) => {
+            const name = i === 0 ? pc.bold(padVisible(label, labelWidth)) : " ".repeat(labelWidth);
+            lines.push(`  ${ICONS[finding.severity]} ${name}  ${finding.message}`);
+        });
     }
     // Detailed findings with file locations
     const located = report.results
@@ -78,31 +151,22 @@ export function renderReport(report, verbose = false) {
         .filter((f) => f.file && f.severity !== "success");
     if (located.length > 0 && verbose) {
         lines.push("");
-        lines.push(pc.bold("Details:"));
+        lines.push(`  ${pc.bold("Details")}`);
         for (const f of located) {
             const loc = f.line ? `${f.file}:${f.line}` : f.file;
-            lines.push(`  ${ICONS[f.severity]} ${pc.dim(loc ?? "")} ${colorFor(f.severity, f.message)}`);
+            lines.push(`    ${ICONS[f.severity]} ${pc.dim(loc ?? "")} ${colorFor(f.severity, f.message)}`);
         }
     }
-    lines.push("");
-    lines.push(`${pc.bold("Score:")} ${scoreColor(report.score)}`);
     const steps = nextSteps(report);
     if (steps.length > 0) {
         lines.push("");
-        lines.push(pc.bold("Recommended next steps:"));
-        steps.forEach((step, i) => lines.push(`${i + 1}. ${step}`));
+        lines.push(`  ${pc.bold("Next steps")}`);
+        steps.forEach((step, i) => lines.push(`    ${pc.dim(`${i + 1}.`)} ${step}`));
     }
     if (located.length > 0 && !verbose) {
         lines.push("");
-        lines.push(pc.dim("Run with --verbose to see file locations."));
+        lines.push(pc.dim("  Run with --verbose to see file locations."));
     }
     lines.push("");
     return lines.join("\n");
 }
-/**
- * Collapses per-file findings into summary lines while keeping
- * top-level findings (those without a file) as-is.
- */
-function summarize(findings) {
-    return findings.filter((f) => !f.file);
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipready",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Pre-flight check for your repo before shipping. Scans AI-coded projects for secrets, env issues, debug leftovers, and generates AI-agent instruction files.",
   "type": "module",
   "license": "MIT",