@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.
Files changed (120) hide show
  1. package/README.md +20 -20
  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/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. package/skills/factory-address-review/patch-coverage.py +0 -68
package/dist/config.mjs CHANGED
@@ -4,7 +4,7 @@
4
4
  // what its functions need, and nothing under src/lib/ loads them.
5
5
  //
6
6
  // factory config get KEY # e.g. repository, tickets.board
7
- // factory plugins [ROLE] # kind, name, role, files or labels
7
+ // factory plugins [SLOT] # kind, name, slot, files or labels
8
8
  // factory config check # prints nothing when sound
9
9
  //
10
10
  // A list prints one item per line. A failure names the key and exits 1.
@@ -15,17 +15,87 @@ import { dirname, join } from "node:path";
15
15
  import { DEFAULT_CODE_HOST, unsupportedCodeHost } from "./code-host/index.mjs";
16
16
  import { matchesAny } from "./lib/glob.mjs";
17
17
  import { DEFAULT_RUNNER, unsupportedRunner } from "./runner/index.mjs";
18
- import { DEFAULT_COLUMNS, STATE_KEYS, sameName, } from "./lib/work-status.mjs";
18
+ import { BUILT, unsupported } from "./tool-names.mjs";
19
+ import { DEFAULT_COLUMNS, STATE_KEYS, sameName, watchOf, } from "./lib/work-status.mjs";
19
20
  export class SettingsError extends Error {
20
21
  }
21
- export const ROLES = ["mockups", "builder", "reviewer"];
22
+ /** What a plug-in does, in the order `factory plugins` prints them. */
23
+ export const SLOTS = [
24
+ "refiner",
25
+ "mockups",
26
+ "builder",
27
+ "reviewer",
28
+ "prover",
29
+ "test-reviewer",
30
+ "resolver",
31
+ ];
32
+ /** The phases `plugins` is grouped by. */
33
+ export const PHASES = ["refine", "build", "test", "conflicts"];
34
+ /** A slot's shape: one plug-in with no files and no labels, unless `takes`
35
+ * says otherwise. */
36
+ const shapeOf = (phase, key, kind, takes = {}) => ({
37
+ phase,
38
+ key,
39
+ kind,
40
+ list: false,
41
+ files: "none",
42
+ labels: "none",
43
+ ...takes,
44
+ });
45
+ /** Each slot: the phase and key it is written under, the one kind it
46
+ * takes, whether it holds one plug-in or a list, and whether a plug-in in
47
+ * it must have, may have, or cannot have `files` and `labels`. */
48
+ export const SLOT_SHAPE = {
49
+ refiner: shapeOf("refine", "refiner", "skill"),
50
+ mockups: shapeOf("refine", "mockups", "skill"),
51
+ builder: shapeOf("build", "builders", "skill", {
52
+ list: true,
53
+ labels: "required",
54
+ }),
55
+ reviewer: shapeOf("build", "reviewers", "agent", {
56
+ list: true,
57
+ files: "required",
58
+ }),
59
+ prover: shapeOf("test", "prover", "skill"),
60
+ "test-reviewer": shapeOf("test", "reviewers", "agent", {
61
+ list: true,
62
+ files: "optional",
63
+ }),
64
+ resolver: shapeOf("conflicts", "resolvers", "skill", {
65
+ list: true,
66
+ files: "required",
67
+ }),
68
+ };
69
+ /** A slot's path in the settings, such as `plugins.build.reviewers`. */
70
+ const slotPath = (slot) => `plugins.${SLOT_SHAPE[slot].phase}.${SLOT_SHAPE[slot].key}`;
71
+ /** The keys of each slot's block, by its path in `SETTINGS_KEYS`: a list's
72
+ * items are under the path with `[]` after it. */
73
+ const slotKeys = () => Object.fromEntries(SLOTS.map((slot) => {
74
+ const shape = SLOT_SHAPE[slot];
75
+ return [
76
+ `${slotPath(slot)}${shape.list ? "[]" : ""}`,
77
+ [
78
+ shape.kind,
79
+ ...(shape.files === "none" ? [] : ["files"]),
80
+ ...(shape.labels === "none" ? [] : ["labels"]),
81
+ ],
82
+ ];
83
+ }));
22
84
  export const TRIGGERS = ["own-server", "github-action", "manual"];
