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.
Files changed (55) hide show
  1. package/LICENSE +21 -0
  2. package/README.ko.md +97 -0
  3. package/README.md +98 -0
  4. package/bin/ticket-runner.js +6 -0
  5. package/docs/templates/operator-skill.md +87 -0
  6. package/package.json +42 -0
  7. package/src/acceptance-criteria.ts +44 -0
  8. package/src/adapters/claude-agent-runner.ts +389 -0
  9. package/src/adapters/exec.ts +169 -0
  10. package/src/adapters/gh-tracker.ts +955 -0
  11. package/src/adapters/git-workspace.ts +951 -0
  12. package/src/adapters/repo-root.ts +20 -0
  13. package/src/adapters/version.ts +118 -0
  14. package/src/base-branch.ts +21 -0
  15. package/src/branch.ts +33 -0
  16. package/src/cli.ts +135 -0
  17. package/src/command-line.ts +190 -0
  18. package/src/config.ts +277 -0
  19. package/src/conventions.ts +118 -0
  20. package/src/criteria.ts +106 -0
  21. package/src/frontier.ts +36 -0
  22. package/src/guards.ts +143 -0
  23. package/src/handoff.ts +82 -0
  24. package/src/host.ts +116 -0
  25. package/src/init.ts +405 -0
  26. package/src/labels.ts +42 -0
  27. package/src/landing.ts +75 -0
  28. package/src/lifecycle.ts +34 -0
  29. package/src/lock.ts +215 -0
  30. package/src/note-schema.ts +58 -0
  31. package/src/notes.ts +433 -0
  32. package/src/operator-skill.ts +24 -0
  33. package/src/orchestrator.ts +1816 -0
  34. package/src/ports/agent-runner.ts +105 -0
  35. package/src/ports/tracker.ts +334 -0
  36. package/src/ports/workspace.ts +422 -0
  37. package/src/progress.ts +231 -0
  38. package/src/prompts.ts +288 -0
  39. package/src/readiness.ts +256 -0
  40. package/src/remove.ts +732 -0
  41. package/src/resume.ts +145 -0
  42. package/src/run-log.ts +85 -0
  43. package/src/run.ts +331 -0
  44. package/src/self-hosting.ts +33 -0
  45. package/src/stage-guard.ts +32 -0
  46. package/src/staleness.ts +101 -0
  47. package/src/start.ts +284 -0
  48. package/src/startup.ts +34 -0
  49. package/src/stop.ts +178 -0
  50. package/src/stranded.ts +136 -0
  51. package/src/templates.ts +596 -0
  52. package/src/title.ts +97 -0
  53. package/src/verdict.ts +88 -0
  54. package/src/version-number.ts +67 -0
  55. package/src/version-pr.ts +103 -0
@@ -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
+ }