@davidbyoung/software-factory 0.1.10 → 0.1.12

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 (83) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ticket-readiness.md +20 -15
  4. package/agents/factory-ui-reviewer.md +2 -2
  5. package/dist/board.d.mts +8 -8
  6. package/dist/board.mjs +53 -37
  7. package/dist/build.d.mts +4 -0
  8. package/dist/build.mjs +9 -4
  9. package/dist/cli.mjs +25 -5
  10. package/dist/code-host/github.mjs +11 -4
  11. package/dist/code-host/types.d.mts +8 -2
  12. package/dist/commands.d.mts +7 -2
  13. package/dist/commands.mjs +96 -17
  14. package/dist/config.d.mts +3 -4
  15. package/dist/config.mjs +7 -8
  16. package/dist/init.d.mts +11 -0
  17. package/dist/init.mjs +56 -1
  18. package/dist/lib/clock.d.mts +3 -1
  19. package/dist/lib/clock.mjs +12 -6
  20. package/dist/lib/pull-tickets.d.mts +15 -0
  21. package/dist/lib/pull-tickets.mjs +12 -0
  22. package/dist/lib/usage.d.mts +3 -1
  23. package/dist/lib/usage.mjs +4 -2
  24. package/dist/lib/work-status.d.mts +28 -24
  25. package/dist/lib/work-status.mjs +21 -35
  26. package/dist/merge-policy.mjs +7 -3
  27. package/dist/poller.d.mts +3 -3
  28. package/dist/poller.mjs +18 -14
  29. package/dist/pr.d.mts +26 -6
  30. package/dist/pr.mjs +92 -28
  31. package/dist/review-tickets.d.mts +12 -0
  32. package/dist/review-tickets.mjs +59 -0
  33. package/dist/review-verdict.d.mts +22 -4
  34. package/dist/review-verdict.mjs +55 -17
  35. package/dist/reviewers.d.mts +7 -4
  36. package/dist/reviewers.mjs +19 -12
  37. package/dist/runner/github-actions.mjs +6 -7
  38. package/dist/runner/types.d.mts +7 -6
  39. package/dist/specs/index.d.mts +6 -0
  40. package/dist/specs/index.mjs +15 -0
  41. package/dist/specs/openspec.d.mts +2 -0
  42. package/dist/specs/openspec.mjs +78 -0
  43. package/dist/specs/types.d.mts +53 -0
  44. package/dist/specs/types.mjs +4 -0
  45. package/dist/status.d.mts +17 -7
  46. package/dist/status.mjs +35 -23
  47. package/dist/sync.d.mts +4 -0
  48. package/dist/sync.mjs +14 -1
  49. package/dist/ticket.d.mts +15 -7
  50. package/dist/ticket.mjs +128 -61
  51. package/dist/tickets/github-access.d.mts +5 -0
  52. package/dist/tickets/github-access.mjs +22 -0
  53. package/dist/tickets/github.d.mts +10 -2
  54. package/dist/tickets/github.mjs +76 -20
  55. package/dist/tickets/index.d.mts +7 -1
  56. package/dist/tickets/index.mjs +15 -1
  57. package/dist/tickets/types.d.mts +63 -30
  58. package/dist/tickets/types.mjs +13 -3
  59. package/dist/tool-names.d.mts +2 -0
  60. package/dist/tool-names.mjs +3 -0
  61. package/dist/tools.d.mts +2 -0
  62. package/dist/tools.mjs +3 -0
  63. package/docs/builds.md +4 -1
  64. package/docs/cli.md +30 -11
  65. package/docs/configuration.md +51 -39
  66. package/docs/developing.md +115 -62
  67. package/docs/existing-repo.md +4 -3
  68. package/docs/github/reference.md +1 -1
  69. package/docs/github/setup.md +20 -3
  70. package/docs/glossary.md +7 -6
  71. package/docs/limitations.md +8 -5
  72. package/docs/plugins.md +6 -6
  73. package/docs/updating.md +18 -0
  74. package/docs/workflow.md +25 -8
  75. package/package.json +1 -1
  76. package/review.md +11 -11
  77. package/rules.md +52 -42
  78. package/skills/factory-address-review/SKILL.md +44 -42
  79. package/skills/factory-build/SKILL.md +71 -72
  80. package/skills/factory-refine/SKILL.md +31 -23
  81. package/skills/factory-resolve-conflicts/SKILL.md +12 -10
  82. package/workflows/factory-build.yml +6 -5
  83. package/workflows/factory-claude-review.yml +38 -1
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import type { CodeHost } from "./code-host/types.mts";
2
3
  export declare const CONTEXT = "Review verdict";
