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
package/src/staleness.ts
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a Run and `init` say when something around them is from another Version,
|
|
3
|
+
* and the one thing neither ever does about it.
|
|
4
|
+
*
|
|
5
|
+
* Two questions, both answered in one line and neither ever a refusal
|
|
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
|
+
* existed would strand a Target on the night its maintainer was asleep, and
|
|
10
|
+
* Target readiness already says what a Target is refused over: the document's
|
|
11
|
+
* absence or a missing Version stamp, never what it says or which Version.
|
|
12
|
+
*
|
|
13
|
+
* A number against a number, always. A development checkout runs a commit past
|
|
14
|
+
* the Version it reports, so comparing anything finer would call every checkout
|
|
15
|
+
* stale the moment its Version was cut.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { join } from "node:path";
|
|
19
|
+
import { CONVENTIONS_PATH, conventionsMark } from "./conventions.js";
|
|
20
|
+
import type { Tracker } from "./ports/tracker.js";
|
|
21
|
+
import { readTargetFile } from "./readiness.js";
|
|
22
|
+
import { isHigher, tagNumber, versionNumber } from "./version-number.js";
|
|
23
|
+
|
|
24
|
+
export interface StalenessQuestion {
|
|
25
|
+
tracker: Tracker;
|
|
26
|
+
/** The Version this copy is, as the CLI resolved it once and handed it down. */
|
|
27
|
+
version: string;
|
|
28
|
+
/**
|
|
29
|
+
* The pipeline's own repository, as `owner/name`. Undefined where the package
|
|
30
|
+
* names none, which asks nothing of the tracker at all: the lookup has no
|
|
31
|
+
* repository to be about, and a Run is owed silence rather than a guess.
|
|
32
|
+
*/
|
|
33
|
+
repository?: string | undefined;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* One line naming the Version that is out and the Version running, and nothing
|
|
38
|
+
* at all where this copy is the latest, is ahead of it, or could not ask.
|
|
39
|
+
*
|
|
40
|
+
* What has been published as a GitHub Release is the question rather than the
|
|
41
|
+
* highest tag, because a tag a workflow has not finished publishing is not a
|
|
42
|
+
* Version anybody can install yet.
|
|
43
|
+
*/
|
|
44
|
+
export async function newerVersionLine({
|
|
45
|
+
tracker,
|
|
46
|
+
version,
|
|
47
|
+
repository,
|
|
48
|
+
}: StalenessQuestion): Promise<string | undefined> {
|
|
49
|
+
const own = versionNumber(version);
|
|
50
|
+
if (own === undefined || repository === undefined) return undefined;
|
|
51
|
+
|
|
52
|
+
const latest = await publishedVersionTag(tracker, repository);
|
|
53
|
+
const published = latest === undefined ? undefined : tagNumber(latest);
|
|
54
|
+
if (published === undefined || !isHigher(published, own)) return undefined;
|
|
55
|
+
|
|
56
|
+
return `A newer Version is out: ${published}, and this is ${own} — upgrade with \`npm install -g "github:${repository}#semver:*"\`.`;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Asking, where asking is possible, and nothing where it is not.
|
|
61
|
+
*
|
|
62
|
+
* The port answers with nothing when it could not reach GitHub, and this
|
|
63
|
+
* catches what it could not answer at all — a `gh` that is not installed, a
|
|
64
|
+
* tracker that threw. Both are the same answer here, because the one thing this
|
|
65
|
+
* may not do is stop a Run.
|
|
66
|
+
*/
|
|
67
|
+
async function publishedVersionTag(
|
|
68
|
+
tracker: Tracker,
|
|
69
|
+
repository: string,
|
|
70
|
+
): Promise<string | undefined> {
|
|
71
|
+
try {
|
|
72
|
+
return await tracker.latestVersionTag(repository);
|
|
73
|
+
} catch {
|
|
74
|
+
return undefined;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* The one warning a Run prints about the conventions document in `repoRoot`,
|
|
80
|
+
* and nothing where the document is this Version's own.
|
|
81
|
+
*
|
|
82
|
+
* Worded for whichever side is behind, because only one of them can be put
|
|
83
|
+
* right from here: a document an older pipeline left is `init`'s to rewrite,
|
|
84
|
+
* and a document a newer one left is the install's to catch up with. A copy
|
|
85
|
+
* carrying no mark at all is not this function's: readiness refuses it before a
|
|
86
|
+
* Run gets this far.
|
|
87
|
+
*/
|
|
88
|
+
export function conventionsWarning(repoRoot: string, version: string): string | undefined {
|
|
89
|
+
const own = versionNumber(version);
|
|
90
|
+
if (own === undefined) return undefined;
|
|
91
|
+
|
|
92
|
+
const document = readTargetFile(join(repoRoot, CONVENTIONS_PATH));
|
|
93
|
+
const mark = conventionsMark(document);
|
|
94
|
+
if (mark === undefined || mark === own) return undefined;
|
|
95
|
+
|
|
96
|
+
const subject = `This Target's \`${CONVENTIONS_PATH}\``;
|
|
97
|
+
if (isHigher(mark, own)) {
|
|
98
|
+
return `${subject} was left by ${mark}, and this Run is ${own} — upgrade \`ticket-runner\`.`;
|
|
99
|
+
}
|
|
100
|
+
return `${subject} was left by ${mark}, and this Run is ${own} — run \`ticket-runner init\` here to bring it up to date.`;
|
|
101
|
+
}
|
package/src/start.ts
ADDED
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
import { resolveBaseBranch } from "./base-branch.js";
|
|
2
|
+
import type { Config } from "./config.js";
|
|
3
|
+
import { hostKind } from "./host.js";
|
|
4
|
+
import { Landing } from "./landing.js";
|
|
5
|
+
import { StandingNotes } from "./notes.js";
|
|
6
|
+
import { lockHeldMessage, unreleasedLockMessage } from "./lock.js";
|
|
7
|
+
import type { Pipeline, TicketOutcome } from "./orchestrator.js";
|
|
8
|
+
import type { AgentRunner } from "./ports/agent-runner.js";
|
|
9
|
+
import type { Tracker } from "./ports/tracker.js";
|
|
10
|
+
import type { Workspace } from "./ports/workspace.js";
|
|
11
|
+
import { readinessRefusal } from "./readiness.js";
|
|
12
|
+
import { LOCAL_STATE_DIR, localStateTickets } from "./resume.js";
|
|
13
|
+
import { writeRunVersion } from "./run-log.js";
|
|
14
|
+
import { type RunStop, processRun } from "./run.js";
|
|
15
|
+
import { isPipelineRepository } from "./self-hosting.js";
|
|
16
|
+
import { conventionsWarning, newerVersionLine } from "./staleness.js";
|
|
17
|
+
import { type StopSource, StopSignal, listenForStop } from "./stop.js";
|
|
18
|
+
import { startupMessages } from "./startup.js";
|
|
19
|
+
import { runSummary } from "./templates.js";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Everything between the arguments and the work: the two refusals a Run can
|
|
23
|
+
* meet before it starts, the Run lock, and the summary it ends with.
|
|
24
|
+
*
|
|
25
|
+
* It lives here rather than in the CLI so that a refusal is provable — a test
|
|
26
|
+
* drives a whole `run` against a temporary Target and a fake Tracker and asserts
|
|
27
|
+
* that neither the lock nor the Frontier was ever reached. The CLI is left with
|
|
28
|
+
* the arguments, the Target's root and the three adapters.
|
|
29
|
+
*/
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* What this invocation was asked to do, once the arguments are understood.
|
|
33
|
+
*
|
|
34
|
+
* A Run may be told how many Lanes it has, which wins over the Target's config
|
|
35
|
+
* because how many Tickets a Host can carry at once is the Host's business, not
|
|
36
|
+
* the Target's (ADR-0008). It may also be narrowed to the Tickets a human
|
|
37
|
+
* named, ascending and each once; with none it drains the whole Frontier.
|
|
38
|
+
*/
|
|
39
|
+
export interface Work {
|
|
40
|
+
command: "run";
|
|
41
|
+
lanes?: number;
|
|
42
|
+
tickets?: number[];
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface StartOptions {
|
|
46
|
+
work: Work;
|
|
47
|
+
repoRoot: string;
|
|
48
|
+
config: Config;
|
|
49
|
+
tracker: Tracker;
|
|
50
|
+
runner: AgentRunner;
|
|
51
|
+
workspace: Workspace;
|
|
52
|
+
runId: string;
|
|
53
|
+
/**
|
|
54
|
+
* The Version this Run is, resolved once in the CLI (ADR-0007). Everything
|
|
55
|
+
* the Run stamps takes it from here, so every stamp says the same thing.
|
|
56
|
+
*/
|
|
57
|
+
version: string;
|
|
58
|
+
/**
|
|
59
|
+
* The pipeline's own repository, as `owner/name`, which the newer-Version
|
|
60
|
+
* notice is looked up against; see {@link import("./staleness.js")}.
|
|
61
|
+
*/
|
|
62
|
+
repository?: string | undefined;
|
|
63
|
+
/** The command line the Run lock records, for whoever loses it. */
|
|
64
|
+
command: string;
|
|
65
|
+
log?: (line: string) => void;
|
|
66
|
+
/** Warnings and refusals, which the CLI puts on stderr as it always has. */
|
|
67
|
+
error?: (line: string) => void;
|
|
68
|
+
/** Where SIGTERM comes from. The process itself, unless a test is watching. */
|
|
69
|
+
signals?: StopSource;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Start a Run, and answer with the exit code it earned.
|
|
74
|
+
*
|
|
75
|
+
* Every refusal comes before the lock: a Target `init` has not set up, one
|
|
76
|
+
* holding State files an earlier pipeline left in the checkout, and one with
|
|
77
|
+
* nothing to gate a merge. None is a Run that went wrong, so none should leave
|
|
78
|
+
* a lock behind for the next one to reclaim.
|
|
79
|
+
*/
|
|
80
|
+
export async function startRun(given: StartOptions): Promise<number> {
|
|
81
|
+
// The count a Run was told is folded into the config once, here, so
|
|
82
|
+
// nothing downstream has two Lane counts to choose between.
|
|
83
|
+
const { lanes } = given.work;
|
|
84
|
+
const options =
|
|
85
|
+
lanes === undefined ? given : { ...given, config: { ...given.config, lanes } };
|
|
86
|
+
const { repoRoot, config, tracker, workspace } = options;
|
|
87
|
+
const log = options.log ?? ((line: string) => console.log(line));
|
|
88
|
+
const error = options.error ?? ((line: string) => console.error(line));
|
|
89
|
+
|
|
90
|
+
const notReady = await readinessRefusal({ repoRoot, labels: config.labels, tracker });
|
|
91
|
+
if (notReady !== undefined) {
|
|
92
|
+
error(notReady);
|
|
93
|
+
return 2;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const leftBehind = localStateTickets(repoRoot);
|
|
97
|
+
if (leftBehind.length > 0) {
|
|
98
|
+
error(localStateMessage(leftBehind));
|
|
99
|
+
return 2;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const { refusal, warnings } = startupMessages(config);
|
|
103
|
+
// Which Version the document names is a warning and never a refusal, so it
|
|
104
|
+
// joins the config's own: readiness has already refused a copy naming none,
|
|
105
|
+
// and one naming another Version is nothing a Run is worse for (ADR-0007).
|
|
106
|
+
const stale = conventionsWarning(repoRoot, options.version);
|
|
107
|
+
for (const warning of [...warnings, ...(stale === undefined ? [] : [stale])]) {
|
|
108
|
+
error(`warning: ${warning}`);
|
|
109
|
+
}
|
|
110
|
+
if (refusal !== undefined) {
|
|
111
|
+
error(refusal);
|
|
112
|
+
return 2;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// Taken before the first write, so two Runs never both claim a Ticket, and
|
|
116
|
+
// on the Target's remote, so that holds whichever Host each Run is on.
|
|
117
|
+
const claim = {
|
|
118
|
+
pid: process.pid,
|
|
119
|
+
command: options.command,
|
|
120
|
+
runId: options.runId,
|
|
121
|
+
startedAt: new Date().toISOString(),
|
|
122
|
+
};
|
|
123
|
+
const found = await workspace.takeRunLock(claim);
|
|
124
|
+
// A lock whose Run on this Host has gone is taken over: the alternative is a
|
|
125
|
+
// Run ended by Ctrl+C blocking the Target until a human releases a lock they
|
|
126
|
+
// have never heard of. One held from another Host is never abandoned, and
|
|
127
|
+
// waits for that human.
|
|
128
|
+
const lock = found.outcome === "abandoned" ? await workspace.takeOverRunLock(claim) : found;
|
|
129
|
+
if (lock.outcome === "held") {
|
|
130
|
+
error(lockHeldMessage(lock));
|
|
131
|
+
return 2;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
// Listened for only while the lock is held, because the lock is what names
|
|
135
|
+
// the process a human sends SIGTERM to, and only a Run holding Tickets has
|
|
136
|
+
// anything to finish. Stopped again in the same breath as the lock: a signal
|
|
137
|
+
// handler holds the event loop open, so a Run still listening would print its
|
|
138
|
+
// summary and never exit.
|
|
139
|
+
const stopping = new StopSignal();
|
|
140
|
+
const deafen = listenForStop(stopping, options.signals);
|
|
141
|
+
try {
|
|
142
|
+
return await execute(options, log, stopping);
|
|
143
|
+
} finally {
|
|
144
|
+
// The lock goes first: SIGTERM between the two is a kill again, and a kill
|
|
145
|
+
// that leaves the lock behind costs the next Run a stale holder to reclaim,
|
|
146
|
+
// where one that leaves the Stop unread costs nothing at all.
|
|
147
|
+
try {
|
|
148
|
+
await workspace.releaseRunLock();
|
|
149
|
+
} catch (failure) {
|
|
150
|
+
// Reported, and the Run's own exit code kept: every Ticket it took has
|
|
151
|
+
// already ended, and the lock left behind is the one thing to tell.
|
|
152
|
+
error(unreleasedLockMessage(failure instanceof Error ? failure.message : String(failure)));
|
|
153
|
+
} finally {
|
|
154
|
+
deafen();
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
async function execute(
|
|
160
|
+
options: StartOptions,
|
|
161
|
+
log: (line: string) => void,
|
|
162
|
+
stopping: StopSignal,
|
|
163
|
+
): Promise<number> {
|
|
164
|
+
const { work, repoRoot, config, tracker, runner, workspace, runId, version } = options;
|
|
165
|
+
|
|
166
|
+
// Before the first Stage, and before the tracker is asked anything: a
|
|
167
|
+
// transcript has to sit beside the pipeline that wrote it, and the Run
|
|
168
|
+
// summary that says the same thing is a terminal these files outlive.
|
|
169
|
+
// Logged and nothing more when it fails — a directory that will not take a
|
|
170
|
+
// one-line file is no reason to take no Ticket at all.
|
|
171
|
+
try {
|
|
172
|
+
writeRunVersion(repoRoot, runId, version);
|
|
173
|
+
} catch (error) {
|
|
174
|
+
log(`could not record the Version beside the transcripts: ${(error as Error).message}`);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
// Asked once, and said twice: at the top of the log a human watches, and
|
|
178
|
+
// again at the head of the summary they scroll back to hours later.
|
|
179
|
+
const newer = await newerVersionLine({
|
|
180
|
+
tracker,
|
|
181
|
+
version,
|
|
182
|
+
repository: options.repository,
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
// Once per Run, before any Ticket: every branch, rebase, pull request and
|
|
186
|
+
// pull of this Run goes to the branch this answers.
|
|
187
|
+
const baseBranch = await resolveBaseBranch(tracker, config);
|
|
188
|
+
|
|
189
|
+
// Once per Run as well: only a Target that is the pipeline's own repository
|
|
190
|
+
// has a checkout that is the pipeline, and every Stage is told which it is in.
|
|
191
|
+
const selfHosted = await isPipelineRepository(tracker, options.repository);
|
|
192
|
+
|
|
193
|
+
const pipeline: Pipeline = {
|
|
194
|
+
tracker,
|
|
195
|
+
runner,
|
|
196
|
+
workspace,
|
|
197
|
+
config,
|
|
198
|
+
repoRoot,
|
|
199
|
+
runId,
|
|
200
|
+
version,
|
|
201
|
+
host: hostKind(process.env),
|
|
202
|
+
baseBranch,
|
|
203
|
+
// Once per Run as well, and for the same reason: the Tickets of one Run
|
|
204
|
+
// take turns between their rebase and their merge, and a Landing made per
|
|
205
|
+
// Ticket would be a queue of one every time (ADR-0005).
|
|
206
|
+
landing: new Landing(),
|
|
207
|
+
// Once per Run as well: the Notes of every Ticket the night takes land on
|
|
208
|
+
// one issue, and the Run looks it up once however many it writes.
|
|
209
|
+
standingNotes: new StandingNotes(),
|
|
210
|
+
selfHosted,
|
|
211
|
+
log,
|
|
212
|
+
};
|
|
213
|
+
|
|
214
|
+
const startedAt = Date.now();
|
|
215
|
+
log(opening(runId, work, config.lanes));
|
|
216
|
+
if (newer !== undefined) log(newer);
|
|
217
|
+
const summary = (outcomes: TicketOutcome[], stop: RunStop) =>
|
|
218
|
+
runSummary({
|
|
219
|
+
version,
|
|
220
|
+
runId,
|
|
221
|
+
durationMs: Date.now() - startedAt,
|
|
222
|
+
outcomes,
|
|
223
|
+
...(newer === undefined ? {} : { newer }),
|
|
224
|
+
stop,
|
|
225
|
+
});
|
|
226
|
+
|
|
227
|
+
const { outcomes, stop } = await processRun(pipeline, stopping, work.tickets);
|
|
228
|
+
log(`\n${summary(outcomes, stop)}`);
|
|
229
|
+
return exitCode(outcomes, work.tickets !== undefined);
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
/**
|
|
233
|
+
* Why a Run will not start over State files a pipeline before the state branch
|
|
234
|
+
* left in the checkout, and what the human does about it.
|
|
235
|
+
*
|
|
236
|
+
* Each is a Ticket that pipeline could resume and this one cannot see, since
|
|
237
|
+
* resume state lives on the Target's remote now and nothing migrates it
|
|
238
|
+
* (ADR-0004). A Run that went ahead would take a released one from the top, over
|
|
239
|
+
* the branch it left, and never sweep a stranded one at all.
|
|
240
|
+
*/
|
|
241
|
+
function localStateMessage(tickets: number[]): string {
|
|
242
|
+
const named = tickets.map((ticket) => `#${ticket}`).join(", ");
|
|
243
|
+
return (
|
|
244
|
+
`${LOCAL_STATE_DIR} holds State files for ${named}, which this Version no longer reads: ` +
|
|
245
|
+
"a Ticket's resume state lives on the Target's remote now. Finish those Tickets with " +
|
|
246
|
+
`the Version that wrote the files, or hand them to a human, then delete ${LOCAL_STATE_DIR} ` +
|
|
247
|
+
"and run again."
|
|
248
|
+
);
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* The line a Run opens with, and the only place the Lane count is said out loud.
|
|
253
|
+
*
|
|
254
|
+
* Everything after it that is about a Ticket starts with that Ticket's number,
|
|
255
|
+
* so a transcript of interleaved Lanes can be read one Ticket at a time; the
|
|
256
|
+
* lines about the Run itself — this one, and the summary — carry no number.
|
|
257
|
+
*
|
|
258
|
+
* A narrowed Run names the Tickets it was given after its Lanes, ascending,
|
|
259
|
+
* which is also the order it takes the ones the Frontier offers in.
|
|
260
|
+
*/
|
|
261
|
+
function opening(runId: string, work: Work, lanes: number): string {
|
|
262
|
+
const subject = [
|
|
263
|
+
`${lanes} ${lanes === 1 ? "lane" : "lanes"}`,
|
|
264
|
+
...(work.tickets === undefined ? [] : [work.tickets.map((ticket) => `#${ticket}`).join(" ")]),
|
|
265
|
+
];
|
|
266
|
+
return `ticket-runner run ${runId} · ${subject.join(" · ")}`;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* A hand-off is what the exit code reports first, because it is the one outcome
|
|
271
|
+
* that asks a human for something. A released Ticket was taken all the same:
|
|
272
|
+
* the rate limit resets and a later Run resumes it.
|
|
273
|
+
*
|
|
274
|
+
* A narrowed Run that took none of the Tickets it was given — every one
|
|
275
|
+
* skipped, blocked, or a mix — took nothing at all, which is the same nothing a
|
|
276
|
+
* lock or a bad argument reports. A Run that was not narrowed and skipped every
|
|
277
|
+
* candidate still exits 0: draining a Frontier of unusable Tickets is the job,
|
|
278
|
+
* not a failure to do it.
|
|
279
|
+
*/
|
|
280
|
+
function exitCode(outcomes: TicketOutcome[], narrowed: boolean): number {
|
|
281
|
+
if (outcomes.some((outcome) => outcome.outcome === "handed-off")) return 1;
|
|
282
|
+
if (narrowed && outcomes.every((outcome) => outcome.outcome === "skipped")) return 2;
|
|
283
|
+
return 0;
|
|
284
|
+
}
|
package/src/startup.ts
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { CONFIG_FILENAME, type Config } from "./config.js";
|
|
2
|
+
|
|
3
|
+
export interface StartupMessages {
|
|
4
|
+
/** When set, the Run must not start; this explains why. */
|
|
5
|
+
refusal?: string;
|
|
6
|
+
warnings: string[];
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* What the human has to be told before a Run starts: a refusal when nothing
|
|
11
|
+
* would gate a merge, and a warning for each gate they turned off on purpose.
|
|
12
|
+
*/
|
|
13
|
+
export function startupMessages(config: Config): StartupMessages {
|
|
14
|
+
const warnings: string[] = [];
|
|
15
|
+
if (!config.gates.checks) {
|
|
16
|
+
warnings.push("Checks gate off: nothing deterministic will gate a merge.");
|
|
17
|
+
}
|
|
18
|
+
if (!config.gates.ci) {
|
|
19
|
+
warnings.push("CI gate off: a pull request with no checks will still be merged.");
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
if (config.gates.checks && config.checks.length === 0) {
|
|
23
|
+
return {
|
|
24
|
+
refusal: [
|
|
25
|
+
"No Check commands are configured and none could be inferred from package.json.",
|
|
26
|
+
`Add them to \`checks\` in ${CONFIG_FILENAME}, add \`test\` and \`typecheck\` scripts to package.json,`,
|
|
27
|
+
`or set \`gates.checks\` to false in ${CONFIG_FILENAME} to run without a net.`,
|
|
28
|
+
].join(" "),
|
|
29
|
+
warnings,
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
return { warnings };
|
|
34
|
+
}
|
package/src/stop.ts
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import { describeHost } from "./host.js";
|
|
2
|
+
import { LOCK_BRANCH } from "./lock.js";
|
|
3
|
+
import type { LockHolder, Workspace } from "./ports/workspace.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* A Stop: how a human asks for one, and how a Run comes to hear about it.
|
|
7
|
+
*
|
|
8
|
+
* SIGTERM is the whole of what a Stop is on the wire (ADR-0006): no file beside
|
|
9
|
+
* the Run lock, and no meaning for Ctrl+C. So both ends of it are small enough
|
|
10
|
+
* to live together — `ticket-runner stop` reads the lock and signals the
|
|
11
|
+
* process it names, and the Run listening at the other end turns that signal
|
|
12
|
+
* into something a test can raise without a process to send one to. What the
|
|
13
|
+
* Run then does with it — finish the Tickets its Lanes hold and claim nothing
|
|
14
|
+
* more — is the Run's own business, and lives with the Run.
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
/** A Stop that reached a Run, and when it did. */
|
|
18
|
+
export interface Stop {
|
|
19
|
+
/** ISO-8601, so a summary and the run id above it read in the same clock. */
|
|
20
|
+
at: string;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** Where SIGTERM comes from: the process itself, unless a test is watching. */
|
|
24
|
+
export interface StopSource {
|
|
25
|
+
on(signal: "SIGTERM", listener: () => void): unknown;
|
|
26
|
+
off(signal: "SIGTERM", listener: () => void): unknown;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/**
|
|
30
|
+
* The one Stop a Run can be asked for.
|
|
31
|
+
*
|
|
32
|
+
* A Stop cannot be taken back and never arrives twice: a second SIGTERM is
|
|
33
|
+
* ignored rather than escalated to a kill. That is dropped here, once, rather
|
|
34
|
+
* than guarded against at each of the places a Run acts on the first one.
|
|
35
|
+
*/
|
|
36
|
+
export class StopSignal {
|
|
37
|
+
private stop: Stop | undefined;
|
|
38
|
+
|
|
39
|
+
/** What the first request has yet to reach. Emptied as it does. */
|
|
40
|
+
private readonly watchers: ((stop: Stop) => void)[] = [];
|
|
41
|
+
|
|
42
|
+
/** Ask the Run to stop. Every request after the first changes nothing. */
|
|
43
|
+
request(at: Date = new Date()): void {
|
|
44
|
+
if (this.stop !== undefined) return;
|
|
45
|
+
this.stop = { at: at.toISOString() };
|
|
46
|
+
for (const watcher of this.watchers.splice(0)) watcher(this.stop);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Be told when the Stop arrives, or at once when it already has.
|
|
51
|
+
*
|
|
52
|
+
* A watcher rather than something a Run polls, because what a Run has to
|
|
53
|
+
* report about a Stop — the Tickets its Lanes were holding — is true only at
|
|
54
|
+
* the moment it arrived: by the time the Run next looks, those are the Lanes
|
|
55
|
+
* that have come back.
|
|
56
|
+
*/
|
|
57
|
+
watch(watcher: (stop: Stop) => void): void {
|
|
58
|
+
if (this.stop !== undefined) {
|
|
59
|
+
watcher(this.stop);
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
this.watchers.push(watcher);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Hear SIGTERM as a Stop until the returned function is called.
|
|
68
|
+
*
|
|
69
|
+
* Listening at all is the whole of the difference between a Stop and a kill:
|
|
70
|
+
* with a handler on it, SIGTERM no longer ends the process. It is stopped when
|
|
71
|
+
* the Run ends, because a signal handler holds the event loop open — a Run that
|
|
72
|
+
* kept listening would print its summary and never exit.
|
|
73
|
+
*/
|
|
74
|
+
export function listenForStop(signal: StopSignal, source: StopSource = process): () => void {
|
|
75
|
+
const stop = (): void => signal.request();
|
|
76
|
+
source.on("SIGTERM", stop);
|
|
77
|
+
return () => {
|
|
78
|
+
source.off("SIGTERM", stop);
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The one line a Run logs when a Stop reaches it.
|
|
84
|
+
*
|
|
85
|
+
* It leads with the Tickets the Lanes hold because they are the only thing
|
|
86
|
+
* about a Stop that is not already known: the request itself came from the
|
|
87
|
+
* human reading the line, and what is left of the transcript is theirs.
|
|
88
|
+
*/
|
|
89
|
+
export function stopLine(busy: number[]): string {
|
|
90
|
+
const held = busy.length === 0 ? "nothing" : busy.map((ticket) => `#${ticket}`).join(" ");
|
|
91
|
+
return `${held} left to finish · stopped`;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** What `ticket-runner stop` needs: the Target's lock, and seams for tests. */
|
|
95
|
+
export interface StopRequest {
|
|
96
|
+
/** Where the Run lock is read from, and which Host is asking. */
|
|
97
|
+
workspace: Workspace;
|
|
98
|
+
/** How the Stop is delivered. A real SIGTERM by default. */
|
|
99
|
+
send?: (pid: number) => void;
|
|
100
|
+
log?: (line: string) => void;
|
|
101
|
+
/** Refusals, which the CLI puts on stderr as it always has. */
|
|
102
|
+
error?: (line: string) => void;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Ask the Run holding this Target's lock to stop, and answer with an exit code.
|
|
107
|
+
*
|
|
108
|
+
* A thin wrapper over the lock, and deliberately nothing more: no config file,
|
|
109
|
+
* no `gh` and no Target readiness, because a human reaching for this has a Run
|
|
110
|
+
* they want to end rather than a Target they want checked. Repeating it is
|
|
111
|
+
* harmless — the second SIGTERM is one the Run ignores (ADR-0006) — so it says
|
|
112
|
+
* the same thing every time rather than reporting a Stop already asked for.
|
|
113
|
+
*/
|
|
114
|
+
export async function requestStop({
|
|
115
|
+
workspace,
|
|
116
|
+
send = sendStop,
|
|
117
|
+
log = (line: string) => console.log(line),
|
|
118
|
+
error = (line: string) => console.error(line),
|
|
119
|
+
}: StopRequest): Promise<number> {
|
|
120
|
+
const held = await workspace.runLockHolder();
|
|
121
|
+
if (held === undefined) {
|
|
122
|
+
error(
|
|
123
|
+
`No Run to stop: nothing holds the Run lock on the \`${LOCK_BRANCH}\` branch, or the` +
|
|
124
|
+
" Run on this Host that left it there is gone. A lock like that is the next Run's to" +
|
|
125
|
+
" reclaim, so nothing here removes it.",
|
|
126
|
+
);
|
|
127
|
+
return 2;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// A Stop is a signal to a process, and only the Host the process runs on can
|
|
131
|
+
// send one (ADR-0006). A pid read off another Host's lock is a stranger's
|
|
132
|
+
// here, if it is anybody's.
|
|
133
|
+
const { holder, onAnotherHost } = held;
|
|
134
|
+
if (onAnotherHost) {
|
|
135
|
+
error(
|
|
136
|
+
`\`${holder.command}\` (run ${holder.runId}) holds the Run lock from` +
|
|
137
|
+
` ${describeHost(holder.host)}, started ${holder.startedAt}. Only that Host can send` +
|
|
138
|
+
" it a Stop: `ticket-runner stop` there, or its Operator on a cloud Host. Nothing" +
|
|
139
|
+
" was sent.",
|
|
140
|
+
);
|
|
141
|
+
return 2;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
try {
|
|
145
|
+
send(holder.pid);
|
|
146
|
+
} catch (failure) {
|
|
147
|
+
// The Run can end between the liveness check and the signal, and one
|
|
148
|
+
// started by another user cannot be signalled from this shell at all.
|
|
149
|
+
error(`Could not ask ${describeHolder(holder)} to stop: ${reason(failure)}`);
|
|
150
|
+
return 2;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
log(
|
|
154
|
+
`${describeHolder(holder)} will stop once the Tickets it holds are finished. It claims no more.`,
|
|
155
|
+
);
|
|
156
|
+
log(
|
|
157
|
+
"Ctrl+C in that Run's own terminal stops it at once instead, at the cost of killing the" +
|
|
158
|
+
" Stages it is running and leaving their Tickets stranded for the next Run.",
|
|
159
|
+
);
|
|
160
|
+
return 0;
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* Which Run, in the three things the lock knows about it: how `stop` names a
|
|
165
|
+
* holder on this Host, and `remove` too.
|
|
166
|
+
*/
|
|
167
|
+
export function describeHolder(holder: LockHolder): string {
|
|
168
|
+
return `\`${holder.command}\` (run ${holder.runId}, pid ${holder.pid})`;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** SIGTERM to the process the lock names, which is the whole of a Stop. */
|
|
172
|
+
function sendStop(pid: number): void {
|
|
173
|
+
process.kill(pid, "SIGTERM");
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
function reason(failure: unknown): string {
|
|
177
|
+
return failure instanceof Error ? failure.message : String(failure);
|
|
178
|
+
}
|