@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,46 @@
|
|
|
1
|
+
// Prints the tools the CI review may use, as the one comma-separated value
|
|
2
|
+
// the review step passes to `--allowedTools`: the factory's own, then a
|
|
3
|
+
// `Bash(COMMAND:*)` for each of the settings' `ci-review.commands`.
|
|
4
|
+
//
|
|
5
|
+
// FACTORY_SETTINGS=base-settings.yaml npx --no-install factory review tools
|
|
6
|
+
//
|
|
7
|
+
// The workflow reads the settings from the pull request's base commit, so
|
|
8
|
+
// a change to the settings alone cannot widen what its own review may run.
|
|
9
|
+
import { loadSettings, SettingsError } from "./config.mjs";
|
|
10
|
+
/** What every review may do: read, edit its scratch copy, read the history
|
|
11
|
+
* and the pull request, and comment on it. */
|
|
12
|
+
export const FACTORY_REVIEW_TOOLS = [
|
|
13
|
+
"Read",
|
|
14
|
+
"Grep",
|
|
15
|
+
"Glob",
|
|
16
|
+
"Edit",
|
|
17
|
+
"Write",
|
|
18
|
+
"Bash(git diff:*)",
|
|
19
|
+
"Bash(git log:*)",
|
|
20
|
+
"Bash(git show:*)",
|
|
21
|
+
"Bash(git merge-base:*)",
|
|
22
|
+
"Bash(git status:*)",
|
|
23
|
+
"Bash(git checkout:*)",
|
|
24
|
+
"Bash(git stash:*)",
|
|
25
|
+
"Bash(gh pr view:*)",
|
|
26
|
+
"Bash(gh pr diff:*)",
|
|
27
|
+
"Bash(gh pr comment:*)",
|
|
28
|
+
"Bash(gh api:*)",
|
|
29
|
+
"mcp__github_inline_comment__create_inline_comment",
|
|
30
|
+
];
|
|
31
|
+
export function allowedTools(commands) {
|
|
32
|
+
return [...FACTORY_REVIEW_TOOLS, ...commands.map((c) => `Bash(${c}:*)`)].join(",");
|
|
33
|
+
}
|
|
34
|
+
export async function run() {
|
|
35
|
+
try {
|
|
36
|
+
const s = await loadSettings();
|
|
37
|
+
console.log(allowedTools(s.ciReview?.commands ?? []));
|
|
38
|
+
return 0;
|
|
39
|
+
}
|
|
40
|
+
catch (e) {
|
|
41
|
+
if (!(e instanceof SettingsError))
|
|
42
|
+
throw e;
|
|
43
|
+
console.error(e.message);
|
|
44
|
+
return 1;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
export declare const CONTEXT = "Review verdict";
|
|
3
|
+
export declare const OVERRIDE = "verdict: override";
|
|
4
|
+
export type Verdict = "ready" | "changes" | null;
|
|
5
|
+
export type Input = {
|
|
6
|
+
event: "workflow_run" | "pull_request_target";
|
|
7
|
+
/** pull_request_target's action, such as synchronize or labeled. */
|
|
8
|
+
action?: string;
|
|
9
|
+
/** The label added or removed, on a labeled or unlabeled action. */
|
|
10
|
+
label?: string;
|
|
11
|
+
isDependabot: boolean;
|
|
12
|
+
isDraft: boolean;
|
|
13
|
+
/** The override label is on the pull request. A push removes it, so it
|
|
14
|
+
* always applies to the head. */
|
|
15
|
+
hasOverride: boolean;
|
|
16
|
+
/** The account behind a labeled event is the repository's owner. Agents
|
|
17
|
+
* act through that account too; the guard hook stops them on the
|
|
18
|
+
* owner's laptop. This stops everyone else. */
|
|
19
|
+
senderIsOwner?: boolean;
|
|
20
|
+
/** workflow_run's conclusion: success, failure, cancelled, skipped. */
|
|
21
|
+
runConclusion?: string;
|
|
22
|
+
/** The marker in the review's summary for this commit; null if none. */
|
|
23
|
+
verdict: Verdict;
|
|
24
|
+
};
|
|
25
|
+
export type Decision = {
|
|
26
|
+
state: "success" | "failure" | "pending";
|
|
27
|
+
description: string;
|
|
28
|
+
removeOverride?: boolean;
|
|
29
|
+
announceOverride?: boolean;
|
|
30
|
+
};
|
|
31
|
+
/** The status to post, or null to leave the commit's status as it is. */
|
|
32
|
+
export declare function decide(input: Input): Decision | null;
|
|
33
|
+
/** Whether a finished review should set the head's verdict. It should when
|
|
34
|
+
* it reviewed the head, or when it finished and its summary is for the head
|
|
35
|
+
* anyway, as when the event that started it named an older commit. Once the
|
|
36
|
+
* head has a verdict of its own, a run of an older commit that was
|
|
37
|
+
* cancelled, failed, or timed out leaves it alone: GitHub delivers a run's
|
|
38
|
+
* completion minutes after the fact, so one can arrive after the head's own
|
|
39
|
+
* review has concluded. Until the head has a verdict, a run that failed or
|
|
40
|
+
* timed out sets it, since it may have been reviewing the head and no other
|
|
41
|
+
* review is coming; a run a newer push cancelled leaves the head to its
|
|
42
|
+
* own. */
|
|
43
|
+
export declare function reviewIsAboutHead(reviewed: string, head: string, verdictForHead: Verdict, conclusion?: string): boolean;
|
|
44
|
+
/** The verdict marker in the last review summary for `sha`, if any. */
|
|
45
|
+
export declare function verdictIn(comments: {
|
|
46
|
+
author: string;
|
|
47
|
+
body: string;
|
|
48
|
+
}[], sha: string): Verdict;
|
|
49
|
+
/** `factory review verdict`. */
|
|
50
|
+
export declare function run(): Promise<number>;
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Post the "Review verdict" commit status from a GitHub Actions event.
|
|
3
|
+
//
|
|
4
|
+
// npx --no-install factory review verdict # reads GITHUB_EVENT_NAME and _PATH
|
|
5
|
+
//
|
|
6
|
+
// Runs from main's copy, on two events: the Claude review finishing
|
|
7
|
+
// (workflow_run), and the pull request itself (pull_request_target: opened,
|
|
8
|
+
// pushed to, marked ready, or labeled "verdict: override"). The verdict is posted
|
|
9
|
+
// on one commit, so a new push always starts without one.
|
|
10
|
+
import { readFileSync } from "node:fs";
|
|
11
|
+
import { openCodeHost } from "./code-host/index.mjs";
|
|
12
|
+
import { openRunner } from "./runner/index.mjs";
|
|
13
|
+
// The status's name, which the main ruleset requires by exactly this text.
|
|
14
|
+
export const CONTEXT = "Review verdict";
|
|
15
|
+
export const OVERRIDE = "verdict: override";
|
|
16
|
+
const WAITING = {
|
|
17
|
+
state: "pending",
|
|
18
|
+
description: "Waiting for the review of this commit",
|
|
19
|
+
};
|
|
20
|
+
const DRAFT = {
|
|
21
|
+
state: "pending",
|
|
22
|
+
description: "Draft: no review until it is marked ready",
|
|
23
|
+
};
|
|
24
|
+
const OVERRIDDEN = {
|
|
25
|
+
state: "success",
|
|
26
|
+
description: "Overridden by the owner",
|
|
27
|
+
};
|
|
28
|
+
function fromVerdict(verdict, ifMissing) {
|
|
29
|
+
if (verdict === "ready") {
|
|
30
|
+
return { state: "success", description: "The review found it ready" };
|
|
31
|
+
}
|
|
32
|
+
if (verdict === "changes") {
|
|
33
|
+
return { state: "failure", description: "The review asked for changes" };
|
|
34
|
+
}
|
|
35
|
+
return ifMissing;
|
|
36
|
+
}
|
|
37
|
+
/** The status to post, or null to leave the commit's status as it is. */
|
|
38
|
+
export function decide(input) {
|
|
39
|
+
if (input.isDependabot) {
|
|
40
|
+
return {
|
|
41
|
+
state: "success",
|
|
42
|
+
description: "Review skipped: Dependabot. CI and end-to-end are the gate",
|
|
43
|
+
};
|
|
44
|
+
}
|
|
45
|
+
if (input.event === "workflow_run") {
|
|
46
|
+
// An override already vouches for this commit; a late review must not
|
|
47
|
+
// overwrite it.
|
|
48
|
+
if (input.hasOverride)
|
|
49
|
+
return null;
|
|
50
|
+
if (input.runConclusion === "skipped") {
|
|
51
|
+
return input.isDraft
|
|
52
|
+
? DRAFT
|
|
53
|
+
: { state: "pending", description: "The review did not run" };
|
|
54
|
+
}
|
|
55
|
+
if (input.runConclusion !== "success") {
|
|
56
|
+
return { state: "failure", description: "The review did not finish" };
|
|
57
|
+
}
|
|
58
|
+
return fromVerdict(input.verdict, {
|
|
59
|
+
state: "failure",
|
|
60
|
+
description: "The review posted no verdict",
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
switch (input.action) {
|
|
64
|
+
case "labeled":
|
|
65
|
+
if (input.label !== OVERRIDE)
|
|
66
|
+
return null;
|
|
67
|
+
if (!input.senderIsOwner) {
|
|
68
|
+
return { ...fromVerdict(input.verdict, WAITING), removeOverride: true };
|
|
69
|
+
}
|
|
70
|
+
return { ...OVERRIDDEN, announceOverride: true };
|
|
71
|
+
case "unlabeled":
|
|
72
|
+
return input.label === OVERRIDE
|
|
73
|
+
? fromVerdict(input.verdict, WAITING)
|
|
74
|
+
: null;
|
|
75
|
+
case "synchronize":
|
|
76
|
+
// The owner overrode the commit they read. The new one is unread.
|
|
77
|
+
return { ...WAITING, removeOverride: input.hasOverride };
|
|
78
|
+
default:
|
|
79
|
+
if (input.hasOverride)
|
|
80
|
+
return OVERRIDDEN;
|
|
81
|
+
if (input.isDraft)
|
|
82
|
+
return DRAFT;
|
|
83
|
+
return fromVerdict(input.verdict, WAITING);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
/** Whether a finished review should set the head's verdict. It should when
|
|
87
|
+
* it reviewed the head, or when it finished and its summary is for the head
|
|
88
|
+
* anyway, as when the event that started it named an older commit. Once the
|
|
89
|
+
* head has a verdict of its own, a run of an older commit that was
|
|
90
|
+
* cancelled, failed, or timed out leaves it alone: GitHub delivers a run's
|
|
91
|
+
* completion minutes after the fact, so one can arrive after the head's own
|
|
92
|
+
* review has concluded. Until the head has a verdict, a run that failed or
|
|
93
|
+
* timed out sets it, since it may have been reviewing the head and no other
|
|
94
|
+
* review is coming; a run a newer push cancelled leaves the head to its
|
|
95
|
+
* own. */
|
|
96
|
+
export function reviewIsAboutHead(reviewed, head, verdictForHead, conclusion) {
|
|
97
|
+
if (reviewed === head)
|
|
98
|
+
return true;
|
|
99
|
+
if (verdictForHead !== null)
|
|
100
|
+
return conclusion === "success";
|
|
101
|
+
return conclusion === "failure" || conclusion === "timed_out";
|
|
102
|
+
}
|
|
103
|
+
/** The verdict marker in the last review summary for `sha`, if any. */
|
|
104
|
+
export function verdictIn(comments, sha) {
|
|
105
|
+
const summaries = comments.filter((c) => c.author === "github-actions[bot]" &&
|
|
106
|
+
c.body.includes(`<!-- claude-review sha=${sha} -->`));
|
|
107
|
+
const body = summaries.at(-1)?.body ?? "";
|
|
108
|
+
const match = /<!-- review-verdict: (ready|changes) -->/.exec(body);
|
|
109
|
+
return match ? match[1] : null;
|
|
110
|
+
}
|
|
111
|
+
async function main() {
|
|
112
|
+
const repo = process.env.GITHUB_REPOSITORY;
|
|
113
|
+
const eventName = process.env.GITHUB_EVENT_NAME;
|
|
114
|
+
const event = JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
|
|
115
|
+
const pulls = openCodeHost(repo);
|
|
116
|
+
// Read the pull request as it is now. The event's copy can be stale: a
|
|
117
|
+
// "marked ready" event sent just after a push carries the previous commit.
|
|
118
|
+
let number;
|
|
119
|
+
if (eventName === "workflow_run") {
|
|
120
|
+
const reviewed = event.workflow_run.head_sha;
|
|
121
|
+
const open = (await pulls.forCommit(reviewed)).find((p) => p.state === "open");
|
|
122
|
+
if (!open)
|
|
123
|
+
return console.log(`No open pull request has ${reviewed}.`);
|
|
124
|
+
number = open.number;
|
|
125
|
+
}
|
|
126
|
+
else {
|
|
127
|
+
number = event.pull_request.number;
|
|
128
|
+
}
|
|
129
|
+
const pr = await pulls.get(number);
|
|
130
|
+
const sha = pr.head.sha;
|
|
131
|
+
const { labels } = pr;
|
|
132
|
+
const comments = await pulls.comments(pr.number);
|
|
133
|
+
if (eventName === "workflow_run" &&
|
|
134
|
+
!reviewIsAboutHead(event.workflow_run.head_sha, sha, verdictIn(comments, sha), event.workflow_run.conclusion)) {
|
|
135
|
+
return console.log(`${sha} is waiting for its own review.`);
|
|
136
|
+
}
|
|
137
|
+
const decision = decide({
|
|
138
|
+
event: eventName,
|
|
139
|
+
action: event.action,
|
|
140
|
+
label: event.label?.name,
|
|
141
|
+
isDependabot: pr.author === "dependabot[bot]",
|
|
142
|
+
isDraft: pr.isDraft,
|
|
143
|
+
hasOverride: labels.includes(OVERRIDE),
|
|
144
|
+
senderIsOwner: event.sender?.login === event.repository?.owner?.login,
|
|
145
|
+
runConclusion: event.workflow_run?.conclusion,
|
|
146
|
+
verdict: verdictIn(comments, sha),
|
|
147
|
+
});
|
|
148
|
+
if (!decision)
|
|
149
|
+
return console.log("Nothing to post.");
|
|
150
|
+
await pulls.setStatus(sha, {
|
|
151
|
+
state: decision.state,
|
|
152
|
+
name: CONTEXT,
|
|
153
|
+
description: decision.description,
|
|
154
|
+
link: openRunner(repo).thisRun(process.env)?.page,
|
|
155
|
+
});
|
|
156
|
+
console.log(`${CONTEXT} on ${sha}: ${decision.state}, ${decision.description}`);
|
|
157
|
+
if (decision.removeOverride)
|
|
158
|
+
await pulls.removeLabel(pr.number, OVERRIDE);
|
|
159
|
+
if (decision.announceOverride) {
|
|
160
|
+
const open = await pulls.openThreadCount(pr.number);
|
|
161
|
+
await pulls.comment(pr.number, `\`${CONTEXT}\` overridden by @${event.sender.login} at ${sha.slice(0, 7)}. ` +
|
|
162
|
+
`${open} review thread(s) still open; each must be resolved before this can merge. ` +
|
|
163
|
+
`A new push removes the override.`);
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
// Only run as a CLI. Importing this module for tests must not call GitHub.
|
|
167
|
+
/** `factory review verdict`. */
|
|
168
|
+
export async function run() {
|
|
169
|
+
await main();
|
|
170
|
+
return 0;
|
|
171
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { type Tickets } from "./tickets/types.mts";
|
|
3
|
+
import { type Clock } from "./lib/clock.mts";
|
|
4
|
+
import { type ReviewerRun } from "./lib/work-status.mts";
|
|
5
|
+
export type HookInput = {
|
|
6
|
+
session_id?: string;
|
|
7
|
+
agent_id?: string;
|
|
8
|
+
agent_type?: string;
|
|
9
|
+
agent_transcript_path?: string;
|
|
10
|
+
last_assistant_message?: string;
|
|
11
|
+
};
|
|
12
|
+
/** What the hook remembers between its runs: the comment it posted, and the
|
|
13
|
+
* rows it shows. */
|
|
14
|
+
export type State = {
|
|
15
|
+
commentId: number | null;
|
|
16
|
+
runs: ReviewerRun[];
|
|
17
|
+
};
|
|
18
|
+
export type Deps = {
|
|
19
|
+
/** The ticket system the settings name, opened only when there is a run
|
|
20
|
+
* to record. */
|
|
21
|
+
tickets: () => Promise<Tickets>;
|
|
22
|
+
now: () => Date;
|
|
23
|
+
clock: (session: string) => Clock | null;
|
|
24
|
+
/** The text of a file, or null when it cannot be read. */
|
|
25
|
+
readFile: (path: string) => string | null;
|
|
26
|
+
state: {
|
|
27
|
+
read: (session: string, issue: number) => State;
|
|
28
|
+
write: (session: string, issue: number, state: State) => void;
|
|
29
|
+
};
|
|
30
|
+
/** Runs `work` while no other hook of this session edits the comment. */
|
|
31
|
+
locked: <T>(session: string, work: () => Promise<T>) => Promise<T>;
|
|
32
|
+
out: (line: string) => void;
|
|
33
|
+
};
|
|
34
|
+
/** The result a reviewer's report ends with. */
|
|
35
|
+
export declare function verdictOf(report: string): Pick<ReviewerRun, "result" | "findings">;
|
|
36
|
+
/** The last thing the agent said, from its transcript. */
|
|
37
|
+
export declare function lastAssistantText(transcript: string): string;
|
|
38
|
+
/** The report a reviewer handed its caller, which is a tool call's input
|
|
39
|
+
* and so in neither the hook's last message nor the transcript's text. */
|
|
40
|
+
export declare function handedBack(transcript: string): string | null;
|
|
41
|
+
/** The model an agent's definition declares, as the row shows it. */
|
|
42
|
+
export declare function modelName(definition: string | null): string;
|
|
43
|
+
/** The model the agent's transcript says it ran on, which can differ from
|
|
44
|
+
* its definition: a session keeps the definition it loaded at its start. */
|
|
45
|
+
export declare function ranOn(transcript: string): string | null;
|
|
46
|
+
export declare const minutes: (from: string, to: string) => string;
|
|
47
|
+
export declare function resultText(run: ReviewerRun, now: Date): string;
|
|
48
|
+
/** The comment: a table for the owner, then each row's hidden copy for
|
|
49
|
+
* `npx --no-install factory status`. It carries no cost marker: the session's next cost
|
|
50
|
+
* note already includes what the reviewers spent. */
|
|
51
|
+
export declare function commentFor(session: string, runs: ReviewerRun[], now: Date): string;
|
|
52
|
+
export declare function main(event: string, input: HookInput, agentsDir: string, d: Deps): Promise<number>;
|
|
53
|
+
/** `factory reviewers start|stop`, with the hook's input on stdin. */
|
|
54
|
+
export declare function run(argv: string[]): Promise<number>;
|
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Records each reviewer agent's run on the issue its session works, in one
|
|
3
|
+
// "Reviewers in this session" comment per session, edited in place. The
|
|
4
|
+
// SubagentStart and SubagentStop hooks in .claude/settings.json run it with
|
|
5
|
+
// the hook's input on stdin:
|
|
6
|
+
//
|
|
7
|
+
// npx --no-install factory reviewers start|stop
|
|
8
|
+
//
|
|
9
|
+
// It records only reviewers, the agents defined in the repository's
|
|
10
|
+
// .claude/agents/ folder, and only while the session's cost clock runs on
|
|
11
|
+
// an issue (`factory ticket claim` or `refining`). Recording a
|
|
12
|
+
// run never blocks the reviewer: every error exits 0, and a failed GitHub
|
|
13
|
+
// call shows the owner one warning line through `systemMessage`. Neither
|
|
14
|
+
// event carries the model, so the start reads it from the agent's
|
|
15
|
+
// definition, and the finish corrects it from the transcript.
|
|
16
|
+
//
|
|
17
|
+
// It reads the repository from the factory's settings only when it has a
|
|
18
|
+
// run to record, so a hook that fires before npm ci does nothing else.
|
|
19
|
+
import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
|
|
20
|
+
import { join } from "node:path";
|
|
21
|
+
import { loadSettings } from "./config.mjs";
|
|
22
|
+
import { targetOf } from "./config.mjs";
|
|
23
|
+
import { openTickets } from "./tickets/index.mjs";
|
|
24
|
+
import { NotFoundError } from "./tickets/types.mjs";
|
|
25
|
+
import { commonDir, readClock } from "./lib/clock.mjs";
|
|
26
|
+
import { subscriptionDollars } from "./lib/pricing.mjs";
|
|
27
|
+
import { dollars, spendIn } from "./lib/usage.mjs";
|
|
28
|
+
import { AGENT_MARK, REVIEWER_RUNS_MARK, isStuck, runLine, utc, } from "./lib/work-status.mjs";
|
|
29
|
+
// The line as the definitions show it, also when a reviewer copies it in
|
|
30
|
+
// backticks or bold.
|
|
31
|
+
const VERDICT = /^[`*]*Verdict: (?:(pass)|fail, (\d+) findings? to fix)\.?[`*]*\s*$/gim;
|
|
32
|
+
/** The result a reviewer's report ends with. */
|
|
33
|
+
export function verdictOf(report) {
|
|
34
|
+
const last = [...report.matchAll(VERDICT)].at(-1);
|
|
35
|
+
if (!last)
|
|
36
|
+
return { result: "no verdict" };
|
|
37
|
+
return last[1]
|
|
38
|
+
? { result: "passed" }
|
|
39
|
+
: { result: "failed", findings: Number(last[2]) };
|
|
40
|
+
}
|
|
41
|
+
/** The last thing the agent said, from its transcript. */
|
|
42
|
+
export function lastAssistantText(transcript) {
|
|
43
|
+
let text = "";
|
|
44
|
+
for (const line of transcript.split("\n")) {
|
|
45
|
+
try {
|
|
46
|
+
const entry = JSON.parse(line);
|
|
47
|
+
if (entry.type !== "assistant")
|
|
48
|
+
continue;
|
|
49
|
+
const content = entry.message?.content;
|
|
50
|
+
const said = Array.isArray(content)
|
|
51
|
+
? content
|
|
52
|
+
.filter((b) => b?.type === "text")
|
|
53
|
+
.map((b) => b.text)
|
|
54
|
+
.join("\n")
|
|
55
|
+
: typeof content === "string"
|
|
56
|
+
? content
|
|
57
|
+
: "";
|
|
58
|
+
if (said.trim())
|
|
59
|
+
text = said;
|
|
60
|
+
}
|
|
61
|
+
catch {
|
|
62
|
+
continue;
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
return text;
|
|
66
|
+
}
|
|
67
|
+
/** The report a reviewer handed its caller, which is a tool call's input
|
|
68
|
+
* and so in neither the hook's last message nor the transcript's text. */
|
|
69
|
+
export function handedBack(transcript) {
|
|
70
|
+
let report = null;
|
|
71
|
+
for (const line of transcript.split("\n")) {
|
|
72
|
+
try {
|
|
73
|
+
const entry = JSON.parse(line);
|
|
74
|
+
const content = entry.message?.content;
|
|
75
|
+
if (entry.type !== "assistant" || !Array.isArray(content))
|
|
76
|
+
continue;
|
|
77
|
+
for (const block of content) {
|
|
78
|
+
const message = block?.type === "tool_use" && block.name === "SubagentHandback"
|
|
79
|
+
? block.input?.message
|
|
80
|
+
: null;
|
|
81
|
+
if (typeof message === "string")
|
|
82
|
+
report = message;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
catch {
|
|
86
|
+
continue;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
return report;
|
|
90
|
+
}
|
|
91
|
+
/** The model an agent's definition declares, as the row shows it. */
|
|
92
|
+
export function modelName(definition) {
|
|
93
|
+
const frontmatter = /^---\s*\n([\s\S]*?)\n---/.exec(definition ?? "")?.[1];
|
|
94
|
+
const declared = /^model:\s*(\S+)/m.exec(frontmatter ?? "")?.[1];
|
|
95
|
+
return declared ? familyName(declared) : "unknown";
|
|
96
|
+
}
|
|
97
|
+
/** "Sonnet" for `sonnet` or `claude-sonnet-5-5`. */
|
|
98
|
+
function familyName(model) {
|
|
99
|
+
const family = /(fable|opus|sonnet|haiku)/i.exec(model)?.[1] ?? model;
|
|
100
|
+
return family[0].toUpperCase() + family.slice(1).toLowerCase();
|
|
101
|
+
}
|
|
102
|
+
/** The model the agent's transcript says it ran on, which can differ from
|
|
103
|
+
* its definition: a session keeps the definition it loaded at its start. */
|
|
104
|
+
export function ranOn(transcript) {
|
|
105
|
+
let model = null;
|
|
106
|
+
for (const line of transcript.split("\n")) {
|
|
107
|
+
try {
|
|
108
|
+
const entry = JSON.parse(line);
|
|
109
|
+
const said = entry.message?.model;
|
|
110
|
+
if (entry.type === "assistant" && said && said !== "<synthetic>")
|
|
111
|
+
model = said;
|
|
112
|
+
}
|
|
113
|
+
catch {
|
|
114
|
+
continue;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
return model && familyName(model);
|
|
118
|
+
}
|
|
119
|
+
export const minutes = (from, to) => `${Math.max(0, Math.round((Date.parse(to) - Date.parse(from)) / 60_000))} min`;
|
|
120
|
+
export function resultText(run, now) {
|
|
121
|
+
if (isStuck(run, now))
|
|
122
|
+
return "no finish recorded";
|
|
123
|
+
switch (run.result) {
|
|
124
|
+
case "running":
|
|
125
|
+
return "running";
|
|
126
|
+
case "passed":
|
|
127
|
+
return "passed";
|
|
128
|
+
case "failed":
|
|
129
|
+
return `${run.findings} finding${run.findings === 1 ? "" : "s"} to fix`;
|
|
130
|
+
case "no verdict":
|
|
131
|
+
return "finished, no verdict";
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
/** The comment: a table for the owner, then each row's hidden copy for
|
|
135
|
+
* `npx --no-install factory status`. It carries no cost marker: the session's next cost
|
|
136
|
+
* note already includes what the reviewers spent. */
|
|
137
|
+
export function commentFor(session, runs, now) {
|
|
138
|
+
const rows = runs.map((run) => {
|
|
139
|
+
const finished = run.result !== "running";
|
|
140
|
+
return `| ${run.reviewer} | ${run.model} | ${utc(run.start)} | ${resultText(run, now)} | ${finished && run.end ? minutes(run.start, run.end) : ""} | ${finished && run.cost !== undefined ? `${dollars(subscriptionDollars(run.cost))} (${dollars(run.cost)})` : ""} |`;
|
|
141
|
+
});
|
|
142
|
+
return [
|
|
143
|
+
"Reviewers in this session, each cost as a share of the subscription and, in parentheses, at API list prices:",
|
|
144
|
+
"",
|
|
145
|
+
"| Reviewer | Model | Started | Result | Ran for | Cost |",
|
|
146
|
+
"| --- | --- | --- | --- | --- | --- |",
|
|
147
|
+
...rows,
|
|
148
|
+
"",
|
|
149
|
+
`${REVIEWER_RUNS_MARK}${session} -->`,
|
|
150
|
+
...runs.map(runLine),
|
|
151
|
+
AGENT_MARK,
|
|
152
|
+
].join("\n");
|
|
153
|
+
}
|
|
154
|
+
async function publish(issue, session, state, d) {
|
|
155
|
+
const body = commentFor(session, state.runs, d.now());
|
|
156
|
+
const tickets = await d.tickets();
|
|
157
|
+
if (state.commentId !== null) {
|
|
158
|
+
try {
|
|
159
|
+
await tickets.editComment(state.commentId, body);
|
|
160
|
+
return state.commentId;
|
|
161
|
+
}
|
|
162
|
+
catch (error) {
|
|
163
|
+
// A deleted comment is posted again; anything else is a failure.
|
|
164
|
+
if (!(error instanceof NotFoundError))
|
|
165
|
+
throw error;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
return tickets.comment(issue, body);
|
|
169
|
+
}
|
|
170
|
+
export async function main(event, input, agentsDir, d) {
|
|
171
|
+
const session = input.session_id ?? "";
|
|
172
|
+
const reviewer = input.agent_type ?? "";
|
|
173
|
+
if (!session || !/^[\w-]+$/.test(reviewer))
|
|
174
|
+
return 0;
|
|
175
|
+
if (event !== "start" && event !== "stop")
|
|
176
|
+
return 0;
|
|
177
|
+
// A reviewer is an agent the repository defines; a built-in one, such as
|
|
178
|
+
// Explore, has no file there.
|
|
179
|
+
const definition = d.readFile(join(agentsDir, `${reviewer}.md`));
|
|
180
|
+
if (definition === null)
|
|
181
|
+
return 0;
|
|
182
|
+
let issue = null;
|
|
183
|
+
try {
|
|
184
|
+
const clock = d.clock(session);
|
|
185
|
+
if (!clock || clock.issue === null)
|
|
186
|
+
return 0;
|
|
187
|
+
issue = clock.issue;
|
|
188
|
+
const on = clock.issue;
|
|
189
|
+
await d.locked(session, async () => {
|
|
190
|
+
const state = d.state.read(session, on);
|
|
191
|
+
const now = d.now().toISOString();
|
|
192
|
+
const id = input.agent_id ?? `${reviewer}-${now}`;
|
|
193
|
+
if (event === "start") {
|
|
194
|
+
state.runs.push({
|
|
195
|
+
id,
|
|
196
|
+
reviewer,
|
|
197
|
+
model: modelName(definition),
|
|
198
|
+
start: now,
|
|
199
|
+
result: "running",
|
|
200
|
+
});
|
|
201
|
+
}
|
|
202
|
+
else {
|
|
203
|
+
let run = state.runs.find((r) => r.id === id);
|
|
204
|
+
if (!run) {
|
|
205
|
+
// The start went unrecorded; keep the finish.
|
|
206
|
+
run = {
|
|
207
|
+
id,
|
|
208
|
+
reviewer,
|
|
209
|
+
model: modelName(definition),
|
|
210
|
+
start: now,
|
|
211
|
+
result: "running",
|
|
212
|
+
};
|
|
213
|
+
state.runs.push(run);
|
|
214
|
+
}
|
|
215
|
+
const transcript = input.agent_transcript_path
|
|
216
|
+
? d.readFile(input.agent_transcript_path)
|
|
217
|
+
: null;
|
|
218
|
+
const report = (transcript ? handedBack(transcript) : null) ??
|
|
219
|
+
input.last_assistant_message ??
|
|
220
|
+
(transcript ? lastAssistantText(transcript) : "");
|
|
221
|
+
Object.assign(run, verdictOf(report), { end: now });
|
|
222
|
+
if (transcript !== null) {
|
|
223
|
+
run.model = ranOn(transcript) ?? run.model;
|
|
224
|
+
const spend = spendIn([transcript]);
|
|
225
|
+
if (spend.priced > 0)
|
|
226
|
+
run.cost = spend.dollars;
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
d.state.write(session, on, state);
|
|
230
|
+
state.commentId = await publish(on, session, state, d);
|
|
231
|
+
d.state.write(session, on, state);
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
|
+
catch (error) {
|
|
235
|
+
const why = error instanceof Error ? error.message : String(error);
|
|
236
|
+
d.out(JSON.stringify({
|
|
237
|
+
systemMessage: `The ${reviewer} run was not recorded${issue === null ? "" : ` on #${issue}`}: ${why.split("\n")[0].slice(0, 200)}`,
|
|
238
|
+
}));
|
|
239
|
+
}
|
|
240
|
+
return 0;
|
|
241
|
+
}
|
|
242
|
+
const statePath = (session, issue) => join(commonDir(), `reviewer-runs-${session}-${issue}.json`);
|
|
243
|
+
/** A lock directory beside the state, since reviewers run in parallel. One
|
|
244
|
+
* older than a minute was left by a hook that died, and is taken over. */
|
|
245
|
+
async function locked(session, work) {
|
|
246
|
+
const lock = join(commonDir(), `reviewer-runs-${session}.lock`);
|
|
247
|
+
for (let tries = 0;; tries++) {
|
|
248
|
+
try {
|
|
249
|
+
mkdirSync(lock);
|
|
250
|
+
break;
|
|
251
|
+
}
|
|
252
|
+
catch {
|
|
253
|
+
if (existsSync(lock) && Date.now() - statSync(lock).mtimeMs > 60_000)
|
|
254
|
+
rmSync(lock, { recursive: true, force: true });
|
|
255
|
+
else if (tries > 100)
|
|
256
|
+
throw new Error("another hook holds the lock");
|
|
257
|
+
else
|
|
258
|
+
await new Promise((resolve) => setTimeout(resolve, 100));
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
try {
|
|
262
|
+
return await work();
|
|
263
|
+
}
|
|
264
|
+
finally {
|
|
265
|
+
rmSync(lock, { recursive: true, force: true });
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
const read = (path) => {
|
|
269
|
+
try {
|
|
270
|
+
return readFileSync(path, "utf8");
|
|
271
|
+
}
|
|
272
|
+
catch {
|
|
273
|
+
return null;
|
|
274
|
+
}
|
|
275
|
+
};
|
|
276
|
+
/** `factory reviewers start|stop`, with the hook's input on stdin. */
|
|
277
|
+
export async function run(argv) {
|
|
278
|
+
let input = {};
|
|
279
|
+
try {
|
|
280
|
+
input = JSON.parse(readFileSync(0, "utf8"));
|
|
281
|
+
}
|
|
282
|
+
catch {
|
|
283
|
+
// No input: nothing to record.
|
|
284
|
+
}
|
|
285
|
+
const project = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
|
|
286
|
+
return main(argv[0] ?? "", input, join(project, ".claude", "agents"), {
|
|
287
|
+
tickets: async () => {
|
|
288
|
+
const settings = await loadSettings();
|
|
289
|
+
return (await openTickets(settings, targetOf(settings, process.env)))
|
|
290
|
+
.tickets;
|
|
291
|
+
},
|
|
292
|
+
now: () => new Date(),
|
|
293
|
+
clock: readClock,
|
|
294
|
+
readFile: read,
|
|
295
|
+
state: {
|
|
296
|
+
read: (session, issue) => {
|
|
297
|
+
const text = read(statePath(session, issue));
|
|
298
|
+
try {
|
|
299
|
+
return text
|
|
300
|
+
? JSON.parse(text)
|
|
301
|
+
: { commentId: null, runs: [] };
|
|
302
|
+
}
|
|
303
|
+
catch {
|
|
304
|
+
return { commentId: null, runs: [] };
|
|
305
|
+
}
|
|
306
|
+
},
|
|
307
|
+
write: (session, issue, state) => writeFileSync(statePath(session, issue), JSON.stringify(state)),
|
|
308
|
+
},
|
|
309
|
+
locked,
|
|
310
|
+
out: (line) => console.log(line),
|
|
311
|
+
}).catch(() => 0);
|
|
312
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { GhIn } from "../lib/gh.mts";
|
|
2
|
+
import type { Transport } from "../tickets/transport.mts";
|
|
3
|
+
import type { Runner } from "./types.mts";
|
|
4
|
+
/** The workflow a build is a run of. */
|
|
5
|
+
export declare const BUILD_WORKFLOW = "factory-build.yml";
|
|
6
|
+
export declare function githubActionsRunner(o: {
|
|
7
|
+
transport: Transport;
|
|
8
|
+
repository: string;
|
|
9
|
+
/** The GitHub CLI, given a secret's value on standard input. Without it,
|
|
10
|
+
* the runner cannot store a secret. */
|
|
11
|
+
cli?: GhIn;
|
|
12
|
+
}): Runner;
|