@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/sync.d.mts CHANGED
@@ -1,4 +1,5 @@
1
- import { type Settings } from "./config.mts";
1
+ import { type Resolved, type Settings } from "./config.mts";
2
+ import { type Replaced } from "./preset.mts";
2
3
  /** The package's own folder: the parent of `src/`, or of `dist/` once
3
4
  * compiled. */
4
5
  export declare const PACKAGE: string;
@@ -58,27 +59,61 @@ export declare function withImport(text: string | null): string;
58
59
  /** `CLAUDE.md` without the rules' import, nor the blank line `withImport`
59
60
  * put before it, or null when nothing else is left. */
60
61
  export declare function withoutImport(text: string): string | null;
61
- export declare function lockText(version: string, files: string[]): string;
62
- export declare function lockedFiles(text: string | null): string[];
62
+ export type LockParts = {
63
+ version: string;
64
+ presets: {
65
+ name: string;
66
+ version: string;
67
+ }[];
68
+ hash: string;
69
+ /** The settings in effect, as `factory config explain` prints them. */
70
+ settings: string[];
71
+ overridden: Record<string, Replaced[]>;
72
+ files: string[];
73
+ };
74
+ export declare function lockText(l: LockParts): string;
75
+ /** The files a lock lists, from any release's lock. One that a merge left
76
+ * with conflict markers is read line by line, from each side's `files`. */
77
+ export declare function lockedFiles(text: string | null, load: (t: string) => unknown): string[];
78
+ /** The dependency auto-merge workflow with each preset's package held back
79
+ * as the factory's own is, so a preset update waits for a person. */
80
+ export declare function withPresetPackages(text: string, packages: string[], file: string): string;
63
81
  export type Plan = {
64
82
  /** Path from the root, and its text, for each file a sync writes. */
65
83
  write: Map<string, string>;
66
- /** Paths the lock lists that this version no longer writes. */
84
+ /** Paths the lock lists that this version no longer writes, and the
85
+ * choices file once its last choice is dropped. */
67
86
  remove: string[];
87
+ /** A line for each preset file left as it is. */
88
+ kept: string[];
89
+ /** A line for each choice dropped. */
90
+ dropped: string[];
68
91
  };
69
92
  /** What a sync of `root` from `pkg` writes and deletes, in a repository
70
93
  * whose default branch is `branch`. */
71
- export declare function plan(pkg: string, root: string, s: Settings, branch: string): Plan;
94
+ export declare function plan(pkg: string, root: string, r: Resolved, branch: string): Promise<Plan>;
72
95
  /** The paths whose content a sync would change, in the plan's order. */
73
96
  export declare function differences(root: string, p: Plan): string[];
74
97
  export declare function main(argv: string[], d: {
75
98
  root: string;
76
99
  pkg: string;
77
- settings: () => Promise<Settings>;
100
+ settings: () => Promise<Resolved>;
101
+ /** Why the lock is stale, or null when it is current. */
102
+ stale: () => Promise<string | null>;
78
103
  /** The repository's default branch, or null when it cannot be told. */
79
- defaultBranch: () => Promise<string | null>;
104
+ defaultBranch: (s: Settings) => Promise<string | null>;
80
105
  out: (line: string) => void;
81
106
  err: (line: string) => void;
82
107
  }): Promise<number>;
108
+ /** The sync of the repository at `root`. */
109
+ export declare const syncDeps: (root: string) => {
110
+ root: string;
111
+ pkg: string;
112
+ settings: () => Promise<Resolved>;
113
+ stale: () => Promise<string | null>;
114
+ defaultBranch: (s: Settings) => Promise<string | null>;
115
+ out: (line: string) => void;
116
+ err: (line: string) => void;
117
+ };
83
118
  export declare function run(argv: string[]): Promise<number>;
84
119
  export {};
package/dist/sync.mjs CHANGED
@@ -1,8 +1,10 @@
1
1
  // Writes the factory's skills, agents, rules, review instructions,
2
2
  // workflows, and the actions they call from the package into the
