@davidbyoung/software-factory 0.1.10 → 0.1.12

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 (83) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ticket-readiness.md +20 -15
  4. package/agents/factory-ui-reviewer.md +2 -2
  5. package/dist/board.d.mts +8 -8
  6. package/dist/board.mjs +53 -37
  7. package/dist/build.d.mts +4 -0
  8. package/dist/build.mjs +9 -4
  9. package/dist/cli.mjs +25 -5
  10. package/dist/code-host/github.mjs +11 -4
  11. package/dist/code-host/types.d.mts +8 -2
  12. package/dist/commands.d.mts +7 -2
  13. package/dist/commands.mjs +96 -17
  14. package/dist/config.d.mts +3 -4
  15. package/dist/config.mjs +7 -8
  16. package/dist/init.d.mts +11 -0
  17. package/dist/init.mjs +56 -1
  18. package/dist/lib/clock.d.mts +3 -1
  19. package/dist/lib/clock.mjs +12 -6
  20. package/dist/lib/pull-tickets.d.mts +15 -0
  21. package/dist/lib/pull-tickets.mjs +12 -0
  22. package/dist/lib/usage.d.mts +3 -1
  23. package/dist/lib/usage.mjs +4 -2
  24. package/dist/lib/work-status.d.mts +28 -24
  25. package/dist/lib/work-status.mjs +21 -35
  26. package/dist/merge-policy.mjs +7 -3
  27. package/dist/poller.d.mts +3 -3
  28. package/dist/poller.mjs +18 -14
  29. package/dist/pr.d.mts +26 -6
  30. package/dist/pr.mjs +92 -28
  31. package/dist/review-tickets.d.mts +12 -0
  32. package/dist/review-tickets.mjs +59 -0
  33. package/dist/review-verdict.d.mts +22 -4
  34. package/dist/review-verdict.mjs +55 -17
  35. package/dist/reviewers.d.mts +7 -4
  36. package/dist/reviewers.mjs +19 -12
  37. package/dist/runner/github-actions.mjs +6 -7
  38. package/dist/runner/types.d.mts +7 -6
  39. package/dist/specs/index.d.mts +6 -0
  40. package/dist/specs/index.mjs +15 -0
  41. package/dist/specs/openspec.d.mts +2 -0
  42. package/dist/specs/openspec.mjs +78 -0
  43. package/dist/specs/types.d.mts +53 -0
  44. package/dist/specs/types.mjs +4 -0
  45. package/dist/status.d.mts +17 -7
  46. package/dist/status.mjs +35 -23
  47. package/dist/sync.d.mts +4 -0
  48. package/dist/sync.mjs +14 -1
  49. package/dist/ticket.d.mts +15 -7
  50. package/dist/ticket.mjs +128 -61
  51. package/dist/tickets/github-access.d.mts +5 -0
  52. package/dist/tickets/github-access.mjs +22 -0
  53. package/dist/tickets/github.d.mts +10 -2
  54. package/dist/tickets/github.mjs +76 -20
  55. package/dist/tickets/index.d.mts +7 -1
  56. package/dist/tickets/index.mjs +15 -1
  57. package/dist/tickets/types.d.mts +63 -30
  58. package/dist/tickets/types.mjs +13 -3
  59. package/dist/tool-names.d.mts +2 -0
  60. package/dist/tool-names.mjs +3 -0
  61. package/dist/tools.d.mts +2 -0
  62. package/dist/tools.mjs +3 -0
  63. package/docs/builds.md +4 -1
  64. package/docs/cli.md +30 -11
  65. package/docs/configuration.md +51 -39
  66. package/docs/developing.md +115 -62
  67. package/docs/existing-repo.md +4 -3
  68. package/docs/github/reference.md +1 -1
  69. package/docs/github/setup.md +20 -3
  70. package/docs/glossary.md +7 -6
  71. package/docs/limitations.md +8 -5
  72. package/docs/plugins.md +6 -6
  73. package/docs/updating.md +18 -0
  74. package/docs/workflow.md +25 -8
  75. package/package.json +1 -1
  76. package/review.md +11 -11
  77. package/rules.md +52 -42
  78. package/skills/factory-address-review/SKILL.md +44 -42
  79. package/skills/factory-build/SKILL.md +71 -72
  80. package/skills/factory-refine/SKILL.md +31 -23
  81. package/skills/factory-resolve-conflicts/SKILL.md +12 -10
  82. package/workflows/factory-build.yml +6 -5
  83. package/workflows/factory-claude-review.yml +38 -1
