@davidbyoung/software-factory 0.1.8 → 0.1.10

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 (69) hide show
  1. package/README.md +2 -0
  2. package/dist/agent/claude-code.mjs +15 -21
  3. package/dist/board.d.mts +20 -3
  4. package/dist/board.mjs +124 -38
  5. package/dist/cli.mjs +84 -9
  6. package/dist/code-host/github-setup.mjs +2 -2
  7. package/dist/code-host/github.d.mts +1 -1
  8. package/dist/code-host/github.mjs +29 -2
  9. package/dist/code-host/types.d.mts +16 -1
  10. package/dist/code-host/types.mjs +8 -0
  11. package/dist/columns-suggest.d.mts +25 -6
  12. package/dist/columns-suggest.mjs +119 -29
  13. package/dist/commands.d.mts +5 -2
  14. package/dist/commands.mjs +37 -12
  15. package/dist/config.d.mts +25 -3
  16. package/dist/config.mjs +159 -33
  17. package/dist/doctor.d.mts +6 -1
  18. package/dist/doctor.mjs +78 -18
  19. package/dist/explain.d.mts +5 -0
  20. package/dist/explain.mjs +36 -1
  21. package/dist/init.d.mts +10 -0
  22. package/dist/init.mjs +133 -31
  23. package/dist/lib/color.d.mts +11 -0
  24. package/dist/lib/color.mjs +15 -0
  25. package/dist/lib/gh.d.mts +6 -0
  26. package/dist/lib/gh.mjs +11 -1
  27. package/dist/lib/listed.d.mts +3 -2
  28. package/dist/lib/listed.mjs +5 -4
  29. package/dist/poller.d.mts +1 -1
  30. package/dist/poller.mjs +9 -6
  31. package/dist/pr.mjs +9 -1
  32. package/dist/preset-commands.d.mts +2 -0
  33. package/dist/preset-commands.mjs +18 -12
  34. package/dist/preset.mjs +3 -2
  35. package/dist/setup.d.mts +3 -0
  36. package/dist/site.d.mts +3 -0
  37. package/dist/site.mjs +8 -1
  38. package/dist/status.d.mts +5 -2
  39. package/dist/status.mjs +13 -22
  40. package/dist/sync.d.mts +7 -1
  41. package/dist/sync.mjs +17 -5
  42. package/dist/ticket-fields.d.mts +84 -0
  43. package/dist/ticket-fields.mjs +374 -0
  44. package/dist/ticket.d.mts +3 -0
  45. package/dist/ticket.mjs +35 -8
  46. package/dist/tickets/github-setup.mjs +1 -1
  47. package/dist/tickets/github.mjs +69 -0
  48. package/dist/tickets/index.d.mts +8 -1
  49. package/dist/tickets/index.mjs +67 -7
  50. package/dist/tickets/types.d.mts +27 -1
  51. package/dist/tickets/types.mjs +4 -0
  52. package/dist/tools.d.mts +1 -1
  53. package/docs/builds.md +26 -13
  54. package/docs/cli.md +73 -36
  55. package/docs/configuration.md +264 -59
  56. package/docs/design.md +10 -0
  57. package/docs/developing.md +49 -18
  58. package/docs/existing-repo.md +184 -34
  59. package/docs/github/by-hand.md +13 -1
  60. package/docs/github/setup.md +14 -2
  61. package/docs/presets.md +15 -3
  62. package/docs/quick-start.md +3 -3
  63. package/docs/skills.md +3 -1
  64. package/docs/updating.md +132 -5
  65. package/docs/workflow.md +1 -1
  66. package/package.json +4 -2
  67. package/settings.schema.json +82 -20
  68. package/skills/factory-build/SKILL.md +39 -7
  69. package/skills/factory-deps/SKILL.md +6 -4
package/dist/config.mjs CHANGED
@@ -5,16 +5,19 @@
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
+ import { colorOn, painter, plain } from "./lib/color.mjs";
11
12
  import { execFileSync } from "node:child_process";
12
13
  import { existsSync, readFileSync } from "node:fs";
13
14
  import { createRequire } from "node:module";
14
15
  import { dirname, join } from "node:path";
15
16
  import { DEFAULT_CODE_HOST, unsupportedCodeHost } from "./code-host/index.mjs";
16
17
  import { matchesAny } from "./lib/glob.mjs";
18
+ import { listed } from "./lib/listed.mjs";
17
19
  import { DEFAULT_RUNNER, unsupportedRunner } from "./runner/index.mjs";
20
+ import { FACTORY_FIELDS } from "./ticket-fields.mjs";
18
21
  import { BUILT, unsupported } from "./tool-names.mjs";
