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
package/src/verdict.ts ADDED
@@ -0,0 +1,88 @@
1
+ import { NOTES_LIST_SCHEMA } from "./note-schema.js";
2
+ import { z } from "zod";
3
+
4
+ /**
5
+ * The structured result of the verify Stage: one status per Acceptance
6
+ * Criterion, with the evidence the session gathered for it.
7
+ */
8
+ const criterionSchema = z.object({
9
+ text: z.string(),
10
+ status: z.enum(["met", "unmet", "unverifiable"]),
11
+ evidence: z.string(),
12
+ });
13
+
14
+ const verdictSchema = z.object({
15
+ criteria: z.array(criterionSchema).min(1),
16
+ /** The agent's own opinion. The pipeline recomputes it; see {@link passes}. */
17
+ pass: z.boolean(),
18
+ });
19
+
20
+ export type Criterion = z.infer<typeof criterionSchema>;
21
+ export type Verdict = z.infer<typeof verdictSchema>;
22
+ export type CriterionStatus = Criterion["status"];
23
+
24
+ /**
25
+ * The `--json-schema` the verify Stage is invoked with: the Verdict, and the
26
+ * Notes channel beside it.
27
+ *
28
+ * The `notes` list has to be declared here even though {@link parseVerdict}
29
+ * strips it and the Notes parser reads it off any object at all, because this
30
+ * schema closes its top level to additional properties. That closure, not the
31
+ * parsing, is what would otherwise leave the most adversarial reader in the
32
+ * pipeline with nowhere to put a finding outside the criteria.
33
+ *
34
+ * It is not required, where the criteria and the flag are. The Verdict is the
35
+ * Stage's product and a session that graded nothing has done none of its job,
36
+ * so every required key here is a way for a Ticket to lose its Verdict — and a
37
+ * side channel may never cost one. A Verdict that leaves the list out is a
38
+ * Verdict from a session that found nothing beside the criteria.
39
+ */
40
+ export const VERDICT_JSON_SCHEMA = {
41
+ type: "object",
42
+ properties: {
43
+ criteria: {
44
+ type: "array",
45
+ items: {
46
+ type: "object",
47
+ properties: {
48
+ text: { type: "string", description: "The Acceptance Criterion verbatim" },
49
+ status: { type: "string", enum: ["met", "unmet", "unverifiable"] },
50
+ evidence: {
51
+ type: "string",
52
+ description: "What you ran or read, and what it showed",
53
+ },
54
+ },
55
+ required: ["text", "status", "evidence"],
56
+ additionalProperties: false,
57
+ },
58
+ },
59
+ pass: { type: "boolean" },
60
+ notes: NOTES_LIST_SCHEMA,
61
+ },
62
+ required: ["criteria", "pass"],
63
+ additionalProperties: false,
64
+ } as const;
65
+
66
+ /** Parse the verify Stage's structured output. Throws when it is unusable. */
67
+ export function parseVerdict(result: unknown): Verdict {
68
+ return verdictSchema.parse(result);
69
+ }
70
+
71
+ /**
72
+ * The pipeline's own pass decision: no criterion is unmet and at least one is
73
+ * met. A Verdict of nothing but `unverifiable` is zero evidence, so it fails.
74
+ */
75
+ export function passes(verdict: Verdict): boolean {
76
+ const counts = countStatuses(verdict);
77
+ return counts.unmet === 0 && counts.met > 0;
78
+ }
79
+
80
+ export function countStatuses(verdict: Verdict): Record<CriterionStatus, number> {
81
+ const counts: Record<CriterionStatus, number> = { met: 0, unmet: 0, unverifiable: 0 };
82
+ for (const criterion of verdict.criteria) counts[criterion.status] += 1;
83
+ return counts;
84
+ }
85
+
86
+ export function unmetCriteria(verdict: Verdict): Criterion[] {
87
+ return verdict.criteria.filter((criterion) => criterion.status === "unmet");
88
+ }
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Arithmetic on Version numbers: which of two is higher, and which number a tag
3
+ * or a Version string carries.
4
+ *
5
+ * Three readers share it and would otherwise each have a comparison of their
6
+ * own: the check on a Version PR, the notice a Run prints when a newer Version
7
+ * has been published, and the mark a Target's conventions document bears
8
+ * (ADR-0007). Nothing here reads a file or asks GitHub — a number against a
9
+ * number — so the one thing every Version question turns on is proved once.
10
+ */
11
+
12
+ /** A number on its own: the three parts every Version tag is cut at. */
13
+ const NUMBER = /^\d+\.\d+\.\d+$/;
14
+
15
+ /**
16
+ * The number a Version string reports, without the commit a development
17
+ * checkout adds: `0.4.0+331d79c.dirty` is `0.4.0`.
18
+ *
19
+ * Undefined where the string carries no number at all, which is what a copy
20
+ * with no package to read calls itself. Comparing by number is what lets a
21
+ * checkout running a commit past the latest Version count as current rather
22
+ * than as stale: between two Versions the commit says nothing either way.
23
+ */
24
+ export function versionNumber(version: string): string | undefined {
25
+ const [number = ""] = version.split("+");
26
+ return NUMBER.test(number) ? number : undefined;
27
+ }
28
+
29
+ /** The number a Version tag names: `v0.4.0` is `0.4.0`, and nothing else is one. */
30
+ export function tagNumber(tag: string): string | undefined {
31
+ return tag.startsWith("v") ? versionNumber(tag.slice(1)) : undefined;
32
+ }
33
+
34
+ /** A Version tag, in both halves its readers want: `v0.4.0` and `0.4.0`. */
35
+ export interface VersionTag {
36
+ tag: string;
37
+ number: string;
38
+ }
39
+
40
+ /**
41
+ * The highest Version among tags shaped `v<x.y.z>`, and undefined where there
42
+ * is no Version tag at all — the first Version, which nothing can be measured
43
+ * against.
44
+ *
45
+ * Every other tag is ignored rather than refused: a repository is free to tag
46
+ * whatever else it likes, and only the Versions say what has been cut. The tag
47
+ * comes back beside its number because a message names the tag as it was cut
48
+ * and the comparison is on the number.
49
+ */
50
+ export function highestVersion(tags: string[]): VersionTag | undefined {
51
+ return tags.reduce<VersionTag | undefined>((highest, tag) => {
52
+ const number = tagNumber(tag);
53
+ if (number === undefined) return highest;
54
+ return highest === undefined || isHigher(number, highest.number) ? { tag, number } : highest;
55
+ }, undefined);
56
+ }
57
+
58
+ /** Whether `number` is above `other`, part by part as numbers: `0.10.0` is above `0.9.0`. */
59
+ export function isHigher(number: string, other: string): boolean {
60
+ const parts = number.split(".").map(Number);
61
+ const others = other.split(".").map(Number);
62
+ for (const [index, part] of parts.entries()) {
63
+ const against = others[index] ?? 0;
64
+ if (part !== against) return part > against;
65
+ }
66
+ return false;
67
+ }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * What a Version PR has to get right, and what its merge publishes.
3
+ *
4
+ * A Version is cut by merging a Version PR: the number in `package.json` goes
5
+ * up, `CHANGELOG.md` gains that Version's section, and the push to `main`
6
+ * creates the tag and a GitHub Release whose body is that section (ADR-0007).
7
+ * The check on the pull request and the workflow that publishes read the same
8
+ * changelog, so they are written together here: a check that found a section
9
+ * the extraction then missed would tag a Version and publish nothing, which is
10
+ * the one failure neither half can see on its own.
11
+ *
12
+ * Both functions are pure. Everything they judge — the two numbers, the tags,
13
+ * the changelog — is read by the workflow that calls them, because a check that
14
+ * ran git itself could not be tested without one.
15
+ */
16
+
17
+ import { highestVersion, isHigher } from "./version-number.js";
18
+
19
+ /**
20
+ * The one heading every Version's notes carry, whatever they group the rest by.
21
+ * What a Target or its human has to do after upgrading is the thing a reader of
22
+ * this tool cannot get anywhere else, so its absence is a refusal.
23
+ */
24
+ const AFTER_UPGRADING = "### After upgrading";
25
+
26
+ /** A pull request, in the five things a Version PR is judged by. */
27
+ export interface VersionPr {
28
+ /** The number in `package.json` on the head. */
29
+ number: string;
30
+ /** The number in `package.json` on the base branch. */
31
+ baseNumber: string;
32
+ /** The number in the lock file on the head. */
33
+ lockNumber: string;
34
+ /** Every tag the repository has, Version tags and anything else. */
35
+ tags: string[];
36
+ /** `CHANGELOG.md` on the head, empty where the head has none. */
37
+ changelog: string;
38
+ }
39
+
40
+ /**
41
+ * Every reason this pull request may not merge, in the order a reader meets
42
+ * them, and empty where it may.
43
+ *
44
+ * All of them at once rather than the first: the human fixing a Version PR is
45
+ * running the check through a pull request, and one refusal per push would cost
46
+ * a round trip each.
47
+ *
48
+ * A number equal to the base branch's is not a Version PR at all, so nothing
49
+ * else is looked at. That is every Ticket's pull request, which passes this
50
+ * check without being written for it.
51
+ */
52
+ export function versionPrRefusals(pr: VersionPr): string[] {
53
+ if (pr.number === pr.baseNumber) return [];
54
+
55
+ const refusals: string[] = [];
56
+ const highest = highestVersion(pr.tags);
57
+ if (highest !== undefined && !isHigher(pr.number, highest.number)) {
58
+ refusals.push(
59
+ `\`${pr.number}\` is not higher than every Version tag; \`${highest.tag}\` exists.`,
60
+ );
61
+ }
62
+ if (pr.lockNumber !== pr.number) {
63
+ refusals.push(`\`package-lock.json\` says \`${pr.lockNumber}\`, not \`${pr.number}\`.`);
64
+ }
65
+
66
+ const notes = versionNotes(pr.changelog, pr.number);
67
+ if (notes === undefined) {
68
+ refusals.push(`\`CHANGELOG.md\` has no \`## ${pr.number}\` section.`);
69
+ } else if (!notes.includes(AFTER_UPGRADING)) {
70
+ refusals.push(
71
+ `The \`${pr.number}\` section of \`CHANGELOG.md\` has no \`${AFTER_UPGRADING}\` heading.`,
72
+ );
73
+ }
74
+ return refusals;
75
+ }
76
+
77
+ /**
78
+ * The Version notes for `number`: its section of the changelog, without the
79
+ * `## ` heading the number is written in, and undefined where the changelog has
80
+ * no section for it.
81
+ *
82
+ * Undefined is not a failure. The tag workflow falls back to GitHub's generated
83
+ * notes, because a Version that reached `main` is cut either way.
84
+ */
85
+ export function versionNotes(changelog: string, number: string): string | undefined {
86
+ return sections(changelog).get(number)?.trim();
87
+ }
88
+
89
+ /**
90
+ * Every section of the changelog, by the number its heading names. A `## `
91
+ * heading is the boundary; the number is its first word, so a heading that lost
92
+ * its date is still read. The newest of two sections for one number wins, since
93
+ * the file is newest first.
94
+ */
95
+ function sections(changelog: string): Map<string, string> {
96
+ const found = new Map<string, string>();
97
+ for (const text of changelog.split(/^## /m).slice(1)) {
98
+ const [heading = "", ...body] = text.split("\n");
99
+ const number = heading.trim().split(/\s/)[0] ?? "";
100
+ if (!found.has(number)) found.set(number, body.join("\n"));
101
+ }
102
+ return found;
103
+ }