@@ -97,6 +97,6 @@ A high or medium finding outside the change under review, such as an
97
97
  existing test that cannot fail, is also written as one follow-up line, in
98
98
  the format under "Follow-ups" in `.claude/factory/rules.md`, led by the test's file, so
99
99
  the author can append it as it stands to the follow-ups issue, rather than
100
- open an issue. Write `#N` for the build number; the author fills it in.
100
+ open an issue. Write `TICKET` for the ticket being built; the author fills it in.
101
101
 
102
102
  End with exactly one line: `Verdict: pass` when there is no high or medium finding, or `Verdict: fail, N findings to fix` with N the number of high and medium findings ("1 finding" when there is one). A low finding does not count. Nothing after that line.
@@ -86,6 +86,6 @@ A high or medium finding outside the change under review, such as an
86
86
  existing test that cannot fail, is also written as one follow-up line, in
87
87
  the format under "Follow-ups" in `.claude/factory/rules.md`, led by the test's file, so
88
88
  the author can append it as it stands to the follow-ups issue, rather than
89
- open an issue. Write `#N` for the build number; the author fills it in.
89
+ open an issue. Write `TICKET` for the ticket being built; the author fills it in.
90
90
 
91
91
  End with exactly one line: `Verdict: pass` when there is no high or medium finding, or `Verdict: fail, N findings to fix` with N the number of high and medium findings ("1 finding" when there is one). A low finding does not count. Nothing after that line.
@@ -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
 
@@ -152,8 +152,8 @@ A finding the builder will leave for the owner, because it needs a decision or
152
152
  is already on the default branch, is also written as one follow-up line, in
153
153
  the format under "Follow-ups" in `.claude/factory/rules.md`, led by the page or
154
154
  file it is about, so the builder can append it to the follow-ups issue as it
155
- stands, rather than open an issue. Write `#N` for the build number; the builder
156
- fills it in.
155
+ stands, rather than open an issue. Write `TICKET` for the ticket being built; the
156
+ builder fills it in.
157
157
 
158
158
  End with exactly one line: `Verdict: pass` when there are no findings, or
