@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/config.d.mts CHANGED
@@ -3,8 +3,23 @@ import { type Built } from "./tool-names.mts";
3
3
  import { type Watch, type Columns, type StateKey } from "./lib/work-status.mts";
4
4
  export declare class SettingsError extends Error {
5
5
  }
6
- export declare const ROLES: readonly ["mockups", "builder", "reviewer"];
7
- export type Role = (typeof ROLES)[number];
6
+ /** What a plug-in does, in the order `factory plugins` prints them. */
7
+ export declare const SLOTS: readonly ["refiner", "mockups", "builder", "reviewer", "prover", "test-reviewer", "resolver"];
8
+ export type Slot = (typeof SLOTS)[number];
9
+ /** The phases `plugins` is grouped by. */
10
+ export declare const PHASES: readonly ["refine", "build", "test", "conflicts"];
11
+ type SlotShape = {
12
+ phase: (typeof PHASES)[number];
13
+ key: string;
14
+ kind: Plugin["kind"];
15
+ list: boolean;
16
+ files: "required" | "optional" | "none";
17
+ labels: "required" | "none";
18
+ };
19
+ /** Each slot: the phase and key it is written under, the one kind it
20
+ * takes, whether it holds one plug-in or a list, and whether a plug-in in
21
+ * it must have, may have, or cannot have `files` and `labels`. */
22
+ export declare const SLOT_SHAPE: Record<Slot, SlotShape>;
8
23
  export declare const TRIGGERS: readonly ["own-server", "github-action", "manual"];
9
24
  /** How often the scheduled poller may check the board, in minutes: each
10
25
  * divides an hour, so a schedule every N minutes keeps an even beat. */
@@ -19,12 +34,12 @@ export type FieldKey = keyof typeof FIELD_DEFAULTS;
19
34
  export type Plugin = {
20
35
  kind: "skill" | "agent";
21
36
  name: string;
22
- role: Role;
37
+ slot: Slot;
23
38
  files: string[];
24
39
  labels: string[];
25
40
  };