19
22
  import { DEFAULT_COLUMNS, STATE_KEYS, sameName, watchOf, } from "./lib/work-status.mjs";
20
23
  export class SettingsError extends Error {
@@ -144,8 +147,11 @@ export const SETTINGS_KEYS = {
144
147
  ],
145
148
  tickets: ["type", "board", "columns", "fields"],
146
149
  "tickets.columns": Object.keys(STATE_KEYS),
147
- "tickets.fields": Object.keys(FIELD_DEFAULTS),
148
- "code-host": ["type"],
150
+ "tickets.fields": [
151
+ ...Object.keys(FIELD_DEFAULTS),
152
+ ...FACTORY_FIELDS.map((f) => f.key),
153
+ ],
154
+ "code-host": ["type", "branch-name"],
149
155
  builds: ["trigger", "runner", "poll-minutes"],
150
156
  specs: ["type", "check"],
151
157
  commands: [
@@ -312,13 +318,61 @@ function names(v, key, defaults) {
312
318
  return [k, value.trim()];
313
319
  }));
314
320
  }
315
- /** Each state's columns: a name, a list of names, or none, each left out
316
- * keeping the factory's own name. Only an approved ticket goes to ready,
317
- * so it takes one name. */
318
- function columnNames(v) {
319
- const o = object(v, "tickets.columns");
321
+ /** A key under `tickets.fields` naming a heading of the repository's own. */
322
+ export const OWN_HEADING = /^[a-z0-9]+(-[a-z0-9]+)*$/;
323
+ /** The ticket-side keys under `tickets.fields`: the four factory fields,
324
+ * each a ticket field's name or none, and any other key a heading of the
325
+ * repository's own. Spec and Acceptance criteria may share a field. */
326
+ function ticketFieldsOf(o) {
327
+ const out = Object.fromEntries(FACTORY_FIELDS.map((f) => [f.key, null]));
328
+ const seen = [];
329
+ for (const [k, value] of Object.entries(o)) {
330
+ if (k in FIELD_DEFAULTS)
331
+ continue;
332
+ const key = `tickets.fields.${k}`;
333
+ if (!FACTORY_FIELDS.some((f) => f.key === k) && !OWN_HEADING.test(k))
334
+ fail(key, "must be a heading in lowercase, with hyphens for spaces");
335
+ if (value === "none") {
336
+ out[k] = null;
337
+ continue;
338
+ }
339
+ if (typeof value !== "string" || !value.trim())
340
+ fail(key, "must be a name, or none");
341
+ const name = value.trim();
342
+ const other = seen.find(([o, n]) => sameName(n, name) &&
343
+ !([o, k].includes("spec") && [o, k].includes("acceptance-criteria")));
344
+ if (other)
345
+ fail(key, `names the same field as ${other[0]}`);
346
+ seen.push([k, name]);
347
+ out[k] = name;
348
+ }
349
+ return out;
350
+ }
351
+ /** Each state's columns: a name, a list of names, or none. With a board,
352
+ * every state is written, since the factory's own names describe one
353
+ * board and a state left to them would read any other wrong. Without one,
354
+ * each state keeps its own name, for the comments and `factory status`.
355
+ * `partial` lets a board's block leave states out, each read as no column
356
+ * and listed in `missing`, for init alone, which fills them in. Only an
357
+ * approved ticket goes to ready, so it takes one name. */
358
+ function columnNames(v, board, partial) {
359
+ const states = Object.entries(STATE_KEYS);
360
+ if (board === null)
361
+ return {
362
+ columns: Object.fromEntries(states.map(([k, status]) => [k, DEFAULT_COLUMNS[status]])),
363
+ missing: [],
364
+ };
365
+ const empty = v === undefined || v === null || (isObj(v) && !Object.keys(v).length);
366
+ if (empty && !partial)
367
+ fail("tickets.columns", `is required with tickets.board: run factory init to choose which of board ${board}'s columns shows each state`);
368
+ const o = empty ? {} : object(v, "tickets.columns");
369
+ const missing = states.map(([k]) => k).filter((k) => o[k] === undefined);
370
+ if (missing.length && !partial)
371
+ fail("tickets.columns", missing.length === 1
372
+ ? `${missing[0]} has no column: give it a column, a list of columns, or none, or run factory init to choose it`
373
+ : `${listed(missing)} have no column: give each a column, a list of columns, or none, or run factory init to choose them`);
320
374
  const out = {};
321
- for (const [k, status] of Object.entries(STATE_KEYS)) {
375
+ for (const [k] of states) {
322
376
  const key = `tickets.columns.${k}`;
323
377
  const value = o[k];
324
378
  if (Array.isArray(value)) {
@@ -331,7 +385,7 @@ function columnNames(v) {
331
385
  : fail(`${key}[${i}]`, "must be a name"));
332
386
  }
333
387
  else if (value === undefined)
334
- out[k] = DEFAULT_COLUMNS[status];
388
+ out[k] = null;
335
389
  else if (value === "none")
336
390
  out[k] = null;
337
391
  else if (typeof value === "string" && value.trim())
@@ -339,7 +393,62 @@ function columnNames(v) {
339
393
  else
340
394
  fail(key, "must be a name, a list of names, or none");
341
395
  }
342
- return out;
396
+ return { columns: out, missing };
397
+ }
398
+ export const BRANCH_PLACEHOLDERS = ["ticket", "user"];
399
+ const QUOTED_EXAMPLE = 'branch-name: "{ticket}"';
400
+ /** The pattern a build's branch is named by, or null when it is left out
401
+ * and `partial` lets it be, for init to ask for. */
402
+ function branchNameOf(v, partial) {
403
+ const key = "code-host.branch-name";
404
+ if (v === undefined || v === null) {
405
+ if (partial)
406
+ return null;
407
+ return fail(key, `is required. Run factory init to set it, or add it, such as ${QUOTED_EXAMPLE}`);
408
+ }
409
+ if (isObj(v))
410
+ return fail(key, `is a map, not a pattern. Quote it: ${QUOTED_EXAMPLE}`);
411
+ if (typeof v !== "string")
412
+ return fail(key, `must be a pattern, such as ${QUOTED_EXAMPLE}`);
413
+ const fault = branchPatternFault(v);
414
+ return fault ? fail(key, fault) : v;
415
+ }
416
+ /** Why a branch name pattern can't be used, in the words the settings
417
+ * check prints after its key, or null when it can. The placeholders are
418
+ * filled before git's rules are applied, so only the pattern's own text
419
+ * can break them. */
420
+ export function branchPatternFault(pattern) {
421
+ for (const [, name] of pattern.matchAll(/\{([A-Za-z0-9-]+)\}/g))
422
+ if (!BRANCH_PLACEHOLDERS.includes(name))
423
+ return `{${name}} is not a placeholder. The placeholders are ${listed(BRANCH_PLACEHOLDERS.map((p) => `{${p}}`))}`;
424
+ if (!pattern.includes("{ticket}"))
425
+ return "needs {ticket}, or every build gets the same branch";
426
+ const reason = gitBranchFault(pattern.replaceAll("{ticket}", "1").replaceAll("{user}", "u"));
427
+ return reason && `${pattern} can't be a git branch name: ${reason}`;
428
+ }
429
+ /** The first of git's rules for a branch name (`git check-ref-format
430
+ * --branch`) that `name` breaks, or null. */
431
+ function gitBranchFault(name) {
432
+ if (name.includes(" "))
433
+ return "it has a space";
434
+ // eslint-disable-next-line no-control-regex
435
+ if (/[\x00-\x1f\x7f]/.test(name))
436
+ return "it has a control character";
437
+ for (const s of ["..", "//", "@{", "~", "^", ":", "?", "*", "[", "\\"])
438
+ if (name.includes(s))
439
+ return `it has ${s}`;
440
+ for (const s of ["-", "/"])
441
+ if (name.startsWith(s))
442
+ return `it starts with ${s}`;
443
+ for (const s of ["/", ".lock", "."])
444
+ if (name.endsWith(s))
445
+ return `it ends with ${s}`;
446
+ const parts = name.split("/");
447
+ if (parts.some((p) => p.startsWith(".")))
448
+ return "a part starts with .";
449
+ if (parts.some((p) => p.endsWith(".lock")))
450
+ return "a part ends with .lock";
451
+ return null;
343
452
  }
344
453
  /** A part you can swap, written as a block with a `type` or as one word. */
345
454
  function typed(v, key, extra) {
@@ -447,7 +556,7 @@ function commandsOf(v) {
447
556
  /** The settings with every default filled in. Throws a SettingsError naming
448
557
  * the key on anything unsound. `exists` says whether a path from the root
449
558
  * exists, for the plugins' files. */
450
- export function parseSettings(raw, exists, built = BUILT) {
559
+ export function parseSettings(raw, exists, built = BUILT, { partial = false } = {}) {
451
560
  const written = raw ?? {};
452
561
  // The version comes before any other key, so a file in the older shape is
453
562
  // told so, not told its keys are unknown.
@@ -487,9 +596,11 @@ export function parseSettings(raw, exists, built = BUILT) {
487
596
  board !== "none" &&
488
597
  !(Number.isInteger(board) && board > 0))
489
598
  fail("tickets.board", "must be a whole number above zero, or none");
490
- const codeHost = typed(top["code-host"], "code-host").type ?? DEFAULT_CODE_HOST;
599
+ const codeHostBlock = typed(top["code-host"], "code-host");
600
+ const codeHost = codeHostBlock.type ?? DEFAULT_CODE_HOST;
491
601
  if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
492
602
  throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
603
+ const branchName = branchNameOf(codeHostBlock["branch-name"], partial);
493
604
  const builds = object(top.builds, "builds");
494
605
  const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
495
606
  const minutes = builds["poll-minutes"];
@@ -506,10 +617,12 @@ export function parseSettings(raw, exists, built = BUILT) {
506
617
  const hasBoard = typeof board === "number";
507
618
  if (tickets.columns !== undefined && !hasBoard)
508
619
  fail("tickets.columns", "needs tickets.board");
509
- if (tickets.fields !== undefined && !hasBoard)
620
+ const rawFields = isObj(tickets.fields) ? tickets.fields : {};
621
+ const boardFields = Object.fromEntries(Object.entries(rawFields).filter(([k]) => k in FIELD_DEFAULTS));
622
+ if (Object.keys(boardFields).length && !hasBoard)
510
623
  fail("tickets.fields", "needs tickets.board");
511
- const columns = columnNames(tickets.columns);
512
- if (columns.backlog === null)
624
+ const { columns, missing } = columnNames(tickets.columns, hasBoard ? board : null, partial);
625
+ if (columns.backlog === null && !missing.includes("backlog"))
513
626
  fail("tickets.columns.backlog", "cannot be none: every ticket starts there");
514
627
  const seen = new Map();
515
628
  for (const [key, list] of Object.entries(columns)) {
@@ -523,9 +636,14 @@ export function parseSettings(raw, exists, built = BUILT) {
523
636
  for (const name of list ?? [])
524
637
  seen.set(name, key);
525
638
  }
526
- if (columns.ready === null && trigger !== "manual")
639
+ if (columns.ready === null &&
640
+ trigger !== "manual" &&
641
+ !missing.includes("ready"))
527
642
  fail("tickets.columns.ready", "no column shows ready, so nothing would start a build: name one, or set builds.trigger to manual");
528
- const fieldNames = names(tickets.fields, "tickets.fields", FIELD_DEFAULTS);
643
+ if (tickets.fields !== undefined && !isObj(tickets.fields))
644
+ fail("tickets.fields", "must be a block of settings");
645
+ const fieldNames = names(boardFields, "tickets.fields", FIELD_DEFAULTS);
646
+ const ticketFields = ticketFieldsOf(rawFields);
529
647
  const specsBlock = typed(top.specs ?? "none", "specs");
530
648
  const specs = oneOf(specsBlock.type, "specs", SPECS, "none");
531
649
  if (specsBlock.check !== undefined && specs !== "openspec")
@@ -564,8 +682,9 @@ export function parseSettings(raw, exists, built = BUILT) {
564
682
  board: typeof board === "number" ? board : null,
565
683
  columns,
566
684
  fields: fieldNames,
685
+ ticketFields,
567
686
  },
568
- codeHost: { type: codeHost },
687
+ codeHost: { type: codeHost, branchName },
569
688
  builds: { trigger, runner, pollMinutes },
570
689
  specs,
571
690
  specCheck,
@@ -655,7 +774,7 @@ export function parseChoices(text, load) {
655
774
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
656
775
  * into the lock. `factoryFile` and `ownFile` say which preset files are
657
776
  * kept back: the factory's own, and the repository's own. */
658
- export async function resolveFiles(d, keep = {}) {
777
+ export async function resolveFiles(d, { partial = false, ...keep } = {}) {
659
778
  const load = await yamlOf(d);
660
779
  let ownText;
661
780
  let own;
@@ -717,7 +836,9 @@ export async function resolveFiles(d, keep = {}) {
717
836
  const exists = (path) => d.exists(path) || resolution.files.has(path);
718
837
  let settings;
719
838
  try {
720
- settings = parseSettings(isObj(own) ? resolution.raw : own, exists);
839
+ settings = parseSettings(isObj(own) ? resolution.raw : own, exists, BUILT, {
840
+ partial,
841
+ });
721
842
  }
722
843
  catch (e) {
723
844
  throw e instanceof SettingsError ? fromPreset(e, resolution) : e;
@@ -875,13 +996,14 @@ export const defaultDeps = (root = repoRoot(), env = process.env) => ({
875
996
  loadYaml: async () => (await import("js-yaml")).load,
876
997
  out: (line) => console.log(line),
877
998
  err: (line) => console.error(line),
999
+ paint: painter(colorOn()),
878
1000
  });
879
1001
  /** The column each state shows in on the board, null for none. */
880
1002
  export function columnsOf(s) {
881
- const out = { ...DEFAULT_COLUMNS };
882
- for (const [key, status] of Object.entries(STATE_KEYS))
883
- out[status] = s.tickets.columns[key];
884
- return out;
1003
+ return Object.fromEntries(Object.entries(STATE_KEYS).map(([key, status]) => [
1004
+ status,
1005
+ s.tickets.columns[key],
1006
+ ]));
885
1007
  }
886
1008
  /** The board's names for the fields the sync writes, null for none. */
887
1009
  export function fieldNamesOf(s) {
@@ -1005,17 +1127,21 @@ export async function main(argv, d) {
1005
1127
  d.err(`warning: ${w}`);
1006
1128
  if (s.site && !s.plugins.some((p) => p.role === "mockups"))
1007
1129
  if (!d.exists(DESIGN_SKILL))
1008
- d.err(`warning: ${DESIGN_SKILL} is missing: run \`npx --no-install factory sync\` to give the site its design skill`);
1130
+ d.err(`warning: ${DESIGN_SKILL} is missing: run \`factory sync\` to give the site its design skill`);
1131
+ d.out(`${(d.paint ?? plain)("green", "✓")} The settings are valid.`);
1009
1132
  return 0;
1010
1133
  }
1011
1134
  if (command === "explain") {
1012
- if (lockText !== null) {
1013
- for (const line of lockSettingsLines(lockText))
1014
- d.out(line);
1015
- return 0;
1016
- }
1017
- const { explainLines, markerOf } = await import("./explain.mjs");
1018
- for (const line of await explainLines(s, markerOf(resolved.resolution), resolved.exists))
1135
+ const { explainLines, markerOf, paintExplainLines } = await import("./explain.mjs");
1136
+ const lines = lockText !== null
1137
+ ? lockSettingsLines(lockText)
1138
+ : await explainLines(s, markerOf(resolved.resolution), resolved.exists);
1139
+ // Printed only: the lock holds the settings, not how to read them.
1140
+ const header = [
1141
+ '# The settings in effect. "# default" marks the factory\'s own value,',
1142
+ "# a preset's name marks that preset's, and an unmarked line is yours.",
1143
+ ];
1144
+ for (const line of paintExplainLines([...header, ...lines], d.paint ?? plain))
1019
1145
  d.out(line);
1020
1146
  return 0;
1021
1147
  }
package/dist/doctor.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type Settings } from "./config.mts";
2
+ import { type Paint } from "./lib/color.mts";
2
3
  import type { Check } from "./setup.mts";
3
4
  import { type Registry } from "./tools.mts";
4
5
  export type { Check } from "./setup.mts";
@@ -19,6 +20,7 @@ export type DoctorDeps = {
19
20
  hasCommand: (name: string) => boolean;
20
21
  tools: Registry;
21
22
  out: (line: string) => void;
23
+ paint?: Paint;
22
24
  };
23
25
  export declare function checks(d: DoctorDeps): Promise<Check[]>;
24
26
  /** Whether Dependabot's settings name the registry at `url` under their
@@ -26,7 +28,10 @@ export declare function checks(d: DoctorDeps): Promise<Check[]>;
26
28
  export declare function usesRegistry(settings: string, url: string): boolean;
27
29
  /** One check as a line: a tick, a cross with what to do, or a dash for a
28
30
  * part that is off. */
29
- export declare function line(c: Check): string;
31
+ export declare function line(c: Check, paint?: Paint): string;
32
+ /** The checks under their headings, each group apart from the next, the
33
+ * whole indented by `indent` spaces. */
34
+ export declare function printChecks(found: Check[], paint?: Paint, indent?: number): string[];
30
35
  export declare function main(_argv: string[], d: DoctorDeps): Promise<number>;
31
36
  /** The checks, run in the repository this command runs in. */
32
37
  export declare function doctorDeps(root?: string): DoctorDeps;
package/dist/doctor.mjs CHANGED
@@ -4,6 +4,7 @@
4
4
  //
5
5
  // A stored secret cannot be read back, so a secret is checked only for
6
6
  // being set.
7
+ import { listed } from "./lib/listed.mjs";
7
8
  import { existsSync, readFileSync } from "node:fs";
8
9
  import { load } from "js-yaml";
9
10
  import { bareRegistry, npmrcAt, privateRegistries } from "./npmrc.mjs";
@@ -11,12 +12,16 @@ import { join } from "node:path";
11
12
  import { defaultDeps, filesDeps, repoRoot, resolveFiles, staleOf, } from "./config.mjs";
12
13
  import { presetChecks } from "./preset-commands.mjs";
13
14
  import { hasCommand } from "./lib/has-command.mjs";
15
+ import { colorOn, painter, plain } from "./lib/color.mjs";
14
16
  import { neededSecrets, PART_TEXT, PARTS, partsOn, } from "./parts.mjs";
15
17
  import { branchDeps, CANNOT_TELL, needDefaultBranch, NoDefaultBranch, } from "./lib/default-branch.mjs";
16
18
  import { differences, LOCK, PACKAGE, plan } from "./sync.mjs";
17
19
  import { inUse, secretSteps, TOOLS } from "./tools.mjs";
18
- const SYNC = "Run npx --no-install factory sync";
19
- const INIT = "Run npx --no-install factory init";
20
+ import { fieldChecks } from "./ticket-fields.mjs";
21
+ const SYNC = "Run factory sync";
22
+ const INIT = "Run factory init";
23
+ const SETTINGS = "Settings and files";
24
+ const OFF = "Parts that are off";
20
25
  const message = (e) => (e instanceof Error ? e.message : String(e));
21
26
  /** -1, 0, or 1 as version `a` is older than, the same as, or newer than `b`. */
22
27
  function compareVersions(a, b) {
@@ -39,7 +44,14 @@ export async function checks(d) {
39
44
  s = await d.settings();
40
45
  }
41
46
  catch (e) {
42
- return [{ state: "fail", text: "The settings are valid", fix: message(e) }];
47
+ return [
48
+ {
49
+ state: "fail",
50
+ text: "The settings are valid",
51
+ fix: message(e),
52
+ group: SETTINGS,
53
+ },
54
+ ];
43
55
  }
44
56
  out.push({ state: "pass", text: "The settings are valid" });
45
57
  let differ = null;
@@ -76,6 +88,9 @@ export async function checks(d) {
76
88
  fix: compareVersions(installed, locked) < 0 ? "Run npm ci" : SYNC,
77
89
  });
78
90
  out.push(...((await d.lockChecks?.()) ?? []));
91
+ for (const c of out)
92
+ c.group = SETTINGS;
93
+ const under = (group, found) => found.map((c) => ({ ...c, group }));
79
94
  const chosen = {
80
95
  codeHost: s.codeHost.type,
81
96
  tickets: s.tickets.type,
@@ -97,8 +112,7 @@ export async function checks(d) {
97
112
  opened,
98
113
  });
99
114
  const [agent, codeHost, tickets, runner] = inUse(d.tools, chosen);
100
- out.push(...((await codeHost.setup.checks?.({ ...context([]), secrets: null })) ??
101
- []));
115
+ out.push(...under(codeHost.label, (await codeHost.setup.checks?.({ ...context([]), secrets: null })) ?? []));
102
116
  // A secret the organization shares with the repository counts as set.
103
117
  const isOrganization = await opened.codeHost
104
118
  .ownerIsOrganization()
@@ -116,6 +130,7 @@ export async function checks(d) {
116
130
  state: "fail",
117
131
  text: "The secrets can be listed",
118
132
  fix: message(e),
133
+ group: runner.label,
119
134
  });
120
135
  }
121
136
  const secrets = own === null ? null : [...own, ...shared];
@@ -133,16 +148,26 @@ export async function checks(d) {
133
148
  fix: INIT,
134
149
  };
135
150
  };
151
+ // One line per secret, naming every part that reads it.
152
+ const reads = new Map();
153
+ const reading = (anyOf, forWhat) => {
154
+ // Parts can accept different names for one secret: the one set is the
155
+ // line, or the names asked for when none is.
156
+ const key = anyOf.find((n) => secrets.includes(n)) ?? anyOf.join(" or ");
157
+ const entry = reads.get(key) ?? { anyOf, fors: [] };
158
+ entry.fors.push(forWhat);
159
+ reads.set(key, entry);
160
+ };
136
161
  for (const part of PARTS) {
137
162
  if (!on.has(part)) {
138
- out.push({ state: "off", text: `${PART_TEXT[part].name}: off` });
163
+ out.push({ state: "off", text: PART_TEXT[part].name, group: OFF });
139
164
  continue;
140
165
  }
141
166
  if (secrets === null)
142
167
  continue;
143
168
  const forPart = PART_TEXT[part].name.replace(/^./, (c) => c.toLowerCase());
144
169
  for (const need of needed.filter((n) => n.part === part))
145
- out.push(secretLine(need.anyOf, forPart));
170
+ reading(need.anyOf, forPart);
146
171
  }
147
172
  // A gate is no part and fails no check: it is shown as off, since a
148
173
  // build cannot finish without one.
@@ -150,14 +175,30 @@ export async function checks(d) {
150
175
  out.push({
151
176
  state: "off",
152
177
  text: "commands.gate is not set: a build cannot finish until it is",
178
+ group: SETTINGS,
153
179
  });
154
180
  if (secrets !== null)
155
181
  for (const need of needed.filter((n) => n.part === null))
156
- out.push(secretLine(need.anyOf, need.tool));
157
- out.push(...(await npmChecks(d.root, opened, isOrganization, own, shared)));
182
+ reading(need.anyOf, need.tool);
183
+ for (const { anyOf, fors } of reads.values())
184
+ out.push({ ...secretLine(anyOf, listed(fors)), group: runner.label });
185
+ out.push(...under(runner.label, await npmChecks(d.root, opened, isOrganization, own, shared)));
158
186
  for (const tool of [tickets, runner, agent])
159
- out.push(...((await tool.setup.checks?.({ ...context(on), secrets })) ?? []));
160
- return out;
187
+ out.push(...under(tool.label, (await tool.setup.checks?.({ ...context(on), secrets })) ?? []));
188
+ out.push(...under(tickets.label, await fieldChecks(opened.tickets, s.tickets.ticketFields, s.repository, tickets.label)));
189
+ const order = [
190
+ SETTINGS,
191
+ codeHost.label,
192
+ runner.label,
193
+ tickets.label,
194
+ agent.label,
195
+ OFF,
196
+ ];
197
+ const rank = (c) => order.indexOf(c.group ?? SETTINGS);
198
+ return out
199
+ .map((c, i) => [c, i])
200
+ .sort(([a, i], [b, j]) => rank(a) - rank(b) || i - j)
201
+ .map(([c]) => c);
161
202
  }
162
203
  const DEPENDABOT = ".github/dependabot.yml";
163
204
  const FOR_NPM = "for installing what .npmrc names";
@@ -275,21 +316,39 @@ export function usesRegistry(settings, url) {
275
316
  }
276
317
  /** One check as a line: a tick, a cross with what to do, or a dash for a
277
318
  * part that is off. */
278
- export function line(c) {
319
+ export function line(c, paint = plain) {
279
320
  if (c.state === "off")
280
- return `- ${c.text}`;
321
+ return `${paint("dim", "-")} ${c.text}`;
281
322
  if (c.state === "unknown")
282
- return `? ${c.text}`;
323
+ return `${paint("yellow", "?")} ${c.text}`;
283
324
  if (c.state === "pass")
284
- return `✓ ${c.text}`;
325
+ return `${paint("green", "✓")} ${c.text}`;
285
326
  const fix = c.fix ?? "";
286
327
  // An instruction follows as its own sentence; a reason, after a colon.
287
- return `✗ ${c.text}${!fix ? "" : /^Run /.test(fix) ? `. ${fix}` : `: ${fix}`}`;
328
+ return `${paint("red", "✗")} ${c.text}${!fix ? "" : /^Run /.test(fix) ? `. ${fix}` : `: ${fix}`}`;
329
+ }
330
+ /** The checks under their headings, each group apart from the next, the
331
+ * whole indented by `indent` spaces. */
332
+ export function printChecks(found, paint = plain, indent = 0) {
333
+ const at = " ".repeat(indent);
334
+ const out = [];
335
+ let heading;
336
+ for (const c of found) {
337
+ if (c.group !== heading || out.length === 0) {
338
+ if (out.length)
339
+ out.push("");
340
+ heading = c.group;
341
+ if (heading)
342
+ out.push(`${at}${heading}`);
343
+ }
344
+ out.push(`${at}${heading ? " " : ""}${line(c, paint)}`);
345
+ }
346
+ return out;
288
347
  }
289
348
  export async function main(_argv, d) {
290
349
  const found = await checks(d);
291
- for (const c of found)
292
- d.out(line(c));
350
+ for (const l of printChecks(found, d.paint))
351
+ d.out(l);
293
352
  return found.some((c) => c.state === "fail") ? 1 : 0;
294
353
  }
295
354
  /** The checks, run in the repository this command runs in. */
@@ -315,6 +374,7 @@ export function doctorDeps(root = repoRoot()) {
315
374
  hasCommand,
316
375
  tools: TOOLS,
317
376
  out: (l) => console.log(l),
377
+ paint: painter(colorOn()),
318
378
  };
319
379
  }
320
380
  export async function run(argv) {
@@ -1,5 +1,6 @@
1
1
  import { type Settings } from "./config.mts";
2
2
  import { type Resolution } from "./preset.mts";
3
+ import type { Paint } from "./lib/color.mts";
3
4
  /** The mark of the value at `path`, or of one item of the list there:
4
5
  * `item` is the item for a list of values and the plugin's name for a
5
6
  * list of plugins. */
@@ -13,3 +14,7 @@ export declare function markerOf(r: Resolution): Marker;
13
14
  /** `exists` says whether a path from the root exists, for the plugins the
14
15
  * factory uses where the settings name none. */
15
16
  export declare function explainLines(s: Settings, marks: Marker, exists: (path: string) => boolean): Promise<string[]>;
17
+ /** The lines as `config explain` prints them to a terminal: a default's
18
+ * whole line dim, a comment line dim, and any other mark alone dim. It
19
+ * works on the text alone, since the lock keeps only that. */
20
+ export declare function paintExplainLines(lines: string[], paint: Paint): string[];
package/dist/explain.mjs CHANGED
@@ -71,7 +71,17 @@ export async function explainLines(s, marks, exists) {
71
71
  for (const [k, v] of Object.entries(s.tickets.fields))
72
72
  put(["tickets", "fields", k], v ?? "none");
73
73
  }
74
- put(["code-host"], s.codeHost.type);
74
+ if (s.tickets.board === null)
75
+ block(["tickets", "fields"]);
76
+ for (const [k, v] of Object.entries(s.tickets.ticketFields))
77
+ put(["tickets", "fields", k], v ?? "none");
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
+ });
75
85
  block(["builds"]);
76
86
  put(["builds", "trigger"], s.builds.trigger);
77
87
  put(["builds", "runner"], s.builds.runner);
@@ -187,3 +197,28 @@ export async function explainLines(s, marks, exists) {
187
197
  const at = Math.max(0, ...marked.map((l) => l.text.length)) + 2;
188
198
  return lines.map((l) => l.mark !== null ? `${l.text.padEnd(at)}# ${l.mark}` : l.text);
189
199
  }
200
+ /** The lines as `config explain` prints them to a terminal: a default's
201
+ * whole line dim, a comment line dim, and any other mark alone dim. It
202
+ * works on the text alone, since the lock keeps only that. */
203
+ export function paintExplainLines(lines, paint) {
204
+ const comment = (l) => l.trimStart().startsWith("#");
205
+ // Every mark starts at one column, two spaces past the longest marked
206
+ // line. A quoted value can hold " # " too, but rarely at that column.
207
+ const counts = new Map();
208
+ for (const l of lines.filter((l) => !comment(l)))
209
+ for (const m of l.matchAll(/ {2}# /g)) {
210
+ const at = m.index + 2;
211
+ counts.set(at, (counts.get(at) ?? 0) + 1);
212
+ }
213
+ const most = Math.max(0, ...counts.values());
214
+ const at = Math.max(-1, ...[...counts].filter(([, n]) => n === most).map(([c]) => c));
215
+ return lines.map((l) => {
216
+ if (comment(l))
217
+ return paint("dim", l);
218
+ if (at < 0 || !l.startsWith(" # ", at - 2))
219
+ return l;
220
+ return l.slice(at) === "# default"
221
+ ? paint("dim", l)
222
+ : l.slice(0, at) + paint("dim", l.slice(at));
223
+ });
224
+ }
package/dist/init.d.mts CHANGED
@@ -1,4 +1,5 @@
1
1
  import { type Registry } from "./tools.mts";
2
+ import { type Paint } from "./lib/color.mts";
2
3
  import { type Check } from "./setup.mts";
3
4
  /** The questions init asks. Each is answered at the terminal, and in tests
4
5
  * from a script. */
@@ -28,6 +29,7 @@ export type InitDeps = {
28
29
  /** The `origin` remote's address, or null without one. */
29
30
  remote: () => string | null;
30
31
  tools: Registry;
32
+ paint?: Paint;
31
33
  sync: () => Promise<number>;
32
34
  /** The files a sync with these settings would write or delete. `host`
33
35
  * asks the code host for the default branch, where the checkout does not
@@ -45,7 +47,15 @@ export type InitDeps = {
45
47
  checks: () => Promise<Check[]>;
46
48
  packageName: string;
47
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>;
48
53
  };
54
+ /** The branch name a preset in effect supplies to the settings `text`
55
+ * of the repository at `root`, or null for none. Settings whose presets
56
+ * can't be read get the question: the check that follows says what is
57
+ * wrong with them. */
58
+ export declare const presetBranchNameAt: (root: string) => (text: string) => Promise<string | null>;
49
59
  /** The repository and code host a remote's address names, or null for one
50
60
  * on a code host the factory does not support. */
51
61
  export declare function parseRemote(url: string, tools?: Registry): {