shippingszn 0.1.0

package/dist/index.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+import * as path from "node:path";
+import * as process from "node:process";
+import { ALL_CHECKS } from "./checks.js";
+import { listFiles } from "./scan.js";
+import { CHECKLIST_ITEMS, permalinkFor } from "./items.js";
+const DEFAULT_BASE_URL = "https://shippingszn.com";
+const PKG_VERSION = "0.1.0";
+function parseArgs(argv) {
+    const opts = {
+        cwd: process.cwd(),
+        json: false,
+        baseUrl: process.env.VIBE_LAUNCH_CHECK_BASE_URL ?? DEFAULT_BASE_URL,
+        help: false,
+        version: false,
+        noColor: !!process.env.NO_COLOR,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--help" || a === "-h")
+            opts.help = true;
+        else if (a === "--version" || a === "-v")
+            opts.version = true;
+        else if (a === "--json")
+            opts.json = true;
+        else if (a === "--no-color")
+            opts.noColor = true;
+        else if (a === "--base-url")
+            opts.baseUrl = argv[++i] ?? opts.baseUrl;
+        else if (a === "--cwd")
+            opts.cwd = path.resolve(argv[++i] ?? opts.cwd);
+        else if (!a.startsWith("-"))
+            opts.cwd = path.resolve(a);
+    }
+    return opts;
+}
+function color(enabled) {
+    const wrap = (codes) => (s) => enabled ? `\x1b[${codes}m${s}\x1b[0m` : s;
+    return {
+        bold: wrap("1"),
+        dim: wrap("2"),
+        red: wrap("31"),
+        yellow: wrap("33"),
+        blue: wrap("34"),
+        cyan: wrap("36"),
+        green: wrap("32"),
+        magenta: wrap("35"),
+        gray: wrap("90"),
+    };
+}
+const SEVERITY_ORDER = ["critical", "high", "medium", "lower"];
+const SEVERITY_LABEL = {
+    critical: "CRITICAL",
+    high: "HIGH",
+    medium: "MEDIUM",
+    lower: "LOWER",
+};
+function printHelp() {
+    process.stdout.write(`shippingszn v${PKG_VERSION}
+
+Read-only scanner that checks the current project against a small set of
+high-signal items from the Vibe Coder Launch Checklist.
+
+Usage:
+  npx shippingszn [path] [options]
+
+Options:
+  --json                Output a machine-readable JSON report.
+  --base-url <url>      Base URL used to build links back to checklist items.
+                        (default: ${DEFAULT_BASE_URL})
+  --cwd <path>          Directory to scan. Default: current working directory.
+  --no-color            Disable ANSI colors in the human-readable report.
+  -h, --help            Show this help.
+  -v, --version         Print version.
+
+The scanner only reads files. It never writes, modifies, or deletes anything.
+Exit code is non-zero if any Critical findings are detected.
+`);
+}
+async function run() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+        printHelp();
+        return 0;
+    }
+    if (opts.version) {
+        process.stdout.write(`${PKG_VERSION}\n`);
+        return 0;
+    }
+    const c = color(!opts.noColor && process.stdout.isTTY === true && !opts.json);
+    const files = await listFiles(opts.cwd);
+    const ctx = { rootDir: opts.cwd, files };
+    const all = [];
+    for (const check of ALL_CHECKS) {
+        try {
+            const out = await check.run(ctx);
+            all.push(...out);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            all.push({
+                checkId: `${check.id}:error`,
+                itemId: "ai-audit",
+                severity: "lower",
+                message: `Check ${check.id} crashed: ${msg}`,
+            });
+        }
+    }
+    const enriched = all.map((f) => {
+        const item = CHECKLIST_ITEMS[f.itemId];
+        return {
+            ...f,
+            itemTitle: item?.title ?? f.itemId,
+            permalink: permalinkFor(f.itemId, opts.baseUrl),
+        };
+    });
+    enriched.sort((a, b) => {
+        const sa = SEVERITY_ORDER.indexOf(a.severity);
+        const sb = SEVERITY_ORDER.indexOf(b.severity);
+        if (sa !== sb)
+            return sa - sb;
+        if (a.itemId !== b.itemId)
+            return a.itemId.localeCompare(b.itemId);
+        return a.checkId.localeCompare(b.checkId);
+    });
+    const totals = {
+        critical: 0,
+        high: 0,
+        medium: 0,
+        lower: 0,
+    };
+    for (const f of enriched)
+        totals[f.severity]++;
+    const report = {
+        generatedAt: new Date().toISOString(),
+        baseUrl: opts.baseUrl,
+        cwd: opts.cwd,
+        filesScanned: files.length,
+        totals,
+        findings: enriched,
+    };
+    if (opts.json) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+        return totals.critical > 0 ? 1 : 0;
+    }
+    // Human-readable report
+    const sevColor = (s) => {
+        if (s === "critical")
+            return c.red;
+        if (s === "high")
+            return c.yellow;
+        if (s === "medium")
+            return c.blue;
+        return c.gray;
+    };
+    process.stdout.write(`\n${c.bold("shippingszn")} ${c.dim(`v${PKG_VERSION}`)}\n`);
+    process.stdout.write(c.dim(`Scanned ${files.length} files in ${opts.cwd}\n\n`));
+    if (enriched.length === 0) {
+        process.stdout.write(c.green("✓ No findings. Nice work — still walk through the full checklist before launch.\n\n"));
+        return 0;
+    }
+    // Strip ASCII control characters (including ESC) so a maliciously-named
+    // file or matched secret slice cannot inject ANSI escape sequences into
+    // the operator's terminal.
+    const safe = (s) => s.replace(/[\x00-\x1f\x7f]/g, "?");
+    for (const sev of SEVERITY_ORDER) {
+        const group = enriched.filter((f) => f.severity === sev);
+        if (group.length === 0)
+            continue;
+        process.stdout.write(`${sevColor(sev)(c.bold(`${SEVERITY_LABEL[sev]} (${group.length})`))}\n`);
+        for (const f of group) {
+            const loc = f.file
+                ? ` ${c.dim(`— ${safe(f.file)}${f.line ? `:${f.line}` : ""}`)}`
+                : "";
+            process.stdout.write(`  ${c.bold("•")} ${safe(f.message)}${loc}\n`);
+            if (f.evidence) {
+                process.stdout.write(`    ${c.dim(`evidence: ${safe(f.evidence)}`)}\n`);
+            }
+            process.stdout.write(`    ${c.cyan(`→ ${safe(f.itemTitle)}`)} ${c.dim(f.permalink)}\n`);
+        }
+        process.stdout.write("\n");
+    }
+    process.stdout.write(`${c.bold("Summary:")} ${c.red(`${totals.critical} critical`)}, ${c.yellow(`${totals.high} high`)}, ${c.blue(`${totals.medium} medium`)}, ${c.gray(`${totals.lower} lower`)}\n`);
+    if (totals.critical > 0) {
+        process.stdout.write(c.red("\nCritical findings detected. Exiting with code 1.\n"));
+        return 1;
+    }
+    process.stdout.write(c.dim("\nNo critical findings. Open the linked checklist items to dig deeper.\n"));
+    return 0;
+}
+run().then((code) => process.exit(code), (err) => {
+    process.stderr.write(`shippingszn failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(2);
+});

package/dist/items.js

@@ -0,0 +1,46 @@
+export const CHECKLIST_ITEMS = {
+    secrets: {
+        id: "secrets",
+        title: "Lock up your API keys and passwords",
+        priority: "critical",
+    },
+    "common-attacks": {
+        id: "common-attacks",
+        title: "Block the most common automated attacks",
+        priority: "critical",
+    },
+    "https-headers": {
+        id: "https-headers",
+        title: "Force HTTPS and add browser-level defenses",
+        priority: "critical",
+    },
+    "dev-prod-data": {
+        id: "dev-prod-data",
+        title: "Keep your test data away from real users",
+        priority: "critical",
+    },
+    github: {
+        id: "github",
+        title: "Get your code into GitHub safely",
+        priority: "high",
+    },
+    seo: {
+        id: "seo",
+        title: "Make sure search engines and link previews work",
+        priority: "medium",
+    },
+    "launch-polish": {
+        id: "launch-polish",
+        title: "Last-mile launch polish",
+        priority: "medium",
+    },
+    "ai-audit": {
+        id: "ai-audit",
+        title: "Audit what your AI builder actually shipped",
+        priority: "critical",
+    },
+};
+export function permalinkFor(itemId, baseUrl) {
+    const trimmed = baseUrl.replace(/\/+$/, "");
+    return `${trimmed}/i/${itemId}`;
+}

package/dist/scan.js

@@ -0,0 +1,171 @@
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+const DEFAULT_IGNORES = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    ".turbo",
+    ".cache",
+    ".vercel",
+    ".netlify",
+    "out",
+    "coverage",
+    ".pnpm-store",
+    ".yarn",
+    ".expo",
+    ".local",
+    "attached_assets",
+    "vendor",
+]);
+const TEXT_EXT = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".json",
+    ".md",
+    ".mdx",
+    ".html",
+    ".htm",
+    ".css",
+    ".scss",
+    ".vue",
+    ".svelte",
+    ".astro",
+    ".py",
+    ".rb",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".swift",
+    ".php",
+    ".cs",
+    ".env",
+    ".example",
+    ".sample",
+    ".local",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".ini",
+    ".conf",
+    ".sh",
+]);
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_DEPTH = 24;
+const MAX_FILES = 50_000;
+export async function listFiles(rootDir) {
+    const out = [];
+    const visited = new Set();
+    const rootResolved = path.resolve(rootDir);
+    async function walk(dir, depth) {
+        if (depth > MAX_DEPTH)
+            return;
+        if (out.length >= MAX_FILES)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= MAX_FILES)
+                return;
+            if (entry.name.startsWith(".") && DEFAULT_IGNORES.has(entry.name))
+                continue;
+            if (DEFAULT_IGNORES.has(entry.name))
+                continue;
+            const abs = path.join(dir, entry.name);
+            // Refuse to follow symlinks: prevents arbitrary file reads outside the
+            // target tree and protects against symlink loops causing exhaustion.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                // Skip test fixture directories: these intentionally contain
+                // bad/insecure inputs (fake secrets, missing files, etc.) used to
+                // exercise the checks themselves. Counting them in a scan of a
+                // consumer repo would produce noisy false positives and would also
+                // break CI for this repo's own PR scan.
+                if (entry.name === "fixtures") {
+                    const parentBase = path.basename(dir);
+                    if (parentBase === "test" ||
+                        parentBase === "tests" ||
+                        parentBase === "__tests__") {
+                        continue;
+                    }
+                }
+                let real;
+                try {
+                    real = await fs.realpath(abs);
+                }
+                catch {
+                    continue;
+                }
+                // Stay within the original root and avoid revisiting the same
+                // directory through hard-linked or aliased paths. Use path.relative
+                // (separator-aware) so that a sibling like "/root-sibling" can never
+                // sneak past a naive prefix check on "/root".
+                const relFromRoot = path.relative(rootResolved, real);
+                if (relFromRoot.startsWith("..") || path.isAbsolute(relFromRoot)) {
+                    continue;
+                }
+                if (visited.has(real))
+                    continue;
+                visited.add(real);
+                await walk(abs, depth + 1);
+            }
+            else if (entry.isFile()) {
+                const rel = path.relative(rootDir, abs);
+                let size = 0;
+                try {
+                    const st = await fs.stat(abs);
+                    size = st.size;
+                }
+                catch {
+                    continue;
+                }
+                out.push({ absPath: abs, relPath: rel, size });
+            }
+        }
+    }
+    await walk(rootDir, 0);
+    return out;
+}
+export function isTextFile(file) {
+    const base = path.basename(file.relPath).toLowerCase();
+    if (base.startsWith(".env"))
+        return true;
+    if (base === "dockerfile" || base === "makefile" || base === "procfile")
+        return true;
+    const ext = path.extname(file.relPath).toLowerCase();
+    if (TEXT_EXT.has(ext))
+        return true;
+    return false;
+}
+export async function readFileSafe(file) {
+    if (file.size > MAX_FILE_BYTES)
+        return null;
+    try {
+        return await fs.readFile(file.absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export async function fileExists(p) {
+    try {
+        await fs.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "shippingszn",
+  "version": "0.1.0",
+  "description": "Read-only CLI scanner that checks a project for common pre-launch issues from the shippingszn.com launch checklist.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "shippingszn": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cli",
+    "launch",
+    "checklist",
+    "preflight",
+    "security",
+    "audit",
+    "scanner",
+    "ship",
+    "shippingszn",
+    "vibe-coder"
+  ],
+  "homepage": "https://shippingszn.com",
+  "bugs": {
+    "url": "https://github.com/keeptahoeblueish/shippingszn-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keeptahoeblueish/shippingszn-cli.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx ./src/index.ts",
+    "start": "node ./dist/index.js",
+    "test": "tsx --test ./test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsx": "4.21.0",
+    "typescript": "^5.6.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}