@davidbyoung/software-factory 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/README.md +2 -0
  2. package/dist/agent/claude-code.mjs +15 -21
  3. package/dist/board.d.mts +20 -3
  4. package/dist/board.mjs +124 -38
  5. package/dist/cli.mjs +84 -9
  6. package/dist/code-host/github-setup.mjs +2 -2
  7. package/dist/code-host/github.d.mts +1 -1
  8. package/dist/code-host/github.mjs +29 -2
  9. package/dist/code-host/types.d.mts +16 -1
  10. package/dist/code-host/types.mjs +8 -0
  11. package/dist/columns-suggest.d.mts +25 -6
  12. package/dist/columns-suggest.mjs +119 -29
  13. package/dist/commands.d.mts +5 -2
  14. package/dist/commands.mjs +37 -12
  15. package/dist/config.d.mts +25 -3
  16. package/dist/config.mjs +159 -33
  17. package/dist/doctor.d.mts +6 -1
  18. package/dist/doctor.mjs +78 -18
  19. package/dist/explain.d.mts +5 -0
  20. package/dist/explain.mjs +36 -1
  21. package/dist/init.d.mts +10 -0
  22. package/dist/init.mjs +133 -31
  23. package/dist/lib/color.d.mts +11 -0
  24. package/dist/lib/color.mjs +15 -0
  25. package/dist/lib/gh.d.mts +6 -0
  26. package/dist/lib/gh.mjs +11 -1
  27. package/dist/lib/listed.d.mts +3 -2
  28. package/dist/lib/listed.mjs +5 -4
  29. package/dist/poller.d.mts +1 -1
  30. package/dist/poller.mjs +9 -6
  31. package/dist/pr.mjs +9 -1
  32. package/dist/preset-commands.d.mts +2 -0
  33. package/dist/preset-commands.mjs +18 -12
  34. package/dist/preset.mjs +3 -2
  35. package/dist/setup.d.mts +3 -0
  36. package/dist/site.d.mts +3 -0
  37. package/dist/site.mjs +8 -1
  38. package/dist/status.d.mts +5 -2
  39. package/dist/status.mjs +13 -22
  40. package/dist/sync.d.mts +7 -1
  41. package/dist/sync.mjs +17 -5
  42. package/dist/ticket-fields.d.mts +84 -0
  43. package/dist/ticket-fields.mjs +374 -0
  44. package/dist/ticket.d.mts +3 -0
  45. package/dist/ticket.mjs +35 -8
  46. package/dist/tickets/github-setup.mjs +1 -1
  47. package/dist/tickets/github.mjs +69 -0
  48. package/dist/tickets/index.d.mts +8 -1
  49. package/dist/tickets/index.mjs +67 -7
  50. package/dist/tickets/types.d.mts +27 -1
  51. package/dist/tickets/types.mjs +4 -0
  52. package/dist/tools.d.mts +1 -1
  53. package/docs/builds.md +26 -13
  54. package/docs/cli.md +73 -36
  55. package/docs/configuration.md +264 -59
  56. package/docs/design.md +10 -0
  57. package/docs/developing.md +49 -18
  58. package/docs/existing-repo.md +184 -34
  59. package/docs/github/by-hand.md +13 -1
  60. package/docs/github/setup.md +14 -2
  61. package/docs/presets.md +15 -3
  62. package/docs/quick-start.md +3 -3
  63. package/docs/skills.md +3 -1
  64. package/docs/updating.md +132 -5
  65. package/docs/workflow.md +1 -1
  66. package/package.json +4 -2
  67. package/settings.schema.json +82 -20
  68. package/skills/factory-build/SKILL.md +39 -7
  69. package/skills/factory-deps/SKILL.md +6 -4
@@ -108,8 +108,8 @@ function shown(key, mapping) {
108
108
  if (c !== "none")
109
109
  return c.column;
110
110
  if (key === "ready")
111
- return "no column: builds start only when you ask";
112
- return `no column, shows in ${columnFor(STATE_KEYS[key], toColumns(mapping))}`;
111
+ return "none";
112
+ return `none, shows in ${columnFor(STATE_KEYS[key], toColumns(mapping))}`;
113
113
  }
