cleartoship 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClearToShip
+
+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,264 @@
+# ClearToShip
+
+> The 30-second pre-launch security clearance for AI-built & vibe-coded apps.
+
+AI coding assistants write code fast, but they optimise for *"runs without errors"*, not
+*"runs without leaks"*. The failure mode is almost never a dangerous line of code — it's an
+**absent** one: the session check that was never written, the RLS policy that was never
+enabled, the package name the model invented.
+
+`cleartoship` is a static pre-flight check for exactly those gaps. No database connection, no
+account, no upload — it reads your repo and exits non-zero if you shouldn't deploy.
+
+```bash
+npx cleartoship
+```
+
+## What it checks
+
+**Next.js server surface** — Server Actions, Route Handlers, client boundary
+
+| Rule | Severity | What it catches |
+| --- | --- | --- |
+| **CTS001** | critical | Server Action / Route Handler mutates the database with no session check |
+| **CTS002** | high | Action takes caller input and writes it with no runtime schema validation |
+| **CTS003** | critical | `SUPABASE_SERVICE_ROLE_KEY` client built inside a user-reachable action |
+| **CTS004** | medium | Authenticated mutation keyed only on a caller-supplied id (IDOR) |
+| **CTS040** | high | Client component reads a server-side `process.env` variable |
+| **CTS041** | high | `supabase.auth.getSession()` used as a server-side auth check — it does not revalidate the JWT |
+| **CTS042** | critical | Webhook endpoint accepts an unsigned, unverified payload |
+| **CTS043** | high | Request body spread straight into a database write (mass assignment) |
+| **CTS044** | medium | `.passthrough()` / `z.any()` makes the schema decorative |
+| **CTS045** | critical | AI SDK client set to `dangerouslyAllowBrowser: true` |
+| **CTS046** | high | Cron route with neither `CRON_SECRET` nor a session check |
+
+**Supabase / PostgreSQL** — schema, RLS, storage
+
+| Rule | Severity | What it catches |
+| --- | --- | --- |
+| **CTS010** | critical | Public table with Row Level Security never enabled |
+| **CTS011** | low | RLS on with no policies — fail-closed, but the feature is probably broken |
+| **CTS012** | critical | Policy grants writes with an always-true predicate |
+| **CTS013** | high | Anonymous `SELECT` over a table holding emails, tokens or billing ids |
+| **CTS014** | high | Table has a `user_id` column but no policy compares it to `auth.uid()` |
+| **CTS015** | medium | `SECURITY DEFINER` function without a pinned `search_path` |
+| **CTS016** | medium/high | View with definer rights, or a materialized view, exposed over the Data API |
+| **CTS017** | critical | `GRANT INSERT/UPDATE/DELETE … TO anon` |
+| **CTS018** | critical | Policy trusts `user_metadata`, which the user can edit themselves |
+| **CTS019** | critical | `auth.users` republished through a view in the public schema |
+| **CTS050** | medium | Overlapping permissive policies — they OR together and only widen access |
+| **CTS051** | high | Storage policy lets anyone list every object in every bucket |
+| **CTS052** | high | `SECURITY DEFINER` function executable by `anon` |
+
+**Supply chain** — hallucinated and hostile dependencies
+
+| Rule | Severity | What it catches |
+| --- | --- | --- |
+| **CTS020** | critical | Dependency that **does not exist** on npm/PyPI — a hallucinated import |
+| **CTS021** | high | Dependency registered days ago with near-zero downloads (slopsquat shape) |
+| **CTS022** | low | Runtime dependency with almost no users |
+| **CTS023** | high/medium | Name is one edit from a popular package (`expres` → `express`) |
+| **CTS024** | by CVSS | Dependency version has a **published advisory**, resolved live from [OSV.dev](https://osv.dev) |
+| **CTS025** | low | Dependency deprecated upstream |
+| **CTS026** | critical | Registry serves HTTP 451 — the package was pulled for malware |
+| **CTS027** | critical | Package was unpublished but still has installs; the name is open to takeover |
+| **CTS028** | critical | `postinstall` hook that curls, evals or shells out |
+
+Dependency rules read `package.json`, `requirements.txt` and `pyproject.toml` — **and**
+`README.md`, `AGENTS.md`, `CLAUDE.md` and `.cursorrules`, because a hallucinated
+`npm install` line gets copy-pasted out of an agent instruction file long before it
+reaches a manifest.
+
+**Secrets & client bundle**
+
+| Rule | Severity | What it catches |
+| --- | --- | --- |
+| **CTS030** | critical | Hardcoded provider key — Supabase service-role, Stripe live, OpenAI, AWS, GitHub … |
+| **CTS031** | critical | Server secret routed through a `NEXT_PUBLIC_` variable |
+| **CTS032** | high | `.env` in a git repo with no matching `.gitignore` rule |
+| **CTS033** | critical | `'use client'` component reaching for a server-only secret |
+| **GL-\*** | high/critical | 219 further credential providers, vendored from [gitleaks](https://github.com/gitleaks/gitleaks) (MIT), gated on Shannon entropy |
+
+**Community ruleset** — 436 additional rules vendored from
+[GuardVibe](https://github.com/goklab/guardvibe) (Apache-2.0)
+
+Reported under their upstream `VG###` ids. These cover ground the AST scanners
+don't: known-vulnerable framework versions (`next` 14.2.3 is still shipped by a
+lot of AI scaffolds and carries CVE-2025-29927, a middleware auth bypass),
+Dockerfiles, Terraform, GitHub Actions pinning, prompt injection and MCP tool
+runtimes, React Native, Go and shell.
+
+27 upstream rules are **superseded** where ClearToShip's own AST check is more
+precise, and 5 are **withheld** as measurably noisy — both lists carry a reason
+per rule in `src/scanners/community.ts`. Run `--no-community` to use only
+ClearToShip's rules. See [ATTRIBUTION.md](ATTRIBUTION.md).
+
+Findings map to **OWASP Top 10:2025** and CWE.
+
+## Usage
+
+```bash
+npx cleartoship                          # scan the whole project
+npx cleartoship app supabase             # scan specific paths
+npx cleartoship --offline                # no registry lookups
+npx cleartoship --fix-prompt             # prompt to paste into Cursor / Claude Code
+npx cleartoship --json -o report.json    # machine-readable
+npx cleartoship --sarif -o results.sarif # GitHub code scanning
+npx cleartoship --fail-on high           # stricter CI gate (default: critical)
+npx cleartoship --ignore CTS004,CTS022   # skip rules
+npx cleartoship --no-community           # ClearToShip rules only
+npx cleartoship --markdown               # markdown report (PR comments / summaries)
+```
+
+Suppress a single finding inline:
+
+```ts
+// cleartoship-ignore CTS001 — invoked only by a cron job, never by a request
+export async function reconcileBilling() { … }
+```
+
+`// cts-ignore` on its own suppresses every rule at that location. The directive
+may sit at the top of a multi-line comment block, so a real justification has
+room to be written out.
+
+## Continuous integration
+
+### GitHub Action (recommended)
+
+Posts a summary comment on every pull request, blocks the merge on critical
+findings, and optionally uploads to the Security tab. Copy
+[`examples/security.yml`](examples/security.yml) into `.github/workflows/`:
+
+```yaml
+name: ClearToShip
+on: [pull_request]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: murtazaozdemir/cleartoship@v0.3.0
+        with:
+          fail-on: critical
+          comment: true
+```
+
+| Input | Default | Purpose |
+| --- | --- | --- |
+| `paths` | *(whole project)* | Files or directories to scan |
+| `fail-on` | `critical` | Fail the job at or above this severity (`critical`/`high`/`medium`/`low`/`none`) |
+| `comment` | `true` | Post/update a sticky summary comment on the PR |
+| `sarif` | `false` | Upload results to GitHub code scanning |
+| `offline` | `false` | Skip registry and OSV lookups |
+| `working-directory` | `.` | Directory to scan from |
+
+Outputs `verdict` (`clear`/`conditional`/`hold`), `critical`, `high` and `total`
+for use in later steps. The comment is *sticky* — re-runs edit the same comment
+instead of piling up. Until the npm package is published, the action builds
+itself from its own checkout, so `uses: …@ref` works immediately.
+
+### Plain CLI
+
+```yaml
+      - run: npx cleartoship --fail-on=critical
+```
+
+To feed findings into GitHub's Security tab without the Action:
+
+```yaml
+      - run: npx cleartoship --sarif -o results.sarif --fail-on=none
+      - uses: github/codeql-action/upload-sarif@v3
+        with: { sarif_file: results.sarif }
+```
+
+## How it works## How it works
+
+Four scanners, all static — nothing is uploaded and no database is contacted.
+
+1. **Server Actions & Route Handlers** — parses TS/TSX with Babel, finds every exported
+   function reachable over HTTP (`'use server'` modules, inline directives, `app/**/route.ts`
+   method exports), then asks whether it authenticates, validates and scopes its writes.
+   Recognises `next-safe-action` / `zsa` style wrappers so wrapped actions are not
+   double-reported.
+2. **Row Level Security** — replays your `.sql` migrations in filename order to build a model
+   of the resulting schema (tables, columns, RLS state, policies, grants, views, functions),
+   then judges the end state. This is the same class of check as Supabase's own `splinter`
+   linter, but static, so it runs on a pull request with no live database.
+3. **Dependency hallucination** — resolves every declared dependency against npm and PyPI,
+   flagging names that do not exist at all, names registered days ago with no users, and names
+   one edit away from a popular package. Results are cached for 24h under
+   `~/.cache/cleartoship`.
+4. **Secrets & client boundary** — pattern plus verification: candidate JWTs are decoded and
+   only reported when the payload actually says `role: service_role`. 15 hand-tuned patterns
+   cover the providers that matter most; 219 more come from the vendored gitleaks ruleset,
+   each gated on a keyword prefilter and a Shannon entropy threshold so that
+   `your_api_key_here` never reads as a breach. Values in test fixtures, docs and
+   commented-out counter-examples are downgraded rather than reported.
+5. **Known vulnerabilities** — dependency versions are resolved from
+   `package-lock.json` / `pnpm-lock.yaml` / `yarn.lock` (falling back to the range floor)
+   and queried against OSV.dev, the database behind Google's `osv-scanner`. Live data
+   beats hand-written version regexes, which go stale the week they are written — so when
+   OSV answers, the vendored CVE rules stand down. `--offline` reverses that.
+
+### Design notes
+
+- **Fail open on uncertainty.** If a registry lookup fails, the package is treated as valid —
+  a network blip must never be reported as a hallucinated dependency.
+- **Test fixtures are not breaches.** Credentials under `tests/`, `fixtures/`, `docs/` or in a
+  commented-out line are reported at `low`, never as blocking criticals.
+- **Precision over recall on the noisy rules.** Typosquat matching skips exact matches and
+  names shorter than five characters, where one-edit neighbours are meaningless.
+
+## Programmatic use
+
+```ts
+import { scan, renderJson } from 'cleartoship';
+
+const result = await scan({ root: process.cwd(), offline: true });
+console.log(result.counts); // { critical: 0, high: 2, medium: 1, low: 0, info: 0 }
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Clear to ship at the configured `--fail-on` threshold |
+| `1` | Findings at or above the threshold |
+| `2` | The scanner itself errored |
+
+## Prior art, and what was taken from where
+
+ClearToShip occupies the gap between general-purpose scanners and the modern AI-assisted
+stack. It is not a replacement for [Semgrep](https://github.com/semgrep/semgrep),
+[Trivy](https://github.com/aquasecurity/trivy), [OSV-Scanner](https://github.com/google/osv-scanner)
+or [TruffleHog](https://github.com/trufflesecurity/trufflehog) — run those too. It answers a
+narrower question they don't: *given that an LLM wrote this, what did it forget?*
+
+The rule set was designed after surveying the field. What each source contributed:
+
+| Source | License | What was taken |
+| --- | --- | --- |
+| [supabase/splinter](https://github.com/supabase/splinter) | none stated | The vulnerability classes behind CTS010–019 and CTS050–052. Splinter runs SQL against a live database; these are static reimplementations against migration files. Verified by pointing ClearToShip at splinter's own `test/sql/` fixtures. |
+| [slopcheck](https://github.com/mattschaller/slopcheck) | MIT | Three distinctions worth making: HTTP 451 (pulled for malware) ≠ 404 (never existed) ≠ unpublished-with-installs (open to takeover) — CTS026/CTS027. And the idea of reading install commands out of prose and agent instruction files. |
+| [guardvibe](https://github.com/goklab/guardvibe) | Apache-2.0 | Coverage gaps: webhook signature verification, cron secrets, mass assignment, `dangerouslyAllowBrowser`, schema escape hatches, `getSession` vs `getUser` — CTS040–046. |
+
+**No rule content was copied.** Every check here is an independent implementation, and the
+detection engine is different in kind: ClearToShip parses TypeScript to an AST and replays SQL
+migrations into a schema model, where the regex-and-window approach used by several of these
+tools cannot express "this function has no auth check anywhere in its body".
+
+That distinction is not just technical pride — it is a licensing constraint. Two of the most
+tempting corpora, **TruffleHog** (800+ verified credential detectors) and
+**RouteWarden**, are **AGPL-3.0**; lifting their detectors into a commercial product carries
+the AGPL's network-use obligations. **semgrep-rules** ships under the bespoke *Semgrep Rules
+License v1.0*, which needs reading before any rule is reused. **splinter** and
+**supabase-exposure-check** publish no license at all, which means default copyright — ideas
+are free, expression is not. Vulnerability classes are facts and cannot be owned; regexes,
+queries and rule text can be.
+
+## License
+
+MIT

package/action.yml

@@ -0,0 +1,154 @@
+name: ClearToShip
+description: Pre-flight security check for AI-built & vibe-coded apps. Blocks PRs on missing Server Action auth, Supabase RLS holes, hallucinated packages and leaked keys.
+author: ClearToShip
+branding:
+  icon: shield
+  color: green
+
+inputs:
+  paths:
+    description: Files or directories to scan, space-separated. Defaults to the whole project.
+    required: false
+    default: ''
+  fail-on:
+    description: Fail the job at or above this severity (critical, high, medium, low, none).
+    required: false
+    default: critical
+  comment:
+    description: Post (and update) a summary comment on the pull request. Requires pull-requests write permission.
+    required: false
+    default: 'true'
+  sarif:
+    description: Write results.sarif for upload to GitHub code scanning.
+    required: false
+    default: 'false'
+  offline:
+    description: Skip registry and OSV lookups.
+    required: false
+    default: 'false'
+  version:
+    description: Version of the cleartoship npm package to run.
+    required: false
+    default: latest
+  working-directory:
+    description: Directory to run the scan from.
+    required: false
+    default: '.'
+  github-token:
+    description: Token used to post the PR comment.
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  verdict:
+    description: One of clear, conditional, or hold.
+    value: ${{ steps.scan.outputs.verdict }}
+  critical:
+    description: Number of critical findings.
+    value: ${{ steps.scan.outputs.critical }}
+  high:
+    description: Number of high findings.
+    value: ${{ steps.scan.outputs.high }}
+  total:
+    description: Total number of findings.
+    value: ${{ steps.scan.outputs.total }}
+
+runs:
+  using: composite
+  steps:
+    - name: Resolve ClearToShip
+      id: resolve
+      shell: bash
+      run: |
+        # Prefer the published npm package. If it cannot be resolved — which is
+        # the case before the first publish, or when a pinned version is not on
+        # the registry — fall back to building from this action's own checkout,
+        # so `uses: <owner>/cleartoship@ref` works with no npm dependency.
+        ver="${{ inputs.version }}"
+        if [ "$ver" != "local" ] && npm view "cleartoship@${ver}" version >/dev/null 2>&1; then
+          echo "cmd=npx --yes cleartoship@${ver}" >> "$GITHUB_OUTPUT"
+          echo "Using published cleartoship@${ver}"
+        else
+          echo "Published package not found; building from the action checkout."
+          ( cd "$GITHUB_ACTION_PATH" && npm ci --silent && npm run build --silent )
+          echo "cmd=node ${GITHUB_ACTION_PATH}/dist/cli.js" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Run ClearToShip
+      id: scan
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: |
+        set -o pipefail
+        CTS="${{ steps.resolve.outputs.cmd }}"
+        args=()
+        [ -n "${{ inputs.paths }}" ] && args+=(${{ inputs.paths }})
+        [ "${{ inputs.offline }}" = "true" ] && args+=(--offline)
+
+        # The gate is applied at the end so the report and comment are produced
+        # regardless of pass/fail; --fail-on=none keeps this step from aborting early.
+        $CTS "${args[@]}" --json --fail-on=none > cleartoship.json
+        $CTS "${args[@]}" --markdown --fail-on=none > cleartoship.md || true
+        if [ "${{ inputs.sarif }}" = "true" ]; then
+          $CTS "${args[@]}" --sarif --fail-on=none > results.sarif || true
+        fi
+
+        node -e '
+          const r = require("./cleartoship.json");
+          const out = process.env.GITHUB_OUTPUT;
+          const fs = require("fs");
+          fs.appendFileSync(out, `verdict=${r.verdict}\n`);
+          fs.appendFileSync(out, `critical=${r.counts.critical}\n`);
+          fs.appendFileSync(out, `high=${r.counts.high}\n`);
+          fs.appendFileSync(out, `total=${r.findings.length}\n`);
+        '
+
+        # Job summary — always shown on the run.
+        cat cleartoship.md >> "$GITHUB_STEP_SUMMARY"
+
+    - name: Comment on pull request
+      if: ${{ inputs.comment == 'true' && github.event_name == 'pull_request' }}
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        GH_TOKEN: ${{ inputs.github-token }}
+        PR: ${{ github.event.pull_request.number }}
+      run: |
+        # A sticky comment: find a previous ClearToShip comment and edit it, so
+        # re-runs update in place instead of piling up.
+        marker="<!-- cleartoship -->"
+        printf '%s\n\n' "$marker" > body.md
+        cat cleartoship.md >> body.md
+
+        id=$(gh api "repos/${{ github.repository }}/issues/${PR}/comments" \
+              --jq "map(select(.body | contains(\"$marker\"))) | .[0].id // empty" 2>/dev/null || true)
+        if [ -n "$id" ]; then
+          gh api -X PATCH "repos/${{ github.repository }}/issues/comments/${id}" -F body=@body.md >/dev/null
+        else
+          gh api -X POST "repos/${{ github.repository }}/issues/${PR}/comments" -F body=@body.md >/dev/null
+        fi
+
+    - name: Upload SARIF
+      if: ${{ inputs.sarif == 'true' && always() }}
+      uses: github/codeql-action/upload-sarif@v3
+      with:
+        sarif_file: ${{ inputs.working-directory }}/results.sarif
+
+    - name: Apply severity gate
+      shell: bash
+      run: |
+        gate="${{ inputs.fail-on }}"
+        [ "$gate" = "none" ] && exit 0
+        declare -A rank=( [critical]=4 [high]=3 [medium]=2 [low]=1 )
+        floor=${rank[$gate]:-4}
+        crit=${{ steps.scan.outputs.critical }}
+        high=${{ steps.scan.outputs.high }}
+        # Only critical and high are wired as outputs; medium/low never block by default.
+        blocking=0
+        [ "$floor" -le 4 ] && blocking=$((blocking + crit))
+        [ "$floor" -le 3 ] && blocking=$((blocking + high))
+        if [ "$blocking" -gt 0 ]; then
+          echo "::error::ClearToShip found $blocking finding(s) at or above '$gate'."
+          exit 1
+        fi
+        echo "ClearToShip: clear to ship at '$gate'."

package/dist/banner.d.ts

@@ -0,0 +1 @@
+export declare function banner(version: string): string;

package/dist/banner.js

@@ -0,0 +1,14 @@
+import pc from 'picocolors';
+const ART = String.raw `
+   ___ _              _____      ___ _    _
+  / __| |___ __ _ _ _|_   _|__  / __| |_ (_)_ __
+ | (__| / -_) _' | '_| | |/ _ \ \__ \ ' \| | '_ \
+  \___|_\___\__,_|_|   |_|\___/ |___/_||_|_| .__/
+                                           |_|`;
+export function banner(version) {
+    return (pc.cyan(ART) +
+        '\n  ' +
+        pc.dim('Pre-flight security check for AI-built & vibe-coded apps') +
+        pc.dim(` • v${version}`) +
+        '\n');
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { Command, Option } from 'commander';
+import { writeFileSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import pc from 'picocolors';
+import { scan } from './scan.js';
+import { banner } from './banner.js';
+import { renderTerminal, renderJson, renderSarif, renderFixPrompt, renderBadge, renderMarkdown, } from './report.js';
+import { SEVERITY_ORDER } from './types.js';
+const here = dirname(fileURLToPath(import.meta.url));
+let version = '0.0.0';
+try {
+    version = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')).version;
+}
+catch {
+    /* running from an unusual layout; version is cosmetic */
+}
+const program = new Command();
+program
+    .name('cleartoship')
+    .description('Pre-flight security check for AI-built & vibe-coded apps.\n' +
+    'Finds missing Server Action auth, Supabase RLS holes, hallucinated npm\n' +
+    'packages and leaked keys before you deploy.')
+    .version(version, '-v, --version')
+    .argument('[paths...]', 'files or directories to scan (default: the whole project)')
+    .option('-C, --cwd <dir>', 'project root', process.cwd())
+    .addOption(new Option('--fail-on <severity>', 'exit non-zero at or above this severity')
+    .choices(['critical', 'high', 'medium', 'low', 'none'])
+    .default('critical'))
+    .addOption(new Option('--min-severity <severity>', 'hide findings below this severity')
+    .choices(['critical', 'high', 'medium', 'low', 'info'])
+    .default('low'))
+    .option('--json', 'emit machine-readable JSON instead of the report')
+    .option('--sarif', 'emit SARIF 2.1.0 (upload to GitHub code scanning)')
+    .option('--fix-prompt', 'emit a ready-to-paste prompt for Cursor / Claude Code')
+    .option('--badge', 'print the markdown status badge for your README')
+    .option('--markdown', 'emit a markdown report (for PR comments / job summaries)')
+    .option('-o, --output <file>', 'write the chosen output to a file instead of stdout')
+    .option('--offline', 'skip registry lookups (no network)')
+    .option('--no-community', 'run only ClearToShip rules, skipping the vendored community ruleset')
+    .option('--ignore <ids>', 'comma-separated rule ids to skip, e.g. CTS004,CTS022')
+    .option('--only <ids>', 'comma-separated rule ids to report exclusively')
+    .option('--no-banner', 'suppress the ASCII header')
+    .option('--quiet', 'only print findings, no passed checks')
+    .option('--verbose', 'extra diagnostic output')
+    .action(async (paths, opts) => {
+    const machineReadable = Boolean(opts.json || opts.sarif || opts.fixPrompt || opts.badge || opts.markdown);
+    const interactive = !machineReadable && !opts.output;
+    if (interactive && opts.banner !== false) {
+        process.stderr.write(banner(version) + '\n');
+    }
+    const list = (value) => value ? value.split(',').map((s) => s.trim()).filter(Boolean) : undefined;
+    const result = await scan({
+        root: opts.cwd,
+        paths,
+        offline: opts.offline,
+        noCommunity: opts.community === false,
+        ignore: list(opts.ignore),
+        only: list(opts.only),
+        minSeverity: opts.minSeverity,
+        verbose: opts.verbose,
+        onProgress: interactive
+            ? (step, total, name) => {
+                process.stderr.write(pc.dim(`  [${step}/${total}] ${name}…\n`));
+            }
+            : undefined,
+    });
+    if (interactive) {
+        process.stderr.write(`\n  ${pc.dim('root')}      ${result.root}\n` +
+            `  ${pc.dim('stack')}     ${result.framework}\n`);
+    }
+    let output;
+    if (opts.json)
+        output = renderJson(result);
+    else if (opts.sarif)
+        output = renderSarif(result, version);
+    else if (opts.fixPrompt)
+        output = renderFixPrompt(result);
+    else if (opts.badge)
+        output = renderBadge(result);
+    else if (opts.markdown)
+        output = renderMarkdown(result);
+    else
+        output = renderTerminal(result, { showPassed: !opts.quiet });
+    if (opts.output) {
+        writeFileSync(opts.output, output.endsWith('\n') ? output : output + '\n');
+        process.stderr.write(pc.dim(`\n  wrote ${opts.output}\n`));
+    }
+    else {
+        process.stdout.write(output.endsWith('\n') ? output : output + '\n');
+    }
+    if (opts.failOn === 'none')
+        return;
+    const floor = SEVERITY_ORDER[opts.failOn];
+    const blocking = result.findings.filter((f) => SEVERITY_ORDER[f.severity] >= floor).length;
+    if (blocking > 0)
+        process.exitCode = 1;
+});
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(pc.red(`cleartoship: ${err instanceof Error ? err.message : String(err)}\n`));
+    process.exitCode = 2;
+});

package/dist/data/popular.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Frequently-installed packages, used as typosquat bait references. A candidate
+ * that sits one edit away from one of these — and has almost no downloads of its
+ * own — is very likely a squat or an LLM misremembering the real name.
+ */
+export declare const POPULAR_NPM: string[];
+export declare const POPULAR_PYPI: string[];
+/** Damerau-Levenshtein distance, capped: returns `max + 1` once it exceeds `max`. */
+export declare function editDistance(a: string, b: string, max?: number): number;
+/**
+ * Closest popular package within `max` edits, or null.
+ *
+ * A name that *is* one of the popular packages is never its own lookalike, and
+ * names shorter than five characters are skipped: at that length almost every
+ * real package has a one-edit neighbour, so the signal is noise.
+ */
+export declare function nearestPopular(name: string, list: string[], max?: number): string | null;