@davidbyoung/software-factory 0.1.11 → 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 (56) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ui-reviewer.md +2 -2
  4. package/dist/board.d.mts +7 -7
  5. package/dist/board.mjs +50 -33
  6. package/dist/build.d.mts +4 -0
  7. package/dist/build.mjs +9 -4
  8. package/dist/cli.mjs +8 -1
  9. package/dist/code-host/github.mjs +9 -4
  10. package/dist/code-host/types.d.mts +4 -2
  11. package/dist/commands.d.mts +1 -1
  12. package/dist/commands.mjs +15 -6
  13. package/dist/lib/clock.d.mts +3 -1
  14. package/dist/lib/clock.mjs +12 -6
  15. package/dist/lib/pull-tickets.d.mts +15 -0
  16. package/dist/lib/pull-tickets.mjs +12 -0
  17. package/dist/lib/usage.d.mts +3 -1
  18. package/dist/lib/usage.mjs +4 -2
  19. package/dist/lib/work-status.d.mts +23 -19
  20. package/dist/lib/work-status.mjs +14 -27
  21. package/dist/poller.d.mts +3 -3
  22. package/dist/poller.mjs +18 -14
  23. package/dist/pr.d.mts +18 -0
  24. package/dist/pr.mjs +54 -7
  25. package/dist/review-tickets.d.mts +12 -0
  26. package/dist/review-tickets.mjs +59 -0
  27. package/dist/reviewers.d.mts +7 -4
  28. package/dist/reviewers.mjs +19 -12
  29. package/dist/runner/github-actions.mjs +6 -7
  30. package/dist/runner/types.d.mts +7 -6
  31. package/dist/status.d.mts +17 -7
  32. package/dist/status.mjs +35 -23
  33. package/dist/sync.d.mts +4 -0
  34. package/dist/sync.mjs +14 -1
  35. package/dist/ticket.d.mts +13 -7
  36. package/dist/ticket.mjs +94 -60
  37. package/dist/tickets/github.d.mts +10 -2
  38. package/dist/tickets/github.mjs +74 -20
  39. package/dist/tickets/index.d.mts +7 -1
  40. package/dist/tickets/index.mjs +15 -1
  41. package/dist/tickets/types.d.mts +59 -30
  42. package/dist/tickets/types.mjs +13 -3
  43. package/docs/cli.md +11 -7
  44. package/docs/configuration.md +1 -1
  45. package/docs/developing.md +16 -8
  46. package/docs/github/reference.md +1 -1
  47. package/docs/plugins.md +6 -6
  48. package/package.json +1 -1
  49. package/review.md +11 -11
  50. package/rules.md +18 -14
  51. package/skills/factory-address-review/SKILL.md +4 -3
  52. package/skills/factory-build/SKILL.md +25 -19
  53. package/skills/factory-refine/SKILL.md +1 -1
  54. package/skills/factory-resolve-conflicts/SKILL.md +4 -3
  55. package/workflows/factory-build.yml +6 -5
  56. package/workflows/factory-claude-review.yml +38 -1
@@ -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. */
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. */
package/dist/status.mjs CHANGED
@@ -15,8 +15,9 @@ import { colorOn, painter } from "./lib/color.mjs";
15
15
  import { setTimeout as sleep } from "node:timers/promises";
16
16
  import { NO_DEPENDENCIES, SettingsError, loadSettings, targetOf, } from "./config.mjs";
17
17
  import { appSessionLink } from "./lib/gh.mjs";
18
- import { DEFAULT_COLUMNS, cardOf, derive, isNotStarted, watchOf, isStale, isStuck, actionsRunLink, buildsPartOf, markedComments, parseRuns, toSnapshot, } from "./lib/work-status.mjs";
18
+ import { DEFAULT_COLUMNS, cardOf, derive, isNotStarted, watchOf, isStale, isStuck, actionsRunLink, markedComments, parseRuns, toSnapshot, } from "./lib/work-status.mjs";
19
19
  import { boardOf, readAll } from "./tickets/types.mjs";
20
+ import { linkPulls, ownLinks } from "./lib/pull-tickets.mjs";
20
21
  import { openTickets } from "./tickets/index.mjs";
21
22
  import { openCodeHost } from "./code-host/index.mjs";
22
23
  import { openRunner } from "./runner/index.mjs";
@@ -66,50 +67,51 @@ export function isWatching(body, now) {
66
67
  }
