@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
package/dist/ticket.mjs CHANGED
@@ -16,13 +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
+ // factory ticket answers N # the comments that count as answers
20
21
  // factory ticket list [--label LABEL] [--title "TITLE"] [--json]
21
22
  // factory ticket edit N [--title TITLE] [--body-file FILE [--attach FILE]...]
22
23
  // factory ticket comment N --body-file FILE [--attach FILE]...
23
24
  // factory ticket open --title TITLE --body-file FILE [--label LABEL]...
24
25
  // factory ticket label N --add LABEL | --remove LABEL | --was-removed LABEL
25
- // factory ticket link N
26
+ // factory ticket link N [--part]
26
27
  // factory ticket blockers N
27
28
  // factory ticket block N --by M
28
29
  // factory ticket unblock N --by M
@@ -32,8 +33,9 @@
32
33
  // `waiting`, `refined`, `stop`, and `cost` post what the session and its
33
34
  // subagents spent, as a share of the subscription and at API list prices,
34
35
  // since the clock started, or since the
35
- // session started when it has none, then restart it. `cost` posts to issue
36
- // 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
37
39
  // hooks receive and the transcript's file name.
38
40
  //
39
41
  // `refined` posts its marker only on a ticket whose body a build can read
@@ -59,27 +61,29 @@ import { sessionIdentity } from "./lib/gh.mjs";
59
61
  import { openCodeHost } from "./code-host/index.mjs";
60
62
  import { openRunner } from "./runner/index.mjs";
61
63
  import { loadSettings, targetOf } from "./config.mjs";
