@brokkai/slopcop 0.0.4 → 0.0.6

package/README.md

@@ -110,9 +110,12 @@ harness is present, and names what it did:
 | `~/.claude/skills/slopcop/` | Claude Code, opencode |
 | `$CODEX_HOME/skills/slopcop/`, or `~/.codex/skills/slopcop/` | Codex home |
 
-A skill that is already there is left alone, so local edits survive and running
-init again is safe. `slopcop init --no-skill` skips the install and any update
-of it.
+A skill that is already there is left alone by init, so running it again is
+safe. `slopcop login` and every check also install the skill in those
+directories, rewriting one that differs from the skill bundled into the binary,
+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.
 
 ## Sign in
 
@@ -135,6 +138,35 @@ Precedence:
 | Service URL | `--service`, `$SLOPCOP_SERVICE`, stored by `slopcop login`, `https://slopcop.com` |
 | Token | `$SLOPCOP_TOKEN`, stored value |
 
+## Workspace and repositories
+
+A login runs its checks and ignores in, and bills, one workspace: the one
+active in the browser when the login was approved.
+
+```console
+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 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
+```
+
+`whoami`, `workspace list` and `repo list` take `--format human|json`, as do
+`workspace use` and `repo enable|disable` for their answer. Every active
+repository after a workspace's first costs credits every 30 days; a disabled
+one is not checked or charged and keeps its reports, findings and settings.
+`repo enable` and `repo disable` ask you to type the repository's `owner/name`
+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.
+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
+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
@@ -160,7 +192,6 @@ Flags:
 | `--base REV` | base commit or revision for the change |
 | `--format human\|json\|sarif` | report format (default `human`) |
 | `--fail-on never\|finding\|note\|warning\|error` | exit-1 threshold for new findings (default `finding`) |
-| `--show-existing` | also list the findings that were already in the code |
 | `--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`) |
@@ -175,6 +206,26 @@ changes, and binary content. Git-ignored files stay out, except selected
 `.slopcop/policies` rules, which must travel because the service evaluates them
 from the patched checkout.
 
+A check run by a Claude Code or Codex agent also sends which models wrote the
+change, so the service can tie each finding to the model that wrote its file.
+The CLI finds the agent's session from its environment and reads that
+session's own record:
+
+- **Claude Code:** `CLAUDE_CODE_SESSION_ID` names the transcript under
+  `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`), subagents included.
+  Each successful Write, Edit, MultiEdit or NotebookEdit gives a model, an
+  effort and a file.
+- **Codex:** `CODEX_THREAD_ID` names the rollout under `~/.codex/sessions` (or
+  `$CODEX_HOME/sessions`). Each completed file change gives the files, and its
+  turn gives the model and effort. A move counts as writing its destination.
+
+It reads only those fields, never the conversation, tool input or file
+contents. What it sends is the harness, its version, the session id as an
+opaque identifier, and each model and effort with the repository-relative
+files it wrote. A check run outside an agent session sends none of this. It
+is analytics only, asserted by the client, and never decides a check.
+`--verbose` prints it.
+
 The service owns the limits on what a check accepts. When a change is too
 large or touches too many files, the service's `payload_too_large` response is
 printed verbatim; the CLI does not impose its own limits.
@@ -188,22 +239,44 @@ Every check also runs the hosted catalog. Rules under
 A check fails only on findings the change introduced or touched: the service
 marks a finding new when it is in a file the change writes and its lines meet a
 line the change added, or the line beside one it removed. Findings that were
-already in the code are counted, never fail the check, and are listed only with
-`--show-existing`. A change that introduces nothing exits `0`, however many
-findings the repository already holds.
+already in the code are counted (`summary.existingFindings`, and `N already in
+the code` in the human summary), never fail the check, and are not listed. A
+change that introduces nothing exits `0`, however many findings the repository
+already holds. `--show-existing` is deprecated and hidden: the service no longer
+sends those findings, so against it the flag lists nothing (a service from
+before that still gets them listed), and it stays so that scripts passing it
+keep running.
+
+### Ignore a false positive
+
+Each finding a check reports carries an `id`. When a finding is a false
+positive, ignore it:
+
+```console
+slopcop ignore 0f8fad5b-d9cb-469f-a165-70867728950e
+```
+
+That finding is not reported again for this repository. Ignoring covers that
+one finding, its rule plus its place in the code, in its repository for your
+workspace; the rule keeps reporting everything else. Ignoring a finding twice
+is fine. `ignore` uses the same login and service URL as a check, exits `0`
+with a one-line confirmation, and otherwise exits `2` with the service's
+message and remedy; `finding_not_found` means the id is unknown or comes from a
+check outside your workspace.
 
 ### Output and exit codes
 
 The service answers structured data; the CLI renders it. `human` prints one
