ticket-runner 0.6.4 → 0.6.6
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/README.ko.md +5 -5
- package/README.md +4 -4
- package/docs/templates/operator-skill.md +81 -16
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +99 -2
- package/src/adapters/claude-agent-runner.ts +5 -5
- package/src/adapters/exec.ts +32 -4
- package/src/adapters/gh-tracker.ts +276 -60
- package/src/adapters/git-workspace.ts +27 -10
- package/src/adapters/liveness.ts +77 -0
- package/src/adapters/process-tree.ts +4 -7
- package/src/adapters/version.ts +5 -5
- package/src/branch.ts +1 -1
- package/src/cli.ts +2 -2
- package/src/config.ts +22 -4
- package/src/conventions.ts +22 -19
- package/src/credential.ts +14 -13
- package/src/criteria.ts +102 -52
- package/src/failing-base.ts +7 -7
- package/src/failure-message.ts +72 -0
- package/src/guards.ts +21 -6
- package/src/handoff.ts +2 -2
- package/src/init.ts +8 -8
- package/src/landing.ts +1 -1
- package/src/lifecycle.ts +2 -2
- package/src/lock.ts +10 -2
- package/src/note-schema.ts +14 -11
- package/src/notes.ts +19 -7
- package/src/operator-skill.ts +2 -2
- package/src/orchestrator.ts +758 -275
- package/src/outside-fault.ts +103 -0
- package/src/ports/agent-runner.ts +1 -1
- package/src/ports/tracker.ts +29 -15
- package/src/ports/workspace.ts +52 -24
- package/src/progress.ts +42 -7
- package/src/prompts.ts +242 -34
- package/src/readiness.ts +11 -11
- package/src/remove.ts +7 -7
- package/src/resume.ts +28 -20
- package/src/run-log.ts +5 -5
- package/src/run.ts +55 -13
- package/src/staleness.ts +14 -14
- package/src/start.ts +29 -16
- package/src/stranded.ts +19 -19
- package/src/templates.ts +398 -149
- package/src/title.ts +106 -8
- package/src/transcript-home.ts +49 -0
- package/src/verdict.ts +132 -27
- package/src/version-number.ts +13 -13
- package/src/version-pr.ts +12 -12
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A fault of GitHub's or of the Host's, which says nothing about the Ticket.
|
|
3
|
+
*
|
|
4
|
+
* Read off what `gh` and git print, since that is all either says about why it
|
|
5
|
+
* failed: GitHub answering with a 5xx status or with a response that is not
|
|
6
|
+
* complete JSON, and git unable to connect to or authenticate with the remote.
|
|
7
|
+
* A Ticket that meets one is released rather than handed off, as over a
|
|
8
|
+
* failing base branch: a human relabelling it would change nothing in its work,
|
|
9
|
+
* and every Ticket behind it would meet the same fault.
|
|
10
|
+
*
|
|
11
|
+
* Everything else a command prints is the Ticket's to answer for, as before: a
|
|
12
|
+
* GitHub 4xx, and a git failure that persists, such as a pull refused over a
|
|
13
|
+
* base branch that has really diverged.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/** Whose side the fault is on: GitHub's, or the git remote's. */
|
|
17
|
+
export type FaultSide = "github" | "remote";
|
|
18
|
+
|
|
19
|
+
/** A command that failed for a fault outside the Ticket, and how it failed. */
|
|
20
|
+
export class OutsideFault extends Error {
|
|
21
|
+
constructor(
|
|
22
|
+
readonly side: FaultSide,
|
|
23
|
+
/** The command as a human would type it, on one line. */
|
|
24
|
+
readonly command: string,
|
|
25
|
+
/** The first line of what it printed, which is what the Run's last line quotes. */
|
|
26
|
+
readonly line: string,
|
|
27
|
+
message: string,
|
|
28
|
+
) {
|
|
29
|
+
super(message);
|
|
30
|
+
this.name = "OutsideFault";
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* GitHub failing on its own side: a 5xx status as `gh` reports it, and a
|
|
36
|
+
* response `gh` could not read as JSON, which is how a gateway that cut the
|
|
37
|
+
* answer short shows.
|
|
38
|
+
*/
|
|
39
|
+
const GITHUB_FAULTS = [
|
|
40
|
+
/\bHTTP 5\d\d\b/,
|
|
41
|
+
/unexpected end of JSON input/i,
|
|
42
|
+
/invalid character .{1,12} looking for beginning of value/,
|
|
43
|
+
];
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* git unable to reach the remote or to be let in. `Could not read from remote
|
|
47
|
+
* repository` is not among them: git says it after a repository that does not
|
|
48
|
+
* exist as well, which no wait mends.
|
|
49
|
+
*/
|
|
50
|
+
const REMOTE_FAULTS = [
|
|
51
|
+
/Permission denied \(publickey/i,
|
|
52
|
+
/Could not resolve host/i,
|
|
53
|
+
/Authentication failed/i,
|
|
54
|
+
/could not read (Username|Password) for/i,
|
|
55
|
+
/Connection refused/i,
|
|
56
|
+
/Connection timed out/i,
|
|
57
|
+
/Operation timed out/i,
|
|
58
|
+
/Connection reset by peer/i,
|
|
59
|
+
/Failed to connect to/i,
|
|
60
|
+
];
|
|
61
|
+
|
|
62
|
+
/** The remote answering with a 5xx, which a push it failed on reports too. */
|
|
63
|
+
const REMOTE_5XX = [/The requested URL returned error: 5\d\d/, /RPC failed; HTTP 5\d\d/];
|
|
64
|
+
|
|
65
|
+
/** Whether `gh` printed a fault of GitHub's own. */
|
|
66
|
+
export function isGitHubFault(output: string): boolean {
|
|
67
|
+
return GITHUB_FAULTS.some((pattern) => pattern.test(output));
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* A push the remote, or a hook before it, refused. A connection that cannot
|
|
72
|
+
* be made fails before git gets that far, so the words of one printed beside
|
|
73
|
+
* it are a pre-push hook's own output, such as a test that could not reach
|
|
74
|
+
* its database, and no fault of the remote's.
|
|
75
|
+
*/
|
|
76
|
+
const PUSH_REFUSED = /failed to push some refs/;
|
|
77
|
+
|
|
78
|
+
/** Whether git printed that it could not connect to or authenticate with the remote. */
|
|
79
|
+
export function isRemoteFault(output: string): boolean {
|
|
80
|
+
if (REMOTE_5XX.some((pattern) => pattern.test(output))) return true;
|
|
81
|
+
return !PUSH_REFUSED.test(output) && REMOTE_FAULTS.some((pattern) => pattern.test(output));
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Whose fault a failed `command` is, from what it printed, or nothing when it
|
|
86
|
+
* is no fault outside the Ticket. Only `gh` speaks for GitHub and only git for
|
|
87
|
+
* the remote, so a Check that happens to print the same words is never one.
|
|
88
|
+
*/
|
|
89
|
+
export function faultSide(command: string, output: string): FaultSide | undefined {
|
|
90
|
+
if (command === "gh" && isGitHubFault(output)) return "github";
|
|
91
|
+
if (command === "git" && isRemoteFault(output)) return "remote";
|
|
92
|
+
return undefined;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The first line of `output` with anything on it, trimmed; empty when there is none. */
|
|
96
|
+
export function firstLine(output: string): string {
|
|
97
|
+
return (
|
|
98
|
+
output
|
|
99
|
+
.split(/\r?\n/)
|
|
100
|
+
.map((line) => line.trim())
|
|
101
|
+
.find((line) => line !== "") ?? ""
|
|
102
|
+
);
|
|
103
|
+
}
|
|
@@ -65,7 +65,7 @@ export interface StageRequest {
|
|
|
65
65
|
* Whether a Stage that emitted no structured output has failed. Defaults to
|
|
66
66
|
* true.
|
|
67
67
|
*
|
|
68
|
-
* It is the verify Stage's
|
|
68
|
+
* It is the verify Stage's verdict that makes it true there: a session that
|
|
69
69
|
* graded nothing has done none of its job. A schema that only carries Notes
|
|
70
70
|
* is a side channel the Stage may have had nothing to put in, and failing a
|
|
71
71
|
* Ticket over an empty one would be failing it for finding nothing.
|
package/src/ports/tracker.ts
CHANGED
|
@@ -40,7 +40,7 @@ export interface Issue {
|
|
|
40
40
|
* Whether the issue is closed.
|
|
41
41
|
*
|
|
42
42
|
* Only ever asked of a Ticket the pipeline kept local state for: a Run sweeps
|
|
43
|
-
* its
|
|
43
|
+
* its state files before it does anything else, and a Ticket that has closed
|
|
44
44
|
* since is one there is nothing left to resume.
|
|
45
45
|
*/
|
|
46
46
|
closed: boolean;
|
|
@@ -128,13 +128,14 @@ export interface CreatePullRequest {
|
|
|
128
128
|
* The outcome of waiting for a pull request's CI checks. Distinct from a Check,
|
|
129
129
|
* which is a command the pipeline runs itself (GLOSSARY.md).
|
|
130
130
|
*
|
|
131
|
-
* `none` means the
|
|
132
|
-
* failure rather than a silent bypass.
|
|
131
|
+
* `none` means the pull request has no checks at all, which `gates.ci` treats
|
|
132
|
+
* as a failure rather than a silent bypass.
|
|
133
133
|
*
|
|
134
|
-
* `conflicting` means the
|
|
135
|
-
* conflicting with the
|
|
136
|
-
* such a
|
|
137
|
-
* lets it through, and it has nothing a fix Stage could act
|
|
134
|
+
* `conflicting` means the pull request has no checks because GitHub reports it
|
|
135
|
+
* as conflicting with the base branch: GitHub runs no `pull_request` workflow
|
|
136
|
+
* for such a pull request, so it would otherwise read as `none`. It cannot be
|
|
137
|
+
* merged, so no gate lets it through, and it has nothing a fix Stage could act
|
|
138
|
+
* on.
|
|
138
139
|
*/
|
|
139
140
|
export type CiOutcome =
|
|
140
141
|
| { state: "passed" }
|
|
@@ -172,6 +173,9 @@ export type Authentication = "authenticated" | "unauthenticated" | "not-installe
|
|
|
172
173
|
*/
|
|
173
174
|
export type NumberKind = "issue" | "pull-request" | "nothing";
|
|
174
175
|
|
|
176
|
+
/** Whether anybody may read a repository, or only those it is shared with. */
|
|
177
|
+
export type Visibility = "public" | "private";
|
|
178
|
+
|
|
175
179
|
export interface Tracker {
|
|
176
180
|
/**
|
|
177
181
|
* Whether `gh` can speak to GitHub as somebody, and if not, whether it is
|
|
@@ -203,21 +207,31 @@ export interface Tracker {
|
|
|
203
207
|
*/
|
|
204
208
|
repository(): Promise<string | undefined>;
|
|
205
209
|
/**
|
|
206
|
-
*
|
|
210
|
+
* Whether anybody may read the Target, or nothing where GitHub could not be
|
|
211
|
+
* asked. An `internal` repository, readable only inside its enterprise, is
|
|
212
|
+
* private here.
|
|
213
|
+
*
|
|
214
|
+
* Asked once at the start of a Run, and only where the config does not say
|
|
215
|
+
* whether a handed-off Ticket's transcripts are kept on the remote. Nothing
|
|
216
|
+
* is refused over the answer: no answer counts as public.
|
|
217
|
+
*/
|
|
218
|
+
visibility(): Promise<Visibility | undefined>;
|
|
219
|
+
/**
|
|
220
|
+
* The tag of the highest version `repository` has published as a GitHub
|
|
207
221
|
* Release, named `owner/name`, or nothing where GitHub could not be asked.
|
|
208
222
|
*
|
|
209
223
|
* Named for the tag rather than for the Release, because a Release in this
|
|
210
224
|
* codebase is what a Stage the rate limit or an API failure stopped does to
|
|
211
225
|
* a Ticket (GLOSSARY.md). A published GitHub Release is what makes a tag a
|
|
212
|
-
*
|
|
226
|
+
* version anybody can install, which is why it is the question rather than
|
|
213
227
|
* the tag alone.
|
|
214
228
|
*
|
|
215
229
|
* The one method of this port that is not about the Target: it is asked about
|
|
216
230
|
* the pipeline's own repository, so a Run and `init` can say that a newer
|
|
217
|
-
*
|
|
231
|
+
* version is out. Nothing is ever refused over the answer, so no answer is an
|
|
218
232
|
* answer — a Target with no network is a Target that works (ADR-0007).
|
|
219
233
|
*
|
|
220
|
-
* Drafts and pre-releases are not published
|
|
234
|
+
* Drafts and pre-releases are not published versions and are not counted. The
|
|
221
235
|
* tag comes back as it was cut, `v0.4.0`, because that is what a human would
|
|
222
236
|
* go and look for.
|
|
223
237
|
*/
|
|
@@ -292,7 +306,7 @@ export interface Tracker {
|
|
|
292
306
|
/**
|
|
293
307
|
* Replace an issue's body.
|
|
294
308
|
*
|
|
295
|
-
* Only ever used to tick Acceptance Criteria a
|
|
309
|
+
* Only ever used to tick Acceptance Criteria a verdict proved, so whatever
|
|
296
310
|
* else the body says is read first and written back unchanged.
|
|
297
311
|
*/
|
|
298
312
|
updateIssueBody(number: number, body: string): Promise<void>;
|
|
@@ -317,9 +331,9 @@ export interface Tracker {
|
|
|
317
331
|
/**
|
|
318
332
|
* Replace the body of an open pull request.
|
|
319
333
|
*
|
|
320
|
-
* A Ticket that spends its fix budget
|
|
321
|
-
* the
|
|
322
|
-
*
|
|
334
|
+
* A Ticket that spends its fix budget comes back to its pull request, and
|
|
335
|
+
* the body is written from the latest body a Stage answered; without this it
|
|
336
|
+
* would keep describing the branch before the fix Stage changed it.
|
|
323
337
|
*/
|
|
324
338
|
updatePullRequestBody(number: number, body: string): Promise<void>;
|
|
325
339
|
/**
|
package/src/ports/workspace.ts
CHANGED
|
@@ -11,7 +11,7 @@ import type { Host } from "../host.js";
|
|
|
11
11
|
* Run, and a port that kept its own copy would be a second answer to the same
|
|
12
12
|
* question.
|
|
13
13
|
*
|
|
14
|
-
* It also keeps the pipeline's own bookkeeping about the Target: the
|
|
14
|
+
* It also keeps the pipeline's own bookkeeping about the Target: the state each
|
|
15
15
|
* resumable Ticket keeps, and the Run lock. Where those live is the adapter's
|
|
16
16
|
* business (ADR-0004), so nothing above the port says whether they are files,
|
|
17
17
|
* a branch, or a map in a test.
|
|
@@ -46,7 +46,7 @@ export type RebaseState = { resolved: true } | { resolved: false; unresolved: st
|
|
|
46
46
|
* behind it.
|
|
47
47
|
*
|
|
48
48
|
* A state of the lifecycle, not a Stage — a Stage is a session (GLOSSARY.md), and
|
|
49
|
-
* what the
|
|
49
|
+
* what the state records is what the Ticket has, not what was running. Only these
|
|
50
50
|
* two, because everything after the implement Stage — the Checks, the rebase,
|
|
51
51
|
* the pull request, CI and the merge — is re-run from the top by a Run that
|
|
52
52
|
* resumes at `implemented`, and none of them is worth a state a resume could
|
|
@@ -56,16 +56,16 @@ export const REACHED_STATES = ["claimed", "implemented"] as const;
|
|
|
56
56
|
|
|
57
57
|
export type ReachedState = (typeof REACHED_STATES)[number];
|
|
58
58
|
|
|
59
|
-
/** The
|
|
59
|
+
/** The state a Ticket keeps while its branch carries work worth resuming. */
|
|
60
60
|
export interface TicketState {
|
|
61
|
-
/** Carried in the
|
|
61
|
+
/** Carried in the state as well as its name, so it reads on its own. */
|
|
62
62
|
ticket: number;
|
|
63
63
|
/** The branch the work is on, which the resuming Run uses rather than deriving. */
|
|
64
64
|
branch: string;
|
|
65
65
|
/** The state the Ticket had reached, which is where a later Run picks it up. */
|
|
66
66
|
state: ReachedState;
|
|
67
67
|
/**
|
|
68
|
-
* Whether the
|
|
68
|
+
* Whether the fix budget has been spent. Resuming must not hand the Ticket a
|
|
69
69
|
* second fix Stage it never earned — except after a hand-off, which records it
|
|
70
70
|
* unspent, the Ticket having been through a human's hands since.
|
|
71
71
|
*/
|
|
@@ -79,21 +79,31 @@ export interface TicketState {
|
|
|
79
79
|
* The latest title a Stage answered for the whole branch, which names the
|
|
80
80
|
* pull request and the squash commit. Without it a Run that resumes after the
|
|
81
81
|
* Stage that wrote it would fall back to the first commit subject. Absent
|
|
82
|
-
* when no Stage has answered one, and in
|
|
82
|
+
* when no Stage has answered one, and in state an earlier pipeline left.
|
|
83
83
|
*/
|
|
84
84
|
title?: string;
|
|
85
|
+
/**
|
|
86
|
+
* The latest pull request body, problem and solution a Stage answered for
|
|
87
|
+
* the whole branch, which the pull request body and the squash commit are
|
|
88
|
+
* written from. Without them a Run that resumes after the Stage that wrote
|
|
89
|
+
* them would publish `Closes #<n>` alone. Each is absent when no Stage has
|
|
90
|
+
* answered it, and in state an earlier pipeline left.
|
|
91
|
+
*/
|
|
92
|
+
body?: string;
|
|
93
|
+
problem?: string;
|
|
94
|
+
solution?: string;
|
|
85
95
|
/**
|
|
86
96
|
* Whether the Run that takes the Ticket up rebases its branch onto the Base
|
|
87
|
-
* branch before its Checks. Set by a Release over a failing
|
|
97
|
+
* branch before its Checks. Set by a Release over a failing base branch, so
|
|
88
98
|
* a fix a human has landed there meanwhile reaches the branch; absent
|
|
89
|
-
* otherwise, and in
|
|
99
|
+
* otherwise, and in state an earlier pipeline left.
|
|
90
100
|
*/
|
|
91
101
|
rebaseFirst?: boolean;
|
|
92
|
-
/** The Run that last wrote the
|
|
102
|
+
/** The Run that last wrote the state, and when — both for a human reading it. */
|
|
93
103
|
runId: string;
|
|
94
104
|
/**
|
|
95
|
-
* The
|
|
96
|
-
* optional when read:
|
|
105
|
+
* The version that wrote the state (ADR-0007). Written on every write, and
|
|
106
|
+
* optional when read: state an earlier pipeline left names none, and a
|
|
97
107
|
* Ticket claimed before this existed still resumes.
|
|
98
108
|
*/
|
|
99
109
|
version?: string;
|
|
@@ -102,10 +112,10 @@ export interface TicketState {
|
|
|
102
112
|
}
|
|
103
113
|
|
|
104
114
|
/**
|
|
105
|
-
* What one Ticket's recorded
|
|
115
|
+
* What one Ticket's recorded state turned out to be.
|
|
106
116
|
*
|
|
107
|
-
* Two cases, where no
|
|
108
|
-
*
|
|
117
|
+
* Two cases, where no state at all is a third: state a Run can resume from, and
|
|
118
|
+
* state it cannot. The second is the one that most needs saying out loud: its
|
|
109
119
|
* Ticket is claimed on the board, so the sweep for Stranded Tickets is the only
|
|
110
120
|
* thing that could ever have found it (ADR-0007).
|
|
111
121
|
*/
|
|
@@ -113,9 +123,9 @@ export type StateFile =
|
|
|
113
123
|
| { readable: true; state: TicketState }
|
|
114
124
|
| {
|
|
115
125
|
readable: false;
|
|
116
|
-
/** Read off where the
|
|
126
|
+
/** Read off where the state was kept, which is the only part of it that parsed. */
|
|
117
127
|
ticket: number;
|
|
118
|
-
/** The
|
|
128
|
+
/** The version the state names, where it names one a reader can make out. */
|
|
119
129
|
version?: string;
|
|
120
130
|
};
|
|
121
131
|
|
|
@@ -313,8 +323,8 @@ export interface Workspace {
|
|
|
313
323
|
* Subjects of the commits on `branch` that `base` does not have, oldest first.
|
|
314
324
|
*
|
|
315
325
|
* The order is the port's promise, not an accident of git's default: the
|
|
316
|
-
* first subject names the whole Ticket, and
|
|
317
|
-
* in the order they were written.
|
|
326
|
+
* first subject names the whole Ticket, and a squash commit with no solution
|
|
327
|
+
* answered lists them in the order they were written.
|
|
318
328
|
*/
|
|
319
329
|
commitSubjects(branch: string, base: string): Promise<string[]>;
|
|
320
330
|
/**
|
|
@@ -389,11 +399,21 @@ export interface Workspace {
|
|
|
389
399
|
*/
|
|
390
400
|
readRemoteFile(branch: string, path: string): Promise<string | undefined>;
|
|
391
401
|
/**
|
|
392
|
-
* Delete `branch` on the remote; the
|
|
402
|
+
* Delete `branch` on the remote; the pull request is merged, so nothing
|
|
403
|
+
* references it.
|
|
393
404
|
* A branch the remote already deleted, as GitHub does on merge when told to,
|
|
394
405
|
* counts as deleted without a delete being sent, which a cloud Host could not.
|
|
395
406
|
*/
|
|
396
407
|
deleteRemoteBranch(branch: string): Promise<void>;
|
|
408
|
+
/**
|
|
409
|
+
* Fetch the whole history of a clone that is shallow, and say whether it was.
|
|
410
|
+
*
|
|
411
|
+
* Asked once before a Run claims anything. A shallow clone cannot show that
|
|
412
|
+
* the remote's base branch is a fast-forward of a local one left on an
|
|
413
|
+
* older commit, so every {@link pullBase} on it is refused, and every Ticket
|
|
414
|
+
* handed off at the rebase.
|
|
415
|
+
*/
|
|
416
|
+
unshallow(): Promise<boolean>;
|
|
397
417
|
/**
|
|
398
418
|
* Fast-forward the main checkout's `base` to the remote: at the door of the
|
|
399
419
|
* Landing, so the rebase is onto what the merge will land on, and after a
|
|
@@ -402,15 +422,15 @@ export interface Workspace {
|
|
|
402
422
|
pullBase(base: string): Promise<void>;
|
|
403
423
|
|
|
404
424
|
/**
|
|
405
|
-
* The
|
|
425
|
+
* The state `ticket` keeps, when a Run can resume from it.
|
|
406
426
|
*
|
|
407
|
-
* State nothing wrote, and
|
|
427
|
+
* State nothing wrote, and state this pipeline cannot read, are both
|
|
408
428
|
* undefined: starting the Ticket over is always safe, and resuming on a guess
|
|
409
429
|
* is not.
|
|
410
430
|
*/
|
|
411
431
|
readState(ticket: number): Promise<TicketState | undefined>;
|
|
412
432
|
/**
|
|
413
|
-
* Every Ticket's
|
|
433
|
+
* Every Ticket's state, in ascending Ticket number, the unreadable ones
|
|
414
434
|
* included: their Tickets are claimed, and the sweep is what tells a human
|
|
415
435
|
* they are there.
|
|
416
436
|
*/
|
|
@@ -419,12 +439,12 @@ export interface Workspace {
|
|
|
419
439
|
writeState(state: TicketState): Promise<void>;
|
|
420
440
|
/**
|
|
421
441
|
* Forget `ticket` is resumable, and the transcripts {@link keepTranscripts}
|
|
422
|
-
* kept beside its
|
|
442
|
+
* kept beside its state with it. A Ticket with no state is not an error.
|
|
423
443
|
*/
|
|
424
444
|
removeState(ticket: number): Promise<void>;
|
|
425
445
|
/**
|
|
426
446
|
* Keep the command lines and transcripts of the Stages Run `runId` ran for
|
|
427
|
-
* `ticket` beside its
|
|
447
|
+
* `ticket` beside its state, where a human can still read them once this
|
|
428
448
|
* Host is gone. Asked of a hand-off, and nothing else: a Ticket nobody has to
|
|
429
449
|
* look into leaves nothing behind.
|
|
430
450
|
*
|
|
@@ -432,6 +452,14 @@ export interface Workspace {
|
|
|
432
452
|
* the Run left none for the Ticket.
|
|
433
453
|
*/
|
|
434
454
|
keepTranscripts(ticket: number, runId: string): Promise<KeptTranscripts | undefined>;
|
|
455
|
+
/**
|
|
456
|
+
* Where on this Host Run `runId` wrote the files {@link keepTranscripts}
|
|
457
|
+
* would keep for `ticket`, as a `/`-separated directory relative to the
|
|
458
|
+
* checkout and ending in `/`, or nothing when it wrote none. Asked of a
|
|
459
|
+
* hand-off whose Run keeps transcripts off the remote: relative, so a public
|
|
460
|
+
* comment naming it does not publish the Host's home path.
|
|
461
|
+
*/
|
|
462
|
+
transcriptsOnHost(ticket: number, runId: string): Promise<string | undefined>;
|
|
435
463
|
/**
|
|
436
464
|
* Take the Run lock for this Run, or say what stands in the way. Taking it is
|
|
437
465
|
* the whole of the mutual exclusion: two Runs never both get `taken`, on one
|
package/src/progress.ts
CHANGED
|
@@ -26,14 +26,19 @@ export const PROGRESS_MARKER = "<!-- ticket-runner:progress -->";
|
|
|
26
26
|
/**
|
|
27
27
|
* What a row is about. Named after the lifecycle step rather than the Stage, for
|
|
28
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.
|
|
29
|
+
* each earn a row, and none of them is an agent session. `setup`, `rebase` and
|
|
30
|
+
* `pr` earn one only where GitHub or the remote failing on its own side
|
|
31
|
+
* released the Ticket there.
|
|
30
32
|
*/
|
|
31
33
|
export type ProgressPoint =
|
|
34
|
+
| "setup"
|
|
32
35
|
| "implement"
|
|
33
36
|
| "checks"
|
|
34
37
|
| "verify"
|
|
35
38
|
| "fix"
|
|
36
39
|
| "conflict"
|
|
40
|
+
| "rebase"
|
|
41
|
+
| "pr"
|
|
37
42
|
| "ci"
|
|
38
43
|
| "merge";
|
|
39
44
|
|
|
@@ -51,7 +56,7 @@ export interface ProgressRow {
|
|
|
51
56
|
const NO_ANSWER = "–";
|
|
52
57
|
|
|
53
58
|
export interface ProgressCommentBody {
|
|
54
|
-
/** The
|
|
59
|
+
/** The version reporting, as every line one Run stamps carries it. */
|
|
55
60
|
version: string;
|
|
56
61
|
runId: string;
|
|
57
62
|
branch: string;
|
|
@@ -88,7 +93,7 @@ export function progressComment({
|
|
|
88
93
|
"|---|---|---|---|",
|
|
89
94
|
...rows.map(
|
|
90
95
|
(row) =>
|
|
91
|
-
`| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${
|
|
96
|
+
`| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${duration(row.durationMs)} |`,
|
|
92
97
|
),
|
|
93
98
|
"",
|
|
94
99
|
].join("\n");
|
|
@@ -99,7 +104,7 @@ export function progressComment({
|
|
|
99
104
|
*
|
|
100
105
|
* Every section under the marker, minus the last when it is this Run's own: a
|
|
101
106
|
* Run that reads the Ticket again rewrites its section rather than starting a
|
|
102
|
-
* second. A comment an earlier
|
|
107
|
+
* second. A comment an earlier version wrote, with one header and one table, is
|
|
103
108
|
* one section like any other.
|
|
104
109
|
*/
|
|
105
110
|
function earlierSections(body: string, runId: string): string {
|
|
@@ -136,9 +141,20 @@ function count(turns: number | undefined): string {
|
|
|
136
141
|
return turns === undefined ? NO_ANSWER : String(turns);
|
|
137
142
|
}
|
|
138
143
|
|
|
139
|
-
/**
|
|
140
|
-
|
|
141
|
-
|
|
144
|
+
/**
|
|
145
|
+
* A duration as GitHub Actions writes one on a pull request's checks: `40s`,
|
|
146
|
+
* `1m 5s`, `3h 15m 35s`. The template says why. A clock stepped back mid-Stage
|
|
147
|
+
* reads `0s` rather than a negative.
|
|
148
|
+
*/
|
|
149
|
+
function duration(durationMs: number | undefined): string {
|
|
150
|
+
if (durationMs === undefined) return NO_ANSWER;
|
|
151
|
+
const total = Math.max(0, Math.round(durationMs / 1000));
|
|
152
|
+
const hours = Math.floor(total / 3600);
|
|
153
|
+
const minutes = Math.floor((total % 3600) / 60);
|
|
154
|
+
const seconds = total % 60;
|
|
155
|
+
if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
|
|
156
|
+
if (minutes > 0) return `${minutes}m ${seconds}s`;
|
|
157
|
+
return `${seconds}s`;
|
|
142
158
|
}
|
|
143
159
|
|
|
144
160
|
/**
|
|
@@ -181,6 +197,8 @@ export class Progress {
|
|
|
181
197
|
private readonly earlier: string;
|
|
182
198
|
/** Set when reporting again could only mean a second comment, never an edit. */
|
|
183
199
|
private stopped = false;
|
|
200
|
+
/** Set while the comment on the Ticket lacks a row the last write failed to carry. */
|
|
201
|
+
private behind = false;
|
|
184
202
|
|
|
185
203
|
constructor(private readonly options: ProgressOptions) {
|
|
186
204
|
// A Ticket taken back from a human keeps the comment that human read: a
|
|
@@ -198,6 +216,20 @@ export class Progress {
|
|
|
198
216
|
/** Append a row, and show it on the Ticket. */
|
|
199
217
|
async record(row: ProgressRow): Promise<void> {
|
|
200
218
|
this.rows.push(row);
|
|
219
|
+
await this.write();
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Write the comment once more if its last write failed, so a row GitHub
|
|
224
|
+
* refused mid-Ticket is on the Ticket by the time it ends. Called once the
|
|
225
|
+
* Ticket merges, is handed off or is released: no later write of the Run
|
|
226
|
+
* would carry it otherwise.
|
|
227
|
+
*/
|
|
228
|
+
async settle(): Promise<void> {
|
|
229
|
+
if (this.behind) await this.write();
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
private async write(): Promise<void> {
|
|
201
233
|
if (this.stopped) return;
|
|
202
234
|
|
|
203
235
|
const { tracker, ticket, version, runId, branch } = this.options;
|
|
@@ -213,9 +245,11 @@ export class Progress {
|
|
|
213
245
|
const id = this.comment?.id;
|
|
214
246
|
if (id !== undefined) {
|
|
215
247
|
await tracker.updateComment(id, body);
|
|
248
|
+
this.behind = false;
|
|
216
249
|
return;
|
|
217
250
|
}
|
|
218
251
|
this.comment = await tracker.comment(ticket, body);
|
|
252
|
+
this.behind = false;
|
|
219
253
|
if (this.comment.id === undefined) {
|
|
220
254
|
// A comment nothing can edit is a comment per Stage, which is the noise
|
|
221
255
|
// this whole table exists to avoid. One row is better than a dozen.
|
|
@@ -223,6 +257,7 @@ export class Progress {
|
|
|
223
257
|
this.options.log?.(`#${ticket} posted a progress comment it cannot edit again`);
|
|
224
258
|
}
|
|
225
259
|
} catch (error) {
|
|
260
|
+
this.behind = true;
|
|
226
261
|
this.options.log?.(
|
|
227
262
|
`#${ticket} could not write the progress comment: ${(error as Error).message}`,
|
|
228
263
|
);
|