@davidbyoung/software-factory 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +205 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. package/workflows/factory-review.yml +75 -0
@@ -0,0 +1,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;