@davidbyoung/software-factory 0.1.7 → 0.1.9

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 (63) 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 +126 -38
  5. package/dist/cli.mjs +75 -9
  6. package/dist/code-host/github-setup.mjs +2 -2
  7. package/dist/code-host/github.mjs +4 -0
  8. package/dist/code-host/types.d.mts +2 -0
  9. package/dist/columns-suggest.d.mts +0 -1
  10. package/dist/columns-suggest.mjs +2 -8
  11. package/dist/commands.d.mts +2 -0
  12. package/dist/commands.mjs +22 -11
  13. package/dist/config.d.mts +12 -0
  14. package/dist/config.mjs +62 -11
  15. package/dist/doctor.d.mts +9 -1
  16. package/dist/doctor.mjs +209 -20
  17. package/dist/explain.d.mts +5 -0
  18. package/dist/explain.mjs +29 -0
  19. package/dist/init.d.mts +2 -0
  20. package/dist/init.mjs +143 -13
  21. package/dist/lib/color.d.mts +11 -0
  22. package/dist/lib/color.mjs +15 -0
  23. package/dist/npmrc.d.mts +29 -0
  24. package/dist/npmrc.mjs +98 -0
  25. package/dist/preset-commands.d.mts +2 -2
  26. package/dist/preset-commands.mjs +20 -24
  27. package/dist/preset.d.mts +4 -0
  28. package/dist/preset.mjs +13 -2
  29. package/dist/runner/github-actions.mjs +47 -10
  30. package/dist/runner/types.d.mts +13 -0
  31. package/dist/setup.d.mts +6 -1
  32. package/dist/site.d.mts +3 -0
  33. package/dist/site.mjs +8 -1
  34. package/dist/status.d.mts +5 -2
  35. package/dist/status.mjs +13 -22
  36. package/dist/sync.d.mts +14 -1
  37. package/dist/sync.mjs +83 -7
  38. package/dist/ticket-fields.d.mts +84 -0
  39. package/dist/ticket-fields.mjs +374 -0
  40. package/dist/ticket.mjs +8 -7
  41. package/dist/tickets/github-setup.mjs +1 -1
  42. package/dist/tickets/github.mjs +69 -0
  43. package/dist/tickets/index.d.mts +8 -1
  44. package/dist/tickets/index.mjs +67 -7
  45. package/dist/tickets/types.d.mts +27 -1
  46. package/dist/tickets/types.mjs +4 -0
  47. package/dist/tools.d.mts +1 -1
  48. package/docs/cli.md +44 -10
  49. package/docs/configuration.md +78 -25
  50. package/docs/design.md +10 -0
  51. package/docs/developing.md +49 -18
  52. package/docs/existing-repo.md +137 -8
  53. package/docs/github/by-hand.md +4 -0
  54. package/docs/github/reference.md +5 -0
  55. package/docs/github/setup.md +146 -8
  56. package/docs/limitations.md +0 -3
  57. package/docs/presets.md +5 -9
  58. package/docs/quick-start.md +3 -3
  59. package/docs/skills.md +3 -1
  60. package/docs/updating.md +3 -3
  61. package/package.json +4 -2
  62. package/settings.schema.json +68 -11
  63. package/skills/factory-deps/SKILL.md +4 -0
package/dist/preset.mjs CHANGED
@@ -7,8 +7,9 @@ import { createHash } from "node:crypto";
7
7
  import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
8
8
  import { dirname, join, relative, sep } from "node:path";
9
9
  import { DEFAULT_CODE_HOST } from "./code-host/index.mjs";
10
- import { ROLE_SHAPE, ROLES, SETTINGS_FILE, SETTINGS_KEYS } from "./config.mjs";
10
+ import { OWN_HEADING, ROLE_SHAPE, ROLES, SETTINGS_FILE, SETTINGS_KEYS, } from "./config.mjs";
11
11
  import { BUILT } from "./tool-names.mjs";
12
+ import { NPMRC, refusal } from "./npmrc.mjs";
12
13
  export const PRESET_FILE = "factory-preset.yaml";
13
14
  export const CHOICES_FILE = ".claude/factory.choices.yaml";
14
15
  export const LOCK_FILE = ".claude/factory.lock";
