@davidbyoung/software-factory 0.1.3 → 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.
Files changed (72) 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 +29 -2
  7. package/dist/commands.d.mts +16 -0
  8. package/dist/commands.mjs +129 -0
  9. package/dist/config.d.mts +61 -13
  10. package/dist/config.mjs +267 -65
  11. package/dist/deps.d.mts +7 -4
  12. package/dist/deps.mjs +20 -9
  13. package/dist/doctor.d.mts +3 -2
  14. package/dist/doctor.mjs +19 -4
  15. package/dist/explain.d.mts +4 -2
  16. package/dist/explain.mjs +66 -19
  17. package/dist/guard-commit.d.mts +7 -2
  18. package/dist/guard-commit.mjs +58 -21
  19. package/dist/init.d.mts +4 -2
  20. package/dist/init.mjs +15 -5
  21. package/dist/lib/default-branch.d.mts +35 -0
  22. package/dist/lib/default-branch.mjs +117 -0
  23. package/dist/lib/refined-check.d.mts +7 -0
  24. package/dist/lib/refined-check.mjs +76 -0
  25. package/dist/patch-coverage.d.mts +13 -0
  26. package/dist/patch-coverage.mjs +73 -0
  27. package/dist/pr-watch.d.mts +3 -2
  28. package/dist/pr-watch.mjs +22 -5
  29. package/dist/pr.mjs +34 -2
  30. package/dist/session-start.d.mts +23 -13
  31. package/dist/session-start.mjs +56 -44
  32. package/dist/site/servers.d.mts +6 -2
  33. package/dist/site/servers.mjs +14 -9
  34. package/dist/site.mjs +2 -2
  35. package/dist/sync.d.mts +8 -2
  36. package/dist/sync.mjs +40 -6
  37. package/dist/ticket.mjs +19 -1
  38. package/docs/builds.md +8 -8
  39. package/docs/cli.md +82 -45
  40. package/docs/configuration.md +455 -139
  41. package/docs/design.md +17 -4
  42. package/docs/developing.md +37 -6
  43. package/docs/existing-repo.md +8 -6
  44. package/docs/github/by-hand.md +23 -10
  45. package/docs/github/reference.md +19 -14
  46. package/docs/github/setup.md +12 -9
  47. package/docs/glossary.md +13 -3
  48. package/docs/limitations.md +27 -2
  49. package/docs/plugins.md +302 -48
  50. package/docs/quick-start.md +36 -8
  51. package/docs/removing.md +1 -1
  52. package/docs/skills.md +101 -52
  53. package/docs/updating.md +148 -3
  54. package/docs/workflow.md +13 -10
  55. package/package.json +1 -1
  56. package/review.md +20 -11
  57. package/rules.md +22 -18
  58. package/settings.schema.json +289 -69
  59. package/skills/factory-address-review/SKILL.md +50 -30
  60. package/skills/factory-build/SKILL.md +75 -22
  61. package/skills/factory-deps/SKILL.md +46 -21
  62. package/skills/factory-design/SKILL.md +17 -8
  63. package/skills/factory-diagnose/SKILL.md +22 -20
  64. package/skills/factory-mutate/SKILL.md +38 -24
  65. package/skills/factory-refine/SKILL.md +55 -31
  66. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  67. package/skills/factory-trace/SKILL.md +3 -2
  68. package/workflows/factory-build.yml +1 -1
  69. package/workflows/factory-conflicts.yml +8 -8
  70. package/workflows/factory-deps.yml +1 -1
  71. package/workflows/factory-review.yml +1 -1
  72. package/skills/factory-address-review/patch-coverage.py +0 -68
package/dist/sync.mjs CHANGED
@@ -7,13 +7,16 @@
7
7
  // factory sync # write what differs
8
8
  // factory sync --check # write nothing; exit 1 naming what differs
9
9
  //
10
- // A copy is the source, byte for byte: edit the source in the package, never
11
- // the copy. A file the lock lists that the package no longer has is
10
+ // A copy is the source, byte for byte but for what the settings and the
11
+ // repository decide: the minutes a session may run, the poller's schedule,
12
+ // the rules' numbers, and the default branch's name in the push triggers.
13
+ // Edit the source in the package, never the copy. A file the lock lists that the package no longer has is
12
14
  // deleted. Nothing else is.