3
- // repository, its hook entries into `.claude/settings.json`, the rules'
4
- // import into `CLAUDE.md`, and
5
- // `.claude/factory.lock`: the factory's version and the files it wrote.
3
+ // repository, the agents and skills its presets ship, its hook entries
4
+ // into `.claude/settings.json`, the rules' import into `CLAUDE.md`, and
5
+ // `.claude/factory.lock`: the factory's version, the presets, the settings
6
+ // in effect, and the files it wrote. Every other command reads the
7
+ // settings from the lock.
6
8
  //
7
9
  // factory sync # write what differs
8
10
  // factory sync --check # write nothing; exit 1 naming what differs
@@ -15,7 +17,8 @@
15
17
  import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
16
18
  import { dirname, join, relative, sep } from "node:path";
17
19
  import { fileURLToPath } from "node:url";
18
- import { defaultDeps, loadSettings, repoRoot, RULE_NUMBERS, } from "./config.mjs";
20
+ import { filesDeps, repoRoot, resolveFiles, RULE_NUMBERS, staleOf, defaultDeps, } from "./config.mjs";
21
+ import { CHOICES_FILE, choicesText, settingsHash, staleChoices, } from "./preset.mjs";
19
22
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
20
23
  /** The package's own folder: the parent of `src/`, or of `dist/` once
21
24
  * compiled. */
@@ -39,7 +42,7 @@ const NEEDS = {
39
42
  "workflows/factory-deps-auto-merge.yml": (_, has) => has(DEPENDABOT),
40
43
  "workflows/factory-board-sync.yml": (s) => s.tickets.board !== null,
41
44
  "workflows/factory-merge-policy.yml": (s) => s.autoMerge.allow.length > 0,
42
- "workflows/factory-claude-review.yml": (s) => s.ciReview !== null,
45
+ "workflows/factory-claude-review.yml": (s) => s.prReview !== null,
43
46
  "workflows/factory-poller.yml": (s) => s.builds.trigger === "github-action",
44
47
  };
45
48
  const POLLER_WORKFLOW = "workflows/factory-poller.yml";
@@ -348,27 +351,102 @@ export function withoutImport(text) {
348
351
  const after = lines.join("\n");
349
352
  return after.trim() ? after : null;
350
353
  }
