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/prompts.ts
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The prompt each Stage is given. Headless mode expands `/plugin:skill` in the
|
|
3
|
+
* prompt string, which is how the pipeline drives a user-invoked skill
|
|
4
|
+
* (ADR-0002).
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import { CONVENTIONS_PATH } from "./conventions.js";
|
|
8
|
+
import type { FailureKind } from "./lifecycle.js";
|
|
9
|
+
import { STAGE_ENV_VAR } from "./stage-guard.js";
|
|
10
|
+
import { BRANCH_TITLE } from "./title.js";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Appended to every Stage prompt, the fix Stage included, in every Target. The
|
|
14
|
+
* mechanical guard in `stage-guard.ts` is a tripwire against a slip; this is
|
|
15
|
+
* what covers intent. It holds wherever the Stage runs, so it names the
|
|
16
|
+
* pipeline as the command that started the session and says nothing of the
|
|
17
|
+
* checkout, which in any other Target is the Target's own.
|
|
18
|
+
*/
|
|
19
|
+
export const STAGE_BOUNDARY_GUIDANCE = `The \`ticket-runner\` command started this session, so running it is running yourself:
|
|
20
|
+
|
|
21
|
+
- Never run \`ticket-runner\` against this repository or GitHub.
|
|
22
|
+
- Never kill processes you did not start. A pattern kill such as \`pkill -f node\` takes down the Run you belong to.
|
|
23
|
+
- ${STAGE_ENV_VAR} is set in this shell and the pipeline's own CLI refuses to start while it is. That refusal is expected; do not work around it.`;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* Appended after {@link STAGE_BOUNDARY_GUIDANCE} only where the Target is the
|
|
27
|
+
* pipeline's own repository, as the Run decided before its first Ticket. There
|
|
28
|
+
* the checkout is the pipeline, so it has tests and fakes to exercise it with
|
|
29
|
+
* and spellings of its commands that name no installed `ticket-runner`.
|
|
30
|
+
*/
|
|
31
|
+
export const SELF_HOSTING_GUIDANCE = `This checkout is the pipeline that started this session:
|
|
32
|
+
|
|
33
|
+
- Exercise the pipeline only through its tests and fakes. Never run it from this checkout either, by any spelling: \`npm run ticket-runner\`, \`npx tsx src/cli.ts\`.`;
|
|
34
|
+
|
|
35
|
+
/** What a Stage is told about the pipeline it runs under, in the Target it runs in. */
|
|
36
|
+
function stageBoundary(selfHosted: boolean): string {
|
|
37
|
+
return selfHosted
|
|
38
|
+
? `${STAGE_BOUNDARY_GUIDANCE}\n\n${SELF_HOSTING_GUIDANCE}`
|
|
39
|
+
: STAGE_BOUNDARY_GUIDANCE;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* How the two Stages that write code are told to finish. A session ends with its
|
|
44
|
+
* turn and stops every background task it started, so a session that hands its
|
|
45
|
+
* last commit to a test run it left in the background never makes that commit.
|
|
46
|
+
* `uncommittedPaths` and `discardChanges` both leave gitignored files alone, so
|
|
47
|
+
* a Stage told only to remove what no commit carries deletes the dependencies
|
|
48
|
+
* it installed for nothing.
|
|
49
|
+
*/
|
|
50
|
+
const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed. Run your final tests in the foreground, then commit.
|
|
51
|
+
- Leave the worktree clean: commit your work and remove every untracked file that is not ignored and that no commit carries, test output included. The pipeline refuses a worktree holding changes no commit carries.
|
|
52
|
+
- Keep gitignored files, such as dependencies you installed. The pipeline does not count them against a clean worktree, and deleting them only leaves the next Stage to install them again.`;
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* How the two Stages that write code are told to title the branch. The title is
|
|
56
|
+
* an answer rather than a commit subject because a commit subject describes its
|
|
57
|
+
* own commit, and a later Stage could not retitle a branch whose first commit
|
|
58
|
+
* was already pushed without rewriting it.
|
|
59
|
+
*/
|
|
60
|
+
const titleGuidance = (base: string) =>
|
|
61
|
+
`- Answer a \`title\` beside your Notes: ${BRANCH_TITLE}, in the \`<type>(<scope>): <summary>\` shape \`${CONVENTIONS_PATH}\` states and without the \`(#<n>)\`. It titles the pull request and the squash commit on \`${base}\`, so each commit subject describes only its own commit.`;
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Guidance appended to every implement Stage, working around known defects of
|
|
65
|
+
* the `implement` skill in an unattended session.
|
|
66
|
+
*/
|
|
67
|
+
const implementGuidance = (base: string) => `This session is unattended. Follow this guidance as well as the skill's own:
|
|
68
|
+
|
|
69
|
+
- Confirm the Ticket title matches what you are about to build before you start.
|
|
70
|
+
- Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
|
|
71
|
+
${titleGuidance(base)}
|
|
72
|
+
- The review the skill asks for is \`/mattpocock-skills:code-review\`. Invoke it by that full name: the short name also matches the CLI's own built-in review skill, which runs neither the Standards review nor the Spec review.
|
|
73
|
+
- Spawn its review sub-agents with \`run_in_background: false\` set explicitly, several in one message so they still run in parallel. Omitting \`run_in_background\` still runs them in the background, and you would then reach your answer before the review has come back.
|
|
74
|
+
- Do not answer the schema until the review has returned and the fixes you take from it are committed. An answer you have already given does not stop you committing: the pipeline waits for this session to exit before it reads the branch.
|
|
75
|
+
- A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.
|
|
76
|
+
${FINISH_GUIDANCE}
|
|
77
|
+
- Do not spawn nested review agents beyond what the skill itself does.
|
|
78
|
+
- Do not open pull requests and do not close the issue; the pipeline does both.
|
|
79
|
+
- Commit all of your work to the branch that is already checked out.`;
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Appended to the two Stages that write code, which are the two that meet
|
|
83
|
+
* things this Ticket is not about. Nothing here changes what the Stage is for:
|
|
84
|
+
* it is the channel that stops a finding becoming either scope creep or a lost
|
|
85
|
+
* paragraph in a transcript.
|
|
86
|
+
*/
|
|
87
|
+
const notesGuidance = (standingNotes?: number) => `Notes for other Tickets: if you discover something that belongs to another Ticket, or to no Ticket yet, do not act on it here and do not widen this Ticket to cover it.
|
|
88
|
+
|
|
89
|
+
- Record it as a Note instead. Your structured output carries a \`notes\` list, and the pipeline posts each entry where a human will meet it.
|
|
90
|
+
${noteEntryGuidance(standingNotes)}`;
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* The same channel, as the Stage that grades rather than writes reads it.
|
|
94
|
+
*
|
|
95
|
+
* The guidance above is written for a Stage that could have fixed what it found
|
|
96
|
+
* and is told not to. verify could not: it is told to fix nothing in the first
|
|
97
|
+
* place, and what it has instead of a commit is a Verdict with a slot per
|
|
98
|
+
* Acceptance Criterion. So this says which findings that Verdict already
|
|
99
|
+
* carries — every judgement of a criterion — and gives the rest the Notes list,
|
|
100
|
+
* because a defect outside the criteria has no slot anywhere else.
|
|
101
|
+
*/
|
|
102
|
+
const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your Verdict grades this Ticket's Acceptance Criteria and nothing else, so anything you find beside them is lost unless you record it as a Note.
|
|
103
|
+
|
|
104
|
+
- What you make of a criterion belongs in the Verdict. A criterion you judge \`unmet\` or \`unverifiable\` is reported in its own slot with the evidence you gathered, and never in a Note as well.
|
|
105
|
+
- A defect the criteria do not cover is a Note. Your structured output carries a \`notes\` list beside the criteria, and the pipeline posts each entry where a human will meet it.
|
|
106
|
+
- A Note of yours carries the evidence that the defect is real in its \`evidence\` field, held to the standard you hold a criterion you judge \`unmet\` to. You have the branch and you can run it, so something you suspect but did not demonstrate is not a Note.
|
|
107
|
+
- Writing the Note is all you do about it: fix nothing, commit nothing, stage nothing, exactly as the rest of your brief says.
|
|
108
|
+
${noteEntryGuidance(standingNotes)}`;
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* What a Note is and what one looks like, whichever Stage is writing one.
|
|
112
|
+
* Written once, because a Stage reading a stale copy is the only place the drift
|
|
113
|
+
* would show.
|
|
114
|
+
*
|
|
115
|
+
* The bar leads, because it is the line that decides whether there is a Note at
|
|
116
|
+
* all. Scope alone — this belongs to another Ticket — was the whole of it once,
|
|
117
|
+
* and it let a preference through beside a defect: triage then read asides at
|
|
118
|
+
* the price of a Ticket each, and the Tickets that came out sent Stages back in
|
|
119
|
+
* to write more.
|
|
120
|
+
*/
|
|
121
|
+
const noteEntryGuidance = (standingNotes?: number) => `- A Note is a defect — something that behaves wrongly or breaks. A preference of yours, a refactor you would enjoy and a test that would be nice to have are not Notes, however right you are about them.
|
|
122
|
+
- Set \`ticket\` to the issue number the Note belongs to, and leave it out when you are not sure which one: a Note with no number becomes a comment on the issue the pipeline gathers Notes for triage on, where a wrong number lands on somebody else's Ticket.
|
|
123
|
+
- Write each Note in its parts: \`summary\` is one short sentence naming the defect; \`evidence\` is where the defect is and what shows it is real, what you ran or read, what you expected and what came back; \`impact\` is what breaks, and for whom; \`next\` is the fix, or the decision a human has to take before anyone can fix it, and is left out when there is neither.
|
|
124
|
+
- Write every part as plain sentences. No checkboxes: they would read as Acceptance Criteria.
|
|
125
|
+
- Emit \`"notes": []\` when you found nothing. That is the ordinary case and costs you nothing.${standingLine(standingNotes)}`;
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Where the Notes with no Ticket have been gathered so far, when any have.
|
|
129
|
+
*
|
|
130
|
+
* The number alone, never what is on it: the prompt would otherwise grow with
|
|
131
|
+
* the backlog, and the Stage can read the issue itself.
|
|
132
|
+
*
|
|
133
|
+
* What it is asked for is what the issue does not already record. A second
|
|
134
|
+
* report of a condition already there earns its comment by changing what a
|
|
135
|
+
* reader would do about it — the facets that become Acceptance Criteria are
|
|
136
|
+
* exactly those, and another instance of the same thing is a duplicate however
|
|
137
|
+
* differently it is worded. Written when one Stage wrote Notes, the rule
|
|
138
|
+
* withheld only an exact repeat; three Stages later that is a duplicate mill.
|
|
139
|
+
*/
|
|
140
|
+
function standingLine(standingNotes?: number): string {
|
|
141
|
+
if (standingNotes === undefined) return "";
|
|
142
|
+
return `\n- Notes with no Ticket are gathered on #${standingNotes}. Read it first and take what it already records as recorded: write a second Note about a condition it names only when what you saw changes what a reader would do about it, and not when it is another instance of the same thing.`;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
const VERIFY_INSTRUCTIONS = `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
|
|
146
|
+
|
|
147
|
+
- Read the Ticket's Acceptance Criteria from its body and from its comments; the checkbox list may live in either.
|
|
148
|
+
- Work in the checked-out branch, which already contains the implementation.
|
|
149
|
+
- Attempt to falsify every criterion: run the code, run the tests, and write throwaway tests where that is the only way to tell.
|
|
150
|
+
- Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
|
|
151
|
+
- Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
|
|
152
|
+
- End by emitting the Verdict: one entry per criterion with its status and the evidence you actually gathered.`;
|
|
153
|
+
|
|
154
|
+
const fixInstructions = (base: string) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
|
|
155
|
+
|
|
156
|
+
- Commit your fix on the branch you are on, in this worktree. Do not create a branch, do not open pull requests, and do not close the Ticket.
|
|
157
|
+
- Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
|
|
158
|
+
- Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.
|
|
159
|
+
- Stay inside this Ticket's Acceptance Criteria. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.
|
|
160
|
+
${FINISH_GUIDANCE}
|
|
161
|
+
- Write commit subjects in the convention \`${CONVENTIONS_PATH}\` states. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
|
|
162
|
+
${titleGuidance(base)}`;
|
|
163
|
+
|
|
164
|
+
const conflictInstructions = (base: string) => `You are the conflict Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and rebasing it onto \`${base}\` stopped on a conflict. That rebase is still in progress in this worktree, and finishing it is the whole of your job.
|
|
165
|
+
|
|
166
|
+
- Follow the skill. Resolve every hunk and carry the rebase through to the end; never \`git rebase --abort\`, and never rewind the branch to escape the conflict.
|
|
167
|
+
- Where the two sides are compatible, keep both intents. Where they are not, keep the behaviour this Ticket's Acceptance Criteria ask for, and keep \`${base}\`'s everywhere the Ticket is silent.
|
|
168
|
+
- Resolve, do not redesign. Implement nothing new, and touch no file the conflict did not.
|
|
169
|
+
- Leave no conflict marker behind in any file, committed or not.
|
|
170
|
+
- Do not push, do not open pull requests, and do not close the Ticket. The pipeline runs the Checks again as soon as you finish, and a failure there spends this Ticket's fix budget.`;
|
|
171
|
+
|
|
172
|
+
/** How the fix prompt announces each kind of failure. */
|
|
173
|
+
const failureSentences = (base: string): Record<FailureKind, string> => ({
|
|
174
|
+
"uncommitted-work":
|
|
175
|
+
"the Stage before you left changes in this worktree it never committed, listed below; commit what belongs to this Ticket and discard the rest",
|
|
176
|
+
"failed-check": "a Check the pipeline runs itself failed",
|
|
177
|
+
"unmet-criteria": "the verify Stage found unmet Acceptance Criteria",
|
|
178
|
+
"failed-ci": "a pull request check failed after the branch was pushed",
|
|
179
|
+
"unresolved-conflict": `the branch conflicts with ${base}, and the session sent in to resolve the rebase did not finish it`,
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
/** What went wrong, in the words the hand-off comment would have used. */
|
|
183
|
+
export interface FixFailure {
|
|
184
|
+
kind: FailureKind;
|
|
185
|
+
/** The one line a human would have read in a notification. */
|
|
186
|
+
summary: string;
|
|
187
|
+
/** Failing Check output, the unmet criteria with their evidence, or a CI excerpt. */
|
|
188
|
+
evidence: string;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** `/mattpocock-skills:implement <url>`, then the corrections, then config. */
|
|
192
|
+
export function implementPrompt(
|
|
193
|
+
issueUrl: string,
|
|
194
|
+
base: string,
|
|
195
|
+
extraPrompt: string,
|
|
196
|
+
selfHosted: boolean,
|
|
197
|
+
standingNotes?: number,
|
|
198
|
+
): string {
|
|
199
|
+
return sections([
|
|
200
|
+
`/mattpocock-skills:implement ${issueUrl}`,
|
|
201
|
+
implementGuidance(base),
|
|
202
|
+
stageBoundary(selfHosted),
|
|
203
|
+
notesGuidance(standingNotes),
|
|
204
|
+
extraPrompt,
|
|
205
|
+
]);
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
/** A fresh session with no plugin skill, graded against the Verdict schema. */
|
|
209
|
+
export function verifyPrompt(
|
|
210
|
+
issueUrl: string,
|
|
211
|
+
extraPrompt: string,
|
|
212
|
+
selfHosted: boolean,
|
|
213
|
+
standingNotes?: number,
|
|
214
|
+
): string {
|
|
215
|
+
return sections([
|
|
216
|
+
`Ticket: ${issueUrl}`,
|
|
217
|
+
VERIFY_INSTRUCTIONS,
|
|
218
|
+
stageBoundary(selfHosted),
|
|
219
|
+
verifyNotesGuidance(standingNotes),
|
|
220
|
+
extraPrompt,
|
|
221
|
+
]);
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** `/mattpocock-skills:resolving-merge-conflicts`, then the conflict git reported. */
|
|
225
|
+
export function conflictPrompt(
|
|
226
|
+
issueUrl: string,
|
|
227
|
+
conflict: string,
|
|
228
|
+
base: string,
|
|
229
|
+
extraPrompt: string,
|
|
230
|
+
selfHosted: boolean,
|
|
231
|
+
): string {
|
|
232
|
+
return sections([
|
|
233
|
+
"/mattpocock-skills:resolving-merge-conflicts",
|
|
234
|
+
`Ticket: ${issueUrl}`,
|
|
235
|
+
conflictInstructions(base),
|
|
236
|
+
outputSection("## Where the rebase stopped", conflict),
|
|
237
|
+
stageBoundary(selfHosted),
|
|
238
|
+
extraPrompt,
|
|
239
|
+
]);
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** A fresh session with no plugin skill, given one failure and told to mend it. */
|
|
243
|
+
export function fixPrompt(
|
|
244
|
+
issueUrl: string,
|
|
245
|
+
failure: FixFailure,
|
|
246
|
+
base: string,
|
|
247
|
+
extraPrompt: string,
|
|
248
|
+
selfHosted: boolean,
|
|
249
|
+
standingNotes?: number,
|
|
250
|
+
): string {
|
|
251
|
+
return sections([
|
|
252
|
+
`Ticket: ${issueUrl}`,
|
|
253
|
+
fixInstructions(base),
|
|
254
|
+
failureSection(failure, base),
|
|
255
|
+
stageBoundary(selfHosted),
|
|
256
|
+
notesGuidance(standingNotes),
|
|
257
|
+
extraPrompt,
|
|
258
|
+
]);
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** The failure, its kind and its evidence, under a heading naming the kind. */
|
|
262
|
+
function failureSection({ kind, summary, evidence }: FixFailure, base: string): string {
|
|
263
|
+
return outputSection(
|
|
264
|
+
`## The failure: ${failureSentences(base)[kind]}`,
|
|
265
|
+
evidence,
|
|
266
|
+
summary,
|
|
267
|
+
);
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
/**
|
|
271
|
+
* A heading, an optional line of prose, and raw command output. The output is
|
|
272
|
+
* fenced because it would otherwise be read as Markdown.
|
|
273
|
+
*/
|
|
274
|
+
function outputSection(heading: string, output: string, prose = ""): string {
|
|
275
|
+
const trimmed = output.trim();
|
|
276
|
+
return [
|
|
277
|
+
heading,
|
|
278
|
+
...(prose === "" ? [] : ["", prose]),
|
|
279
|
+
...(trimmed === "" ? [] : ["", "```", trimmed, "```"]),
|
|
280
|
+
].join("\n");
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
function sections(parts: string[]): string {
|
|
284
|
+
return parts
|
|
285
|
+
.map((part) => part.trim())
|
|
286
|
+
.filter((part) => part !== "")
|
|
287
|
+
.join("\n\n");
|
|
288
|
+
}
|
package/src/readiness.ts
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
import { readFileSync } from "node:fs";
|
|
2
|
+
import { join } from "node:path";
|
|
3
|
+
import type { Labels } from "./config.js";
|
|
4
|
+
import { CLAUDE_SECTION, CONVENTIONS_PATH, conventionsMark } from "./conventions.js";
|
|
5
|
+
import { OPERATOR_SKILL_PATH } from "./operator-skill.js";
|
|
6
|
+
import type { Authentication, Tracker } from "./ports/tracker.js";
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* What `ticket-runner init` must have left in a Target before a Run may start.
|
|
10
|
+
*
|
|
11
|
+
* One module says what a set-up Target looks like and two commands read it:
|
|
12
|
+
* `init` puts each item in place, and `run` refuses a Target that is missing
|
|
13
|
+
* one. A Run repairs nothing — a command that quietly wrote into the
|
|
14
|
+
* Target it was only asked to work in is the thing `init` exists to keep to one
|
|
15
|
+
* place — so the refusal names the item and the command that fixes it.
|
|
16
|
+
*
|
|
17
|
+
* Presence and the Version stamp, never content. The conventions document and
|
|
18
|
+
* the Operator's skill are the pipeline's own text and change with it, so
|
|
19
|
+
* comparing either at every start would refuse a Target for carrying last
|
|
20
|
+
* week's copy, which is a thing the next `init` rewrites and nothing a Run is
|
|
21
|
+
* worse for. The document's Version stamp is asked for, though never which
|
|
22
|
+
* Version it names: an Operator installs the pipeline a cloud Host runs at that
|
|
23
|
+
* Version, and a Target without one leaves it guessing (ADR-0008).
|
|
24
|
+
*
|
|
25
|
+
* The Target's own files are read here rather than through a port, which every
|
|
26
|
+
* external effect of a Run goes through. What a port buys is a fake to drive the
|
|
27
|
+
* state machine with, and there is no state machine here: this is five questions
|
|
28
|
+
* asked of a directory before a Run exists, and the answers are already driven
|
|
29
|
+
* from a temporary repository root, which is how the local state under
|
|
30
|
+
* `.ticket-runner/` is tested too (ADR-0004). Widening the `Workspace` port for
|
|
31
|
+
* them would put reads no Stage and no Ticket ever makes on the interface the
|
|
32
|
+
* orchestrator depends on.
|
|
33
|
+
*
|
|
34
|
+
* Every item is asked on every Host, the cloud's own needs included, so a
|
|
35
|
+
* Target a workstation accepts is never one a cloud Run then refuses.
|
|
36
|
+
*/
|
|
37
|
+
|
|
38
|
+
/** The file every agent session in a Target reads first. */
|
|
39
|
+
export const CLAUDE_FILENAME = "CLAUDE.md";
|
|
40
|
+
|
|
41
|
+
/** One of the pipeline's own directories, and the comment it is ignored under. */
|
|
42
|
+
export interface IgnoredDirectory {
|
|
43
|
+
comment: string;
|
|
44
|
+
line: string;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The pipeline's two directories, each under the comment `init` writes it
|
|
49
|
+
* with, in the order it writes them. `remove` takes an entry out only where
|
|
50
|
+
* both lines still read exactly this, so the two commands share one text.
|
|
51
|
+
*/
|
|
52
|
+
export const IGNORED: readonly IgnoredDirectory[] = [
|
|
53
|
+
{ comment: "# Pipeline worktrees, one per Ticket.", line: ".worktrees/" },
|
|
54
|
+
{ comment: "# Run logs, transcripts and state.", line: ".ticket-runner/" },
|
|
55
|
+
];
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Which of the pipeline's directories this Target's gitignore does not cover
|
|
59
|
+
* yet, in the order they are written. Empty is a Target that ignores both.
|
|
60
|
+
*/
|
|
61
|
+
export function missingIgnoreLines(repoRoot: string): IgnoredDirectory[] {
|
|
62
|
+
const ignored = new Set(
|
|
63
|
+
(readTargetFile(join(repoRoot, ".gitignore")) ?? "").split("\n").map(ignorePattern),
|
|
64
|
+
);
|
|
65
|
+
return IGNORED.filter((entry) => !ignored.has(ignorePattern(entry.line)));
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* What a gitignore line means, whatever it was punctuated as: `.worktrees`,
|
|
70
|
+
* `.worktrees/` and `/.worktrees/` all keep the same directory out of a commit,
|
|
71
|
+
* and a Target that already says one of them is not missing the others.
|
|
72
|
+
*/
|
|
73
|
+
function ignorePattern(line: string): string {
|
|
74
|
+
return line.trim().replace(/^\//, "").replace(/\/$/, "");
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* A gitignore without `entry`, where `init`'s comment and line are still there
|
|
79
|
+
* exactly and one straight after the other, and nothing where they are not:
|
|
80
|
+
* a line the Target ignores under a comment of its own may be the Target's.
|
|
81
|
+
*
|
|
82
|
+
* The blank line `init` put between the entry and what came before goes with
|
|
83
|
+
* it, so a gitignore reads as it did before `init` wrote into it.
|
|
84
|
+
*/
|
|
85
|
+
export function withoutIgnoreEntry(
|
|
86
|
+
gitignore: string,
|
|
87
|
+
entry: IgnoredDirectory,
|
|
88
|
+
): string | undefined {
|
|
89
|
+
const lines = gitignore.split("\n");
|
|
90
|
+
// The empty string after a last newline is no line of the file.
|
|
91
|
+
const ended = lines.at(-1) === "";
|
|
92
|
+
if (ended) lines.pop();
|
|
93
|
+
|
|
94
|
+
const at = lines.findIndex(
|
|
95
|
+
(line, index) => line === entry.comment && lines[index + 1] === entry.line,
|
|
96
|
+
);
|
|
97
|
+
if (at === -1) return undefined;
|
|
98
|
+
lines.splice(at, 2);
|
|
99
|
+
if (lines[at] === "" && (at === 0 || lines[at - 1] === "")) lines.splice(at, 1);
|
|
100
|
+
else if (at === lines.length && lines[at - 1] === "") lines.splice(at - 1, 1);
|
|
101
|
+
|
|
102
|
+
return lines.length === 0 ? "" : `${lines.join("\n")}${ended ? "\n" : ""}`;
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* A `CLAUDE.md` without the section `init` appends, where it is still there
|
|
107
|
+
* exactly and starts a line, and nothing where it is not: a section a human
|
|
108
|
+
* reworded is theirs, pointer or not. The blank line before it goes too.
|
|
109
|
+
*/
|
|
110
|
+
export function withoutClaudeSection(claude: string): string | undefined {
|
|
111
|
+
let at = claude.indexOf(CLAUDE_SECTION);
|
|
112
|
+
while (at > 0 && claude[at - 1] !== "\n") at = claude.indexOf(CLAUDE_SECTION, at + 1);
|
|
113
|
+
if (at === -1) return undefined;
|
|
114
|
+
|
|
115
|
+
let before = claude.slice(0, at);
|
|
116
|
+
let after = claude.slice(at + CLAUDE_SECTION.length);
|
|
117
|
+
if (after === "" || after.startsWith("\n")) {
|
|
118
|
+
if (before.endsWith("\n\n")) before = before.slice(0, -1);
|
|
119
|
+
else if (before === "") after = after.slice(1);
|
|
120
|
+
}
|
|
121
|
+
return `${before}${after}`;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* Whether a `CLAUDE.md` points at the conventions document, taking the contents
|
|
126
|
+
* a Target has there and `undefined` for a Target with no such file.
|
|
127
|
+
*
|
|
128
|
+
* Judged on the path, not on the section `init` writes: a human who reworded the
|
|
129
|
+
* section around the same path still has a pointer.
|
|
130
|
+
*/
|
|
131
|
+
export function hasClaudePointer(claude: string | undefined): boolean {
|
|
132
|
+
return claude !== undefined && claude.includes(CONVENTIONS_PATH);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export interface ReadinessOptions {
|
|
136
|
+
repoRoot: string;
|
|
137
|
+
labels: Labels;
|
|
138
|
+
tracker: Tracker;
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* The message a Run is refused with when this Target is not set up, and nothing
|
|
143
|
+
* when it is.
|
|
144
|
+
*
|
|
145
|
+
* The first missing item is the whole message: a human who has not run `init`
|
|
146
|
+
* here is missing all of them, and one item to put right reads as one command to
|
|
147
|
+
* type. The Target's own files are asked about before GitHub is, so that Target
|
|
148
|
+
* is refused without a network call at all. Whether `gh` is there to ask comes
|
|
149
|
+
* next, so a Host without it is refused in words rather than with the spawn
|
|
150
|
+
* error the first label lookup would crash on.
|
|
151
|
+
*/
|
|
152
|
+
export async function readinessRefusal({
|
|
153
|
+
repoRoot,
|
|
154
|
+
labels,
|
|
155
|
+
tracker,
|
|
156
|
+
}: ReadinessOptions): Promise<string | undefined> {
|
|
157
|
+
const missing =
|
|
158
|
+
missingFileMessage(repoRoot) ??
|
|
159
|
+
(await missingGhMessage(tracker)) ??
|
|
160
|
+
(await missingLabelMessage(tracker, labels)) ??
|
|
161
|
+
(await missingBranchDeletionMessage(tracker));
|
|
162
|
+
if (missing === undefined) return undefined;
|
|
163
|
+
|
|
164
|
+
return [
|
|
165
|
+
`This Target is not set up: ${missing}.`,
|
|
166
|
+
"Run `ticket-runner init` here and start again;",
|
|
167
|
+
"a Run puts nothing in place itself.",
|
|
168
|
+
].join(" ");
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** Names the first thing `init` writes into a Target that this one does not have. */
|
|
172
|
+
function missingFileMessage(repoRoot: string): string | undefined {
|
|
173
|
+
const [unignored] = missingIgnoreLines(repoRoot);
|
|
174
|
+
if (unignored !== undefined) {
|
|
175
|
+
return `\`.gitignore\` does not ignore \`${unignored.line}\``;
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
const conventions = readTargetFile(join(repoRoot, CONVENTIONS_PATH));
|
|
179
|
+
if (conventions === undefined) {
|
|
180
|
+
return `\`${CONVENTIONS_PATH}\` is not there`;
|
|
181
|
+
}
|
|
182
|
+
if (conventionsMark(conventions) === undefined) {
|
|
183
|
+
return `\`${CONVENTIONS_PATH}\` carries no Version`;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
if (!hasClaudePointer(readTargetFile(join(repoRoot, CLAUDE_FILENAME)))) {
|
|
187
|
+
return `\`${CLAUDE_FILENAME}\` does not point at \`${CONVENTIONS_PATH}\``;
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
// Asked of a workstation too, though only a cloud session reads it: a Target
|
|
191
|
+
// a local Run accepts is then one the app can run as well (ADR-0008).
|
|
192
|
+
if (readTargetFile(join(repoRoot, OPERATOR_SKILL_PATH)) === undefined) {
|
|
193
|
+
return `the Operator's skill \`${OPERATOR_SKILL_PATH}\` is not there`;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
return undefined;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/** What `init` and readiness both call a Host with no `gh` it can run. */
|
|
200
|
+
export const GH_NOT_INSTALLED = "`gh` is not installed";
|
|
201
|
+
|
|
202
|
+
/** What the human does about it, which neither of them can do for them. */
|
|
203
|
+
export const GH_INSTALL = "install the GitHub CLI from https://cli.github.com";
|
|
204
|
+
|
|
205
|
+
/**
|
|
206
|
+
* What is wrong with a `gh` that cannot speak to GitHub, as `init` and `remove`
|
|
207
|
+
* both say it, and what the human does about it: only a `gh` that runs can be
|
|
208
|
+
* logged in.
|
|
209
|
+
*/
|
|
210
|
+
export const GH_FAILURE: Record<
|
|
211
|
+
Exclude<Authentication, "authenticated">,
|
|
212
|
+
{ failure: string; remedy: string }
|
|
213
|
+
> = {
|
|
214
|
+
unauthenticated: { failure: "`gh` is not authenticated", remedy: "run `gh auth login`" },
|
|
215
|
+
"not-installed": { failure: GH_NOT_INSTALLED, remedy: GH_INSTALL },
|
|
216
|
+
};
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Names a `gh` that cannot be run at all, and the install that comes before
|
|
220
|
+
* the `init` the refusal goes on to name. One that runs but is not logged in is
|
|
221
|
+
* left to the GitHub questions after it, which fail on it loudly enough.
|
|
222
|
+
*/
|
|
223
|
+
async function missingGhMessage(tracker: Tracker): Promise<string | undefined> {
|
|
224
|
+
return (await tracker.authentication()) === "not-installed"
|
|
225
|
+
? `${GH_NOT_INSTALLED} — ${GH_INSTALL} first`
|
|
226
|
+
: undefined;
|
|
227
|
+
}
|
|
228
|
+
|
|
229
|
+
/** Names the first triage label this Target is missing, as config spells it. */
|
|
230
|
+
async function missingLabelMessage(
|
|
231
|
+
tracker: Tracker,
|
|
232
|
+
labels: Labels,
|
|
233
|
+
): Promise<string | undefined> {
|
|
234
|
+
const existing = new Set(await tracker.listLabels());
|
|
235
|
+
const missing = Object.values(labels).find((name) => !existing.has(name));
|
|
236
|
+
return missing === undefined ? undefined : `the \`${missing}\` label is not on this Target`;
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* Names the repository setting a cloud Host depends on, when it is off: nothing
|
|
241
|
+
* there can delete a branch, so a merged Ticket's goes only if GitHub takes it.
|
|
242
|
+
*/
|
|
243
|
+
async function missingBranchDeletionMessage(tracker: Tracker): Promise<string | undefined> {
|
|
244
|
+
return (await tracker.deletesBranchOnMerge())
|
|
245
|
+
? undefined
|
|
246
|
+
: "the repository does not delete a pull request's branch when it merges";
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** A Target file's contents, or nothing when the Target does not have it. */
|
|
250
|
+
export function readTargetFile(path: string): string | undefined {
|
|
251
|
+
try {
|
|
252
|
+
return readFileSync(path, "utf8");
|
|
253
|
+
} catch {
|
|
254
|
+
return undefined;
|
|
255
|
+
}
|
|
256
|
+
}
|