13
15
  import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
14
16
  import { dirname, join, relative, sep } from "node:path";
15
17
  import { fileURLToPath } from "node:url";
16
18
  import { defaultDeps, loadSettings, repoRoot, RULE_NUMBERS, } from "./config.mjs";
19
+ import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
17
20
  /** The package's own folder: the parent of `src/`, or of `dist/` once
18
21
  * compiled. */
19
22
  export const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -30,6 +33,7 @@ const DEPENDABOT = ".github/dependabot.yml";
30
33
  const NEEDS = {
31
34
  "skills/factory-design": (s) => s.site !== null,
32
35
  "agents/factory-ui-reviewer.md": (s) => s.site !== null,
36
+ "agents/factory-e2e-reviewer.md": (s) => s.commands.endToEnd !== null,
33
37
  "skills/factory-deps": (_, has) => has(DEPENDABOT),
34
38
  "workflows/factory-deps.yml": (_, has) => has(DEPENDABOT),
35
39
  "workflows/factory-deps-auto-merge.yml": (_, has) => has(DEPENDABOT),
@@ -48,6 +52,24 @@ export function withSchedule(text, minutes, file) {
48
52
  const cron = minutes === 60 ? "0 * * * *" : `*/${minutes} * * * *`;
49
53
  return text.replace(pattern, (_, lead) => `${lead}"${cron}"`);
50
54
  }
55
+ /** The workflows whose push trigger names the default branch. A workflow
56
+ * cannot ask for it in a trigger, so the sync writes it there. */
57
+ const PUSH_WORKFLOWS = [
58
+ "workflows/factory-check.yml",
59
+ "workflows/factory-conflicts.yml",
60
+ ];
61
+ /** A workflow with the one `branches:` line of its push trigger naming the
62
+ * default branch and nothing else. */
63
+ export function withDefaultBranch(text, name, file) {
64
+ const pattern = /^(\s+branches: )\[[^\]\n]*\]$/gm;
65
+ if ((text.match(pattern) ?? []).length !== 1)
66
+ throw new Error(`${file}: expected one branches line, to set the push trigger's branch`);
67
+ // Plain where YAML reads the name as text, quoted otherwise.
68
+ const written = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(name)
69
+ ? name
70
+ : JSON.stringify(name);
71
+ return text.replace(pattern, (_, lead) => `${lead}[${written}]`);
72
+ }
51
73
  /** The workflows that run a Claude session, by the kind of session each
52
74
  * runs. */