351
- export function lockText(version, files) {
354
+ /** A key or a value as YAML: plain where it reads back as the same text,
355
+ * quoted as JSON otherwise. */
356
+ const scalar = (v) => typeof v === "string" &&
357
+ /^[A-Za-z0-9_./][A-Za-z0-9_./ -]*$/.test(v) &&
358
+ !/ $/.test(v) &&
359
+ !/^(true|false|null|yes|no|on|off|~|[-+.\d][\d._eE+-]*)$/i.test(v)
360
+ ? v
361
+ : JSON.stringify(v);
362
+ export function lockText(l) {
363
+ const replaced = Object.entries(l.overridden);
352
364
  return [
353
- "# Written by `factory sync`: the factory's version and the files it",
354
- "# wrote. Do not edit.",
355
- `version: ${version}`,
365
+ "# Written by `factory sync`: the factory's version, the presets, the",
366
+ "# settings in effect, and the files it wrote. Do not edit.",
367
+ `version: ${l.version}`,
368
+ ...(l.presets.length
369
+ ? [
370
+ "presets:",
371
+ ...l.presets.flatMap((p) => [
372
+ ` - name: ${JSON.stringify(p.name)}`,
373
+ ` version: ${scalar(p.version)}`,
374
+ ]),
375
+ ]
376
+ : ["presets: []"]),
377
+ `settings-hash: ${l.hash}`,
378
+ "settings:",
379
+ ...l.settings.map((line) => ` ${line}`),
380
+ ...(replaced.length
381
+ ? [
382
+ "overridden:",
383
+ ...replaced.flatMap(([key, values]) => [
384
+ ` ${scalar(key)}:`,
385
+ ...values.flatMap((r) => [
386
+ ` - from: ${JSON.stringify(r.from)}`,
387
+ ` value: ${JSON.stringify(r.value)}`,
388
+ ]),
389
+ ]),
390
+ ]
391
+ : ["overridden: {}"]),
356
392
  "files:",
357
- ...files.map((f) => ` - ${f}`),
393
+ ...l.files.map((f) => ` - ${f}`),
358
394
  "",
359
395
  ].join("\n");
360
396
  }
361
- export function lockedFiles(text) {
397
+ /** The files a lock lists, from any release's lock. One that a merge left
398
+ * with conflict markers is read line by line, from each side's `files`. */
399
+ export function lockedFiles(text, load) {
362
400
  if (!text)
363
401
  return [];
402
+ try {
403
+ const o = load(text);
404
+ return Array.isArray(o?.files) ? o.files.map(String) : [];
405
+ }
406
+ catch {
407
+ const out = [];
408
+ let inFiles = false;
409
+ for (const line of text.split("\n")) {
410
+ if (/^files:/.test(line))
411
+ inFiles = true;
412
+ else if (/^\S/.test(line) && !/^(<{7}|={7}|>{7})/.test(line))
413
+ inFiles = false;
414
+ const item = inFiles ? /^ {2}- (.+)$/.exec(line)?.[1] : undefined;
415
+ if (item && !out.includes(item))
416
+ out.push(item);
417
+ }
418
+ return out;
419
+ }
420
+ }
421
+ const AUTO_MERGE_WORKFLOW = "workflows/factory-deps-auto-merge.yml";
422
+ const FACTORY_EXCLUSION = "!contains(steps.meta.outputs.dependency-names, 'davidbyoung/software-factory')";
423
+ /** The dependency auto-merge workflow with each preset's package held back
424
+ * as the factory's own is, so a preset update waits for a person. */
425
+ export function withPresetPackages(text, packages, file) {
426
+ if (!packages.length)
427
+ return text;
428
+ const at = text.split(FACTORY_EXCLUSION).length - 1;
429
+ if (at !== 1)
430
+ throw new Error(`${file}: expected one line holding back the factory, to hold back the presets too`);
364
431
  return text
365
432
  .split("\n")
366
- .map((l) => /^ {2}- (.+)$/.exec(l)?.[1])
367
- .filter((f) => Boolean(f));
433
+ .map((line) => {
434
+ if (line.trim() !== FACTORY_EXCLUSION)
435
+ return line;
436
+ const indent = line.slice(0, line.indexOf("!"));
437
+ return [
438
+ `${line} &&`,
439
+ ...packages.map((p, i) => `${indent}!contains(steps.meta.outputs.dependency-names, '${p}')${i < packages.length - 1 ? " &&" : ""}`),
440
+ ].join("\n");
441
+ })
442
+ .join("\n");
368
443
  }
369
444
  /** What a sync of `root` from `pkg` writes and deletes, in a repository
370
445
  * whose default branch is `branch`. */
371
- export function plan(pkg, root, s, branch) {
446
+ export async function plan(pkg, root, r, branch) {
447
+ const { load } = await import("js-yaml");
448
+ const { explainLines, markerOf } = await import("./explain.mjs");
449
+ const s = r.settings;
372
450
  const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
373
451
  const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
374
452
  const write = new Map();
@@ -383,15 +461,55 @@ export function plan(pkg, root, s, branch) {
383
461
  ? withMinutes(text, s.sessionMinutes[kind], from)
384
462
  : from === POLLER_WORKFLOW
385
463
  ? withSchedule(text, s.builds.pollMinutes, from)
386
- : withRules(text, s.rules, from));
464
+ : from === AUTO_MERGE_WORKFLOW
465
+ ? withPresetPackages(text, [...new Set(r.presets.map((p) => p.pkg))], from)
466
+ : withRules(text, s.rules, from));
467
+ }
468
+ // A preset's agent or skill, unless the factory's own file or one the
469
+ // repository wrote itself is at its path: those always stay.
470
+ const previous = lockedFiles(read(LOCK), load);
471
+ const kept = [];
472
+ for (const [to, { from, source }] of r.resolution.files) {
473
+ if (write.has(to))
474
+ kept.push(`kept ${to}, the factory's own, over ${from}`);
475
+ else if (existsSync(join(root, to)) && !previous.includes(to))
476
+ kept.push(`kept ${to}, this repository's own, over ${from}`);
477
+ else
478
+ write.set(to, readFileSync(source, "utf8"));
387
479
  }
388
480
  const launcher = launcherPath(pkg, root, manifest.name);
389
481
  write.set(SETTINGS_JSON, withHooks(read(SETTINGS_JSON), launcher));
390
482
  write.set(CLAUDE_MD, withImport(read(CLAUDE_MD)));
391
483
  const files = [...write.keys()].filter((p) => p !== SETTINGS_JSON && p !== CLAUDE_MD);
392
- write.set(LOCK, lockText(manifest.version, files));
393
- const remove = lockedFiles(read(LOCK)).filter((p) => !write.has(p) && existsSync(join(root, p)));
394
- return { write, remove };
484
+ // A choice whose preset is gone, or no longer sets its key, is dropped.
485
+ const stale = staleChoices(r.choices, r.presets.map((p) => p.name), r.resolution.setBy);
486
+ const choices = { ...r.choices };
487
+ for (const c of stale)
488
+ delete choices[c.key];
489
+ const chosen = stale.length ? choicesText(choices) : r.choicesText;
490
+ const remove = [];
491
+ if (stale.length) {
492
+ if (chosen === null)
493
+ remove.push(CHOICES_FILE);
494
+ else
495
+ write.set(CHOICES_FILE, chosen);
496
+ }
497
+ const settings = await explainLines(s, markerOf(r.resolution), (p) => r.exists(p) || write.has(p));
498
+ write.set(LOCK, lockText({
499
+ version: manifest.version,
500
+ presets: r.presets.map((p) => ({ name: p.name, version: p.version })),
501
+ hash: settingsHash(r.ownText, chosen),
502
+ settings,
503
+ overridden: Object.fromEntries(r.resolution.overridden),
504
+ files,
505
+ }));
506
+ remove.unshift(...previous.filter((p) => !write.has(p) && existsSync(join(root, p))));
507
+ return {
508
+ write,
509
+ remove: remove.filter((p) => existsSync(join(root, p))),
510
+ kept,
511
+ dropped: stale.map((c) => `dropped the choice for ${c.key}: ${c.reason}`),
512
+ };
395
513
  }
396
514
  /** The paths whose content a sync would change, in the plan's order. */
397
515
  export function differences(root, p) {
@@ -401,13 +519,25 @@ export function differences(root, p) {
401
519
  return !existsSync(at) || readFileSync(at, "utf8") !== text;
402
520
  })
403
521
  .map(([path]) => path);
404
- return [...changed, ...p.remove];
522
+ // The lock comes last, as it records everything before it.
523
+ return [
524
+ ...changed.filter((path) => path !== LOCK),
525
+ ...p.remove,
526
+ ...changed.filter((path) => path === LOCK),
527
+ ];
405
528
  }
