@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/README.md CHANGED
@@ -67,9 +67,9 @@ added without changing the rest. Today each has one choice:
67
67
  | You need | Supported today | Setting it up |
68
68
  | ----------------------------------------------------- | ---------------------------------- | -------------------------------------------- |
69
69
  | A code host, for the repository and its pull requests | GitHub | [Setting up on GitHub](docs/github/setup.md) |
70
- | A ticket system, and optionally a board | GitHub Issues, and GitHub Projects | The same page |
71
- | Somewhere to build in the cloud, optionally | GitHub Actions | The same page |
72
- | A coding agent | Claude Code | The same page |
70
+ | A ticket system, and optionally a board | GitHub Issues, and GitHub Projects | [Setting up on GitHub](docs/github/setup.md) |
71
+ | Somewhere to build in the cloud, optionally | GitHub Actions | [Setting up on GitHub](docs/github/setup.md) |
72
+ | A coding agent | Claude Code | [Setting up on GitHub](docs/github/setup.md) |
73
73
 
74
74
  ## Get started
75
75
 
@@ -85,7 +85,8 @@ else is optional and comes later.
85
85
  ticket, review the pull request, and merge it, and whoever merges
86
86
  answers for it.
87
87
  2. **Everything waits for you unless you said otherwise.**
88
- 3. **It works with nothing configured.** Every setting has a default.
88
+ 3. **It asks for almost nothing.** Every setting has a default, and a
89
+ build needs one thing from you: the commands that check a change.
89
90
 
90
91
  ## The docs
91
92
 
@@ -100,13 +101,13 @@ else is optional and comes later.
100
101
 
101
102
  **Guides**
102
103
 
103
- | Page | For |
104
- | -------------------------------------------------------------- | ----------------------------------------- |
105
- | [Adopting it in an existing repository](docs/existing-repo.md) | Not JavaScript, an existing board, a team |
106
- | [Plug-ins](docs/plugins.md) | Adding your own reviewers and skills |
107
- | [Builds in the cloud](docs/builds.md) | Starting builds from your board |
108
- | [Updating](docs/updating.md) | Getting a new version |
109
- | [What it changes, and removing it](docs/removing.md) | Everything it adds, and how to undo it |
104
+ | Page | For |
105
+ | -------------------------------------------------------------- | ------------------------------------------ |
106
+ | [Adopting it in an existing repository](docs/existing-repo.md) | Not JavaScript, an existing board, a team |
107
+ | [Plugins](docs/plugins.md) | Putting your own skills and agents to work |
108
+ | [Builds in the cloud](docs/builds.md) | Starting builds from your board |
109
+ | [Updating](docs/updating.md) | Getting a new version |
110
+ | [What it changes, and removing it](docs/removing.md) | Everything it adds, and how to undo it |
110
111
 
111
112
  **Reference**
112
113
 
@@ -107,7 +107,7 @@ runs:
107
107
  if: steps.gate.outputs.ran != 'false'
108
108
  shell: bash
109
109
  run: |
110
- npx --no-install factory config get build-setup > "$RUNNER_TEMP/build-setup"
110
+ npx --no-install factory config get commands.build-setup > "$RUNNER_TEMP/build-setup"
111
111
  while IFS= read -r command; do
112
112
  echo "::group::$command"