@@ -130,7 +131,8 @@ export function unknownKey(raw) {
130
131
  for (const [k, value] of Object.entries(v)) {
131
132
  const at = path ? `${path}.${k}` : k;
132
133
  const show = shown ? `${shown}.${k}` : k;
133
- if (!allowed.includes(k) && !extra.includes(k))
134
+ const own = path === "tickets.fields" && OWN_HEADING.test(k);
135
+ if (!allowed.includes(k) && !extra.includes(k) && !own)
134
136
  return `${show}: unknown key`;
135
137
  const inner = SETTINGS_KEYS[`${at}[]`] && Array.isArray(value)
136
138
  ? value
@@ -509,6 +511,9 @@ export function readLock(text, load) {
509
511
  }))
510
512
  : [],
511
513
  hash: typeof d["settings-hash"] === "string" ? d["settings-hash"] : null,
514
+ npmrcVariables: Array.isArray(d["npmrc-variables"])
515
+ ? d["npmrc-variables"].map(String)
516
+ : [],
512
517
  settings: isObj(d.settings) ? d.settings : null,
513
518
  overridden: isObj(d.overridden)
514
519
  ? d.overridden
@@ -536,6 +541,12 @@ export function staleReason(d) {
536
541
  const choicesOnly = changed.includes(CHOICES_FILE) && !changed.includes(SETTINGS_FILE);
537
542
  return staleMessages.changed(choicesOnly ? CHOICES_FILE : SETTINGS_FILE);
538
543
  }
