shipready 1.0.0

package/dist/checks/todos.js

@@ -0,0 +1,72 @@
+const MARKER_RE = /\b(TODO|FIXME|HACK|XXX)\b/;
+const DEBUG_PATTERNS = [
+    { label: "console.log", re: /\bconsole\.log\s*\(/ },
+    { label: "debugger", re: /^\s*debugger\b/ },
+    {
+        label: "not implemented",
+        re: /throw new Error\((?:"Not implemented"|'Not implemented')\)/,
+    },
+];
+/** Scans a file's content for TODO/debug markers. */
+export function scanContentForTodos(content, file) {
+    const found = [];
+    const lines = content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const marker = line.match(MARKER_RE);
+        if (marker) {
+            found.push({ kind: "marker", label: marker[1], file, line: i + 1 });
+        }
+        for (const { label, re } of DEBUG_PATTERNS) {
+            if (re.test(line)) {
+                found.push({ kind: "debug", label, file, line: i + 1 });
+            }
+        }
+    }
+    return found;
+}
+/** Builds the CheckResult from all todo/debug findings. */
+export function checkTodos(todoFindings) {
+    const findings = [];
+    const markers = todoFindings.filter((f) => f.kind === "marker");
+    const debug = todoFindings.filter((f) => f.kind === "debug");
+    if (markers.length === 0 && debug.length === 0) {
+        findings.push({
+            severity: "success",
+            rule: "todos.clean",
+            message: "No TODO/FIXME or debug leftovers found",
+        });
+        return { name: "todos", findings };
+    }
+    if (markers.length > 0) {
+        findings.push({
+            severity: "warning",
+            rule: "todos.markers",
+            message: `${markers.length} TODO/FIXME comment${markers.length > 1 ? "s" : ""} found`,
+        });
+    }
+    if (debug.length > 0) {
+        const logs = debug.filter((d) => d.label === "console.log").length;
+        const other = debug.length - logs;
+        const parts = [];
+        if (logs > 0)
+            parts.push(`${logs} console.log call${logs > 1 ? "s" : ""}`);
+        if (other > 0)
+            parts.push(`${other} other debug marker${other > 1 ? "s" : ""}`);
+        findings.push({
+            severity: "warning",
+            rule: "todos.debug",
+            message: `${parts.join(" and ")} found`,
+        });
+    }
+    for (const f of todoFindings) {
+        findings.push({
+            severity: "info",
+            rule: "todos.item",
+            message: f.label,
+            file: f.file,
+            line: f.line,
+        });
+    }
+    return { name: "todos", findings };
+}

package/dist/cli.js

