@davidbyoung/software-factory 0.1.11 → 0.1.13

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 (85) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ui-reviewer.md +2 -2
  4. package/dist/board.d.mts +9 -7
  5. package/dist/board.mjs +59 -36
  6. package/dist/build.d.mts +4 -0
  7. package/dist/build.mjs +9 -4
  8. package/dist/cli.mjs +8 -1
  9. package/dist/code-host/github.mjs +9 -4
  10. package/dist/code-host/types.d.mts +4 -2
  11. package/dist/commands.d.mts +1 -1
  12. package/dist/commands.mjs +16 -7
  13. package/dist/config.d.mts +7 -0
  14. package/dist/config.mjs +68 -5
  15. package/dist/explain.mjs +6 -0
  16. package/dist/guard-commit.d.mts +3 -3
  17. package/dist/guard-commit.mjs +31 -6
  18. package/dist/guard-ticket-text.d.mts +3 -2
  19. package/dist/guard-ticket-text.mjs +7 -4
  20. package/dist/labels.d.mts +28 -0
  21. package/dist/labels.mjs +36 -0
  22. package/dist/lib/clock.d.mts +3 -1
  23. package/dist/lib/clock.mjs +12 -6
  24. package/dist/lib/pull-tickets.d.mts +15 -0
  25. package/dist/lib/pull-tickets.mjs +12 -0
  26. package/dist/lib/refined-check.d.mts +1 -1
  27. package/dist/lib/refined-check.mjs +3 -5
  28. package/dist/lib/usage.d.mts +3 -1
  29. package/dist/lib/usage.mjs +4 -2
  30. package/dist/lib/work-status.d.mts +29 -23
  31. package/dist/lib/work-status.mjs +30 -33
  32. package/dist/merge-policy.d.mts +9 -7
  33. package/dist/merge-policy.mjs +13 -11
  34. package/dist/poller.d.mts +5 -3
  35. package/dist/poller.mjs +27 -17
  36. package/dist/pr.d.mts +22 -0
  37. package/dist/pr.mjs +60 -10
  38. package/dist/remove.mjs +16 -9
  39. package/dist/review-tickets.d.mts +12 -0
  40. package/dist/review-tickets.mjs +59 -0
  41. package/dist/review-verdict.d.mts +6 -1
  42. package/dist/review-verdict.mjs +15 -9
  43. package/dist/reviewers.d.mts +7 -4
  44. package/dist/reviewers.mjs +19 -12
  45. package/dist/runner/github-actions.mjs +6 -7
  46. package/dist/runner/types.d.mts +7 -6
  47. package/dist/status.d.mts +19 -7
  48. package/dist/status.mjs +38 -23
  49. package/dist/sync.d.mts +8 -0
  50. package/dist/sync.mjs +30 -1
  51. package/dist/ticket-fields.d.mts +4 -2
  52. package/dist/ticket-fields.mjs +10 -3
  53. package/dist/ticket.d.mts +14 -7
  54. package/dist/ticket.mjs +121 -72
  55. package/dist/tickets/github.d.mts +10 -2
  56. package/dist/tickets/github.mjs +74 -20
  57. package/dist/tickets/index.d.mts +9 -2
  58. package/dist/tickets/index.mjs +20 -5
  59. package/dist/tickets/types.d.mts +59 -30
  60. package/dist/tickets/types.mjs +13 -3
  61. package/dist/tool-names.d.mts +7 -0
  62. package/dist/tool-names.mjs +1 -0
  63. package/dist/tools.d.mts +4 -1
  64. package/dist/tools.mjs +5 -0
  65. package/docs/cli.md +12 -8
  66. package/docs/configuration.md +179 -9
  67. package/docs/developing.md +17 -9
  68. package/docs/github/by-hand.md +2 -2
  69. package/docs/github/reference.md +22 -22
  70. package/docs/plugins.md +6 -6
  71. package/docs/workflow.md +8 -6
  72. package/package.json +1 -1
  73. package/review.md +11 -11
  74. package/rules.md +25 -16
  75. package/settings.schema.json +45 -0
  76. package/skills/factory-address-review/SKILL.md +7 -6
  77. package/skills/factory-build/SKILL.md +28 -22
  78. package/skills/factory-refine/SKILL.md +1 -1
  79. package/skills/factory-resolve-conflicts/SKILL.md +5 -4
  80. package/workflows/factory-build.yml +6 -5
  81. package/workflows/factory-claude-review.yml +38 -1
  82. package/workflows/factory-conflicts.yml +1 -1
  83. package/workflows/factory-merge-policy.yml +8 -7
  84. package/workflows/factory-review-verdict.yml +1 -1
  85. package/workflows/factory-review.yml +1 -1