85
+ /** How often the scheduled poller may check the board, in minutes: each
86
+ * divides an hour, so a schedule every N minutes keeps an even beat. */
87
+ export const POLL_MINUTES = [5, 10, 15, 30, 60];
23
88
  export const SPECS = ["none", "openspec"];
24
89
  const FIELD_DEFAULTS = {
25
90
  session: "Session",
26
91
  "runs-in": "Runs in",
27
92
  cost: "Cost",
28
93
  };
94
+ /** Each number the rules use, with its default. */
95
+ export const RULE_NUMBERS = {
96
+ "small-change-lines": 30,
97
+ "review-rounds": 2,
98
+ };
29
99
  /** Each kind of unattended session, with how long it may run by default. */
30
100
  export const SESSION_MINUTES = {
31
101
  build: 230,
@@ -41,11 +111,17 @@ export const ACCESSIBILITY = [
41
111
  ];
42
112
  /** The agent that needs `site`. */
43
113
  export const SITE_AGENT = "factory-ui-reviewer";
114
+ /** The agent that needs `commands.end-to-end`. */
115
+ export const E2E_AGENT = "factory-e2e-reviewer";
116
+ /** The spec check where `specs.type` is openspec and none is written. */
117
+ export const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
118
+ /** `commands.relock` where none is written. */
119
+ export const DEFAULT_RELOCK = "npm install";
44
120
  export const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
45
121
  /** The keys each block allows, by the block's path: `""` is the top of the
46
- * file and `plugins[]` is one plug-in. `settings.schema.json` lists the same
47
- * keys, and a test fails when the two differ. A key the code accepts goes
48
- * here, in the schema, and in docs/configuration.md. */
122
+ * file and `plugins.build.builders[]` is one builder. `settings.schema.json`
123
+ * lists the same keys, and a test fails when the two differ. A key the code
124
+ * accepts goes here, in the schema, and in docs/configuration.md. */
49
125
  export const SETTINGS_KEYS = {
50
126
  "": [
51
127
  "version",
@@ -54,20 +130,30 @@ export const SETTINGS_KEYS = {
54
130
  "code-host",
55
131
  "builds",
56
132
  "specs",
57
- "before-commit",
58
- "build-setup",
133
+ "commands",
59
134
  "plugins",
60
135
  "auto-merge",
61
136
  "ci-review",
62
137
  "site",
63
138
  "session-minutes",
139
+ "rules",
64
140
  ],
65
141
  tickets: ["type", "board", "columns", "fields"],
66
142
  "tickets.columns": Object.keys(STATE_KEYS),
67
143
  "tickets.fields": Object.keys(FIELD_DEFAULTS),
68
144
  "code-host": ["type"],
69
- builds: ["trigger", "runner"],
70
- specs: ["type"],
145
+ builds: ["trigger", "runner", "poll-minutes"],
146
+ specs: ["type", "check"],
147
+ commands: [
148
+ "build-setup",
149
+ "before-commit",
150
+ "gate",
151
+ "test-one",
152
+ "end-to-end",
153
+ "coverage",
154
+ "relock",
155
+ ],
156
+ "commands.coverage": ["run", "report"],
71
157
  "auto-merge": ["allow", "deny", "commands"],
72
158
  "ci-review": ["commands"],
73
159
  site: [
@@ -83,8 +169,14 @@ export const SETTINGS_KEYS = {
83
169
  "accessibility",
84
170
  "new-values",
85
171
  ],
86
- "plugins[]": ["skill", "agent", "role", "files", "labels"],
172
+ plugins: PHASES,
173
+ ...Object.fromEntries(PHASES.map((phase) => [
174
+ `plugins.${phase}`,
175
+ SLOTS.filter((slot) => SLOT_SHAPE[slot].phase === phase).map((slot) => SLOT_SHAPE[slot].key),
176
+ ])),
177
+ ...slotKeys(),
87
178
  "session-minutes": Object.keys(SESSION_MINUTES),
179
+ rules: Object.keys(RULE_NUMBERS),
88
180
  };
89
181
  function wholeNumber(v, key, fallback) {
90
182
  if (v === undefined)
@@ -162,14 +254,14 @@ const fail = (key, message) => {
162
254
  throw new SettingsError(`${SETTINGS_FILE}: ${key}: ${message}`);
163
255
  };
164
256
  const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
165
- /** A block of settings. Its keys are `SETTINGS_KEYS[path]`, and `path` is
166
- * the block's `key` unless a list's item names it otherwise. */
167
- function object(v, key, path = key) {
257
+ /** A block of settings. Its keys are `SETTINGS_KEYS[path]` and `extra`,
258
+ * and `path` is the block's `key` unless a list's item names it otherwise. */
259
+ function object(v, key, path = key, extra = []) {
168
260
  if (v === undefined)
169
261
  return {};
170
262
  if (!isObj(v))
171
263
  return fail(key, "must be a block of settings");
172
- const allowed = SETTINGS_KEYS[path];
264
+ const allowed = [...SETTINGS_KEYS[path], ...extra];
173
265
  for (const k of Object.keys(v)) {
174
266
  if (!allowed.includes(k))
175
267
  fail(key ? `${key}.${k}` : k, "unknown key");
@@ -217,63 +309,157 @@ function names(v, key, defaults) {
217
309
  }));
218
310
  }
219
311
  /** A part you can swap, written as a block with a `type` or as one word. */
220
- function typed(v, key) {
312
+ function typed(v, key, extra) {
221
313
  if (typeof v === "string")
222
314
  return { type: v };
223
- return object(v, key);
315
+ return object(v, key, key, extra);
224
316
  }
225
- function plugin(v, i, exists) {
226
- const key = `plugins[${i}]`;
227
- const o = object(v, key, "plugins[]");
228
- const kind = "skill" in o && !("agent" in o)
229
- ? "skill"
230
- : "agent" in o && !("skill" in o)
231
- ? "agent"
232
- : fail(key, "names one skill or one agent");
233
- const name = o[kind];
317
+ /** One plug-in, written at `key` in the slot `slot`. */
318
+ function plugin(v, key, slot) {
319
+ const shape = SLOT_SHAPE[slot];
320
+ const other = shape.kind === "skill" ? "agent" : "skill";
321
+ if (isObj(v) && (other in v || !(shape.kind in v)))
322
+ fail(key, shape.kind === "skill" ? "names a skill" : "names an agent");
323
+ const o = object(v, key, `${slotPath(slot)}${shape.list ? "[]" : ""}`);
324
+ const name = o[shape.kind];
234
325
  if (typeof name !== "string" || !/^[\w-]+$/.test(name))
235
- fail(`${key}.${kind}`, "must be a name");
236
- const path = kind === "skill"
237
- ? `.claude/skills/${name}/SKILL.md`
238
- : `.claude/agents/${name}.md`;
239
- if (!exists(path))
240
- fail(`${key}.${kind}`, `${path} does not exist`);
326
+ fail(`${key}.${shape.kind}`, "must be a name");
327
+ const listed = (k) => {
328
+ const list = strings(o[k], `${key}.${k}`);
329
+ if (shape[k] === "required" && list.length === 0)
330
+ fail(`${key}.${k}`, "is required");
331
+ return list;
332
+ };
241
333
  return {
242
- kind,
334
+ kind: shape.kind,
243
335
  name: name,
244
- role: o.role === undefined
245
- ? fail(`${key}.role`, `must be one of ${ROLES.join(", ")}`)
246
- : oneOf(o.role, `${key}.role`, ROLES, "reviewer"),
247
- files: strings(o.files, `${key}.files`),
248
- labels: strings(o.labels, `${key}.labels`),
336
+ slot,
337
+ files: listed("files"),
338
+ labels: listed("labels"),
339
+ };
340
+ }
341
+ /** The plug-ins `plugins` names, in the slots' order, and whether it
342
+ * writes the list of test reviewers. */
343
+ function pluginsWritten(v) {
344
+ if (Array.isArray(v))
345
+ fail("plugins", `must be grouped by phase: ${PHASES.join(", ")}`);
346
+ const phases = object(v ?? {}, "plugins");
347
+ const slots = Object.fromEntries(PHASES.map((phase) => [
348
+ phase,
349
+ object(phases[phase] ?? {}, `plugins.${phase}`),
350
+ ]));
351
+ const at = (slot) => slots[SLOT_SHAPE[slot].phase][SLOT_SHAPE[slot].key];
352
+ return {
353
+ plugins: SLOTS.flatMap((slot) => {
354
+ const written = at(slot);
355
+ const key = slotPath(slot);
356
+ if (written === undefined)
357
+ return [];
358
+ if (!SLOT_SHAPE[slot].list)
359
+ return [plugin(written, key, slot)];
360
+ if (!Array.isArray(written))
361
+ return fail(key, "must be a list");
362
+ return written.map((item, i) => plugin(item, `${key}[${i}]`, slot));
363
+ }),
364
+ testReviewersWritten: at("test-reviewer") !== undefined,
365
+ };
366
+ }
367
+ /** Where each of the settings' plug-ins is written, such as
368
+ * `plugins.build.reviewers[0]`. */
369
+ function pluginPaths(plugins) {
370
+ const seen = new Map();
371
+ return plugins.map((p) => {
372
+ if (!SLOT_SHAPE[p.slot].list)
373
+ return slotPath(p.slot);
374
+ const i = seen.get(p.slot) ?? 0;
375
+ seen.set(p.slot, i + 1);
376
+ return `${slotPath(p.slot)}[${i}]`;
377
+ });
378
+ }
379
+ /** A command written as one line of text, or null when it is not written. */
380
+ function command(v, key) {
381
+ if (v === undefined)
382
+ return null;
383
+ return typeof v === "string" && v ? v : fail(key, "must be text");
384
+ }
385
+ function commandsOf(v) {
386
+ const o = object(v ?? {}, "commands");
387
+ let coverage = null;
388
+ if (o.coverage !== undefined) {
389
+ const c = object(o.coverage ?? {}, "commands.coverage");
390
+ for (const k of ["run", "report"])
391
+ if (typeof c[k] !== "string" || !c[k])
392
+ fail(`commands.coverage.${k}`, "is required when commands.coverage is written");
393
+ coverage = { run: c.run, report: c.report };
394
+ }
395
+ return {
396
+ buildSetup: strings(o["build-setup"], "commands.build-setup"),
397
+ beforeCommit: strings(o["before-commit"], "commands.before-commit"),
398
+ gate: strings(o.gate, "commands.gate"),
399
+ testOne: command(o["test-one"], "commands.test-one"),
400
+ endToEnd: command(o["end-to-end"], "commands.end-to-end"),
401
+ coverage,
402
+ relock: command(o.relock, "commands.relock") ?? DEFAULT_RELOCK,
249
403
  };
250
404
  }
251
405
  /** The settings with every default filled in. Throws a SettingsError naming
252
406
  * the key on anything unsound. `exists` says whether a path from the root
253
407
  * exists, for the plug-ins' files. */
254
- export function parseSettings(raw, exists) {
255
- const top = object(raw ?? {}, "");
256
- if (top.version !== 1)
257
- fail("version", "must be 1");
408
+ export function parseSettings(raw, exists, built = BUILT) {
409
+ const written = raw ?? {};
410
+ // The version comes before any other key, so a file in the older shape is
411
+ // told so, not told its keys are unknown.
412
+ if (isObj(written)) {
413
+ if (written.version === 1)
414
+ fail("version", 'must be 2: this file is version 1, see "Moving to settings version 2" in docs/updating.md');
415
+ if (written.version !== 2)
416
+ fail("version", "must be 2");
417
+ for (const key of ["before-commit", "build-setup"])
418
+ if (key in written)
419
+ fail(key, `moved to commands.${key}`);
420
+ }
421
+ const top = object(written, "");
258
422
  if (typeof top.repository !== "string" ||
259
423
  !/^[\w.-]+\/[\w.-]+$/.test(top.repository))
260
424
  fail("repository", "must be owner/name");
261
- const tickets = typed(top.tickets, "tickets");
262
- if (tickets.type !== undefined && tickets.type !== "github")
425
+ const declared = (v) => {
426
+ const type = isObj(v) ? v.type : v;
427
+ return typeof type === "string" ? (built.tickets[type] ?? []) : [];
428
+ };
429
+ const ticketType = (isObj(top.tickets) ? top.tickets.type : top.tickets) ?? "github";
430
+ if (typeof ticketType !== "string" || !(ticketType in built.tickets))
263
431
  // The same words every ticket command fails with (`tickets/index.mts`).
264
- throw new SettingsError(`${SETTINGS_FILE}: tickets.type "${String(tickets.type)}" is not supported. "github" is the only ticket system built.`);
432
+ throw new SettingsError(`${SETTINGS_FILE}: ${unsupported("tickets.type", String(ticketType), "ticket system", Object.keys(built.tickets))}`);
433
+ const tickets = typed(top.tickets, "tickets", declared(top.tickets));
434
+ const options = Object.fromEntries(declared(top.tickets)
435
+ .filter((k) => tickets[k] !== undefined)
436
+ .map((k) => [
437
+ k,
438
+ typeof tickets[k] === "string" && tickets[k]
439
+ ? tickets[k]
440
+ : fail(`tickets.${k}`, "must be text"),
441
+ ]));
265
442
  const board = tickets.board;
266
443
  if (board !== undefined &&
267
444
  board !== "none" &&
268
445
  !(Number.isInteger(board) && board > 0))
269
446
  fail("tickets.board", "must be a whole number above zero, or none");
270
- const codeHost = typed(top["code-host"], "code-host").type;
271
- if (codeHost !== undefined && codeHost !== DEFAULT_CODE_HOST)
272
- throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost))}`);
447
+ const codeHost = typed(top["code-host"], "code-host").type ?? DEFAULT_CODE_HOST;
448
+ if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
449
+ throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
273
450
  const builds = object(top.builds, "builds");
274
451
  const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
275
- if (builds.runner !== undefined && builds.runner !== DEFAULT_RUNNER)
276
- throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedRunner(String(builds.runner))}`);
452
+ const minutes = builds["poll-minutes"];
453
+ if (minutes !== undefined && trigger !== "github-action")
454
+ throw new SettingsError(`${SETTINGS_FILE}: builds.poll-minutes needs builds.trigger: github-action`);
455
+ const pollMinutes = minutes === undefined
456
+ ? 5
457
+ : POLL_MINUTES.includes(minutes)
458
+ ? minutes
459
+ : fail("builds.poll-minutes", `must be one of ${POLL_MINUTES.join(", ")}`);
460
+ const runner = builds.runner ?? DEFAULT_RUNNER;
461
+ if (typeof runner !== "string" || !built.runner.includes(runner))
462
+ throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedRunner(String(runner), built.runner)}`);
277
463
  const hasBoard = typeof board === "number";
278
464
  if (tickets.columns !== undefined && !hasBoard)
279
465
  fail("tickets.columns", "needs tickets.board");
@@ -294,32 +480,52 @@ export function parseSettings(raw, exists) {
294
480
  if (columns.ready === null && trigger !== "manual")
295
481
  fail("tickets.columns.ready", "no column shows ready, so nothing would start a build: name one, or set builds.trigger to manual");
296
482
  const fieldNames = names(tickets.fields, "tickets.fields", FIELD_DEFAULTS);
297
- const specs = typed(top.specs ?? "none", "specs");
483
+ const specsBlock = typed(top.specs ?? "none", "specs");
484
+ const specs = oneOf(specsBlock.type, "specs", SPECS, "none");
485
+ if (specsBlock.check !== undefined && specs !== "openspec")
486
+ throw new SettingsError(`${SETTINGS_FILE}: specs.check needs specs.type: openspec`);
487
+ const specCheck = specs === "openspec"
488
+ ? (command(specsBlock.check, "specs.check") ?? OPENSPEC_CHECK)
489
+ : null;
298
490
  const autoMerge = object(top["auto-merge"], "auto-merge");
299
491
  const ciReview = top["ci-review"] === undefined
300
492
  ? null
301
493
  : object(top["ci-review"] ?? {}, "ci-review");
302
- if (top.plugins !== undefined && !Array.isArray(top.plugins))
303
- fail("plugins", "must be a list");
304
494
  const site = parseSite(top.site, exists);
305
- const plugins = (top.plugins ?? []).map((p, i) => plugin(p, i, exists));
306
- if (!site && plugins.some((p) => p.kind === "agent" && p.name === SITE_AGENT))
495
+ const commands = commandsOf(top.commands);
496
+ const { plugins, testReviewersWritten } = pluginsWritten(top.plugins);
497
+ // What an agent of the factory's needs comes before its file: the sync
498
+ // writes the file only once the setting is there.
499
+ const lists = (agent) => plugins.some((p) => p.kind === "agent" && p.name === agent);
500
+ if (!site && lists(SITE_AGENT))
307
501
  fail("site", `is required to list ${SITE_AGENT}`);
502
+ if (commands.endToEnd === null && lists(E2E_AGENT))
503
+ fail("commands.end-to-end", `is required to list ${E2E_AGENT}`);
504
+ pluginPaths(plugins).forEach((key, i) => {
505
+ const p = plugins[i];
506
+ const path = p.kind === "skill"
507
+ ? `.claude/skills/${p.name}/SKILL.md`
508
+ : `.claude/agents/${p.name}.md`;
509
+ if (!exists(path))
510
+ fail(`${key}.${p.kind}`, `${path} does not exist`);
511
+ });
308
512
  return {
309
- version: 1,
513
+ version: 2,
310
514
  repository: top.repository,
311
515
  tickets: {
312
- type: "github",
516
+ type: ticketType,
517
+ options,
313
518
  board: typeof board === "number" ? board : null,
314
519
  columns,
315
520
  fields: fieldNames,
316
521
  },
317
- codeHost: { type: DEFAULT_CODE_HOST },
318
- builds: { trigger, runner: DEFAULT_RUNNER },
319
- specs: oneOf(specs.type, "specs", SPECS, "none"),
320
- beforeCommit: strings(top["before-commit"], "before-commit"),
321
- buildSetup: strings(top["build-setup"], "build-setup"),
522
+ codeHost: { type: codeHost },
523
+ builds: { trigger, runner, pollMinutes },
524
+ specs,
525
+ specCheck,
526
+ commands,
322
527
  plugins,
528
+ testReviewersWritten,
323
529
  autoMerge: {
324
530
  allow: strings(autoMerge.allow, "auto-merge.allow"),
325
531
  deny: strings(autoMerge.deny, "auto-merge.deny"),
@@ -328,6 +534,7 @@ export function parseSettings(raw, exists) {
328
534
  ciReview: ciReview && { commands: reviewCommands(ciReview.commands) },
329
535
  site,
330
536
  sessionMinutes: sessionMinutesOf(top["session-minutes"]),
537
+ rules: rulesOf(top.rules),
331
538
  };
332
539
  }
333
540
  function sessionMinutesOf(v) {
@@ -337,12 +544,21 @@ function sessionMinutesOf(v) {
337
544
  wholeNumber(o[kind], `session-minutes.${kind}`, fallback),
338
545
  ]));
339
546
  }
547
+ function rulesOf(v) {
548
+ const o = object(v ?? {}, "rules");
549
+ const n = (k) => wholeNumber(o[k], `rules.${k}`, RULE_NUMBERS[k]);
550
+ return {
551
+ smallChangeLines: n("small-change-lines"),
552
+ reviewRounds: n("review-rounds"),
553
+ };
554
+ }
340
555
  /** One line for each pattern that matches none of `files`: a stale pattern
341
556
  * is how a policy rots. */
342
557
  export function patternWarnings(s, files) {
558
+ const paths = pluginPaths(s.plugins);
343
559
  const lists = [
344
560
  ...s.plugins.map((p, i) => [
345
- `plugins[${i}].files`,
561
+ `${paths[i]}.files`,
346
562
  p.files,
347
563
  ]),
348
564
  ["auto-merge.allow", s.autoMerge.allow],
@@ -356,6 +572,10 @@ export const NO_DEPENDENCIES = "The factory's settings cannot be read until depe
356
572
  /** js-yaml is loaded when needed, so a checkout without dependencies gets
357
573
  * one line saying what to do rather than a stack trace. */
358
574
  async function read(d) {
575
+ return parseSettings(await readRaw(d), d.exists);
576
+ }
577
+ /** The file as it is written, before any default is filled in. */
578
+ async function readRaw(d) {
359
579
  let load;
360
580
  try {
361
581
  load = await d.loadYaml();
@@ -363,14 +583,12 @@ async function read(d) {
363
583
  catch {
364
584
  throw new SettingsError(NO_DEPENDENCIES);
365
585
  }
366
- let raw;
367
586
  try {
368
- raw = load(d.readFile());
587
+ return load(d.readFile());
369
588
  }
370
589
  catch (e) {
371
590
  throw new SettingsError(`${SETTINGS_FILE}: ${e.message}`);
372
591
  }
373
- return parseSettings(raw, d.exists);
374
592
  }
375
593
  /** The settings file: FACTORY_SETTINGS where it is set, for trying settings
376
594
  * against a board without changing the repository's, and otherwise the
@@ -413,9 +631,21 @@ export function fieldNamesOf(s) {
413
631
  /** The settings of the checkout the command runs in. */
414
632
  export const loadSettings = (d = defaultDeps()) => read(d);
415
633
  function lookup(s, key) {
634
+ if (key === "specs.check")
635
+ return s.specCheck;
636
+ // Coverage is a block whether or not it is written, and its two keys
637
+ // print `none` when it is not.
638
+ if (key === "commands.coverage")
639
+ return undefined;
640
+ if (s.commands.coverage === null)
641
+ for (const k of SETTINGS_KEYS["commands.coverage"])
642
+ if (key === `commands.coverage.${k}`)
643
+ return null;
416
644
  const camel = {
417
645
  "before-commit": "beforeCommit",
418
646
  "build-setup": "buildSetup",
647
+ "test-one": "testOne",
648
+ "end-to-end": "endToEnd",
419
649
  "auto-merge": "autoMerge",
420
650
  "ci-review": "ciReview",
421
651
  "code-host": "codeHost",
@@ -435,33 +665,48 @@ function lookup(s, key) {
435
665
  /** The factory's design skill, which `factory sync` writes where there is a
436
666
  * site. */
437
667
  const DESIGN_SKILL = ".claude/skills/factory-design/SKILL.md";
438
- /** The settings' plug-ins, and the factory's design skill as the mockups
439
- * plug-in of a site that lists none, once it is synced. */
668
+ /** Every plug-in the factory will use, in the slots' order: the settings'
669
+ * own, and the factory's for each slot they leave out. The refiner and the
670
+ * prover are always there. The factory's test reviewer is there unless the
671
+ * settings write the list. Its design skill is the mockups plug-in of a
672
+ * site that names none, once it is synced. */
440
673
  export function pluginsOf(s, exists) {
441
- if (!s.site || s.plugins.some((p) => p.role === "mockups"))
442
- return s.plugins;
443
- if (!exists(DESIGN_SKILL))
444
- return s.plugins;
445
- return [
446
- {
447
- kind: "skill",
448
- name: "factory-design",
449
- role: "mockups",
450
- files: [],
451
- labels: [],
452
- },
453
- ...s.plugins,
454
- ];
674
+ const builtIn = (kind, name, slot) => ({
675
+ kind,
676
+ name,
677
+ slot,
678
+ files: [],
679
+ labels: [],
680
+ });
681
+ const fallback = {
682
+ refiner: [builtIn("skill", "factory-refine", "refiner")],
683
+ mockups: s.site && exists(DESIGN_SKILL)
684
+ ? [builtIn("skill", "factory-design", "mockups")]
685
+ : [],
686
+ builder: [],
687
+ reviewer: [],
688
+ prover: [builtIn("skill", "factory-mutate", "prover")],
689
+ "test-reviewer": s.testReviewersWritten
690
+ ? []
691
+ : [builtIn("agent", "factory-test-reviewer", "test-reviewer")],
692
+ resolver: [],
693
+ };
694
+ return SLOTS.flatMap((slot) => {
695
+ const own = s.plugins.filter((p) => p.slot === slot);
696
+ return own.length ? own : fallback[slot];
697
+ });
455
698
  }
456
699
  export async function main(argv, d) {
457
700
  const [command, arg] = argv;
458
701
  if (!command) {
459
- d.err("Usage: factory config get KEY | config check | plugins [ROLE]");
702
+ d.err("Usage: factory config get KEY | config check | config explain | plugins [SLOT]");
460
703
  return 2;
461
704
  }
462
705
  let s;
706
+ let raw;
463
707
  try {
464
- s = await read(d);
708
+ raw = await readRaw(d);
709
+ s = parseSettings(raw, d.exists);
465
710
  }
466
711
  catch (e) {
467
712
  if (!(e instanceof SettingsError))
@@ -476,16 +721,26 @@ export async function main(argv, d) {
476
721
  }
477
722
  for (const w of patternWarnings(s, d.listFiles()))
478
723
  d.err(`warning: ${w}`);
479
- if (s.site && !s.plugins.some((p) => p.role === "mockups"))
724
+ if (s.site && !s.plugins.some((p) => p.slot === "mockups"))
480
725
  if (!d.exists(DESIGN_SKILL))
481
726
  d.err(`warning: ${DESIGN_SKILL} is missing: run \`npx --no-install factory sync\` to give the site its design skill`);
482
727
  return 0;
483
728
  }
729
+ if (command === "explain") {
730
+ const { explainLines } = await import("./explain.mjs");
731
+ for (const line of await explainLines(s, raw, d.exists))
732
+ d.out(line);
733
+ return 0;
734
+ }
484
735
  if (command === "plugins") {
736
+ if (arg && !SLOTS.includes(arg)) {
737
+ d.err(`${arg}: must be one of ${SLOTS.join(", ")}`);
738
+ return 1;
739
+ }
485
740
  for (const p of pluginsOf(s, d.exists)) {
486
- if (arg && p.role !== arg)
741
+ if (arg && p.slot !== arg)
487
742
  continue;
488
- d.out([p.kind, p.name, p.role, ...p.files, ...p.labels].join(" ").trim());
743
+ d.out([p.kind, p.name, p.slot, ...p.files, ...p.labels].join(" "));
489
744
  }
490
745
  return 0;
491
746
  }
@@ -512,7 +767,7 @@ export async function main(argv, d) {
512
767
  return 0;
513
768
  }
514
769
  /** `factory config get KEY`, `factory config check`, and
515
- * `factory plugins [ROLE]`. */
770
+ * `factory plugins [SLOT]`. */
516
771
  export async function run(argv) {
517
772
  return main(argv, defaultDeps());
518
773
  }
@@ -524,7 +779,7 @@ export function targetOf(s, env) {
524
779
  board: env.FACTORY_BOARD_NUMBER
525
780
  ? Number(env.FACTORY_BOARD_NUMBER)
526
781
  : s.tickets.board,
527
- watched: s.builds.trigger !== "manual",
782
+ watch: watchOf(s.builds.trigger, s.builds.pollMinutes),
528
783
  columns: columnsOf(s),
529
784
  };
530
785
  }
