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
package/src/resume.ts
CHANGED
|
@@ -4,15 +4,15 @@ import { z } from "zod";
|
|
|
4
4
|
import { REACHED_STATES, type StateFile, type TicketState } from "./ports/workspace.js";
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
|
-
* The
|
|
7
|
+
* The state file a Ticket keeps while its branch carries work worth resuming,
|
|
8
8
|
* and what a later Run makes of it (ADR-0004).
|
|
9
9
|
*
|
|
10
10
|
* A Ticket keeps the file for as long as there is work on its branch worth
|
|
11
|
-
* resuming, so it is written as part of the
|
|
11
|
+
* resuming, so it is written as part of the claim and rewritten whenever the
|
|
12
12
|
* Ticket reaches something a later Run should not pay for again. Three Runs read
|
|
13
13
|
* it, and what the board says decides which. One finds a Ticket the subscription
|
|
14
14
|
* rate limit or a transient API failure released: nothing was wrong with it, so
|
|
15
|
-
* the
|
|
15
|
+
* the claim came off and this file says where to carry on from. One finds a
|
|
16
16
|
* Ticket still claimed — the Run that claimed it was killed and never released
|
|
17
17
|
* anything — and resumes it in place. One finds a Ticket a human was handed and has relabelled
|
|
18
18
|
* `ready-for-agent`, which is the human handing it back. A Ticket still sitting
|
|
@@ -25,7 +25,7 @@ import { REACHED_STATES, type StateFile, type TicketState } from "./ports/worksp
|
|
|
25
25
|
* This is only what the file says and what its name is, which that Workspace
|
|
26
26
|
* reads and writes through here. Whether the branch a file names is still there
|
|
27
27
|
* is the Workspace's other question, and whether the Ticket is released or
|
|
28
|
-
* stranded is the
|
|
28
|
+
* stranded is the claim's, read off GitHub.
|
|
29
29
|
*/
|
|
30
30
|
|
|
31
31
|
const stateSchema = z.object({
|
|
@@ -35,6 +35,9 @@ const stateSchema = z.object({
|
|
|
35
35
|
fixUsed: z.boolean(),
|
|
36
36
|
pullRequest: z.number().int().positive().optional(),
|
|
37
37
|
title: z.string().optional(),
|
|
38
|
+
body: z.string().optional(),
|
|
39
|
+
problem: z.string().optional(),
|
|
40
|
+
solution: z.string().optional(),
|
|
38
41
|
rebaseFirst: z.boolean().optional(),
|
|
39
42
|
runId: z.string(),
|
|
40
43
|
version: z.string().optional(),
|
|
@@ -66,7 +69,7 @@ export function stateFileContents(state: TicketState): string {
|
|
|
66
69
|
* A file that is not JSON, one missing what resuming needs, and one a newer
|
|
67
70
|
* pipeline shaped differently are all unreadable: starting the Ticket over is
|
|
68
71
|
* always safe, and resuming on a guess is not. So is one that names another
|
|
69
|
-
* Ticket than its own name does, which no
|
|
72
|
+
* Ticket than its own name does, which no version would resume either.
|
|
70
73
|
*/
|
|
71
74
|
export function readStateFile(contents: string, ticket: number): StateFile {
|
|
72
75
|
const raw = parseJson(contents);
|
|
@@ -76,17 +79,21 @@ export function readStateFile(contents: string, ticket: number): StateFile {
|
|
|
76
79
|
return { readable: false, ticket, ...(version === undefined ? {} : { version }) };
|
|
77
80
|
}
|
|
78
81
|
|
|
79
|
-
// A pull request nobody opened, a title
|
|
80
|
-
// older pipeline never wrote, are keys that are
|
|
81
|
-
// holding nothing: the rest of the pipeline reads
|
|
82
|
-
// distinction.
|
|
83
|
-
const { pullRequest, title, rebaseFirst, version, ...state } =
|
|
82
|
+
// A pull request nobody opened, a title, body, problem or solution no Stage
|
|
83
|
+
// answered, and a version an older pipeline never wrote, are keys that are
|
|
84
|
+
// not there rather than keys holding nothing: the rest of the pipeline reads
|
|
85
|
+
// these with the same distinction.
|
|
86
|
+
const { pullRequest, title, body, problem, solution, rebaseFirst, version, ...state } =
|
|
87
|
+
parsed.data;
|
|
84
88
|
return {
|
|
85
89
|
readable: true,
|
|
86
90
|
state: {
|
|
87
91
|
...state,
|
|
88
92
|
...(pullRequest === undefined ? {} : { pullRequest }),
|
|
89
93
|
...(title === undefined ? {} : { title }),
|
|
94
|
+
...(body === undefined ? {} : { body }),
|
|
95
|
+
...(problem === undefined ? {} : { problem }),
|
|
96
|
+
...(solution === undefined ? {} : { solution }),
|
|
90
97
|
...(rebaseFirst === undefined ? {} : { rebaseFirst }),
|
|
91
98
|
...(version === undefined ? {} : { version }),
|
|
92
99
|
},
|
|
@@ -94,11 +101,11 @@ export function readStateFile(contents: string, ticket: number): StateFile {
|
|
|
94
101
|
}
|
|
95
102
|
|
|
96
103
|
/**
|
|
97
|
-
* The
|
|
104
|
+
* The version a file that will not parse still names, where it names one.
|
|
98
105
|
*
|
|
99
106
|
* Read off the raw JSON rather than the schema, because the schema is exactly
|
|
100
|
-
* what refused the file: a
|
|
101
|
-
*
|
|
107
|
+
* what refused the file: a state file a newer pipeline wrote is named by the
|
|
108
|
+
* version that wrote it, whatever else about it this one cannot read.
|
|
102
109
|
*/
|
|
103
110
|
function namedVersion(raw: unknown): string | undefined {
|
|
104
111
|
if (raw === null || typeof raw !== "object" || !("version" in raw)) return undefined;
|
|
@@ -116,19 +123,20 @@ function parseJson(contents: string): unknown {
|
|
|
116
123
|
}
|
|
117
124
|
|
|
118
125
|
/**
|
|
119
|
-
* The branch of the Target's remote that holds every Ticket's
|
|
120
|
-
* per Ticket, and the transcripts of a handed-off Ticket's Stages beside it
|
|
121
|
-
*
|
|
122
|
-
* the Workspace that writes it,
|
|
123
|
-
*
|
|
126
|
+
* The branch of the Target's remote that holds every Ticket's state, one file
|
|
127
|
+
* per Ticket, and the transcripts of a handed-off Ticket's Stages beside it
|
|
128
|
+
* where the Run keeps them on the remote, under the prefix the pipeline owns
|
|
129
|
+
* (ADR-0004). Named here rather than only in the Workspace that writes it,
|
|
130
|
+
* because `ticket-runner remove` deletes it by name and the conventions
|
|
131
|
+
* document names it to every human.
|
|
124
132
|
*/
|
|
125
133
|
export const STATE_BRANCH = "ticket-runner/state";
|
|
126
134
|
|
|
127
|
-
/** Where a pipeline before the state branch kept the
|
|
135
|
+
/** Where a pipeline before the state branch kept the state files, in the checkout. */
|
|
128
136
|
export const LOCAL_STATE_DIR = join(".ticket-runner", "state");
|
|
129
137
|
|
|
130
138
|
/**
|
|
131
|
-
* The Tickets whose
|
|
139
|
+
* The Tickets whose state files a pipeline before the state branch left in this
|
|
132
140
|
* checkout, in ascending number.
|
|
133
141
|
*
|
|
134
142
|
* Nothing reads them any more, and nothing migrates them (ADR-0004): a Run that
|
package/src/run-log.ts
CHANGED
|
@@ -18,21 +18,21 @@ export function stageLogDir(repoRoot: string, runId: string, ticket: number): st
|
|
|
18
18
|
* Where the fix Stage and the pass it bought write instead.
|
|
19
19
|
*
|
|
20
20
|
* A Stage's files are named after the Stage and emptied when it starts, so a
|
|
21
|
-
* second verify would overwrite the
|
|
21
|
+
* second verify would overwrite the verdict that spent the fix budget — which
|
|
22
22
|
* is the transcript a human most needs when the Ticket is handed off anyway.
|
|
23
23
|
*/
|
|
24
24
|
export function retryLogDir(repoRoot: string, runId: string, ticket: number): string {
|
|
25
25
|
return join(stageLogDir(repoRoot, runId, ticket), "retry");
|
|
26
26
|
}
|
|
27
27
|
|
|
28
|
-
/** The file naming the
|
|
28
|
+
/** The file naming the version, at the top of a Run's transcripts. */
|
|
29
29
|
export const VERSION_FILE = "version.txt";
|
|
30
30
|
|
|
31
31
|
/**
|
|
32
|
-
* Say which
|
|
32
|
+
* Say which version this Run is, beside the transcripts it is about to write.
|
|
33
33
|
*
|
|
34
34
|
* Written before the first Stage, so a transcript always sits beside the
|
|
35
|
-
* pipeline that wrote it: the Run summary names the
|
|
35
|
+
* pipeline that wrote it: the Run summary names the version too, but that is a
|
|
36
36
|
* terminal the night is over for, and these files outlive it (ADR-0007).
|
|
37
37
|
*/
|
|
38
38
|
export function writeRunVersion(repoRoot: string, runId: string, version: string): void {
|
|
@@ -58,7 +58,7 @@ export interface TranscriptFile {
|
|
|
58
58
|
/**
|
|
59
59
|
* The files Run `runId` wrote for `ticket` that a hand-off keeps, in name
|
|
60
60
|
* order: every Stage's command line and transcript, the retries' in `retry/`,
|
|
61
|
-
* and the
|
|
61
|
+
* and the version the Run was, so they still name the pipeline that wrote them
|
|
62
62
|
* once they are somewhere else. None when the Run wrote nothing for the Ticket.
|
|
63
63
|
*/
|
|
64
64
|
export function transcriptFiles(
|
package/src/run.ts
CHANGED
|
@@ -2,7 +2,8 @@ import { branchName } from "./branch.js";
|
|
|
2
2
|
import { selectFrontier } from "./frontier.js";
|
|
3
3
|
import { type Refusal, isGuardReason, skipReason } from "./guards.js";
|
|
4
4
|
import type { RoutedNote } from "./notes.js";
|
|
5
|
-
import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator.js";
|
|
5
|
+
import { type Pipeline, type TicketOutcome, faultOutcome, processTicket } from "./orchestrator.js";
|
|
6
|
+
import { type FaultSide, OutsideFault } from "./outside-fault.js";
|
|
6
7
|
import { StopSignal, stopLine } from "./stop.js";
|
|
7
8
|
import { holdsClaim, strandedTickets } from "./stranded.js";
|
|
8
9
|
import { releaseWords } from "./templates.js";
|
|
@@ -34,7 +35,8 @@ export interface RunResult {
|
|
|
34
35
|
* A Run that drained the Frontier carries what was left held back; one a
|
|
35
36
|
* Release stopped carries no candidates, because it ended before it could say
|
|
36
37
|
* one was held back all Run, and the rate limit carries when it resets, where a
|
|
37
|
-
* Stage was told,
|
|
38
|
+
* Stage was told, a failing base branch the Check it fails and where, and a
|
|
39
|
+
* fault of GitHub's or the remote's the command and what it printed; one
|
|
38
40
|
* a human stopped carries the moment it was asked and what it still had in
|
|
39
41
|
* hand. That is why this is a choice rather than a flag beside
|
|
40
42
|
* the list: the stops do not report the same things.
|
|
@@ -63,6 +65,14 @@ export type RunStop =
|
|
|
63
65
|
/** The Check command it failed. */
|
|
64
66
|
command: string;
|
|
65
67
|
}
|
|
68
|
+
| {
|
|
69
|
+
/** GitHub, or the git remote, failing on its own side. */
|
|
70
|
+
reason: FaultSide;
|
|
71
|
+
/** The command that failed, on one line. */
|
|
72
|
+
command: string;
|
|
73
|
+
/** The first line it printed. */
|
|
74
|
+
line: string;
|
|
75
|
+
}
|
|
66
76
|
| {
|
|
67
77
|
reason: "stopped";
|
|
68
78
|
/** When the Stop reached the Run, ISO-8601. */
|
|
@@ -96,11 +106,13 @@ export type RunStop =
|
|
|
96
106
|
* A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
|
|
97
107
|
* the Ticket — the subscription or the API key ran out of room, or the API
|
|
98
108
|
* failed on its own side after the CLI had given up retrying it — so the next
|
|
99
|
-
* one would be stopped the same way, and claiming it would spend a
|
|
109
|
+
* one would be stopped the same way, and claiming it would spend a claim, a
|
|
100
110
|
* worktree and a doomed Stage to learn what the first one already said. The Lanes still busy finish
|
|
101
111
|
* what they hold, and the Run reports what stopped it once the last of them
|
|
102
112
|
* comes back. It does not wait for the limit to reset: a human or an Operator
|
|
103
|
-
* starts the next Run, and the summary says when the limit resets.
|
|
113
|
+
* starts the next Run, and the summary says when the limit resets. A hand-off
|
|
114
|
+
* that GitHub or the remote cut short stops it the same way, for the same
|
|
115
|
+
* reason, though its Ticket is reported handed off.
|
|
104
116
|
*
|
|
105
117
|
* A Stop is the same shape with a different reason: a human asked for no more
|
|
106
118
|
* Tickets rather than the subscription, so the Lanes busy at that moment finish
|
|
@@ -109,7 +121,7 @@ export type RunStop =
|
|
|
109
121
|
* own behind where a killed one leaves all of them (ADR-0006).
|
|
110
122
|
*
|
|
111
123
|
* Before any of that, the Tickets a Run that never came back left claimed are
|
|
112
|
-
* resumed. They are not on the Frontier and never will be — the
|
|
124
|
+
* resumed. They are not on the Frontier and never will be — the claim they still
|
|
113
125
|
* wear is what keeps them off it — so this sweep is the only thing that ever
|
|
114
126
|
* picks them up again, and a free Lane takes one before it takes anything the
|
|
115
127
|
* Frontier is offering.
|
|
@@ -132,7 +144,7 @@ export async function processRun(
|
|
|
132
144
|
// Every Ticket this Run has taken. A Ticket normally leaves the candidate
|
|
133
145
|
// list by being closed or relabelled; this is what stops a Run offering one
|
|
134
146
|
// to a second Lane, whether because that write did not land or because the
|
|
135
|
-
//
|
|
147
|
+
// claim of the Lane holding it has not reached GitHub yet.
|
|
136
148
|
const taken = new Set<number>();
|
|
137
149
|
// The Lanes with a Ticket in them, by Ticket number. A Lane takes itself out
|
|
138
150
|
// of here as its Ticket ends rather than where the Run waits, so a fill pass
|
|
@@ -189,9 +201,10 @@ export async function processRun(
|
|
|
189
201
|
/**
|
|
190
202
|
* Put a Ticket in a Lane, and record what came back when it ends.
|
|
191
203
|
*
|
|
192
|
-
* The line about the Run stopping is logged by the Release that stopped it
|
|
193
|
-
* by
|
|
194
|
-
*
|
|
204
|
+
* The line about the Run stopping is logged by the Release that stopped it,
|
|
205
|
+
* or by the hand-off a fault outside the Ticket cut short, and by no other,
|
|
206
|
+
* even where a later Release outranks it on the last line. The Ticket's own
|
|
207
|
+
* release is already logged where it happened; this says the Run
|
|
195
208
|
* goes no further, so a transcript shows the Frontier was left alone rather
|
|
196
209
|
* than found empty, and a Release into a Run that an earlier Release or a
|
|
197
210
|
* Stop had stopped already claims to have stopped nothing. It leads with the
|
|
@@ -206,6 +219,17 @@ export async function processRun(
|
|
|
206
219
|
busy.delete(ticket.number);
|
|
207
220
|
ended += 1;
|
|
208
221
|
outcomes.push(outcome);
|
|
222
|
+
if (outcome.outcome === "handed-off" && outcome.fault !== undefined) {
|
|
223
|
+
// A hand-off the fault cut short stops the Run as a Release over it
|
|
224
|
+
// would, and outranks nothing that stopped it first.
|
|
225
|
+
if (runStop !== undefined) return;
|
|
226
|
+
const { side, command, line } = outcome.fault;
|
|
227
|
+
runStop = { reason: side, command, line };
|
|
228
|
+
pipeline.log?.(
|
|
229
|
+
`#${outcome.ticket} stopped the Run · ${releaseWords(side, pipeline.credential)}`,
|
|
230
|
+
);
|
|
231
|
+
return;
|
|
232
|
+
}
|
|
209
233
|
if (outcome.outcome !== "released") return;
|
|
210
234
|
if (runStop === undefined) {
|
|
211
235
|
runStop = releaseStop(outcome, pipeline.baseBranch);
|
|
@@ -319,7 +343,7 @@ function pollFailure(error: unknown): string {
|
|
|
319
343
|
|
|
320
344
|
/**
|
|
321
345
|
* The stop a Release puts on the Run: what released it, when a limit resets,
|
|
322
|
-
*
|
|
346
|
+
* which Check the base branch fails, and what GitHub or the remote failed.
|
|
323
347
|
*/
|
|
324
348
|
function releaseStop(
|
|
325
349
|
outcome: Extract<TicketOutcome, { outcome: "released" }>,
|
|
@@ -327,6 +351,9 @@ function releaseStop(
|
|
|
327
351
|
): RunStop {
|
|
328
352
|
if (outcome.cause === "api-error") return { reason: "api-error" };
|
|
329
353
|
if (outcome.cause === "out-of-budget") return { reason: "out-of-budget" };
|
|
354
|
+
if ((outcome.cause === "github" || outcome.cause === "remote") && outcome.fault !== undefined) {
|
|
355
|
+
return { reason: outcome.cause, ...outcome.fault };
|
|
356
|
+
}
|
|
330
357
|
if (outcome.failingBase !== undefined) {
|
|
331
358
|
return { reason: "failing-base", baseBranch, ...outcome.failingBase };
|
|
332
359
|
}
|
|
@@ -343,8 +370,9 @@ function releaseStop(
|
|
|
343
370
|
* it alone needs the human to act: no wait mends it, only the Console. The
|
|
344
371
|
* rate limit outranks an API failure, which says nothing of when the next Run
|
|
345
372
|
* can start, and a limit nobody was told the end of is outranked by one a
|
|
346
|
-
* Stage was told. A failing
|
|
347
|
-
* them, and so does an API budget,
|
|
373
|
+
* Stage was told. A failing base branch and a Stop stay whatever comes after
|
|
374
|
+
* them, and so does an API budget, a limit already told when it resets, and a
|
|
375
|
+
* fault of GitHub's or the remote's.
|
|
348
376
|
*/
|
|
349
377
|
function outranks(
|
|
350
378
|
outcome: Extract<TicketOutcome, { outcome: "released" }>,
|
|
@@ -425,6 +453,10 @@ async function nobodysToTake(pipeline: Pipeline, ticket: number): Promise<Skippe
|
|
|
425
453
|
* hand-off writes are outside that net: a tracker that goes down mid-Ticket
|
|
426
454
|
* would otherwise take the whole Run with it. The Ticket is reported as handed
|
|
427
455
|
* off — which, without the label, is what a human will find on the board.
|
|
456
|
+
*
|
|
457
|
+
* Unless GitHub or the remote failed on its own side, before the claim or in
|
|
458
|
+
* it: that is a fault outside the Ticket, reported released so the Run claims
|
|
459
|
+
* no more, and the Ticket is left as far as the claim got, for the next Run.
|
|
428
460
|
*/
|
|
429
461
|
async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
|
|
430
462
|
// Handed to the Ticket rather than read off its outcome, because there is no
|
|
@@ -434,6 +466,16 @@ async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
|
|
|
434
466
|
try {
|
|
435
467
|
return await processTicket(pipeline, ticket.number, notes);
|
|
436
468
|
} catch (error) {
|
|
469
|
+
if (error instanceof OutsideFault) {
|
|
470
|
+
pipeline.log?.(`#${ticket.number} stopped at setup · ${error.message}`);
|
|
471
|
+
return faultOutcome(
|
|
472
|
+
{ number: ticket.number, title: ticket.title },
|
|
473
|
+
ticket.branch,
|
|
474
|
+
"setup",
|
|
475
|
+
error,
|
|
476
|
+
notes,
|
|
477
|
+
);
|
|
478
|
+
}
|
|
437
479
|
const failure = (error as Error).message;
|
|
438
480
|
pipeline.log?.(`#${ticket.number} failed outside the hand-off path: ${failure}`);
|
|
439
481
|
return {
|
|
@@ -454,7 +496,7 @@ async function take(pipeline: Pipeline, ticket: Taken): Promise<TicketOutcome> {
|
|
|
454
496
|
*
|
|
455
497
|
* The branch is carried rather than derived, because the two ways a Run reaches
|
|
456
498
|
* a Ticket know it differently: a candidate off the Frontier has whatever its
|
|
457
|
-
* title derives to, and a stranded Ticket has the branch its
|
|
499
|
+
* title derives to, and a stranded Ticket has the branch its state file names —
|
|
458
500
|
* which is where the work actually is, whatever the title says now.
|
|
459
501
|
*/
|
|
460
502
|
interface Taken {
|
package/src/staleness.ts
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* What a Run and `init` say when something around them is from another
|
|
2
|
+
* What a Run and `init` say when something around them is from another version,
|
|
3
3
|
* and the one thing neither ever does about it.
|
|
4
4
|
*
|
|
5
5
|
* Two questions, both answered in one line and neither ever a refusal
|
|
6
|
-
* (ADR-0007): is a newer
|
|
7
|
-
* Target's conventions document from another
|
|
8
|
-
* Nothing here is a gate. A pipeline that refused to work while a newer
|
|
6
|
+
* (ADR-0007): is a newer version published than the one running, and is the
|
|
7
|
+
* Target's conventions document from another version than the one reading it.
|
|
8
|
+
* Nothing here is a gate. A pipeline that refused to work while a newer version
|
|
9
9
|
* existed would strand a Target on the night its maintainer was asleep, and
|
|
10
10
|
* Target readiness already says what a Target is refused over: the document's
|
|
11
|
-
* absence or a missing
|
|
11
|
+
* absence or a missing version stamp, never what it says or which version.
|
|
12
12
|
*
|
|
13
13
|
* A number against a number, always. A development checkout runs a commit past
|
|
14
|
-
* the
|
|
15
|
-
* stale the moment its
|
|
14
|
+
* the version it reports, so comparing anything finer would call every checkout
|
|
15
|
+
* stale the moment its version was cut.
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
18
|
import { join } from "node:path";
|
|
@@ -22,14 +22,14 @@ import { readTargetFile } from "./readiness.js";
|
|
|
22
22
|
import { isHigher, tagNumber, versionNumber } from "./version-number.js";
|
|
23
23
|
|
|
24
24
|
/**
|
|
25
|
-
* How any copy is upgraded, whatever repository it asks about: every
|
|
25
|
+
* How any copy is upgraded, whatever repository it asks about: every version
|
|
26
26
|
* is on npm before it has a GitHub Release (ADR-0007).
|
|
27
27
|
*/
|
|
28
28
|
export const UPGRADE_COMMAND = "npm install -g ticket-runner";
|
|
29
29
|
|
|
30
30
|
export interface StalenessQuestion {
|
|
31
31
|
tracker: Tracker;
|
|
32
|
-
/** The
|
|
32
|
+
/** The version this copy is, as the CLI resolved it once and handed it down. */
|
|
33
33
|
version: string;
|
|
34
34
|
/**
|
|
35
35
|
* The pipeline's own repository, as `owner/name`. Undefined where the package
|
|
@@ -40,13 +40,13 @@ export interface StalenessQuestion {
|
|
|
40
40
|
}
|
|
41
41
|
|
|
42
42
|
/**
|
|
43
|
-
* One line naming the
|
|
43
|
+
* One line naming the version that is out and the version running, and nothing
|
|
44
44
|
* at all where this copy is the latest, is ahead of it, or could not ask.
|
|
45
45
|
*
|
|
46
46
|
* What has been published as a GitHub Release is the question rather than the
|
|
47
47
|
* highest tag, because a tag a workflow has not finished publishing is not a
|
|
48
|
-
*
|
|
49
|
-
* only once npm has the
|
|
48
|
+
* version anybody can install yet. The tag workflow makes the GitHub Release
|
|
49
|
+
* only once npm has the version, so the answer names one the upgrade finds.
|
|
50
50
|
*/
|
|
51
51
|
export async function newerVersionLine({
|
|
52
52
|
tracker,
|
|
@@ -60,7 +60,7 @@ export async function newerVersionLine({
|
|
|
60
60
|
const published = latest === undefined ? undefined : tagNumber(latest);
|
|
61
61
|
if (published === undefined || !isHigher(published, own)) return undefined;
|
|
62
62
|
|
|
63
|
-
return `A newer
|
|
63
|
+
return `A newer version is out: ${published}, and this is ${own} — upgrade with \`${UPGRADE_COMMAND}\`.`;
|
|
64
64
|
}
|
|
65
65
|
|
|
66
66
|
/**
|
|
@@ -84,7 +84,7 @@ async function publishedVersionTag(
|
|
|
84
84
|
|
|
85
85
|
/**
|
|
86
86
|
* The one warning a Run prints about the conventions document in `repoRoot`,
|
|
87
|
-
* and nothing where the document is this
|
|
87
|
+
* and nothing where the document is this version's own.
|
|
88
88
|
*
|
|
89
89
|
* Worded for whichever side is behind, because only one of them can be put
|
|
90
90
|
* right from here: a document an older pipeline left is `init`'s to rewrite,
|
package/src/start.ts
CHANGED
|
@@ -3,6 +3,7 @@ import type { Config } from "./config.js";
|
|
|
3
3
|
import { type Credential, credentialRefusal, emptyBilling } from "./credential.js";
|
|
4
4
|
import { type HostKind, hostKind } from "./host.js";
|
|
5
5
|
import { BaseBranchChecks } from "./failing-base.js";
|
|
6
|
+
import { printEachOutputOnce } from "./failure-message.js";
|
|
6
7
|
import { Landing } from "./landing.js";
|
|
7
8
|
import { StandingNotes } from "./notes.js";
|
|
8
9
|
import { lockHeldMessage, unreleasedLockMessage } from "./lock.js";
|
|
@@ -19,6 +20,7 @@ import { conventionsWarning, newerVersionLine } from "./staleness.js";
|
|
|
19
20
|
import { type StopSource, StopSignal, listenForStop } from "./stop.js";
|
|
20
21
|
import { startupMessages } from "./startup.js";
|
|
21
22
|
import { runSummary } from "./templates.js";
|
|
23
|
+
import { resolveTranscriptHome } from "./transcript-home.js";
|
|
22
24
|
|
|
23
25
|
/**
|
|
24
26
|
* Everything between the arguments and the work: the two refusals a Run can
|
|
@@ -57,12 +59,12 @@ export interface StartOptions {
|
|
|
57
59
|
workspace: Workspace;
|
|
58
60
|
runId: string;
|
|
59
61
|
/**
|
|
60
|
-
* The
|
|
62
|
+
* The version this Run is, resolved once in the CLI (ADR-0007). Everything
|
|
61
63
|
* the Run stamps takes it from here, so every stamp says the same thing.
|
|
62
64
|
*/
|
|
63
65
|
version: string;
|
|
64
66
|
/**
|
|
65
|
-
* The pipeline's own repository, as `owner/name`, which the newer-
|
|
67
|
+
* The pipeline's own repository, as `owner/name`, which the newer-version
|
|
66
68
|
* notice is looked up against; see {@link import("./staleness.js")}.
|
|
67
69
|
*/
|
|
68
70
|
repository?: string | undefined;
|
|
@@ -85,7 +87,7 @@ export interface StartOptions {
|
|
|
85
87
|
*
|
|
86
88
|
* Every refusal comes before the lock: an `--api-key` the Host cannot honour,
|
|
87
89
|
* a Target `init` has not set up, one whose remote lacks what `init` wrote,
|
|
88
|
-
* one holding
|
|
90
|
+
* one holding state files an earlier pipeline left in the checkout, and one
|
|
89
91
|
* with nothing to gate a merge. None is a Run that went wrong, so none should
|
|
90
92
|
* leave a lock behind for the next one to reclaim.
|
|
91
93
|
*/
|
|
@@ -101,7 +103,7 @@ export async function startRun(given: StartOptions): Promise<number> {
|
|
|
101
103
|
const env = options.env ?? process.env;
|
|
102
104
|
|
|
103
105
|
// First, because it asks nothing of the Target: the Host either can or
|
|
104
|
-
// cannot
|
|
106
|
+
// cannot bill the Stages to what the Run was started with.
|
|
105
107
|
const credential: Credential = options.work.apiKey === true ? "api-key" : "subscription";
|
|
106
108
|
const host = hostKind(env);
|
|
107
109
|
const refusedCredential = credentialRefusal(credential, host, env);
|
|
@@ -135,9 +137,9 @@ export async function startRun(given: StartOptions): Promise<number> {
|
|
|
135
137
|
}
|
|
136
138
|
|
|
137
139
|
const { refusal, warnings } = startupMessages(config);
|
|
138
|
-
// Which
|
|
140
|
+
// Which version the document names is a warning and never a refusal, so it
|
|
139
141
|
// joins the config's own: readiness has already refused a copy naming none,
|
|
140
|
-
// and one naming another
|
|
142
|
+
// and one naming another version is nothing a Run is worse for (ADR-0007).
|
|
141
143
|
const stale = conventionsWarning(repoRoot, options.version);
|
|
142
144
|
for (const warning of [...warnings, ...(stale === undefined ? [] : [stale])]) {
|
|
143
145
|
error(`warning: ${warning}`);
|
|
@@ -174,7 +176,7 @@ export async function startRun(given: StartOptions): Promise<number> {
|
|
|
174
176
|
const stopping = new StopSignal();
|
|
175
177
|
const deafen = listenForStop(stopping, options.signals);
|
|
176
178
|
try {
|
|
177
|
-
return await execute(options, { credential,
|
|
179
|
+
return await execute(options, { credential, baseBranch, host }, log, stopping);
|
|
178
180
|
} finally {
|
|
179
181
|
// The lock goes first: SIGTERM between the two is a kill again, and a kill
|
|
180
182
|
// that leaves the lock behind costs the next Run a stale holder to reclaim,
|
|
@@ -195,13 +197,17 @@ async function execute(
|
|
|
195
197
|
options: StartOptions,
|
|
196
198
|
{
|
|
197
199
|
credential,
|
|
198
|
-
host,
|
|
199
200
|
baseBranch,
|
|
200
|
-
|
|
201
|
-
|
|
201
|
+
host,
|
|
202
|
+
}: { credential: Credential; baseBranch: string; host: HostKind },
|
|
203
|
+
print: (line: string) => void,
|
|
202
204
|
stopping: StopSignal,
|
|
203
205
|
): Promise<number> {
|
|
204
206
|
const { work, repoRoot, config, tracker, runner, workspace, runId, version } = options;
|
|
207
|
+
// Every event of the Run goes through this, and one cause tends to fail
|
|
208
|
+
// several of them with the same output, so each output is printed once. The
|
|
209
|
+
// summary is printed as it is: it is one block, written once.
|
|
210
|
+
const log = printEachOutputOnce(print);
|
|
205
211
|
|
|
206
212
|
// Before the first Stage, and before the tracker is asked anything: a
|
|
207
213
|
// transcript has to sit beside the pipeline that wrote it, and the Run
|
|
@@ -211,7 +217,7 @@ async function execute(
|
|
|
211
217
|
try {
|
|
212
218
|
writeRunVersion(repoRoot, runId, version);
|
|
213
219
|
} catch (error) {
|
|
214
|
-
log(`could not record the
|
|
220
|
+
log(`could not record the version beside the transcripts: ${(error as Error).message}`);
|
|
215
221
|
}
|
|
216
222
|
|
|
217
223
|
// Asked once, and said twice: at the top of the log a human watches, and
|
|
@@ -225,6 +231,9 @@ async function execute(
|
|
|
225
231
|
// Once per Run: only a Target that is the pipeline's own repository
|
|
226
232
|
// has a checkout that is the pipeline, and every Stage is told which it is in.
|
|
227
233
|
const selfHosted = await isPipelineRepository(tracker, options.repository);
|
|
234
|
+
// Once per Run as well: whether the Target is public is read here and no
|
|
235
|
+
// later, so every hand-off of the Run keeps its transcripts in one place.
|
|
236
|
+
const transcriptHome = await resolveTranscriptHome({ config, tracker, host });
|
|
228
237
|
|
|
229
238
|
const pipeline: Pipeline = {
|
|
230
239
|
tracker,
|
|
@@ -234,7 +243,6 @@ async function execute(
|
|
|
234
243
|
repoRoot,
|
|
235
244
|
runId,
|
|
236
245
|
version,
|
|
237
|
-
host,
|
|
238
246
|
credential,
|
|
239
247
|
billing: emptyBilling(),
|
|
240
248
|
baseBranch,
|
|
@@ -249,12 +257,17 @@ async function execute(
|
|
|
249
257
|
// branch run it at their merge-base once between them.
|
|
250
258
|
baseChecks: new BaseBranchChecks(),
|
|
251
259
|
selfHosted,
|
|
260
|
+
transcriptHome: transcriptHome.home,
|
|
252
261
|
log,
|
|
253
262
|
};
|
|
254
263
|
|
|
255
264
|
const startedAt = Date.now();
|
|
256
265
|
log(opening(runId, work, config.lanes));
|
|
257
266
|
if (newer !== undefined) log(newer);
|
|
267
|
+
if (transcriptHome.said !== undefined) log(transcriptHome.said);
|
|
268
|
+
// Before the first claim, on any Host: a shallow clone refuses every move of
|
|
269
|
+
// its base branch a rebase needs, and would hand off each Ticket there.
|
|
270
|
+
if (await workspace.unshallow()) log("the clone was shallow, so its full history was fetched");
|
|
258
271
|
const summary = (outcomes: TicketOutcome[], stop: RunStop) =>
|
|
259
272
|
runSummary({
|
|
260
273
|
version,
|
|
@@ -268,12 +281,12 @@ async function execute(
|
|
|
268
281
|
});
|
|
269
282
|
|
|
270
283
|
const { outcomes, stop } = await processRun(pipeline, stopping, work.tickets);
|
|
271
|
-
|
|
284
|
+
print(`\n${summary(outcomes, stop)}`);
|
|
272
285
|
return exitCode(outcomes, work.tickets !== undefined);
|
|
273
286
|
}
|
|
274
287
|
|
|
275
288
|
/**
|
|
276
|
-
* Why a Run will not start over
|
|
289
|
+
* Why a Run will not start over state files a pipeline before the state branch
|
|
277
290
|
* left in the checkout, and what the human does about it.
|
|
278
291
|
*
|
|
279
292
|
* Each is a Ticket that pipeline could resume and this one cannot see, since
|
|
@@ -284,9 +297,9 @@ async function execute(
|
|
|
284
297
|
function localStateMessage(tickets: number[]): string {
|
|
285
298
|
const named = tickets.map((ticket) => `#${ticket}`).join(", ");
|
|
286
299
|
return (
|
|
287
|
-
`${LOCAL_STATE_DIR} holds
|
|
300
|
+
`${LOCAL_STATE_DIR} holds state files for ${named}, which this version no longer reads: ` +
|
|
288
301
|
"a Ticket's resume state lives on the Target's remote now. Finish those Tickets with " +
|
|
289
|
-
`the
|
|
302
|
+
`the version that wrote the files, or hand them to a human, then delete ${LOCAL_STATE_DIR} ` +
|
|
290
303
|
"and run again."
|
|
291
304
|
);
|
|
292
305
|
}
|
package/src/stranded.ts
CHANGED
|
@@ -5,26 +5,26 @@ import type { StateFile, Workspace } from "./ports/workspace.js";
|
|
|
5
5
|
* The Tickets a Run that never came back left claimed, and how a later Run finds
|
|
6
6
|
* them.
|
|
7
7
|
*
|
|
8
|
-
* A Run killed mid-Ticket releases nothing: the
|
|
9
|
-
*
|
|
8
|
+
* A Run killed mid-Ticket releases nothing: the claim stays on the board, the
|
|
9
|
+
* state file on the Target's remote, and the branch on the remote as of its
|
|
10
10
|
* last committing Stage. The Frontier cannot see such a Ticket — it is claimed —
|
|
11
11
|
* so without this nobody would ever pick it up again, on this Host or another.
|
|
12
12
|
*
|
|
13
13
|
* Nothing here needs a process id. The Run lock allows one Run at a time
|
|
14
|
-
* (ADR-0004), so a Run holding the lock that finds a
|
|
15
|
-
* still carries this user's
|
|
14
|
+
* (ADR-0004), so a Run holding the lock that finds a state file whose Ticket
|
|
15
|
+
* still carries this user's claim knows the Run that wrote it is gone.
|
|
16
16
|
*/
|
|
17
17
|
|
|
18
18
|
/** A Ticket still claimed by a Run that never came back, and where its work is. */
|
|
19
19
|
export interface StrandedTicket {
|
|
20
20
|
number: number;
|
|
21
21
|
title: string;
|
|
22
|
-
/** The branch the
|
|
22
|
+
/** The branch the state file named, which is where the work actually is. */
|
|
23
23
|
branch: string;
|
|
24
24
|
}
|
|
25
25
|
|
|
26
26
|
/**
|
|
27
|
-
* Whether this issue carries this user's
|
|
27
|
+
* Whether this issue carries this user's claim: assigned to them and labelled
|
|
28
28
|
* `in-progress`, which is what {@link import("./orchestrator.js").processTicket}
|
|
29
29
|
* writes when it claims a Ticket. Both halves, because a Ticket holding only one
|
|
30
30
|
* of them is one nobody can say is being worked on.
|
|
@@ -35,12 +35,12 @@ export function holdsClaim(issue: Issue, user: string, inProgress: string): bool
|
|
|
35
35
|
|
|
36
36
|
export interface StrandedSweep {
|
|
37
37
|
tracker: Tracker;
|
|
38
|
-
/** Where the
|
|
38
|
+
/** Where the state is kept. */
|
|
39
39
|
workspace: Workspace;
|
|
40
40
|
/** The `in-progress` label, as this repo configured it. */
|
|
41
41
|
inProgress: string;
|
|
42
42
|
/**
|
|
43
|
-
* The Tickets a narrowed Run was given. The
|
|
43
|
+
* The Tickets a narrowed Run was given. The state of every other Ticket is
|
|
44
44
|
* not read, asked about or removed: it is the next unnarrowed Run's.
|
|
45
45
|
*/
|
|
46
46
|
only?: ReadonlySet<number>;
|
|
@@ -48,13 +48,13 @@ export interface StrandedSweep {
|
|
|
48
48
|
}
|
|
49
49
|
|
|
50
50
|
/**
|
|
51
|
-
* Sweep the
|
|
51
|
+
* Sweep the state the Workspace keeps on the remote for the Tickets this
|
|
52
52
|
* pipeline still holds, whichever Host's Run claimed them.
|
|
53
53
|
*
|
|
54
|
-
* Four things can be behind a
|
|
54
|
+
* Four things can be behind a state file, and only one of them is stranded:
|
|
55
55
|
*
|
|
56
|
-
* - the Ticket still carries this user's
|
|
57
|
-
* - the
|
|
56
|
+
* - the Ticket still carries this user's claim — stranded, and resumed in place
|
|
57
|
+
* - the claim has come off — a released Ticket, or one handed to a human, and
|
|
58
58
|
* neither is the sweep's: the Frontier picks up whichever of them is labelled
|
|
59
59
|
* `ready-for-agent`, and a `ready-for-human` Ticket waits, inert, until a
|
|
60
60
|
* human relabels it. Both are passed over in silence
|
|
@@ -118,19 +118,19 @@ export async function strandedTickets(sweep: StrandedSweep): Promise<StrandedTic
|
|
|
118
118
|
}
|
|
119
119
|
|
|
120
120
|
/**
|
|
121
|
-
* A
|
|
121
|
+
* A state file nothing here can resume from, named rather than dropped.
|
|
122
122
|
*
|
|
123
|
-
* The file and the
|
|
123
|
+
* The file and the claim are left exactly where they are. A Ticket carrying a
|
|
124
124
|
* file this pipeline cannot use is one a newer pipeline probably wrote, and
|
|
125
|
-
* deleting either would take a
|
|
125
|
+
* deleting either would take a claim off the board that the machine which
|
|
126
126
|
* understands the file is still counting on (ADR-0007). So the sweep says the
|
|
127
|
-
* Ticket number and whichever
|
|
127
|
+
* Ticket number and whichever version the file names, and a human decides.
|
|
128
128
|
*
|
|
129
129
|
* `cannot use` rather than `cannot read`, because the two files that land here
|
|
130
130
|
* are not the same: one will not parse at all, and one parses but names another
|
|
131
|
-
* Ticket than the file it is in, which no
|
|
131
|
+
* Ticket than the file it is in, which no version would resume either.
|
|
132
132
|
*/
|
|
133
133
|
function unreadableLine(file: Extract<StateFile, { readable: false }>): string {
|
|
134
|
-
const wrote = file.version === undefined ? "naming no
|
|
135
|
-
return `#${file.ticket} has a
|
|
134
|
+
const wrote = file.version === undefined ? "naming no version" : `written by ${file.version}`;
|
|
135
|
+
return `#${file.ticket} has a state file this version cannot use, ${wrote}; it and the claim are left alone`;
|
|
136
136
|
}
|