@intentius/chant 0.124.57 → 0.124.58

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 (121) hide show
  1. package/dist/ci-product-words.d.ts +47 -2
  2. package/dist/ci-product-words.d.ts.map +1 -1
  3. package/dist/ci-product-words.js +59 -1
  4. package/dist/ci-product.d.ts +26 -2
  5. package/dist/ci-product.d.ts.map +1 -1
  6. package/dist/ci-product.js +26 -2
  7. package/dist/cli/commands/init.d.ts +2 -0
  8. package/dist/cli/commands/init.d.ts.map +1 -1
  9. package/dist/cli/commands/init.js +1 -1
  10. package/dist/cli/handlers/build.d.ts.map +1 -1
  11. package/dist/cli/handlers/build.js +5 -1
  12. package/dist/cli/handlers/init.d.ts.map +1 -1
  13. package/dist/cli/handlers/init.js +16 -0
  14. package/dist/cli/handlers/serve.d.ts.map +1 -1
  15. package/dist/cli/handlers/serve.js +9 -0
  16. package/dist/cli/main.d.ts.map +1 -1
  17. package/dist/cli/main.js +6 -2
  18. package/dist/cli/mcp/product-tools.d.ts +40 -7
  19. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  20. package/dist/cli/mcp/product-tools.js +59 -15
  21. package/dist/cli/mcp/read-only.d.ts +2 -1
  22. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  23. package/dist/cli/mcp/read-only.js +2 -1
  24. package/dist/cli/mcp/server.d.ts +11 -0
  25. package/dist/cli/mcp/server.d.ts.map +1 -1
  26. package/dist/cli/mcp/server.js +15 -3
  27. package/dist/cli/mcp-config.d.ts +4 -1
  28. package/dist/cli/mcp-config.d.ts.map +1 -1
  29. package/dist/cli/mcp-config.js +6 -2
  30. package/dist/cli/parse-args.d.ts.map +1 -1
  31. package/dist/cli/parse-args.js +9 -0
  32. package/dist/cli/registry.d.ts +8 -0
  33. package/dist/cli/registry.d.ts.map +1 -1
  34. package/dist/components/pr-pipeline.d.ts +56 -0
  35. package/dist/components/pr-pipeline.d.ts.map +1 -1
  36. package/dist/components/pr-pipeline.js +55 -2
  37. package/dist/components/product-pipeline.d.ts +18 -1
  38. package/dist/components/product-pipeline.d.ts.map +1 -1
  39. package/dist/components/product-pipeline.js +8 -2
  40. package/dist/e2e-harness/driver.d.ts.map +1 -1
  41. package/dist/e2e-harness/driver.js +97 -0
  42. package/dist/e2e-harness/forgejo.d.ts +5 -1
  43. package/dist/e2e-harness/forgejo.d.ts.map +1 -1
  44. package/dist/e2e-harness/forgejo.js +35 -0
  45. package/dist/e2e-harness/index.d.ts +7 -0
  46. package/dist/e2e-harness/index.d.ts.map +1 -1
  47. package/dist/e2e-harness/index.js +11 -1
  48. package/dist/e2e-harness/ports.d.ts +31 -0
  49. package/dist/e2e-harness/ports.d.ts.map +1 -1
  50. package/dist/e2e-harness/scenario.d.ts.map +1 -1
  51. package/dist/e2e-harness/scenario.js +9 -5
  52. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  53. package/dist/e2e-harness/schemas/index.d.ts +22 -1
  54. package/dist/e2e-harness/schemas/index.d.ts.map +1 -1
  55. package/dist/e2e-harness/schemas/index.js +1 -1
  56. package/dist/e2e-harness/steps.d.ts.map +1 -1
  57. package/dist/e2e-harness/steps.js +4 -0
  58. package/dist/mcp/types.d.ts +9 -0
  59. package/dist/mcp/types.d.ts.map +1 -1
  60. package/dist/release-floors.d.ts +1 -1
  61. package/dist/release-floors.js +1 -1
  62. package/dist/template-request/index.d.ts +9 -0
  63. package/dist/template-request/index.d.ts.map +1 -0
  64. package/dist/template-request/index.js +8 -0
  65. package/dist/template-request/request-body.d.ts +21 -0
  66. package/dist/template-request/request-body.d.ts.map +1 -0
  67. package/dist/template-request/request-body.js +86 -0
  68. package/dist/template-request/template-request.d.ts +100 -0
  69. package/dist/template-request/template-request.d.ts.map +1 -0
  70. package/dist/template-request/template-request.js +150 -0
  71. package/dist/template-request/template-request.schema.json +100 -0
  72. package/dist/template-request/template-spec.d.ts +83 -0
  73. package/dist/template-request/template-spec.d.ts.map +1 -0
  74. package/dist/template-request/template-spec.js +146 -0
  75. package/dist/template-request/template.schema.json +114 -0
  76. package/dist/template-request/validate.d.ts +4 -0
  77. package/dist/template-request/validate.d.ts.map +1 -0
  78. package/dist/template-request/validate.js +21 -0
  79. package/dist/wave-runtime.mjs +4 -4
  80. package/package.json +8 -1
  81. package/src/ci-product-words.test.ts +23 -0
  82. package/src/ci-product-words.ts +68 -3
  83. package/src/ci-product.ts +32 -1
  84. package/src/cli/commands/init.ts +3 -1
  85. package/src/cli/handlers/build.ts +5 -1
  86. package/src/cli/handlers/init.ts +18 -0
  87. package/src/cli/handlers/serve.ts +9 -0
  88. package/src/cli/main.ts +6 -2
  89. package/src/cli/mcp/product-tools.test.ts +57 -1
  90. package/src/cli/mcp/product-tools.ts +67 -15
  91. package/src/cli/mcp/read-only.ts +2 -1
  92. package/src/cli/mcp/server.ts +20 -5
  93. package/src/cli/mcp-config.test.ts +52 -2
  94. package/src/cli/mcp-config.ts +6 -3
  95. package/src/cli/parse-args.ts +7 -0
  96. package/src/cli/registry.ts +8 -0
  97. package/src/components/pr-pipeline.ts +87 -2
  98. package/src/components/product-actions.test.ts +76 -0
  99. package/src/components/product-pipeline.ts +21 -2
  100. package/src/e2e-harness/driver.test.ts +163 -0
  101. package/src/e2e-harness/driver.ts +86 -1
  102. package/src/e2e-harness/forgejo.ts +42 -1
  103. package/src/e2e-harness/index.ts +12 -1
  104. package/src/e2e-harness/ports.ts +33 -0
  105. package/src/e2e-harness/scenario.ts +8 -6
  106. package/src/e2e-harness/schemas/README.md +11 -2
  107. package/src/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  108. package/src/e2e-harness/schemas/index.ts +5 -1
  109. package/src/e2e-harness/schemas.test.ts +44 -1
  110. package/src/e2e-harness/steps.ts +4 -0
  111. package/src/mcp/types.ts +9 -0
  112. package/src/release-floors.ts +1 -1
  113. package/src/template-request/__fixtures__/request-body.md +41 -0
  114. package/src/template-request/index.ts +8 -0
  115. package/src/template-request/request-body.ts +91 -0
  116. package/src/template-request/template-request.schema.json +100 -0
  117. package/src/template-request/template-request.test.ts +316 -0
  118. package/src/template-request/template-request.ts +235 -0
  119. package/src/template-request/template-spec.ts +176 -0
  120. package/src/template-request/template.schema.json +114 -0
  121. package/src/template-request/validate.ts +28 -0
