@davidbyoung/software-factory 0.1.11 → 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-ui-reviewer.md +2 -2
- package/dist/board.d.mts +7 -7
- package/dist/board.mjs +50 -33
- package/dist/build.d.mts +4 -0
- package/dist/build.mjs +9 -4
- package/dist/cli.mjs +8 -1
- package/dist/code-host/github.mjs +9 -4
- package/dist/code-host/types.d.mts +4 -2
- package/dist/commands.d.mts +1 -1
- package/dist/commands.mjs +15 -6
- 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 +23 -19
- package/dist/lib/work-status.mjs +14 -27
- package/dist/poller.d.mts +3 -3
- package/dist/poller.mjs +18 -14
- package/dist/pr.d.mts +18 -0
- package/dist/pr.mjs +54 -7
- package/dist/review-tickets.d.mts +12 -0
- package/dist/review-tickets.mjs +59 -0
- 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/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 +13 -7
- package/dist/ticket.mjs +94 -60
- package/dist/tickets/github.d.mts +10 -2
- package/dist/tickets/github.mjs +74 -20
- package/dist/tickets/index.d.mts +7 -1
- package/dist/tickets/index.mjs +15 -1
- package/dist/tickets/types.d.mts +59 -30
- package/dist/tickets/types.mjs +13 -3
- package/docs/cli.md +11 -7
- package/docs/configuration.md +1 -1
- package/docs/developing.md +16 -8
- package/docs/github/reference.md +1 -1
- package/docs/plugins.md +6 -6
- package/package.json +1 -1
- package/review.md +11 -11
- package/rules.md +18 -14
- package/skills/factory-address-review/SKILL.md +4 -3
- package/skills/factory-build/SKILL.md +25 -19
- package/skills/factory-refine/SKILL.md +1 -1
- package/skills/factory-resolve-conflicts/SKILL.md +4 -3
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-claude-review.yml +38 -1
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,32 +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:
|
|
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>;
|
|
181
194
|
/** Whether a comment by `author` may decide on a ticket: an answer to a
|
|
182
195
|
* question, taken as an instruction. Rejects when the system cannot
|
|
183
196
|
* say. */
|
|
184
197
|
mayDecide(author: string): Promise<boolean>;
|
|
185
|
-
/**
|
|
186
|
-
|
|
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;
|
|
187
204
|
/** The address of the ticket's page. */
|
|
188
|
-
address(ticket:
|
|
205
|
+
address(ticket: Key): string;
|
|
189
206
|
board?: BoardOps;
|
|
190
207
|
blockers?: BlockerOps;
|
|
191
208
|
labelHistory?: LabelHistoryOps;
|
|
192
209
|
attachments?: AttachmentOps;
|
|
193
210
|
fields?: FieldOps;
|
|
194
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;
|
|
195
224
|
/** A ticket or comment that does not exist, told apart from any other
|
|
196
225
|
* failure. Every adapter throws this one. */
|
|
197
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/docs/cli.md
CHANGED
|
@@ -137,21 +137,23 @@ prints what the ticket system returned as one JSON value. `edit`,
|
|
|
137
137
|
`comment`, and `open` refuse a body with a bare tag-like `<word>` the
|
|
138
138
|
ticket system would swallow, name it, and post nothing.
|
|
139
139
|
|
|
140
|
+
N is the ticket's key as your ticket system writes it: `12` on GitHub.
|
|
141
|
+
|
|
140
142
|
| Command | What it does |
|
|
141
143
|
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
142
144
|
| `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
|
|
143
145
|
| `factory ticket answers N` | Prints each comment on N that counts as an answer: its author can write to the repository, and it is not the factory's own. Says so when there is none |
|
|
144
|
-
| `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `
|
|
145
|
-
| `factory ticket list` | Lists the open tickets:
|
|
146
|
+
| `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), `body`, or `ref`, how the ticket system writes N in prose, such as `#12`, and nothing else |
|
|
147
|
+
| `factory ticket list` | Lists the open tickets: key, title, and labels, separated by tabs |
|
|
146
148
|
| `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
|
|
147
149
|
| `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
|
|
148
150
|
| `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
|
|
149
|
-
| `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its
|
|
151
|
+
| `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its key. `--label LABEL` adds a label |
|
|
150
152
|
| `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
151
153
|
| `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
|
|
152
|
-
| `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12"
|
|
154
|
+
| `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12". `--part` prints the text that says it builds part of N, such as "Part of #4" |
|
|
153
155
|
| `factory ticket branch N` | Prints the branch a build of N pushes, from [`code-host.branch-name`](configuration.md#code-host), such as `12` or `feature/octocat/12`. Exits 1 when N does not exist, or the pattern has `{user}` and `gh` is not signed in |
|
|
154
|
-
| `factory ticket blockers N` | One line per ticket N waits on: its
|
|
156
|
+
| `factory ticket blockers N` | One line per ticket N waits on: the ticket, as its system writes it, and whether it is open |
|
|
155
157
|
| `factory ticket block N --by M` | Records that N waits on M |
|
|
156
158
|
| `factory ticket unblock N --by M` | Removes that record |
|
|
157
159
|
| `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
|
|
@@ -163,7 +165,7 @@ ticket system would swallow, name it, and post nothing.
|
|
|
163
165
|
| `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
|
|
164
166
|
| `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
|
|
165
167
|
| `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
|
|
166
|
-
| `factory ticket cost N` | Notes what this session spent on N since it started
|
|
168
|
+
| `factory ticket cost N` | Notes what this session spent on ticket N since it started |
|
|
167
169
|
| `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
|
|
168
170
|
|
|
169
171
|
`factory ticket refined N` posts nothing and exits 1 when N's body lacks a
|
|
@@ -183,7 +185,8 @@ ticket system.
|
|
|
183
185
|
| `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
|
|
184
186
|
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
|
|
185
187
|
| `factory pr resolve N COMMENT` | Resolves a thread |
|
|
186
|
-
| `factory pr closes N` | The tickets N closes
|
|
188
|
+
| `factory pr closes N` | The tickets N closes, by key |
|
|
189
|
+
| `factory pr cost N` | Notes what this session spent on pull request N since it started |
|
|
187
190
|
| `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
|
|
188
191
|
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
|
|
189
192
|
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
|
|
@@ -263,6 +266,7 @@ the commit hook blocks a session's git command with it.
|
|
|
263
266
|
| `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
|
|
264
267
|
| `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
|
|
265
268
|
| `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`pr-review.commands`](configuration.md#pr-review) | Built |
|
|
269
|
+
| `factory review tickets N` | The review workflow | Each ticket pull request N closes or builds part of, headed by its name and title, with its body | Built |
|
|
266
270
|
| `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
|
|
267
271
|
| `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
|
|
268
272
|
| `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
|
package/docs/configuration.md
CHANGED
|
@@ -430,7 +430,7 @@ it out:
|
|
|
430
430
|
|
|
431
431
|
| Placeholder | What it becomes | For ticket 12 |
|
|
432
432
|
| ----------- | ------------------------------------ | ------------- |
|
|
433
|
-
| `{ticket}` | The ticket's
|
|
433
|
+
| `{ticket}` | The ticket's key, without `#` | `12` |
|
|
434
434
|
| `{user}` | The GitHub account the build runs as | `octocat` |
|
|
435
435
|
|
|
436
436
|
In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
|
package/docs/developing.md
CHANGED
|
@@ -226,19 +226,22 @@ the work to that type's adapter.** An adapter is one module in
|
|
|
226
226
|
|
|
227
227
|
| Operation | In `Tickets` | What it returns or does |
|
|
228
228
|
| ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
229
|
-
|
|
|
230
|
-
|
|
|
229
|
+
| Parse a key | `key` | The key a person typed, or `KeyError` saying what a key looks like in this system. GitHub's are numbers, such as `12` |
|
|
230
|
+
| Write a ticket | `ref` | How the ticket is written in prose and output, such as `#12` |
|
|
231
|
+
| Read a ticket | `read` | Its key, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
|
|
232
|
+
| List open tickets | `listOpen` | Key, title, and labels, for every open ticket however many there are |
|
|
231
233
|
| Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
|
|
232
234
|
| Write a ticket's body | `writeBody` | |
|
|
233
235
|
| Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
|
|
234
236
|
| Edit a comment | `editComment` | By its ID |
|
|
235
237
|
| Delete a comment | `deleteComment` | By its ID |
|
|
236
238
|
| Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
|
|
237
|
-
| Open a ticket | `open` | With a title, a body, and labels. Returns its
|
|
239
|
+
| Open a ticket | `open` | With a title, a body, and labels. Returns its key |
|
|
238
240
|
| Add or remove a label | `addLabel`, `removeLabel` | |
|
|
239
241
|
| Who may decide | `mayDecide` | Whether a comment's author may decide on a ticket, so `factory ticket answers` takes their comment as an answer. GitHub's asks whether they can write to the repository. Rejects when it cannot say |
|
|
240
|
-
| Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12"
|
|
241
|
-
|
|
|
242
|
+
| Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12", and what says it builds part of one, "Part of #4" |
|
|
243
|
+
| Links in a body | `linksIn` | The tickets a pull request's body closes, and those it builds part of, each in the body's order |
|
|
244
|
+
| The address of a ticket | `address` | Its page, which the views link a ticket to |
|
|
242
245
|
|
|
243
246
|
"Read everything at once" has a default, `readAll` in
|
|
244
247
|
`src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
|
|
@@ -281,13 +284,18 @@ package.
|
|
|
281
284
|
What stays above the interface: working out a ticket's state from its
|
|
282
285
|
marker comments, costs, and the formatting of every view, in
|
|
283
286
|
`src/lib/work-status.mts` and the commands. They are the factory's own
|
|
284
|
-
logic, the same for any system.
|
|
287
|
+
logic, the same for any system. Nothing there writes `#` or reads a link
|
|
288
|
+
from a pull request's body itself: it asks the adapter. The code host's
|
|
289
|
+
own links, such as GitHub's closing references, count only when the
|
|
290
|
+
tickets are the code host's own (`src/lib/pull-tickets.mts`).
|
|
285
291
|
|
|
286
292
|
A second adapter exists from the start: an in-memory one,
|
|
287
293
|
`tests/memory-tickets.ts`, that every command's tests run against. It
|
|
288
294
|
keeps the interface honest, since anything the tests need has to go
|
|
289
|
-
through it.
|
|
290
|
-
|
|
295
|
+
through it. Its keys are numbers, as GitHub's are; with `strict` they are
|
|
296
|
+
keys like `PROJ-12`, and comment IDs and authors are opaque text, as Jira
|
|
297
|
+
and Linear give them, so a command that treats either as a number fails
|
|
298
|
+
there. The GitHub adapter has its own tests against recorded responses.
|
|
291
299
|
|
|
292
300
|
What an adapter does not cover: pull requests, reviews, and checks, which
|
|
293
301
|
are the code host's, and where an unattended build runs, which is the
|
package/docs/github/reference.md
CHANGED
|
@@ -87,7 +87,7 @@ anything to do, and stops there when there is not.
|
|
|
87
87
|
| `factory-poller.yml` | Every `builds.poll-minutes` minutes, or by hand | Runs one pass of the poller, starting a build for each Ready ticket. Written once `builds.trigger` is `github-action` |
|
|
88
88
|
|
|
89
89
|
**Starting a build by hand.** The Actions tab, "Factory build", "Run
|
|
90
|
-
workflow", and the ticket's
|
|
90
|
+
workflow", and the ticket's key, such as `12`. The board's "Runs in" field then shows
|
|
91
91
|
"Actions", and "Session" the run's link. The run's log also shows each
|
|
92
92
|
tool call the session was denied, with the reason.
|
|
93
93
|
|
package/docs/plugins.md
CHANGED
|
@@ -74,12 +74,12 @@ plugins:
|
|
|
74
74
|
skill: acme-refine
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
| Step | What happens
|
|
78
|
-
| ----------- |
|
|
79
|
-
| **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited
|
|
80
|
-
| **Handed** | The ticket's
|
|
81
|
-
| **Returns** | A ticket a build can start from: everything in the list below
|
|
82
|
-
| **Then** | The ticket waits for your approval, and the build reads what the refiner left
|
|
77
|
+
| Step | What happens |
|
|
78
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
|
+
| **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
|
|
80
|
+
| **Handed** | The ticket's key. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
|
|
81
|
+
| **Returns** | A ticket a build can start from: everything in the list below |
|
|
82
|
+
| **Then** | The ticket waits for your approval, and the build reads what the refiner left |
|
|
83
83
|
|
|
84
84
|
**What a refiner must deliver.** The board and the build read these, so a
|
|
85
85
|
refiner that leaves one out leaves a ticket that cannot be built.
|
package/package.json
CHANGED
package/review.md
CHANGED
|
@@ -56,21 +56,21 @@ defend.
|
|
|
56
56
|
the facts; if you still disagree, say so once in the summary, with your
|
|
57
57
|
evidence, rather than opening a new thread.
|
|
58
58
|
|
|
59
|
-
4. Read what the pull request was asked to do
|
|
60
|
-
|
|
59
|
+
4. Read what the pull request was asked to do: its body, and the tickets it
|
|
60
|
+
builds, which the workflow has read for you into the file TICKETS names.
|
|
61
|
+
Read that file with the Read tool. Each ticket there starts with a `## `
|
|
62
|
+
line naming it and its title. When the file says the tickets could not be
|
|
63
|
+
read, say so in the summary and go by the body.
|
|
61
64
|
|
|
62
65
|
```bash
|
|
63
|
-
gh pr view PR_NUMBER --json body
|
|
64
|
-
gh api graphql -F n=ISSUE_NUMBER -f query='query($n: Int!) { repository(owner: "OWNER", name: "NAME") { issue(number: $n) { body } } }' --jq .data.repository.issue.body
|
|
66
|
+
gh pr view PR_NUMBER --json body
|
|
65
67
|
```
|
|
66
68
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
The issue's "Spec" and "Acceptance criteria" sections are what the
|
|
70
|
-
change must do, and its "Decisions" are settled. An issue with neither
|
|
69
|
+
The ticket's "Spec" and "Acceptance criteria" sections are what the
|
|
70
|
+
change must do, and its "Decisions" are settled. A ticket with neither
|
|
71
71
|
is held only to what it plainly asks for: a fix it suggests is not a
|
|
72
|
-
criterion. The follow-ups
|
|
73
|
-
body says this pull request built. A pull request that
|
|
72
|
+
criterion. The follow-ups ticket is held to the lines the
|
|
73
|
+
body says this pull request built. A pull request that builds no ticket,
|
|
74
74
|
such as a source audit, has only its body to go by.
|
|
75
75
|
|
|
76
76
|
## What to look for
|
|
@@ -79,7 +79,7 @@ defend.
|
|
|
79
79
|
that is silently dropped.
|
|
80
80
|
- **What it was asked to do.** A Spec line or criterion from step 4 that
|
|
81
81
|
the whole pull request, `git diff origin/DEFAULT...HEAD`, does not meet, or
|
|
82
|
-
meets only in part, is a finding, since the merge closes the
|
|
82
|
+
meets only in part, is a finding, since the merge closes the ticket as
|
|
83
83
|
done: High when a user would see the gap, Medium otherwise. Behavior
|
|
84
84
|
no line asked for is Medium, unless the body or the owner's comments on
|
|
85
85
|
the pull request explain it. Quote the line either way.
|
package/rules.md
CHANGED
|
@@ -109,8 +109,9 @@ discovering it at push time.
|
|
|
109
109
|
`npx --no-install factory pr state N --wait`, and does not run it, since
|
|
110
110
|
nothing can wake it once it stops.
|
|
111
111
|
- **A pull request that resolves an issue closes it.** When asked to open
|
|
112
|
-
one, start the body with
|
|
113
|
-
so the merge closes them. Check that
|
|
112
|
+
one, start the body with the line `npx --no-install factory ticket link N`
|
|
113
|
+
prints for each issue the branch resolves, so the merge closes them. Check that `npx --no-install factory pr closes PR`
|
|
114
|
+
prints each one.
|
|
114
115
|
- **After pushing, check for review automatically.** The `Claude review`
|
|
115
116
|
workflow reviews every push to a PR. If an open PR exists for the branch,
|
|
116
117
|
wait for the review of that push, then work it with the `factory-address-review` skill
|
|
@@ -167,7 +168,7 @@ always the owner's.
|
|
|
167
168
|
|
|
168
169
|
## Spec track
|
|
169
170
|
|
|
170
|
-
The
|
|
171
|
+
The ticket is the spec: `factory-refine` writes it, the owner
|
|
171
172
|
approves it by moving its card to Ready or telling a session to build
|
|
172
173
|
it, and `factory-build` builds it. A change that adds or alters behavior
|
|
173
174
|
a user can see carries the `spec` label, which `factory-refine` adds,
|
|
@@ -217,8 +218,8 @@ npx --no-install factory ticket blockers N
|
|
|
217
218
|
npx --no-install factory ticket unblock N --by M
|
|
218
219
|
```
|
|
219
220
|
|
|
220
|
-
`blockers` prints one line per ticket N waits on,
|
|
221
|
-
it is open. A ticket system without blockers says so: check with
|
|
221
|
+
`blockers` prints one line per ticket N waits on, as the ticket system
|
|
222
|
+
writes it, and whether it is open. A ticket system without blockers says so: check with
|
|
222
223
|
`npx --no-install factory ticket supports blockers`.
|
|
223
224
|
|
|
224
225
|
## Follow-ups
|
|
@@ -235,18 +236,20 @@ labeled `follow-up`, holding a checklist. A line leads with the file or
|
|
|
235
236
|
page it is about:
|
|
236
237
|
|
|
237
238
|
```
|
|
238
|
-
- [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building
|
|
239
|
+
- [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building <ticket>. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
|
|
239
240
|
```
|
|
240
241
|
|
|
241
242
|
It is added with the file and the rest of the line as two arguments, and
|
|
242
243
|
the script opens the issue when none is open:
|
|
243
244
|
|
|
244
245
|
```bash
|
|
245
|
-
npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building
|
|
246
|
+
npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building TICKET. The rule it breaks."
|
|
246
247
|
```
|
|
247
248
|
|
|
248
|
-
|
|
249
|
-
|
|
249
|
+
TICKET is the ticket as its system writes it, which
|
|
250
|
+
`npx --no-install factory ticket view N --field ref` prints, such as `#12`.
|
|
251
|
+
A reviewer that does not know the ticket writes `TICKET` as it stands, and
|
|
252
|
+
whoever appends the line fills it in.
|
|
250
253
|
|
|
251
254
|
A placeholder or tag name in issue or comment text, such as `<slug>` or
|
|
252
255
|
`<code>`, goes in backticks: GitHub drops an unknown tag and renders a
|
|
@@ -271,11 +274,12 @@ hook refuses the same in text sent to GitHub directly, as the
|
|
|
271
274
|
|
|
272
275
|
The follow-ups issue builds as one branch and one pull request, one commit
|
|
273
276
|
per line, once the owner approves it, by moving its card to Ready or
|
|
274
|
-
telling a session to build it. The pull request closes it with
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
277
|
+
telling a session to build it. The pull request closes it with the line
|
|
278
|
+
`npx --no-install factory ticket link N` prints only when every line is
|
|
279
|
+
checked; otherwise it starts with the line
|
|
280
|
+
`npx --no-install factory ticket link N --part` prints, and the unchecked
|
|
281
|
+
lines wait there. The sync reads that line as a partial build, so any
|
|
282
|
+
other link to the follow-ups issue words it differently. It has no spec tool change. `factory-build` appends a line and
|
|
279
283
|
builds the issue; `factory-refine` refines it per line. Its lines can be
|
|
280
284
|
about anything, so the one pull request waits for the owner when any line
|
|
281
285
|
touches a file that does, and gets the fresh-agent trace ("Changing the
|
|
@@ -393,8 +393,9 @@ Never accept or reject from reading alone. Each finding gets evidence:
|
|
|
393
393
|
there, say so rather than reasoning from memory.
|
|
394
394
|
- **A claim about the codebase** gets a grep or a file read at the cited line.
|
|
395
395
|
- **A finding that would reverse a choice** also gets the recorded reason:
|
|
396
|
-
read the commit message, the pull request's body, and the
|
|
397
|
-
|
|
396
|
+
read the commit message, the pull request's body, and the Decisions of
|
|
397
|
+
each ticket `npx --no-install factory pr closes PR` prints, with
|
|
398
|
+
`npx --no-install factory ticket view N`, before accepting it. A session without the build context has only these. If
|
|
398
399
|
the finding conflicts with a recorded decision and the evidence does not
|
|
399
400
|
settle it, reply with both and leave the thread open for the owner.
|
|
400
401
|
|
|
@@ -551,7 +552,7 @@ again. Add whether the tests are good enough to make a swap verifiable.
|
|
|
551
552
|
First, note what this round of work cost, on the pull request:
|
|
552
553
|
|
|
553
554
|
```bash
|
|
554
|
-
npx --no-install factory
|
|
555
|
+
npx --no-install factory pr cost PR
|
|
555
556
|
```
|
|
556
557
|
|
|
557
558
|
It posts what the session spent at API list prices since its last note, or
|