114
114
  /** The table of each state's column, as `factory board check` words it. */
115
115
  export function table(mapping) {
@@ -119,18 +119,20 @@ export function table(mapping) {
119
119
  ...KEYS.map((k) => pad(k) + shown(k, mapping)),
120
120
  ];
121
121
  }
122
- /** What `Yes` writes under `tickets.columns`: each state whose column is
123
- * not the factory's own name. */
122
+ /** What `Yes` writes under `tickets.columns`: every state, a column init
123
+ * adds by its factory name. */
124
124
  export function written(mapping) {
125
- return KEYS.flatMap((k) => {
125
+ return KEYS.map((k) => {
126
126
  const c = mapping[k];
127
- if (c === "add")
128
- return [];
129
- if (c === "none")
130
- return [[k, "none"]];
131
- return sameName(c.column, STATE_KEYS[k]) ? [] : [[k, c.column]];
127
+ return [k, c === "none" ? "none" : c === "add" ? STATE_KEYS[k] : c.column];
132
128
  });
133
129
  }
130
+ /** Every state written with the factory's own name: a board init creates,
131
+ * one with no columns, and the answer No. */
132
+ export const FACTORY_LINES = KEYS.map((k) => [
133
+ k,
134
+ STATE_KEYS[k],
135
+ ]);
134
136
  const AGAIN_OR_WRITE = "write tickets.columns in .claude/factory.yaml yourself.";
135
137
  /** The board's columns, as init's first line about them says. */
136
138
  export const boardLine = (board, columns) => `Board ${board} has the columns ${listed(columns)}.`;
@@ -139,6 +141,14 @@ function showing(name, key, current) {
139
141
  return (KEYS.find((k) => k !== key &&
140
142
  (current[STATE_KEYS[k]] ?? []).some((c) => sameName(c, name))) ?? null);
141
143
  }
144
+ /** The "No column" choice for `key`, saying where its tickets show with
145
+ * `columns` and no column of its own, or null where it has none. */
146
+ function noColumnFor(key, columns, fromBoard) {
147
+ if (key === "backlog" || (key === "ready" && fromBoard))
148
+ return null;
149
+ const others = { ...columns, [STATE_KEYS[key]]: null };
150
+ return NO_COLUMN[key](columnFor(STATE_KEYS[key], others));
151
+ }
142
152
  /** Asks which column shows `key`, with `current` selected. */
143
153
  async function pickColumn(d, key, columns, current, noColumn) {
144
154
  const factory = STATE_KEYS[key];
@@ -154,26 +164,30 @@ async function pickColumn(d, key, columns, current, noColumn) {
154
164
  }
155
165
  const valueOf = (c) => c === "none" ? NONE : c === "add" ? ADD : `column:${c.column}`;
156
166
  const choiceOf = (v) => v === NONE ? "none" : v === ADD ? "add" : { column: v.slice(7) };
157
- /** "Change some": the states you pick, then a column for each, until no
158
- * two states share one. */
159
- async function changeSome(d, mapping, columns, fromBoard) {
167
+ /** "Change some": the states you pick, of `keys`, then a column for each,
168
+ * until no two states share one. `written` holds the states the settings
169
+ * already give, by their whole lists, which the mapping shows joined. */
170
+ async function changeSome(d, mapping, columns, fromBoard, keys = KEYS, written = {}) {
171
+ const shownBy = (m) => {
172
+ const out = toColumns(m);
173
+ for (const [k, list] of Object.entries(written))
174
+ out[STATE_KEYS[k]] = list;
175
+ return out;
176
+ };
160
177
  const m = { ...mapping };
161
178
  let picked = [];
162
179
  for (;;) {
163
- picked = await d.ask.checkbox("Which states do you want to change?", KEYS.map((k) => ({
180
+ picked = await d.ask.checkbox("Which states do you want to change?", keys.map((k) => ({
164
181
  name: `${k}: ${shown(k, m)}`,
165
182
  value: k,
166
183
  checked: picked.includes(k),
167
184
  })));
168
185
  let clash = false;
169
- for (const key of KEYS.filter((k) => picked.includes(k))) {
170
- const others = { ...m, [key]: "none" };
171
- const noColumn = key === "backlog" || (key === "ready" && fromBoard)
172
- ? null
173
- : NO_COLUMN[key](columnFor(STATE_KEYS[key], toColumns(others)));
186
+ for (const key of keys.filter((k) => picked.includes(k))) {
187
+ const noColumn = noColumnFor(key, toColumns(m), fromBoard);
174
188
  const choice = choiceOf(await pickColumn(d, key, columns, valueOf(m[key]), noColumn));
175
189
  const name = nameOf(key, choice);
176
- const other = name === null ? null : showing(name, key, toColumns(m));
190
+ const other = name === null ? null : showing(name, key, shownBy(m));
177
191
  if (other) {
178
192
  d.out(`${name} already shows ${other}. Pick another column for ${key}.`);
179
193
  clash = true;
@@ -185,17 +199,11 @@ async function changeSome(d, mapping, columns, fromBoard) {
185
199
  return m;
186
200
  }
187
201
  }
188
- /** The column step: the mapping's `tickets.columns` lines to write, none
189
- * for the factory's own columns, or 1 when init stops. */
202
+ /** The column step: the mapping's `tickets.columns` lines to write, or 1
203
+ * when init stops. */
190
204
  export async function suggestColumns(d, o) {
191
205
  d.out("");
192
206
  d.out(boardLine(o.board, o.columns));
193
- if (!d.agent.installed(d.hasCommand)) {
194
- d.out(`Matching them to the factory's six states needs ${d.label}, which is not installed.`);
195
- d.out(`Install it and run factory init again, or ${AGAIN_OR_WRITE}`);
196
- d.out("Nothing changed.");
197
- return 1;
198
- }
199
207
  d.out(`Asking ${d.label} which of them shows each of the factory's six states...`);
200
208
  const got = await d.agent.answer({
201
209
  prompt: prompt(o.columns, o.fromBoard),
@@ -231,7 +239,7 @@ export async function suggestColumns(d, o) {
231
239
  if (use === "yes")
232
240
  return written(mapping);
233
241
  if (use === "no")
234
- return "default";
242
+ return FACTORY_LINES;
235
243
  mapping = await changeSome(d, mapping, o.columns, o.fromBoard);
236
244
  }
237
245
  }
@@ -257,3 +265,85 @@ export async function askReady(d, o) {
257
265
  d.out(`${name} already shows ${other}. Pick another column for ready.`);
258
266
  }
259
267
  }
268
+ /** A board with a column of each of the factory's names: init says so,
269
+ * shows them as the board spells them, and writes them. */
270
+ export function everyColumn(d, o) {
271
+ const mapping = Object.fromEntries(KEYS.map((k) => [k, { column: onBoard(STATE_KEYS[k], o.columns) }]));
272
+ d.out("");
273
+ d.out(`Board ${o.board} has a column for each of the factory's six states:`);
274
+ d.out("");
275
+ for (const line of table(mapping))
276
+ d.out(line);
277
+ return written(mapping);
278
+ }
279
+ /** A re-run's column step for a block that leaves states out. Each state
280
+ * left out takes the board's column of its factory name, when the board
281
+ * has one no written state names, since that is the column the factory
282
+ * read for it; any other is asked for. The lines to write for the states
283
+ * left out. */
284
+ export async function fillColumns(d, o) {
285
+ const missing = KEYS.filter((k) => !(k in o.written));
286
+ const lists = {
287
+ ...o.written,
288
+ };
289
+ const now = () => Object.fromEntries(KEYS.map((k) => [STATE_KEYS[k], lists[k] ?? null]));
290
+ const mapping = {};
291
+ for (const k of KEYS)
292
+ if (k in o.written)
293
+ mapping[k] =
294
+ o.written[k] === null ? "none" : { column: o.written[k].join(", ") };
295
+ const asks = [];
296
+ for (const k of missing) {
297
+ const name = onBoard(STATE_KEYS[k], o.columns);
298
+ const other = name === null ? null : showing(name, k, now());
299
+ if (name !== null && other === null) {
300
+ mapping[k] = { column: name };
301
+ lists[k] = [name];
302
+ }
303
+ else
304
+ asks.push([
305
+ k,
306
+ name === null
307
+ ? `board ${o.board} has no ${STATE_KEYS[k]} column`
308
+ : `${name} already shows ${other}`,
309
+ ]);
310
+ }
311
+ const lines = (m) => written(m).filter(([k]) => missing.includes(k));
312
+ d.out("");
313
+ if (!asks.length) {
314
+ d.out(`Your settings give no column to ${listed(missing, "or")}.`);
315
+ d.out(`Board ${o.board} has a column of the factory's name for each:`);
316
+ d.out("");
317
+ for (const line of table(mapping))
318
+ d.out(line);
319
+ return lines(mapping);
320
+ }
321
+ for (const [k, why] of asks) {
322
+ d.out(`Your settings give no column to ${k}, and ${why}.`);
323
+ for (;;) {
324
+ const choice = choiceOf(await pickColumn(d, k, o.columns, ADD, noColumnFor(k, now(), o.fromBoard)));
325
+ const name = nameOf(k, choice);
326
+ const other = name === null ? null : showing(name, k, now());
327
+ if (other === null) {
328
+ mapping[k] = choice;
329
+ lists[k] = name === null ? null : [name];
330
+ break;
331
+ }
332
+ d.out(`${name} already shows ${other}. Pick another column for ${k}.`);
333
+ }
334
+ }
335
+ let m = mapping;
336
+ for (;;) {
337
+ d.out("");
338
+ for (const line of table(m))
339
+ d.out(line);
340
+ d.out("");
341
+ const use = await d.ask.select("Use these columns?", [
342
+ { name: "Yes", value: "yes" },
343
+ { name: "Change some", value: "change" },
344
+ ], "yes");
345
+ if (use === "yes")
346
+ return lines(m);
347
+ m = await changeSome(d, m, o.columns, o.fromBoard, missing, o.written);
348
+ }
349
+ }
@@ -1,3 +1,4 @@
1
+ import { type Paint } from "./lib/color.mts";
1
2
  import { type Settings } from "./config.mts";
2
3
  export type Deps = {
3
4
  /** The repository's root, where every command runs. */
@@ -8,9 +9,11 @@ export type Deps = {
8
9
  exec: (command: string, cwd: string, env: Record<string, string>) => number;
9
10
  out: (line: string) => void;
10
11
  err: (line: string) => void;
12
+ paint?: Paint;
11
13
  };
12
14
  /** `argv` is the command's name, then its arguments. */
13
15
  export declare function main(argv: string[], d: Deps): Promise<number>;
14
- /** `factory gate`, `factory test-one`, `factory end-to-end`, and
15
- * `factory specs check`, the last as `specs-check`. */
16
+ /** `factory gate`, `factory test-one`, `factory end-to-end`,
17
+ * `factory specs check`, and `factory specs change-name`, the last two as
18
+ * `specs-check` and `specs-change-name`. */
16
19
  export declare function run(argv: string[]): Promise<number>;
package/dist/commands.mjs CHANGED
@@ -11,12 +11,14 @@
11
11
  // environment, `end-to-end` FILE, and the spec check DO_NOT_TRACK=1. An
12
12
  // argument a command does not know prints its usage and exits 2.
13
13
  import { spawnSync } from "node:child_process";
14
+ import { colorOn, painter, plain } from "./lib/color.mjs";
14
15
  import { defaultDeps, loadSettings, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
15
16
  const USAGE = {
16
17
  gate: "Usage: factory gate",
17
18
  "test-one": "Usage: factory test-one FILE [NAME]",
18
19
  "end-to-end": "Usage: factory end-to-end FILE [--times K]",
19
20
  "specs-check": "Usage: factory specs check",
21
+ "specs-change-name": "Usage: factory specs change-name N",
20
22
  };
21
23
  /** What `factory end-to-end` was asked: the file, and how many runs when
22
24
  * `--times` is given; null when the arguments are not ones it knows. */
@@ -49,6 +51,10 @@ export async function main(argv, d) {
49
51
  if (args.length > 0)
50
52
  return usage();
51
53
  }
54
+ else if (name === "specs-change-name") {
55
+ if (args.length !== 1 || !/^[1-9]\d*$/.test(args[0]))
56
+ return usage();
57
+ }
52
58
  else if (name === "test-one") {
53
59
  if (args.length < 1 || args.length > 2)
54
60
  return usage();
@@ -67,6 +73,15 @@ export async function main(argv, d) {
67
73
  d.err(e.message);
68
74
  return 1;
69
75
  }
76
+ const paint = d.paint ?? plain;
77
+ /** The command's own closing line, after the output passed through. */
78
+ const ended = (status, passed, failed) => {
79
+ if (status === 0)
80
+ d.out(`${paint("green", "✓")} ${passed}`);
81
+ else
82
+ d.err(`${paint("red", "✗")} ${failed}`);
83
+ return status;
84
+ };
70
85
  const notSet = (key) => {
71
86
  d.err(`commands.${key} is not set`);
72
87
  return 1;
@@ -78,41 +93,49 @@ export async function main(argv, d) {
78
93
  }
79
94
  for (const command of s.commands.gate) {
80
95
  d.out(`$ ${command}`);
81
- if (d.exec(command, d.root, {}) !== 0) {
82
- d.err(`gate failed on: ${command}`);
83
- return 1;
84
- }
96
+ if (d.exec(command, d.root, {}) !== 0)
97
+ return ended(1, "", `The gate failed on: ${command}`);
85
98
  }
86
- return 0;
99
+ return ended(0, "Every gate command passed.", "");
87
100
  }
88
101
  if (name === "test-one") {
89
102
  if (s.commands.testOne === null)
90
103
  return notSet("test-one");
91
104
  const [file, test = ""] = args;
92
- return d.exec(s.commands.testOne, d.root, { FILE: file, NAME: test });
105
+ return ended(d.exec(s.commands.testOne, d.root, { FILE: file, NAME: test }), "The test passed.", "The test failed.");
93
106
  }
94
107
  if (name === "end-to-end") {
95
108
  const { file, times } = e2e;
96
109
  const command = s.commands.endToEnd;
97
110
  if (command === null)
98
111
  return notSet("end-to-end");
112
+ const test = (status) => ended(status, "The test passed.", "The test failed.");
99
113
  if (times === null)
100
- return d.exec(command, d.root, { FILE: file });
114
+ return test(d.exec(command, d.root, { FILE: file }));
101
115
  for (let run = 1; run <= times; run++)
102
116
  if (d.exec(command, d.root, { FILE: file }) !== 0) {
103
117
  d.err(`failed on run ${run} of ${times}`);
104
- return 1;
118
+ return test(1);
105
119
  }
120
+ return test(0);
121
+ }
122
+ if (name === "specs-change-name") {
123
+ if (s.specs === "none") {
124
+ d.err("specs are off: there is no spec change to name");
125
+ return 1;
126
+ }
127
+ d.out(`issue-${args[0]}`);
106
128
  return 0;
107
129
  }
108
130
  if (s.specCheck === null) {
109
131
  d.out("specs are off");
110
132
  return 0;
111
133
  }
112
- return d.exec(s.specCheck, d.root, { DO_NOT_TRACK: "1" });
134
+ return ended(d.exec(s.specCheck, d.root, { DO_NOT_TRACK: "1" }), "The specs check passed.", "The specs check failed.");
113
135
  }
114
- /** `factory gate`, `factory test-one`, `factory end-to-end`, and
115
- * `factory specs check`, the last as `specs-check`. */
136
+ /** `factory gate`, `factory test-one`, `factory end-to-end`,
137
+ * `factory specs check`, and `factory specs change-name`, the last two as
138
+ * `specs-check` and `specs-change-name`. */
116
139
  export async function run(argv) {
117
140
  const root = repoRoot();
118
141
  return main(argv, {
@@ -120,10 +143,12 @@ export async function run(argv) {
120
143
  settings: () => loadSettings(defaultDeps(root)),
121
144
  exec: (command, cwd, env) => spawnSync("bash", ["-c", command], {
122
145
  cwd,
123
- env: { ...process.env, ...env },
146
+ // npm 11 prints a notice line for every script and npx it runs.
147
+ env: { npm_config_loglevel: "warn", ...process.env, ...env },
124
148
  stdio: ["ignore", "inherit", "inherit"],
125
149
  }).status ?? 1,
126
150
  out: (line) => console.log(line),
127
151
  err: (line) => console.error(line),
152
+ paint: painter(colorOn()),
128
153
  });
129
154
  }
package/dist/config.d.mts CHANGED
@@ -1,4 +1,6 @@
1
1
  #!/usr/bin/env node
2
+ import { type Paint } from "./lib/color.mts";
3
+ import { type FieldMapping } from "./ticket-fields.mts";
2
4
  import { type Built } from "./tool-names.mts";
3
5
  import { type Watch, type Columns, type StateKey } from "./lib/work-status.mts";
4
6
  export declare class SettingsError extends Error {
@@ -52,10 +54,17 @@ export type Settings = {
52
54
  columns: Record<StateKey, readonly string[] | null>;
53
55
  /** The board's field for each of three the sync writes, null for none. */
54
56
  fields: Record<FieldKey, string | null>;
57
+ /** Each ticket-side key under `tickets.fields`, the four factory fields
58
+ * first and then any heading of the repository's own, with the ticket
59
+ * field that holds it, or null for the description. */
60
+ ticketFields: FieldMapping;
55
61
  };
56
- /** Where pull requests are. */
62
+ /** Where pull requests are, and the pattern a build's branch is named
63
+ * by. The pattern is null only when init reads settings without it, to
64
+ * ask for it. */
57
65
  codeHost: {
58
66
  type: string;
67
+ branchName: string | null;
59
68
  };
60
69
  builds: {
61
70
  /** What notices a card moved to Ready and starts its build. */
@@ -167,10 +176,20 @@ export declare function siteLines(site: Site): string[];
167
176
  * above `from` that holds `.git`, or `from` itself when none does. */
168
177
  export declare function repoRoot(from?: string): string;
169
178
  export declare const SETTINGS_FILE = ".claude/factory.yaml";
179
+ /** A key under `tickets.fields` naming a heading of the repository's own. */
180
+ export declare const OWN_HEADING: RegExp;
181
+ export declare const BRANCH_PLACEHOLDERS: readonly ["ticket", "user"];
182
+ /** Why a branch name pattern can't be used, in the words the settings
183
+ * check prints after its key, or null when it can. The placeholders are
184
+ * filled before git's rules are applied, so only the pattern's own text
185
+ * can break them. */
186
+ export declare function branchPatternFault(pattern: string): string | null;
170
187
  /** The settings with every default filled in. Throws a SettingsError naming
171
188
  * the key on anything unsound. `exists` says whether a path from the root
172
189
  * exists, for the plugins' files. */
173
- export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built): Settings;
190
+ export declare function parseSettings(raw: unknown, exists: (path: string) => boolean, built?: Built, { partial }?: {
191
+ partial?: boolean;
192
+ }): Settings;
174
193
  /** One line for each pattern that matches none of `files`: a stale pattern
175
194
  * is how a policy rots. */
176
195
  export declare function patternWarnings(s: Settings, files: string[]): string[];
@@ -185,6 +204,7 @@ export type Deps = {
185
204
  loadYaml: () => Promise<YamlLoad>;
186
205
  out: (line: string) => void;
187
206
  err: (line: string) => void;
207
+ paint?: Paint;
188
208
  /** Where the settings come from when every command reads the lock:
189
209
  * `check` stops on a stale one. Unset, they are resolved from the files
190
210
  * the lock is made from. */
@@ -226,9 +246,11 @@ export declare function parseChoices(text: string | null, load: YamlLoad): Recor
226
246
  * `presets`, and `.claude/factory.yaml`, as `factory sync` combines them
227
247
  * into the lock. `factoryFile` and `ownFile` say which preset files are
228
248
  * kept back: the factory's own, and the repository's own. */
229
- export declare function resolveFiles(d: Deps, keep?: {
249
+ export declare function resolveFiles(d: Deps, { partial, ...keep }?: {
230
250
  factoryFile?: (path: string) => boolean;
231
251
  ownFile?: (path: string) => boolean;
252
+ /** Read settings init fills in, as `parseSettings` takes it. */
253
+ partial?: boolean;
232
254
  }): Promise<Resolved>;
233
255
  /** Why the lock `d` reads is stale, or null when it is current or `d`
234
256
  * reads none. */