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.
- package/LICENSE +21 -0
- package/README.ko.md +97 -0
- package/README.md +98 -0
- package/bin/ticket-runner.js +6 -0
- package/docs/templates/operator-skill.md +87 -0
- package/package.json +42 -0
- package/src/acceptance-criteria.ts +44 -0
- package/src/adapters/claude-agent-runner.ts +389 -0
- package/src/adapters/exec.ts +169 -0
- package/src/adapters/gh-tracker.ts +955 -0
- package/src/adapters/git-workspace.ts +951 -0
- package/src/adapters/repo-root.ts +20 -0
- package/src/adapters/version.ts +118 -0
- package/src/base-branch.ts +21 -0
- package/src/branch.ts +33 -0
- package/src/cli.ts +135 -0
- package/src/command-line.ts +190 -0
- package/src/config.ts +277 -0
- package/src/conventions.ts +118 -0
- package/src/criteria.ts +106 -0
- package/src/frontier.ts +36 -0
- package/src/guards.ts +143 -0
- package/src/handoff.ts +82 -0
- package/src/host.ts +116 -0
- package/src/init.ts +405 -0
- package/src/labels.ts +42 -0
- package/src/landing.ts +75 -0
- package/src/lifecycle.ts +34 -0
- package/src/lock.ts +215 -0
- package/src/note-schema.ts +58 -0
- package/src/notes.ts +433 -0
- package/src/operator-skill.ts +24 -0
- package/src/orchestrator.ts +1816 -0
- package/src/ports/agent-runner.ts +105 -0
- package/src/ports/tracker.ts +334 -0
- package/src/ports/workspace.ts +422 -0
- package/src/progress.ts +231 -0
- package/src/prompts.ts +288 -0
- package/src/readiness.ts +256 -0
- package/src/remove.ts +732 -0
- package/src/resume.ts +145 -0
- package/src/run-log.ts +85 -0
- package/src/run.ts +331 -0
- package/src/self-hosting.ts +33 -0
- package/src/stage-guard.ts +32 -0
- package/src/staleness.ts +101 -0
- package/src/start.ts +284 -0
- package/src/startup.ts +34 -0
- package/src/stop.ts +178 -0
- package/src/stranded.ts +136 -0
- package/src/templates.ts +596 -0
- package/src/title.ts +97 -0
- package/src/verdict.ts +88 -0
- package/src/version-number.ts +67 -0
- package/src/version-pr.ts +103 -0
|
@@ -0,0 +1,422 @@
|
|
|
1
|
+
import type { Host } from "../host.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The git working copy a Ticket is implemented in.
|
|
5
|
+
*
|
|
6
|
+
* Each Ticket gets its own worktree on its own branch, so the main checkout is
|
|
7
|
+
* never touched and a failed Ticket leaves something to inspect.
|
|
8
|
+
*
|
|
9
|
+
* Every operation that names a branch to work against takes it as `base` rather
|
|
10
|
+
* than holding one: the Target's base branch is resolved once at the start of a
|
|
11
|
+
* Run, and a port that kept its own copy would be a second answer to the same
|
|
12
|
+
* question.
|
|
13
|
+
*
|
|
14
|
+
* It also keeps the pipeline's own bookkeeping about the Target: the State each
|
|
15
|
+
* resumable Ticket keeps, and the Run lock. Where those live is the adapter's
|
|
16
|
+
* business (ADR-0004), so nothing above the port says whether they are files,
|
|
17
|
+
* a branch, or a map in a test.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* How one Check command ended. A failed Check says whether the wall-clock limit
|
|
22
|
+
* killed it, because that is the difference between a Check that hung and one
|
|
23
|
+
* that failed, and a fix Stage is told which it is mending.
|
|
24
|
+
*/
|
|
25
|
+
export type CheckOutcome =
|
|
26
|
+
/** stdout and stderr combined, as a human would see them in a terminal. */
|
|
27
|
+
| { ok: true; output: string }
|
|
28
|
+
| { ok: false; output: string; timedOut: boolean };
|
|
29
|
+
|
|
30
|
+
export type RebaseOutcome = { ok: true } | { ok: false; conflict: string };
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Whether the worktree holds a finished rebase, asked after a session has been
|
|
34
|
+
* sent in to resolve one.
|
|
35
|
+
*
|
|
36
|
+
* `unresolved` is what a human would have to be told: a rebase git is still in
|
|
37
|
+
* the middle of, paths it still calls unmerged, conflict markers left in a
|
|
38
|
+
* tracked file, or a branch that no longer sits on top of the base branch at
|
|
39
|
+
* all.
|
|
40
|
+
*/
|
|
41
|
+
export type RebaseState = { resolved: true } | { resolved: false; unresolved: string };
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* How far a Ticket got: `claimed` is one the implement Stage never finished,
|
|
45
|
+
* `implemented` one carrying that Stage's work on its branch with no merge
|
|
46
|
+
* behind it.
|
|
47
|
+
*
|
|
48
|
+
* A state of the lifecycle, not a Stage — a Stage is a session (CONTEXT.md), and
|
|
49
|
+
* what the State records is what the Ticket has, not what was running. Only these
|
|
50
|
+
* two, because everything after the implement Stage — the Checks, the rebase,
|
|
51
|
+
* the pull request, CI and the merge — is re-run from the top by a Run that
|
|
52
|
+
* resumes at `implemented`, and none of them is worth a state a resume could
|
|
53
|
+
* land on halfway.
|
|
54
|
+
*/
|
|
55
|
+
export const REACHED_STATES = ["claimed", "implemented"] as const;
|
|
56
|
+
|
|
57
|
+
export type ReachedState = (typeof REACHED_STATES)[number];
|
|
58
|
+
|
|
59
|
+
/** The State a Ticket keeps while its branch carries work worth resuming. */
|
|
60
|
+
export interface TicketState {
|
|
61
|
+
/** Carried in the State as well as its name, so it reads on its own. */
|
|
62
|
+
ticket: number;
|
|
63
|
+
/** The branch the work is on, which the resuming Run uses rather than deriving. */
|
|
64
|
+
branch: string;
|
|
65
|
+
/** The state the Ticket had reached, which is where a later Run picks it up. */
|
|
66
|
+
state: ReachedState;
|
|
67
|
+
/**
|
|
68
|
+
* Whether the Fix budget has been spent. Resuming must not hand the Ticket a
|
|
69
|
+
* second fix Stage it never earned — except after a hand-off, which records it
|
|
70
|
+
* unspent, the Ticket having been through a human's hands since.
|
|
71
|
+
*/
|
|
72
|
+
fixUsed: boolean;
|
|
73
|
+
/**
|
|
74
|
+
* The pull request the Ticket already has, if it got that far. Without it the
|
|
75
|
+
* resuming Run would try to open a second one for the branch.
|
|
76
|
+
*/
|
|
77
|
+
pullRequest?: number;
|
|
78
|
+
/**
|
|
79
|
+
* The latest title a Stage answered for the whole branch, which names the
|
|
80
|
+
* pull request and the squash commit. Without it a Run that resumes after the
|
|
81
|
+
* Stage that wrote it would fall back to the first commit subject. Absent
|
|
82
|
+
* when no Stage has answered one, and in State an earlier pipeline left.
|
|
83
|
+
*/
|
|
84
|
+
title?: string;
|
|
85
|
+
/** The Run that last wrote the State, and when — both for a human reading it. */
|
|
86
|
+
runId: string;
|
|
87
|
+
/**
|
|
88
|
+
* The Version that wrote the State (ADR-0007). Written on every write, and
|
|
89
|
+
* optional when read: State an earlier pipeline left names none, and a
|
|
90
|
+
* Ticket claimed before this existed still resumes.
|
|
91
|
+
*/
|
|
92
|
+
version?: string;
|
|
93
|
+
/** ISO 8601. */
|
|
94
|
+
updatedAt: string;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* What one Ticket's recorded State turned out to be.
|
|
99
|
+
*
|
|
100
|
+
* Two cases, where no State at all is a third: State a Run can resume from, and
|
|
101
|
+
* State it cannot. The second is the one that most needs saying out loud: its
|
|
102
|
+
* Ticket is claimed on the board, so the sweep for Stranded Tickets is the only
|
|
103
|
+
* thing that could ever have found it (ADR-0007).
|
|
104
|
+
*/
|
|
105
|
+
export type StateFile =
|
|
106
|
+
| { readable: true; state: TicketState }
|
|
107
|
+
| {
|
|
108
|
+
readable: false;
|
|
109
|
+
/** Read off where the State was kept, which is the only part of it that parsed. */
|
|
110
|
+
ticket: number;
|
|
111
|
+
/** The Version the State names, where it names one a reader can make out. */
|
|
112
|
+
version?: string;
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
/** Who holds the Run lock: one Run at a time per Target, whichever Host it is on. */
|
|
116
|
+
export interface LockHolder {
|
|
117
|
+
/**
|
|
118
|
+
* The Host the holder runs on. Only a Run on that same Host can see whether
|
|
119
|
+
* the process below is still running, so a holder on another Host is never
|
|
120
|
+
* presumed gone (ADR-0008).
|
|
121
|
+
*/
|
|
122
|
+
host: Host;
|
|
123
|
+
pid: number;
|
|
124
|
+
/** The command line the holder is running, for the message the loser prints. */
|
|
125
|
+
command: string;
|
|
126
|
+
runId: string;
|
|
127
|
+
/** ISO 8601, so the lock is readable without the pipeline. */
|
|
128
|
+
startedAt: string;
|
|
129
|
+
/**
|
|
130
|
+
* The holder process's start time as the operating system reports it, taken
|
|
131
|
+
* when the lock was claimed. Distinct from `startedAt` above, which is the
|
|
132
|
+
* Run's own wall clock, written for a human reading the lock.
|
|
133
|
+
*
|
|
134
|
+
* A pid a lock names can be recycled — by a wrapped counter, or by a reboot
|
|
135
|
+
* climbing back through the numbers a pre-reboot Run was using — so a live
|
|
136
|
+
* pid alone cannot say the process behind it is still the holder. This is
|
|
137
|
+
* what a recycled pid cannot forge. Absent when it could not be read, or
|
|
138
|
+
* when the lock predates this field; either way a live pid alone is treated
|
|
139
|
+
* as the holder, which is what this check has always done.
|
|
140
|
+
*
|
|
141
|
+
* An opaque token, not a timestamp to parse or display: its shape is
|
|
142
|
+
* whatever the platform's own record of it looks like (kernel ticks on
|
|
143
|
+
* Linux, a `ps` field on macOS), good for nothing but comparing a pid's
|
|
144
|
+
* past and present selves on the same host.
|
|
145
|
+
*/
|
|
146
|
+
processStartedAt?: string;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* What a Run asks the lock to record about itself. The Host and the process's
|
|
151
|
+
* own start time are the Workspace's to read, not a caller's to vouch for.
|
|
152
|
+
*/
|
|
153
|
+
export type LockClaim = Pick<LockHolder, "pid" | "command" | "runId" | "startedAt">;
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* A lock somebody holds, and whether they hold it from another Host, which is
|
|
157
|
+
* the difference between a Run to wait for here and one a human releases.
|
|
158
|
+
*/
|
|
159
|
+
export interface HeldLock {
|
|
160
|
+
holder: LockHolder;
|
|
161
|
+
onAnotherHost: boolean;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/** Whether a Run got the lock, and who has it when it did not. */
|
|
165
|
+
export type LockOutcome = { outcome: "taken" } | ({ outcome: "held" } & HeldLock);
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* What an attempt to take the lock found. `abandoned` is a lock a Run on this
|
|
169
|
+
* same Host held and whose process has gone, and is the one a Run may take
|
|
170
|
+
* over; a holder on another Host is never abandoned, only `held`. It names the
|
|
171
|
+
* holder that has gone, for a command that takes nothing over to say whose it
|
|
172
|
+
* was.
|
|
173
|
+
*/
|
|
174
|
+
export type LockTake = LockOutcome | { outcome: "abandoned"; holder: LockHolder };
|
|
175
|
+
|
|
176
|
+
/**
|
|
177
|
+
* Where a handed-off Ticket's transcripts were kept on the remote: a branch, and
|
|
178
|
+
* the directory on it, spelt as a human looking for them would look them up.
|
|
179
|
+
*/
|
|
180
|
+
export interface KeptTranscripts {
|
|
181
|
+
branch: string;
|
|
182
|
+
/** Ends in `/`, so it reads as the directory it is. */
|
|
183
|
+
path: string;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
export interface WorktreeRef {
|
|
187
|
+
path: string;
|
|
188
|
+
branch: string;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* One of a Target's `ticket-<n>` worktrees as `ticket-runner remove` finds it,
|
|
193
|
+
* and whether removing it would lose work GitHub does not have.
|
|
194
|
+
*/
|
|
195
|
+
export interface TicketWorktree {
|
|
196
|
+
path: string;
|
|
197
|
+
/** The branch it has checked out, and nothing for a detached one. */
|
|
198
|
+
branch?: string;
|
|
199
|
+
/** Tracked files changed, or untracked files git does not ignore. */
|
|
200
|
+
uncommitted: boolean;
|
|
201
|
+
/**
|
|
202
|
+
* Commits its branch on the remote does not have, or, where the remote has
|
|
203
|
+
* no such branch, commits no branch on the remote has.
|
|
204
|
+
*/
|
|
205
|
+
unpushed: boolean;
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Where a resumed Ticket's worktree came from, measured against its branch on
|
|
210
|
+
* the remote, which is what carries a Ticket's work between Hosts (ADR-0004).
|
|
211
|
+
*
|
|
212
|
+
* - `made`: this Host had no worktree of the branch, so one was made from the
|
|
213
|
+
* remote branch
|
|
214
|
+
* - `kept`: this Host's worktree contains the remote branch, which is a Run on
|
|
215
|
+
* this Host that died before it pushed, and it is used as it is. A rebase
|
|
216
|
+
* of the remote branch this Host never pushed contains it too, since it
|
|
217
|
+
* makes every change the remote's commits make
|
|
218
|
+
* - `parted`: this Host's copy and the remote branch each carry commits the
|
|
219
|
+
* other lacks, so another Host moved on while this one held work it never
|
|
220
|
+
* pushed, and nothing is touched
|
|
221
|
+
* - `gone`: neither this Host nor the remote has the branch
|
|
222
|
+
*/
|
|
223
|
+
export type WorktreeFromRemote = "made" | "kept" | "parted" | "gone";
|
|
224
|
+
|
|
225
|
+
export interface Workspace {
|
|
226
|
+
/**
|
|
227
|
+
* Create `branch` fresh from `base` as the remote holds it now, and check it
|
|
228
|
+
* out at `path`. The checkout's own `base` is not moved.
|
|
229
|
+
*/
|
|
230
|
+
createWorktree(worktree: WorktreeRef, base: string): Promise<void>;
|
|
231
|
+
/**
|
|
232
|
+
* Remove the worktree and delete its branch; a detached worktree, which has
|
|
233
|
+
* none, is only removed.
|
|
234
|
+
*/
|
|
235
|
+
removeWorktree(worktree: { path: string; branch?: string }): Promise<void>;
|
|
236
|
+
/**
|
|
237
|
+
* Every `ticket-<n>` worktree of this repo under the Target's `.worktrees/`,
|
|
238
|
+
* whatever Ticket or Run made it, with what each holds that GitHub lacks.
|
|
239
|
+
*
|
|
240
|
+
* Asked by `ticket-runner remove` alone, which refuses to take out a
|
|
241
|
+
* worktree holding work nothing else has.
|
|
242
|
+
*/
|
|
243
|
+
ticketWorktrees(): Promise<TicketWorktree[]>;
|
|
244
|
+
/** The local branches whose names start with `prefix`, in no particular order. */
|
|
245
|
+
listBranches(prefix: string): Promise<string[]>;
|
|
246
|
+
/** The same, of the branches the remote has. */
|
|
247
|
+
listRemoteBranches(prefix: string): Promise<string[]>;
|
|
248
|
+
/**
|
|
249
|
+
* Delete a local branch, whatever it carries. A branch still checked out in a
|
|
250
|
+
* worktree git has not forgotten is refused, with git's reason.
|
|
251
|
+
*/
|
|
252
|
+
deleteBranch(branch: string): Promise<void>;
|
|
253
|
+
/**
|
|
254
|
+
* Whether `path` is still a worktree of this repo, checked out on `branch`.
|
|
255
|
+
*
|
|
256
|
+
* Asked of a branch in the way of a Ticket taken from the top, and of one
|
|
257
|
+
* parted from the remote, because a hand-off over either sends the human to
|
|
258
|
+
* the worktree the branch is checked out in, when it is in one.
|
|
259
|
+
*/
|
|
260
|
+
hasWorktree(worktree: WorktreeRef): Promise<boolean>;
|
|
261
|
+
/**
|
|
262
|
+
* Ready the worktree a resumed Ticket carries on in, from its branch on the
|
|
263
|
+
* remote rather than from whatever this Host happens to have.
|
|
264
|
+
*
|
|
265
|
+
* A rebase a dead Run left in progress is aborted first. A worktree already
|
|
266
|
+
* here is kept only when it contains the remote branch, unpushed commits and
|
|
267
|
+
* all. One the remote has merely moved ahead of is
|
|
268
|
+
* brought up to it, since it holds nothing the remote lacks. One that has
|
|
269
|
+
* parted from the remote branch is reported and left exactly as it is, as is
|
|
270
|
+
* the remote: choosing between the two is a human's call. A branch this Host
|
|
271
|
+
* kept without its worktree is measured the same way.
|
|
272
|
+
*
|
|
273
|
+
* A worktree here and no branch on the remote is kept too: a Run on this Host
|
|
274
|
+
* that died before its first push.
|
|
275
|
+
*/
|
|
276
|
+
worktreeFromRemote(worktree: WorktreeRef): Promise<WorktreeFromRemote>;
|
|
277
|
+
/**
|
|
278
|
+
* Whether `branch` is a branch of this local repo, asked before a Ticket's
|
|
279
|
+
* worktree is created.
|
|
280
|
+
*
|
|
281
|
+
* {@link createWorktree} branches fresh from the base branch and fails on a
|
|
282
|
+
* name that is taken, and a branch nobody can account for is not reused
|
|
283
|
+
* (ADR-0004). Asking first is what lets the Ticket be handed over with a
|
|
284
|
+
* message naming the branch and what to do with it, rather than with git's own.
|
|
285
|
+
*
|
|
286
|
+
* Local only: a branch that exists nowhere but the remote is not one this
|
|
287
|
+
* answers yes about.
|
|
288
|
+
*/
|
|
289
|
+
hasBranch(branch: string): Promise<boolean>;
|
|
290
|
+
/**
|
|
291
|
+
* Subjects of the commits on `branch` that `base` does not have, oldest first.
|
|
292
|
+
*
|
|
293
|
+
* The order is the port's promise, not an accident of git's default: the
|
|
294
|
+
* first subject names the whole Ticket, and the squash commit lists the rest
|
|
295
|
+
* in the order they were written.
|
|
296
|
+
*/
|
|
297
|
+
commitSubjects(branch: string, base: string): Promise<string[]>;
|
|
298
|
+
/**
|
|
299
|
+
* The unique `Co-authored-by` trailer values across the branch's commits, in
|
|
300
|
+
* the order first seen. GitHub adds these to a default squash message; the
|
|
301
|
+
* pipeline composes its own, so it has to carry them itself.
|
|
302
|
+
*/
|
|
303
|
+
coAuthors(branch: string, base: string): Promise<string[]>;
|
|
304
|
+
/**
|
|
305
|
+
* Run one Check command in `cwd`, killing it after `timeoutMs`.
|
|
306
|
+
*
|
|
307
|
+
* The limit is passed per call, not held by the workspace, because it is the
|
|
308
|
+
* config's to decide and every Check gets the whole of it: a Check is a
|
|
309
|
+
* command a user wrote, and without a limit one that hangs stalls the Run for
|
|
310
|
+
* good.
|
|
311
|
+
*/
|
|
312
|
+
runCheck(command: string, cwd: string, timeoutMs: number): Promise<CheckOutcome>;
|
|
313
|
+
/**
|
|
314
|
+
* The paths in the worktree at `cwd` that no commit carries: tracked files
|
|
315
|
+
* modified or staged, and untracked files git does not ignore. None when the
|
|
316
|
+
* worktree is exactly its branch tip.
|
|
317
|
+
*
|
|
318
|
+
* Asked before the Checks grade a pass, because the branch is what lands and
|
|
319
|
+
* a Stage that left its last changes uncommitted would otherwise be graded on
|
|
320
|
+
* code the pull request never carries.
|
|
321
|
+
*/
|
|
322
|
+
uncommittedPaths(cwd: string): Promise<string[]>;
|
|
323
|
+
/** Restore the worktree to its committed state, tracked and untracked. */
|
|
324
|
+
discardChanges(cwd: string): Promise<void>;
|
|
325
|
+
/**
|
|
326
|
+
* Replay the branch checked out at `cwd` onto `base`.
|
|
327
|
+
*
|
|
328
|
+
* A conflict is reported rather than thrown, and the rebase is left in
|
|
329
|
+
* progress: that stopped state is what a session sent in to resolve the
|
|
330
|
+
* conflict works on. Every caller that gets one therefore owes the worktree
|
|
331
|
+
* either a finished rebase or an {@link abortRebase}.
|
|
332
|
+
*/
|
|
333
|
+
rebase(cwd: string, base: string): Promise<RebaseOutcome>;
|
|
334
|
+
/** What, if anything, still stands between the worktree and a finished rebase. */
|
|
335
|
+
rebaseState(cwd: string, base: string): Promise<RebaseState>;
|
|
336
|
+
/**
|
|
337
|
+
* Put the worktree back the way it was before the rebase started. A no-op
|
|
338
|
+
* when no rebase is in progress, so it is safe on any failure path.
|
|
339
|
+
*/
|
|
340
|
+
abortRebase(cwd: string): Promise<void>;
|
|
341
|
+
/**
|
|
342
|
+
* Push `branch` from the worktree at `cwd`, overwriting what the remote has
|
|
343
|
+
* only when it is what this Host last saw there: a rebase rewrites the
|
|
344
|
+
* branch, and another Host's newer work must not be.
|
|
345
|
+
*
|
|
346
|
+
* Pushed after every Stage that commits, not only at the pull request, so a
|
|
347
|
+
* Host that vanishes mid-Ticket loses no committed work.
|
|
348
|
+
*/
|
|
349
|
+
push(cwd: string, branch: string): Promise<void>;
|
|
350
|
+
/**
|
|
351
|
+
* Whether the remote has `branch`, asked by a hand-off so its comment says
|
|
352
|
+
* where the work is once this Host is gone only when that is true.
|
|
353
|
+
*/
|
|
354
|
+
hasRemoteBranch(branch: string): Promise<boolean>;
|
|
355
|
+
/**
|
|
356
|
+
* Delete `branch` on the remote; the PR is merged, so nothing references it.
|
|
357
|
+
* A branch the remote already deleted, as GitHub does on merge when told to,
|
|
358
|
+
* counts as deleted without a delete being sent, which a cloud Host could not.
|
|
359
|
+
*/
|
|
360
|
+
deleteRemoteBranch(branch: string): Promise<void>;
|
|
361
|
+
/**
|
|
362
|
+
* Fast-forward the main checkout's `base` to the remote: at the door of the
|
|
363
|
+
* Landing, so the rebase is onto what the merge will land on, and after a
|
|
364
|
+
* merge.
|
|
365
|
+
*/
|
|
366
|
+
pullBase(base: string): Promise<void>;
|
|
367
|
+
|
|
368
|
+
/**
|
|
369
|
+
* The State `ticket` keeps, when a Run can resume from it.
|
|
370
|
+
*
|
|
371
|
+
* State nothing wrote, and State this pipeline cannot read, are both
|
|
372
|
+
* undefined: starting the Ticket over is always safe, and resuming on a guess
|
|
373
|
+
* is not.
|
|
374
|
+
*/
|
|
375
|
+
readState(ticket: number): Promise<TicketState | undefined>;
|
|
376
|
+
/**
|
|
377
|
+
* Every Ticket's State, in ascending Ticket number, the unreadable ones
|
|
378
|
+
* included: their Tickets are claimed, and the sweep is what tells a human
|
|
379
|
+
* they are there.
|
|
380
|
+
*/
|
|
381
|
+
readAllStates(): Promise<StateFile[]>;
|
|
382
|
+
/** Record `state` as its Ticket's, replacing whatever was there. */
|
|
383
|
+
writeState(state: TicketState): Promise<void>;
|
|
384
|
+
/**
|
|
385
|
+
* Forget `ticket` is resumable, and the transcripts {@link keepTranscripts}
|
|
386
|
+
* kept beside its State with it. A Ticket with no State is not an error.
|
|
387
|
+
*/
|
|
388
|
+
removeState(ticket: number): Promise<void>;
|
|
389
|
+
/**
|
|
390
|
+
* Keep the command lines and transcripts of the Stages Run `runId` ran for
|
|
391
|
+
* `ticket` beside its State, where a human can still read them once this
|
|
392
|
+
* Host is gone. Asked of a hand-off, and nothing else: a Ticket nobody has to
|
|
393
|
+
* look into leaves nothing behind.
|
|
394
|
+
*
|
|
395
|
+
* Where they were kept, for the hand-off comment to name, or nothing when
|
|
396
|
+
* the Run left none for the Ticket.
|
|
397
|
+
*/
|
|
398
|
+
keepTranscripts(ticket: number, runId: string): Promise<KeptTranscripts | undefined>;
|
|
399
|
+
/**
|
|
400
|
+
* Take the Run lock for this Run, or say what stands in the way. Taking it is
|
|
401
|
+
* the whole of the mutual exclusion: two Runs never both get `taken`, on one
|
|
402
|
+
* Host or on two.
|
|
403
|
+
*/
|
|
404
|
+
takeRunLock(claim: LockClaim): Promise<LockTake>;
|
|
405
|
+
/**
|
|
406
|
+
* Take a lock {@link takeRunLock} found `abandoned`. A Run that took it in
|
|
407
|
+
* the meantime is `held` again, and is not taken from.
|
|
408
|
+
*/
|
|
409
|
+
takeOverRunLock(claim: LockClaim): Promise<LockOutcome>;
|
|
410
|
+
/**
|
|
411
|
+
* Who holds the Run lock, when anybody still does. An abandoned lock has no
|
|
412
|
+
* holder, and is left exactly where it is: taking it over belongs to a Run
|
|
413
|
+
* that is actually starting, where this only reads.
|
|
414
|
+
*/
|
|
415
|
+
runLockHolder(): Promise<HeldLock | undefined>;
|
|
416
|
+
/**
|
|
417
|
+
* Give up the Run lock this Workspace took. A lock somebody else holds by
|
|
418
|
+
* now — a human released this Run's and another Run took it — is theirs,
|
|
419
|
+
* and is left alone.
|
|
420
|
+
*/
|
|
421
|
+
releaseRunLock(): Promise<void>;
|
|
422
|
+
}
|
package/src/progress.ts
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one comment a Ticket's Stages share.
|
|
3
|
+
*
|
|
4
|
+
* A Run reports on a Ticket a dozen times, and a comment per report would make
|
|
5
|
+
* the Ticket unreadable and notify its watchers every time. So there is one
|
|
6
|
+
* comment, found by a hidden marker and rewritten in place as each Stage
|
|
7
|
+
* finishes: only the first Stage notifies anyone. Each Run that works the
|
|
8
|
+
* Ticket has a section of it, below the sections earlier Runs left exactly as
|
|
9
|
+
* they left them, because a cloud Host's transcripts go with its VM and those
|
|
10
|
+
* sections are then all that says what that Run did. The one Run that starts a
|
|
11
|
+
* second comment is the one taking the Ticket back from a human, which leaves
|
|
12
|
+
* the comment that human read exactly as they read it. Everything a human has
|
|
13
|
+
* to act on — a hand-off, a guard warning — stays a comment of its own, because
|
|
14
|
+
* those are exactly the ones a notification is worth.
|
|
15
|
+
*
|
|
16
|
+
* `docs/templates/progress-comment.md` is the source of truth for the shape.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
import { carriesCurrentHandoff } from "./handoff.js";
|
|
20
|
+
import type { IssueComment, Tracker } from "./ports/tracker.js";
|
|
21
|
+
import { findMarkedComment } from "./templates.js";
|
|
22
|
+
|
|
23
|
+
/** How the pipeline finds its own progress comment again. */
|
|
24
|
+
export const PROGRESS_MARKER = "<!-- ticket-runner:progress -->";
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* What a row is about. Named after the lifecycle step rather than the Stage, for
|
|
28
|
+
* the reason `FailurePoint` in `lifecycle.ts` is: the Checks, CI and the merge
|
|
29
|
+
* each earn a row, and none of them is an agent session.
|
|
30
|
+
*/
|
|
31
|
+
export type ProgressPoint =
|
|
32
|
+
| "implement"
|
|
33
|
+
| "checks"
|
|
34
|
+
| "verify"
|
|
35
|
+
| "fix"
|
|
36
|
+
| "conflict"
|
|
37
|
+
| "ci"
|
|
38
|
+
| "merge";
|
|
39
|
+
|
|
40
|
+
export interface ProgressRow {
|
|
41
|
+
/** Written under the `Stage` column, which is what the template heads it. */
|
|
42
|
+
point: ProgressPoint;
|
|
43
|
+
/** An icon and a handful of words; details belong to the hand-off comment. */
|
|
44
|
+
outcome: string;
|
|
45
|
+
/** Agent turns. Checks, CI and the merge run no agent, so they have none. */
|
|
46
|
+
turns?: number;
|
|
47
|
+
durationMs?: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** A cell with no answer, which is not the same as a zero. */
|
|
51
|
+
const NO_ANSWER = "–";
|
|
52
|
+
|
|
53
|
+
export interface ProgressCommentBody {
|
|
54
|
+
/** The Version reporting, as every line one Run stamps carries it. */
|
|
55
|
+
version: string;
|
|
56
|
+
runId: string;
|
|
57
|
+
branch: string;
|
|
58
|
+
/** Every row so far, oldest first. */
|
|
59
|
+
rows: ProgressRow[];
|
|
60
|
+
/**
|
|
61
|
+
* The sections earlier Runs wrote, oldest first, exactly as they wrote them.
|
|
62
|
+
* This Run's section goes below them.
|
|
63
|
+
*/
|
|
64
|
+
earlier?: string;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** Opens every section, and is how one is told from the table above it. */
|
|
68
|
+
const SECTION_HEADER = "**ticket-runner**";
|
|
69
|
+
|
|
70
|
+
/** How a section's header names its Run, which is how a Run finds its own. */
|
|
71
|
+
function runLabel(runId: string): string {
|
|
72
|
+
return `run \`${runId}\``;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
export function progressComment({
|
|
76
|
+
version,
|
|
77
|
+
runId,
|
|
78
|
+
branch,
|
|
79
|
+
rows,
|
|
80
|
+
earlier = "",
|
|
81
|
+
}: ProgressCommentBody): string {
|
|
82
|
+
return [
|
|
83
|
+
PROGRESS_MARKER,
|
|
84
|
+
...(earlier === "" ? [] : [earlier, ""]),
|
|
85
|
+
`${SECTION_HEADER} \`${version}\` · ${runLabel(runId)} · \`${branch}\``,
|
|
86
|
+
"",
|
|
87
|
+
"| Stage | Outcome | Turns | Duration |",
|
|
88
|
+
"|---|---|---|---|",
|
|
89
|
+
...rows.map(
|
|
90
|
+
(row) =>
|
|
91
|
+
`| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${minutes(row.durationMs)} |`,
|
|
92
|
+
),
|
|
93
|
+
"",
|
|
94
|
+
].join("\n");
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* The sections of a progress comment that belong to Runs other than `runId`.
|
|
99
|
+
*
|
|
100
|
+
* Every section under the marker, minus the last when it is this Run's own: a
|
|
101
|
+
* Run that reads the Ticket again rewrites its section rather than starting a
|
|
102
|
+
* second. A comment an earlier Version wrote, with one header and one table, is
|
|
103
|
+
* one section like any other.
|
|
104
|
+
*/
|
|
105
|
+
function earlierSections(body: string, runId: string): string {
|
|
106
|
+
const sections: string[][] = [];
|
|
107
|
+
for (const line of body.trimStart().slice(PROGRESS_MARKER.length).split("\n")) {
|
|
108
|
+
if (line.startsWith(SECTION_HEADER)) sections.push([line]);
|
|
109
|
+
else sections.at(-1)?.push(line);
|
|
110
|
+
}
|
|
111
|
+
if (sections.at(-1)?.[0]?.includes(runLabel(runId))) sections.pop();
|
|
112
|
+
return sections.map(headerAndTable).join("\n\n");
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* A section's header and table as the pipeline wrote them, and nothing after.
|
|
117
|
+
*
|
|
118
|
+
* A Host may append a footer to every comment written — a cloud Host appends a
|
|
119
|
+
* "Generated by Claude Code" line — and it lands below the last table. Carried
|
|
120
|
+
* forward with that table, it would be one more footer for every Run, so
|
|
121
|
+
* whatever follows the table goes, whatever its wording.
|
|
122
|
+
*/
|
|
123
|
+
function headerAndTable([header = "", ...rest]: string[]): string {
|
|
124
|
+
const table = rest.findIndex((line) => line.startsWith("|"));
|
|
125
|
+
if (table === -1) return header;
|
|
126
|
+
const after = rest.findIndex((line, index) => index > table && !line.startsWith("|"));
|
|
127
|
+
return [header, ...rest.slice(0, after === -1 ? rest.length : after)].join("\n");
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** A Check command or a failure summary may hold the one character a table cannot. */
|
|
131
|
+
function cell(text: string): string {
|
|
132
|
+
return text.replaceAll("|", "\\|");
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
function count(turns: number | undefined): string {
|
|
136
|
+
return turns === undefined ? NO_ANSWER : String(turns);
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Minutes, as the rest of the pipeline reports durations to humans. */
|
|
140
|
+
function minutes(durationMs: number | undefined): string {
|
|
141
|
+
return durationMs === undefined ? NO_ANSWER : `${Math.round(durationMs / 60_000)}m`;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* The progress comment already on a Ticket, if there is one this Run can edit.
|
|
146
|
+
*
|
|
147
|
+
* A Run that comes back to a Ticket another Run reported on carries on in that
|
|
148
|
+
* comment rather than starting a second table beside it. One the tracker gave
|
|
149
|
+
* no id for is not one of those: it cannot be edited, so a fresh comment is the
|
|
150
|
+
* only way to report at all.
|
|
151
|
+
*/
|
|
152
|
+
export function findProgressComment(comments: IssueComment[]): IssueComment | undefined {
|
|
153
|
+
const found = findMarkedComment(comments, PROGRESS_MARKER);
|
|
154
|
+
return found?.id === undefined ? undefined : found;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export interface ProgressOptions {
|
|
158
|
+
tracker: Tracker;
|
|
159
|
+
ticket: number;
|
|
160
|
+
version: string;
|
|
161
|
+
runId: string;
|
|
162
|
+
branch: string;
|
|
163
|
+
/** The Ticket's comments as they were when it was claimed. */
|
|
164
|
+
comments: IssueComment[];
|
|
165
|
+
log?: (line: string) => void;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
/**
|
|
169
|
+
* One Ticket's progress comment, from the first Stage to the merge.
|
|
170
|
+
*
|
|
171
|
+
* Holds the rows so far and the comment they are written to, so the orchestrator
|
|
172
|
+
* only ever says what just happened. Nothing here throws: the comment is how a
|
|
173
|
+
* human watches a Ticket, not part of how it is decided, and a Ticket that is
|
|
174
|
+
* otherwise mergeable must not be handed off because GitHub would not take a
|
|
175
|
+
* table.
|
|
176
|
+
*/
|
|
177
|
+
export class Progress {
|
|
178
|
+
private readonly rows: ProgressRow[] = [];
|
|
179
|
+
private comment: IssueComment | undefined;
|
|
180
|
+
/** What earlier Runs wrote in the comment this Run carries on in. */
|
|
181
|
+
private readonly earlier: string;
|
|
182
|
+
/** Set when reporting again could only mean a second comment, never an edit. */
|
|
183
|
+
private stopped = false;
|
|
184
|
+
|
|
185
|
+
constructor(private readonly options: ProgressOptions) {
|
|
186
|
+
// A Ticket taken back from a human keeps the comment that human read: a
|
|
187
|
+
// Run resuming one rewrites nothing and starts a comment of its own. Every
|
|
188
|
+
// other Run — a released Ticket, a stranded one, a second pass of this one
|
|
189
|
+
// — carries on in the comment it finds, which is what the one comment is
|
|
190
|
+
// for, below whatever earlier Runs wrote in it.
|
|
191
|
+
this.comment = carriesCurrentHandoff(options.comments)
|
|
192
|
+
? undefined
|
|
193
|
+
: findProgressComment(options.comments);
|
|
194
|
+
this.earlier =
|
|
195
|
+
this.comment === undefined ? "" : earlierSections(this.comment.body, options.runId);
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
/** Append a row, and show it on the Ticket. */
|
|
199
|
+
async record(row: ProgressRow): Promise<void> {
|
|
200
|
+
this.rows.push(row);
|
|
201
|
+
if (this.stopped) return;
|
|
202
|
+
|
|
203
|
+
const { tracker, ticket, version, runId, branch } = this.options;
|
|
204
|
+
const body = progressComment({
|
|
205
|
+
version,
|
|
206
|
+
runId,
|
|
207
|
+
branch,
|
|
208
|
+
rows: this.rows,
|
|
209
|
+
earlier: this.earlier,
|
|
210
|
+
});
|
|
211
|
+
|
|
212
|
+
try {
|
|
213
|
+
const id = this.comment?.id;
|
|
214
|
+
if (id !== undefined) {
|
|
215
|
+
await tracker.updateComment(id, body);
|
|
216
|
+
return;
|
|
217
|
+
}
|
|
218
|
+
this.comment = await tracker.comment(ticket, body);
|
|
219
|
+
if (this.comment.id === undefined) {
|
|
220
|
+
// A comment nothing can edit is a comment per Stage, which is the noise
|
|
221
|
+
// this whole table exists to avoid. One row is better than a dozen.
|
|
222
|
+
this.stopped = true;
|
|
223
|
+
this.options.log?.(`#${ticket} posted a progress comment it cannot edit again`);
|
|
224
|
+
}
|
|
225
|
+
} catch (error) {
|
|
226
|
+
this.options.log?.(
|
|
227
|
+
`#${ticket} could not write the progress comment: ${(error as Error).message}`,
|
|
228
|
+
);
|
|
229
|
+
}
|
|
230
|
+
}
|
|
231
|
+
}
|