@brokkai/slopcop 0.0.5 → 0.0.7

package/README.md

@@ -138,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
@@ -163,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`) |
@@ -178,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.
@@ -191,9 +239,13 @@ 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
 
@@ -215,16 +267,16 @@ check outside your workspace.
 ### Output and exit codes
 
 The service answers structured data; the CLI renders it. `human` prints one
-block per new finding, with an `ID:` line when the service names one, 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 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` or `unchanged` and the finding id in `properties["slopcop.findingId"]`. `--format` and `--show-existing` only change the rendering, never
-the request, so the service answers the same check whichever is used.
+`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 |
 | --- | --- |
@@ -232,13 +284,20 @@ 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 |
 
-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
-the change` line (`inconclusiveElsewhere` in `json`, a `note` notification in
-`sarif`) and never changes the exit code. A check that timed out counts
-wherever it is. The service can place an inconclusive check only once Bifrost
-reports which files it concerns; until then every one counts as in the change.
+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, one that ran but could not prove there is nothing
+more to find, never changes the exit code and is not named in any format.
+Complete proof is rare in static analysis, typically at a library boundary,
+so this is the norm rather than a gap. `summary.inconclusive` counts them in
+`json`, as does `slopcop.inconclusive` in `sarif`. A check that timed out or
+that Bifrost judged unreliable is incomplete and counts wherever it is.
 
 The service applies `--fail-on` and sets the status; the exit code follows it.
 The CLI always sends `--fail-on`, defaulting to `finding`: a check fails only
@@ -260,9 +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.
+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
 
@@ -293,11 +355,27 @@ 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.5",
+  "version": "0.0.7",
   "description": "Static analysis for coding agents and CI: check a change through the hosted SlopCop API",
   "keywords": [
     "agents",