@davidbyoung/software-factory 0.1.9 → 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/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";
@@ -150,7 +151,7 @@ export const SETTINGS_KEYS = {
150
151
  ...Object.keys(FIELD_DEFAULTS),
151
152
  ...FACTORY_FIELDS.map((f) => f.key),
152
153
  ],
153
- "code-host": ["type"],
154
+ "code-host": ["type", "branch-name"],
154
155
  builds: ["trigger", "runner", "poll-minutes"],
155
156
  specs: ["type", "check"],
156
157
  commands: [
@@ -347,13 +348,31 @@ function ticketFieldsOf(o) {
347
348
  }
348
349
  return out;
349
350
  }
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");
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`);
355
374
  const out = {};
356
- for (const [k, status] of Object.entries(STATE_KEYS)) {
375
+ for (const [k] of states) {
357
376
  const key = `tickets.columns.${k}`;
358
377
  const value = o[k];
359
378
  if (Array.isArray(value)) {
@@ -366,7 +385,7 @@ function columnNames(v) {
366
385
  : fail(`${key}[${i}]`, "must be a name"));
367
386
  }
368
387
  else if (value === undefined)
369
- out[k] = DEFAULT_COLUMNS[status];
388
+ out[k] = null;
370
389
  else if (value === "none")
371
390
  out[k] = null;
372
391
  else if (typeof value === "string" && value.trim())
@@ -374,7 +393,62 @@ function columnNames(v) {
374
393
  else
375
394
  fail(key, "must be a name, a list of names, or none");
376
395
  }
377
- 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;
378
452
  }
379
453
  /** A part you can swap, written as a block with a `type` or as one word. */
380
454
  function typed(v, key, extra) {
@@ -482,7 +556,7 @@ function commandsOf(v) {
482
556
  /** The settings with every default filled in. Throws a SettingsError naming
483
557
  * the key on anything unsound. `exists` says whether a path from the root
484
558
  * exists, for the plugins' files. */
485
- export function parseSettings(raw, exists, built = BUILT) {
559
+ export function parseSettings(raw, exists, built = BUILT, { partial = false } = {}) {
486
560
  const written = raw ?? {};
487
561
  // The version comes before any other key, so a file in the older shape is
488
562
  // told so, not told its keys are unknown.
@@ -522,9 +596,11 @@ export function parseSettings(raw, exists, built = BUILT) {
522
596
  board !== "none" &&
523
597
  !(Number.isInteger(board) && board > 0))
524
598
  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;
599
+ const codeHostBlock = typed(top["code-host"], "code-host");
600
+ const codeHost = codeHostBlock.type ?? DEFAULT_CODE_HOST;
526
601
  if (typeof codeHost !== "string" || !built.codeHost.includes(codeHost))
527
602
  throw new SettingsError(`${SETTINGS_FILE}: ${unsupportedCodeHost(String(codeHost), built.codeHost)}`);
603
+ const branchName = branchNameOf(codeHostBlock["branch-name"], partial);
528
604
  const builds = object(top.builds, "builds");
529
605
  const trigger = oneOf(builds.trigger, "builds.trigger", TRIGGERS, "manual");
530
606
  const minutes = builds["poll-minutes"];
@@ -545,8 +621,8 @@ export function parseSettings(raw, exists, built = BUILT) {
545
621
  const boardFields = Object.fromEntries(Object.entries(rawFields).filter(([k]) => k in FIELD_DEFAULTS));
546
622
  if (Object.keys(boardFields).length && !hasBoard)
547
623
  fail("tickets.fields", "needs tickets.board");
548
- const columns = columnNames(tickets.columns);
549
- if (columns.backlog === null)
624
+ const { columns, missing } = columnNames(tickets.columns, hasBoard ? board : null, partial);
625
+ if (columns.backlog === null && !missing.includes("backlog"))
550
626
  fail("tickets.columns.backlog", "cannot be none: every ticket starts there");
551
627
  const seen = new Map();
552
628
  for (const [key, list] of Object.entries(columns)) {
@@ -560,7 +636,9 @@ export function parseSettings(raw, exists, built = BUILT) {
560
636
  for (const name of list ?? [])
561
637
  seen.set(name, key);
562
638
  }
563
- if (columns.ready === null && trigger !== "manual")
639
+ if (columns.ready === null &&
640
+ trigger !== "manual" &&
641
+ !missing.includes("ready"))
564
642
  fail("tickets.columns.ready", "no column shows ready, so nothing would start a build: name one, or set builds.trigger to manual");
565
643
  if (tickets.fields !== undefined && !isObj(tickets.fields))
566
644
  fail("tickets.fields", "must be a block of settings");
@@ -606,7 +684,7 @@ export function parseSettings(raw, exists, built = BUILT) {
606
684
  fields: fieldNames,
607
685
  ticketFields,
608
686
  },
609
- codeHost: { type: codeHost },
687
+ codeHost: { type: codeHost, branchName },
610
688
  builds: { trigger, runner, pollMinutes },
611
689
  specs,
612
690
  specCheck,
@@ -696,7 +774,7 @@ export function parseChoices(text, load) {
696
774
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
697
775
  * into the lock. `factoryFile` and `ownFile` say which preset files are
698
776
  * kept back: the factory's own, and the repository's own. */
699
- export async function resolveFiles(d, keep = {}) {
777
+ export async function resolveFiles(d, { partial = false, ...keep } = {}) {
700
778
  const load = await yamlOf(d);
701
779
  let ownText;
702
780
  let own;
@@ -758,7 +836,9 @@ export async function resolveFiles(d, keep = {}) {
758
836
  const exists = (path) => d.exists(path) || resolution.files.has(path);
759
837
  let settings;
760
838
  try {
761
- settings = parseSettings(isObj(own) ? resolution.raw : own, exists);
839
+ settings = parseSettings(isObj(own) ? resolution.raw : own, exists, BUILT, {
840
+ partial,
841
+ });
762
842
  }
763
843
  catch (e) {
764
844
  throw e instanceof SettingsError ? fromPreset(e, resolution) : e;
@@ -920,10 +1000,10 @@ export const defaultDeps = (root = repoRoot(), env = process.env) => ({
920
1000
  });
921
1001
  /** The column each state shows in on the board, null for none. */
922
1002
  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;
1003
+ return Object.fromEntries(Object.entries(STATE_KEYS).map(([key, status]) => [
1004
+ status,
1005
+ s.tickets.columns[key],
1006
+ ]));
927
1007
  }
928
1008
  /** The board's names for the fields the sync writes, null for none. */
929
1009
  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,15 @@ 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>;
50
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>;
51
59
  /** The repository and code host a remote's address names, or null for one
52
60
  * on a code host the factory does not support. */
53
61
  export declare function parseRemote(url: string, tools?: Registry): {
package/dist/init.mjs CHANGED
@@ -10,10 +10,10 @@ import { execFileSync, spawn, spawnSync } from "node:child_process";
10
10
  import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
11
11
  import { tmpdir } from "node:os";
12
12
  import { dirname, join } from "node:path";
13
- import { isMap, parseDocument } from "yaml";
13
+ import { isMap, parseDocument, Scalar } from "yaml";
14
14
  import { builtOf, secretSteps, TOOLS, } from "./tools.mjs";
15
15
  import { NeedsScopeError } from "./code-host/types.mjs";
16
- import { columnsOf, fieldNamesOf, filesDeps, parseSettings, resolveFiles, POLL_MINUTES, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
16
+ import { branchPatternFault, columnsOf, fieldNamesOf, filesDeps, parseSettings, resolveFiles, POLL_MINUTES, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
17
17
  import { colorOn, painter } from "./lib/color.mjs";
18
18
  import { checks as doctorChecks, doctorDeps, printChecks } from "./doctor.mjs";
19
19
  import { branchDeps, needDefaultBranch, NoDefaultBranch, } from "./lib/default-branch.mjs";
@@ -25,8 +25,8 @@ import { neededSecrets, PART_TEXT, PARTS, partsOn, resolveParts, SIGNING_KEY, }
25
25
  import { CONTEXT as REVIEW_VERDICT } from "./review-verdict.mjs";
26
26
  import { RULE } from "./setup.mjs";
27
27
  import { differences, PACKAGE, plan as syncPlan } from "./sync.mjs";
28
- import { DEFAULT_COLUMNS, STATE_KEYS, sameName } from "./lib/work-status.mjs";
29
- import { askReady, suggestColumns } from "./columns-suggest.mjs";
28
+ import { DEFAULT_COLUMNS, STATE_KEYS, sameName, } from "./lib/work-status.mjs";
29
+ import { askReady, everyColumn, FACTORY_LINES, fillColumns, suggestColumns, } from "./columns-suggest.mjs";
30
30
  import { FACTORY_FIELDS, suggestFields } from "./ticket-fields.mjs";
31
31
  const SIGNING_TITLE = "software factory builds";
32
32
  /** Where each release's poller image is published. */
@@ -34,6 +34,45 @@ const POLLER_IMAGE = "ghcr.io/davidbyoung/software-factory-poller";
34
34
  /** A month of runs at each interval the scheduled poller allows. */
35
35
  const RUNS_A_MONTH = (minutes) => (30 * 24 * 60) / minutes;
36
36
  const AGAIN = "Run factory init again to add it.";
37
+ /** Each state `tickets.columns` writes, as its columns or null for none,
38
+ * from the settings as parsed YAML. */
39
+ function writtenColumnsOf(raw) {
40
+ const tickets = raw?.tickets;
41
+ const columns = tickets?.columns;
42
+ if (typeof columns !== "object" || columns === null)
43
+ return {};
44
+ return Object.fromEntries(Object.entries(columns)
45
+ .filter(([k]) => k in STATE_KEYS)
46
+ .map(([k, v]) => [
47
+ k,
48
+ v === "none" ? null : Array.isArray(v) ? v.map(String) : [String(v)],
49
+ ]));
50
+ }
51
+ /** The branch name a preset in effect supplies to the settings `text`
52
+ * of the repository at `root`, or null for none. Settings whose presets
53
+ * can't be read get the question: the check that follows says what is
54
+ * wrong with them. */
55
+ export const presetBranchNameAt = (root) => async (text) => {
56
+ try {
57
+ const r = await resolveFiles({ ...filesDeps(root), readFile: () => text }, { partial: true });
58
+ return r.settings.codeHost.branchName;
59
+ }
60
+ catch {
61
+ return null;
62
+ }
63
+ };
64
+ const BRANCH_QUESTION = "How should a build name its branch? Use {ticket}, and {user} for the GitHub account:";
65
+ /** The pattern a build names its branch by, asked until the answer is one
66
+ * the settings check takes. */
67
+ async function askBranchName(d) {
68
+ for (;;) {
69
+ const answer = (await d.ask.input(BRANCH_QUESTION, "{ticket}")).trim();
70
+ const fault = branchPatternFault(answer);
71
+ if (!fault)
72
+ return answer;
73
+ d.out(fault);
74
+ }
75
+ }
37
76
  /** The columns and fields the board sync uses: the settings' names where
38
77
  * they rename one, and none for one they set to none. */
39
78
  function boardShape(s) {
@@ -98,7 +137,8 @@ export async function main(_argv, d) {
98
137
  let settings = null;
99
138
  if (settingsText !== null) {
100
139
  try {
101
- settings = parseSettings(doc.toJS(), (p) => existsSync(at(p)), builtOf(d.tools));
140
+ // A block that leaves states out is what the column step fills in.
141
+ settings = parseSettings(doc.toJS(), (p) => existsSync(at(p)), builtOf(d.tools), { partial: true });
102
142
  }
103
143
  catch (e) {
104
144
  d.out(`${SETTINGS_FILE}: ${message(e)}`);
@@ -183,6 +223,10 @@ export async function main(_argv, d) {
183
223
  runner: await pick("runner", "Where do cloud builds run?"),
184
224
  agent: agentName,
185
225
  };
226
+ const branchName = doc.hasIn(["code-host", "branch-name"]) ||
227
+ (await d.presetBranchName(String(doc))) !== null
228
+ ? null
229
+ : await askBranchName(d);
186
230
  const codeHost = d.tools.codeHost[chosen.codeHost].open(repository);
187
231
  const runner = d.tools.runner[chosen.runner].open(repository);
188
232
  const tickets = await d.tools.tickets[chosen.tickets].open({ repository, board: null }, settings);
@@ -284,19 +328,21 @@ export async function main(_argv, d) {
284
328
  })), "30"));
285
329
  }
286
330
  }
287
- // The board's columns: the coding agent suggests them when an existing
288
- // board lacks one of the factory's and the settings name none, and a
289
- // ready column is asked for when builds from the board turn on without
290
- // one.
331
+ // The board's columns, all six written: the coding agent suggests them
332
+ // when an existing board lacks one of the factory's and the settings
333
+ // name none, a block that leaves states out is filled in, and a ready
334
+ // column is asked for when builds from the board turn on without one.
291
335
  let columnLines = [];
292
336
  let readyColumn;
337
+ const writtenColumns = writtenColumnsOf(doc.toJS());
338
+ const missing = Object.keys(STATE_KEYS).filter((k) => !(k in writtenColumns));
293
339
  if (parts.has("board") && typeof board === "number" && boardOps) {
294
340
  const asksReady = parts.has("from-board") &&
295
341
  !before.has("from-board") &&
296
342
  settings?.tickets.columns.ready === null;
297
- const suggests = !doc.hasIn(["tickets", "columns"]);
343
+ const suggests = missing.length === Object.keys(STATE_KEYS).length;
298
344
  let names = [];
299
- if (suggests || asksReady)
345
+ if (missing.length || asksReady)
300
346
  try {
301
347
  names = await boardOps.columns(board);
302
348
  }
@@ -306,22 +352,24 @@ export async function main(_argv, d) {
306
352
  return 1;
307
353
  }
308
354
  const lacks = Object.values(STATE_KEYS).some((f) => !names.some((n) => sameName(n, f)));
355
+ const fromBoard = parts.has("from-board") && trigger !== "manual";
309
356
  if (suggests && names.length && lacks) {
310
357
  const got = await suggestColumns({
311
358
  ask: d.ask,
312
359
  out: d.out,
313
360
  agent: agent.agent,
314
361
  label: agent.label,
315
- }, {
316
- board,
317
- columns: names,
318
- fromBoard: parts.has("from-board") && trigger !== "manual",
319
- });
362
+ }, { board, columns: names, fromBoard });
320
363
  if (got === 1)
321
364
  return 1;
322
- if (got !== "default")
323
- columnLines = got;
365
+ columnLines = got;
324
366
  }
367
+ else if (suggests && names.length)
368
+ columnLines = everyColumn(d, { board, columns: names });
369
+ else if (suggests)
370
+ columnLines = FACTORY_LINES;
371
+ else if (missing.length)
372
+ columnLines = await fillColumns({ ask: d.ask, out: d.out }, { board, columns: names, written: writtenColumns, fromBoard });
325
373
  else if (asksReady && settings)
326
374
  readyColumn = await askReady({ ask: d.ask, out: d.out }, { columns: names, current: columnsOf(settings) });
327
375
  }
@@ -369,16 +417,22 @@ export async function main(_argv, d) {
369
417
  doc.setIn(["tickets", "columns", key], name);
370
418
  for (const [key, name] of fieldLines)
371
419
  doc.setIn(["tickets", "fields", key], name);
372
- if (readyColumn === null)
373
- remove(doc, ["tickets", "columns", "ready"]);
374
- else if (readyColumn !== undefined)
375
- doc.setIn(["tickets", "columns", "ready"], readyColumn);
420
+ if (readyColumn !== undefined)
421
+ doc.setIn(["tickets", "columns", "ready"], readyColumn ?? "Ready");
376
422
  if (!parts.has("board")) {
377
423
  for (const key of ["board", "columns"])
378
424
  remove(doc, ["tickets", key]);
379
425
  for (const key of ["session", "runs-in", "cost"])
380
426
  remove(doc, ["tickets", "fields", key]);
381
427
  }
428
+ if (branchName !== null) {
429
+ if (!isMap(doc.get("code-host")))
430
+ doc.set("code-host", doc.createNode({ type: chosen.codeHost }));
431
+ // Quoted: YAML reads a pattern that starts with `{` as a map.
432
+ const quoted = new Scalar(branchName);
433
+ quoted.type = Scalar.QUOTE_DOUBLE;
434
+ doc.setIn(["code-host", "branch-name"], quoted);
435
+ }
382
436
  if (parts.has("from-board"))
383
437
  doc.setIn(["builds", "trigger"], trigger);
384
438
  else if (before.has("from-board"))
@@ -500,6 +554,7 @@ export async function main(_argv, d) {
500
554
  }
501
555
  // The board first, since the settings name its number.
502
556
  if (parts.has("board") && boardOps) {
557
+ const creating = board === "new";
503
558
  while (board === "new") {
504
559
  try {
505
560
  board = await boardOps.create(name);
@@ -512,6 +567,10 @@ export async function main(_argv, d) {
512
567
  }
513
568
  if (typeof board === "number") {
514
569
  doc.setIn(["tickets", "board"], board);
570
+ // A block needs a board, so one init creates has none written yet.
571
+ if (creating)
572
+ for (const [key, name] of FACTORY_LINES)
573
+ doc.setIn(["tickets", "columns", key], name);
515
574
  try {
516
575
  const shape = boardShape(standing());
517
576
  const columns = await boardOps.addColumns(board, shape.columns);
@@ -656,6 +715,7 @@ export async function main(_argv, d) {
656
715
  ` FACTORY_BOARD_OWNER=${owner}`,
657
716
  ` FACTORY_BOARD_NUMBER=${board}`,
658
717
  " FACTORY_BOARD_TOKEN=the access token you just made",
718
+ ` FACTORY_READY_COLUMN=${columnsOf(standing()).Ready?.[0]}`,
659
719
  ].join("\n"));
660
720
  // Init asks for no command, so a gate is the owner's to add: without one
661
721
  // `factory gate` fails, and a build cannot finish.
@@ -725,6 +785,7 @@ export async function run(argv) {
725
785
  const branch = await needDefaultBranch({ ...branchDeps(root), host });
726
786
  return differences(root, await syncPlan(PACKAGE, root, r, branch));
727
787
  },
788
+ presetBranchName: presetBranchNameAt(root),
728
789
  interactive: async (argv2) => spawnSync(argv2[0], argv2.slice(1), { stdio: "inherit" }).status ?? 1,
729
790
  hasCommand,
730
791
  openPage: (url) => {
package/dist/lib/gh.d.mts CHANGED
@@ -11,6 +11,12 @@ export declare function refusalsIn(stdout: string): string;
11
11
  /** A failed call's error: the call, the CLI's own message, and the reasons
12
12
  * in the answer it printed. */
13
13
  export declare function failureOf(args: string[], detail: string, stdout: string): string;
14
+ /** A call the GitHub CLI failed, with the status it exited with: 4 when
15
+ * it is signed in as nobody. */
16
+ export declare class GhError extends Error {
17
+ readonly exitCode: number | null;
18
+ constructor(message: string, exitCode: number | null);
19
+ }
14
20
  export declare const gh: Gh;
15
21
  export declare const ghIn: GhIn;
16
22
  export declare function ghJson<T>(run: Gh, args: string[]): Promise<T>;
package/dist/lib/gh.mjs CHANGED
@@ -25,10 +25,20 @@ export function failureOf(args, detail, stdout) {
25
25
  const said = refusalsIn(stdout);
26
26
  return `gh ${args.slice(0, 4).join(" ")}: ${detail.trim()}${said ? `: ${said}` : ""}`;
27
27
  }
28
+ /** A call the GitHub CLI failed, with the status it exited with: 4 when
29
+ * it is signed in as nobody. */
30
+ export class GhError extends Error {
31
+ exitCode;
32
+ constructor(message, exitCode) {
33
+ super(message);
34
+ this.name = "GhError";
35
+ this.exitCode = exitCode;
36
+ }
37
+ }
28
38
  export const gh = (args) => new Promise((resolve, reject) => {
29
39
  execFile("gh", args, { maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
30
40
  if (error)
31
- reject(new Error(failureOf(args, stderr || error.message, stdout)));
41
+ reject(new GhError(failureOf(args, stderr || error.message, stdout), typeof error.code === "number" ? error.code : null));
32
42
  else
33
43
  resolve(stdout);
34
44
  });
@@ -1,2 +1,3 @@
1
- /** Items as a sentence lists them: "a", "a and b", "a, b, and c". */
2
- export declare const listed: (items: readonly string[]) => string;
1
+ /** Items as a sentence lists them: "a", "a and b", "a, b, and c", or
2
+ * with "or" in place of "and". */
3
+ export declare const listed: (items: readonly string[], conjunction?: "and" | "or") => string;
@@ -1,4 +1,5 @@
1
- /** Items as a sentence lists them: "a", "a and b", "a, b, and c". */
2
- export const listed = (items) => items.length < 3
3
- ? items.join(" and ")
4
- : `${items.slice(0, -1).join(", ")}, and ${items.at(-1)}`;
1
+ /** Items as a sentence lists them: "a", "a and b", "a, b, and c", or
2
+ * with "or" in place of "and". */
3
+ export const listed = (items, conjunction = "and") => items.length < 3
4
+ ? items.join(` ${conjunction} `)
5
+ : `${items.slice(0, -1).join(", ")}, ${conjunction} ${items.at(-1)}`;
package/dist/poller.d.mts CHANGED
@@ -10,7 +10,7 @@ export declare function selectToStart(snapshot: RepoSnapshot, board: Board, colu
10
10
  export declare function startMarker(): string;
11
11
  /** The columns the poller reads a board by. It runs with no settings file,
12
12
  * so it is told the one name it needs, the column that approves a build:
13
- * FACTORY_READY_COLUMN, which defaults to Ready. */
13
+ * FACTORY_READY_COLUMN, which `readConfig` requires. */
14
14
  export declare function columnsFrom(env: Record<string, string | undefined>): Columns;
15
15
  /** What a refused dispatch's comment says GitHub answered: the status, and
16
16
  * the answer's message or else the status text. */
package/dist/poller.mjs CHANGED
@@ -6,10 +6,12 @@
6
6
  // column from the settings in its checkout and needs only the token.
7
7
  //
8
8
  // Hosted, its environment: FACTORY_REPOSITORY (owner/name), FACTORY_BOARD_OWNER,
9
- // FACTORY_BOARD_NUMBER, and FACTORY_BOARD_TOKEN (a classic token with the
9
+ // FACTORY_BOARD_NUMBER, FACTORY_BOARD_TOKEN (a classic token with the
10
10
  // repo and project scopes, or a fine-grained one that can also write
11
- // Actions: it starts the workflow). It has no checkout, so it reads
12
- // the repository from its environment rather than the factory's settings.
11
+ // Actions: it starts the workflow), and FACTORY_READY_COLUMN (the column
12
+ // tickets.columns.ready names). It has no checkout, so it reads the
13
+ // repository and the column from its environment rather than the
14
+ // factory's settings.
13
15
  //
14
16
  // Once started it never exits on its own: a host that deploys every
15
17
  // component together can fail the whole deploy when a worker exits during
@@ -45,11 +47,11 @@ export function startMarker() {
45
47
  }
46
48
  /** The columns the poller reads a board by. It runs with no settings file,
47
49
  * so it is told the one name it needs, the column that approves a build:
48
- * FACTORY_READY_COLUMN, which defaults to Ready. */
50
+ * FACTORY_READY_COLUMN, which `readConfig` requires. */
49
51
  export function columnsFrom(env) {
50
52
  return {
51
53
  ...DEFAULT_COLUMNS,
52
- Ready: [env.FACTORY_READY_COLUMN?.trim() || "Ready"],
54
+ Ready: [env.FACTORY_READY_COLUMN.trim()],
53
55
  };
54
56
  }
55
57
  /** What a refused dispatch's comment says GitHub answered: the status, and
@@ -90,8 +92,9 @@ export function readConfig(env) {
90
92
  "FACTORY_BOARD_OWNER",
91
93
  "FACTORY_BOARD_NUMBER",
92
94
  "FACTORY_BOARD_TOKEN",
95
+ "FACTORY_READY_COLUMN",
93
96
  ];
94
- const missing = names.filter((name) => !env[name]);
97
+ const missing = names.filter((name) => !env[name]?.trim());
95
98
  if (missing.length)
96
99
  return { missing };
97
100
  return {
package/dist/pr.mjs CHANGED
@@ -210,7 +210,7 @@ const FIELDS = {
210
210
  };
211
211
  /** How many lines of a failed job's log `failed` prints, from its end. */
212
212
  const LOG_TAIL = 200;
213
- const USAGE = `Usage: npx --no-install factory pr state [N] [--wait] | threads N [--all] | reply N COMMENT_ID --body-file FILE | resolve N COMMENT_ID | ready N | closes N | wait-checks N | comments N [--author LOGIN] [--contains TEXT] [--json] | comment N --body-file FILE | comment-view ID | label N --add LABEL | --remove LABEL | review-pending N REVIEW | conflicts | open --title TITLE --body-file FILE [--base BRANCH] [--ready] | view N --field ${Object.keys(FIELDS).join("|")} | review N REVIEW | unverified N | uncovered [BASE] [LCOV] | failed N | review-again N`;
213
+ const USAGE = `Usage: npx --no-install factory pr state [N] [--wait] | threads N [--all] | reply N COMMENT_ID --body-file FILE | resolve N COMMENT_ID | ready N | closes N | for-branch BRANCH | wait-checks N | comments N [--author LOGIN] [--contains TEXT] [--json] | comment N --body-file FILE | comment-view ID | label N --add LABEL | --remove LABEL | review-pending N REVIEW | conflicts | open --title TITLE --body-file FILE [--base BRANCH] [--ready] | view N --field ${Object.keys(FIELDS).join("|")} | review N REVIEW | unverified N | uncovered [BASE] [LCOV] | failed N | review-again N`;
214
214
  function option(args, name) {
215
215
  const at = args.indexOf(name);
216
216
  if (at === -1)
@@ -367,6 +367,14 @@ export async function main(argv, d) {
367
367
  d.out("ready");
368
368
  return 0;
369
369
  }
370
+ case "for-branch": {
371
+ const [branch] = rest;
372
+ if (!branch || rest.length > 1)
373
+ throw new Error(USAGE);
374
+ const last = await p.lastForBranch(branch);
375
+ d.out(last ? `#${last.number} ${last.state}` : "none");
376
+ return 0;
377
+ }
370
378
  case "closes": {
371
379
  const [pr] = numbers;
372
380
  if (!pr)
package/dist/ticket.d.mts CHANGED
@@ -40,6 +40,9 @@ export type Deps = {
40
40
  };
41
41
  /** What the session spent since `since`, or since it started. */
42
42
  measure: (session: string, since: string | null) => Measured;
43
+ /** Who the code host's CLI is signed in as, for a branch name's
44
+ * `{user}`. */
45
+ signedInAs: (repository: string, codeHost: string) => Promise<string>;
43
46
  };
44
47
  export type { Clock };
45
48
  export declare function readComments(c: {