@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
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 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,26 @@ 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[];
68
+ /** One comment as `view` prints it: a line naming it, then its body. */
69
+ export declare function formatComment(c: TicketComment): string[];
62
70
  export declare function main(argv: string[], deps: Deps): Promise<number>;
63
71
  /** `factory ticket ...` and `factory follow-up ...`. */
64
72
  export declare function run(argv: string[]): Promise<number>;