544
+ const names = d.npmrcNames ?? [];
545
+ const refused = names.map(refusal).find((r) => r !== null);
546
+ if (refused)
547
+ return refused;
548
+ if (names.join("\n") !== lock.npmrcVariables.join("\n"))
549
+ return staleMessages.changed(NPMRC);
539
550
  for (const p of lock.presets) {
540
551
  const v = d.installed(splitName(p.name).pkg);
541
552
  if (v === null)
@@ -11,6 +11,17 @@ const FAILED = ["failure", "timed_out", "startup_failure"];
11
11
  export function githubActionsRunner(o) {
12
12
  const t = o.transport;
13
13
  const API = `repos/${o.repository}`;
14
+ /** Every secret a listing names, page by page: the list is an object,
15
+ * not an array, so it is paged by hand. */
16
+ const secretsAt = async (path) => {
17
+ const all = [];
18
+ for (let page = 1;; page++) {
19
+ const listed = await t.rest("GET", `${path}?per_page=100&page=${page}`);
20
+ all.push(...listed.secrets);
21
+ if (listed.secrets.length < 100)
22
+ return all;
23
+ }
24
+ };
14
25
  const reviewsOf = async (sha) => (await t.rest("GET", `${API}/actions/workflows/${REVIEW_WORKFLOW}/runs?head_sha=${sha}&per_page=5`)).workflow_runs;
15
26
  return {
16
27
  async startBuild(ticket, branch) {
@@ -90,20 +101,46 @@ export function githubActionsRunner(o) {
90
101
  throw error;
91
102
  }
92
103
  },
93
- async secretNames() {
94
- // The list is an object, not an array, so it is paged by hand.
95
- const names = [];
96
- for (let page = 1;; page++) {
97
- const listed = await t.rest("GET", `${API}/actions/secrets?per_page=100&page=${page}`);
98
- names.push(...listed.secrets.map((x) => x.name));
99
- if (listed.secrets.length < 100)
100
- return names;
101
- }
102
- },
104
+ secretNames: async () => (await secretsAt(`${API}/actions/secrets`)).map((x) => x.name),
103
105
  async setSecret(name, value) {
104
106
  if (!o.cli)
105
107
  throw new Error("Storing a secret needs the GitHub CLI.");
106
108
  await o.cli(["secret", "set", name, "--repo", o.repository], value);
107
109
  },
110
+ dependabotSecretNames: async () => (await secretsAt(`${API}/dependabot/secrets`)).map((x) => x.name),
111
+ async setDependabotSecret(name, value) {
112
+ if (!o.cli)
113
+ throw new Error("Storing a secret needs the GitHub CLI.");
114
+ await o.cli(["secret", "set", name, "--app", "dependabot", "--repo", o.repository], value);
115
+ },
116
+ organizationSecretNames: async () => (await secretsAt(`${API}/actions/organization-secrets`)).map((x) => x.name),
117
+ async organizationDependabotSecretNames(isPrivate) {
118
+ const org = `orgs/${o.repository.split("/")[0]}/dependabot/secrets`;
119
+ try {
120
+ const names = [];
121
+ for (const s of await secretsAt(org)) {
122
+ if (s.visibility === "all" ||
123
+ (s.visibility === "private" && isPrivate))
124
+ names.push(s.name);
125
+ else if (s.visibility === "selected") {
126
+ for (let page = 1;; page++) {
127
+ const shared = await t.rest("GET", `${org}/${s.name}/repositories?per_page=100&page=${page}`);
128
+ if (shared.repositories.some((r) => r.full_name === o.repository)) {
129
+ names.push(s.name);
130
+ break;
131
+ }
132
+ if (shared.repositories.length < 100)
133
+ break;
134
+ }
135
+ }
136
+ }
137
+ return names;
138
+ }
139
+ catch (error) {
140
+ if (statusOf(error) !== null)
141
+ return null;
142
+ throw error;
143
+ }
144
+ },
108
145
  };
109
146
  }
@@ -60,4 +60,17 @@ export type Runner = {
60
60
  /** Stores a secret the runner's jobs can read. The value never appears
61
61
  * in a command's arguments or its output. */
62
62
  setSecret(name: string, value: string): Promise<void>;
63
+ /** The names of the secrets the runner gives a job that the dependency
64
+ * bot's pull request starts. */
65
+ dependabotSecretNames(): Promise<string[]>;
66
+ /** Stores a secret for those jobs, as `setSecret` does. */
67
+ setDependabotSecret(name: string, value: string): Promise<void>;
68
+ /** The names of the secrets the repository's organization shares with
69
+ * it. Not called on a repository a person owns. */
70
+ organizationSecretNames(): Promise<string[]>;
71
+ /** The names of the organization's secrets for the dependency bot that
72
+ * reach this repository, which private ones do only when it is private,
73
+ * or null when the organization will not list them. Not called on a
74
+ * repository a person owns. */
75
+ organizationDependabotSecretNames(isPrivate: boolean): Promise<string[] | null>;
63
76
  };
package/dist/setup.d.mts CHANGED
@@ -7,10 +7,15 @@ import type { Tickets } from "./tickets/types.mts";
7
7
  * removing it is deleting that one rule. */
8
8
  export declare const RULE = "Software factory";
9
9
  export type Check = {
10
- state: "pass" | "fail" | "off";
10
+ /** `unknown`: the check can't be made from the repository, and fails
11
+ * nothing. */
12
+ state: "pass" | "fail" | "off" | "unknown";
11
13
  text: string;
12
14
  /** What to do about a failure. */
13
15
  fix?: string;
16
+ /** The heading `doctor` prints it under: a tool's name, or one of its
17
+ * own. */
18
+ group?: string;
14
19
  };
15
20
  /** A secret is needed for a part that is on, or always when `part` is
16
21
  * null, and any one of `anyOf` being set meets it. */
package/dist/site.d.mts CHANGED
@@ -57,4 +57,7 @@ export declare function givenUrls(argv: string[]): {
57
57
  before: string;
58
58
  after: string;
59
59
  } | null;
60
+ /** What `factory site stop` says: a kept comparison is always two sites,
61
+ * this branch's and the base's. */
62
+ export declare function stopMessage(stopped: boolean): string;
60
63
  export declare function run(argv: string[]): Promise<number>;
package/dist/site.mjs CHANGED
@@ -317,13 +317,20 @@ async function compare(argv) {
317
317
  cleanup();
318
318
  }
319
319
  }
