wachiman 1.12.0 → 1.13.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +132 -101
- package/package.json +1 -1
- package/skills/wachiman-loop/SKILL.md +91 -0
- package/src/call-message.ts +26 -3
- package/src/cli.ts +81 -5
- package/src/config.ts +19 -0
- package/src/connectors/local-git.ts +101 -13
- package/src/cost.ts +20 -0
- package/src/doctor/checks.ts +1 -1
- package/src/engine.ts +532 -55
- package/src/estimate.ts +64 -0
- package/src/fidelity/block.ts +263 -0
- package/src/fidelity/claims-call.ts +172 -0
- package/src/fidelity/claims.ts +69 -0
- package/src/fidelity/digest.ts +80 -0
- package/src/fidelity/grade.ts +242 -0
- package/src/fidelity/inert.ts +25 -0
- package/src/fidelity/rules.ts +166 -0
- package/src/fidelity/sink.ts +135 -0
- package/src/fidelity/summary.ts +16 -0
- package/src/fidelity/types.ts +93 -0
- package/src/formats.ts +16 -3
- package/src/history/fingerprint.ts +1 -1
- package/src/history/store.ts +39 -1
- package/src/init/options.ts +1 -1
- package/src/local.ts +20 -2
- package/src/loop/command.ts +441 -0
- package/src/loop/state.ts +88 -0
- package/src/loop/stop-rule.ts +98 -0
- package/src/providers/claude-code.ts +47 -12
- package/src/providers/codex.ts +3 -2
- package/src/providers/index.ts +5 -2
- package/src/providers/types.ts +10 -0
- package/src/sinks/json.ts +13 -2
- package/src/skills/install.ts +4 -4
- package/src/store/command.ts +109 -0
- package/src/store/figures.ts +153 -0
- package/src/store/html.ts +138 -0
- package/src/store/index.ts +298 -0
- package/templates/caller-workflow.yml +45 -15
- package/templates/wachiman-review-caller.yml +8 -0
package/README.md
CHANGED
|
@@ -2,13 +2,127 @@
|
|
|
2
2
|
|
|
3
3
|
<img src="docs/assets/wachi.png" alt="Wachiman, a cartoon watchman with a cap and a whistle" width="96" align="right">
|
|
4
4
|
|
|
5
|
-
Advisory code reviews by an agent CLI
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
watchman who warns you and lets you decide; the Spanish word comes from the English one.
|
|
5
|
+
Advisory code reviews by an agent CLI. Review a branch on your laptop with your own Claude
|
|
6
|
+
subscription, or review every pull request inside your own GitHub Actions with your own API key or Claude subscription token.
|
|
7
|
+
One engine, same findings either way. Wachiman never approves or blocks a merge: it warns, you
|
|
8
|
+
decide.
|
|
10
9
|
|
|
11
|
-
|
|
10
|
+
**Documentation: [wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)** ·
|
|
11
|
+
[npm](https://www.npmjs.com/package/wachiman) · [Changelog](CHANGELOG.md)
|
|
12
|
+
|
|
13
|
+
Wachiman (pronounced *watchman*) is named after the Peruvian *wachimán*, the street watchman who
|
|
14
|
+
warns you and lets you decide; the Spanish word comes from the English one.
|
|
15
|
+
|
|
16
|
+
## Contents
|
|
17
|
+
|
|
18
|
+
- [Install](#install)
|
|
19
|
+
- [What you can do with it](#what-you-can-do-with-it)
|
|
20
|
+
- [Documentation](#documentation)
|
|
21
|
+
- [What a pull request review looks like](#what-a-pull-request-review-looks-like)
|
|
22
|
+
- [What it will not do](#what-it-will-not-do)
|
|
23
|
+
- [The trust decision, in brief](#the-trust-decision-in-brief)
|
|
24
|
+
- [Providers and platforms](#providers-and-platforms)
|
|
25
|
+
- [License](#license)
|
|
26
|
+
- [Commit messages](#commit-messages)
|
|
27
|
+
|
|
28
|
+
## Install
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npm i -g wachiman # or: bun add -g wachiman
|
|
32
|
+
wachiman --version
|
|
33
|
+
wachiman init # set up this project: local reviews, GitHub Actions, or both
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
You need Node 20 or later and, for local reviews, Claude Code (`claude`) signed in. The package
|
|
37
|
+
installs [Bun](https://bun.sh) for you through its `bun` dependency (a 23 to 42 MB download); with
|
|
38
|
+
`--ignore-scripts` it uses a Bun already on your `PATH`. No API key is needed for local reviews.
|
|
39
|
+
Details, the supply-chain note and installing from a clone: [docs/local-review.md](docs/local-review.md#3-install).
|
|
40
|
+
|
|
41
|
+
`wachiman init` asks which mode you want. Local setup uses your current Claude session (or a
|
|
42
|
+
separate profile), checks the machine and account, and prints the first review command. GitHub
|
|
43
|
+
setup writes the workflow file; adding the secret and pushing the workflow stay manual steps.
|
|
44
|
+
See [project setup](docs/local-review.md#configure-this-project).
|
|
45
|
+
|
|
46
|
+
## What you can do with it
|
|
47
|
+
|
|
48
|
+
| Way | Where it runs | What you need | Guide |
|
|
49
|
+
| --- | --- | --- | --- |
|
|
50
|
+
| `wachiman local` | Your laptop, on a branch or commit; nothing is posted | Claude Code signed in; no API key | [docs/local-review.md](docs/local-review.md) |
|
|
51
|
+
| Reusable GitHub Actions workflow | Your repository's runners, on each pull request | A provider API key, or a Claude subscription token, as a secret | [docs/install.md](docs/install.md) |
|
|
52
|
+
|
|
53
|
+
A GitHub App is a design only; it is not implemented.
|
|
54
|
+
|
|
55
|
+
**Review your branch before you push.** `wachiman local` reviews the committed change on your
|
|
56
|
+
branch with your own signed-in `claude` and prints the findings in the terminal, or writes them as
|
|
57
|
+
Markdown or JSON. Nothing is posted, no GitHub requests are made and no telemetry is sent; your
|
|
58
|
+
code goes to your configured Claude account. Read [docs/local-review.md](docs/local-review.md)
|
|
59
|
+
before running it on an employer's code.
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
wachiman local # current branch against origin's default branch
|
|
63
|
+
wachiman local --commit abc1234 # exactly one commit
|
|
64
|
+
wachiman local --from abc1234 # that commit and everything after it
|
|
65
|
+
wachiman local --format markdown --output review.md
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**Loop until clean.** `wachiman loop --base main` runs one review round per call and exits `0`
|
|
69
|
+
when nothing keeps it open, `10` while findings do and `11` when it stopped without converging; a
|
|
70
|
+
coding agent fixes between calls and the CLI never edits code ([docs/cli.md](docs/cli.md#loop)).
|
|
71
|
+
|
|
72
|
+
**Ask about a change.** `wachiman ask "<question>"` answers one question about the same local
|
|
73
|
+
change, grounded in its stored review when there is one; with no question it walks you through the
|
|
74
|
+
change ([docs/cli.md](docs/cli.md#ask)).
|
|
75
|
+
|
|
76
|
+
**See what local runs cost.** `wachiman status` shows the cost of the runs kept on this laptop
|
|
77
|
+
([docs/cli.md](docs/cli.md#status)); workflow runs are not in it. `wachiman dashboard` writes one
|
|
78
|
+
offline HTML page (or JSON) with the spend per day and repository, the findings by severity and
|
|
79
|
+
verdict and the loop rounds ([docs/local-dashboard.md](docs/local-dashboard.md)).
|
|
80
|
+
|
|
81
|
+
**Let your coding agent run it.** `wachiman skills install` copies the `wachiman-review` agent
|
|
82
|
+
skill, which teaches Claude Code or Codex to pick the range from what you ask, run a local review
|
|
83
|
+
and present the findings, and the `wachiman-loop` skill, which fixes between loop rounds ([docs/local-review.md](docs/local-review.md#let-your-coding-agent-run-it)).
|
|
84
|
+
|
|
85
|
+
**Review every pull request in GitHub Actions.** A short caller file in your repository pins a
|
|
86
|
+
release, passes your key and names the operator. Start with [docs/install.md](docs/install.md),
|
|
87
|
+
from an empty repository to a posted review; the caller file is
|
|
88
|
+
[`templates/wachiman-review-caller.yml`](templates/wachiman-review-caller.yml). Already copied the
|
|
89
|
+
engine into a repository? [docs/setup-copy.md](docs/setup-copy.md) explains how to move to the
|
|
90
|
+
maintained workflow.
|
|
91
|
+
|
|
92
|
+
## Documentation
|
|
93
|
+
|
|
94
|
+
The guides are published at **[wachiman.dev/docs](https://wachiman.dev/docs/what-it-is/)**. The
|
|
95
|
+
same material, in this repository:
|
|
96
|
+
|
|
97
|
+
| I want to… | Read |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| Get a first review on a repository | [docs/install.md](docs/install.md) |
|
|
100
|
+
| Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
|
|
101
|
+
| Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
|
|
102
|
+
| Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
|
103
|
+
| Ask for reviews, scope them, read the results | [docs/reviews.md](docs/reviews.md) |
|
|
104
|
+
| Understand what a run can cost and what coverage means | [docs/costs.md](docs/costs.md) |
|
|
105
|
+
| Read the PR Confidence grade in a description (trial) | [docs/pr-confidence.md](docs/pr-confidence.md) |
|
|
106
|
+
| Tell the reviewer what matters in my repository | [docs/review-policy.md](docs/review-policy.md) |
|
|
107
|
+
| Adopt a new release, or roll one back | [docs/upgrading.md](docs/upgrading.md) |
|
|
108
|
+
| Turn it off and remove it | [docs/uninstall.md](docs/uninstall.md) |
|
|
109
|
+
| Quick answers and limitations | [docs/faq.md](docs/faq.md) |
|
|
110
|
+
| Run the engine from the command line | [docs/cli.md](docs/cli.md) |
|
|
111
|
+
| Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
|
|
112
|
+
| See the spend, findings and loops of my local reviews on one page | [docs/local-dashboard.md](docs/local-dashboard.md) |
|
|
113
|
+
| See what a provider adapter runs and inherits | [docs/providers/claude-code.md](docs/providers/claude-code.md), [docs/providers/codex.md](docs/providers/codex.md) |
|
|
114
|
+
| Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
|
|
115
|
+
| Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
|
|
116
|
+
| Measure false positives | [docs/precision.md](docs/precision.md) |
|
|
117
|
+
| See how it compares with Pullfrog and CodeRabbit | [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks) |
|
|
118
|
+
| See what changed in a release | [CHANGELOG.md](CHANGELOG.md) |
|
|
119
|
+
| Cut a release (maintainers) | [docs/releasing.md](docs/releasing.md) |
|
|
120
|
+
|
|
121
|
+
Design decisions are recorded as ADRs in [docs/adr/](docs/adr/), starting with
|
|
122
|
+
[ADR 0001: distribution and trust](docs/adr/0001-distribution-and-trust.md) and
|
|
123
|
+
[ADR 0002: TypeScript on Bun, no runtime dependencies besides Bun itself](docs/adr/0002-typescript-on-bun-zero-dependencies.md).
|
|
124
|
+
|
|
125
|
+
## What a pull request review looks like
|
|
12
126
|
|
|
13
127
|
A GitHub Actions workflow that reads a pull request and posts one GitHub review on it. Each
|
|
14
128
|
finding is an inline comment on its line, labelled with a severity (when to act: Blocker, Fix,
|
|
@@ -66,107 +180,24 @@ you do:
|
|
|
66
180
|
This is not a sandbox. What is enforced, what the tests show and what is still unverified:
|
|
67
181
|
[SECURITY.md](SECURITY.md).
|
|
68
182
|
|
|
69
|
-
##
|
|
183
|
+
## Providers and platforms
|
|
70
184
|
|
|
71
|
-
The current release is
|
|
72
|
-
([docs/cli.md](docs/cli.md)) and the
|
|
73
|
-
|
|
74
|
-
|
|
185
|
+
The current release is on [npm](https://www.npmjs.com/package/wachiman) and in
|
|
186
|
+
[CHANGELOG.md](CHANGELOG.md). The command-line contract ([docs/cli.md](docs/cli.md)) and the
|
|
187
|
+
provider adapter boundary are in place. The older `CLAUDE_REVIEW_*` variables,
|
|
188
|
+
`.github/agent-review.md`, `.github/claude-review.md`, `/wachi` and the `@claude` mention are still
|
|
189
|
+
read with a notice; see [docs/upgrading.md](docs/upgrading.md).
|
|
75
190
|
|
|
76
191
|
- **Claude Code** (`claude -p`) is the provider the reusable workflow installs and runs, with
|
|
77
|
-
`ANTHROPIC_API_KEY`
|
|
192
|
+
`ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN` to run on a Claude subscription
|
|
193
|
+
([docs/providers/claude-code.md](docs/providers/claude-code.md)).
|
|
78
194
|
- **Codex CLI** (`codex exec`, for OpenAI models) is a second adapter, available only from the
|
|
79
195
|
command line. The reusable workflow does not install it or pass an OpenAI key
|
|
80
196
|
([docs/providers/codex.md](docs/providers/codex.md)).
|
|
81
|
-
- **npm:**
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
Installing from source (`scripts/install-local.sh`) still works. macOS and Linux are covered by CI;
|
|
86
|
-
Windows is not tested in CI, and is expected to work wherever Node and Bun run.
|
|
87
|
-
|
|
88
|
-
## Ways to run it
|
|
89
|
-
|
|
90
|
-
One review engine, started from different places. Same findings, same labels, your own account each
|
|
91
|
-
time.
|
|
92
|
-
|
|
93
|
-
| Way | Where it runs | What you need | Status |
|
|
94
|
-
| --- | --- | --- | --- |
|
|
95
|
-
| Reusable GitHub Actions workflow | Your repository's runners, on each pull request | A provider API key as a secret | Shipped; [docs/install.md](docs/install.md) |
|
|
96
|
-
| `wachiman local` | Your laptop, on a branch or commit; nothing is posted | Claude Code signed in; no API key | Shipped; [docs/local-review.md](docs/local-review.md) |
|
|
97
|
-
| GitHub App | Not available | | A design only, not implemented |
|
|
98
|
-
|
|
99
|
-
After a local run, `wachiman status` shows what the runs kept on this laptop cost
|
|
100
|
-
([docs/cli.md](docs/cli.md#status)); runs by the workflow are not in it.
|
|
101
|
-
|
|
102
|
-
## Install
|
|
103
|
-
|
|
104
|
-
The recommended way is the reusable workflow: a short caller file in your repository pins a
|
|
105
|
-
release, passes your key and names the operator.
|
|
106
|
-
|
|
107
|
-
**Start here: [docs/install.md](docs/install.md)**, the first advisory review from an empty
|
|
108
|
-
repository to a posted review. The caller file itself is
|
|
109
|
-
[`templates/wachiman-review-caller.yml`](templates/wachiman-review-caller.yml).
|
|
110
|
-
|
|
111
|
-
Already copied the engine into a repository? That setup still runs, and
|
|
112
|
-
[docs/setup-copy.md](docs/setup-copy.md) explains how to move to the maintained workflow.
|
|
113
|
-
|
|
114
|
-
### Review locally on your own subscription
|
|
115
|
-
|
|
116
|
-
`wachiman local` reviews the branch you have checked out, on your own signed-in `claude`, and
|
|
117
|
-
prints the review in the terminal or writes it as Markdown or JSON. No API key, no GitHub token,
|
|
118
|
-
nothing posted: Wachiman sends no telemetry and makes no GitHub requests in local mode; your code
|
|
119
|
-
is sent to your configured Claude account for the review. Read
|
|
120
|
-
[docs/local-review.md](docs/local-review.md) before running it on an employer's code.
|
|
121
|
-
|
|
122
|
-
Install it from npm (below), or from source: run `scripts/install-local.sh` once from your clone. The npm package
|
|
123
|
-
(`npm i -g wachiman` or `bun add -g wachiman`; it is written to work on Windows (Git Bash, PowerShell), and it is expected to work wherever Node and Bun run, but it is not tested in CI: it ships the
|
|
124
|
-
TypeScript source and a small Node launcher, and it installs Bun for you by depending on the
|
|
125
|
-
official npm package `bun`, which means installing it downloads Bun, 23 to 42 MB compressed; with
|
|
126
|
-
`--ignore-scripts` it uses a Bun already on your `PATH`; details and the supply-chain note are in
|
|
127
|
-
[docs/local-review.md](docs/local-review.md#from-npm)) is published. Both give a global `wachiman local …`
|
|
128
|
-
command; the script also links the `wachiman-review` agent skill, usable from any project, and the
|
|
129
|
-
`wachiman-audit` skill, which compares Wachiman's findings with another reviewer's on the same
|
|
130
|
-
commits (data and procedure in
|
|
131
|
-
[wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks)). Details and the Windows
|
|
132
|
-
note are in [docs/local-review.md](docs/local-review.md#3-install).
|
|
133
|
-
|
|
134
|
-
Configure an existing project with `wachiman init`: choose local reviews, GitHub Actions, or
|
|
135
|
-
both. Local setup offers your current Claude session and checks the machine/account before
|
|
136
|
-
suggesting the first review command. GitHub setup writes the workflow; adding the secret and
|
|
137
|
-
submitting the workflow remain manual. See [project setup](docs/local-review.md#configure-this-project).
|
|
138
|
-
|
|
139
|
-
`wachiman ask "<question>"` answers one question about the same local change (or walks through it
|
|
140
|
-
with no question), grounded in the stored review of that change when there is one. It is in
|
|
141
|
-
[docs/cli.md](docs/cli.md#ask).
|
|
142
|
-
|
|
143
|
-
## Documentation map
|
|
144
|
-
|
|
145
|
-
| I want to… | Read |
|
|
146
|
-
| --- | --- |
|
|
147
|
-
| Get a first review on a repository | [docs/install.md](docs/install.md) |
|
|
148
|
-
| Know what I am trusting, and what is unverified | [SECURITY.md](SECURITY.md) |
|
|
149
|
-
| Look up an input, a default or an environment setting | [docs/configuration.md](docs/configuration.md) |
|
|
150
|
-
| Find out why there was no review, or an error | [docs/troubleshooting.md](docs/troubleshooting.md) |
|
|
151
|
-
| Ask for reviews, scope them, read the results | [docs/reviews.md](docs/reviews.md) |
|
|
152
|
-
| Understand what a run can cost and what coverage means | [docs/costs.md](docs/costs.md) |
|
|
153
|
-
| Tell the reviewer what matters in my repository | [docs/review-policy.md](docs/review-policy.md) |
|
|
154
|
-
| Adopt a new release, or roll one back | [docs/upgrading.md](docs/upgrading.md) |
|
|
155
|
-
| Turn it off and remove it | [docs/uninstall.md](docs/uninstall.md) |
|
|
156
|
-
| Quick answers and limitations | [docs/faq.md](docs/faq.md) |
|
|
157
|
-
| Run the engine from the command line | [docs/cli.md](docs/cli.md) |
|
|
158
|
-
| Review a branch on my laptop, on my own Claude subscription | [docs/local-review.md](docs/local-review.md) |
|
|
159
|
-
| See what a provider adapter runs and inherits | [docs/providers/claude-code.md](docs/providers/claude-code.md), [docs/providers/codex.md](docs/providers/codex.md) |
|
|
160
|
-
| Move from a copied installation | [docs/setup-copy.md](docs/setup-copy.md) |
|
|
161
|
-
| Understand how a review is built | [docs/architecture.md](docs/architecture.md) |
|
|
162
|
-
| Measure false positives | [docs/precision.md](docs/precision.md) |
|
|
163
|
-
| See how it compares with Pullfrog and CodeRabbit | [wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks) |
|
|
164
|
-
| See what changed in a release | [CHANGELOG.md](CHANGELOG.md) |
|
|
165
|
-
| Cut a release (maintainers) | [docs/releasing.md](docs/releasing.md) |
|
|
166
|
-
|
|
167
|
-
Design decisions are recorded as ADRs in [docs/adr/](docs/adr/), starting with
|
|
168
|
-
[ADR 0001: distribution and trust](docs/adr/0001-distribution-and-trust.md) and
|
|
169
|
-
[ADR 0002: TypeScript on Bun, no runtime dependencies besides Bun itself](docs/adr/0002-typescript-on-bun-zero-dependencies.md).
|
|
197
|
+
- **npm releases:** version 1.10.0 was published by hand, without a provenance statement; the
|
|
198
|
+
release workflow publishes later versions with one.
|
|
199
|
+
- **Platforms:** macOS and Linux are covered by CI. Windows (Git Bash, PowerShell) is not tested
|
|
200
|
+
in CI and is expected to work wherever Node and Bun run.
|
|
170
201
|
|
|
171
202
|
## License
|
|
172
203
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "wachiman",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.13.0",
|
|
4
4
|
"description": "Advisory pull request reviews by an agent CLI, run in your own GitHub Actions with your own key, or locally on your own Claude subscription",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: wachiman-loop
|
|
3
|
+
description: Use when the developer asks you to review your own change with Wachiman and keep fixing what it finds until it is clean ("loop until clean", "run the wachiman loop", "fix what wachiman reports and run it again") on their laptop. Not for a single review or for judging a finding outside a loop; that is wachiman-review.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Fix a branch with the Wachiman loop
|
|
7
|
+
|
|
8
|
+
## Why
|
|
9
|
+
|
|
10
|
+
`wachiman loop` runs **one review round per call** on the developer's signed-in `claude` and
|
|
11
|
+
tells you whether to stop. The CLI keeps the books: round count, which findings are still open,
|
|
12
|
+
retries and the stop rule. **You fix the code between calls; the CLI never edits it, and you never
|
|
13
|
+
review the code yourself.** Choose the account the way `wachiman-review` does ("Choose the
|
|
14
|
+
profile"): ask `wachiman project show --json`, never read inside a profile directory.
|
|
15
|
+
|
|
16
|
+
## The command
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
env -u ANTHROPIC_API_KEY wachiman loop --repo-dir <clone> --base <ref> --format json \
|
|
20
|
+
[--profile <name>] [--max-rounds <n>] 2> <tmp>/loop.log
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
- `--base <ref>` **starts** a loop: round 1 reviews the whole branch range from that ref (the
|
|
24
|
+
default branch, unless the developer names another). Run it from a directory outside the clone.
|
|
25
|
+
- The same command **without** `--base` continues the open loop of the branch: it reviews only the
|
|
26
|
+
commits made since the previous round. **Commit your fix first**; uncommitted work is not reviewed.
|
|
27
|
+
- Three rounds by default. Raise `--max-rounds` only when the developer says so.
|
|
28
|
+
|
|
29
|
+
## Read the exit code first
|
|
30
|
+
|
|
31
|
+
| Exit | Meaning | You do |
|
|
32
|
+
| --- | --- | --- |
|
|
33
|
+
| `0` | Converged: nothing keeps the loop open | Report it as below |
|
|
34
|
+
| `10` | Findings still open | Work through `open[]`, commit, call again |
|
|
35
|
+
| `11` | Stopped without converging (`outcome.reason`: `round cap` or `review failed`) | Stop. Report the reason and what is still open. Do not call again unless the developer says so |
|
|
36
|
+
| `2` | Usage error (no loop open, detached HEAD, bad flag) | Read stderr and fix the call |
|
|
37
|
+
|
|
38
|
+
A stop is never an approval. `0` means the rule found nothing open in the commits reviewed; it is
|
|
39
|
+
not a statement that the branch is safe to merge.
|
|
40
|
+
|
|
41
|
+
## Between rounds (exit 10)
|
|
42
|
+
|
|
43
|
+
The JSON has `open[]` (each with `id`, `path`, `line`, `severity`, `title`, `status`), `released[]`
|
|
44
|
+
(findings that no longer count, with `why`) and `notes[]` (🟡 and ⚪, which never keep the loop
|
|
45
|
+
open). For each finding in `open[]`:
|
|
46
|
+
|
|
47
|
+
1. Read the cited code in the repository and decide whether the finding is true.
|
|
48
|
+
2. **True:** fix it at that place and commit. The next round has to see the change; a finding at
|
|
49
|
+
lines nobody changed stays open even if the reviewer does not repeat it.
|
|
50
|
+
3. **False, and you can say why in one sentence:** judge it, with the reason:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
wachiman history --repo-dir <clone> --verdict <id> wrong --reason "<why it is not a defect>"
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
A `wrong` verdict without a reason does not release the finding.
|
|
57
|
+
4. **Not sure:** do not guess. Ask the developer, and leave the finding open.
|
|
58
|
+
|
|
59
|
+
**Never judge a finding `wrong` to make the loop converge.** The reason must be something you
|
|
60
|
+
checked in the code, not "out of scope" or "not worth fixing". Every finding you judge `wrong`
|
|
61
|
+
appears in the outcome, and the owner reads that list.
|
|
62
|
+
|
|
63
|
+
Then call `wachiman loop` again without `--base`. A call with no new commit makes no review call
|
|
64
|
+
(and still counts as a round), so use it only after a verdict, never to wait.
|
|
65
|
+
|
|
66
|
+
## At the end
|
|
67
|
+
|
|
68
|
+
Tell the developer, in this order:
|
|
69
|
+
|
|
70
|
+
1. The exit code and `outcome.message`, in your own words but with every caveat. A loop that
|
|
71
|
+
converged at round 1 says "Round 1 reviewed the whole range". A loop that converged later says
|
|
72
|
+
"converged on incremental rounds": round 1 read the whole range and later rounds only your fix
|
|
73
|
+
commits; interactions with code outside them were not re-read. Pass on whichever caveat it
|
|
74
|
+
printed.
|
|
75
|
+
2. What you fixed, with the commit of each.
|
|
76
|
+
3. Every finding in `released[]` with `why: "judged wrong"`, with its reason, so they can overrule
|
|
77
|
+
you. Also name the findings released as `probably-fixed`: that is inferred from the code
|
|
78
|
+
changing, not proved.
|
|
79
|
+
4. The `notes[]`, one line each, as optional.
|
|
80
|
+
|
|
81
|
+
## Never
|
|
82
|
+
|
|
83
|
+
| Tempting | Instead |
|
|
84
|
+
| --- | --- |
|
|
85
|
+
| Editing code inside the CLI, or asking it to apply a fix | You edit and commit; the CLI only reviews |
|
|
86
|
+
| Marking findings `wrong` until exit 0 | Fix the true ones; give a checked reason for the false ones; ask when unsure |
|
|
87
|
+
| Calling again after exit 11 to "try once more" | Report the stop; the developer decides |
|
|
88
|
+
| Running `wachiman review <pr>`, `gh` or a GitHub token | `loop` is local; nothing is posted |
|
|
89
|
+
| Running with `ANTHROPIC_API_KEY` set | `env -u ANTHROPIC_API_KEY wachiman loop ...`; the subscription pays |
|
|
90
|
+
| Editing files under `~/.wachiman` to reset or close a loop | `--base <ref>` starts a new loop |
|
|
91
|
+
| Claiming the branch is approved or safe | Report the outcome and its limits |
|
package/src/call-message.ts
CHANGED
|
@@ -3,7 +3,9 @@
|
|
|
3
3
|
* scripts parse. The JSON stays the contract; this line is for the person reading the log.
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
+
import { isEstimate } from "./cost";
|
|
6
7
|
import type { ProviderErrorClass } from "./providers/errors";
|
|
8
|
+
import type { ProviderAuth } from "./providers/types";
|
|
7
9
|
|
|
8
10
|
export interface CallSummary {
|
|
9
11
|
/** Which call: `batch 1/2`, `threads`, `question`. */
|
|
@@ -15,6 +17,8 @@ export interface CallSummary {
|
|
|
15
17
|
durationMs: number;
|
|
16
18
|
providerError?: ProviderErrorClass;
|
|
17
19
|
errorText?: string;
|
|
20
|
+
/** What paid for the call; absent means `api-key`. */
|
|
21
|
+
credential?: ProviderAuth;
|
|
18
22
|
}
|
|
19
23
|
|
|
20
24
|
const MAX_TEXT = 300;
|
|
@@ -29,18 +33,37 @@ const turnsText = (n: number) => `${n} turn${n === 1 ? "" : "s"}`;
|
|
|
29
33
|
const seconds = (ms: number) => `${(ms / 1000).toFixed(1)} s`;
|
|
30
34
|
const dollars = (usd: number) => `$${usd.toFixed(2)}`;
|
|
31
35
|
|
|
36
|
+
/** The messages for a call refused on a subscription token: its credential is not an API key, so nothing here names one. */
|
|
37
|
+
function describeTokenRefusal(head: string, providerError: ProviderErrorClass | undefined, api: string): string | undefined {
|
|
38
|
+
switch (providerError) {
|
|
39
|
+
case "auth":
|
|
40
|
+
return `❌ ${head}: Claude refused the call: the subscription token was rejected. Check the CLAUDE_CODE_OAUTH_TOKEN secret (a token lasts a year; make a new one with \`claude setup-token\`).${api}`;
|
|
41
|
+
case "billing":
|
|
42
|
+
return `❌ ${head}: Claude refused the call: the subscription's usage limit or plan access stopped it. Wait for the limit to reset, then re-run this job; the review does not fall back to an API key.${api}`;
|
|
43
|
+
case "rate_limit":
|
|
44
|
+
return `⏳ ${head}: Claude rate-limited the call. This is usually temporary.${api}`;
|
|
45
|
+
default:
|
|
46
|
+
return undefined;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
32
50
|
export function describeCall(call: CallSummary): string {
|
|
33
51
|
const head = call.label;
|
|
52
|
+
const estimate = isEstimate(call.credential);
|
|
34
53
|
if (!call.isError && call.terminalReason === "success")
|
|
35
|
-
return `✅ ${head}: finished in ${turnsText(call.turns)}, ${seconds(call.durationMs)}, ${dollars(call.costUsd)}.`;
|
|
54
|
+
return `✅ ${head}: finished in ${turnsText(call.turns)}, ${seconds(call.durationMs)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
|
|
36
55
|
if (call.terminalReason === "budget")
|
|
37
|
-
return `💸 ${head}: stopped at its budget after ${turnsText(call.turns)}, ${dollars(call.costUsd)}.`;
|
|
56
|
+
return `💸 ${head}: stopped at its budget after ${turnsText(call.turns)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
|
|
38
57
|
if (call.terminalReason === "turns")
|
|
39
|
-
return `⏹️ ${head}: hit the turn limit after ${turnsText(call.turns)}, ${dollars(call.costUsd)}.`;
|
|
58
|
+
return `⏹️ ${head}: hit the turn limit after ${turnsText(call.turns)}, ${dollars(call.costUsd)}${estimate ? " (API-price estimate)" : ""}.`;
|
|
40
59
|
if (call.terminalReason === "timeout") return `⏱️ ${head}: killed at the time limit after ${seconds(call.durationMs)}.`;
|
|
41
60
|
|
|
42
61
|
const said = quoted(call.errorText);
|
|
43
62
|
const api = said ? ` API said: ${said}` : "";
|
|
63
|
+
if (call.credential === "oauth-token") {
|
|
64
|
+
const line = describeTokenRefusal(head, call.providerError, api);
|
|
65
|
+
if (line) return line;
|
|
66
|
+
}
|
|
44
67
|
switch (call.providerError) {
|
|
45
68
|
case "billing":
|
|
46
69
|
return `❌ ${head}: the Anthropic API refused the call: the account has no credit. Top up, then re-run this job.${api}`;
|
package/src/cli.ts
CHANGED
|
@@ -10,10 +10,14 @@
|
|
|
10
10
|
* when the head was already reviewed
|
|
11
11
|
* wachiman local [paths…] review the committed branch of a clone on the signed-in
|
|
12
12
|
* `claude`, and print it; no GitHub call (src/local.ts)
|
|
13
|
+
* wachiman loop [--base <ref>] one review round of a fix loop on the signed-in `claude`; exit 0
|
|
14
|
+
* converged, 10 findings open, 11 stopped (src/loop/command.ts)
|
|
13
15
|
* wachiman ask [question…] answer a question about the local change, or explain it; one
|
|
14
16
|
* call, no GitHub request, grounded in the stored review (src/local-ask.ts)
|
|
15
17
|
* wachiman history list and judge what `local --history` kept on this laptop
|
|
16
18
|
* wachiman status what the local history kept and its estimated cost; files only
|
|
19
|
+
* wachiman dashboard spend, findings and loops across every repository in the history, as one
|
|
20
|
+
* static HTML file or JSON, from a rebuildable index (src/store/)
|
|
17
21
|
* wachiman setup [--profile <name>] bind this repository to an account profile (home config only);
|
|
18
22
|
* on a terminal without --profile it asks
|
|
19
23
|
* wachiman init write the GitHub caller workflow, or hand over to `setup`
|
|
@@ -24,7 +28,7 @@
|
|
|
24
28
|
* wachiman --setup-profile [name] sign in an isolated Claude Code profile under the Wachiman home
|
|
25
29
|
*
|
|
26
30
|
* Exit codes: 0 posted or nothing to do; 1 engine error (nothing posted); 2 usage error;
|
|
27
|
-
* 130 cancelled (`local`, `setup`, `init`).
|
|
31
|
+
* 130 cancelled (`local`, `loop`, `setup`, `init`); `loop` also exits 10 and 11 (see its help).
|
|
28
32
|
* The settings are documented in docs/cli.md.
|
|
29
33
|
*/
|
|
30
34
|
import { existsSync, readFileSync, statSync, writeSync } from "node:fs";
|
|
@@ -33,8 +37,10 @@ import { writeStepSummary, type CallCost } from "./cost";
|
|
|
33
37
|
import { loadConfig, UsageError } from "./config";
|
|
34
38
|
import { historyUsage, parseHistoryArgs, runHistory } from "./history/command";
|
|
35
39
|
import { parseStatusArgs, runStatus, statusUsage } from "./status/command";
|
|
36
|
-
import {
|
|
40
|
+
import { dashboardUsage, parseDashboardArgs, runDashboard } from "./store/command";
|
|
41
|
+
import { comment, defaultGh, isThreadQuestion, review, threadReplies, type Deps, type GhFn, type ReviewLineComment } from "./engine";
|
|
37
42
|
import { localUsage, parseLocalArgs, runLocal } from "./local";
|
|
43
|
+
import { loopUsage, parseLoopArgs, runLoop } from "./loop/command";
|
|
38
44
|
import { askUsage, parseAskArgs, runAsk } from "./local-ask";
|
|
39
45
|
import { parseProfileArgs, parseProjectArgs, profileUsage, projectUsage, runProfile, runProject, setupUsage } from "./accounts/commands";
|
|
40
46
|
import { wachimanHome } from "./accounts/config";
|
|
@@ -45,6 +51,7 @@ import { DEFAULT_WORKFLOW_REF } from "./init/options";
|
|
|
45
51
|
import { runInitCommand } from "./init/run";
|
|
46
52
|
import { projectCommands } from "./wizard/command";
|
|
47
53
|
import { DEFAULT_ISOLATED_NAME, setupProfile } from "./profiles";
|
|
54
|
+
import { resetConfidence } from "./fidelity/sink";
|
|
48
55
|
import { getProvider, PROVIDER_NAMES, UnknownProviderError } from "./providers";
|
|
49
56
|
import { parseSetupFlags } from "./setup/args";
|
|
50
57
|
import { runSetupCommand } from "./setup/run";
|
|
@@ -53,11 +60,20 @@ export const USAGE = `Usage:
|
|
|
53
60
|
wachiman review <pr> [paths…] [--repo-dir <dir>] Review a pull request (or only the given paths)
|
|
54
61
|
wachiman comment <pr> [--repo-dir <dir>] Handle the comment in $REQUEST (a review or an answer)
|
|
55
62
|
wachiman threads <pr> [--repo-dir <dir>] Answer the pending Wachiman threads (an automatic run)
|
|
63
|
+
wachiman reset-confidence <pr> [--commit <sha>] Write "cannot say" into the PR Confidence block (no model call;
|
|
64
|
+
the first step of a review run, with AGENT_REVIEW_CONFIDENCE=1)
|
|
56
65
|
${localUsage}
|
|
57
66
|
Review the committed branch of a clone on your
|
|
58
67
|
signed-in claude, and print it; nothing is posted.
|
|
59
68
|
--commit: that one commit (<commit>^ → <commit>);
|
|
60
69
|
--from: that commit forward (<commit>^ → HEAD)
|
|
70
|
+
${loopUsage}
|
|
71
|
+
One round of a review loop on your signed-in claude:
|
|
72
|
+
--base starts it (round 1 reviews the whole range),
|
|
73
|
+
a call with a loop open continues it and reviews only
|
|
74
|
+
the commits since the last round. Fix, or judge a
|
|
75
|
+
finding wrong with a reason, between calls; the CLI
|
|
76
|
+
never edits code. Three rounds by default
|
|
61
77
|
${askUsage}
|
|
62
78
|
Answer a question about the change the scope flags
|
|
63
79
|
select, or explain it when no question is given. One
|
|
@@ -72,6 +88,17 @@ export const USAGE = `Usage:
|
|
|
72
88
|
What this laptop kept of its local runs and their
|
|
73
89
|
estimated cost, filterable; uses local history. GitHub
|
|
74
90
|
Actions runs are not counted
|
|
91
|
+
${dashboardUsage}
|
|
92
|
+
Write one static HTML page (or print JSON) with the
|
|
93
|
+
spend per day and repository, the findings by severity
|
|
94
|
+
and verdict and the loop rounds of every repository in
|
|
95
|
+
the local history. Built from an index under the
|
|
96
|
+
Wachiman home that is rebuilt whenever it is missing or
|
|
97
|
+
out of date. It writes only that index and, without
|
|
98
|
+
--json, the page, and, like \`wachiman history\`, moves
|
|
99
|
+
a damaged run file aside. No claude, no GitHub, no
|
|
100
|
+
network, no server, no browser. --repo-dir is accepted
|
|
101
|
+
and unused
|
|
75
102
|
${setupUsage}
|
|
76
103
|
Bind this repository to an account profile; written
|
|
77
104
|
in the Wachiman home, never in the repository. On a
|
|
@@ -92,7 +119,7 @@ export const USAGE = `Usage:
|
|
|
92
119
|
Claude configuration directory, used in place
|
|
93
120
|
${projectUsage.split("\n").join("\n ")}
|
|
94
121
|
${skillsUsage.split("\n").join("\n ")}
|
|
95
|
-
Copy the wachiman-review and wachiman-audit agent
|
|
122
|
+
Copy the wachiman-review, wachiman-loop and wachiman-audit agent
|
|
96
123
|
skills into ~/.agents/skills and each Claude Code
|
|
97
124
|
config directory; uninstall removes only the copies
|
|
98
125
|
it marked. Never touches ~/.wachiman
|
|
@@ -107,17 +134,21 @@ Options:
|
|
|
107
134
|
|
|
108
135
|
Environment:
|
|
109
136
|
GH_TOKEN, GITHUB_REPOSITORY required (not read by \`local\`, \`ask\` or \`--setup-profile\`)
|
|
110
|
-
ANTHROPIC_API_KEY
|
|
111
|
-
\`local\` and \`ask\` refuse to start when it is set
|
|
137
|
+
ANTHROPIC_API_KEY the claude-code provider needs this or CLAUDE_CODE_OAUTH_TOKEN
|
|
138
|
+
(not in a dry run); \`local\` and \`ask\` refuse to start when it is set
|
|
139
|
+
CLAUDE_CODE_OAUTH_TOKEN a Claude subscription token (\`claude setup-token\`); if set, it is
|
|
140
|
+
used and ANTHROPIC_API_KEY never reaches the agent
|
|
112
141
|
REQUEST the comment text, for \`comment\`
|
|
113
142
|
AGENT_REVIEW_COMMENT_AUTHOR the login of the comment's author, for \`comment\` and \`threads\`
|
|
114
143
|
AGENT_REVIEW_* optional settings; see docs/cli.md
|
|
115
144
|
|
|
116
145
|
Exit codes: 0 posted or nothing to do, 1 engine error, 2 usage error.
|
|
117
146
|
\`local\`: 0 a report was printed, 1 no call returned a review, 2 usage error, 130 interrupted.
|
|
147
|
+
\`loop\`: 0 converged, 10 findings still open, 11 stopped without converging (round cap or review failed), 2 usage error, 130 interrupted. A stop is never an approval.
|
|
118
148
|
\`ask\`: 0 an answer was printed (it may say what it could not answer), 1 no answer (the call failed or returned nothing usable), 2 usage error, 130 interrupted.
|
|
119
149
|
\`history\`: 0 listed (or nothing to list), 2 usage error, including an unknown finding id.
|
|
120
150
|
\`status\`: 0 printed (also with no run kept), 2 usage error.
|
|
151
|
+
\`dashboard\`: 0 written or printed (also with no run kept), 2 usage error, 1 the index or the page could not be written.
|
|
121
152
|
\`doctor\`: 0 every required check passed, 1 one failed. \`setup\`: 1 when its closing doctor summary failed.
|
|
122
153
|
\`setup\`, \`init\`: 130 cancelled (Escape, Ctrl-C, Ctrl-D); nothing pending is saved.
|
|
123
154
|
\`skills\`: 0 done (copies left in place are warned about), 1 a copy could not be written, 2 usage error or a refused target.
|
|
@@ -247,6 +278,37 @@ async function runWizard(mode: "setup" | "init", args: string[], repoDir: string
|
|
|
247
278
|
});
|
|
248
279
|
}
|
|
249
280
|
|
|
281
|
+
/**
|
|
282
|
+
* `wachiman reset-confidence <pr> [--commit <sha>]`: the first step of a review run (ADR 0033
|
|
283
|
+
* decision 14). It rewrites the PR Confidence block to `cannot say` for the commit under review
|
|
284
|
+
* before the push wait, so a run cancelled during it leaves no letter from an older commit. No
|
|
285
|
+
* model, no provider. A failure inside the reset itself (reading or writing the description) is a
|
|
286
|
+
* warning and the exit code stays 0. A usage or configuration error is not: a bad pull request
|
|
287
|
+
* number or flag, an invalid `AGENT_REVIEW_*` value, or a missing `GH_TOKEN` or
|
|
288
|
+
* `GITHUB_REPOSITORY` exits non-zero. The workflow steps run it with `continue-on-error`.
|
|
289
|
+
*/
|
|
290
|
+
export function runResetConfidence(args: string[], env: Record<string, string | undefined>, gh: GhFn = defaultGh): number {
|
|
291
|
+
const [prArg, ...flags] = args;
|
|
292
|
+
const pr = Number(prArg);
|
|
293
|
+
if (!/^\d+$/.test(prArg ?? "") || pr <= 0) throw new UsageError("reset-confidence needs a pull request number.");
|
|
294
|
+
let commit: string | undefined;
|
|
295
|
+
for (let i = 0; i < flags.length; i++) {
|
|
296
|
+
if (flags[i] !== "--commit" || !flags[i + 1]) throw new UsageError(`reset-confidence: unexpected "${flags[i]}".`);
|
|
297
|
+
commit = flags[++i];
|
|
298
|
+
}
|
|
299
|
+
const config = loadConfig(env);
|
|
300
|
+
if (!config.confidence) return 0;
|
|
301
|
+
required(env, "GH_TOKEN");
|
|
302
|
+
const repo = required(env, "GITHUB_REPOSITORY");
|
|
303
|
+
resetConfidence(
|
|
304
|
+
{ gh, dryRun: config.dryRun, log: (line) => console.log(line), warn: (line) => console.error(line) },
|
|
305
|
+
repo,
|
|
306
|
+
pr,
|
|
307
|
+
commit,
|
|
308
|
+
);
|
|
309
|
+
return 0;
|
|
310
|
+
}
|
|
311
|
+
|
|
250
312
|
export async function main(argv: string[], env: Record<string, string | undefined>): Promise<number> {
|
|
251
313
|
const mode = argv[0];
|
|
252
314
|
if (mode === "--help" || mode === "-h") {
|
|
@@ -281,6 +343,14 @@ export async function main(argv: string[], env: Record<string, string | undefine
|
|
|
281
343
|
engineVersion: readVersion(),
|
|
282
344
|
});
|
|
283
345
|
}
|
|
346
|
+
if (mode === "loop") {
|
|
347
|
+
// Like `local`: no GitHub token, no `gh` function anywhere on this path.
|
|
348
|
+
return runLoop(parseLoopArgs(args.slice(1)), repoDir, env, {
|
|
349
|
+
stdout: (text) => writeAll(1, text),
|
|
350
|
+
stderr: (line) => console.error(line),
|
|
351
|
+
engineVersion: readVersion(),
|
|
352
|
+
});
|
|
353
|
+
}
|
|
284
354
|
if (mode === "ask") {
|
|
285
355
|
// Like `local`: no GitHub token, no `gh` function anywhere on this path.
|
|
286
356
|
return runAsk(parseAskArgs(args.slice(1)), repoDir, env, {
|
|
@@ -298,9 +368,15 @@ export async function main(argv: string[], env: Record<string, string | undefine
|
|
|
298
368
|
if ("help" in parsed) return (writeAll(1, `${statusUsage}\n`), 0);
|
|
299
369
|
return runStatus(parsed, repoDir, env, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line), version: readVersion() });
|
|
300
370
|
}
|
|
371
|
+
if (mode === "dashboard") {
|
|
372
|
+
const parsed = parseDashboardArgs(args.slice(1));
|
|
373
|
+
if ("help" in parsed) return (writeAll(1, `${dashboardUsage}\n`), 0);
|
|
374
|
+
return runDashboard(parsed, env, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) });
|
|
375
|
+
}
|
|
301
376
|
if (mode === "history") {
|
|
302
377
|
return runHistory(parseHistoryArgs(args.slice(1)), repoDir, env, { stdout: (text) => writeAll(1, text), stderr: (line) => console.error(line) });
|
|
303
378
|
}
|
|
379
|
+
if (mode === "reset-confidence") return runResetConfidence(args.slice(1), env);
|
|
304
380
|
const [, prArg, ...rest] = args;
|
|
305
381
|
if (mode !== "review" && mode !== "comment" && mode !== "threads") {
|
|
306
382
|
throw new UsageError(mode ? `Unknown command "${mode}".` : "No command given.");
|