@davidbyoung/software-factory 0.1.3 → 0.1.5
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 +12 -11
- 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/cli.mjs +28 -1
- package/dist/code-host/github-setup.mjs +1 -1
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +61 -13
- package/dist/config.mjs +271 -69
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +3 -2
- package/dist/doctor.mjs +19 -4
- package/dist/explain.d.mts +4 -2
- package/dist/explain.mjs +70 -23
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +4 -2
- package/dist/init.mjs +18 -8
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -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 +2 -2
- package/dist/lib/work-status.mjs +4 -4
- package/dist/parts.d.mts +1 -1
- package/dist/parts.mjs +2 -2
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/review-cost.mjs +1 -1
- package/dist/review-tools.mjs +3 -3
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/sync.d.mts +8 -2
- package/dist/sync.mjs +41 -7
- package/dist/ticket.mjs +19 -1
- package/docs/builds.md +8 -8
- package/docs/cli.md +82 -45
- package/docs/configuration.md +838 -565
- package/docs/design.md +17 -4
- package/docs/developing.md +44 -8
- package/docs/existing-repo.md +9 -7
- package/docs/github/by-hand.md +27 -14
- package/docs/github/reference.md +21 -16
- package/docs/github/setup.md +14 -11
- package/docs/glossary.md +14 -5
- package/docs/limitations.md +27 -2
- package/docs/plugins.md +307 -52
- package/docs/quick-start.md +37 -9
- package/docs/removing.md +2 -2
- package/docs/skills.md +103 -54
- package/docs/updating.md +149 -3
- package/docs/workflow.md +13 -10
- package/package.json +1 -1
- package/review.md +20 -11
- package/rules.md +23 -19
- package/settings.schema.json +292 -72
- 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 +18 -9
- 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 +3 -2
- package/workflows/factory-build.yml +1 -1
- package/workflows/factory-claude-review.yml +1 -1
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/cli.md
CHANGED
|
@@ -55,11 +55,15 @@ read is set.
|
|
|
55
55
|
| ------------------------ | ----------------------------------------------------------------- | ----- |
|
|
56
56
|
| `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
|
|
57
57
|
| `factory config explain` | To see every setting in effect, defaults included | Built |
|
|
58
|
-
| `factory plugins` | To see
|
|
58
|
+
| `factory plugins` | To see the plugins the factory will use, by role | Built |
|
|
59
59
|
| `factory site compare` | To picture a website's pages before and after a change. See below | Built |
|
|
60
60
|
| `factory site stop` | To end the sites `compare --keep` left running | Built |
|
|
61
61
|
| `factory remove` | To take the factory out of a repository | Built |
|
|
62
62
|
|
|
63
|
+
`factory plugins` prints one line for each plugin, the factory's own
|
|
64
|
+
included: its kind, its name, its [role](plugins.md#the-roles), then its
|
|
65
|
+
files or labels. `factory plugins ROLE` prints one role's lines.
|
|
66
|
+
|
|
63
67
|
A new version is installed with npm and applied with `factory sync`, as
|
|
64
68
|
[Updating](updating.md) says. [Removing](removing.md) says what `remove`
|
|
65
69
|
deletes and what it leaves to you.
|
|
@@ -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. [Plugins](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,25 +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 | Run by | What it does
|
|
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
|
|
154
|
-
| `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments
|
|
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
|
|
156
|
-
| `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why
|
|
157
|
-
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit
|
|
158
|
-
| `factory review cost` | The review workflow | Adds what the CI review cost to its summary
|
|
159
|
-
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`
|
|
160
|
-
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md)
|
|
161
|
-
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings
|
|
162
|
-
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call
|
|
163
|
-
| `factory guard commit` | Within `factory guard` | Blocks a commit on your
|
|
164
|
-
| `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow
|
|
165
|
-
| `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost
|
|
166
|
-
| `factory reviewers stop` | A hook, when an agent stops | The same
|
|
167
|
-
| `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state
|
|
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 [`pr-review.commands`](configuration.md#pr-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 |
|
|
168
203
|
|
|
169
204
|
The board sync runs `collect` and `apply` as two steps, so the board's
|
|
170
205
|
token reaches only the second. The board's number comes from
|
|
@@ -174,7 +209,9 @@ token reaches only the second. The board's number comes from
|
|
|
174
209
|
|
|
175
210
|
- `0`: done, or the answer is the line printed.
|
|
176
211
|
- `2`: no such command; the usage is printed. A guard also exits 2 when it
|
|
177
|
-
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.
|
|
178
215
|
- `3`: `pr wait-checks` saw a check fail.
|
|
179
216
|
- Any other non-zero: it could not do it, and the reason is on standard
|
|
180
217
|
error. A command that could not reach the code host or the ticket system
|