159
159
  `Verdict: fail, N findings to fix` with N the number of findings ("1 finding"
package/dist/board.d.mts CHANGED
@@ -3,7 +3,7 @@ import { type Paint } from "./lib/color.mts";
3
3
  import { type Settings } from "./config.mts";
4
4
  import { type Columns, type Board, type BoardField, type Derived, type PullRequest, type RepoSnapshot } from "./lib/work-status.mts";
5
5
  import { type Runner } from "./runner/index.mts";
6
- import { type Ticket, type Tickets, type Write } from "./tickets/types.mts";
6
+ import { type Key, type Links, type Ticket, type Tickets, type Write } from "./tickets/types.mts";
7
7
  export type { Write };
8
8
  /** Which of the board's fields the sync writes, named as the settings name
9
9
  * them; null means never. */
@@ -65,7 +65,7 @@ export declare function boardRows(fields: BoardField[], cfg: BoardConfig, settin
65
65
  * field, under the setting each comes from. */
66
66
  export declare function boardReport(number: number, board: Board, cfg: BoardConfig, settings: Pick<Settings, "builds">, paint?: Paint): string[];
67
67
  export type Plan = {
68
- number: number;
68
+ key: Key;
69
69
  itemId: string | null;
70
70
  derived: Derived;
71
71
  /** The cost markers' sum as subscription dollars, or null when there are
@@ -79,10 +79,10 @@ 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[];
83
- export declare function logLine(plan: Plan): string;
82
+ export declare function planSync(snapshot: RepoSnapshot, board: Board, runPage: (id: string) => string, cfg?: BoardConfig): Plan[];
83
+ export declare function logLine(plan: Plan, ref: (key: Key) => string): string;
84
84
  export type Comment = {
85
- issue: number;
85
+ issue: Key;
86
86
  body: string;
87
87
  };
88
88
  type PullEvent = {
@@ -96,10 +96,10 @@ type PullEvent = {
96
96
  /** The comments a closed pull request calls for: one on each issue it
97
97
  * closes when it was not merged, and one on each open follow-ups issue it
98
98
  * built part of without closing. */
99
- export declare function closedPullComments(event: PullEvent, closes: number[], openFollowUps: number[], columns?: Columns): Comment[];
99
+ export declare function closedPullComments(event: PullEvent, links: Links, openFollowUps: Key[], columns: Columns, ref: (key: Key) => string): Comment[];
100
100
  /** The nightly run's clears: claims and starts over 24 hours old with no
101
101
  * pull request. */
102
- export declare function nightlyComments(snapshot: RepoSnapshot, now: Date, columns?: Columns): Comment[];
102
+ export declare function nightlyComments(snapshot: RepoSnapshot, now: Date, columns: Columns, ref: (key: Key) => string): Comment[];
103
103
  /** What collect saves for apply: the tickets and the pull requests. */
104
104
  export type Saved = {
105
105
  tickets: Ticket[];
@@ -113,7 +113,7 @@ export type PullSource = {
113
113
  costs: boolean;
114
114
  }): Promise<PullRequest[]>;
115
115
  linking(skip: number[]): Promise<PullRequest[]>;
116
- closes(pull: number): Promise<number[]>;
116
+ closes(pull: number): Promise<Key[]>;
117
117
  };
118
118
  export type Deps = {
119
119
  /** The ticket system and the pull requests for the repository and board
package/dist/board.mjs CHANGED
@@ -24,12 +24,13 @@ import { colorOn, painter, plain, } from "./lib/color.mjs";
24
24
  import { readFileSync, writeFileSync } from "node:fs";
25
25
  import { join } from "node:path";
26
26
  import { columnsOf, fieldNamesOf, loadSettings, } from "./config.mjs";
27
- import { DEFAULT_COLUMNS, STATE_KEYS, cardOf, columnFor, columnsFor, sameName, statusOfColumn, commentBody, derive, buildsPartOf, issueCost, toClear, toSnapshot, actionsRunLink, } from "./lib/work-status.mjs";
27
+ import { DEFAULT_COLUMNS, STATE_KEYS, cardOf, columnFor, columnsFor, sameName, statusOfColumn, commentBody, derive, issueCost, toClear, toSnapshot, actionsRunLink, } from "./lib/work-status.mjs";
28
28
  import { subscriptionDollars } from "./lib/pricing.mjs";
29
29
  import { openCodeHost } from "./code-host/index.mjs";
30
30
  import { openRunner } from "./runner/index.mjs";
31
31
  import { toBoard } from "./tickets/github.mjs";
32
- import { openTickets } from "./tickets/index.mjs";
32
+ import { openTickets, refOf } from "./tickets/index.mjs";
33
+ import { linkPulls, ownLinks, ticketsOf } from "./lib/pull-tickets.mjs";
33
34
  import { need, readAll, } from "./tickets/types.mjs";
34
35
  export const DEFAULT_FIELDS = {
35
36
  session: "Session",
@@ -256,19 +257,18 @@ export function boardReport(number, board, cfg, settings, paint = plain) {
256
257
  /** What each issue's fields should hold, and which writes get them there.
257
258
  * A card's Session is an Actions run's page, which `runPage` gives for its
258
259
  * 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];
260
+ export function planSync(snapshot, board, runPage, cfg = DEFAULT_BOARD) {
261
261
  const everyPull = [...snapshot.pulls, ...(snapshot.donePulls ?? [])];
262
262
  const fields = checkFields(board.fields, cfg);
263
263
  return snapshot.issues.map((issue) => {
264
- const derived = derive(issue, cardOf(board, issue.number, cfg.columns), snapshot.pulls, cfg.columns);
265
- const listPrice = issueCost(issue, everyPull, owner);
264
+ const derived = derive(issue, cardOf(board, issue.key, cfg.columns), snapshot.pulls, cfg.columns);
265
+ const listPrice = issueCost(issue, everyPull);
266
266
  const cost = listPrice === null
267
267
  ? null
268
268
  : Math.round(subscriptionDollars(listPrice) * 100) / 100;
269
- const item = board.items.get(issue.number);
269
+ const item = board.items.get(issue.key);
270
270
  const base = {
271
- number: issue.number,
271
+ key: issue.key,
272
272
  itemId: item?.itemId ?? null,
273
273
  derived,
274
274
  cost,
@@ -307,27 +307,29 @@ export function planSync(snapshot, board, repository, runPage, cfg = DEFAULT_BOA
307
307
  return { ...base, writes };
308
308
  });
309
309
  }
310
- export function logLine(plan) {
310
+ export function logLine(plan, ref) {
311
311
  const d = plan.derived;
312
+ const name = ref(plan.key);
312
313
  if (plan.unmapped !== undefined)
313
- return `#${plan.number} card is in "${plan.unmapped}", which no state names (left alone)`;
314
+ return `${name} card is in "${plan.unmapped}", which no state names (left alone)`;
314
315
  const cost = plan.cost === null ? "(empty)" : plan.cost.toFixed(2);
315
316
  const values = `Status=${d.status}, Session=${d.session || "(empty)"}, Runs in=${d.runsIn || "(empty)"}, Cost=${cost}`;
316
317
  if (plan.writes.length === 0)
317
- return `#${plan.number} ${values} (unchanged)`;
318
+ return `${name} ${values} (unchanged)`;
318
319
  const added = plan.itemId ? "" : "added to the board; ";
319
- return `#${plan.number} ${values} (${added}set ${plan.writes.map((w) => w.field).join(", ")})`;
320
+ return `${name} ${values} (${added}set ${plan.writes.map((w) => w.field).join(", ")})`;
320
321
  }
321
322
  /** The comments a closed pull request calls for: one on each issue it
322
323
  * closes when it was not merged, and one on each open follow-ups issue it
323
324
  * built part of without closing. */
324
- export function closedPullComments(event, closes, openFollowUps, columns = DEFAULT_COLUMNS) {
325
+ export function closedPullComments(event, links, openFollowUps, columns, ref) {
325
326
  if (event.action !== "closed")
326
327
  return [];
327
328
  const pull = event.pull_request;
329
+ const { closes } = links;
328
330
  const closedKind = (issue) => ({
329
331
  kind: "pull-closed",
330
- issue,
332
+ issue: { key: issue, ref: ref(issue) },
331
333
  pull: pull.number,
332
334
  });
333
335
  const comments = [];
@@ -335,7 +337,7 @@ export function closedPullComments(event, closes, openFollowUps, columns = DEFAU
335
337
  for (const issue of closes)
336
338
  comments.push({ issue, body: commentBody(closedKind(issue), columns) });
337
339
  for (const followUps of openFollowUps) {
338
- if (closes.includes(followUps) || !buildsPartOf(pull.body ?? "", followUps))
340
+ if (closes.includes(followUps) || !links.partOf.includes(followUps))
339
341
  continue;
340
342
  comments.push({
341
343
  issue: followUps,
@@ -348,21 +350,18 @@ export function closedPullComments(event, closes, openFollowUps, columns = DEFAU
348
350
  }
349
351
  /** The nightly run's clears: claims and starts over 24 hours old with no
350
352
  * pull request. */
351
- export function nightlyComments(snapshot, now, columns = DEFAULT_COLUMNS) {
353
+ export function nightlyComments(snapshot, now, columns, ref) {
352
354
  return snapshot.issues.flatMap((issue) => {
353
355
  const clear = toClear(issue, snapshot.pulls, now);
354
356
  if (!clear)
355
357
  return [];
358
+ const named = { key: issue.key, ref: ref(issue.key) };
356
359
  return [
357
360
  {
358
- issue: issue.number,
361
+ issue: issue.key,
359
362
  body: commentBody(clear.kind === "claim"
360
- ? { kind: "cleared-claim", issue: issue.number, since: clear.since }
361
- : {
362
- kind: "cleared-start",
363
- issue: issue.number,
364
- since: clear.since,
365
- }, columns),
363
+ ? { kind: "cleared-claim", issue: named, since: clear.since }
364
+ : { kind: "cleared-start", issue: named, since: clear.since }, columns),
366
365
  },
367
366
  ];
368
367
  });
@@ -371,19 +370,24 @@ async function postAll(comments, d, dryRun) {
371
370
  for (const c of comments) {
372
371
  const first = c.body.split("\n")[0];
373
372
  if (dryRun) {
374
- d.out(`would comment on #${c.issue}: ${first}`);
373
+ d.out(`would comment on ${d.tickets.ref(c.issue)}: ${first}`);
375
374
  continue;
376
375
  }
377
376
  await d.tickets.comment(c.issue, c.body);
378
- d.out(`commented on #${c.issue}: ${first}`);
377
+ d.out(`commented on ${d.tickets.ref(c.issue)}: ${first}`);
379
378
  }
380
379
  }
381
380
  async function read(d) {
382
- const [tickets, pulls] = await Promise.all([
381
+ const [tickets, open] = await Promise.all([
383
382
  readAll(d.tickets),
384
383
  d.pulls.open({ costs: true }),
385
384
  ]);
386
- const donePulls = await d.pulls.linking(pulls.map((p) => p.number));
385
+ const pulls = linkPulls(open, d.tickets, d.own);
386
+ // Only the code host's own links say which closed pull requests built a
387
+ // ticket.
388
+ const donePulls = d.own
389
+ ? linkPulls(await d.pulls.linking(pulls.map((p) => p.number)), d.tickets, d.own)
390
+ : [];
387
391
  return { tickets, pulls, donePulls };
388
392
  }
389
393
  const snapshotOf = (saved, now) => toSnapshot(saved.tickets, saved.pulls, now, saved.donePulls);
@@ -395,8 +399,12 @@ async function collect(d, opts) {
395
399
  if (event.action === "closed") {
396
400
  const followUps = snapshot.issues
397
401
  .filter((i) => i.state === "open" && i.labels.includes("follow-up"))
398
- .map((i) => i.number);
399
- const comments = closedPullComments(event, await d.pulls.closes(event.pull_request.number), followUps, d.config.columns);
402
+ .map((i) => i.key);
403
+ const links = ticketsOf({
404
+ body: event.pull_request.body ?? "",
405
+ closes: d.own ? await d.pulls.closes(event.pull_request.number) : [],
406
+ }, d.tickets, d.own);
407
+ const comments = closedPullComments(event, links, followUps, d.config.columns, (k) => d.tickets.ref(k));
400
408
  await postAll(comments, d, opts.dryRun);
401
409
  if (comments.length && !opts.dryRun) {
402
410
  saved = await read(d);
@@ -405,7 +413,7 @@ async function collect(d, opts) {
405
413
  }
406
414
  }
407
415
  if (opts.nightly) {
408
- const comments = nightlyComments(snapshot, d.now(), d.config.columns);
416
+ const comments = nightlyComments(snapshot, d.now(), d.config.columns, (k) => d.tickets.ref(k));
409
417
  await postAll(comments, d, opts.dryRun);
410
418
  if (comments.length && !opts.dryRun)
411
419
  saved = await read(d);
@@ -421,12 +429,12 @@ async function apply(saved, board, d, write) {
421
429
  for (const line of inspected.lines)
422
430
  if (line.text.startsWith("skipped"))
423
431
  d.out(`${line.label} ${line.text}`);
424
- const plans = planSync(snapshotOf(saved, d.now()), board, d.repository, d.runPage, d.config);
432
+ const plans = planSync(snapshotOf(saved, d.now()), board, d.runPage, d.config);
425
433
  for (const plan of plans) {
426
- d.out(logLine(plan));
434
+ d.out(logLine(plan, d.ref));
427
435
  if (!write || plan.writes.length === 0)
428
436
  continue;
429
- const itemId = plan.itemId ?? (await write.add(plan.number));
437
+ const itemId = plan.itemId ?? (await write.add(plan.key));
430
438
  await write.set(itemId, plan.writes);
431
439
  }
432
440
  }
@@ -456,6 +464,7 @@ export async function main(argv, deps) {
456
464
  const repository = deps.env.GITHUB_REPOSITORY || settings.repository;
457
465
  const runner = deps.runner(repository, settings.builds.runner);
458
466
  const runPage = (id) => runner.runPage(id);
467
+ const ref = refOf(settings.tickets.type);
459
468
  const fixture = option(argv, "--fixture");
460
469
  if (argv[0] !== "collect" &&
461
470
  argv[0] !== "apply" &&
@@ -465,12 +474,19 @@ export async function main(argv, deps) {
465
474
  if (fixture) {
466
475
  const saved = JSON.parse(deps.readFile(join(fixture, "repo.json")));
467
476
  const boardPages = JSON.parse(deps.readFile(join(fixture, "board.json")));
468
- await apply(saved, toBoard(boardPages, repository), { ...deps, repository, config, runPage }, null);
477
+ await apply(saved, toBoard(boardPages, repository), { ...deps, repository, config, runPage, ref }, null);
469
478
  return 0;
470
479
  }
471
480
  const board = argv[0] === "collect" ? null : await projectNumber(deps);
472
481
  const opened = await deps.open(settings, { repository, board });
473
- const d = { ...deps, config, repository, runPage, ...opened };
482
+ const d = {
483
+ ...deps,
484
+ config,
485
+ repository,
486
+ runPage,
487
+ ...opened,
488
+ own: ownLinks(settings),
489
+ };
474
490
  if (argv[0] === "collect") {
475
491
  const out = option(argv, "--out");
476
492
  if (!out)
@@ -501,11 +517,11 @@ export async function main(argv, deps) {
501
517
  throw new Error("apply needs --in FILE.");
502
518
  if (!d.env.GH_TOKEN)
503
519
  throw new Error("FACTORY_BOARD_TOKEN is not set.");
504
- await apply(JSON.parse(d.readFile(input)), await boardOps.read(), d, dryRun ? null : boardOps);
520
+ await apply(JSON.parse(d.readFile(input)), await boardOps.read(), { ...d, ref }, dryRun ? null : boardOps);
505
521
  return 0;
506
522
  }
507
523
  const saved = await collect(d, { nightly: false, dryRun: true });
508
- await apply(saved, await boardOps.read(), d, null);
524
+ await apply(saved, await boardOps.read(), { ...d, ref }, null);
509
525
  return 0;
510
526
  }
511
527
  catch (error) {
package/dist/build.d.mts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { type Settings } from "./config.mts";
2
2
  import { type CodeHost } from "./code-host/index.mts";
3
3
  import { type Runner } from "./runner/index.mts";
4
+ import type { Key } from "./tickets/types.mts";
4
5
  export type Deps = {
5
6
  settings: () => Promise<Settings>;
6
7
  env: Record<string, string | undefined>;
@@ -8,6 +9,9 @@ export type Deps = {
8
9
  codeHost: (repository: string, type: string) => CodeHost;
9
10
  /** The runner of that name. */
10
11
  runner: (repository: string, name: string) => Runner;
12
+ /** How the settings' ticket system reads a key and writes a ticket. */
13
+ keyOf: (type: string) => (typed: string) => Key;
14
+ refOf: (type: string) => (key: Key) => string;
11
15
  now: () => Date;
12
16
  sleep: (ms: number) => Promise<unknown>;
13
17
  out: (line: string) => void;
package/dist/build.mjs CHANGED
@@ -10,18 +10,21 @@ import { setTimeout as sleep } from "node:timers/promises";
10
10
  import { loadSettings, targetOf } from "./config.mjs";
11
11
  import { openCodeHost } from "./code-host/index.mjs";
12
12
  import { openRunner } from "./runner/index.mjs";
13
+ import { keyOf, refOf } from "./tickets/index.mjs";
13
14
  const USAGE = "Usage: factory build N";
14
15
  /** How long to look for the run, and how often. */
15
16
  const FIND_FOR_MS = 15_000;
16
17
  const EVERY_MS = 3_000;
17
18
  export async function main(argv, d) {
18
- const ticket = Number(argv[0]);
19
- if (argv.length !== 1 || !Number.isInteger(ticket) || ticket <= 0) {
19
+ if (argv.length !== 1 || !argv[0] || argv[0].startsWith("-")) {
20
20
  d.err(USAGE);
21
21
  return 2;
22
22
  }
23
23
  try {
24
24
  const settings = await d.settings();
25
+ const ticket = d.keyOf(settings.tickets.type)(argv[0]);
26
+ const ref = d.refOf(settings.tickets.type)(ticket);
27
+ const runName = `Build ${ref}`;
25
28
  const { repository } = targetOf(settings, d.env);
26
29
  const runner = d.runner(repository, settings.builds.runner);
27
30
  const branch = await d
@@ -31,12 +34,12 @@ export async function main(argv, d) {
31
34
  await runner.startBuild(ticket, branch);
32
35
  let link = null;
33
36
  for (;;) {
34
- link = await runner.findBuild(ticket, since);
37
+ link = await runner.findBuild(runName, since);
35
38
  if (link || d.now().getTime() - since >= FIND_FOR_MS)
36
39
  break;
37
40
  await d.sleep(EVERY_MS);
38
41
  }
39
- d.out(`Started a build of #${ticket} in GitHub Actions:`);
42
+ d.out(`Started a build of ${ref} in GitHub Actions:`);
40
43
  d.out(link ?? runner.buildsPage());
41
44
  return 0;
42
45
  }
@@ -52,6 +55,8 @@ export async function run(argv) {
52
55
  env: process.env,
53
56
  codeHost: (repository, type) => openCodeHost(repository, type),
54
57
  runner: (repository, name) => openRunner(repository, name),
58
+ keyOf,
59
+ refOf,
55
60
  now: () => new Date(),
56
61
  sleep,
57
62
  out: (line) => console.log(line),
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",
@@ -35,6 +36,7 @@ const PR_STEPS = [
35
36
  "resolve",
36
37
  "ready",
37
38
  "closes",
39
+ "cost",
38
40
  "for-branch",
39
41
  "comments",
40
42
  "comment",
@@ -63,7 +65,8 @@ const pr = (sub, args) => ({
63
65
  const TICKET_ARGS = {
64
66
  refined: "N [--check] [--before-file FILE]",
65
67
  stop: 'N "reason"',
66
- view: "N [--field title|state|labels|body] [--json]",
68
+ view: "N [--field title|state|labels|body|ref] [--json]",
69
+ link: "N [--part]",
67
70
  list: '[--label LABEL] [--title "TITLE"] [--json]',
68
71
  edit: "N --body-file FILE [--attach FILE]",
69
72
  comment: "N --body-file FILE [--attach FILE]",
@@ -81,7 +84,7 @@ const PR_ARGS = {
81
84
  review: "N REVIEW",
82
85
  reply: "N COMMENT --body-file FILE",
83
86
  resolve: "N COMMENT",
84
- comments: "N [--author LOGIN] [--contains TEXT] [--json]",
87
+ comments: "N [--author LOGIN] [--contains TEXT] [--from-approvers] [--json]",
85
88
  comment: "N --body-file FILE",
86
89
  "comment-view": "ID",
87
90
  label: "N --add LABEL | --remove LABEL",
@@ -207,9 +210,19 @@ export const COMMANDS = [
207
210
  run: async (argv) => (await import("./commands.mjs")).run(["specs-check", ...argv]),
208
211
  },
209
212
  {
210
- words: ["specs", "change-name"],
213
+ words: ["specs", "list"],
214
+ args: "",
215
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-list", ...argv]),
216
+ },
217
+ {
218
+ words: ["specs", "new"],
219
+ args: "N",
220
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-new", ...argv]),
221
+ },
222
+ {
223
+ words: ["specs", "finish"],
211
224
  args: "N",
212
- run: async (argv) => (await import("./commands.mjs")).run(["specs-change-name", ...argv]),
225
+ run: async (argv) => (await import("./commands.mjs")).run(["specs-finish", ...argv]),
213
226
  },
214
227
  {
215
228
  words: ["default-branch"],
@@ -261,6 +274,11 @@ export const COMMANDS = [
261
274
  args: "",
262
275
  run: async () => (await import("./review-tools.mjs")).run(),
263
276
  },
277
+ {
278
+ words: ["review", "tickets"],
279
+ args: "N",
280
+ run: async (argv) => (await import("./review-tickets.mjs")).run(argv),
281
+ },
264
282
  {
265
283
  words: ["reviewers", "start"],
266
284
  args: "",
@@ -346,8 +364,10 @@ const USAGE = [
346
364
  ["gate", "Run the commands under commands.gate"],
347
365
  ["test-one FILE [NAME]", "Run one test file, or one test in it"],
348
366
  ["end-to-end FILE", "Run one end-to-end spec"],
367
+ ["specs list", "List the specs your spec tool keeps"],
368
+ ["specs new N", "Start ticket N's spec"],
349
369
  ["specs check", "Check your written specs"],
350
- ["specs change-name N", "Print the name of ticket N's spec change"],
370
+ ["specs finish N", "Fold ticket N's spec into your specs"],
351
371
  ["default-branch", "Print the default branch's name"],
352
372
  ],
353
373
  ],
@@ -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. */
@@ -138,7 +139,7 @@ fragment links on Issue {
138
139
  }
139
140
  }`;
140
141
  const toComments = (raw) => (raw?.nodes ?? []).map((c) => ({
141
- id: c.databaseId,
142
+ id: String(c.databaseId),
142
143
  createdAt: c.createdAt,
143
144
  body: c.body,
144
145
  author: c.author?.login ?? "ghost",
@@ -152,7 +153,8 @@ export function toPull(raw, repository) {
152
153
  author: raw.author?.login ?? "ghost",
153
154
  closes: raw.closingIssuesReferences.nodes
154
155
  .filter((ref) => ref.repository.nameWithOwner === repository)
155
- .map((ref) => ref.number),
156
+ .map((ref) => String(ref.number)),
157
+ partOf: [],
156
158
  openThreads: (raw.reviewThreads?.nodes ?? []).filter((t) => !t.isResolved)
157
159
  .length,
158
160
  checks: raw.commits?.nodes[0]?.commit.statusCheckRollup?.state ?? null,
@@ -183,7 +185,7 @@ const CLOSING_QUERY = `
183
185
  query ClosingIssues($owner: String!, $name: String!, $number: Int!) {
184
186
  repository(owner: $owner, name: $name) {
185
187
  pullRequest(number: $number) {
186
- closingIssuesReferences(first: 25) { nodes { number } }
188
+ closingIssuesReferences(first: 25) { nodes { number repository { nameWithOwner } } }
187
189
  }
188
190
  }
189
191
  }`;
@@ -258,6 +260,7 @@ export function githubCodeHost(o) {
258
260
  const repo = await t.rest("GET", API);
259
261
  return repo.owner.type === "Organization";
260
262
  },
263
+ canWrite: (login) => writeAccess(t, o.repository, login),
261
264
  async checkRuns(sha) {
262
265
  const answer = await t.rest("GET", `${API}/commits/${sha}/check-runs?per_page=100`);
263
266
  return answer.check_runs.map((c) => ({
@@ -344,7 +347,11 @@ export function githubCodeHost(o) {
344
347
  },
345
348
  async closes(n) {
346
349
  const result = await t.graphql(CLOSING_QUERY, { owner, name, number: n });
347
- return result.data.repository.pullRequest.closingIssuesReferences.nodes.map((x) => x.number);
350
+ return result.data.repository.pullRequest.closingIssuesReferences.nodes
351
+ .filter((x) => !x.repository ||
352
+ x.repository.nameWithOwner.toLowerCase() ===
353
+ o.repository.toLowerCase())
354
+ .map((x) => String(x.number));
348
355
  },
349
356
  async open(options = {}) {
350
357
  const page = await t.graphql(OPEN_PULLS_QUERY, {
@@ -1,4 +1,5 @@
1
1
  import type { PullRequest } from "../lib/work-status.mts";
2
+ import type { Key } from "../tickets/types.mts";
2
3
  /** One end of a pull request: the commit, its branch, and the repository
3
4
  * the branch is in, as owner/name. */
4
5
  export type PullEnd = {
@@ -134,6 +135,10 @@ export type CodeHost = {
134
135
  isPrivate(): Promise<boolean>;
135
136
  /** Whether an organization owns the repository, rather than a person. */
136
137
  ownerIsOrganization(): Promise<boolean>;
138
+ /** Whether the account can write to the repository: an approver, whose
139
+ * words a session takes as instructions. Rejects when the code host
140
+ * cannot say. */
141
+ canWrite(login: string): Promise<boolean>;
137
142
  /** The check runs on a commit, without its statuses. */
138
143
  checkRuns(sha: string): Promise<CheckRun[]>;
139
144
  /** The statuses on a commit, without its check runs. */
@@ -167,8 +172,9 @@ export type CodeHost = {
167
172
  /** One line for each commit on the pull request the code host does not
168
173
  * show as signed: its short ID and the reason, such as `unsigned`. */
169
174
  unverifiedCommits(pull: number): Promise<string[]>;
170
- /** The tickets the pull request closes when it merges. */
171
- closes(pull: number): Promise<number[]>;
175
+ /** The tickets the pull request closes when it merges, by the code
176
+ * host's own links: only tickets the code host keeps itself. */
177
+ closes(pull: number): Promise<Key[]>;
172
178
  /** The open pull requests, as the views and the sync read them: with
173
179
  * their check state when `checks` is asked, and their comments, for the
174
180
  * cost markers, when `costs` is. */
@@ -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: string) => 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>;