@davidbyoung/software-factory 0.1.9 → 0.1.11

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 (67) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +4 -7
  4. package/dist/cli.mjs +23 -1
  5. package/dist/code-host/github.d.mts +1 -1
  6. package/dist/code-host/github.mjs +31 -2
  7. package/dist/code-host/types.d.mts +20 -1
  8. package/dist/code-host/types.mjs +8 -0
  9. package/dist/columns-suggest.d.mts +25 -5
  10. package/dist/columns-suggest.mjs +117 -21
  11. package/dist/commands.d.mts +8 -2
  12. package/dist/commands.mjs +92 -8
  13. package/dist/config.d.mts +19 -7
  14. package/dist/config.mjs +109 -30
  15. package/dist/doctor.mjs +1 -2
  16. package/dist/explain.mjs +7 -1
  17. package/dist/init.d.mts +19 -0
  18. package/dist/init.mjs +139 -23
  19. package/dist/lib/gh.d.mts +6 -0
  20. package/dist/lib/gh.mjs +11 -1
  21. package/dist/lib/listed.d.mts +3 -2
  22. package/dist/lib/listed.mjs +5 -4
  23. package/dist/lib/work-status.d.mts +5 -5
  24. package/dist/lib/work-status.mjs +7 -8
  25. package/dist/merge-policy.mjs +7 -3
  26. package/dist/poller.d.mts +1 -1
  27. package/dist/poller.mjs +9 -6
  28. package/dist/pr.d.mts +8 -6
  29. package/dist/pr.mjs +47 -22
  30. package/dist/review-verdict.d.mts +22 -4
  31. package/dist/review-verdict.mjs +55 -17
  32. package/dist/specs/index.d.mts +6 -0
  33. package/dist/specs/index.mjs +15 -0
  34. package/dist/specs/openspec.d.mts +2 -0
  35. package/dist/specs/openspec.mjs +78 -0
  36. package/dist/specs/types.d.mts +53 -0
  37. package/dist/specs/types.mjs +4 -0
  38. package/dist/ticket.d.mts +6 -1
  39. package/dist/ticket.mjs +62 -3
  40. package/dist/tickets/github-access.d.mts +5 -0
  41. package/dist/tickets/github-access.mjs +22 -0
  42. package/dist/tickets/github.mjs +2 -0
  43. package/dist/tickets/types.d.mts +4 -0
  44. package/dist/tool-names.d.mts +2 -0
  45. package/dist/tool-names.mjs +3 -0
  46. package/dist/tools.d.mts +2 -0
  47. package/dist/tools.mjs +3 -0
  48. package/docs/builds.md +30 -14
  49. package/docs/cli.md +48 -30
  50. package/docs/configuration.md +237 -73
  51. package/docs/developing.md +104 -59
  52. package/docs/existing-repo.md +51 -29
  53. package/docs/github/by-hand.md +13 -1
  54. package/docs/github/setup.md +26 -2
  55. package/docs/glossary.md +7 -6
  56. package/docs/limitations.md +8 -5
  57. package/docs/presets.md +15 -3
  58. package/docs/updating.md +147 -2
  59. package/docs/workflow.md +26 -9
  60. package/package.json +1 -1
  61. package/rules.md +36 -30
  62. package/settings.schema.json +14 -9
  63. package/skills/factory-address-review/SKILL.md +40 -39
  64. package/skills/factory-build/SKILL.md +77 -52
  65. package/skills/factory-deps/SKILL.md +6 -4
  66. package/skills/factory-refine/SKILL.md +30 -22
  67. package/skills/factory-resolve-conflicts/SKILL.md +8 -7
package/dist/commands.mjs CHANGED
@@ -6,18 +6,30 @@
6
6
  // factory end-to-end FILE [--times K] # commands.end-to-end, K times in a row
7
7
  // factory specs check # specs.check
8
8
  //
9
+ // and the commands that reach the spec tool `specs` names:
10
+ //
11
+ // factory specs list # each spec it keeps
12
+ // factory specs new N # start ticket N's spec
13
+ // factory specs finish N # fold ticket N's spec in
14
+ //
9
15
  // Each command runs with bash from the repository's root, with its output
