shippingszn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vibe Coder Launch Checklist 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,93 @@
+# shippingszn
+
+A small, read-only CLI that scans a project for common pre-launch issues from
+the [shippingszn.com launch checklist](https://shippingszn.com). Run it
+before you ship to catch obvious mistakes — leaked API keys, missing
+`robots.txt`, no security headers, and so on — and get a friendly report
+linking each finding back to the matching checklist item.
+
+```bash
+npx shippingszn
+# or
+pnpm dlx shippingszn
+```
+
+Run it inside any project root. The CLI **never writes, modifies, or deletes**
+any files — it only reads. Everything stays on your machine.
+
+## What gets checked
+
+The initial check set is intentionally small and high-signal. Each finding
+maps back to one of the items on the checklist.
+
+- Hardcoded API keys across many providers (OpenAI, Anthropic, Stripe, AWS,
+  Google, GitHub, Slack, private key blocks).
+- `.env` present but not ignored in `.gitignore`, or `.env` present but no
+  `.env.example`.
+- Missing `.gitignore`, `robots.txt`, `sitemap.xml`, or a custom favicon.
+- Missing security-header middleware in common server configs.
+- Dangerous code patterns: unsafe HTML injection in React, runtime
+  code-execution calls, wildcard CORS.
+- Python: common debug-mode slip-ups, hardcoded framework secrets, missing
+  env-var loading.
+- Ruby: unsafe string rendering, hardcoded Rails secrets.
+- Go: `http.ListenAndServe` without TLS, hardcoded token / apiKey / secret
+  literals.
+- Placeholder content (`lorem ipsum`, `John Doe`, `test@example.com`) and
+  `TODO` / `FIXME` / `XXX` / `HACK` comments.
+
+Each finding is tagged Critical, High, Medium, or Lower and links back to the
+relevant checklist item on shippingszn.com.
+
+## What does NOT get checked
+
+These are deliberately out of scope for v1:
+
+- Anything that requires running your app (no live HTTP probing, no auth
+  flows).
+- Auto-fixing problems. The CLI is read-only.
+- Deep static analysis or language-specific lints. Use ESLint, Semgrep, or
+  Snyk for that.
+- Validating your actual third-party dashboards (Stripe spend caps, OpenAI
+  quotas, etc.).
+
+A clean report is **not** a launch certificate — it just means none of the
+obvious things tripped a tripwire. Walk through the full checklist before you
+ship.
+
+## Usage
+
+```text
+shippingszn [path] [options]
+
+Options:
+  --json                Output a machine-readable JSON report.
+  --base-url <url>      Base URL used to build links back to checklist items.
+  --cwd <path>          Directory to scan. Default: current working directory.
+  --no-color            Disable ANSI colors in the human-readable report.
+  -h, --help            Show help.
+  -v, --version         Print version.
+```
+
+## Exit codes
+
+- `0` — No critical findings.
+- `1` — One or more critical findings detected.
+- `2` — The scanner itself crashed.
+
+This makes the CLI suitable for CI:
+
+```yaml
+# .github/workflows/launch-check.yml
+- run: npx shippingszn --json > launch-check.json
+```
+
+## Privacy
+
+`shippingszn` reads files on your machine. It never uploads source code,
+makes outbound network calls, or phones home. No telemetry. No accounts.
+Inspect the source or audit `npm pack --dry-run` to confirm.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/checks/dangerous.js

@@ -0,0 +1,58 @@
+import * as path from "node:path";
+import { isTextFile, readFileSafe } from "../scan.js";
+import { findLine, isScanExempt, lineContainsIgnoreMarker, relPosix, } from "./helpers.js";
+const DANGEROUS_PATTERNS = [
+    {
+        id: "dangerously-set-inner-html",
+        regex: /dangerouslySetInnerHTML/,
+        itemId: "common-attacks",
+        severity: "high",
+        message: "Use of dangerouslySetInnerHTML — make sure the content is sanitized or comes from a trusted source.",
+    },
+    {
+        id: "eval-call",
+        regex: /(^|[^A-Za-z0-9_$])eval\s*\(/,
+        itemId: "common-attacks",
+        severity: "high",
+        message: "Use of eval() — almost always avoidable and a common path to remote code execution if any input is user-controlled.",
+    },
+    {
+        id: "cors-wildcard",
+        regex: /Access-Control-Allow-Origin\s*[:=]\s*['"`]\*['"`]/i,
+        itemId: "common-attacks",
+        severity: "medium",
+        message: "Wildcard CORS (Access-Control-Allow-Origin: *). Lock this down to specific origins for any authenticated endpoint.",
+    },
+];
+export async function checkDangerousPatterns(ctx) {
+    const findings = [];
+    for (const file of ctx.files) {
+        if (!isTextFile(file))
+            continue;
+        if (isScanExempt(file.relPath))
+            continue;
+        const ext = path.extname(file.relPath).toLowerCase();
+        if (![".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".html"].includes(ext))
+            continue;
+        const content = await readFileSafe(file);
+        if (!content)
+            continue;
+        for (const pat of DANGEROUS_PATTERNS) {
+            const m = pat.regex.exec(content);
+            if (!m)
+                continue;
+            if (lineContainsIgnoreMarker(content, m.index))
+                continue;
+            const line = findLine(content, m.index);
+            findings.push({
+                checkId: pat.id,
+                itemId: pat.itemId,
+                severity: pat.severity,
+                message: pat.message,
+                file: relPosix(file.relPath),
+                line,
+            });
+        }
+    }
+    return findings;
+}

package/dist/checks/env.js

@@ -0,0 +1,59 @@
+import * as path from "node:path";
+import { fileExists, readFileSafe } from "../scan.js";
+import { relPosix } from "./helpers.js";
+export async function checkEnvCommitted(ctx) {
+    const findings = [];
+    const gitignorePath = path.join(ctx.rootDir, ".gitignore");
+    let gitignore = "";
+    if (await fileExists(gitignorePath)) {
+        gitignore = (await readFileSafe({ absPath: gitignorePath, relPath: ".gitignore", size: 0 })) ?? "";
+    }
+    const ignoresEnv = /^\s*\.env(\s|$)/m.test(gitignore) || /^\s*\*\.env(\s|$)/m.test(gitignore);
+    for (const file of ctx.files) {
+        const base = path.basename(file.relPath);
+        if (base !== ".env" && base !== ".env.local" && base !== ".env.production")
+            continue;
+        if (!ignoresEnv) {
+            findings.push({
+                checkId: "env-not-ignored",
+                itemId: "secrets",
+                severity: "high",
+                message: `${base} found and your .gitignore does not appear to ignore .env files.`,
+                file: relPosix(file.relPath),
+            });
+        }
+    }
+    return findings;
+}
+export async function checkEnvExample(ctx) {
+    const hasEnv = ctx.files.some((f) => path.basename(f.relPath) === ".env");
+    const hasExample = ctx.files.some((f) => {
+        const b = path.basename(f.relPath);
+        return b === ".env.example" || b === ".env.sample" || b === ".env.template";
+    });
+    if (hasEnv && !hasExample) {
+        return [
+            {
+                checkId: "missing-env-example",
+                itemId: "secrets",
+                severity: "medium",
+                message: "Found a .env file but no .env.example. Add a sanitized .env.example so collaborators know which variables are required.",
+            },
+        ];
+    }
+    return [];
+}
+export async function checkGitignore(ctx) {
+    const gitignorePath = path.join(ctx.rootDir, ".gitignore");
+    if (!(await fileExists(gitignorePath))) {
+        return [
+            {
+                checkId: "missing-gitignore",
+                itemId: "github",
+                severity: "high",
+                message: "No .gitignore at the project root. Add one tuned to your stack so you don't accidentally commit secrets, local DBs, or build artifacts.",
+            },
+        ];
+    }
+    return [];
+}

package/dist/checks/headers.js

@@ -0,0 +1,60 @@
+import * as path from "node:path";
+import { readFileSafe } from "../scan.js";
+const SECURITY_HEADER_NAMES = [
+    "Strict-Transport-Security",
+    "Content-Security-Policy",
+    "X-Content-Type-Options",
+    "X-Frame-Options",
+    "Referrer-Policy",
+];
+export async function checkSecurityHeaders(ctx) {
+    const candidateFiles = ctx.files.filter((f) => {
+        const rp = f.relPath.toLowerCase();
+        if (rp.endsWith(".test.ts") || rp.endsWith(".spec.ts"))
+            return false;
+        return (rp.endsWith("vite.config.ts") ||
+            rp.endsWith("vite.config.js") ||
+            rp.endsWith("next.config.js") ||
+            rp.endsWith("next.config.mjs") ||
+            rp.endsWith("next.config.ts") ||
+            rp.endsWith("nuxt.config.ts") ||
+            rp.endsWith("svelte.config.js") ||
+            rp.endsWith("astro.config.mjs") ||
+            rp.endsWith("astro.config.ts") ||
+            rp.endsWith("vercel.json") ||
+            rp.endsWith("netlify.toml") ||
+            /server\/index\.(t|j)s$/.test(rp) ||
+            /^server\.(t|j)s$/.test(path.basename(rp)) ||
+            /\bapp\.(t|j)s$/.test(rp) ||
+            /\bindex\.(t|j)s$/.test(rp));
+    });
+    if (candidateFiles.length === 0)
+        return [];
+    let foundAny = false;
+    for (const file of candidateFiles) {
+        const content = await readFileSafe(file);
+        if (!content)
+            continue;
+        for (const h of SECURITY_HEADER_NAMES) {
+            if (content.toLowerCase().includes(h.toLowerCase())) {
+                foundAny = true;
+                break;
+            }
+        }
+        if (content.includes("helmet(") || content.includes('require("helmet")') || content.includes('from "helmet"')) {
+            foundAny = true;
+        }
+        if (foundAny)
+            break;
+    }
+    if (foundAny)
+        return [];
+    return [
+        {
+            checkId: "missing-security-headers",
+            itemId: "https-headers",
+            severity: "high",
+            message: "Couldn't find any common security headers (CSP, HSTS, X-Frame-Options, etc.) or helmet() middleware in your server/host configs. Add them so the browser enforces baseline defenses.",
+        },
+    ];
+}

package/dist/checks/helpers.js

@@ -0,0 +1,155 @@
+import * as path from "node:path";
+import { fileExists, isTextFile, readFileSafe, } from "../scan.js";
+export function relPosix(p) {
+    return p.split(path.sep).join("/");
+}
+export function findLine(content, idx) {
+    let line = 1;
+    for (let i = 0; i < idx; i++)
+        if (content.charCodeAt(i) === 10)
+            line++;
+    return line;
+}
+/**
+ * Inline opt-out marker. Any line containing this token is exempt from
+ * substring/regex-based checks (placeholder content, dangerous patterns).
+ * Used by the scanner's own source to avoid matching its pattern definitions.
+ *
+ * The literal value is split across a concatenation so that grep'ing for the
+ * marker only finds the *uses*, not this definition.
+ */
+export const IGNORE_MARKER = "shippingszn" + ":ignore";
+export function lineContainsIgnoreMarker(content, charIndex) {
+    const lineStart = content.lastIndexOf("\n", charIndex - 1) + 1;
+    const lineEnd = content.indexOf("\n", charIndex);
+    const line = content.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
+    return line.includes(IGNORE_MARKER);
+}
+const PUBLIC_DIR_CANDIDATES = [
+    "public",
+    "static",
+    "www",
+    "dist",
+    "build",
+    "out",
+];
+export async function findPublicDirs(ctx) {
+    const dirs = [];
+    for (const cand of PUBLIC_DIR_CANDIDATES) {
+        const p = path.join(ctx.rootDir, cand);
+        if (await fileExists(p))
+            dirs.push(cand);
+    }
+    // Also any artifact public dirs in monorepo style.
+    const seen = new Set(dirs);
+    for (const f of ctx.files) {
+        const parts = f.relPath.split("/");
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (parts[i] === "public" || parts[i] === "static") {
+                const dir = parts.slice(0, i + 1).join("/");
+                if (!seen.has(dir)) {
+                    seen.add(dir);
+                    dirs.push(dir);
+                }
+            }
+        }
+    }
+    return dirs;
+}
+/**
+ * Narrow per-file exemption for substring/regex checks (placeholder
+ * content, dangerous patterns, language patterns).
+ *
+ * This deliberately does NOT exempt the CLI source or test trees as a
+ * whole — broad exemptions hide real bugs. It only lists files that
+ * define or document the patterns the scanner looks for, where a literal
+ * pattern in source is the file's whole purpose:
+ *
+ *   - `tools/cli/src/checks/{dangerous,quality,language}.ts` define the
+ *     regexes and human-readable messages, both of which contain the
+ *     literal pattern strings.
+ *   - `tools/cli/README.md` documents what the scanner detects, citing
+ *     the pattern strings verbatim.
+ *   - `tools/cli/test/fixtures/` contains intentional positive fixtures.
+ *   - `artifacts/checklist/src/data/checklist/` is user-facing checklist
+ *     copy that names the patterns by name (e.g. "look for TODO/FIXME"). shippingszn:ignore
+ *
+ * Secret scanning is NOT exempted from any of these paths — the secret
+ * regexes contain regex metacharacters in source and don't self-match,
+ * so real hardcoded secrets in the CLI source would still be caught.
+ *
+ * For one-off cases in normal source files, prefer the inline
+ * `shippingszn:ignore` marker (handled by lineContainsIgnoreMarker)
+ * instead of adding paths here.
+ */
+const PATTERN_DEFINITION_FILES = new Set([
+    "tools/cli/src/checks/dangerous.ts",
+    "tools/cli/src/checks/quality.ts",
+    "tools/cli/src/checks/language.ts",
+    "tools/cli/README.md",
+]);
+const PATTERN_DEFINITION_PREFIXES = [
+    "tools/cli/test/fixtures/",
+    "artifacts/checklist/src/data/checklist/",
+];
+export function isScanExempt(relPath) {
+    const p = relPosix(relPath);
+    if (PATTERN_DEFINITION_FILES.has(p))
+        return true;
+    for (const prefix of PATTERN_DEFINITION_PREFIXES) {
+        if (p.startsWith(prefix) || p.includes("/" + prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Does any source file in the project look like it dynamically emits or
+ * serves the given asset (e.g. `robots.txt`, `sitemap.xml`)? Used by
+ * `checkRobotsTxt` / `checkSitemapXml` to suppress false positives in
+ * projects that generate these at build time via a Vite plugin or serve
+ * them from an Express/Next route.
+ *
+ * Heuristic: a `.ts`/`.js`/`.mjs`/`.cjs` source file that mentions the
+ * asset filename as a string literal AND contains an emission/serve
+ * indicator (`emitFile`, `setHeader`, `res.end`, `res.send`,
+ * `configureServer`, `app.get`, `router.get`, `next/headers`).
+ */
+const SERVE_INDICATORS = [
+    "emitFile",
+    "setHeader",
+    "res.end",
+    "res.send",
+    "configureServer",
+    "configurePreviewServer",
+    "app.get",
+    "app.use",
+    "router.get",
+    "router.use",
+];
+const DYNAMIC_ASSET_SOURCE_EXTS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+]);
+export async function isAssetEmittedDynamically(ctx, assetName) {
+    const literalPatterns = [`"${assetName}"`, `'${assetName}'`, `/${assetName}`];
+    for (const file of ctx.files) {
+        if (!isTextFile(file))
+            continue;
+        const ext = path.extname(file.relPath).toLowerCase();
+        if (!DYNAMIC_ASSET_SOURCE_EXTS.has(ext))
+            continue;
+        const content = await readFileSafe(file);
+        if (!content)
+            continue;
+        if (!literalPatterns.some((p) => content.includes(p)))
+            continue;
+        if (!SERVE_INDICATORS.some((s) => content.includes(s)))
+            continue;
+        return true;
+    }
+    return false;
+}

package/dist/checks/index.js

@@ -0,0 +1,34 @@
+/**
+ * Public entry point for the scanner's check registry.
+ *
+ * Adding a new check: implement it in one of the per-domain modules
+ * (secrets, env, headers, dangerous, language, public-assets, quality)
+ * and append a `{ id, run }` entry to `ALL_CHECKS` below. The id is the
+ * stable identifier surfaced in CLI output and is what users would put
+ * in any future per-check disable list.
+ */
+import { checkHardcodedSecrets, checkConfigSecretLeaks } from "./secrets.js";
+import { checkEnvCommitted, checkEnvExample, checkGitignore } from "./env.js";
+import { checkRobotsTxt, checkSitemapXml, checkFavicon } from "./public-assets.js";
+import { checkSecurityHeaders } from "./headers.js";
+import { checkDangerousPatterns } from "./dangerous.js";
+import { checkLanguagePatterns, checkPythonSecretKeyEnv, checkRubySecretKeyBaseEnv, } from "./language.js";
+import { checkPlaceholderContent } from "./quality.js";
+export * from "./types.js";
+export { checkHardcodedSecrets, checkConfigSecretLeaks, checkEnvCommitted, checkEnvExample, checkGitignore, checkRobotsTxt, checkSitemapXml, checkFavicon, checkSecurityHeaders, checkDangerousPatterns, checkLanguagePatterns, checkPythonSecretKeyEnv, checkRubySecretKeyBaseEnv, checkPlaceholderContent, };
+export const ALL_CHECKS = [
+    { id: "hardcoded-secrets", run: checkHardcodedSecrets },
+    { id: "config-secret-leaks", run: checkConfigSecretLeaks },
+    { id: "env-committed", run: checkEnvCommitted },
+    { id: "env-example", run: checkEnvExample },
+    { id: "gitignore", run: checkGitignore },
+    { id: "robots-txt", run: checkRobotsTxt },
+    { id: "sitemap-xml", run: checkSitemapXml },
+    { id: "favicon", run: checkFavicon },
+    { id: "security-headers", run: checkSecurityHeaders },
+    { id: "dangerous-patterns", run: checkDangerousPatterns },
+    { id: "language-patterns", run: checkLanguagePatterns },
+    { id: "python-secret-key-env", run: checkPythonSecretKeyEnv },
+    { id: "ruby-secret-key-base-env", run: checkRubySecretKeyBaseEnv },
+    { id: "placeholder-content", run: checkPlaceholderContent },
+];