-block per new finding, then the pre-existing ones with `--show-existing`, a
-summary line such as `1 new finding across 1 file(s); 72 already in the code
-(--show-existing lists them) | Analysis complete`, and any omitted or
+block per new finding, with an `ID:` line when the service names one, then a
+summary line such as `1 new finding across 1 file(s); 72 already in the code |
+Analysis complete`, and any omitted or
 incomplete checks. `json` prints `status`, `baseCommit`, `summary`
 (`newFindings` and `existingFindings` count the split), `findings` (each with
-`new`), `incomplete`, and `failure` when the analysis did not complete. `sarif`
-prints a SARIF 2.1.0 log whose results carry `baselineState` `new` or
-`unchanged`. `--format` and `--show-existing` only change the rendering, never
-the request, so the service answers the same check whichever is used.
+`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 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.
 
 | Exit | Meaning |
 | --- | --- |
@@ -211,6 +284,13 @@ the request, so the service answers the same check 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 |
+| `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
+service can never pass a check by accident, and stderr names the status. An
+interrupted check prints no report. Interrupted before it was sent, nothing
+reached the service; after, a service that received it keeps running it, and
+running the same check again picks up its result.
 
 An inconclusive check fails the check only when it concerns a file the
 change writes. One about other files is listed on an `Inconclusive outside
@@ -239,13 +319,12 @@ again picks up the same analysis.
 Service failures print the closed contract exactly: message, remedy, and any
 install URL. The codes, messages, and remedies are defined by the service in
 `server/src/check.rs` of `BrokkAi/bifrost-service`; the CLI does not
-rewrite them. The remedies name no client, so when one says to sign in the CLI
-adds the `slopcop login` command after it. A failed request prints no report
-on stdout.
-
-While SlopCop is still indexing the repository, the service answers
-`indexing_in_progress` at once instead of running the check. The CLI prints it
-and exits `2` without waiting or retrying.
+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.
 
 ## API
 
@@ -268,11 +347,35 @@ were marked `new`, the CLI treats every finding as new, as that service gated
 on all of them. Non-2xx responses carry `code`, `message`,
 `remedy`, `retryable`, and an optional `installUrl`.
 
+Each finding in the response carries an `id`; a service from before findings
+could be ignored omits it.
+
+`slopcop ignore <id>` calls `POST <service>/v1/ignore` with the same bearer
+token and `{"findingId": "<id>"}`, and gets back
+`{"findingId": "<id>", "status": "ignored"}`. Failures use the same closed
+contract, including `finding_not_found`.
+
+The account commands use the same bearer token. `GET <service>/v1/whoami`
+answers `account`, `workspace` (`id`, `name`, `kind`, `role`, `current`),
+`plan` (`pro` or `free`) and `workspaces`. `POST <service>/v1/workspace` with
+`{"workspaceId"}` rebinds the login. `GET <service>/v1/repositories` answers
+`repositories` (`id`, `provider`, `fullName`, `enabled`, `active`) with
+`activeRepositoryLimit`, `activeRepositories` and `canManageRepositories`, and
+`POST <service>/v1/repositories/state` with `{"repositoryId", "enabled"}`
+answers `{repositoryId, fullName, enabled, active}`. Their failure codes add
+`account_required`, `workspace_not_found`, `workspace_repository_not_found`,
+`owner_required` and `browser_required` (a private Bitbucket or GitLab
+repository, which only the web app can change) to the check's.
+
 `slopcop login` uses the device flow: `POST /api/device` returns a
 `deviceCode`, `userCode`, `verificationUri`, `expiresIn`, and `interval`, and
 `POST /api/token` returns `202` while pending or `200` with a `token` once
-approved. The polling codes are `authorization_pending`, `slow_down`,
-`expired_token`, and `access_denied`.
+approved. The failure codes are `slow_down`, which raises the polling interval,
+`expired_token`, `access_denied`, and `device_flow_disabled`. A failure the
+service marks `retryable`, such as `rate_limited` or `service_unavailable`,
+keeps the code valid, and so do a dropped connection and a proxy's `429`,
+`502`, `503` or `504` without a code: login waits the `Retry-After`, or the
+interval if that is longer, and polls again until the code expires.
 
 ## Development
 

package/package.json

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