@brokkai/slopcop 0.0.7 → 0.0.9

package/README.md

@@ -25,16 +25,17 @@ prompts, one request, and the analyzer's exit contract.
 
 ## Install
 
-npm, PyPI, the release archive, and the PowerShell installer all install the
-same release binary for macOS, Linux, and Windows on x64 and arm64, so
-`slopcop version` reports which release it came from. The Go toolchain can
-build that binary from source instead.
+npm, PyPI, the release archive, and the shell and PowerShell installers all
+install the same release binary for macOS, Linux, and Windows on x64 and
+arm64, so `slopcop version` reports which release it came from. The Go
+toolchain can build that binary from source instead.
 
 | Channel | Platforms | Needs |
 | --- | --- | --- |
 | [npm](#npm) | macOS, Linux, Windows | Node 22 or newer |
 | [PyPI](#pypi) | macOS, Linux, Windows | Python 3.9 or newer |
 | [Release archive](#release-archive) | macOS, Linux, Windows | nothing |
+| [Shell installer](#shell-installer) | macOS, Linux | curl |
 | [PowerShell installer](#powershell-installer) | Windows | PowerShell |
 | [Go](#go) | built from source | Go 1.25 or newer |
 
@@ -78,6 +79,17 @@ tar -xzf "slopcop_v${ver}_${os}_${arch}.tar.gz" slopcop
 sudo install -m 755 slopcop /usr/local/bin/slopcop
 ```
 
+### Shell installer
+
+```console
+curl -fsSL https://raw.githubusercontent.com/BrokkAi/slopcop/master/install.sh | sh
+```
+
+It takes the latest release, verifies the archive against `checksums.txt`,
+installs `slopcop` to `$HOME/.local/bin`, and adds that directory to the
+shell profile. `SLOPCOP_VERSION`, `SLOPCOP_INSTALL_DIR`, and
+`SLOPCOP_NO_MODIFY_PATH` override its defaults.
+
 ### PowerShell installer
 
 ```powershell
@@ -89,6 +101,25 @@ installs `slopcop.exe` to `%LOCALAPPDATA%\Programs\slopcop`, and adds that
 directory to the user `Path`. `SLOPCOP_VERSION`, `SLOPCOP_INSTALL_DIR`, and
 `SLOPCOP_NO_MODIFY_PATH` override its defaults.
 
+### Upgrade notice
+
+Every response from the service names its newest release in the
+`SlopCop-Latest-Version` header. When that is newer than the running build,
+the CLI prints one line on stderr, never stdout, so `--format json` and
+`sarif` stay clean:
+
+```text
+slopcop v0.0.9 is available (you have v0.0.7). Upgrade: npm install --global @brokkai/slopcop@latest
+```
+
+The command follows the channel the binary was installed through (npm, npx,
+pip, pipx, or uv), judged by where it lives, and links back here otherwise.
+The notice prints at most once a day; the time of the last one is kept in
+`slopcop/update-notice` next to the config. `dev` builds, `Stop` hook runs, and
+runs with `$SLOPCOP_NO_UPDATE_NOTICE` set to any non-empty value never print
+it. A service that no longer accepts a version answers `client_outdated`
+(HTTP 426), which exits `2`.
+
 ### Go
 
 ```console
@@ -101,8 +132,9 @@ its version; in a clone, `make install` stamps the version from `git describe`.
 ## Enable it in an agent
 
 The binary carries the agent skill that teaches a coding agent how to run
-slopcop. `slopcop init` installs it into each well-known skills directory whose
-harness is present, and names what it did:
+slopcop, plus an automatic check hook for Claude Code and Codex. `slopcop init`
+installs the skill into each well-known skills directory whose harness is
+present, and names what it did:
 
 | Location | Harness |
 | --- | --- |
@@ -117,6 +149,47 @@ so an agent follows the instructions of the slopcop version it runs; local
 edits to an installed skill do not survive them. `slopcop init --no-skill`
 skips the install and any update of it.
 
+Init also adds a `Stop` hook for each harness installed here, and leaves
+everything else in the file as it was:
+
+| File | Harness |
+| --- | --- |
+| `settings.json` under `CLAUDE_CONFIG_DIR`, or `~/.claude` | Claude Code |
+| `hooks.json` under `CODEX_HOME`, or `~/.codex` | Codex |
+
+Codex runs a new or changed hook only once you trust it: open Codex and review
+it with `/hooks`. Init never writes that trust itself, and reminds you each
+time it runs, since Codex says nothing of a hook it skips. The hook stays the
+same from one release to the next, so an update does not ask for it again.
+
+When the agent stops, the hook checks the working tree through the same
+hosted API, but only when all of these hold:
+
+- the session wrote files in the repository with its edit tools (a Codex
+  session's subagents included);
+- slopcop is signed in, and the workspace a check would use
+  (`$SLOPCOP_WORKSPACE`, or the login's) has the repository active
+  (`slopcop repo list`), so nothing is sent from other repositories;
+- the tree differs from the last check in the session, including a check the
+  agent ran by hand.
+
+New findings in files the session wrote are handed to the agent to fix, once
+for a given tree and at most twice in a row; then the agent is let go and you
+are told what remains. A finding ignored with `slopcop ignore` is not handed
+back. New findings in other files on the branch are only mentioned. The hook
+never keeps the agent going on its own failures: a refusal the service calls
+final, such as an expired login, is reported once and the hook stays quiet for
+the rest of the session, until a check by hand completes; a brief outage is
+only reported. The hook runs as `slopcop hook claude || true` (and
+`slopcop hook codex || true`, or `|| exit /b 0` under Windows' `cmd`), so even
+a `slopcop` that cannot run it, such as an older one first on `PATH`, lets the
+agent stop; init warns when that is the case, because no check would run.
+
+Use `slopcop init --no-hooks` to install only the skill, or
+`slopcop init --remove-hooks` to remove SlopCop's hooks and nothing else.
+Ordinary checks do not reinstall a removed hook. The skill remains the way to
+check from other harnesses.
+
 ## Sign in
 
 ```console
@@ -137,6 +210,7 @@ Precedence:
 | --- | --- |
 | Service URL | `--service`, `$SLOPCOP_SERVICE`, stored by `slopcop login`, `https://slopcop.com` |
 | Token | `$SLOPCOP_TOKEN`, stored value |
+| Workspace (`check`, `ignore`, `repo`) | `-w`/`--workspace`, `$SLOPCOP_WORKSPACE`, the one the login is bound to |
 
 ## Workspace and repositories
 
@@ -147,6 +221,7 @@ active in the browser when the login was approved.
 slopcop whoami                     # account, this login's workspace, its plan, the service URL
 slopcop workspace list             # the account's workspaces; * marks this login's
 slopcop workspace use "Acme team"  # move this login (not the browser) to another, by name or id
+slopcop check -w "Acme team"       # check in, and bill, another workspace this once
 slopcop repo list                  # the workspace's repositories: active, disabled, or over the limit
 slopcop repo disable acme/widgets  # stop checking and charging for one (owner only)
 slopcop repo enable acme/widgets   # turn it back on, within the workspace's active limit
@@ -160,9 +235,23 @@ one is not checked or charged and keeps its reports, findings and settings.
 and refuse when stdin is not a terminal: an agent or CI job runs with your
 login, and the service cannot tell it from you, so changing what the workspace
 pays stays a step you take yourself.
+`workspace use` moves every agent and script using this login, not only the
+one that runs it, so it asks `[y/N]` and refuses when stdin is not a terminal.
+To check in another workspace without moving anyone, `check`, `ignore` and
+`repo` take `-w`/`--workspace <name|id>` (or `$SLOPCOP_WORKSPACE`) for that one
+command; the login stays where it was. Give agents that share a login their
+own `--workspace` instead of switching it.
+
 Names match without regard to case; when two workspaces share a name, or two
 providers a repository name, pass the id the listing prints. There is no `repo
-add`: a first check adds a repository. Deleting repositories, archiving
+add`: a first check adds a repository. When the workspace would then pay for
+it (it already has an active repository and is charged), the service refuses
+the check with `repository_add_unconfirmed` until a person confirms: at a
+terminal `check` prints what it costs, asks `Add owner/name to "Workspace"?
+[y/N]`, and on a yes sends the check again; with no terminal, as for an agent
+or CI, it exits `4` with the service's remedy and, in `json`, a `failed`
+report naming the code. A workspace's first repository
+is added without asking. Deleting repositories, archiving
 workspaces, members, credits and repository settings stay in the web app. The
 commands exit `0` on success and `2` with the service's message and remedy
 otherwise, as `ignore` does.
@@ -176,13 +265,19 @@ slopcop --root ../repo --base HEAD~1
 ```
 
 The base commit defaults to the merge base with the branch upstream, then the
-merge base with `origin/HEAD`, then `HEAD`. The service must already have the
+merge base with `origin/HEAD`, then `HEAD` when neither is known. When the
+upstream merge base yields an empty patch, as on a branch whose commits are all
+pushed, the CLI uses the merge base with `origin/HEAD` instead, so a check
+right after a push still covers the branch. The service must already have the
 base commit in its clone; a missing one comes back as the service's
 `base_not_found` message and remedy.
 
 Every run sends one check request, even when the working tree matches the base
 and the patch is empty. A clean result or a failure always comes from the
-service.
+service. A report for an empty patch comes with a note on stderr that suggests
+`--base`, and `json` adds `"emptyChange": true` (`sarif`:
+`properties["slopcop.emptyChange"]`): a clean result then means nothing
+changed was checked.
 
 Flags:
 
@@ -195,6 +290,7 @@ Flags:
 | `--policy PATH` | repository-relative `.rqlp` file to evaluate (repeatable) |
 | `--no-policy-discovery` | skip `.slopcop/policies` rules |
 | `--timeout DURATION` | how long to wait for the result (default `10m`) |
+| `-w`, `--workspace NAME\|ID` | check in, and bill, this workspace of the account instead of the login's |
 | `--verbose` | print the resolved request to stderr |
 
 ### What is sent
@@ -272,8 +368,8 @@ summary line such as `1 new finding across 1 file(s); 72 already in the code |
 Analysis complete`, and any omitted new findings or
 incomplete checks. `json` prints `status`, `baseCommit`, `summary`
 (`newFindings` and `existingFindings` count the split), `findings` (each with
-`new` and its `id`), `incomplete`, and `failure` when the analysis did not
-complete. `sarif` prints a SARIF 2.1.0 log whose results carry `baselineState`
+`new` and its `id`), `incomplete`, `failure` when the analysis did not
+complete, and `emptyChange` when the patch was empty. `sarif` prints a SARIF 2.1.0 log whose results carry `baselineState`
 `new` and the finding id in `properties["slopcop.findingId"]`. `--format` only
 changes the rendering, never the request, so the service answers the same check
 whichever is used.
@@ -284,6 +380,7 @@ whichever is used.
 | `1` | A new finding crossed `--fail-on` |
 | `2` | No new finding crossed `--fail-on`, but a check was incomplete; or the CLI or service failed |
 | `3` | The check was still running when `--timeout` ran out |
+| `4` | The service refused the check, and only a person can clear it |
 | `130`, `143` | Interrupted before the check answered: `130` for Ctrl-C, `143` for SIGTERM |
 
 Only `clean` exits `0`: a status this CLI does not know exits `2`, so a newer
@@ -323,8 +420,21 @@ rewrite them. The remedies name no client, so the CLI adds its own command
 after some: `slopcop login` when the remedy is to sign in, the listing to
 choose from after `workspace_not_found` or `workspace_repository_not_found`,
 and `slopcop whoami` after `repository_disabled`, since the workspace that
-disabled it is the one this login is bound to. A failed request prints no
-report on stdout.
+disabled it is the one this login is bound to, and `--workspace` after
+`owner_required`. A failed check exits `4` when only a person can clear the
+refusal (`auth_required`, `auth_expired`, `account_required`,
+`repo_not_indexed`, `app_not_installed`, `app_no_repo_access`,
+`gitlab_not_connected`, `no_access`, `insufficient_credits`,
+`repository_disabled`, `repository_add_unconfirmed`,
+`workspace_repository_limit_reached`, `active_repository_limit_reached`,
+`owner_required`, and `browser_required`), so a script can stop instead of
+retrying, and `2` otherwise. Stderr starts with the code, as in `slopcop:
+repository_add_unconfirmed: …`. `human` prints nothing on stdout; `json`
+prints `{"status": "failed", "code": …, "message": …, "remedy": …,
+"retryable": …}`, plus `installUrl` or `topUpUrl` when the service sent one;
+`sarif` prints a run with `slopcop.status` `failed`, whose invocation is
+unsuccessful and carries an `error` notification whose descriptor id is the
+code.
 
 ## API
 
@@ -336,11 +446,16 @@ The CLI calls `POST <service>/v1/check` with a bearer token:
   "baseCommit": "0123456789abcdef0123456789abcdef01234567",
   "change": "<base64 git patch>",
   "selection": {"files": [".slopcop/policies/rule.rqlp"]},
-  "failOn": "finding"
+  "failOn": "finding",
+  "addRepository": true
 }
 ```
 
-The service rejects any other field. The response carries `status`,
+`addRepository` is sent only after a person confirms adding the repository. The
+service rejects any other field. With `--workspace`, every request, the
+check's, the ignore's and the account routes', carries the workspace's id in
+the `SlopCop-Workspace` header; a name is first looked up with
+`GET <service>/v1/whoami`. The response carries `status`,
 `baseCommit`, `applied`, `summary`, `findings`, `incomplete`, and `failure`
 when the analysis did not complete. Against a service from before findings
 were marked `new`, the CLI treats every finding as new, as that service gated
@@ -414,6 +529,7 @@ Layout:
 | `internal/service` | `/v1/check` client and the wire contract |
 | `internal/report` | human, JSON, and SARIF rendering from the structured response |
 | `internal/config` | stored service URL and token |
+| `internal/hooks` | Claude Code and Codex hook installation and removal |
 | `npm` | launcher, packer, and tests of the `@brokkai/slopcop` package |
 | `packaging/pypi` | wheel packer and launcher of the `brokk-slopcop` package |
 | `skills/slopcop` | the agent skill the binary embeds and installs |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brokkai/slopcop",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Static analysis for coding agents and CI: check a change through the hosted SlopCop API",
   "keywords": [
     "agents",