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/stranded.ts
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import type { Issue, Tracker } from "./ports/tracker.js";
|
|
2
|
+
import type { StateFile, Workspace } from "./ports/workspace.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The Tickets a Run that never came back left claimed, and how a later Run finds
|
|
6
|
+
* them.
|
|
7
|
+
*
|
|
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
|
+
* last committing Stage. The Frontier cannot see such a Ticket — it is claimed —
|
|
11
|
+
* so without this nobody would ever pick it up again, on this Host or another.
|
|
12
|
+
*
|
|
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 State file whose Ticket
|
|
15
|
+
* still carries this user's Claim knows the Run that wrote it is gone.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** A Ticket still claimed by a Run that never came back, and where its work is. */
|
|
19
|
+
export interface StrandedTicket {
|
|
20
|
+
number: number;
|
|
21
|
+
title: string;
|
|
22
|
+
/** The branch the State file named, which is where the work actually is. */
|
|
23
|
+
branch: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Whether this issue carries this user's Claim: assigned to them and labelled
|
|
28
|
+
* `in-progress`, which is what {@link import("./orchestrator.js").processTicket}
|
|
29
|
+
* writes when it claims a Ticket. Both halves, because a Ticket holding only one
|
|
30
|
+
* of them is one nobody can say is being worked on.
|
|
31
|
+
*/
|
|
32
|
+
export function holdsClaim(issue: Issue, user: string, inProgress: string): boolean {
|
|
33
|
+
return issue.assignees.includes(user) && issue.labels.includes(inProgress);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export interface StrandedSweep {
|
|
37
|
+
tracker: Tracker;
|
|
38
|
+
/** Where the State is kept. */
|
|
39
|
+
workspace: Workspace;
|
|
40
|
+
/** The `in-progress` label, as this repo configured it. */
|
|
41
|
+
inProgress: string;
|
|
42
|
+
/**
|
|
43
|
+
* The Tickets a narrowed Run was given. The State of every other Ticket is
|
|
44
|
+
* not read, asked about or removed: it is the next unnarrowed Run's.
|
|
45
|
+
*/
|
|
46
|
+
only?: ReadonlySet<number>;
|
|
47
|
+
log?: (line: string) => void;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Sweep the State the Workspace keeps on the remote for the Tickets this
|
|
52
|
+
* pipeline still holds, whichever Host's Run claimed them.
|
|
53
|
+
*
|
|
54
|
+
* Four things can be behind a State file, and only one of them is stranded:
|
|
55
|
+
*
|
|
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
|
+
* neither is the sweep's: the Frontier picks up whichever of them is labelled
|
|
59
|
+
* `ready-for-agent`, and a `ready-for-human` Ticket waits, inert, until a
|
|
60
|
+
* human relabels it. Both are passed over in silence
|
|
61
|
+
* - the Ticket has closed — there is nothing left to resume, so the file goes
|
|
62
|
+
* - somebody else holds it now — a human took the Ticket over, and neither the
|
|
63
|
+
* Ticket nor the file is this Run's to touch; it is logged and left
|
|
64
|
+
*
|
|
65
|
+
* A Ticket the tracker cannot be asked about is left alone too: a `gh` that is
|
|
66
|
+
* down says nothing about whose Ticket it is, and a Run must not resume, or
|
|
67
|
+
* forget, a Ticket on a guess.
|
|
68
|
+
*/
|
|
69
|
+
export async function strandedTickets(sweep: StrandedSweep): Promise<StrandedTicket[]> {
|
|
70
|
+
const { tracker, workspace, inProgress } = sweep;
|
|
71
|
+
const log = sweep.log ?? (() => {});
|
|
72
|
+
|
|
73
|
+
const files = (await workspace.readAllStates()).filter(
|
|
74
|
+
(file) => sweep.only === undefined || sweep.only.has(file.readable ? file.state.ticket : file.ticket),
|
|
75
|
+
);
|
|
76
|
+
// Said before anything is asked of the tracker, because it is the one finding
|
|
77
|
+
// here that needs nothing of it: the file is all the evidence there is.
|
|
78
|
+
for (const file of files) if (!file.readable) log(unreadableLine(file));
|
|
79
|
+
|
|
80
|
+
const recorded = files.flatMap((file) => (file.readable ? [file.state] : []));
|
|
81
|
+
// Asked only when there is something to ask about, so a Run on a Target that
|
|
82
|
+
// has never claimed anything spends no call on the sweep.
|
|
83
|
+
if (recorded.length === 0) return [];
|
|
84
|
+
const user = await tracker.currentUser();
|
|
85
|
+
|
|
86
|
+
const stranded: StrandedTicket[] = [];
|
|
87
|
+
for (const state of recorded) {
|
|
88
|
+
const ticket = state.ticket;
|
|
89
|
+
let issue: Issue;
|
|
90
|
+
try {
|
|
91
|
+
issue = await tracker.getIssue(ticket);
|
|
92
|
+
} catch (error) {
|
|
93
|
+
log(`#${ticket} is resumable, but reading it failed: ${(error as Error).message}`);
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
if (issue.closed) {
|
|
98
|
+
// A remote that will not take the removal costs nothing but a second
|
|
99
|
+
// try from the next Run, where letting it throw would end this one.
|
|
100
|
+
try {
|
|
101
|
+
await workspace.removeState(ticket);
|
|
102
|
+
log(`#${ticket} has closed, so the state it left is gone`);
|
|
103
|
+
} catch (error) {
|
|
104
|
+
log(`#${ticket} has closed, but removing its state failed: ${(error as Error).message}`);
|
|
105
|
+
}
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
if (issue.assignees.length > 0 && !issue.assignees.includes(user)) {
|
|
109
|
+
log(`#${ticket} is resumable, but ${issue.assignees.join(", ")} holds it now`);
|
|
110
|
+
continue;
|
|
111
|
+
}
|
|
112
|
+
if (!holdsClaim(issue, user, inProgress)) continue;
|
|
113
|
+
|
|
114
|
+
stranded.push({ number: ticket, title: issue.title, branch: state.branch });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
return stranded;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* A State file nothing here can resume from, named rather than dropped.
|
|
122
|
+
*
|
|
123
|
+
* The file and the Claim are left exactly where they are. A Ticket carrying a
|
|
124
|
+
* file this pipeline cannot use is one a newer pipeline probably wrote, and
|
|
125
|
+
* deleting either would take a Claim off the board that the machine which
|
|
126
|
+
* understands the file is still counting on (ADR-0007). So the sweep says the
|
|
127
|
+
* Ticket number and whichever Version the file names, and a human decides.
|
|
128
|
+
*
|
|
129
|
+
* `cannot use` rather than `cannot read`, because the two files that land here
|
|
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 Version would resume either.
|
|
132
|
+
*/
|
|
133
|
+
function unreadableLine(file: Extract<StateFile, { readable: false }>): string {
|
|
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
|
+
}
|