@brokkai/slopcop 0.0.8 → 0.0.10

package/README.md

@@ -101,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
@@ -229,42 +248,65 @@ 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 `2` with the service's remedy. 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.
+[y/N]`, and on a yes sends the check again and says `added owner/name to
+"Workspace"` on stderr. With no terminal, as for an agent or CI (a pipe or the
+null device is not one), nothing is asked: the check exits `4` with the
+service's remedy, a line naming the command that confirms it, and, in `json`,
+a `failed` report naming the code. A no at the terminal ends the same way.
+Once the person has approved it, `check --add-repository --workspace
+<name|id>` confirms without a terminal; the flag needs `--workspace` (the
+flag itself, not `$SLOPCOP_WORKSPACE`), so an approval given for one
+workspace cannot add the repository to the one the login happens to point at.
+The flag changes nothing for a repository already in that workspace. 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.
 
 ## Check
 
 ```console
 slopcop                          # check the change in the current checkout
 slopcop check --format json      # same, machine-readable
-slopcop --root ../repo --base HEAD~1
+slopcop --root ../repo --base origin/main
 ```
 
 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
-base commit in its clone; a missing one comes back as the service's
-`base_not_found` message and remedy.
+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. `--base REV` names the branch the
+change started from and, like `git diff REV...HEAD`, uses the merge base of
+`REV` and `HEAD`, so commits that landed on `REV` after the branch point are not
+sent as reverse edits. `--base-exact REV` diffs against `REV` itself. 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. The CLI then asks origin for its default
+branch (`git ls-remote`, no prompt, 10 second limit) and adds a line when the
+clone explains the failure: origin's default branch was renamed and
+`origin/HEAD` still names the old one, or the base is not on origin's default
+branch.
 
 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:
 
 | Flag | Meaning |
 | --- | --- |
 | `--root PATH` | repository to check (default `.`) |
-| `--base REV` | base commit or revision for the change |
+| `--base REV` | branch or revision the change started from; the base is its merge base with `HEAD` |
+| `--base-exact REV` | exact base commit or revision, without a merge base |
 | `--format human\|json\|sarif` | report format (default `human`) |
 | `--fail-on never\|finding\|note\|warning\|error` | exit-1 threshold for new findings (default `finding`) |
 | `--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 |
+| `--add-repository` | add the repository to the workspace `--workspace` names, which then pays for it, without asking at a terminal; for after the user approved it |
 | `--verbose` | print the resolved request to stderr |
 
 ### What is sent
@@ -342,8 +384,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.
@@ -354,6 +396,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
@@ -393,9 +436,23 @@ 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, and `--workspace` after
-`owner_required`. A failed request prints no
-report on stdout.
+disabled it is the one this login is bound to, `--workspace` after
+`owner_required`, and `--add-repository --workspace "Name"`, with the
+workspace the check would have added the repository to, after
+`repository_add_unconfirmed`. 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
 
@@ -412,11 +469,11 @@ The CLI calls `POST <service>/v1/check` with a bearer token:
 }
 ```
 
-`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`,
+`addRepository` is sent only after a person confirms adding the repository, at
+the terminal or with `--add-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

package/package.json

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