53
75
  const SESSION_WORKFLOWS = {
@@ -344,14 +366,18 @@ export function lockedFiles(text) {
344
366
  .map((l) => /^ {2}- (.+)$/.exec(l)?.[1])
345
367
  .filter((f) => Boolean(f));
346
368
  }
347
- /** What a sync of `root` from `pkg` writes and deletes. */
348
- export function plan(pkg, root, s) {
369
+ /** What a sync of `root` from `pkg` writes and deletes, in a repository
370
+ * whose default branch is `branch`. */
371
+ export function plan(pkg, root, s, branch) {
349
372
  const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
350
373
  const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
351
374
  const write = new Map();
352
375
  const has = (p) => existsSync(join(root, p));
353
376
  for (const [from, to] of copies(pkg, s, has)) {
354
- const text = readFileSync(join(pkg, from), "utf8");
377
+ const source = readFileSync(join(pkg, from), "utf8");
378
+ const text = PUSH_WORKFLOWS.includes(from)
379
+ ? withDefaultBranch(source, branch, from)
380
+ : source;
355
381
  const kind = SESSION_WORKFLOWS[from.replace(/^workflows\//, "")];
356
382
  write.set(to, kind && from.startsWith("workflows/")
357
383
  ? withMinutes(text, s.sessionMinutes[kind], from)
@@ -387,7 +413,14 @@ export async function main(argv, d) {
387
413
  d.err(e instanceof Error ? e.message : String(e));
388
414
  return 1;
389
415
  }
390
- const p = plan(d.pkg, d.root, s);
416
+ // Nothing is written with a guessed name: a push trigger that names the
417
+ // wrong branch never runs.
418
+ const branch = await d.defaultBranch();
419
+ if (branch === null) {
420
+ d.err(CANNOT_TELL);
421
+ return 1;
422
+ }
423
+ const p = plan(d.pkg, d.root, s, branch);
391
424
  const differ = differences(d.root, p);
392
425
  if (check) {
393
426
  if (differ.length === 0)
@@ -419,6 +452,7 @@ export async function run(argv) {
419
452
  root,
420
453
  pkg: PACKAGE,
421
454
  settings: () => loadSettings(defaultDeps(root)),
455
+ defaultBranch: () => defaultBranch(branchDeps(root)),
422
456
  out: (line) => console.log(line),
423
457
  err: (line) => console.error(line),
424
458
  });
package/dist/ticket.mjs CHANGED
@@ -8,7 +8,7 @@
8
8
  // npx --no-install factory ticket stop N "one-line reason"
9
9
  // npx --no-install factory ticket end N
10
10
  // npx --no-install factory ticket refining|waiting N
11
- // npx --no-install factory ticket refined N [--before-file FILE]
11
+ // npx --no-install factory ticket refined N [--check] [--before-file FILE]
12
12
  // npx --no-install factory follow-up FILE "what is wrong"
13
13
  // npx --no-install factory ticket ready N
14
14
  // npx --no-install factory ticket cost N
@@ -36,6 +36,11 @@
36
36
  // or pull request N. The clock is keyed by CLAUDE_CODE_SESSION_ID, the ID the
37
37
  // hooks receive and the transcript's file name.
38
38
  //
39
+ // `refined` posts its marker only on a ticket whose body a build can read
40
+ // (`lib/refined-check.mts`): otherwise it prints one line for each part that
41
+ // is missing and exits 1. With `--check` it posts nothing, and prints
42
+ // `sound` when nothing is missing.
43
+ //
39
44
  // `ready` moves issue N's card to Ready when the owner asks a session to, so
40
45
  // the sync and the poller treat it as the owner's own move. It is the one
41
46
  // write to Status outside the sync, and needs the project scope:
@@ -55,6 +60,7 @@ import { openCodeHost } from "./code-host/index.mjs";
55
60
  import { openRunner } from "./runner/index.mjs";
56
61
  import { loadSettings, targetOf } from "./config.mjs";
57
62
  import { commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
63
+ import { missingParts } from "./lib/refined-check.mjs";
58
64
  import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
59
65
  import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
60
66
  import { boardConfigOf, checkFields } from "./board.mjs";
@@ -509,6 +515,18 @@ export async function main(argv, deps) {
509
515
  await post(d, issue, { kind: "cost", cost: takeCost(issue, d) });
510
516
  break;
511
517
  case "refined": {
518
+ // A body the build could not read gets no marker, whoever wrote it.
519
+ const ticket = await d.tickets.read(issue);
520
+ const missing = missingParts(ticket.body, ticket.labels);
521
+ if (missing.length > 0) {
522
+ for (const line of missing)
523
+ console.error(line);
524
+ return 1;
525
+ }
526
+ if (rest.includes("--check")) {
527
+ d.out("sound");
528
+ return 0;
529
+ }
512
530
  const at = rest.indexOf("--before-file");
513
531
  const before = at === -1 ? undefined : d.readFile(rest[at + 1]);
514
532
  await post(d, issue, {
package/docs/builds.md CHANGED
@@ -72,8 +72,8 @@ the account the build acts as. Without one, its commits are unsigned.
72
72
  commits is not shown as verified, when your own git signs commits.
73
73
 
74
74
  **Before the session starts,** the commands under
75
- [`build-setup`](configuration.md#build-setup) in your settings run, after
76
- your npm dependencies are installed.
75
+ [`commands.build-setup`](configuration.md#commandsbuild-setup) in your
76
+ settings run, after your npm dependencies are installed.
77
77
 
78
78
  ## The other jobs that run in the cloud
79
79
 
@@ -82,11 +82,11 @@ anything to do and starts a session only when there is, so a run with
82
82
  nothing to do costs about a minute of the runner and no use of the agent. A
83
83
  run that works costs about what a build does.
84
84
 
85
- | Job | Starts on | What the session does |
86
- | ------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
87
- | Answering your review | A review you submit on a pull request | Works your comments with `factory-address-review` |
88
- | The conflict sweep | A push to your main branch, nightly, or by hand | Merges your main branch into each pull request that conflicts with it, with `factory-resolve-conflicts` |
89
- | Dependency pull requests | Three times a day, or by hand | Moves each dependency update toward merged, with `factory-deps`, in a repository with a `.github/dependabot.yml` |
85
+ | Job | Starts on | What the session does |
86
+ | ------------------------ | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
87
+ | Answering your review | A review you submit on a pull request | Works your comments with `factory-address-review` |
88
+ | The conflict sweep | A push to your default branch, nightly, or by hand | Merges your default branch into each pull request that conflicts with it, with `factory-resolve-conflicts` |
89
+ | Dependency pull requests | Three times a day, or by hand | Moves each dependency update toward merged, with `factory-deps`, in a repository with a `.github/dependabot.yml` |
90
90
 
91
91
  Each acts as the same account a build does. The review job answers your
92
92
  reviews only: the factory's own replies start runs that find nothing of
@@ -101,7 +101,7 @@ each ticket in Ready with no open blocker it:
101
101
 
102
102
  1. posts a comment on the ticket saying a build is starting, carrying a
103
103
  marker;
104
- 2. starts a build of that ticket in the cloud, from your main branch.
104
+ 2. starts a build of that ticket in the cloud, from your default branch.
105
105
 
106
106
  ```bash
107
107
  factory poller
package/docs/cli.md CHANGED
@@ -55,11 +55,15 @@ read is set.
55
55
  | ------------------------ | ----------------------------------------------------------------- | ----- |
56
56
  | `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
57
57
  | `factory config explain` | To see every setting in effect, defaults included | Built |
58
- | `factory plugins` | To see your plug-ins by role | Built |
58
+ | `factory plugins` | To see the plug-ins the factory will use, by slot | Built |
59
59
  | `factory site compare` | To picture a website's pages before and after a change. See below | Built |
60
60
  | `factory site stop` | To end the sites `compare --keep` left running | Built |
61
61
  | `factory remove` | To take the factory out of a repository | Built |
62
62
 
63
+ `factory plugins` prints one line for each plug-in, the factory's own
64
+ included: its kind, its name, its [slot](plugins.md#the-slots), then its
65
+ files or labels. `factory plugins SLOT` prints one slot's lines.
66
+
63
67
  A new version is installed with npm and applied with `factory sync`, as
64
68
  [Updating](updating.md) says. [Removing](removing.md) says what `remove`
65
69
  deletes and what it leaves to you.
@@ -102,42 +106,48 @@ ticket system would swallow, name it, and post nothing.
102
106
  | `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
103
107
  | `factory ticket refining N` | Marks N as being refined |
104
108
  | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
105
- | `factory ticket refined N` | Marks N as refined and waiting for your approval |
109
+ | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
106
110
  | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
107
111
  | `factory ticket cost N` | Notes what this session spent on N since it started |
108
112
  | `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
109
113
 
114
+ `factory ticket refined N` posts nothing and exits 1 when N's body lacks a
115
+ section a build reads, printing one line for each, such as
116
+ `missing: ## Acceptance criteria`. With `--check` it prints `sound` for a
117
+ body that passes. [Plug-ins](plugins.md#refiner) lists the sections.
118
+
110
119
  ### Pull requests
111
120
 
112
121
  Pull requests stay on the code host whatever the ticket system. A pull
113
122
  request's conversation comments and labels go through these, never the
114
123
  ticket system.
115
124
 
116
- | Command | What it does |
117
- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
118
- | `factory pr state [N]` | What stands between N and a merge: checks, review, threads, conflict |
119
- | `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
120
- | `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
121
- | `factory pr resolve N COMMENT` | Resolves a thread |
122
- | `factory pr closes N` | The tickets N closes |
123
- | `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
124
- | `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
125
- | `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
126
- | `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does |
127
- | `factory pr comment-view ID` | Prints one conversation comment's body |
128
- | `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
129
- | `factory pr watch N` | Waits until N needs attention, says why, and exits |
130
- | `factory pr watch N --release` | Stops watching N |
131
- | `factory pr review-pending N REVIEW` | Exits 0 when the owner's review has something of theirs to answer, and 1, saying why, when it has not |
132
- | `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none |
133
- | `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open |
134
- | `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out) |
135
- | `factory pr review N REVIEW` | One review as JSON: its author, its body, and each comment it left on a line, with the comment a reply replies to |
136
- | `factory pr unverified N` | Each of N's commits the code host does not show as signed, with the reason. Prints nothing when it shows them all |
137
- | `factory pr failed N` | For N's last commit, the failures `wait-checks` counts: each failed job's name and the last 200 lines of its log, from the newest run of each workflow started by a push or a pull request, and what a check that did not pass wrote about itself. Prints nothing when nothing failed |
138
- | `factory pr review-again N` | Asks for a fresh review of N's last commit. Exits 1, saying so, when no review has run on it |
139
- | `factory deps` | The open dependency pull requests, their checks, and what each needs |
140
- | `factory deps --any` | Exits 0 when a dependency pull request is open and 1 when none is |
125
+ | Command | What it does |
126
+ | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
127
+ | `factory pr state [N]` | What stands between N and a merge: checks, review, threads, conflict |
128
+ | `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
129
+ | `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
130
+ | `factory pr resolve N COMMENT` | Resolves a thread |
131
+ | `factory pr closes N` | The tickets N closes |
132
+ | `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
133
+ | `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
134
+ | `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
135
+ | `factory pr comment N --body-file FILE` | Posts a conversation comment and prints its ID. Refuses a bare tag-like `<word>`, as `ticket comment` does |
136
+ | `factory pr comment-view ID` | Prints one conversation comment's body |
137
+ | `factory pr label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
138
+ | `factory pr watch N` | Waits until N needs attention, says why, and exits |
139
+ | `factory pr watch N --release` | Stops watching N |
140
+ | `factory pr review-pending N REVIEW` | Exits 0 when the owner's review has something of theirs to answer, and 1, saying why, when it has not |
141
+ | `factory pr conflicts` | The pull requests the conflict sweep takes, one number a line; exits 0 when there is one and 1 when none |
142
+ | `factory pr open --title TITLE --body-file FILE` | Opens a draft pull request from the current branch into the default branch and prints its number. `--base BRANCH` names another base, and `--ready` opens it ready for review. Fails in the code host's own words when the branch has nothing new or already has one open |
143
+ | `factory pr view N --field FIELD` | Prints one field of N: `head` (its last commit, in full), `branch`, `base`, `title`, `body`, `state`, or `mergeable` (`dirty` for a conflict, `unknown` until the code host has worked it out) |
144
+ | `factory pr review N REVIEW` | One review as JSON: its author, its body, and each comment it left on a line, with the comment a reply replies to |
145
+ | `factory pr unverified N` | Each of N's commits the code host does not show as signed, with the reason. Prints nothing when it shows them all |
146
+ | `factory pr uncovered [BASE] [LCOV]` | The lines the branch added or changed that the coverage report shows no test covers, a file at a time: `MISS` for a line no test ran, and `PART` for a line that ran with a branch never taken. `BASE` is what the branch is compared with, and is the default branch on `origin` when left out. `LCOV` is the report, and is `coverage/lcov.info` when left out. Prints nothing when every such line is covered |
147
+ | `factory pr failed N` | For N's last commit, the failures `wait-checks` counts: each failed job's name and the last 200 lines of its log, from the newest run of each workflow started by a push or a pull request, and what a check that did not pass wrote about itself. Prints nothing when nothing failed |
148
+ | `factory pr review-again N` | Asks for a fresh review of N's last commit. Exits 1, saying so, when no review has run on it |
149
+ | `factory deps` | The open dependency pull requests, their checks, and what each needs |
150
+ | `factory deps --any` | Exits 0 when a dependency pull request is open and 1 when none is |
141
151
 
142
152
  `factory pr wait-checks N` waits until the code host
143
153
  shows the commit you pushed as N's head, then until the newest run of each
@@ -146,25 +156,50 @@ the factory's own jobs, so a failed board sync does not stop a pull
146
156
  request being marked ready. With no run two minutes after the commit became the head, it
147
157
  prints `no checks` and exits 0. A failure exits 3.
148
158
 
159
+ ### Your repository's commands
160
+
161
+ Skills call these to check and test a change, so no skill names a test
162
+ runner or a linter: each runs what your settings list under
163
+ [`commands`](configuration.md#commands) and
164
+ [`specs`](configuration.md#specs), with bash, from the repository's root.
165
+ You can run them too.
166
+
167
+ | Command | What it does |
168
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
169
+ | `factory gate` | Runs each [`commands.gate`](configuration.md#commandsgate) command in order, printing `$` and the command before each. Stops at the first that fails, with `gate failed on:` and the command. Exits 0 when every command passes, and 1 at the first that fails or when no gate is set |
170
+ | `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
171
+ | `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails |
172
+ | `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status. Prints `specs are off` when `specs` is `none` |
173
+ | `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
174
+
175
+ `factory default-branch` asks, in turn, the event of the workflow run it
176
+ is in, `origin/HEAD` in your checkout, and the code host, whose answer it
177
+ writes to `origin/HEAD` so the next run asks nobody. A checkout with no
178
+ `origin` remote takes git's own `init.defaultBranch`, or `main`. When a
179
+ remote exists and none of the three answers, it exits 1 with
180
+ `Could not tell the default branch. Run: git remote set-head origin --auto`.
181
+ `factory sync` and `factory site compare` stop with the same line, and
182
+ the commit hook blocks a session's git command with it.
183
+
149
184
  ### Workflows and hooks
150
185
 
151
- | Command | Run by | What it does | State |
152
- | --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----- |
153
- | `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
154
- | `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
155
- | `factory board --dry-run` | You, to see what it would set | Reads the tickets and the board, prints what the sync would set, and writes nothing | Built |
156
- | `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
157
- | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
158
- | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
159
- | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
160
- | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
161
- | `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
162
- | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
163
- | `factory guard commit` | Within `factory guard` | Blocks a commit on your main branch, a force push, or a failing [`before-commit`](configuration.md#before-commit) command | Built |
164
- | `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
165
- | `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
166
- | `factory reviewers stop` | A hook, when an agent stops | The same | Built |
167
- | `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
186
+ | Command | Run by | What it does | State |
187
+ | --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
188
+ | `factory board collect` | The board-sync workflow | Reads the tickets and posts the comments a closed pull request or the nightly run needs | Built |
189
+ | `factory board apply` | The board-sync workflow | Sets each ticket's column and fields from its comments | Built |
190
+ | `factory board --dry-run` | You, to see what it would set | Reads the tickets and the board, prints what the sync would set, and writes nothing | Built |
191
+ | `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
192
+ | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
193
+ | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
194
+ | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
195
+ | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
196
+ | `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
197
+ | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
198
+ | `factory guard commit` | Within `factory guard` | Blocks a commit on your default branch, a push to it, a force push, or a commit while a [`commands.before-commit`](configuration.md#commandsbefore-commit) command fails | Built |
199
+ | `factory guard ticket-text` | Within `factory guard` | Refuses ticket text with a bare `<tag>`, which the ticket system would swallow | Built |
200
+ | `factory reviewers start` | A hook, when an agent starts | Records a reviewer's run on the ticket, for its cost | Built |
201
+ | `factory reviewers stop` | A hook, when an agent stops | The same | Built |
202
+ | `factory session-start` | A hook, when a session starts | Shows unfinished branches and each ticket's state | Built |
168
203
 
169
204
  The board sync runs `collect` and `apply` as two steps, so the board's
170
205
  token reaches only the second. The board's number comes from
@@ -174,7 +209,9 @@ token reaches only the second. The board's number comes from
174
209
 
175
210
  - `0`: done, or the answer is the line printed.
176
211
  - `2`: no such command; the usage is printed. A guard also exits 2 when it
177
- blocks a call.
212
+ blocks a call, and so does one of
213
+ [your repository's commands](#your-repositorys-commands) given an
214
+ argument it does not know.
178
215
  - `3`: `pr wait-checks` saw a check fail.
179
216
  - Any other non-zero: it could not do it, and the reason is on standard
180
217
  error. A command that could not reach the code host or the ticket system