@davidbyoung/software-factory 0.1.2 → 0.1.4
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 +20 -20
- package/actions/factory-agent/action.yml +1 -1
- package/agents/factory-e2e-reviewer.md +102 -0
- package/agents/factory-test-reviewer.md +26 -64
- package/agents/factory-ticket-readiness.md +14 -6
- package/dist/agent/claude-code.d.mts +3 -0
- package/dist/agent/claude-code.mjs +89 -0
- package/dist/agent/index.d.mts +2 -0
- package/dist/agent/index.mjs +5 -0
- package/dist/board.mjs +1 -1
- package/dist/cli.mjs +46 -4
- package/dist/code-host/github-setup.d.mts +5 -0
- package/dist/code-host/github-setup.mjs +133 -0
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/index.d.mts +1 -1
- package/dist/code-host/index.mjs +2 -1
- package/dist/code-host/types.d.mts +2 -0
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +87 -20
- package/dist/config.mjs +344 -89
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +9 -16
- package/dist/doctor.mjs +71 -68
- package/dist/explain.d.mts +4 -0
- package/dist/explain.mjs +174 -0
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +12 -14
- package/dist/init.mjs +194 -136
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/has-command.d.mts +5 -0
- package/dist/lib/has-command.mjs +8 -0
- package/dist/lib/listed.d.mts +2 -0
- package/dist/lib/listed.mjs +4 -0
- package/dist/lib/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -0
- package/dist/lib/work-status.d.mts +12 -2
- package/dist/lib/work-status.mjs +14 -3
- package/dist/parts.d.mts +18 -15
- package/dist/parts.mjs +15 -43
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/remove.d.mts +11 -0
- package/dist/remove.mjs +156 -0
- package/dist/runner/github-actions.d.mts +1 -1
- package/dist/runner/github-actions.mjs +12 -0
- package/dist/runner/index.d.mts +1 -1
- package/dist/runner/index.mjs +2 -1
- package/dist/runner/setup.d.mts +2 -0
- package/dist/runner/setup.mjs +22 -0
- package/dist/runner/types.d.mts +3 -0
- package/dist/runner/types.mjs +0 -2
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +26 -2
- package/dist/sync.mjs +177 -13
- package/dist/ticket.mjs +19 -1
- package/dist/tickets/github-setup.d.mts +2 -0
- package/dist/tickets/github-setup.mjs +50 -0
- package/dist/tickets/github.mjs +0 -2
- package/dist/tickets/index.mjs +2 -1
- package/dist/tickets/transport.mjs +1 -3
- package/dist/tickets/types.mjs +0 -2
- package/dist/tool-names.d.mts +11 -0
- package/dist/tool-names.mjs +20 -0
- package/dist/tools.d.mts +56 -0
- package/dist/tools.mjs +76 -0
- package/docs/builds.md +111 -59
- package/docs/cli.md +106 -69
- package/docs/configuration.md +489 -171
- package/docs/design.md +18 -5
- package/docs/developing.md +179 -73
- package/docs/existing-repo.md +25 -12
- package/docs/github/by-hand.md +334 -0
- package/docs/github/reference.md +76 -67
- package/docs/github/setup.md +105 -286
- package/docs/glossary.md +18 -7
- package/docs/limitations.md +39 -12
- package/docs/plugins.md +305 -56
- package/docs/quick-start.md +85 -100
- package/docs/removing.md +37 -17
- package/docs/skills.md +121 -62
- package/docs/updating.md +150 -9
- package/docs/workflow.md +23 -19
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/review.md +20 -11
- package/rules.md +36 -30
- package/settings.schema.json +313 -69
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +76 -23
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +17 -8
- package/skills/factory-diagnose/SKILL.md +22 -20
- package/skills/factory-mutate/SKILL.md +38 -24
- package/skills/factory-refine/SKILL.md +55 -31
- package/skills/factory-resolve-conflicts/SKILL.md +76 -34
- package/skills/factory-trace/SKILL.md +80 -0
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-poller.yml +46 -0
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/builds.md
CHANGED
|
@@ -6,7 +6,7 @@ the cloud does the same with nobody at the keyboard: it runs on your code
|
|
|
6
6
|
host's cloud runner, and you read its log or its pull request afterward.
|
|
7
7
|
|
|
8
8
|
On GitHub, the cloud runner is GitHub Actions.
|
|
9
|
-
[Setting up on GitHub](github/setup.md
|
|
9
|
+
[Setting up on GitHub](github/setup.md) has the steps,
|
|
10
10
|
and the [reference](github/reference.md#workflows) has what runs there.
|
|
11
11
|
|
|
12
12
|
## Three ways a build starts
|
|
@@ -15,16 +15,17 @@ and the [reference](github/reference.md#workflows) has what runs there.
|
|
|
15
15
|
| ----------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
|
|
16
16
|
| Ask a session: "build ticket 12" | In that session, wherever you opened it | Nothing |
|
|
17
17
|
| Run `factory build 12` | In the cloud | Builds in the cloud set up |
|
|
18
|
-
| Move the ticket to Ready on a board | In the cloud,
|
|
18
|
+
| Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
|
|
19
19
|
|
|
20
|
-
Which of the last two you use is
|
|
20
|
+
Which of the last two you use is
|
|
21
|
+
[`builds.trigger`](configuration.md#builds) in your
|
|
21
22
|
[settings](configuration.md#builds):
|
|
22
23
|
|
|
23
|
-
| `trigger` | Moving a ticket to Ready
|
|
24
|
-
| --------------- |
|
|
25
|
-
| `manual` | Records your approval and starts nothing. The default
|
|
26
|
-
| `own-server` | Starts a build within a minute, through the poller you host
|
|
27
|
-
| `github-action` |
|
|
24
|
+
| `trigger` | Moving a ticket to Ready |
|
|
25
|
+
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
26
|
+
| `manual` | Records your approval and starts nothing. The default |
|
|
27
|
+
| `own-server` | Starts a build within a minute, through the poller you host |
|
|
28
|
+
| `github-action` | Starts one at the next pass of a schedule on the cloud runner, every `poll-minutes` minutes, with nothing to host |
|
|
28
29
|
|
|
29
30
|
`manual` is a fine place to stay. Asking a session and running
|
|
30
31
|
`factory build` work whatever the trigger.
|
|
@@ -54,8 +55,9 @@ so a failed run does not hold its ticket.
|
|
|
54
55
|
|
|
55
56
|
**What it needs.** Two credentials, stored as secrets on the code host:
|
|
56
57
|
the agent's token, which pays for the session, and an access token for the
|
|
57
|
-
code host, which the build acts as.
|
|
58
|
-
|
|
58
|
+
code host, which the build acts as.
|
|
59
|
+
[`factory init`](github/setup.md#run-factory-init) asks for each and
|
|
60
|
+
stores it.
|
|
59
61
|
|
|
60
62
|
**Who it acts as.** The build acts as whoever owns that access token. Its
|
|
61
63
|
commits name your coding agent as their author and that account as their
|
|
@@ -70,8 +72,8 @@ the account the build acts as. Without one, its commits are unsigned.
|
|
|
70
72
|
commits is not shown as verified, when your own git signs commits.
|
|
71
73
|
|
|
72
74
|
**Before the session starts,** the commands under
|
|
73
|
-
[`build-setup`](configuration.md#
|
|
74
|
-
your npm dependencies are installed.
|
|
75
|
+
[`commands.build-setup`](configuration.md#commandsbuild-setup) in your
|
|
76
|
+
settings run, after your npm dependencies are installed.
|
|
75
77
|
|
|
76
78
|
## The other jobs that run in the cloud
|
|
77
79
|
|
|
@@ -80,11 +82,11 @@ anything to do and starts a session only when there is, so a run with
|
|
|
80
82
|
nothing to do costs about a minute of the runner and no use of the agent. A
|
|
81
83
|
run that works costs about what a build does.
|
|
82
84
|
|
|
83
|
-
| Job | Starts on
|
|
84
|
-
| ------------------------ |
|
|
85
|
-
| Answering your review | A review you submit on a pull request
|
|
86
|
-
| The conflict sweep | A push to your
|
|
87
|
-
| Dependency pull requests | Three times a day, or by hand
|
|
85
|
+
| Job | Starts on | What the session does |
|
|
86
|
+
| ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
87
|
+
| Answering your review | A review you submit on a pull request | Works your comments with `factory-address-review` |
|
|
88
|
+
| The conflict sweep | A push to your default branch, nightly, or by hand | Merges your default branch into each pull request that conflicts with it, with `factory-resolve-conflicts` |
|
|
89
|
+
| Dependency pull requests | Three times a day, or by hand | Moves each dependency update toward merged, with `factory-deps`, in a repository with a `.github/dependabot.yml` |
|
|
88
90
|
|
|
89
91
|
Each acts as the same account a build does. The review job answers your
|
|
90
92
|
reviews only: the factory's own replies start runs that find nothing of
|
|
@@ -92,13 +94,14 @@ yours in them and stop.
|
|
|
92
94
|
|
|
93
95
|
## The poller
|
|
94
96
|
|
|
95
|
-
The poller is a small program of the factory's
|
|
96
|
-
|
|
97
|
-
|
|
97
|
+
The poller is a small program of the factory's. It runs on a server you
|
|
98
|
+
host, reading your board once a minute and never exiting, or as one pass
|
|
99
|
+
at a time on a schedule in the cloud. Each time it reads the board, for
|
|
100
|
+
each ticket in Ready with no open blocker it:
|
|
98
101
|
|
|
99
102
|
1. posts a comment on the ticket saying a build is starting, carrying a
|
|
100
103
|
marker;
|
|
101
|
-
2. starts a build of that ticket in the cloud, from your
|
|
104
|
+
2. starts a build of that ticket in the cloud, from your default branch.
|
|
102
105
|
|
|
103
106
|
```bash
|
|
104
107
|
factory poller
|
|
@@ -111,9 +114,10 @@ does no further check.
|
|
|
111
114
|
|
|
112
115
|
### What it reads from its environment
|
|
113
116
|
|
|
114
|
-
|
|
115
|
-
from environment variables. All four are required; it
|
|
116
|
-
naming any that is missing.
|
|
117
|
+
On a server you host, the poller runs with no copy of your repository, so
|
|
118
|
+
it takes everything from environment variables. All four are required; it
|
|
119
|
+
exits at startup naming any that is missing. On a schedule it has a
|
|
120
|
+
checkout, and needs only the token.
|
|
117
121
|
|
|
118
122
|
| Variable | What it is |
|
|
119
123
|
| ---------------------- | ------------------------------------------------------------------- |
|
|
@@ -122,10 +126,11 @@ naming any that is missing.
|
|
|
122
126
|
| `FACTORY_BOARD_NUMBER` | Which board |
|
|
123
127
|
| `FACTORY_BOARD_TOKEN` | An access token that can read the board, comment, and start a build |
|
|
124
128
|
|
|
125
|
-
One more is optional. `FACTORY_READY_COLUMN` is the name of the column
|
|
126
|
-
approves a build, and defaults to Ready. The poller has no settings
|
|
127
|
-
so a repository whose
|
|
128
|
-
|
|
129
|
+
One more is optional. `FACTORY_READY_COLUMN` is the name of the column
|
|
130
|
+
that approves a build, and defaults to Ready. The poller has no settings
|
|
131
|
+
file, so a repository whose
|
|
132
|
+
[`tickets.columns.ready`](configuration.md#ticketscolumns) names another
|
|
133
|
+
column sets it where the poller runs. `factory board check` reminds you
|
|
129
134
|
when it applies.
|
|
130
135
|
|
|
131
136
|
The repository and the board's number repeat what your settings file says,
|
|
@@ -135,8 +140,9 @@ a board owned by another account is not supported yet.
|
|
|
135
140
|
|
|
136
141
|
### Its limits
|
|
137
142
|
|
|
138
|
-
- **It starts at most 20 builds an hour
|
|
139
|
-
|
|
143
|
+
- **It starts at most 20 builds an hour,** counted from the start comments
|
|
144
|
+
it posted, so a restart or a scheduled pass still knows them. A ticket
|
|
145
|
+
past that waits, and the poller's log says so. Each build may run as long as
|
|
140
146
|
[`session-minutes`](configuration.md#session-minutes) allows, so several
|
|
141
147
|
can run at once: each pays for its own minutes, and the cloud runner
|
|
142
148
|
limits how many run at the same time.
|
|
@@ -151,25 +157,39 @@ a board owned by another account is not supported yet.
|
|
|
151
157
|
The poller needs one always-on container with outbound network access and
|
|
152
158
|
half a gigabyte of memory. It serves no traffic.
|
|
153
159
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
160
|
+
Each release of the factory publishes the poller as a container image,
|
|
161
|
+
`ghcr.io/davidbyoung/software-factory-poller`, tagged with its version and
|
|
162
|
+
`latest`. It holds nothing but Node and that version of the factory, runs
|
|
163
|
+
as an unprivileged user, and needs no sign-in to pull. Run the version your
|
|
164
|
+
repository installs, with the variables above; `factory init` prints the
|
|
165
|
+
exact line. To try it on your machine:
|
|
157
166
|
|
|
158
167
|
```bash
|
|
159
|
-
docker build -f poller.Dockerfile -t factory-poller .
|
|
160
168
|
docker run \
|
|
161
169
|
-e FACTORY_REPOSITORY=your-name/your-repo \
|
|
162
170
|
-e FACTORY_BOARD_OWNER=your-name \
|
|
163
171
|
-e FACTORY_BOARD_NUMBER=1 \
|
|
164
172
|
-e FACTORY_BOARD_TOKEN \
|
|
165
|
-
factory-poller
|
|
173
|
+
ghcr.io/davidbyoung/software-factory-poller:0.2.0
|
|
166
174
|
```
|
|
167
175
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
176
|
+
**A host that builds from your repository,** rather than running an image,
|
|
177
|
+
needs a Dockerfile there. Add one of a single line, such as
|
|
178
|
+
`poller/Dockerfile`:
|
|
179
|
+
|
|
180
|
+
```dockerfile
|
|
181
|
+
FROM ghcr.io/davidbyoung/software-factory-poller:0.2.0
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
and this entry in `.github/dependabot.yml`, so each new version of the
|
|
185
|
+
factory updates it, alongside the factory's own update:
|
|
186
|
+
|
|
187
|
+
```yaml
|
|
188
|
+
- package-ecosystem: docker
|
|
189
|
+
directory: /poller
|
|
190
|
+
schedule:
|
|
191
|
+
interval: weekly
|
|
192
|
+
```
|
|
173
193
|
|
|
174
194
|
As an example, one setup runs it as a worker on DigitalOcean's App
|
|
175
195
|
Platform, in the same app as the site it builds, for about $5 a month. Its
|
|
@@ -184,33 +204,65 @@ the factory never deploys it.
|
|
|
184
204
|
|
|
185
205
|
| What you see | What happened | What to do |
|
|
186
206
|
| --------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
187
|
-
| `factory status` flags a Ready ticket "not started"
|
|
188
|
-
| A comment saying a build could not start, with a refusal from the code host | The token cannot start a build | Give it what [
|
|
207
|
+
| `factory status` flags a Ready ticket "not started, is the poller running?" | The poller is down or stuck | Read its log |
|
|
208
|
+
| A comment saying a build could not start, with a refusal from the code host | The token cannot start a build | Give it what [Secrets](github/by-hand.md#secrets) names, then move the ticket to Ready again |
|
|
189
209
|
| The board stops updating | The board's token is missing or expired | Replace it. The poller uses the same token |
|
|
190
|
-
| A ticket in Ready is skipped | It is blocked by an open ticket | It starts
|
|
191
|
-
|
|
192
|
-
## A scheduled poller: `github-action` _[Planned](developing.md#what-is-built)_
|
|
210
|
+
| A ticket in Ready is skipped | It is blocked by an open ticket | It starts at the poller's first pass after the blocker closes |
|
|
193
211
|
|
|
194
|
-
|
|
212
|
+
## A scheduled poller: `github-action`
|
|
195
213
|
|
|
196
|
-
For a repository with nowhere to run a container.
|
|
197
|
-
|
|
214
|
+
For a repository with nowhere to run a container. `factory sync` writes a
|
|
215
|
+
workflow, `factory-poller.yml`, that runs one pass of the poller on a
|
|
216
|
+
schedule, and by hand:
|
|
198
217
|
|
|
199
218
|
```bash
|
|
200
219
|
factory poller --once
|
|
201
220
|
```
|
|
202
221
|
|
|
203
|
-
It
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
-
|
|
213
|
-
|
|
222
|
+
It reads your board and the Ready column from your settings, and the
|
|
223
|
+
board's token from the secret the board sync already uses. Each build it
|
|
224
|
+
starts is a run of its own, so several build at once, as with the poller
|
|
225
|
+
you host. Two passes never overlap: a late one waits for the one before.
|
|
226
|
+
|
|
227
|
+
It is slower and can cost more than the poller you host, so know how
|
|
228
|
+
before choosing it:
|
|
229
|
+
|
|
230
|
+
- **It starts a build at its next pass.** The schedule runs every
|
|
231
|
+
`builds.poll-minutes` minutes, 5 at the fastest, and the cloud runner
|
|
232
|
+
starts scheduled runs late when it is busy: at 5, a build starts 5 to 15
|
|
233
|
+
minutes after the card moves, and longer at a longer interval.
|
|
234
|
+
- **It costs Actions minutes on a private repository.** Each pass is billed
|
|
235
|
+
as at least a minute, whether or not a card was Ready. A public
|
|
236
|
+
repository pays nothing.
|
|
237
|
+
|
|
238
|
+
| `poll-minutes` | Passes a month |
|
|
239
|
+
| -------------- | -------------- |
|
|
240
|
+
| 5, the default | 8,640 |
|
|
241
|
+
| 10 | 4,320 |
|
|
242
|
+
| 15 | 2,880 |
|
|
243
|
+
| 30 | 1,440 |
|
|
244
|
+
| 60 | 720 |
|
|
245
|
+
|
|
246
|
+
`factory init` asks the interval on a private repository, suggesting 30.
|
|
247
|
+
|
|
248
|
+
- **The code host can switch a schedule off** in a public repository that
|
|
249
|
+
goes quiet. `factory doctor` fails when it has, and says how to switch it
|
|
250
|
+
back on.
|
|
251
|
+
|
|
252
|
+
`factory status` flags a Ready card "not started, is the factory-poller
|
|
253
|
+
workflow running?" once it has waited the interval and 15 minutes more.
|
|
254
|
+
|
|
255
|
+
**Moving from a poller you host to the schedule,** stop the one you host:
|
|
256
|
+
both would start builds, and each start comment counts toward the 20 an
|
|
257
|
+
hour.
|
|
258
|
+
|
|
259
|
+
### When the schedule fails
|
|
260
|
+
|
|
261
|
+
| What you see | What happened | What to do |
|
|
262
|
+
| -------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------ |
|
|
263
|
+
| `factory status` flags a Ready ticket "not started, is the factory-poller workflow running?" | The workflow failed, or the code host switched it off | Run `factory doctor`, and read the workflow's last run |
|
|
264
|
+
| `factory doctor` says `factory-poller.yml is disabled` | The code host switched the schedule off in a quiet repository | Do what `doctor` says to switch it back on |
|
|
265
|
+
| A failed run of the workflow saying `not polling: FACTORY_BOARD_TOKEN not set` | The board's token is not a secret here | Run `factory init` to add it |
|
|
214
266
|
|
|
215
267
|
[The reference](github/reference.md#limits) has GitHub's own numbers.
|
|
216
268
|
|
package/docs/cli.md
CHANGED
|
@@ -26,14 +26,14 @@ such as "refine ticket 12". [Skills](skills.md) lists them.
|
|
|
26
26
|
|
|
27
27
|
## Setting up
|
|
28
28
|
|
|
29
|
-
| Command | When you run it
|
|
30
|
-
| ---------------------- |
|
|
31
|
-
| `factory init` | Once, to set a repository up. Again, to turn a part on or off
|
|
32
|
-
| `factory sync` | After installing, updating, or editing `.claude/factory.yaml`
|
|
33
|
-
| `factory sync --check` | To see that the factory's files match your settings. It also runs in CI
|
|
34
|
-
| `factory config check` | To validate your settings. It also runs in CI
|
|
35
|
-
| `factory board check` | After pointing `tickets.board` at your board, to see how it reads it
|
|
36
|
-
| `factory doctor` | When something seems off. It checks the settings, files, version, secrets, and
|
|
29
|
+
| Command | When you run it |
|
|
30
|
+
| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
31
|
+
| `factory init` | Once, to set a repository up. Again, to turn a part on or off |
|
|
32
|
+
| `factory sync` | After installing, updating, or editing `.claude/factory.yaml` |
|
|
33
|
+
| `factory sync --check` | To see that the factory's files match your settings. It also runs in CI |
|
|
34
|
+
| `factory config check` | To validate your settings. It also runs in CI |
|
|
35
|
+
| `factory board check` | After pointing [`tickets.board`](configuration.md#tickets) at your board, to see how it reads it |
|
|
36
|
+
| `factory doctor` | When something seems off. It checks the settings, files, version, secrets, board, and each tool's own setup |
|
|
37
37
|
|
|
38
38
|
`init` asks its questions in the terminal, and reads each token in a
|
|
39
39
|
masked prompt. `doctor` exits 1 when a check fails. GitHub never lets a
|
|
@@ -51,18 +51,22 @@ read is set.
|
|
|
51
51
|
|
|
52
52
|
## Now and then
|
|
53
53
|
|
|
54
|
-
| Command | When you run it | State
|
|
55
|
-
| ------------------------ | ----------------------------------------------------------------- |
|
|
56
|
-
| `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built
|
|
57
|
-
| `factory config explain` | To see every setting in effect, defaults included |
|
|
58
|
-
| `factory plugins` | To see
|
|
59
|
-
| `factory site compare` | To picture a website's pages before and after a change. See below | Built
|
|
60
|
-
| `factory site stop` | To end the sites `compare --keep` left running | Built
|
|
61
|
-
| `factory remove` | To take the factory out of a repository |
|
|
54
|
+
| Command | When you run it | State |
|
|
55
|
+
| ------------------------ | ----------------------------------------------------------------- | ----- |
|
|
56
|
+
| `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
|
|
57
|
+
| `factory config explain` | To see every setting in effect, defaults included | Built |
|
|
58
|
+
| `factory plugins` | To see the plug-ins the factory will use, by slot | Built |
|
|
59
|
+
| `factory site compare` | To picture a website's pages before and after a change. See below | Built |
|
|
60
|
+
| `factory site stop` | To end the sites `compare --keep` left running | Built |
|
|
61
|
+
| `factory remove` | To take the factory out of a repository | Built |
|
|
62
|
+
|
|
63
|
+
`factory plugins` prints one line for each plug-in, the factory's own
|
|
64
|
+
included: its kind, its name, its [slot](plugins.md#the-slots), then its
|
|
65
|
+
files or labels. `factory plugins SLOT` prints one slot's lines.
|
|
62
66
|
|
|
63
67
|
A new version is installed with npm and applied with `factory sync`, as
|
|
64
|
-
[Updating](updating.md) says
|
|
65
|
-
|
|
68
|
+
[Updating](updating.md) says. [Removing](removing.md) says what `remove`
|
|
69
|
+
deletes and what it leaves to you.
|
|
66
70
|
|
|
67
71
|
## Run for you
|
|
68
72
|
|
|
@@ -102,42 +106,48 @@ ticket system would swallow, name it, and post nothing.
|
|
|
102
106
|
| `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
|
|
103
107
|
| `factory ticket refining N` | Marks N as being refined |
|
|
104
108
|
| `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
|
|
105
|
-
| `factory ticket refined N` | Marks N as refined
|
|
109
|
+
| `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
|
|
106
110
|
| `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
|
|
107
111
|
| `factory ticket cost N` | Notes what this session spent on N since it started |
|
|
108
112
|
| `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
|
|
109
113
|
|
|
114
|
+
`factory ticket refined N` posts nothing and exits 1 when N's body lacks a
|
|
115
|
+
section a build reads, printing one line for each, such as
|
|
116
|
+
`missing: ## Acceptance criteria`. With `--check` it prints `sound` for a
|
|
117
|
+
body that passes. [Plug-ins](plugins.md#refiner) lists the sections.
|
|
118
|
+
|
|
110
119
|
### Pull requests
|
|
111
120
|
|
|
112
121
|
Pull requests stay on the code host whatever the ticket system. A pull
|
|
113
122
|
request's conversation comments and labels go through these, never the
|
|
114
123
|
ticket system.
|
|
115
124
|
|
|
116
|
-
| Command | What it does
|
|
117
|
-
| ------------------------------------------------ |
|
|
118
|
-
| `factory pr state [N]` | What stands between N and a merge: checks, review, threads, conflict
|
|
119
|
-
| `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too
|
|
120
|
-
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread
|
|
121
|
-
| `factory pr resolve N COMMENT` | Resolves a thread
|
|
122
|
-
| `factory pr closes N` | The tickets N closes
|
|
123
|
-
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks`
|
|
124
|
-
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified
|
|
125
|
-
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at`
|
|
126
|
-
| `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does
|
|
127
|
-
| `factory pr comment-view ID` | Prints one conversation comment's body
|
|
128
|
-
| `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off
|
|
129
|
-
| `factory pr watch N` | Waits until N needs attention, says why, and exits
|
|
130
|
-
| `factory pr watch N --release` | Stops watching N
|
|
131
|
-
| `factory pr review-pending N REVIEW` | Exits 0 when the owner's review has something of theirs to answer, and 1, saying why, when it has not
|
|
132
|
-
| `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none
|
|
133
|
-
| `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open
|
|
134
|
-
| `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out)
|
|
135
|
-
| `factory pr review N REVIEW` | One review as JSON: its author, its body, and each comment it left on a line, with the comment a reply replies to
|
|
136
|
-
| `factory pr unverified N` | Each of N's commits the code host does not show as signed, with the reason. Prints nothing when it shows them all
|
|
137
|
-
| `factory pr
|
|
138
|
-
| `factory pr
|
|
139
|
-
| `factory
|
|
140
|
-
| `factory deps
|
|
125
|
+
| Command | What it does |
|
|
126
|
+
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| `factory pr state [N]` | What stands between N and a merge: checks, review, threads, conflict |
|
|
128
|
+
| `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
|
|
129
|
+
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
|
|
130
|
+
| `factory pr resolve N COMMENT` | Resolves a thread |
|
|
131
|
+
| `factory pr closes N` | The tickets N closes |
|
|
132
|
+
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
|
|
133
|
+
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
|
|
134
|
+
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
|
|
135
|
+
| `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does |
|
|
136
|
+
| `factory pr comment-view ID` | Prints one conversation comment's body |
|
|
137
|
+
| `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
138
|
+
| `factory pr watch N` | Waits until N needs attention, says why, and exits |
|
|
139
|
+
| `factory pr watch N --release` | Stops watching N |
|
|
140
|
+
| `factory pr review-pending N REVIEW` | Exits 0 when the owner's review has something of theirs to answer, and 1, saying why, when it has not |
|
|
141
|
+
| `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none |
|
|
142
|
+
| `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open |
|
|
143
|
+
| `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out) |
|
|
144
|
+
| `factory pr review N REVIEW` | One review as JSON: its author, its body, and each comment it left on a line, with the comment a reply replies to |
|
|
145
|
+
| `factory pr unverified N` | Each of N's commits the code host does not show as signed, with the reason. Prints nothing when it shows them all |
|
|
146
|
+
| `factory pr uncovered [BASE] [LCOV]` | The lines the branch added or changed that the coverage report shows no test covers, a file at a time: `MISS` for a line no test ran, and `PART` for a line that ran with a branch never taken. `BASE` is what the branch is compared with, and is the default branch on `origin` when left out. `LCOV` is the report, and is `coverage/lcov.info` when left out. Prints nothing when every such line is covered |
|
|
147
|
+
| `factory pr failed N` | For N's last commit, the failures `wait-checks` counts: each failed job's name and the last 200 lines of its log, from the newest run of each workflow started by a push or a pull request, and what a check that did not pass wrote about itself. Prints nothing when nothing failed |
|
|
148
|
+
| `factory pr review-again N` | Asks for a fresh review of N's last commit. Exits 1, saying so, when no review has run on it |
|
|
149
|
+
| `factory deps` | The open dependency pull requests, their checks, and what each needs |
|
|
150
|
+
| `factory deps --any` | Exits 0 when a dependency pull request is open and 1 when none is |
|
|
141
151
|
|
|
142
152
|
`factory pr wait-checks N` waits until the code host
|
|
143
153
|
shows the commit you pushed as N's head, then until the newest run of each
|
|
@@ -146,26 +156,50 @@ the factory's own jobs, so a failed board sync does not stop a pull
|
|
|
146
156
|
request being marked ready. With no run two minutes after the commit became the head, it
|
|
147
157
|
prints `no checks` and exits 0. A failure exits 3.
|
|
148
158
|
|
|
159
|
+
### Your repository's commands
|
|
160
|
+
|
|
161
|
+
Skills call these to check and test a change, so no skill names a test
|
|
162
|
+
runner or a linter: each runs what your settings list under
|
|
163
|
+
[`commands`](configuration.md#commands) and
|
|
164
|
+
[`specs`](configuration.md#specs), with bash, from the repository's root.
|
|
165
|
+
You can run them too.
|
|
166
|
+
|
|
167
|
+
| Command | What it does |
|
|
168
|
+
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
169
|
+
| `factory gate` | Runs each [`commands.gate`](configuration.md#commandsgate) command in order, printing `$` and the command before each. Stops at the first that fails, with `gate failed on:` and the command. Exits 0 when every command passes, and 1 at the first that fails or when no gate is set |
|
|
170
|
+
| `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
|
|
171
|
+
| `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails |
|
|
172
|
+
| `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status. Prints `specs are off` when `specs` is `none` |
|
|
173
|
+
| `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
|
|
174
|
+
|
|
175
|
+
`factory default-branch` asks, in turn, the event of the workflow run it
|
|
176
|
+
is in, `origin/HEAD` in your checkout, and the code host, whose answer it
|
|
177
|
+
writes to `origin/HEAD` so the next run asks nobody. A checkout with no
|
|
178
|
+
`origin` remote takes git's own `init.defaultBranch`, or `main`. When a
|
|
179
|
+
remote exists and none of the three answers, it exits 1 with
|
|
180
|
+
`Could not tell the default branch. Run: git remote set-head origin --auto`.
|
|
181
|
+
`factory sync` and `factory site compare` stop with the same line, and
|
|
182
|
+
the commit hook blocks a session's git command with it.
|
|
183
|
+
|
|
149
184
|
### Workflows and hooks
|
|
150
185
|
|
|
151
|
-
| Command
|
|
152
|
-
|
|
|
153
|
-
| `factory
|
|
154
|
-
| `factory board
|
|
155
|
-
| `factory board
|
|
156
|
-
| `factory
|
|
157
|
-
| `factory
|
|
158
|
-
| `factory review
|
|
159
|
-
| `factory review
|
|
160
|
-
| `factory
|
|
161
|
-
| `factory poller`
|
|
162
|
-
| `factory
|
|
163
|
-
| `factory guard`
|
|
164
|
-
| `factory guard
|
|
165
|
-
| `factory
|
|
166
|
-
| `factory reviewers
|
|
167
|
-
| `factory
|
|
168
|
-
| `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
|
|
186
|
+
| Command | Run by | What it does | State |
|
|
187
|
+
| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
|
|
188
|
+
| `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
|
|
189
|
+
| `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
|
|
190
|
+
| `factory board --dry-run` | You, to see what it would set | Reads the tickets and the board, prints what the sync would set, and writes nothing | Built |
|
|
191
|
+
| `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
|
|
192
|
+
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
|
|
193
|
+
| `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
|
|
194
|
+
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
|
|
195
|
+
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
|
|
196
|
+
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
|
|
197
|
+
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
|
|
198
|
+
| `factory guard commit` | Within `factory guard` | Blocks a commit on your default branch, a push to it, a force push, or a commit while a [`commands.before-commit`](configuration.md#commandsbefore-commit) command fails | Built |
|
|
199
|
+
| `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
|
|
200
|
+
| `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
|
|
201
|
+
| `factory reviewers stop` | A hook, when an agent stops | The same | Built |
|
|
202
|
+
| `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
|
|
169
203
|
|
|
170
204
|
The board sync runs `collect` and `apply` as two steps, so the board's
|
|
171
205
|
token reaches only the second. The board's number comes from
|
|
@@ -175,7 +209,9 @@ token reaches only the second. The board's number comes from
|
|
|
175
209
|
|
|
176
210
|
- `0`: done, or the answer is the line printed.
|
|
177
211
|
- `2`: no such command; the usage is printed. A guard also exits 2 when it
|
|
178
|
-
blocks a call
|
|
212
|
+
blocks a call, and so does one of
|
|
213
|
+
[your repository's commands](#your-repositorys-commands) given an
|
|
214
|
+
argument it does not know.
|
|
179
215
|
- `3`: `pr wait-checks` saw a check fail.
|
|
180
216
|
- Any other non-zero: it could not do it, and the reason is on standard
|
|
181
217
|
error. A command that could not reach the code host or the ticket system
|
|
@@ -183,13 +219,14 @@ token reaches only the second. The board's number comes from
|
|
|
183
219
|
|
|
184
220
|
## `factory site`
|
|
185
221
|
|
|
186
|
-
`factory site compare` starts the working tree with
|
|
187
|
-
default branch from a
|
|
188
|
-
|
|
189
|
-
|
|
222
|
+
`factory site compare` starts the working tree with
|
|
223
|
+
[`site.start`](configuration.md#site), starts the default branch from a
|
|
224
|
+
temporary git worktree on another port, shoots each page at each width in
|
|
225
|
+
light and dark, and prints the pages that changed, with the pixels and
|
|
226
|
+
rows. It writes the pictures before, after, and with what changed
|
|
190
227
|
outlined, and `report.json`, under `node_modules/.cache/factory/site/`. It
|
|
191
|
-
exits 0 whether or not anything changed, and non-zero only when it could
|
|
192
|
-
its job.
|
|
228
|
+
exits 0 whether or not anything changed, and non-zero only when it could
|
|
229
|
+
not do its job.
|
|
193
230
|
|
|
194
231
|
- **Three measurements** are made on each view that changed, a view being one
|
|
195
232
|
page at one width in one scheme, on the base and on the branch, and only what
|