@davidbyoung/software-factory 0.1.10 → 0.1.11

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 (51) hide show
  1. package/agents/factory-ticket-readiness.md +20 -15
  2. package/dist/board.d.mts +1 -1
  3. package/dist/board.mjs +3 -4
  4. package/dist/cli.mjs +17 -4
  5. package/dist/code-host/github.mjs +2 -0
  6. package/dist/code-host/types.d.mts +4 -0
  7. package/dist/commands.d.mts +7 -2
  8. package/dist/commands.mjs +86 -16
  9. package/dist/config.d.mts +3 -4
  10. package/dist/config.mjs +7 -8
  11. package/dist/init.d.mts +11 -0
  12. package/dist/init.mjs +56 -1
  13. package/dist/lib/work-status.d.mts +5 -5
  14. package/dist/lib/work-status.mjs +7 -8
  15. package/dist/merge-policy.mjs +7 -3
  16. package/dist/pr.d.mts +8 -6
  17. package/dist/pr.mjs +39 -22
  18. package/dist/review-verdict.d.mts +22 -4
  19. package/dist/review-verdict.mjs +55 -17
  20. package/dist/specs/index.d.mts +6 -0
  21. package/dist/specs/index.mjs +15 -0
  22. package/dist/specs/openspec.d.mts +2 -0
  23. package/dist/specs/openspec.mjs +78 -0
  24. package/dist/specs/types.d.mts +53 -0
  25. package/dist/specs/types.mjs +4 -0
  26. package/dist/ticket.d.mts +3 -1
  27. package/dist/ticket.mjs +36 -3
  28. package/dist/tickets/github-access.d.mts +5 -0
  29. package/dist/tickets/github-access.mjs +22 -0
  30. package/dist/tickets/github.mjs +2 -0
  31. package/dist/tickets/types.d.mts +4 -0
  32. package/dist/tool-names.d.mts +2 -0
  33. package/dist/tool-names.mjs +3 -0
  34. package/dist/tools.d.mts +2 -0
  35. package/dist/tools.mjs +3 -0
  36. package/docs/builds.md +4 -1
  37. package/docs/cli.md +19 -4
  38. package/docs/configuration.md +50 -38
  39. package/docs/developing.md +104 -59
  40. package/docs/existing-repo.md +4 -3
  41. package/docs/github/setup.md +20 -3
  42. package/docs/glossary.md +7 -6
  43. package/docs/limitations.md +8 -5
  44. package/docs/updating.md +18 -0
  45. package/docs/workflow.md +25 -8
  46. package/package.json +1 -1
  47. package/rules.md +36 -30
  48. package/skills/factory-address-review/SKILL.md +40 -39
  49. package/skills/factory-build/SKILL.md +46 -53
  50. package/skills/factory-refine/SKILL.md +30 -22
  51. package/skills/factory-resolve-conflicts/SKILL.md +8 -7
