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
|
@@ -13,12 +13,14 @@ import type {
|
|
|
13
13
|
PullRequestRef,
|
|
14
14
|
SquashCommit,
|
|
15
15
|
Tracker,
|
|
16
|
+
Visibility,
|
|
16
17
|
} from "../ports/tracker.js";
|
|
17
18
|
import { DEFAULT_CI_GRACE_MINUTES } from "../config.js";
|
|
18
19
|
import { type HostKind, hostKind } from "../host.js";
|
|
19
20
|
import { MAX_TAIL_LINES, logTail } from "../log-tail.js";
|
|
20
21
|
import { highestVersion } from "../version-number.js";
|
|
21
|
-
import {
|
|
22
|
+
import { OutsideFault, firstLine, isGitHubFault } from "../outside-fault.js";
|
|
23
|
+
import { type Execution, type RunProcess, exec, shownCommand, throwOnFailure } from "./exec.js";
|
|
22
24
|
|
|
23
25
|
export interface GhTrackerOptions {
|
|
24
26
|
run?: RunProcess;
|
|
@@ -38,6 +40,44 @@ export interface GhTrackerOptions {
|
|
|
38
40
|
host?: HostKind;
|
|
39
41
|
}
|
|
40
42
|
|
|
43
|
+
/**
|
|
44
|
+
* How long each try again of a `gh` call GitHub failed on its own side waits,
|
|
45
|
+
* in turn: doubling, and about a minute in all. A gateway down for seconds
|
|
46
|
+
* costs seconds, and one still down after the last is a fault of GitHub's,
|
|
47
|
+
* which the caller is told as an {@link OutsideFault}.
|
|
48
|
+
*/
|
|
49
|
+
export const GITHUB_RETRY_DELAYS_MS: readonly number[] = [2_000, 4_000, 8_000, 16_000, 30_000];
|
|
50
|
+
|
|
51
|
+
/** What a call's stdout has to parse as: one JSON document, or one per line as `--jq` prints them. */
|
|
52
|
+
type Json = "document" | "lines";
|
|
53
|
+
|
|
54
|
+
/** How one `gh` call is run, and what of its failure the caller takes as an answer. */
|
|
55
|
+
interface GhOptions {
|
|
56
|
+
/** A failure comes back rather than throwing, once GitHub's own faults have had their tries. */
|
|
57
|
+
allowFailure?: boolean;
|
|
58
|
+
/** The one failure a caller takes as an answer: it comes back instead of throwing. */
|
|
59
|
+
tolerate?: RegExp;
|
|
60
|
+
/** What stdout must parse as. A response that does not is GitHub's fault, and tried again. */
|
|
61
|
+
json?: Json;
|
|
62
|
+
/**
|
|
63
|
+
* Tried once whatever fails: a write that creates something, which a second
|
|
64
|
+
* try after a failure that had in fact landed would create twice.
|
|
65
|
+
*/
|
|
66
|
+
once?: boolean;
|
|
67
|
+
/**
|
|
68
|
+
* Whether what the call does has already happened, as a pull request a 502
|
|
69
|
+
* opened all the same has. Yes ends the tries, and the call answers with the
|
|
70
|
+
* failure it last met.
|
|
71
|
+
*
|
|
72
|
+
* Asked after each wait, before trying again, as a glance: once, and a
|
|
73
|
+
* failure to answer is a no. Asked again when GitHub refuses the call, since
|
|
74
|
+
* a refusal can be GitHub declining to do twice what an earlier try did while
|
|
75
|
+
* the glance between them failed. That ask is `patient`: tried again like any
|
|
76
|
+
* read, and a fault of GitHub's that outlasts the tries is thrown.
|
|
77
|
+
*/
|
|
78
|
+
landed?: (patient: boolean) => Promise<boolean>;
|
|
79
|
+
}
|
|
80
|
+
|
|
41
81
|
/**
|
|
42
82
|
* One issue as the REST API reports it, in the fields the pipeline reads. The
|
|
43
83
|
* issue list, the dependency list and a single issue all answer in this shape.
|
|
@@ -82,6 +122,8 @@ interface RawPullRequest {
|
|
|
82
122
|
/** The GraphQL id, which a workstation's draft and ready mutations take. */
|
|
83
123
|
node_id: string;
|
|
84
124
|
draft: boolean;
|
|
125
|
+
/** Whether it has merged, which a merge GitHub failed to answer may have. */
|
|
126
|
+
merged?: boolean;
|
|
85
127
|
head: { sha: string };
|
|
86
128
|
/**
|
|
87
129
|
* Whether GitHub can merge the pull request into its base: `false` when the
|
|
@@ -233,6 +275,26 @@ export class GhTracker implements Tracker {
|
|
|
233
275
|
}
|
|
234
276
|
}
|
|
235
277
|
|
|
278
|
+
/**
|
|
279
|
+
* Whether the Target is public, read through REST like {@link repository}.
|
|
280
|
+
* Every failure, and a visibility GitHub may add later, is no answer, which
|
|
281
|
+
* the caller counts as public.
|
|
282
|
+
*/
|
|
283
|
+
async visibility(): Promise<Visibility | undefined> {
|
|
284
|
+
try {
|
|
285
|
+
const { exitCode, stdout } = await this.gh(
|
|
286
|
+
["api", "repos/{owner}/{repo}", "--jq", ".visibility"],
|
|
287
|
+
{ allowFailure: true },
|
|
288
|
+
);
|
|
289
|
+
if (exitCode !== 0) return undefined;
|
|
290
|
+
const said = stdout.trim();
|
|
291
|
+
if (said === "public") return "public";
|
|
292
|
+
return said === "private" || said === "internal" ? "private" : undefined;
|
|
293
|
+
} catch {
|
|
294
|
+
return undefined;
|
|
295
|
+
}
|
|
296
|
+
}
|
|
297
|
+
|
|
236
298
|
/**
|
|
237
299
|
* The tag of the highest version published on `repository` as a Release.
|
|
238
300
|
*
|
|
@@ -249,7 +311,7 @@ export class GhTracker implements Tracker {
|
|
|
249
311
|
try {
|
|
250
312
|
const { exitCode, stdout } = await this.gh(
|
|
251
313
|
["api", "--method", "GET", `repos/${repository}/releases`, "-F", "per_page=100"],
|
|
252
|
-
{ allowFailure: true },
|
|
314
|
+
{ allowFailure: true, json: "document" },
|
|
253
315
|
);
|
|
254
316
|
if (exitCode !== 0) return undefined;
|
|
255
317
|
const releases = JSON.parse(stdout) as RawRelease[];
|
|
@@ -327,7 +389,9 @@ export class GhTracker implements Tracker {
|
|
|
327
389
|
* its blockers, only a count of each.
|
|
328
390
|
*/
|
|
329
391
|
async getIssue(number: number): Promise<Issue> {
|
|
330
|
-
const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/issues/${number}`]
|
|
392
|
+
const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/issues/${number}`], {
|
|
393
|
+
json: "document",
|
|
394
|
+
});
|
|
331
395
|
const raw = JSON.parse(stdout) as RawIssue;
|
|
332
396
|
const comments = await this.list<RawComment>(`repos/{owner}/{repo}/issues/${number}/comments`);
|
|
333
397
|
const blockers = await this.blockers(number);
|
|
@@ -365,11 +429,18 @@ export class GhTracker implements Tracker {
|
|
|
365
429
|
* issue, so a missing label is `init`'s to catch, not this call's.
|
|
366
430
|
*/
|
|
367
431
|
async createIssue(issue: CreateIssue): Promise<IssueRef> {
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
432
|
+
// Once: a 502 can follow an issue GitHub did open, and a second try would
|
|
433
|
+
// open a second.
|
|
434
|
+
const { stdout } = await this.rest(
|
|
435
|
+
"POST",
|
|
436
|
+
"repos/{owner}/{repo}/issues",
|
|
437
|
+
[
|
|
438
|
+
`title=${issue.title}`,
|
|
439
|
+
`body=${issue.body}`,
|
|
440
|
+
...issue.labels.map((label) => `labels[]=${label}`),
|
|
441
|
+
],
|
|
442
|
+
{ once: true, json: "document" },
|
|
443
|
+
);
|
|
373
444
|
const created = JSON.parse(stdout) as Partial<RawIssue>;
|
|
374
445
|
if (typeof created.number !== "number" || typeof created.html_url !== "string") {
|
|
375
446
|
throw new Error(`could not read an issue number from gh output: ${stdout}`);
|
|
@@ -419,6 +490,7 @@ export class GhTracker implements Tracker {
|
|
|
419
490
|
"POST",
|
|
420
491
|
`repos/{owner}/{repo}/issues/${number}/assignees`,
|
|
421
492
|
[`assignees[]=${user}`],
|
|
493
|
+
{ json: "document" },
|
|
422
494
|
);
|
|
423
495
|
const assignees = (JSON.parse(stdout) as Partial<RawIssue>).assignees ?? [];
|
|
424
496
|
if (!assignees.some((assignee) => assignee.login.toLowerCase() === user.toLowerCase())) {
|
|
@@ -450,11 +522,18 @@ export class GhTracker implements Tracker {
|
|
|
450
522
|
await this.rest("DELETE", path, [], { tolerate: /Label does not exist/ });
|
|
451
523
|
}
|
|
452
524
|
|
|
453
|
-
/**
|
|
525
|
+
/**
|
|
526
|
+
* REST answers with the new comment, whose id is what it is edited by later.
|
|
527
|
+
* Posted once, as an issue is opened once: a second try after a 502 that had
|
|
528
|
+
* posted it would post it twice, and notify twice.
|
|
529
|
+
*/
|
|
454
530
|
async comment(number: number, body: string): Promise<IssueComment> {
|
|
455
|
-
const { stdout } = await this.rest(
|
|
456
|
-
|
|
457
|
-
|
|
531
|
+
const { stdout } = await this.rest(
|
|
532
|
+
"POST",
|
|
533
|
+
`repos/{owner}/{repo}/issues/${number}/comments`,
|
|
534
|
+
[`body=${body}`],
|
|
535
|
+
{ once: true, json: "document" },
|
|
536
|
+
);
|
|
458
537
|
return { ...withCommentId(JSON.parse(stdout) as RawComment), body };
|
|
459
538
|
}
|
|
460
539
|
|
|
@@ -470,14 +549,29 @@ export class GhTracker implements Tracker {
|
|
|
470
549
|
/**
|
|
471
550
|
* Open a pull request through REST, and read its number back out of the
|
|
472
551
|
* answer rather than off anything printed.
|
|
552
|
+
*
|
|
553
|
+
* Tried again after a fault of GitHub's like any write, but only once no
|
|
554
|
+
* pull request is open on the branch: one the failed try opened all the
|
|
555
|
+
* same is the answer. A try GitHub refuses, as it refuses a second pull
|
|
556
|
+
* request on one branch, is asked about the same way, so one opened while
|
|
557
|
+
* the lookup between tries failed is still the answer.
|
|
473
558
|
*/
|
|
474
559
|
async createPullRequest(pr: CreatePullRequest): Promise<PullRequestRef> {
|
|
560
|
+
let opened: PullRequestRef | undefined;
|
|
475
561
|
const { stdout } = await this.rest(
|
|
476
562
|
"POST",
|
|
477
563
|
"repos/{owner}/{repo}/pulls",
|
|
478
564
|
[`base=${pr.base}`, `head=${pr.head}`, `title=${pr.title}`, `body=${pr.body}`],
|
|
479
|
-
{
|
|
565
|
+
{
|
|
566
|
+
typed: [`draft=${pr.draft}`],
|
|
567
|
+
json: "document",
|
|
568
|
+
landed: async (patient) => {
|
|
569
|
+
opened = await this.openPullRequestOn(pr.head, patient);
|
|
570
|
+
return opened !== undefined;
|
|
571
|
+
},
|
|
572
|
+
},
|
|
480
573
|
);
|
|
574
|
+
if (opened !== undefined) return opened;
|
|
481
575
|
const created = JSON.parse(stdout) as Partial<RawPullRequest>;
|
|
482
576
|
if (typeof created.number !== "number" || typeof created.html_url !== "string") {
|
|
483
577
|
throw new Error(`could not read a pull request number from gh output: ${stdout}`);
|
|
@@ -493,6 +587,29 @@ export class GhTracker implements Tracker {
|
|
|
493
587
|
return pulls.map((pull) => ({ number: pull.number, head: pull.head.ref }));
|
|
494
588
|
}
|
|
495
589
|
|
|
590
|
+
/**
|
|
591
|
+
* The open pull request from `head`, or nothing where there is none.
|
|
592
|
+
*
|
|
593
|
+
* Between the tries of a create it is asked once, and GitHub not saying is
|
|
594
|
+
* nothing too: the next try then asks GitHub to open one, as it would have
|
|
595
|
+
* anyway. After a refusal it is asked `patient`ly, and a GitHub that still
|
|
596
|
+
* will not say is a fault of GitHub's, thrown as any read's is.
|
|
597
|
+
*/
|
|
598
|
+
private async openPullRequestOn(head: string, patient: boolean): Promise<PullRequestRef | undefined> {
|
|
599
|
+
try {
|
|
600
|
+
const pulls = await this.list<{ number: number; html_url: string; head: { ref: string } }>(
|
|
601
|
+
"repos/{owner}/{repo}/pulls",
|
|
602
|
+
["-f", "state=open"],
|
|
603
|
+
patient ? {} : { once: true },
|
|
604
|
+
);
|
|
605
|
+
const pull = pulls.find((candidate) => candidate.head.ref === head);
|
|
606
|
+
return pull === undefined ? undefined : { number: pull.number, url: pull.html_url };
|
|
607
|
+
} catch (error) {
|
|
608
|
+
if (patient) throw error;
|
|
609
|
+
return undefined;
|
|
610
|
+
}
|
|
611
|
+
}
|
|
612
|
+
|
|
496
613
|
async convertPullRequestToDraft(number: number): Promise<void> {
|
|
497
614
|
await this.setDraft(number, true);
|
|
498
615
|
}
|
|
@@ -621,18 +738,36 @@ export class GhTracker implements Tracker {
|
|
|
621
738
|
/**
|
|
622
739
|
* Squash-merge through REST, with the subject and body the pipeline composed
|
|
623
740
|
* as the commit's title and message.
|
|
741
|
+
*
|
|
742
|
+
* Tried again after a fault of GitHub's, but only while the pull request has
|
|
743
|
+
* not merged: a merge the failed try made is done. A try GitHub refuses, as
|
|
744
|
+
* it refuses to merge a pull request already merged, is asked about the same
|
|
745
|
+
* way, so a merge made while the lookup between tries failed is still done.
|
|
624
746
|
*/
|
|
625
747
|
async squashMerge(number: number, commit: SquashCommit): Promise<void> {
|
|
626
|
-
await this.rest(
|
|
627
|
-
"
|
|
628
|
-
`
|
|
629
|
-
`commit_message=${commit.body}
|
|
630
|
-
|
|
748
|
+
await this.rest(
|
|
749
|
+
"PUT",
|
|
750
|
+
`repos/{owner}/{repo}/pulls/${number}/merge`,
|
|
751
|
+
["merge_method=squash", `commit_title=${commit.subject}`, `commit_message=${commit.body}`],
|
|
752
|
+
{
|
|
753
|
+
landed: async (patient) => {
|
|
754
|
+
try {
|
|
755
|
+
return (await this.pullRequest(number, patient ? {} : { once: true })).merged === true;
|
|
756
|
+
} catch (error) {
|
|
757
|
+
if (patient) throw error;
|
|
758
|
+
return false;
|
|
759
|
+
}
|
|
760
|
+
},
|
|
761
|
+
},
|
|
762
|
+
);
|
|
631
763
|
}
|
|
632
764
|
|
|
633
765
|
/** One pull request, read through REST. */
|
|
634
|
-
private async pullRequest(number: number): Promise<RawPullRequest> {
|
|
635
|
-
const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/pulls/${number}`]
|
|
766
|
+
private async pullRequest(number: number, options: GhOptions = {}): Promise<RawPullRequest> {
|
|
767
|
+
const { stdout } = await this.gh(["api", `repos/{owner}/{repo}/pulls/${number}`], {
|
|
768
|
+
...options,
|
|
769
|
+
json: "document",
|
|
770
|
+
});
|
|
636
771
|
return JSON.parse(stdout) as RawPullRequest;
|
|
637
772
|
}
|
|
638
773
|
|
|
@@ -677,10 +812,14 @@ export class GhTracker implements Tracker {
|
|
|
677
812
|
* counts as its re-run, as `gh pr checks` counted it.
|
|
678
813
|
*/
|
|
679
814
|
private async ciSnapshot(number: number): Promise<CiSnapshot> {
|
|
680
|
-
const
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
815
|
+
const args = ["api", `repos/{owner}/{repo}/pulls/${number}`];
|
|
816
|
+
const pr = await this.gh(args, { allowFailure: true, json: "document" });
|
|
817
|
+
if (pr.exitCode !== 0) {
|
|
818
|
+
// GitHub failing on its own side after every try is no reading at all,
|
|
819
|
+
// where any other refusal reads as no checks, as it always has.
|
|
820
|
+
if (isGitHubFault(pr.output)) throwOnFailure("gh", args, pr);
|
|
821
|
+
return { checks: undefined, conflicting: false };
|
|
822
|
+
}
|
|
684
823
|
const { head, mergeable } = JSON.parse(pr.stdout) as RawPullRequest;
|
|
685
824
|
// `null` is GitHub still working it out, which is no conflict yet.
|
|
686
825
|
const conflicting = mergeable === false;
|
|
@@ -709,10 +848,12 @@ export class GhTracker implements Tracker {
|
|
|
709
848
|
* joins arrays, not the objects around them.
|
|
710
849
|
*/
|
|
711
850
|
private async wrappedList(path: string, key: string): Promise<unknown[] | undefined> {
|
|
712
|
-
const
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
851
|
+
const args = [...pagedGet(path), "--jq", `.${key}[]`];
|
|
852
|
+
const result = await this.gh(args, { allowFailure: true, json: "lines" });
|
|
853
|
+
if (result.exitCode !== 0) {
|
|
854
|
+
if (isGitHubFault(result.output)) throwOnFailure("gh", args, result);
|
|
855
|
+
return undefined;
|
|
856
|
+
}
|
|
716
857
|
try {
|
|
717
858
|
return result.stdout
|
|
718
859
|
.split("\n")
|
|
@@ -755,39 +896,114 @@ export class GhTracker implements Tracker {
|
|
|
755
896
|
method: "POST" | "PATCH" | "PUT" | "DELETE",
|
|
756
897
|
path: string,
|
|
757
898
|
fields: string[],
|
|
758
|
-
options:
|
|
899
|
+
options: GhOptions & { typed?: string[] } = {},
|
|
759
900
|
): Promise<Execution> {
|
|
901
|
+
const { typed = [], ...rest } = options;
|
|
760
902
|
const args = [
|
|
761
903
|
"api",
|
|
762
904
|
"--method",
|
|
763
905
|
method,
|
|
764
906
|
path,
|
|
765
907
|
...fields.flatMap((field) => ["-f", field]),
|
|
766
|
-
...
|
|
908
|
+
...typed.flatMap((field) => ["-F", field]),
|
|
767
909
|
];
|
|
768
|
-
|
|
769
|
-
if (options.allowFailure || options.tolerate?.test(result.output)) return result;
|
|
770
|
-
return throwOnFailure("gh", args, result);
|
|
910
|
+
return await this.gh(args, rest);
|
|
771
911
|
}
|
|
772
912
|
|
|
773
913
|
/**
|
|
774
914
|
* Every page of a REST list, as one array: `gh --paginate` joins the pages.
|
|
775
915
|
* `--method GET` is spelled out because fields would otherwise make it a POST.
|
|
776
916
|
*/
|
|
777
|
-
private async list<T>(path: string, fields: string[] = []): Promise<T[]> {
|
|
778
|
-
const { stdout } = await this.gh([...pagedGet(path), ...fields]);
|
|
917
|
+
private async list<T>(path: string, fields: string[] = [], options: GhOptions = {}): Promise<T[]> {
|
|
918
|
+
const { stdout } = await this.gh([...pagedGet(path), ...fields], { ...options, json: "document" });
|
|
779
919
|
return JSON.parse(stdout) as T[];
|
|
780
920
|
}
|
|
781
921
|
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
922
|
+
/**
|
|
923
|
+
* One `gh` call, tried again while GitHub fails on its own side.
|
|
924
|
+
*
|
|
925
|
+
* A 5xx, or an answer that is not the complete JSON the caller reads, is
|
|
926
|
+
* GitHub's: the call waits and tries again, {@link GITHUB_RETRY_DELAYS_MS}
|
|
927
|
+
* apart, and one that still fails after the last is an {@link OutsideFault}
|
|
928
|
+
* — or, for a caller that takes failures as answers, the failure it met.
|
|
929
|
+
* Every other failure is the caller's at once, as it always was, unless the
|
|
930
|
+
* call can tell it has landed: a refusal that follows a try GitHub failed may
|
|
931
|
+
* be GitHub declining to do again what that try did after all.
|
|
932
|
+
*/
|
|
933
|
+
private async gh(args: string[], options: GhOptions = {}): Promise<Execution> {
|
|
934
|
+
for (let tried = 0; ; tried++) {
|
|
935
|
+
const result = await this.runProcess("gh", args, {
|
|
936
|
+
...(this.cwd === undefined ? {} : { cwd: this.cwd }),
|
|
937
|
+
});
|
|
938
|
+
const fault = githubFaultIn(result, options);
|
|
939
|
+
const delay = options.once === true ? undefined : GITHUB_RETRY_DELAYS_MS[tried];
|
|
940
|
+
if (fault === undefined || delay === undefined) {
|
|
941
|
+
if (tried > 0 && refused(result, fault, options) && (await options.landed?.(true))) {
|
|
942
|
+
return result;
|
|
943
|
+
}
|
|
944
|
+
return finalAnswer(args, result, fault, options);
|
|
945
|
+
}
|
|
946
|
+
await this.sleep(delay);
|
|
947
|
+
if (await options.landed?.(false)) return result;
|
|
948
|
+
}
|
|
949
|
+
}
|
|
950
|
+
}
|
|
951
|
+
|
|
952
|
+
/**
|
|
953
|
+
* The fault of GitHub's a call met, in the one line the Run's last line quotes,
|
|
954
|
+
* or nothing where it met none: a 5xx or an unreadable answer `gh` reported,
|
|
955
|
+
* or an answer that is not the JSON the caller asked for. A failure the caller
|
|
956
|
+
* tolerates is its answer, whatever it says.
|
|
957
|
+
*/
|
|
958
|
+
function githubFaultIn(result: Execution, options: GhOptions): string | undefined {
|
|
959
|
+
if (result.exitCode !== 0) {
|
|
960
|
+
if (options.tolerate?.test(result.output)) return undefined;
|
|
961
|
+
return isGitHubFault(result.output) ? firstLine(result.output) : undefined;
|
|
962
|
+
}
|
|
963
|
+
return options.json === undefined ? undefined : incompleteJson(result.stdout, options.json);
|
|
964
|
+
}
|
|
965
|
+
|
|
966
|
+
/**
|
|
967
|
+
* Whether GitHub turned the call down, as a 4xx: a failure that is no fault of
|
|
968
|
+
* GitHub's and that the caller does not take as an answer.
|
|
969
|
+
*/
|
|
970
|
+
function refused(result: Execution, fault: string | undefined, options: GhOptions): boolean {
|
|
971
|
+
if (result.exitCode === 0 || fault !== undefined || options.allowFailure) return false;
|
|
972
|
+
return options.tolerate?.test(result.output) !== true;
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
/** Why `stdout` is not the JSON a caller reads, or nothing when it is. */
|
|
976
|
+
function incompleteJson(stdout: string, json: Json): string | undefined {
|
|
977
|
+
try {
|
|
978
|
+
if (json === "document") JSON.parse(stdout);
|
|
979
|
+
else for (const line of stdout.split("\n")) if (line.trim() !== "") JSON.parse(line);
|
|
980
|
+
return undefined;
|
|
981
|
+
} catch (error) {
|
|
982
|
+
return (error as Error).message;
|
|
983
|
+
}
|
|
984
|
+
}
|
|
985
|
+
|
|
986
|
+
/** A call's last answer, as its caller takes it: the result, or the error it is. */
|
|
987
|
+
function finalAnswer(
|
|
988
|
+
args: string[],
|
|
989
|
+
result: Execution,
|
|
990
|
+
fault: string | undefined,
|
|
991
|
+
options: GhOptions,
|
|
992
|
+
): Execution {
|
|
993
|
+
if (result.exitCode !== 0) {
|
|
994
|
+
if (options.allowFailure || options.tolerate?.test(result.output)) return result;
|
|
995
|
+
return throwOnFailure("gh", args, result);
|
|
996
|
+
}
|
|
997
|
+
if (fault !== undefined) {
|
|
998
|
+
const shown = shownCommand("gh", args);
|
|
999
|
+
throw new OutsideFault(
|
|
1000
|
+
"github",
|
|
1001
|
+
shown,
|
|
1002
|
+
fault,
|
|
1003
|
+
`\`${shown}\` answered with a response that is not complete JSON\n${fault}`,
|
|
1004
|
+
);
|
|
790
1005
|
}
|
|
1006
|
+
return result;
|
|
791
1007
|
}
|
|
792
1008
|
|
|
793
1009
|
/**
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
|
|
2
2
|
import { tmpdir } from "node:os";
|
|
3
|
-
import { basename, dirname, join, resolve } from "node:path";
|
|
3
|
+
import { basename, dirname, join, relative, resolve, sep } from "node:path";
|
|
4
4
|
import { type Host, currentHost, sameHost } from "../host.js";
|
|
5
5
|
import {
|
|
6
6
|
LOCK_BRANCH,
|
|
@@ -36,7 +36,7 @@ import {
|
|
|
36
36
|
stateFileName,
|
|
37
37
|
stateFileTicket,
|
|
38
38
|
} from "../resume.js";
|
|
39
|
-
import { transcriptFiles } from "../run-log.js";
|
|
39
|
+
import { stageLogDir, transcriptFiles } from "../run-log.js";
|
|
40
40
|
import { exec, execOrThrow, throwOnFailure } from "./exec.js";
|
|
41
41
|
|
|
42
42
|
/**
|
|
@@ -597,6 +597,13 @@ export class GitWorkspace implements Workspace {
|
|
|
597
597
|
throwOnFailure("git", args, result);
|
|
598
598
|
}
|
|
599
599
|
|
|
600
|
+
async unshallow(): Promise<boolean> {
|
|
601
|
+
const { stdout } = await this.git(["rev-parse", "--is-shallow-repository"]);
|
|
602
|
+
if (stdout.trim() !== "true") return false;
|
|
603
|
+
await this.git(["fetch", "--unshallow", this.remote]);
|
|
604
|
+
return true;
|
|
605
|
+
}
|
|
606
|
+
|
|
600
607
|
async pullBase(base: string): Promise<void> {
|
|
601
608
|
const { stdout } = await this.git(["rev-parse", "--abbrev-ref", "HEAD"]);
|
|
602
609
|
if (stdout.trim() === base) {
|
|
@@ -676,6 +683,12 @@ export class GitWorkspace implements Workspace {
|
|
|
676
683
|
return { branch: STATE_BRANCH, path: directory };
|
|
677
684
|
}
|
|
678
685
|
|
|
686
|
+
async transcriptsOnHost(ticket: number, runId: string): Promise<string | undefined> {
|
|
687
|
+
if (transcriptFiles(this.repoRoot, runId, ticket).length === 0) return undefined;
|
|
688
|
+
const directory = relative(this.repoRoot, stageLogDir(this.repoRoot, runId, ticket));
|
|
689
|
+
return `${directory.split(sep).join("/")}/`;
|
|
690
|
+
}
|
|
691
|
+
|
|
679
692
|
/**
|
|
680
693
|
* Rewrite the state branch as one new snapshot commit, the same as the tip
|
|
681
694
|
* but for `edits`, and push it over the tip it was built from. Edits that
|
package/src/config.ts
CHANGED
|
@@ -38,6 +38,7 @@ const configSchema = z
|
|
|
38
38
|
baseBranch: z.string().min(1).optional(),
|
|
39
39
|
lanes: z.number().int().positive().optional(),
|
|
40
40
|
checks: z.array(z.string().min(1)).optional(),
|
|
41
|
+
merge: z.boolean().optional(),
|
|
41
42
|
gates: z
|
|
42
43
|
.object({ checks: z.boolean().optional(), ci: z.boolean().optional() })
|
|
43
44
|
.strict()
|
|
@@ -55,6 +56,7 @@ const configSchema = z
|
|
|
55
56
|
ciTimeoutMinutes: z.number().positive().optional(),
|
|
56
57
|
ciGraceMinutes: z.number().nonnegative().optional(),
|
|
57
58
|
checkTimeoutMinutes: z.number().positive().optional(),
|
|
59
|
+
keepTranscripts: z.boolean().optional(),
|
|
58
60
|
labels: z
|
|
59
61
|
.object({
|
|
60
62
|
needsTriage: z.string().min(1).optional(),
|
|
@@ -100,6 +102,13 @@ export interface Config {
|
|
|
100
102
|
*/
|
|
101
103
|
lanes: number;
|
|
102
104
|
checks: string[];
|
|
105
|
+
/**
|
|
106
|
+
* Whether a Run merges a Ticket whose CI is green. A Target that merges by
|
|
107
|
+
* hand sets it to `false`, and its green Tickets are handed off with their
|
|
108
|
+
* pull requests as published. Not a gate: a gate switched off loosens what
|
|
109
|
+
* reaches a merge, and this tightens it.
|
|
110
|
+
*/
|
|
111
|
+
merge: boolean;
|
|
103
112
|
gates: { checks: boolean; ci: boolean };
|
|
104
113
|
stages: {
|
|
105
114
|
implement: StageConfig;
|
|
@@ -121,6 +130,12 @@ export interface Config {
|
|
|
121
130
|
* the whole pipeline, and every command gets the whole of it.
|
|
122
131
|
*/
|
|
123
132
|
checkTimeoutMinutes: number;
|
|
133
|
+
/**
|
|
134
|
+
* Whether a handed-off Ticket's transcripts are kept on the Target's remote,
|
|
135
|
+
* where the config says. Absent means it follows the Target's visibility,
|
|
136
|
+
* which {@link import("./transcript-home.js").resolveTranscriptHome} reads.
|
|
137
|
+
*/
|
|
138
|
+
keepTranscripts?: boolean;
|
|
124
139
|
labels: Labels;
|
|
125
140
|
}
|
|
126
141
|
|
|
@@ -189,6 +204,7 @@ export function loadConfig(repoRoot: string, version: string): Config {
|
|
|
189
204
|
...(file.baseBranch === undefined ? {} : { baseBranch: file.baseBranch }),
|
|
190
205
|
lanes: file.lanes ?? DEFAULT_LANES,
|
|
191
206
|
checks: file.checks ?? inferChecks(repoRoot),
|
|
207
|
+
merge: file.merge ?? true,
|
|
192
208
|
gates: {
|
|
193
209
|
checks: file.gates?.checks ?? true,
|
|
194
210
|
ci: file.gates?.ci ?? true,
|
|
@@ -203,6 +219,8 @@ export function loadConfig(repoRoot: string, version: string): Config {
|
|
|
203
219
|
ciTimeoutMinutes: file.ciTimeoutMinutes ?? 30,
|
|
204
220
|
ciGraceMinutes: file.ciGraceMinutes ?? DEFAULT_CI_GRACE_MINUTES,
|
|
205
221
|
checkTimeoutMinutes: file.checkTimeoutMinutes ?? DEFAULT_CHECK_TIMEOUT_MINUTES,
|
|
222
|
+
// Spread, as baseBranch is: unset is an answer of its own, not false.
|
|
223
|
+
...(file.keepTranscripts === undefined ? {} : { keepTranscripts: file.keepTranscripts }),
|
|
206
224
|
labels: labels(file.labels),
|
|
207
225
|
};
|
|
208
226
|
}
|
package/src/conventions.ts
CHANGED
|
@@ -94,13 +94,13 @@ Besides names such as GitHub and Claude Code, a capitalised word below is one of
|
|
|
94
94
|
## Branches
|
|
95
95
|
|
|
96
96
|
- \`agent/<n>-<slug>\` belongs to the pipeline. A Run creates one per Ticket, works in a worktree of it, and pushes it after every Stage that commits. The repository deletes it when the pull request merges, a setting \`ticket-runner init\` switches on. Nothing else branches there.
|
|
97
|
-
- \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, releasing a lock a vanished Host left behind.
|
|
97
|
+
- \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket where the \`keepTranscripts\` setting keeps them there, which it does by default only on a private repository. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, and, while no Run holds this repository, to carry the human's decision on a handed-off Ticket to the board, releasing a lock a vanished Host left behind.
|
|
98
98
|
|
|
99
99
|
## What a Ticket needs
|
|
100
100
|
|
|
101
101
|
A Ticket is one issue the pipeline can implement in a single session. It is refused unless it carries all three:
|
|
102
102
|
|
|
103
|
-
- **Acceptance Criteria** — unticked task list items, a \`- [ ]\` at the head of a line, in the issue body or in one of its comments.
|
|
103
|
+
- **Acceptance Criteria** — unticked task list items, a \`- [ ]\` at the head of a line, in the issue body or in one of its comments. The verify Stage grades them one by one, and beside them any defect the Ticket's own branch made, which fails the Ticket as an unmet criterion does unless the Ticket leaves it out of scope or a documented decision accepts it. A promise written as prose is not a criterion, and a Ticket whose checkboxes are all ticked has none.
|
|
104
104
|
- **Blockers as native dependencies** — GitHub's own \`blocked by\` edges, as \`gh issue create --blocked-by <n>\` records them. A \`Blocked by\` section in the body is a human-readable copy and nothing the pipeline reads.
|
|
105
105
|
- **The \`ready-for-agent\` label** — how a Run finds the Ticket. A Run labels it \`in-progress\` for as long as it holds it.
|
|
106
106
|
|
|
@@ -111,7 +111,7 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
|
|
|
111
111
|
|
|
112
112
|
## The Operator's skill
|
|
113
113
|
|
|
114
|
-
- \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
|
|
114
|
+
- \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. It also says what an Operator may write on the board, only at a human's explicit request and only while no Run holds this repository: swap a handed-off Ticket's \`ready-for-human\` label for \`ready-for-agent\`, post the human's decision as a comment with each new criterion as its own \`- [ ]\` checkbox, and turn a criterion the human names as replaced into \`- (superseded)\` followed by its words. It rewrites no criterion and no body otherwise. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
|
|
115
115
|
|
|
116
116
|
## Local directories
|
|
117
117
|
|