shipclear 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -68,6 +68,7 @@ npx shipclear ship # the full gate → SHIP-REPORT.md + verdict
68
68
  npx shipclear ship --fix-history
69
69
  # after fixing everything else: erase old commits that held a secret
70
70
  # (only for repos never pushed anywhere; refuses if it would lose any work)
71
+ npx shipclear badge # add a self-updating "cleared to ship" badge to your README
71
72
  ```
72
73
 
73
74
  The full report (`SHIP-REPORT.md`) ends with a checklist meant for an AI to work through with you — if you don't have one built into your terminal, paste that checklist and your code into any AI chat (ChatGPT, Claude.ai, Gemini — even a free one) and ask it to go through the list, or ask a developer friend.
@@ -82,6 +83,28 @@ The full report (`SHIP-REPORT.md`) ends with a checklist meant for an AI to work
82
83
  - 🟡 **SHIP WITH FIXES** — nothing catastrophic; close the listed items first.
83
84
  - 🛑 **DO NOT SHIP** — a critical finding (a leaked secret, a committed `.env`) needs fixing *and* usually a key rotation. The report tells you exactly what to do, step by step.
84
85
 
86
+ ## The badge
87
+
88
+ Once you've passed the gate, one command puts a **cleared to ship** badge in your README:
89
+
90
+ ```bash
91
+ npx shipclear badge
92
+ ```
93
+
94
+ It changes two files — your `README.md` (the badge itself) and `.github/workflows/shipclear.yml` (a GitHub Actions workflow). Commit and push both, and the badge is live:
95
+
96
+ ```bash
97
+ git add -A && git commit -m "add ShipClear badge" && git push
98
+ ```
99
+
100
+ That workflow is the point. Every time you push, GitHub re-runs the gate on the code you actually pushed, and the badge shows the real result — green while every pushed commit clears, red the moment one doesn't, and grey ("no status") before anything has been checked. You never update it by hand, and you can't make it green by skipping the gate on your laptop.
101
+
102
+ **Expect grey at first.** Until that first push triggers the workflow, the badge honestly reports that nothing has been checked yet.
103
+
104
+ **If it goes red,** run `npx shipclear ship` locally, fix what it lists, and push again. Red isn't the badge being broken — it's the badge doing its job.
105
+
106
+ If your project isn't on GitHub yet, `shipclear badge` will tell you so and stop, rather than giving you a badge that could never turn green.
107
+
85
108
  ## False positives
86
109
 
87
110
  Real-world code sometimes trips a pattern. Add the file path to a `.shipclearignore` in your project root (one path or glob per line) — and please [tell us](https://github.com/adamtimmerberg/ShipClear/issues/new?template=false_positive.md) so the pattern gets fixed for everyone.
@@ -60,8 +60,40 @@ That's the "Semantic checks" section at the bottom of `SHIP-REPORT.md`, and it's
60
60
 
61
61
  Expected. Deleting the fake account also removed what your login checked against, so you need a *real* login system now. The easiest path: ask the AI assistant you built the app with to "replace the hardcoded login with a real login system." (Common choices it might use: Supabase Auth, Clerk, Auth0, NextAuth — but you don't have to choose; it can.)
62
62
 
63
+ ## "My badge says `no status` / is grey"
64
+
65
+ Nothing has been checked yet, and the badge is saying so rather than guessing. It turns green or red after the first push that runs the workflow — check the **Actions** tab of your repo on GitHub. If no run appears there at all: make sure you committed **and pushed** `.github/workflows/shipclear.yml`, and that Actions is enabled for the repo (Settings → Actions → General).
66
+
67
+ ## "My badge went red but `shipclear ship` passes on my computer"
68
+
69
+ Three usual reasons, in order of likelihood:
70
+
71
+ 1. **You haven't pushed your fix yet.** The badge grades what's on GitHub, not what's on your laptop. `git add -A && git commit -m "fix" && git push`.
72
+ 2. **The findings aren't critical.** The badge requires a full ✅ CLEARED. Plain `shipclear ship` exits successfully on 🟡 SHIP WITH FIXES so a human can decide — the badge can't decide, so it demands a clean pass. Run `npx shipclear ship --no-fix --strict` to see exactly what the badge sees.
73
+ 3. **`shipclear ship` fixed something for you locally, and the fix isn't committed.** The gate applies safe fixes (like adding `.env` to `.gitignore`) and then reports you clean. GitHub gets the unfixed version, so it reports the finding. `git status` will show the changed files — commit them.
74
+
75
+ ## "Can I just put the green badge in my README myself?"
76
+
77
+ You can, but it would be a lie the first time you push something unchecked, and anyone reading your repo can click the badge and see there's no run behind it. That's exactly why `shipclear badge` installs a real check instead of handing you a green image.
78
+
63
79
  ---
64
80
 
81
+ ## "Is `--probe` safe to run? Will it break my live site?"
82
+
83
+ It makes ordinary read requests — the same kind your browser makes when it loads a page. It never
84
+ sends anything, never logs in, never tries to get past anything, and only touches the address you
85
+ type plus paths under it. It's about 19 requests in total, which is less traffic than one person
86
+ visiting your site. Nothing is uploaded anywhere: ShipClear has no server to upload to.
87
+
88
+ Only point it at a site you own. Probing someone else's site isn't dangerous to them, but it isn't
89
+ yours to check.
90
+
91
+ ## "`--probe` says it wasn't run"
92
+
93
+ Two reasons. Either you answered no to the confirmation, or there was no terminal to ask in — which
94
+ happens when it runs inside a script, a CI job, or a tool that captures the output. Add `--yes` to
95
+ say "don't ask, I already decided" in those places.
96
+
65
97
  ## Mini-glossary
66
98
 
67
99
  - **Terminal** — the text window where you type commands instead of clicking. (In Bolt/Lovable/Replit, look for a "Terminal" or "Console" tab; on Mac, the Terminal app; on Windows, PowerShell.)
@@ -73,3 +105,8 @@ Expected. Deleting the fake account also removed what your login checked against
73
105
  - **`.env.example`** — a safe-to-share template: the same setting *names* as `.env`, but with the values blank.
74
106
  - **rotate a key** — get a brand-new key from whoever issued it (e.g. log into OpenAI and generate a new one) and stop using the old one. This is what actually protects you after a leak.
75
107
  - **force-push** — overwrite the copy of history on GitHub with your cleaned-up local version. Fine for a repo only you work on.
108
+ - **default password** — the password a piece of software ships with, written in its own documentation (`postgres`, `minioadmin`, `admin`). Everyone knows them, including the programs that scan the internet looking for them, which is why one left in place is treated as serious as a leaked key.
109
+ - **environment variable** — a setting your app reads from outside its own code, so the value can differ between your laptop and the live site. `.env` is where you keep yours.
110
+ - **bucket** — a folder in a storage service (S3, MinIO, Cloud Storage) where your app keeps uploaded files. "Listing" a bucket means asking it for an index of everything inside, which is why read-only-but-listable is still bad news.
111
+ - **proxy / reverse proxy** — the program that takes requests from the internet and decides which part of your app answers them (Caddy, nginx, Traefik). A route that is too broad can hand a visitor a service you never meant to publish.
112
+ - **security headers** — short instructions your server sends with each page telling the browser what the page is allowed to do (`Content-Security-Policy` and friends). They only help on the responses that are actual pages.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "shipclear",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "The last command before you launch. A free, local, cross-agent security gate for AI-built apps: prevents leaked secrets while you build, blocks them at commit time, and gives you a plain-English safe-to-ship verdict.",
5
5
  "keywords": [
6
6
  "security",