@davidbyoung/software-factory 0.1.7 → 0.1.9

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 (63) hide show
  1. package/README.md +2 -0
  2. package/dist/agent/claude-code.mjs +15 -21
  3. package/dist/board.d.mts +20 -3
  4. package/dist/board.mjs +126 -38
  5. package/dist/cli.mjs +75 -9
  6. package/dist/code-host/github-setup.mjs +2 -2
  7. package/dist/code-host/github.mjs +4 -0
  8. package/dist/code-host/types.d.mts +2 -0
  9. package/dist/columns-suggest.d.mts +0 -1
  10. package/dist/columns-suggest.mjs +2 -8
  11. package/dist/commands.d.mts +2 -0
  12. package/dist/commands.mjs +22 -11
  13. package/dist/config.d.mts +12 -0
  14. package/dist/config.mjs +62 -11
  15. package/dist/doctor.d.mts +9 -1
  16. package/dist/doctor.mjs +209 -20
  17. package/dist/explain.d.mts +5 -0
  18. package/dist/explain.mjs +29 -0
  19. package/dist/init.d.mts +2 -0
  20. package/dist/init.mjs +143 -13
  21. package/dist/lib/color.d.mts +11 -0
  22. package/dist/lib/color.mjs +15 -0
  23. package/dist/npmrc.d.mts +29 -0
  24. package/dist/npmrc.mjs +98 -0
  25. package/dist/preset-commands.d.mts +2 -2
  26. package/dist/preset-commands.mjs +20 -24
  27. package/dist/preset.d.mts +4 -0
  28. package/dist/preset.mjs +13 -2
  29. package/dist/runner/github-actions.mjs +47 -10
  30. package/dist/runner/types.d.mts +13 -0
  31. package/dist/setup.d.mts +6 -1
  32. package/dist/site.d.mts +3 -0
  33. package/dist/site.mjs +8 -1
  34. package/dist/status.d.mts +5 -2
  35. package/dist/status.mjs +13 -22
  36. package/dist/sync.d.mts +14 -1
  37. package/dist/sync.mjs +83 -7
  38. package/dist/ticket-fields.d.mts +84 -0
  39. package/dist/ticket-fields.mjs +374 -0
  40. package/dist/ticket.mjs +8 -7
  41. package/dist/tickets/github-setup.mjs +1 -1
  42. package/dist/tickets/github.mjs +69 -0
  43. package/dist/tickets/index.d.mts +8 -1
  44. package/dist/tickets/index.mjs +67 -7
  45. package/dist/tickets/types.d.mts +27 -1
  46. package/dist/tickets/types.mjs +4 -0
  47. package/dist/tools.d.mts +1 -1
  48. package/docs/cli.md +44 -10
  49. package/docs/configuration.md +78 -25
  50. package/docs/design.md +10 -0
  51. package/docs/developing.md +49 -18
  52. package/docs/existing-repo.md +137 -8
  53. package/docs/github/by-hand.md +4 -0
  54. package/docs/github/reference.md +5 -0
  55. package/docs/github/setup.md +146 -8
  56. package/docs/limitations.md +0 -3
  57. package/docs/presets.md +5 -9
  58. package/docs/quick-start.md +3 -3
  59. package/docs/skills.md +3 -1
  60. package/docs/updating.md +3 -3
  61. package/package.json +4 -2
  62. package/settings.schema.json +68 -11
  63. package/skills/factory-deps/SKILL.md +4 -0