package/dist/ticket.d.mts CHANGED
@@ -2,9 +2,10 @@
2
2
  import type { Runner } from "./runner/types.mts";
3
3
  import { type Settings } from "./config.mts";
4
4
  import { type IssueComment, type PullRequest } from "./lib/work-status.mts";
5
+ import { type Labels } from "./labels.mts";
5
6
  import { type Clock } from "./lib/clock.mts";
6
7
  import type { Measured } from "./lib/usage.mts";
7
- import { type Ticket, type TicketComment, type Tickets } from "./tickets/types.mts";
8
+ import { type Key, type Ticket, type TicketComment, type Tickets } from "./tickets/types.mts";
8
9
  /** The ticket system this session reaches. */
9
10
  export type Opened = {
10
11
  tickets: Tickets;
@@ -28,8 +29,8 @@ export type Deps = {
28
29
  out: (line: string) => void;
29
30
  /** Where this checkout remembers the claim it posted on each issue. */
30
31
  claimStore: {
31
- read: (issue: number) => number | null;
32
- write: (issue: number, commentId: number) => void;
32
+ read: (issue: Key) => string | null;
33
+ write: (issue: Key, commentId: string) => void;
33
34
  };
34
35
  readFile: (path: string) => string;
35
36
  now: () => Date;
@@ -47,18 +48,24 @@ export type Deps = {
47
48
  export type { Clock };
48
49
  export declare function readComments(c: {
49
50
  tickets: Tickets;
50
- }, issue: number): Promise<IssueComment[]>;
51
+ }, issue: Key): Promise<IssueComment[]>;
52
+ /** What a cost note needs: the session's clock and what it spent. */
53
+ export type CostDeps = Pick<Deps, "env" | "clock" | "now" | "measure">;
54
+ /** The cost note for what this session spent since its clock started, and
55
+ * the clock restarted from now. `on` is where the note is posted, as
56
+ * written in prose. */
57
+ export declare function takeCost(on: string, d: CostDeps): string;
51
58
  /** What the ticket waits on that is still open; none when the ticket
52
59
  * system records no blockers. */
53
60
  export declare function openBlockers(c: {
54
61
  tickets: Tickets;
55
- }, issue: number): Promise<number[]>;
62
+ }, issue: Key): Promise<Key[]>;
56
63
  /** The outcome of a claim, as `factory-build` reads it. */
57
- export declare function claimOutcome(comments: IssueComment[], mine: number): "claimed" | `held by ${string}`;
64
+ export declare function claimOutcome(comments: IssueComment[], mine: string): "claimed" | `held by ${string}`;
58
65
  export declare function withLine(body: string, line: string): string;
59
66
  /** A ticket for a reader: title, state, labels, body, and each comment with
60
67
  * its ID and author. */
61
- export declare function formatTicket(t: Ticket): string[];
68
+ export declare function formatTicket(t: Ticket, ref: string, names: Labels["tickets"]): string[];
62
69
  /** One comment as `view` prints it: a line naming it, then its body. */
63
70
  export declare function formatComment(c: TicketComment): string[];
64
71
  export declare function main(argv: string[], deps: Deps): Promise<number>;
package/dist/ticket.mjs CHANGED
@@ -16,14 +16,14 @@
16
16
  // And the reads and writes the skills make, through the ticket interface
17
17
  // (`tickets/`), so no skill calls a ticket system itself:
