@davidbyoung/software-factory 0.1.2 → 0.1.3
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 +8 -9
- 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 +17 -2
- 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/config.d.mts +26 -7
- package/dist/config.mjs +79 -26
- package/dist/doctor.d.mts +6 -14
- package/dist/doctor.mjs +52 -64
- package/dist/explain.d.mts +2 -0
- package/dist/explain.mjs +127 -0
- package/dist/init.d.mts +8 -12
- package/dist/init.mjs +179 -131
- 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/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/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- 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/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +18 -0
- package/dist/sync.mjs +137 -7
- 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 +103 -51
- package/docs/cli.md +42 -42
- package/docs/configuration.md +34 -32
- package/docs/design.md +1 -1
- package/docs/developing.md +143 -68
- package/docs/existing-repo.md +20 -9
- package/docs/github/by-hand.md +321 -0
- package/docs/github/reference.md +65 -61
- package/docs/github/setup.md +83 -267
- package/docs/glossary.md +5 -4
- package/docs/limitations.md +12 -10
- package/docs/plugins.md +9 -14
- package/docs/quick-start.md +62 -105
- package/docs/removing.md +36 -16
- package/docs/skills.md +47 -37
- package/docs/updating.md +2 -6
- package/docs/workflow.md +13 -12
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/rules.md +14 -12
- package/settings.schema.json +24 -0
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-trace/SKILL.md +79 -0
- package/workflows/factory-build.yml +5 -4
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-poller.yml +46 -0
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
|
|
@@ -92,9 +94,10 @@ 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;
|
|
@@ -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,18 @@ 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 your plug-ins by role | 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 |
|
|
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 your plug-ins by role | 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
62
|
|
|
63
63
|
A new version is installed with npm and applied with `factory sync`, as
|
|
64
|
-
[Updating](updating.md) says
|
|
65
|
-
|
|
64
|
+
[Updating](updating.md) says. [Removing](removing.md) says what `remove`
|
|
65
|
+
deletes and what it leaves to you.
|
|
66
66
|
|
|
67
67
|
## Run for you
|
|
68
68
|
|
|
@@ -148,24 +148,23 @@ prints `no checks` and exits 0. A failure exits 3.
|
|
|
148
148
|
|
|
149
149
|
### Workflows and hooks
|
|
150
150
|
|
|
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 |
|
|
151
|
+
| Command | Run by | What it does | State |
|
|
152
|
+
| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
|
|
153
|
+
| `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
|
|
154
|
+
| `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
|
|
155
|
+
| `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 |
|
|
156
|
+
| `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
|
|
157
|
+
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
|
|
158
|
+
| `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
|
|
159
|
+
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
|
|
160
|
+
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
|
|
161
|
+
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
|
|
162
|
+
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
|
|
163
|
+
| `factory guard commit` | Within `factory guard` | Blocks a commit on your main branch, a force push, or a failing [`before-commit`](configuration.md#before-commit) command | Built |
|
|
164
|
+
| `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
|
|
165
|
+
| `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
|
|
166
|
+
| `factory reviewers stop` | A hook, when an agent stops | The same | Built |
|
|
167
|
+
| `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
|
|
169
168
|
|
|
170
169
|
The board sync runs `collect` and `apply` as two steps, so the board's
|
|
171
170
|
token reaches only the second. The board's number comes from
|
|
@@ -183,13 +182,14 @@ token reaches only the second. The board's number comes from
|
|
|
183
182
|
|
|
184
183
|
## `factory site`
|
|
185
184
|
|
|
186
|
-
`factory site compare` starts the working tree with
|
|
187
|
-
default branch from a
|
|
188
|
-
|
|
189
|
-
|
|
185
|
+
`factory site compare` starts the working tree with
|
|
186
|
+
[`site.start`](configuration.md#site), starts the default branch from a
|
|
187
|
+
temporary git worktree on another port, shoots each page at each width in
|
|
188
|
+
light and dark, and prints the pages that changed, with the pixels and
|
|
189
|
+
rows. It writes the pictures before, after, and with what changed
|
|
190
190
|
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.
|
|
191
|
+
exits 0 whether or not anything changed, and non-zero only when it could
|
|
192
|
+
not do its job.
|
|
193
193
|
|
|
194
194
|
- **Three measurements** are made on each view that changed, a view being one
|
|
195
195
|
page at one width in one scheme, on the base and on the branch, and only what
|
package/docs/configuration.md
CHANGED
|
@@ -48,7 +48,7 @@ default.
|
|
|
48
48
|
- **A board,** to see every ticket's state. Set `tickets.board` to your
|
|
49
49
|
board's number, and when your columns have other names, map them under
|
|
50
50
|
`tickets.columns`. [`tickets`](#tickets) has both. On GitHub,
|
|
51
|
-
[Setting up on GitHub](github/setup.md
|
|
51
|
+
[Setting up on GitHub](github/setup.md) has the steps around
|
|
52
52
|
them.
|
|
53
53
|
- **What merges without you.** List the files that may under
|
|
54
54
|
`auto-merge.allow`, such as your docs. [`auto-merge`](#auto-merge).
|
|
@@ -145,8 +145,9 @@ state.
|
|
|
145
145
|
when you tell a session to build the ticket or run
|
|
146
146
|
`factory build N`, so
|
|
147
147
|
`factory config check` requires `builds.trigger: manual`.
|
|
148
|
-
- **If a repository's `ready` column has another name,**
|
|
149
|
-
too: see `FACTORY_READY_COLUMN` in [Builds](builds.md).
|
|
148
|
+
- **If a repository's `ready` column has another name,** a poller you host
|
|
149
|
+
needs it too: see `FACTORY_READY_COLUMN` in [Builds](builds.md). A
|
|
150
|
+
scheduled one reads it from here.
|
|
150
151
|
- `factory config get tickets.columns.ready` prints the
|
|
151
152
|
name in effect, or `none`.
|
|
152
153
|
|
|
@@ -206,8 +207,6 @@ It reads no board.
|
|
|
206
207
|
else. Only `github` is built. Any other value fails
|
|
207
208
|
`factory config check` and every ticket command with:
|
|
208
209
|
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
209
|
-
A type that names a package, for an adapter you write yourself, is
|
|
210
|
-
planned, not built.
|
|
211
210
|
|
|
212
211
|
### `code-host`
|
|
213
212
|
|
|
@@ -237,10 +236,11 @@ builds:
|
|
|
237
236
|
runner: github-actions
|
|
238
237
|
```
|
|
239
238
|
|
|
240
|
-
| Key
|
|
241
|
-
|
|
|
242
|
-
| `trigger`
|
|
243
|
-
| `runner`
|
|
239
|
+
| Key | Meaning | Allowed | Default |
|
|
240
|
+
| -------------- | -------------------------------------------------------------------- | --------------------------------------- | ---------------- |
|
|
241
|
+
| `trigger` | What starts a build for a ticket you moved to Ready | `own-server`, `github-action`, `manual` | `manual` |
|
|
242
|
+
| `runner` | Where a build in the cloud runs | `github-actions` | `github-actions` |
|
|
243
|
+
| `poll-minutes` | How often the scheduled poller reads the board, with `github-action` | 5, 10, 15, 30, or 60 | 5 |
|
|
244
244
|
|
|
245
245
|
`trigger` is what notices a card moved to Ready, and `runner` is where the
|
|
246
246
|
build it starts then runs: a poller on your own server still starts its
|
|
@@ -251,13 +251,17 @@ the settings and reaches the runner, with:
|
|
|
251
251
|
|
|
252
252
|
- **`manual`:** nothing watches the board. You tell a session "work 12".
|
|
253
253
|
- **`own-server`:** a small poller you host reads the board once a minute.
|
|
254
|
-
- **`github-action`:** a schedule on the cloud runner does the same
|
|
255
|
-
|
|
256
|
-
|
|
254
|
+
- **`github-action`:** a schedule on the cloud runner does the same every
|
|
255
|
+
`poll-minutes` minutes, with nothing to host. On a private repository,
|
|
256
|
+
each pass is billed as at least an Actions minute.
|
|
257
257
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
258
|
+
`factory config check` fails on `poll-minutes` beside any other trigger,
|
|
259
|
+
and on any value but the five above.
|
|
260
|
+
|
|
261
|
+
[Builds](builds.md) explains each. **If no poller is running,** a ticket
|
|
262
|
+
moved to Ready sits there, and `factory status` flags it "not started":
|
|
263
|
+
after 5 minutes with `own-server`, and after `poll-minutes` and 15 more
|
|
264
|
+
with `github-action`.
|
|
261
265
|
|
|
262
266
|
### `specs`
|
|
263
267
|
|
|
@@ -518,8 +522,7 @@ The automated review of every pull request: Claude reads each one once it
|
|
|
518
522
|
is marked ready, comments on what it finds, and posts a verdict. It is on
|
|
519
523
|
while `ci-review` is written, even with nothing under it, and `factory
|
|
520
524
|
sync` then writes its workflow, `.github/workflows/factory-claude-review.yml`.
|
|
521
|
-
[
|
|
522
|
-
it needs on GitHub.
|
|
525
|
+
[Setting up on GitHub](github/setup.md) has what it needs on GitHub.
|
|
523
526
|
|
|
524
527
|
```yaml
|
|
525
528
|
# The automated review of every pull request, on while this is written.
|
|
@@ -569,10 +572,9 @@ and never takes one as an instruction.
|
|
|
569
572
|
|
|
570
573
|
### `rules`
|
|
571
574
|
|
|
572
|
-
_[Planned](developing.md#what-is-built)_: `factory config check`
|
|
573
|
-
refuses this key until it is built.
|
|
574
|
-
|
|
575
575
|
Numbers the process rules use, for a repository that wants different ones.
|
|
576
|
+
`factory sync` writes each into the copies of the rules and skills that
|
|
577
|
+
state it, so run it after changing one.
|
|
576
578
|
|
|
577
579
|
```yaml
|
|
578
580
|
rules:
|
|
@@ -580,10 +582,10 @@ rules:
|
|
|
580
582
|
review-rounds: 2
|
|
581
583
|
```
|
|
582
584
|
|
|
583
|
-
| Key | Meaning
|
|
584
|
-
| -------------------- |
|
|
585
|
-
| `small-change-lines` | A change under this many lines
|
|
586
|
-
| `review-rounds` | Rounds a session works a review before it hands what is left to you
|
|
585
|
+
| Key | Meaning | Default |
|
|
586
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- |
|
|
587
|
+
| `small-change-lines` | A change under this many lines outside tests, specs, and content, adding no component and no state, takes the lighter path | `30` |
|
|
588
|
+
| `review-rounds` | Rounds a session works a review before it hands what is left to you | `2` |
|
|
587
589
|
|
|
588
590
|
- **If a value is not a whole number above zero:**
|
|
589
591
|
`factory config check` fails and names the key.
|
|
@@ -594,12 +596,12 @@ factory's rules.
|
|
|
594
596
|
|
|
595
597
|
## Checking the file
|
|
596
598
|
|
|
597
|
-
| Command | What it does
|
|
598
|
-
| ------------------------ |
|
|
599
|
-
| Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it
|
|
600
|
-
| `factory config check` | Fails on an unknown key, a wrong type, a plug-in with no file, and warns on a pattern matching nothing. Runs in CI
|
|
601
|
-
| `factory config explain` |
|
|
602
|
-
| `factory doctor` | Checks the file against the real board, and that each secret your parts read is set
|
|
599
|
+
| Command | What it does |
|
|
600
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
|
|
601
|
+
| Your editor | The first line of the file points at the factory's schema, which flags a misspelled key as you type it |
|
|
602
|
+
| `factory config check` | Fails on an unknown key, a wrong type, a plug-in with no file, and warns on a pattern matching nothing. Runs in CI |
|
|
603
|
+
| `factory config explain` | Prints every setting in effect, as the file would read with every default written out, each default marked `# default` |
|
|
604
|
+
| `factory doctor` | Checks the file against the real board, and that each secret your parts read is set |
|
|
603
605
|
|
|
604
606
|
The first line of the file, which the three files below start with:
|
|
605
607
|
|
|
@@ -802,8 +804,8 @@ auto-merge:
|
|
|
802
804
|
```
|
|
803
805
|
|
|
804
806
|
If this team moved its tickets to Jira, only the `tickets` block would
|
|
805
|
-
change. **
|
|
806
|
-
|
|
807
|
+
change. **Only GitHub is built**; the block below shows the shape the
|
|
808
|
+
design leaves room for.
|
|
807
809
|
|
|
808
810
|
```yaml
|
|
809
811
|
tickets:
|
package/docs/design.md
CHANGED
|
@@ -87,7 +87,7 @@ They are separate on purpose.
|
|
|
87
87
|
|
|
88
88
|
| Number | Where it is | Changes when |
|
|
89
89
|
| ------------------- | -------------------------------------------- | ------------------------------------ |
|
|
90
|
-
| The factory's |
|
|
90
|
+
| The factory's | The installed package and `factory.lock` | Every release |
|
|
91
91
|
| The settings file's | `version:` at the top of `factory.yaml` | A key is renamed or moved |
|
|
92
92
|
| The markers' | In the comments the factory posts on tickets | The format of those comments changes |
|
|
93
93
|
|