wachiman 0.0.0-stage → 1.12.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.
Files changed (80) hide show
  1. package/LICENSE +105 -0
  2. package/README.md +207 -2
  3. package/bin/launcher-args.js +179 -0
  4. package/bin/wachiman.js +10 -0
  5. package/bunfig.toml +6 -0
  6. package/package.json +40 -4
  7. package/skills/wachiman-audit/SKILL.md +80 -0
  8. package/skills/wachiman-review/SKILL.md +127 -0
  9. package/src/accounts/commands.ts +684 -0
  10. package/src/accounts/config.ts +322 -0
  11. package/src/accounts/confirm.ts +231 -0
  12. package/src/accounts/profile-list.ts +70 -0
  13. package/src/accounts/resolve.ts +152 -0
  14. package/src/ask.ts +240 -0
  15. package/src/call-message.ts +54 -0
  16. package/src/cli.ts +367 -0
  17. package/src/config.ts +227 -0
  18. package/src/connectors/local-git.ts +483 -0
  19. package/src/connectors/working-tree.ts +333 -0
  20. package/src/contracts.ts +246 -0
  21. package/src/cost.ts +180 -0
  22. package/src/doctor/checks.ts +434 -0
  23. package/src/doctor/render.ts +76 -0
  24. package/src/doctor/run.ts +157 -0
  25. package/src/engine.ts +4060 -0
  26. package/src/evidence.ts +739 -0
  27. package/src/flags.ts +44 -0
  28. package/src/formats.ts +333 -0
  29. package/src/history/command.ts +175 -0
  30. package/src/history/fingerprint.ts +58 -0
  31. package/src/history/index.ts +106 -0
  32. package/src/history/match.ts +181 -0
  33. package/src/history/store.ts +325 -0
  34. package/src/history/types.ts +69 -0
  35. package/src/init/args.ts +27 -0
  36. package/src/init/options.ts +124 -0
  37. package/src/init/prompt.ts +54 -0
  38. package/src/init/render.ts +31 -0
  39. package/src/init/run.ts +163 -0
  40. package/src/init/write.ts +114 -0
  41. package/src/install-claude-code.sh +85 -0
  42. package/src/install-kind.ts +50 -0
  43. package/src/json-schema.ts +95 -0
  44. package/src/local-ask.ts +231 -0
  45. package/src/local.ts +585 -0
  46. package/src/precision.ts +175 -0
  47. package/src/profiles.ts +157 -0
  48. package/src/providers/claude-code.settings.json +5 -0
  49. package/src/providers/claude-code.ts +406 -0
  50. package/src/providers/codex.ts +391 -0
  51. package/src/providers/errors.ts +64 -0
  52. package/src/providers/index.ts +54 -0
  53. package/src/providers/locate.ts +15 -0
  54. package/src/providers/types.ts +116 -0
  55. package/src/questions/bounded-wait.ts +68 -0
  56. package/src/questions/destructive-step.ts +74 -0
  57. package/src/questions/index.ts +55 -0
  58. package/src/questions/overlapping-calls.ts +63 -0
  59. package/src/questions/read-error-as-empty.ts +138 -0
  60. package/src/questions/stale-write-back.ts +91 -0
  61. package/src/questions/types.ts +14 -0
  62. package/src/risk.ts +264 -0
  63. package/src/setup/args.ts +16 -0
  64. package/src/setup/options.ts +32 -0
  65. package/src/setup/prompt.ts +183 -0
  66. package/src/setup/run.ts +231 -0
  67. package/src/sinks/agent-prompt.ts +18 -0
  68. package/src/sinks/common.ts +242 -0
  69. package/src/sinks/json.ts +9 -0
  70. package/src/sinks/markdown.ts +89 -0
  71. package/src/sinks/terminal.ts +57 -0
  72. package/src/skills/install.ts +379 -0
  73. package/src/status/command.ts +202 -0
  74. package/src/verify.ts +413 -0
  75. package/src/wizard/command.ts +23 -0
  76. package/src/wizard/interactive.ts +16 -0
  77. package/src/wizard/prompt.ts +189 -0
  78. package/src/wizard/style.ts +19 -0
  79. package/templates/caller-workflow.yml +343 -0
  80. package/templates/wachiman-review-caller.yml +37 -0