18
18
  //
19
- // factory ticket view N [--field title|state|labels|body] [--json]
19
+ // factory ticket view N [--field title|state|labels|body|ref] [--json]
20
20
  // factory ticket answers N # the comments that count as answers
21
21
  // factory ticket list [--label LABEL] [--title "TITLE"] [--json]
22
22
  // factory ticket edit N [--title TITLE] [--body-file FILE [--attach FILE]...]
23
23
  // factory ticket comment N --body-file FILE [--attach FILE]...
24
24
  // factory ticket open --title TITLE --body-file FILE [--label LABEL]...
25
25
  // factory ticket label N --add LABEL | --remove LABEL | --was-removed LABEL
26
- // factory ticket link N
26
+ // factory ticket link N [--part]
27
27
  // factory ticket blockers N
28
28
  // factory ticket block N --by M
29
29
  // factory ticket unblock N --by M
@@ -33,8 +33,9 @@
33
33
  // `waiting`, `refined`, `stop`, and `cost` post what the session and its
34
34
  // subagents spent, as a share of the subscription and at API list prices,
35
35
  // since the clock started, or since the
36
- // session started when it has none, then restart it. `cost` posts to issue
37
- // or pull request N. The clock is keyed by CLAUDE_CODE_SESSION_ID, the ID the
36
+ // session started when it has none, then restart it. `cost` posts to ticket
37
+ // N; `factory pr cost` posts to a pull request. The clock is keyed by
38
+ // CLAUDE_CODE_SESSION_ID, the ID the
38
39
  // hooks receive and the transcript's file name.
39
40
  //
40
41
  // `refined` posts its marker only on a ticket whose body a build can read
@@ -62,25 +63,28 @@ import { openRunner } from "./runner/index.mjs";
62
63
  import { loadSettings, targetOf } from "./config.mjs";
