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/remove.ts
ADDED
|
@@ -0,0 +1,732 @@
|
|
|
1
|
+
import { existsSync, readdirSync, realpathSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { basename, dirname, join, relative } from "node:path";
|
|
3
|
+
import { AGENT_BRANCH_PREFIX } from "./branch.js";
|
|
4
|
+
import { CONFIG_FILENAME, type Config } from "./config.js";
|
|
5
|
+
import { CONVENTIONS_PATH } from "./conventions.js";
|
|
6
|
+
import { describeHost, hostKind } from "./host.js";
|
|
7
|
+
import { newerSetUp } from "./init.js";
|
|
8
|
+
import { FREE_LOCK, LOCK_BRANCH, LOCK_FILE } from "./lock.js";
|
|
9
|
+
import { findStandingNotes } from "./notes.js";
|
|
10
|
+
import { OPERATOR_SKILL_PATH } from "./operator-skill.js";
|
|
11
|
+
import type { Tracker } from "./ports/tracker.js";
|
|
12
|
+
import type { LockTake, TicketWorktree, Workspace } from "./ports/workspace.js";
|
|
13
|
+
import {
|
|
14
|
+
CLAUDE_FILENAME,
|
|
15
|
+
GH_FAILURE,
|
|
16
|
+
IGNORED,
|
|
17
|
+
type IgnoredDirectory,
|
|
18
|
+
hasClaudePointer,
|
|
19
|
+
readTargetFile,
|
|
20
|
+
withoutClaudeSection,
|
|
21
|
+
withoutIgnoreEntry,
|
|
22
|
+
} from "./readiness.js";
|
|
23
|
+
import { STATE_BRANCH } from "./resume.js";
|
|
24
|
+
import { nestedRunRefusal } from "./stage-guard.js";
|
|
25
|
+
import { describeHolder } from "./stop.js";
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* `ticket-runner remove`: take the pipeline out of a Target, so a human who
|
|
29
|
+
* tried it on a repository of their own can undo it.
|
|
30
|
+
*
|
|
31
|
+
* It removes what it can prove the pipeline put there — what `init` wrote, and
|
|
32
|
+
* what Runs left behind — and nothing else. What Planning shares with the
|
|
33
|
+
* pipeline, the five triage labels other than in-progress, and what the
|
|
34
|
+
* repository may have had before `init`, the two merge settings, stay, and so
|
|
35
|
+
* does the work and the writing addressed to humans: `agent/` branches on
|
|
36
|
+
* GitHub and their pull requests, the Notes issue, comments on issues. The
|
|
37
|
+
* report names each of them, with what to do about it.
|
|
38
|
+
*
|
|
39
|
+
* Like `init` it commits nothing, and leaves the working tree changed for the
|
|
40
|
+
* human to review. Unlike `init` it takes the Run lock, recording itself as
|
|
41
|
+
* the holder, so that no Run starts on a Target that is being taken apart, and
|
|
42
|
+
* the lock branch is the last thing it deletes. A removal that fails is
|
|
43
|
+
* reported and the rest carry on; the lock is then released rather than
|
|
44
|
+
* deleted, and running the command again is a first run over what is left.
|
|
45
|
+
*
|
|
46
|
+
* The Target's own files are read and written here rather than through a
|
|
47
|
+
* port, for the reason `init` gives: setting a Target up and taking it out
|
|
48
|
+
* again are nothing a Run does. Its branches, worktrees and label go through
|
|
49
|
+
* the ports, which is what lets its tests drive it through fakes and a
|
|
50
|
+
* temporary repository root, as `init`'s are.
|
|
51
|
+
*/
|
|
52
|
+
|
|
53
|
+
/** The pipeline's directory of worktrees, one `ticket-<n>` per Ticket. */
|
|
54
|
+
const WORKTREES_DIR = ".worktrees";
|
|
55
|
+
|
|
56
|
+
/** The pipeline's directory of Run logs and transcripts. */
|
|
57
|
+
const LOCAL_DIR = ".ticket-runner";
|
|
58
|
+
|
|
59
|
+
/** The files `init` writes that are wholly the pipeline's, whatever they now say. */
|
|
60
|
+
const PIPELINE_FILES = [CONFIG_FILENAME, CONVENTIONS_PATH, OPERATOR_SKILL_PATH];
|
|
61
|
+
|
|
62
|
+
const PASS = "✓";
|
|
63
|
+
const FAIL = "✗";
|
|
64
|
+
|
|
65
|
+
export interface RemoveOptions {
|
|
66
|
+
repoRoot: string;
|
|
67
|
+
/** The Version doing the removing, which the report's first line names (ADR-0007). */
|
|
68
|
+
version: string;
|
|
69
|
+
/** The pipeline's own repository, as `owner/name`, which the upgrade is named from. */
|
|
70
|
+
repository?: string | undefined;
|
|
71
|
+
/** Read before anything is removed, because it names the in-progress label. */
|
|
72
|
+
config: Config;
|
|
73
|
+
tracker: Tracker;
|
|
74
|
+
workspace: Workspace;
|
|
75
|
+
/** `-y` or `--yes`: go ahead without asking. */
|
|
76
|
+
yes: boolean;
|
|
77
|
+
/** Whether a human is there to answer the question, which a terminal says. */
|
|
78
|
+
interactive: boolean;
|
|
79
|
+
/** Put the question to that human, and give back what they typed. */
|
|
80
|
+
ask: (question: string) => Promise<string>;
|
|
81
|
+
/** The run id and command line the Run lock records while this holds it. */
|
|
82
|
+
runId: string;
|
|
83
|
+
command: string;
|
|
84
|
+
/** The shell it was started in, which the Stage mark and the Host are read from. */
|
|
85
|
+
env?: NodeJS.ProcessEnv;
|
|
86
|
+
log?: (line: string) => void;
|
|
87
|
+
error?: (line: string) => void;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** What of the pipeline's a Target still has, as `remove` finds it. */
|
|
91
|
+
interface Found {
|
|
92
|
+
/** Those of {@link PIPELINE_FILES} it has, as paths from the root. */
|
|
93
|
+
files: string[];
|
|
94
|
+
/**
|
|
95
|
+
* `CLAUDE.md` as `init` left it: holding its section and more, holding
|
|
96
|
+
* nothing else, pointing at the document in words `init` did not write, or
|
|
97
|
+
* none of these.
|
|
98
|
+
*/
|
|
99
|
+
claude: "section" | "whole" | "edited" | undefined;
|
|
100
|
+
/** The gitignore entries still exactly as `init` writes them. */
|
|
101
|
+
ignores: IgnoredDirectory[];
|
|
102
|
+
/** Whether `.ticket-runner/` is there. */
|
|
103
|
+
localDir: boolean;
|
|
104
|
+
worktrees: TicketWorktree[];
|
|
105
|
+
/** The local `agent/` branches no `ticket-<n>` worktree has checked out. */
|
|
106
|
+
branches: string[];
|
|
107
|
+
/** What `.worktrees/` holds besides the pipeline's worktrees. */
|
|
108
|
+
besides: string[];
|
|
109
|
+
/** Whether the Target has the in-progress label. */
|
|
110
|
+
label: boolean;
|
|
111
|
+
stateBranch: boolean;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Take the pipeline out of the Target and report on it. Returns the exit code:
|
|
116
|
+
* 0 when everything it set out to remove is gone or there was nothing to
|
|
117
|
+
* remove, 1 when at least one removal failed, and 2 when it refused before
|
|
118
|
+
* anything changed.
|
|
119
|
+
*/
|
|
120
|
+
export async function removeTarget(options: RemoveOptions): Promise<number> {
|
|
121
|
+
const { repoRoot, config, tracker, workspace } = options;
|
|
122
|
+
const log = options.log ?? ((line: string) => console.log(line));
|
|
123
|
+
const error = options.error ?? ((line: string) => console.error(line));
|
|
124
|
+
const env = options.env ?? process.env;
|
|
125
|
+
const refuse = (message: string): number => {
|
|
126
|
+
error(message);
|
|
127
|
+
return 2;
|
|
128
|
+
};
|
|
129
|
+
|
|
130
|
+
// Before the first read of the Target, as `init` refuses it.
|
|
131
|
+
const nested = nestedRunRefusal(env);
|
|
132
|
+
if (nested !== undefined) return refuse(nested);
|
|
133
|
+
|
|
134
|
+
// A cloud Host can delete no ref on the remote (ADR-0008), so it would leave
|
|
135
|
+
// the lock and State branches behind whatever else it took out.
|
|
136
|
+
if (hostKind(env) === "cloud") {
|
|
137
|
+
return refuse(
|
|
138
|
+
"Refusing to remove on a cloud Host: it can delete no branch on the remote, so the Run" +
|
|
139
|
+
" lock and State branches would stay. Run `ticket-runner remove` on a workstation instead.",
|
|
140
|
+
);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
const authentication = await tracker.authentication();
|
|
144
|
+
if (authentication !== "authenticated") {
|
|
145
|
+
const { failure, remedy } = GH_FAILURE[authentication];
|
|
146
|
+
return refuse(`Refusing to remove: ${failure} — ${remedy}, then \`ticket-runner remove\` again.`);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
// A newer Version may have put things in the Target this one has never
|
|
150
|
+
// heard of, and a removal that left them would report a Target it had not
|
|
151
|
+
// emptied as done.
|
|
152
|
+
const newer = newerSetUp(repoRoot, options.version);
|
|
153
|
+
if (newer !== undefined) {
|
|
154
|
+
const upgrade =
|
|
155
|
+
options.repository === undefined
|
|
156
|
+
? "Upgrade `ticket-runner`"
|
|
157
|
+
: `Upgrade with \`npm install -g "github:${options.repository}#semver:*"\``;
|
|
158
|
+
return refuse(
|
|
159
|
+
`Refusing to remove: ${newer.mark} set this Target up and this is ${newer.own}, so it may` +
|
|
160
|
+
` have left things this Version does not know to remove. ${upgrade}, then run` +
|
|
161
|
+
" `ticket-runner remove` again.",
|
|
162
|
+
);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
const header = `ticket-runner ${options.version} remove · ${repoRoot}`;
|
|
166
|
+
|
|
167
|
+
// Asked before the lock, so a Target the pipeline never touched is left
|
|
168
|
+
// without a lock branch it never had.
|
|
169
|
+
const before = await find(options);
|
|
170
|
+
if (nothingFound(before) && !(await workspace.hasRemoteBranch(LOCK_BRANCH))) {
|
|
171
|
+
log(header);
|
|
172
|
+
logGroup(log, "Removed", []);
|
|
173
|
+
logGroup(log, "GitHub", []);
|
|
174
|
+
logGroup(log, "Left for you", await leftForYou(options, { removed: false }));
|
|
175
|
+
log("");
|
|
176
|
+
log("Nothing to remove: ticket-runner has not set this Target up.");
|
|
177
|
+
return 0;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
if (!options.yes && !options.interactive) {
|
|
181
|
+
return refuse(
|
|
182
|
+
"Refusing to remove: there is no terminal to ask whether to go ahead. Run" +
|
|
183
|
+
" `ticket-runner remove --yes` to remove without asking.",
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
const taken = await workspace.takeRunLock({
|
|
188
|
+
pid: process.pid,
|
|
189
|
+
command: options.command,
|
|
190
|
+
runId: options.runId,
|
|
191
|
+
startedAt: new Date().toISOString(),
|
|
192
|
+
});
|
|
193
|
+
if (taken.outcome !== "taken") return refuse(lockRefusal(taken));
|
|
194
|
+
|
|
195
|
+
let found: Found;
|
|
196
|
+
try {
|
|
197
|
+
const refusal = await heldWorkRefusal(options);
|
|
198
|
+
if (refusal !== undefined) {
|
|
199
|
+
await workspace.releaseRunLock();
|
|
200
|
+
return refuse(refusal);
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// Found again under the lock, which is what it removes: a Run could have
|
|
204
|
+
// come and gone between the first look and the take.
|
|
205
|
+
found = await find(options);
|
|
206
|
+
log(header);
|
|
207
|
+
if (!options.yes) {
|
|
208
|
+
logGroup(log, "About to remove", planned(repoRoot, found, config));
|
|
209
|
+
log("");
|
|
210
|
+
const answer = await options.ask("Remove all of this? Nothing will be committed. [y/N] ");
|
|
211
|
+
if (!/^y(es)?$/i.test(answer.trim())) {
|
|
212
|
+
await workspace.releaseRunLock();
|
|
213
|
+
return refuse(
|
|
214
|
+
"Nothing was removed. Run `ticket-runner remove` again when you want it gone.",
|
|
215
|
+
);
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
} catch (failure) {
|
|
219
|
+
// Nothing is removed yet, so the lock is all there is to put back.
|
|
220
|
+
await workspace.releaseRunLock();
|
|
221
|
+
throw failure;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const outcome = await removeFound(options, found);
|
|
225
|
+
logGroup(log, "Removed", outcome.removed);
|
|
226
|
+
logGroup(log, "GitHub", outcome.github);
|
|
227
|
+
logGroup(
|
|
228
|
+
log,
|
|
229
|
+
"Left for you",
|
|
230
|
+
await leftForYou(options, {
|
|
231
|
+
removed: outcome.removed.some((line) => line.startsWith(PASS)),
|
|
232
|
+
states: outcome.states,
|
|
233
|
+
stays: outcome.left,
|
|
234
|
+
}),
|
|
235
|
+
);
|
|
236
|
+
|
|
237
|
+
log("");
|
|
238
|
+
if (outcome.failed === 0) {
|
|
239
|
+
log("Done: the pipeline has gone from this Target.");
|
|
240
|
+
return 0;
|
|
241
|
+
}
|
|
242
|
+
log(
|
|
243
|
+
`Not done: ${outcome.failed} ${outcome.failed === 1 ? "removal" : "removals"} failed — run` +
|
|
244
|
+
" `ticket-runner remove` again to remove what is left.",
|
|
245
|
+
);
|
|
246
|
+
return 1;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/**
|
|
250
|
+
* What stops the removal once the lock is held: work a Run or a human still
|
|
251
|
+
* has in hand, which removing the pipeline would take away from under them.
|
|
252
|
+
*/
|
|
253
|
+
async function heldWorkRefusal({
|
|
254
|
+
config,
|
|
255
|
+
tracker,
|
|
256
|
+
workspace,
|
|
257
|
+
repoRoot,
|
|
258
|
+
}: RemoveOptions): Promise<string | undefined> {
|
|
259
|
+
const stranded = (await tracker.listCandidates(config.labels.inProgress))
|
|
260
|
+
.map((candidate) => candidate.number)
|
|
261
|
+
.sort((a, b) => a - b);
|
|
262
|
+
if (stranded.length > 0) {
|
|
263
|
+
const named = stranded.map((ticket) => `#${ticket}`);
|
|
264
|
+
const one = named.length === 1;
|
|
265
|
+
const listed = one ? named[0] : `${named.slice(0, -1).join(", ")} and ${named.at(-1)}`;
|
|
266
|
+
const them = one ? "it" : "them";
|
|
267
|
+
return (
|
|
268
|
+
`Refusing to remove: ${listed} still ${one ? "carries" : "carry"} the` +
|
|
269
|
+
` \`${config.labels.inProgress}\` label, so ${one ? "it is a Stranded Ticket" : "they are Stranded Tickets"}` +
|
|
270
|
+
` a Run was killed holding. Finish ${them} with \`ticket-runner run\`, or relabel ${them},` +
|
|
271
|
+
" then run `ticket-runner remove` again."
|
|
272
|
+
);
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
const holding = (await workspace.ticketWorktrees()).filter(
|
|
276
|
+
(worktree) => worktree.uncommitted || worktree.unpushed,
|
|
277
|
+
);
|
|
278
|
+
if (holding.length === 0) return undefined;
|
|
279
|
+
return [
|
|
280
|
+
"Refusing to remove: these worktrees hold work GitHub does not have, which removing them would lose:",
|
|
281
|
+
...holding.map((worktree) => {
|
|
282
|
+
const held = [
|
|
283
|
+
...(worktree.uncommitted ? ["uncommitted changes"] : []),
|
|
284
|
+
...(worktree.unpushed ? ["commits its branch on the remote does not have"] : []),
|
|
285
|
+
];
|
|
286
|
+
return ` ${shown(repoRoot, worktree.path)}: ${held.join(", and ")}`;
|
|
287
|
+
}),
|
|
288
|
+
"Push what is worth keeping, and take out a worktree nothing in is wanted with" +
|
|
289
|
+
" `git worktree remove --force <path>`, then run `ticket-runner remove` again.",
|
|
290
|
+
].join("\n");
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* Who holds the lock `remove` did not get, named as `stop` names a holder, and
|
|
295
|
+
* what the human does about it. None of them is taken over: a lock whose
|
|
296
|
+
* process has gone may still name Tickets somebody means to finish.
|
|
297
|
+
*/
|
|
298
|
+
function lockRefusal(taken: Exclude<LockTake, { outcome: "taken" }>): string {
|
|
299
|
+
const { holder } = taken;
|
|
300
|
+
const again = "then run `ticket-runner remove` again.";
|
|
301
|
+
const release =
|
|
302
|
+
`commit a \`${LOCK_FILE}\` that reads \`${FREE_LOCK}\` to the \`${LOCK_BRANCH}\` branch,` +
|
|
303
|
+
` ${again}`;
|
|
304
|
+
if (taken.outcome === "abandoned") {
|
|
305
|
+
return (
|
|
306
|
+
`Refusing to remove: ${describeHolder(holder)} holds the Run lock, but its process on this` +
|
|
307
|
+
" Host has gone. `remove` takes over no lock: start `ticket-runner run` to take it over" +
|
|
308
|
+
` and finish what it held, or ${release}`
|
|
309
|
+
);
|
|
310
|
+
}
|
|
311
|
+
if (taken.onAnotherHost) {
|
|
312
|
+
return (
|
|
313
|
+
`Refusing to remove: \`${holder.command}\` (run ${holder.runId}) holds the Run lock from` +
|
|
314
|
+
` ${describeHost(holder.host)}, started ${holder.startedAt}. Wait for it to finish or, if` +
|
|
315
|
+
` it is gone, ${release}`
|
|
316
|
+
);
|
|
317
|
+
}
|
|
318
|
+
return (
|
|
319
|
+
`Refusing to remove: ${describeHolder(holder)} holds the Run lock on this Host, started` +
|
|
320
|
+
` ${holder.startedAt}. Wait for it to finish, or ask it to with \`ticket-runner stop\`, ${again}`
|
|
321
|
+
);
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/** Everything of the pipeline's the Target still has. */
|
|
325
|
+
async function find({ repoRoot, config, tracker, workspace }: RemoveOptions): Promise<Found> {
|
|
326
|
+
const worktrees = await workspace.ticketWorktrees();
|
|
327
|
+
const checkedOut = new Set(worktrees.map((worktree) => worktree.branch));
|
|
328
|
+
const kept = new Set(worktrees.map((worktree) => basename(worktree.path)));
|
|
329
|
+
const besides = listDirectory(join(repoRoot, WORKTREES_DIR)).filter((name) => !kept.has(name));
|
|
330
|
+
|
|
331
|
+
const gitignore = readTargetFile(join(repoRoot, ".gitignore")) ?? "";
|
|
332
|
+
const ignores = IGNORED.filter(
|
|
333
|
+
(entry) =>
|
|
334
|
+
withoutIgnoreEntry(gitignore, entry) !== undefined &&
|
|
335
|
+
// Kept while anything else is under the directory, which it keeps out of
|
|
336
|
+
// a commit as much as the pipeline's worktrees.
|
|
337
|
+
(entry.line !== `${WORKTREES_DIR}/` || besides.length === 0),
|
|
338
|
+
);
|
|
339
|
+
|
|
340
|
+
return {
|
|
341
|
+
files: PIPELINE_FILES.filter((path) => existsSync(join(repoRoot, path))),
|
|
342
|
+
claude: claudeFound(readTargetFile(join(repoRoot, CLAUDE_FILENAME))),
|
|
343
|
+
ignores,
|
|
344
|
+
localDir: existsSync(join(repoRoot, LOCAL_DIR)),
|
|
345
|
+
worktrees,
|
|
346
|
+
branches: (await workspace.listBranches(AGENT_BRANCH_PREFIX))
|
|
347
|
+
.filter((branch) => !checkedOut.has(branch))
|
|
348
|
+
.sort(),
|
|
349
|
+
besides,
|
|
350
|
+
label: (await tracker.listLabels()).includes(config.labels.inProgress),
|
|
351
|
+
stateBranch: await workspace.hasRemoteBranch(STATE_BRANCH),
|
|
352
|
+
};
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
function claudeFound(claude: string | undefined): Found["claude"] {
|
|
356
|
+
if (claude === undefined) return undefined;
|
|
357
|
+
const rest = withoutClaudeSection(claude);
|
|
358
|
+
if (rest !== undefined) return rest.trim() === "" ? "whole" : "section";
|
|
359
|
+
return hasClaudePointer(claude) ? "edited" : undefined;
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/** Whether nothing `remove` would take out is there; what it leaves does not count. */
|
|
363
|
+
function nothingFound(found: Found): boolean {
|
|
364
|
+
return (
|
|
365
|
+
found.files.length === 0 &&
|
|
366
|
+
(found.claude === undefined || found.claude === "edited") &&
|
|
367
|
+
found.ignores.length === 0 &&
|
|
368
|
+
!found.localDir &&
|
|
369
|
+
found.worktrees.length === 0 &&
|
|
370
|
+
found.branches.length === 0 &&
|
|
371
|
+
!found.label &&
|
|
372
|
+
!found.stateBranch
|
|
373
|
+
);
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/** What the question lists, in the order the removal goes. */
|
|
377
|
+
function planned(repoRoot: string, found: Found, config: Config): string[] {
|
|
378
|
+
return [
|
|
379
|
+
...found.files.filter((file) => file !== CONFIG_FILENAME),
|
|
380
|
+
...(found.claude === "whole"
|
|
381
|
+
? [`${CLAUDE_FILENAME}, because the section \`init\` wrote is all it holds`]
|
|
382
|
+
: []),
|
|
383
|
+
...(found.claude === "section" ? [claudeLine(found)] : []),
|
|
384
|
+
...(found.localDir ? [`${LOCAL_DIR}/`] : []),
|
|
385
|
+
...found.worktrees.map((worktree) => worktreeLine(repoRoot, worktree)),
|
|
386
|
+
...found.branches.map((branch) => `${branch}, a local branch`),
|
|
387
|
+
...(found.ignores.length > 0 ? [".gitignore: the entries `init` wrote"] : []),
|
|
388
|
+
"any directory this leaves empty",
|
|
389
|
+
...(found.label ? [`the \`${config.labels.inProgress}\` label`] : []),
|
|
390
|
+
...(found.stateBranch ? [`the \`${STATE_BRANCH}\` branch`] : []),
|
|
391
|
+
...(found.files.includes(CONFIG_FILENAME) ? [CONFIG_FILENAME] : []),
|
|
392
|
+
`the \`${LOCK_BRANCH}\` branch`,
|
|
393
|
+
];
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
function claudeLine(found: Found): string {
|
|
397
|
+
return found.claude === "whole"
|
|
398
|
+
? `${CLAUDE_FILENAME}: deleted, because the section \`init\` wrote was all it held`
|
|
399
|
+
: `${CLAUDE_FILENAME}: the section pointing at ${CONVENTIONS_PATH}`;
|
|
400
|
+
}
|
|
401
|
+
|
|
402
|
+
function worktreeLine(repoRoot: string, worktree: TicketWorktree): string {
|
|
403
|
+
const path = shown(repoRoot, worktree.path);
|
|
404
|
+
return worktree.branch === undefined ? path : `${path}, and its branch ${worktree.branch}`;
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
/** What the removal did, group by group, and what it has to say beyond that. */
|
|
408
|
+
interface Removal {
|
|
409
|
+
removed: string[];
|
|
410
|
+
github: string[];
|
|
411
|
+
/** What it left, and why, where it was one of the things it set out to remove. */
|
|
412
|
+
left: string[];
|
|
413
|
+
failed: number;
|
|
414
|
+
/** The Tickets whose State files went with the state branch. */
|
|
415
|
+
states: number[];
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
/**
|
|
419
|
+
* Remove everything `found` holds, carrying on past each failure, and the lock
|
|
420
|
+
* branch last of all: deleted where every other removal went, and released to
|
|
421
|
+
* free where one did not, so the next `remove` can take it again.
|
|
422
|
+
*/
|
|
423
|
+
async function removeFound(options: RemoveOptions, found: Found): Promise<Removal> {
|
|
424
|
+
const { repoRoot, config, tracker, workspace } = options;
|
|
425
|
+
const removal: Removal = { removed: [], github: [], left: [], failed: 0, states: [] };
|
|
426
|
+
const attempt = async (
|
|
427
|
+
group: string[],
|
|
428
|
+
line: string,
|
|
429
|
+
act: () => unknown,
|
|
430
|
+
): Promise<boolean> => {
|
|
431
|
+
try {
|
|
432
|
+
await act();
|
|
433
|
+
group.push(`${PASS} ${line}`);
|
|
434
|
+
return true;
|
|
435
|
+
} catch (failure) {
|
|
436
|
+
removal.failed += 1;
|
|
437
|
+
group.push(`${FAIL} ${line}: ${reason(failure)}`);
|
|
438
|
+
return false;
|
|
439
|
+
}
|
|
440
|
+
};
|
|
441
|
+
const emptied = new Set<string>();
|
|
442
|
+
|
|
443
|
+
for (const path of found.files.filter((file) => file !== CONFIG_FILENAME)) {
|
|
444
|
+
const gone = await attempt(removal.removed, path, () => rmSync(join(repoRoot, path)));
|
|
445
|
+
if (gone) emptied.add(dirname(path));
|
|
446
|
+
}
|
|
447
|
+
if (found.claude === "whole" || found.claude === "section") {
|
|
448
|
+
await attempt(removal.removed, claudeLine(found), () => {
|
|
449
|
+
const path = join(repoRoot, CLAUDE_FILENAME);
|
|
450
|
+
if (found.claude === "whole") rmSync(path);
|
|
451
|
+
else writeFileSync(path, withoutClaudeSection(readTargetFile(path) ?? "") ?? "");
|
|
452
|
+
});
|
|
453
|
+
}
|
|
454
|
+
if (found.localDir) {
|
|
455
|
+
await attempt(removal.removed, `${LOCAL_DIR}/`, () =>
|
|
456
|
+
rmSync(join(repoRoot, LOCAL_DIR), { recursive: true, force: true }),
|
|
457
|
+
);
|
|
458
|
+
}
|
|
459
|
+
|
|
460
|
+
for (const worktree of found.worktrees) {
|
|
461
|
+
await attempt(removal.removed, worktreeLine(repoRoot, worktree), () =>
|
|
462
|
+
workspace.removeWorktree(worktree),
|
|
463
|
+
);
|
|
464
|
+
}
|
|
465
|
+
for (const branch of found.branches) {
|
|
466
|
+
await attempt(removal.removed, `${branch}, a local branch`, () =>
|
|
467
|
+
workspace.deleteBranch(branch),
|
|
468
|
+
);
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
// Asked of the directory now rather than taken from what was found: a
|
|
472
|
+
// worktree that would not go keeps it, and its entry, for the next run.
|
|
473
|
+
const worktreesDir = join(repoRoot, WORKTREES_DIR);
|
|
474
|
+
const worktreesLeft = listDirectory(worktreesDir);
|
|
475
|
+
if (existsSync(worktreesDir) && worktreesLeft.length === 0) {
|
|
476
|
+
await attempt(removal.removed, `${WORKTREES_DIR}/, left empty`, () => rmdirSync(worktreesDir));
|
|
477
|
+
} else if (found.besides.length > 0) {
|
|
478
|
+
removal.left.push(
|
|
479
|
+
`${WORKTREES_DIR}/: holds ${found.besides.join(", ")} besides the pipeline's worktrees, so` +
|
|
480
|
+
" it stays, and so does its `.gitignore` entry",
|
|
481
|
+
);
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
const ignores = found.ignores.filter(
|
|
485
|
+
(entry) => entry.line !== `${WORKTREES_DIR}/` || worktreesLeft.length === 0,
|
|
486
|
+
);
|
|
487
|
+
if (ignores.length > 0) await removeIgnores(repoRoot, ignores, removal.removed, attempt);
|
|
488
|
+
|
|
489
|
+
for (const directory of prunable(repoRoot, emptied)) {
|
|
490
|
+
await attempt(removal.removed, `${directory}/, left empty`, () =>
|
|
491
|
+
rmdirSync(join(repoRoot, directory)),
|
|
492
|
+
);
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
if (found.label) {
|
|
496
|
+
await attempt(
|
|
497
|
+
removal.github,
|
|
498
|
+
`the \`${config.labels.inProgress}\` label, from every issue that wore it`,
|
|
499
|
+
() => tracker.deleteLabel(config.labels.inProgress),
|
|
500
|
+
);
|
|
501
|
+
}
|
|
502
|
+
if (found.stateBranch) {
|
|
503
|
+
// Read before the branch goes, because it is the only place they are
|
|
504
|
+
// named: a branch whose Tickets could not be read is kept, so the report
|
|
505
|
+
// never loses one a Run could have resumed.
|
|
506
|
+
await attempt(removal.github, `the \`${STATE_BRANCH}\` branch`, async () => {
|
|
507
|
+
const states = await workspace.readAllStates();
|
|
508
|
+
await workspace.deleteRemoteBranch(STATE_BRANCH);
|
|
509
|
+
removal.states = states.map((file) => (file.readable ? file.state.ticket : file.ticket));
|
|
510
|
+
});
|
|
511
|
+
}
|
|
512
|
+
|
|
513
|
+
// Last before the lock, because it is the only place a label the human
|
|
514
|
+
// renamed is named: where a removal above failed, it stays, so the next
|
|
515
|
+
// `remove` looks for the in-progress label and the Stranded Tickets under
|
|
516
|
+
// the names it gives rather than the defaults.
|
|
517
|
+
if (found.files.includes(CONFIG_FILENAME)) {
|
|
518
|
+
if (removal.failed === 0) {
|
|
519
|
+
await attempt(removal.removed, CONFIG_FILENAME, () => rmSync(join(repoRoot, CONFIG_FILENAME)));
|
|
520
|
+
} else {
|
|
521
|
+
removal.left.push(
|
|
522
|
+
`${CONFIG_FILENAME}: kept, because a removal above failed and it names the labels the` +
|
|
523
|
+
" next `ticket-runner remove` looks for — that run deletes it with the rest",
|
|
524
|
+
);
|
|
525
|
+
}
|
|
526
|
+
}
|
|
527
|
+
|
|
528
|
+
const deleted =
|
|
529
|
+
removal.failed === 0 &&
|
|
530
|
+
(await attempt(removal.github, `the \`${LOCK_BRANCH}\` branch`, () =>
|
|
531
|
+
workspace.deleteRemoteBranch(LOCK_BRANCH),
|
|
532
|
+
));
|
|
533
|
+
if (!deleted) {
|
|
534
|
+
const released = await attempt(removal.github, "the Run lock, released to free", () =>
|
|
535
|
+
workspace.releaseRunLock(),
|
|
536
|
+
);
|
|
537
|
+
if (released) {
|
|
538
|
+
removal.left.push(
|
|
539
|
+
`${LOCK_BRANCH}: released rather than deleted, because a removal above failed —` +
|
|
540
|
+
" `ticket-runner remove` again deletes it with the rest",
|
|
541
|
+
);
|
|
542
|
+
}
|
|
543
|
+
}
|
|
544
|
+
return removal;
|
|
545
|
+
}
|
|
546
|
+
|
|
547
|
+
/**
|
|
548
|
+
* Take `init`'s entries out of the gitignore, and the gitignore with them when
|
|
549
|
+
* they were all it held.
|
|
550
|
+
*/
|
|
551
|
+
async function removeIgnores(
|
|
552
|
+
repoRoot: string,
|
|
553
|
+
ignores: IgnoredDirectory[],
|
|
554
|
+
removed: string[],
|
|
555
|
+
attempt: (group: string[], line: string, act: () => unknown) => Promise<boolean>,
|
|
556
|
+
): Promise<void> {
|
|
557
|
+
const path = join(repoRoot, ".gitignore");
|
|
558
|
+
let rest = readTargetFile(path) ?? "";
|
|
559
|
+
for (const entry of ignores) rest = withoutIgnoreEntry(rest, entry) ?? rest;
|
|
560
|
+
|
|
561
|
+
const entries = ignores.map((entry) => `\`${entry.line}\``).join(" and ");
|
|
562
|
+
const line =
|
|
563
|
+
rest.trim() === ""
|
|
564
|
+
? ".gitignore: deleted, because the entries `init` wrote were all it held"
|
|
565
|
+
: `.gitignore: ${entries}, with the ${ignores.length === 1 ? "comment" : "comments"} \`init\` wrote ${ignores.length === 1 ? "it" : "them"} under`;
|
|
566
|
+
await attempt(removed, line, () => {
|
|
567
|
+
if (rest.trim() === "") rmSync(path);
|
|
568
|
+
else writeFileSync(path, rest);
|
|
569
|
+
});
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* The directories, as paths from the root, that removing files from `emptied`
|
|
574
|
+
* left with nothing in them, each walked up from the file's own until one
|
|
575
|
+
* still holds something: each held what was removed, so none of them was
|
|
576
|
+
* empty before, and a parent goes only once its children have.
|
|
577
|
+
*/
|
|
578
|
+
function prunable(repoRoot: string, emptied: Set<string>): string[] {
|
|
579
|
+
const pruned: string[] = [];
|
|
580
|
+
const isEmpty = (directory: string): boolean =>
|
|
581
|
+
existsSync(join(repoRoot, directory)) &&
|
|
582
|
+
listDirectory(join(repoRoot, directory)).every((name) =>
|
|
583
|
+
pruned.includes(join(directory, name)),
|
|
584
|
+
);
|
|
585
|
+
for (const start of emptied) {
|
|
586
|
+
for (
|
|
587
|
+
let directory = start;
|
|
588
|
+
directory !== "." && !pruned.includes(directory) && isEmpty(directory);
|
|
589
|
+
directory = dirname(directory)
|
|
590
|
+
) {
|
|
591
|
+
pruned.push(directory);
|
|
592
|
+
}
|
|
593
|
+
}
|
|
594
|
+
return pruned;
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
/**
|
|
598
|
+
* The lines of the last group: what the pipeline cannot prove it put there,
|
|
599
|
+
* or leaves on purpose, each with what to do about it.
|
|
600
|
+
*
|
|
601
|
+
* A GitHub question that fails is named in its line rather than failing the
|
|
602
|
+
* report: nothing here was a removal, so nothing here changes the exit code.
|
|
603
|
+
*/
|
|
604
|
+
async function leftForYou(
|
|
605
|
+
{ repoRoot, config, tracker, workspace }: RemoveOptions,
|
|
606
|
+
{
|
|
607
|
+
removed,
|
|
608
|
+
states = [],
|
|
609
|
+
stays = [],
|
|
610
|
+
}: {
|
|
611
|
+
removed: boolean;
|
|
612
|
+
states?: number[];
|
|
613
|
+
/** What the removal kept of what it set out to remove, and why. */
|
|
614
|
+
stays?: string[];
|
|
615
|
+
},
|
|
616
|
+
): Promise<string[]> {
|
|
617
|
+
const lines: string[] = [];
|
|
618
|
+
const asking = async (what: string, ask: () => Promise<string[]>): Promise<void> => {
|
|
619
|
+
try {
|
|
620
|
+
lines.push(...(await ask()));
|
|
621
|
+
} catch (failure) {
|
|
622
|
+
lines.push(`${what}: could not be listed — ${reason(failure)}`);
|
|
623
|
+
}
|
|
624
|
+
};
|
|
625
|
+
|
|
626
|
+
await asking("labels", async () => {
|
|
627
|
+
const existing = new Set(await tracker.listLabels());
|
|
628
|
+
return Object.entries(config.labels)
|
|
629
|
+
.filter(([role, name]) => role !== "inProgress" && existing.has(name))
|
|
630
|
+
.map(
|
|
631
|
+
([, name]) =>
|
|
632
|
+
`label \`${name}\`: Planning uses it too — \`gh label delete ${name}\` removes it`,
|
|
633
|
+
);
|
|
634
|
+
});
|
|
635
|
+
lines.push(
|
|
636
|
+
"merge settings: squash merging and deleting a pull request's branch when it merges are" +
|
|
637
|
+
" left as they are, since this repository may have had them before `init` —" +
|
|
638
|
+
" `gh repo edit --enable-squash-merge=false` or" +
|
|
639
|
+
" `gh repo edit --delete-branch-on-merge=false` turns one off",
|
|
640
|
+
);
|
|
641
|
+
await asking("branches on GitHub", async () => {
|
|
642
|
+
const branches = (await workspace.listRemoteBranches(AGENT_BRANCH_PREFIX)).sort();
|
|
643
|
+
if (branches.length === 0) return [];
|
|
644
|
+
const pulls = await tracker.openPullRequests();
|
|
645
|
+
return branches.map((branch) => {
|
|
646
|
+
const pull = pulls.find((candidate) => candidate.head === branch);
|
|
647
|
+
return pull === undefined
|
|
648
|
+
? `branch \`${branch}\` on GitHub: no pull request is open on it`
|
|
649
|
+
: `branch \`${branch}\` on GitHub: pull request #${pull.number} is open on it`;
|
|
650
|
+
});
|
|
651
|
+
});
|
|
652
|
+
await asking("the Notes issue", async () => {
|
|
653
|
+
const notes = await findStandingNotes({ tracker, needsTriage: config.labels.needsTriage });
|
|
654
|
+
return notes === undefined
|
|
655
|
+
? []
|
|
656
|
+
: [`issue #${notes}: the standing Notes issue, left open with the Notes on it`];
|
|
657
|
+
});
|
|
658
|
+
|
|
659
|
+
if (states.length > 0) {
|
|
660
|
+
lines.push(
|
|
661
|
+
`${states.map((ticket) => `#${ticket}`).join(", ")}: no Run can resume ${states.length === 1 ? "it" : "them"}` +
|
|
662
|
+
` any more, because ${states.length === 1 ? "its State file" : "their State files"}, and any` +
|
|
663
|
+
` hand-off transcripts kept beside ${states.length === 1 ? "it" : "them"}, went with \`${STATE_BRANCH}\``,
|
|
664
|
+
);
|
|
665
|
+
}
|
|
666
|
+
|
|
667
|
+
lines.push(
|
|
668
|
+
"comments on issues: the progress, hand-off and Note comments Runs wrote are left as they" +
|
|
669
|
+
" are, since they are addressed to humans",
|
|
670
|
+
);
|
|
671
|
+
|
|
672
|
+
const claude = readTargetFile(join(repoRoot, CLAUDE_FILENAME));
|
|
673
|
+
if (claudeFound(claude) === "edited") {
|
|
674
|
+
lines.push(
|
|
675
|
+
`${CLAUDE_FILENAME}: the section pointing at ${CONVENTIONS_PATH} is not the text \`init\`` +
|
|
676
|
+
" writes, so it stays",
|
|
677
|
+
);
|
|
678
|
+
}
|
|
679
|
+
const gitignore = (readTargetFile(join(repoRoot, ".gitignore")) ?? "").split("\n");
|
|
680
|
+
for (const entry of IGNORED) {
|
|
681
|
+
const kept = gitignore.some((line) => line.trim() === entry.line);
|
|
682
|
+
if (kept && withoutIgnoreEntry(gitignore.join("\n"), entry) === undefined) {
|
|
683
|
+
lines.push(
|
|
684
|
+
`.gitignore: \`${entry.line}\` stays, because it is not under the comment \`init\`` +
|
|
685
|
+
" writes it with",
|
|
686
|
+
);
|
|
687
|
+
}
|
|
688
|
+
}
|
|
689
|
+
|
|
690
|
+
lines.push(...stays);
|
|
691
|
+
if (removed) {
|
|
692
|
+
lines.push(
|
|
693
|
+
"nothing was committed: review the changes with `git status` and commit them yourself",
|
|
694
|
+
);
|
|
695
|
+
}
|
|
696
|
+
return lines;
|
|
697
|
+
}
|
|
698
|
+
|
|
699
|
+
/** One headed group of the report, indented under its heading. */
|
|
700
|
+
function logGroup(log: (line: string) => void, heading: string, lines: string[]): void {
|
|
701
|
+
log("");
|
|
702
|
+
log(`${heading}:`);
|
|
703
|
+
for (const line of lines.length === 0 ? ["nothing to remove"] : lines) log(` ${line}`);
|
|
704
|
+
}
|
|
705
|
+
|
|
706
|
+
/** The names in a directory, and none where there is no directory to read. */
|
|
707
|
+
function listDirectory(path: string): string[] {
|
|
708
|
+
try {
|
|
709
|
+
return readdirSync(path).sort();
|
|
710
|
+
} catch {
|
|
711
|
+
return [];
|
|
712
|
+
}
|
|
713
|
+
}
|
|
714
|
+
|
|
715
|
+
/**
|
|
716
|
+
* A path as the report names it, from the Target's root. Git names a
|
|
717
|
+
* worktree by its real path, so a root reached through a symlink is resolved
|
|
718
|
+
* before a path it does not start with is measured from it.
|
|
719
|
+
*/
|
|
720
|
+
function shown(repoRoot: string, path: string): string {
|
|
721
|
+
const from = relative(repoRoot, path);
|
|
722
|
+
if (!from.startsWith("..")) return from;
|
|
723
|
+
try {
|
|
724
|
+
return relative(realpathSync(repoRoot), path);
|
|
725
|
+
} catch {
|
|
726
|
+
return path;
|
|
727
|
+
}
|
|
728
|
+
}
|
|
729
|
+
|
|
730
|
+
function reason(failure: unknown): string {
|
|
731
|
+
return failure instanceof Error ? failure.message : String(failure);
|
|
732
|
+
}
|