@davidbyoung/software-factory 0.1.10 → 0.1.11

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 (51) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +3 -4
  4. package/dist/cli.mjs +17 -4
  5. package/dist/code-host/github.mjs +2 -0
  6. package/dist/code-host/types.d.mts +4 -0
  7. package/dist/commands.d.mts +7 -2
  8. package/dist/commands.mjs +86 -16
  9. package/dist/config.d.mts +3 -4
  10. package/dist/config.mjs +7 -8
  11. package/dist/init.d.mts +11 -0
  12. package/dist/init.mjs +56 -1
  13. package/dist/lib/work-status.d.mts +5 -5
  14. package/dist/lib/work-status.mjs +7 -8
  15. package/dist/merge-policy.mjs +7 -3
  16. package/dist/pr.d.mts +8 -6
  17. package/dist/pr.mjs +39 -22
  18. package/dist/review-verdict.d.mts +22 -4
  19. package/dist/review-verdict.mjs +55 -17
  20. package/dist/specs/index.d.mts +6 -0
  21. package/dist/specs/index.mjs +15 -0
  22. package/dist/specs/openspec.d.mts +2 -0
  23. package/dist/specs/openspec.mjs +78 -0
  24. package/dist/specs/types.d.mts +53 -0
  25. package/dist/specs/types.mjs +4 -0
  26. package/dist/ticket.d.mts +3 -1
  27. package/dist/ticket.mjs +36 -3
  28. package/dist/tickets/github-access.d.mts +5 -0
  29. package/dist/tickets/github-access.mjs +22 -0
  30. package/dist/tickets/github.mjs +2 -0
  31. package/dist/tickets/types.d.mts +4 -0
  32. package/dist/tool-names.d.mts +2 -0
  33. package/dist/tool-names.mjs +3 -0
  34. package/dist/tools.d.mts +2 -0
  35. package/dist/tools.mjs +3 -0
  36. package/docs/builds.md +4 -1
  37. package/docs/cli.md +19 -4
  38. package/docs/configuration.md +50 -38
  39. package/docs/developing.md +104 -59
  40. package/docs/existing-repo.md +4 -3
  41. package/docs/github/setup.md +20 -3
  42. package/docs/glossary.md +7 -6
  43. package/docs/limitations.md +8 -5
  44. package/docs/updating.md +18 -0
  45. package/docs/workflow.md +25 -8
  46. package/package.json +1 -1
  47. package/rules.md +36 -30
  48. package/skills/factory-address-review/SKILL.md +40 -39
  49. package/skills/factory-build/SKILL.md +46 -53
  50. package/skills/factory-refine/SKILL.md +30 -22
  51. package/skills/factory-resolve-conflicts/SKILL.md +8 -7
@@ -21,7 +21,7 @@ Whichever skill refined the issue, `factory-refine` or the repository's own
21
21
  refiner, read what it left against the same list, what refinement
22
22
  delivers: the `spec` label decided, each build order recorded as a
23
23
  blocked-by relationship, and a body with the sections `factory-build`
24
- reads, in the shape it copies into an OpenSpec change. "What to look for"
24
+ reads, in the shape a spec tool takes when there is one. "What to look for"
25
25
  says how each is checked.
26
26
 
27
27
  **Read-only.** Never comment on, edit, or label the issue, and never change a
@@ -38,16 +38,18 @@ unverified, for the builder to check.
38
38
  `For the builder` on the `spec` track, or `Acceptance criteria` without
39
39
  the label. An issue without `spec` has no `For the builder`: the area's
40
40
  rules ("Rules by area" in `CLAUDE.md`) say how it is built.
41
- 2. The latest refinement round in the comments, and any reply from the
42
- repository owner after it. Until the owner replies, each proposed default
41
+ 2. The latest refinement round in the comments, and any reply
42
+ `npx --no-install factory ticket answers N` prints after it. Until it prints one, each proposed default
43
43
  stands.
44
44
  3. `CLAUDE.md`, the files it imports, and the `CLAUDE.md` for every area
45
45
  the notes name.
46
46
  4. Every file the notes name, to check that it exists and works the way the
47
47
  notes say.
48
- 5. On the `spec` track, `openspec/specs/<capability>/spec.md` for every
49
- capability the Spec names, to check that a "modified" line changes what
50
- the spec says today and a "No longer" line names a requirement it has.
48
+ 5. On the `spec` track, the file `npx --no-install factory specs list`
49
+ prints for every capability the Spec names, to check that a "modified"
50
+ line changes what the spec says today and a "No longer" line names a
51
+ requirement it has. With no spec tool it lists none: check those lines
52
+ against the code instead.
51
53
 
52
54
  ## The question you are answering
53
55
 
@@ -71,8 +73,8 @@ anything?
71
73
  - **A blocking step with no owner,** such as an account, key, or form that
72
74
  only the owner can create, with no word on whether it exists.