67
68
  /** One row per open issue, and one per open pull request that closes no
68
69
  * issue and builds no part of the follow-ups, such as Dependabot's. */
69
- export function toRows(snapshot, board, blockers, now,
70
- /** What starts builds from the board, so that a card left in Ready is
71
- * worth flagging; null when builds.trigger is manual. */
72
- watch = watchOf("own-server", 5), columns = DEFAULT_COLUMNS) {
70
+ export function toRows(snapshot, board, blockers, now, options) {
71
+ const watch = options.watch === undefined ? watchOf("own-server", 5) : options.watch;
72
+ const columns = options.columns ?? DEFAULT_COLUMNS;
73
73
  const rows = [];
74
74
  const closed = [];
75
75
  const claimed = new Set();
76
76
  for (const issue of snapshot.issues) {
77
- const derived = derive(issue, cardOf(board, issue.number, columns), snapshot.pulls, columns);
77
+ const derived = derive(issue, cardOf(board, issue.key, columns), snapshot.pulls, columns);
78
78
  const pulls = snapshot.pulls.filter((p) => derived.pulls.includes(p.number));
79
79
  pulls.forEach((p) => claimed.add(p.number));
80
80
  const flags = [];
81
81
  if (isStale(derived, now))
82
82
  flags.push("stale");
83
83
  if (watch &&
84
- isNotStarted(derived, blockers.get(issue.number) ?? [], now, watch.minutes))
84
+ isNotStarted(derived, blockers.get(issue.key) ?? [], now, watch.minutes))
85
85
  flags.push(watch.flag);
86
86
  const row = {
87
- number: issue.number,
87
+ key: issue.key,
88
+ name: options.ref(issue.key),
88
89
  kind: "issue",
89
90
  title: issue.title,
90
91
  derived,
91
92
  pulls,
92
93
  runs: cardRuns(issue, derived),
93
94
  flags,
94
- cost: board.items.get(issue.number)?.cost ?? null,
95
+ cost: board.items.get(issue.key)?.cost ?? null,
95
96
  };
96
97
  (derived.status === "Done" ? closed : rows).push(row);
97
98
  }
98
99
  for (const pull of snapshot.pulls) {
99
100
  if (claimed.has(pull.number))
100
101
  continue;
101
- const followUps = snapshot.issues.filter((i) => i.labels.includes("follow-up") && buildsPartOf(pull.body, i.number));
102
+ const followUps = snapshot.issues.filter((i) => i.labels.includes("follow-up") && pull.partOf.includes(i.key));
102
103
  if (pull.closes.length > 0 || followUps.length > 0)
103
104
  continue;
104
105
  rows.push({
105
- number: pull.number,
106
+ key: String(pull.number),
107
+ name: `#${pull.number}`,
106
108
  kind: "pull",
107
109
  title: `pull request by ${pull.author}`,
108
110
  derived: null,
109
111
  pulls: [pull],
110
112
  runs: [],
111
113
  flags: [],
112
- cost: board.items.get(pull.number)?.cost ?? null,
114
+ cost: null,
113
115
  });
114
116
  }
115
117
  return { rows, closed };
@@ -133,7 +135,9 @@ const INDENT = " ";
133
135
  const GAP = " ";
134
136
  const MIN_TITLE = 20;
135
137
  const HEADER = ["#", "Title", "Time in status", "Cost", "Session"];
136
- const linkTo = (kind, style, n) => style.links?.[kind](n);
138
+ const linkTo = (row, style) => row.kind === "issue"
139
+ ? style.links?.ticket(row.key)
140
+ : style.links?.pull(Number(row.key));
137
141
  const width = (segs) => segs.reduce((n, s) => n + [...s.text].length, 0);
138
142
  function paint(text, style, ...codes) {
139
143
  if (!style.color || codes.length === 0)
@@ -189,7 +193,10 @@ function pullLine(pull, now, named, style) {
189
193
  return named
190
194
  ? [
191
195
  { text: "↳ Pull request " },
192
- { text: `#${pull.number}`, url: linkTo("pull", style, pull.number) },
196
+ {
197
+ text: `#${pull.number}`,
198
+ url: linkTo({ kind: "pull", key: String(pull.number) }, style),
199
+ },
193
200
  { text: ` · ${rest}` },
194
201
  ]
195
202
  : [{ text: `↳ ${rest}` }];
@@ -259,10 +266,10 @@ export function formatRows({ rows, closed }, now, withClosed = true, style = PLA
259
266
  lines.push("Nothing open.");
260
267
  else {
261
268
  const cells = rows.map((row) => {
262
- const url = linkTo(row.kind === "issue" ? "ticket" : "pull", style, row.number);
269
+ const url = linkTo(row, style);
263
270
  return {
264
271
  row,
265
- number: `#${row.number}`,
272
+ number: row.name,
266
273
  url,
267
274
  time: age(row.derived?.since ?? null, now),
268
275
  // Read from the board, never summed here, so it matches the card.
@@ -359,8 +366,8 @@ export function formatRows({ rows, closed }, now, withClosed = true, style = PLA
359
366
  lines.push("", `${paint("Closed in the last 24 hours:", style, "dim")} ${closed
360
367
  .map((r) => paint(render([
361
368
  {
362
- text: `#${r.number}`,
363
- url: linkTo("ticket", style, r.number),
369
+ text: r.name,
370
+ url: linkTo(r, style),
364
371
  },
365
372
  ], style), style, "blueBright"))
366
373
  .join(", ")}`);
@@ -384,17 +391,21 @@ async function snapshotLines(source, target, now, hook, style = PLAIN) {
384
391
  readAll(source.tickets, { board: target.board !== null }),
385
392
  source.pulls.open({ checks: true }),
386
393
  ]);
387
- const snapshot = toSnapshot(tickets, pulls, now);
394
+ const snapshot = toSnapshot(tickets, linkPulls(pulls, source.tickets, source.own), now);
388
395
  const board = boardOf(tickets);
389
396
  const blockers = new Map();
390
397
  for (const issue of snapshot.issues) {
391
398
  if (!source.tickets.blockers ||
392
- derive(issue, cardOf(board, issue.number, target.columns), snapshot.pulls, target.columns).status !== "Ready")
399
+ derive(issue, cardOf(board, issue.key, target.columns), snapshot.pulls, target.columns).status !== "Ready")
393
400
  continue;
394
- const list = await source.tickets.blockers.list(issue.number);
395
- blockers.set(issue.number, list.filter((b) => b.state === "open").map((b) => b.number));
401
+ const list = await source.tickets.blockers.list(issue.key);
402
+ blockers.set(issue.key, list.filter((b) => b.state === "open").map((b) => b.key));
396
403
  }
397
- return formatRows(toRows(snapshot, board, blockers, now, target.watch, target.columns), now, !hook, { ...style, links, columns: target.columns });
404
+ return formatRows(toRows(snapshot, board, blockers, now, {
405
+ watch: target.watch,
406
+ columns: target.columns,
407
+ ref: (k) => source.tickets.ref(k),
408
+ }), now, !hook, { ...style, links, columns: target.columns });
398
409
  }
399
410
  const WATCH_MS = 15_000;
400
411
  // The alternate screen with the cursor hidden, and back.
@@ -484,6 +495,7 @@ export async function run(argv) {
484
495
  tickets,
485
496
  pulls: openCodeHost(target.repository, settings.codeHost.type),
486
497
  runner: openRunner(target.repository, settings.builds.runner),
498
+ own: ownLinks(settings),
487
499
  };
488
500
  },
489
501
  now: () => new Date(),
package/dist/sync.d.mts CHANGED
@@ -16,6 +16,10 @@ export declare function withSchedule(text: string, minutes: number, file: string
16
16
  /** A workflow with the one `branches:` line of its push trigger naming the
17
17
  * default branch and nothing else. */
18
18
  export declare function withDefaultBranch(text: string, name: string, file: string): string;
19
+ /** The build workflow with its run named as the ticket system writes the
20
+ * ticket, such as `Build #12` on GitHub, which `factory build` finds the
21
+ * run by. */
22
+ export declare function withRunName(text: string, ref: (key: string) => string, file: string): string;
19
23
  /** A session workflow with the minutes its session may run, and its job 10
20
24
  * more, so the steps after the session still run before the job is
21
25
  * stopped. */
package/dist/sync.mjs CHANGED
@@ -19,6 +19,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync,
19
19
  import { dirname, join, relative, sep } from "node:path";
20
20
  import { fileURLToPath } from "node:url";
21
21
  import { firstRefusal, npmrcAt } from "./npmrc.mjs";
22
+ import { refOf } from "./tickets/index.mjs";
22
23
  import { filesDeps, repoRoot, resolveFiles, RULE_NUMBERS, staleOf, defaultDeps, } from "./config.mjs";
23
24
  import { CHOICES_FILE, choicesText, settingsHash, staleChoices, } from "./preset.mjs";
24
25
  import { branchDeps, CANNOT_TELL, defaultBranch, } from "./lib/default-branch.mjs";
@@ -75,6 +76,16 @@ export function withDefaultBranch(text, name, file) {
75
76
  : JSON.stringify(name);
76
77
  return text.replace(pattern, (_, lead) => `${lead}[${written}]`);
77
78
  }
79
+ const BUILD_WORKFLOW = "workflows/factory-build.yml";
80
+ /** The build workflow with its run named as the ticket system writes the
81
+ * ticket, such as `Build #12` on GitHub, which `factory build` finds the
82
+ * run by. */
83
+ export function withRunName(text, ref, file) {
84
+ const pattern = /^run-name: .*$/gm;
85
+ if ((text.match(pattern) ?? []).length !== 1)
86
+ throw new Error(`${file}: expected one run-name line, to name the build`);
87
+ return text.replace(pattern, () => `run-name: ${JSON.stringify(`Build ${ref("${{ inputs.ticket }}")}`)}`);
88
+ }
78
89
  /** The workflows that run a Claude session, by the kind of session each
79
90
  * runs. */
80
91
  const SESSION_WORKFLOWS = {
@@ -511,7 +522,9 @@ export async function plan(pkg, root, r, branch) {
511
522
  const source = readFileSync(join(pkg, from), "utf8");
512
523
  const text = PUSH_WORKFLOWS.includes(from)
513
524
  ? withDefaultBranch(source, branch, from)
514
- : source;
525
+ : from === BUILD_WORKFLOW
526
+ ? withRunName(source, refOf(s.tickets.type), from)
527
+ : source;
515
528
  const kind = SESSION_WORKFLOWS[from.replace(/^workflows\//, "")];
516
529
  const written = kind && from.startsWith("workflows/")
517
530
  ? withMinutes(text, s.sessionMinutes[kind], from)
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 TicketComment, type Tickets } from "./tickets/types.mts";
7
+ import { type Key, 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;
@@ -28,8 +28,8 @@ export type Deps = {
28
28
  out: (line: string) => void;
29
29
  /** Where this checkout remembers the claim it posted on each issue. */
30
30
  claimStore: {
31
- read: (issue: number) => number | null;
32
- write: (issue: number, commentId: number) => void;
31
+ read: (issue: Key) => string | null;
32
+ write: (issue: Key, commentId: string) => void;
33
33
  };
34
34
  readFile: (path: string) => string;
35
35
  now: () => Date;
@@ -47,18 +47,24 @@ export type Deps = {
47
47
  export type { Clock };
48
48
  export declare function readComments(c: {
49
49
  tickets: Tickets;
50
- }, issue: number): Promise<IssueComment[]>;
50
+ }, issue: Key): Promise<IssueComment[]>;
51
+ /** What a cost note needs: the session's clock and what it spent. */
52
+ export type CostDeps = Pick<Deps, "env" | "clock" | "now" | "measure">;
53
+ /** The cost note for what this session spent since its clock started, and
54
+ * the clock restarted from now. `on` is where the note is posted, as
55
+ * written in prose. */
56
+ export declare function takeCost(on: string, d: CostDeps): string;
51
57
  /** What the ticket waits on that is still open; none when the ticket
52
58
  * system records no blockers. */
53
59
  export declare function openBlockers(c: {
54
60
  tickets: Tickets;
55
- }, issue: number): Promise<number[]>;
61
+ }, issue: Key): Promise<Key[]>;
56
62
  /** The outcome of a claim, as `factory-build` reads it. */
57
- export declare function claimOutcome(comments: IssueComment[], mine: number): "claimed" | `held by ${string}`;
63
+ export declare function claimOutcome(comments: IssueComment[], mine: string): "claimed" | `held by ${string}`;
58
64
  export declare function withLine(body: string, line: string): string;
59
65
  /** A ticket for a reader: title, state, labels, body, and each comment with
60
66
  * its ID and author. */
61
- export declare function formatTicket(t: Ticket): string[];
67
+ export declare function formatTicket(t: Ticket, ref: string): string[];
62
68
  /** One comment as `view` prints it: a line naming it, then its body. */
63
69
  export declare function formatComment(c: TicketComment): string[];
64
70
  export declare function main(argv: string[], deps: Deps): Promise<number>;