@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/commands.mjs CHANGED
@@ -6,19 +6,31 @@
6
6
  // factory end-to-end FILE [--times K] # commands.end-to-end, K times in a row
7
7
  // factory specs check # specs.check
8
8
  //
9
+ // and the commands that reach the spec tool `specs` names:
10
+ //
11
+ // factory specs list # each spec it keeps
12
+ // factory specs new N # start ticket N's spec
13
+ // factory specs finish N # fold ticket N's spec in
14
+ //
9
15
  // Each command runs with bash from the repository's root, with its output
10
16
  // passed through and no standard input. `test-one` gets FILE and NAME in its
11
- // environment, `end-to-end` FILE, and the spec check DO_NOT_TRACK=1. An
12
- // argument a command does not know prints its usage and exits 2.
17
+ // environment, `end-to-end` FILE, and the spec check the spec tool's
18
+ // environment. An argument a command does not know prints its usage and
19
+ // exits 2.
13
20
  import { spawnSync } from "node:child_process";
14
21
  import { colorOn, painter, plain } from "./lib/color.mjs";
15
22
  import { defaultDeps, loadSettings, repoRoot, SETTINGS_FILE, SettingsError, } from "./config.mjs";
23
+ import { specTools } from "./specs/index.mjs";
24
+ import { keyOf, openTickets } from "./tickets/index.mjs";
25
+ import { KeyError } from "./tickets/types.mjs";
16
26
  const USAGE = {
17
27
  gate: "Usage: factory gate",
18
28
  "test-one": "Usage: factory test-one FILE [NAME]",
19
29
  "end-to-end": "Usage: factory end-to-end FILE [--times K]",
20
30
  "specs-check": "Usage: factory specs check",
21
- "specs-change-name": "Usage: factory specs change-name N",
31
+ "specs-list": "Usage: factory specs list",
32
+ "specs-new": "Usage: factory specs new N",
33
+ "specs-finish": "Usage: factory specs finish N",
22
34
  };
23
35
  /** What `factory end-to-end` was asked: the file, and how many runs when
24
36
  * `--times` is given; null when the arguments are not ones it knows. */
@@ -47,12 +59,12 @@ export async function main(argv, d) {
47
59
  return 2;
48
60
  };
49
61
  const e2e = name === "end-to-end" ? endToEndArgs(args) : null;
50
- if (name === "gate" || name === "specs-check") {
62
+ if (name === "gate" || name === "specs-check" || name === "specs-list") {
51
63
  if (args.length > 0)
52
64
  return usage();
53
65
  }
54
- else if (name === "specs-change-name") {
55
- if (args.length !== 1 || !/^[1-9]\d*$/.test(args[0]))
66
+ else if (name === "specs-new" || name === "specs-finish") {
67
+ if (args.length !== 1 || args[0].startsWith("-"))
56
68
  return usage();
57
69
  }
58
70
  else if (name === "test-one") {
@@ -73,6 +85,16 @@ export async function main(argv, d) {
73
85
  d.err(e.message);
74
86
  return 1;
75
87
  }
88
+ if (name === "specs-new" || name === "specs-finish")
89
+ try {
90
+ keyOf(s.tickets.type)(args[0]);
91
+ }
92
+ catch (e) {
93
+ if (!(e instanceof KeyError))
94
+ throw e;
95
+ d.err(e.message);
96
+ return 1;
97
+ }
76
98
  const paint = d.paint ?? plain;
77
99
  /** The command's own closing line, after the output passed through. */
78
100
  const ended = (status, passed, failed) => {
@@ -119,23 +141,72 @@ export async function main(argv, d) {
119
141
  }
120
142
  return test(0);
121
143
  }
122
- if (name === "specs-change-name") {
123
- if (s.specs === "none") {
124
- d.err("specs are off: there is no spec change to name");
125
- return 1;
126
- }
127
- d.out(`issue-${args[0]}`);
144
+ const tool = d.specTools[s.specs];
145
+ if (s.specs === "none" || !tool) {
146
+ d.out(`${paint("dim", "-")} ${NO_SPEC_TOOL}`);
128
147
  return 0;
129
148
  }
130
- if (s.specCheck === null) {
131
- d.out("specs are off");
149
+ if (name === "specs-check")
150
+ return ended(d.exec(s.specCheck, d.root, tool.env), "The specs check passed.", "The specs check failed.");
151
+ if (name === "specs-list") {
152
+ const specs = tool.list(d.root);
153
+ d.out(`specs: ${s.specs}`);
154
+ if (specs.length === 0)
155
+ d.out(" none yet");
156
+ const width = Math.max(0, ...specs.map((x) => x.name.length));
157
+ for (const x of specs)
158
+ d.out(` ${x.name.padEnd(width)} ${x.path}`);
132
159
  return 0;
133
160
  }
134
- return ended(d.exec(s.specCheck, d.root, { DO_NOT_TRACK: "1" }), "The specs check passed.", "The specs check failed.");
161
+ const id = args[0];
162
+ const failed = (line) => {
163
+ d.err(`${paint("red", "✗")} ${line}`);
164
+ return 1;
165
+ };
166
+ if (name === "specs-finish") {
167
+ if (!tool.started(d.root, id)) {
168
+ if (tool.finished(d.root, id)) {
169
+ d.out(`${paint("green", "✓")} Ticket ${id}'s spec is already folded into ${tool.foldsInto}.`);
170
+ return 0;
171
+ }
172
+ return failed(`Ticket ${id} has no spec started: run factory specs new ${id} first.`);
173
+ }
174
+ if (tool.finish(d.root, id) !== 0)
175
+ return failed(`Could not fold ticket ${id}'s spec into ${tool.foldsInto}.`);
176
+ d.out(`${paint("green", "✓")} Folded ticket ${id}'s spec into ${tool.foldsInto}.`);
177
+ return 0;
178
+ }
179
+ let labels;
180
+ try {
181
+ labels = await d.labels(s, id);
182
+ }
183
+ catch (e) {
184
+ d.err(e instanceof Error ? e.message : String(e));
185
+ return 1;
186
+ }
187
+ if (!tool.runs(d.root))
188
+ return failed(`${tool.name} is not installed: run factory init, which installs it.`);
189
+ const folder = tool.folder(id);
190
+ if (tool.started(d.root, id))
191
+ d.out(`Ticket ${id}'s spec is already started in ${folder}`);
192
+ else {
193
+ if (tool.start(d.root, id) !== 0)
194
+ return failed(`Could not start ticket ${id}'s spec in ${folder}`);
195
+ d.out(`Started ticket ${id}'s spec in ${folder}`);
196
+ }
197
+ const files = tool.files(id, labels.includes("spec"));
198
+ const width = Math.max(...files.map((f) => f.path.length)) + 2;
199
+ const kinds = Math.max(...files.map((f) => f.kind.length));
200
+ d.out(`Write each file from ticket ${id}'s body:`);
201
+ for (const f of files)
202
+ d.out(` ${f.kind.padEnd(kinds)} ${f.path.padEnd(width)}${f.what}`);
203
+ d.out(`Then: ${tool.then}`);
204
+ return 0;
135
205
  }
206
+ export const NO_SPEC_TOOL = "No spec tool (specs: none): each ticket holds its own spec.";
136
207
  /** `factory gate`, `factory test-one`, `factory end-to-end`,
137
- * `factory specs check`, and `factory specs change-name`, the last two as
138
- * `specs-check` and `specs-change-name`. */
208
+ * and `factory specs check`, `list`, `new`, and `finish`, as `specs-check`
209
+ * and the rest. */
139
210
  export async function run(argv) {
140
211
  const root = repoRoot();
141
212
  return main(argv, {
@@ -150,5 +221,13 @@ export async function run(argv) {
150
221
  out: (line) => console.log(line),
151
222
  err: (line) => console.error(line),
152
223
  paint: painter(colorOn()),
224
+ specTools: specTools(),
225
+ labels: async (settings, id) => {
226
+ const { tickets } = await openTickets(settings, {
227
+ repository: settings.repository,
228
+ board: null,
229
+ });
230
+ return (await tickets.read(tickets.key(id))).labels;
231
+ },
153
232
  });
154
233
  }
package/dist/config.d.mts CHANGED
@@ -26,7 +26,8 @@ export declare const TRIGGERS: readonly ["own-server", "github-action", "manual"
26
26
  /** How often the scheduled poller may check the board, in minutes: each
27
27
  * divides an hour, so a schedule every N minutes keeps an even beat. */
28
28
  export declare const POLL_MINUTES: readonly [5, 10, 15, 30, 60];
29
- export declare const SPECS: readonly ["none", "openspec"];
29
+ /** The values `specs` takes: none, or a spec tool built. */
30
+ export declare const SPECS: string[];
30
31
  declare const FIELD_DEFAULTS: {
31
32
  readonly session: "Session";
32
33
  readonly "runs-in": "Runs in";
@@ -74,7 +75,7 @@ export type Settings = {
74
75
  /** How often the scheduled poller checks the board. */
75
76
  pollMinutes: (typeof POLL_MINUTES)[number];
76
77
  };
77
- specs: (typeof SPECS)[number];
78
+ specs: string;
78
79
  /** The command that checks the specs, or null when `specs` is none. */
79
80
  specCheck: string | null;
80
81
  /** Every command a build runs, each from the repository's root. */
@@ -160,8 +161,6 @@ export type Accessibility = (typeof ACCESSIBILITY)[number];
160
161
  export declare const SITE_AGENT = "factory-ui-reviewer";
161
162
  /** The agent that needs `commands.end-to-end`. */
162
163
  export declare const E2E_AGENT = "factory-e2e-reviewer";
163
- /** The spec check where `specs.type` is openspec and none is written. */
164
- export declare const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
165
164
  /** `commands.relock` where none is written. */
166
165
  export declare const DEFAULT_RELOCK = "npm install";
167
166
  export declare const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
package/dist/config.mjs CHANGED
@@ -91,7 +91,8 @@ export const TRIGGERS = ["own-server", "github-action", "manual"];
91
91
  /** How often the scheduled poller may check the board, in minutes: each
92
92
  * divides an hour, so a schedule every N minutes keeps an even beat. */
93
93
  export const POLL_MINUTES = [5, 10, 15, 30, 60];
94
- export const SPECS = ["none", "openspec"];
94
+ /** The values `specs` takes: none, or a spec tool built. */
95
+ export const SPECS = ["none", ...Object.keys(BUILT.specs)];
95
96
  const FIELD_DEFAULTS = {
96
97
  session: "Session",
97
98
  "runs-in": "Runs in",
@@ -119,8 +120,6 @@ export const ACCESSIBILITY = [
119
120
  export const SITE_AGENT = "factory-ui-reviewer";
120
121
  /** The agent that needs `commands.end-to-end`. */
121
122
  export const E2E_AGENT = "factory-e2e-reviewer";
122
- /** The spec check where `specs.type` is openspec and none is written. */
123
- export const OPENSPEC_CHECK = "npx --no-install openspec validate --all --strict --no-interactive";
124
123
  /** `commands.relock` where none is written. */
125
124
  export const DEFAULT_RELOCK = "npm install";
126
125
  export const NO_PLAYWRIGHT = "site needs Playwright: npm install -D playwright";
@@ -645,12 +644,12 @@ export function parseSettings(raw, exists, built = BUILT, { partial = false } =
645
644
  const fieldNames = names(boardFields, "tickets.fields", FIELD_DEFAULTS);
646
645
  const ticketFields = ticketFieldsOf(rawFields);
647
646
  const specsBlock = typed(top.specs ?? "none", "specs");
648
- const specs = oneOf(specsBlock.type, "specs", SPECS, "none");
649
- if (specsBlock.check !== undefined && specs !== "openspec")
647
+ const specs = oneOf(specsBlock.type, "specs", ["none", ...Object.keys(built.specs)], "none");
648
+ if (specsBlock.check !== undefined && specs === "none")
650
649
  throw new SettingsError(`${SETTINGS_FILE}: specs.check needs specs.type: openspec`);
651
- const specCheck = specs === "openspec"
652
- ? (command(specsBlock.check, "specs.check") ?? OPENSPEC_CHECK)
653
- : null;
650
+ const specCheck = specs === "none"
651
+ ? null
652
+ : (command(specsBlock.check, "specs.check") ?? built.specs[specs]);
654
653
  const autoMerge = object(top["auto-merge"], "auto-merge");
655
654
  const prReview = top["pr-review"] === undefined
656
655
  ? null
package/dist/init.d.mts CHANGED
@@ -50,12 +50,23 @@ export type InitDeps = {
50
50
  /** The branch name a preset in effect supplies to settings that read
51
51
  * as `settingsText`, or null for none. */
52
52
  presetBranchName: (settingsText: string) => Promise<string | null>;
53
+ /** The spec tool a preset in effect names for settings that read as
54
+ * `settingsText`, \`none\` included, or null when none names one. */
55
+ presetSpecs: (settingsText: string) => Promise<string | null>;
56
+ /** Runs an install from the root; its status and standard error. */
57
+ install: (argv: string[]) => Promise<{
58
+ status: number;
59
+ stderr: string;
60
+ }>;
53
61
  };
54
62
  /** The branch name a preset in effect supplies to the settings `text`
55
63
  * of the repository at `root`, or null for none. Settings whose presets
56
64
  * can't be read get the question: the check that follows says what is
57
65
  * wrong with them. */
58
66
  export declare const presetBranchNameAt: (root: string) => (text: string) => Promise<string | null>;
67
+ /** The spec tool a preset in effect names, as `presetBranchNameAt` finds
68
+ * a branch name. */
69
+ export declare const presetSpecsAt: (root: string) => (text: string) => Promise<string | null>;
59
70
  /** The repository and code host a remote's address names, or null for one
60
71
  * on a code host the factory does not support. */
61
72
  export declare function parseRemote(url: string, tools?: Registry): {
package/dist/init.mjs CHANGED
@@ -61,6 +61,18 @@ export const presetBranchNameAt = (root) => async (text) => {
61
61
  return null;
62
62
  }
63
63
  };
64
+ /** The spec tool a preset in effect names, as `presetBranchNameAt` finds
65
+ * a branch name. */
66
+ export const presetSpecsAt = (root) => async (text) => {
67
+ try {
68
+ const r = await resolveFiles({ ...filesDeps(root), readFile: () => text }, { partial: true });
69
+ return "specs" in r.resolution.raw ? r.settings.specs : null;
70
+ }
71
+ catch {
72
+ return null;
73
+ }
74
+ };
75
+ const NO_SPEC_TOOL = "None: each ticket holds its own spec";
64
76
  const BRANCH_QUESTION = "How should a build name its branch? Use {ticket}, and {user} for the GitHub account:";
65
77
  /** The pattern a build names its branch by, asked until the answer is one
66
78
  * the settings check takes. */
@@ -227,6 +239,23 @@ export async function main(_argv, d) {
227
239
  (await d.presetBranchName(String(doc))) !== null
228
240
  ? null
229
241
  : await askBranchName(d);
242
+ const ownSpecs = doc.get("specs");
243
+ const writtenSpecs = isMap(ownSpecs)
244
+ ? String(ownSpecs.get("type") ?? "none")
245
+ : ownSpecs === undefined
246
+ ? await d.presetSpecs(String(doc))
247
+ : String(ownSpecs);
248
+ const specsAnswer = writtenSpecs === null
249
+ ? await d.ask.select("Which spec tool do you use?", [
250
+ { name: NO_SPEC_TOOL, value: "none" },
251
+ ...Object.entries(d.tools.specs).map(([value, t]) => ({
252
+ name: t.label,
253
+ value,
254
+ })),
255
+ ], "none")
256
+ : null;
257
+ const specTool = d.tools.specs[specsAnswer ?? writtenSpecs ?? "none"];
258
+ const installing = specTool && !specTool.install.installed(d.root) ? specTool : null;
230
259
  const codeHost = d.tools.codeHost[chosen.codeHost].open(repository);
231
260
  const runner = d.tools.runner[chosen.runner].open(repository);
232
261
  const tickets = await d.tools.tickets[chosen.tickets].open({ repository, board: null }, settings);
@@ -433,6 +462,8 @@ export async function main(_argv, d) {
433
462
  quoted.type = Scalar.QUOTE_DOUBLE;
434
463
  doc.setIn(["code-host", "branch-name"], quoted);
435
464
  }
465
+ if (specsAnswer !== null)
466
+ doc.set("specs", specsAnswer);
436
467
  if (parts.has("from-board"))
437
468
  doc.setIn(["builds", "trigger"], trigger);
438
469
  else if (before.has("from-board"))
@@ -546,6 +577,8 @@ export async function main(_argv, d) {
546
577
  planRow("Settings", "allow auto-merge on the repository");
547
578
  if (parts.has("review"))
548
579
  planRow("Rules", `Require "${REVIEW_VERDICT}" before a merge to the default branch, as the rule "${RULE}"`);
580
+ if (installing)
581
+ planRow("Install", `${installing.install.package}, with ${installing.install.via}`);
549
582
  for (const part of removed)
550
583
  planRow("Turn off", PART_TEXT[part].name);
551
584
  if (!(await d.ask.confirm("Go ahead?", true))) {
@@ -594,6 +627,19 @@ export async function main(_argv, d) {
594
627
  if (!/^\/?node_modules\/?$/m.test(ignore ?? ""))
595
628
  write(".gitignore", `${ignore ?? ""}${ignore && !ignore.endsWith("\n") ? "\n" : ""}node_modules/\n`);
596
629
  write(SETTINGS_FILE, String(doc));
630
+ let installFailed = null;
631
+ if (installing) {
632
+ const { package: pkg, via } = installing.install;
633
+ const r = await d.install([...via.split(" "), pkg]);
634
+ if (r.status === 0)
635
+ d.out(`Installed ${pkg}.`);
636
+ else {
637
+ d.out(`Could not install ${pkg}:`);
638
+ for (const l of r.stderr.trimEnd().split("\n").slice(-5))
639
+ d.out(` ${l}`);
640
+ installFailed = `Install ${installing.name}, which a build writes specs with: ${via} ${pkg}`;
641
+ }
642
+ }
597
643
  const synced = await d.sync();
598
644
  if (synced !== 0)
599
645
  d.out("The sync failed, as above.");
@@ -702,7 +748,7 @@ export async function main(_argv, d) {
702
748
  d.out("");
703
749
  if (deletable.length)
704
750
  d.out(`You can now delete these secrets: ${deletable.join(", ")}`);
705
- const left = [];
751
+ const left = installFailed ? [installFailed] : [];
706
752
  const app = codeHost.reviewAppPage();
707
753
  if (parts.has("review") && app)
708
754
  left.push(`Install the app the review posts through: ${app}`);
@@ -786,6 +832,15 @@ export async function run(argv) {
786
832
  return differences(root, await syncPlan(PACKAGE, root, r, branch));
787
833
  },
788
834
  presetBranchName: presetBranchNameAt(root),
835
+ presetSpecs: presetSpecsAt(root),
836
+ install: async (argv2) => {
837
+ const r = spawnSync(argv2[0], argv2.slice(1), {
838
+ cwd: root,
839
+ encoding: "utf8",
840
+ stdio: ["ignore", "ignore", "pipe"],
841
+ });
842
+ return { status: r.status ?? 1, stderr: r.stderr ?? "" };
843
+ },
789
844
  interactive: async (argv2) => spawnSync(argv2[0], argv2.slice(1), { stdio: "inherit" }).status ?? 1,
790
845
  hasCommand,
791
846
  openPage: (url) => {
@@ -2,7 +2,7 @@
2
2
  * claimed or refined an issue: its spend is counted once, but its reviewer
3
3
  * runs belong to no issue. */
4
4
  export type Clock = {
5
- issue: number | null;
5
+ issue: string | null;
6
6
  start: string;
7
7
  };
8
8
  /** The repository's shared git directory, so a session that moves to
@@ -11,4 +11,6 @@ export declare function commonDir(): string;
11
11
  export declare const clockPath: (session: string) => string;
12
12
  /** The clock, or null when none was started or it cannot be read. */
13
13
  export declare function readClock(session: string): Clock | null;
14
+ /** A clock file's text as the clock, or null when it is not one. */
15
+ export declare function parseClock(text: string): Clock | null;
14
16
  export declare function writeClock(session: string, clock: Clock): void;
@@ -18,13 +18,19 @@ export const clockPath = (session) => join(commonDir(), `work-clock-${session}`)
18
18
  /** The clock, or null when none was started or it cannot be read. */
19
19
  export function readClock(session) {
20
20
  const path = clockPath(session);
21
- if (!existsSync(path))
22
- return null;
21
+ return existsSync(path) ? parseClock(readFileSync(path, "utf8")) : null;
22
+ }
23
+ /** A clock file's text as the clock, or null when it is not one. */
24
+ export function parseClock(text) {
23
25
  try {
24
- const clock = JSON.parse(readFileSync(path, "utf8"));
25
- return (clock.issue === null || Number.isInteger(clock.issue)) &&
26
- !Number.isNaN(Date.parse(clock.start))
27
- ? clock
26
+ const clock = JSON.parse(text);
27
+ if (Number.isNaN(Date.parse(clock.start)))
28
+ return null;
29
+ // A clock written before tickets had keys holds the issue's number.
30
+ if (typeof clock.issue === "number" && Number.isInteger(clock.issue))
31
+ return { issue: String(clock.issue), start: clock.start };
32
+ return clock.issue === null || typeof clock.issue === "string"
33
+ ? { issue: clock.issue, start: clock.start }
28
34
  : null;
29
35
  }
30
36
  catch {
@@ -0,0 +1,15 @@
1
+ import type { Settings } from "../config.mts";
2
+ import type { Links, Tickets } from "../tickets/types.mts";
3
+ import type { PullRequest } from "./work-status.mts";
4
+ /** Whether the code host keeps the tickets itself, so its own links, such
5
+ * as GitHub's closing references, say which tickets a pull request closes. */
6
+ export declare const ownLinks: (settings: Settings) => boolean;
7
+ /** The tickets a pull request closes and builds part of. `closes` is the
8
+ * code host's list as it read it. */
9
+ export declare function ticketsOf(pull: {
10
+ body: string;
11
+ closes: Links["closes"];
12
+ }, tickets: Pick<Tickets, "linksIn">, own: boolean): Links;
13
+ /** The pull requests with `closes` and `partOf` read as `ticketsOf` reads
14
+ * them. */
15
+ export declare const linkPulls: <P extends PullRequest>(pulls: P[], tickets: Pick<Tickets, "linksIn">, own: boolean) => P[];
@@ -0,0 +1,12 @@
1
+ /** Whether the code host keeps the tickets itself, so its own links, such
2
+ * as GitHub's closing references, say which tickets a pull request closes. */
3
+ export const ownLinks = (settings) => settings.tickets.type === "github" && settings.codeHost.type === "github";
4
+ /** The tickets a pull request closes and builds part of. `closes` is the
5
+ * code host's list as it read it. */
6
+ export function ticketsOf(pull, tickets, own) {
7
+ const links = tickets.linksIn(pull.body);
8
+ return { closes: own ? pull.closes : links.closes, partOf: links.partOf };
9
+ }
10
+ /** The pull requests with `closes` and `partOf` read as `ticketsOf` reads
11
+ * them. */
12
+ export const linkPulls = (pulls, tickets, own) => pulls.map((pull) => ({ ...pull, ...ticketsOf(pull, tickets, own) }));
@@ -24,7 +24,9 @@ export declare const dollars: (amount: number) => string;
24
24
  export declare const bothPrices: (listPrice: number) => string;
25
25
  /** The cost note's visible line and hidden marker, or the line that says
26
26
  * why the cost could not be measured. */
27
- export declare function costNote(measured: Measured, issue: number, session: string): string;
27
+ export declare function costNote(measured: Measured,
28
+ /** Where the note is posted, as written in prose, such as `#12`. */
29
+ on: string, session: string): string;
28
30
  /** Where Claude Code keeps its transcripts. */
29
31
  export declare function projectsDir(env: Record<string, string | undefined>): string;
30
32
  /** The session's own transcript and its subagents', or null when the
@@ -81,7 +81,9 @@ function unpricedClause(spend) {
81
81
  }
82
82
  /** The cost note's visible line and hidden marker, or the line that says
83
83
  * why the cost could not be measured. */
84
- export function costNote(measured, issue, session) {
84
+ export function costNote(measured,
85
+ /** Where the note is posted, as written in prose, such as `#12`. */
86
+ on, session) {
85
87
  const failed = (reason) => `This session's cost could not be measured: ${reason}.`;
86
88
  if (!measured.ok)
87
89
  return failed(measured.reason);
@@ -91,7 +93,7 @@ export function costNote(measured, issue, session) {
91
93
  ? "its transcript records no usage since its last note"
92
94
  : `no token in it is on a model with a list price${unpricedClause(spend).replace(/^, plus/, ":")}`);
93
95
  const amount = spend.dollars.toFixed(2);
94
- return `This session used ${bothPrices(spend.dollars)} on #${issue} since its last note${unpricedClause(spend)}.\n\n<!-- cost: ${amount} session=${session} -->`;
96
+ return `This session used ${bothPrices(spend.dollars)} on ${on} since its last note${unpricedClause(spend)}.\n\n<!-- cost: ${amount} session=${session} -->`;
95
97
  }
96
98
  /** Where Claude Code keeps its transcripts. */
97
99
  export function projectsDir(env) {
@@ -1,4 +1,4 @@
1
- import type { Board, Ticket, TicketComment } from "../tickets/types.mts";
1
+ import type { Board, Key, Ticket, TicketComment } from "../tickets/types.mts";
2
2
  export type { Board, BoardField, BoardItem } from "../tickets/types.mts";
3
3
  export declare const AGENT_MARK = "<!-- agent -->";
4
4
  export declare const STATUSES: readonly ["Backlog", "In refinement", "Ready", "In progress", "In review", "Done"];
@@ -75,16 +75,13 @@ export declare const CI_BOT = "github-actions[bot]";
75
75
  * prose does not count. */
76
76
  export declare function hasCostMarker(body: string): boolean;
77
77
  /** The cost markers in one comment, read as markers are: each on a line of
78
- * its own, outside a fenced code block. Only the owner's account, which the
79
- * agents post as, and the pull request review's bot count; the owner's comments count
80
- * only with the agent mark. */
81
- export declare function parseCosts(comment: IssueComment, owner: string): number[];
82
- /** Whether a pull request's body says it builds this issue, as "Closes #N"
83
- * or "Part of #N". */
84
- export declare function buildsIssue(body: string, number: number): boolean;
78
+ * its own, outside a fenced code block. A comment counts when it carries the
79
+ * agent mark, whoever posted it, as a claim or a release does, or when the
80
+ * pull request review's bot posted it. */
81
+ export declare function parseCosts(comment: IssueComment): number[];
85
82
  /** The issue's Cost: every cost marker on it and on each pull request, open,
86
83
  * merged, or closed, that builds it, to the cent. Null when there are none. */
87
- export declare function issueCost(issue: Issue, pulls: PullRequest[], owner: string): number | null;
84
+ export declare function issueCost(issue: Issue, pulls: PullRequest[]): number | null;
88
85
  export declare const REVIEWER_RUNS_MARK = "<!-- reviewer-runs session=";
89
86
  export type RunResult = "running" | "passed" | "failed" | "no verdict";
90
87
  export type ReviewerRun = {
@@ -129,8 +126,13 @@ export type PullRequest = {
129
126
  number: number;
130
127
  createdAt: string;
131
128
  body: string;
132
- /** Issue numbers GitHub links as closed by this pull request. */
133
- closes: number[];
129
+ /** The tickets it closes when it merges. The code host fills it with its
130
+ * own links, and `linkPulls` (`lib/pull-tickets.mts`) with what the
131
+ * factory counts. */
132
+ closes: Key[];
133
+ /** The tickets its body says it builds part of, once `linkPulls` has
134
+ * read it; empty before. */
135
+ partOf: Key[];
134
136
  isDraft: boolean;
135
137
  checks: string | null;
136
138
  openThreads: number;
@@ -151,10 +153,6 @@ export type Derived = {
151
153
  /** Open pull requests that put the issue In review. */
152
154
  pulls: number[];
153
155
  };
154
- /** Whether a pull request's body says it builds part of the follow-ups
155
- * issue, as "Part of #N". A plain mention, such as a build linking the issue
156
- * it added a line to, does not count. */
157
- export declare function buildsPartOf(body: string, number: number): boolean;
158
156
  /** The pull requests that put this issue In review. */
159
157
  export declare function reviewingPulls(issue: Issue, pulls: PullRequest[]): PullRequest[];
160
158
  /** The page of an Actions run, from the board's or the view's session: the
@@ -177,7 +175,7 @@ export type Watch = {
177
175
  export declare function watchOf(trigger: "own-server" | "github-action" | "manual", pollMinutes: number): Watch | null;
178
176
  /** Ready for longer than the poller takes, with no start: it should have
179
177
  * fired. */
180
- export declare function isNotStarted(derived: Derived, openBlockers: number[], now: Date, minutes?: number): boolean;
178
+ export declare function isNotStarted(derived: Derived, openBlockers: Key[], now: Date, minutes?: number): boolean;
181
179
  /** A claim or start over 24 hours old with no pull request, which the
182
180
  * nightly sync clears. Null when there is nothing to clear. */
183
181
  export declare function toClear(issue: Issue, pulls: PullRequest[], now: Date): {
@@ -195,6 +193,12 @@ export type Identity = {
195
193
  };
196
194
  /** The comments sessions, the poller, and the sync post: one visible
197
195
  * sentence, then its marker line and the agent mark. */
196
+ /** A ticket as a comment names it: its key, for a command, and its written
197
+ * form, for prose. */
198
+ export type Named = {
199
+ key: Key;
200
+ ref: string;
201
+ };
198
202
  export type CommentKind = {
199
203
  kind: "refining";
200
204
  who: Identity;
@@ -203,7 +207,7 @@ export type CommentKind = {
203
207
  cost?: string;
204
208
  } | {
205
209
  kind: "refined";
206
- issue: number;
210
+ issue: Named;
207
211
  before?: string;
208
212
  cost?: string;
209
213
  } | {
@@ -211,7 +215,7 @@ export type CommentKind = {
211
215
  marker: string;
212
216
  } | {
213
217
  kind: "dispatch-failed";
214
- issue: number;
218
+ issue: Named;
215
219
  status: string;
216
220
  reason: string;
217
221
  } | {
@@ -220,7 +224,7 @@ export type CommentKind = {
220
224
  } | {
221
225
  kind: "stopped";
222
226
  where: SessionKind;
223
- issue: number;
227
+ issue: Named;
224
228
  reason: string;
225
229
  cost?: string;
226
230
  } | {
@@ -228,21 +232,21 @@ export type CommentKind = {
228
232
  cost: string;
229
233
  } | {
230
234
  kind: "ended";
231
- issue: number;
235
+ issue: Named;
232
236
  } | {
233
237
  kind: "cleared-claim";
234
- issue: number;
238
+ issue: Named;
235
239
  since: string;
236
240
  } | {
237
241
  kind: "cleared-start";
238
- issue: number;
242
+ issue: Named;
239
243
  since: string;
240
244
  } | {
241
245
  kind: "follow-ups-merged";
242
246
  pull: number;
243
247
  } | {
244
248
  kind: "pull-closed";
245
- issue: number;
249
+ issue: Named;
246
250
  pull: number;
247
251
  };
248
252
  export declare function commentBody(c: CommentKind, columns?: Columns): string;
@@ -261,4 +265,4 @@ export declare function toSnapshot(tickets: Issue[], pulls: PullRequest[], now:
261
265
  /** A ticket's card, its column read as the state that column shows. A
262
266
  * card with no Status has none; one in a column no state names is
263
267
  * "Unmapped". */
264
- export declare const cardOf: (board: Board, number: number, columns?: Columns) => BoardCard | null;
268
+ export declare const cardOf: (board: Board, key: Key, columns?: Columns) => BoardCard | null;