@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import pc from "picocolors";
+import { detectProject, runScan, scanFiles } from "./scanner.js";
+import { loadConfig } from "./config.js";
+import { fixAgentFiles } from "./fixers/agentFiles.js";
+import { fixEnvExample } from "./fixers/envExample.js";
+import { fixGitignore } from "./fixers/gitignore.js";
+import { renderReport } from "./utils/report.js";
+function printFixResults(results) {
+    for (const r of results) {
+        if (r.action === "created") {
+            console.log(`${pc.green("+")} created ${pc.bold(r.file)}`);
+        }
+        else if (r.action === "updated") {
+            console.log(`${pc.yellow("~")} updated ${pc.bold(r.file)}`);
+        }
+        else {
+            console.log(`${pc.dim("-")} skipped ${r.file}${r.reason ? pc.dim(` (${r.reason})`) : ""}`);
+        }
+    }
+}
+/** Resolves and validates the target directory argument. */
+function resolveRoot(dir) {
+    const root = path.resolve(dir ?? process.cwd());
+    if (!fs.existsSync(root)) {
+        throw new Error(`directory not found: ${root}`);
+    }
+    if (!fs.statSync(root).isDirectory()) {
+        throw new Error(`not a directory: ${root}`);
+    }
+    return root;
+}
+/** Applies all safe fixes for the given root; returns the results. */
+async function applyFixes(root, force) {
+    const config = loadConfig(root);
+    const project = await detectProject(root, config);
+    const { envUsages } = scanFiles(root, project.sourceFiles, config.secretAllowlist);
+    return [
+        fixEnvExample(root, envUsages, force),
+        fixGitignore(root),
+        ...fixAgentFiles(root, project, force),
+    ];
+}
+/** Builds the commander program. Exported for testing. */
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name("shipready")
+        .description("Pre-flight check for your repo before shipping.")
+        .version("1.0.0");
+    program
+        .command("check")
+        .description("Scan a project for shipping blockers")
+        .argument("[path]", "project directory to scan (defaults to current directory)")
+        .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")
+        .action(async (dir, opts) => {
+        try {
+            const root = resolveRoot(dir);
+            let report = await runScan(root);
+            if (opts.fix) {
+                const before = report.score;
+                const results = await applyFixes(root, false);
+                report = await runScan(root);
+                if (!opts.json) {
+                    console.log("");
+                    console.log(pc.bold(pc.magenta("shipready check --fix")));
+                    console.log("");
+                    printFixResults(results);
+                    console.log("");
+                    const delta = report.score - before;
+                    console.log(`Score: ${pc.bold(String(before))} -> ${pc.bold(String(report.score))}` +
+                        (delta > 0 ? pc.green(` (+${delta})`) : pc.dim(" (no change)")));
+                }
+            }
+            if (opts.json) {
+                console.log(JSON.stringify(report, null, 2));
+            }
+            else {
+                console.log(renderReport(report, opts.verbose ?? false));
+            }
+            // Non-zero exit when errors are present, useful for CI.
+            const hasErrors = report.results.some((r) => r.findings.some((f) => f.severity === "error"));
+            process.exitCode = hasErrors ? 1 : 0;
+        }
+        catch (err) {
+            console.error(pc.red(`shipready check failed: ${err.message}`));
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command("init")
+        .description("Generate AI-agent instruction files (AGENTS.md, CLAUDE.md, Cursor rules)")
+        .argument("[path]", "project directory (defaults to current directory)")
+        .option("-f, --force", "overwrite existing files")
+        .action(async (dir, opts) => {
+        try {
+            const root = resolveRoot(dir);
+            const project = await detectProject(root, loadConfig(root));
+            console.log("");
+            console.log(pc.bold(pc.magenta("shipready init")));
+            console.log("");
+            const results = fixAgentFiles(root, project, opts.force ?? false);
+            printFixResults(results);
+            const skipped = results.filter((r) => r.action === "skipped").length;
+            if (skipped > 0 && !opts.force) {
+                console.log("");
+                console.log(pc.dim("Some files already exist. Re-run with --force to overwrite."));
+            }
+            console.log("");
+        }
+        catch (err) {
+            console.error(pc.red(`shipready init failed: ${err.message}`));
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command("fix")
+        .description("Apply safe automatic fixes (.env.example, .gitignore, agent files)")
+        .argument("[path]", "project directory (defaults to current directory)")
+        .option("-f, --force", "overwrite existing files")
+        .action(async (dir, opts) => {
+        try {
+            const root = resolveRoot(dir);
+            console.log("");
+            console.log(pc.bold(pc.magenta("shipready fix")));
+            console.log("");
+            const results = await applyFixes(root, opts.force ?? false);
+            printFixResults(results);
+            const changed = results.filter((r) => r.action !== "skipped").length;
+            console.log("");
+            console.log(changed > 0
+                ? pc.green(`${changed} file${changed > 1 ? "s" : ""} changed.`)
+                : pc.dim("Nothing to fix - everything already in place."));
+            console.log("");
+        }
+        catch (err) {
+            console.error(pc.red(`shipready fix failed: ${err.message}`));
+            process.exitCode = 1;
+        }
+    });
+    return program;
+}
+/** CLI entry: parses argv and runs the matching command. */
+export async function run(argv) {
+    const program = buildProgram();
+    await program.parseAsync(argv);
+}

package/dist/config.js

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+export const CONFIG_FILE = "shipready.config.json";
+const DEFAULT_CONFIG = {
+    ignore: [],
+    disableRules: [],
+    secretAllowlist: [],
+};
+function assertStringArray(value, field) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        throw new Error(`Invalid ${CONFIG_FILE}: "${field}" must be an array of strings`);
+    }
+    return value;
+}
+/**
+ * Loads shipready.config.json from the project root.
+ * Returns defaults when the file does not exist.
+ * Throws a readable error for malformed JSON or wrong field types.
+ */
+export function loadConfig(root) {
+    const abs = path.join(root, CONFIG_FILE);
+    if (!fs.existsSync(abs))
+        return { ...DEFAULT_CONFIG };
+    let raw;
+    try {
+        raw = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Invalid ${CONFIG_FILE}: file is not valid JSON`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`Invalid ${CONFIG_FILE}: expected a JSON object`);
+    }
+    const obj = parsed;
+    const known = new Set(["ignore", "disableRules", "secretAllowlist"]);
+    for (const key of Object.keys(obj)) {
+        if (!known.has(key)) {
+            throw new Error(`Invalid ${CONFIG_FILE}: unknown field "${key}" (allowed: ignore, disableRules, secretAllowlist)`);
+        }
+    }
+    return {
+        ignore: assertStringArray(obj.ignore, "ignore"),
+        disableRules: assertStringArray(obj.disableRules, "disableRules"),
+        secretAllowlist: assertStringArray(obj.secretAllowlist, "secretAllowlist"),
+    };
+}
+/** Returns true when the rule is disabled by config (exact id or check prefix). */
+export function isRuleDisabled(rule, disableRules) {
+    return disableRules.some((d) => d === rule || rule === d || rule.startsWith(`${d}.`));
+}

package/dist/fixers/agentFiles.js

@@ -0,0 +1,23 @@
+import { generateAgentsMd } from "../generators/agentsMd.js";
+import { generateClaudeMd } from "../generators/claudeMd.js";
+import { generateCursorRules } from "../generators/cursorRules.js";
+import { fileExists, writeTextFile } from "../utils/files.js";
+const TARGETS = [
+    { file: "AGENTS.md", generate: generateAgentsMd },
+    { file: "CLAUDE.md", generate: generateClaudeMd },
+    { file: ".cursor/rules/shipready.md", generate: generateCursorRules },
+];
+/** Generates all agent instruction files, honoring --force. */
+export function fixAgentFiles(root, project, force) {
+    const results = [];
+    for (const { file, generate } of TARGETS) {
+        if (fileExists(root, file) && !force) {
+            results.push({ file, action: "skipped", reason: "already exists (use --force)" });
+            continue;
+        }
+        const existed = fileExists(root, file);
+        writeTextFile(root, file, generate(project));
+        results.push({ file, action: existed ? "updated" : "created" });
+    }
+    return results;
+}

package/dist/fixers/envExample.js

@@ -0,0 +1,27 @@
+import { fileExists, writeTextFile } from "../utils/files.js";
+/** Builds .env.example content from detected env var usages. */
+export function buildEnvExample(usages) {
+    const names = [...new Set(usages.map((u) => u.name))].sort();
+    const lines = [
+        "# Environment variables used by this project.",
+        "# Copy to .env and fill in real values. Do not commit .env.",
+        "",
+        ...names.map((n) => `${n}=`),
+        "",
+    ];
+    return lines.join("\n");
+}
+/** Creates .env.example if missing (or with force). */
+export function fixEnvExample(root, usages, force) {
+    const file = ".env.example";
+    const names = [...new Set(usages.map((u) => u.name))];
+    if (names.length === 0) {
+        return { file, action: "skipped", reason: "no env vars detected in code" };
+    }
+    if (fileExists(root, file) && !force) {
+        return { file, action: "skipped", reason: "already exists (use --force)" };
+    }
+    const existed = fileExists(root, file);
+    writeTextFile(root, file, buildEnvExample(usages));
+    return { file, action: existed ? "updated" : "created" };
+}

package/dist/fixers/gitignore.js

@@ -0,0 +1,29 @@
+import { missingIgnoreEntries } from "../checks/gitignore.js";
+import { readTextFile, writeTextFile } from "../utils/files.js";
+/** Adds missing important entries to .gitignore (creates it if absent). */
+export function fixGitignore(root) {
+    const file = ".gitignore";
+    const existing = readTextFile(root, file);
+    if (existing === null) {
+        const content = [
+            "# Added by shipready",
+            ".env",
+            ".env.local",
+            "node_modules",
+            "dist",
+            "build",
+            ".next",
+            "",
+        ].join("\n");
+        writeTextFile(root, file, content);
+        return { file, action: "created" };
+    }
+    const missing = missingIgnoreEntries(existing);
+    if (missing.length === 0) {
+        return { file, action: "skipped", reason: "already complete" };
+    }
+    const suffix = existing.endsWith("\n") ? "" : "\n";
+    const addition = `${suffix}\n# Added by shipready\n${missing.join("\n")}\n`;
+    writeTextFile(root, file, existing + addition);
+    return { file, action: "updated" };
+}

package/dist/generators/agentsMd.js

@@ -0,0 +1,66 @@
+import { installCommand, runCommand } from "../utils/framework.js";
+/** Shared list of rules for AI agents working in the repo. */
+export const AGENT_RULES = [
+    "Do not edit .env files directly.",
+    "Do not commit secrets or API keys.",
+    "Run the build command before finalizing major changes.",
+    "Keep changes small and focused.",
+    "Prefer existing project patterns over introducing new libraries.",
+    "Update README when setup steps change.",
+];
+/** Builds the shared command table used by all generated files. */
+export function buildCommandSection(project) {
+    const pm = project.packageManager;
+    const s = project.scripts;
+    const rows = [`- Install: \`${installCommand(pm)}\``];
+    if (s.dev)
+        rows.push(`- Dev: \`${runCommand(pm, "dev")}\``);
+    if (s.build)
+        rows.push(`- Build: \`${runCommand(pm, "build")}\``);
+    if (s.test)
+        rows.push(`- Test: \`${runCommand(pm, "test")}\``);
+    if (s.lint)
+        rows.push(`- Lint: \`${runCommand(pm, "lint")}\``);
+    return rows.join("\n");
+}
+/** Builds a short project structure summary from scanned files. */
+export function buildStructureSummary(project) {
+    const dirs = new Set();
+    for (const f of project.sourceFiles) {
+        const top = f.split("/")[0];
+        if (top && !top.startsWith(".") && f.includes("/"))
+            dirs.add(top);
+    }
+    const list = [...dirs].sort().slice(0, 12);
+    if (list.length === 0)
+        return "- Flat project (no top-level source directories detected)";
+    return list.map((d) => `- \`${d}/\``).join("\n");
+}
+/** Generates AGENTS.md content. */
+export function generateAgentsMd(project) {
+    const name = project.packageJson?.name ?? "this project";
+    return `# AGENTS.md
+
+Instructions for AI coding agents working on ${name}.
+
+## Project
+
+- Framework: ${project.framework}
+- Package manager: ${project.packageManager}
+
+## Commands
+
+${buildCommandSection(project)}
+
+## Project structure
+
+${buildStructureSummary(project)}
+
+## Rules
+
+${AGENT_RULES.map((r) => `- ${r}`).join("\n")}
+
+---
+Generated by [shipready](https://www.npmjs.com/package/shipready).
+`;
+}

package/dist/generators/claudeMd.js

@@ -0,0 +1,35 @@
+import { AGENT_RULES, buildCommandSection, buildStructureSummary, } from "./agentsMd.js";
+/** Generates CLAUDE.md content. */
+export function generateClaudeMd(project) {
+    const name = project.packageJson?.name ?? "this project";
+    return `# CLAUDE.md
+
+Guidance for Claude when working on ${name}.
+
+## Project
+
+- Framework: ${project.framework}
+- Package manager: ${project.packageManager}
+
+## Commands
+
+${buildCommandSection(project)}
+
+## Project structure
+
+${buildStructureSummary(project)}
+
+## Rules
+
+${AGENT_RULES.map((r) => `- ${r}`).join("\n")}
+
+## Workflow
+
+- Read existing code before writing new code.
+- Verify changes compile/pass tests before declaring them done.
+- Ask before making sweeping refactors.
+
+---
+Generated by [shipready](https://www.npmjs.com/package/shipready).
+`;
+}

package/dist/generators/cursorRules.js

@@ -0,0 +1,21 @@
+import { AGENT_RULES, buildCommandSection } from "./agentsMd.js";
+/** Generates .cursor/rules/shipready.md content. */
+export function generateCursorRules(project) {
+    return `# shipready rules
+
+Project: ${project.framework} (${project.packageManager})
+
+## Commands
+
+${buildCommandSection(project)}
+
+## Rules for AI edits
+
+${AGENT_RULES.map((r) => `- ${r}`).join("\n")}
+- Mask or omit any secret values when displaying file contents.
+- Never write real credentials into example or config files.
+
+---
+Generated by shipready.
+`;
+}

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+run(process.argv).catch((err) => {
+    console.error(`shipready: ${err.message}`);
+    process.exit(1);
+});

package/dist/scanner.js

@@ -0,0 +1,116 @@
+import path from "node:path";
+import { checkEnv, extractEnvUsages } from "./checks/env.js";
+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 { checkTodos, scanContentForTodos } from "./checks/todos.js";
+import { fileExists, findSourceFiles, isProbablyBinary, readJsonFile, readTextFile, } from "./utils/files.js";
+import { detectFramework, detectPackageManager } from "./utils/framework.js";
+import { isRuleDisabled, loadConfig } from "./config.js";
+/** File extensions considered code for content scanning (not config/data). */
+const CODE_ONLY = new Set([
+    ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs", ".mts", ".cts",
+    ".vue", ".svelte", ".py", ".rb", ".go", ".rs", ".java", ".php",
+]);
+/** Gathers structured project info from the given root. */
+export async function detectProject(root, config) {
+    const pkg = readJsonFile(root, "package.json");
+    const sourceFiles = await findSourceFiles(root, config?.ignore ?? []);
+    return {
+        root,
+        hasPackageJson: fileExists(root, "package.json"),
+        packageJson: pkg,
+        packageManager: detectPackageManager(root),
+        framework: detectFramework(pkg),
+        scripts: pkg?.scripts ?? {},
+        sourceFiles,
+    };
+}
+/** Extracts env usages, secrets, and todos from all source files. */
+export function scanFiles(root, files, secretAllowlist = []) {
+    const envUsages = [];
+    const secrets = [];
+    const todos = [];
+    for (const file of files) {
+        const base = path.basename(file);
+        // Never flag .env files themselves for secrets/todos; they are expected
+        // to contain real values and are handled by the env check.
+        const isEnvFile = base.startsWith(".env");
+        const ext = path.extname(file).toLowerCase();
+        const isCode = CODE_ONLY.has(ext);
+        if (isProbablyBinary(root, file))
+            continue;
+        const content = readTextFile(root, file);
+        if (content === null)
+            continue;
+        if (isCode) {
+            envUsages.push(...extractEnvUsages(content, file));
+            todos.push(...scanContentForTodos(content, file));
+        }
+        if (!isEnvFile && base !== ".env.example" && base !== ".env.sample") {
+            secrets.push(...scanContentForSecrets(content, file, secretAllowlist));
+        }
+    }
+    return { envUsages, secrets, todos };
+}
+/** Score deductions per the shipready scoring model. */
+export function calculateScore(results) {
+    let score = 100;
+    const all = results.flatMap((r) => r.findings);
+    const has = (rule) => all.some((f) => f.rule === rule);
+    const count = (rule) => all.filter((f) => f.rule === rule).length;
+    if (has("package-json.missing"))
+        score -= 20;
+    if (has("readme.missing"))
+        score -= 15;
+    if (has("readme.weak"))
+        score -= 8;
+    // Missing scripts: look at message to determine which ones
+    const scriptsFinding = all.find((f) => f.rule === "scripts.missing");
+    if (scriptsFinding) {
+        if (scriptsFinding.message.includes("build"))
+            score -= 8;
+        if (scriptsFinding.message.includes("test"))
+            score -= 6;
+    }
+    if (has("env.example-missing"))
+        score -= 10;
+    if (has("env.not-ignored"))
+        score -= 15;
+    const secretCount = count("secrets.detected-item");
+    score -= Math.min(secretCount * 25, 50);
+    const todoCount = count("todos.item");
+    score -= Math.min(todoCount * 2, 15);
+    return Math.max(0, score);
+}
+/** Removes findings whose rules are disabled by config. */
+function applyDisabledRules(results, disableRules) {
+    if (disableRules.length === 0)
+        return results;
+    return results.map((r) => ({
+        ...r,
+        findings: r.findings.filter((f) => !isRuleDisabled(f.rule, disableRules) && !isRuleDisabled(r.name, disableRules)),
+    }));
+}
+/** Runs the full scan and returns a structured report. */
+export async function runScan(root) {
+    const config = loadConfig(root);
+    const project = await detectProject(root, config);
+    const { envUsages, secrets, todos } = scanFiles(root, project.sourceFiles, config.secretAllowlist);
+    const rawResults = [
+        checkPackageJson(project),
+        checkReadme(root),
+        checkEnv(root, envUsages),
+        checkSecrets(secrets),
+        checkTodos(todos),
+        checkGitignore(root),
+    ];
+    // Disabled rules are removed before scoring so they don't affect the score.
+    const results = applyDisabledRules(rawResults, config.disableRules);
+    return {
+        project,
+        results,
+        score: calculateScore(results),
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};