10
16
  // passed through and no standard input. `test-one` gets FILE and NAME in its
11
- // environment, `end-to-end` FILE, and the spec check DO_NOT_TRACK=1. An
12
- // argument a command does not know prints its usage and exits 2.
17
+ // environment, `end-to-end` FILE, and the spec check the spec tool's
18
+ // environment. An argument a command does not know prints its usage and
19
+ // exits 2.
13
20
  import { spawnSync } from "node:child_process";
14
21
  import { colorOn, painter, plain } from "./lib/color.mjs";
15
22
  import { defaultDeps, loadSettings, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
23
+ import { specTools } from "./specs/index.mjs";
24
+ import { openTickets } from "./tickets/index.mjs";
16
25
  const USAGE = {
17
26
  gate: "Usage: factory gate",
18
27
  "test-one": "Usage: factory test-one FILE [NAME]",
19
28
  "end-to-end": "Usage: factory end-to-end FILE [--times K]",
20
29
  "specs-check": "Usage: factory specs check",
30
+ "specs-list": "Usage: factory specs list",
31
+ "specs-new": "Usage: factory specs new N",
32
+ "specs-finish": "Usage: factory specs finish N",
21
33
  };
22
34
  /** What `factory end-to-end` was asked: the file, and how many runs when
23
35
  * `--times` is given; null when the arguments are not ones it knows. */
@@ -46,10 +58,16 @@ export async function main(argv, d) {
46
58
  return 2;
47
59
  };
48
60
  const e2e = name === "end-to-end" ? endToEndArgs(args) : null;
49
- if (name === "gate" || name === "specs-check") {
61
+ if (name === "gate" || name === "specs-check" || name === "specs-list") {
50
62
  if (args.length > 0)
51
63
  return usage();
52
64
  }
65
+ else if (name === "specs-new" || name === "specs-finish") {
66
+ // A ticket as the ticket system writes it: GitHub's, the only one
67
+ // built, are whole numbers.
68
+ if (args.length !== 1 || !/^[1-9]\d*$/.test(args[0]))
69
+ return usage();
70
+ }
53
71
  else if (name === "test-one") {
54
72
  if (args.length < 1 || args.length > 2)
55
73
  return usage();
@@ -114,14 +132,72 @@ export async function main(argv, d) {
114
132
  }
115
133
  return test(0);
116
134
  }
117
- if (s.specCheck === null) {
118
- d.out("specs are off");
135
+ const tool = d.specTools[s.specs];
136
+ if (s.specs === "none" || !tool) {
137
+ d.out(`${paint("dim", "-")} ${NO_SPEC_TOOL}`);
138
+ return 0;
139
+ }
140
+ if (name === "specs-check")
141
+ return ended(d.exec(s.specCheck, d.root, tool.env), "The specs check passed.", "The specs check failed.");
142
+ if (name === "specs-list") {
143
+ const specs = tool.list(d.root);
144
+ d.out(`specs: ${s.specs}`);
145
+ if (specs.length === 0)
146
+ d.out(" none yet");
147
+ const width = Math.max(0, ...specs.map((x) => x.name.length));
148
+ for (const x of specs)
149
+ d.out(` ${x.name.padEnd(width)} ${x.path}`);
150
+ return 0;
151
+ }
152
+ const id = args[0];
153
+ const failed = (line) => {
154
+ d.err(`${paint("red", "✗")} ${line}`);
155
+ return 1;
156
+ };
157
+ if (name === "specs-finish") {
158
+ if (!tool.started(d.root, id)) {
159
+ if (tool.finished(d.root, id)) {
160
+ d.out(`${paint("green", "✓")} Ticket ${id}'s spec is already folded into ${tool.foldsInto}.`);
161
+ return 0;
162
+ }
163
+ return failed(`Ticket ${id} has no spec started: run factory specs new ${id} first.`);
164
+ }
165
+ if (tool.finish(d.root, id) !== 0)
166
+ return failed(`Could not fold ticket ${id}'s spec into ${tool.foldsInto}.`);
167
+ d.out(`${paint("green", "✓")} Folded ticket ${id}'s spec into ${tool.foldsInto}.`);
119
168
  return 0;
120
169
  }
121
- return ended(d.exec(s.specCheck, d.root, { DO_NOT_TRACK: "1" }), "The specs check passed.", "The specs check failed.");
170
+ let labels;
171
+ try {
172
+ labels = await d.labels(s, Number(id));
173
+ }
174
+ catch (e) {
175
+ d.err(e instanceof Error ? e.message : String(e));
176
+ return 1;
177
+ }
178
+ if (!tool.runs(d.root))
179
+ return failed(`${tool.name} is not installed: run factory init, which installs it.`);
180
+ const folder = tool.folder(id);
181
+ if (tool.started(d.root, id))
182
+ d.out(`Ticket ${id}'s spec is already started in ${folder}`);
183
+ else {
184
+ if (tool.start(d.root, id) !== 0)
185
+ return failed(`Could not start ticket ${id}'s spec in ${folder}`);
186
+ d.out(`Started ticket ${id}'s spec in ${folder}`);
187
+ }
188
+ const files = tool.files(id, labels.includes("spec"));
189
+ const width = Math.max(...files.map((f) => f.path.length)) + 2;
190
+ const kinds = Math.max(...files.map((f) => f.kind.length));
191
+ d.out(`Write each file from ticket ${id}'s body:`);
192
+ for (const f of files)
193
+ d.out(` ${f.kind.padEnd(kinds)} ${f.path.padEnd(width)}${f.what}`);
194
+ d.out(`Then: ${tool.then}`);
195
+ return 0;
122
196
  }
123
- /** `factory gate`, `factory test-one`, `factory end-to-end`, and
124
- * `factory specs check`, the last as `specs-check`. */
197
+ export const NO_SPEC_TOOL = "No spec tool (specs: none): each ticket holds its own spec.";
198
+ /** `factory gate`, `factory test-one`, `factory end-to-end`,
199
+ * and `factory specs check`, `list`, `new`, and `finish`, as `specs-check`
200
+ * and the rest. */
125
201
  export async function run(argv) {
126
202
  const root = repoRoot();
127
203
  return main(argv, {
@@ -136,5 +212,13 @@ export async function run(argv) {
136
212
  out: (line) => console.log(line),
137
213
  err: (line) => console.error(line),
138
214
  paint: painter(colorOn()),
215
+ specTools: specTools(),
216
+ labels: async (settings, id) => {
217
+ const { tickets } = await openTickets(settings, {
218
+ repository: settings.repository,
219
+ board: null,
220
+ });
221
+ return (await tickets.read(id)).labels;
222
+ },
139
223
  });
140
224
  }
package/dist/config.d.mts CHANGED
@@ -26,7 +26,8 @@ export declare const TRIGGERS: readonly ["own-server", "github-action", "manual"
26
26
  /** How often the scheduled poller may check the board, in minutes: each
27
27
  * divides an hour, so a schedule every N minutes keeps an even beat. */
28
28
  export declare const POLL_MINUTES: readonly [5, 10, 15, 30, 60];
29
- export declare const SPECS: readonly ["none", "openspec"];
29
+ /** The values `specs` takes: none, or a spec tool built. */
30
+ export declare const SPECS: string[];
30
31
  declare const FIELD_DEFAULTS: {
31
32
  readonly session: "Session";
32
33
  readonly "runs-in": "Runs in";
@@ -59,9 +60,12 @@ export type Settings = {
59
60
  * field that holds it, or null for the description. */
60
61
  ticketFields: FieldMapping;
61
62
  };
62
- /** Where pull requests are. */
63
+ /** Where pull requests are, and the pattern a build's branch is named
64
+ * by. The pattern is null only when init reads settings without it, to
65
+ * ask for it. */
63
66
  codeHost: {
64
67
  type: string;
68
+ branchName: string | null;
65
69
  };
66
70
  builds: {
67
71
  /** What notices a card moved to Ready and starts its build. */
@@ -71,7 +75,7 @@ export type Settings = {
71
75
  /** How often the scheduled poller checks the board. */
72
76
  pollMinutes: (typeof POLL_MINUTES)[number];
73
77
  };
74
- specs: (typeof SPECS)[number];
78
+ specs: string;
75
79
  /** The command that checks the specs, or null when `specs` is none. */
76
80
  specCheck: string | null;
77
81
  /** Every command a build runs, each from the repository's root. */
@@ -157,8 +161,6 @@ export type Accessibility = (typeof ACCESSIBILITY)[number];
157
161
  export declare const SITE_AGENT = "factory-ui-reviewer";
158
162
  /** The agent that needs `commands.end-to-end`. */
159
163
  export declare const E2E_AGENT = "factory-e2e-reviewer";
160
- /** The spec check where `specs.type` is openspec and none is written. */
161
- export declare const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
162
164
  /** `commands.relock` where none is written. */
163
165
  export declare const DEFAULT_RELOCK = "npm install";
164
166
  export declare const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
@@ -175,10 +177,18 @@ export declare function repoRoot(from?: string): string;
175
177
  export declare const SETTINGS_FILE = ".claude/factory.yaml";
176
178
  /** A key under `tickets.fields` naming a heading of the repository's own. */
177
179
  export declare const OWN_HEADING: RegExp;
180
+ export declare const BRANCH_PLACEHOLDERS: readonly ["ticket", "user"];
181
+ /** Why a branch name pattern can't be used, in the words the settings
182
+ * check prints after its key, or null when it can. The placeholders are
183
+ * filled before git's rules are applied, so only the pattern's own text
184
+ * can break them. */
185
+ export declare function branchPatternFault(pattern: string): string | null;
178
186
  /** The settings with every default filled in. Throws a SettingsError naming
179
187
  * the key on anything unsound. `exists` says whether a path from the root
180
188
  * exists, for the plugins' files. */
181
- export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built): Settings;
189
+ export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built, { partial }?: {
190
+ partial?: boolean;
191
+ }): Settings;
182
192
  /** One line for each pattern that matches none of `files`: a stale pattern
183
193
  * is how a policy rots. */
184
194
  export declare function patternWarnings(s: Settings, files: string[]): string[];
@@ -235,9 +245,11 @@ export declare function parseChoices(text: string | null, load: YamlLoad): Recor
235
245
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
236
246
  * into the lock. `factoryFile` and `ownFile` say which preset files are
237
247
  * kept back: the factory's own, and the repository's own. */
238
- export declare function resolveFiles(d: Deps, keep?: {
248
+ export declare function resolveFiles(d: Deps, { partial, ...keep }?: {
239
249
  factoryFile?: (path: string) => boolean;
240
250
  ownFile?: (path: string) => boolean;
251
+ /** Read settings init fills in, as `parseSettings` takes it. */
252
+ partial?: boolean;
241
253
  }): Promise<Resolved>;
242
254
  /** Why the lock `d` reads is stale, or null when it is current or `d`
243
255
  * reads none. */
package/dist/config.mjs CHANGED
@@ -5,7 +5,7 @@
5
5
  //
6
6
  // factory config get KEY # e.g. repository, tickets.board
7
7
  // factory plugins [ROLE] # kind, name, role, files or labels
8
- // factory config check # prints nothing when sound
8
+ // factory config check # ✓ The settings are valid., or what is wrong
9
9
  //
10
10
  // A list prints one item per line. A failure names the key and exits 1.
11
11
  import { colorOn, painter, plain } from "./lib/color.mjs";
@@ -15,6 +15,7 @@ import { createRequire } from "node:module";
15
15
  import { dirname, join } from "node:path";
16
16
  import { DEFAULT_CODE_HOST, unsupportedCodeHost } from "./code-host/index.mjs";
17
17
  import { matchesAny } from "./lib/glob.mjs";
18
+ import { listed } from "./lib/listed.mjs";
18
19
  import { DEFAULT_RUNNER, unsupportedRunner } from "./runner/index.mjs";
19
20
  import { FACTORY_FIELDS } from "./ticket-fields.mjs";
20
21
  import { BUILT, unsupported } from "./tool-names.mjs";
@@ -90,7 +91,8 @@ export const TRIGGERS = ["own-server", "github-action", "manual"];
90
91
  /** How often the scheduled poller may check the board, in minutes: each
91
92
  * divides an hour, so a schedule every N minutes keeps an even beat. */
92
93
  export const POLL_MINUTES = [5, 10, 15, 30, 60];
93
- export const SPECS = ["none", "openspec"];
94
+ /** The values `specs` takes: none, or a spec tool built. */
95
+ export const SPECS = ["none", ...Object.keys(BUILT.specs)];
94
96
  const FIELD_DEFAULTS = {
95
97
  session: "Session",
96
98
  "runs-in": "Runs in",
@@ -118,8 +120,6 @@ export const ACCESSIBILITY = [
118
120
  export const SITE_AGENT = "factory-ui-reviewer";
119
121
  /** The agent that needs `commands.end-to-end`. */
120
122
  export const E2E_AGENT = "factory-e2e-reviewer";
121
- /** The spec check where `specs.type` is openspec and none is written. */
122
- export const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
123
123
  /** `commands.relock` where none is written. */
124
124
  export const DEFAULT_RELOCK = "npm install";
125
125
  export const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
@@ -150,7 +150,7 @@ export const SETTINGS_KEYS = {
150
150
  ...Object.keys(FIELD_DEFAULTS),
151
151
  ...FACTORY_FIELDS.map((f) => f.key),
152
152
  ],
153
- "code-host": ["type"],
153
+ "code-host": ["type", "branch-name"],
154
154
  builds: ["trigger", "runner", "poll-minutes"],
155
155
  specs: ["type", "check"],
156
156
  commands: [
@@ -347,13 +347,31 @@ function ticketFieldsOf(o) {
347
347
  }
348
348
  return out;
349
349
  }
350
- /** Each state's columns: a name, a list of names, or none, each left out
351
- * keeping the factory's own name. Only an approved ticket goes to ready,
352
- * so it takes one name. */
353
- function columnNames(v) {
354
- const o = object(v, "tickets.columns");
350
+ /** Each state's columns: a name, a list of names, or none. With a board,
351
+ * every state is written, since the factory's own names describe one
352
+ * board and a state left to them would read any other wrong. Without one,
353
+ * each state keeps its own name, for the comments and `factory status`.
354
+ * `partial` lets a board's block leave states out, each read as no column
355
+ * and listed in `missing`, for init alone, which fills them in. Only an
356
+ * approved ticket goes to ready, so it takes one name. */
357
+ function columnNames(v, board, partial) {
358
+ const states = Object.entries(STATE_KEYS);
359
+ if (board === null)
360
+ return {
361
+ columns: Object.fromEntries(states.map(([k, status]) => [k, DEFAULT_COLUMNS[status]])),
362
+ missing: [],
363
+ };
364
+ const empty = v === undefined || v === null || (isObj(v) && !Object.keys(v).length);
365
+ if (empty && !partial)
366
+ fail("tickets.columns", `is required with tickets.board: run factory init to choose which of board ${board}'s columns shows each state`);
367
+ const o = empty ? {} : object(v, "tickets.columns");
368
+ const missing = states.map(([k]) => k).filter((k) => o[k] === undefined);
369
+ if (missing.length && !partial)
370
+ fail("tickets.columns", missing.length === 1
371
+ ? `${missing[0]} has no column: give it a column, a list of columns, or none, or run factory init to choose it`
372
+ : `${listed(missing)} have no column: give each a column, a list of columns, or none, or run factory init to choose them`);
355
373
  const out = {};
356
- for (const [k, status] of Object.entries(STATE_KEYS)) {
374
+ for (const [k] of states) {
357
375
  const key = `tickets.columns.${k}`;
358
376
  const value = o[k];
359
377
  if (Array.isArray(value)) {
@@ -366,7 +384,7 @@ function columnNames(v) {
366
384
  : fail(`${key}[${i}]`, "must be a name"));
367
385
  }
368
386
  else if (value === undefined)
369
- out[k] = DEFAULT_COLUMNS[status];
387
+ out[k] = null;
370
388
  else if (value === "none")
371
389
  out[k] = null;
372
390
  else if (typeof value === "string" && value.trim())
@@ -374,7 +392,62 @@ function columnNames(v) {
374
392
  else
375
393
  fail(key, "must be a name, a list of names, or none");
376
394
  }
377
- return out;
395
+ return { columns: out, missing };
396
+ }
397
+ export const BRANCH_PLACEHOLDERS = ["ticket", "user"];
398
+ const QUOTED_EXAMPLE = 'branch-name: "{ticket}"';
399
+ /** The pattern a build's branch is named by, or null when it is left out
400
+ * and `partial` lets it be, for init to ask for. */
401
+ function branchNameOf(v, partial) {
402
+ const key = "code-host.branch-name";
403
+ if (v === undefined || v === null) {
404
+ if (partial)
405
+ return null;
406
+ return fail(key, `is required. Run factory init to set it, or add it, such as ${QUOTED_EXAMPLE}`);
407
+ }
408
+ if (isObj(v))
409
+ return fail(key, `is a map, not a pattern. Quote it: ${QUOTED_EXAMPLE}`);
410
+ if (typeof v !== "string")
411
+ return fail(key, `must be a pattern, such as ${QUOTED_EXAMPLE}`);
412
+ const fault = branchPatternFault(v);
413
+ return fault ? fail(key, fault) : v;
414
+ }
415
+ /** Why a branch name pattern can't be used, in the words the settings
416
+ * check prints after its key, or null when it can. The placeholders are
417
+ * filled before git's rules are applied, so only the pattern's own text
418
+ * can break them. */
419
+ export function branchPatternFault(pattern) {
420
+ for (const [, name] of pattern.matchAll(/\{([A-Za-z0-9-]+)\}/g))
421
+ if (!BRANCH_PLACEHOLDERS.includes(name))
422
+ return `{${name}} is not a placeholder. The placeholders are ${listed(BRANCH_PLACEHOLDERS.map((p) => `{${p}}`))}`;
423
+ if (!pattern.includes("{ticket}"))
424
+ return "needs {ticket}, or every build gets the same branch";
425
+ const reason = gitBranchFault(pattern.replaceAll("{ticket}", "1").replaceAll("{user}", "u"));
426
+ return reason && `${pattern} can't be a git branch name: ${reason}`;
427
+ }
428
+ /** The first of git's rules for a branch name (`git check-ref-format
429
+ * --branch`) that `name` breaks, or null. */
430
+ function gitBranchFault(name) {
431
+ if (name.includes(" "))
432
+ return "it has a space";
433
+ // eslint-disable-next-line no-control-regex
434
+ if (/[\x00-\x1f\x7f]/.test(name))
435
+ return "it has a control character";
436
+ for (const s of ["..", "//", "@{", "~", "^", ":", "?", "*", "[", "\\"])
437
+ if (name.includes(s))
438
+ return `it has ${s}`;
439
+ for (const s of ["-", "/"])
440
+ if (name.startsWith(s))
441
+ return `it starts with ${s}`;
442
+ for (const s of ["/", ".lock", "."])
443
+ if (name.endsWith(s))
444
+ return `it ends with ${s}`;
445
+ const parts = name.split("/");
446
+ if (parts.some((p) => p.startsWith(".")))
447
+ return "a part starts with .";
448
+ if (parts.some((p) => p.endsWith(".lock")))
449
+ return "a part ends with .lock";
450
+ return null;
378
451
  }
379
452
  /** A part you can swap, written as a block with a `type` or as one word. */
380
453
  function typed(v, key, extra) {
@@ -482,7 +555,7 @@ function commandsOf(v) {
482
555
  /** The settings with every default filled in. Throws a SettingsError naming
483
556
  * the key on anything unsound. `exists` says whether a path from the root
484
557
  * exists, for the plugins' files. */
485
- export function parseSettings(raw, exists, built = BUILT) {
558
+ export function parseSettings(raw, exists, built = BUILT, { partial = false } = {}) {
486
559
  const written = raw ?? {};
487
560
  // The version comes before any other key, so a file in the older shape is
488
561
  // told so, not told its keys are unknown.
@@ -522,9 +595,11 @@ export function parseSettings(raw, exists, built = BUILT) {
522
595
  board !== "none" &&
523
596
  !(Number.isInteger(board) && board > 0))
524
597
  fail("tickets.board", "must be a whole number above zero, or none");
525
- const codeHost = typed(top["code-host"], "code-host").type ?? DEFAULT_CODE_HOST;
598
+ const codeHostBlock = typed(top["code-host"], "code-host");
599
+ const codeHost = codeHostBlock.type ?? DEFAULT_CODE_HOST;
526
600
  if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
527
601
  throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
602
+ const branchName = branchNameOf(codeHostBlock["branch-name"], partial);
528
603
  const builds = object(top.builds, "builds");
529
604
  const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
530
605
  const minutes = builds["poll-minutes"];
@@ -545,8 +620,8 @@ export function parseSettings(raw, exists, built = BUILT) {
545
620
  const boardFields = Object.fromEntries(Object.entries(rawFields).filter(([k]) => k in FIELD_DEFAULTS));
546
621
  if (Object.keys(boardFields).length && !hasBoard)
547
622
  fail("tickets.fields", "needs tickets.board");
548
- const columns = columnNames(tickets.columns);
549
- if (columns.backlog === null)
623
+ const { columns, missing } = columnNames(tickets.columns, hasBoard ? board : null, partial);
624
+ if (columns.backlog === null && !missing.includes("backlog"))
550
625
  fail("tickets.columns.backlog", "cannot be none: every ticket starts there");
551
626
  const seen = new Map();
552
627
  for (const [key, list] of Object.entries(columns)) {
@@ -560,19 +635,21 @@ export function parseSettings(raw, exists, built = BUILT) {
560
635
  for (const name of list ?? [])
561
636
  seen.set(name, key);
562
637
  }
563
- if (columns.ready === null && trigger !== "manual")
638
+ if (columns.ready === null &&
639
+ trigger !== "manual" &&
640
+ !missing.includes("ready"))
564
641
  fail("tickets.columns.ready", "no column shows ready, so nothing would start a build: name one, or set builds.trigger to manual");
565
642
  if (tickets.fields !== undefined && !isObj(tickets.fields))
566
643
  fail("tickets.fields", "must be a block of settings");
567
644
  const fieldNames = names(boardFields, "tickets.fields", FIELD_DEFAULTS);
568
645
  const ticketFields = ticketFieldsOf(rawFields);
569
646
  const specsBlock = typed(top.specs ?? "none", "specs");
570
- const specs = oneOf(specsBlock.type, "specs", SPECS, "none");
571
- if (specsBlock.check !== undefined && specs !== "openspec")
647
+ const specs = oneOf(specsBlock.type, "specs", ["none", ...Object.keys(built.specs)], "none");
648
+ if (specsBlock.check !== undefined && specs === "none")
572
649
  throw new SettingsError(`${SETTINGS_FILE}: specs.check needs specs.type: openspec`);
573
- const specCheck = specs === "openspec"
574
- ? (command(specsBlock.check, "specs.check") ?? OPENSPEC_CHECK)
575
- : null;
650
+ const specCheck = specs === "none"
651
+ ? null
652
+ : (command(specsBlock.check, "specs.check") ?? built.specs[specs]);
576
653
  const autoMerge = object(top["auto-merge"], "auto-merge");
577
654
  const prReview = top["pr-review"] === undefined
578
655
  ? null
@@ -606,7 +683,7 @@ export function parseSettings(raw, exists, built = BUILT) {
606
683
  fields: fieldNames,
607
684
  ticketFields,
608
685
  },
609
- codeHost: { type: codeHost },
686
+ codeHost: { type: codeHost, branchName },
610
687
  builds: { trigger, runner, pollMinutes },
611
688
  specs,
612
689
  specCheck,
@@ -696,7 +773,7 @@ export function parseChoices(text, load) {
696
773
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
697
774
  * into the lock. `factoryFile` and `ownFile` say which preset files are
698
775
  * kept back: the factory's own, and the repository's own. */
699
- export async function resolveFiles(d, keep = {}) {
776
+ export async function resolveFiles(d, { partial = false, ...keep } = {}) {
700
777
  const load = await yamlOf(d);
701
778
  let ownText;
702
779
  let own;
@@ -758,7 +835,9 @@ export async function resolveFiles(d, keep = {}) {
758
835
  const exists = (path) => d.exists(path) || resolution.files.has(path);
759
836
  let settings;
760
837
  try {
761
- settings = parseSettings(isObj(own) ? resolution.raw : own, exists);
838
+ settings = parseSettings(isObj(own) ? resolution.raw : own, exists, BUILT, {
839
+ partial,
840
+ });
762
841
  }
763
842
  catch (e) {
764
843
  throw e instanceof SettingsError ? fromPreset(e, resolution) : e;
@@ -920,10 +999,10 @@ export const defaultDeps = (root = repoRoot(), env = process.env) => ({
920
999
  });
921
1000
  /** The column each state shows in on the board, null for none. */
922
1001
  export function columnsOf(s) {
923
- const out = { ...DEFAULT_COLUMNS };
924
- for (const [key, status] of Object.entries(STATE_KEYS))
925
- out[status] = s.tickets.columns[key];
926
- return out;
1002
+ return Object.fromEntries(Object.entries(STATE_KEYS).map(([key, status]) => [
1003
+ status,
1004
+ s.tickets.columns[key],
1005
+ ]));
927
1006
  }
928
1007
  /** The board's names for the fields the sync writes, null for none. */
929
1008
  export function fieldNamesOf(s) {
package/dist/doctor.mjs CHANGED
@@ -155,8 +155,7 @@ export async function checks(d) {
155
155
  // line, or the names asked for when none is.
156
156
  const key = anyOf.find((n) => secrets.includes(n)) ?? anyOf.join(" or ");
157
157
  const entry = reads.get(key) ?? { anyOf, fors: [] };
158
- if (!entry.fors.includes(forWhat))
159
- entry.fors.push(forWhat);
158
+ entry.fors.push(forWhat);
160
159
  reads.set(key, entry);
161
160
  };
162
161
  for (const part of PARTS) {
package/dist/explain.mjs CHANGED
@@ -75,7 +75,13 @@ export async function explainLines(s, marks, exists) {
75
75
  block(["tickets", "fields"]);
76
76
  for (const [k, v] of Object.entries(s.tickets.ticketFields))
77
77
  put(["tickets", "fields", k], v ?? "none");
78
- put(["code-host"], s.codeHost.type);
78
+ block(["code-host"]);
79
+ put(["code-host", "type"], s.codeHost.type);
80
+ // Quoted always: YAML reads a pattern that starts with `{` as a map.
81
+ lines.push({
82
+ text: `${pad(1)}branch-name: ${JSON.stringify(s.codeHost.branchName)}`,
83
+ mark: marks.value(["code-host", "branch-name"]),
84
+ });
79
85
  block(["builds"]);
80
86
  put(["builds", "trigger"], s.builds.trigger);
81
87
  put(["builds", "runner"], s.builds.runner);
package/dist/init.d.mts CHANGED
@@ -47,7 +47,26 @@ export type InitDeps = {
47
47
  checks: () => Promise<Check[]>;
48
48
  packageName: string;
49
49
  packageVersion: string;
50
+ /** The branch name a preset in effect supplies to settings that read
51
+ * as `settingsText`, or null for none. */
52
+ presetBranchName: (settingsText: string) => Promise<string | null>;
53
+ /** The spec tool a preset in effect names for settings that read as
54
+ * `settingsText`, \`none\` included, or null when none names one. */
55
+ presetSpecs: (settingsText: string) => Promise<string | null>;
56
+ /** Runs an install from the root; its status and standard error. */
57
+ install: (argv: string[]) => Promise<{
58
+ status: number;
59
+ stderr: string;
60
+ }>;
50
61
  };
62
+ /** The branch name a preset in effect supplies to the settings `text`
63
+ * of the repository at `root`, or null for none. Settings whose presets
64
+ * can't be read get the question: the check that follows says what is
65
+ * wrong with them. */
66
+ export declare const presetBranchNameAt: (root: string) => (text: string) => Promise<string | null>;
67
+ /** The spec tool a preset in effect names, as `presetBranchNameAt` finds
68
+ * a branch name. */
69
+ export declare const presetSpecsAt: (root: string) => (text: string) => Promise<string | null>;
51
70
  /** The repository and code host a remote's address names, or null for one
52
71
  * on a code host the factory does not support. */
53
72
  export declare function parseRemote(url: string, tools?: Registry): {