shippingszn 0.8.0 → 0.8.3

package/README.md

@@ -1,10 +1,9 @@
 # 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.
+Primary local scanner for shippingszn launch readiness. Run it inside the app
+you are about to ship to catch the launch blockers AI builders commonly miss:
+leaked API keys, missing crawl assets, weak browser defenses, dangerous code
+patterns, and last-mile polish gaps.
 
 ```bash
 npx shippingszn
@@ -12,8 +11,74 @@ npx shippingszn
 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.
+The CLI **never writes, modifies, or deletes** any files - it only reads.
+Everything stays on your machine unless you explicitly opt in with `--proof`
+or `--publish`.
+
+Human output starts with a Launch Readiness Score, scope covered, the top next
+step to fix, and severity counts. Run with `--json` to get machine-readable
+findings, copy/paste fix prompts for your AI builder, and proof/report handoff
+fields:
+
+```json
+{
+  "launchReadiness": {
+    "score": 43,
+    "rawScore": 43,
+    "label": "No-go: launch blocked",
+    "decisionLabel": "No-go: launch blocked",
+    "goNoGoLabel": "No-go",
+    "confidence": "high",
+    "coveragePenalty": 0,
+    "coverageSummary": "CLI scan covered 4 readiness areas with 4 areas requiring owner verification.",
+    "topNextStep": "Fix Lock up your API keys and passwords: Possible OpenAI API key hardcoded in source.",
+    "proofCreatePath": "https://shippingszn.com/scan",
+    "proofUploadHint": "Run `npx shippingszn --json > shippingszn-scan.json`, then paste or upload that JSON in the web scan proof flow to create a shareable launch proof result.",
+    "proofUrl": "https://shippingszn.com/proof/00000000-0000-4000-8000-000000000123",
+    "proofResultId": "00000000-0000-4000-8000-000000000123",
+    "badgeMarkdown": "[![Launch readiness proof: 70%](https://shippingszn.com/api/badge.svg?...)](https://shippingszn.com/proof/00000000-0000-4000-8000-000000000123)",
+    "wallUrl": "https://shippingszn.com/wall",
+    "reportUrl": "https://shippingszn.com/report?scanResultId=00000000-0000-4000-8000-000000000123"
+  },
+  "findings": [
+    {
+      "severity": "critical",
+      "message": "Possible OpenAI API key hardcoded in source.",
+      "remediation": {
+        "fixPrompt": "You are fixing a shippingszn launch-readiness finding...",
+        "verify": "Re-run npx shippingszn --json and confirm this exact finding is gone...",
+        "escalation": "Escalate before launch if this touches secrets, auth, payments...",
+        "proofNextStep": "After the fix verifies clean, run npx shippingszn --json..."
+      }
+    }
+  ]
+}
+```
+
+When Critical or High findings make paid confidence relevant, the summary also
+includes a `/report` link. Clean scans and lower-risk findings do not push the
+paid report CTA.
+
+## Direct proof publishing
+
+Use `--proof` when you want the current scan to become shareable launch proof:
+
+```bash
+npx shippingszn --json --proof > shippingszn-scan.json
+```
+
+That opt-in posts the scan summary and remediation fields to
+`/api/scan-results`, then adds `launchReadiness.proofUrl`,
+`launchReadiness.proofResultId`, `launchReadiness.badgeMarkdown`,
+`launchReadiness.wallUrl`, and `launchReadiness.reportUrl` to the JSON. It
+also posts a proof-linked severity summary to the Wall of Launches. If proof
+upload fails, findings still print and JSON includes
+`launchReadiness.proofUploadError`; if the Wall publish fails, JSON includes
+`launchReadiness.wallPublishError`.
+
+For a manual handoff, you can still run `npx shippingszn --json >
+shippingszn-scan.json` and paste or upload the file at
+`https://shippingszn.com/scan`.
 
 ## What gets checked
 
@@ -62,6 +127,12 @@ shippingszn [path] [options]
 
 Options:
   --json                Output a machine-readable JSON report.
+  --publish             Opt in to posting an anonymous summary to the public
+                        Wall of Launches. Never uploads source code, paths,
+                        filenames, or project names.
+  --proof               Opt in to posting this scan to /api/scan-results and
+                        printing a proof URL, Wall URL, report URL, and badge.
+                        Can also be enabled with SHIPPINGSZN_PROOF=1.
   --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.
@@ -79,15 +150,33 @@ This makes the CLI suitable for CI:
 
 ```yaml
 # .github/workflows/launch-check.yml
-- run: npx shippingszn --json > launch-check.json
+- run: npx shippingszn --json --proof > launch-check.json
 ```
 
+For PR scan proof, have GitHub Actions run the scanner with `--proof` and post
+the JSON summary as a comment: score, severity counts, top next step, proof URL,
+badge markdown, Wall URL, report URL, and worst Critical/High findings. Keep
+`--publish` out of the workflow unless you explicitly want to publish an
+anonymous Wall summary when proof upload fails.
+
 ## Privacy
 
 `shippingszn` reads files on your machine. It never uploads source code,
-makes outbound network calls, or phones home. No telemetry. No accounts.
+makes outbound network calls, or phones home by default. No accounts.
 Inspect the source or audit `npm pack --dry-run` to confirm.
 
+If you want public launch-readiness proof, pass `--proof`. That opt-in posts
+the current scan result to shippingszn so it can create a proof page, report
+handoff, README badge, and proof-linked Wall entry. It uploads finding titles,
+messages, remediation prompts, verification text, checklist permalinks,
+severity counts, score, file count, target folder name, and scanner version. It
+does not upload source code or secret values.
+
+If you only want an anonymous Wall of Launches summary, pass `--publish`.
+That opt-in posts files scanned count, finding counts by severity, detected
+stack tags, and scanner version. It never uploads source code, file paths,
+filenames, project names, secrets, or report contents.
+
 ## License
 
 MIT. See [LICENSE](./LICENSE).