@@ -5,14 +5,19 @@
5
5
  * the BREAK run, and checks each step's outcomes against chant's own reports
6
6
  * and run ledger, never the runner's status or logs.
7
7
  *
8
+ * A pull request comes from the driver's own open step or from a product:
9
+ * an await-pull step waits for the one a product opened from its branch
10
+ * (chant#4650), and later steps name it as they name an open step's.
11
+ *
8
12
  * A run ends one of three ways. Every outcome held: the plain run passes, and
9
13
  * a BREAK run that ends so was missed. An outcome did not hold: the run stops
10
14
  * there, the plain run fails, and the BREAK run was caught. A step did not
11
15
  * finish (past its limit, or an error): the run stalled, which is neither.
12
16
  */
13
17
  import { reportKey } from "../pr-report-url";
18
+ import type { GatedRequestRead } from "../lifecycle/gated-request";
14
19
  import type { OpRunRecord } from "../op/runtime";
15
- import type { Bucket, Chant, Clock, ForgeReads, Jobs, Ledger, Log, OutOfBand, PullForge } from "./ports";
20
+ import type { Bucket, Chant, Clock, ForgePull, ForgeReads, Jobs, Ledger, Log, OutOfBand, PullForge } from "./ports";
16
21
  import { componentStatuses, reportObjectKey, splitReportUrl, waitForReport, type PrReportView, type ReportStage } from "./reports";
17
22
  import type { BreakVerdict, PlainVerdict, Scenario, ScenarioOutcome, ScenarioStep, ScenarioStepKind } from "./schemas/index";
18
23
  import { limitsFor } from "./steps";
@@ -75,6 +80,12 @@ interface Opened {
75
80
 
76
81
  const iso = (ms: number) => new Date(ms).toISOString();
77
82
 
83
+ /** How a gated request stands: gated until a finished line names it, then ok or failed. */
84
+ function gatedStatus(r: GatedRequestRead): "gated" | "ok" | "failed" {
85
+ if (!r.finished) return "gated";
86
+ return r.finished.result === "applied" ? "ok" : "failed";
87
+ }
88
+
78
89
  /** The check of one outcome, or null when it holds. */
79
90
  async function checkOutcome(
80
91
  o: ScenarioOutcome,
@@ -106,6 +117,36 @@ async function checkOutcome(
106
117
  }
107
118
  return matching.length > 0 ? null : `no ${o.ledger.op} run${o.ledger.status ? ` ${o.ledger.status}` : ""} on the ledger since the run started`;
108
119
  }
120
+ if ("gated" in o) {
121
+ if (!p.ledger?.gatedRequests) throw new Stall("a gated outcome needs the ledger's gated requests");
122
+ const asked = (await p.ledger.gatedRequests(o.gated.op)).filter((r) => r.pending.timestamp >= ctx.since);
123
+ const matching = o.gated.status ? asked.filter((r) => gatedStatus(r) === o.gated.status) : asked;
124
+ const status = o.gated.status ? ` ${o.gated.status}` : "";
125
+ if (o.gated.count !== undefined) {
126
+ return matching.length === o.gated.count ? null : `${matching.length} gated ${o.gated.op} requests${status} on the ledger, not ${o.gated.count}`;
127
+ }
128
+ return matching.length > 0 ? null : `no gated ${o.gated.op} request${status} on the ledger since the run started`;
129
+ }
130
+ if ("pull" in o) {
131
+ if (ctx.pull === undefined) return "no pull request to read";
132
+ if (o.pull.title !== undefined) {
133
+ if (!p.forge.pullInfo) throw new Stall("a pull outcome with a title needs the forge's pull requests");
134
+ const info = await p.forge.pullInfo(ctx.pull);
135
+ if (!info) return `the forge does not know pull request ${ctx.pull}`;
136
+ if (!info.title.includes(o.pull.title)) return `pull request ${ctx.pull} is titled "${info.title}", which does not hold "${o.pull.title}"`;
137
+ }
138
+ if (o.pull.files !== undefined) {
139
+ if (!p.forge.changedFiles) throw new Stall("a pull outcome with files needs the forge's changed files");
140
+ const changed = await p.forge.changedFiles(ctx.pull);
141
+ const missing = o.pull.files.filter((f) => !changed.includes(f));
142
+ if (missing.length > 0) return `pull request ${ctx.pull} does not change ${missing.join(", ")}`;
143
+ if (o.pull.only) {
144
+ const extra = changed.filter((f) => !o.pull.files!.includes(f));
145
+ if (extra.length > 0) return `pull request ${ctx.pull} also changes ${extra.join(", ")} beyond the files named`;
146
+ }
147
+ }
148
+ return null;
149
+ }
109
150
  if ("comment" in o) {
110
151
  if (!p.forge.comments) throw new Stall("a comment outcome needs the forge's comments");
111
152
  if (ctx.pull === undefined) return "no pull request to read comments of";
@@ -175,10 +216,39 @@ export async function runArm(s: Scenario, arm: Arm, p: DriverPorts, opts: Driver
175
216
  if (!o) throw new Stall(`no pull request from ${id}`);
176
217
  return o;
177
218
  };
219
+ // The pull requests open when the run started. await-pull never binds one
220
+ // of these, so the BREAK run cannot pick up the plain run's pull request
221
+ // when the reset left it open.
222
+ let before = new Set<number>();
223
+ const awaitPull = async (step: Extract<ScenarioStep, { do: "await-pull" }>): Promise<StepResult> => {
224
+ const find = p.forge.findPull;
225
+ if (!find) throw new Stall("an await-pull step needs the forge's findPull");
226
+ // The product picks the branch, so it is the same on both runs.
227
+ const deadline = deadlineOf("await-pull");
228
+ let seen: ForgePull | undefined;
229
+ for (;;) {
230
+ const found = await find.call(p.forge, step.branch);
231
+ if (found && !before.has(found.number) && (step.title === undefined || found.title.includes(step.title))) {
232
+ opened.set(step.id, { pull: found.number, head: found.head });
233
+ log(`${s.id} ${arm}: ${step.id} found pull request ${found.number} at ${found.head.slice(0, 8)}`);
234
+ return { id: step.id, do: step.do, pull: found.number, commit: found.head };
235
+ }
236
+ if (found) seen = found;
237
+ if (p.clock.now() >= deadline) break;
238
+ await p.clock.sleep(opts.pollMs ?? 2000);
239
+ }
240
+ const why = !seen
241
+ ? `no open pull request from ${step.branch} within ${limits["await-pull"]}s`
242
+ : before.has(seen.number)
243
+ ? `pull request ${seen.number} from ${step.branch} was open before the run started, and no new one came within ${limits["await-pull"]}s`
244
+ : `pull request ${seen.number} from ${step.branch} is titled "${seen.title}", which does not hold "${step.title}", after ${limits["await-pull"]}s`;
245
+ throw new Stall(why);
246
+ };
178
247
 
179
248
  try {
180
249
  await p.reset?.();
181
250
  await p.arm?.(arm, arm === "break" ? { ...s.break.env } : {});
251
+ if (s.steps.some((x) => x.do === "await-pull")) before = new Set(await p.forge.openPulls());
182
252
  for (let i = 0; i < s.steps.length; i++) {
183
253
  const step = s.steps[i]!;
184
254
  let result: StepResult;
@@ -204,6 +274,11 @@ export async function runArm(s: Scenario, arm: Arm, p: DriverPorts, opts: Driver
204
274
  }
205
275
  continue;
206
276
  }
277
+ case "await-pull": {
278
+ result = await awaitPull(step);
279
+ ctx.pull = result.pull;
280
+ break;
281
+ }
207
282
  case "plan": {
208
283
  const o = pullOf(step.pull);
209
284
  const r = await report("plan", o.pull, o.head, "plan");
@@ -230,6 +305,16 @@ export async function runArm(s: Scenario, arm: Arm, p: DriverPorts, opts: Driver
230
305
  result = { id: step.id, do: step.do, pull: o.pull, commit };
231
306
  break;
232
307
  }
308
+ case "comment": {
309
+ const o = pullOf(step.pull);
310
+ const post = p.forge.postComment;
311
+ if (!post) throw new Stall("a comment step needs the forge's postComment");
312
+ await within("comment", post.call(p.forge, o.pull, step.body, step.as ?? "author"));
313
+ log(`${s.id} ${arm}: ${step.id} commented on pull request ${o.pull} as ${step.as ?? "author"}`);
314
+ ctx.pull = o.pull;
315
+ result = { id: step.id, do: step.do, pull: o.pull };
316
+ break;
317
+ }
233
318
  case "apply": {
234
319
  const m = merged.get(step.merge);
235
320
  if (!m) throw new Stall(`no merge from ${step.merge}`);
@@ -11,7 +11,7 @@
11
11
  import { mkdirSync, rmSync, writeFileSync } from "node:fs";
12
12
  import { dirname, join } from "node:path";
13
13
  import { guardedGit, remoteWith, type GuardedGit } from "./git";
14
- import type { Clock, ForgeIssue, ForgeRun, HarnessForge } from "./ports";
14
+ import type { Clock, ForgeIssue, ForgePerson, ForgePull, ForgeRun, HarnessForge } from "./ports";
15
15
  import { forgejoRunnerConfig, type RunnerConfigOptions } from "./stack";
16
16
 
17
17
  export interface Person {
@@ -73,6 +73,16 @@ interface ActionRun {
73
73
  workflow_id?: string;
74
74
  }
75
75
 
76
+ /** A pull request as Forgejo's API answers, the fields read here. */
77
+ interface ForgejoPull {
78
+ number: number;
79
+ title: string;
80
+ head?: { ref?: string; sha?: string; repo?: { full_name?: string } | null };
81
+ }
82
+
83
+ const pullOf = (p: ForgejoPull): ForgePull => ({ number: p.number, title: p.title, branch: p.head?.ref ?? "", head: p.head?.sha ?? "" });
84
+ const sameRepo = (a: string | undefined, b: string) => a !== undefined && a.toLowerCase() === b.toLowerCase();
85
+
76
86
  const DONE = new Set(["success", "failure", "cancelled", "skipped"]);
77
87
 
78
88
  export class ForgejoForge implements HarnessForge {
@@ -201,6 +211,37 @@ export class ForgejoForge implements HarnessForge {
201
211
  return out;
202
212
  }
203
213
 
214
+ async findPull(branch: string): Promise<ForgePull | undefined> {
215
+ const found: ForgePull[] = [];
216
+ for (let page = 1; page < 50; page++) {
217
+ const list = await this.api<ForgejoPull[]>(this.o.admin, "GET", `${this.r}/pulls?state=open&sort=oldest&page=${page}&limit=50`);
218
+ if (!list || list.length === 0) break;
219
+ for (const p of list) if (p.head?.ref === branch && sameRepo(p.head.repo?.full_name, this.o.repo)) found.push(pullOf(p));
220
+ if (list.length < 50) break;
221
+ }
222
+ return found.sort((a, b) => a.number - b.number)[0];
223
+ }
224
+
225
+ async pullInfo(pull: number): Promise<ForgePull | undefined> {
226
+ const p = await this.api<ForgejoPull>(this.o.admin, "GET", `${this.r}/pulls/${pull}`, undefined, true);
227
+ return p ? pullOf(p) : undefined;
228
+ }
229
+
230
+ async changedFiles(pull: number): Promise<string[]> {
231
+ const out: string[] = [];
232
+ for (let page = 1; page < 50; page++) {
233
+ const list = await this.api<Array<{ filename: string }>>(this.o.admin, "GET", `${this.r}/pulls/${pull}/files?page=${page}&limit=50`);
234
+ if (!list || list.length === 0) break;
235
+ out.push(...list.map((f) => f.filename));
236
+ if (list.length < 50) break;
237
+ }
238
+ return out;
239
+ }
240
+
241
+ async postComment(pull: number, body: string, as: ForgePerson): Promise<void> {
242
+ await this.api(this.o[as], "POST", `${this.r}/issues/${pull}/comments`, { body });
243
+ }
244
+
204
245
  applyAgain(sha: string, workflow: string): Promise<ForgeRun> {
205
246
  return this.dispatch(sha, workflow);
206
247
  }
@@ -13,14 +13,25 @@
13
13
  * - the no-real-cloud wrapper: ./safe-run.ts
14
14
  *
15
15
  * A product on a published chant without this subpath feature-detects:
16
- * import it lazily, and use it when `E2E_HARNESS_FLOOR` is there.
16
+ * import it lazily, and use it when `E2E_HARNESS_FLOOR` is there. A scenario
17
+ * with await-pull or comment steps, or a pull or gated outcome, needs
18
+ * `E2E_HARNESS_PULL_STEPS_FLOOR` as well.
17
19
  */
18
20
  import { existsSync } from "node:fs";
19
21
  import { join } from "node:path";
22
+ import { NEXT_RELEASE } from "../release-floors";
20
23
 
21
24
  /** The first chant with the e2e harness. */
22
25
  export const E2E_HARNESS_FLOOR = "0.124.56";
23
26
 
27
+ /**
28
+ * The first chant whose harness follows a pull request a product opened
29
+ * (chant#4650): the await-pull and comment steps, the pull and gated
30
+ * outcomes, and the forge reads under them. A scenario that uses one needs
31
+ * this chant or newer.
32
+ */
33
+ export const E2E_HARNESS_PULL_STEPS_FLOOR = NEXT_RELEASE;
34
+
24
35
  /**
25
36
  * The harness's chant docker-lexicon project, to `chant build <dir>/src
26
37
  * --lexicon docker`. It ships as source in the package's src/.
@@ -4,6 +4,7 @@
4
4
  * chant's reports land, chant run outside the pipeline, the ledger, and time.
5
5
  * The real ones are ./forgejo.ts and ./bucket.ts; tests pass fakes.
6
6
  */
7
+ import type { GatedRequestRead } from "../lifecycle/gated-request";
7
8
  import type { OpRunRecord } from "../op/runtime";
8
9
 
9
10
  /** A forge repository as the author, the reviewer and the admin: the pull request loop. */
@@ -48,6 +49,19 @@ export interface ForgeIssue {
48
49
  open: boolean;
49
50
  }
50
51
 
52
+ /** An open pull request as the forge reads it. */
53
+ export interface ForgePull {
54
+ number: number;
55
+ title: string;
56
+ /** Its head branch. */
57
+ branch: string;
58
+ /** Its head commit's sha. */
59
+ head: string;
60
+ }
61
+
62
+ /** Who on the forge a comment comes from. */
63
+ export type ForgePerson = "author" | "reviewer" | "admin";
64
+
51
65
  /**
52
66
  * sql-yodeler's Forge verbs (scenarios/forges/forge.ts:26-61) that the pull
53
67
  * request loop lacks. `openPr` and `merge` there are `openPull` and
@@ -59,6 +73,18 @@ export interface ForgeReads {
59
73
  comments(pull: number): Promise<string[]>;
60
74
  /** The repository's issues, open and closed, without pull requests. */
61
75
  issues(): Promise<ForgeIssue[]>;
76
+ /**
77
+ * The OPEN pull request from `branch` in this repository (a fork's branch
78
+ * of the same name is not it), or undefined. The oldest when there are
79
+ * several. A product opens it, and the await-pull step finds it.
80
+ */
81
+ findPull(branch: string): Promise<ForgePull | undefined>;
82
+ /** Pull request `pull`, open or not, or undefined when the forge does not know it. */
83
+ pullInfo(pull: number): Promise<ForgePull | undefined>;
84
+ /** The repo-relative paths pull request `pull` changes, a renamed file under its new path. */
85
+ changedFiles(pull: number): Promise<string[]>;
86
+ /** Post `body` as a comment on pull request `pull`, as `as`. */
87
+ postComment(pull: number, body: string, as: ForgePerson): Promise<void>;
62
88
  }
63
89
 
64
90
  export interface ForgeRuns {
@@ -107,6 +133,13 @@ export interface Chant {
107
133
  /** The run ledger of the scenario's repo (`chant/lifecycle`), read. */
108
134
  export interface Ledger {
109
135
  runs(env: string, op: string): Promise<OpRunRecord[]>;
136
+ /**
137
+ * The gated requests of `op`, oldest first, for the gated outcome. A gated
138
+ * request writes no op-run record, so `runs` never sees it. The real one
139
+ * is `readGatedRequests(op, location)` from the lifecycle module, on the
140
+ * scenario repo's ledger.
141
+ */
142
+ gatedRequests?(op: string): Promise<GatedRequestRead[]>;
110
143
  }
111
144
 
112
145
  /** Work outside the forge and chant: a change made out of band. */
@@ -3,7 +3,8 @@
3
3
  * a repo tree, an ordered list of pull request steps, and the outcomes each
4
4
  * step must show. The lint refuses one that cannot record a row: no claim
5
5
  * id, no BREAK arm, nothing to check, or a step that names a pull request or
6
- * a merge no earlier step made.
6
+ * a merge no earlier step made. An await-pull step makes a pull request as
7
+ * an open step does.
7
8
  */
8
9
  import { readFileSync } from "node:fs";
9
10
  import { validateScenario, type Scenario, type ScenarioStep } from "./schemas/index";
@@ -41,7 +42,7 @@ export function lintScenario(data: unknown): ScenarioFinding[] {
41
42
  if (seen.has(step.id)) out.push({ at: `${at}/id`, message: `step id ${step.id} is used twice` });
42
43
  const opened = (id: string) => {
43
44
  const o = seen.get(id);
44
- return o !== undefined && (o.do === "open" || o.do === "open-concurrent");
45
+ return o !== undefined && (o.do === "open" || o.do === "open-concurrent" || o.do === "await-pull");
45
46
  };
46
47
  switch (step.do) {
47
48
  case "open-concurrent": {
@@ -54,7 +55,8 @@ export function lintScenario(data: unknown): ScenarioFinding[] {
54
55
  case "plan":
55
56
  case "approve":
56
57
  case "merge":
57
- if (!opened(step.pull)) out.push({ at: `${at}/pull`, message: `${step.do} names ${step.pull}, which is not an earlier open step` });
58
+ case "comment":
59
+ if (!opened(step.pull)) out.push({ at: `${at}/pull`, message: `${step.do} names ${step.pull}, which is not an earlier open or await-pull step` });
58
60
  break;
59
61
  case "apply": {
60
62
  const m = seen.get(step.merge);
@@ -69,9 +71,9 @@ export function lintScenario(data: unknown): ScenarioFinding[] {
69
71
  if ("report" in e && step.do !== "plan" && step.do !== "apply") {
70
72
  out.push({ at: `${at}/expect/${j}`, message: `a report outcome belongs on a plan or apply step, not ${step.do}` });
71
73
  }
72
- if ("comment" in e && !("pull" in step) && step.do !== "open" && step.do !== "open-concurrent") {
73
- out.push({ at: `${at}/expect/${j}`, message: "a comment outcome belongs on a step with a pull request" });
74
- }
74
+ const hasPull = "pull" in step || step.do === "open" || step.do === "open-concurrent" || step.do === "await-pull";
75
+ if ("comment" in e && !hasPull) out.push({ at: `${at}/expect/${j}`, message: "a comment outcome belongs on a step with a pull request" });
76
+ if ("pull" in e && !hasPull) out.push({ at: `${at}/expect/${j}`, message: "a pull outcome belongs on a step with a pull request" });
75
77
  if ("exit" in e && step.do !== "out-of-band") out.push({ at: `${at}/expect/${j}`, message: "an exit outcome belongs on an out-of-band step" });
76
78
  }
77
79
  seen.set(step.id, step);
@@ -48,10 +48,19 @@ JSON Schemas (draft 2020-12) of the e2e harness (chant#4587). `index.ts` exports
48
48
  | `reportUrl` | yes | The pipeline's `--report-url`, `s3://<bucket>/<prefix>`. |
49
49
  | `env` | no | The chant environment the ledger records runs under. Default `local`. |
50
50
  | `limits` | no | Seconds per kind of step, over the defaults in `steps.ts`. |
51
- | `steps` | yes | In order. `do` is open, open-concurrent, plan, approve, merge, apply, out-of-band or kill-job; each may carry `expect`. |
51
+ | `steps` | yes | In order. `do` is open, open-concurrent, await-pull, plan, approve, merge, comment, apply, out-of-band or kill-job; each may carry `expect`. |
52
52
  | `break` | yes | The BREAK arm: `env` with `BREAK: "1"`, and an optional `overlay` copied over every pull request of the break run. |
53
53
 
54
- An outcome in `expect` has one key: `report` (`status`, `components`, `only`) on a plan or apply step, `ledger` (`op`, `status`, `count`), `comment`, `issue` (`title`, `open`), or `exit` on an out-of-band step.
54
+ An outcome in `expect` has one key: `report` (`status`, `components`, `only`) on a plan or apply step, `ledger` (`op`, `status`, `count`), `gated` (`op`, `status`, `count`), `comment`, `pull` (`title`, `files`, `only`) on a step with a pull request, `issue` (`title`, `open`), or `exit` on an out-of-band step.
55
+
56
+ The steps a product's pull request needs:
57
+
58
+ | Step | Fields | Does |
59
+ |---|---|---|
60
+ | `await-pull` | `branch`, `title`? | Waits, within its limit (300 s by default), for an open pull request from exactly `branch` whose title holds `title`, and binds it to the step's id. A product's command in an earlier `out-of-band` step opens it. Both runs wait for the same branch, and a pull request already open when the run started is never bound. |
61
+ | `comment` | `pull`, `body`, `as`? | Posts `body` on the pull request of the open or await-pull step `pull`, as `author` (the default), `reviewer` or `admin`. Limit 60 s. |
62
+
63
+ `plan`, `approve` and `merge` name an await-pull step in `pull` as they name an open step. The `pull` outcome reads the step's pull request: its title holds `title`, it changes every path in `files`, and with `only: true` it changes no other path. The `gated` outcome counts the gated requests of `op` asked since the run started, which write no op-run record and so never reach `ledger`: `gated` until a finished line names one, then `ok` when it applied or `failed`. These steps and outcomes were added within contract 1 by chant 0.124.58.
55
64
 
56
65
  ## e2e-claim-row/v1 and e2e-claims/v1
57
66
 
@@ -55,7 +55,7 @@
55
55
  },
56
56
  "$defs": {
57
57
  "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
58
- "do": { "enum": ["open", "open-concurrent", "plan", "approve", "merge", "apply", "out-of-band", "kill-job"] },
58
+ "do": { "enum": ["open", "open-concurrent", "await-pull", "plan", "approve", "merge", "comment", "apply", "out-of-band", "kill-job"] },
59
59
  "step": {
60
60
  "type": "object",
61
61
  "required": ["id", "do"],
@@ -81,10 +81,29 @@
81
81
  "type": "object",
82
82
  "properties": {
83
83
  "do": { "enum": ["plan", "approve", "merge"] },
84
- "pull": { "$ref": "#/$defs/name", "description": "The id of the open step whose pull request this is." }
84
+ "pull": { "$ref": "#/$defs/name", "description": "The id of the open or await-pull step whose pull request this is." }
85
85
  },
86
86
  "required": ["pull"]
87
87
  },
88
+ {
89
+ "type": "object",
90
+ "properties": {
91
+ "do": { "const": "await-pull" },
92
+ "branch": { "type": "string", "minLength": 1, "description": "The exact head branch of the pull request a product opens. Both runs wait for this same branch: the BREAK run does not add -break to it." },
93
+ "title": { "type": "string", "minLength": 1, "description": "Text the pull request's title must hold, when given." }
94
+ },
95
+ "required": ["branch"]
96
+ },
97
+ {
98
+ "type": "object",
99
+ "properties": {
100
+ "do": { "const": "comment" },
101
+ "pull": { "$ref": "#/$defs/name", "description": "The id of the open or await-pull step whose pull request the comment goes on." },
102
+ "body": { "type": "string", "minLength": 1 },
103
+ "as": { "enum": ["author", "reviewer", "admin"], "description": "Who posts it. Default author." }
104
+ },
105
+ "required": ["pull", "body"]
106
+ },
88
107
  {
89
108
  "type": "object",
90
109
  "properties": {
@@ -112,7 +131,7 @@
112
131
  },
113
132
  "outcome": {
114
133
  "type": "object",
115
- "description": "One thing a step must show. report reads the step's pr-plan.json or pr-apply.json; ledger reads the run records the scenario added; comment and issue read the forge; exit is an out-of-band command's exit code.",
134
+ "description": "One thing a step must show. report reads the step's pr-plan.json or pr-apply.json; ledger reads the run records the scenario added; gated reads the gated requests the scenario added; comment, issue and pull read the forge; exit is an out-of-band command's exit code.",
116
135
  "minProperties": 1,
117
136
  "maxProperties": 1,
118
137
  "additionalProperties": false,
@@ -136,7 +155,28 @@
136
155
  "count": { "type": "integer", "minimum": 0 }
137
156
  }
138
157
  },
158
+ "gated": {
159
+ "type": "object",
160
+ "required": ["op"],
161
+ "additionalProperties": false,
162
+ "description": "Gated requests of op on the ledger, asked since the run started. A request is gated until a finished line names it, then ok when it applied and failed when it did not.",
163
+ "properties": {
164
+ "op": { "type": "string" },
165
+ "status": { "enum": ["gated", "ok", "failed"] },
166
+ "count": { "type": "integer", "minimum": 0 }
167
+ }
168
+ },
139
169
  "comment": { "type": "string", "minLength": 1, "description": "Text one of the step's pull request comments holds." },
170
+ "pull": {
171
+ "type": "object",
172
+ "additionalProperties": false,
173
+ "description": "The step's pull request: its title holds title, it changes every path in files, and with only it changes no other path.",
174
+ "properties": {
175
+ "title": { "type": "string", "minLength": 1 },
176
+ "files": { "type": "array", "items": { "type": "string", "minLength": 1 } },
177
+ "only": { "type": "boolean", "description": "files names every path the pull request changes." }
178
+ }
179
+ },
140
180
  "issue": {
141
181
  "type": "object",
142
182
  "required": ["title"],
@@ -111,14 +111,16 @@ export interface DemoCycle {
111
111
 
112
112
  // ── e2e-scenario/v1 ───────────────────────────────────────────────────
113
113
 
114
- export const SCENARIO_STEP_KINDS = ["open", "open-concurrent", "plan", "approve", "merge", "apply", "out-of-band", "kill-job"] as const;
114
+ export const SCENARIO_STEP_KINDS = ["open", "open-concurrent", "await-pull", "plan", "approve", "merge", "comment", "apply", "out-of-band", "kill-job"] as const;
115
115
  export type ScenarioStepKind = (typeof SCENARIO_STEP_KINDS)[number];
116
116
 
117
117
  /** One thing a step must show. Exactly one key is set. */
118
118
  export type ScenarioOutcome =
119
119
  | { report: { status?: string; components?: Record<string, string>; only?: boolean } }
120
120
  | { ledger: { op: string; status?: "ok" | "fail" | "gated" | "waiting"; count?: number } }
121
+ | { gated: { op: string; status?: "gated" | "ok" | "failed"; count?: number } }
121
122
  | { comment: string }
123
+ | { pull: { title?: string; files?: string[]; only?: boolean } }
122
124
  | { issue: { title: string; open?: boolean } }
123
125
  | { exit: number };
124
126
 
@@ -130,7 +132,9 @@ interface StepBase {
130
132
 
131
133
  export type ScenarioStep =
132
134
  | (StepBase & { do: "open" | "open-concurrent"; branch: string; overlay: string; title: string; body?: string })
135
+ | (StepBase & { do: "await-pull"; branch: string; title?: string })
133
136
  | (StepBase & { do: "plan" | "approve" | "merge"; pull: string })
137
+ | (StepBase & { do: "comment"; pull: string; body: string; as?: "author" | "reviewer" | "admin" })
134
138
  | (StepBase & { do: "apply"; merge: string })
135
139
  | (StepBase & { do: "out-of-band"; command: string[] })
136
140
  | (StepBase & { do: "kill-job"; match?: string });
@@ -65,7 +65,7 @@ describe("e2e-scenario/v1 and its lint", () => {
65
65
  steps[2] = { id: "one-plan", do: "plan", pull: "nobody", expect: [{ report: { status: "planned" } }] };
66
66
  steps[4] = { id: "one-apply", do: "apply", merge: "one", expect: [{ exit: 0 }] };
67
67
  const findings = lintScenario(s);
68
- expect(findings).toContainEqual({ at: "/steps/2/pull", message: "plan names nobody, which is not an earlier open step" });
68
+ expect(findings).toContainEqual({ at: "/steps/2/pull", message: "plan names nobody, which is not an earlier open or await-pull step" });
69
69
  expect(findings).toContainEqual({ at: "/steps/4/merge", message: "apply names one, which is not an earlier merge step" });
70
70
  expect(findings).toContainEqual({ at: "/steps/4/expect/0", message: "an exit outcome belongs on an out-of-band step" });
71
71
  });
@@ -97,6 +97,49 @@ describe("e2e-scenario/v1 and its lint", () => {
97
97
  });
98
98
  });
99
99
 
100
+ describe("e2e-scenario/v1 steps for a pull request a product opens (chant#4650)", () => {
101
+ const product = (steps: unknown[]): Record<string, unknown> => ({ ...scenario(), steps });
102
+ const request = { id: "request", do: "out-of-band", command: ["terragucci", "request"], expect: [{ exit: 0 }] };
103
+
104
+ test("await-pull, comment and the pull and gated outcomes are in the schema", () => {
105
+ const s = product([
106
+ request,
107
+ { id: "pr", do: "await-pull", branch: "request/bucket/orders", title: "orders", expect: [{ pull: { title: "orders", files: ["apps/orders/main.tf"], only: true } }] },
108
+ { id: "pr-plan", do: "plan", pull: "pr", expect: [{ report: { status: "planned" } }] },
109
+ { id: "invoke", do: "comment", pull: "pr", body: "/terragucci action orders rotate", as: "reviewer", expect: [{ gated: { op: "tf-action", status: "gated", count: 1 } }] },
110
+ ]);
111
+ expect(validateScenario(s)).toMatchObject({ ok: true });
112
+ expect(lintScenario({ ...s, limits: { "await-pull": 600, comment: 30 } })).toEqual([]);
113
+ });
114
+
115
+ test("a plan naming an await-pull step lints clean, and one naming an unknown id has one finding naming it", () => {
116
+ const steps = (pull: string) => [request, { id: "pr", do: "await-pull", branch: "request/bucket/orders" }, { id: "pr-plan", do: "plan", pull, expect: [{ report: { status: "planned" } }] }];
117
+ expect(lintScenario(product(steps("pr")))).toEqual([]);
118
+ expect(lintScenario(product(steps("nobody")))).toEqual([{ at: "/steps/2/pull", message: "plan names nobody, which is not an earlier open or await-pull step" }]);
119
+ });
120
+
121
+ test("a comment step names an earlier pull request, and a pull outcome belongs on a step with one", () => {
122
+ expect(lintScenario(product([request, { id: "c", do: "comment", pull: "later", body: "hi" }]))).toEqual([{ at: "/steps/1/pull", message: "comment names later, which is not an earlier open or await-pull step" }]);
123
+ expect(lintScenario(product([{ ...request, expect: [{ pull: { only: true } }] }]))).toEqual([{ at: "/steps/0/expect/0", message: "a pull outcome belongs on a step with a pull request" }]);
124
+ });
125
+
126
+ test("the schema refuses an await-pull with no branch, a comment with no pull or body, and unknown fields in the outcomes", () => {
127
+ for (const bad of [
128
+ { id: "s", do: "await-pull", title: "T" },
129
+ { id: "s", do: "comment", pull: "one" },
130
+ { id: "s", do: "comment", body: "hi" },
131
+ { id: "s", do: "comment", pull: "one", body: "hi", as: "stranger" },
132
+ { id: "s", do: "plan", pull: "one", expect: [{ pull: { branch: "x" } }] },
133
+ { id: "s", do: "plan", pull: "one", expect: [{ gated: { status: "ok" } }] },
134
+ { id: "s", do: "plan", pull: "one", expect: [{ gated: { op: "tf-action", status: "applied" } }] },
135
+ ]) {
136
+ const s = scenario();
137
+ (s.steps as unknown[]).push(bad);
138
+ expect(validateScenario(s).ok, JSON.stringify(bad)).toBe(false);
139
+ }
140
+ });
141
+ });
142
+
100
143
  const row = (over: Partial<ClaimRow> = {}): ClaimRow => ({
101
144
  $schema: E2E_CLAIM_ROW_SCHEMA,
102
145
  contract: 1,
@@ -10,12 +10,16 @@ export const HARNESS_LIMITS: Record<ScenarioStepKind, number> = {
10
10
  /** The branch push and the pull request open. */
11
11
  open: 60,
12
12
  "open-concurrent": 60,
13
+ /** An open pull request from the branch, which a product opens. */
14
+ "await-pull": 300,
13
15
  /** pr-plan.json at the head, from the push. */
14
16
  plan: 600,
15
17
  /** The forge review and chant approve. */
16
18
  approve: 120,
17
19
  /** The merge and its merge commit. */
18
20
  merge: 60,
21
+ /** Posting a comment on the pull request. */
22
+ comment: 60,
19
23
  /** pr-apply.json at the merge commit, from the merge. */
20
24
  apply: 900,
21
25
  /** A command run out of band. */
package/src/mcp/types.ts CHANGED
@@ -18,6 +18,15 @@ export interface McpToolContribution {
18
18
  * that leaves it out is served only by the ordinary server.
19
19
  */
20
20
  readOnly?: boolean;
21
+ /**
22
+ * A CI product's tool that writes to the forge and nowhere else (chant#4655):
23
+ * it opens a pull request or posts a comment, and runs no Op, resolves no
24
+ * gate, approves, merges and applies nothing. `chant serve mcp --read-only
25
+ * --propose` serves a product tool that declares this; the read-only server
26
+ * without `--propose` refuses to start with one, and the ordinary server
27
+ * serves it as any other tool. Lexicon tools do not use it.
28
+ */
29
+ forgeWrite?: true;
21
30
  }
22
31
 
23
32
  export interface McpResourceContribution {
@@ -19,4 +19,4 @@
19
19
  * this constant to the next patch (#4501). The check fails while a floor
20
20
  * still names this constant after its version shipped.
21
21
  */
22
- export const NEXT_RELEASE = "0.124.57";
22
+ export const NEXT_RELEASE = "0.124.58";
@@ -0,0 +1,41 @@
1
+ ### terragucci request: app `orders` from bucket
2
+
3
+ | | |
4
+ | --- | --- |
5
+ | Template | `acme/bucket/aws` |
6
+ | Version | `1.0.0` |
7
+ | Requested by | `alice` |
8
+ | Claimed by (as given by the client; the forge does not vouch for it) | `bob` |
9
+ | Through | an agent over MCP |
10
+
11
+ | Input | Value |
12
+ | --- | --- |
13
+ | `bucket_name` | `"orders-data"` |
14
+ | `readers` | `["svc-a","svc-b"]` |
15
+ | `tags` | `{"team":"pay\|ments"}` |
16
+
17
+ Nothing was applied or approved. This pull request only adds files; it is planned like any other, and a person reviews and merges it.
18
+
19
+ ```json https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json
20
+ {
21
+ "$schema": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json",
22
+ "contract": 1,
23
+ "kind": "app",
24
+ "template": "acme/bucket/aws",
25
+ "version": "1.0.0",
26
+ "app": "orders",
27
+ "inputs": {
28
+ "bucket_name": "orders-data",
29
+ "tags": {
30
+ "team": "pay|ments"
31
+ },
32
+ "readers": [
33
+ "svc-a",
34
+ "svc-b"
35
+ ]
36
+ },
37
+ "requestedBy": "alice",
38
+ "claimedBy": "bob",
39
+ "via": "mcp"
40
+ }
41
+ ```
@@ -0,0 +1,8 @@
1
+ /**
2
+ * `@intentius/chant/template-request` (#4651): the template request
3
+ * document (template-request/v1), template.yml/v1 with its engine-neutral
4
+ * input kinds, the refusals, the branch and the pull request body.
5
+ */
6
+ export * from "./template-spec";
7
+ export * from "./template-request";
8
+ export * from "./request-body";