@davidbyoung/software-factory 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +205 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. package/workflows/factory-review.yml +75 -0
package/docs/cli.md ADDED
@@ -0,0 +1,221 @@
1
+ # The CLI
2
+
3
+ `factory` is the command-line tool. Skills, hooks, and workflows call it for
4
+ everything that must give the same answer every time. You will run a few
5
+ of these yourself; most are run for you.
6
+
7
+ Run any command as `factory`, from the global install the
8
+ [quick start](quick-start.md#1-install) sets up. Run in a repository, it
9
+ hands the run to the copy that repository installed, so each repository
10
+ keeps its own version; in a repository with none, it says how to install
11
+ one and exits 1. `factory` with no command, or one it does not have, prints
12
+ the list of commands it has and exits non-zero.
13
+
14
+ > **Without the global install, type `npx --no-install factory`.** Another
15
+ > package on npm is called `factory`. Where this one is not installed, `npx`
16
+ > without `--no-install` offers to download and run that one instead; with
17
+ > it, `npx` fails. The factory's own skills, hooks, and workflows always
18
+ > run it that way, since they cannot count on a global install.
19
+
20
+ A table with a State column has commands still to come, marked
21
+ **Planned**; every command in a table without one is built.
22
+ [What is built](developing.md#what-is-built) lists the parts.
23
+
24
+ The skills are not commands: you ask a session for one in plain words,
25
+ such as "refine ticket 12". [Skills](skills.md) lists them.
26
+
27
+ ## Setting up
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 board |
37
+
38
+ `init` asks its questions in the terminal, and reads each token in a
39
+ masked prompt. `doctor` exits 1 when a check fails. GitHub never lets a
40
+ secret be read back, so `doctor` checks only that each secret your parts
41
+ read is set.
42
+
43
+ ## Every day
44
+
45
+ | Command | When you run it |
46
+ | ------------------------ | ------------------------------------------------------- |
47
+ | `factory status` | To see each ticket's state and which session is on it |
48
+ | `factory status --watch` | The same, read again every 15 seconds |
49
+ | `factory build N` | To build ticket N in the cloud. Prints the run's link |
50
+ | `factory pr watch N` | To wait until pull request N needs you, and be told why |
51
+
52
+ ## Now and then
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 | Planned |
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 | Planned |
62
+
63
+ A new version is installed with npm and applied with `factory sync`, as
64
+ [Updating](updating.md) says; until `remove` is built,
65
+ [Removing](removing.md) lists what to delete by hand.
66
+
67
+ ## Run for you
68
+
69
+ The rest are run by the skills, the hooks, and the workflows, not by you.
70
+ They are listed so nothing the factory does is hidden.
71
+
72
+ ### Tickets
73
+
74
+ Skills call these to read or change a ticket. Every one goes through one
75
+ interface, which is what lets another ticket system be added later:
76
+ [Developing](developing.md#adding-a-ticket-system) explains it. Each exits
77
+ non-zero with the error when it cannot reach the ticket system: a failed
78
+ read is never an empty answer. `view` and `list` take `--json`, which
79
+ prints what the ticket system returned as one JSON value. `edit`,
80
+ `comment`, and `open` refuse a body with a bare tag-like `<word>` the
81
+ ticket system would swallow, name it, and post nothing.
82
+
83
+ | Command | What it does |
84
+ | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
85
+ | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
86
+ | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
87
+ | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
88
+ | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
89
+ | `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
90
+ | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
91
+ | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
92
+ | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
93
+ | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
94
+ | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
95
+ | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
96
+ | `factory ticket block N --by M` | Records that N waits on M |
97
+ | `factory ticket unblock N --by M` | Removes that record |
98
+ | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
99
+ | `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
100
+ | `factory ticket still-live N` | Says whether this session still holds N |
101
+ | `factory ticket stop N "reason"` | Releases N and says why |
102
+ | `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
+ | `factory ticket refining N` | Marks N as being refined |
104
+ | `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 |
106
+ | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
107
+ | `factory ticket cost N` | Notes what this session spent on N since it started |
108
+ | `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
+
110
+ ### Pull requests
111
+
112
+ Pull requests stay on the code host whatever the ticket system. A pull
113
+ request's conversation comments and labels go through these, never the
114
+ ticket system.
115
+
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 |
141
+
142
+ `factory pr wait-checks N` waits until the code host
143
+ shows the commit you pushed as N's head, then until the newest run of each
144
+ CI job started by that push or pull request has finished. It leaves out
145
+ the factory's own jobs, so a failed board sync does not stop a pull
146
+ request being marked ready. With no run two minutes after the commit became the head, it
147
+ prints `no checks` and exits 0. A failure exits 3.
148
+
149
+ ### Workflows and hooks
150
+
151
+ | Command | Run by | What it does | State |
152
+ | ------------------------------ | ----------------------------- | --------------------------------------------------------------------------------------- | ------- |
153
+ | `factory migrate` | `factory-deps`, on an update | Converts your settings after a release changes their shape | Planned |
154
+ | `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
155
+ | `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
156
+ | `factory board sync --dry-run` | You, to see what it would set | The same, writing nothing | Planned |
157
+ | `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
158
+ | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
159
+ | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
160
+ | `factory review tools` | The review workflow | Prints the tools the CI review may use, from `ci-review.commands` | Built |
161
+ | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
162
+ | `factory poller --once` | A schedule | One pass of the poller | Planned |
163
+ | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
164
+ | `factory guard commit` | Within `factory guard` | Blocks a commit on your main branch, a force push, or a failing `before-commit` command | Built |
165
+ | `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
166
+ | `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
167
+ | `factory reviewers stop` | A hook, when an agent stops | The same | Built |
168
+ | `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
169
+
170
+ The board sync runs `collect` and `apply` as two steps, so the board's
171
+ token reaches only the second. The board's number comes from
172
+ `tickets.board` in your settings.
173
+
174
+ ## Exit codes
175
+
176
+ - `0`: done, or the answer is the line printed.
177
+ - `2`: no such command; the usage is printed. A guard also exits 2 when it
178
+ blocks a call.
179
+ - `3`: `pr wait-checks` saw a check fail.
180
+ - Any other non-zero: it could not do it, and the reason is on standard
181
+ error. A command that could not reach the code host or the ticket system
182
+ always exits non-zero.
183
+
184
+ ## `factory site`
185
+
186
+ `factory site compare` starts the working tree with `site.start`, starts the
187
+ default branch from a temporary git worktree on another port, shoots each page
188
+ at each width in light and dark, and prints the pages that changed, with the
189
+ pixels and rows. It writes the pictures before, after, and with what changed
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 not do
192
+ its job.
193
+
194
+ - **Three measurements** are made on each view that changed, a view being one
195
+ page at one width in one scheme, on the base and on the branch, and only what
196
+ got worse prints, one `measured:` line each after the table, beside the lines
197
+ your `site.checks` print, and the same in `report.json`:
198
+ - **Accessibility,** by axe-core at the level `site.accessibility` names
199
+ (`wcag22aa` by default), including text contrast and the standard's target
200
+ size. A failure is new when the base has none of the same rule on an
201
+ element with the same selector or the same markup.
202
+ - **A page that scrolls sideways** on the branch and not on the base.
203
+ - **A new style value:** a font size, color, spacing, or corner radius that
204
+ the base uses in no view of that scheme. It is a fact to weigh, not a
205
+ failure. `site.new-values: false` leaves it out.
206
+
207
+ ```text
208
+ measured: /about/ 390 light: accessibility color-contrast: p.intro: Element has insufficient color contrast of 2.5 (foreground color: #9aa5b4, ...). Expected contrast ratio of 4.5:1
209
+ measured: /about/ 390 light: sideways scroll: the page is 412 px wide in a 390 px window
210
+ measured: /about/ 390 light: new value: font-size 15px on h2 "Background"; the site uses 12, 14, 16, 18, 24, 30, and 36 px
211
+ ```
212
+
213
+ A page the base does not have is measured alone, and everything found on it
214
+ is new. A view whose pictures did not change is not measured.
215
+
216
+ - `--base REF` compares against something other than the default branch.
217
+ - `--keep` leaves both sites running and prints their addresses, for a state
218
+ that takes a click to reach. `factory site stop` ends them and removes the
219
+ worktree.
220
+ - `--before URL --after URL` compares two sites that are already running and
221
+ starts nothing. One without the other is refused.