package/dist/pr.d.mts CHANGED
@@ -19,7 +19,9 @@ export type Deps = {
19
19
  export declare function withAgentMark(body: string): string;
20
20
  export type Report = {
21
21
  pull: Pull;
22
- ownerLogin: string;
22
+ /** The authors among the reviews and the threads' last comments who can
23
+ * write to the repository. */
24
+ approvers: string[];
23
25
  reviewRun: {
24
26
  status: string;
25
27
  conclusion: string | null;
@@ -30,10 +32,10 @@ export type Report = {
30
32
  threads: Thread[];
31
33
  checks: Check[];
32
34
  };
33
- /** The owner's review bodies still to answer: submitted after the last
35
+ /** An approver's review bodies still to answer: submitted after the last
34
36
  * conversation comment carrying the agent mark, a sweep's own comments
35
37
  * aside. */
36
- export declare function ownerReviewsToWork(r: Report): Review[];
38
+ export declare function approverReviewsToWork(r: Report): Review[];
37
39
  /** A review is coming for this head only on a pull request the Claude review
38
40
  * workflow runs on. */
39
41
  export declare function reviewExpected(pull: Pull): boolean;
@@ -44,11 +46,11 @@ export declare function newestRuns(runs: Run[]): Run[];
44
46
  /** A conversation comment as `pr comments` lists it: ID, author, time, and
45
47
  * its first line. */
46
48
  export declare function commentLine(c: PullComment): string;
47
- /** Whether the owner's review has something in it to work, and if not,
48
- * why: "closed", "someone else's review", or "the factory's own reply". An
49
+ /** Whether an approver's review has something in it to work, and if not,
50
+ * why: "closed", "not an approver's", or "the factory's own reply". An
49
51
  * empty body counts for nothing, since the factory's reply is a review with
50
52
  * an empty body and one comment carrying the marker. */
51
- export declare function reviewPending(p: CodeHost, pr: number, reviewId: number, owner: string): Promise<{
53
+ export declare function reviewPending(p: CodeHost, pr: number, reviewId: number): Promise<{
52
54
  pending: true;
53
55
  } | {
54
56
  pending: false;
package/dist/pr.mjs CHANGED
@@ -8,11 +8,12 @@
8
8
  // npx --no-install factory pr ready N # refuses an unverified commit when git signs
9
9
  // npx --no-install factory pr closes N # issues the pull request closes
10
10
  // npx --no-install factory pr wait-checks N # every check on HEAD
11
- // npx --no-install factory pr review-pending N REVIEW # exits 0 when the owner's review needs an answer
11
+ // npx --no-install factory pr review-pending N REVIEW # exits 0 when an approver's review needs an answer
12
12
  // npx --no-install factory pr conflicts # the pull requests the conflict sweep takes
13
13
  // npx --no-install factory pr open --title TITLE --body-file FILE [--base BRANCH] [--ready]
14
14
  // npx --no-install factory pr view N --field FIELD # one field of a pull request
15
15
  // npx --no-install factory pr review N REVIEW # a review's author, body, and line comments
16
+ // npx --no-install factory pr comments N [--from-approvers] # conversation comments, or only an approver's
16
17
  // npx --no-install factory pr unverified N # the commits not shown as signed
17
18
  // npx --no-install factory pr failed N # each failed job's log, and a failed check's own report
18
19
  // npx --no-install factory pr review-again N # a fresh review of the same commit
@@ -36,16 +37,16 @@ export function withAgentMark(body) {
36
37
  : `${body.trimEnd()}\n\n${AGENT_MARK}`;
37
38
  }
38
39
  const SKIP_AS_LAST = /<!-- (conflict-fix|session-handoff) -->|conflict-stop/;
39
- /** The owner's review bodies still to answer: submitted after the last
40
+ /** An approver's review bodies still to answer: submitted after the last
40
41
  * conversation comment carrying the agent mark, a sweep's own comments
41
42
  * aside. */
42
- export function ownerReviewsToWork(r) {
43
+ export function approverReviewsToWork(r) {
43
44
  const answered = r.conversation
44
45
  .filter((c) => c.body.includes(AGENT_MARK) && !SKIP_AS_LAST.test(c.body))
45
46
  .map((c) => c.createdAt)
46
47
  .sort()
47
48
  .at(-1);
48
- return r.reviews.filter((review) => review.author === r.ownerLogin &&
49
+ return r.reviews.filter((review) => r.approvers.includes(review.author) &&
49
50
  review.body.trim() !== "" &&
50
51
  !review.body.includes(AGENT_MARK) &&
51
52
  (!answered || review.submittedAt > answered));
@@ -87,16 +88,18 @@ export function formatReport(r) {
87
88
  }
88
89
  else
89
90
  lines.push("summary: none for this head");
90
- const owner = ownerReviewsToWork(r);
91
- lines.push(`owner review bodies to answer: ${owner.length}`);
92
- for (const review of owner)
91
+ const toAnswer = approverReviewsToWork(r);
92
+ lines.push(`approver review bodies to answer: ${toAnswer.length}`);
93
+ for (const review of toAnswer)
93
94
  lines.push(` - review ${review.id} at ${review.submittedAt}: ${firstLine(review.body)}`);
94
95
  const open = r.threads.filter((t) => !t.isResolved);
95
96
  lines.push(`unresolved threads: ${open.length}`);
96
97
  for (const t of open) {
97
98
  const last = t.comments.at(-1);
98
- const ownerTurn = last?.author === r.ownerLogin && !last.body.includes(AGENT_MARK);
99
- lines.push(` - ${t.commentId} on ${t.path}:${t.line ?? "?"}${t.isOutdated ? " (outdated)" : ""} by ${t.comments[0]?.author ?? "?"}${ownerTurn ? ", owner's turn" : ""}: ${firstLine(t.comments[0]?.body ?? "")}`);
99
+ const approverTurn = last !== undefined &&
100
+ r.approvers.includes(last.author) &&
101
+ !last.body.includes(AGENT_MARK);
102
+ lines.push(` - ${t.commentId} on ${t.path}:${t.line ?? "?"}${t.isOutdated ? " (outdated)" : ""} by ${t.comments[0]?.author ?? "?"}${approverTurn ? ", approver's turn" : ""}: ${firstLine(t.comments[0]?.body ?? "")}`);
100
103
  }
101
104
  lines.push("checks:");
102
105
  if (r.checks.length === 0)
@@ -117,6 +120,13 @@ async function readPull(p, pr, d) {
117
120
  await d.sleep(10_000);
118
121
  }
119
122
  }
123
+ /** The distinct names among `authors` that can write to the repository,
124
+ * asking the code host once for each. Rejects when it cannot say. */
125
+ async function writers(p, authors) {
126
+ const distinct = [...new Set(authors)];
127
+ const can = await Promise.all(distinct.map((a) => p.canWrite(a)));
128
+ return distinct.filter((_, i) => can[i]);
129
+ }
120
130
  async function readReport(p, pr, d) {
121
131
  const pull = await readPull(p, pr, d);
122
132
  const sha = pull.head.sha;
@@ -132,10 +142,15 @@ async function readReport(p, pr, d) {
132
142
  .filter((c) => c.author === "github-actions[bot]" &&
133
143
  c.body.includes(`claude-review sha=${sha}`))
134
144
  .at(-1) ?? null;
145
+ const authors = [
146
+ ...reviews.map((review) => review.author),
147
+ ...threads
148
+ .filter((t) => !t.isResolved)
149
+ .flatMap((t) => t.comments.at(-1)?.author ?? []),
150
+ ];
135
151
  return {
136
152
  pull,
137
- // The owner is the part of the repository before the slash.
138
- ownerLogin: d.repository.split("/")[0],
153
+ approvers: await writers(p, authors),
139
154
  reviewRun: runs[0] ?? null,
140
155
  summary,
141
156
  conversation,
@@ -210,7 +225,7 @@ const FIELDS = {
210
225
  };
211
226
  /** How many lines of a failed job's log `failed` prints, from its end. */
212
227
  const LOG_TAIL = 200;
213
- const USAGE = `Usage: npx --no-install factory pr state [N] [--wait] | threads N [--all] | reply N COMMENT_ID --body-file FILE | resolve N COMMENT_ID | ready N | closes N | for-branch BRANCH | wait-checks N | comments N [--author LOGIN] [--contains TEXT] [--json] | comment N --body-file FILE | comment-view ID | label N --add LABEL | --remove LABEL | review-pending N REVIEW | conflicts | open --title TITLE --body-file FILE [--base BRANCH] [--ready] | view N --field ${Object.keys(FIELDS).join("|")} | review N REVIEW | unverified N | uncovered [BASE] [LCOV] | failed N | review-again N`;
228
+ const USAGE = `Usage: npx --no-install factory pr state [N] [--wait] | threads N [--all] | reply N COMMENT_ID --body-file FILE | resolve N COMMENT_ID | ready N | closes N | for-branch BRANCH | wait-checks N | comments N [--author LOGIN] [--contains TEXT] [--from-approvers] [--json] | comment N --body-file FILE | comment-view ID | label N --add LABEL | --remove LABEL | review-pending N REVIEW | conflicts | open --title TITLE --body-file FILE [--base BRANCH] [--ready] | view N --field ${Object.keys(FIELDS).join("|")} | review N REVIEW | unverified N | uncovered [BASE] [LCOV] | failed N | review-again N`;
214
229
  function option(args, name) {
215
230
  const at = args.indexOf(name);
216
231
  if (at === -1)
@@ -243,11 +258,11 @@ function gitSigns(d) {
243
258
  return false;
244
259
  }
245
260
  }
246
- /** Whether the owner's review has something in it to work, and if not,
247
- * why: "closed", "someone else's review", or "the factory's own reply". An
261
+ /** Whether an approver's review has something in it to work, and if not,
262
+ * why: "closed", "not an approver's", or "the factory's own reply". An
248
263
  * empty body counts for nothing, since the factory's reply is a review with
249
264
  * an empty body and one comment carrying the marker. */
250
- export async function reviewPending(p, pr, reviewId, owner) {
265
+ export async function reviewPending(p, pr, reviewId) {
251
266
  const pull = await p.get(pr);
252
267
  if (pull.state !== "open")
253
268
  return {
@@ -257,8 +272,8 @@ export async function reviewPending(p, pr, reviewId, owner) {
257
272
  const review = (await p.reviews(pr)).find((r) => r.id === reviewId);
258
273
  if (!review)
259
274
  throw new Error(`No review ${reviewId} on #${pr}.`);
260
- if (review.author !== owner)
261
- return { pending: false, why: `review ${reviewId} is someone else's` };
275
+ if (!(await p.canWrite(review.author)))
276
+ return { pending: false, why: `review ${reviewId} is not an approver's` };
262
277
  const { body } = review;
263
278
  if (body.trim() !== "" && !body.includes(AGENT_MARK))
264
279
  return { pending: true };
@@ -267,7 +282,7 @@ export async function reviewPending(p, pr, reviewId, owner) {
267
282
  return { pending: true };
268
283
  return {
269
284
  pending: false,
270
- why: `review ${reviewId} is the factory's own reply: nothing of the owner's in it`,
285
+ why: `review ${reviewId} is the factory's own reply: nothing of an approver's in it`,
271
286
  };
272
287
  }
273
288
  const CONFLICT_READS = 5;
@@ -394,9 +409,7 @@ export async function main(argv, d) {
394
409
  const [pr, review] = numbers;
395
410
  if (!pr || !review)
396
411
  throw new Error(USAGE);
397
- const result = await reviewPending(p, pr, review,
398
- // The owner is the part of the repository before the slash.
399
- d.repository.split("/")[0]);
412
+ const result = await reviewPending(p, pr, review);
400
413
  if (result.pending) {
401
414
  d.out("pending");
402
415
  return 0;
@@ -419,8 +432,12 @@ export async function main(argv, d) {
419
432
  throw new Error(USAGE);
420
433
  const author = option(rest, "--author");
421
434
  const contains = option(rest, "--contains");
422
- const kept = (await p.comments(pr)).filter((c) => (author === undefined || c.author === author) &&
435
+ let kept = (await p.comments(pr)).filter((c) => (author === undefined || c.author === author) &&
423
436
  (contains === undefined || c.body.includes(contains)));
437
+ if (rest.includes("--from-approvers")) {
438
+ const can = await writers(p, kept.map((c) => c.author));
439
+ kept = kept.filter((c) => can.includes(c.author));
440
+ }
424
441
  if (rest.includes("--json"))
425
442
  d.out(JSON.stringify(kept.map(inGithubNames), null, 2));
426
443
  else
@@ -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
  }
@@ -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/ticket.d.mts CHANGED
@@ -4,7 +4,7 @@ import { type Settings } from "./config.mts";
4
4
  import { type IssueComment, type PullRequest } from "./lib/work-status.mts";
5
5
  import { type Clock } from "./lib/clock.mts";
6
6
  import type { Measured } from "./lib/usage.mts";
7
- import { type Ticket, type Tickets } from "./tickets/types.mts";
7
+ import { type Ticket, type TicketComment, type Tickets } from "./tickets/types.mts";
8
8
  /** The ticket system this session reaches. */
9
9
  export type Opened = {
10
10
  tickets: Tickets;
@@ -59,6 +59,8 @@ export declare function withLine(body: string, line: string): string;
59
59
  /** A ticket for a reader: title, state, labels, body, and each comment with
60
60
  * its ID and author. */
61
61
  export declare function formatTicket(t: Ticket): string[];
62
+ /** One comment as `view` prints it: a line naming it, then its body. */
63
+ export declare function formatComment(c: TicketComment): string[];
62
64
  export declare function main(argv: string[], deps: Deps): Promise<number>;
63
65
  /** `factory ticket ...` and `factory follow-up ...`. */
64
66
  export declare function run(argv: string[]): Promise<number>;
package/dist/ticket.mjs CHANGED
@@ -17,6 +17,7 @@
17
17
  // (`tickets/`), so no skill calls a ticket system itself:
18
18
  //
19
19
  // factory ticket view N [--field title|state|labels|body] [--json]
20
+ // factory ticket answers N # the comments that count as answers
20
21
  // factory ticket list [--label LABEL] [--title "TITLE"] [--json]
21
22
  // factory ticket edit N [--title TITLE] [--body-file FILE [--attach FILE]...]
22
23
  // factory ticket comment N --body-file FILE [--attach FILE]...
@@ -59,7 +60,7 @@ import { sessionIdentity } from "./lib/gh.mjs";
59
60
  import { openCodeHost } from "./code-host/index.mjs";
60
61
  import { openRunner } from "./runner/index.mjs";
61
62
  import { loadSettings, targetOf } from "./config.mjs";
62
- import { commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
63
+ import { AGENT_MARK, commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
63
64
  import { missingParts } from "./lib/refined-check.mjs";
64
65
  import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
65
66
  import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
@@ -281,12 +282,32 @@ export function formatTicket(t) {
281
282
  t.body.trimEnd() || "(no body)",
282
283
  ];
283
284
  for (const c of t.comments)
284
- lines.push("", `--- comment ${c.id} by ${c.author} at ${c.createdAt}`, c.body.trimEnd());
285
+ lines.push("", ...formatComment(c));
285
286
  return lines;
286
287
  }
288
+ /** One comment as `view` prints it: a line naming it, then its body. */
289
+ export function formatComment(c) {
290
+ return [
291
+ `--- comment ${c.id} by ${c.author} at ${c.createdAt}`,
292
+ c.body.trimEnd(),
293
+ ];
294
+ }
295
+ /** The comments on a ticket that count as answers: by someone the ticket
296
+ * system says may decide, without the agent mark, oldest first. Asks once
297
+ * for each distinct author. */
298
+ async function answersOf(t, ticket) {
299
+ const unmarked = ticket.comments.filter((c) => !c.body.includes(AGENT_MARK));
300
+ const authors = [...new Set(unmarked.map((c) => c.author))];
301
+ const may = await Promise.all(authors.map((a) => t.mayDecide(a)));
302
+ const deciders = new Set(authors.filter((_, i) => may[i]));
303
+ return unmarked
304
+ .filter((c) => deciders.has(c.author))
305
+ .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
306
+ }
287
307
  const FIELDS = ["title", "state", "labels", "body"];
288
308
  const READS_AND_WRITES = new Set([
289
309
  "view",
310
+ "answers",
290
311
  "list",
291
312
  "edit",
292
313
  "comment",
@@ -342,6 +363,18 @@ async function ticketCommand(command, args, d) {
342
363
  d.out(String(ticket[field]));
343
364
  return 0;
344
365
  }
366
+ case "answers": {
367
+ const ticket = await t.read(numbered());
368
+ const answers = await answersOf(t, ticket);
369
+ if (answers.length === 0)
370
+ d.out(`#${ticket.number} has no answers from an approver yet.`);
371
+ answers.forEach((c, i) => {
372
+ if (i > 0)
373
+ d.out("");
374
+ formatComment(c).forEach(d.out);
375
+ });
376
+ return 0;
377
+ }
345
378
  case "list": {
346
379
  const label = option(args, "--label");
347
380
  const title = option(args, "--title");
@@ -460,7 +493,7 @@ async function ticketCommand(command, args, d) {
460
493
  return null;
461
494
  }
462
495
  }
463
- const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
496
+ const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|answers|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
464
497
  export async function main(argv, deps) {
465
498
  const [command, first, ...rest] = argv;
466
499
  const issue = Number(first);
@@ -0,0 +1,5 @@
1
+ import { type Transport } from "./transport.mts";
2
+ /** Whether `login` can write to `repository` (owner/name), counting every
3
+ * grant: repository, team, organization, and enterprise. Rejects when
4
+ * GitHub cannot say, so a failed lookup is never read as "yes". */
5
+ export declare function writeAccess(t: Transport, repository: string, login: string): Promise<boolean>;