@davidbyoung/software-factory 0.0.0-stage → 0.1.1
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/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +209 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- 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.
|