@@ -15,6 +15,11 @@ it leaves for you to do.
15
15
  | Claude Code, signed in | `claude --version` | [Install it](https://claude.com/claude-code), run `claude`, and sign in |
16
16
  | Node 22.18 or later | `node --version` | [nodejs.org](https://nodejs.org) |
17
17
 
18
+ `factory init` stops before its first question when Claude Code isn't
19
+ installed, and changes nothing. It needs Claude Code to set up the
20
+ coding agent's token, and to suggest your board's columns and your
21
+ tickets' fields.
22
+
18
23
  ## Run `factory init`
19
24
 
20
25
  In your repository, with the package
@@ -42,13 +47,14 @@ machine, which is all the [quick start](../quick-start.md) needs.
42
47
 
43
48
  It then asks only what your parts need:
44
49
 
45
- | Question | Asked when you chose | What you do |
46
- | ------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
47
- | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
48
- | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
49
- | Where the poller runs | Builds that start from the board | Choose a schedule on GitHub Actions or a server you host. [Builds in the cloud](../builds.md) compares them |
50
- | The token `claude setup-token` prints | The review, and builds in the cloud | It runs the command for you. Follow what it says, then paste the token it prints |
51
- | A GitHub access token | A board, builds in the cloud, and pull requests that merge themselves | It opens GitHub's page with the right scopes checked. Choose an expiry, generate the token, and paste it |
50
+ | Question | Asked when you chose | What you do |
51
+ | ------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
52
+ | Which board | A board | Choose a new one, made with the factory's columns, or a Project you already have |
53
+ | Which files may merge without you | Pull requests that merge themselves | Type their patterns, such as `docs/**`. Start with a short list |
54
+ | Where the poller runs | Builds that start from the board | Choose a schedule on GitHub Actions or a server you host. [Builds in the cloud](../builds.md) compares them |
55
+ | The token `claude setup-token` prints | The review, and builds in the cloud | It runs the command for you. Follow what it says, then paste the token it prints |
56
+ | A GitHub access token | A board, builds in the cloud, and pull requests that merge themselves | It opens GitHub's page with the right scopes checked. Choose an expiry, generate the token, and paste it |
57
+ | The token your `.npmrc` reads | Nothing: it asks whenever `.npmrc` reads one ([Private npm packages](#private-npm-packages)) | Paste a token that can only read from your registry |
52
58
 
53
59
  A token is typed into a masked prompt and goes straight to your
54
60
  repository's secrets on GitHub. It is never printed or written to a file.
@@ -120,10 +126,142 @@ factory doctor
120
126
 
121
127
  runs the checks again at any time: the settings, the factory's files, the
122
128
  installed version, who the GitHub CLI is signed in as, that each secret
123
- your parts read is set, and the board's columns. GitHub never lets a
129
+ your parts read is set, those for
130
+ [private npm packages](#private-npm-packages), and the board's columns. GitHub never lets a
124
131
  secret be read back, so a wrong one shows when the first run that needs it
125
132
  fails, naming it.
126
133
 
134
+ ## Private npm packages
135
+
136
+ For a repository that installs a package from a private registry, such as
137
+ your company's own packages or a private [preset](../presets.md). At the
138
+ end, the factory's workflows install it as your machine does, and
139
+ Dependabot offers its new versions.
140
+
141
+ ### 1. Read the token from a variable in `.npmrc`
142
+
143
+ The workflows sign in to your registry the way npm does on your machine:
144
+ from the `.npmrc` at the root of your repository, which you commit. It
145
+ needs two lines, one that sends your packages' scope to the registry and
146
+ one that reads the token from an environment variable:
147
+
148
+ ```ini
149
+ @acme:registry=https://acme.jfrog.io/artifactory/api/npm/npm/
150
+ //acme.jfrog.io/artifactory/api/npm/npm/:_authToken=${NPM_TOKEN}
151
+ ```
152
+
153
+ Your registry's documentation gives both lines with its own address. The
154
+ variable can have any name; the factory stores the token as a secret of
155
+ the same name, so wherever this section says `NPM_TOKEN`, use yours. On
156
+ your machine, set the variable in your shell's profile, such as
157
+ `export NPM_TOKEN=...`. If the token line is only in your own
158
+ `~/.npmrc`, move it into this file with the variable in place of the
159
+ token: the workflows read only this one.
160
+
161
+ **It worked when** `npm ci` succeeds on your machine with the variable
162
+ set.
163
+
164
+ #### GitHub Packages
165
+
166
+ Read `${GITHUB_TOKEN}` in the token line. In the workflows it is their own
167
+ token, which can read the packages that give this repository access, so
168
+ `init` asks for nothing and you skip step 2. On your machine, set
169
+ `GITHUB_TOKEN` to a personal access token with the `read:packages` scope.
170
+ Dependabot has no token of its own for it: in step 4, store that personal
171
+ access token with `gh secret set PACKAGES_TOKEN --app dependabot`, and
172
+ name `PACKAGES_TOKEN` in place of `NPM_TOKEN`.
173
+
174
+ ### 2. Make a read-only token
175
+
176
+ On your registry, make a token that can only read, and only the packages
177
+ this repository installs. Builds and reviews in the cloud hold it while
178
+ they work, and they read tickets and pull requests that anyone with access
179
+ to the repository can write, so a read-only token is all that text could
180
+ ever lead one to give away.
181
+
182
+ ### 3. Store it with `factory init`
183
+
184
+ ```bash
185
+ factory init
186
+ ```
187
+
188
+ Under "Found", `init` lists `.npmrc` and the variable it reads. Then it
189
+ asks you to paste the token, rewrites the factory's workflows under
190
+ `.github/workflows/` to pass the token to npm, and stores it twice: as an
191
+ Actions secret, and as a Dependabot secret, since a workflow that
192
+ Dependabot's pull request starts can read only Dependabot secrets. If
193
+ `.npmrc` isn't listed under "Found", the token line is missing from the
194
+ file at your repository's root.
195
+
196
+ If your organization already shares the secret with this repository,
197
+ `init` does not ask for the Actions copy. It still asks for the Dependabot
198
+ copy, since only an organization admin can see whether the organization
199
+ sets that one: leave it empty if yours does. To set both once for every
200
+ repository, an organization admin runs:
201
+
202
+ ```bash
203
+ gh secret set NPM_TOKEN --org acme --visibility all
204
+ gh secret set NPM_TOKEN --org acme --visibility all --app dependabot
205
+ ```
206
+
207
+ ### 4. Tell Dependabot the registry
208
+
209
+ Skip this without a `.github/dependabot.yml`, or when your organization
210
+ sets the registry for Dependabot, which an organization admin can tell
211
+ you. Otherwise add the registry, and name it in your npm entry, or
212
+ Dependabot never sees a new version of a package from there:
213
+
214
+ ```yaml
215
+ registries:
216
+ acme: # any name; the npm entry uses it
217
+ type: npm-registry
218
+ url: https://acme.jfrog.io/artifactory/api/npm/npm/ # as in .npmrc
219
+ token: ${{secrets.NPM_TOKEN}} # the Dependabot secret from step 3
220
+ updates:
221
+ - package-ecosystem: npm
222
+ directory: /
223
+ registries: [acme]
224
+ schedule:
225
+ interval: weekly
226
+ ```
227
+
228
+ ### 5. Check it, and merge
229
+
230
+ Run `factory doctor`. **It worked when** it shows:
231
+
232
+ ```text
233
+ ✓ NPM_TOKEN is set, for installing what .npmrc names
234
+ ✓ NPM_TOKEN is set for Dependabot, for installing on Dependabot's pull requests
235
+ ✓ .github/dependabot.yml uses https://acme.jfrog.io/artifactory/api/npm/npm/ for its npm updates
236
+ ```
237
+
238
+ Without a `.github/dependabot.yml` there is no third line. A line that
239
+ starts with `?` is one `doctor` cannot check from the repository, such as
240
+ a secret or a registry your organization may set, which only an
241
+ organization admin can see. It fails nothing.
242
+
243
+ Then commit `.npmrc` and what `init` wrote on a branch, open a pull
244
+ request, and merge it as any other change. The pull request's own
245
+ "Factory check" is the last check: its "Install dependencies" step passes
246
+ once the workflows can sign in.
247
+
248
+ ### Replacing the token
249
+
250
+ When the token expires, the next workflow fails at `npm ci` with a 401.
251
+ Store the new one in both places:
252
+
253
+ ```bash
254
+ gh secret set NPM_TOKEN
255
+ gh secret set NPM_TOKEN --app dependabot
256
+ ```
257
+
258
+ or run `factory init` and answer yes when it asks to replace the secrets
259
+ already set. An organization admin runs the two commands in step 3
260
+ again instead.
261
+
262
+ If you rename the variable in `.npmrc`, the factory's commands stop and
263
+ say to run `factory sync`, which rewrites the workflows for the new name.
264
+
127
265
  ## Doing it by hand
128
266
 
129
267
  [Setting up on GitHub by hand](by-hand.md) has every step `init` takes,
@@ -48,9 +48,6 @@ as a code host's billing or what its workflows can see, are in
48
48
  then guards the old branch and not the new one. After the rename, run
49
49
  that command in each checkout, then `factory sync`, which writes the
50
50
  name into two workflows.
51
- - **A private [preset](presets.md) works on your machine, not yet in the
52
- factory's workflows.** _[Planned](developing.md#what-is-built)_: the
53
- workflows can't install a private package yet.
54
51
  - **One lock file is rebuilt for you after a conflict,** the one
55
52
  [`commands.relock`](configuration.md#commandsrelock) rebuilds, npm's by
56
53
  default. A second, such as another package manager's beside the
package/docs/presets.md CHANGED
@@ -391,16 +391,12 @@ it gets a pull request at its dependency bot's next run, as
391
391
 
392
392
  A preset is an npm package, so a private one installs on your machine the
393
393
  way any other private package does, from whichever registry your company
394
- uses, through your repository's `.npmrc`. Give the preset a Dependabot
395
- group of its own, the way
394
+ uses, through your repository's `.npmrc`.
395
+ [Private npm packages](github/setup.md#private-npm-packages) sets up the
396
+ factory's workflows and Dependabot to install it too. Give the preset a
397
+ Dependabot group of its own as well, the way
396
398
  [Dependency bots](github/reference.md#dependency-bots) does for the
397
- factory, and add its registry under `registries` in
398
- `.github/dependabot.yml`, so Dependabot sees its new versions.
399
- `factory preset add` names either one that's missing.
400
-
401
- _[Planned](developing.md#what-is-built)_: the factory's workflows can't
402
- install a private package yet, so a private preset works on your machine
403
- and not yet in the factory's workflows.
399
+ factory. `factory preset add` names what's missing.
404
400
 
405
401
  **It worked when** `factory doctor` shows:
406
402
 
@@ -12,7 +12,7 @@ A word you do not know is in the [glossary](glossary.md).
12
12
 
13
13
  - A repository on a supported code host, cloned on your machine, with the
14
14
  code host's command-line tool signed in.
15
- - A supported coding agent, signed in.
15
+ - A supported coding agent, signed in. `factory init` stops without one.
16
16
  - Node 22.18 or later.
17
17
 
18
18
  [What you need](github/setup.md#what-you-need) names the supported tools
@@ -77,8 +77,8 @@ A repository with no tests yet lists the checks it does have, such as a
77
77
  formatter or a compile, and adds its tests to the gate when there are
78
78
  some.
79
79
 
80
- **It worked when** `factory gate` runs each command and ends without a
81
- line that starts `gate failed on`.
80
+ **It worked when** `factory gate` runs each command and ends with
81
+ `✓ Every gate command passed.`
82
82
 
83
83
  ## 3. Merge the setup
84
84
 
package/docs/skills.md CHANGED
@@ -79,7 +79,9 @@ spec when [`specs`](configuration.md#specs) is on.
79
79
  **What it writes.**
80
80
 
81
81
  - The ticket's body: your text first, untouched, then Decisions and
82
- Acceptance criteria, or a Spec when the change is visible and not small.
82
+ Acceptance criteria, or a Spec when the change is visible and not
83
+ small. Each of these goes in a ticket field of yours instead, when
84
+ [`tickets.fields`](configuration.md#ticketsfields) names one.
83
85
  - Marker comments that move the ticket to "refining" and show it waiting on
84
86
  you.
85
87
  - A blocked-by relationship for each ticket that must be built first.
package/docs/updating.md CHANGED
@@ -91,8 +91,8 @@ and its checks fail until the file is moved. On the pull request's branch:
91
91
  4. Run `factory config check`, then `factory sync`, and commit what
92
92
  changed.
93
93
 
94
- **It worked when** `factory config check` prints nothing, and
95
- `factory sync --check` passes.
94
+ **It worked when** `factory config check` prints
95
+ `✓ The settings are valid.`, and `factory sync --check` passes.
96
96
 
97
97
  ### Each key that moved or changed shape
98
98
 
@@ -231,7 +231,7 @@ not match `package-lock.json`.
231
231
 
232
232
  | What you see | What happened | What to do |
233
233
  | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------- |
234
- | CI fails with "the factory's files are out of sync" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
234
+ | CI fails with "of the factory's files don't match the settings" | A factory file was edited by hand, or settings changed without a sync | Run `factory sync` and commit the result |
235
235
  | `factory doctor` says your installed version is older than the repository's | You pulled an update and have not installed it | Run `npm ci` |
236
236
  | A command stops with `version: must be 2` | The update changed the shape of the settings file | [Move the file](#moving-to-settings-version-2) |
237
237
  | A command stops with `.claude/factory.lock is from an earlier version of the factory` | The update's sync has not run on this checkout | Run `factory sync` and commit the result |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.7",
3
+ "version": "0.1.9",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -30,10 +30,11 @@
30
30
  ],
31
31
  "scripts": {
32
32
  "test": "vitest run",
33
+ "coverage": "vitest run --coverage",
33
34
  "typecheck": "tsc --noEmit",
34
35
  "format": "prettier --write .",
35
36
  "format:check": "prettier --check .",
36
- "check": "prettier --check . && tsc --noEmit && npm run -s spec:validate && node bin/factory.js sync --check && node bin/factory.js config check && vitest run",
37
+ "check": "prettier --check . && tsc --noEmit && npm run -s spec:validate && node bin/factory.js sync --check && node bin/factory.js config check && vitest run --coverage",
37
38
  "prepack": "tsc -p tsconfig.build.json",
38
39
  "pack-check": "node tests/pack-check.mts",
39
40
  "site-check": "node --test tests/site-check.mts",
@@ -51,6 +52,7 @@
51
52
  "@types/js-yaml": "^4.0.9",
52
53
  "@types/node": "^22.18.0",
53
54
  "@types/pngjs": "^6.0.5",
55
+ "@vitest/coverage-v8": "^5.1.0",
54
56
  "ajv": "^8.20.0",
55
57
  "playwright": "^1.65.0",
56
58
  "prettier": "^3.10.0",
@@ -119,22 +119,34 @@
119
119
  "properties": {
120
120
  "backlog": {
121
121
  "oneOf": [
122
- { "type": "string", "minLength": 1 },
122
+ {
123
+ "type": "string",
124
+ "minLength": 1
125
+ },
123
126
  {
124
127
  "type": "array",
125
128
  "minItems": 1,
126
- "items": { "type": "string", "minLength": 1 }
129
+ "items": {
130
+ "type": "string",
131
+ "minLength": 1
132
+ }
127
133
  }
128
134
  ],
129
135
  "description": "The board's column for the backlog state, or a list of its columns. Default: Backlog."
130
136
  },
131
137
  "refining": {
132
138
  "oneOf": [
133
- { "type": "string", "minLength": 1 },
139
+ {
140
+ "type": "string",
141
+ "minLength": 1
142
+ },
134
143
  {
135
144
  "type": "array",
136
145
  "minItems": 1,
137
- "items": { "type": "string", "minLength": 1 }
146
+ "items": {
147
+ "type": "string",
148
+ "minLength": 1
149
+ }
138
150
  }
139
151
  ],
140
152
  "description": "The board's column for the refining state, or a list of its columns. Default: In refinement. May be none."
@@ -146,33 +158,51 @@
146
158
  },
147
159
  "building": {
148
160
  "oneOf": [
149
- { "type": "string", "minLength": 1 },
161
+ {
162
+ "type": "string",
163
+ "minLength": 1
164
+ },
150
165
  {
151
166
  "type": "array",
152
167
  "minItems": 1,
153
- "items": { "type": "string", "minLength": 1 }
168
+ "items": {
169
+ "type": "string",
170
+ "minLength": 1
171
+ }
154
172
  }
155
173
  ],
156
174
  "description": "The board's column for the building state, or a list of its columns. Default: In progress. May be none."
157
175
  },
158
176
  "review": {
159
177
  "oneOf": [
160
- { "type": "string", "minLength": 1 },
178
+ {
179
+ "type": "string",
180
+ "minLength": 1
181
+ },
161
182
  {
162
183
  "type": "array",
163
184
  "minItems": 1,
164
- "items": { "type": "string", "minLength": 1 }
185
+ "items": {
186
+ "type": "string",
187
+ "minLength": 1
188
+ }
165
189
  }
166
190
  ],
167
191
  "description": "The board's column for the review state, or a list of its columns. Default: In review. May be none."
168
192
  },
169
193
  "done": {
170
194
  "oneOf": [
171
- { "type": "string", "minLength": 1 },
195
+ {
196
+ "type": "string",
197
+ "minLength": 1
198
+ },
172
199
  {
173
200
  "type": "array",
174
201
  "minItems": 1,
175
- "items": { "type": "string", "minLength": 1 }
202
+ "items": {
203
+ "type": "string",
204
+ "minLength": 1
205
+ }
176
206
  }
177
207
  ],
178
208
  "description": "The board's column for the done state, or a list of its columns. Default: Done. May be none."
@@ -181,7 +211,7 @@
181
211
  },
182
212
  "tickets.fields": {
183
213
  "type": "object",
184
- "description": "Which of your board's fields the sync writes. Needs a board.",
214
+ "description": "Which of your fields holds each of the factory's fields: on the board, session, runs-in, and cost, which need a board; on the ticket, decisions, spec, acceptance-criteria, for-the-builder, and any heading of your own.",
185
215
  "additionalProperties": false,
186
216
  "properties": {
187
217
  "session": {
@@ -198,6 +228,33 @@
198
228
  "type": "string",
199
229
  "minLength": 1,
200
230
  "description": "The board's field the sync writes for cost. Default: Cost. May be none."
231
+ },
232
+ "decisions": {
233
+ "type": "string",
234
+ "minLength": 1,
235
+ "description": "The ticket field that holds Decisions. Default: none, the description. Spec and acceptance-criteria may name the same field."
236
+ },
237
+ "spec": {
238
+ "type": "string",
239
+ "minLength": 1,
240
+ "description": "The ticket field that holds Spec. Default: none, the description. Spec and acceptance-criteria may name the same field."
241
+ },
242
+ "acceptance-criteria": {
243
+ "type": "string",
244
+ "minLength": 1,
245
+ "description": "The ticket field that holds Acceptance criteria. Default: none, the description. Spec and acceptance-criteria may name the same field."
246
+ },
247
+ "for-the-builder": {
248
+ "type": "string",
249
+ "minLength": 1,
250
+ "description": "The ticket field that holds For the builder. Default: none, the description. Spec and acceptance-criteria may name the same field."
251
+ }
252
+ },
253
+ "patternProperties": {
254
+ "^[a-z0-9]+(-[a-z0-9]+)*$": {
255
+ "type": "string",
256
+ "minLength": 1,
257
+ "description": "The ticket field that holds a heading of your own: the heading in lowercase, with hyphens for spaces. May be none."
201
258
  }
202
259
  }
203
260
  },
@@ -150,6 +150,10 @@ changed the settings' shape, as version 2 does.
150
150
  Stop (step 6), and say the settings are the owner's to move, as "Moving to
151
151
  settings version 2" in the factory's `docs/updating.md` says for that
152
152
  release. Never edit `.claude/factory.yaml`.
153
+ When it fails on `.npmrc` instead, refusing a variable a sign-in line
154
+ reads, stop the same way and say the name is the owner's to change:
155
+ renaming it renames the secret and every developer's variable. Never edit
156
+ `.npmrc`.
153
157
 
154
158
  Commit what the sync wrote as a second commit, "Sync the factory's files to
155
159
  VERSION" or "Sync the settings to PACKAGE VERSION", and push. The push changes workflows, so it needs a token with