73
75
  - **A conflict** between the criteria, the notes, and the repository's rules.
74
- - **A build order with no relationship behind it.** The body or a comment
75
- by the repository owner says to build this after another issue that is
76
+ - **A build order with no relationship behind it.** The body or an answer
77
+ `factory ticket answers N` prints says to build this after another issue that is
76
78
  still open, and
77
79
  `npx --no-install factory ticket blockers N` does not list it. `factory-build` stops only on a recorded relationship, so
78
80
  the prose alone lets the build start too soon. Word the finding as:
@@ -80,13 +82,16 @@ anything?
80
82
  `.claude/factory/rules.md`
81
83
  and needs the relationship, or the sentence comes out. A prerequisite
82
84
  that is already closed is not a finding.
83
- - **A missing track or shape.** When `npx --no-install factory config get specs`
84
- prints `openspec`, a change a user would see needs the `spec` label. On the `spec` track the body needs "Decisions", "Spec" grouped by
85
- capability, and "For the builder" with "Design" and "Tasks", which
86
- `factory-build` copies into an OpenSpec change; also a Spec line that could
87
- not stand as one WHEN/THEN scenario on its own, a capability named unlike
88
- `openspec/specs/`, or a "modified" line that restates the current spec
89
- instead of changing it. Without the label the body needs "Decisions" and
85
+ - **A missing track or shape.** A change a user would see, and that is not
86
+ small, needs the `spec` label, whatever the spec tool. On the `spec`
87
+ track the body needs "Decisions", "Spec" grouped by capability, and "For
88
+ the builder" with "Design" and "Tasks", which `factory-build` builds
89
+ from and, with a spec tool, writes into the repository's specs; also a
90
+ Spec line that could not stand as one WHEN/THEN scenario on its own, a
91
+ capability named unlike those `factory specs list` prints (with no
92
+ spec tool, which lists none, one not in lowercase words joined by
93
+ hyphens), or a
94
+ "modified" line that restates the current spec instead of changing it. Without the label the body needs "Decisions" and
90
95
  "Acceptance criteria", and a missing "For the builder" is not a finding:
91
96
  ask only what the criteria and the area's rules leave open.
92
97
 