320
+ /** What `factory site stop` says: a kept comparison is always two sites,
321
+ * this branch's and the base's. */
322
+ export function stopMessage(stopped) {
323
+ return stopped
324
+ ? "Stopped the 2 sites site compare --keep left running."
325
+ : "No sites were left running.";
326
+ }
320
327
  export async function run(argv) {
321
328
  const [command, ...rest] = argv;
322
329
  try {
323
330
  if (command === "compare")
324
331
  return await compare(rest);
325
332
  if (command === "stop") {
326
- stopKept(repoRoot());
333
+ console.log(stopMessage(stopKept(repoRoot())));
327
334
  return 0;
328
335
  }
329
336
  console.error("Usage: factory site compare | site stop");
package/dist/status.d.mts CHANGED
@@ -51,8 +51,9 @@ export type Style = {
51
51
  columns?: Columns;
52
52
  };
53
53
  export declare const PLAIN: Style;
54
- /** A terminal unless NO_COLOR is set to anything (no-color.org). */
55
- export declare function styleFor(isTTY: boolean | undefined, columns: number | undefined, noColor: string | undefined): Style;
54
+ /** Colors, links, and fitting to the window go together, where `colorOn`
55
+ * says the output is colored. */
56
+ export declare function styleFor(color: boolean, columns: number | undefined): Style;
56
57
  /** One reviewer's row under its card: a mark that carries the result
57
58
  * without color, the name, the model, the result, how long it ran, and its
58
59
  * cost in subscription dollars. */
@@ -96,5 +97,7 @@ export type Deps = {
96
97
  * frame as tall as the window. */
97
98
  export declare function frame(lines: string[]): string;
98
99
  export declare function main(argv: string[], d: Deps): Promise<number>;
100
+ /** The style for what `run` prints to stdout. */
101
+ export declare const terminalStyle: () => Style;
99
102
  /** `factory status [--watch]`, and `factory session-start`'s second half. */
100
103
  export declare function run(argv: string[]): Promise<number>;
package/dist/status.mjs CHANGED
@@ -11,6 +11,7 @@
11
11
  // The repository and the board come from the factory's settings, whose
12
12
  // loader needs dependencies installed; before npm ci the hook prints
13
13
  // nothing.
14
+ import { colorOn, painter } from "./lib/color.mjs";
14
15
  import { setTimeout as sleep } from "node:timers/promises";
15
16
  import { NO_DEPENDENCIES, SettingsError, loadSettings, targetOf, } from "./config.mjs";
16
17
  import { appSessionLink } from "./lib/gh.mjs";
@@ -114,26 +115,14 @@ watch = watchOf("own-server", 5), columns = DEFAULT_COLUMNS) {
114
115
  return { rows, closed };
115
116
  }
116
117
  export const PLAIN = { color: false, width: null };
117
- /** A terminal unless NO_COLOR is set to anything (no-color.org). */
118
- export function styleFor(isTTY, columns, noColor) {
119
- return isTTY && !noColor ? { color: true, width: columns ?? 80 } : PLAIN;
118
+ /** Colors, links, and fitting to the window go together, where `colorOn`
119
+ * says the output is colored. */
120
+ export function styleFor(color, columns) {
121
+ return color ? { color: true, width: columns ?? 80 } : PLAIN;
120
122
  }
121
123
  const ESC = "\x1B";
122
- const SGR = {
123
- bold: 1,
124
- dim: 2,
125
- underline: 4,
126
- red: 31,
127
- green: 32,
128
- yellow: 33,
129
- magenta: 35,
130
- cyan: 36,
131
- white: 37,
132
- brightBlue: 94,
133
- brightWhite: 97,
134
- };
135
124
  const GROUPS = [
136
- { name: "Backlog", color: "brightWhite" },
125
+ { name: "Backlog", color: "whiteBright" },
137
126
  { name: "In refinement", color: "yellow" },
138
127
  { name: "Ready", color: "green" },
139
128
  { name: "In progress", color: "cyan" },
@@ -149,7 +138,7 @@ const width = (segs) => segs.reduce((n, s) => n + [...s.text].length, 0);
149
138
  function paint(text, style, ...codes) {
150
139
  if (!style.color || codes.length === 0)
151
140
  return text;
152
- return `${ESC}[${codes.map((c) => SGR[c]).join(";")}m${text}${ESC}[0m`;
141
+ return painter(true)(codes, text);
153
142
  }
154
143
  function render(segs, style) {
155
144
  return segs
@@ -324,7 +313,7 @@ export function formatRows({ rows, closed }, now, withClosed = true, style = PLA
324
313
  {
325
314
  name: UNLINKED,
326
315
  label: UNLINKED,
327
- color: "brightWhite",
316
+ color: "whiteBright",
328
317
  cells: cells.filter((c) => c.row.kind === "pull"),
329
318
  always: false,
330
319
  },
@@ -342,7 +331,7 @@ export function formatRows({ rows, closed }, now, withClosed = true, style = PLA
342
331
  ? paint(c.session, style, "bold", "yellow")
343
332
  : render(sessionSegs(c.session, c.row.derived, style.links), style);
344
333
  lines.push((INDENT +
345
- paint(render([{ text: c.number, url: c.url }], style), style, "brightBlue") +
334
+ paint(render([{ text: c.number, url: c.url }], style), style, "blueBright") +
346
335
  pad(c.number, numW) +
347
336
  GAP +
348
337
  render(title, style) +
@@ -373,7 +362,7 @@ export function formatRows({ rows, closed }, now, withClosed = true, style = PLA
373
362
  text: `#${r.number}`,
374
363
  url: linkTo("ticket", style, r.number),
375
364
  },
376
- ], style), style, "brightBlue"))
365
+ ], style), style, "blueBright"))
377
366
  .join(", ")}`);
378
367
  return lines;
379
368
  }
@@ -484,6 +473,8 @@ export async function main(argv, d) {
484
473
  await d.sleep(WATCH_MS);
485
474
  }
486
475
  }
476
+ /** The style for what `run` prints to stdout. */
477
+ export const terminalStyle = () => styleFor(colorOn(), process.stdout.columns);
487
478
  /** `factory status [--watch]`, and `factory session-start`'s second half. */
488
479
  export async function run(argv) {
489
480
  const code = await main(argv, {
@@ -506,7 +497,7 @@ export async function run(argv) {
506
497
  process.exit(130);
507
498
  });
508
499
  },
509
- style: () => styleFor(process.stdout.isTTY, process.stdout.columns, process.env.NO_COLOR),
500
+ style: terminalStyle,
510
501
  settings: () => loadSettings(),
511
502
  env: process.env,
512
503
  });
package/dist/sync.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { type Paint } from "./lib/color.mts";
1
2
  import { type Resolved, type Settings } from "./config.mts";
2
3
  import { type Replaced } from "./preset.mts";
3
4
  /** The package's own folder: the parent of `src/`, or of `dist/` once
@@ -19,6 +20,11 @@ export declare function withDefaultBranch(text: string, name: string, file: stri
19
20
  * more, so the steps after the session still run before the job is
20
21
  * stopped. */
21
22
  export declare function withMinutes(text: string, minutes: number, file: string): string;
23
+ /** A workflow whose jobs that install packages set each name in `names`
24
+ * from a secret of the same name, in the job's `env`, so every step that
25
+ * runs npm reads it, a composite action's included. With `GITHUB_TOKEN`
26
+ * among them, the workflow may also read packages. Only lines are added. */
27
+ export declare function withNpmEnv(text: string, names: string[], file: string): string;
22
28
  /** A copy with the rules' numbers the settings give in place of the
23
29
  * defaults. A phrase is replaced only when its number is not the default,
24
30
  * and must then match exactly once. */
@@ -66,6 +72,8 @@ export type LockParts = {
66
72
  version: string;
67
73
  }[];
68
74
  hash: string;
75
+ /** The variables `.npmrc`'s sign-in lines read. */
76
+ npmrcVariables: string[];
69
77
  /** The settings in effect, as `factory config explain` prints them. */
70
78
  settings: string[];
71
79
  overridden: Record<string, Replaced[]>;
@@ -104,6 +112,10 @@ export declare function main(argv: string[], d: {
104
112
  defaultBranch: (s: Settings) => Promise<string | null>;
105
113
  out: (line: string) => void;
106
114
  err: (line: string) => void;
115
+ paint?: Paint;
116
+ /** Whether a person ran it, so a sync that changes nothing says so;
117
+ * `init` and the preset commands run it inside their own output. */
118
+ announce?: boolean;
107
119
  }): Promise<number>;
108
120
  /** The sync of the repository at `root`. */
109
121
  export declare const syncDeps: (root: string) => {
@@ -115,5 +127,6 @@ export declare const syncDeps: (root: string) => {
115
127
  out: (line: string) => void;
116
128
  err: (line: string) => void;
117
129
  };
118
- export declare function run(argv: string[]): Promise<number>;
130
+ /** `announce` is false when `init` runs the sync inside its own output. */
131
+ export declare function run(argv: string[], announce?: boolean): Promise<number>;
119
132
  export {};
package/dist/sync.mjs CHANGED
@@ -14,9 +14,11 @@
14
14
  // the rules' numbers, and the default branch's name in the push triggers.
15
15
  // Edit the source in the package, never the copy. A file the lock lists that the package no longer has is
16
16
  // deleted. Nothing else is.
17
+ import { colorOn, painter, plain } from "./lib/color.mjs";
17
18
  import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
18
19
  import { dirname, join, relative, sep } from "node:path";
19
20
  import { fileURLToPath } from "node:url";
21
+ import { firstRefusal, npmrcAt } from "./npmrc.mjs";
20
22
  import { filesDeps, repoRoot, resolveFiles, RULE_NUMBERS, staleOf, defaultDeps, } from "./config.mjs";
21
23
  import { CHOICES_FILE, choicesText, settingsHash, staleChoices, } from "./preset.mjs";
22
24
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
@@ -93,6 +95,56 @@ export function withMinutes(text, minutes, file) {
93
95
  const session = one(/^(\s+minutes: )\d+$/gm, minutes, text);
94
96
  return one(/^(\s+timeout-minutes: )\d+$/gm, minutes + 10, session);
95
97
  }
98
+ /** A workflow whose jobs that install packages set each name in `names`
99
+ * from a secret of the same name, in the job's `env`, so every step that
100
+ * runs npm reads it, a composite action's included. With `GITHUB_TOKEN`
101
+ * among them, the workflow may also read packages. Only lines are added. */
102
+ export function withNpmEnv(text, names, file) {
103
+ if (!names.length)
104
+ return text;
105
+ const lines = text.split("\n");
106
+ const jobsAt = lines.indexOf("jobs:");
107
+ if (jobsAt < 0)
108
+ return text;
109
+ const starts = lines
110
+ .map((l, i) => (i > jobsAt && /^ {2}[A-Za-z0-9_-]+:\s*$/.test(l) ? i : -1))
111
+ .filter((i) => i >= 0);
112
+ const entries = names.map((n) => ` ${n}: \${{ secrets.${n} }}`);
113
+ const inserts = [];
114
+ starts.forEach((start, k) => {
115
+ const end = starts[k + 1] ?? lines.length;
116
+ const job = lines.slice(start, end);
117
+ const installs = job.some((l) => (/\bnpm ci\b/.test(l) && !/^\s*#/.test(l)) ||
118
+ /^\s+uses: \.\/\.github\/actions\/factory-agent\s*$/.test(l));
119
+ if (!installs)
120
+ return;
121
+ const env = job.findIndex((l) => /^ {4}env:\s*$/.test(l));
122
+ const runsOn = job.findIndex((l) => /^ {4}runs-on:/.test(l));
123
+ const permissions = job.findIndex((l) => /^ {4}permissions:\s*$/.test(l));
124
+ if (names.includes("GITHUB_TOKEN") && permissions >= 0)
125
+ inserts.push({
126
+ at: start + permissions + 1,
127
+ lines: [" packages: read"],
128
+ });
129
+ if (env >= 0)
130
+ inserts.push({ at: start + env + 1, lines: entries });
131
+ else if (runsOn >= 0)
132
+ inserts.push({ at: start + runsOn + 1, lines: [" env:", ...entries] });
133
+ else
134
+ throw new Error(`${file}: expected a runs-on line in each job that installs, to set its env`);
135
+ });
136
+ if (!inserts.length)
137
+ return text;
138
+ if (names.includes("GITHUB_TOKEN")) {
139
+ const permissions = lines.indexOf("permissions:");
140
+ if (permissions < 0)
141
+ throw new Error(`${file}: expected a permissions block, to let GITHUB_TOKEN read packages`);
142
+ inserts.push({ at: permissions + 1, lines: [" packages: read"] });
143
+ }
144
+ for (const { at, lines: added } of inserts.sort((a, b) => b.at - a.at))
145
+ lines.splice(at, 0, ...added);
146
+ return lines.join("\n");
147
+ }
96
148
  const WORDS = [
97
149
  "zero",
98
150
  "one",
@@ -375,6 +427,9 @@ export function lockText(l) {
375
427
  ]
376
428
  : ["presets: []"]),
377
429
  `settings-hash: ${l.hash}`,
430
+ ...(l.npmrcVariables.length
431
+ ? ["npmrc-variables:", ...l.npmrcVariables.map((n) => ` - ${n}`)]
432
+ : ["npmrc-variables: []"]),
378
433
  "settings:",
379
434
  ...l.settings.map((line) => ` ${line}`),
380
435
  ...(replaced.length
@@ -451,19 +506,23 @@ export async function plan(pkg, root, r, branch) {
451
506
  const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
452
507
  const write = new Map();
453
508
  const has = (p) => existsSync(join(root, p));
509
+ const npmrc = npmrcAt(root);
454
510
  for (const [from, to] of copies(pkg, s, has)) {
455
511
  const source = readFileSync(join(pkg, from), "utf8");
456
512
  const text = PUSH_WORKFLOWS.includes(from)
457
513
  ? withDefaultBranch(source, branch, from)
458
514
  : source;
459
515
  const kind = SESSION_WORKFLOWS[from.replace(/^workflows\//, "")];
460
- write.set(to, kind && from.startsWith("workflows/")
516
+ const written = kind && from.startsWith("workflows/")
461
517
  ? withMinutes(text, s.sessionMinutes[kind], from)
462
518
  : from === POLLER_WORKFLOW
463
519
  ? withSchedule(text, s.builds.pollMinutes, from)
464
520
  : from === AUTO_MERGE_WORKFLOW
465
521
  ? withPresetPackages(text, [...new Set(r.presets.map((p) => p.pkg))], from)
466
- : withRules(text, s.rules, from));
522
+ : withRules(text, s.rules, from);
523
+ write.set(to, from.startsWith("workflows/")
524
+ ? withNpmEnv(written, npmrc.names, from)
525
+ : written);
467
526
  }
468
527
  // A preset's agent or skill, unless the factory's own file or one the
469
528
  // repository wrote itself is at its path: those always stay.
@@ -499,6 +558,7 @@ export async function plan(pkg, root, r, branch) {
499
558
  version: manifest.version,
500
559
  presets: r.presets.map((p) => ({ name: p.name, version: p.version })),
501
560
  hash: settingsHash(r.ownText, chosen),
561
+ npmrcVariables: npmrc.names,
502
562
  settings,
503
563
  overridden: Object.fromEntries(r.resolution.overridden),
504
564
  files,
@@ -528,6 +588,7 @@ export function differences(root, p) {
528
588
  }
529
589
  export async function main(argv, d) {
530
590
  const check = argv.includes("--check");
591
+ const paint = d.paint ?? plain;
531
592
  let r;
532
593
  try {
533
594
  if (check) {
@@ -538,6 +599,11 @@ export async function main(argv, d) {
538
599
  }
539
600
  }
540
601
  r = await d.settings();
602
+ const refused = firstRefusal(npmrcAt(d.root));
603
+ if (refused) {
604
+ d.err(refused);
605
+ return 1;
606
+ }
541
607
  }
542
608
  catch (e) {
543
609
  d.err(e instanceof Error ? e.message : String(e));
@@ -553,12 +619,15 @@ export async function main(argv, d) {
553
619
  const p = await plan(d.pkg, d.root, r, branch);
554
620
  const differ = differences(d.root, p);
555
621
  if (check) {
556
- if (differ.length === 0)
622
+ if (differ.length === 0) {
623
+ d.out(`${paint("green", "✓")} The factory's files match the settings.`);
557
624
  return 0;
