shippingszn 0.9.7 → 0.10.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 shippingszn llc
+Copyright (c) 2026 Ryan Zaucha
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,27 +1,46 @@
 # shippingszn
 
-Primary local launch inspector for AI-built apps. Run it inside the app you are
-about to ship to catch the launch debt AI builders commonly miss: leaked API
-keys, missing crawl assets, weak browser defenses, dangerous code patterns, and
-last-mile polish gaps.
+`shippingszn` is a local, read-only launch-readiness scanner for apps built with
+AI. It runs inside the project you are about to ship and reads your files to
+catch the launch debt AI builders commonly miss — leaked API keys, missing crawl
+assets, weak browser defenses, dangerous code patterns, unguarded routes, and
+last-mile polish gaps — then prints a 0-100 readiness score, a launch verdict,
+and every finding with the file and line it came from. It never writes to your
+project and needs no account to run.
+
+## Install / usage
 
 ```bash
-npx shippingszn@latest
+npx shippingszn@latest          # scan the current directory
+npx shippingszn@latest ./path   # scan a specific directory
+npx shippingszn@latest --no-telemetry   # run fully offline, zero network calls
 # or
 pnpm dlx shippingszn@latest
 ```
 
-The CLI **never writes, modifies, or deletes** any files - it only reads.
-Normal runs create a locked scan handoff for checkout and send one anonymous
-Wall report-card summary with score, severity counts, files scanned, scanner
-version, and safe stack tags. It never uploads source code, repo URLs, project
-names, secrets, handles, or emails. Finding-level detail stays out of public
-CLI/Wall output and opens inside the paid Launch Fix Kit.
-
-Human output starts with a verdict, a higher-is-better Readiness Score,
-severity counts, a short plain-English launch-risk explanation, completed
-checks, and the locked Fix Kit handoff. Run with `--json` to get the same
-score-and-counts summary in a machine-readable shape:
+This is the open-source scanner. The optional paid **Launch Fix Kit** — the
+remediation layer with per-finding fixes, prompts to paste straight into your AI
+builder, the 58-item launch workbook, unlimited re-scans, and launch monitoring
+— lives at <https://shippingszn.com/fix-kit>. The scanner is free and always
+will be; the Fix Kit is how you fix what it finds.
+
+The CLI **never writes, modifies, or deletes** any files - it only reads. (The
+one exception is a tiny first-run marker under your config dir,
+`~/.config/shippingszn/seen`, used to show the telemetry notice once.) By
+default each run makes two anonymous requests: a scan handoff for checkout that
+carries finding-level detail (severity, checklist item, `file:line`, and a short
+evidence snippet — secret values always redacted before upload), and an
+aggregate Wall summary with score, severity counts, files scanned, scanner
+version, and safe stack tags. Neither uploads full source files, repo URLs,
+project names, unredacted secrets, handles, or emails. Pass `--no-telemetry` to
+run fully offline (zero network calls). Details in [Telemetry](#telemetry).
+
+**The free scan is the full diagnosis.** Human output prints a verdict, a
+higher-is-better Readiness Score, severity counts, and **every finding grouped
+by severity** — its severity, the checklist item it maps to, the `file:line`,
+and what's wrong — plus completed-checks coverage and the Fix Kit CTA. Run with
+`--json` to get the same in a machine-readable shape, including the full
+`findings` array:
 
 ```json
 {
@@ -30,7 +49,19 @@ score-and-counts summary in a machine-readable shape:
   "counts": { "critical": 0, "high": 11, "medium": 1, "lower": 1 },
   "filesScanned": 128,
   "coverage": { "checksCompleted": 19, "checklistAreas": 51 },
-  "detailsLocked": true,
+  "scannerVersion": "0.10.0",
+  "findings": [
+    {
+      "checkId": "hardcoded-secrets",
+      "itemId": "secrets",
+      "severity": "high",
+      "itemTitle": "Lock up your API keys and passwords",
+      "file": "src/lib/config.ts",
+      "line": 12,
+      "message": "Possible hardcoded API key detected.",
+      "permalink": "https://shippingszn.com/i/secrets"
+    }
+  ],
   "unlockUrl": "https://shippingszn.com/fix-kit?scanResultId=00000000-0000-4000-8000-000000000123",
   "scanHandoff": {
     "status": "uploaded",
@@ -40,15 +71,37 @@ score-and-counts summary in a machine-readable shape:
 }
 ```
 
-Finding titles, files, evidence, AI-builder punch list, and verification steps
-are paid. The free CLI explains why the score matters, but the actual fixes
-unlock inside the Launch Fix Kit.
+The findings are free. What's **paid** is the remediation layer: per-finding fix
+instructions, prompts to paste straight into your AI builder, the 58-item launch
+workbook, unlimited re-scans, and launch monitoring. The free CLI tells you
+exactly what's wrong; the Launch Fix Kit is how you fix it.
+
+## Telemetry
+
+Plain `npx shippingszn@latest` makes **two** anonymous requests per run:
 
-## Aggregate summary
+1. **Scan handoff** (`POST /api/scan-results`) — powers the `/fix-kit` link the
+   CLI prints. It carries finding-level detail: each finding's severity, the
+   checklist item it maps to, its `file:line` location, and a short evidence
+   snippet from the matched line. Secret values are always redacted to a
+   `abc123…x9z2` form before upload. It does not include your repo URL, project
+   name, or full source files.
+2. **Aggregate Wall summary** (`POST /api/wall`) — intentionally small: score,
+   launch label, files scanned, finding counts by severity, detected stack
+   tags, scanner version, and timestamp. No paths, no filenames, no
+   finding-level detail.
+
+On the **first run on a machine**, the CLI prints a description of both requests
+plus the exact aggregate payload (to stderr, so it never corrupts `--json`
+output) and a note that you can turn it off. Telemetry is default-on but fully
+transparent and opt-out-able:
+
+```bash
+npx shippingszn@latest --no-telemetry   # zero network calls, fully offline
+```
 
-Plain `npx shippingszn@latest` sends the Wall summary automatically. The stored
-row is anonymous and intentionally small: score, launch label, files scanned,
-finding counts by severity, detected stack tags, scanner version, and timestamp.
+`--no-wall` is an alias for `--no-telemetry`. With telemetry off, the CLI makes
+**no** scan-handoff upload and **no** Wall ping.
 
 The same run also creates a scan-specific paid-report handoff. The terminal
 prints a `/fix-kit?scanResultId=...` URL so checkout can carry that scan into
@@ -79,10 +132,38 @@ maps back to one of the items on the checklist.
 - Placeholder content (`lorem ipsum`, `John Doe`, `test@example.com`) and
   `TODO` / `FIXME` / `XXX` / `HACK` comments.
 
-Internally each finding is tagged Critical, High, Medium, or Lower and maps to
-the relevant checklist item. The free CLI output keeps that finding-level detail
-locked; the Fix Kit turns it into the human launch decision and AI-builder punch
-list.
+Each finding is tagged Critical, High, Medium, or Lower and maps to the relevant
+checklist item. All of that finding-level detail is free and printed on every
+run; the Fix Kit turns it into the human launch decision and AI-builder punch
+list of fixes.
+
+## Scoring
+
+The 0-100 Readiness Score is not a black box. Each finding subtracts a fixed
+number of penalty points from 100 based on its severity:
+
+| Severity | Penalty per finding |
+| -------- | ------------------- |
+| Critical | 35                  |
+| High     | 22                  |
+| Medium   | 10                  |
+| Lower    | 5                   |
+
+The raw score is `100 - (sum of all penalties)`, clamped to the `0-100` range.
+The score is then floored into a severity band so the number can never contradict
+the verdict — the most severe finding present sets the band ceiling:
+
+| Band                 | Score range | Trigger                                   |
+| -------------------- | ----------- | ----------------------------------------- |
+| Fix now (no-go)      | 0-59        | any Critical finding caps the score at 59 |
+| Fix-first            | 60-79       | any High finding (no Critical) caps at 79 |
+| Verify before launch | 80-89       | any Medium finding (no Critical/High)     |
+| Launchable           | 90-100      | only Lower findings, or a clean scan      |
+
+So one Critical finding alone drops you to at most 59 ("Fix now") regardless of
+how few findings there are; a single High caps you at 79 ("Fix-first"). Count
+pressure moves the score inside its band. The CLI runs with no source-side score
+cap — the score you see is the severity-banded score.
 
 ## Suppressing false positives
 
@@ -132,7 +213,10 @@ rerun loop before you ship.
 shippingszn [path] [options]
 
 Options:
-  --json                Output a machine-readable JSON summary.
+  --json                Output a machine-readable JSON summary (includes the
+                        full findings array).
+  --no-telemetry        Run fully offline: no scan handoff, no Wall ping, zero
+                        network calls. (--no-wall is an alias.)
   --proof               Backward-compatible alias. Normal runs already return
                         a scan-specific Launch Fix Kit URL.
   --base-url <url>      Base URL used to build checkout and Fix Kit links.
@@ -156,17 +240,18 @@ This makes the CLI suitable for CI:
 ```
 
 For PR scan signal, have GitHub Actions run the scanner and post the JSON
-summary as a comment: score, severity counts, and unlock URL.
+summary as a comment: score, severity counts, findings, and unlock URL.
 
 ## Privacy
 
 `shippingszn` reads files on your machine. It never uploads source code. By
-default it creates a locked scan handoff for checkout and makes one best-effort
+default it creates a scan handoff for checkout and makes one best-effort
 outbound request to post anonymous Wall stats: score, launch label, files
 scanned count, finding counts by severity, detected stack tags, scanner version,
 and timestamp. Wall stats never include source code, file paths, filenames,
 project names, repo URLs, secrets, emails, handles, finding titles, evidence, or
-report contents. The Wall summary is automatic and not user-configurable.
+report contents. The first run on a machine prints the exact payload to stderr,
+and `--no-telemetry` (alias `--no-wall`) turns off all network calls.
 
 ## License