62
- import { commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
64
+ import { AGENT_MARK, commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
63
65
  import { missingParts } from "./lib/refined-check.mjs";
64
66
  import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
65
67
  import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
66
68
  import { boardConfigOf, checkFields } from "./board.mjs";
67
69
  import { refuseBareTags, refuseOverride } from "./guard-ticket-text.mjs";
68
70
  import { openTickets } from "./tickets/index.mjs";
69
- import { GROUPS, need, supports, } from "./tickets/types.mjs";
71
+ import { GROUPS, compareKeys, need, supports, } from "./tickets/types.mjs";
72
+ import { linkPulls, ownLinks } from "./lib/pull-tickets.mjs";
70
73
  import { NotSignedInError } from "./code-host/types.mjs";
71
74
  export async function readComments(c, issue) {
72
75
  return (await c.tickets.read(issue)).comments;
73
76
  }
74
77
  /** The cost note for what this session spent since its clock started, and
75
- * the clock restarted from now. */
76
- function takeCost(issue, d) {
78
+ * the clock restarted from now. `on` is where the note is posted, as
79
+ * written in prose. */
80
+ export function takeCost(on, d) {
77
81
  const session = d.env.CLAUDE_CODE_SESSION_ID ?? "";
78
82
  if (!session)
79
- return costNote({ ok: false, reason: "CLAUDE_CODE_SESSION_ID is not set" }, issue, session);
83
+ return costNote({ ok: false, reason: "CLAUDE_CODE_SESSION_ID is not set" }, on, session);
80
84
  const clock = d.clock.read(session);
81
85
  const now = d.now().toISOString();
82
- const note = costNote(measure(d, session, clock?.start ?? null), issue, session);
86
+ const note = costNote(measure(d, session, clock?.start ?? null), on, session);
83
87
  // Only claim and refining choose the issue: a note posted elsewhere, such
84
88
  // as on a pull request, keeps the clock's.
85
89
  d.clock.write(session, { issue: clock ? clock.issue : null, start: now });
@@ -105,6 +109,11 @@ function startClock(issue, d) {
105
109
  async function post(c, issue, kind) {
106
110
  return c.tickets.comment(issue, commentBody(kind, c.config.columns));
107
111
  }
112
+ /** The ticket as a comment names it. */
113
+ const named = (c, key) => ({
114
+ key,
115
+ ref: c.tickets.ref(key),
116
+ });
108
117
  async function remove(c, commentId) {
109
118
  await c.tickets.deleteComment(commentId);
110
119
  }
@@ -114,7 +123,7 @@ export async function openBlockers(c, issue) {
114
123
  if (!c.tickets.blockers)
115
124
  return [];
116
125
  const blockers = await c.tickets.blockers.list(issue);
117
- return blockers.filter((b) => b.state === "open").map((b) => b.number);
126
+ return blockers.filter((b) => b.state === "open").map((b) => b.key);
118
127
  }
119
128
  /** The outcome of a claim, as `factory-build` reads it. */
120
129
  export function claimOutcome(comments, mine) {
@@ -132,7 +141,7 @@ async function claim(issue, who, d) {
132
141
  await post(d, issue, {
133
142
  kind: "stopped",
134
143
  where: "actions",
135
- issue,
144
+ issue: named(d, issue),
136
145
  reason,
137
146
  });
138
147
  };
@@ -145,7 +154,7 @@ async function claim(issue, who, d) {
145
154
  throw error;
146
155
  }
147
156
  if (blockers.length > 0) {
148
- const list = blockers.map((n) => `#${n}`).join(", ");
157
+ const list = blockers.map((k) => d.tickets.ref(k)).join(", ");
149
158
  await stopUnattended(`it waits on ${list}, which has to merge first`);
150
159
  return `blocked by: ${list}`;
151
160
  }
@@ -188,10 +197,10 @@ async function end(issue, who, d) {
188
197
  (live.marker.where === who.where && live.marker.id === who.id));
189
198
  if (!mine)
190
199
  return "not live";
191
- const pulls = await d.openPulls(d.repository, d.codeHost);
200
+ const pulls = linkPulls(await d.openPulls(d.repository, d.codeHost), d.tickets, d.own);
192
201
  if (reviewingPulls(ticket, pulls).length > 0)
193
202
  return "kept";
194
- await post(d, issue, { kind: "ended", issue });
203
+ await post(d, issue, { kind: "ended", issue: named(d, issue) });
195
204
  return "released";
196
205
  }
197
206
  export function withLine(body, line) {
@@ -202,11 +211,11 @@ export function withLine(body, line) {
202
211
  async function followUp(file, text, d) {
203
212
  const line = `- [ ] ${file}: ${text}`;
204
213
  const open = (await d.tickets.listOpen()).filter((t) => t.labels.includes("follow-up"));
205
- const [first] = open.sort((a, b) => a.number - b.number);
214
+ const [first] = open.sort((a, b) => compareKeys(a.key, b.key));
206
215
  if (first) {
207
- const issue = await d.tickets.read(first.number);
208
- await d.tickets.writeBody(first.number, withLine(issue.body, line));
209
- return `added to #${first.number}`;
216
+ const issue = await d.tickets.read(first.key);
217
+ await d.tickets.writeBody(first.key, withLine(issue.body, line));
218
+ return `added to ${d.tickets.ref(first.key)}`;
210
219
  }
211
220
  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);
212
221
  const made = await d.tickets.open({
@@ -214,23 +223,24 @@ async function followUp(file, text, d) {
214
223
  labels: ["follow-up"],
215
224
  body,
216
225
  });
217
- return `opened #${made}`;
226
+ return `opened ${d.tickets.ref(made)}`;
218
227
  }
219
228
  /** Set the card's Status to Ready, as the owner would. */
220
229
  async function moveToReady(issue, d) {
230
+ const ref = d.tickets.ref(issue);
221
231
  const found = await d.tickets.read(issue);
222
232
  if (found.state !== "open")
223
- throw new Error(`#${issue} is closed.`);
233
+ throw new Error(`${ref} is closed.`);
224
234
  if (d.board === null)
225
235
  throw new Error("The settings name no board.");
226
236
  const ready = d.config.columns.Ready?.[0] ?? null;
227
237
  if (ready === null)
228
- throw new Error(`This board has no column for ready. Tell a session to build #${issue}, or run factory build ${issue}.`);
238
+ throw new Error(`This board has no column for ready. Tell a session to build ${ref}, or run factory build ${issue}.`);
229
239
  const board = need(d.tickets, "board");
230
240
  const read = await board.read();
231
241
  const item = read.items.get(issue);
232
242
  if (!item)
233
- throw new Error(`#${issue} is not on the board.`);
243
+ throw new Error(`${ref} is not on the board.`);
234
244
  if (item.status !== null && sameName(item.status, ready))
235
245
  return;
236
246
  const fields = checkFields(read.fields, d.config);
@@ -272,21 +282,46 @@ function options(args, name) {
272
282
  }
273
283
  /** A ticket for a reader: title, state, labels, body, and each comment with
274
284
  * its ID and author. */
275
- export function formatTicket(t) {
285
+ export function formatTicket(t, ref) {
276
286
  const lines = [
277
- `#${t.number} ${t.title}`,
287
+ `${ref} ${t.title}`,
278
288
  `state: ${t.state}`,
279
289
  `labels: ${t.labels.join(", ") || "(none)"}`,
280
290
  "",
281
291
  t.body.trimEnd() || "(no body)",
282
292
  ];
283
293
  for (const c of t.comments)
284
- lines.push("", `--- comment ${c.id} by ${c.author} at ${c.createdAt}`, c.body.trimEnd());
294
+ lines.push("", ...formatComment(c));
285
295
  return lines;
286
296
  }
287
- const FIELDS = ["title", "state", "labels", "body"];
297
+ /** One comment as `view` prints it: a line naming it, then its body. */
298
+ export function formatComment(c) {
299
+ return [
300
+ `--- comment ${c.id} by ${c.author} at ${c.createdAt}`,
301
+ c.body.trimEnd(),
302
+ ];
303
+ }
304
+ /** The comments on a ticket that count as answers: by someone the ticket
305
+ * system says may decide, without the agent mark, oldest first. Asks once
306
+ * for each distinct author. */
307
+ async function answersOf(t, ticket) {
308
+ const unmarked = ticket.comments.filter((c) => !c.body.includes(AGENT_MARK));
309
+ const authors = [...new Set(unmarked.map((c) => c.author))];
310
+ const may = await Promise.all(authors.map((a) => t.mayDecide(a)));
311
+ const deciders = new Set(authors.filter((_, i) => may[i]));
312
+ return unmarked
313
+ .filter((c) => deciders.has(c.author))
314
+ .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
315
+ }
316
+ const FIELDS = ["title", "state", "labels", "body", "ref"];
317
+ /** A ticket as `--json` prints it: its key, then its written form. */
318
+ const withRef = (t, tickets) => {
319
+ const { key, ...rest } = t;
320
+ return { key, ref: tickets.ref(key), ...rest };
321
+ };
288
322
  const READS_AND_WRITES = new Set([
289
323
  "view",
324
+ "answers",
290
325
  "list",
291
326
  "edit",
292
327
  "comment",
@@ -311,54 +346,65 @@ async function branchOf(ticket, d) {
311
346
  throw e;
312
347
  throw new Error("code-host.branch-name uses {user}, and gh is not signed in: run gh auth login", { cause: e });
313
348
  }
314
- return d.branchName
315
- .replaceAll("{ticket}", String(ticket))
316
- .replaceAll("{user}", user);
349
+ return d.branchName.replaceAll("{ticket}", ticket).replaceAll("{user}", user);
317
350
  }
318
351
  /** The commands that read or write a ticket for a skill. Null when
319
352
  * `command` is not one of them. */
320
353
  async function ticketCommand(command, args, d) {
321
354
  const t = d.tickets;
322
- const n = Number(args[0]);
323
- const numbered = () => {
324
- if (!Number.isInteger(n) || n <= 0)
355
+ const keyed = () => {
356
+ if (!args[0] || args[0].startsWith("--"))
325
357
  throw new Error(USAGE);
326
- return n;
358
+ return t.key(args[0]);
327
359
  };
328
360
  const json = args.includes("--json");
329
361
  switch (command) {
330
362
  case "view": {
331
- const ticket = await t.read(numbered());
363
+ const ticket = await t.read(keyed());
332
364
  const field = option(args, "--field");
333
365
  if (json)
334
- d.out(JSON.stringify(ticket, null, 2));
366
+ d.out(JSON.stringify(withRef(ticket, t), null, 2));
335
367
  else if (field === undefined)
336
- formatTicket(ticket).forEach(d.out);
368
+ formatTicket(ticket, t.ref(ticket.key)).forEach(d.out);
337
369
  else if (!FIELDS.includes(field))
338
370
  throw new Error(`--field is one of ${FIELDS.join(", ")}.`);
339
371
  else if (field === "labels")
340
372
  ticket.labels.forEach(d.out);
373
+ else if (field === "ref")
374
+ d.out(t.ref(ticket.key));
341
375
  else
342
376
  d.out(String(ticket[field]));
343
377
  return 0;
344
378
  }
379
+ case "answers": {
380
+ const ticket = await t.read(keyed());
381
+ const answers = await answersOf(t, ticket);
382
+ if (answers.length === 0)
383
+ d.out(`${t.ref(ticket.key)} has no answers from an approver yet.`);
384
+ answers.forEach((c, i) => {
385
+ if (i > 0)
386
+ d.out("");
387
+ formatComment(c).forEach(d.out);
388
+ });
389
+ return 0;
390
+ }
345
391
  case "list": {
346
392
  const label = option(args, "--label");
347
393
  const title = option(args, "--title");
348
394
  const kept = (await t.listOpen())
349
395
  .filter((x) => label === undefined || x.labels.includes(label))
350
396
  .filter((x) => title === undefined || x.title === title)
351
- .sort((a, b) => a.number - b.number);
397
+ .sort((a, b) => compareKeys(a.key, b.key));
352
398
  if (json)
353
- d.out(JSON.stringify(kept, null, 2));
399
+ d.out(JSON.stringify(kept.map((x) => withRef(x, t)), null, 2));
354
400
  else
355
401
  for (const x of kept)
356
- d.out(`${x.number}\t${x.title}\t${x.labels.join(", ")}`);
402
+ d.out(`${x.key}\t${x.title}\t${x.labels.join(", ")}`);
357
403
  return 0;
358
404
  }
359
405
  case "edit":
360
406
  case "comment": {
361
- const ticket = numbered();
407
+ const ticket = keyed();
362
408
  const file = option(args, "--body-file");
363
409
  const newTitle = command === "edit" ? option(args, "--title") : undefined;
364
410
  if (!file && newTitle === undefined)
@@ -405,7 +451,7 @@ async function ticketCommand(command, args, d) {
405
451
  return 0;
406
452
  }
407
453
  case "label": {
408
- const ticket = numbered();
454
+ const ticket = keyed();
409
455
  const add = option(args, "--add");
410
456
  const removed = option(args, "--remove");
411
457
  const was = option(args, "--was-removed");
@@ -417,7 +463,6 @@ async function ticketCommand(command, args, d) {
417
463
  d.out((await history.wasRemoved(ticket, was)) ? "yes" : "no");
418
464
  }
419
465
  else if (add !== undefined) {
420
- // GitHub labels a pull request through its ticket API too.
421
466
  refuseOverride(add);
422
467
  await t.addLabel(ticket, add);
423
468
  d.out("added");
@@ -429,25 +474,26 @@ async function ticketCommand(command, args, d) {
429
474
  return 0;
430
475
  }
431
476
  case "link":
432
- d.out(t.linkText(numbered()));
477
+ d.out(t.linkText(keyed(), args.includes("--part") ? "part" : "closes"));
433
478
  return 0;
434
479
  case "branch": {
435
- const ticket = await t.read(numbered());
436
- d.out(await branchOf(ticket.number, d));
480
+ const ticket = await t.read(keyed());
481
+ d.out(await branchOf(ticket.key, d));
437
482
  return 0;
438
483
  }
439
484
  case "blockers": {
440
- const list = await need(t, "blockers").list(numbered());
485
+ const list = await need(t, "blockers").list(keyed());
441
486
  for (const b of list)
442
- d.out(`#${b.number} ${b.state}`);
487
+ d.out(`${t.ref(b.key)} ${b.state}`);
443
488
  return 0;
444
489
  }
445
490
  case "block":
446
491
  case "unblock": {
447
- const ticket = numbered();
448
- const by = Number(option(args, "--by"));
449
- if (!Number.isInteger(by) || by <= 0)
492
+ const ticket = keyed();
493
+ const given = option(args, "--by");
494
+ if (given === undefined)
450
495
  throw new Error(USAGE);
496
+ const by = t.key(given);
451
497
  const blockers = need(t, "blockers");
452
498
  if (command === "block")
453
499
  await blockers.add(ticket, by);
@@ -460,10 +506,21 @@ async function ticketCommand(command, args, d) {
460
506
  return null;
461
507
  }
462
508
  }
463
- const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
509
+ /** The steps after the reads and writes, each on one ticket. */
510
+ const STEPS = new Set([
511
+ "claim",
512
+ "still-live",
513
+ "stop",
514
+ "end",
515
+ "ready",
516
+ "refining",
517
+ "waiting",
518
+ "cost",
519
+ "refined",
520
+ ]);
521
+ 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 ...";
464
522
  export async function main(argv, deps) {
465
523
  const [command, first, ...rest] = argv;
466
- const issue = Number(first);
467
524
  try {
468
525
  // `supports` answers before anything is read: it names the groups.
469
526
  const settings = await deps.settings();
@@ -478,6 +535,7 @@ export async function main(argv, deps) {
478
535
  repository,
479
536
  board,
480
537
  ...opened,
538
+ own: ownLinks(settings),
481
539
  };
482
540
  if (command === "supports") {
483
541
  if (!first || !GROUPS.includes(first))
@@ -494,8 +552,9 @@ export async function main(argv, deps) {
494
552
  const handled = await ticketCommand(command ?? "", first === undefined ? rest : [first, ...rest], d);
495
553
  if (handled !== null)
496
554
  return handled;
497
- if (!command || !Number.isInteger(issue) || issue <= 0)
555
+ if (!STEPS.has(command ?? "") || !first || first.startsWith("--"))
498
556
  throw new Error(USAGE);
557
+ const issue = d.tickets.key(first);
499
558
  if (command === "still-live") {
500
559
  const live = await stillLive(issue, d);
501
560
  d.out(live ? "live" : "not live");
@@ -516,9 +575,9 @@ export async function main(argv, deps) {
516
575
  await post(d, issue, {
517
576
  kind: "stopped",
518
577
  where: who.where,
519
- issue,
578
+ issue: named(d, issue),
520
579
  reason: rest[0],
521
- cost: takeCost(issue, d),
580
+ cost: takeCost(d.tickets.ref(issue), d),
522
581
  });
523
582
  d.out("released");
524
583
  return 0;
@@ -535,10 +594,18 @@ export async function main(argv, deps) {
535
594
  startClock(issue, d);
536
595
  break;
537
596
  case "waiting":
538
- await post(d, issue, { kind: "waiting", cost: takeCost(issue, d) });
597
+ await post(d, issue, {
598
+ kind: "waiting",
599
+ cost: takeCost(d.tickets.ref(issue), d),
600
+ });
539
601
  break;
540
602
  case "cost":
541
- await post(d, issue, { kind: "cost", cost: takeCost(issue, d) });
603
+ // Read first: a number that is no ticket leaves the clock.
604
+ await d.tickets.read(issue);
605
+ await post(d, issue, {
606
+ kind: "cost",
607
+ cost: takeCost(d.tickets.ref(issue), d),
608
+ });
542
609
  break;
543
610
  case "refined": {
544
611
  // A body the build could not read gets no marker, whoever wrote it.
@@ -557,9 +624,9 @@ export async function main(argv, deps) {
557
624
  const before = at === -1 ? undefined : d.readFile(rest[at + 1]);
558
625
  await post(d, issue, {
559
626
  kind: "refined",
560
- issue,
627
+ issue: named(d, issue),
561
628
  before,
562
- cost: takeCost(issue, d),
629
+ cost: takeCost(d.tickets.ref(issue), d),
563
630
  });
564
631
  break;
565
632
  }
@@ -599,7 +666,7 @@ export async function run(argv) {
599
666
  claimStore: {
600
667
  read: (issue) => {
601
668
  const path = claimPath(issue);
602
- return existsSync(path) ? Number(readFileSync(path, "utf8")) : null;
669
+ return existsSync(path) ? readFileSync(path, "utf8").trim() : null;
603
670
  },
604
671
  write: (issue, id) => writeFileSync(claimPath(issue), String(id)),
605
672
  },
@@ -0,0 +1,5 @@
1
+ import { type Transport } from "./transport.mts";
2
+ /** Whether `login` can write to `repository` (owner/name), counting every
3
+ * grant: repository, team, organization, and enterprise. Rejects when
4
+ * GitHub cannot say, so a failed lookup is never read as "yes". */
5
+ export declare function writeAccess(t: Transport, repository: string, login: string): Promise<boolean>;
@@ -0,0 +1,22 @@
1
+ // Whether an account can write to a GitHub repository: the one lookup both
2
+ // GitHub adapters ask when they decide whose words count as instructions.
3
+ import { statusOf } from "./transport.mjs";
4
+ /** Whether `login` can write to `repository` (owner/name), counting every
5
+ * grant: repository, team, organization, and enterprise. Rejects when
6
+ * GitHub cannot say, so a failed lookup is never read as "yes". */
7
+ export async function writeAccess(t, repository, login) {
8
+ const API = `repos/${repository}`;
9
+ try {
10
+ const answer = await t.rest("GET", `${API}/collaborators/${encodeURIComponent(login)}/permission`);
11
+ return answer.permission === "admin" || answer.permission === "write";
12
+ }
13
+ catch (error) {
14
+ if (statusOf(error) !== 404)
15
+ throw error;
16
+ // A token that cannot see a private repository gets a 404 for every
17
+ // name, so a 404 means "no such account" only when the repository can
18
+ // be read.
19
+ await t.rest("GET", API);
20
+ return false;
21
+ }
22
+ }
@@ -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 {};