@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.
Files changed (80) hide show
  1. package/README.md +12 -11
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/cli.mjs +28 -1
  7. package/dist/code-host/github-setup.mjs +1 -1
  8. package/dist/commands.d.mts +16 -0
  9. package/dist/commands.mjs +129 -0
  10. package/dist/config.d.mts +61 -13
  11. package/dist/config.mjs +271 -69
  12. package/dist/deps.d.mts +7 -4
  13. package/dist/deps.mjs +20 -9
  14. package/dist/doctor.d.mts +3 -2
  15. package/dist/doctor.mjs +19 -4
  16. package/dist/explain.d.mts +4 -2
  17. package/dist/explain.mjs +70 -23
  18. package/dist/guard-commit.d.mts +7 -2
  19. package/dist/guard-commit.mjs +58 -21
  20. package/dist/init.d.mts +4 -2
  21. package/dist/init.mjs +18 -8
  22. package/dist/lib/default-branch.d.mts +35 -0
  23. package/dist/lib/default-branch.mjs +117 -0
  24. package/dist/lib/refined-check.d.mts +7 -0
  25. package/dist/lib/refined-check.mjs +76 -0
  26. package/dist/lib/work-status.d.mts +2 -2
  27. package/dist/lib/work-status.mjs +4 -4
  28. package/dist/parts.d.mts +1 -1
  29. package/dist/parts.mjs +2 -2
  30. package/dist/patch-coverage.d.mts +13 -0
  31. package/dist/patch-coverage.mjs +73 -0
  32. package/dist/pr-watch.d.mts +3 -2
  33. package/dist/pr-watch.mjs +22 -5
  34. package/dist/pr.mjs +34 -2
  35. package/dist/review-cost.mjs +1 -1
  36. package/dist/review-tools.mjs +3 -3
  37. package/dist/session-start.d.mts +23 -13
  38. package/dist/session-start.mjs +56 -44
  39. package/dist/site/servers.d.mts +6 -2
  40. package/dist/site/servers.mjs +14 -9
  41. package/dist/site.mjs +2 -2
  42. package/dist/sync.d.mts +8 -2
  43. package/dist/sync.mjs +41 -7
  44. package/dist/ticket.mjs +19 -1
  45. package/docs/builds.md +8 -8
  46. package/docs/cli.md +82 -45
  47. package/docs/configuration.md +838 -565
  48. package/docs/design.md +17 -4
  49. package/docs/developing.md +44 -8
  50. package/docs/existing-repo.md +9 -7
  51. package/docs/github/by-hand.md +27 -14
  52. package/docs/github/reference.md +21 -16
  53. package/docs/github/setup.md +14 -11
  54. package/docs/glossary.md +14 -5
  55. package/docs/limitations.md +27 -2
  56. package/docs/plugins.md +307 -52
  57. package/docs/quick-start.md +37 -9
  58. package/docs/removing.md +2 -2
  59. package/docs/skills.md +103 -54
  60. package/docs/updating.md +149 -3
  61. package/docs/workflow.md +13 -10
  62. package/package.json +1 -1
  63. package/review.md +20 -11
  64. package/rules.md +23 -19
  65. package/settings.schema.json +292 -72
  66. package/skills/factory-address-review/SKILL.md +50 -30
  67. package/skills/factory-build/SKILL.md +76 -23
  68. package/skills/factory-deps/SKILL.md +46 -21
  69. package/skills/factory-design/SKILL.md +18 -9
  70. package/skills/factory-diagnose/SKILL.md +22 -20
  71. package/skills/factory-mutate/SKILL.md +38 -24
  72. package/skills/factory-refine/SKILL.md +55 -31
  73. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  74. package/skills/factory-trace/SKILL.md +3 -2
  75. package/workflows/factory-build.yml +1 -1
  76. package/workflows/factory-claude-review.yml +1 -1
  77. package/workflows/factory-conflicts.yml +8 -8
  78. package/workflows/factory-deps.yml +1 -1
  79. package/workflows/factory-review.yml +1 -1
  80. 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 your plug-ins by role | Built |
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 and waiting for your approval |
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 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 |
138
- | `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 |
139
- | `factory deps` | The open dependency pull requests, their checks, and what each needs |
140
- | `factory deps --any` | Exits 0 when a dependency pull request is open and 1 when none is |
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 | 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 |
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