package/dist/deps.d.mts CHANGED
@@ -20,13 +20,16 @@ export type Bump = {
20
20
  /** A major bump changes the leading number. A grouped bump is minor and
21
21
  * patch only. */
22
22
  export declare function isMajor(title: string): boolean;
23
- /** What the skill does with a bump, in the order its steps take them. */
24
- export declare function nextStep(bump: Bump): string;
23
+ /** What the skill does with a bump, in the order its steps take them.
24
+ * `branch` is the default branch, which a conflicting bump merges. */
25
+ export declare function nextStep(bump: Bump, branch: string): string;
25
26
  /** Every check on the bump's commit, not a fixed list of names: passed, or
26
27
  * the names that failed and the names still running. */
27
28
  export declare function checksLine(bump: Bump): string;
28
- export declare function formatBump(bump: Bump): string[];
29
- export declare function main(p: CodeHost, out: (line: string) => void, argv?: string[]): Promise<number>;
29
+ export declare function formatBump(bump: Bump, branch: string): string[];
30
+ /** `defaultBranch` gives the default branch's name, and rejects when it
31
+ * cannot be told. It is asked only when a pull request is listed. */
32
+ export declare function main(p: CodeHost, out: (line: string) => void, argv: string[], defaultBranch: () => Promise<string>): Promise<number>;
30
33
  /** `factory deps`. */
31
34
  export declare function run(argv?: string[]): Promise<number>;
32
35
  export {};