@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.
- package/agents/factory-e2e-reviewer.md +1 -1
- package/agents/factory-test-reviewer.md +1 -1
- package/agents/factory-ticket-readiness.md +20 -15
- package/agents/factory-ui-reviewer.md +2 -2
- package/dist/board.d.mts +8 -8
- package/dist/board.mjs +53 -37
- package/dist/build.d.mts +4 -0
- package/dist/build.mjs +9 -4
- package/dist/cli.mjs +25 -5
- package/dist/code-host/github.mjs +11 -4
- package/dist/code-host/types.d.mts +8 -2
- package/dist/commands.d.mts +7 -2
- package/dist/commands.mjs +96 -17
- package/dist/config.d.mts +3 -4
- package/dist/config.mjs +7 -8
- package/dist/init.d.mts +11 -0
- package/dist/init.mjs +56 -1
- package/dist/lib/clock.d.mts +3 -1
- package/dist/lib/clock.mjs +12 -6
- package/dist/lib/pull-tickets.d.mts +15 -0
- package/dist/lib/pull-tickets.mjs +12 -0
- package/dist/lib/usage.d.mts +3 -1
- package/dist/lib/usage.mjs +4 -2
- package/dist/lib/work-status.d.mts +28 -24
- package/dist/lib/work-status.mjs +21 -35
- package/dist/merge-policy.mjs +7 -3
- package/dist/poller.d.mts +3 -3
- package/dist/poller.mjs +18 -14
- package/dist/pr.d.mts +26 -6
- package/dist/pr.mjs +92 -28
- package/dist/review-tickets.d.mts +12 -0
- package/dist/review-tickets.mjs +59 -0
- package/dist/review-verdict.d.mts +22 -4
- package/dist/review-verdict.mjs +55 -17
- package/dist/reviewers.d.mts +7 -4
- package/dist/reviewers.mjs +19 -12
- package/dist/runner/github-actions.mjs +6 -7
- package/dist/runner/types.d.mts +7 -6
- package/dist/specs/index.d.mts +6 -0
- package/dist/specs/index.mjs +15 -0
- package/dist/specs/openspec.d.mts +2 -0
- package/dist/specs/openspec.mjs +78 -0
- package/dist/specs/types.d.mts +53 -0
- package/dist/specs/types.mjs +4 -0
- package/dist/status.d.mts +17 -7
- package/dist/status.mjs +35 -23
- package/dist/sync.d.mts +4 -0
- package/dist/sync.mjs +14 -1
- package/dist/ticket.d.mts +15 -7
- package/dist/ticket.mjs +128 -61
- package/dist/tickets/github-access.d.mts +5 -0
- package/dist/tickets/github-access.mjs +22 -0
- package/dist/tickets/github.d.mts +10 -2
- package/dist/tickets/github.mjs +76 -20
- package/dist/tickets/index.d.mts +7 -1
- package/dist/tickets/index.mjs +15 -1
- package/dist/tickets/types.d.mts +63 -30
- package/dist/tickets/types.mjs +13 -3
- package/dist/tool-names.d.mts +2 -0
- package/dist/tool-names.mjs +3 -0
- package/dist/tools.d.mts +2 -0
- package/dist/tools.mjs +3 -0
- package/docs/builds.md +4 -1
- package/docs/cli.md +30 -11
- package/docs/configuration.md +51 -39
- package/docs/developing.md +115 -62
- package/docs/existing-repo.md +4 -3
- package/docs/github/reference.md +1 -1
- package/docs/github/setup.md +20 -3
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/plugins.md +6 -6
- package/docs/updating.md +18 -0
- package/docs/workflow.md +25 -8
- package/package.json +1 -1
- package/review.md +11 -11
- package/rules.md +52 -42
- package/skills/factory-address-review/SKILL.md +44 -42
- package/skills/factory-build/SKILL.md +71 -72
- package/skills/factory-refine/SKILL.md +31 -23
- package/skills/factory-resolve-conflicts/SKILL.md +12 -10
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-claude-review.yml +38 -1
package/dist/tickets/github.mjs
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
298
|
-
|
|
299
|
-
.
|
|
300
|
-
|
|
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
|
-
|
|
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
|
-
|
|
480
|
-
|
|
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.
|
|
576
|
+
card: board.items.get(x.key) ?? null,
|
|
521
577
|
}));
|
|
522
578
|
};
|
|
523
579
|
if (o.cli) {
|
package/dist/tickets/index.d.mts
CHANGED
|
@@ -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: {
|
package/dist/tickets/index.mjs
CHANGED
|
@@ -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) {
|
package/dist/tickets/types.d.mts
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
54
|
-
items: Map<
|
|
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:
|
|
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
|
-
|
|
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:
|
|
118
|
+
list(ticket: Key): Promise<Blocker[]>;
|
|
112
119
|
/** Records that `ticket` waits on `by`. */
|
|
113
|
-
add(ticket:
|
|
114
|
-
remove(ticket:
|
|
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:
|
|
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:
|
|
129
|
+
comment(ticket: Key, body: string, files: string[]): Promise<string>;
|
|
123
130
|
/** Replaces the body with the images attached. */
|
|
124
|
-
writeBody(ticket:
|
|
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:
|
|
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:
|
|
153
|
+
read(ticket: Key): Promise<Record<string, string>>;
|
|
147
154
|
/** Sets each field by name; null clears it. */
|
|
148
|
-
write(ticket:
|
|
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:
|
|
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:
|
|
170
|
-
writeTitle(ticket:
|
|
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:
|
|
185
|
+
comment(ticket: Key, body: string): Promise<string>;
|
|
173
186
|
/** NotFoundError when the comment is gone. */
|
|
174
|
-
editComment(id:
|
|
187
|
+
editComment(id: string, body: string): Promise<void>;
|
|
175
188
|
/** NotFoundError when the comment is gone. */
|
|
176
|
-
deleteComment(id:
|
|
177
|
-
/** Returns the new ticket's
|
|
178
|
-
open(ticket: NewTicket): Promise<
|
|
179
|
-
addLabel(ticket:
|
|
180
|
-
removeLabel(ticket:
|
|
181
|
-
/**
|
|
182
|
-
|
|
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:
|
|
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 {
|
package/dist/tickets/types.mjs
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
86
|
+
items.set(t.key, t.card);
|
|
77
87
|
return { projectId: "", fields: [], items };
|
|
78
88
|
}
|
package/dist/tool-names.d.mts
CHANGED
|
@@ -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
|
package/dist/tool-names.mjs
CHANGED
|
@@ -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
|