@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
@@ -6,11 +6,12 @@
6
6
  import { rmSync, writeFileSync } from "node:fs";
7
7
  import { tmpdir } from "node:os";
8
8
  import { dirname, join } from "node:path";
9
- import { NotFoundError, } from "./types.mjs";
9
+ import { KeyError, NotFoundError, } from "./types.mjs";
10
+ import { writeAccess } from "./github-access.mjs";
10
11
  import { statusOf } from "./transport.mjs";
11
12
  import { sameName } from "../lib/work-status.mjs";
12
13
  const toComment = (raw) => ({
13
- id: raw.id,
14
+ id: String(raw.id),
14
15
  createdAt: raw.created_at,
15
16
  body: raw.body ?? "",
16
17
  author: raw.user?.login ?? "ghost",
@@ -50,14 +51,14 @@ fragment issue on Issue {
50
51
  }
51
52
  }`;
52
53
  export const toComments = (raw) => (raw?.nodes ?? []).map((c) => ({
53
- id: c.databaseId,
54
+ id: String(c.databaseId),
54
55
  createdAt: c.createdAt,
55
56
  body: c.body,
56
57
  author: c.author?.login ?? "ghost",
57
58
  }));
58
59
  export function fromRawIssue(raw) {
59
60
  return {
60
- number: raw.number,
61
+ key: String(raw.number),
61
62
  title: raw.title,
62
63
  state: raw.state === "OPEN" ? "open" : "closed",
63
64
  closedAt: raw.closedAt,
@@ -124,9 +125,9 @@ export function toBoard(pages, repository) {
124
125
  if (number === undefined ||
125
126
  raw.content?.repository?.nameWithOwner !== repository)
126
127
  continue;
127
- items.set(number, {
128
+ items.set(String(number), {
128
129
  itemId: raw.id,
129
- number,
130
+ key: String(number),
130
131
  status: raw.status?.name ?? null,
131
132
  updatedAt: raw.status?.updatedAt ?? null,
132
133
  session: raw.session?.text ?? "",
@@ -207,7 +208,29 @@ export function commentIdFromUrl(url) {
207
208
  const match = /#issuecomment-(\d+)/.exec(url);
208
209
  if (!match)
209
210
  throw new Error(`gh printed no comment address: ${url.trim()}`);
210
- return Number(match[1]);
211
+ return match[1];
212
+ }
213
+ /** A key typed for GitHub: an issue's number. */
214
+ export function githubKey(typed) {
215
+ if (/^[1-9]\d*$/.test(typed))
216
+ return typed;
217
+ if (/^[\w.-]+\/[\w.-]+#\d+$/.test(typed))
218
+ throw new KeyError(`${typed} is in another repository: the factory reads only its state as a blocker`);
219
+ throw new KeyError(`${typed} is not a ticket here: a GitHub ticket is its number, such as 12`);
220
+ }
221
+ /** How GitHub writes a ticket: `#12`, or `owner/repo#4` for one in another
222
+ * repository, whose key is already written that way. */
223
+ export const githubRef = (key) => key.includes("/") ? key : `#${key}`;
224
+ export const githubLinkText = (key, kind) => `${kind === "closes" ? "Closes" : "Part of"} ${githubRef(key)}`;
225
+ /** The `Closes #N` and `Part of #N` lines in a pull request's body. */
226
+ export function githubLinksIn(body) {
227
+ const links = { closes: [], partOf: [] };
228
+ for (const m of body.matchAll(/\b(closes|part of) #(\d+)(?!\d)/gi)) {
229
+ const list = m[1].toLowerCase() === "closes" ? links.closes : links.partOf;
230
+ if (!list.includes(m[2]))
231
+ list.push(m[2]);
232
+ }
233
+ return links;
211
234
  }
212
235
  const ISSUE_FIELDS = `query IssueFields($owner: String!, $name: String!) {
213
236
  repository(owner: $owner, name: $name) {
@@ -243,6 +266,18 @@ export function githubTickets(o) {
243
266
  const t = o.transport;
244
267
  let lastBoard = null;
245
268
  const issue = (n) => found(`#${n}`, t.rest("GET", `${API}/issues/${n}`));
269
+ // GitHub numbers issues and pull requests from one sequence, and its
270
+ // issues API writes to either, so a write first checks that the number
271
+ // is an issue.
272
+ const issues = new Set();
273
+ const anIssue = async (n) => {
274
+ if (issues.has(n))
275
+ return;
276
+ const raw = await issue(n);
277
+ if (raw.pull_request)
278
+ throw new NotFoundError(`#${n}`);
279
+ issues.add(n);
280
+ };
246
281
  /** Board `number`'s Status field, or null when it has none. */
247
282
  const statusField = async (number) => {
248
283
  const answer = await t.graphql(STATUS_FIELD, { owner: o.boardOwner ?? repoOwner, number });
@@ -277,13 +312,16 @@ export function githubTickets(o) {
277
312
  return lastBoard;
278
313
  };
279
314
  const tickets = {
315
+ key: githubKey,
316
+ ref: githubRef,
280
317
  async read(n) {
281
318
  const raw = await issue(n);
282
319
  if (raw.pull_request)
283
320
  throw new NotFoundError(`#${n}`);
321
+ issues.add(n);
284
322
  const comments = await t.rest("GET", `${API}/issues/${n}/comments?per_page=100`, { paginate: true });
285
323
  return {
286
- number: raw.number,
324
+ key: String(raw.number),
287
325
  title: raw.title,
288
326
  state: raw.state === "closed" ? "closed" : "open",
289
327
  closedAt: raw.closed_at,
@@ -294,25 +332,29 @@ export function githubTickets(o) {
294
332
  },
295
333
  async listOpen() {
296
334
  const all = await t.rest("GET", `${API}/issues?state=open&per_page=100`, { paginate: true });
297
- return all
298
- .filter((i) => !i.pull_request)
299
- .map((i) => ({
300
- number: i.number,
335
+ const open = all.filter((i) => !i.pull_request);
336
+ for (const i of open)
337
+ issues.add(String(i.number));
338
+ return open.map((i) => ({
339
+ key: String(i.number),
301
340
  title: i.title,
302
341
  labels: i.labels.map(labelName),
303
342
  }));
304
343
  },
305
344
  async writeBody(n, body) {
345
+ await anIssue(n);
306
346
  await found(`#${n}`, t.rest("PATCH", `${API}/issues/${n}`, { fields: { body } }));
307
347
  },
308
348
  async writeTitle(n, title) {
349
+ await anIssue(n);
309
350
  await found(`#${n}`, t.rest("PATCH", `${API}/issues/${n}`, { fields: { title } }));
310
351
  },
311
352
  async comment(n, body) {
353
+ await anIssue(n);
312
354
  const made = await found(`#${n}`, t.rest("POST", `${API}/issues/${n}/comments`, {
313
355
  fields: { body },
314
356
  }));
315
- return made.id;
357
+ return String(made.id);
316
358
  },
317
359
  async editComment(id, body) {
318
360
  await found(`comment ${id}`, t.rest("PATCH", `${API}/issues/comments/${id}`, { fields: { body } }));
@@ -327,14 +369,16 @@ export function githubTickets(o) {
327
369
  const made = await t.rest("POST", `${API}/issues`, {
328
370
  fields,
329
371
  });
330
- return made.number;
372
+ return String(made.number);
331
373
  },
332
374
  async addLabel(n, label) {
375
+ await anIssue(n);
333
376
  await found(`#${n}`, t.rest("POST", `${API}/issues/${n}/labels`, {
334
377
  fields: { labels: [label] },
335
378
  }));
336
379
  },
337
380
  async removeLabel(n, label) {
381
+ await anIssue(n);
338
382
  try {
339
383
  await t.rest("DELETE", `${API}/issues/${n}/labels/${encodeURIComponent(label)}`);
340
384
  }
@@ -346,7 +390,9 @@ export function githubTickets(o) {
346
390
  await issue(n);
347
391
  }
348
392
  },
349
- linkText: (n) => `Closes #${n}`,
393
+ mayDecide: (author) => writeAccess(t, o.repository, author),
394
+ linkText: githubLinkText,
395
+ linksIn: githubLinksIn,
350
396
  address: (n) => `https://github.com/${o.repository}/issues/${n}`,
351
397
  board: {
352
398
  read: readBoard,
@@ -355,6 +401,8 @@ export function githubTickets(o) {
355
401
  if (o.board === null)
356
402
  throw new Error("The settings name no board.");
357
403
  const raw = await issue(n);
404
+ if (raw.pull_request)
405
+ throw new NotFoundError(`#${n}`);
358
406
  const added = await t.graphql(ADD_CARD, { project: board.projectId, content: raw.node_id });
359
407
  return added.data.addProjectV2ItemById.item.id;
360
408
  },
@@ -461,6 +509,7 @@ export function githubTickets(o) {
461
509
  },
462
510
  async write(n, values) {
463
511
  const fields = await issueFields();
512
+ await anIssue(n);
464
513
  const { node_id } = await issue(n);
465
514
  for (const [name, value] of Object.entries(values)) {
466
515
  const field = fields.find((f) => f.name === name);
@@ -475,12 +524,17 @@ export function githubTickets(o) {
475
524
  blockers: {
476
525
  async list(n) {
477
526
  const list = await found(`#${n}`, t.rest("GET", `${API}/issues/${n}/dependencies/blocked_by`, { paginate: true }));
478
- return list.map((b) => ({
479
- number: b.number,
480
- state: b.state === "open" ? "open" : "closed",
481
- }));
527
+ return list.map((b) => {
528
+ const repo = b.repository_url?.replace(/^.*\/repos\//, "");
529
+ const elsewhere = repo && repo.toLowerCase() !== o.repository.toLowerCase();
530
+ return {
531
+ key: elsewhere ? `${repo}#${b.number}` : String(b.number),
532
+ state: b.state === "open" ? "open" : "closed",
533
+ };
534
+ });
482
535
  },
483
536
  async add(n, by) {
537
+ await anIssue(n);
484
538
  const blocker = await issue(by);
485
539
  await found(`#${n}`, t.rest("POST", `${API}/issues/${n}/dependencies/blocked_by`, {
486
540
  fields: { issue_id: blocker.id },
@@ -512,12 +566,14 @@ export function githubTickets(o) {
512
566
  after = info.hasNextPage ? info.endCursor : null;
513
567
  } while (after);
514
568
  const read = fromIssuesPages(pages);
569
+ for (const x of read)
570
+ issues.add(x.key);
515
571
  if (!options.board)
516
572
  return read;
517
573
  const board = await readBoard();
518
574
  return read.map((x) => ({
519
575
  ...x,
520
- card: board.items.get(x.number) ?? null,
576
+ card: board.items.get(x.key) ?? null,
521
577
  }));
522
578
  };
523
579
  if (o.cli) {
@@ -1,6 +1,6 @@
1
1
  import { type Gh } from "../lib/gh.mts";
2
2
  import { type Settings } from "../config.mts";
3
- import { type Tickets } from "./types.mts";
3
+ import { type Key, type Tickets } from "./types.mts";
4
4
  import { type FieldMapping } from "../ticket-fields.mts";
5
5
  export * from "./types.mts";
6
6
  /** The ticket system's message for a type that is not built. */
@@ -8,6 +8,12 @@ export declare const unsupportedType: (type: string) => string;
8
8
  export type Opened = {
9
9
  tickets: Tickets;
10
10
  };
11
+ /** How a ticket system of this type writes a ticket, without opening its
12
+ * adapter, for text written ahead of time, such as a workflow's run name. */
13
+ export declare function refOf(type: string): (key: Key) => string;
14
+ /** How a ticket system of this type reads a typed key, as `Tickets.key`
15
+ * does, without opening its adapter. */
16
+ export declare function keyOf(type: string): (typed: string) => Key;
11
17
  /** The settings' adapter, reaching its system through the GitHub CLI. The
12
18
  * repository and board are the caller's, since a workflow can name its own. */
13
19
  export declare function openTickets(settings: Settings, target: {
@@ -3,7 +3,7 @@
3
3
  // value before this runs (`config.mts`).
4
4
  import { gh } from "../lib/gh.mjs";
5
5
  import { fieldNamesOf } from "../config.mjs";
6
- import { githubTickets } from "./github.mjs";
6
+ import { githubKey, githubRef, githubTickets } from "./github.mjs";
7
7
  import { ghTransport } from "./transport.mjs";
8
8
  import { need } from "./types.mjs";
9
9
  import { join, split } from "../ticket-fields.mjs";
@@ -11,6 +11,20 @@ import { BUILT, unsupported } from "../tool-names.mjs";
11
11
  export * from "./types.mjs";
12
12
  /** The ticket system's message for a type that is not built. */
13
13
  export const unsupportedType = (type) => unsupported("tickets.type", type, "ticket system", Object.keys(BUILT.tickets));
14
+ /** How a ticket system of this type writes a ticket, without opening its
15
+ * adapter, for text written ahead of time, such as a workflow's run name. */
16
+ export function refOf(type) {
17
+ if (type !== "github")
18
+ throw new Error(unsupportedType(type));
19
+ return githubRef;
20
+ }
21
+ /** How a ticket system of this type reads a typed key, as `Tickets.key`
22
+ * does, without opening its adapter. */
23
+ export function keyOf(type) {
24
+ if (type !== "github")
25
+ throw new Error(unsupportedType(type));
26
+ return githubKey;
27
+ }
14
28
  /** The settings' adapter, reaching its system through the GitHub CLI. The
15
29
  * repository and board are the caller's, since a workflow can name its own. */
16
30
  export async function openTickets(settings, target, run = gh) {
@@ -1,5 +1,9 @@
1
+ /** A ticket's identity: the key its ticket system gives it, as text, such
2
+ * as `12` on GitHub or `PROJ-12` in Jira. */
3
+ export type Key = string;
1
4
  export type TicketComment = {
2
- id: number;
5
+ /** Opaque: never compared as a number. */
6
+ id: string;
3
7
  author: string;
4
8
  createdAt: string;
5
9
  body: string;
@@ -8,7 +12,7 @@ export type TicketComment = {
8
12
  export type BoardItem = {
9
13
  /** The system's own ID for the card, for the adapter's writes. */
10
14
  itemId: string;
11
- number: number;
15
+ key: Key;
12
16
  status: string | null;
13
17
  /** When Status last changed. */
14
18
  updatedAt: string | null;
@@ -18,19 +22,20 @@ export type BoardItem = {
18
22
  cost?: number | null;
19
23
  };
20
24
  export type Ticket = {
21
- number: number;
25
+ key: Key;
22
26
  title: string;
23
27
  state: "open" | "closed";
24
28
  closedAt: string | null;
25
29
  labels: string[];
26
30
  body: string;
31
+ /** Oldest first, in the order the ticket system keeps them. */
27
32
  comments: TicketComment[];
28
33
  /** The ticket's card, when "Read everything at once" was asked for the
29
34
  * board and the adapter has one; null when it is not on the board. */
30
35
  card?: BoardItem | null;
31
36
  };
32
37
  export type TicketSummary = {
33
- number: number;
38
+ key: Key;
34
39
  title: string;
35
40
  labels: string[];
36
41
  };
@@ -50,8 +55,8 @@ export type Board = {
50
55
  /** The board's own title, for the report `factory board check` prints. */
51
56
  title?: string;
52
57
  fields: BoardField[];
53
- /** This repository's tickets on the board, by number. */
54
- items: Map<number, BoardItem>;
58
+ /** This repository's tickets on the board, by key. */
59
+ items: Map<Key, BoardItem>;
55
60
  };
56
61
  /** One write to a card's field. */
57
62
  export type Write = {
@@ -71,7 +76,7 @@ export type BoardOps = {
71
76
  /** Every card and the board's fields. */
72
77
  read(): Promise<Board>;
73
78
  /** Puts the ticket on the board, and returns its card's ID. */
74
- add(ticket: number): Promise<string>;
79
+ add(ticket: Key): Promise<string>;
75
80
  /** Writes the fields of a card already on the board. */
76
81
  set(itemId: string, writes: Write[]): Promise<void>;
77
82
  /** The open boards the repository's owner has. */
@@ -102,26 +107,28 @@ export type NewField = {
102
107
  type: "select";
103
108
  options: string[];
104
109
  };
110
+ /** A ticket another waits on. Its key can name a ticket `key` would refuse,
111
+ * such as one in another repository. */
105
112
  export type Blocker = {
106
- number: number;
113
+ key: Key;
107
114
  state: "open" | "closed";
108
115
  };
109
116
  export type BlockerOps = {
110
117
  /** What a ticket waits on, open or closed. */
111
- list(ticket: number): Promise<Blocker[]>;
118
+ list(ticket: Key): Promise<Blocker[]>;
112
119
  /** Records that `ticket` waits on `by`. */
113
- add(ticket: number, by: number): Promise<void>;
114
- remove(ticket: number, by: number): Promise<void>;
120
+ add(ticket: Key, by: Key): Promise<void>;
121
+ remove(ticket: Key, by: Key): Promise<void>;
115
122
  };
116
123
  export type LabelHistoryOps = {
117
124
  /** Whether the label was ever removed from the ticket. */
118
- wasRemoved(ticket: number, label: string): Promise<boolean>;
125
+ wasRemoved(ticket: Key, label: string): Promise<boolean>;
119
126
  };
120
127
  export type AttachmentOps = {
121
128
  /** Comments with the images attached; returns the comment's ID. */
122
- comment(ticket: number, body: string, files: string[]): Promise<number>;
129
+ comment(ticket: Key, body: string, files: string[]): Promise<string>;
123
130
  /** Replaces the body with the images attached. */
124
- writeBody(ticket: number, body: string, files: string[]): Promise<void>;
131
+ writeBody(ticket: Key, body: string, files: string[]): Promise<void>;
125
132
  };
126
133
  /** A field tickets can have, set on the ticket itself. */
127
134
  export type TicketField = {
@@ -137,15 +144,15 @@ export type FieldOps = {
137
144
  /** The fields tickets can have, in the system's order. */
138
145
  list(): Promise<TicketField[]>;
139
146
  /** Whether the ticket can hold the field, and how many characters. */
140
- holds(ticket: number, field: string): Promise<{
147
+ holds(ticket: Key, field: string): Promise<{
141
148
  max: number | null;
142
149
  } | {
143
150
  reason: string;
144
151
  }>;
145
152
  /** The ticket's text field values, by field name. */
146
- read(ticket: number): Promise<Record<string, string>>;
153
+ read(ticket: Key): Promise<Record<string, string>>;
147
154
  /** Sets each field by name; null clears it. */
148
- write(ticket: number, values: Record<string, string | null>): Promise<void>;
155
+ write(ticket: Key, values: Record<string, string | null>): Promise<void>;
149
156
  };
150
157
  export declare const GROUPS: readonly ["board", "blockers", "label-history", "attachments", "fields"];
151
158
  export type Group = (typeof GROUPS)[number];
@@ -155,8 +162,14 @@ export type NewTicket = {
155
162
  labels: string[];
156
163
  };
157
164
  export type Tickets = {
165
+ /** The key a person typed, or KeyError saying what a key looks like in
166
+ * this system. It checks only typed input: keys the adapter returned, such
167
+ * as a blocker's, are used as they are. */
168
+ key(typed: string): Key;
169
+ /** How the ticket is written in prose and output, such as `#12`. */
170
+ ref(ticket: Key): string;
158
171
  /** The ticket, or NotFoundError when there is none. */
159
- read(ticket: number): Promise<Ticket>;
172
+ read(ticket: Key): Promise<Ticket>;
160
173
  /** Every open ticket, however many there are. */
161
174
  listOpen(): Promise<TicketSummary[]>;
162
175
  /** Every open ticket and the 30 closed ones most recently updated, as
@@ -166,28 +179,48 @@ export type Tickets = {
166
179
  readAll?(options?: {
167
180
  board?: boolean;
168
181
  }): Promise<Ticket[]>;
169
- writeBody(ticket: number, body: string): Promise<void>;
170
- writeTitle(ticket: number, title: string): Promise<void>;
182
+ writeBody(ticket: Key, body: string): Promise<void>;
183
+ writeTitle(ticket: Key, title: string): Promise<void>;
171
184
  /** Returns the comment's ID. The body is posted as given. */
172
- comment(ticket: number, body: string): Promise<number>;
185
+ comment(ticket: Key, body: string): Promise<string>;
173
186
  /** NotFoundError when the comment is gone. */
174
- editComment(id: number, body: string): Promise<void>;
187
+ editComment(id: string, body: string): Promise<void>;
175
188
  /** NotFoundError when the comment is gone. */
176
- deleteComment(id: number): Promise<void>;
177
- /** Returns the new ticket's number. */
178
- open(ticket: NewTicket): Promise<number>;
179
- addLabel(ticket: number, label: string): Promise<void>;
180
- removeLabel(ticket: number, label: string): Promise<void>;
181
- /** What makes a merged pull request close the ticket. */
182
- linkText(ticket: number): string;
189
+ deleteComment(id: string): Promise<void>;
190
+ /** Returns the new ticket's key. */
191
+ open(ticket: NewTicket): Promise<Key>;
192
+ addLabel(ticket: Key, label: string): Promise<void>;
193
+ removeLabel(ticket: Key, label: string): Promise<void>;
194
+ /** Whether a comment by `author` may decide on a ticket: an answer to a
195
+ * question, taken as an instruction. Rejects when the system cannot
196
+ * say. */
197
+ mayDecide(author: string): Promise<boolean>;
198
+ /** The line in a pull request's body that closes the ticket when it
199
+ * merges, or that says it builds part of it. */
200
+ linkText(ticket: Key, kind: LinkKind): string;
201
+ /** The tickets a pull request's body closes and builds part of, each in
202
+ * the order the body links them, once. */
203
+ linksIn(body: string): Links;
183
204
  /** The address of the ticket's page. */
184
- address(ticket: number): string;
205
+ address(ticket: Key): string;
185
206
  board?: BoardOps;
186
207
  blockers?: BlockerOps;
187
208
  labelHistory?: LabelHistoryOps;
188
209
  attachments?: AttachmentOps;
189
210
  fields?: FieldOps;
190
211
  };
212
+ export type LinkKind = "closes" | "part";
213
+ export type Links = {
214
+ closes: Key[];
215
+ partOf: Key[];
216
+ };
217
+ /** Typed text that is not a key this ticket system uses. */
218
+ export declare class KeyError extends Error {
219
+ constructor(message: string);
220
+ }
221
+ /** The order tickets are listed in: by key, letters first, then the number
222
+ * as a number, so PROJ-9 comes before PROJ-12. */
223
+ export declare const compareKeys: (a: Key, b: Key) => number;
191
224
  /** A ticket or comment that does not exist, told apart from any other
192
225
  * failure. Every adapter throws this one. */
193
226
  export declare class NotFoundError extends Error {
@@ -10,6 +10,16 @@ export const GROUPS = [
10
10
  "attachments",
11
11
  "fields",
12
12
  ];
13
+ /** Typed text that is not a key this ticket system uses. */
14
+ export class KeyError extends Error {
15
+ constructor(message) {
16
+ super(message);
17
+ this.name = "KeyError";
18
+ }
19
+ }
20
+ /** The order tickets are listed in: by key, letters first, then the number
21
+ * as a number, so PROJ-9 comes before PROJ-12. */
22
+ export const compareKeys = (a, b) => a.localeCompare(b, "en", { numeric: true });
13
23
  /** A ticket or comment that does not exist, told apart from any other
14
24
  * failure. Every adapter throws this one. */
15
25
  export class NotFoundError extends Error {
@@ -62,17 +72,17 @@ export async function readAll(tickets, options = {}) {
62
72
  if (tickets.readAll)
63
73
  return tickets.readAll(options);
64
74
  const open = await tickets.listOpen();
65
- const read = await Promise.all(open.map((t) => tickets.read(t.number)));
75
+ const read = await Promise.all(open.map((t) => tickets.read(t.key)));
66
76
  if (!options.board || !tickets.board)
67
77
  return read;
68
78
  const board = await tickets.board.read();
69
- return read.map((t) => ({ ...t, card: board.items.get(t.number) ?? null }));
79
+ return read.map((t) => ({ ...t, card: board.items.get(t.key) ?? null }));
70
80
  }
71
81
  /** The cards `readAll` carried, as a Board, for the code that reads one. */
72
82
  export function boardOf(tickets) {
73
83
  const items = new Map();
74
84
  for (const t of tickets)
75
85
  if (t.card)
76
- items.set(t.number, t.card);
86
+ items.set(t.key, t.card);
77
87
  return { projectId: "", fields: [], items };
78
88
  }
@@ -3,6 +3,8 @@ export type Built = {
3
3
  /** Each ticket system, with the keys it adds under `tickets`. */
4
4
  tickets: Readonly<Record<string, readonly string[]>>;
5
5
  runner: readonly string[];
6
+ /** Each spec tool, with the check \`specs.check\` defaults to. */
7
+ specs: Readonly<Record<string, string>>;
6
8
  };
7
9
  export declare const BUILT: Built;
8
10
  /** The words every command fails with for a name that is not built, such
@@ -8,6 +8,9 @@ export const BUILT = {
8
8
  codeHost: ["github"],
9
9
  tickets: { github: [] },
10
10
  runner: ["github-actions"],
11
+ specs: {
12
+ openspec: "npx --no-install openspec validate --all --strict --no-interactive",
13
+ },
11
14
  };
12
15
  /** The words every command fails with for a name that is not built, such
13
16
  * as `tickets.type "jira" is not supported. "github" is the only ticket
package/dist/tools.d.mts CHANGED
@@ -5,6 +5,7 @@ import type { Part } from "./parts.mts";
5
5
  import { type Runner } from "./runner/index.mts";
6
6
  import type { Chosen, SecretStep, SetupContext, SetupStep, ToolSetup } from "./setup.mts";
7
7
  import { type Tickets } from "./tickets/index.mts";
8
+ import { type SpecTools } from "./specs/index.mts";
8
9
  import { type Built } from "./tool-names.mts";
9
10
  export type Tool = {
10
11
  label: string;
@@ -31,6 +32,7 @@ export type Registry = {
31
32
  agent: Record<string, Tool & {
32
33
  agent: Agent;
33
34
  }>;
35
+ specs: SpecTools;
34
36
  };
35
37
  export declare const TOOLS: Registry;
36
38
  /** The names and keys the settings accept, as `config.mts` checks them. */
package/dist/tools.mjs CHANGED
@@ -12,6 +12,7 @@ import { githubTicketsSetup } from "./tickets/github-setup.mjs";
12
12
  import { openTickets } from "./tickets/index.mjs";
13
13
  import { ghTransport } from "./tickets/transport.mjs";
14
14
  import { githubActionsSetup } from "./runner/setup.mjs";
15
+ import { specTools } from "./specs/index.mjs";
15
16
  import { BUILT } from "./tool-names.mjs";
16
17
  export const TOOLS = {
17
18
  codeHost: {
@@ -50,6 +51,7 @@ export const TOOLS = {
50
51
  agent: claudeCodeAgent(spawn),
51
52
  },
52
53
  },
54
+ specs: specTools(),
53
55
  };
54
56
  /** The names and keys the settings accept, as `config.mts` checks them. */
55
57
  export function builtOf(r) {
@@ -57,6 +59,7 @@ export function builtOf(r) {
57
59
  codeHost: Object.keys(r.codeHost),
58
60
  tickets: Object.fromEntries(Object.entries(r.tickets).map(([name, t]) => [name, t.keys])),
59
61
  runner: Object.keys(r.runner),
62
+ specs: Object.fromEntries(Object.entries(r.specs).map(([name, t]) => [name, t.defaultCheck])),
60
63
  };
61
64
  }
62
65
  /** The tools in use, in the order setup asks for them. */
package/docs/builds.md CHANGED
@@ -64,7 +64,10 @@ stores it.
64
64
  commits name your coding agent as their author and that account as their
65
65
  committer, and its pull request and comments are that account's. When the token is yours, that is you. A team that wants an
66
66
  agent account makes one on the code host, gives it write access, and stores
67
- its token instead. Nothing else changes.
67
+ its token instead. Nothing else changes. An agent account can write to the
68
+ repository, so it counts as an approver, but every comment it posts
69
+ carries the factory's mark, and a session never takes a marked comment as
70
+ an instruction.
68
71
 
69
72
  **Signed commits.** With a signing key stored as a secret, the build signs
70
73
  each commit, and the code host shows it as verified when the key belongs to