@patchlight/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patchlight
+
+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,150 @@
+# @patchlight/cli
+
+[Patchlight](https://patchlight.dev) in your terminal: AI security scanning of the
+code on your disk **right now** — uncommitted work included — with findings
+streaming in one at a time and keyboard triage when they land.
+
+Node.js 18.17+.
+
+```bash
+npm install -g @patchlight/cli
+patchlight login
+cd your-repo && patchlight scan --diff
+```
+
+## Why this and not `@patchlight/sdk`
+
+They are the same product with different jobs.
+
+|  | `@patchlight/sdk` | `@patchlight/cli` |
+|---|---|---|
+| For | CI pipelines | developers at a terminal |
+| Runtime dependencies | **zero** | ink, react, highlight.js |
+| Auth | `PATCHLIGHT_API_KEY` | `patchlight login` (browser) |
+| Output | plain text / `--json` | live TUI, then triage |
+
+Everything non-interactive — `review`, `status`, `findings`, `repos`,
+`balance`, `--fail-on` — behaves identically here, because this package
+delegates those commands to the SDK's own implementation rather than
+reimplementing them. Installing this does not change what your pipeline does.
+
+## Sign in
+
+```bash
+patchlight login
+```
+
+Opens a browser, shows you a short code to confirm, and stores a token in
+`~/.patchlight/credentials.json` (mode `0600`). No secret passes through your
+shell history, and the machine appears in the dashboard under **API Keys** where
+you can revoke it.
+
+Headless box or over SSH? The code and URL are always printed — open them
+anywhere you are signed in.
+
+`PATCHLIGHT_API_KEY` still wins when it is set, so a CI job on a machine somebody
+once logged into uses the credential its pipeline configured.
+
+## Scan
+
+```bash
+patchlight scan
+```
+
+Asks what to scan, then runs it:
+
+- **Changed files** — what this branch touched, uncommitted work included. Seconds
+  and cents. This is the one to run on every push.
+- **Whole repository** — every scannable file here. The monthly one.
+- **A directory** — one subtree.
+
+Skip the picker with flags:
+
+```bash
+patchlight scan --diff              # changed files
+patchlight scan --diff --base main  # against an explicit base
+patchlight scan --path src/api      # one subtree
+patchlight scan --no-neighbours     # with --diff, changed files only
+```
+
+### What happens
+
+1. **Local walk** — instant, no network. Skips `node_modules`, build output,
+   lockfiles and binaries.
+2. **Preflight** — checks your balance and the size caps before a single byte of
+   code is uploaded.
+3. **Upload** — a bounded snapshot of the working tree.
+4. **Triage** — how much of it is worth reading, summarised by weakness family.
+5. **Findings** — streamed as the model completes them, not batched to the end.
+
+All of it runs fullscreen, and the terminal you started in is left exactly as it
+was when you quit — with a short summary of what was found printed under your
+prompt.
+
+### Triage
+
+When the scan ends you are already in it — no second command, nothing to copy.
+Each finding shows the offending lines **read from your disk**, syntax
+highlighted by highlight.js on a tinted block with the flagged line picked out,
+and the suggested fix underneath — code highlighted, advice as plain text.
+
+```
+↑↓ move · d dismiss · r resolve · u reopen · o open in $EDITOR · q quit
+```
+
+`g` / `G` jump to the first and last finding; `PgUp` / `PgDn` move a page at a
+time. `o` hands the terminal over to `$EDITOR` at the right line and takes it
+back when you quit — `vim`, `code`, `cursor`, `subl` and `zed` all get the
+argument form they actually want.
+
+Triage writes through to the same place the dashboard reads, so a dismissal here
+is a dismissal everywhere.
+
+### `--diff` is the one to learn
+
+A full-repo scan is a monthly thing. A branch scan is a per-push thing: it reads
+only what you changed (plus same-directory siblings, so cross-file flows are still
+visible), takes seconds, and costs cents. It also sees code you have not committed
+— which a server that clones your repository structurally cannot.
+
+## Non-interactive use
+
+Piping or redirecting output turns off the picker, the fullscreen UI and the
+triage keys: the scan runs whole-repo and prints one plain report.
+
+```bash
+patchlight scan --diff > scan.log
+```
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | Scan completed |
+| `1` | Findings at or above `--fail-on` (the delegated CI commands) |
+| `2` | Scan failed |
+| `3` | Usage/authentication error |
+| `4` | Transient — safe to retry |
+
+## Environment
+
+| Variable | Meaning |
+|---|---|
+| `PATCHLIGHT_API_KEY` | API key; overrides a stored login |
+| `PATCHLIGHT_BASE_URL` | API origin override |
+| `PATCHLIGHT_CONFIG_DIR` | Credential directory (default `~/.patchlight`) |
+| `EDITOR` / `VISUAL` | Used by `o` in triage |
+| `NO_COLOR` / `FORCE_COLOR` | Standard colour control; honoured by the whole UI |
+
+## Privacy
+
+`patchlight scan` uploads the text files of your working tree, under the skip
+rules and size caps above, to the Patchlight API for analysis. It never uploads
+binaries, lockfiles, dependency directories, or anything outside the repository
+root. Use `--path` or `--diff` to narrow what is sent.
+
+## Documentation
+
+<https://patchlight.dev/docs/cli>
+
+## License
+
+MIT