shipready 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shipready contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# shipready
+
+> Pre-flight check for your repo before shipping.
+
+[![CI](https://github.com/formalness/shipready/actions/workflows/ci.yml/badge.svg)](https://github.com/formalness/shipready/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/shipready.svg)](https://www.npmjs.com/package/shipready)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![node >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+shipready is a CLI for developers who build with AI and vibe-coding tools. It scans your project for the things AI-generated code tends to leave behind — hardcoded secrets, missing `.env.example` files, debug logs, unfinished TODOs, and broken repo hygiene — and helps you fix them before you ship.
+
+**No API key required. Works fully offline. No telemetry.**
+
+## Why shipready exists
+
+AI coding tools are great at producing working code fast, but they routinely:
+
+- paste API keys directly into source files
+- forget `.env.example` while sprinkling `process.env.X` everywhere
+- leave `console.log`, `debugger`, and `TODO` breadcrumbs all over
+- skip README setup instructions entirely
+- ignore `.gitignore` hygiene
+
+shipready catches all of that in seconds, scores your repo, and can auto-fix the safe stuff.
+
+## Installation
+
+```bash
+# Run directly
+npx shipready check
+
+# Or install globally
+npm install -g shipready
+shipready check
+```
+
+## Usage
+
+```bash
+shipready check [path]   # scan a project (current dir by default)
+shipready init  [path]   # generate AI-agent instruction files
+shipready fix   [path]   # apply safe automatic fixes
+```
+
+## Commands
+
+### `shipready check [path]`
+
+Scans the project and prints a report with a 0-100 score.
+
+| Flag | Effect |
+| --- | --- |
+| `-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 |
+
+Exits with code `1` when errors are found, so you can use it in CI pipelines.
+
+### `shipready init [path]`
+
+Generates AI-agent instruction files based on your detected framework, package manager, and scripts:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.cursor/rules/shipready.md`
+
+Existing files are never overwritten unless you pass `--force`.
+
+### `shipready fix [path]`
+
+Applies safe automatic fixes:
+
+- creates `.env.example` from detected `process.env.X` usages (keys only, no values)
+- adds missing entries to `.gitignore` (`.env`, `node_modules`, `dist`, ...)
+- generates the AI-agent files above if missing
+
+It never deletes user code and never overwrites files without `--force`. A summary of changed files is printed at the end.
+
+## 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
+```
+
+## What it checks
+
+| Check | What it looks for |
+| --- | --- |
+| **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) |
+| **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`) |
+
+Ignored during scans: `node_modules`, `.git`, `dist`, `build`, `.next`, `out`, `coverage`, `.cache`.
+
+## Detected secrets
+
+| 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...` |
+| Supabase | `sbp_...` |
+| Vercel | `vercel_...` |
+| npm | `npm_...` |
+| SendGrid | `SG.xxx.xxx` |
+| Twilio | `AC` / `SK` + 32 hex |
+| Telegram bot | `123456789:AA...` |
+| 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.
+
+## Configuration
+
+Optional `shipready.config.json` in your project root:
+
+```json
+{
+  "ignore": ["fixtures/**", "docs/**"],
+  "disableRules": ["todos", "readme.weak"],
+  "secretAllowlist": ["not-a-real-key-used-in-tests"]
+}
+```
+
+| Field | Purpose |
+| --- | --- |
+| `ignore` | Extra glob patterns excluded from scanning (on top of the built-in ignores) |
+| `disableRules` | Rule ids (`readme.weak`) or whole checks (`todos`) to disable; disabled rules don't affect the score |
+| `secretAllowlist` | Substrings marking known false positives; matching lines are not reported |
+
+## Using in CI
+
+`shipready check` exits with code `1` when errors are found:
+
+```yaml
+# .github/workflows/quality.yml
+name: Quality gate
+on: [push, pull_request]
+jobs:
+  shipready:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx shipready check --verbose
+```
+
+Use `--json` to feed the report into other tooling.
+
+## Scoring
+
+Every project starts at 100 and loses points for issues:
+
+| Issue | Deduction |
+| --- | --- |
+| Missing package.json | -20 |
+| Missing README | -15 |
+| Weak README | -8 |
+| Missing build script | -8 |
+| Missing test script | -6 |
+| Missing .env.example (when env vars exist) | -10 |
+| .env not gitignored | -15 |
+| Possible secret | -25 each (max -50) |
+| TODO/debug leftovers | -2 each (max -15) |
+
+The score never goes below 0.
+
+## Development
+
+```bash
+pnpm install
+pnpm build    # compile TypeScript to dist/
+pnpm test     # run Vitest suite
+pnpm dev      # run the CLI from source (tsx)
+```
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for project structure and how to add new checks or secret patterns.
+
+## Roadmap
+
+- [ ] Optional AI-powered fix suggestions (bring your own key)
+- [ ] `shipready check --staged` for pre-commit hooks
+- [ ] Markdown/SARIF report output for GitHub code scanning
+- [ ] More frameworks and secret providers
+
+## License
+
+[MIT](./LICENSE)

package/dist/checks/env.js

@@ -0,0 +1,156 @@
+import { fileExists, readTextFile } from "../utils/files.js";
+const ENV_USAGE_RE = /process\.env\.([A-Z][A-Z0-9_]*)/g;
+const IMPORT_META_ENV_RE = /import\.meta\.env\.([A-Z][A-Z0-9_]*)/g;
+/** Built-in variables that don't need to be in .env.example. */
+const BUILTIN_VARS = new Set([
+    "NODE_ENV",
+    "CI",
+    "PORT",
+    "HOME",
+    "PATH",
+    "PWD",
+    "TZ",
+    "MODE",
+    "DEV",
+    "PROD",
+    "SSR",
+    "BASE_URL",
+]);
+/** Extracts `process.env` / `import.meta.env` variable usages from source code. */
+export function extractEnvUsages(content, file) {
+    const usages = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        for (const re of [ENV_USAGE_RE, IMPORT_META_ENV_RE]) {
+            re.lastIndex = 0;
+            let match;
+            while ((match = re.exec(lines[i])) !== null) {
+                const name = match[1];
+                if (!BUILTIN_VARS.has(name)) {
+                    usages.push({ name, file, line: i + 1 });
+                }
+            }
+        }
+    }
+    return usages;
+}
+/** Parses variable names from a dotenv-format file. */
+export function parseEnvKeys(content) {
+    const keys = [];
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, "");
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            keys.push(key);
+    }
+    return keys;
+}
+/** Values in .env.example that look like real secrets rather than placeholders. */
+export function findRealLookingExampleValues(content) {
+    const suspicious = [];
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+        if (!value)
+            continue;
+        const lower = value.toLowerCase();
+        const placeholder = lower.includes("your") ||
+            lower.includes("example") ||
+            lower.includes("placeholder") ||
+            lower.includes("changeme") ||
+            lower.includes("xxx") ||
+            lower.includes("<") ||
+            lower === "true" ||
+            lower === "false" ||
+            /^\d+$/.test(value) ||
+            value.length < 8;
+        // Long, high-entropy-looking values that aren't placeholders
+        if (!placeholder && /^[A-Za-z0-9+/_.-]{20,}$/.test(value)) {
+            suspicious.push(key);
+        }
+    }
+    return suspicious;
+}
+/** Checks .env / .env.example / gitignore safety around env vars. */
+export function checkEnv(root, envUsages) {
+    const findings = [];
+    const hasEnv = fileExists(root, ".env");
+    const exampleContent = readTextFile(root, ".env.example") ?? readTextFile(root, ".env.sample");
+    const hasExample = exampleContent !== null;
+    const gitignore = readTextFile(root, ".gitignore") ?? "";
+    const usedVars = [...new Set(envUsages.map((u) => u.name))];
+    // .env should be gitignored if it exists
+    if (hasEnv) {
+        const ignored = gitignore
+            .split("\n")
+            .map((l) => l.trim())
+            .some((l) => l === ".env" || l === ".env*" || l === "*.env");
+        if (ignored) {
+            findings.push({
+                severity: "success",
+                rule: "env.ignored",
+                message: ".env is ignored by git",
+            });
+        }
+        else {
+            findings.push({
+                severity: "error",
+                rule: "env.not-ignored",
+                message: ".env is not ignored by git",
+            });
+        }
+    }
+    // .env.example presence
+    if (usedVars.length > 0 && !hasExample) {
+        findings.push({
+            severity: "error",
+            rule: "env.example-missing",
+            message: `.env.example missing (${usedVars.length} env var${usedVars.length > 1 ? "s" : ""} used in code)`,
+        });
+    }
+    else if (hasExample) {
+        findings.push({
+            severity: "success",
+            rule: "env.example-found",
+            message: ".env.example found",
+        });
+        // Are all used vars documented?
+        const exampleKeys = new Set(parseEnvKeys(exampleContent));
+        const undocumented = usedVars.filter((v) => !exampleKeys.has(v));
+        if (undocumented.length > 0) {
+            findings.push({
+                severity: "warning",
+                rule: "env.example-incomplete",
+                message: `.env.example missing variables: ${undocumented.join(", ")}`,
+            });
+        }
+        // Real-looking secrets in the example file?
+        const leaky = findRealLookingExampleValues(exampleContent);
+        if (leaky.length > 0) {
+            findings.push({
+                severity: "warning",
+                rule: "env.example-real-values",
+                message: `.env.example has real-looking values for: ${leaky.join(", ")}`,
+            });
+        }
+    }
+    else if (usedVars.length === 0) {
+        findings.push({
+            severity: "info",
+            rule: "env.none-used",
+            message: "No environment variables detected in code",
+        });
+    }
+    return { name: "env", findings };
+}

package/dist/checks/gitignore.js

@@ -0,0 +1,56 @@
+import { readTextFile } from "../utils/files.js";
+export const IMPORTANT_IGNORES = [
+    ".env",
+    ".env.local",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+];
+/** Returns which important entries are missing from gitignore content. */
+export function missingIgnoreEntries(content) {
+    const lines = content
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith("#"));
+    const covers = (entry) => lines.some((l) => {
+        const normalized = l.replace(/\/+$/, "").replace(/^\//, "");
+        if (normalized === entry)
+            return true;
+        // ".env*" covers ".env" and ".env.local"
+        if (normalized === ".env*" && entry.startsWith(".env"))
+            return true;
+        // "node_modules/" style already normalized above
+        return false;
+    });
+    return IMPORTANT_IGNORES.filter((e) => !covers(e));
+}
+/** Checks .gitignore existence and important entries. */
+export function checkGitignore(root) {
+    const findings = [];
+    const content = readTextFile(root, ".gitignore");
+    if (content === null) {
+        findings.push({
+            severity: "error",
+            rule: "gitignore.missing",
+            message: ".gitignore missing",
+        });
+        return { name: "gitignore", findings };
+    }
+    const missing = missingIgnoreEntries(content);
+    if (missing.length > 0) {
+        findings.push({
+            severity: "warning",
+            rule: "gitignore.incomplete",
+            message: `.gitignore missing entries: ${missing.join(", ")}`,
+        });
+    }
+    else {
+        findings.push({
+            severity: "success",
+            rule: "gitignore.complete",
+            message: ".gitignore covers important entries",
+        });
+    }
+    return { name: "gitignore", findings };
+}

package/dist/checks/packageJson.js

@@ -0,0 +1,34 @@
+const IMPORTANT_SCRIPTS = ["dev", "build", "test", "lint"];
+/** Checks package.json existence and important scripts. */
+export function checkPackageJson(project) {
+    const findings = [];
+    if (!project.hasPackageJson) {
+        findings.push({
+            severity: "error",
+            rule: "package-json.missing",
+            message: "package.json missing",
+        });
+        return { name: "package.json", findings };
+    }
+    findings.push({
+        severity: "success",
+        rule: "package-json.found",
+        message: "package.json found",
+    });
+    const missing = IMPORTANT_SCRIPTS.filter((s) => !project.scripts[s]);
+    if (missing.length > 0) {
+        findings.push({
+            severity: "warning",
+            rule: "scripts.missing",
+            message: `Missing script${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}`,
+        });
+    }
+    else {
+        findings.push({
+            severity: "success",
+            rule: "scripts.found",
+            message: "All important scripts present (dev, build, test, lint)",
+        });
+    }
+    return { name: "package.json", findings };
+}

package/dist/checks/readme.js

@@ -0,0 +1,47 @@
+import { readTextFile } from "../utils/files.js";
+const SECTION_KEYWORDS = [
+    "installation",
+    "install",
+    "usage",
+    "quickstart",
+    "quick start",
+    "getting started",
+    "environment variables",
+    "development",
+    "build",
+    "license",
+];
+/** Minimum character count for a README to not be considered "too empty". */
+const MIN_README_LENGTH = 200;
+/** Minimum number of keyword hits for a README to be considered useful. */
+const MIN_KEYWORD_HITS = 2;
+/** Checks README existence and quality heuristics. */
+export function checkReadme(root) {
+    const findings = [];
+    const content = readTextFile(root, "README.md") ??
+        readTextFile(root, "readme.md") ??
+        readTextFile(root, "Readme.md");
+    if (content === null) {
+        findings.push({
+            severity: "error",
+            rule: "readme.missing",
+            message: "README.md missing",
+        });
+        return { name: "README", findings };
+    }
+    findings.push({
+        severity: "success",
+        rule: "readme.found",
+        message: "README.md found",
+    });
+    const lower = content.toLowerCase();
+    const hits = SECTION_KEYWORDS.filter((k) => lower.includes(k)).length;
+    if (content.trim().length < MIN_README_LENGTH || hits < MIN_KEYWORD_HITS) {
+        findings.push({
+            severity: "warning",
+            rule: "readme.weak",
+            message: "README looks thin - add installation and usage instructions",
+        });
+    }
+    return { name: "README", findings };
+}

package/dist/checks/secrets.js

@@ -0,0 +1,105 @@
+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 )?PRIVATE KEY-----/,
+    },
+    {
+        kind: "GCP service account key",
+        re: /"private_key_id"\s*:\s*"[a-f0-9]{20,}"/,
+    },
+    {
+        kind: "JWT",
+        re: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/,
+    },
+    {
+        // Credential-style assignment with a long opaque 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,
+    },
+];
+/** 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. */
+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 prefixLen = (prefixMatch?.[0].length ?? 0) + 2;
+    const prefix = secret.slice(0, Math.min(prefixLen, secret.length - 4));
+    const suffix = secret.slice(-4);
+    return `${prefix}...${suffix}`;
+}
+/** Scans a single file's content for potential secrets. */
+export function scanContentForSecrets(content, file, allowlist = []) {
+    const found = [];
+    const lines = content.split("\n");
+    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))
+            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))) {
+                    continue;
+                }
+                found.push({
+                    kind,
+                    file,
+                    line: i + 1,
+                    masked: maskSecret(match[0]),
+                });
+                break; // one finding per line is enough
+            }
+        }
+    }
+    return found;
+}
+/** Builds the CheckResult from all secret findings. */
+export function checkSecrets(secretFindings) {
+    const findings = [];
+    if (secretFindings.length === 0) {
+        findings.push({
+            severity: "success",
+            rule: "secrets.none",
+            message: "No obvious secrets found",
+        });
+    }
+    else {
+        findings.push({
+            severity: "error",
+            rule: "secrets.detected",
+            message: `${secretFindings.length} potential secret${secretFindings.length > 1 ? "s" : ""} detected`,
+        });
+        for (const s of secretFindings) {
+            findings.push({
+                severity: "error",
+                rule: "secrets.detected-item",
+                message: `${s.kind}: ${s.masked}`,
+                file: s.file,
+                line: s.line,
+            });
+        }
+    }
+    return { name: "secrets", findings };
+}