@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.
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 +209 -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
package/dist/sync.mjs ADDED
@@ -0,0 +1,292 @@
1
+ // Writes the factory's skills, agents, rules, review instructions,
2
+ // workflows, and the actions they call from the package into the
3
+ // repository, its hook entries into `.claude/settings.json`, the rules'
4
+ // import into `CLAUDE.md`, and
5
+ // `.claude/factory.lock`: the factory's version and the files it wrote.
6
+ //
7
+ // factory sync # write what differs
8
+ // factory sync --check # write nothing; exit 1 naming what differs
9
+ //
10
+ // A copy is the source, byte for byte: edit the source in the package, never
11
+ // the copy. A file the lock lists that the package no longer has is
12
+ // deleted. Nothing else is.
13
+ import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
14
+ import { dirname, join, relative, sep } from "node:path";
15
+ import { fileURLToPath } from "node:url";
16
+ import { defaultDeps, loadSettings, repoRoot, } from "./config.mjs";
17
+ /** The package's own folder: the parent of `src/`, or of `dist/` once
18
+ * compiled. */
19
+ export const PACKAGE = dirname(dirname(fileURLToPath(import.meta.url)));
20
+ export const LOCK = ".claude/factory.lock";
21
+ export const SETTINGS_JSON = ".claude/settings.json";
22
+ export const CLAUDE_MD = "CLAUDE.md";
23
+ export const IMPORT_LINE = "@.claude/factory/rules.md";
24
+ const LAUNCHER = "bin/factory.js";
25
+ const DEPENDABOT = ".github/dependabot.yml";
26
+ /** A part of the package written only when a setting or a file in the
27
+ * repository turns it on, by its path in the package: a skill's folder, an
28
+ * agent's file, or a workflow's file. Everything else is the factory's
29
+ * core, called by its own steps, and is written to every repository. */
30
+ const NEEDS = {
31
+ "skills/factory-design": (s) => s.site !== null,
32
+ "agents/factory-ui-reviewer.md": (s) => s.site !== null,
33
+ "skills/factory-deps": (_, has) => has(DEPENDABOT),
34
+ "workflows/factory-deps.yml": (_, has) => has(DEPENDABOT),
35
+ "workflows/factory-deps-auto-merge.yml": (_, has) => has(DEPENDABOT),
36
+ "workflows/factory-board-sync.yml": (s) => s.tickets.board !== null,
37
+ "workflows/factory-merge-policy.yml": (s) => s.autoMerge.allow.length > 0,
38
+ "workflows/factory-claude-review.yml": (s) => s.ciReview !== null,
39
+ };
40
+ /** The workflows that run a Claude session, by the kind of session each
41
+ * runs. */
42
+ const SESSION_WORKFLOWS = {
43
+ "factory-build.yml": "build",
44
+ "factory-conflicts.yml": "conflicts",
45
+ "factory-review.yml": "review",
46
+ "factory-deps.yml": "dependencies",
47
+ };
48
+ /** A session workflow with the minutes its session may run, and its job 10
49
+ * more, so the steps after the session still run before the job is
50
+ * stopped. */
51
+ export function withMinutes(text, minutes, file) {
52
+ const one = (pattern, value, out) => {
53
+ if ((out.match(pattern) ?? []).length !== 1)
54
+ throw new Error(`${file}: expected one line matching ${pattern.source}, to set the session's minutes`);
55
+ return out.replace(pattern, (_, indent) => `${indent}${value}`);
56
+ };
57
+ const session = one(/^(\s+minutes: )\d+$/gm, minutes, text);
58
+ return one(/^(\s+timeout-minutes: )\d+$/gm, minutes + 10, session);
59
+ }
60
+ function walk(dir, base = dir) {
61
+ if (!existsSync(dir))
62
+ return [];
63
+ return readdirSync(dir)
64
+ .sort()
65
+ .flatMap((name) => {
66
+ const path = join(dir, name);
67
+ return statSync(path).isDirectory()
68
+ ? walk(path, base)
69
+ : [relative(base, path).split(sep).join("/")];
70
+ });
71
+ }
72
+ /** Each copy, as [path in the package, path in the repository]. */
73
+ export function copies(pkg, s, has) {
74
+ const wanted = (from) => {
75
+ const [kind, name] = from.split("/");
76
+ const needs = NEEDS[`${kind}/${name}`];
77
+ return !needs || needs(s, has);
78
+ };
79
+ const out = [];
80
+ const add = (dir, to) => {
81
+ for (const f of walk(join(pkg, dir)))
82
+ if (wanted(`${dir}/${f}`))
83
+ out.push([`${dir}/${f}`, `${to}/${f}`]);
84
+ };
85
+ add("skills", ".claude/skills");
86
+ add("agents", ".claude/agents");
87
+ out.push(["rules.md", ".claude/factory/rules.md"]);
88
+ out.push(["review.md", ".github/factory-review.md"]);
89
+ add("workflows", ".github/workflows");
90
+ add("actions", ".github/actions");
91
+ return out;
92
+ }
93
+ /** The launcher's path from the repository's root: the package's own
94
+ * folder where it is inside the repository, as a workspace or installed,
95
+ * and where it would be installed otherwise. */
96
+ export function launcherPath(pkg, root, name) {
97
+ const rel = relative(realpathSync(root), realpathSync(pkg))
98
+ .split(sep)
99
+ .join("/");
100
+ const base = rel && !rel.startsWith("..") && !rel.startsWith("/")
101
+ ? rel
102
+ : `node_modules/${name}`;
103
+ return `${base}/${LAUNCHER}`;
104
+ }
105
+ /** The five hook entries, one per event. */
106
+ export function factoryHooks(launcher) {
107
+ const run = (args) => `node "$CLAUDE_PROJECT_DIR"/${launcher} ${args}`;
108
+ return [
109
+ [
110
+ "SessionStart",
111
+ {
112
+ hooks: [
113
+ { type: "command", command: run("session-start"), timeout: 30 },
114
+ ],
115
+ },
116
+ ],
117
+ [
118
+ "PreToolUse",
119
+ {
120
+ matcher: "Bash",
121
+ hooks: [
122
+ {
123
+ type: "command",
124
+ command: run("guard"),
125
+ timeout: 180,
126
+ statusMessage: "Checking the factory's guards",
127
+ },
128
+ ],
129
+ },
130
+ ],
131
+ [
132
+ "PermissionRequest",
133
+ {
134
+ matcher: "Write|Edit|MultiEdit",
135
+ hooks: [
136
+ { type: "command", command: run("guard permission"), timeout: 30 },
137
+ ],
138
+ },
139
+ ],
140
+ [
141
+ "SubagentStart",
142
+ {
143
+ hooks: [
144
+ {
145
+ type: "command",
146
+ command: `${run("reviewers start")} 2>/dev/null || true`,
147
+ timeout: 30,
148
+ },
149
+ ],
150
+ },
151
+ ],
152
+ [
153
+ "SubagentStop",
154
+ {
155
+ hooks: [
156
+ {
157
+ type: "command",
158
+ command: `${run("reviewers stop")} 2>/dev/null || true`,
159
+ timeout: 30,
160
+ },
161
+ ],
162
+ },
163
+ ],
164
+ ];
165
+ }
166
+ /** Claude Code's lines that name an AI in a commit and a pull request, all
167
+ * off: a person's account owns every commit. It is in this file because a
168
+ * session that runs where nobody's own settings reach, as a build in GitHub
169
+ * Actions does, reads the repository's. */
170
+ const NO_ATTRIBUTION = { commit: "", pr: "", sessionUrl: false };
171
+ const isFactory = (h) => typeof h.command === "string" && h.command.includes(`/${LAUNCHER}`);
172
+ /** `.claude/settings.json` with the entries that run the factory's launcher
173
+ * replaced by the five above, and attribution turned off unless the file
174
+ * sets its own. Every other entry stays, in its order. */
175
+ export function withHooks(text, launcher) {
176
+ const settings = text ? JSON.parse(text) : {};
177
+ const hooks = {};
178
+ for (const [event, groups] of Object.entries(settings.hooks ?? {})) {
179
+ const kept = groups
180
+ .map((g) => ({ ...g, hooks: g.hooks.filter((h) => !isFactory(h)) }))
181
+ .filter((g) => g.hooks.length > 0);
182
+ if (kept.length)
183
+ hooks[event] = kept;
184
+ }
185
+ for (const [event, group] of factoryHooks(launcher))
186
+ (hooks[event] ??= []).push(group);
187
+ const attribution = settings.attribution ?? NO_ATTRIBUTION;
188
+ return `${JSON.stringify({ ...settings, attribution, hooks }, null, 2)}\n`;
189
+ }
190
+ /** `CLAUDE.md` with the rules' import added when no line is that import. */
191
+ export function withImport(text) {
192
+ if (text === null)
193
+ return `${IMPORT_LINE}\n`;
194
+ if (text.split("\n").some((line) => line.trim() === IMPORT_LINE))
195
+ return text;
196
+ return `${text}${text.endsWith("\n") || !text ? "" : "\n"}\n${IMPORT_LINE}\n`;
197
+ }
198
+ export function lockText(version, files) {
199
+ return [
200
+ "# Written by `factory sync`: the factory's version and the files it",
201
+ "# wrote. Do not edit.",
202
+ `version: ${version}`,
203
+ "files:",
204
+ ...files.map((f) => ` - ${f}`),
205
+ "",
206
+ ].join("\n");
207
+ }
208
+ export function lockedFiles(text) {
209
+ if (!text)
210
+ return [];
211
+ return text
212
+ .split("\n")
213
+ .map((l) => /^ {2}- (.+)$/.exec(l)?.[1])
214
+ .filter((f) => Boolean(f));
215
+ }
216
+ /** What a sync of `root` from `pkg` writes and deletes. */
217
+ export function plan(pkg, root, s) {
218
+ const manifest = JSON.parse(readFileSync(join(pkg, "package.json"), "utf8"));
219
+ const read = (p) => existsSync(join(root, p)) ? readFileSync(join(root, p), "utf8") : null;
220
+ const write = new Map();
221
+ const has = (p) => existsSync(join(root, p));
222
+ for (const [from, to] of copies(pkg, s, has)) {
223
+ const text = readFileSync(join(pkg, from), "utf8");
224
+ const kind = SESSION_WORKFLOWS[from.replace(/^workflows\//, "")];
225
+ write.set(to, kind && from.startsWith("workflows/")
226
+ ? withMinutes(text, s.sessionMinutes[kind], from)
227
+ : text);
228
+ }
229
+ const launcher = launcherPath(pkg, root, manifest.name);
230
+ write.set(SETTINGS_JSON, withHooks(read(SETTINGS_JSON), launcher));
231
+ write.set(CLAUDE_MD, withImport(read(CLAUDE_MD)));
232
+ const files = [...write.keys()].filter((p) => p !== SETTINGS_JSON && p !== CLAUDE_MD);
233
+ write.set(LOCK, lockText(manifest.version, files));
234
+ const remove = lockedFiles(read(LOCK)).filter((p) => !write.has(p) && existsSync(join(root, p)));
235
+ return { write, remove };
236
+ }
237
+ /** The paths whose content a sync would change, in the plan's order. */
238
+ export function differences(root, p) {
239
+ const changed = [...p.write]
240
+ .filter(([path, text]) => {
241
+ const at = join(root, path);
242
+ return !existsSync(at) || readFileSync(at, "utf8") !== text;
243
+ })
244
+ .map(([path]) => path);
245
+ return [...changed, ...p.remove];
246
+ }
247
+ export async function main(argv, d) {
248
+ const check = argv.includes("--check");
249
+ let s;
250
+ try {
251
+ s = await d.settings();
252
+ }
253
+ catch (e) {
254
+ d.err(e instanceof Error ? e.message : String(e));
255
+ return 1;
256
+ }
257
+ const p = plan(d.pkg, d.root, s);
258
+ const differ = differences(d.root, p);
259
+ if (check) {
260
+ if (differ.length === 0)
261
+ return 0;
262
+ d.err("the factory's files are out of sync:");
263
+ for (const path of differ)
264
+ d.err(` ${path}`);
265
+ d.err("Run `npx --no-install factory sync` and commit the result.");
266
+ return 1;
267
+ }
268
+ for (const path of differ) {
269
+ const at = join(d.root, path);
270
+ const text = p.write.get(path);
271
+ if (text === undefined) {
272
+ rmSync(at, { force: true });
273
+ d.out(`deleted ${path}`);
274
+ }
275
+ else {
276
+ mkdirSync(dirname(at), { recursive: true });
277
+ writeFileSync(at, text);
278
+ d.out(`wrote ${path}`);
279
+ }
280
+ }
281
+ return 0;
282
+ }
283
+ export async function run(argv) {
284
+ const root = repoRoot();
285
+ return main(argv, {
286
+ root,
287
+ pkg: PACKAGE,
288
+ settings: () => loadSettings(defaultDeps(root)),
289
+ out: (line) => console.log(line),
290
+ err: (line) => console.error(line),
291
+ });
292
+ }
@@ -0,0 +1,61 @@
1
+ #!/usr/bin/env node
2
+ import type { Runner } from "./runner/types.mts";
3
+ import { type Settings } from "./config.mts";
4
+ import { type IssueComment, type PullRequest } from "./lib/work-status.mts";
5
+ import { type Clock } from "./lib/clock.mts";
6
+ import type { Measured } from "./lib/usage.mts";
7
+ import { type Ticket, type Tickets } from "./tickets/types.mts";
8
+ /** The ticket system this session reaches. */
9
+ export type Opened = {
10
+ tickets: Tickets;
11
+ };
12
+ export type Deps = {
13
+ /** The adapter the settings pick, for the repository and board named. */
14
+ open: (settings: Settings, target: {
15
+ repository: string;
16
+ board: number | null;
17
+ }) => Promise<Opened>;
18
+ /** The open pull requests of a repository, on the code host the settings
19
+ * name, which `end` reads for a link to the ticket. */
20
+ openPulls: (repository: string, codeHost: string) => Promise<PullRequest[]>;
21
+ /** The runner the settings name, which says whether this session is in
22
+ * one of its runs. */
23
+ runner: (repository: string, name: string) => Pick<Runner, "thisRun">;
24
+ /** The factory's settings, read once when the command starts. */
25
+ settings: () => Promise<Settings>;
26
+ env: Record<string, string | undefined>;
27
+ sleep: (ms: number) => Promise<unknown>;
28
+ out: (line: string) => void;
29
+ /** Where this checkout remembers the claim it posted on each issue. */
30
+ claimStore: {
31
+ read: (issue: number) => number | null;
32
+ write: (issue: number, commentId: number) => void;
33
+ };
34
+ readFile: (path: string) => string;
35
+ now: () => Date;
36
+ /** The session's cost clock, by session ID. */
37
+ clock: {
38
+ read: (session: string) => Clock | null;
39
+ write: (session: string, clock: Clock) => void;
40
+ };
41
+ /** What the session spent since `since`, or since it started. */
42
+ measure: (session: string, since: string | null) => Measured;
43
+ };
44
+ export type { Clock };
45
+ export declare function readComments(c: {
46
+ tickets: Tickets;
47
+ }, issue: number): Promise<IssueComment[]>;
48
+ /** What the ticket waits on that is still open; none when the ticket
49
+ * system records no blockers. */
50
+ export declare function openBlockers(c: {
51
+ tickets: Tickets;
52
+ }, issue: number): Promise<number[]>;
53
+ /** The outcome of a claim, as `factory-build` reads it. */
54
+ export declare function claimOutcome(comments: IssueComment[], mine: number): "claimed" | `held by ${string}`;
55
+ export declare function withLine(body: string, line: string): string;
56
+ /** A ticket for a reader: title, state, labels, body, and each comment with
57
+ * its ID and author. */
58
+ export declare function formatTicket(t: Ticket): string[];
59
+ export declare function main(argv: string[], deps: Deps): Promise<number>;
60
+ /** `factory ticket ...` and `factory follow-up ...`. */
61
+ export declare function run(argv: string[]): Promise<number>;