3
4
  export declare const OVERRIDE = "verdict: override";
4
5
  export type Verdict = "ready" | "changes" | null;
@@ -13,10 +14,12 @@ export type Input = {
13
14
  /** The override label is on the pull request. A push removes it, so it
14
15
  * always applies to the head. */
15
16
  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;
17
+ /** The account behind a labeled event can write to the repository.
18
+ * Agents act through such accounts too; the guard hook stops them on a
19
+ * person's laptop. This stops everyone else. */
20
+ senderIsApprover?: boolean;
21
+ /** The code host could not say whether that account can write. */
22
+ senderUnchecked?: boolean;
20
23
  /** workflow_run's conclusion: success, failure, cancelled, skipped. */
21
24
  runConclusion?: string;
22
25
  /** The marker in the review's summary for this commit; null if none. */
@@ -27,6 +30,8 @@ export type Decision = {
27
30
  description: string;
28
31
  removeOverride?: boolean;
29
32
  announceOverride?: boolean;
33
+ /** Why the override was removed, for the comment that says so. */
34
+ explainRemoval?: "not an approver" | "could not check";
30
35
  };
31
36
  /** The status to post, or null to leave the commit's status as it is. */
32
37
  export declare function decide(input: Input): Decision | null;
@@ -46,5 +51,18 @@ export declare function verdictIn(comments: {
46
51
  author: string;
47
52
  body: string;
48
53
  }[], sha: string): Verdict;
54
+ /** Posts the verdict for one event, removes or announces the override,
55
+ * and says why it removed one. When the code host cannot say whether the
56
+ * account that added the override can write, it removes the label, then
57
+ * rejects with the reason. */
58
+ export declare function apply(o: {
59
+ eventName: Input["event"];
60
+ /** The event as GitHub sends it. */
61
+ event: any;
62
+ pulls: CodeHost;
63
+ /** The page of the run posting the status. */
64
+ link?: string;
65
+ log: (line: string) => void;
66
+ }): Promise<void>;
49
67
  /** `factory review verdict`. */
50
68
  export declare function run(): Promise<number>;
@@ -23,7 +23,7 @@ const DRAFT = {
23
23
  };
24
24
  const OVERRIDDEN = {
25
25
  state: "success",
26
- description: "Overridden by the owner",
26
+ description: "Overridden by an approver",
27
27
  };
28
28
  function fromVerdict(verdict, ifMissing) {
29
29
  if (verdict === "ready") {
@@ -64,8 +64,14 @@ export function decide(input) {
64
64
  case "labeled":
65
65
  if (input.label !== OVERRIDE)
66
66
  return null;
67
- if (!input.senderIsOwner) {
68
- return { ...fromVerdict(input.verdict, WAITING), removeOverride: true };
67
+ if (!input.senderIsApprover) {
68
+ return {
69
+ ...fromVerdict(input.verdict, WAITING),
70
+ removeOverride: true,
71
+ explainRemoval: input.senderUnchecked
72
+ ? "could not check"
73
+ : "not an approver",
74
+ };
69
75
  }
70
76
  return { ...OVERRIDDEN, announceOverride: true };
71
77
  case "unlabeled":
@@ -73,7 +79,7 @@ export function decide(input) {
73
79
  ? fromVerdict(input.verdict, WAITING)
74
80
  : null;
75
81
  case "synchronize":
76
- // The owner overrode the commit they read. The new one is unread.
82
+ // The approver overrode the commit they read. The new one is unread.
77
83
  return { ...WAITING, removeOverride: input.hasOverride };
78
84
  default:
79
85
  if (input.hasOverride)
@@ -108,11 +114,12 @@ export function verdictIn(comments, sha) {
108
114
  const match = /<!-- review-verdict: (ready|changes) -->/.exec(body);
109
115
  return match ? match[1] : null;
110
116
  }
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);
117
+ /** Posts the verdict for one event, removes or announces the override,
118
+ * and says why it removed one. When the code host cannot say whether the
119
+ * account that added the override can write, it removes the label, then
120
+ * rejects with the reason. */
121
+ export async function apply(o) {
122
+ const { eventName, event, pulls, log } = o;
116
123
  // Read the pull request as it is now. The event's copy can be stale: a
117
124
  // "marked ready" event sent just after a push carries the previous commit.
118
125
  let number;
@@ -120,7 +127,7 @@ async function main() {
120
127
  const reviewed = event.workflow_run.head_sha;
121
128
  const open = (await pulls.forCommit(reviewed)).find((p) => p.state === "open");
122
129
  if (!open)
123
- return console.log(`No open pull request has ${reviewed}.`);
130
+ return log(`No open pull request has ${reviewed}.`);
124
131
  number = open.number;
125
132
  }
126
133
  else {
@@ -132,8 +139,18 @@ async function main() {
132
139
  const comments = await pulls.comments(pr.number);
133
140
  if (eventName === "workflow_run" &&
134
141
  !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.`);
142
+ return log(`${sha} is waiting for its own review.`);
136
143
  }
144
+ let senderIsApprover;
145
+ let lookupFailure;
146
+ if (event.action === "labeled" && event.label?.name === OVERRIDE)
147
+ try {
148
+ senderIsApprover = await pulls.canWrite(event.sender.login);
149
+ }
150
+ catch (error) {
151
+ senderIsApprover = false;
152
+ lookupFailure = error ?? new Error("The access lookup failed.");
153
+ }
137
154
  const decision = decide({
138
155
  event: eventName,
139
156
  action: event.action,
@@ -141,21 +158,29 @@ async function main() {
141
158
  isDependabot: pr.author === "dependabot[bot]",
142
159
  isDraft: pr.isDraft,
143
160
  hasOverride: labels.includes(OVERRIDE),
144
- senderIsOwner: event.sender?.login === event.repository?.owner?.login,
161
+ senderIsApprover,
162
+ senderUnchecked: lookupFailure !== undefined,
145
163
  runConclusion: event.workflow_run?.conclusion,
146
164
  verdict: verdictIn(comments, sha),
147
165
  });
148
166
  if (!decision)
149
- return console.log("Nothing to post.");
167
+ return log("Nothing to post.");
150
168
  await pulls.setStatus(sha, {
151
169
  state: decision.state,
152
170
  name: CONTEXT,
153
171
  description: decision.description,
154
- link: openRunner(repo).thisRun(process.env)?.page,
172
+ link: o.link,
155
173
  });
156
- console.log(`${CONTEXT} on ${sha}: ${decision.state}, ${decision.description}`);
174
+ log(`${CONTEXT} on ${sha}: ${decision.state}, ${decision.description}`);
157
175
  if (decision.removeOverride)
158
176
  await pulls.removeLabel(pr.number, OVERRIDE);
177
+ const who = event.sender?.login;
178
+ if (decision.explainRemoval === "not an approver")
179
+ await pulls.comment(pr.number, `Removed \`${OVERRIDE}\`: @${who} cannot write to this repository, and only an account that can may pass the verdict.`);
180
+ if (decision.explainRemoval === "could not check") {
181
+ await pulls.comment(pr.number, `Removed \`${OVERRIDE}\`: could not check whether @${who} can write to this repository. Add the label again to retry.`);
182
+ throw lookupFailure;
183
+ }
159
184
  if (decision.announceOverride) {
160
185
  const open = await pulls.openThreadCount(pr.number);
161
186
  await pulls.comment(pr.number, `\`${CONTEXT}\` overridden by @${event.sender.login} at ${sha.slice(0, 7)}. ` +
@@ -166,6 +191,19 @@ async function main() {
166
191
  // Only run as a CLI. Importing this module for tests must not call GitHub.
167
192
  /** `factory review verdict`. */
168
193
  export async function run() {
169
- await main();
170
- return 0;
194
+ const repo = process.env.GITHUB_REPOSITORY;
195
+ try {
196
+ await apply({
197
+ eventName: process.env.GITHUB_EVENT_NAME,
198
+ event: JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, "utf8")),
199
+ pulls: openCodeHost(repo),
200
+ link: openRunner(repo).thisRun(process.env)?.page,
201
+ log: (line) => console.log(line),
202
+ });
203
+ return 0;
204
+ }
205
+ catch (error) {
206
+ console.error(error instanceof Error ? error.message : String(error));
207
+ return 1;
208
+ }
171
209
  }
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { type Tickets } from "./tickets/types.mts";
2
+ import { type Key, type Tickets } from "./tickets/types.mts";
3
3
  import { type Clock } from "./lib/clock.mts";
4
4
  import { type ReviewerRun } from "./lib/work-status.mts";
5
5
  export type HookInput = {
@@ -12,7 +12,7 @@ export type HookInput = {
12
12
  /** What the hook remembers between its runs: the comment it posted, and the
13
13
  * rows it shows. */
14
14
  export type State = {
15
- commentId: number | null;
15
+ commentId: string | null;
16
16
  runs: ReviewerRun[];
17
17
  };
18
18
  export type Deps = {
@@ -24,8 +24,8 @@ export type Deps = {
24
24
  /** The text of a file, or null when it cannot be read. */
25
25
  readFile: (path: string) => string | null;
26
26
  state: {
27
- read: (session: string, issue: number) => State;
28
- write: (session: string, issue: number, state: State) => void;
27
+ read: (session: string, issue: Key) => State;
28
+ write: (session: string, issue: Key, state: State) => void;
29
29
  };
30
30
  /** Runs `work` while no other hook of this session edits the comment. */
31
31
  locked: <T>(session: string, work: () => Promise<T>) => Promise<T>;
@@ -50,5 +50,8 @@ export declare function resultText(run: ReviewerRun, now: Date): string;
50
50
  * note already includes what the reviewers spent. */
51
51
  export declare function commentFor(session: string, runs: ReviewerRun[], now: Date): string;
52
52
  export declare function main(event: string, input: HookInput, agentsDir: string, d: Deps): Promise<number>;
53
+ /** A state file's text as the state; none when there is no file or it
54
+ * cannot be read. */
55
+ export declare function parseState(text: string | null): State;
53
56
  /** `factory reviewers start|stop`, with the hook's input on stdin. */
54
57
  export declare function run(argv: string[]): Promise<number>;
@@ -234,11 +234,28 @@ export async function main(event, input, agentsDir, d) {
234
234
  catch (error) {
235
235
  const why = error instanceof Error ? error.message : String(error);
236
236
  d.out(JSON.stringify({
237
- systemMessage: `The ${reviewer} run was not recorded${issue === null ? "" : ` on #${issue}`}: ${why.split("\n")[0].slice(0, 200)}`,
237
+ systemMessage: `The ${reviewer} run was not recorded${issue === null ? "" : ` on ticket ${issue}`}: ${why.split("\n")[0].slice(0, 200)}`,
238
238
  }));
239
239
  }
240
240
  return 0;
241
241
  }
242
+ /** A state file's text as the state; none when there is no file or it
243
+ * cannot be read. */
244
+ export function parseState(text) {
245
+ try {
246
+ if (!text)
247
+ return { commentId: null, runs: [] };
248
+ const state = JSON.parse(text);
249
+ // State written before comment IDs were text holds a number.
250
+ return {
251
+ ...state,
252
+ commentId: state.commentId === null ? null : String(state.commentId),
253
+ };
254
+ }
255
+ catch {
256
+ return { commentId: null, runs: [] };
257
+ }
258
+ }
242
259
  const statePath = (session, issue) => join(commonDir(), `reviewer-runs-${session}-${issue}.json`);
243
260
  /** A lock directory beside the state, since reviewers run in parallel. One
244
261
  * older than a minute was left by a hook that died, and is taken over. */
@@ -293,17 +310,7 @@ export async function run(argv) {
293
310
  clock: readClock,
294
311
  readFile: read,
295
312
  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
- },
313
+ read: (session, issue) => parseState(read(statePath(session, issue))),
307
314
  write: (session, issue, state) => writeFileSync(statePath(session, issue), JSON.stringify(state)),
308
315
  },
309
316
  locked,
@@ -25,16 +25,15 @@ export function githubActionsRunner(o) {
25
25
  const reviewsOf = async (sha) => (await t.rest("GET", `${API}/actions/workflows/${REVIEW_WORKFLOW}/runs?head_sha=${sha}&per_page=5`)).workflow_runs;
26
26
  return {
27
27
  async startBuild(ticket, branch) {
28
- await t.rest("POST", `${API}/actions/workflows/${BUILD_WORKFLOW}/dispatches`, { fields: { ref: branch, inputs: { ticket: String(ticket) } } });
28
+ await t.rest("POST", `${API}/actions/workflows/${BUILD_WORKFLOW}/dispatches`, { fields: { ref: branch, inputs: { ticket } } });
29
29
  },
30
- // GitHub answers a dispatch with no run. The build workflow names each
31
- // run `Build #N`, and GitHub's times are whole seconds, so `since` is
32
- // rounded down to one.
33
- async findBuild(ticket, since) {
30
+ // GitHub answers a dispatch with no run, so the run is found by the
31
+ // name the build workflow gives it. GitHub's times are whole seconds, so
32
+ // `since` is rounded down to one.
33
+ async findBuild(runName, since) {
34
34
  const from = Math.floor(since / 1000) * 1000;
35
35
  const answer = await t.rest("GET", `${API}/actions/workflows/${BUILD_WORKFLOW}/runs?event=workflow_dispatch&per_page=30`);
36
- const found = answer.workflow_runs.find((r) => r.display_title === `Build #${ticket}` &&
37
- Date.parse(r.created_at) >= from);
36
+ const found = answer.workflow_runs.find((r) => r.display_title === runName && Date.parse(r.created_at) >= from);
38
37
  return found?.html_url ?? null;
39
38
  },
40
39
  buildsPage: () => `${SITE}/${o.repository}/actions/workflows/${BUILD_WORKFLOW}`,
@@ -1,3 +1,4 @@
1
+ import type { Key } from "../tickets/types.mts";
1
2
  /** One run of the repository's jobs for a commit. `status` is `completed`
2
3
  * once it has ended, and `conclusion` says how. */
3
4
  export type Run = {
@@ -26,12 +27,12 @@ export type FailedJob = {
26
27
  log: string;
27
28
  };
28
29
  export type Runner = {
29
- /** Starts a build of the ticket on the branch. The runner may answer
30
- * before the run exists, so `findBuild` finds it. */
31
- startBuild(ticket: number, branch: string): Promise<void>;
32
- /** The page of the ticket's build started at or after `since`, in
33
- * milliseconds, or null when none shows yet. */
34
- findBuild(ticket: number, since: number): Promise<string | null>;
30
+ /** Starts a build of the ticket, by its key, on the branch. The runner
31
+ * may answer before the run exists, so `findBuild` finds it. */
32
+ startBuild(ticket: Key, branch: string): Promise<void>;
33
+ /** The page of the build named `runName`, such as `Build #12`, started at
34
+ * or after `since`, in milliseconds, or null when none shows yet. */
35
+ findBuild(runName: string, since: number): Promise<string | null>;
35
36
  /** The page that lists builds. */
36
37
  buildsPage(): string;
37
38
  /** The page of a run, from its ID. */
@@ -0,0 +1,6 @@
1
+ import type { Run, SpecTool } from "./types.mts";
2
+ export type SpecTools = Record<string, SpecTool>;
3
+ export declare const runCommand: Run;
4
+ export declare function specTools(run?: Run): SpecTools;
5
+ /** Every built tool's process files, whichever tool the settings name. */
6
+ export declare function processFiles(tools?: SpecTools): string[];
@@ -0,0 +1,15 @@
1
+ // The spec tools the factory has built, by the name `specs` gives each.
2
+ import { spawnSync } from "node:child_process";
3
+ import { openspec } from "./openspec.mjs";
4
+ export const runCommand = (argv, cwd, env, quiet) => spawnSync(argv[0], argv.slice(1), {
5
+ cwd,
6
+ env: { npm_config_loglevel: "warn", ...process.env, ...env },
7
+ stdio: quiet ? "ignore" : ["ignore", "inherit", "inherit"],
8
+ }).status ?? 1;
9
+ export function specTools(run = runCommand) {
10
+ return { openspec: openspec(run) };
11
+ }
12
+ /** Every built tool's process files, whichever tool the settings name. */
13
+ export function processFiles(tools = specTools()) {
14
+ return Object.values(tools).flatMap((t) => [...t.processFiles]);
15
+ }
@@ -0,0 +1,2 @@
1
+ import type { Run, SpecTool } from "./types.mts";
2
+ export declare function openspec(run: Run): SpecTool;
@@ -0,0 +1,78 @@
1
+ // OpenSpec (https://github.com/Fission-AI/OpenSpec): a ticket's spec is a
2
+ // change under openspec/changes/, archived into openspec/specs/.
3
+ import { existsSync, readdirSync, readFileSync } from "node:fs";
4
+ import { join } from "node:path";
5
+ import { BUILT } from "../tool-names.mjs";
6
+ const PACKAGE = "@fission-ai/openspec";
7
+ const CHANGES = "openspec/changes";
8
+ const SPECS = "openspec/specs";
9
+ const ENV = { DO_NOT_TRACK: "1" };
10
+ const OPENSPEC = ["npx", "--no-install", "openspec"];
11
+ /** A change's name, from the ticket as the ticket system writes it. */
12
+ const changeOf = (id) => `issue-${id.toLowerCase()}`;
13
+ function listsPackage(root) {
14
+ try {
15
+ const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
16
+ return [pkg.dependencies, pkg.devDependencies].some((deps) => deps && typeof deps === "object" && PACKAGE in deps);
17
+ }
18
+ catch {
19
+ return false;
20
+ }
21
+ }
22
+ const folders = (dir) => existsSync(dir)
23
+ ? readdirSync(dir, { withFileTypes: true })
24
+ .filter((e) => e.isDirectory())
25
+ .map((e) => e.name)
26
+ : [];
27
+ export function openspec(run) {
28
+ return {
29
+ name: "OpenSpec",
30
+ label: "OpenSpec: each ticket holds its spec, and each build also keeps it in openspec/specs/",
31
+ install: {
32
+ package: PACKAGE,
33
+ via: "npm install --save-dev",
34
+ installed: listsPackage,
35
+ },
36
+ defaultCheck: BUILT.specs.openspec,
37
+ env: ENV,
38
+ processFiles: ["openspec/config.yaml"],
39
+ runs: (root) => run([...OPENSPEC, "--version"], root, ENV, true) === 0,
40
+ list: (root) => folders(join(root, SPECS))
41
+ .filter((name) => existsSync(join(root, SPECS, name, "spec.md")))
42
+ .sort()
43
+ .map((name) => ({ name, path: `${SPECS}/${name}/spec.md` })),
44
+ folder: (id) => `${CHANGES}/${changeOf(id)}/`,
45
+ started: (root, id) => existsSync(join(root, CHANGES, changeOf(id))),
46
+ start: (root, id) => run([...OPENSPEC, "new", "change", changeOf(id)], root, ENV, true),
47
+ files: (id, spec) => [
48
+ {
49
+ kind: "new",
50
+ path: "proposal.md",
51
+ what: `The owner's text and Decisions, linking ticket ${id}`,
52
+ },
53
+ {
54
+ kind: "new",
55
+ path: "specs/CAPABILITY/spec.md",
56
+ what: 'One per heading under Spec: ADDED for (new), MODIFIED for (modified), REMOVED for each "No longer" line; each numbered line is one requirement whose SHALL sentence restates it, with one scenario whose WHEN is the line\'s "When" clause and whose THEN is the rest',
57
+ },
58
+ ...(spec
59
+ ? [
60
+ {
61
+ kind: "new",
62
+ path: "design.md",
63
+ what: "Design, under For the builder",
64
+ },
65
+ {
66
+ kind: "new",
67
+ path: "tasks.md",
68
+ what: "Tasks, under For the builder",
69
+ },
70
+ ]
71
+ : []),
72
+ ],
73
+ then: "factory specs check",
74
+ finished: (root, id) => folders(join(root, CHANGES, "archive")).some((name) => name.endsWith(`-${changeOf(id)}`)),
75
+ finish: (root, id) => run([...OPENSPEC, "archive", changeOf(id), "--yes"], root, ENV, false),
76
+ foldsInto: `${SPECS}/`,
77
+ };
78
+ }
@@ -0,0 +1,53 @@
1
+ /** Runs a command from `cwd` with `env` added to the environment, and
2
+ * returns its exit status. A quiet run prints nothing; any other passes
3
+ * the command's output through. */
4
+ export type Run = (argv: string[], cwd: string, env: Record<string, string>, quiet: boolean) => number;
5
+ /** A file a build writes or updates from a ticket's body, and what goes in
6
+ * it. */
7
+ export type SpecFile = {
8
+ kind: "new" | "update";
9
+ path: string;
10
+ what: string;
11
+ };
12
+ export type SpecTool = {
13
+ /** Its name in init's messages, such as `OpenSpec`. */
14
+ name: string;
15
+ /** Its option in init's question. */
16
+ label: string;
17
+ install: {
18
+ /** What is installed, such as `@fission-ai/openspec`. */
19
+ package: string;
20
+ /** The command that installs it, without the package. */
21
+ via: string;
22
+ installed(root: string): boolean;
23
+ };
24
+ /** The check `specs.check` defaults to. */
25
+ defaultCheck: string;
26
+ /** Added to the environment of every command the tool runs. */
27
+ env: Record<string, string>;
28
+ /** Its files that never merge without the owner, from the root. */
29
+ processFiles: readonly string[];
30
+ /** Whether its command runs at the repository's root. */
31
+ runs(root: string): boolean;
32
+ /** Each spec it keeps, by name, with its file from the root. */
33
+ list(root: string): {
34
+ name: string;
35
+ path: string;
36
+ }[];
37
+ /** The folder ticket `id`'s spec is written in, ending in `/`. */
38
+ folder(id: string): string;
39
+ started(root: string, id: string): boolean;
40
+ /** Starts ticket `id`'s spec; its exit status. */
41
+ start(root: string, id: string): number;
42
+ /** The files to write, for a ticket with the `spec` label or without. */
43
+ files(id: string, spec: boolean): SpecFile[];
44
+ /** What to run once the files are written. */
45
+ then: string;
46
+ /** Whether ticket `id`'s spec is already folded in. */
47
+ finished(root: string, id: string): boolean;
48
+ /** Folds ticket `id`'s spec in, passing the tool's output through; its
49
+ * exit status. */
50
+ finish(root: string, id: string): number;
51
+ /** Where `finish` folds a spec, ending in `/`. */
52
+ foldsInto: string;
53
+ };
@@ -0,0 +1,4 @@
1
+ // What a spec tool gives the factory. Each tool is one adapter in this
2
+ // folder; `factory specs`, `factory init`, the settings check, and the merge
3
+ // policy reach a tool only through this type.
4
+ export {};
package/dist/status.d.mts CHANGED
@@ -1,11 +1,15 @@
1
1
  #!/usr/bin/env node
2
2
  import { type Settings, type Target } from "./config.mts";
3
3
  import { type Columns, type Watch, type Board, type Derived, type PullRequest, type Issue, type RepoSnapshot, type ReviewerRun } from "./lib/work-status.mts";
4
- import { type Tickets } from "./tickets/types.mts";
4
+ import { type Key, type Tickets } from "./tickets/types.mts";
5
5
  import { type CodeHost } from "./code-host/index.mts";
6
6
  import { type Runner } from "./runner/index.mts";
7
7
  export type Row = {
8
- number: number;
8
+ /** A ticket's key, or a pull request's number. */
9
+ key: string;
10
+ /** How it is written: the ticket system's form, or `#N` for a pull
11
+ * request. */
12
+ name: string;
9
13
  kind: "issue" | "pull";
10
14
  title: string;
11
15
  derived: Derived | null;
@@ -26,17 +30,21 @@ export declare function age(since: string | null, now: Date): string;
26
30
  export declare function isWatching(body: string, now: Date): boolean;
27
31
  /** One row per open issue, and one per open pull request that closes no
28
32
  * issue and builds no part of the follow-ups, such as Dependabot's. */
29
- export declare function toRows(snapshot: RepoSnapshot, board: Board, blockers: Map<number, number[]>, now: Date,
30
- /** What starts builds from the board, so that a card left in Ready is
31
- * worth flagging; null when builds.trigger is manual. */
32
- watch?: Watch | null, columns?: Columns): {
33
+ export declare function toRows(snapshot: RepoSnapshot, board: Board, blockers: Map<Key, Key[]>, now: Date, options: {
34
+ /** What starts builds from the board, so that a card left in Ready is
35
+ * worth flagging; null when builds.trigger is manual. */
36
+ watch?: Watch | null;
37
+ columns?: Columns;
38
+ /** How the ticket system writes a ticket. */
39
+ ref: (key: Key) => string;
40
+ }): {
33
41
  rows: Row[];
34
42
  closed: Row[];
35
43
  };
36
44
  /** Where a ticket's number, a pull request's number, and an Actions run's
37
45
  * ID each lead. */
38
46
  export type Links = {
39
- ticket: (n: number) => string;
47
+ ticket: (key: Key) => string;
40
48
  pull: (n: number) => string;
41
49
  run: (id: string) => string;
42
50
  };
@@ -75,6 +83,8 @@ export type Source = {
75
83
  tickets: Tickets;
76
84
  pulls: Pick<CodeHost, "open" | "address">;
77
85
  runner: Pick<Runner, "runPage">;
86
+ /** Whether the code host's own links count (`lib/pull-tickets.mts`). */
87
+ own: boolean;
78
88
  };
79
89
  export type Deps = {
80
90
  /** The ticket system and pull requests for the target. */