ticket-runner 0.6.5 → 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 +1 -1
- package/README.md +1 -1
- package/docs/templates/operator-skill.md +76 -11
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +97 -0
- package/src/adapters/claude-agent-runner.ts +2 -2
- package/src/adapters/exec.ts +15 -2
- package/src/adapters/gh-tracker.ts +259 -43
- package/src/adapters/git-workspace.ts +15 -2
- package/src/config.ts +18 -0
- package/src/conventions.ts +3 -3
- package/src/criteria.ts +81 -123
- package/src/guards.ts +19 -4
- package/src/note-schema.ts +12 -9
- package/src/notes.ts +11 -1
- package/src/orchestrator.ts +606 -163
- package/src/outside-fault.ts +103 -0
- package/src/ports/tracker.ts +16 -3
- package/src/ports/workspace.ts +29 -2
- package/src/progress.ts +40 -5
- package/src/prompts.ts +184 -19
- package/src/resume.ts +17 -9
- package/src/run.ts +50 -8
- package/src/start.ts +12 -4
- package/src/templates.ts +257 -89
- package/src/title.ts +73 -11
- package/src/transcript-home.ts +49 -0
- package/src/verdict.ts +130 -25
package/README.ko.md
CHANGED
|
@@ -37,7 +37,7 @@ Acceptance Criteria 체크리스트가 달리고, blocker가 연결됩니다. **
|
|
|
37
37
|
설정해 두었고, Ticket 하나는 세션 하나로 끝낼 만큼 작습니다.
|
|
38
38
|
- pull request에서 도는 CI 워크플로가 있고, 파이프라인이 직접 돌릴 테스트나 typecheck 명령이 있습니다.
|
|
39
39
|
- 돌리는 머신에 Node 22 이상, `git`, 인증된 [`gh`](https://cli.github.com/), 그리고
|
|
40
|
-
[`mattpocock-skills`](https://github.com/mattpocock/skills) 플러그인 1.
|
|
40
|
+
[`mattpocock-skills`](https://github.com/mattpocock/skills) 플러그인 1.3.0 이상 버전을 설치한 `claude`가
|
|
41
41
|
있습니다.
|
|
42
42
|
|
|
43
43
|
파이프라인은 묻지 않고 base branch에 merge합니다. 그걸 원하는 저장소에 쓰세요.
|
package/README.md
CHANGED
|
@@ -40,7 +40,7 @@ It fits a repository where:
|
|
|
40
40
|
run itself
|
|
41
41
|
- the machine running it has Node 22 or newer, `git`, an authenticated
|
|
42
42
|
[`gh`](https://cli.github.com/), and `claude` with the
|
|
43
|
-
[`mattpocock-skills`](https://github.com/mattpocock/skills) plugin, version 1.
|
|
43
|
+
[`mattpocock-skills`](https://github.com/mattpocock/skills) plugin, version 1.3.0 or later
|
|
44
44
|
|
|
45
45
|
It merges to your base branch without asking. It is for repositories where that is what you want.
|
|
46
46
|
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ticket-runner
|
|
3
|
-
description: Operate ticket-runner on this repository from a Claude Code cloud session — ready the Host (the machine the pipeline runs on), start a Run (one invocation of the pipeline)
|
|
3
|
+
description: Operate ticket-runner on this repository from a Claude Code cloud session — ready the Host (the machine the pipeline runs on), start a Run (one invocation of the pipeline) detached from the session's shell, narrowed to the Tickets (GitHub issues each sized for one session of work) the human names when they name any, watch its log and report each Ticket as it ends, pass on a Stop (the human's request that a Run finish the Tickets it holds and take no more), release a Run lock a vanished Host left behind, and, while no Run holds this repository, carry the human's decision on a handed-off Ticket (one given to a human to carry on) to the board when they ask. Use when the human asks to run the pipeline ("run it"), to work particular Tickets, to stop the Run, to release its lock, or to put a handed-off Ticket back for a Run. Never from a Stage (a Claude Code session a Run started for a single purpose).
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Operating ticket-runner
|
|
7
7
|
|
|
8
|
-
You are the Operator: the Claude session a human opened on this repository to run `ticket-runner` for them, and to watch and steer it from the app. You start the Run, report
|
|
8
|
+
You are the Operator: the Claude session a human opened on this repository to run `ticket-runner` for them, and to watch and steer it from the app. You start the Run, report the Tickets it ends, pass on a Stop, and release a lock when asked. While no Run holds this repository, you also carry the human's decision on a handed-off Ticket to the board when they ask, in the three ways [The board while no Run holds it](#the-board-while-no-run-holds-it) lists. Nothing else. The Run does the work, and everything else a human wants of a Ticket goes through the board by their own hand.
|
|
9
9
|
|
|
10
10
|
If `TICKET_RUNNER_STAGE` is set in your shell, you are a Stage of a Run, not an Operator. Stop here and use none of this.
|
|
11
11
|
|
|
@@ -43,24 +43,69 @@ Tell the human in one line which of these you installed, this repository's depen
|
|
|
43
43
|
|
|
44
44
|
## Start
|
|
45
45
|
|
|
46
|
-
Start what the human asked for
|
|
46
|
+
Start what the human asked for detached from your shell, with its output going to a log file, so it runs for as long as it needs and the session stays free to answer them. Give it no timeout, and never start it as a background command: one with a time limit is killed when the limit runs out, in the middle of a Ticket, and leaves the lock held and no summary.
|
|
47
47
|
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
48
|
+
What goes in place of `<arguments>` below:
|
|
49
|
+
|
|
50
|
+
- Nothing, to work through every Ticket that is ready.
|
|
51
|
+
- `<n>...` when the human names Tickets, one number each. The Run takes only those, lowest number first whatever order they were named in, and leaves every other Ticket alone.
|
|
52
|
+
- `--lanes <count>` when the human asks for a number of Tickets at once, with or without numbers. Pass it only when they do; otherwise the repository's own config decides.
|
|
53
|
+
- `--api-key` when the human asks for the Run to bill their API key rather than their Claude plan, beside numbers or `--lanes` or without. Pass it only when they do. Tell them an API-key Run needs a workstation Host: a cloud Host refuses it, because a cloud session runs every Stage on the subscription whatever key it exports.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
mkdir -p .ticket-runner
|
|
57
|
+
rm -f .ticket-runner/run.pid
|
|
58
|
+
setsid sh -c 'echo $$ > .ticket-runner/run.pid; ticket-runner run "$@"; echo "ticket-runner exited with $?"' sh <arguments> > .ticket-runner/run.log 2>&1 < /dev/null &
|
|
59
|
+
until [ -s .ticket-runner/run.pid ]; do sleep 1; done
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The log's last line is then the exit line, `ticket-runner exited with <code>`, written once the Run has ended. `.ticket-runner/` is ignored by git, so the log touches nothing the Run pulls. `ticket-runner stop` still finds the Run, through the pid its lock names.
|
|
52
63
|
|
|
53
64
|
Start one at a time. While a Run of yours is running, start no other.
|
|
54
65
|
|
|
66
|
+
## Watch
|
|
67
|
+
|
|
68
|
+
Watch the log with your tool that streams to you each line a command prints, running this command with `from` set to the first line to read:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
from=1
|
|
72
|
+
tail -n "+$from" -F --pid="$(cat .ticket-runner/run.pid)" .ticket-runner/run.log 2>/dev/null |
|
|
73
|
+
awk -v n="$from" '
|
|
74
|
+
/^ticket-runner [0-9][^ ]* run / { summary = 1 }
|
|
75
|
+
summary || !/^#[0-9]+ (claimed|resumed from|taken from the top|verified ·|fixing ·|rebased onto|resolving a rebase conflict|noted on #)/ { print n ": " $0; fflush() }
|
|
76
|
+
{ n++ }'
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
It shows each line it reads with that line's number in the log, except the progress lines: a Ticket claimed (resumed, or taken from the top), verified, fixing, rebased, resolving a rebase conflict, or noted on. From the summary's header on, it shows every line. It exits by itself once the Run has ended and the exit line has arrived.
|
|
80
|
+
|
|
81
|
+
When the watch expires before that, arm it again at once with `from` one past the number of the last line it showed, and say nothing to the human about it. Arm one watch at a time, and none once the exit line has come.
|
|
82
|
+
|
|
55
83
|
## Report
|
|
56
84
|
|
|
57
|
-
Report what the
|
|
85
|
+
Report what the watch shows, in a form a phone screen reads:
|
|
58
86
|
|
|
59
|
-
|
|
87
|
+
- One short line per Ticket that ended, saying which Ticket and whether it merged, was handed off (given to a human to carry on), was released (given back for a later Run to take up again) or was skipped, and why when the Run gives a reason.
|
|
88
|
+
- Any other line it shows, as it is worded: a refusal, which names what to do, the line saying a Release, or a hand-off GitHub or the remote cut short, stopped the Run, the Tickets a Stop left to finish, a warning.
|
|
89
|
+
|
|
90
|
+
Say nothing about a line the watch did not show, and nothing when you arm it again.
|
|
91
|
+
|
|
92
|
+
When the exit line arrives, report the summary, what the exit code means, and how many Notes the Run posted: defects a Stage met that belong to another Ticket or to none yet, posted on GitHub where a human will find them instead of being fixed there, one `noted` row each in the summary. Its exit code is `1` when at least one Ticket was handed off to a human, `2` when nothing was taken at all, because the Run was refused or because it was given Ticket numbers and took none of them, every one skipped or blocked, and `0` otherwise.
|
|
60
93
|
|
|
61
94
|
## Stop
|
|
62
95
|
|
|
63
|
-
When the human asks for a Stop, send the Run SIGTERM by running `ticket-runner stop`, which signals the Run this Host holds the lock for. Report what it prints, then keep
|
|
96
|
+
When the human asks for a Stop, send the Run SIGTERM by running `ticket-runner stop`, which signals the Run this Host holds the lock for. Report what it prints, then keep watching: a Stop finishes the Tickets the Run already holds and takes no more, so the Run ends by itself with its summary, whether or not it was given Ticket numbers. Never end a Run any other way. SIGINT or SIGKILL ends it in the middle of a Ticket.
|
|
97
|
+
|
|
98
|
+
## Your own Run gone
|
|
99
|
+
|
|
100
|
+
Your Run has gone without its summary when the watch ended with no summary before the exit line, or the log has no exit line and the pid in `.ticket-runner/run.pid` is no longer running (`kill -0` fails). It was killed: its Tickets were left stranded and its lock held. Read the lock, and this session's id beside it:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
git fetch origin ticket-runner/lock
|
|
104
|
+
git show FETCH_HEAD:lock.json
|
|
105
|
+
echo "${CLAUDE_CODE_REMOTE_SESSION_ID:-$CLAUDE_CODE_SESSION_ID}"
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
When the lock's `host.id` is this session's id, the lock names this Operator's Host. Do not ask the human to release it: a Run started here takes over a lock whose Run on this Host has gone, by itself, and resumes the Tickets it left stranded. Tell the human the Run ended without its summary, and offer to start it again; start it, as under [Start](#start), when they ask. A lock that names another Host is the next section's.
|
|
64
109
|
|
|
65
110
|
## Release a lock another Host left
|
|
66
111
|
|
|
@@ -82,7 +127,27 @@ git push --no-verify --force-with-lease="refs/heads/ticket-runner/lock:$tip" ori
|
|
|
82
127
|
|
|
83
128
|
Check that the `lock.json` it shows names the Host the refusal named before you push. If the push is refused, the lock moved: read it again and tell the human who holds it now. Delete nothing, on the remote or here.
|
|
84
129
|
|
|
130
|
+
## The board while no Run holds it
|
|
131
|
+
|
|
132
|
+
While a Run holds this repository, the board is the human's alone: the Run reads it as it goes, and a Stop is the human's only way into a running Run. No Run holds it while the lock is free, `lock.json` reading `{ "held": false }`, or names only your own Run that has gone ([Your own Run gone](#your-own-run-gone)). Read the lock as that section does right before you write. Then, and only when the human explicitly asks, you may carry their decision on a handed-off Ticket to the board in these three ways:
|
|
133
|
+
|
|
134
|
+
- Swap the Ticket's `ready-for-human` label for `ready-for-agent`, keeping its other labels. Where `ticket-runner.json` renames either label, use its name.
|
|
135
|
+
- Post the human's decision as a comment on the Ticket, in words the human approved, with each new criterion as its own `- [ ]` checkbox line.
|
|
136
|
+
- Turn a criterion the human names as replaced from `- [ ] X` into `- (superseded) X`, keeping its words, in the body or comment that holds it, so the verify Stage no longer grades it.
|
|
137
|
+
|
|
138
|
+
Write through `gh api`, as the Run does: a cloud Host refuses the GraphQL that `gh issue edit` and `gh issue comment` use. `{owner}/{repo}` is filled in by `gh` itself.
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
gh api -X DELETE "repos/{owner}/{repo}/issues/<n>/labels/ready-for-human"
|
|
142
|
+
gh api "repos/{owner}/{repo}/issues/<n>/labels" -f "labels[]=ready-for-agent"
|
|
143
|
+
gh api "repos/{owner}/{repo}/issues/<n>/comments" -F body=@<file>
|
|
144
|
+
gh api -X PATCH "repos/{owner}/{repo}/issues/<n>" -F body=@<file>
|
|
145
|
+
gh api -X PATCH "repos/{owner}/{repo}/issues/comments/<comment id>" -F body=@<file>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Keep `<file>` outside the checkout, in a temporary directory, and change nothing in it but the criterion the human named. Rewrite no criterion and no part of the body otherwise. If a Run holds the lock, write nothing, and tell the human to make the change on the board themselves.
|
|
149
|
+
|
|
85
150
|
## What you leave alone
|
|
86
151
|
|
|
87
152
|
- While your Run holds this repository, leave the checkout and `.worktrees/` alone. Edit no file, and run no git command that changes them: no checkout, pull, commit, stash, reset or worktree command. The Run pulls this checkout after every merge, and an edit of yours breaks that pull.
|
|
88
|
-
-
|
|
153
|
+
- Change no code, and close or edit no pull request. Relabel, comment on or edit an issue only as [The board while no Run holds it](#the-board-while-no-run-holds-it) allows: at the human's explicit request, while no Run holds this repository, and in those three ways. When the human asks for anything else about a Ticket, or for one of those while a Run holds this repository, tell them to do it on the board: a label, a comment or an edit to the issue is how a Run is steered.
|
package/package.json
CHANGED
|
@@ -42,3 +42,100 @@ export const UNCHECKED_BOX = String.raw`${ITEM_HEAD}\[ \]`;
|
|
|
42
42
|
* before and the after of the same count.
|
|
43
43
|
*/
|
|
44
44
|
export const TICKED_BOX = String.raw`${ITEM_HEAD}\[x\]`;
|
|
45
|
+
|
|
46
|
+
/** {@link UNCHECKED_BOX}, extended to capture the criterion after the box. */
|
|
47
|
+
const CRITERION_LINE = new RegExp(`${UNCHECKED_BOX}(.*)$`);
|
|
48
|
+
|
|
49
|
+
/** Any task list item, ticked or not, which a criterion's indented lines stop short of. */
|
|
50
|
+
const ANY_BOX = new RegExp(String.raw`${ITEM_HEAD}\[[ xX]\]`);
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* One Acceptance Criterion as the pipeline lists it for the verify Stage, by
|
|
54
|
+
* the number the verdict answers it with.
|
|
55
|
+
*
|
|
56
|
+
* The verdict answers a number rather than a copy of the text, so nothing ever
|
|
57
|
+
* has to match a Stage's copy back to a checkbox: the copy is where the verdict
|
|
58
|
+
* folded a sub-list into its line, decoded an escape or split a sentence, and
|
|
59
|
+
* left a met criterion unticked.
|
|
60
|
+
*/
|
|
61
|
+
export interface ListedCriterion {
|
|
62
|
+
/** Its place in the list, from 1: the body's checkboxes first, then each comment's. */
|
|
63
|
+
number: number;
|
|
64
|
+
/**
|
|
65
|
+
* The checkbox line exactly as the Ticket wrote it when it was listed. A met
|
|
66
|
+
* criterion is ticked on the unticked line that still reads so.
|
|
67
|
+
*/
|
|
68
|
+
line: string;
|
|
69
|
+
/** The criterion as its checkbox line reads after the box. */
|
|
70
|
+
text: string;
|
|
71
|
+
/**
|
|
72
|
+
* The indented lines under the checkbox that are not checkboxes themselves,
|
|
73
|
+
* as written: a sub-list or a code block that says what the line means. A
|
|
74
|
+
* nested checkbox is a criterion of its own, and so are the lines under it.
|
|
75
|
+
*/
|
|
76
|
+
details: string[];
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Every unticked checkbox on a Ticket, numbered in reading order: `texts` are
|
|
81
|
+
* the places it writes its criteria, its body first and then its comments.
|
|
82
|
+
*/
|
|
83
|
+
export function listCriteria(texts: readonly string[]): ListedCriterion[] {
|
|
84
|
+
const listed: ListedCriterion[] = [];
|
|
85
|
+
for (const text of texts) {
|
|
86
|
+
// A body edited on GitHub's web form ends its lines in CRLF; the line a
|
|
87
|
+
// criterion is listed as is the one ticking finds, which never holds the CR.
|
|
88
|
+
const lines = text.split(/\r?\n/);
|
|
89
|
+
for (const [index, line] of lines.entries()) {
|
|
90
|
+
const match = CRITERION_LINE.exec(line);
|
|
91
|
+
if (match === null) continue;
|
|
92
|
+
listed.push({
|
|
93
|
+
number: listed.length + 1,
|
|
94
|
+
line,
|
|
95
|
+
text: (match[2] ?? "").trim(),
|
|
96
|
+
details: detailsUnder(lines, index),
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
return listed;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* The lines indented under the checkbox at `lines[at]`, up to the first line
|
|
105
|
+
* that is not, leaving out any checkbox among them and the lines indented under
|
|
106
|
+
* that one. A blank line inside the run is kept; blank lines at its end are not.
|
|
107
|
+
*/
|
|
108
|
+
function detailsUnder(lines: readonly string[], at: number): string[] {
|
|
109
|
+
const own = indentOf(lines[at] ?? "");
|
|
110
|
+
const details: string[] = [];
|
|
111
|
+
/** The indent of a nested checkbox whose own lines are being passed over. */
|
|
112
|
+
let nested: number | undefined;
|
|
113
|
+
for (const line of lines.slice(at + 1)) {
|
|
114
|
+
if (line.trim() === "") {
|
|
115
|
+
if (nested === undefined) details.push(line);
|
|
116
|
+
continue;
|
|
117
|
+
}
|
|
118
|
+
const indent = indentOf(line);
|
|
119
|
+
if (indent <= own) break;
|
|
120
|
+
if (nested !== undefined && indent > nested) continue;
|
|
121
|
+
nested = undefined;
|
|
122
|
+
if (ANY_BOX.test(line)) {
|
|
123
|
+
nested = indent;
|
|
124
|
+
continue;
|
|
125
|
+
}
|
|
126
|
+
details.push(line);
|
|
127
|
+
}
|
|
128
|
+
while (details.length > 0 && (details.at(-1) ?? "").trim() === "") details.pop();
|
|
129
|
+
return details;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** How far a line is indented, a tab counting as four columns as Markdown counts it. */
|
|
133
|
+
function indentOf(line: string): number {
|
|
134
|
+
let width = 0;
|
|
135
|
+
for (const character of line) {
|
|
136
|
+
if (character === " ") width += 1;
|
|
137
|
+
else if (character === "\t") width += 4 - (width % 4);
|
|
138
|
+
else break;
|
|
139
|
+
}
|
|
140
|
+
return width;
|
|
141
|
+
}
|
|
@@ -321,7 +321,7 @@ interface StageLog {
|
|
|
321
321
|
/**
|
|
322
322
|
* What stands in a Stage's files for the Host's API key, wherever the session
|
|
323
323
|
* printed it: an `--api-key` Stage that runs `env` would otherwise put the key
|
|
324
|
-
* in a transcript, which
|
|
324
|
+
* in a transcript, which a hand-off may keep on the Target's remote.
|
|
325
325
|
*/
|
|
326
326
|
const REDACTED_KEY = `<${API_KEY_ENV_VAR}>`;
|
|
327
327
|
|
|
@@ -597,7 +597,7 @@ function structuredOutputOf(result: ResultEvent): unknown {
|
|
|
597
597
|
* How the environment differed from the Host's leads it: a subscription Stage
|
|
598
598
|
* ran without the Host's key, which `env -u` removes again, and an API-key
|
|
599
599
|
* Stage ran on it, which is named and left for the shell to fill in. Its value
|
|
600
|
-
* is never written: command files
|
|
600
|
+
* is never written: a hand-off may keep command files on the Target's remote.
|
|
601
601
|
*/
|
|
602
602
|
function quoteCommand(
|
|
603
603
|
credential: Credential,
|
package/src/adapters/exec.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { spawn } from "node:child_process";
|
|
2
|
+
import { OutsideFault, faultSide, firstLine } from "../outside-fault.js";
|
|
2
3
|
import { type Mark, killTree } from "./process-tree.js";
|
|
3
4
|
|
|
4
5
|
export interface Execution {
|
|
@@ -203,12 +204,24 @@ export function throwOnFailure(
|
|
|
203
204
|
result: Execution,
|
|
204
205
|
): Execution {
|
|
205
206
|
if (result.exitCode !== 0) {
|
|
206
|
-
const shown =
|
|
207
|
-
|
|
207
|
+
const shown = shownCommand(command, args);
|
|
208
|
+
const message = `\`${shown}\` exited ${result.exitCode}\n${result.output.trim()}`;
|
|
209
|
+
// The same message either way: what differs is whether the caller can
|
|
210
|
+
// tell GitHub or the remote failed, rather than the Ticket's own work.
|
|
211
|
+
const side = faultSide(command, result.output);
|
|
212
|
+
// stderr first, where both commands say why they failed: `gh api` prints
|
|
213
|
+
// the body of a 5xx, often a page of HTML, on stdout before it.
|
|
214
|
+
const line = firstLine(result.stderr) || firstLine(result.output);
|
|
215
|
+
throw side === undefined ? new Error(message) : new OutsideFault(side, shown, line, message);
|
|
208
216
|
}
|
|
209
217
|
return result;
|
|
210
218
|
}
|
|
211
219
|
|
|
220
|
+
/** A command as a failure names it: on one line, each argument by its first. */
|
|
221
|
+
export function shownCommand(command: string, args: string[]): string {
|
|
222
|
+
return [command, ...args.map(firstLineOf)].join(" ");
|
|
223
|
+
}
|
|
224
|
+
|
|
212
225
|
/** An argument as a failed command's message shows it: on one line. */
|
|
213
226
|
function firstLineOf(arg: string): string {
|
|
214
227
|
const newline = arg.search(/\r?\n/);
|