@davidbyoung/software-factory 0.1.4 → 0.1.6

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 (57) hide show
  1. package/README.md +9 -8
  2. package/dist/cli.mjs +13 -1
  3. package/dist/code-host/github-setup.mjs +1 -1
  4. package/dist/config.d.mts +74 -20
  5. package/dist/config.mjs +326 -76
  6. package/dist/deps.d.mts +6 -4
  7. package/dist/deps.mjs +29 -7
  8. package/dist/doctor.d.mts +3 -0
  9. package/dist/doctor.mjs +7 -4
  10. package/dist/explain.d.mts +13 -2
  11. package/dist/explain.mjs +58 -43
  12. package/dist/init.mjs +9 -7
  13. package/dist/lib/default-branch.d.mts +1 -1
  14. package/dist/lib/default-branch.mjs +2 -2
  15. package/dist/lib/refined-check.mjs +1 -1
  16. package/dist/lib/work-status.d.mts +2 -2
  17. package/dist/lib/work-status.mjs +4 -4
  18. package/dist/parts.d.mts +1 -1
  19. package/dist/parts.mjs +2 -2
  20. package/dist/preset-commands.d.mts +65 -0
  21. package/dist/preset-commands.mjs +1148 -0
  22. package/dist/preset.d.mts +169 -0
  23. package/dist/preset.mjs +550 -0
  24. package/dist/remove.mjs +34 -1
  25. package/dist/review-cost.mjs +1 -1
  26. package/dist/review-tools.mjs +3 -3
  27. package/dist/session-start.d.mts +3 -0
  28. package/dist/session-start.mjs +12 -1
  29. package/dist/sync.d.mts +42 -7
  30. package/dist/sync.mjs +166 -32
  31. package/docs/builds.md +12 -11
  32. package/docs/cli.md +27 -8
  33. package/docs/configuration.md +723 -714
  34. package/docs/design.md +1 -1
  35. package/docs/developing.md +20 -8
  36. package/docs/existing-repo.md +1 -1
  37. package/docs/github/by-hand.md +9 -9
  38. package/docs/github/reference.md +4 -19
  39. package/docs/github/setup.md +3 -3
  40. package/docs/glossary.md +18 -9
  41. package/docs/limitations.md +4 -1
  42. package/docs/plugins.md +36 -24
  43. package/docs/presets.md +410 -0
  44. package/docs/quick-start.md +21 -18
  45. package/docs/removing.md +1 -1
  46. package/docs/skills.md +28 -23
  47. package/docs/updating.md +22 -14
  48. package/docs/workflow.md +13 -14
  49. package/package.json +1 -1
  50. package/rules.md +1 -1
  51. package/settings.schema.json +60 -11
  52. package/skills/factory-build/SKILL.md +1 -1
  53. package/skills/factory-deps/SKILL.md +23 -12
  54. package/skills/factory-design/SKILL.md +2 -2
  55. package/skills/factory-refine/SKILL.md +2 -2
  56. package/skills/factory-resolve-conflicts/SKILL.md +6 -0
  57. package/workflows/factory-claude-review.yml +8 -3
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 [SLOT] # kind, name, slot, files or labels
7
+ // factory plugins [ROLE] # kind, name, role, 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,8 +19,8 @@ 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
- /** What a plug-in does, in the order `factory plugins` prints them. */
23
- export const SLOTS = [
22
+ /** What a plugin does, in the order `factory plugins` prints them. */
23
+ export const ROLES = [
24
24
  "refiner",
25
25
  "mockups",
26
26
  "builder",
@@ -31,7 +31,7 @@ export const SLOTS = [
31
31
  ];
32
32
  /** The phases `plugins` is grouped by. */
33
33
  export const PHASES = ["refine", "build", "test", "conflicts"];
34
- /** A slot's shape: one plug-in with no files and no labels, unless `takes`
34
+ /** A role's shape: one plugin with no files and no labels, unless `takes`
35
35
  * says otherwise. */
36
36
  const shapeOf = (phase, key, kind, takes = {}) => ({
37
37
  phase,
@@ -42,10 +42,10 @@ const shapeOf = (phase, key, kind, takes = {}) => ({
42
42
  labels: "none",
43
43
  ...takes,
44
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
45
+ /** Each role: the phase and key it is written under, the one kind it
46
+ * takes, whether it holds one plugin or a list, and whether a plugin in
47
47
  * it must have, may have, or cannot have `files` and `labels`. */
48
- export const SLOT_SHAPE = {
48
+ export const ROLE_SHAPE = {
49
49
  refiner: shapeOf("refine", "refiner", "skill"),
50
50
  mockups: shapeOf("refine", "mockups", "skill"),
51
51
  builder: shapeOf("build", "builders", "skill", {
@@ -66,18 +66,21 @@ export const SLOT_SHAPE = {
66
66
  files: "required",
67
67
  }),
68
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
69
+ /** A role's path in the settings, such as `plugins.build.reviewers`. */
70
+ const rolePath = (role) => `plugins.${ROLE_SHAPE[role].phase}.${ROLE_SHAPE[role].key}`;
71
+ /** The keys of each role's block, by its path in `SETTINGS_KEYS`: a list's
72
72
  * items are under the path with `[]` after it. */
73
- const slotKeys = () => Object.fromEntries(SLOTS.map((slot) => {
74
- const shape = SLOT_SHAPE[slot];
73
+ const roleKeys = () => Object.fromEntries(ROLES.map((role) => {
74
+ const shape = ROLE_SHAPE[role];
75
75
  return [
76
- `${slotPath(slot)}${shape.list ? "[]" : ""}`,
76
+ `${rolePath(role)}${shape.list ? "[]" : ""}`,
77
77
  [
78
78
  shape.kind,
79
79
  ...(shape.files === "none" ? [] : ["files"]),
80
80
  ...(shape.labels === "none" ? [] : ["labels"]),
81
+ // Only the repository's own settings leave out a plugin that a
82
+ // preset adds, and only from a list.
83
+ ...(shape.list ? ["off"] : []),
81
84
  ],
82
85
  ];
83
86
  }));
@@ -126,6 +129,7 @@ export const SETTINGS_KEYS = {
126
129
  "": [
127
130
  "version",
128
131
  "repository",
132
+ "presets",
129
133
  "tickets",
130
134
  "code-host",
131
135
  "builds",
@@ -133,7 +137,7 @@ export const SETTINGS_KEYS = {
133
137
  "commands",
134
138
  "plugins",
135
139
  "auto-merge",
136
- "ci-review",
140
+ "pr-review",
137
141
  "site",
138
142
  "session-minutes",
139
143
  "rules",
@@ -155,7 +159,7 @@ export const SETTINGS_KEYS = {
155
159
  ],
156
160
  "commands.coverage": ["run", "report"],
157
161
  "auto-merge": ["allow", "deny", "commands"],
158
- "ci-review": ["commands"],
162
+ "pr-review": ["commands"],
159
163
  site: [
160
164
  "start",
161
165
  "url",
@@ -172,9 +176,9 @@ export const SETTINGS_KEYS = {
172
176
  plugins: PHASES,
173
177
  ...Object.fromEntries(PHASES.map((phase) => [
174
178
  `plugins.${phase}`,
175
- SLOTS.filter((slot) => SLOT_SHAPE[slot].phase === phase).map((slot) => SLOT_SHAPE[slot].key),
179
+ ROLES.filter((role) => ROLE_SHAPE[role].phase === phase).map((role) => ROLE_SHAPE[role].key),
176
180
  ])),
177
- ...slotKeys(),
181
+ ...roleKeys(),
178
182
  "session-minutes": Object.keys(SESSION_MINUTES),
179
183
  rules: Object.keys(RULE_NUMBERS),
180
184
  };
@@ -277,11 +281,11 @@ function strings(v, key) {
277
281
  ? item
278
282
  : fail(`${key}[${i}]`, "must be text"));
279
283
  }
280
- /** The CI review's commands: each becomes `Bash(COMMAND:*)` in a list
284
+ /** The pull request review's commands: each becomes `Bash(COMMAND:*)` in a list
281
285
  * that commas separate, so none may hold a comma, a parenthesis, or a
282
286
  * quote. */
283
287
  function reviewCommands(v) {
284
- const key = "ci-review.commands";
288
+ const key = "pr-review.commands";
285
289
  return strings(v, key).map((command, i) => /[,()"]/.test(command)
286
290
  ? fail(`${key}[${i}]`, "must hold no comma, parenthesis, or quote")
287
291
  : command);
@@ -314,13 +318,13 @@ function typed(v, key, extra) {
314
318
  return { type: v };
315
319
  return object(v, key, key, extra);
316
320
  }
317
- /** One plug-in, written at `key` in the slot `slot`. */
318
- function plugin(v, key, slot) {
319
- const shape = SLOT_SHAPE[slot];
321
+ /** One plugin, written at `key` in the role `role`. */
322
+ function plugin(v, key, role) {
323
+ const shape = ROLE_SHAPE[role];
320
324
  const other = shape.kind === "skill" ? "agent" : "skill";
321
325
  if (isObj(v) && (other in v || !(shape.kind in v)))
322
326
  fail(key, shape.kind === "skill" ? "names a skill" : "names an agent");
323
- const o = object(v, key, `${slotPath(slot)}${shape.list ? "[]" : ""}`);
327
+ const o = object(v, key, `${rolePath(role)}${shape.list ? "[]" : ""}`);
324
328
  const name = o[shape.kind];
325
329
  if (typeof name !== "string" || !/^[\w-]+$/.test(name))
326
330
  fail(`${key}.${shape.kind}`, "must be a name");
@@ -333,47 +337,56 @@ function plugin(v, key, slot) {
333
337
  return {
334
338
  kind: shape.kind,
335
339
  name: name,
336
- slot,
340
+ role,
337
341
  files: listed("files"),
338
342
  labels: listed("labels"),
339
343
  };
340
344
  }
341
- /** The plug-ins `plugins` names, in the slots' order, and whether it
345
+ /** The plugins `plugins` names, in the roles' order, and whether it
342
346
  * writes the list of test reviewers. */
343
347
  function pluginsWritten(v) {
344
348
  if (Array.isArray(v))
345
349
  fail("plugins", `must be grouped by phase: ${PHASES.join(", ")}`);
346
350
  const phases = object(v ?? {}, "plugins");
347
- const slots = Object.fromEntries(PHASES.map((phase) => [
351
+ const roles = Object.fromEntries(PHASES.map((phase) => [
348
352
  phase,
349
353
  object(phases[phase] ?? {}, `plugins.${phase}`),
350
354
  ]));
351
- const at = (slot) => slots[SLOT_SHAPE[slot].phase][SLOT_SHAPE[slot].key];
355
+ const at = (role) => roles[ROLE_SHAPE[role].phase][ROLE_SHAPE[role].key];
352
356
  return {
353
- plugins: SLOTS.flatMap((slot) => {
354
- const written = at(slot);
355
- const key = slotPath(slot);
357
+ plugins: ROLES.flatMap((role) => {
358
+ const written = at(role);
359
+ const key = rolePath(role);
356
360
  if (written === undefined)
357
361
  return [];
358
- if (!SLOT_SHAPE[slot].list)
359
- return [plugin(written, key, slot)];
362
+ if (!ROLE_SHAPE[role].list)
363
+ return [plugin(written, key, role)];
360
364
  if (!Array.isArray(written))
361
365
  return fail(key, "must be a list");
362
- return written.map((item, i) => plugin(item, `${key}[${i}]`, slot));
366
+ // A plugin left out with `off: true` is not used, and its role still
367
+ // counts as written.
368
+ return written.flatMap((item, i) => {
369
+ if (isObj(item) && "off" in item) {
370
+ if (item.off !== true)
371
+ fail(`${key}[${i}].off`, "must be true");
372
+ return [];
373
+ }
374
+ return [plugin(item, `${key}[${i}]`, role)];
375
+ });
363
376
  }),
364
377
  testReviewersWritten: at("test-reviewer") !== undefined,
365
378
  };
366
379
  }
367
- /** Where each of the settings' plug-ins is written, such as
380
+ /** Where each of the settings' plugins is written, such as
368
381
  * `plugins.build.reviewers[0]`. */
369
382
  function pluginPaths(plugins) {
370
383
  const seen = new Map();
371
384
  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}]`;
385
+ if (!ROLE_SHAPE[p.role].list)
386
+ return rolePath(p.role);
387
+ const i = seen.get(p.role) ?? 0;
388
+ seen.set(p.role, i + 1);
389
+ return `${rolePath(p.role)}[${i}]`;
377
390
  });
378
391
  }
379
392
  /** A command written as one line of text, or null when it is not written. */
@@ -404,7 +417,7 @@ function commandsOf(v) {
404
417
  }
405
418
  /** The settings with every default filled in. Throws a SettingsError naming
406
419
  * the key on anything unsound. `exists` says whether a path from the root
407
- * exists, for the plug-ins' files. */
420
+ * exists, for the plugins' files. */
408
421
  export function parseSettings(raw, exists, built = BUILT) {
409
422
  const written = raw ?? {};
410
423
  // The version comes before any other key, so a file in the older shape is
@@ -419,6 +432,7 @@ export function parseSettings(raw, exists, built = BUILT) {
419
432
  fail(key, `moved to commands.${key}`);
420
433
  }
421
434
  const top = object(written, "");
435
+ strings(top.presets, "presets");
422
436
  if (typeof top.repository !== "string" ||
423
437
  !/^[\w.-]+\/[\w.-]+$/.test(top.repository))
424
438
  fail("repository", "must be owner/name");
@@ -488,9 +502,9 @@ export function parseSettings(raw, exists, built = BUILT) {
488
502
  ? (command(specsBlock.check, "specs.check") ?? OPENSPEC_CHECK)
489
503
  : null;
490
504
  const autoMerge = object(top["auto-merge"], "auto-merge");
491
- const ciReview = top["ci-review"] === undefined
505
+ const prReview = top["pr-review"] === undefined
492
506
  ? null
493
- : object(top["ci-review"] ?? {}, "ci-review");
507
+ : object(top["pr-review"] ?? {}, "pr-review");
494
508
  const site = parseSite(top.site, exists);
495
509
  const commands = commandsOf(top.commands);
496
510
  const { plugins, testReviewersWritten } = pluginsWritten(top.plugins);
@@ -531,7 +545,7 @@ export function parseSettings(raw, exists, built = BUILT) {
531
545
  deny: strings(autoMerge.deny, "auto-merge.deny"),
532
546
  commands: strings(autoMerge.commands, "auto-merge.commands"),
533
547
  },
534
- ciReview: ciReview && { commands: reviewCommands(ciReview.commands) },
548
+ prReview: prReview && { commands: reviewCommands(prReview.commands) },
535
549
  site,
536
550
  sessionMinutes: sessionMinutesOf(top["session-minutes"]),
537
551
  rules: rulesOf(top.rules),
@@ -571,31 +585,243 @@ export function patternWarnings(s, files) {
571
585
  export const NO_DEPENDENCIES = "The factory's settings cannot be read until dependencies are installed: run npm ci.";
572
586
  /** js-yaml is loaded when needed, so a checkout without dependencies gets
573
587
  * one line saying what to do rather than a stack trace. */
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) {
579
- let load;
588
+ async function yamlOf(d) {
580
589
  try {
581
- load = await d.loadYaml();
590
+ return await d.loadYaml();
582
591
  }
583
592
  catch {
584
593
  throw new SettingsError(NO_DEPENDENCIES);
585
594
  }
595
+ }
596
+ const readOrNull = (path) => {
597
+ try {
598
+ return readFileSync(path, "utf8");
599
+ }
600
+ catch {
601
+ return null;
602
+ }
603
+ };
604
+ /** The choices file read as a map from a key to a preset's name. */
605
+ export function parseChoices(text, load) {
606
+ if (text === null)
607
+ return {};
608
+ const bad = () => new SettingsError('.claude/factory.choices.yaml: each line must be KEY: "PRESET"');
609
+ let v;
610
+ try {
611
+ v = load(text);
612
+ }
613
+ catch {
614
+ throw bad();
615
+ }
616
+ if (v === null || v === undefined)
617
+ return {};
618
+ if (!isObj(v) || Object.values(v).some((x) => typeof x !== "string"))
619
+ throw bad();
620
+ return v;
621
+ }
622
+ /** The settings combined from the factory's defaults, each preset in
623
+ * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
624
+ * into the lock. `factoryFile` and `ownFile` say which preset files are
625
+ * kept back: the factory's own, and the repository's own. */
626
+ export async function resolveFiles(d, keep = {}) {
627
+ const load = await yamlOf(d);
628
+ let ownText;
629
+ let own;
586
630
  try {
587
- return load(d.readFile());
631
+ ownText = d.readFile();
632
+ own = load(ownText);
588
633
  }
589
634
  catch (e) {
590
635
  throw new SettingsError(`${SETTINGS_FILE}: ${e.message}`);
591
636
  }
637
+ const P = await import("./preset.mjs");
638
+ const top = isObj(own) ? own : {};
639
+ const names = isObj(own) ? strings(top.presets, "presets") : [];
640
+ const twice = names.find((n, i) => names.indexOf(n) !== i);
641
+ if (twice)
642
+ throw new SettingsError(`presets: ${twice} is listed twice`);
643
+ const root = d.root ?? repoRoot();
644
+ const presets = [];
645
+ const layers = [];
646
+ const ships = new Map();
647
+ for (const name of names) {
648
+ let found;
649
+ try {
650
+ found = P.findPreset(root, name);
651
+ }
652
+ catch (e) {
653
+ if (e instanceof P.PresetError)
654
+ throw new SettingsError(e.message);
655
+ throw e;
656
+ }
657
+ let raw;
658
+ try {
659
+ raw = load(readFileSync(join(found.dir, P.PRESET_FILE), "utf8"));
660
+ }
661
+ catch (e) {
662
+ throw new SettingsError(`${name}: ${e.message}`);
663
+ }
664
+ const fault = P.presetFaults(raw)[0];
665
+ if (fault)
666
+ throw new SettingsError(`${name}: ${fault.key}: ${fault.message}`);
667
+ // The version is the preset file's own, and never the repository's.
668
+ const { version: _, ...settings } = raw;
669
+ presets.push(found);
670
+ layers.push({ name, raw: settings });
671
+ ships.set(name, P.shipped(found.dir));
672
+ }
673
+ layers.push({ name: P.OWN, raw: top });
674
+ const choicesText = d.readChoices?.() ?? null;
675
+ const choices = parseChoices(choicesText, load);
676
+ let resolution;
677
+ try {
678
+ resolution = P.combine({ layers, choices, ships, ...keep });
679
+ }
680
+ catch (e) {
681
+ if (e instanceof P.PresetError)
682
+ throw new SettingsError(e.message);
683
+ throw e;
684
+ }
685
+ const exists = (path) => d.exists(path) || resolution.files.has(path);
686
+ let settings;
687
+ try {
688
+ settings = parseSettings(isObj(own) ? resolution.raw : own, exists);
689
+ }
690
+ catch (e) {
691
+ throw e instanceof SettingsError ? fromPreset(e, resolution) : e;
692
+ }
693
+ return {
694
+ settings,
695
+ resolution,
696
+ presets,
697
+ own: top,
698
+ ownText,
699
+ choices,
700
+ choicesText,
701
+ exists,
702
+ };
703
+ }
704
+ /** A fault the settings' check found in a value a preset gave, named by
705
+ * that preset rather than by `.claude/factory.yaml`. */
706
+ function fromPreset(e, r) {
707
+ const m = new RegExp(`^${SETTINGS_FILE.replace(/\./g, "\\.")}: ([^:]+): `).exec(e.message);
708
+ if (!m)
709
+ return e;
710
+ const key = m[1].replace(/\[\d+\]/g, "");
711
+ for (let at = key; at; at = at.includes(".") ? at.slice(0, at.lastIndexOf(".")) : "") {
712
+ const from = r.sources.get(at)?.from;
713
+ if (from === undefined)
714
+ continue;
715
+ if (!from || from === SETTINGS_FILE)
716
+ return e;
717
+ return new SettingsError(`${from}: ${e.message.slice(SETTINGS_FILE.length + 2)}`);
718
+ }
719
+ return e;
720
+ }
721
+ /** Why the lock `d` reads is stale, or null when it is current or `d`
722
+ * reads none. */
723
+ export async function staleOf(d) {
724
+ if (!d.lock)
725
+ return null;
726
+ const load = await yamlOf(d);
727
+ const P = await import("./preset.mjs");
728
+ const root = d.root ?? repoRoot();
729
+ let own;
730
+ try {
731
+ own = d.readFile();
732
+ }
733
+ catch {
734
+ own = null;
735
+ }
736
+ return P.staleReason({
737
+ lock: d.lock.read(),
738
+ own,
739
+ choices: d.readChoices?.() ?? null,
740
+ changed: d.changed ?? (() => []),
741
+ installed: d.installed ??
742
+ ((pkg) => existsSync(join(root, "node_modules"))
743
+ ? (P.findPackage(root, pkg)?.version ?? null)
744
+ : undefined),
745
+ load,
746
+ });
747
+ }
748
+ /** The settings in the lock, after checking it is current where `check`
749
+ * says to. */
750
+ async function fromLock(d, lock) {
751
+ const load = await yamlOf(d);
752
+ const P = await import("./preset.mjs");
753
+ if (lock.check) {
754
+ const reason = await staleOf(d);
755
+ if (reason)
756
+ throw new SettingsError(reason);
757
+ }
758
+ const text = lock.read();
759
+ if (text === null)
760
+ throw new SettingsError(P.staleMessages.missing);
761
+ let parsed;
762
+ try {
763
+ parsed = P.readLock(text, load);
764
+ }
765
+ catch (e) {
766
+ throw new SettingsError(`${P.LOCK_FILE}: ${e.message}`);
767
+ }
768
+ if (!parsed.settings)
769
+ throw new SettingsError(P.staleMessages.earlier);
770
+ return { settings: parseSettings(parsed.settings, d.exists), text };
771
+ }
772
+ /** The lines of the lock's `settings` block, as `factory config explain`
773
+ * printed them when the lock was written. */
774
+ export function lockSettingsLines(text) {
775
+ const lines = text.split("\n");
776
+ const start = lines.indexOf("settings:");
777
+ if (start < 0)
778
+ return [];
779
+ const out = [];
780
+ for (const line of lines.slice(start + 1)) {
781
+ if (line && !line.startsWith(" "))
782
+ break;
783
+ out.push(line.slice(2));
784
+ }
785
+ return out;
592
786
  }
593
787
  /** The settings file: FACTORY_SETTINGS where it is set, for trying settings
594
788
  * against a board without changing the repository's, and otherwise the
595
789
  * repository's own. */
596
790
  export const settingsPath = (root, env = process.env) => env.FACTORY_SETTINGS || `${root}/${SETTINGS_FILE}`;
597
- export const defaultDeps = (root = repoRoot()) => ({
598
- readFile: () => readFileSync(settingsPath(root), "utf8"),
791
+ /** The settings of the checkout at `root`, read from its lock, or from
792
+ * the lock FACTORY_LOCK names without checking it is current, or from the
793
+ * settings file FACTORY_SETTINGS names with no lock at all. */
794
+ export const defaultDeps = (root = repoRoot(), env = process.env) => ({
795
+ readFile: () => readFileSync(settingsPath(root, env), "utf8"),
796
+ root,
797
+ readChoices: () => env.FACTORY_SETTINGS
798
+ ? null
799
+ : readOrNull(join(root, ".claude/factory.choices.yaml")),
800
+ lock: env.FACTORY_LOCK
801
+ ? { read: () => readOrNull(env.FACTORY_LOCK), check: false }
802
+ : env.FACTORY_SETTINGS
803
+ ? undefined
804
+ : {
805
+ read: () => readOrNull(join(root, ".claude/factory.lock")),
806
+ check: true,
807
+ },
808
+ changed: () => {
809
+ try {
810
+ return execFileSync("git", [
811
+ "status",
812
+ "--porcelain",
813
+ "--",
814
+ SETTINGS_FILE,
815
+ ".claude/factory.choices.yaml",
816
+ ], { cwd: root, encoding: "utf8" })
817
+ .split("\n")
818
+ .filter(Boolean)
819
+ .map((l) => l.slice(3));
820
+ }
821
+ catch {
822
+ return [];
823
+ }
824
+ },
599
825
  exists: (path) => existsSync(`${root}/${path}`),
600
826
  hasPackage: (name) => {
601
827
  try {
@@ -628,8 +854,16 @@ export function fieldNamesOf(s) {
628
854
  cost: s.tickets.fields.cost,
629
855
  };
630
856
  }
631
- /** The settings of the checkout the command runs in. */
632
- export const loadSettings = (d = defaultDeps()) => read(d);
857
+ /** The settings of the checkout at `root` resolved from the files the lock
858
+ * is made from, for the commands that make or check the lock. */
859
+ export const filesDeps = (root = repoRoot(), env = process.env) => ({ ...defaultDeps(root, env), lock: undefined });
860
+ /** The settings of the checkout the command runs in: from its lock, or
861
+ * resolved from the files where `d` reads no lock. */
862
+ export async function loadSettings(d = defaultDeps()) {
863
+ return d.lock
864
+ ? (await fromLock(d, d.lock)).settings
865
+ : (await resolveFiles(d)).settings;
866
+ }
633
867
  function lookup(s, key) {
634
868
  if (key === "specs.check")
635
869
  return s.specCheck;
@@ -647,7 +881,7 @@ function lookup(s, key) {
647
881
  "test-one": "testOne",
648
882
  "end-to-end": "endToEnd",
649
883
  "auto-merge": "autoMerge",
650
- "ci-review": "ciReview",
884
+ "pr-review": "prReview",
651
885
  "code-host": "codeHost",
652
886
  "design-guide": "designGuide",
653
887
  "max-pages": "maxPages",
@@ -665,16 +899,16 @@ function lookup(s, key) {
665
899
  /** The factory's design skill, which `factory sync` writes where there is a
666
900
  * site. */
667
901
  const DESIGN_SKILL = ".claude/skills/factory-design/SKILL.md";
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
902
+ /** Every plugin the factory will use, in the roles' order: the settings'
903
+ * own, and the factory's for each role they leave out. The refiner and the
670
904
  * 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
905
+ * settings write the list. Its design skill is the mockups plugin of a
672
906
  * site that names none, once it is synced. */
673
907
  export function pluginsOf(s, exists) {
674
- const builtIn = (kind, name, slot) => ({
908
+ const builtIn = (kind, name, role) => ({
675
909
  kind,
676
910
  name,
677
- slot,
911
+ role,
678
912
  files: [],
679
913
  labels: [],
680
914
  });
@@ -691,22 +925,33 @@ export function pluginsOf(s, exists) {
691
925
  : [builtIn("agent", "factory-test-reviewer", "test-reviewer")],
692
926
  resolver: [],
693
927
  };
694
- return SLOTS.flatMap((slot) => {
695
- const own = s.plugins.filter((p) => p.slot === slot);
696
- return own.length ? own : fallback[slot];
928
+ return ROLES.flatMap((role) => {
929
+ const own = s.plugins.filter((p) => p.role === role);
930
+ return own.length ? own : fallback[role];
697
931
  });
698
932
  }
699
933
  export async function main(argv, d) {
700
934
  const [command, arg] = argv;
701
935
  if (!command) {
702
- d.err("Usage: factory config get KEY | config check | config explain | plugins [SLOT]");
936
+ d.err("Usage: factory config get KEY | config check | config explain | plugins [ROLE]");
703
937
  return 2;
704
938
  }
939
+ // `config check` reads the files the lock is made from, so it can say
940
+ // what is wrong with them while the lock is stale; everything else reads
941
+ // the lock.
705
942
  let s;
706
- let raw;
943
+ let resolved = null;
944
+ let lockText = null;
707
945
  try {
708
- raw = await readRaw(d);
709
- s = parseSettings(raw, d.exists);
946
+ if (d.lock && command !== "check") {
947
+ const read = await fromLock(d, d.lock);
948
+ s = read.settings;
949
+ lockText = read.text;
950
+ }
951
+ else {
952
+ resolved = await resolveFiles({ ...d, lock: undefined });
953
+ s = resolved.settings;
954
+ }
710
955
  }
711
956
  catch (e) {
712
957
  if (!(e instanceof SettingsError))
@@ -721,26 +966,31 @@ export async function main(argv, d) {
721
966
  }
722
967
  for (const w of patternWarnings(s, d.listFiles()))
723
968
  d.err(`warning: ${w}`);
724
- if (s.site && !s.plugins.some((p) => p.slot === "mockups"))
969
+ if (s.site && !s.plugins.some((p) => p.role === "mockups"))
725
970
  if (!d.exists(DESIGN_SKILL))
726
971
  d.err(`warning: ${DESIGN_SKILL} is missing: run \`npx --no-install factory sync\` to give the site its design skill`);
727
972
  return 0;
728
973
  }
729
974
  if (command === "explain") {
730
- const { explainLines } = await import("./explain.mjs");
731
- for (const line of await explainLines(s, raw, d.exists))
975
+ if (lockText !== null) {
976
+ for (const line of lockSettingsLines(lockText))
977
+ d.out(line);
978
+ return 0;
979
+ }
980
+ const { explainLines, markerOf } = await import("./explain.mjs");
981
+ for (const line of await explainLines(s, markerOf(resolved.resolution), resolved.exists))
732
982
  d.out(line);
733
983
  return 0;
734
984
  }
735
985
  if (command === "plugins") {
736
- if (arg && !SLOTS.includes(arg)) {
737
- d.err(`${arg}: must be one of ${SLOTS.join(", ")}`);
986
+ if (arg && !ROLES.includes(arg)) {
987
+ d.err(`${arg}: must be one of ${ROLES.join(", ")}`);
738
988
  return 1;
739
989
  }
740
990
  for (const p of pluginsOf(s, d.exists)) {
741
- if (arg && p.slot !== arg)
991
+ if (arg && p.role !== arg)
742
992
  continue;
743
- d.out([p.kind, p.name, p.slot, ...p.files, ...p.labels].join(" "));
993
+ d.out([p.kind, p.name, p.role, ...p.files, ...p.labels].join(" "));
744
994
  }
745
995
  return 0;
746
996
  }
@@ -767,7 +1017,7 @@ export async function main(argv, d) {
767
1017
  return 0;
768
1018
  }
769
1019
  /** `factory config get KEY`, `factory config check`, and
770
- * `factory plugins [SLOT]`. */
1020
+ * `factory plugins [ROLE]`. */
771
1021
  export async function run(argv) {
772
1022
  return main(argv, defaultDeps());
773
1023
  }
package/dist/deps.d.mts CHANGED
@@ -21,15 +21,17 @@ export type Bump = {
21
21
  * patch only. */
22
22
  export declare function isMajor(title: string): boolean;
23
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;
24
+ * `branch` is the default branch, which a conflicting bump merges, and
25
+ * `synced` the packages whose update needs `factory sync`: the factory's
26
+ * own and each preset's. */
27
+ export declare function nextStep(bump: Bump, branch: string, synced?: string[]): string;
26
28
  /** Every check on the bump's commit, not a fixed list of names: passed, or
27
29
  * the names that failed and the names still running. */
28
30
  export declare function checksLine(bump: Bump): string;
29
- export declare function formatBump(bump: Bump, branch: string): string[];
31
+ export declare function formatBump(bump: Bump, branch: string, synced?: string[]): string[];
30
32
  /** `defaultBranch` gives the default branch's name, and rejects when it
31
33
  * 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>;
34
+ export declare function main(p: CodeHost, out: (line: string) => void, argv: string[], defaultBranch: () => Promise<string>, synced?: string[]): Promise<number>;
33
35
  /** `factory deps`. */
34
36
  export declare function run(argv?: string[]): Promise<number>;
35
37
  export {};