558
- d.err("the factory's files are out of sync:");
625
+ }
626
+ const n = differ.length;
627
+ d.err(`${paint("red", "✗")} ${n} of the factory's files ${n === 1 ? "doesn't" : "don't"} match the settings:`);
559
628
  for (const path of differ)
560
629
  d.err(` ${path}`);
561
- d.err("Run `npx --no-install factory sync` and commit the result.");
630
+ d.err("Run factory sync and commit what it writes.");
562
631
  return 1;
563
632
  }
564
633
  for (const line of [...p.kept, ...p.dropped])
@@ -576,6 +645,8 @@ export async function main(argv, d) {
576
645
  d.out(`wrote ${path}`);
577
646
  }
578
647
  }
648
+ if (differ.length === 0 && d.announce)
649
+ d.out("The factory's files already match the settings. Nothing changed.");
579
650
  return 0;
580
651
  }
581
652
  /** The sync of the repository at `root`. */
@@ -588,6 +659,11 @@ export const syncDeps = (root) => ({
588
659
  out: (line) => console.log(line),
589
660
  err: (line) => console.error(line),
590
661
  });
591
- export async function run(argv) {
592
- return main(argv, syncDeps(repoRoot()));
662
+ /** `announce` is false when `init` runs the sync inside its own output. */
663
+ export async function run(argv, announce = true) {
664
+ return main(argv, {
665
+ ...syncDeps(repoRoot()),
666
+ paint: painter(colorOn()),
667
+ announce,
668
+ });
593
669
  }
@@ -0,0 +1,84 @@
1
+ import type { Agent } from "./agent/types.mts";
2
+ import type { Ask } from "./init.mts";
3
+ import type { Check } from "./setup.mts";
4
+ import type { Tickets } from "./tickets/types.mts";
5
+ /** The factory fields a refined ticket has, in the order its body has them. */
6
+ export declare const FACTORY_FIELDS: readonly [{
7
+ readonly key: "decisions";
8
+ readonly heading: "Decisions";
9
+ readonly holds: "the questions refinement settled, and what was chosen";
10
+ }, {
11
+ readonly key: "spec";
12
+ readonly heading: "Spec";
13
+ readonly holds: "what a change users will notice must do, line by line";
14
+ }, {
15
+ readonly key: "acceptance-criteria";
16
+ readonly heading: "Acceptance criteria";
17
+ readonly holds: "what must be true for any other ticket to be done";
18
+ }, {
19
+ readonly key: "for-the-builder";
20
+ readonly heading: "For the builder";
21
+ readonly holds: "how to build it, as a design and a list of tasks";
22
+ }];
23
+ export type FactoryKey = (typeof FACTORY_FIELDS)[number]["key"];
24
+ /** Each ticket-side key under `tickets.fields`, in settings order, with
25
+ * the ticket field that holds it, or null for the description. */
26
+ export type FieldMapping = Record<string, string | null>;
27
+ /** The heading a key stands for: the factory's own, or the key with its
28
+ * hyphens as spaces and its first letter capitalized. */
29
+ export declare function headingOf(key: string): string;
30
+ /** The key a heading stands for: lowercase, with hyphens for spaces. */
31
+ export declare const keyOf: (heading: string) => string;
32
+ /** A ticket's document taken apart: the description, and each named ticket
33
+ * field's text, or null to clear it. */
34
+ export declare function split(body: string, mapping: FieldMapping): {
35
+ description: string;
36
+ values: Record<string, string | null>;
37
+ } | {
38
+ error: string;
39
+ };
40
+ /** A ticket's document: its description with each ticket field's text under
41
+ * its key's heading, before the first later heading the description has. */
42
+ export declare function join(description: string, values: Record<string, string>, mapping: FieldMapping, labels: readonly string[]): string;
43
+ /** The agent's answer for a factory field no ticket field fits. A token,
44
+ * so a ticket field called "Description" stays usable. */
45
+ export declare const DESCRIPTION = "__description__";
46
+ export declare const TIMEOUT_MS = 60000;
47
+ /** Each factory field's ticket field, or null for the description. */
48
+ export type Suggestion = Record<FactoryKey, string | null>;
49
+ export declare function prompt(fields: readonly TicketFieldInfo[]): string;
50
+ /** A field as the prompt and the checks need it. */
51
+ export type TicketFieldInfo = {
52
+ name: string;
53
+ description: string | null;
54
+ };
55
+ export declare function schema(fields: readonly TicketFieldInfo[]): object;
56
+ /** The suggestion the agent's answer gives, or the reason it can't be
57
+ * used, the first that applies in the order the issue lists them. */
58
+ export declare function check(answer: unknown, fields: readonly TicketFieldInfo[], repository: string): {
59
+ suggestion: Suggestion;
60
+ } | {
61
+ reason: string;
62
+ };
63
+ /** The table of each factory field's ticket field. */
64
+ export declare function table(suggestion: Suggestion): string[];
65
+ export type FieldStepDeps = {
66
+ ask: Ask;
67
+ out: (line: string) => void;
68
+ agent: Agent;
69
+ /** The agent's registered label, which every line names it by. */
70
+ label: string;
71
+ };
72
+ /** The field step: the four factory fields' lines to write under
73
+ * `tickets.fields`, or 1 when init stops. */
74
+ export declare function suggestFields(d: FieldStepDeps, o: {
75
+ repository: string;
76
+ fields: readonly TicketFieldInfo[];
77
+ /** The ticket system's label, when its fields show text as typed. */
78
+ plainText: string | null;
79
+ }): Promise<[FactoryKey, string][] | 1>;
80
+ /** The checks `factory doctor` and `init` end with: that each ticket field
81
+ * the settings name exists and holds text. None when they name none. */
82
+ export declare function fieldChecks(tickets: Tickets, mapping: FieldMapping, repository: string,
83
+ /** The ticket system's registered label. */
84
+ label: string): Promise<Check[]>;