@davidbyoung/software-factory 0.0.0-stage → 0.1.0

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 (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +205 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. package/workflows/factory-review.yml +75 -0
@@ -0,0 +1,158 @@
1
+ // How the GitHub adapter and `src/code-host/` reach GitHub: one function for a
2
+ // REST call and one for a GraphQL query. There are two. `ghTransport` runs
3
+ // the GitHub CLI, for sessions and CI. `fetchTransport` calls the API with a
4
+ // token, for the poller, which runs with no `gh` and no install. A failed
5
+ // call rejects, so a failed read is never mistaken for an empty answer.
6
+ //
7
+ // Node built-ins only: the poller's image copies this file.
8
+ import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
9
+ import { tmpdir } from "node:os";
10
+ import { join } from "node:path";
11
+ /** A call GitHub answered with an HTTP error. */
12
+ export class HttpError extends Error {
13
+ // A plain field, not a parameter property: the poller runs this file
14
+ // unbuilt, and Node's type stripping refuses parameter properties.
15
+ status;
16
+ /** What GitHub said was wrong: the `message` in its answer, or the status
17
+ * text when it gave none. */
18
+ reason;
19
+ constructor(status, message, reason = "") {
20
+ super(message);
21
+ this.name = "HttpError";
22
+ this.status = status;
23
+ this.reason = reason;
24
+ }
25
+ }
26
+ /** The HTTP status in an error a transport threw, or null. */
27
+ export function statusOf(error) {
28
+ if (error instanceof HttpError)
29
+ return error.status;
30
+ const match = /HTTP (\d{3})\b/.exec(String(error));
31
+ return match ? Number(match[1]) : null;
32
+ }
33
+ function ghFields(fields) {
34
+ const args = [];
35
+ for (const [name, value] of Object.entries(fields)) {
36
+ if (Array.isArray(value))
37
+ for (const item of value)
38
+ args.push("-f", `${name}[]=${item}`);
39
+ else if (typeof value === "object")
40
+ for (const [key, item] of Object.entries(value))
41
+ args.push("-f", `${name}[${key}]=${item}`);
42
+ else
43
+ args.push(typeof value === "string" ? "-f" : "-F", `${name}=${String(value)}`);
44
+ }
45
+ return args;
46
+ }
47
+ function parse(text) {
48
+ return (text.trim() ? JSON.parse(text) : undefined);
49
+ }
50
+ /** The GitHub CLI as a transport. */
51
+ export function ghTransport(run) {
52
+ return {
53
+ async rest(method, path, options = {}) {
54
+ if (options.body !== undefined) {
55
+ const dir = mkdtempSync(join(tmpdir(), "factory-body-"));
56
+ const file = join(dir, "body.json");
57
+ writeFileSync(file, JSON.stringify(options.body));
58
+ try {
59
+ return parse(await run(["api", "-X", method, path, "--input", file]));
60
+ }
61
+ finally {
62
+ rmSync(dir, { recursive: true, force: true });
63
+ }
64
+ }
65
+ if (options.paginate) {
66
+ const pages = parse(await run(["api", "--paginate", "--slurp", path]));
67
+ return pages.flat();
68
+ }
69
+ const args = method === "GET" ? ["api", path] : ["api", "-X", method, path];
70
+ args.push(...ghFields(options.fields ?? {}));
71
+ return parse(await run(args));
72
+ },
73
+ async graphql(query, variables = {}) {
74
+ const args = ["api", "graphql", "-f", `query=${query}`];
75
+ for (const [name, value] of Object.entries(variables)) {
76
+ if (value === null)
77
+ continue;
78
+ args.push(typeof value === "string" ? "-f" : "-F", `${name}=${value}`);
79
+ }
80
+ const result = parse(await run(args));
81
+ if (result.errors?.length)
82
+ throw new Error(result.errors.map((e) => e.message).join("; "));
83
+ return result;
84
+ },
85
+ // Without the flag the CLI refuses to print an answer that holds a
86
+ // terminal's escape sequences, as a job's log does.
87
+ text: (path) => run(["api", "--allow-escape-sequences", path]),
88
+ };
89
+ }
90
+ const API = "https://api.github.com";
91
+ /** The `message` in an error answer's JSON body, or "". */
92
+ async function answerMessage(response) {
93
+ try {
94
+ const body = JSON.parse(await response.text());
95
+ return typeof body.message === "string" ? body.message : "";
96
+ }
97
+ catch {
98
+ return "";
99
+ }
100
+ }
101
+ /** The next page's address from a Link header, or null. */
102
+ export function nextLink(link) {
103
+ if (!link)
104
+ return null;
105
+ for (const part of link.split(",")) {
106
+ const match = /<([^>]+)>;\s*rel="next"/.exec(part);
107
+ if (match)
108
+ return match[1];
109
+ }
110
+ return null;
111
+ }
112
+ /** The API called with a token, as the poller does. Each call gives up
113
+ * after `timeoutMs`. */
114
+ export function fetchTransport(options) {
115
+ const call = async (method, url, body) => {
116
+ const response = await options.fetch(url, {
117
+ method,
118
+ headers: {
119
+ Authorization: `Bearer ${options.token}`,
120
+ Accept: "application/vnd.github+json",
121
+ "User-Agent": options.userAgent ?? "software-factory",
122
+ },
123
+ body: body === undefined ? undefined : JSON.stringify(body),
124
+ signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
125
+ });
126
+ if (!response.ok) {
127
+ const path = url.startsWith(API) ? url.slice(API.length + 1) : url;
128
+ const said = await answerMessage(response);
129
+ const reason = said || response.statusText;
130
+ throw new HttpError(response.status, `GitHub ${path} answered ${response.status} (HTTP ${response.status})${said ? `: ${said}` : ""}`, reason);
131
+ }
132
+ return response;
133
+ };
134
+ const json = async (response) => parse(await response.text());
135
+ return {
136
+ async rest(method, path, opts = {}) {
137
+ const url = `${API}/${path}`;
138
+ if (opts.paginate) {
139
+ const items = [];
140
+ for (let next = url; next;) {
141
+ const response = await call("GET", next);
142
+ items.push(...(await json(response)));
143
+ next = nextLink(response.headers.get("link"));
144
+ }
145
+ return items;
146
+ }
147
+ const body = opts.body ?? opts.fields;
148
+ return json(await call(method, url, method === "GET" || body === undefined ? undefined : body));
149
+ },
150
+ async graphql(query, variables = {}) {
151
+ const result = await json(await call("POST", `${API}/graphql`, { query, variables }));
152
+ if (result.errors?.length)
153
+ throw new Error(`GitHub graphql: ${result.errors.map((e) => e.message).join("; ")}`);
154
+ return result;
155
+ },
156
+ text: async (path) => (await call("GET", `${API}/${path}`)).text(),
157
+ };
158
+ }
@@ -0,0 +1,191 @@
1
+ export type TicketComment = {
2
+ id: number;
3
+ author: string;
4
+ createdAt: string;
5
+ body: string;
6
+ };
7
+ /** A card's place on the board and its fields. */
8
+ export type BoardItem = {
9
+ /** The system's own ID for the card, for the adapter's writes. */
10
+ itemId: string;
11
+ number: number;
12
+ status: string | null;
13
+ /** When Status last changed. */
14
+ updatedAt: string | null;
15
+ session: string;
16
+ runsIn: string;
17
+ /** The Cost field, which only the sync writes. */
18
+ cost?: number | null;
19
+ };
20
+ export type Ticket = {
21
+ number: number;
22
+ title: string;
23
+ state: "open" | "closed";
24
+ closedAt: string | null;
25
+ labels: string[];
26
+ body: string;
27
+ comments: TicketComment[];
28
+ /** The ticket's card, when "Read everything at once" was asked for the
29
+ * board and the adapter has one; null when it is not on the board. */
30
+ card?: BoardItem | null;
31
+ };
32
+ export type TicketSummary = {
33
+ number: number;
34
+ title: string;
35
+ labels: string[];
36
+ };
37
+ /** A board field and, for a single select, its options. */
38
+ export type BoardField = {
39
+ id: string;
40
+ name: string;
41
+ dataType: string;
42
+ options?: {
43
+ id: string;
44
+ name: string;
45
+ }[];
46
+ };
47
+ export type Board = {
48
+ /** The system's own ID for the board, for the adapter's writes. */
49
+ projectId: string;
50
+ /** The board's own title, for the report `factory board check` prints. */
51
+ title?: string;
52
+ fields: BoardField[];
53
+ /** This repository's tickets on the board, by number. */
54
+ items: Map<number, BoardItem>;
55
+ };
56
+ /** One write to a card's field. */
57
+ export type Write = {
58
+ field: string;
59
+ optionName: string;
60
+ } | {
61
+ field: string;
62
+ text: string;
63
+ } | {
64
+ field: string;
65
+ number: number;
66
+ } | {
67
+ field: string;
68
+ clear: true;
69
+ };
70
+ export type BoardOps = {
71
+ /** Every card and the board's fields. */
72
+ read(): Promise<Board>;
73
+ /** Puts the ticket on the board, and returns its card's ID. */
74
+ add(ticket: number): Promise<string>;
75
+ /** Writes the fields of a card already on the board. */
76
+ set(itemId: string, writes: Write[]): Promise<void>;
77
+ /** The open boards the repository's owner has. */
78
+ list(): Promise<{
79
+ number: number;
80
+ title: string;
81
+ }[]>;
82
+ /** Creates a board under the repository's owner, linked to the
83
+ * repository, and returns its number. */
84
+ create(title: string): Promise<number>;
85
+ /** Gives board `number` each of `columns` it lacks, the columns in that
86
+ * order before any other it has, and returns the ones it added. */
87
+ addColumns(number: number, columns: string[]): Promise<string[]>;
88
+ /** Gives board `number` each of `fields` it lacks, by name, and returns
89
+ * the names of the ones it added. */
90
+ addFields(number: number, fields: NewField[]): Promise<string[]>;
91
+ };
92
+ /** A board field to add: text, a number, or a single select with its
93
+ * options. */
94
+ export type NewField = {
95
+ name: string;
96
+ type: "text" | "number";
97
+ } | {
98
+ name: string;
99
+ type: "select";
100
+ options: string[];
101
+ };
102
+ export type Blocker = {
103
+ number: number;
104
+ state: "open" | "closed";
105
+ };
106
+ export type BlockerOps = {
107
+ /** What a ticket waits on, open or closed. */
108
+ list(ticket: number): Promise<Blocker[]>;
109
+ /** Records that `ticket` waits on `by`. */
110
+ add(ticket: number, by: number): Promise<void>;
111
+ remove(ticket: number, by: number): Promise<void>;
112
+ };
113
+ export type LabelHistoryOps = {
114
+ /** Whether the label was ever removed from the ticket. */
115
+ wasRemoved(ticket: number, label: string): Promise<boolean>;
116
+ };
117
+ export type AttachmentOps = {
118
+ /** Comments with the images attached; returns the comment's ID. */
119
+ comment(ticket: number, body: string, files: string[]): Promise<number>;
120
+ /** Replaces the body with the images attached. */
121
+ writeBody(ticket: number, body: string, files: string[]): Promise<void>;
122
+ };
123
+ export declare const GROUPS: readonly ["board", "blockers", "label-history", "attachments"];
124
+ export type Group = (typeof GROUPS)[number];
125
+ export type NewTicket = {
126
+ title: string;
127
+ body: string;
128
+ labels: string[];
129
+ };
130
+ export type Tickets = {
131
+ /** The ticket, or NotFoundError when there is none. */
132
+ read(ticket: number): Promise<Ticket>;
133
+ /** Every open ticket, however many there are. */
134
+ listOpen(): Promise<TicketSummary[]>;
135
+ /** Every open ticket and the 30 closed ones most recently updated, as
136
+ * `read` returns each, with its card when `board` is asked and the
137
+ * adapter has the board group. Optional: `readAll` in `index.mts` builds
138
+ * it from `listOpen` and `read` when an adapter does not. */
139
+ readAll?(options?: {
140
+ board?: boolean;
141
+ }): Promise<Ticket[]>;
142
+ writeBody(ticket: number, body: string): Promise<void>;
143
+ writeTitle(ticket: number, title: string): Promise<void>;
144
+ /** Returns the comment's ID. The body is posted as given. */
145
+ comment(ticket: number, body: string): Promise<number>;
146
+ /** NotFoundError when the comment is gone. */
147
+ editComment(id: number, body: string): Promise<void>;
148
+ /** NotFoundError when the comment is gone. */
149
+ deleteComment(id: number): Promise<void>;
150
+ /** Returns the new ticket's number. */
151
+ open(ticket: NewTicket): Promise<number>;
152
+ addLabel(ticket: number, label: string): Promise<void>;
153
+ removeLabel(ticket: number, label: string): Promise<void>;
154
+ /** What makes a merged pull request close the ticket. */
155
+ linkText(ticket: number): string;
156
+ /** The address of the ticket's page. */
157
+ address(ticket: number): string;
158
+ board?: BoardOps;
159
+ blockers?: BlockerOps;
160
+ labelHistory?: LabelHistoryOps;
161
+ attachments?: AttachmentOps;
162
+ };
163
+ /** A ticket or comment that does not exist, told apart from any other
164
+ * failure. Every adapter throws this one. */
165
+ export declare class NotFoundError extends Error {
166
+ constructor(what: string);
167
+ }
168
+ /** A command that needs an optional group its adapter lacks. */
169
+ export declare class UnsupportedError extends Error {
170
+ constructor(group: Group);
171
+ }
172
+ /** Whether the adapter has the optional group. */
173
+ export declare function supports(tickets: Tickets, group: Group): boolean;
174
+ /** The group's operations, or UnsupportedError naming it. */
175
+ export declare function need<G extends Group>(tickets: Tickets, group: G): NonNullable<Tickets[GroupKey<G>]>;
176
+ declare const GROUP_KEYS: {
177
+ readonly board: "board";
178
+ readonly blockers: "blockers";
179
+ readonly "label-history": "labelHistory";
180
+ readonly attachments: "attachments";
181
+ };
182
+ type GroupKey<G extends Group> = (typeof GROUP_KEYS)[G];
183
+ /** "Read everything at once" from the list and the single reads, for an
184
+ * adapter that does not override it. It returns the open tickets: a list of
185
+ * open tickets cannot name the closed ones. */
186
+ export declare function readAll(tickets: Tickets, options?: {
187
+ board?: boolean;
188
+ }): Promise<Ticket[]>;
189
+ /** The cards `readAll` carried, as a Board, for the code that reads one. */
190
+ export declare function boardOf(tickets: Ticket[]): Board;
191
+ export {};
@@ -0,0 +1,76 @@
1
+ // The one interface every ticket system's adapter implements. The factory's
2
+ // commands read and write tickets only through it, so a second system is an
3
+ // adapter added beside `github.mts`, not a rewrite of the commands. What a
4
+ // ticket's state means (the marker comments, costs, and the views) stays
5
+ // above it, in `lib/work-status.mts` and the commands.
6
+ //
7
+ // Node built-ins only: the poller's image copies this file.
8
+ export const GROUPS = [
9
+ "board",
10
+ "blockers",
11
+ "label-history",
12
+ "attachments",
13
+ ];
14
+ /** A ticket or comment that does not exist, told apart from any other
15
+ * failure. Every adapter throws this one. */
16
+ export class NotFoundError extends Error {
17
+ constructor(what) {
18
+ super(`${what} was not found`);
19
+ this.name = "NotFoundError";
20
+ }
21
+ }
22
+ /** A command that needs an optional group its adapter lacks. */
23
+ export class UnsupportedError extends Error {
24
+ constructor(group) {
25
+ super(`This ticket system does not support ${group}; check with \`factory ticket supports ${group}\` first.`);
26
+ this.name = "UnsupportedError";
27
+ }
28
+ }
29
+ /** Whether the adapter has the optional group. */
30
+ export function supports(tickets, group) {
31
+ switch (group) {
32
+ case "board":
33
+ return tickets.board !== undefined;
34
+ case "blockers":
35
+ return tickets.blockers !== undefined;
36
+ case "label-history":
37
+ return tickets.labelHistory !== undefined;
38
+ case "attachments":
39
+ return tickets.attachments !== undefined;
40
+ }
41
+ }
42
+ /** The group's operations, or UnsupportedError naming it. */
43
+ export function need(tickets, group) {
44
+ const key = GROUP_KEYS[group];
45
+ const ops = tickets[key];
46
+ if (ops === undefined)
47
+ throw new UnsupportedError(group);
48
+ return ops;
49
+ }
50
+ const GROUP_KEYS = {
51
+ board: "board",
52
+ blockers: "blockers",
53
+ "label-history": "labelHistory",
54
+ attachments: "attachments",
55
+ };
56
+ /** "Read everything at once" from the list and the single reads, for an
57
+ * adapter that does not override it. It returns the open tickets: a list of
58
+ * open tickets cannot name the closed ones. */
59
+ export async function readAll(tickets, options = {}) {
60
+ if (tickets.readAll)
61
+ return tickets.readAll(options);
62
+ const open = await tickets.listOpen();
63
+ const read = await Promise.all(open.map((t) => tickets.read(t.number)));
64
+ if (!options.board || !tickets.board)
65
+ return read;
66
+ const board = await tickets.board.read();
67
+ return read.map((t) => ({ ...t, card: board.items.get(t.number) ?? null }));
68
+ }
69
+ /** The cards `readAll` carried, as a Board, for the code that reads one. */
70
+ export function boardOf(tickets) {
71
+ const items = new Map();
72
+ for (const t of tickets)
73
+ if (t.card)
74
+ items.set(t.number, t.card);
75
+ return { projectId: "", fields: [], items };
76
+ }
package/docs/builds.md ADDED
@@ -0,0 +1,227 @@
1
+ # Builds in the cloud
2
+
3
+ A build is one session taking one approved ticket to a pull request. You
4
+ can always build a ticket by asking a session on your machine. A build in
5
+ the cloud does the same with nobody at the keyboard: it runs on your code
6
+ host's cloud runner, and you read its log or its pull request afterward.
7
+
8
+ On GitHub, the cloud runner is GitHub Actions.
9
+ [Setting up on GitHub](github/setup.md#builds-in-the-cloud) has the steps,
10
+ and the [reference](github/reference.md#workflows) has what runs there.
11
+
12
+ ## Three ways a build starts
13
+
14
+ | You | The build runs | You need |
15
+ | ----------------------------------- | --------------------------------------- | ----------------------------------------------------------------- |
16
+ | Ask a session: "build ticket 12" | In that session, wherever you opened it | Nothing |
17
+ | Run `factory build 12` | In the cloud | Builds in the cloud set up |
18
+ | Move the ticket to Ready on a board | In the cloud, within a minute | Builds in the cloud set up, and [the poller](#the-poller) running |
19
+
20
+ Which of the last two you use is `builds.trigger` in your
21
+ [settings](configuration.md#builds):
22
+
23
+ | `trigger` | Moving a ticket to Ready |
24
+ | --------------- | -------------------------------------------------------------------------------------------------------- |
25
+ | `manual` | Records your approval and starts nothing. The default |
26
+ | `own-server` | Starts a build within a minute, through the poller you host |
27
+ | `github-action` | _[Planned](developing.md#what-is-built)_: starts one within minutes, from a schedule on the cloud runner |
28
+
29
+ `manual` is a fine place to stay. Asking a session and running
30
+ `factory build` work whatever the trigger.
31
+
32
+ ## What a build in the cloud does
33
+
34
+ ```text
35
+ $ factory build 12
36
+ Started a build of ticket 12 in the cloud:
37
+ https://your-code-host/your-name/your-repo/runs/123456789
38
+ ```
39
+
40
+ Anyone who can write to the repository can start one, and the claim
41
+ comment on the ticket names who did. The run's log shows each thing the
42
+ session says and each command it runs, as it happens, then the session's
43
+ turns and cost. The board shows the ticket In progress, with where it runs
44
+ and the run's link.
45
+
46
+ It ends as any build does: a pull request marked ready, its review worked,
47
+ and a report posted on the ticket. Nothing watches the pull request once
48
+ the run ends.
49
+
50
+ **How long it may run.** A build's session may run for 230 minutes, which
51
+ [`session-minutes`](configuration.md#session-minutes) changes. A build that
52
+ ends without opening a pull request releases its claim in its last step,
53
+ so a failed run does not hold its ticket.
54
+
55
+ **What it needs.** Two credentials, stored as secrets on the code host:
56
+ the agent's token, which pays for the session, and an access token for the
57
+ code host, which the build acts as. [Setting up on
58
+ GitHub](github/setup.md#secrets) says how to make and store each.
59
+
60
+ **Who it acts as.** The build acts as whoever owns that access token. Its
61
+ commits name your coding agent as their author and that account as their
62
+ committer, and its pull request and comments are that account's. When the token is yours, that is you. A team that wants an
63
+ agent account makes one on the code host, gives it write access, and stores
64
+ its token instead. Nothing else changes.
65
+
66
+ **Signed commits.** With a signing key stored as a secret, the build signs
67
+ each commit, and the code host shows it as verified when the key belongs to
68
+ the account the build acts as. Without one, its commits are unsigned.
69
+ `factory pr ready` refuses to mark a pull request ready while one of its
70
+ commits is not shown as verified, when your own git signs commits.
71
+
72
+ **Before the session starts,** the commands under
73
+ [`build-setup`](configuration.md#build-setup) in your settings run, after
74
+ your npm dependencies are installed.
75
+
76
+ ## The other jobs that run in the cloud
77
+
78
+ Three more jobs run on the cloud runner. Each checks first whether there is
79
+ anything to do and starts a session only when there is, so a run with
80
+ nothing to do costs about a minute of the runner and no use of the agent. A
81
+ run that works costs about what a build does.
82
+
83
+ | Job | Starts on | What the session does |
84
+ | ------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
85
+ | Answering your review | A review you submit on a pull request | Works your comments with `factory-address-review` |
86
+ | The conflict sweep | A push to your main branch, nightly, or by hand | Merges your main branch into each pull request that conflicts with it, with `factory-resolve-conflicts` |
87
+ | Dependency pull requests | Three times a day, or by hand | Moves each dependency update toward merged, with `factory-deps`, in a repository with a `.github/dependabot.yml` |
88
+
89
+ Each acts as the same account a build does. The review job answers your
90
+ reviews only: the factory's own replies start runs that find nothing of
91
+ yours in them and stop.
92
+
93
+ ## The poller
94
+
95
+ The poller is a small program of the factory's that never exits. Once a
96
+ minute it reads your board, and for each ticket in Ready with no open
97
+ blocker it:
98
+
99
+ 1. posts a comment on the ticket saying a build is starting, carrying a
100
+ marker;
101
+ 2. starts a build of that ticket in the cloud, from your main branch.
102
+
103
+ ```bash
104
+ factory poller
105
+ ```
106
+
107
+ The board shows the ticket as starting until the build claims it, and a
108
+ nightly pass releases a start nothing claimed in 24 hours. Only someone
109
+ who can write to the repository can start a build, so the build itself
110
+ does no further check.
111
+
112
+ ### What it reads from its environment
113
+
114
+ The poller runs with no copy of your repository, so it takes everything
115
+ from environment variables. All four are required; it exits at startup
116
+ naming any that is missing.
117
+
118
+ | Variable | What it is |
119
+ | ---------------------- | ------------------------------------------------------------------- |
120
+ | `FACTORY_REPOSITORY` | The repository, as `owner/name` |
121
+ | `FACTORY_BOARD_OWNER` | The account the board belongs to |
122
+ | `FACTORY_BOARD_NUMBER` | Which board |
123
+ | `FACTORY_BOARD_TOKEN` | An access token that can read the board, comment, and start a build |
124
+
125
+ One more is optional. `FACTORY_READY_COLUMN` is the name of the column that
126
+ approves a build, and defaults to Ready. The poller has no settings file,
127
+ so a repository whose `tickets.columns.ready` names another column sets it
128
+ where the poller runs. `factory board check` reminds you
129
+ when it applies.
130
+
131
+ The repository and the board's number repeat what your settings file says,
132
+ because the poller cannot read it. The factory takes the board's owner to
133
+ be the repository's owner everywhere else, a person or an organization, so
134
+ a board owned by another account is not supported yet.
135
+
136
+ ### Its limits
137
+
138
+ - **It starts at most 20 builds an hour.** A ticket past that waits, and
139
+ the poller's log says so. Each build may run as long as
140
+ [`session-minutes`](configuration.md#session-minutes) allows, so several
141
+ can run at once: each pays for its own minutes, and the cloud runner
142
+ limits how many run at the same time.
143
+ - **It backs off** when it cannot read the board, and logs each failure.
144
+ - **It logs a heartbeat each hour** with the number of Ready tickets it saw.
145
+ - **It never retries a build.** A build that failed to start leaves a
146
+ comment on the ticket, with the code host's reason, and the ticket in
147
+ "building", waiting on you.
148
+
149
+ ## Hosting the poller: `own-server`
150
+
151
+ The poller needs one always-on container with outbound network access and
152
+ half a gigabyte of memory. It serves no traffic.
153
+
154
+ The factory ships a Dockerfile for it, `poller.Dockerfile`. It installs
155
+ nothing but Node and the poller, and runs as an unprivileged user. To try it
156
+ on your machine, from the root of the factory's own repository:
157
+
158
+ ```bash
159
+ docker build -f poller.Dockerfile -t factory-poller .
160
+ docker run \
161
+ -e FACTORY_REPOSITORY=your-name/your-repo \
162
+ -e FACTORY_BOARD_OWNER=your-name \
163
+ -e FACTORY_BOARD_NUMBER=1 \
164
+ -e FACTORY_BOARD_TOKEN \
165
+ factory-poller
166
+ ```
167
+
168
+ _[Planned](developing.md#what-is-built)_: building it from an installed
169
+ package, whose files are under `node_modules/`. Until then, the Dockerfile
170
+ builds only from the factory's own repository, and a repository that uses
171
+ the factory writes its own: a Node image that runs `npm ci` and then
172
+ `npx --no-install factory poller`.
173
+
174
+ As an example, one setup runs it as a worker on DigitalOcean's App
175
+ Platform, in the same app as the site it builds, for about $5 a month. Its
176
+ app spec declares the worker, points it at the Dockerfile, redeploys it on
177
+ every merge, and sets the variables above, with the board's token as a
178
+ secret. Any host that runs a container works the same way.
179
+
180
+ That hosting is yours. Nothing about it goes in `.claude/factory.yaml`, and
181
+ the factory never deploys it.
182
+
183
+ ### When something fails
184
+
185
+ | What you see | What happened | What to do |
186
+ | --------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------- |
187
+ | `factory status` flags a Ready ticket "not started" | The poller is down or stuck | Read its log |
188
+ | A comment saying a build could not start, with a refusal from the code host | The token cannot start a build | Give it what [the setup](github/setup.md#secrets) names, then move the ticket to Ready again |
189
+ | The board stops updating | The board's token is missing or expired | Replace it. The poller uses the same token |
190
+ | A ticket in Ready is skipped | It is blocked by an open ticket | It starts within a minute of the blocker closing |
191
+
192
+ ## A scheduled poller: `github-action` _[Planned](developing.md#what-is-built)_
193
+
194
+ Until it is built, use the poller above, or `manual`.
195
+
196
+ For a repository with nowhere to run a container. Setup would add a
197
+ scheduled job on the cloud runner that runs the poller for one pass:
198
+
199
+ ```bash
200
+ factory poller --once
201
+ ```
202
+
203
+ It is a weaker poller, and you should know how before choosing it:
204
+
205
+ - **It is slower.** The shortest schedule is every few minutes, and
206
+ scheduled runs can start late.
207
+ - **It can cost money on a private repository.** A run every five minutes
208
+ is roughly 8,600 runs a month, each billed as at least a minute. That is
209
+ an estimate, not a measurement.
210
+ - **A scheduled job can be switched off** by the code host in a repository
211
+ that goes quiet.
212
+ - **The hourly cap needs a new home.** The poller keeps its count of recent
213
+ builds in memory, which a run that exits loses.
214
+
215
+ [The reference](github/reference.md#limits) has GitHub's own numbers.
216
+
217
+ ## No trigger: `manual`
218
+
219
+ Nothing watches the board. Moving a ticket to Ready records your approval
220
+ and starts nothing. Ask a session:
221
+
222
+ ```text
223
+ build ticket 12
224
+ ```
225
+
226
+ The session claims the ticket, which moves it to "building" on the board,
227
+ and builds it where you are.