package/dist/board.d.mts CHANGED
@@ -79,7 +79,7 @@ export type Plan = {
79
79
  /** What each issue's fields should hold, and which writes get them there.
80
80
  * A card's Session is an Actions run's page, which `runPage` gives for its
81
81
  * ID, and any other session as it is. */
82
- export declare function planSync(snapshot: RepoSnapshot, board: Board, repository: string, runPage: (id: string) => string, cfg?: BoardConfig): Plan[];
82
+ export declare function planSync(snapshot: RepoSnapshot, board: Board, runPage: (id: string) => string, cfg?: BoardConfig): Plan[];
83
83
  export declare function logLine(plan: Plan): string;
84
84
  export type Comment = {
85
85
  issue: number;
package/dist/board.mjs CHANGED
@@ -256,13 +256,12 @@ export function boardReport(number, board, cfg, settings, paint = plain) {
256
256
  /** What each issue's fields should hold, and which writes get them there.
257
257
  * A card's Session is an Actions run's page, which `runPage` gives for its
258
258
  * ID, and any other session as it is. */
259
- export function planSync(snapshot, board, repository, runPage, cfg = DEFAULT_BOARD) {
260
- const owner = repository.split("/")[0];
259
+ export function planSync(snapshot, board, runPage, cfg = DEFAULT_BOARD) {
261
260
  const everyPull = [...snapshot.pulls, ...(snapshot.donePulls ?? [])];
262
261
  const fields = checkFields(board.fields, cfg);
263
262
  return snapshot.issues.map((issue) => {
264
263
  const derived = derive(issue, cardOf(board, issue.number, cfg.columns), snapshot.pulls, cfg.columns);
265
- const listPrice = issueCost(issue, everyPull, owner);
264
+ const listPrice = issueCost(issue, everyPull);
266
265
  const cost = listPrice === null
267
266
  ? null
268
267
  : Math.round(subscriptionDollars(listPrice) * 100) / 100;
@@ -421,7 +420,7 @@ async function apply(saved, board, d, write) {
421
420
  for (const line of inspected.lines)
422
421
  if (line.text.startsWith("skipped"))
423
422
  d.out(`${line.label} ${line.text}`);
424
- const plans = planSync(snapshotOf(saved, d.now()), board, d.repository, d.runPage, d.config);
423
+ const plans = planSync(snapshotOf(saved, d.now()), board, d.runPage, d.config);
425
424
  for (const plan of plans) {
426
425
  d.out(logLine(plan));
427
426
  if (!write || plan.writes.length === 0)
package/dist/cli.mjs CHANGED
@@ -16,6 +16,7 @@ const TICKET_STEPS = [
16
16
  "end",
17
17
  "cost",
18
18
  "view",
19
+ "answers",
19
20
  "list",
20
21
  "edit",
21
22
  "comment",
@@ -81,7 +82,7 @@ const PR_ARGS = {
81
82
  review: "N REVIEW",
82
83
  reply: "N COMMENT --body-file FILE",
83
84
  resolve: "N COMMENT",
84
- comments: "N [--author LOGIN] [--contains TEXT] [--json]",
85
+ comments: "N [--author LOGIN] [--contains TEXT] [--from-approvers] [--json]",
85
86
  comment: "N --body-file FILE",
86
87
  "comment-view": "ID",
87
88
  label: "N --add LABEL | --remove LABEL",
@@ -207,9 +208,19 @@ export const COMMANDS = [
207
208
  run: async (argv) => (await import("./commands.mjs")).run(["specs-check", ...argv]),
208
209
  },
209
210
  {
210
- words: ["specs", "change-name"],
211
+ words: ["specs", "list"],
212
+ args: "",
213
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-list", ...argv]),
214
+ },
215
+ {
216
+ words: ["specs", "new"],
217
+ args: "N",
218
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-new", ...argv]),
219
+ },
220
+ {
221
+ words: ["specs", "finish"],
211
222
  args: "N",
212
- run: async (argv) => (await import("./commands.mjs")).run(["specs-change-name", ...argv]),
223
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-finish", ...argv]),
213
224
  },
214
225
  {
215
226
  words: ["default-branch"],
@@ -346,8 +357,10 @@ const USAGE = [
346
357
  ["gate", "Run the commands under commands.gate"],
347
358
  ["test-one FILE [NAME]", "Run one test file, or one test in it"],
348
359
  ["end-to-end FILE", "Run one end-to-end spec"],
360
+ ["specs list", "List the specs your spec tool keeps"],
361
+ ["specs new N", "Start ticket N's spec"],
349
362
  ["specs check", "Check your written specs"],
350
- ["specs change-name N", "Print the name of ticket N's spec change"],
363
+ ["specs finish N", "Fold ticket N's spec into your specs"],
351
364
  ["default-branch", "Print the default branch's name"],
352
365
  ],
353
366
  ],
@@ -6,6 +6,7 @@
6
6
  // issues API, so those calls are here too, not in the ticket adapter.
7
7
  import { GhError } from "../lib/gh.mjs";
8
8
  import { NotFoundError } from "../tickets/types.mjs";
9
+ import { writeAccess } from "../tickets/github-access.mjs";
9
10
  import { statusOf } from "../tickets/transport.mjs";
10
11
  import { NeedsScopeError, NotSignedInError } from "./types.mjs";
11
12
  /** What a check wrote about its result: its title and its summary. */
@@ -258,6 +259,7 @@ export function githubCodeHost(o) {
258
259
  const repo = await t.rest("GET", API);
259
260
  return repo.owner.type === "Organization";
260
261
  },
262
+ canWrite: (login) => writeAccess(t, o.repository, login),
261
263
  async checkRuns(sha) {
262
264
  const answer = await t.rest("GET", `${API}/commits/${sha}/check-runs?per_page=100`);
263
265
  return answer.check_runs.map((c) => ({
@@ -134,6 +134,10 @@ export type CodeHost = {
134
134
  isPrivate(): Promise<boolean>;
135
135
  /** Whether an organization owns the repository, rather than a person. */
136
136
  ownerIsOrganization(): Promise<boolean>;
137
+ /** Whether the account can write to the repository: an approver, whose
138
+ * words a session takes as instructions. Rejects when the code host
139
+ * cannot say. */
140
+ canWrite(login: string): Promise<boolean>;
137
141
  /** The check runs on a commit, without its statuses. */
138
142
  checkRuns(sha: string): Promise<CheckRun[]>;
139
143
  /** The statuses on a commit, without its check runs. */
@@ -1,5 +1,6 @@
1
1
  import { type Paint } from "./lib/color.mts";
2
2
  import { type Settings } from "./config.mts";
3
+ import { type SpecTools } from "./specs/index.mts";
3
4
  export type Deps = {
4
5
  /** The repository's root, where every command runs. */
5
6
  root: string;
@@ -10,10 +11,14 @@ export type Deps = {
10
11
  out: (line: string) => void;
11
12
  err: (line: string) => void;
12
13
  paint?: Paint;
14
+ specTools: SpecTools;
15
+ /** Ticket `id`'s labels; throws when it can't be read. */
16
+ labels: (settings: Settings, id: number) => Promise<string[]>;
13
17
  };
14
18
  /** `argv` is the command's name, then its arguments. */
15
19
  export declare function main(argv: string[], d: Deps): Promise<number>;
20
+ export declare const NO_SPEC_TOOL = "No spec tool (specs: none): each ticket holds its own spec.";
16
21
  /** `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`. */
22
+ * and `factory specs check`, `list`, `new`, and `finish`, as `specs-check`
23
+ * and the rest. */
19
24
  export declare function run(argv: string[]): Promise<number>;
package/dist/commands.mjs CHANGED
@@ -6,19 +6,30 @@
6
6
  // factory end-to-end FILE [--times K] # commands.end-to-end, K times in a row
7
7
  // factory specs check # specs.check
8
8
  //
9
+ // and the commands that reach the spec tool `specs` names:
10
+ //
11
+ // factory specs list # each spec it keeps
12
+ // factory specs new N # start ticket N's spec
13
+ // factory specs finish N # fold ticket N's spec in
14
+ //
9
15
  // Each command runs with bash from the repository's root, with its output
10
16
  // passed through and no standard input. `test-one` gets FILE and NAME in its
11
- // environment, `end-to-end` FILE, and the spec check DO_NOT_TRACK=1. An
12
- // argument a command does not know prints its usage and exits 2.
17
+ // environment, `end-to-end` FILE, and the spec check the spec tool's
18
+ // environment. An argument a command does not know prints its usage and
19
+ // exits 2.
13
20
  import { spawnSync } from "node:child_process";
14
21
  import { colorOn, painter, plain } from "./lib/color.mjs";
15
22
  import { defaultDeps, loadSettings, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
23
+ import { specTools } from "./specs/index.mjs";
24
+ import { openTickets } from "./tickets/index.mjs";
16
25
  const USAGE = {
17
26
  gate: "Usage: factory gate",
18
27
  "test-one": "Usage: factory test-one FILE [NAME]",
19
28
  "end-to-end": "Usage: factory end-to-end FILE [--times K]",
20
29
  "specs-check": "Usage: factory specs check",
21
- "specs-change-name": "Usage: factory specs change-name N",
30
+ "specs-list": "Usage: factory specs list",
31
+ "specs-new": "Usage: factory specs new N",
32
+ "specs-finish": "Usage: factory specs finish N",
22
33
  };
23
34
  /** What `factory end-to-end` was asked: the file, and how many runs when
24
35
  * `--times` is given; null when the arguments are not ones it knows. */
@@ -47,11 +58,13 @@ export async function main(argv, d) {
47
58
  return 2;
48
59
  };
49
60
  const e2e = name === "end-to-end" ? endToEndArgs(args) : null;
50
- if (name === "gate" || name === "specs-check") {
61
+ if (name === "gate" || name === "specs-check" || name === "specs-list") {
51
62
  if (args.length > 0)
52
63
  return usage();
53
64
  }
54
- else if (name === "specs-change-name") {
65
+ else if (name === "specs-new" || name === "specs-finish") {
66
+ // A ticket as the ticket system writes it: GitHub's, the only one
67
+ // built, are whole numbers.
55
68
  if (args.length !== 1 || !/^[1-9]\d*$/.test(args[0]))
56
69
  return usage();
57
70
  }
@@ -119,23 +132,72 @@ export async function main(argv, d) {
119
132
  }
120
133
  return test(0);
121
134
  }
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]}`);
135
+ const tool = d.specTools[s.specs];
136
+ if (s.specs === "none" || !tool) {
137
+ d.out(`${paint("dim", "-")} ${NO_SPEC_TOOL}`);
128
138
  return 0;
129
139
  }
130
- if (s.specCheck === null) {
131
- d.out("specs are off");
140
+ if (name === "specs-check")
141
+ return ended(d.exec(s.specCheck, d.root, tool.env), "The specs check passed.", "The specs check failed.");
142
+ if (name === "specs-list") {
143
+ const specs = tool.list(d.root);
144
+ d.out(`specs: ${s.specs}`);
145
+ if (specs.length === 0)
146
+ d.out(" none yet");
147
+ const width = Math.max(0, ...specs.map((x) => x.name.length));
148
+ for (const x of specs)
149
+ d.out(` ${x.name.padEnd(width)} ${x.path}`);
150
+ return 0;
151
+ }
152
+ const id = args[0];
153
+ const failed = (line) => {
154
+ d.err(`${paint("red", "✗")} ${line}`);
155
+ return 1;
156
+ };
157
+ if (name === "specs-finish") {
158
+ if (!tool.started(d.root, id)) {
159
+ if (tool.finished(d.root, id)) {
160
+ d.out(`${paint("green", "✓")} Ticket ${id}'s spec is already folded into ${tool.foldsInto}.`);
161
+ return 0;
162
+ }
163
+ return failed(`Ticket ${id} has no spec started: run factory specs new ${id} first.`);
164
+ }
165
+ if (tool.finish(d.root, id) !== 0)
166
+ return failed(`Could not fold ticket ${id}'s spec into ${tool.foldsInto}.`);
167
+ d.out(`${paint("green", "✓")} Folded ticket ${id}'s spec into ${tool.foldsInto}.`);
132
168
  return 0;
133
169
  }
134
- return ended(d.exec(s.specCheck, d.root, { DO_NOT_TRACK: "1" }), "The specs check passed.", "The specs check failed.");
170
+ let labels;
171
+ try {
172
+ labels = await d.labels(s, Number(id));
173
+ }
174
+ catch (e) {
175
+ d.err(e instanceof Error ? e.message : String(e));
176
+ return 1;
177
+ }
178
+ if (!tool.runs(d.root))
179
+ return failed(`${tool.name} is not installed: run factory init, which installs it.`);
180
+ const folder = tool.folder(id);
181
+ if (tool.started(d.root, id))
182
+ d.out(`Ticket ${id}'s spec is already started in ${folder}`);
183
+ else {
184
+ if (tool.start(d.root, id) !== 0)
185
+ return failed(`Could not start ticket ${id}'s spec in ${folder}`);
186
+ d.out(`Started ticket ${id}'s spec in ${folder}`);
187
+ }
188
+ const files = tool.files(id, labels.includes("spec"));
189
+ const width = Math.max(...files.map((f) => f.path.length)) + 2;
190
+ const kinds = Math.max(...files.map((f) => f.kind.length));
191
+ d.out(`Write each file from ticket ${id}'s body:`);
192
+ for (const f of files)
193
+ d.out(` ${f.kind.padEnd(kinds)} ${f.path.padEnd(width)}${f.what}`);
194
+ d.out(`Then: ${tool.then}`);
195
+ return 0;
135
196
  }
197
+ export const NO_SPEC_TOOL = "No spec tool (specs: none): each ticket holds its own spec.";
136
198
  /** `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`. */
199
+ * and `factory specs check`, `list`, `new`, and `finish`, as `specs-check`
200
+ * and the rest. */
139
201
  export async function run(argv) {
140
202
  const root = repoRoot();
141
203
  return main(argv, {
@@ -150,5 +212,13 @@ export async function run(argv) {
150
212
  out: (line) => console.log(line),
151
213
  err: (line) => console.error(line),
152
214
  paint: painter(colorOn()),
215
+ specTools: specTools(),
216
+ labels: async (settings, id) => {
217
+ const { tickets } = await openTickets(settings, {
218
+ repository: settings.repository,
219
+ board: null,
220
+ });
221
+ return (await tickets.read(id)).labels;
222
+ },
153
223
  });
154
224
  }
package/dist/config.d.mts CHANGED
@@ -26,7 +26,8 @@ export declare const TRIGGERS: readonly ["own-server", "github-action", "manual"
26
26
  /** How often the scheduled poller may check the board, in minutes: each
27
27
  * divides an hour, so a schedule every N minutes keeps an even beat. */
28
28
  export declare const POLL_MINUTES: readonly [5, 10, 15, 30, 60];
29
- export declare const SPECS: readonly ["none", "openspec"];
29
+ /** The values `specs` takes: none, or a spec tool built. */
30
+ export declare const SPECS: string[];
30
31
  declare const FIELD_DEFAULTS: {
31
32
  readonly session: "Session";
32
33
  readonly "runs-in": "Runs in";
@@ -74,7 +75,7 @@ export type Settings = {
74
75
  /** How often the scheduled poller checks the board. */
75
76
  pollMinutes: (typeof POLL_MINUTES)[number];
76
77
  };
77
- specs: (typeof SPECS)[number];
78
+ specs: string;
78
79
  /** The command that checks the specs, or null when `specs` is none. */
79
80
  specCheck: string | null;
80
81
  /** Every command a build runs, each from the repository's root. */
@@ -160,8 +161,6 @@ export type Accessibility = (typeof ACCESSIBILITY)[number];
160
161
  export declare const SITE_AGENT = "factory-ui-reviewer";
161
162
  /** The agent that needs `commands.end-to-end`. */
162
163
  export declare const E2E_AGENT = "factory-e2e-reviewer";
163
- /** The spec check where `specs.type` is openspec and none is written. */
164
- export declare const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
165
164
  /** `commands.relock` where none is written. */
166
165
  export declare const DEFAULT_RELOCK = "npm install";
167
166
  export declare const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
package/dist/config.mjs CHANGED
@@ -91,7 +91,8 @@ export const TRIGGERS = ["own-server", "github-action", "manual"];
91
91
  /** How often the scheduled poller may check the board, in minutes: each
92
92
  * divides an hour, so a schedule every N minutes keeps an even beat. */
93
93
  export const POLL_MINUTES = [5, 10, 15, 30, 60];
94
- export const SPECS = ["none", "openspec"];
94
+ /** The values `specs` takes: none, or a spec tool built. */
95
+ export const SPECS = ["none", ...Object.keys(BUILT.specs)];
95
96
  const FIELD_DEFAULTS = {
96
97
  session: "Session",
97
98
  "runs-in": "Runs in",
@@ -119,8 +120,6 @@ export const ACCESSIBILITY = [
119
120
  export const SITE_AGENT = "factory-ui-reviewer";
120
121
  /** The agent that needs `commands.end-to-end`. */
121
122
  export const E2E_AGENT = "factory-e2e-reviewer";
122
- /** The spec check where `specs.type` is openspec and none is written. */
123
- export const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
124
123
  /** `commands.relock` where none is written. */
125
124
  export const DEFAULT_RELOCK = "npm install";
126
125
  export const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
@@ -645,12 +644,12 @@ export function parseSettings(raw, exists, built = BUILT, { partial = false } =
645
644
  const fieldNames = names(boardFields, "tickets.fields", FIELD_DEFAULTS);
646
645
  const ticketFields = ticketFieldsOf(rawFields);
647
646
  const specsBlock = typed(top.specs ?? "none", "specs");
648
- const specs = oneOf(specsBlock.type, "specs", SPECS, "none");
649
- if (specsBlock.check !== undefined && specs !== "openspec")
647
+ const specs = oneOf(specsBlock.type, "specs", ["none", ...Object.keys(built.specs)], "none");
648
+ if (specsBlock.check !== undefined && specs === "none")
650
649
  throw new SettingsError(`${SETTINGS_FILE}: specs.check needs specs.type: openspec`);
651
- const specCheck = specs === "openspec"
652
- ? (command(specsBlock.check, "specs.check") ?? OPENSPEC_CHECK)
653
- : null;
650
+ const specCheck = specs === "none"
651
+ ? null
652
+ : (command(specsBlock.check, "specs.check") ?? built.specs[specs]);
654
653
  const autoMerge = object(top["auto-merge"], "auto-merge");
655
654
  const prReview = top["pr-review"] === undefined
656
655
  ? null
package/dist/init.d.mts CHANGED
@@ -50,12 +50,23 @@ export type InitDeps = {
50
50
  /** The branch name a preset in effect supplies to settings that read
51
51
  * as `settingsText`, or null for none. */
52
52
  presetBranchName: (settingsText: string) => Promise<string | null>;
53
+ /** The spec tool a preset in effect names for settings that read as
54
+ * `settingsText`, \`none\` included, or null when none names one. */
55
+ presetSpecs: (settingsText: string) => Promise<string | null>;
56
+ /** Runs an install from the root; its status and standard error. */
57
+ install: (argv: string[]) => Promise<{
58
+ status: number;
59
+ stderr: string;
60
+ }>;
53
61
  };
54
62
  /** The branch name a preset in effect supplies to the settings `text`
55
63
  * of the repository at `root`, or null for none. Settings whose presets
56
64
  * can't be read get the question: the check that follows says what is
57
65
  * wrong with them. */
58
66
  export declare const presetBranchNameAt: (root: string) => (text: string) => Promise<string | null>;
67
+ /** The spec tool a preset in effect names, as `presetBranchNameAt` finds
68
+ * a branch name. */
69
+ export declare const presetSpecsAt: (root: string) => (text: string) => Promise<string | null>;
59
70
  /** The repository and code host a remote's address names, or null for one
60
71
  * on a code host the factory does not support. */
61
72
  export declare function parseRemote(url: string, tools?: Registry): {
package/dist/init.mjs CHANGED
@@ -61,6 +61,18 @@ export const presetBranchNameAt = (root) => async (text) => {
61
61
  return null;
62
62
  }
63
63
  };
64
+ /** The spec tool a preset in effect names, as `presetBranchNameAt` finds
65
+ * a branch name. */
66
+ export const presetSpecsAt = (root) => async (text) => {
67
+ try {
68
+ const r = await resolveFiles({ ...filesDeps(root), readFile: () => text }, { partial: true });
69
+ return "specs" in r.resolution.raw ? r.settings.specs : null;
70
+ }
71
+ catch {
72
+ return null;
73
+ }
74
+ };
75
+ const NO_SPEC_TOOL = "None: each ticket holds its own spec";
64
76
  const BRANCH_QUESTION = "How should a build name its branch? Use {ticket}, and {user} for the GitHub account:";
65
77
  /** The pattern a build names its branch by, asked until the answer is one
66
78
  * the settings check takes. */
@@ -227,6 +239,23 @@ export async function main(_argv, d) {
227
239
  (await d.presetBranchName(String(doc))) !== null
228
240
  ? null
229
241
  : await askBranchName(d);
242
+ const ownSpecs = doc.get("specs");
243
+ const writtenSpecs = isMap(ownSpecs)
244
+ ? String(ownSpecs.get("type") ?? "none")
245
+ : ownSpecs === undefined
246
+ ? await d.presetSpecs(String(doc))
247
+ : String(ownSpecs);
248
+ const specsAnswer = writtenSpecs === null
249
+ ? await d.ask.select("Which spec tool do you use?", [
250
+ { name: NO_SPEC_TOOL, value: "none" },
251
+ ...Object.entries(d.tools.specs).map(([value, t]) => ({
252
+ name: t.label,
253
+ value,
254
+ })),
255
+ ], "none")
256
+ : null;
257
+ const specTool = d.tools.specs[specsAnswer ?? writtenSpecs ?? "none"];
258
+ const installing = specTool && !specTool.install.installed(d.root) ? specTool : null;
230
259
  const codeHost = d.tools.codeHost[chosen.codeHost].open(repository);
231
260
  const runner = d.tools.runner[chosen.runner].open(repository);
232
261
  const tickets = await d.tools.tickets[chosen.tickets].open({ repository, board: null }, settings);
@@ -433,6 +462,8 @@ export async function main(_argv, d) {
433
462
  quoted.type = Scalar.QUOTE_DOUBLE;
434
463
  doc.setIn(["code-host", "branch-name"], quoted);
435
464
  }
465
+ if (specsAnswer !== null)
466
+ doc.set("specs", specsAnswer);
436
467
  if (parts.has("from-board"))
437
468
  doc.setIn(["builds", "trigger"], trigger);
438
469
  else if (before.has("from-board"))
@@ -546,6 +577,8 @@ export async function main(_argv, d) {
546
577
  planRow("Settings", "allow auto-merge on the repository");
547
578
  if (parts.has("review"))
548
579
  planRow("Rules", `Require "${REVIEW_VERDICT}" before a merge to the default branch, as the rule "${RULE}"`);
580
+ if (installing)
581
+ planRow("Install", `${installing.install.package}, with ${installing.install.via}`);
549
582
  for (const part of removed)
550
583
  planRow("Turn off", PART_TEXT[part].name);
551
584
  if (!(await d.ask.confirm("Go ahead?", true))) {
@@ -594,6 +627,19 @@ export async function main(_argv, d) {
594
627
  if (!/^\/?node_modules\/?$/m.test(ignore ?? ""))
595
628
  write(".gitignore", `${ignore ?? ""}${ignore && !ignore.endsWith("\n") ? "\n" : ""}node_modules/\n`);
596
629
  write(SETTINGS_FILE, String(doc));
630
+ let installFailed = null;
631
+ if (installing) {
632
+ const { package: pkg, via } = installing.install;
633
+ const r = await d.install([...via.split(" "), pkg]);
634
+ if (r.status === 0)
635
+ d.out(`Installed ${pkg}.`);
636
+ else {
637
+ d.out(`Could not install ${pkg}:`);
638
+ for (const l of r.stderr.trimEnd().split("\n").slice(-5))
639
+ d.out(` ${l}`);
640
+ installFailed = `Install ${installing.name}, which a build writes specs with: ${via} ${pkg}`;
641
+ }
642
+ }
597
643
  const synced = await d.sync();
598
644
  if (synced !== 0)
599
645
  d.out("The sync failed, as above.");
@@ -702,7 +748,7 @@ export async function main(_argv, d) {
702
748
  d.out("");
703
749
  if (deletable.length)
704
750
  d.out(`You can now delete these secrets: ${deletable.join(", ")}`);
705
- const left = [];
751
+ const left = installFailed ? [installFailed] : [];
706
752
  const app = codeHost.reviewAppPage();
707
753
  if (parts.has("review") && app)
708
754
  left.push(`Install the app the review posts through: ${app}`);
@@ -786,6 +832,15 @@ export async function run(argv) {
786
832
  return differences(root, await syncPlan(PACKAGE, root, r, branch));
787
833
  },
788
834
  presetBranchName: presetBranchNameAt(root),
835
+ presetSpecs: presetSpecsAt(root),
836
+ install: async (argv2) => {
837
+ const r = spawnSync(argv2[0], argv2.slice(1), {
838
+ cwd: root,
839
+ encoding: "utf8",
840
+ stdio: ["ignore", "ignore", "pipe"],
841
+ });
842
+ return { status: r.status ?? 1, stderr: r.stderr ?? "" };
843
+ },
789
844
  interactive: async (argv2) => spawnSync(argv2[0], argv2.slice(1), { stdio: "inherit" }).status ?? 1,
790
845
  hasCommand,
791
846
  openPage: (url) => {
@@ -75,16 +75,16 @@ export declare const CI_BOT = "github-actions[bot]";
75
75
  * prose does not count. */
76
76
  export declare function hasCostMarker(body: string): boolean;
77
77
  /** The cost markers in one comment, read as markers are: each on a line of
78
- * its own, outside a fenced code block. Only the owner's account, which the
79
- * agents post as, and the pull request review's bot count; the owner's comments count
80
- * only with the agent mark. */
81
- export declare function parseCosts(comment: IssueComment, owner: string): number[];
78
+ * its own, outside a fenced code block. A comment counts when it carries the
79
+ * agent mark, whoever posted it, as a claim or a release does, or when the
80
+ * pull request review's bot posted it. */
81
+ export declare function parseCosts(comment: IssueComment): number[];
82
82
  /** Whether a pull request's body says it builds this issue, as "Closes #N"
83
83
  * or "Part of #N". */
84
84
  export declare function buildsIssue(body: string, number: number): boolean;
85
85
  /** The issue's Cost: every cost marker on it and on each pull request, open,
86
86
  * merged, or closed, that builds it, to the cent. Null when there are none. */
87
- export declare function issueCost(issue: Issue, pulls: PullRequest[], owner: string): number | null;
87
+ export declare function issueCost(issue: Issue, pulls: PullRequest[]): number | null;
88
88
  export declare const REVIEWER_RUNS_MARK = "<!-- reviewer-runs session=";
89
89
  export type RunResult = "running" | "passed" | "failed" | "no verdict";
90
90
  export type ReviewerRun = {
@@ -115,12 +115,11 @@ export function hasCostMarker(body) {
115
115
  return linesOutsideFences(body).some((line) => COST_LINE.test(line));
116
116
  }
117
117
  /** The cost markers in one comment, read as markers are: each on a line of
118
- * its own, outside a fenced code block. Only the owner's account, which the
119
- * agents post as, and the pull request review's bot count; the owner's comments count
120
- * only with the agent mark. */
121
- export function parseCosts(comment, owner) {
122
- const fromAgent = comment.author === owner && comment.body.includes(AGENT_MARK);
123
- if (!fromAgent && comment.author !== CI_BOT)
118
+ * its own, outside a fenced code block. A comment counts when it carries the
119
+ * agent mark, whoever posted it, as a claim or a release does, or when the
120
+ * pull request review's bot posted it. */
121
+ export function parseCosts(comment) {
122
+ if (!comment.body.includes(AGENT_MARK) && comment.author !== CI_BOT)
124
123
  return [];
125
124
  return linesOutsideFences(comment.body).flatMap((line) => {
126
125
  const match = COST_LINE.exec(line);
@@ -134,7 +133,7 @@ export function buildsIssue(body, number) {
134
133
  }
135
134
  /** The issue's Cost: every cost marker on it and on each pull request, open,
136
135
  * merged, or closed, that builds it, to the cent. Null when there are none. */
137
- export function issueCost(issue, pulls, owner) {
136
+ export function issueCost(issue, pulls) {
138
137
  const comments = [
139
138
  ...issue.comments,
140
139
  ...pulls
@@ -142,7 +141,7 @@ export function issueCost(issue, pulls, owner) {
142
141
  buildsIssue(pull.body, issue.number))
143
142
  .flatMap((pull) => pull.comments ?? []),
144
143
  ];
145
- const costs = comments.flatMap((c) => parseCosts(c, owner));
144
+ const costs = comments.flatMap((c) => parseCosts(c));
146
145
  if (costs.length === 0)
147
146
  return null;
148
147
  return Math.round(costs.reduce((a, b) => a + b, 0) * 100) / 100;
@@ -12,6 +12,7 @@ import { spawnSync } from "node:child_process";
12
12
  import { loadSettings } from "./config.mjs";
13
13
  import { openCodeHost } from "./code-host/index.mjs";
14
14
  import { matchesAny } from "./lib/glob.mjs";
15
+ import { processFiles } from "./specs/index.mjs";
15
16
  /** The code host's changed files under those names. */
16
17
  export const inGithubNames = (files) => files.map(({ path, previousPath, status }) => ({
17
18
  filename: path,
@@ -23,10 +24,13 @@ export const inGithubNames = (files) => files.map(({ path, previousPath, status
23
24
  export const AUTOMATIC = "merge: automatic";
24
25
  export const MANUAL = "merge: manual";
25
26
  /** The factory's own files, held whatever the settings allow: a pull request
26
- * must not be able to change how pull requests are judged. */
27
- const FACTORY_FILES = /^(\.github|\.claude)\/|(^|\/)(CLAUDE|AGENTS)\.md$|^openspec\/config\.yaml$/;
27
+ * must not be able to change how pull requests are judged. Every spec tool's
28
+ * process files are among them, whichever the settings name, since a pull
29
+ * request could change that setting too. */
30
+ const FACTORY_FILES = /^(\.github|\.claude)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
31
+ const SPEC_TOOL_FILES = new Set(processFiles());
28
32
  function classifyPath(path, policy) {
29
- if (FACTORY_FILES.test(path))
33
+ if (FACTORY_FILES.test(path) || SPEC_TOOL_FILES.has(path))
30
34
  return "the factory's own files";
31
35
  if (matchesAny(path, policy.deny))
32
36
  return "held by auto-merge.deny";