package/LICENSE ADDED
@@ -0,0 +1,105 @@
1
+ # Functional Source License, Version 1.1, ALv2 Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-ALv2
6
+
7
+ ## Notice
8
+
9
+ Copyright 2026 Niway S.A.C.
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the Apache License, Version 2.0 that is effective on the second anniversary of
91
+ the date we make the Software available. On or after that date, you may use the
92
+ Software under the Apache License, Version 2.0, in which case the following
93
+ will apply:
94
+
95
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
96
+ this file except in compliance with the License.
97
+
98
+ You may obtain a copy of the License at
99
+
100
+ http://www.apache.org/licenses/LICENSE-2.0
101
+
102
+ Unless required by applicable law or agreed to in writing, software distributed
103
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
104
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the
105
+ specific language governing permissions and limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,208 @@
1
- # Temporary Holding Version
1
+ # Wachiman
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img src="docs/assets/wachi.png" alt="Wachiman, a cartoon watchman with a cap and a whistle" width="96" align="right">
4
+
5
+ Advisory code reviews by an agent CLI: a pull request review that runs inside your own GitHub
6
+ Actions with your own API key, or a review of a branch on your laptop with your own Claude
7
+ subscription. One engine, two ways to start it today ([below](#ways-to-run-it)). Wachiman
8
+ (pronounced *watchman*) is named after the Peruvian *wachimán*, the street
9
+ watchman who warns you and lets you decide; the Spanish word comes from the English one.
10
+
11
+ ## What it is
12
+
13
+ A GitHub Actions workflow that reads a pull request and posts one GitHub review on it. Each
14
+ finding is an inline comment on its line, labelled with a severity (when to act: Blocker, Fix,
15
+ Consider) and a topic (what it is about: bug, docs, security…), for example `🟠📝 Fix · docs`.
16
+ Information that asks for no reply, such as a notice that the pull request edits a decision
17
+ record, goes in the review body. Every comment opens with "👮 **Wachiman**".
18
+
19
+ - **It runs in your repository.** The workflow runs on your runners and spends your own provider
20
+ key. This project operates no service that receives your code or your key.
21
+ - **It is advisory.** The review is posted as a plain comment review. It never approves,
22
+ requests changes or blocks a merge, and "Blocker" is a label on a comment, not a status
23
+ GitHub enforces.
24
+ - **It starts on a pull request and on request.** It reviews when a pull request opens or leaves
25
+ draft, and, if your caller lists `synchronize`, on each push (only the new commits). The operator
26
+ you name can comment `/wachiman review` to ask for another review of what changed, or any other
27
+ `/wachiman …` text to ask a question. An answer reads the latest review and checks its file and
28
+ line references against the pull request's head. `/wachiman` alone, or `/wachiman explain`, gets
29
+ a walkthrough of the change. A reply the operator writes in a review thread gets an answer
30
+ without a push. All automatic runs on one pull request together stop at $6 by default
31
+ (`auto_budget_usd`); `/wachiman review` is not limited. Only the operator can ask by default. A
32
+ collaborator can be allowed to ask too (set the `askers` input to `write`; their questions then
33
+ share a ceiling of $3 per pull request, `ask_ceiling_usd`). Details: [docs/reviews.md](docs/reviews.md).
34
+ - **Large pull requests are reviewed in batches**, riskiest files first (the risk is a score
35
+ computed from file paths, not a reading of the code). Each batch is one agent call with a
36
+ spend limit. What that limit does and does not guarantee, and what "all files reviewed"
37
+ establishes, is in [docs/costs.md](docs/costs.md).
38
+
39
+ ## What it will not do
40
+
41
+ - It does not approve, request changes, gate a merge or replace a human review.
42
+ - It does not run your code or tests. In the Claude Code workflow the agent is started with
43
+ read-only tools and no shell; that is a tested configuration, not a sandbox
44
+ ([SECURITY.md](SECURITY.md)).
45
+ - It does not check every changed file in every case: lockfiles, build output and generated files
46
+ are dropped first, and coverage is what the model reports per file. If some files are not
47
+ reviewed, the first line of the review says so.
48
+ - It is not a sandbox, and it is not a tool for reviewing code from people you do not trust (see
49
+ below).
50
+
51
+ ## The trust decision, in brief
52
+
53
+ Installing it gives a workflow your model API key and read access to your pull requests. Before
54
+ you do:
55
+
56
+ - **Everyone who can push a branch to the repository must be someone you trust with the key.** On
57
+ a pull request GitHub runs the workflow file from the pull request's own branch, so a person
58
+ who can push can change the workflow and read the key. Nothing in this tool defends against
59
+ that. Fork pull requests are skipped.
60
+ - **Your code goes to the model provider.** The review sends the pull request's diff, and the
61
+ files the agent chooses to read, to the provider you configured (Anthropic, for Claude Code)
62
+ from your runner.
63
+ - **The version you pin decides what runs with your key.** See
64
+ [docs/install.md](docs/install.md#what-pinning-a-version-does-and-does-not-guarantee).
65
+
66
+ This is not a sandbox. What is enforced, what the tests show and what is still unverified:
67
+ [SECURITY.md](SECURITY.md).
68
+
69
+ ## Status and providers
70
+
71
+ The current release is **v1.5.0** ([CHANGELOG.md](CHANGELOG.md)). The command-line contract
72
+ ([docs/cli.md](docs/cli.md)) and the provider adapter boundary are in place. The older
73
+ `CLAUDE_REVIEW_*` variables, `.github/agent-review.md`, `.github/claude-review.md`, `/wachi` and the `@claude` mention are still read
74
+ with a notice; see [docs/upgrading.md](docs/upgrading.md).
75
+
76
+ - **Claude Code** (`claude -p`) is the provider the reusable workflow installs and runs, with
77
+ `ANTHROPIC_API_KEY` ([docs/providers/claude-code.md](docs/providers/claude-code.md)).
78
+ - **Codex CLI** (`codex exec`, for OpenAI models) is a second adapter, available only from the
79
+ command line. The reusable workflow does not install it or pass an OpenAI key
80
+ ([docs/providers/codex.md](docs/providers/codex.md)).
81
+ - **npm:** the package `wachiman` is on npm (`npm i -g wachiman`; a Node launcher that installs
82
+ Bun through its `bun` dependency;
83
+ [docs/local-review.md](docs/local-review.md#3-install)). Version 1.10.0 was published by hand,
84
+ without a provenance statement; the release workflow publishes the following versions with one.
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).
170
+
171
+ ## License
172
+
173
+ Wachiman is **source available**, not open source. It is licensed under the
174
+ [Functional Source License, Version 1.1, ALv2 Future License](LICENSE) (`FSL-1.1-ALv2`), a
175
+ [Fair Source](https://fair.io/) license. Copyright 2026 Niway S.A.C.
176
+
177
+ - **You may** use it for any purpose except a Competing Use: run it on your own repositories and
178
+ in your company, read and modify it, fork it for internal use, use it for non-commercial
179
+ education and research, and use it to give professional services to a client who may also
180
+ use it.
181
+ - **You may not**, without a commercial license, make it available to others as a commercial
182
+ product or service that does what Wachiman does, hosted or packaged.
183
+ - **Each version published under FSL-1.1-ALv2 also becomes available under Apache 2.0 two years
184
+ after that version is made available.** The license says so under "Grant of Future License".
185
+ - **Commercial license:** write to contact@niway.com. There is no price list.
186
+ - **Name and logo:** the license grants no rights to them. See [TRADEMARKS.md](TRADEMARKS.md).
187
+
188
+ ### Licensing history
189
+
190
+ Everything published before the commit that replaced LICENSE, including releases through v1.3.0,
191
+ remains available under GNU AGPL version 3 or any later version, as stated in those versions'
192
+ LICENSE files. The
193
+ `LICENSE` file inside each release tag says which license that release carries. The reason for the
194
+ change is recorded in [ADR 0013](docs/adr/0013-license-fsl-1-1-alv2.md).
195
+
196
+ Benchmark reports and the review dataset live in
197
+ [niway-dev/wachiman-benchmarks](https://github.com/niway-dev/wachiman-benchmarks); they moved there
198
+ from `docs/benchmark/` on 2026-11-02. Quoted third-party text in them, and in this repository's
199
+ history, belongs to its authors and is reproduced for research and comparison; it is not covered by
200
+ the license above.
201
+
202
+ ## Commit messages
203
+
204
+ Releases and the changelog are generated from commit messages, so pull request titles (squash
205
+ merges use them) follow [Conventional Commits](https://www.conventionalcommits.org/):
206
+ `feat:` is a minor release, `fix:` and `perf:` a patch, `feat!:` or a `BREAKING CHANGE:` footer a
207
+ major one. `docs:`, `test:`, `ci:`, `build:`, `chore:` and `style:` appear in no release notes.
208
+ Release pull requests are titled `chore: release X.Y.Z`.
@@ -0,0 +1,179 @@
1
+ // The launcher's logic, in one dependency-free module (Node built-ins only). `bin/wachiman.js`
2
+ // calls `launch`; the Bun tests import this same file, so no second copy of the argv exists.
3
+ //
4
+ // The launcher's one job is to make the npm install portable. It never changes the environment,
5
+ // never turns a variable into a flag, and never downloads or installs anything: the Bun it runs is
6
+ // the one the package's own `bun` dependency installed, or one already on PATH.
7
+ import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
8
+ import { existsSync } from "node:fs";
9
+ import { createRequire } from "node:module";
10
+ import { constants } from "node:os";
11
+ import { dirname, join, posix, win32 } from "node:path";
12
+
13
+ export const BUN_INSTALL_LINE = "wachiman needs Bun 1.3 or later: https://bun.sh";
14
+ export const MIN_BUN = [1, 3, 0];
15
+
16
+ /**
17
+ * Pure. The argv the launcher gives to `bun`: the isolation flags first (Bun reads `.env` and a
18
+ * `bunfig.toml`, which can run code, from its working directory, and that directory is the
19
+ * reviewed repository), then the package's own entry point, then the user's arguments untouched.
20
+ */
21
+ export function launcherArgs(pkgDir, argv) {
22
+ return ["--no-env-file", `--config=${join(pkgDir, "bunfig.toml")}`, join(pkgDir, "src", "cli.ts"), ...argv];
23
+ }
24
+
25
+ /**
26
+ * Where the official npm package `bun` (a regular dependency of this package) keeps its binary:
27
+ * `<package>/bin/bun.exe`, on every OS. Resolved from this file's own location through Node's
28
+ * module lookup, never from the working directory, so a `node_modules/bun` inside the reviewed
29
+ * repository is never reached. Null when the package is not installed. The file may still be the
30
+ * placeholder the package ships when its postinstall did not run (`--ignore-scripts`): see `probeBun`.
31
+ */
32
+ export function bundledBunPath(resolve = createRequire(import.meta.url).resolve) {
33
+ try {
34
+ return join(dirname(resolve("bun/package.json")), "bin", "bun.exe");
35
+ } catch {
36
+ return null;
37
+ }
38
+ }
39
+
40
+ /** Pure. `[major, minor, patch]` from the first line of `bun --version` output, or null. */
41
+ export function parseBunVersion(text) {
42
+ const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(text ?? "").trim());
43
+ return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
44
+ }
45
+
46
+ /** Pure. True when version `a` is the same as or later than version `b` (both `[major, minor, patch]`). */
47
+ export function versionAtLeast(a, b = MIN_BUN) {
48
+ for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] > b[i];
49
+ return true;
50
+ }
51
+
52
+ /**
53
+ * Runs `<binary> --version` and judges the answer. A file that exists is not enough: with
54
+ * `--ignore-scripts` the `bun` package leaves a placeholder in `bin/bun.exe` that cannot run. Returns `{ ok: true, version }`, `{ ok: false, reason: "old", version }`
55
+ * `{ ok: false, reason: "timeout" }` or `{ ok: false, reason: "unusable" }`. No shell, a timeout generous
56
+ * enough for the first start of a freshly installed binary, the caller's environment.
57
+ */
58
+ export function probeBun(binary, { env, cwd, spawnSync = nodeSpawnSync, timeout = 15000 }) {
59
+ let result;
60
+ try {
61
+ result = spawnSync(binary, ["--version"], { shell: false, timeout, env, cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
62
+ } catch {
63
+ return { ok: false, reason: "unusable" };
64
+ }
65
+ if (result?.error?.code === "ETIMEDOUT" || result?.signal === "SIGTERM") return { ok: false, reason: "timeout" };
66
+ if (!result || result.error || result.status !== 0) return { ok: false, reason: "unusable" };
67
+ const version = parseBunVersion(String(result.stdout ?? "").split("\n")[0]);
68
+ if (version === null) return { ok: false, reason: "unusable" };
69
+ const text = version.join(".");
70
+ return versionAtLeast(version) ? { ok: true, version: text } : { ok: false, reason: "old", version: text };
71
+ }
72
+
73
+ /**
74
+ * Pure apart from `exists`. The first `bun` found on PATH, or null. Only absolute entries count,
75
+ * on every OS: an empty or relative entry (or ".") means the working directory, which is the
76
+ * reviewed repository, and a binary there must never run. On Windows a bare name would also be
77
+ * looked up in the working directory first, so the PATH is always scanned here. Each entry may
78
+ * hold `bun` (`bun.exe` on Windows) or, on Windows, the npm-global layout
79
+ * `node_modules\bun\bin\bun.exe` that `npm install -g bun` creates next to its `bun.cmd` shim.
80
+ */
81
+ export function resolveBun(platform, env, exists = existsSync) {
82
+ const windows = platform === "win32";
83
+ const path = windows ? win32 : posix;
84
+ const key = Object.keys(env).find((name) => (windows ? name.toLowerCase() === "path" : name === "PATH"));
85
+ const value = key === undefined ? "" : env[key] ?? "";
86
+ for (const raw of value.split(windows ? ";" : ":")) {
87
+ const entry = windows ? raw.trim().replace(/^"(.*)"$/, "$1") : raw;
88
+ if (entry === "" || !path.isAbsolute(entry)) continue;
89
+ const candidates = windows ? [path.join(entry, "bun.exe"), path.join(entry, "node_modules", "bun", "bin", "bun.exe")] : [path.join(entry, "bun")];
90
+ for (const candidate of candidates) if (exists(candidate)) return candidate;
91
+ }
92
+ return null;
93
+ }
94
+
95
+ /**
96
+ * The Bun to run: the bundled one when it works, else a Bun on PATH when it works, else the
97
+ * reason there is none. Returns `{ binary, version }`, or `{ binary: null, old, failed }` where `old`
98
+ * is the `{ version, path }` of the first Bun that runs but is older than 1.3 (null when none) and
99
+ * `failed` is the path of the first candidate that did not run at all (a placeholder, an error or
100
+ * a timeout), undefined when there was none.
101
+ */
102
+ export function findBun({ platform, env, cwd, exists = existsSync, spawnSync = nodeSpawnSync, bundled = bundledBunPath }) {
103
+ let old = null;
104
+ let failed;
105
+ const candidates = [bundled(), resolveBun(platform, env, exists)].filter((path) => path !== null && path !== undefined);
106
+ for (const binary of [...new Set(candidates)]) {
107
+ const probe = probeBun(binary, { env, cwd, spawnSync });
108
+ if (probe.ok) return { binary, version: probe.version };
109
+ if (probe.reason === "old" && old === null) old = { version: probe.version, path: binary };
110
+ else if (probe.reason !== "old" && failed === undefined) failed = binary;
111
+ }
112
+ return { binary: null, old, failed };
113
+ }
114
+
115
+ /** Pure. The stderr lines for "no usable Bun": which case it is, then the commands. */
116
+ export function missingBunLines(found, platform) {
117
+ const first = found.old
118
+ ? `wachiman needs Bun 1.3 or later, but found Bun ${found.old.version} (${found.old.path}): https://bun.sh`
119
+ : BUN_INSTALL_LINE;
120
+ const lines = [
121
+ first,
122
+ found.old
123
+ ? "Upgrade it, or install a newer one:"
124
+ : found.failed
125
+ ? `A Bun was found (${found.failed}) but did not run (an install with --ignore-scripts leaves a placeholder that cannot run; a first start can also be slow, try again). Install or repair one:`
126
+ : "No Bun was found: the `bun` package that npm installs with wachiman is missing and no Bun is on PATH. Install one:",
127
+ " npm install -g bun",
128
+ ];
129
+ if (platform === "win32") lines.push(' powershell -c "irm bun.sh/install.ps1|iex" (then open a new terminal)');
130
+ lines.push(" https://bun.sh");
131
+ return lines;
132
+ }
133
+
134
+ /**
135
+ * Runs the engine under Bun and resolves to the exit code. Everything it touches is a parameter,
136
+ * so a test can replace `spawn` and `stderr`; `env` is handed to the child as the same object it
137
+ * was given and is never written to. While the child runs the launcher ignores SIGINT (the
138
+ * terminal already delivers it to the child's process group, and the child cleans up on its own
139
+ * schedule) and forwards SIGTERM and SIGHUP; it exits with the child's code, or 128+n when the
140
+ * child died from signal n. A SIGINT sent to the launcher's pid alone is dropped; use SIGTERM,
141
+ * which is forwarded. The Bun comes from the package's own `bun` dependency or from the absolute
142
+ * PATH entries only (see `findBun`), so a `bun` in the reviewed repository (the cwd) is never run.
143
+ */
144
+ export function launch({ pkgDir, argv, platform = process.platform, env = process.env, spawn = nodeSpawn, stderr = (line) => console.error(line), exists = existsSync, spawnSync = nodeSpawnSync, bundled = bundledBunPath }) {
145
+ return new Promise((resolve) => {
146
+ const { binary, old, failed } = findBun({ platform, env, cwd: pkgDir, exists, spawnSync, bundled });
147
+ if (binary === null) {
148
+ for (const line of missingBunLines({ old, failed }, platform)) stderr(line);
149
+ resolve(2);
150
+ return;
151
+ }
152
+ const child = spawn(binary, launcherArgs(pkgDir, argv), { stdio: "inherit", env });
153
+ const ignore = () => {};
154
+ const forward = { SIGTERM: () => child.kill("SIGTERM"), SIGHUP: () => child.kill("SIGHUP") };
155
+ process.on("SIGINT", ignore);
156
+ for (const [name, handler] of Object.entries(forward)) process.on(name, handler);
157
+ let done = false;
158
+ const finish = (code) => {
159
+ if (done) return;
160
+ done = true;
161
+ process.off("SIGINT", ignore);
162
+ for (const [name, handler] of Object.entries(forward)) process.off(name, handler);
163
+ resolve(code);
164
+ };
165
+ child.on("error", (error) => {
166
+ if (error.code === "ENOENT") {
167
+ stderr(BUN_INSTALL_LINE);
168
+ finish(2);
169
+ } else {
170
+ stderr(`wachiman: could not start bun: ${error.message}`);
171
+ finish(1);
172
+ }
173
+ });
174
+ child.on("close", (code, signal) => {
175
+ if (code !== null && code !== undefined) finish(code);
176
+ else finish(signal && constants.signals[signal] ? 128 + constants.signals[signal] : 1);
177
+ });
178
+ });
179
+ }
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+ // The npm `bin` for `wachiman` and `agent-review`: finds Bun on PATH and runs this package's
3
+ // TypeScript engine with it. All logic is in ./launcher-args.js.
4
+ import { dirname } from "node:path";
5
+ import { fileURLToPath } from "node:url";
6
+ import { launch } from "./launcher-args.js";
7
+
8
+ // Node resolves the symlink npm puts in `bin/`, so this is the real package directory.
9
+ const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
10
+ process.exitCode = await launch({ pkgDir, argv: process.argv.slice(2) });
package/bunfig.toml ADDED
@@ -0,0 +1,6 @@
1
+ # Engine-owned Bun configuration. The workflow runs the engine with
2
+ # `bun --no-env-file --config=<this file>`, so Bun never reads a bunfig.toml (and its
3
+ # `preload`, which runs code) or a .env file from the reviewed pull request's checkout.
4
+ # Keep this file minimal: no `preload`, no `env`.
5
+ [install]
6
+ auto = "disable"
package/package.json CHANGED
@@ -1,6 +1,42 @@
1
1
  {
2
2
  "name": "wachiman",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.12.0",
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
+ "private": false,
6
+ "type": "module",
7
+ "license": "FSL-1.1-ALv2",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/niway-dev/wachiman.git"
11
+ },
12
+ "bin": {
13
+ "wachiman": "bin/wachiman.js",
14
+ "agent-review": "bin/wachiman.js"
15
+ },
16
+ "files": [
17
+ "bin/wachiman.js",
18
+ "bin/launcher-args.js",
19
+ "src/",
20
+ "skills/",
21
+ "templates/",
22
+ "bunfig.toml",
23
+ "LICENSE",
24
+ "README.md",
25
+ "!**/*.test.ts",
26
+ "!**/fixtures/"
27
+ ],
28
+ "dependencies": {
29
+ "bun": "1.3.4"
30
+ },
31
+ "engines": {
32
+ "bun": ">=1.3",
33
+ "node": ">=20"
34
+ },
35
+ "publishConfig": {
36
+ "access": "public",
37
+ "provenance": true
38
+ },
39
+ "scripts": {
40
+ "test": "bun test"
41
+ }
42
+ }
@@ -0,0 +1,80 @@
1
+ ---
2
+ name: wachiman-audit
3
+ description: Use when the developer asks to compare Wachiman's findings with CodeRabbit's or Pullfrog's on real pull requests, what one found that the other missed, or whether a day or a release of reviews was worth its cost. Not for reviewing code; that is wachiman-review.
4
+ ---
5
+
6
+ # Audit Wachiman against another reviewer
7
+
8
+ ## Why
9
+
10
+ Comparing two reviewers by hand mixes things that must stay apart: a finding posted on one commit
11
+ with a finding posted on the next, a live CI run with a rerun on a laptop, a tool that found nothing
12
+ with a tool that never ran. The pairing is mechanical and a script does it; the judgement is not,
13
+ and that is the only part you do.
14
+
15
+ ## The one command
16
+
17
+ From a worktree of `niway-dev/wachiman-benchmarks`:
18
+
19
+ ```sh
20
+ bun scripts/pair.ts --repo <owner/name> --prs <a-b[,c]> --other coderabbit|pullfrog --out <YYYY-MM-DD-<topic>>/pairs
21
+ ```
22
+
23
+ `--other` accepts only those two tools. Asked about another bot, stop and say that `pair.ts` needs a
24
+ parser for it first; do not compare by hand.
25
+
26
+ It writes `pairs.csv`, `special-cases.csv`, `reviews.csv`, `findings.csv` and a generated `pairs.md`.
27
+ Never edit those files, and never build the comparison from the PR page instead of them.
28
+
29
+ ## What a pair is
30
+
31
+ A **pair** is one commit that both tools finished reviewing. Only findings with
32
+ `comparison: paired` in `findings.csv` are compared. A commit one tool reviewed and the other did
33
+ not, a refusal (no credit), a skip (path filters) or a partial review is a **special case**: it is
34
+ reported, with its reason and what would make it comparable, and it is never counted in the
35
+ comparison. A rerun on a laptop at the same commit makes a new row with `basis: rerun`; it goes in
36
+ the special-cases section, not in the pairs.
37
+
38
+ ## Judge, then write
39
+
40
+ For every paired finding, add one row to a hand-written `verdicts.csv` next to the pairs:
41
+
42
+ | column | values |
43
+ | --- | --- |
44
+ | `id` | the `findings.csv` id; a comment that bundles several points gets `<id>-1`, `<id>-2` |
45
+ | `verdict` | `verified` (you read the code at that commit), `owner-accepted` (fixed after the comment), `answered` (a question with a checkable answer), `wrong`, `unverified` |
46
+ | `defect_severity` | `high`, `medium`, `low`, `none`: yours, not the tool's label |
47
+ | `difficulty` | 1 to 5: how hard for a human reviewer of the diff to find |
48
+ | `matched_by` | the other tool's finding id on the same defect, or empty |
49
+ | `judge` | the model that decided, e.g. `claude-fable-5-1` |
50
+ | `evidence` | `path:line` at the commit, or the fixing sha |
51
+
52
+ Then write `README.md` in the same folder, in this order:
53
+
54
+ 1. **One-minute block**: PRs, pairs, special cases, verified defects, and the one-line answer to
55
+ "what did the other tool find that Wachiman did not", with `basis` and the Wachiman versions
56
+ seen (from `pairs.csv`, not from memory: a footer never shows the version).
57
+ 2. **Pairs**: the `pairs.md` table, plus per pair what each tool found and the verdicts.
58
+ 3. **Gaps**: for each finding only the other tool made and you verified: what happens, why that
59
+ tool found it (its posted commands or cited files), severity, difficulty.
60
+ 4. **Special cases**: the `special-cases.csv` table ordered by what was lost: `refused` first (a
61
+ change merged with no Wachiman review), then `skipped`, `partial`, `unpaired`.
62
+ 5. **Cost**: Wachiman's sum from `pairs.csv`. The other tool's cost only when it published one;
63
+ otherwise "not published", never an estimate.
64
+ 6. **Limits**: days, PRs, repositories, who judged, what is still `unverified`.
65
+
66
+ Before pushing, check the audited repository's visibility (`gh repo view <owner/name> --json visibility`).
67
+ Public: open the result as a draft PR on `wachiman-benchmarks`. Private: the folder holds counts
68
+ only, no finding text, and the developer confirms before the push. Nothing about a comparison goes
69
+ under `wachiman/docs`.
70
+
71
+ ## Never
72
+
73
+ | Tempting | Instead |
74
+ | --- | --- |
75
+ | "Both tools reviewed the PR" | Both reviewed the **commit**: check `pairs.csv` |
76
+ | Counting a laptop rerun with the live runs | `basis: rerun`, special-cases section |
77
+ | Writing the Wachiman version from the release of the day | `wachiman_version` column: #535 ran v1.7.0 on the night v1.8.0 shipped |
78
+ | Guessing the other tool's cost | "not published" |
79
+ | Scoring a finding only one tool made and nobody verified | `unverified`, listed, not scored |
80
+ | Committing a private repository's findings to the benchmarks repo | Counts only: the posted findings quote the code, and wachiman-benchmarks is public |