@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.
- package/README.md +2 -0
- package/dist/agent/claude-code.mjs +15 -21
- package/dist/board.d.mts +20 -3
- package/dist/board.mjs +124 -38
- package/dist/cli.mjs +84 -9
- package/dist/code-host/github-setup.mjs +2 -2
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +29 -2
- package/dist/code-host/types.d.mts +16 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -6
- package/dist/columns-suggest.mjs +119 -29
- package/dist/commands.d.mts +5 -2
- package/dist/commands.mjs +37 -12
- package/dist/config.d.mts +25 -3
- package/dist/config.mjs +159 -33
- package/dist/doctor.d.mts +6 -1
- package/dist/doctor.mjs +78 -18
- package/dist/explain.d.mts +5 -0
- package/dist/explain.mjs +36 -1
- package/dist/init.d.mts +10 -0
- package/dist/init.mjs +133 -31
- package/dist/lib/color.d.mts +11 -0
- package/dist/lib/color.mjs +15 -0
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.mjs +9 -1
- package/dist/preset-commands.d.mts +2 -0
- package/dist/preset-commands.mjs +18 -12
- package/dist/preset.mjs +3 -2
- package/dist/setup.d.mts +3 -0
- package/dist/site.d.mts +3 -0
- package/dist/site.mjs +8 -1
- package/dist/status.d.mts +5 -2
- package/dist/status.mjs +13 -22
- package/dist/sync.d.mts +7 -1
- package/dist/sync.mjs +17 -5
- package/dist/ticket-fields.d.mts +84 -0
- package/dist/ticket-fields.mjs +374 -0
- package/dist/ticket.d.mts +3 -0
- package/dist/ticket.mjs +35 -8
- package/dist/tickets/github-setup.mjs +1 -1
- package/dist/tickets/github.mjs +69 -0
- package/dist/tickets/index.d.mts +8 -1
- package/dist/tickets/index.mjs +67 -7
- package/dist/tickets/types.d.mts +27 -1
- package/dist/tickets/types.mjs +4 -0
- package/dist/tools.d.mts +1 -1
- package/docs/builds.md +26 -13
- package/docs/cli.md +73 -36
- package/docs/configuration.md +264 -59
- package/docs/design.md +10 -0
- package/docs/developing.md +49 -18
- package/docs/existing-repo.md +184 -34
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +14 -2
- package/docs/presets.md +15 -3
- package/docs/quick-start.md +3 -3
- package/docs/skills.md +3 -1
- package/docs/updating.md +132 -5
- package/docs/workflow.md +1 -1
- package/package.json +4 -2
- package/settings.schema.json +82 -20
- package/skills/factory-build/SKILL.md +39 -7
- 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 #
|
|
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":
|
|
148
|
-
|
|
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
|
-
/**
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
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
|
|
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] =
|
|
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
|
|
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
|
-
|
|
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 &&
|
|
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
|
-
|
|
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
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
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 \`
|
|
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
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
const
|
|
1018
|
-
|
|
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
|
-
|
|
19
|
-
const
|
|
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 [
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
157
|
-
|
|
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
|
-
|
|
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
|
|
321
|
+
return `${paint("dim", "-")} ${c.text}`;
|
|
281
322
|
if (c.state === "unknown")
|
|
282
|
-
return
|
|
323
|
+
return `${paint("yellow", "?")} ${c.text}`;
|
|
283
324
|
if (c.state === "pass")
|
|
284
|
-
return
|
|
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
|
|
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
|
|
292
|
-
d.out(
|
|
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) {
|
package/dist/explain.d.mts
CHANGED
|
@@ -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
|
-
|
|
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): {
|