lockpicks 0.3.0 → 0.4.0

package/README.md

@@ -18,7 +18,7 @@ npm install -g lockpicks
 
 With it installed, `lockpick mcp config` points agents at `lockpick mcp`; without it, at `npx -y lockpicks mcp`.
 
-Use HTTPS for a remote Lockpick host. HTTP is accepted for local network and Tailscale development hosts. The CLI refuses redirects during API calls so a saved key stays on its selected host. `--host` takes precedence over `LOCKPICK_HOST`, which takes precedence over the last login. Each host has its own saved profile; `lockpick logout --host <url>` revokes and removes only that host's key. When the OS keychain is unavailable, the CLI writes the config through a private temporary file and replaces the old file only after the new one is complete. If the config is damaged, repair it before logging in again; the CLI will not silently discard saved profiles.
+Use HTTPS for a remote Lockpick host; a host without a scheme (`lockpick.app`) means HTTPS, and a local one (`studio-mac:3000`) means HTTP. HTTP is accepted for local network and Tailscale development hosts. The CLI never follows redirects during API calls, so a saved key stays on its selected host: when a host only moves to its canonical address (`lockpick.app` to `www.lockpick.app`), `login`, which sends no key, signs in there and saves that address, and every other command names the address to use. `--host` takes precedence over `LOCKPICK_HOST`, which takes precedence over the last login. Each host has its own saved profile; `lockpick logout --host <url>` revokes and removes only that host's key. When the OS keychain is unavailable, the CLI writes the config through a private temporary file and replaces the old file only after the new one is complete. If the config is damaged, repair it before logging in again; the CLI will not silently discard saved profiles.
 
 ## Commands
 
@@ -51,10 +51,16 @@ Use HTTPS for a remote Lockpick host. HTTP is accepted for local network and Tai
 | `lockpick compare <runId>`             | What a Pulse recheck changed against its baseline                                                                                                                                                                   |
 | `lockpick open <id>`                   | Opens a run or project in the browser                                                                                                                                                                               |
 | `lockpick skills`                      | Adds the Lockpick skills to your coding agent (`npx skills add`)                                                                                                                                                    |
+| `lockpick docs [words]`                | Searches the Lockpick docs from the terminal, or lists the CLI guides (`--open` opens the best match)                                                                                                               |
+| `lockpick ci init <site>`              | Writes `.github/workflows/lockpick.yml`: a Pulse on each published release and on demand that fails on `--fail-on` findings (default `high`); `--dry-run` prints it, `--action` uses the Lockpick GitHub Action     |
 
 Every command takes `--host` and `--json`. With `--json`, errors are printed to stderr as `{ "error": "…", "code": "…" }`, plus `nextStep`, `retryAfterSeconds`, `webUrl` and `requestId` for the agent commands.
 
-Exit codes: `0` success; `1` network or other error; `2` authentication; `3` a watched result failed, was cancelled or did not finish before the wait limit; `4` permission or allowance; `5` invalid input; `6` rate limit; `7` provider capacity or service failure. JSON results go to stdout, with errors and human progress on stderr. `--json` never adds terminal colors.
+Exit codes: `0` success; `1` network, not found or other error; `2` authentication; `3` a watched result failed, was cancelled or did not finish before the wait limit; `4` permission (key scope or project role) or allowance; `5` invalid input; `6` rate limit; `7` provider capacity or service failure; `8` open findings reached `--fail-on`. JSON results go to stdout, with errors and human progress on stderr. Text errors end with a `Help:` link to the docs page on your Lockpick host that explains them (`docsUrl` in JSON errors). `--json` never adds terminal colors; `NO_COLOR` turns them off and `FORCE_COLOR=1` turns them on for a CI log. While a scan runs, a terminal shows one live progress line; a pipe or CI (`CI` set) gets one line per change.
+
+`--fail-on critical|high|medium|low` on `pulse`, `recheck`, `watch`, `deep start` and `findings` exits `8` when open findings are that severe or worse, for CI. `lockpick ci init <site>` writes a GitHub Actions workflow that runs `npx -y lockpicks@<this version> pulse <site> --fail-on high` with the key from the `LOCKPICK_KEY` repository secret; it runs on published releases and by hand only, because each run uses a Pulse.
+
+Text from scanned sites and saved briefs can carry terminal escape sequences. The CLI neutralizes every control character in API responses before printing them (an escape shows as `␛`), and keeps only its own colours on the way out, so a scanned page cannot clear your screen, write your clipboard or hide a link. Ids are checked before they go into a URL, and the key is never printed, even when a server error repeats it.
 
 `watch`, `pulse`, full `recheck` and `deep start` wait for at most 600 seconds by default. Use `--timeout <seconds>` (up to 3600) and `--interval <seconds>` (2–30), or `--no-wait` for a started scan id immediately. If a wait ends while the scan is running, the CLI prints its id and exits `3`; resume with `lockpick watch <scanId>`. Waiting never sends the start request again. A quick check waits up to 90 seconds and a DNS recheck up to 60 seconds by default.
 
@@ -83,5 +89,8 @@ Agents set up for CLI 0.2.0 keep working: `lockpick_list_projects`, `lockpick_pr
 | `LOCKPICK_KEY`        | A key to use without logging in (CI)                       |
 | `LOCKPICK_CONFIG_DIR` | Where the config file lives (default `~/.config/lockpick`) |
 | `LOCKPICK_KEYCHAIN=0` | Skip the OS keychain and use the config file               |
+| `NO_COLOR`            | Turn colour off                                            |
+| `FORCE_COLOR=1`       | Colour even when output is not a terminal (CI logs)        |
+| `LOCKPICK_ACTION_REF` | The GitHub Action `ci init --action` refers to             |
 
 Requires Node.js 20.9 or later.