406
529
  export async function main(argv, d) {
407
530
  const check = argv.includes("--check");
408
- let s;
531
+ let r;
409
532
  try {
410
- s = await d.settings();
533
+ if (check) {
534
+ const reason = await d.stale();
535
+ if (reason) {
536
+ d.err(reason);
537
+ return 1;
538
+ }
539
+ }
540
+ r = await d.settings();
411
541
  }
412
542
  catch (e) {
413
543
  d.err(e instanceof Error ? e.message : String(e));
@@ -415,12 +545,12 @@ export async function main(argv, d) {
415
545
  }
416
546
  // Nothing is written with a guessed name: a push trigger that names the
417
547
  // wrong branch never runs.
418
- const branch = await d.defaultBranch();
548
+ const branch = await d.defaultBranch(r.settings);
419
549
  if (branch === null) {
420
550
  d.err(CANNOT_TELL);
421
551
  return 1;
422
552
  }
423
- const p = plan(d.pkg, d.root, s, branch);
553
+ const p = await plan(d.pkg, d.root, r, branch);
424
554
  const differ = differences(d.root, p);
425
555
  if (check) {
426
556
  if (differ.length === 0)
@@ -431,6 +561,8 @@ export async function main(argv, d) {
431
561
  d.err("Run `npx --no-install factory sync` and commit the result.");
432
562
  return 1;
433
563
  }
564
+ for (const line of [...p.kept, ...p.dropped])
565
+ d.out(line);
434
566
  for (const path of differ) {
435
567
  const at = join(d.root, path);
436
568
  const text = p.write.get(path);
@@ -446,14 +578,16 @@ export async function main(argv, d) {
446
578
  }
447
579
  return 0;
448
580
  }
581
+ /** The sync of the repository at `root`. */
582
+ export const syncDeps = (root) => ({
583
+ root,
584
+ pkg: PACKAGE,
585
+ settings: () => resolveFiles(filesDeps(root)),
586
+ stale: () => staleOf(defaultDeps(root)),
587
+ defaultBranch: (s) => defaultBranch(branchDeps(root, process.env, async () => s)),
588
+ out: (line) => console.log(line),
589
+ err: (line) => console.error(line),
590
+ });
449
591
  export async function run(argv) {
450
- const root = repoRoot();
451
- return main(argv, {
452
- root,
453
- pkg: PACKAGE,
454
- settings: () => loadSettings(defaultDeps(root)),
455
- defaultBranch: () => defaultBranch(branchDeps(root)),
456
- out: (line) => console.log(line),
457
- err: (line) => console.error(line),
458
- });
592
+ return main(argv, syncDeps(repoRoot()));
459
593
  }
package/docs/builds.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # Builds in the cloud
2
2
 
3
3
  A build is one session taking one approved ticket to a pull request. You
4
- can always build a ticket by asking a session on your machine. A build in
4
+ can always build a ticket by running `/factory-build N` in a session on
5
+ your machine. A build in
5
6
  the cloud does the same with nobody at the keyboard: it runs on your code
6
7
  host's cloud runner, and you read its log or its pull request afterward.
7
8
 
@@ -11,24 +12,24 @@ and the [reference](github/reference.md#workflows) has what runs there.
11
12
 
12
13
  ## Three ways a build starts
13
14
 
14
- | You | The build runs | You need |
15
- | ----------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
16
- | Ask a session: "build ticket 12" | In that session, wherever you opened it | Nothing |
17
- | Run `factory build 12` | In the cloud | Builds in the cloud set up |
18
- | Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
15
+ | What you do | Where the build runs | What you need |
16
+ | ------------------------------------ | --------------------------------------- | ----------------------------------------------------------------- |
17
+ | Run `/factory-build 12` in a session | In that session, wherever you opened it | Nothing |
18
+ | Run `factory build 12` | In the cloud | Builds in the cloud set up |
19
+ | Move the ticket to Ready on a board | In the cloud, at the poller's next pass | Builds in the cloud set up, and [the poller](#the-poller) running |
19
20
 
20
21
  Which of the last two you use is
21
22
  [`builds.trigger`](configuration.md#builds) in your
22
23
  [settings](configuration.md#builds):
23
24
 
24
- | `trigger` | Moving a ticket to Ready |
25
+ | `trigger` | What moving a ticket to Ready does |
25
26
  | --------------- | ----------------------------------------------------------------------------------------------------------------- |
26
27
  | `manual` | Records your approval and starts nothing. The default |
27
28
  | `own-server` | Starts a build within a minute, through the poller you host |
28
29
  | `github-action` | Starts one at the next pass of a schedule on the cloud runner, every `poll-minutes` minutes, with nothing to host |
29
30
 
30
- `manual` is a fine place to stay. Asking a session and running
31
- `factory build` work whatever the trigger.
31
+ `manual` is a fine place to stay. Running `/factory-build N` in a session
32
+ and running `factory build N` work whatever the trigger.
32
33
 
33
34
  ## What a build in the cloud does
34
35
 
@@ -269,10 +270,10 @@ hour.
269
270
  ## No trigger: `manual`
270
271
 
271
272
  Nothing watches the board. Moving a ticket to Ready records your approval
272
- and starts nothing. Ask a session:
273
+ and starts nothing. In a session, type:
273
274
 
274
275
  ```text
275
- build ticket 12
276
+ /factory-build 12
276
277
  ```
277
278
 
278
279
  The session claims the ticket, which moves it to "building" on the board,
package/docs/cli.md CHANGED
@@ -21,8 +21,8 @@ A table with a State column has commands still to come, marked
21
21
  **Planned**; every command in a table without one is built.
22
22
  [What is built](developing.md#what-is-built) lists the parts.
23
23
 
24
- The skills are not commands: you ask a session for one in plain words,
25
- such as "refine ticket 12". [Skills](skills.md) lists them.
24
+ The skills are not `factory` commands: you type one in a session as a
25
+ slash command, such as `/factory-refine 12`. [Skills](skills.md) lists them.
26
26
 
27
27
  ## Setting up
28
28
 
@@ -55,19 +55,38 @@ read is set.
55
55
  | ------------------------ | ----------------------------------------------------------------- | ----- |
56
56
  | `factory config get KEY` | To print one setting in effect, such as `tickets.board` | Built |
57
57
  | `factory config explain` | To see every setting in effect, defaults included | Built |
58
- | `factory plugins` | To see the plug-ins the factory will use, by slot | Built |
58
+ | `factory plugins` | To see the plugins the factory will use, by role | Built |
59
59
  | `factory site compare` | To picture a website's pages before and after a change. See below | Built |
60
60
  | `factory site stop` | To end the sites `compare --keep` left running | Built |
61
61
  | `factory remove` | To take the factory out of a repository | Built |
62
62
 
63
- `factory plugins` prints one line for each plug-in, the factory's own
64
- included: its kind, its name, its [slot](plugins.md#the-slots), then its
65
- files or labels. `factory plugins SLOT` prints one slot's lines.
63
+ `factory plugins` prints one line for each plugin, the factory's own
64
+ included: its kind, its name, its [role](plugins.md#the-roles), then its
65
+ files or labels. `factory plugins ROLE` prints one role's lines.
66
66
 
67
67
  A new version is installed with npm and applied with `factory sync`, as
68
68
  [Updating](updating.md) says. [Removing](removing.md) says what `remove`
69
69
  deletes and what it leaves to you.
70
70
 
71
+ ## Presets
72
+
73
+ A [preset](presets.md) is an npm package of settings that several
74
+ repositories share, listed under
75
+ [`presets`](configuration.md#presets).
76
+
77
+ | Command | When you run it |
78
+ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
79
+ | `factory preset add NAME` | To follow a preset. It shows what would change and asks before changing anything |
80
+ | `factory preset remove NAME` | To stop following one, the same way |
81
+ | `factory preset choices` | To see where two of your presets disagree, and choose which one this repository follows |
82
+ | `factory preset choose KEY PRESET` | To record one of those choices without questions, from a session or a script, as [Your choices](presets.md#your-choices) shows |
83
+ | `factory preset check` | In a preset's own package, before publishing it |
84
+ | `factory preset changes REF` | To see what the presets' update changed since `REF`, a git branch, tag, or commit such as `origin/main`. The [`factory-deps`](skills.md#factory-deps) skill posts it on each preset update |
85
+
86
+ `add` and `remove` ask only in a terminal. Elsewhere they print what would
87
+ change and stop, unless given `--yes`; `--dry-run` prints it and changes
88
+ nothing.
89
+
71
90
  ## Run for you
72
91
 
73
92
  The rest are run by the skills, the hooks, and the workflows, not by you.
@@ -114,7 +133,7 @@ ticket system would swallow, name it, and post nothing.
114
133
  `factory ticket refined N` posts nothing and exits 1 when N's body lacks a
115
134
  section a build reads, printing one line for each, such as
116
135
  `missing: ## Acceptance criteria`. With `--check` it prints `sound` for a
117
- body that passes. [Plug-ins](plugins.md#refiner) lists the sections.
136
+ body that passes. [Plugins](plugins.md#refiner) lists the sections.
118
137
 
119
138
  ### Pull requests
120
139
 
@@ -191,7 +210,7 @@ the commit hook blocks a session's git command with it.
191
210
  | `factory merge-policy N` | The merge-policy workflow | Decides whether N may merge without you, and why | Built |
192
211
  | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
193
212
  | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
194
- | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`ci-review.commands`](configuration.md#ci-review) | Built |
213
+ | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`pr-review.commands`](configuration.md#pr-review) | Built |
195
214
  | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
196
215
  | `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
197
216
  | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |