ticket-runner 0.6.0

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 (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +97 -0
  3. package/README.md +98 -0
  4. package/bin/ticket-runner.js +6 -0
  5. package/docs/templates/operator-skill.md +87 -0
  6. package/package.json +42 -0
  7. package/src/acceptance-criteria.ts +44 -0
  8. package/src/adapters/claude-agent-runner.ts +389 -0
  9. package/src/adapters/exec.ts +169 -0
  10. package/src/adapters/gh-tracker.ts +955 -0
  11. package/src/adapters/git-workspace.ts +951 -0
  12. package/src/adapters/repo-root.ts +20 -0
  13. package/src/adapters/version.ts +118 -0
  14. package/src/base-branch.ts +21 -0
  15. package/src/branch.ts +33 -0
  16. package/src/cli.ts +135 -0
  17. package/src/command-line.ts +190 -0
  18. package/src/config.ts +277 -0
  19. package/src/conventions.ts +118 -0
  20. package/src/criteria.ts +106 -0
  21. package/src/frontier.ts +36 -0
  22. package/src/guards.ts +143 -0
  23. package/src/handoff.ts +82 -0
  24. package/src/host.ts +116 -0
  25. package/src/init.ts +405 -0
  26. package/src/labels.ts +42 -0
  27. package/src/landing.ts +75 -0
  28. package/src/lifecycle.ts +34 -0
  29. package/src/lock.ts +215 -0
  30. package/src/note-schema.ts +58 -0
  31. package/src/notes.ts +433 -0
  32. package/src/operator-skill.ts +24 -0
  33. package/src/orchestrator.ts +1816 -0
  34. package/src/ports/agent-runner.ts +105 -0
  35. package/src/ports/tracker.ts +334 -0
  36. package/src/ports/workspace.ts +422 -0
  37. package/src/progress.ts +231 -0
  38. package/src/prompts.ts +288 -0
  39. package/src/readiness.ts +256 -0
  40. package/src/remove.ts +732 -0
  41. package/src/resume.ts +145 -0
  42. package/src/run-log.ts +85 -0
  43. package/src/run.ts +331 -0
  44. package/src/self-hosting.ts +33 -0
  45. package/src/stage-guard.ts +32 -0
  46. package/src/staleness.ts +101 -0
  47. package/src/start.ts +284 -0
  48. package/src/startup.ts +34 -0
  49. package/src/stop.ts +178 -0
  50. package/src/stranded.ts +136 -0
  51. package/src/templates.ts +596 -0
  52. package/src/title.ts +97 -0
  53. package/src/verdict.ts +88 -0
  54. package/src/version-number.ts +67 -0
  55. package/src/version-pr.ts +103 -0
@@ -0,0 +1,105 @@
1
+ /**
2
+ * One Claude Code session per Stage (ADR-0002).
3
+ *
4
+ * The orchestrator hands over a fully built prompt and the limits the Stage
5
+ * must respect; the adapter owns the child process and the transcript on disk.
6
+ */
7
+
8
+ export type StageName = "implement" | "verify" | "fix" | "conflict";
9
+
10
+ /**
11
+ * The permission modes a Stage can run under. Only the modes that can actually
12
+ * do work unattended: `plan` and the prompting modes would guarantee a no-op.
13
+ */
14
+ export const PERMISSION_MODES = ["auto", "acceptEdits", "bypassPermissions"] as const;
15
+
16
+ export type PermissionMode = (typeof PERMISSION_MODES)[number];
17
+
18
+ /**
19
+ * How hard a Stage thinks, as `claude --effort` takes it, from the cheapest to
20
+ * the most thorough. The Target's dial for trading a Stage's cost against how
21
+ * much of a Ticket it gets through.
22
+ */
23
+ export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
24
+
25
+ export type Effort = (typeof EFFORT_LEVELS)[number];
26
+
27
+ /**
28
+ * Why a Stage did not finish cleanly. `rate-limited` is singled out because the
29
+ * pipeline releases a claim rather than blaming the Ticket for it.
30
+ */
31
+ export type StageFailure =
32
+ | "rate-limited"
33
+ | "timed-out"
34
+ | "turn-capped"
35
+ | "nonzero-exit"
36
+ | "invalid-result";
37
+
38
+ export interface StageRequest {
39
+ stage: StageName;
40
+ prompt: string;
41
+ /** The worktree the session runs in. */
42
+ cwd: string;
43
+ model: string;
44
+ effort: Effort;
45
+ maxTurns: number;
46
+ maxMinutes: number;
47
+ permissionMode: PermissionMode;
48
+ /** Where the command line, stdout, stderr and transcript are written. */
49
+ logDir: string;
50
+ /** When set, the Stage is asked for structured output matching this schema. */
51
+ jsonSchema?: unknown;
52
+ /**
53
+ * Whether a Stage that emitted no structured output has failed. Defaults to
54
+ * true.
55
+ *
56
+ * It is the verify Stage's Verdict that makes it true there: a session that
57
+ * graded nothing has done none of its job. A schema that only carries Notes
58
+ * is a side channel the Stage may have had nothing to put in, and failing a
59
+ * Ticket over an empty one would be failing it for finding nothing.
60
+ */
61
+ resultRequired?: boolean;
62
+ }
63
+
64
+ export interface StageResult {
65
+ ok: boolean;
66
+ failure?: StageFailure;
67
+ /** The structured output, present only when `jsonSchema` was requested. */
68
+ result?: unknown;
69
+ /** The exact command line, reproducible by hand. */
70
+ commandLine: string;
71
+ transcriptPath: string;
72
+ turns?: number;
73
+ durationMs: number;
74
+ }
75
+
76
+ /**
77
+ * The plugin whose skills the Stages drive (ADR-0002). A Target whose machine
78
+ * does not have it installed gets an implement Stage with no skill behind it.
79
+ */
80
+ export const SKILLS_PLUGIN = "mattpocock-skills";
81
+
82
+ /**
83
+ * What `init` can find out about the agent side of a Target's machine without
84
+ * starting a Stage. Both are reported to the human and neither is repaired:
85
+ * installing a CLI and a plugin is the one part of setup only they can do.
86
+ */
87
+ export interface AgentPreflight {
88
+ /** Whether the agent CLI could be run at all. */
89
+ runs: boolean;
90
+ /**
91
+ * Whether {@link SKILLS_PLUGIN} is installed. False whenever the CLI could
92
+ * not be asked, since an answer nobody could get is not a yes.
93
+ */
94
+ plugin: boolean;
95
+ }
96
+
97
+ export interface AgentRunner {
98
+ run(request: StageRequest): Promise<StageResult>;
99
+ /**
100
+ * Ask the agent CLI about itself. Reports rather than throws: every way it
101
+ * can go wrong — no binary, a CLI that cannot list its plugins — is a line
102
+ * in the `init` report and never an error that stops setup.
103
+ */
104
+ preflight(): Promise<AgentPreflight>;
105
+ }
@@ -0,0 +1,334 @@
1
+ /**
2
+ * The issue tracker the pipeline claims Tickets from and reports back to.
3
+ *
4
+ * Every GitHub effect the orchestrator performs goes through this port, so the
5
+ * state machine can be driven by an in-memory fake in tests.
6
+ */
7
+
8
+ export interface LabelSpec {
9
+ name: string;
10
+ color: string;
11
+ description: string;
12
+ }
13
+
14
+ /**
15
+ * One comment on an issue, carried with the id the pipeline edits it by.
16
+ *
17
+ * The pipeline writes comments it later has to find and change — the progress
18
+ * comment it edits every Stage, the Acceptance Criteria it ticks when a Ticket
19
+ * merges — so a body on its own is not enough to go on.
20
+ */
21
+ export interface IssueComment {
22
+ /**
23
+ * GitHub's own id for the comment, as {@link Tracker.updateComment} takes it.
24
+ *
25
+ * Absent when the tracker reported a comment it gave no id for, which means
26
+ * nothing more than that this one cannot be edited. Reading an issue must not
27
+ * fail over it: the bodies are what the guards grade a candidate on, and
28
+ * whether a comment can be rewritten decides nothing.
29
+ */
30
+ id?: string;
31
+ body: string;
32
+ }
33
+
34
+ export interface Issue {
35
+ number: number;
36
+ title: string;
37
+ url: string;
38
+ body: string;
39
+ /**
40
+ * Whether the issue is closed.
41
+ *
42
+ * Only ever asked of a Ticket the pipeline kept local state for: a Run sweeps
43
+ * its State files before it does anything else, and a Ticket that has closed
44
+ * since is one there is nothing left to resume.
45
+ */
46
+ closed: boolean;
47
+ labels: string[];
48
+ assignees: string[];
49
+ /**
50
+ * Every comment on the issue, oldest first.
51
+ *
52
+ * The order is part of the answer: a Ticket can carry more than one comment
53
+ * wearing the same marker — a second progress table, a second hand-off — and
54
+ * the newest is the one the pipeline is writing now.
55
+ */
56
+ comments: IssueComment[];
57
+ /** How many native sub-issues it has; anything above zero is a Spec. */
58
+ subIssues: number;
59
+ /**
60
+ * The issues GitHub records as blocking this one, open or closed. The body's
61
+ * own `Blocked by` section is never a substitute for these (ADR-0003).
62
+ */
63
+ blockedBy: number[];
64
+ }
65
+
66
+ /**
67
+ * What the Frontier is computed from: one open issue carrying the
68
+ * `ready-for-agent` label, with the two facts that can keep it off the
69
+ * Frontier.
70
+ */
71
+ export interface Candidate {
72
+ number: number;
73
+ title: string;
74
+ assignees: string[];
75
+ /**
76
+ * Open `blocked by` issues, counted off GitHub's native dependency list for
77
+ * the issue. Body text is never read (ADR-0003).
78
+ */
79
+ openBlockers: number;
80
+ }
81
+
82
+ /**
83
+ * The commit a squash merge lands on the base branch. Both halves are used
84
+ * verbatim, so GitHub appends no pull request number to the subject.
85
+ */
86
+ export interface SquashCommit {
87
+ subject: string;
88
+ body: string;
89
+ }
90
+
91
+ export interface PullRequestRef {
92
+ number: number;
93
+ url: string;
94
+ }
95
+
96
+ /**
97
+ * A new issue the pipeline opens itself. Only ever the standing Notes issue,
98
+ * which the Notes nobody had a Ticket for are gathered on as comments, so it
99
+ * arrives untriaged: labelled `needs-triage` and nothing else.
100
+ */
101
+ export interface CreateIssue {
102
+ title: string;
103
+ body: string;
104
+ labels: string[];
105
+ }
106
+
107
+ /** An open pull request, and the branch it would merge. */
108
+ export interface OpenPullRequest {
109
+ number: number;
110
+ head: string;
111
+ }
112
+
113
+ export interface IssueRef {
114
+ number: number;
115
+ url: string;
116
+ }
117
+
118
+ export interface CreatePullRequest {
119
+ /** The branch it merges into: the Target's base branch, as the Run resolved it. */
120
+ base: string;
121
+ head: string;
122
+ title: string;
123
+ body: string;
124
+ draft: boolean;
125
+ }
126
+
127
+ /**
128
+ * The outcome of waiting for a pull request's CI checks. Distinct from a Check,
129
+ * which is a command the pipeline runs itself (CONTEXT.md).
130
+ *
131
+ * `none` means the PR has no checks at all, which `gates.ci` treats as a
132
+ * failure rather than a silent bypass.
133
+ *
134
+ * `conflicting` means the PR has no checks because GitHub reports it as
135
+ * conflicting with the Base branch: GitHub runs no `pull_request` workflow for
136
+ * such a PR, so it would otherwise read as `none`. It cannot be merged, so no gate
137
+ * lets it through, and it has nothing a fix Stage could act on.
138
+ */
139
+ export type CiOutcome =
140
+ | { state: "passed" }
141
+ | {
142
+ state: "failed";
143
+ /** The one line a human reads in a notification: which checks went red. */
144
+ summary: string;
145
+ /**
146
+ * The tail of the failing job's log, as the fix Stage's evidence.
147
+ *
148
+ * The names alone say nothing a fix Stage can work from: it cannot see
149
+ * the CI log, and a failure that only happens on the runner may not
150
+ * reproduce in the worktree. A failing job whose log could not be
151
+ * fetched is named with where to find it and a note that its log was
152
+ * unavailable, since the failure is owed to the caller either way. Empty
153
+ * when no failing check was an Actions job, so every reader of it
154
+ * degrades to the summary.
155
+ */
156
+ excerpt: string;
157
+ }
158
+ | { state: "none" }
159
+ | { state: "conflicting" }
160
+ | { state: "timed-out" };
161
+
162
+ /**
163
+ * How `gh` answers on this Host: it speaks to GitHub as somebody, it runs but
164
+ * as nobody, or it cannot be run at all. The last two want different things
165
+ * of the human — a login, and an install — so they are never one answer.
166
+ */
167
+ export type Authentication = "authenticated" | "unauthenticated" | "not-installed";
168
+
169
+ /**
170
+ * What a number is on the Target. GitHub numbers issues and pull requests
171
+ * from one sequence, so a number a human types can be either, or neither.
172
+ */
173
+ export type NumberKind = "issue" | "pull-request" | "nothing";
174
+
175
+ export interface Tracker {
176
+ /**
177
+ * Whether `gh` can speak to GitHub as somebody, and if not, whether it is
178
+ * there to be logged in.
179
+ *
180
+ * `init` reports the answer, and Target readiness refuses a Host with no
181
+ * `gh` on it before its first GitHub question, which would otherwise fail on
182
+ * the spawn. Every other operation of this port fails loudly without a login,
183
+ * which is all a Run needs to know about that one.
184
+ */
185
+ authentication(): Promise<Authentication>;
186
+ currentUser(): Promise<string>;
187
+ /**
188
+ * The branch GitHub calls the Target's default.
189
+ *
190
+ * Asked once at the start of a Run, and only where the config names no
191
+ * `baseBranch` of its own: it is what a Run branches from, rebases onto,
192
+ * merges into and pulls, so a repository on `master` needs no config file.
193
+ */
194
+ defaultBranch(): Promise<string>;
195
+ /**
196
+ * The Target's GitHub repository as `owner/name`, or nothing where GitHub
197
+ * could not be asked.
198
+ *
199
+ * Asked once at the start of a Run, to learn whether the Target is the
200
+ * pipeline's own repository, which decides what each Stage is told about the
201
+ * checkout it stands in. Nothing is refused over the answer, so no answer is
202
+ * an answer: a Target this cannot name is treated as any other Target.
203
+ */
204
+ repository(): Promise<string | undefined>;
205
+ /**
206
+ * The tag of the highest Version `repository` has published as a GitHub
207
+ * Release, named `owner/name`, or nothing where GitHub could not be asked.
208
+ *
209
+ * Named for the tag rather than for the Release, because a Release in this
210
+ * codebase is what a rate-limited Stage does to a Ticket (CONTEXT.md). A
211
+ * published GitHub Release is what makes a tag a Version anybody can install,
212
+ * which is why it is the question rather than the tag alone.
213
+ *
214
+ * The one method of this port that is not about the Target: it is asked about
215
+ * the pipeline's own repository, so a Run and `init` can say that a newer
216
+ * Version is out. Nothing is ever refused over the answer, so no answer is an
217
+ * answer — a Target with no network is a Target that works (ADR-0007).
218
+ *
219
+ * Drafts and pre-releases are not published Versions and are not counted. The
220
+ * tag comes back as it was cut, `v0.4.0`, because that is what a human would
221
+ * go and look for.
222
+ */
223
+ latestVersionTag(repository: string): Promise<string | undefined>;
224
+ listLabels(): Promise<string[]>;
225
+ /**
226
+ * Create a label, and say whether this call is what made it.
227
+ *
228
+ * A label the Target already has answers `false` rather than throwing, and is
229
+ * left as it is: GitHub seeds a new repository's default labels a few seconds
230
+ * after making it, so one can arrive between a listing that lacked it and
231
+ * this create. Every other refusal still throws.
232
+ */
233
+ createLabel(label: LabelSpec): Promise<boolean>;
234
+ /**
235
+ * Delete a label, which GitHub takes off every issue wearing it, open or
236
+ * closed, and say whether this call is what deleted it.
237
+ *
238
+ * A label the Target does not have answers `false` rather than throwing:
239
+ * `ticket-runner remove` run twice finds it gone the second time.
240
+ */
241
+ deleteLabel(name: string): Promise<boolean>;
242
+ /**
243
+ * Allow squash merging on the Target, and change no other merge setting.
244
+ *
245
+ * The pipeline merges no other way, so a Target with squash merging off
246
+ * refuses the merge at the end of every Ticket. Whether the Target also
247
+ * allows merge commits or rebase merging is the Target's own policy.
248
+ */
249
+ enableSquashMerge(): Promise<void>;
250
+ /**
251
+ * Whether GitHub deletes a pull request's branch when it merges.
252
+ *
253
+ * A Target readiness item on every Host: a cloud Host can delete nothing on
254
+ * the remote, so a merged Ticket's branch goes only when the repository takes
255
+ * it (ADR-0008). Asked of a workstation too, so a Target it accepts is never
256
+ * one a cloud Run then refuses.
257
+ */
258
+ deletesBranchOnMerge(): Promise<boolean>;
259
+ /** Switch on {@link deletesBranchOnMerge}, and change no other setting. */
260
+ enableDeleteBranchOnMerge(): Promise<void>;
261
+ getIssue(number: number): Promise<Issue>;
262
+ /**
263
+ * Whether `number` is an issue, a pull request, or nothing the Target has.
264
+ *
265
+ * Asked of a number a human named to a Run that the Run then never met, so
266
+ * the summary can say why: {@link getIssue} fails over a number with nothing
267
+ * behind it, and reads a pull request as though it were an issue. A number
268
+ * GitHub has nothing for, or had and deleted, is `nothing`; every other
269
+ * failure throws.
270
+ */
271
+ numberKind(number: number): Promise<NumberKind>;
272
+ /** Open an issue, and say which one it is so a summary can name it. */
273
+ createIssue(issue: CreateIssue): Promise<IssueRef>;
274
+ /**
275
+ * Every open issue carrying `label`, in no particular order.
276
+ *
277
+ * The Frontier is computed from the `ready-for-agent` ones; the same call
278
+ * under `needs-triage` is how a Run finds the standing Notes issue, which is
279
+ * why being open is part of the question rather than a filter a caller
280
+ * applies.
281
+ */
282
+ listCandidates(label: string): Promise<Candidate[]>;
283
+ assign(number: number, user: string): Promise<void>;
284
+ unassign(number: number, user: string): Promise<void>;
285
+ addLabel(number: number, label: string): Promise<void>;
286
+ removeLabel(number: number, label: string): Promise<void>;
287
+ /** Post a comment, and say which one it is so it can be edited later. */
288
+ comment(number: number, body: string): Promise<IssueComment>;
289
+ /** Replace a comment's body, leaving it where it is in the thread. */
290
+ updateComment(id: string, body: string): Promise<void>;
291
+ /**
292
+ * Replace an issue's body.
293
+ *
294
+ * Only ever used to tick Acceptance Criteria a Verdict proved, so whatever
295
+ * else the body says is read first and written back unchanged.
296
+ */
297
+ updateIssueBody(number: number, body: string): Promise<void>;
298
+ createPullRequest(pr: CreatePullRequest): Promise<PullRequestRef>;
299
+ /**
300
+ * Every open pull request on the Target, with its head branch, so what
301
+ * `ticket-runner remove` leaves on an `agent/` branch can be named by the
302
+ * pull request a human would go and look at.
303
+ */
304
+ openPullRequests(): Promise<OpenPullRequest[]>;
305
+ convertPullRequestToDraft(number: number): Promise<void>;
306
+ /**
307
+ * Take an open pull request back out of draft.
308
+ *
309
+ * The other direction of {@link convertPullRequestToDraft}, and what a Run
310
+ * that takes a handed-off Ticket back from a human owes the pull request the
311
+ * Hand-off drafted: a draft cannot be merged. Asked before the wait for CI
312
+ * rather than at the merge, because a draft pull request often runs no
313
+ * workflows at all, and waiting on one first would read as "no checks".
314
+ */
315
+ markPullRequestReady(number: number): Promise<void>;
316
+ /**
317
+ * Replace the body of an open pull request.
318
+ *
319
+ * A Ticket that spends its fix budget is graded twice, and the body carries
320
+ * the Verdict a human reads; without this it would keep the Verdict that
321
+ * failed while the squash commit carried the one that passed.
322
+ */
323
+ updatePullRequestBody(number: number, body: string): Promise<void>;
324
+ /**
325
+ * Replace the title of an open pull request.
326
+ *
327
+ * The title is the subject of the squash commit, and a fix Stage may answer a
328
+ * new one for a pull request an earlier pass already opened; without this the
329
+ * pull request would keep the old title while a different subject landed.
330
+ */
331
+ updatePullRequestTitle(number: number, title: string): Promise<void>;
332
+ waitForCi(number: number, timeoutMs: number): Promise<CiOutcome>;
333
+ squashMerge(number: number, commit: SquashCommit): Promise<void>;
334
+ }