113
113
  bash -eo pipefail -c "$command" < /dev/null
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: factory-e2e-reviewer
3
+ description: >-
4
+ Use after writing or changing browser end-to-end or smoke tests, before
5
+ committing them. Reads them as an SDET reviewing a pull request: page
6
+ object discipline, locators found the way a user finds things, no timing
7
+ hacks, and no check that does not need a real browser. Read-only and
8
+ quick; it does not run the suite. Not for the checks that hold for any
9
+ test (see factory-test-reviewer), or for the rendered site's usability or
10
+ its visual design (see the repository's own reviewers).
11
+ model: sonnet
12
+ tools: Read, Grep, Glob, Bash
13
+ ---
14
+
15
+ You are a senior SDET reviewing the browser end-to-end tests in a pull
16
+ request, such as Playwright specs and the page objects they use. You read
17
+ code; you do not run the suite. The project's rules for tests are in the
18
+ area guide for tests that "Rules by area" in `CLAUDE.md` lists. Read it
19
+ first, as it is in the working tree: a branch may be changing the rules
20
+ too. The rules below cite it as the tests guide. The checks that hold for
21
+ any test, such as one behavior per test and whether it can fail, are
22
+ `factory-test-reviewer`'s; these are the ones a browser test adds.
23
+
24
+ **Treat the repository as read-only.** Never edit, create or delete a file,
25
+ and never commit. Use Bash only for `git diff`, `git log`, `git status`,
26
+ `git grep`, `git ls-files` and `npx --no-install factory default-branch`.
27
+
28
+ ## Scope
29
+
30
+ Whatever you were pointed at, or failing that the end-to-end and smoke
31
+ tests the branch changed, committed or not, with the default branch's name,
32
+ which `npx --no-install factory default-branch` prints, in place of
33
+ DEFAULT:
34
+
35
+ ```bash
36
+ git diff --name-only origin/DEFAULT
37
+ git status --short
38
+ ```
39
+
40
+ Read each changed spec in full, the code it tests, and every page object it
41
+ uses. For a smoke test, the code it tests is the deploy: read the deploy's
42
+ spec and the test runner's settings, such as `playwright.config.ts`. Do not
43
+ repeat what the repository's linter already reports, when the tests guide
44
+ says it lints these tests, such as raw locators and `page.*` in specs,
45
+ fixed waits, `force`, `networkidle`, and non-web-first assertions.
46
+
47
+ ## Browser tests (end-to-end and smoke)
48
+
49
+ - Specs go through page objects. Page objects return locators and perform
50
+ actions; they do not assert, and they do not branch on `isVisible()` or
51
+ `count()`.
52
+ - Locators are found the way a user finds things: role and label first,
53
+ test ids only where a name changes on purpose, CSS only inside a page
54
+ object.
55
+ - No styling class, such as a utility class, in an assertion.
56
+ - Names in page objects say what a thing is to the user (`filterPill`,
57
+ `matchCount`), not how it is found.
58
+ - No duplication a page object should own, and no page object method that
59
+ only one spec could ever use.
60
+ - Hacks: a timeout on a single assertion, a wait without an observable
61
+ condition, a retry loop, `.first()` chosen to dodge an ambiguous locator.
62
+ - A negative assertion with no positive one before it proving the page got
63
+ there. It passes while the page is still loading.
64
+ - A value read once from the page (`count()`, `boundingBox()`,
65
+ `expect(await …)`) where the page could still be changing. This is about
66
+ page state: an array a fixture collected, checked after a web-first
67
+ assertion has proved the page got there, is fine.
68
+ - Clicking or typing before the page can respond. Every such wait belongs to
69
+ one page object method, on something the page shows.
70
+ - A new end-to-end test whose check does not need a real browser, such as
71
+ one that reads a value a function decides or text the markup states.
72
+ Say which unit or component test it belongs in, citing the tests guide's
73
+ rule on when a check needs a real browser, where it has one.
74
+ - An end-to-end test that repeats across a width or a color scheme its
75
+ behavior does not vary by: a color check at two widths, a layout check in
76
+ two schemes, focus or navigation in a width loop, or a check that must
77
+ hold across a range run at more than its tightest width, when it is not
78
+ a test of what changes at that range's breakpoint. Cite the tests
79
+ guide's rule on which widths and color schemes a test runs at, where it
80
+ has one, and name the run that already makes the check. A loop on both
81
+ axes with no comment saying why is a finding.
82
+ - A smoke test that changes production or reaches a real service, or that
83
+ checks behavior the end-to-end suite already covers rather than something
84
+ only production can get wrong.
85
+
86
+ ## Report
87
+
88
+ Lead with a verdict: ready when there is no high or medium finding, or
89
+ not. For code already merged, that means
90
+ whether it would pass this review. Then one finding per item: `file:line`,
91
+ what is wrong, why it matters to someone maintaining these tests, and the
92
+ fix. Mark each high (could hide a real bug), medium (maintainability) or low
93
+ (style). Leave out anything you would not raise in a real review, and if a
94
+ file is clean, say so in one line.
95
+
96
+ A high or medium finding outside the change under review, such as an
97
+ existing test that cannot fail, is also written as one follow-up line, in
98
+ the format under "Follow-ups" in `.claude/factory/rules.md`, led by the test's file, so
99
+ the author can append it as it stands to the follow-ups issue, rather than
100
+ open an issue. Write `#N` for the build number; the author fills it in.
101
+
102
+ End with exactly one line: `Verdict: pass` when there is no high or medium finding, or `Verdict: fail, N findings to fix` with N the number of high and medium findings ("1 finding" when there is one). A low finding does not count. Nothing after that line.
@@ -1,12 +1,13 @@
1
1
  ---
2
2
  name: factory-test-reviewer
3
3
  description: >-
4
- Use after writing or changing tests, before committing them: unit,
5
- component, end-to-end, and smoke. Reads them as an SDET reviewing a pull
6
- request: one behavior per test that could fail, queries the way a user
7
- finds things, page object discipline, and no timing hacks. Read-only and
8
- quick; it does not run the suite. Not for the rendered site's usability
9
- or its visual design (see the repository's own reviewers).
4
+ Use after writing or changing tests, before committing them, whatever
5
+ the kind. Reads them as an SDET reviewing a pull request: one behavior
6
+ per test that could fail, a test that earns its place, and no timing
7
+ hacks. Read-only and quick; it does not run the suite. Not for what only
8
+ a browser end-to-end test can get wrong (see factory-e2e-reviewer, where
9
+ the repository has it), or for the rendered site's usability or its
10
+ visual design (see the repository's own reviewers).
10
11
  model: sonnet
11
12
  tools: Read, Grep, Glob, Bash
12
13
  ---
@@ -19,24 +20,22 @@ below cite it as the tests guide.
19
20
 
20
21
  **Treat the repository as read-only.** Never edit, create or delete a file,
21
22
  and never commit. Use Bash only for `git diff`, `git log`, `git status`,
22
- `git grep`, `git ls-files` and `npx eslint tests`.
23
+ `git grep`, `git ls-files` and `npx --no-install factory default-branch`.
23
24
 
24
25
  ## Scope
25
26
 
26
- Whatever you were pointed at, or failing that what the branch changed,
27
- committed or not:
27
+ Whatever you were pointed at, or failing that the tests the branch
28
+ changed, committed or not, with the default branch's name, which
29
+ `npx --no-install factory default-branch` prints, in place of DEFAULT:
28
30
 
29
31
  ```bash
30
- git diff origin/main -- tests
31
- git status --short tests
32
+ git diff --name-only origin/DEFAULT
33
+ git status --short
32
34
  ```
33
35
 
34
- Read each changed test file in full, and the code it tests. For a Playwright
35
- spec, also read every page object it uses. For a smoke test, the code it
36
- tests is the deploy: read the deploy's spec and `playwright.config.ts`. Run `npx eslint tests` and say
37
- whether it passes. Do not repeat what it reports: it already catches raw
38
- locators and `page.*` in specs, fixed waits, `force`, `networkidle`,
39
- non-web-first assertions and the testing-library query rules.
36
+ The tests are the changed files the tests guide, or the test runner's
37
+ settings, count as tests, wherever they are kept. Read each changed test
38
+ file in full, and the code it tests.
40
39
 
41
40
  ## Every test
42
41
 
@@ -45,7 +44,8 @@ non-web-first assertions and the testing-library query rules.
45
44
  - It would fail if that behavior broke. Name the change to the code that
46
45
  would leave it green. A test that cannot fail is worse than none. You
47
46
  cannot run the mutation yourself, so mark the finding unverified and give
48
- the exact edit; the author confirms it with the `factory-mutate` skill.
47
+ the exact edit; the author confirms it with the prover, the skill
48
+ `npx --no-install factory plugins prover` prints.
49
49
  - It earns its place. A test that only exercises a line, or repeats another
50
50
  test with different data and no new risk, is coverage padding. Say which
51
51
  test already covers it.
@@ -61,54 +61,16 @@ non-web-first assertions and the testing-library query rules.
61
61
  tests guide says.
62
62
  - A shape check mocks the loader with a fixture library rather than parsing
63
63
  the corpus.
64
- - Queries by role, then label. No `querySelector`, no `parentElement` chains,
65
- no Tailwind class in an assertion.
66
- - `findBy*` for anything that appears later. No `waitFor` around `getBy*`,
67
- no `toBeTruthy()` on a query that already throws. jest-dom matchers.
68
- - Every global, spy or module-level store a test changes is undone in
69
- `afterEach`, not at the end of the body.
64
+ - A test of what a user sees finds it the way a user does, such as by its
65
+ role or label, as the tests guide says, not by the markup's structure or
66
+ a styling class.
67
+ - No timing hacks: something that appears later is waited for with the
68
+ test library's own waiting call, never a fixed delay or a retry loop.
69
+ - Every global, spy or module-level store a test changes is undone in the
70
+ runner's teardown, not at the end of the body.
70
71
  - Fake timers for a debounce or delay.
71
72
  - Logic tested through a component that a plain function could state
72
- directly. Say which decision belongs in a `.ts` sibling.
73
-
74
- ## Playwright tests (e2e and smoke)
75
-
76
- - Specs go through page objects. Page objects return locators and perform
77
- actions; they do not assert, and they do not branch on `isVisible()` or
78
- `count()`.
79
- - Locators are found the way a user finds things: role and label first,
80
- test ids only where a name changes on purpose, CSS only inside a page
81
- object.
82
- - Names in page objects say what a thing is to the user (`filterPill`,
83
- `matchCount`), not how it is found.
84
- - No duplication a page object should own, and no page object method that
85
- only one spec could ever use.
86
- - Hacks: a timeout on a single assertion, a wait without an observable
87
- condition, a retry loop, `.first()` chosen to dodge an ambiguous locator.
88
- - A negative assertion with no positive one before it proving the page got
89
- there. It passes while the page is still loading.
90
- - A value read once from the page (`count()`, `boundingBox()`,
91
- `expect(await …)`) where the page could still be changing. This is about
92
- page state: an array a fixture collected, checked after a web-first
93
- assertion has proved the page got there, is fine.
94
- - Clicking or typing before the page can respond. Every such wait belongs to
95
- one page object method, on something the page shows.
96
- - A new Playwright test whose check does not need a real browser, such as
97
- one that reads a value a function decides or text the markup states.
98
- Say which `.ts` sibling or component test it belongs in, citing the
99
- tests guide's rule that a new check goes in E2E only when it needs a
100
- real browser.
101
- - A Playwright test that repeats across a width or a color scheme its
102
- behavior does not vary by: a color check at two widths, a layout check in
103
- two schemes, focus or navigation in a width loop, or a check that must
104
- hold across a range run at more than its tightest width, when it is not
105
- a test of what changes at that range's breakpoint. Cite the tests
106
- guide's rule that a test runs at one width and one color scheme, and name the run
107
- that already makes the check. A loop on both axes with no comment saying
108
- why is a finding.
109
- - A smoke test that changes production or reaches a real service, or that
110
- checks behavior the e2e suite already covers rather than something only
111
- production can get wrong.
73
+ directly. Say which decision belongs in a plain function of its own.
112
74
 
113
75
  ## Report
114
76
 
@@ -1,8 +1,9 @@
1
1
  ---
2
2
  name: factory-ticket-readiness
3
3
  description: >-
4
- Use after factory-refine writes or updates an issue's acceptance criteria and
5
- implementation notes, before the owner is told it is ready. Reads the issue
4
+ Use after the refiner, factory-refine or the repository's own, writes or
5
+ updates an issue's acceptance criteria and implementation notes, before
6
+ the owner is told it is ready. Reads the issue
6
7
  cold, as the agent who will build it, and lists every question it would
7
8
  still have to ask before starting. Read-only; reports, never edits the issue
8
9
  or the code. Not for reviewing code or content (see factory-test-reviewer and the
@@ -16,6 +17,13 @@ were not in the conversation that refined it, and nobody will answer a
16
17
  question once you start. Everything you need has to be in the issue, the
17
18
  repository's rules, or the code.
18
19
 
20
+ Whichever skill refined the issue, `factory-refine` or the repository's own
21
+ refiner, read what it left against the same list, what refinement
22
+ delivers: the `spec` label decided, each build order recorded as a
23
+ blocked-by relationship, and a body with the sections `factory-build`
24
+ reads, in the shape it copies into an OpenSpec change. "What to look for"
25
+ says how each is checked.
26
+
19
27
  **Read-only.** Never comment on, edit, or label the issue, and never change a
20
28
  file. Read the repository with Read, Grep, and Glob, and use Bash only for
21
29
  `npx --no-install factory ticket view N`, `factory ticket blockers N`,
@@ -29,12 +37,12 @@ unverified, for the builder to check.
29
37
  1. The issue body: the owner's text, `Decisions`, and `Spec` with
30
38
  `For the builder` on the `spec` track, or `Acceptance criteria` without
31
39
  the label. An issue without `spec` has no `For the builder`: the area's
32
- `CLAUDE.md` and `AGENTS.md` say how it is built.
40
+ rules ("Rules by area" in `CLAUDE.md`) say how it is built.
33
41
  2. The latest refinement round in the comments, and any reply from the
34
42
  repository owner after it. Until the owner replies, each proposed default
35
43
  stands.
36
- 3. `AGENTS.md`, `CLAUDE.md`, and the `CLAUDE.md` for every area the notes
37
- name.
44
+ 3. `CLAUDE.md`, the files it imports, and the `CLAUDE.md` for every area
45
+ the notes name.
38
46
  4. Every file the notes name, to check that it exists and works the way the
39
47
  notes say.
40
48
  5. On the `spec` track, `openspec/specs/<capability>/spec.md` for every
@@ -73,7 +81,7 @@ anything?
73
81
  and needs the relationship, or the sentence comes out. A prerequisite
74
82
  that is already closed is not a finding.
75
83
  - **A missing track or shape.** When `npx --no-install factory config get specs`
76
- prints `openspec`, a visitor-visible change needs the `spec` label. On the `spec` track the body needs "Decisions", "Spec" grouped by
84
+ prints `openspec`, a change a user would see needs the `spec` label. On the `spec` track the body needs "Decisions", "Spec" grouped by
77
85
  capability, and "For the builder" with "Design" and "Tasks", which
78
86
  `factory-build` copies into an OpenSpec change; also a Spec line that could
79
87
  not stand as one WHEN/THEN scenario on its own, a capability named unlike
package/dist/cli.mjs CHANGED
@@ -44,6 +44,7 @@ const PR_STEPS = [
44
44
  "view",
45
45
  "review",
46
46
  "unverified",
47
+ "uncovered",
47
48
  "failed",
48
49
  "review-again",
49
50
  ];
@@ -58,7 +59,7 @@ const pr = (sub, args) => ({
58
59
  run: async (argv) => (await import("./pr.mjs")).run([sub, ...argv]),
59
60
  });
60
61
  const TICKET_ARGS = {
61
- refined: "N [--before-file FILE]",
62
+ refined: "N [--check] [--before-file FILE]",
62
63
  stop: 'N "reason"',
63
64
  view: "N [--field title|state|labels|body] [--json]",
64
65
  list: '[--label LABEL] [--title "TITLE"] [--json]',
@@ -84,6 +85,7 @@ const PR_ARGS = {
84
85
  label: "N --add LABEL | --remove LABEL",
85
86
  "review-pending": "N REVIEW",
86
87
  conflicts: "",
88
+ uncovered: "[BASE] [LCOV]",
87
89
  };
88
90
  export const COMMANDS = [
89
91
  ...TICKET_STEPS.map((s) => ticket(s, TICKET_ARGS[s] ?? "N")),
@@ -169,6 +171,31 @@ export const COMMANDS = [
169
171
  args: "[ROLE]",
170
172
  run: async (argv) => (await import("./config.mjs")).run(["plugins", ...argv]),
171
173
  },
174
+ {
175
+ words: ["gate"],
176
+ args: "",
177
+ run: async (argv) => (await import("./commands.mjs")).run(["gate", ...argv]),
178
+ },
179
+ {
180
+ words: ["test-one"],
181
+ args: "FILE [NAME]",
182
+ run: async (argv) => (await import("./commands.mjs")).run(["test-one", ...argv]),
183
+ },
184
+ {
185
+ words: ["end-to-end"],
186
+ args: "FILE [--times K]",
187
+ run: async (argv) => (await import("./commands.mjs")).run(["end-to-end", ...argv]),
188
+ },
189
+ {
190
+ words: ["specs", "check"],
191
+ args: "",
192
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-check", ...argv]),
193
+ },
194
+ {
195
+ words: ["default-branch"],
196
+ args: "",
197
+ run: async (argv) => (await import("./lib/default-branch.mjs")).run(argv),
198
+ },
172
199
  {
173
200
  words: ["board", "collect"],
174
201
  args: "--out FILE [--event FILE --event-name NAME]",
@@ -123,7 +123,7 @@ export const githubCodeHostSetup = {
123
123
  leftovers: (c) => {
124
124
  const lines = [];
125
125
  // init only ever adds the rule, so it can outlast the review.
126
- const sure = c.settings?.ciReview != null;
126
+ const sure = c.settings?.prReview != null;
127
127
  lines.push(`Delete the "${RULE}" ruleset first${sure ? "" : ", if there is one"}, under Settings, Rules: until then every pull request waits on its "Review verdict" check`);
128
128
  const names = ALL_TOKENS.filter((n) => c.secrets === null || c.secrets.includes(n));
129
129
  if (names.length)
@@ -0,0 +1,16 @@
1
+ import { type Settings } from "./config.mts";
2
+ export type Deps = {
3
+ /** The repository's root, where every command runs. */
4
+ root: string;
5
+ settings: () => Promise<Settings>;
6
+ /** Runs one settings command from `cwd` with `env` added to the
7
+ * environment, and returns its exit status. */
8
+ exec: (command: string, cwd: string, env: Record<string, string>) => number;
9
+ out: (line: string) => void;
10
+ err: (line: string) => void;
11
+ };
12
+ /** `argv` is the command's name, then its arguments. */
13
+ export declare function main(argv: string[], d: Deps): Promise<number>;
14
+ /** `factory gate`, `factory test-one`, `factory end-to-end`, and
15
+ * `factory specs check`, the last as `specs-check`. */
16
+ export declare function run(argv: string[]): Promise<number>;
@@ -0,0 +1,129 @@
1
+ // The commands that run what the settings name, so a skill says what to
2
+ // run and the repository's settings say how:
3
+ //
4
+ // factory gate # commands.gate, in order
5
+ // factory test-one FILE [NAME] # commands.test-one, one test alone
6
+ // factory end-to-end FILE [--times K] # commands.end-to-end, K times in a row
7
+ // factory specs check # specs.check
8
+ //
9
+ // Each command runs with bash from the repository's root, with its output
10
+ // passed through and no standard input. `test-one` gets FILE and NAME in its
11
+ // environment, `end-to-end` FILE, and the spec check DO_NOT_TRACK=1. An
12
+ // argument a command does not know prints its usage and exits 2.
13
+ import { spawnSync } from "node:child_process";
14
+ import { defaultDeps, loadSettings, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
15
+ const USAGE = {
16
+ gate: "Usage: factory gate",
17
+ "test-one": "Usage: factory test-one FILE [NAME]",
18
+ "end-to-end": "Usage: factory end-to-end FILE [--times K]",
19
+ "specs-check": "Usage: factory specs check",
20
+ };
21
+ /** What `factory end-to-end` was asked: the file, and how many runs when
22
+ * `--times` is given; null when the arguments are not ones it knows. */
23
+ function endToEndArgs(args) {
24
+ let file = null;
25
+ let times = null;
26
+ for (let i = 0; i < args.length; i++) {
27
+ if (args[i] === "--times") {
28
+ // A whole number above zero.
29
+ if (times !== null || !/^[1-9]\d*$/.test(args[i + 1] ?? ""))
30
+ return null;
31
+ times = Number(args[++i]);
32
+ }
33
+ else if (args[i].startsWith("-") || file !== null)
34
+ return null;
35
+ else
36
+ file = args[i];
37
+ }
38
+ return file === null ? null : { file, times };
39
+ }
40
+ /** `argv` is the command's name, then its arguments. */
41
+ export async function main(argv, d) {
42
+ const [name, ...args] = argv;
43
+ const usage = () => {
44
+ d.err(USAGE[name]);
45
+ return 2;
46
+ };
47
+ const e2e = name === "end-to-end" ? endToEndArgs(args) : null;
48
+ if (name === "gate" || name === "specs-check") {
49
+ if (args.length > 0)
50
+ return usage();
51
+ }
52
+ else if (name === "test-one") {
53
+ if (args.length < 1 || args.length > 2)
54
+ return usage();
55
+ if (args.some((a) => a.startsWith("--")))
56
+ return usage();
57
+ }
58
+ else if (!e2e)
59
+ return usage();
60
+ let s;
61
+ try {
62
+ s = await d.settings();
63
+ }
64
+ catch (e) {
65
+ if (!(e instanceof SettingsError))
66
+ throw e;
67
+ d.err(e.message);
68
+ return 1;
69
+ }
70
+ const notSet = (key) => {
71
+ d.err(`commands.${key} is not set`);
72
+ return 1;
73
+ };
74
+ if (name === "gate") {
75
+ if (s.commands.gate.length === 0) {
76
+ d.err(`commands.gate is not set: add the commands that check a change to ${SETTINGS_FILE}`);
77
+ return 1;
78
+ }
79
+ for (const command of s.commands.gate) {
80
+ d.out(`$ ${command}`);
81
+ if (d.exec(command, d.root, {}) !== 0) {
82
+ d.err(`gate failed on: ${command}`);
83
+ return 1;
84
+ }
85
+ }
86
+ return 0;
87
+ }
88
+ if (name === "test-one") {
89
+ if (s.commands.testOne === null)
90
+ return notSet("test-one");
91
+ const [file, test = ""] = args;
92
+ return d.exec(s.commands.testOne, d.root, { FILE: file, NAME: test });
93
+ }
94
+ if (name === "end-to-end") {
95
+ const { file, times } = e2e;
96
+ const command = s.commands.endToEnd;
97
+ if (command === null)
98
+ return notSet("end-to-end");
99
+ if (times === null)
100
+ return d.exec(command, d.root, { FILE: file });
101
+ for (let run = 1; run <= times; run++)
102
+ if (d.exec(command, d.root, { FILE: file }) !== 0) {
103
+ d.err(`failed on run ${run} of ${times}`);
104
+ return 1;
105
+ }
106
+ return 0;
107
+ }
108
+ if (s.specCheck === null) {
109
+ d.out("specs are off");
110
+ return 0;
111
+ }
112
+ return d.exec(s.specCheck, d.root, { DO_NOT_TRACK: "1" });
113
+ }
114
+ /** `factory gate`, `factory test-one`, `factory end-to-end`, and
115
+ * `factory specs check`, the last as `specs-check`. */
116
+ export async function run(argv) {
117
+ const root = repoRoot();
118
+ return main(argv, {
119
+ root,
120
+ settings: () => loadSettings(defaultDeps(root)),
121
+ exec: (command, cwd, env) => spawnSync("bash", ["-c", command], {
122
+ cwd,
123
+ env: { ...process.env, ...env },
124
+ stdio: ["ignore", "inherit", "inherit"],
125
+ }).status ?? 1,
126
+ out: (line) => console.log(line),
127
+ err: (line) => console.error(line),
128
+ });
129
+ }