26
41
  export type Settings = {
27
- version: 1;
42
+ version: 2;
28
43
  repository: string;
29
44
  tickets: {
30
45
  type: string;
@@ -49,10 +64,34 @@ export type Settings = {
49
64
  pollMinutes: (typeof POLL_MINUTES)[number];
50
65
  };
51
66
  specs: (typeof SPECS)[number];
52
- beforeCommit: string[];
53
- /** Commands an unattended build runs from the root before it starts. */
54
- buildSetup: string[];
67
+ /** The command that checks the specs, or null when `specs` is none. */
68
+ specCheck: string | null;
69
+ /** Every command a build runs, each from the repository's root. */
70
+ commands: {
71
+ /** Before an unattended build starts work. */
72
+ buildSetup: string[];
73
+ /** Before every commit a session makes. */
74
+ beforeCommit: string[];
75
+ /** Before a session reports a task done. */
76
+ gate: string[];
77
+ /** One test alone, with `FILE` and `NAME` in its environment. */
78
+ testOne: string | null;
79
+ /** One end-to-end spec alone, with `FILE` in its environment. */
80
+ endToEnd: string | null;
81
+ /** Coverage, and where its report lands. */
82
+ coverage: {
83
+ run: string;
84
+ report: string;
85
+ } | null;
86
+ /** Rebuilds the package manager's lock file after a conflict in it. */
87
+ relock: string;
88
+ };
89
+ /** The plug-ins the settings name, in the slots' order. `pluginsOf` adds
90
+ * the factory's own for each slot left out. */
55
91
  plugins: Plugin[];
92
+ /** Whether `plugins.test.reviewers` is written. Written, it is the whole
93
+ * list of test reviewers, even when it is empty. */
94
+ testReviewersWritten: boolean;
56
95
  autoMerge: {
57
96
  allow: string[];
58
97
  deny: string[];
@@ -108,11 +147,17 @@ export declare const ACCESSIBILITY: readonly ["wcag22aa", "wcag21aa", "wcag2aa",
108
147
  export type Accessibility = (typeof ACCESSIBILITY)[number];
109
148
  /** The agent that needs `site`. */
110
149
  export declare const SITE_AGENT = "factory-ui-reviewer";
150
+ /** The agent that needs `commands.end-to-end`. */
151
+ export declare const E2E_AGENT = "factory-e2e-reviewer";
152
+ /** The spec check where `specs.type` is openspec and none is written. */
153
+ export declare const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
154
+ /** `commands.relock` where none is written. */
155
+ export declare const DEFAULT_RELOCK = "npm install";
111
156
  export declare const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
112
157
  /** The keys each block allows, by the block's path: `""` is the top of the
113
- * file and `plugins[]` is one plug-in. `settings.schema.json` lists the same
114
- * keys, and a test fails when the two differ. A key the code accepts goes
115
- * here, in the schema, and in docs/configuration.md. */
158
+ * file and `plugins.build.builders[]` is one builder. `settings.schema.json`
159
+ * lists the same keys, and a test fails when the two differ. A key the code
160
+ * accepts goes here, in the schema, and in docs/configuration.md. */
116
161
  export declare const SETTINGS_KEYS: Record<string, readonly string[]>;
117
162
  /** `factory config get site`: every key in the table's order. */
118
163
  export declare function siteLines(site: Site): string[];
@@ -154,12 +199,15 @@ export declare function fieldNamesOf(s: Settings): {
154
199
  };
155
200
  /** The settings of the checkout the command runs in. */
156
201
  export declare const loadSettings: (d?: Deps) => Promise<Settings>;
157
- /** The settings' plug-ins, and the factory's design skill as the mockups
158
- * plug-in of a site that lists none, once it is synced. */
202
+ /** Every plug-in the factory will use, in the slots' order: the settings'
203
+ * own, and the factory's for each slot they leave out. The refiner and the
204
+ * prover are always there. The factory's test reviewer is there unless the
205
+ * settings write the list. Its design skill is the mockups plug-in of a
206
+ * site that names none, once it is synced. */
159
207
  export declare function pluginsOf(s: Settings, exists: (path: string) => boolean): Plugin[];
160
208
  export declare function main(argv: string[], d: Deps): Promise<number>;
161
209
  /** `factory config get KEY`, `factory config check`, and
162
- * `factory plugins [ROLE]`. */
210
+ * `factory plugins [SLOT]`. */
163
211
  export declare function run(argv: string[]): Promise<number>;
164
212
  /** What a reading needs from the settings. */
165
213
  export type Target = {
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.
@@ -19,7 +19,68 @@ import { BUILT, unsupported } from "./tool-names.mjs";
19
19
  import { DEFAULT_COLUMNS, STATE_KEYS, sameName, watchOf, } from "./lib/work-status.mjs";
20
20
  export class SettingsError extends Error {
21
21
  }
22
- 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
+ }));
23
84
  export const TRIGGERS = ["own-server", "github-action", "manual"];
24
85
  /** How often the scheduled poller may check the board, in minutes: each
25
86
  * divides an hour, so a schedule every N minutes keeps an even beat. */
@@ -50,11 +111,17 @@ export const ACCESSIBILITY = [
50
111
  ];
51
112
  /** The agent that needs `site`. */
52
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";
53
120
  export const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
54
121
  /** The keys each block allows, by the block's path: `""` is the top of the
55
- * file and `plugins[]` is one plug-in. `settings.schema.json` lists the same
56
- * keys, and a test fails when the two differ. A key the code accepts goes
57
- * 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. */
58
125
  export const SETTINGS_KEYS = {
59
126
  "": [
60
127
  "version",
@@ -63,8 +130,7 @@ export const SETTINGS_KEYS = {
63
130
  "code-host",
64
131
  "builds",
65
132
  "specs",
66
- "before-commit",
67
- "build-setup",
133
+ "commands",
68
134
  "plugins",
69
135
  "auto-merge",
70
136
  "ci-review",
@@ -77,7 +143,17 @@ export const SETTINGS_KEYS = {
77
143
  "tickets.fields": Object.keys(FIELD_DEFAULTS),
78
144
  "code-host": ["type"],
79
145
  builds: ["trigger", "runner", "poll-minutes"],
80
- specs: ["type"],
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"],
81
157
  "auto-merge": ["allow", "deny", "commands"],
82
158
  "ci-review": ["commands"],
83
159
  site: [
@@ -93,7 +169,12 @@ export const SETTINGS_KEYS = {
93
169
  "accessibility",
94
170
  "new-values",
95
171
  ],
96
- "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(),
97
178
  "session-minutes": Object.keys(SESSION_MINUTES),
98
179
  rules: Object.keys(RULE_NUMBERS),
99
180
  };
@@ -233,39 +314,111 @@ function typed(v, key, extra) {
233
314
  return { type: v };
234
315
  return object(v, key, key, extra);
235
316
  }
236
- function plugin(v, i, exists) {
237
- const key = `plugins[${i}]`;
238
- const o = object(v, key, "plugins[]");
239
- const kind = "skill" in o && !("agent" in o)
240
- ? "skill"
241
- : "agent" in o && !("skill" in o)
242
- ? "agent"
243
- : fail(key, "names one skill or one agent");
244
- 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];
245
325
  if (typeof name !== "string" || !/^[\w-]+$/.test(name))
246
- fail(`${key}.${kind}`, "must be a name");
247
- const path = kind === "skill"
248
- ? `.claude/skills/${name}/SKILL.md`
249
- : `.claude/agents/${name}.md`;
250
- if (!exists(path))
251
- 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
+ };
252
333
  return {
253
- kind,
334
+ kind: shape.kind,
254
335
  name: name,
255
- role: o.role === undefined
256
- ? fail(`${key}.role`, `must be one of ${ROLES.join(", ")}`)
257
- : oneOf(o.role, `${key}.role`, ROLES, "reviewer"),
258
- files: strings(o.files, `${key}.files`),
259
- 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,
260
403
  };
261
404
  }
262
405
  /** The settings with every default filled in. Throws a SettingsError naming
263
406
  * the key on anything unsound. `exists` says whether a path from the root
264
407
  * exists, for the plug-ins' files. */
265
408
  export function parseSettings(raw, exists, built = BUILT) {
266
- const top = object(raw ?? {}, "");
267
- if (top.version !== 1)
268
- fail("version", "must be 1");
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, "");
269
422
  if (typeof top.repository !== "string" ||
270
423
  !/^[\w.-]+\/[\w.-]+$/.test(top.repository))
271
424
  fail("repository", "must be owner/name");
@@ -327,19 +480,37 @@ export function parseSettings(raw, exists, built = BUILT) {
327
480
  if (columns.ready === null && trigger !== "manual")
328
481
  fail("tickets.columns.ready", "no column shows ready, so nothing would start a build: name one, or set builds.trigger to manual");
329
482
  const fieldNames = names(tickets.fields, "tickets.fields", FIELD_DEFAULTS);
330
- 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;
331
490
  const autoMerge = object(top["auto-merge"], "auto-merge");
332
491
  const ciReview = top["ci-review"] === undefined
333
492
  ? null
334
493
  : object(top["ci-review"] ?? {}, "ci-review");
335
- if (top.plugins !== undefined && !Array.isArray(top.plugins))
336
- fail("plugins", "must be a list");
337
494
  const site = parseSite(top.site, exists);
338
- const plugins = (top.plugins ?? []).map((p, i) => plugin(p, i, exists));
339
- 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))
340
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
+ });
341
512
  return {
342
- version: 1,
513
+ version: 2,
343
514
  repository: top.repository,
344
515
  tickets: {
345
516
  type: ticketType,
@@ -350,10 +521,11 @@ export function parseSettings(raw, exists, built = BUILT) {
350
521
  },
351
522
  codeHost: { type: codeHost },
352
523
  builds: { trigger, runner, pollMinutes },
353
- specs: oneOf(specs.type, "specs", SPECS, "none"),
354
- beforeCommit: strings(top["before-commit"], "before-commit"),
355
- buildSetup: strings(top["build-setup"], "build-setup"),
524
+ specs,
525
+ specCheck,
526
+ commands,
356
527
  plugins,
528
+ testReviewersWritten,
357
529
  autoMerge: {
358
530
  allow: strings(autoMerge.allow, "auto-merge.allow"),
359
531
  deny: strings(autoMerge.deny, "auto-merge.deny"),
@@ -383,9 +555,10 @@ function rulesOf(v) {
383
555
  /** One line for each pattern that matches none of `files`: a stale pattern
384
556
  * is how a policy rots. */
385
557
  export function patternWarnings(s, files) {
558
+ const paths = pluginPaths(s.plugins);
386
559
  const lists = [
387
560
  ...s.plugins.map((p, i) => [
388
- `plugins[${i}].files`,
561
+ `${paths[i]}.files`,
389
562
  p.files,
390
563
  ]),
391
564
  ["auto-merge.allow", s.autoMerge.allow],
@@ -458,9 +631,21 @@ export function fieldNamesOf(s) {
458
631
  /** The settings of the checkout the command runs in. */
459
632
  export const loadSettings = (d = defaultDeps()) => read(d);
460
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;
461
644
  const camel = {
462
645
  "before-commit": "beforeCommit",
463
646
  "build-setup": "buildSetup",
647
+ "test-one": "testOne",
648
+ "end-to-end": "endToEnd",
464
649
  "auto-merge": "autoMerge",
465
650
  "ci-review": "ciReview",
466
651
  "code-host": "codeHost",
@@ -480,28 +665,41 @@ function lookup(s, key) {
480
665
  /** The factory's design skill, which `factory sync` writes where there is a
481
666
  * site. */
482
667
  const DESIGN_SKILL = ".claude/skills/factory-design/SKILL.md";
483
- /** The settings' plug-ins, and the factory's design skill as the mockups
484
- * 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. */
485
673
  export function pluginsOf(s, exists) {
486
- if (!s.site || s.plugins.some((p) => p.role === "mockups"))
487
- return s.plugins;
488
- if (!exists(DESIGN_SKILL))
489
- return s.plugins;
490
- return [
491
- {
492
- kind: "skill",
493
- name: "factory-design",
494
- role: "mockups",
495
- files: [],
496
- labels: [],
497
- },
498
- ...s.plugins,
499
- ];
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
+ });
500
698
  }
501
699
  export async function main(argv, d) {
502
700
  const [command, arg] = argv;
503
701
  if (!command) {
504
- d.err("Usage: factory config get KEY | config check | config explain | plugins [ROLE]");
702
+ d.err("Usage: factory config get KEY | config check | config explain | plugins [SLOT]");
505
703
  return 2;
506
704
  }
507
705
  let s;
@@ -523,22 +721,26 @@ export async function main(argv, d) {
523
721
  }
524
722
  for (const w of patternWarnings(s, d.listFiles()))
525
723
  d.err(`warning: ${w}`);
526
- if (s.site && !s.plugins.some((p) => p.role === "mockups"))
724
+ if (s.site && !s.plugins.some((p) => p.slot === "mockups"))
527
725
  if (!d.exists(DESIGN_SKILL))
528
726
  d.err(`warning: ${DESIGN_SKILL} is missing: run \`npx --no-install factory sync\` to give the site its design skill`);
529
727
  return 0;
530
728
  }
531
729
  if (command === "explain") {
532
730
  const { explainLines } = await import("./explain.mjs");
533
- for (const line of await explainLines(s, raw))
731
+ for (const line of await explainLines(s, raw, d.exists))
534
732
  d.out(line);
535
733
  return 0;
536
734
  }
537
735
  if (command === "plugins") {
736
+ if (arg && !SLOTS.includes(arg)) {
737
+ d.err(`${arg}: must be one of ${SLOTS.join(", ")}`);
738
+ return 1;
739
+ }
538
740
  for (const p of pluginsOf(s, d.exists)) {
539
- if (arg && p.role !== arg)
741
+ if (arg && p.slot !== arg)
540
742
  continue;
541
- 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(" "));
542
744
  }
543
745
  return 0;
544
746
  }
@@ -565,7 +767,7 @@ export async function main(argv, d) {
565
767
  return 0;
566
768
  }
567
769
  /** `factory config get KEY`, `factory config check`, and
568
- * `factory plugins [ROLE]`. */
770
+ * `factory plugins [SLOT]`. */
569
771
  export async function run(argv) {
570
772
  return main(argv, defaultDeps());
571
773
  }
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 {};