@davidbyoung/software-factory 0.1.2 → 0.1.4
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 +20 -20
- 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/agent/claude-code.d.mts +3 -0
- package/dist/agent/claude-code.mjs +89 -0
- package/dist/agent/index.d.mts +2 -0
- package/dist/agent/index.mjs +5 -0
- package/dist/board.mjs +1 -1
- package/dist/cli.mjs +46 -4
- package/dist/code-host/github-setup.d.mts +5 -0
- package/dist/code-host/github-setup.mjs +133 -0
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/index.d.mts +1 -1
- package/dist/code-host/index.mjs +2 -1
- package/dist/code-host/types.d.mts +2 -0
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +87 -20
- package/dist/config.mjs +344 -89
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +9 -16
- package/dist/doctor.mjs +71 -68
- package/dist/explain.d.mts +4 -0
- package/dist/explain.mjs +174 -0
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +12 -14
- package/dist/init.mjs +194 -136
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/has-command.d.mts +5 -0
- package/dist/lib/has-command.mjs +8 -0
- package/dist/lib/listed.d.mts +2 -0
- package/dist/lib/listed.mjs +4 -0
- package/dist/lib/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -0
- package/dist/lib/work-status.d.mts +12 -2
- package/dist/lib/work-status.mjs +14 -3
- package/dist/parts.d.mts +18 -15
- package/dist/parts.mjs +15 -43
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/remove.d.mts +11 -0
- package/dist/remove.mjs +156 -0
- package/dist/runner/github-actions.d.mts +1 -1
- package/dist/runner/github-actions.mjs +12 -0
- package/dist/runner/index.d.mts +1 -1
- package/dist/runner/index.mjs +2 -1
- package/dist/runner/setup.d.mts +2 -0
- package/dist/runner/setup.mjs +22 -0
- package/dist/runner/types.d.mts +3 -0
- package/dist/runner/types.mjs +0 -2
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +26 -2
- package/dist/sync.mjs +177 -13
- package/dist/ticket.mjs +19 -1
- package/dist/tickets/github-setup.d.mts +2 -0
- package/dist/tickets/github-setup.mjs +50 -0
- package/dist/tickets/github.mjs +0 -2
- package/dist/tickets/index.mjs +2 -1
- package/dist/tickets/transport.mjs +1 -3
- package/dist/tickets/types.mjs +0 -2
- package/dist/tool-names.d.mts +11 -0
- package/dist/tool-names.mjs +20 -0
- package/dist/tools.d.mts +56 -0
- package/dist/tools.mjs +76 -0
- package/docs/builds.md +111 -59
- package/docs/cli.md +106 -69
- package/docs/configuration.md +489 -171
- package/docs/design.md +18 -5
- package/docs/developing.md +179 -73
- package/docs/existing-repo.md +25 -12
- package/docs/github/by-hand.md +334 -0
- package/docs/github/reference.md +76 -67
- package/docs/github/setup.md +105 -286
- package/docs/glossary.md +18 -7
- package/docs/limitations.md +39 -12
- package/docs/plugins.md +305 -56
- package/docs/quick-start.md +85 -100
- package/docs/removing.md +37 -17
- package/docs/skills.md +121 -62
- package/docs/updating.md +150 -9
- package/docs/workflow.md +23 -19
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/review.md +20 -11
- package/rules.md +36 -30
- package/settings.schema.json +313 -69
- 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 +17 -8
- 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 +80 -0
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-poller.yml +46 -0
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
package/docs/design.md
CHANGED
|
@@ -68,10 +68,23 @@ differently from one day to the next.
|
|
|
68
68
|
|
|
69
69
|
## The order of the workflow is fixed
|
|
70
70
|
|
|
71
|
-
You can turn parts off
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
71
|
+
You can turn parts off in [the settings](configuration.md), such as
|
|
72
|
+
written specs or the automated review, and a [plug-in](plugins.md) of yours can take a
|
|
73
|
+
step over: how a ticket is refined, how a ticket with one of your labels
|
|
74
|
+
is built, how a test is proved able to fail, which agents read the tests
|
|
75
|
+
and the change, and how a generated file is rebuilt after a conflict. You
|
|
76
|
+
cannot reorder the six states, add one, or leave one out.
|
|
77
|
+
|
|
78
|
+
A step can be replaced because what it hands to the next one can be
|
|
79
|
+
written down, and the part a build depends on is checked by a script: a
|
|
80
|
+
refined ticket is refused until its body has the sections a build reads,
|
|
81
|
+
whichever skill refined it. So whatever does a step, the next step reads
|
|
82
|
+
the same thing.
|
|
83
|
+
|
|
84
|
+
The order is another matter. Mapping names is cheap to support, which is
|
|
85
|
+
why a board's columns can be yours. Every extra shape of workflow is one
|
|
86
|
+
more path each skill has to handle correctly, and a skill is instructions,
|
|
87
|
+
which cannot be unit tested.
|
|
75
88
|
|
|
76
89
|
## Small problems go on one checklist
|
|
77
90
|
|
|
@@ -87,7 +100,7 @@ They are separate on purpose.
|
|
|
87
100
|
|
|
88
101
|
| Number | Where it is | Changes when |
|
|
89
102
|
| ------------------- | -------------------------------------------- | ------------------------------------ |
|
|
90
|
-
| The factory's |
|
|
103
|
+
| The factory's | The installed package and `factory.lock` | Every release |
|
|
91
104
|
| The settings file's | `version:` at the top of `factory.yaml` | A key is renamed or moved |
|
|
92
105
|
| The markers' | In the comments the factory posts on tickets | The format of those comments changes |
|
|
93
106
|
|
package/docs/developing.md
CHANGED
|
@@ -13,7 +13,7 @@ it shares with that repository: each repository's sync reads only its own
|
|
|
13
13
|
cards.
|
|
14
14
|
|
|
15
15
|
**It uses the factory on itself.** `.claude/factory.yaml` here sets the
|
|
16
|
-
board, OpenSpec, and the CI review, and `node bin/factory.js sync` copies
|
|
16
|
+
board, OpenSpec, the gate, and the CI review, and `node bin/factory.js sync` copies
|
|
17
17
|
this repository's own skills, agents, rules, and workflows into `.claude/`
|
|
18
18
|
and `.github/`, with hooks that run `bin/factory.js` at the root. So a
|
|
19
19
|
change to a skill shows in the same pull request twice: the source, and
|
|
@@ -30,40 +30,49 @@ completes with the files the version writes ([Updating](updating.md)).
|
|
|
30
30
|
The factory is the npm package `@davidbyoung/software-factory`. Parts not
|
|
31
31
|
marked working below exist only in these docs.
|
|
32
32
|
|
|
33
|
-
| Part
|
|
34
|
-
|
|
|
35
|
-
| Refining, building, and working a pull request's review
|
|
36
|
-
| The board, its sync, and `status`
|
|
37
|
-
| Builds from the board, with a poller you host
|
|
38
|
-
| Builds that run in GitHub Actions, started by a command
|
|
39
|
-
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions
|
|
40
|
-
| Who merges, and the review's verdict
|
|
41
|
-
| The labels `merge: manual` and `verdict: override`
|
|
42
|
-
| These docs
|
|
43
|
-
| `.claude/factory.yaml`, and the factory's files kept apart from the host's
|
|
44
|
-
| The follow-ups ticket as one checklist
|
|
45
|
-
| The `factory` tool, `sync`, and the package folder
|
|
46
|
-
| A global `factory` command that runs each repository's own copy
|
|
47
|
-
| The automated review as one of the factory's workflows, and `ci-review`
|
|
48
|
-
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball
|
|
49
|
-
| The `factory-` names and the `FACTORY_` secrets
|
|
50
|
-
| Ticket commands that go through one interface
|
|
51
|
-
| The code host and the runner, each behind one interface
|
|
52
|
-
| A published package
|
|
53
|
-
|
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
| `
|
|
60
|
-
|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
| `
|
|
64
|
-
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
33
|
+
| Part | State |
|
|
34
|
+
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
35
|
+
| Refining, building, and working a pull request's review | Working |
|
|
36
|
+
| The board, its sync, and `status` | Working |
|
|
37
|
+
| Builds from the board, with a poller you host | Working |
|
|
38
|
+
| Builds that run in GitHub Actions, started by a command | Working |
|
|
39
|
+
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
|
|
40
|
+
| Who merges, and the review's verdict | Working |
|
|
41
|
+
| The labels `merge: manual` and `verdict: override` | Working |
|
|
42
|
+
| These docs | Working |
|
|
43
|
+
| `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
|
|
44
|
+
| The follow-ups ticket as one checklist | Working |
|
|
45
|
+
| The `factory` tool, `sync`, and the package folder | Working |
|
|
46
|
+
| A global `factory` command that runs each repository's own copy | Working |
|
|
47
|
+
| The automated review as one of the factory's workflows, and [`ci-review`](configuration.md#ci-review) | Working |
|
|
48
|
+
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
|
|
49
|
+
| The `factory-` names and the `FACTORY_` secrets | Working |
|
|
50
|
+
| Ticket commands that go through one interface | Working |
|
|
51
|
+
| The code host and the runner, each behind one interface | Working |
|
|
52
|
+
| A published package | Working |
|
|
53
|
+
| Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working |
|
|
54
|
+
| `factory board --dry-run` | Working |
|
|
55
|
+
| Your own column names on a board | Working |
|
|
56
|
+
| A UI reviewer for any website | Working |
|
|
57
|
+
| Built-in measurements for any website | Working |
|
|
58
|
+
| A design skill for any website | Working |
|
|
59
|
+
| `init`, which can be re-run, and `doctor` | Working |
|
|
60
|
+
| A second repository set up and removed from the quick start alone | Working |
|
|
61
|
+
| `factory remove` | Working |
|
|
62
|
+
| Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
|
|
63
|
+
| [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working |
|
|
64
|
+
| Settings version 2: commands, a spec check, and plug-ins grouped by phase | Working |
|
|
65
|
+
| `factory gate`, `test-one`, `end-to-end`, and `specs check`, which run the settings' commands | Working |
|
|
66
|
+
| The default branch read from Git and the code host, never assumed, and `factory default-branch` | Working |
|
|
67
|
+
| A refiner, a prover, test reviewers, and conflict resolvers of your own, and `factory-e2e-reviewer` | Working |
|
|
68
|
+
| `factory ticket refined` refusing a ticket a build could not read | Working |
|
|
69
|
+
| No skill, agent, rule, or review instruction names a stack, checked by a test | Working |
|
|
70
|
+
| `approvers` in the settings | Planned, [#14](https://github.com/davidbyoung/software-factory/issues/14) |
|
|
71
|
+
| Another ticket system, such as Jira | Not planned. The design leaves room |
|
|
72
|
+
| A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
|
|
73
|
+
| Another code host or runner | Not planned. The design leaves room |
|
|
74
|
+
| Each tool's setup, checks, and removal declared by the tool | Working |
|
|
75
|
+
| Sharing plug-ins between repositories | Not planned |
|
|
67
76
|
|
|
68
77
|
When a part is built, its pull request updates this table, and corrects any
|
|
69
78
|
page the build had to differ from. [The CLI](cli.md) marks each command
|
|
@@ -95,8 +104,23 @@ It is laid out as a Claude Code plugin even though it is not delivered as
|
|
|
95
104
|
one. That costs nothing, and it keeps the plugin's own tooling usable on the
|
|
96
105
|
folder. The settings are validated in code, and `settings.schema.json` is the
|
|
97
106
|
editor's copy of their keys. A new key goes in `SETTINGS_KEYS` in
|
|
98
|
-
`src/config.mts`, in the schema,
|
|
99
|
-
fails when the first two differ.
|
|
107
|
+
`src/config.mts`, in the schema, in `src/explain.mts`, which prints it, and
|
|
108
|
+
in `docs/configuration.md`, and a test fails when the first two differ.
|
|
109
|
+
|
|
110
|
+
- **A command a session runs** goes under
|
|
111
|
+
[`commands`](configuration.md#commands), with a `factory`
|
|
112
|
+
command in `src/commands.mts` that runs it, so a skill names the
|
|
113
|
+
`factory` command and never the repository's own.
|
|
114
|
+
- **A plug-in slot** goes in `SLOTS` and `SLOT_SHAPE` in `src/config.mts`,
|
|
115
|
+
which say its phase, whether it takes a skill or an agent, one or a
|
|
116
|
+
list, and `files` or `labels`. Its keys in `SETTINGS_KEYS` follow from
|
|
117
|
+
that table. `docs/plugins.md` gains its table of what it is handed and
|
|
118
|
+
what it returns.
|
|
119
|
+
- **A key that is renamed or moved** raises the settings' `version`.
|
|
120
|
+
There is no command that converts a file: the older version is refused
|
|
121
|
+
with a line that names a section of `docs/updating.md`, as version 1 is
|
|
122
|
+
with "Moving to settings version 2", and that section shows each key
|
|
123
|
+
before and after.
|
|
100
124
|
|
|
101
125
|
## Running from source
|
|
102
126
|
|
|
@@ -127,8 +151,9 @@ guard runs before every command a session runs: `npx` took 289 ms a call,
|
|
|
127
151
|
`node` on the launcher 56 ms.
|
|
128
152
|
|
|
129
153
|
To prove the package works outside its host, CI packs the folder, installs
|
|
130
|
-
the tarball into an empty repository, and runs `
|
|
131
|
-
`config check`, and `plugins`
|
|
154
|
+
the tarball into an empty repository, and runs `factory sync`,
|
|
155
|
+
`factory sync --check`, `factory config check`, and `factory plugins`
|
|
156
|
+
there:
|
|
132
157
|
|
|
133
158
|
```bash
|
|
134
159
|
npm run pack-check
|
|
@@ -159,10 +184,22 @@ A factory file must name nothing that belongs to the host repository: not
|
|
|
159
184
|
its paths, its commands, its subject, or its own skills. A test fails when
|
|
160
185
|
one does. That is what keeps the folder movable.
|
|
161
186
|
|
|
187
|
+
Nor does a skill, an agent, the rules, or the review's instructions name
|
|
188
|
+
one stack: a test runner, a framework, a package manager's commands, or a
|
|
189
|
+
branch called `main`. A skill runs `factory gate`, `factory test-one`,
|
|
190
|
+
`factory end-to-end`, and `factory specs check`, which run the repository's
|
|
191
|
+
own commands from its settings, and writes the default branch as the name
|
|
192
|
+
`factory default-branch` prints. `tests/boundary.test.ts` lists the words
|
|
193
|
+
it fails on. The three files written only for a website or an end-to-end
|
|
194
|
+
suite, `factory-ui-reviewer`, `factory-e2e-reviewer`, and `factory-design`,
|
|
195
|
+
may name a browser tool, and `factory-deps` npm's own files and commands,
|
|
196
|
+
since the factory's update is an npm package's.
|
|
197
|
+
|
|
162
198
|
## Adding a ticket system
|
|
163
199
|
|
|
164
200
|
Only GitHub is built. The factory is built so that a second system is an
|
|
165
|
-
addition, not a rewrite. Four rules keep it that way
|
|
201
|
+
addition, not a rewrite. Four rules keep it that way, and its setup is
|
|
202
|
+
[declared like any tool's](#setting-a-tool-up).
|
|
166
203
|
|
|
167
204
|
**1. Nothing talks to the ticket system except through the tool.** A skill
|
|
168
205
|
never runs `gh issue` or calls GitHub's issues or projects API. It runs
|
|
@@ -178,13 +215,12 @@ runs. Every command reaches a ticket, a pull request, or a build through
|
|
|
178
215
|
one of them, and a test fails when a file elsewhere under `src/` calls
|
|
179
216
|
GitHub or holds a `github.com` address.
|
|
180
217
|
|
|
181
|
-
**3. The tool reads `tickets.type` and hands
|
|
182
|
-
adapter.** An adapter is one module in
|
|
183
|
-
`
|
|
184
|
-
|
|
218
|
+
**3. The tool reads [`tickets.type`](configuration.md#tickets) and hands
|
|
219
|
+
the work to that type's adapter.** An adapter is one module in
|
|
220
|
+
`src/tickets/` that implements the `Tickets` type in
|
|
221
|
+
`src/tickets/types.mts`. `github` is the only one; any other value fails
|
|
222
|
+
`factory config check` and every ticket command with
|
|
185
223
|
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
186
|
-
A type that names a package, so a team can write an adapter for a system
|
|
187
|
-
the factory does not ship, is planned, not built.
|
|
188
224
|
|
|
189
225
|
| Operation | In `Tickets` | What it returns or does |
|
|
190
226
|
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -229,9 +265,8 @@ order is prose in the ticket and nothing enforces it.
|
|
|
229
265
|
and one for an answer in plain text, such as a job's log
|
|
230
266
|
(`src/tickets/transport.mts`). `ghTransport` runs the GitHub CLI, for
|
|
231
267
|
sessions and CI. `fetchTransport` calls the API with a token, for the
|
|
232
|
-
poller, which runs with no `gh
|
|
233
|
-
|
|
234
|
-
fails when it misses one.
|
|
268
|
+
poller, which runs with no `gh`: its image installs only the published
|
|
269
|
+
package.
|
|
235
270
|
|
|
236
271
|
What stays above the interface: working out a ticket's state from its
|
|
237
272
|
marker comments, costs, and the formatting of every view, in
|
|
@@ -253,18 +288,18 @@ a third.
|
|
|
253
288
|
## Adding a code host
|
|
254
289
|
|
|
255
290
|
The code host is where pull requests are. Only GitHub is built. The
|
|
256
|
-
settings name it with `code-host.type
|
|
257
|
-
a command the implementation of that name:
|
|
258
|
-
that implements the `CodeHost` type in
|
|
259
|
-
value fails `factory config check`,
|
|
260
|
-
settings and reaches a pull request, with
|
|
291
|
+
settings name it with [`code-host.type`](configuration.md#code-host), and
|
|
292
|
+
`src/code-host/index.mts` hands a command the implementation of that name:
|
|
293
|
+
one module in `src/code-host/` that implements the `CodeHost` type in
|
|
294
|
+
`src/code-host/types.mts`. Any other value fails `factory config check`,
|
|
295
|
+
and every command that reads the settings and reaches a pull request, with
|
|
261
296
|
`code-host.type "X" is not supported. "github" is the only code host built.`
|
|
262
|
-
A type that names a package is planned, not built.
|
|
263
297
|
|
|
264
298
|
A command that a workflow also runs, such as `factory pr`, does not read
|
|
265
299
|
the settings there, so an unreadable settings file cannot fail the
|
|
266
|
-
workflow's step; it asks for the default. The poller has no
|
|
267
|
-
all and names its implementations itself
|
|
300
|
+
workflow's step; it asks for the default. The poller you host has no
|
|
301
|
+
settings at all and names its implementations itself; a scheduled pass
|
|
302
|
+
reads the settings only for its board and Ready column.
|
|
268
303
|
|
|
269
304
|
| Operation | In `CodeHost` | What it returns or does |
|
|
270
305
|
| ---------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -317,7 +352,7 @@ of which call GitHub is sent belongs.
|
|
|
317
352
|
## Adding a runner
|
|
318
353
|
|
|
319
354
|
The runner is where an unattended build runs. Only GitHub Actions is
|
|
320
|
-
built. The settings name it with `builds.runner
|
|
355
|
+
built. The settings name it with [`builds.runner`](configuration.md#builds), and
|
|
321
356
|
`src/runner/index.mts` hands a command the implementation of that name:
|
|
322
357
|
one module in `src/runner/` that implements the `Runner` type in
|
|
323
358
|
`src/runner/types.mts`. Any other value fails `factory config check`, and
|
|
@@ -352,6 +387,44 @@ variables, and reach pull requests through the code host.
|
|
|
352
387
|
The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
|
|
353
388
|
its own tests against faked replies.
|
|
354
389
|
|
|
390
|
+
## Setting a tool up
|
|
391
|
+
|
|
392
|
+
A tool is a code host, a ticket system, a runner, or a coding agent. Each
|
|
393
|
+
says what it needs, so `factory init` sets it up, `factory doctor` checks
|
|
394
|
+
it, and `factory remove` takes it out, with no edit to those commands.
|
|
395
|
+
`src/tools.mts` registers each one by the name a setting gives it, with
|
|
396
|
+
how to open it and its setup, the `ToolSetup` type in `src/setup.mts`. The
|
|
397
|
+
names the settings accept are in `src/tool-names.mts`, and a test fails
|
|
398
|
+
when the two differ. Every member of a setup is optional.
|
|
399
|
+
|
|
400
|
+
| Member | What it gives | Used by |
|
|
401
|
+
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
402
|
+
| `found` | Its row under "Found", when it says more than the tool's name, such as that a command is not installed | `init` |
|
|
403
|
+
| `steps` | A value to write under the tool's block of the settings, or a secret: which parts read it, how to get it, and how to check a pasted one | `init` |
|
|
404
|
+
| `checks` | Its own lines in `doctor`: that it is reachable, signed in, or configured, each failure with its fix in the tool's words | `doctor` |
|
|
405
|
+
| `leftovers` | What removing the factory leaves outside the repository, such as its secrets | `remove` |
|
|
406
|
+
| `unconfigure` | Its own files with the factory's part taken out, such as a coding agent's settings without the factory's hooks | `remove` |
|
|
407
|
+
|
|
408
|
+
**A value** is asked for once, after the parts are chosen, and written
|
|
409
|
+
under the tool's block: a ticket system's under `tickets`, which accepts a
|
|
410
|
+
key only when the ticket system in use declares it. **A secret** names the
|
|
411
|
+
parts that read it, or none when the tool always needs it. `init` asks for
|
|
412
|
+
it when one of those is not set, prints the tool's introduction, opens
|
|
413
|
+
its page or runs its command, reads it in a masked prompt, and stores it
|
|
414
|
+
through the runner under each name the tool gives. Its words are the
|
|
415
|
+
tool's: the prompt, the reason it refuses a value, and the line when
|
|
416
|
+
nothing is pasted.
|
|
417
|
+
|
|
418
|
+
With more than one tool of a kind, `init` asks which, except for the code
|
|
419
|
+
host, which it reads from the git remote: each code host says which
|
|
420
|
+
remotes are its own. The coding agent has no setting until there is a
|
|
421
|
+
second.
|
|
422
|
+
|
|
423
|
+
The tests show a tool that the factory does not ship going through all
|
|
424
|
+
three commands: `tests/fake-tools.ts` has a ticket system with a site
|
|
425
|
+
address and a token of its own, and a coding agent whose configuration is
|
|
426
|
+
one file.
|
|
427
|
+
|
|
355
428
|
## Checking a change
|
|
356
429
|
|
|
357
430
|
| Check | What it proves |
|
|
@@ -359,7 +432,7 @@ its own tests against faked replies.
|
|
|
359
432
|
| The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
|
|
360
433
|
| `factory sync --check` | The copies match the source |
|
|
361
434
|
| Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
|
|
362
|
-
|
|
|
435
|
+
| `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
|
|
363
436
|
| Fork safety | No workflow it runs or ships could run a fork's code with a secret or write access (`tests/fork-safety.test.ts`). This repository is public |
|
|
364
437
|
| One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
|
|
365
438
|
|
|
@@ -368,18 +441,32 @@ last row is the only real proof that a change to one still works.
|
|
|
368
441
|
|
|
369
442
|
## Releasing
|
|
370
443
|
|
|
371
|
-
1.
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
444
|
+
1. On the Actions tab, run **Release** on `main` and choose the part of
|
|
445
|
+
the version to raise: patch for fixes alone, minor for something new,
|
|
446
|
+
and major for a change that breaks a repository using the factory. From
|
|
447
|
+
0.1.2, they give 0.1.3, 0.2.0, and 1.0.0.
|
|
448
|
+
2. The run raises the highest `vX.Y.Z` tag by that part, and runs the
|
|
449
|
+
whole CI on `main`'s commit, the same jobs a pull request gets. Only
|
|
450
|
+
once they pass does it publish the version to npm, then the poller's
|
|
451
|
+
image of that version to GitHub's container registry. Last, it tags the
|
|
452
|
+
commit and creates a GitHub Release whose notes list the pull requests
|
|
453
|
+
merged since the previous version. Those notes are the changelog, and
|
|
454
|
+
Dependabot copies them into the update pull requests it opens, so a
|
|
455
|
+
pull request's title is the line a user reads. When a release needs
|
|
456
|
+
something done by hand in a repository that uses the factory, edit its
|
|
457
|
+
GitHub Release as soon as the run ends, and put the steps first.
|
|
458
|
+
3. A run that stops partway has made no tag. Re-running its failed jobs,
|
|
459
|
+
from the run's page, finishes it on the same commit and version, and
|
|
460
|
+
does not publish to npm twice. A new run for a version npm already has
|
|
461
|
+
stops and says so.
|
|
462
|
+
4. After the first release that publishes the image, pull it with no
|
|
463
|
+
sign-in: `docker logout ghcr.io` and
|
|
464
|
+
`docker pull ghcr.io/davidbyoung/software-factory-poller:VERSION`. If it
|
|
465
|
+
is refused, set the package to Public on its GitHub page, once.
|
|
466
|
+
|
|
467
|
+
Nothing is committed for a release. `package.json` on `main` keeps the
|
|
468
|
+
version `0.0.0-development`, and the run writes the real one into its own
|
|
469
|
+
copy before publishing, so the tags and npm hold the released versions.
|
|
383
470
|
|
|
384
471
|
The first version, 0.1.0, was published by hand, since npm sets up a
|
|
385
472
|
trusted publisher only for a package that exists:
|
|
@@ -398,8 +485,8 @@ drawn out of.
|
|
|
398
485
|
## Writing for the factory
|
|
399
486
|
|
|
400
487
|
- **American English, with the Oxford comma.**
|
|
401
|
-
- **The factory's own words:** ticket, follow-up, the six states, the
|
|
402
|
-
|
|
488
|
+
- **The factory's own words:** ticket, follow-up, the six states, the seven
|
|
489
|
+
slots. Not issue, card, or sweep.
|
|
403
490
|
- **A key name must make sense unexplained.** Each reference settings file
|
|
404
491
|
is read cold by a fresh agent that is told only what the factory is. A key
|
|
405
492
|
it explains wrongly, or cannot tell from another, is renamed or given a
|
|
@@ -412,3 +499,22 @@ drawn out of.
|
|
|
412
499
|
to differ.
|
|
413
500
|
- **Examples carry the reason for a rule, without the host's private
|
|
414
501
|
history.**
|
|
502
|
+
|
|
503
|
+
### A page a reader follows
|
|
504
|
+
|
|
505
|
+
`README.md` and every page under `docs/` but this one is read by someone
|
|
506
|
+
who has never seen the factory and wants one thing done. `docs-reader`,
|
|
507
|
+
this repository's own reviewer, reads a changed page as that person.
|
|
508
|
+
|
|
509
|
+
- **A page says who it is for and what they will have at the end,** in its
|
|
510
|
+
first lines.
|
|
511
|
+
- **Lead with the command that does it.** The same steps by hand go on a
|
|
512
|
+
page of their own, linked once.
|
|
513
|
+
- **Say only what the reader must do or decide.** What a command does for
|
|
514
|
+
them is one sentence, and a link to the page that lists it.
|
|
515
|
+
- **A setting links to its entry in `docs/configuration.md` where a page
|
|
516
|
+
first names it.** A test fails on one that does not.
|
|
517
|
+
- **A setting the reader writes is shown as YAML they can paste,** with
|
|
518
|
+
what each line is for.
|
|
519
|
+
- **A step ends with how the reader knows it worked.**
|
|
520
|
+
- **Each fact has one home.** Every other page links to it.
|
package/docs/existing-repo.md
CHANGED
|
@@ -17,8 +17,16 @@ The factory's tool runs on Node and is installed with npm, whatever your
|
|
|
17
17
|
project is written in. In a PHP, Python, or Go repository that means:
|
|
18
18
|
|
|
19
19
|
- **A `package.json` appears**, holding one development dependency and
|
|
20
|
-
nothing else.
|
|
21
|
-
|
|
20
|
+
nothing else. Make it yourself before installing, marked private so it
|
|
21
|
+
can never be published:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
echo '{ "private": true }' > package.json
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Without one, npm installs into the nearest folder above that has a
|
|
28
|
+
`package.json`, if there is one, rather than into your repository.
|
|
29
|
+
|
|
22
30
|
- **`package-lock.json` is committed.** It is what keeps everyone on the
|
|
23
31
|
same version of the factory.
|
|
24
32
|
- **`node_modules/` is ignored.** `factory init` adds it
|
|
@@ -28,8 +36,10 @@ project is written in. In a PHP, Python, or Go repository that means:
|
|
|
28
36
|
- **Your own CI does not change.** The factory's cloud jobs install Node
|
|
29
37
|
for themselves. If you turn on the automated review, how it installs your
|
|
30
38
|
project, such as `composer install`, is yours to edit.
|
|
31
|
-
- **Your commands stay yours.**
|
|
32
|
-
|
|
39
|
+
- **Your commands stay yours.** The gate a build runs, and everything
|
|
40
|
+
else under [`commands`](configuration.md#commands) in the settings, is
|
|
41
|
+
whatever your project runs: `composer test`, `make check`,
|
|
42
|
+
`go vet ./...`.
|
|
33
43
|
|
|
34
44
|
The factory's hooks run its own tool, so they need nothing beyond Node.
|
|
35
45
|
Someone who only writes code by hand, and never runs an agent session in
|
|
@@ -58,9 +68,10 @@ Added to board 3: Backlog, In refinement, Ready, In review, Session, Runs in, Co
|
|
|
58
68
|
or move them all once and retire the column.
|
|
59
69
|
- **The factory's fields are overwritten on every sync.** Do not type into
|
|
60
70
|
Session, Runs in, or Cost. Your own fields are never touched.
|
|
61
|
-
- **Using your own column names** works today:
|
|
62
|
-
|
|
63
|
-
|
|
71
|
+
- **Using your own column names** works today:
|
|
72
|
+
[`tickets.columns`](configuration.md#ticketscolumns) in your settings
|
|
73
|
+
says which of your columns shows each state, and `none` says your board
|
|
74
|
+
has none. [Configuration](configuration.md#ticketscolumns) has the
|
|
64
75
|
mapping for a board with Todo, In Progress, and Done. To see what the
|
|
65
76
|
factory will do with your board, run:
|
|
66
77
|
|
|
@@ -105,7 +116,7 @@ names each file.
|
|
|
105
116
|
teammate's session goes out under that teammate's account. A cloud build
|
|
106
117
|
acts as the one account that owns its token: yours, or an account you
|
|
107
118
|
create for the team's builds
|
|
108
|
-
([
|
|
119
|
+
([Secrets](github/by-hand.md#secrets)).
|
|
109
120
|
- **Say who approves.** By default only the repository's owner can approve
|
|
110
121
|
a ticket for building or give a session instructions in a comment. List
|
|
111
122
|
the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
|
|
@@ -129,10 +140,12 @@ and how to undo each. The short version:
|
|
|
129
140
|
- Files it owns, all named `factory-...`, and its rules.
|
|
130
141
|
- One line in your agent's instructions file, and a few hooks in your
|
|
131
142
|
agent's settings.
|
|
132
|
-
- Hooks that stop a session committing on your
|
|
133
|
-
pushing, and that run your
|
|
134
|
-
|
|
143
|
+
- Hooks that stop a session committing on your default branch or force
|
|
144
|
+
pushing, and that run your
|
|
145
|
+
[`commands.before-commit`](configuration.md#commandsbefore-commit)
|
|
146
|
+
commands. They apply to agent sessions, not to your own terminal.
|
|
135
147
|
- Its CI workflows: one that checks the factory's files are in step, the
|
|
136
148
|
ones that run a session in the cloud, and one more for each optional part
|
|
137
|
-
you turn on.
|
|
149
|
+
you turn on. With a Dependabot configuration, two more complete
|
|
150
|
+
Dependabot's pull requests, the factory's own updates among them.
|
|
138
151
|
- Comments on tickets it works, and one "Follow-ups" ticket.
|