dw-mc 0.2.0 → 0.3.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 -32
- package/dist/bin.js +2573 -2149
- package/dist/bin.js.map +1 -1
- package/package.json +20 -2
package/README.md
CHANGED
|
@@ -1,13 +1,36 @@
|
|
|
1
1
|
# dw-mc
|
|
2
2
|
|
|
3
|
-
Mission control for the pull requests you have open
|
|
3
|
+
**Mission control for the pull requests you have open** — one bucket per PR, reviewed by the agent CLIs already on your machine.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/dw-mc)
|
|
6
|
+
[](https://github.com/dominikwozniak/dw-mc/actions/workflows/quality-gate.yaml)
|
|
7
|
+
[](./LICENSE)
|
|
8
|
+
[](https://nodejs.org)
|
|
6
9
|
|
|
7
|
-
-
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
10
|
+
`dw-mc` keeps what it knows about each of your open pull requests on disk, reads GitHub through your own `gh`, runs code reviews through local agent CLIs, and sorts every pull request into the one bucket that says what it waits on.
|
|
11
|
+
|
|
12
|
+
- **One bucket per pull request** — _needs me_, _needs review run_, _waiting on others_, _ready_. Never two at once.
|
|
13
|
+
- **Reviews on the agent CLIs you already have** — Claude Code, the Codex CLI, or one as your bar and the other as a second opinion.
|
|
14
|
+
- **Nothing leaves the machine** — no server, no GitHub App, no webhooks. Only the GitHub calls you would have made yourself, and whatever the agent CLIs send their own providers.
|
|
15
|
+
- **State in plain files** — JSON and Markdown under XDG paths, readable without the tool.
|
|
16
|
+
- **A prompt, not a TUI** — the picker runs the command you would have typed, so nothing it does is hidden from you.
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
$ dw-mc status
|
|
20
|
+
|
|
21
|
+
Needs me
|
|
22
|
+
● dominikwozniak/dw-mc#71 │ feat(sweep): notice a head that moved under a run │ 2 blocking findings
|
|
23
|
+
|
|
24
|
+
Needs review run
|
|
25
|
+
◐ dominikwozniak/dw-mc#65 │ docs(agents): how a change becomes a release │ no review run on this head
|
|
26
|
+
◐ dominikwozniak/dw-mc#66 │ docs(skill): the CLI surface the skill actually has │ no review run on this head
|
|
27
|
+
|
|
28
|
+
Waiting on others
|
|
29
|
+
○ dominikwozniak/dw-mc#68 │ fix(rebase): keep the lease on a head that moved │ CI is still running
|
|
30
|
+
|
|
31
|
+
Ready
|
|
32
|
+
◆ dominikwozniak/dw-mc#62 ✓ │ feat(comments): read a pull request's threads │ approved, green, mergeable
|
|
33
|
+
```
|
|
11
34
|
|
|
12
35
|
## Install
|
|
13
36
|
|
|
@@ -17,45 +40,111 @@ pnpm add -g dw-mc
|
|
|
17
40
|
|
|
18
41
|
To look before installing, `pnpm dlx dw-mc --help` runs the same binary from a throwaway copy.
|
|
19
42
|
|
|
20
|
-
|
|
43
|
+
### Requirements
|
|
44
|
+
|
|
45
|
+
- Node 24 or newer
|
|
46
|
+
- [`gh`](https://cli.github.com), authenticated: `gh auth login`
|
|
47
|
+
- `git`
|
|
48
|
+
- [Claude Code](https://claude.com/claude-code) as `claude`, or the [Codex CLI](https://developers.openai.com/codex/cli) as `codex` — at least one, for review runs and the sessions they open
|
|
49
|
+
|
|
50
|
+
## Quick start
|
|
21
51
|
|
|
22
52
|
```sh
|
|
23
|
-
dw-mc init
|
|
53
|
+
dw-mc init # once on the machine, then once inside each repository you want followed
|
|
54
|
+
dw-mc # the picker: every tracked PR under its bucket, and the commands that move it
|
|
55
|
+
dw-mc review 62 # or drive any command straight
|
|
24
56
|
```
|
|
25
57
|
|
|
26
|
-
|
|
58
|
+
`init` asks which runner is your bar and whether Codex should give a second opinion beside it, then writes both answers to one file you can keep in your dotfiles.
|
|
27
59
|
|
|
28
|
-
|
|
60
|
+
Every command that takes a pull request takes it as `62` inside the repository, or as `owner/name#62` from anywhere.
|
|
29
61
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
62
|
+
## Commands
|
|
63
|
+
|
|
64
|
+
| Command | Flags | What it does |
|
|
65
|
+
| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
66
|
+
| `dw-mc` | — | Opens the picker: every tracked pull request under its bucket, and what moves the one you choose. |
|
|
67
|
+
| `dw-mc init` | `--runner`, `--codex`, `--effort`, `--base` | Sets this machine up and registers the repository you are in. |
|
|
68
|
+
| `dw-mc sweep` | — | Refreshes what mission control knows about every tracked pull request. It only reads. |
|
|
69
|
+
| `dw-mc status` | — | Shows which bucket every tracked pull request sits in, and which ones you have stamped. |
|
|
70
|
+
| `dw-mc comments <pr>` | `--all` | Prints the conversation on a pull request, and what in it is waiting on you. |
|
|
71
|
+
| `dw-mc review <pr>` | `--effort`, `--force` | Reviews one pull request on the configured runners, in a throwaway worktree. |
|
|
72
|
+
| `dw-mc findings <pr>` | `--runner`, `--json` | Prints what the current review run found. |
|
|
73
|
+
| `dw-mc fix <pr>` | `--print`, `--commit` | Opens a session on the findings you pick, in a worktree that outlives it. |
|
|
74
|
+
| `dw-mc stamp <pr>` | `--withdraw` | Prints your stamp on a pull request, or withdraws it by hand. |
|
|
75
|
+
| `dw-mc rebase <pr>` | — | Rebases a branch onto its base and pushes it with a lease. |
|
|
76
|
+
| `dw-mc resolve <pr>` | `--print` | Opens a session on the conflict that stopped a rebase. |
|
|
77
|
+
| `dw-mc rerun <pr>` | — | Runs a flaky red CI again, once per head. |
|
|
78
|
+
| `dw-mc merge <pr>` | — | Squash-merges a Ready, stamped pull request of yours and deletes its branch. |
|
|
79
|
+
| `dw-mc cleanup` | `--yes` | Takes back the disk spent on clones and review worktrees, and keeps everything you decided. |
|
|
80
|
+
| `dw-mc uninstall` | `--config`, `--force`, `--yes` | Removes everything the tool wrote on this machine, and says how to remove the binary. |
|
|
81
|
+
|
|
82
|
+
`dw-mc <command> --help` prints the flags and what each one is worth.
|
|
83
|
+
|
|
84
|
+
## How it works
|
|
33
85
|
|
|
34
|
-
|
|
86
|
+
A **bucket** is the one place a pull request sits at a time, named for what it waits on. The rules are tried in order and the first that claims the pull request wins, so a pull request that both needs a review run and has changes requested is yours to move, not the runner's.
|
|
35
87
|
|
|
36
|
-
|
|
88
|
+
| Bucket | Marker | It waits on |
|
|
89
|
+
| ----------------- | ------ | --------------------------------------------------------------------------------------- |
|
|
90
|
+
| Needs me | `●` | You: blocking findings, changes requested, a conflict, a red CI, an unanswered comment. |
|
|
91
|
+
| Needs review run | `◐` | A review run on this head. |
|
|
92
|
+
| Waiting on others | `○` | A reviewer who has not answered, or CI that is still running. |
|
|
93
|
+
| Ready | `◆` | Nothing. |
|
|
37
94
|
|
|
38
|
-
|
|
39
|
-
| --------------------- | --------------------------------------------------------------------------------------- |
|
|
40
|
-
| `dw-mc sweep` | Refreshes what mission control knows about every tracked pull request. It only reads. |
|
|
41
|
-
| `dw-mc status` | Shows which bucket every tracked pull request sits in, and which ones you have stamped. |
|
|
42
|
-
| `dw-mc comments <pr>` | Prints the conversation on a pull request, and what in it is waiting on you. |
|
|
43
|
-
| `dw-mc review <pr>` | Reviews one pull request on the configured runners, in a throwaway worktree. |
|
|
44
|
-
| `dw-mc findings <pr>` | Prints what the current review run found. |
|
|
45
|
-
| `dw-mc fix <pr>` | Opens a session on the findings you pick, in a worktree that outlives it. |
|
|
46
|
-
| `dw-mc stamp <pr>` | Prints your stamp on a pull request, or withdraws it by hand. |
|
|
47
|
-
| `dw-mc rebase <pr>` | Rebases a branch onto its base and pushes it with a lease. |
|
|
48
|
-
| `dw-mc resolve <pr>` | Opens a session on the conflict that stopped a rebase. |
|
|
49
|
-
| `dw-mc rerun <pr>` | Runs a flaky red CI again, once per head. |
|
|
95
|
+
A **stamp** is your own mark that a pull request has passed your bar. It lives on this machine and is never a GitHub approval — but `dw-mc merge` reads it, so a pull request you have not stamped does not merge.
|
|
50
96
|
|
|
51
|
-
A
|
|
97
|
+
A review run works in a worktree that is thrown away when the run ends. The worktree a `fix` or `resolve` session opens is left standing, on a branch of the tool's own, because the work you commit in it is yours.
|
|
52
98
|
|
|
53
|
-
|
|
99
|
+
Every other word this tool uses is defined in [`CONTEXT.md`](./CONTEXT.md), and the decisions behind them in [`docs/adr/`](./docs/adr).
|
|
100
|
+
|
|
101
|
+
## Configuration
|
|
54
102
|
|
|
55
103
|
- Configuration: `$XDG_CONFIG_HOME/dw-mc/config.yaml`, or `~/.config/dw-mc/config.yaml`
|
|
56
|
-
- State: `$XDG_STATE_HOME/dw-mc`, or `~/.local/state/dw-mc`
|
|
104
|
+
- State, including the worktrees: `$XDG_STATE_HOME/dw-mc`, or `~/.local/state/dw-mc`
|
|
105
|
+
|
|
106
|
+
`init` writes the file, and every key in it is optional: what it leaves out is inherited rather than reset, and `repos` overrides `defaults` in the same shape.
|
|
107
|
+
|
|
108
|
+
```yaml
|
|
109
|
+
launcher:
|
|
110
|
+
command: [claude] # program + argument prefix that starts Claude Code
|
|
111
|
+
fix_args: [] # flags only a fix session gets
|
|
112
|
+
codex: [codex] # program + argument prefix that starts the Codex CLI
|
|
113
|
+
defaults:
|
|
114
|
+
base: null # the default branch from gh when null
|
|
115
|
+
review:
|
|
116
|
+
runners: [builtin] # one or more of builtin | prompt | codex
|
|
117
|
+
effort: low # builtin only
|
|
118
|
+
model: null # prompt and codex only
|
|
119
|
+
skill: null # passed through as the first line of the tool's own prompt
|
|
120
|
+
docs_only: ["**/*.md", "docs/**"]
|
|
121
|
+
path_instructions: [] # [{ path: glob, instructions: text }]
|
|
122
|
+
ci:
|
|
123
|
+
ignore: [] # check names that do not count towards green
|
|
124
|
+
flaky_patterns: []
|
|
125
|
+
fix:
|
|
126
|
+
commits: false # whether a fix session may commit; --commit overrides it
|
|
127
|
+
rebase:
|
|
128
|
+
enabled: false
|
|
129
|
+
stamp:
|
|
130
|
+
blocks_on: error
|
|
131
|
+
supporting_blocks: false # whether a supporting runner's findings block
|
|
132
|
+
repos:
|
|
133
|
+
owner/name:
|
|
134
|
+
# the same keys, overriding defaults
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Taking it back
|
|
138
|
+
|
|
139
|
+
Removing the package removes the binary and nothing else — a package manager runs no uninstall script, so the two directories above would stay where they are. The tool takes them back itself.
|
|
57
140
|
|
|
58
|
-
|
|
141
|
+
```sh
|
|
142
|
+
dw-mc cleanup # the bare clones and the worktrees a review run left: disk the tool spends on itself
|
|
143
|
+
dw-mc uninstall # every record, report, clone and worktree
|
|
144
|
+
pnpm remove -g dw-mc
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Both print what they would take, with its weight, and ask before taking it; `--yes` answers for a machine with no terminal. `cleanup` keeps your configuration and every record, and keeps the clone of a repository a `fix` or `resolve` session still stands on, because that session's history lives inside it. `uninstall` keeps the configuration file too unless `--config` asks for it. A worktree a `fix` or `resolve` session left standing is yours: `cleanup` never touches one, and `uninstall` names what it still holds — uncommitted changes, or a commit your pull request's head does not have — and removes nothing until `--force`.
|
|
59
148
|
|
|
60
149
|
## The skill
|
|
61
150
|
|
|
@@ -65,6 +154,17 @@ An agent session can reach mission control's state through the `/dw-mc` skill, w
|
|
|
65
154
|
pnpm dlx skills@latest add dominikwozniak/dw-mc
|
|
66
155
|
```
|
|
67
156
|
|
|
68
|
-
##
|
|
157
|
+
## Contributing
|
|
158
|
+
|
|
159
|
+
```sh
|
|
160
|
+
pnpm install
|
|
161
|
+
pnpm check # lint, format, typecheck, test, build — the whole gate, and what CI runs
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Work lands on `main` through a pull request, on a branch named `type/<issue>-subject`, squash-merged under a [Conventional Commits](https://www.conventionalcommits.org) title. [`CONTRIBUTING.md`](./CONTRIBUTING.md) has the rest: what is worth an issue first, the layers a module belongs to, and when a change carries a changeset. Everyone taking part is held to the [Code of Conduct](./CODE_OF_CONDUCT.md).
|
|
165
|
+
|
|
166
|
+
Found a security issue? Do not open an issue — [`SECURITY.md`](./SECURITY.md) says how to report it privately.
|
|
167
|
+
|
|
168
|
+
## License
|
|
69
169
|
|
|
70
170
|
MIT. Third-party notices are in [`NOTICE.md`](./NOTICE.md).
|