@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.
- 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 +205 -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,146 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Decide whether a pull request can merge without the owner.
|
|
3
|
+
//
|
|
4
|
+
// npx --no-install factory merge-policy PR_NUMBER # prints the labels to set
|
|
5
|
+
//
|
|
6
|
+
// "merge: automatic" only when no changed file is one of the factory's own,
|
|
7
|
+
// none matches auto-merge.deny in .claude/factory.yaml, every one matches
|
|
8
|
+
// auto-merge.allow, and every command under auto-merge.commands exits 0;
|
|
9
|
+
// "merge: manual" otherwise. The merge-policy workflow runs this from main's copy,
|
|
10
|
+
// with main's settings, so a pull request cannot change how it is judged.
|
|
11
|
+
import { spawnSync } from "node:child_process";
|
|
12
|
+
import { loadSettings } from "./config.mjs";
|
|
13
|
+
import { openCodeHost } from "./code-host/index.mjs";
|
|
14
|
+
import { matchesAny } from "./lib/glob.mjs";
|
|
15
|
+
/** The code host's changed files under those names. */
|
|
16
|
+
export const inGithubNames = (files) => files.map(({ path, previousPath, status }) => ({
|
|
17
|
+
filename: path,
|
|
18
|
+
previous_filename: previousPath,
|
|
19
|
+
status,
|
|
20
|
+
}));
|
|
21
|
+
/** The two merge labels. The merge-policy workflow applies one and removes the
|
|
22
|
+
* other; only "merge: automatic" turns auto-merge on. */
|
|
23
|
+
export const AUTOMATIC = "merge: automatic";
|
|
24
|
+
export const MANUAL = "merge: manual";
|
|
25
|
+
/** The factory's own files, held whatever the settings allow: a pull request
|
|
26
|
+
* must not be able to change how pull requests are judged. */
|
|
27
|
+
const FACTORY_FILES = /^(\.github|\.claude)\/|(^|\/)(CLAUDE|AGENTS)\.md$|^openspec\/config\.yaml$/;
|
|
28
|
+
function classifyPath(path, policy) {
|
|
29
|
+
if (FACTORY_FILES.test(path))
|
|
30
|
+
return "the factory's own files";
|
|
31
|
+
if (matchesAny(path, policy.deny))
|
|
32
|
+
return "held by auto-merge.deny";
|
|
33
|
+
return matchesAny(path, policy.allow) ? null : "not in auto-merge.allow";
|
|
34
|
+
}
|
|
35
|
+
/** The decision from the changed paths alone: a factory file, then deny,
|
|
36
|
+
* then anything outside allow, holds the pull request. A renamed file is
|
|
37
|
+
* checked under both names. */
|
|
38
|
+
export function classify(files, policy) {
|
|
39
|
+
if (files.length === 0) {
|
|
40
|
+
return { risk: MANUAL, reasons: ["no changed files"] };
|
|
41
|
+
}
|
|
42
|
+
const reasons = [];
|
|
43
|
+
for (const file of files) {
|
|
44
|
+
const paths = [file.filename, file.previous_filename].filter((p) => Boolean(p));
|
|
45
|
+
for (const path of new Set(paths)) {
|
|
46
|
+
const reason = classifyPath(path, policy);
|
|
47
|
+
if (reason)
|
|
48
|
+
reasons.push(`${path}: ${reason}`);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return reasons.length
|
|
52
|
+
? { risk: MANUAL, reasons: [...new Set(reasons)] }
|
|
53
|
+
: { risk: AUTOMATIC, reasons: [] };
|
|
54
|
+
}
|
|
55
|
+
/** Runs one command from the current directory, the root of the checkout
|
|
56
|
+
* the workflow made, with the pull request as JSON on its standard input. */
|
|
57
|
+
export function runCommand(command, input) {
|
|
58
|
+
const r = spawnSync("sh", ["-c", command], {
|
|
59
|
+
input: JSON.stringify(input),
|
|
60
|
+
encoding: "utf8",
|
|
61
|
+
});
|
|
62
|
+
// 126 and 127 are the shell's "cannot execute" and "not found".
|
|
63
|
+
const ran = !r.error && r.status !== 126 && r.status !== 127;
|
|
64
|
+
return { command, status: r.status, output: (r.stdout ?? "").trim(), ran };
|
|
65
|
+
}
|
|
66
|
+
/** Exit 0 allows the merge. Anything else holds it, with what the command
|
|
67
|
+
* printed as the reason, or the command's name when it printed nothing. */
|
|
68
|
+
export function commandReasons(results) {
|
|
69
|
+
return results.flatMap(({ command, status, output, ran }) => {
|
|
70
|
+
if (!ran)
|
|
71
|
+
return [`held by ${command}: it could not be run`];
|
|
72
|
+
if (status === 0)
|
|
73
|
+
return [];
|
|
74
|
+
const lines = output.split("\n").filter((l) => l.trim());
|
|
75
|
+
return lines.length ? lines : [`held by ${command}`];
|
|
76
|
+
});
|
|
77
|
+
}
|
|
78
|
+
/** The path decision, then each command's, as one. */
|
|
79
|
+
export function decide(paths, commandHolds) {
|
|
80
|
+
const reasons = [...paths.reasons, ...commandHolds];
|
|
81
|
+
return reasons.length
|
|
82
|
+
? { risk: MANUAL, reasons: [...new Set(reasons)] }
|
|
83
|
+
: { risk: AUTOMATIC, reasons: [] };
|
|
84
|
+
}
|
|
85
|
+
/** The description of the "Who merges" commit status: what happens, and why,
|
|
86
|
+
* on one line. GitHub cuts a status description at 140 characters. */
|
|
87
|
+
export function statusLine({ risk, reasons }) {
|
|
88
|
+
if (risk === AUTOMATIC) {
|
|
89
|
+
return "Merges itself once every gate passes: every file is on the allowlist";
|
|
90
|
+
}
|
|
91
|
+
const more = reasons.length > 1 ? `, and ${reasons.length - 1} more` : "";
|
|
92
|
+
// A path can hold a newline, which would write extra keys into the
|
|
93
|
+
// merge-policy workflow's outputs, such as automatic=true. Keep it to one line.
|
|
94
|
+
const first = reasons[0].replace(/[\u0000-\u001f\u007f]+/g, " ");
|
|
95
|
+
const line = `Waits for the owner: ${first}${more}`;
|
|
96
|
+
return line.length > 140 ? `${line.slice(0, 139)}…` : line;
|
|
97
|
+
}
|
|
98
|
+
/** What the merge-policy workflow needs: the label to set, the one to remove,
|
|
99
|
+
* whether auto-merge goes on, and the status line. */
|
|
100
|
+
export function workflowOutput(result) {
|
|
101
|
+
const automatic = result.risk === AUTOMATIC;
|
|
102
|
+
return {
|
|
103
|
+
...result,
|
|
104
|
+
other: automatic ? MANUAL : AUTOMATIC,
|
|
105
|
+
automatic,
|
|
106
|
+
status: statusLine(result),
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
async function main(argv) {
|
|
110
|
+
const pr = argv[0];
|
|
111
|
+
if (!pr) {
|
|
112
|
+
console.error("Usage: factory merge-policy PR");
|
|
113
|
+
process.exit(2);
|
|
114
|
+
}
|
|
115
|
+
const settings = await loadSettings();
|
|
116
|
+
const repo = process.env.GITHUB_REPOSITORY || settings.repository;
|
|
117
|
+
const { autoMerge } = settings;
|
|
118
|
+
const pulls = openCodeHost(repo, settings.codeHost.type);
|
|
119
|
+
const pull = await pulls.get(Number(pr));
|
|
120
|
+
const mergeBase = await pulls.mergeBase(pull.base.sha, pull.head.sha);
|
|
121
|
+
const files = inGithubNames(await pulls.files(Number(pr)));
|
|
122
|
+
const paths = classify(files, autoMerge);
|
|
123
|
+
// A pull request with no files waits for the owner whatever a command says.
|
|
124
|
+
const holds = files.length
|
|
125
|
+
? commandReasons(autoMerge.commands.map((command) => runCommand(command, {
|
|
126
|
+
repository: repo,
|
|
127
|
+
pull: Number(pr),
|
|
128
|
+
base: mergeBase,
|
|
129
|
+
head: pull.head.sha,
|
|
130
|
+
files,
|
|
131
|
+
})))
|
|
132
|
+
: [];
|
|
133
|
+
// The pull request as it is now, not as the event described it: an event
|
|
134
|
+
// sent just after a push can carry the previous commit and draft state.
|
|
135
|
+
console.log(JSON.stringify({
|
|
136
|
+
...workflowOutput(decide(paths, holds)),
|
|
137
|
+
sha: pull.head.sha,
|
|
138
|
+
draft: pull.isDraft,
|
|
139
|
+
}));
|
|
140
|
+
}
|
|
141
|
+
// Only run as a CLI. Importing this module for tests must not call GitHub.
|
|
142
|
+
/** `factory merge-policy N`. */
|
|
143
|
+
export async function run(argv) {
|
|
144
|
+
await main(argv);
|
|
145
|
+
return 0;
|
|
146
|
+
}
|
package/dist/parts.d.mts
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { Settings } from "./config.mts";
|
|
2
|
+
import type { TokenNeed } from "./code-host/types.mts";
|
|
3
|
+
export declare const PARTS: readonly ["review", "board", "cloud", "from-board", "auto-merge", "signing"];
|
|
4
|
+
export type Part = (typeof PARTS)[number];
|
|
5
|
+
/** Each part's name, and what it gives you, in plain words. */
|
|
6
|
+
export declare const PART_TEXT: Record<Part, {
|
|
7
|
+
name: string;
|
|
8
|
+
gives: string;
|
|
9
|
+
}>;
|
|
10
|
+
/** The workflow that runs the automated review, which `factory sync`
|
|
11
|
+
* writes while the settings have `ci-review`. */
|
|
12
|
+
export declare const REVIEW_WORKFLOW = ".github/workflows/factory-claude-review.yml";
|
|
13
|
+
export declare const AGENT_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
|
|
14
|
+
export declare const AGENT_KEY = "ANTHROPIC_API_KEY";
|
|
15
|
+
export declare const BOARD_TOKEN = "FACTORY_BOARD_TOKEN";
|
|
16
|
+
export declare const BUILD_TOKEN = "FACTORY_BUILD_TOKEN";
|
|
17
|
+
export declare const AUTOMERGE_TOKEN = "FACTORY_AUTOMERGE_TOKEN";
|
|
18
|
+
export declare const SIGNING_KEY = "FACTORY_SIGNING_KEY";
|
|
19
|
+
/** The parts on: those with a setting, from the settings; and cloud
|
|
20
|
+
* builds and signing, from the secrets set. */
|
|
21
|
+
export declare function partsOn(s: Settings | null, secrets: string[]): Set<Part>;
|
|
22
|
+
/** The parts chosen, with what one needs turned on alongside it, and a part
|
|
23
|
+
* turned off when one it needs was just turned off. `before` is what was on,
|
|
24
|
+
* so turning a needed part off wins over keeping the part that needs it. */
|
|
25
|
+
export declare function resolveParts(before: Set<Part>, chosen: Set<Part>): {
|
|
26
|
+
parts: Set<Part>;
|
|
27
|
+
notes: string[];
|
|
28
|
+
};
|
|
29
|
+
/** The secrets the parts read: each entry is met by any one of its names. */
|
|
30
|
+
export declare function neededSecrets(parts: Set<Part>): {
|
|
31
|
+
part: Part;
|
|
32
|
+
anyOf: string[];
|
|
33
|
+
}[];
|
|
34
|
+
/** The names the one access token is stored under: the board's with a
|
|
35
|
+
* board, which builds also read, the build token's without one, and the
|
|
36
|
+
* auto-merge token's. */
|
|
37
|
+
export declare function tokenNames(parts: Set<Part>): string[];
|
|
38
|
+
/** What the access token must be able to do for the parts. */
|
|
39
|
+
export declare function tokenNeeds(parts: Set<Part>): TokenNeed[];
|
package/dist/parts.mjs
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
export const PARTS = [
|
|
2
|
+
"review",
|
|
3
|
+
"board",
|
|
4
|
+
"cloud",
|
|
5
|
+
"from-board",
|
|
6
|
+
"auto-merge",
|
|
7
|
+
"signing",
|
|
8
|
+
];
|
|
9
|
+
/** Each part's name, and what it gives you, in plain words. */
|
|
10
|
+
export const PART_TEXT = {
|
|
11
|
+
review: {
|
|
12
|
+
name: "An automated review of every pull request",
|
|
13
|
+
gives: "your coding agent reads each pull request before you do",
|
|
14
|
+
},
|
|
15
|
+
board: {
|
|
16
|
+
name: "A board",
|
|
17
|
+
gives: "every ticket's state, which session has it, and what it cost",
|
|
18
|
+
},
|
|
19
|
+
cloud: {
|
|
20
|
+
name: "Builds in the cloud",
|
|
21
|
+
gives: "a ticket builds with no session open on your machine",
|
|
22
|
+
},
|
|
23
|
+
"from-board": {
|
|
24
|
+
name: "Builds that start when you move a card to Ready",
|
|
25
|
+
gives: "needs a small server you host",
|
|
26
|
+
},
|
|
27
|
+
"auto-merge": {
|
|
28
|
+
name: "Pull requests that merge themselves",
|
|
29
|
+
gives: "changes to files you list as safe do not wait for you",
|
|
30
|
+
},
|
|
31
|
+
signing: {
|
|
32
|
+
name: "Signed commits from cloud builds",
|
|
33
|
+
gives: "a cloud build's commits show as verified",
|
|
34
|
+
},
|
|
35
|
+
};
|
|
36
|
+
/** The workflow that runs the automated review, which `factory sync`
|
|
37
|
+
* writes while the settings have `ci-review`. */
|
|
38
|
+
export const REVIEW_WORKFLOW = ".github/workflows/factory-claude-review.yml";
|
|
39
|
+
export const AGENT_TOKEN = "CLAUDE_CODE_OAUTH_TOKEN";
|
|
40
|
+
export const AGENT_KEY = "ANTHROPIC_API_KEY";
|
|
41
|
+
export const BOARD_TOKEN = "FACTORY_BOARD_TOKEN";
|
|
42
|
+
export const BUILD_TOKEN = "FACTORY_BUILD_TOKEN";
|
|
43
|
+
export const AUTOMERGE_TOKEN = "FACTORY_AUTOMERGE_TOKEN";
|
|
44
|
+
export const SIGNING_KEY = "FACTORY_SIGNING_KEY";
|
|
45
|
+
const AGENT = [AGENT_TOKEN, AGENT_KEY];
|
|
46
|
+
const ACCESS = [BUILD_TOKEN, BOARD_TOKEN];
|
|
47
|
+
/** The parts on: those with a setting, from the settings; and cloud
|
|
48
|
+
* builds and signing, from the secrets set. */
|
|
49
|
+
export function partsOn(s, secrets) {
|
|
50
|
+
const has = (names) => names.some((n) => secrets.includes(n));
|
|
51
|
+
const on = new Set();
|
|
52
|
+
if (s?.ciReview)
|
|
53
|
+
on.add("review");
|
|
54
|
+
if (s?.tickets.board != null)
|
|
55
|
+
on.add("board");
|
|
56
|
+
if (has(AGENT) && has(ACCESS))
|
|
57
|
+
on.add("cloud");
|
|
58
|
+
if (s && s.builds.trigger !== "manual")
|
|
59
|
+
on.add("from-board");
|
|
60
|
+
if (s && s.autoMerge.allow.length > 0)
|
|
61
|
+
on.add("auto-merge");
|
|
62
|
+
if (has([SIGNING_KEY]))
|
|
63
|
+
on.add("signing");
|
|
64
|
+
return on;
|
|
65
|
+
}
|
|
66
|
+
/** A part that needs another, each named as a note about it reads. */
|
|
67
|
+
const NEEDS = [
|
|
68
|
+
{
|
|
69
|
+
part: "from-board",
|
|
70
|
+
needs: "board",
|
|
71
|
+
parts: "Builds that start from the board",
|
|
72
|
+
need: "a board",
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
part: "from-board",
|
|
76
|
+
needs: "cloud",
|
|
77
|
+
parts: "Builds that start from the board",
|
|
78
|
+
need: "builds in the cloud",
|
|
79
|
+
},
|
|
80
|
+
];
|
|
81
|
+
/** The parts chosen, with what one needs turned on alongside it, and a part
|
|
82
|
+
* turned off when one it needs was just turned off. `before` is what was on,
|
|
83
|
+
* so turning a needed part off wins over keeping the part that needs it. */
|
|
84
|
+
export function resolveParts(before, chosen) {
|
|
85
|
+
const parts = new Set(chosen);
|
|
86
|
+
const notes = [];
|
|
87
|
+
for (const n of NEEDS) {
|
|
88
|
+
if (!parts.has(n.part) || parts.has(n.needs))
|
|
89
|
+
continue;
|
|
90
|
+
if (before.has(n.needs)) {
|
|
91
|
+
parts.delete(n.part);
|
|
92
|
+
notes.push(`${n.parts} need ${n.need}, so they are off too.`);
|
|
93
|
+
}
|
|
94
|
+
else {
|
|
95
|
+
parts.add(n.needs);
|
|
96
|
+
notes.push(`${n.parts} need ${n.need}, so that is on too.`);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
return { parts, notes };
|
|
100
|
+
}
|
|
101
|
+
/** The secrets the parts read: each entry is met by any one of its names. */
|
|
102
|
+
export function neededSecrets(parts) {
|
|
103
|
+
const out = [];
|
|
104
|
+
for (const part of PARTS) {
|
|
105
|
+
if (!parts.has(part))
|
|
106
|
+
continue;
|
|
107
|
+
if (part === "review")
|
|
108
|
+
out.push({ part, anyOf: AGENT });
|
|
109
|
+
if (part === "cloud")
|
|
110
|
+
out.push({ part, anyOf: AGENT }, { part, anyOf: ACCESS });
|
|
111
|
+
if (part === "board" || part === "from-board")
|
|
112
|
+
out.push({ part, anyOf: [BOARD_TOKEN] });
|
|
113
|
+
if (part === "auto-merge")
|
|
114
|
+
out.push({ part, anyOf: [AUTOMERGE_TOKEN] });
|
|
115
|
+
if (part === "signing")
|
|
116
|
+
out.push({ part, anyOf: [SIGNING_KEY] });
|
|
117
|
+
}
|
|
118
|
+
return out;
|
|
119
|
+
}
|
|
120
|
+
/** The names the one access token is stored under: the board's with a
|
|
121
|
+
* board, which builds also read, the build token's without one, and the
|
|
122
|
+
* auto-merge token's. */
|
|
123
|
+
export function tokenNames(parts) {
|
|
124
|
+
const names = [];
|
|
125
|
+
if (parts.has("board"))
|
|
126
|
+
names.push(BOARD_TOKEN);
|
|
127
|
+
else if (parts.has("cloud"))
|
|
128
|
+
names.push(BUILD_TOKEN);
|
|
129
|
+
if (parts.has("auto-merge"))
|
|
130
|
+
names.push(AUTOMERGE_TOKEN);
|
|
131
|
+
return names;
|
|
132
|
+
}
|
|
133
|
+
/** What the access token must be able to do for the parts. */
|
|
134
|
+
export function tokenNeeds(parts) {
|
|
135
|
+
return parts.has("board")
|
|
136
|
+
? ["push", "workflows", "board"]
|
|
137
|
+
: ["push", "workflows"];
|
|
138
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { type Columns, type Board, type RepoSnapshot } from "./lib/work-status.mts";
|
|
3
|
+
import type { CodeHost } from "./code-host/types.mts";
|
|
4
|
+
import type { Runner } from "./runner/types.mts";
|
|
5
|
+
import { type Tickets } from "./tickets/types.mts";
|
|
6
|
+
export declare const FIRE_LIMIT = 20;
|
|
7
|
+
/** The open issues the shared derivation puts in Ready, oldest number first. */
|
|
8
|
+
export declare function selectToStart(snapshot: RepoSnapshot, board: Board, columns?: Columns): number[];
|
|
9
|
+
export declare function startMarker(): string;
|
|
10
|
+
/** The columns the poller reads a board by. It runs with no settings file,
|
|
11
|
+
* so it is told the one name it needs, the column that approves a build:
|
|
12
|
+
* FACTORY_READY_COLUMN, which defaults to Ready. */
|
|
13
|
+
export declare function columnsFrom(env: Record<string, string | undefined>): Columns;
|
|
14
|
+
/** What a refused dispatch's comment says GitHub answered: the status, and
|
|
15
|
+
* the answer's message or else the status text. */
|
|
16
|
+
export declare function dispatchFailure(error: unknown): {
|
|
17
|
+
status: string;
|
|
18
|
+
reason: string;
|
|
19
|
+
};
|
|
20
|
+
/** Whether another fire fits in the rolling hour, given when the recent ones
|
|
21
|
+
* went out. */
|
|
22
|
+
export declare function capAllows(fired: number[], now: number): boolean;
|
|
23
|
+
/** A minute between reads, and ten once ten in a row have failed. */
|
|
24
|
+
export declare function nextDelay(failuresInARow: number): number;
|
|
25
|
+
export type Config = {
|
|
26
|
+
owner: string;
|
|
27
|
+
number: number;
|
|
28
|
+
githubToken: string;
|
|
29
|
+
};
|
|
30
|
+
export declare function readConfig(env: Record<string, string | undefined>): Config | {
|
|
31
|
+
missing: string[];
|
|
32
|
+
};
|
|
33
|
+
export type State = {
|
|
34
|
+
fired: number[];
|
|
35
|
+
failuresInARow: number;
|
|
36
|
+
lastHeartbeat: number;
|
|
37
|
+
};
|
|
38
|
+
export type Deps = {
|
|
39
|
+
/** The repository whose issues it starts, as owner/name. */
|
|
40
|
+
repository: string;
|
|
41
|
+
fetch: typeof fetch;
|
|
42
|
+
env: Record<string, string | undefined>;
|
|
43
|
+
now: () => number;
|
|
44
|
+
log: (line: string) => void;
|
|
45
|
+
marker: () => string;
|
|
46
|
+
/** The repository's default branch, read from GitHub once the poller is
|
|
47
|
+
* running; a dispatch runs on it. */
|
|
48
|
+
defaultBranch?: string;
|
|
49
|
+
};
|
|
50
|
+
/** The ticket system, the code host, and the runner, over the `fetch`
|
|
51
|
+
* transport. */
|
|
52
|
+
export declare function sources(d: Deps, c: Config): {
|
|
53
|
+
tickets: Tickets;
|
|
54
|
+
codeHost: CodeHost;
|
|
55
|
+
runner: Runner;
|
|
56
|
+
};
|
|
57
|
+
/** One minute's work. It never throws: every failure is logged, and a failed
|
|
58
|
+
* read counts toward the slower retry. */
|
|
59
|
+
export declare function tick(d: Deps, state: State): Promise<void>;
|
|
60
|
+
/** `factory poller`. */
|
|
61
|
+
export declare function run(): Promise<number>;
|
package/dist/poller.mjs
ADDED
|
@@ -0,0 +1,247 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Start a build in GitHub Actions for each card the owner moves to Ready. A board owned
|
|
3
|
+
// by a user account sends no event, so this reads it once a minute. It runs
|
|
4
|
+
// as a worker on a server the repository's owner hosts.
|
|
5
|
+
//
|
|
6
|
+
// Environment: FACTORY_REPOSITORY (owner/name), FACTORY_BOARD_OWNER,
|
|
7
|
+
// FACTORY_BOARD_NUMBER, and FACTORY_BOARD_TOKEN (a classic token with the
|
|
8
|
+
// repo and project scopes, or a fine-grained one that can also write
|
|
9
|
+
// Actions: it starts the workflow). It has no checkout, so it reads
|
|
10
|
+
// the repository from its environment rather than the factory's settings.
|
|
11
|
+
//
|
|
12
|
+
// Once started it never exits on its own: a host that deploys every
|
|
13
|
+
// component together can fail the whole deploy when a worker exits during
|
|
14
|
+
// a rollout. The one exit is at start, with no repository to read.
|
|
15
|
+
//
|
|
16
|
+
// It names its implementations itself, having no settings to name them:
|
|
17
|
+
// the GitHub ticket adapter, GitHub as the code host, and GitHub Actions as
|
|
18
|
+
// the runner, each over the `fetch` transport, since it runs with no `gh`.
|
|
19
|
+
// Node built-ins and the modules below only; its image copies nothing else.
|
|
20
|
+
import { randomBytes } from "node:crypto";
|
|
21
|
+
import { setTimeout as sleep } from "node:timers/promises";
|
|
22
|
+
import { pathToFileURL } from "node:url";
|
|
23
|
+
import { DEFAULT_COLUMNS, cardOf, commentBody, derive, toSnapshot, } from "./lib/work-status.mjs";
|
|
24
|
+
import { githubCodeHost } from "./code-host/github.mjs";
|
|
25
|
+
import { BUILD_WORKFLOW, githubActionsRunner, } from "./runner/github-actions.mjs";
|
|
26
|
+
import { githubTickets } from "./tickets/github.mjs";
|
|
27
|
+
import { HttpError, fetchTransport, statusOf } from "./tickets/transport.mjs";
|
|
28
|
+
import { boardOf } from "./tickets/types.mjs";
|
|
29
|
+
const MINUTE = 60_000;
|
|
30
|
+
const HOUR = 60 * MINUTE;
|
|
31
|
+
export const FIRE_LIMIT = 20;
|
|
32
|
+
const FIRE_TIMEOUT_MS = 30_000;
|
|
33
|
+
/** The open issues the shared derivation puts in Ready, oldest number first. */
|
|
34
|
+
export function selectToStart(snapshot, board, columns = DEFAULT_COLUMNS) {
|
|
35
|
+
return snapshot.issues
|
|
36
|
+
.filter((issue) => issue.state === "open" &&
|
|
37
|
+
derive(issue, cardOf(board, issue.number, columns), snapshot.pulls, columns).status === "Ready")
|
|
38
|
+
.map((issue) => issue.number)
|
|
39
|
+
.sort((a, b) => a - b);
|
|
40
|
+
}
|
|
41
|
+
export function startMarker() {
|
|
42
|
+
return `st_${randomBytes(6).toString("hex")}`;
|
|
43
|
+
}
|
|
44
|
+
/** The columns the poller reads a board by. It runs with no settings file,
|
|
45
|
+
* so it is told the one name it needs, the column that approves a build:
|
|
46
|
+
* FACTORY_READY_COLUMN, which defaults to Ready. */
|
|
47
|
+
export function columnsFrom(env) {
|
|
48
|
+
return {
|
|
49
|
+
...DEFAULT_COLUMNS,
|
|
50
|
+
Ready: env.FACTORY_READY_COLUMN?.trim() || "Ready",
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
/** What a refused dispatch's comment says GitHub answered: the status, and
|
|
54
|
+
* the answer's message or else the status text. */
|
|
55
|
+
export function dispatchFailure(error) {
|
|
56
|
+
if (error instanceof HttpError)
|
|
57
|
+
return {
|
|
58
|
+
status: String(error.status),
|
|
59
|
+
reason: error.reason || "no reason given",
|
|
60
|
+
};
|
|
61
|
+
const status = statusOf(error);
|
|
62
|
+
return {
|
|
63
|
+
status: status === null ? "nothing" : String(status),
|
|
64
|
+
reason: error instanceof Error ? error.message : String(error),
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
/** Whether another fire fits in the rolling hour, given when the recent ones
|
|
68
|
+
* went out. */
|
|
69
|
+
export function capAllows(fired, now) {
|
|
70
|
+
return fired.filter((at) => now - at < HOUR).length < FIRE_LIMIT;
|
|
71
|
+
}
|
|
72
|
+
/** A minute between reads, and ten once ten in a row have failed. */
|
|
73
|
+
export function nextDelay(failuresInARow) {
|
|
74
|
+
return failuresInARow >= 10 ? 10 * MINUTE : MINUTE;
|
|
75
|
+
}
|
|
76
|
+
export function readConfig(env) {
|
|
77
|
+
const names = [
|
|
78
|
+
"FACTORY_BOARD_OWNER",
|
|
79
|
+
"FACTORY_BOARD_NUMBER",
|
|
80
|
+
"FACTORY_BOARD_TOKEN",
|
|
81
|
+
];
|
|
82
|
+
const missing = names.filter((name) => !env[name]);
|
|
83
|
+
if (missing.length)
|
|
84
|
+
return { missing };
|
|
85
|
+
return {
|
|
86
|
+
owner: env.FACTORY_BOARD_OWNER,
|
|
87
|
+
number: Number(env.FACTORY_BOARD_NUMBER),
|
|
88
|
+
githubToken: env.FACTORY_BOARD_TOKEN,
|
|
89
|
+
};
|
|
90
|
+
}
|
|
91
|
+
/** The ticket system, the code host, and the runner, over the `fetch`
|
|
92
|
+
* transport. */
|
|
93
|
+
export function sources(d, c) {
|
|
94
|
+
const transport = fetchTransport({
|
|
95
|
+
token: c.githubToken,
|
|
96
|
+
fetch: d.fetch,
|
|
97
|
+
timeoutMs: FIRE_TIMEOUT_MS,
|
|
98
|
+
userAgent: "ready-poller",
|
|
99
|
+
});
|
|
100
|
+
return {
|
|
101
|
+
tickets: githubTickets({
|
|
102
|
+
transport,
|
|
103
|
+
repository: d.repository,
|
|
104
|
+
board: c.number,
|
|
105
|
+
boardOwner: c.owner,
|
|
106
|
+
}),
|
|
107
|
+
codeHost: githubCodeHost({ transport, repository: d.repository }),
|
|
108
|
+
runner: githubActionsRunner({ transport, repository: d.repository }),
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
async function readAll(tickets, codeHost, d) {
|
|
112
|
+
const [read, open] = await Promise.all([
|
|
113
|
+
tickets.readAll({ board: true }),
|
|
114
|
+
codeHost.open(),
|
|
115
|
+
]);
|
|
116
|
+
return {
|
|
117
|
+
snapshot: toSnapshot(read, open, new Date(d.now())),
|
|
118
|
+
board: boardOf(read),
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
/** Start a build of one ticket on the default branch. */
|
|
122
|
+
async function dispatch(runner, branch, issue) {
|
|
123
|
+
try {
|
|
124
|
+
await runner.startBuild(issue, branch);
|
|
125
|
+
return { ok: true };
|
|
126
|
+
}
|
|
127
|
+
catch (error) {
|
|
128
|
+
return { ok: false, ...dispatchFailure(error) };
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
/** One minute's work. It never throws: every failure is logged, and a failed
|
|
132
|
+
* read counts toward the slower retry. */
|
|
133
|
+
export async function tick(d, state) {
|
|
134
|
+
const config = readConfig(d.env);
|
|
135
|
+
if ("missing" in config) {
|
|
136
|
+
d.log(`not polling: ${config.missing.join(", ")} not set`);
|
|
137
|
+
state.failuresInARow += 1;
|
|
138
|
+
return;
|
|
139
|
+
}
|
|
140
|
+
const { tickets, codeHost, runner } = sources(d, config);
|
|
141
|
+
let read;
|
|
142
|
+
try {
|
|
143
|
+
read = await readAll(tickets, codeHost, d);
|
|
144
|
+
state.failuresInARow = 0;
|
|
145
|
+
}
|
|
146
|
+
catch (error) {
|
|
147
|
+
state.failuresInARow += 1;
|
|
148
|
+
d.log(`read failed (${state.failuresInARow} in a row): ${String(error)}`);
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
if (!d.defaultBranch) {
|
|
152
|
+
try {
|
|
153
|
+
d.defaultBranch = await codeHost.defaultBranch();
|
|
154
|
+
}
|
|
155
|
+
catch (error) {
|
|
156
|
+
state.failuresInARow += 1;
|
|
157
|
+
d.log(`default branch not read: ${String(error)}`);
|
|
158
|
+
return;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
const columns = columnsFrom(d.env);
|
|
162
|
+
const ready = selectToStart(read.snapshot, read.board, columns);
|
|
163
|
+
if (d.now() - state.lastHeartbeat >= HOUR) {
|
|
164
|
+
d.log(`heartbeat: ${ready.length} Ready card${ready.length === 1 ? "" : "s"}`);
|
|
165
|
+
state.lastHeartbeat = d.now();
|
|
166
|
+
}
|
|
167
|
+
for (const issue of ready) {
|
|
168
|
+
try {
|
|
169
|
+
const blockers = await tickets.blockers.list(issue);
|
|
170
|
+
const open = blockers.filter((b) => b.state === "open");
|
|
171
|
+
if (open.length) {
|
|
172
|
+
d.log(`#${issue} waits on ${open.map((b) => `#${b.number}`).join(", ")}`);
|
|
173
|
+
continue;
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
catch (error) {
|
|
177
|
+
d.log(`#${issue} skipped: its blockers could not be read (${String(error)})`);
|
|
178
|
+
continue;
|
|
179
|
+
}
|
|
180
|
+
if (!capAllows(state.fired, d.now())) {
|
|
181
|
+
d.log(`#${issue} waits: ${FIRE_LIMIT} builds started in the last hour`);
|
|
182
|
+
continue;
|
|
183
|
+
}
|
|
184
|
+
const marker = d.marker();
|
|
185
|
+
try {
|
|
186
|
+
await tickets.comment(issue, commentBody({ kind: "started", marker }, columns));
|
|
187
|
+
}
|
|
188
|
+
catch (error) {
|
|
189
|
+
d.log(`#${issue} not started: the start comment failed (${String(error)})`);
|
|
190
|
+
continue;
|
|
191
|
+
}
|
|
192
|
+
state.fired.push(d.now());
|
|
193
|
+
state.fired = state.fired.filter((at) => d.now() - at < HOUR);
|
|
194
|
+
const outcome = await dispatch(runner, d.defaultBranch, issue);
|
|
195
|
+
if (outcome.ok) {
|
|
196
|
+
d.log(`#${issue} started ${marker}: dispatched ${BUILD_WORKFLOW}`);
|
|
197
|
+
continue;
|
|
198
|
+
}
|
|
199
|
+
d.log(`#${issue} dispatch failed: ${outcome.status} (${outcome.reason})`);
|
|
200
|
+
try {
|
|
201
|
+
await tickets.comment(issue, commentBody({
|
|
202
|
+
kind: "dispatch-failed",
|
|
203
|
+
issue,
|
|
204
|
+
status: outcome.status,
|
|
205
|
+
reason: outcome.reason,
|
|
206
|
+
}, columns));
|
|
207
|
+
}
|
|
208
|
+
catch (error) {
|
|
209
|
+
d.log(`#${issue} dispatch-failure comment failed (${String(error)})`);
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
async function main() {
|
|
214
|
+
const repository = process.env.FACTORY_REPOSITORY;
|
|
215
|
+
if (!repository) {
|
|
216
|
+
console.error("ready-poller not started: FACTORY_REPOSITORY is not set. Set it to the repository, as owner/name.");
|
|
217
|
+
return 1;
|
|
218
|
+
}
|
|
219
|
+
const state = { fired: [], failuresInARow: 0, lastHeartbeat: 0 };
|
|
220
|
+
const d = {
|
|
221
|
+
repository,
|
|
222
|
+
fetch,
|
|
223
|
+
env: process.env,
|
|
224
|
+
now: () => Date.now(),
|
|
225
|
+
log: (line) => console.log(`${new Date().toISOString()} ${line}`),
|
|
226
|
+
marker: startMarker,
|
|
227
|
+
};
|
|
228
|
+
process.on("unhandledRejection", (error) => d.log(`unhandled: ${String(error)}`));
|
|
229
|
+
d.log("ready-poller started");
|
|
230
|
+
for (;;) {
|
|
231
|
+
try {
|
|
232
|
+
await tick(d, state);
|
|
233
|
+
}
|
|
234
|
+
catch (error) {
|
|
235
|
+
d.log(`tick failed: ${String(error)}`);
|
|
236
|
+
}
|
|
237
|
+
await sleep(nextDelay(state.failuresInARow));
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
/** `factory poller`. */
|
|
241
|
+
export async function run() {
|
|
242
|
+
process.exit(await main());
|
|
243
|
+
}
|
|
244
|
+
if (process.argv[1] &&
|
|
245
|
+
import.meta.url === pathToFileURL(process.argv[1]).href) {
|
|
246
|
+
await run();
|
|
247
|
+
}
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { type CheckRun, type CommitStatus } from "./code-host/index.mts";
|
|
3
|
+
export type Check = {
|
|
4
|
+
/** A re-run has a new id, so its result is news on the same commit. */
|
|
5
|
+
id: number;
|
|
6
|
+
name: string;
|
|
7
|
+
state: "pending" | "passed" | "failed";
|
|
8
|
+
url?: string;
|
|
9
|
+
};
|
|
10
|
+
export type Comment = {
|
|
11
|
+
id: number;
|
|
12
|
+
author: string;
|
|
13
|
+
where: string;
|
|
14
|
+
body: string;
|
|
15
|
+
};
|
|
16
|
+
export type Snapshot = {
|
|
17
|
+
state: string;
|
|
18
|
+
merged: boolean;
|
|
19
|
+
headSha: string;
|
|
20
|
+
mergeableState: string;
|
|
21
|
+
checks: Check[];
|
|
22
|
+
/** Conversation comments on the pull request, for the review summaries. */
|
|
23
|
+
conversation: Comment[];
|
|
24
|
+
comments: Comment[];
|
|
25
|
+
reviews: Comment[];
|
|
26
|
+
};
|
|
27
|
+
export type WatchEvent = {
|
|
28
|
+
key: string;
|
|
29
|
+
line: string;
|
|
30
|
+
};
|
|
31
|
+
export declare function toChecks(runs: CheckRun[], statuses: CommitStatus[]): Check[];
|
|
32
|
+
/** What needs the session now and has not been reported. A closed pull
|
|
33
|
+
* request ends the watch, so nothing else about it is news. */
|
|
34
|
+
export declare function newEvents(snapshot: Snapshot, seen: Set<string>): WatchEvent[];
|
|
35
|
+
export declare function withWatchMark(body: string, now: Date): string;
|
|
36
|
+
export declare function withoutWatchMark(body: string): string;
|
|
37
|
+
/** A mark goes stale after an hour, so a session that has gone stops holding
|
|
38
|
+
* back the workflow soon after. Renewing it covers the time a session spends
|
|
39
|
+
* working what the watcher reported, when nothing renews it. */
|
|
40
|
+
export declare function watchMarkNeedsRenewing(body: string, now: Date): boolean;
|
|
41
|
+
/** A login that has expired or a pull request that does not exist will not
|
|
42
|
+
* recover by waiting, so the session should hear about it now. */
|
|
43
|
+
export declare function isPermanentFailure(error: unknown): boolean;
|
|
44
|
+
/** `factory pr watch N [--release]`. */
|
|
45
|
+
export declare function run(argv: string[]): Promise<number>;
|