63
64
  import { AGENT_MARK, commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
64
65
  import { missingParts } from "./lib/refined-check.mjs";
66
+ import { labelOf, shownLabels } from "./labels.mjs";
65
67
  import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
66
68
  import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
67
69
  import { boardConfigOf, checkFields } from "./board.mjs";
68
70
  import { refuseBareTags, refuseOverride } from "./guard-ticket-text.mjs";
69
71
  import { openTickets } from "./tickets/index.mjs";
70
- import { GROUPS, need, supports, } from "./tickets/types.mjs";
72
+ import { GROUPS, compareKeys, need, supports, } from "./tickets/types.mjs";
73
+ import { linkPulls, ownLinks } from "./lib/pull-tickets.mjs";
71
74
  import { NotSignedInError } from "./code-host/types.mjs";
72
75
  export async function readComments(c, issue) {
73
76
  return (await c.tickets.read(issue)).comments;
74
77
  }
75
78
  /** The cost note for what this session spent since its clock started, and
76
- * the clock restarted from now. */
77
- function takeCost(issue, d) {
79
+ * the clock restarted from now. `on` is where the note is posted, as
80
+ * written in prose. */
81
+ export function takeCost(on, d) {
78
82
  const session = d.env.CLAUDE_CODE_SESSION_ID ?? "";
79
83
  if (!session)
80
- return costNote({ ok: false, reason: "CLAUDE_CODE_SESSION_ID is not set" }, issue, session);
84
+ return costNote({ ok: false, reason: "CLAUDE_CODE_SESSION_ID is not set" }, on, session);
81
85
  const clock = d.clock.read(session);
82
86
  const now = d.now().toISOString();
83
- const note = costNote(measure(d, session, clock?.start ?? null), issue, session);
87
+ const note = costNote(measure(d, session, clock?.start ?? null), on, session);
84
88
  // Only claim and refining choose the issue: a note posted elsewhere, such
85
89
  // as on a pull request, keeps the clock's.
86
90
  d.clock.write(session, { issue: clock ? clock.issue : null, start: now });
@@ -106,6 +110,11 @@ function startClock(issue, d) {
106
110
  async function post(c, issue, kind) {
107
111
  return c.tickets.comment(issue, commentBody(kind, c.config.columns));
108
112
  }
113
+ /** The ticket as a comment names it. */
114
+ const named = (c, key) => ({
115
+ key,
116
+ ref: c.tickets.ref(key),
117
+ });
109
118
  async function remove(c, commentId) {
110
119
  await c.tickets.deleteComment(commentId);
111
120
  }
@@ -115,7 +124,7 @@ export async function openBlockers(c, issue) {
115
124
  if (!c.tickets.blockers)
116
125
  return [];
117
126
  const blockers = await c.tickets.blockers.list(issue);
118
- return blockers.filter((b) => b.state === "open").map((b) => b.number);
127
+ return blockers.filter((b) => b.state === "open").map((b) => b.key);
119
128
  }
120
129
  /** The outcome of a claim, as `factory-build` reads it. */
121
130
  export function claimOutcome(comments, mine) {
@@ -133,7 +142,7 @@ async function claim(issue, who, d) {
133
142
  await post(d, issue, {
134
143
  kind: "stopped",
135
144
  where: "actions",
136
- issue,
145
+ issue: named(d, issue),
137
146
  reason,
138
147
  });
139
148
  };
@@ -146,7 +155,7 @@ async function claim(issue, who, d) {
146
155
  throw error;
147
156
  }
148
157
  if (blockers.length > 0) {
149
- const list = blockers.map((n) => `#${n}`).join(", ");
158
+ const list = blockers.map((k) => d.tickets.ref(k)).join(", ");
150
159
  await stopUnattended(`it waits on ${list}, which has to merge first`);
151
160
  return `blocked by: ${list}`;
152
161
  }
@@ -189,10 +198,10 @@ async function end(issue, who, d) {
189
198
  (live.marker.where === who.where && live.marker.id === who.id));
190
199
  if (!mine)
191
200
  return "not live";
192
- const pulls = await d.openPulls(d.repository, d.codeHost);
193
- if (reviewingPulls(ticket, pulls).length > 0)
201
+ const pulls = linkPulls(await d.openPulls(d.repository, d.codeHost), d.tickets, d.own);
202
+ if (reviewingPulls(ticket, pulls, d.labels.tickets["follow-up"]).length > 0)
194
203
  return "kept";
195
- await post(d, issue, { kind: "ended", issue });
204
+ await post(d, issue, { kind: "ended", issue: named(d, issue) });
196
205
  return "released";
197
206
  }
198
207
  export function withLine(body, line) {
@@ -202,36 +211,38 @@ export function withLine(body, line) {
202
211
  * is open. The file leads the line, so each one names what it is about. */
203
212
  async function followUp(file, text, d) {
204
213
  const line = `- [ ] ${file}: ${text}`;
205
- const open = (await d.tickets.listOpen()).filter((t) => t.labels.includes("follow-up"));
206
- const [first] = open.sort((a, b) => a.number - b.number);
214
+ const label = d.labels.tickets["follow-up"];
215
+ const open = (await d.tickets.listOpen()).filter((t) => t.labels.includes(label));
216
+ const [first] = open.sort((a, b) => compareKeys(a.key, b.key));
207
217
  if (first) {
208
- const issue = await d.tickets.read(first.number);
209
- await d.tickets.writeBody(first.number, withLine(issue.body, line));
210
- return `added to #${first.number}`;
218
+ const issue = await d.tickets.read(first.key);
219
+ await d.tickets.writeBody(first.key, withLine(issue.body, line));
220
+ return `added to ${d.tickets.ref(first.key)}`;
211
221
  }
212
222
  const body = withLine('Small problems noticed while doing other work, one line each, built together once the owner approves this issue. See "Follow-ups" in `.claude/factory/rules.md`.\n', line);
213
223
  const made = await d.tickets.open({
214
224
  title: "Follow-ups",
215
- labels: ["follow-up"],
225
+ labels: [label],
216
226
  body,
217
227
  });
218
- return `opened #${made}`;
228
+ return `opened ${d.tickets.ref(made)}`;
219
229
  }
220
230
  /** Set the card's Status to Ready, as the owner would. */
221
231
  async function moveToReady(issue, d) {
232
+ const ref = d.tickets.ref(issue);
222
233
  const found = await d.tickets.read(issue);
223
234
  if (found.state !== "open")
224
- throw new Error(`#${issue} is closed.`);
235
+ throw new Error(`${ref} is closed.`);
225
236
  if (d.board === null)
226
237
  throw new Error("The settings name no board.");
227
238
  const ready = d.config.columns.Ready?.[0] ?? null;
228
239
  if (ready === null)
229
- throw new Error(`This board has no column for ready. Tell a session to build #${issue}, or run factory build ${issue}.`);
240
+ throw new Error(`This board has no column for ready. Tell a session to build ${ref}, or run factory build ${issue}.`);
230
241
  const board = need(d.tickets, "board");
231
242
  const read = await board.read();
232
243
  const item = read.items.get(issue);
233
244
  if (!item)
234
- throw new Error(`#${issue} is not on the board.`);
245
+ throw new Error(`${ref} is not on the board.`);
235
246
  if (item.status !== null && sameName(item.status, ready))
236
247
  return;
237
248
  const fields = checkFields(read.fields, d.config);
@@ -273,11 +284,11 @@ function options(args, name) {
273
284
  }
274
285
  /** A ticket for a reader: title, state, labels, body, and each comment with
275
286
  * its ID and author. */
276
- export function formatTicket(t) {
287
+ export function formatTicket(t, ref, names) {
277
288
  const lines = [
278
- `#${t.number} ${t.title}`,
289
+ `${ref} ${t.title}`,
279
290
  `state: ${t.state}`,
280
- `labels: ${t.labels.join(", ") || "(none)"}`,
291
+ `labels: ${shownLabels(t.labels, names).join(", ") || "(none)"}`,
281
292
  "",
282
293
  t.body.trimEnd() || "(no body)",
283
294
  ];
@@ -304,7 +315,12 @@ async function answersOf(t, ticket) {
304
315
  .filter((c) => deciders.has(c.author))
305
316
  .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
306
317
  }
307
- const FIELDS = ["title", "state", "labels", "body"];
318
+ const FIELDS = ["title", "state", "labels", "body", "ref"];
319
+ /** A ticket as `--json` prints it: its key, then its written form. */
320
+ const withRef = (t, tickets) => {
321
+ const { key, ...rest } = t;
322
+ return { key, ref: tickets.ref(key), ...rest };
323
+ };
308
324
  const READS_AND_WRITES = new Set([
309
325
  "view",
310
326
  "answers",
@@ -332,42 +348,45 @@ async function branchOf(ticket, d) {
332
348
  throw e;
333
349
  throw new Error("code-host.branch-name uses {user}, and gh is not signed in: run gh auth login", { cause: e });
334
350
  }
335
- return d.branchName
336
- .replaceAll("{ticket}", String(ticket))
337
- .replaceAll("{user}", user);
351
+ return d.branchName.replaceAll("{ticket}", ticket).replaceAll("{user}", user);
338
352
  }
339
353
  /** The commands that read or write a ticket for a skill. Null when
340
354
  * `command` is not one of them. */
341
355
  async function ticketCommand(command, args, d) {
342
356
  const t = d.tickets;
343
- const n = Number(args[0]);
344
- const numbered = () => {
345
- if (!Number.isInteger(n) || n <= 0)
357
+ const keyed = () => {
358
+ if (!args[0] || args[0].startsWith("--"))
346
359
  throw new Error(USAGE);
347
- return n;
360
+ return t.key(args[0]);
348
361
  };
349
362
  const json = args.includes("--json");
363
+ const names = d.labels.tickets;
364
+ /** A ticket label's key as its name, and the override's too, which a
365
+ * session may ask about or remove but never add. */
366
+ const named = (word) => labelOf({ ...names, "verdict-override": d.labels.codeHost["verdict-override"] }, word);
350
367
  switch (command) {
351
368
  case "view": {
352
- const ticket = await t.read(numbered());
369
+ const ticket = await t.read(keyed());
353
370
  const field = option(args, "--field");
354
371
  if (json)
355
- d.out(JSON.stringify(ticket, null, 2));
372
+ d.out(JSON.stringify(withRef(ticket, t), null, 2));
356
373
  else if (field === undefined)
357
- formatTicket(ticket).forEach(d.out);
374
+ formatTicket(ticket, t.ref(ticket.key), names).forEach(d.out);
358
375
  else if (!FIELDS.includes(field))
359
376
  throw new Error(`--field is one of ${FIELDS.join(", ")}.`);
360
377
  else if (field === "labels")
361
- ticket.labels.forEach(d.out);
378
+ shownLabels(ticket.labels, names).forEach(d.out);
379
+ else if (field === "ref")
380
+ d.out(t.ref(ticket.key));
362
381
  else
363
382
  d.out(String(ticket[field]));
364
383
  return 0;
365
384
  }
366
385
  case "answers": {
367
- const ticket = await t.read(numbered());
386
+ const ticket = await t.read(keyed());
368
387
  const answers = await answersOf(t, ticket);
369
388
  if (answers.length === 0)
370
- d.out(`#${ticket.number} has no answers from an approver yet.`);
389
+ d.out(`${t.ref(ticket.key)} has no answers from an approver yet.`);
371
390
  answers.forEach((c, i) => {
372
391
  if (i > 0)
373
392
  d.out("");
@@ -376,22 +395,23 @@ async function ticketCommand(command, args, d) {
376
395
  return 0;
377
396
  }
378
397
  case "list": {
379
- const label = option(args, "--label");
398
+ const given = option(args, "--label");
399
+ const label = given === undefined ? undefined : labelOf(names, given);
380
400
  const title = option(args, "--title");
381
401
  const kept = (await t.listOpen())
382
402
  .filter((x) => label === undefined || x.labels.includes(label))
383
403
  .filter((x) => title === undefined || x.title === title)
384
- .sort((a, b) => a.number - b.number);
404
+ .sort((a, b) => compareKeys(a.key, b.key));
385
405
  if (json)
386
- d.out(JSON.stringify(kept, null, 2));
406
+ d.out(JSON.stringify(kept.map((x) => withRef(x, t)), null, 2));
387
407
  else
388
408
  for (const x of kept)
389
- d.out(`${x.number}\t${x.title}\t${x.labels.join(", ")}`);
409
+ d.out(`${x.key}\t${x.title}\t${shownLabels(x.labels, names).join(", ")}`);
390
410
  return 0;
391
411
  }
392
412
  case "edit":
393
413
  case "comment": {
394
- const ticket = numbered();
414
+ const ticket = keyed();
395
415
  const file = option(args, "--body-file");
396
416
  const newTitle = command === "edit" ? option(args, "--title") : undefined;
397
417
  if (!file && newTitle === undefined)
@@ -434,11 +454,15 @@ async function ticketCommand(command, args, d) {
434
454
  const body = d.readFile(file);
435
455
  refuseBareTags(title);
436
456
  refuseBareTags(body);
437
- d.out(String(await t.open({ title, body, labels: options(args, "--label") })));
457
+ d.out(String(await t.open({
458
+ title,
459
+ body,
460
+ labels: options(args, "--label").map((l) => labelOf(names, l)),
461
+ })));
438
462
  return 0;
439
463
  }
440
464
  case "label": {
441
- const ticket = numbered();
465
+ const ticket = keyed();
442
466
  const add = option(args, "--add");
443
467
  const removed = option(args, "--remove");
444
468
  const was = option(args, "--was-removed");
@@ -447,40 +471,40 @@ async function ticketCommand(command, args, d) {
447
471
  throw new Error(USAGE);
448
472
  if (was !== undefined) {
449
473
  const history = need(t, "label-history");
450
- d.out((await history.wasRemoved(ticket, was)) ? "yes" : "no");
474
+ d.out((await history.wasRemoved(ticket, named(was))) ? "yes" : "no");
451
475
  }
452
476
  else if (add !== undefined) {
453
- // GitHub labels a pull request through its ticket API too.
454
- refuseOverride(add);
455
- await t.addLabel(ticket, add);
477
+ refuseOverride(add, d.labels.codeHost["verdict-override"]);
478
+ await t.addLabel(ticket, labelOf(names, add));
456
479
  d.out("added");
457
480
  }
458
481
  else {
459
- await t.removeLabel(ticket, removed);
482
+ await t.removeLabel(ticket, named(removed));
460
483
  d.out("removed");
461
484
  }
462
485
  return 0;
463
486
  }
464
487
  case "link":
465
- d.out(t.linkText(numbered()));
488
+ d.out(t.linkText(keyed(), args.includes("--part") ? "part" : "closes"));
466
489
  return 0;
467
490
  case "branch": {
468
- const ticket = await t.read(numbered());
469
- d.out(await branchOf(ticket.number, d));
491
+ const ticket = await t.read(keyed());
492
+ d.out(await branchOf(ticket.key, d));
470
493
  return 0;
471
494
  }
472
495
  case "blockers": {
473
- const list = await need(t, "blockers").list(numbered());
496
+ const list = await need(t, "blockers").list(keyed());
474
497
  for (const b of list)
475
- d.out(`#${b.number} ${b.state}`);
498
+ d.out(`${t.ref(b.key)} ${b.state}`);
476
499
  return 0;
477
500
  }
478
501
  case "block":
479
502
  case "unblock": {
480
- const ticket = numbered();
481
- const by = Number(option(args, "--by"));
482
- if (!Number.isInteger(by) || by <= 0)
503
+ const ticket = keyed();
504
+ const given = option(args, "--by");
505
+ if (given === undefined)
483
506
  throw new Error(USAGE);
507
+ const by = t.key(given);
484
508
  const blockers = need(t, "blockers");
485
509
  if (command === "block")
486
510
  await blockers.add(ticket, by);
@@ -493,10 +517,21 @@ async function ticketCommand(command, args, d) {
493
517
  return null;
494
518
  }
495
519
  }
520
+ /** The steps after the reads and writes, each on one ticket. */
521
+ const STEPS = new Set([
522
+ "claim",
523
+ "still-live",
524
+ "stop",
525
+ "end",
526
+ "ready",
527
+ "refining",
528
+ "waiting",
529
+ "cost",
530
+ "refined",
531
+ ]);
496
532
  const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|answers|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
497
533
  export async function main(argv, deps) {
498
534
  const [command, first, ...rest] = argv;
499
- const issue = Number(first);
500
535
  try {
501
536
  // `supports` answers before anything is read: it names the groups.
502
537
  const settings = await deps.settings();
@@ -511,6 +546,11 @@ export async function main(argv, deps) {
511
546
  repository,
512
547
  board,
513
548
  ...opened,
549
+ own: ownLinks(settings),
550
+ labels: {
551
+ tickets: settings.tickets.labels,
552
+ codeHost: settings.codeHost.labels,
553
+ },
514
554
  };
515
555
  if (command === "supports") {
516
556
  if (!first || !GROUPS.includes(first))
@@ -527,8 +567,9 @@ export async function main(argv, deps) {
527
567
  const handled = await ticketCommand(command ?? "", first === undefined ? rest : [first, ...rest], d);
528
568
  if (handled !== null)
529
569
  return handled;
530
- if (!command || !Number.isInteger(issue) || issue <= 0)
570
+ if (!STEPS.has(command ?? "") || !first || first.startsWith("--"))
531
571
  throw new Error(USAGE);
572
+ const issue = d.tickets.key(first);
532
573
  if (command === "still-live") {
533
574
  const live = await stillLive(issue, d);
534
575
  d.out(live ? "live" : "not live");
@@ -549,9 +590,9 @@ export async function main(argv, deps) {
549
590
  await post(d, issue, {
550
591
  kind: "stopped",
551
592
  where: who.where,
552
- issue,
593
+ issue: named(d, issue),
553
594
  reason: rest[0],
554
- cost: takeCost(issue, d),
595
+ cost: takeCost(d.tickets.ref(issue), d),
555
596
  });
556
597
  d.out("released");
557
598
  return 0;
@@ -568,15 +609,23 @@ export async function main(argv, deps) {
568
609
  startClock(issue, d);
569
610
  break;
570
611
  case "waiting":
571
- await post(d, issue, { kind: "waiting", cost: takeCost(issue, d) });
612
+ await post(d, issue, {
613
+ kind: "waiting",
614
+ cost: takeCost(d.tickets.ref(issue), d),
615
+ });
572
616
  break;
573
617
  case "cost":
574
- await post(d, issue, { kind: "cost", cost: takeCost(issue, d) });
618
+ // Read first: a number that is no ticket leaves the clock.
619
+ await d.tickets.read(issue);
620
+ await post(d, issue, {
621
+ kind: "cost",
622
+ cost: takeCost(d.tickets.ref(issue), d),
623
+ });
575
624
  break;
576
625
  case "refined": {
577
626
  // A body the build could not read gets no marker, whoever wrote it.
578
627
  const ticket = await d.tickets.read(issue);
579
- const missing = missingParts(ticket.body, ticket.labels);
628
+ const missing = missingParts(ticket.body, ticket.labels, d.labels.tickets);
580
629
  if (missing.length > 0) {
581
630
  for (const line of missing)
582
631
  console.error(line);
@@ -590,9 +639,9 @@ export async function main(argv, deps) {
590
639
  const before = at === -1 ? undefined : d.readFile(rest[at + 1]);
591
640
  await post(d, issue, {
592
641
  kind: "refined",
593
- issue,
642
+ issue: named(d, issue),
594
643
  before,
595
- cost: takeCost(issue, d),
644
+ cost: takeCost(d.tickets.ref(issue), d),
596
645
  });
597
646
  break;
598
647
  }
@@ -632,7 +681,7 @@ export async function run(argv) {
632
681
  claimStore: {
633
682
  read: (issue) => {
634
683
  const path = claimPath(issue);
635
- return existsSync(path) ? Number(readFileSync(path, "utf8")) : null;
684
+ return existsSync(path) ? readFileSync(path, "utf8").trim() : null;
636
685
  },
637
686
  write: (issue, id) => writeFileSync(claimPath(issue), String(id)),
638
687
  },
@@ -1,5 +1,5 @@
1
1
  import type { Gh } from "../lib/gh.mts";
2
- import { type Board, type BoardField, type NewField, type Ticket, type TicketComment, type Tickets } from "./types.mts";
2
+ import { type Key, type LinkKind, type Links, type Board, type BoardField, type NewField, type Ticket, type TicketComment, type Tickets } from "./types.mts";
3
3
  import { type Transport } from "./transport.mts";
4
4
  export type GithubOptions = {
5
5
  transport: Transport;
@@ -123,6 +123,14 @@ type StatusOption = {
123
123
  * valid GraphQL. */
124
124
  export declare function setColumnsMutation(field: string, options: StatusOption[]): string;
125
125
  /** The id in the URL `gh issue comment` prints. */
126
- export declare function commentIdFromUrl(url: string): number;
126
+ export declare function commentIdFromUrl(url: string): string;
127
+ /** A key typed for GitHub: an issue's number. */
128
+ export declare function githubKey(typed: string): Key;
129
+ /** How GitHub writes a ticket: `#12`, or `owner/repo#4` for one in another
130
+ * repository, whose key is already written that way. */
131
+ export declare const githubRef: (key: Key) => string;
132
+ export declare const githubLinkText: (key: Key, kind: LinkKind) => string;
133
+ /** The `Closes #N` and `Part of #N` lines in a pull request's body. */
134
+ export declare function githubLinksIn(body: string): Links;
127
135
  export declare function githubTickets(o: GithubOptions): Tickets;
128
136
  export {};