@intentius/chant 0.124.56 → 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 (199) hide show
  1. package/dist/ci-audit/index.d.ts.map +1 -1
  2. package/dist/ci-audit/index.js +1 -2
  3. package/dist/ci-product-words.d.ts +47 -2
  4. package/dist/ci-product-words.d.ts.map +1 -1
  5. package/dist/ci-product-words.js +59 -1
  6. package/dist/ci-product.d.ts +26 -2
  7. package/dist/ci-product.d.ts.map +1 -1
  8. package/dist/ci-product.js +30 -7
  9. package/dist/cli/commands/init.d.ts +2 -0
  10. package/dist/cli/commands/init.d.ts.map +1 -1
  11. package/dist/cli/commands/init.js +1 -1
  12. package/dist/cli/handlers/build.d.ts.map +1 -1
  13. package/dist/cli/handlers/build.js +5 -1
  14. package/dist/cli/handlers/init.d.ts.map +1 -1
  15. package/dist/cli/handlers/init.js +16 -0
  16. package/dist/cli/handlers/lifecycle.d.ts.map +1 -1
  17. package/dist/cli/handlers/lifecycle.js +14 -0
  18. package/dist/cli/handlers/pr.d.ts.map +1 -1
  19. package/dist/cli/handlers/pr.js +90 -35
  20. package/dist/cli/handlers/serve.d.ts.map +1 -1
  21. package/dist/cli/handlers/serve.js +9 -0
  22. package/dist/cli/main.d.ts.map +1 -1
  23. package/dist/cli/main.js +6 -2
  24. package/dist/cli/mcp/product-tools.d.ts +40 -7
  25. package/dist/cli/mcp/product-tools.d.ts.map +1 -1
  26. package/dist/cli/mcp/product-tools.js +59 -15
  27. package/dist/cli/mcp/read-only.d.ts +2 -1
  28. package/dist/cli/mcp/read-only.d.ts.map +1 -1
  29. package/dist/cli/mcp/read-only.js +2 -1
  30. package/dist/cli/mcp/server.d.ts +11 -0
  31. package/dist/cli/mcp/server.d.ts.map +1 -1
  32. package/dist/cli/mcp/server.js +15 -3
  33. package/dist/cli/mcp-config.d.ts +4 -1
  34. package/dist/cli/mcp-config.d.ts.map +1 -1
  35. package/dist/cli/mcp-config.js +6 -2
  36. package/dist/cli/parse-args.d.ts.map +1 -1
  37. package/dist/cli/parse-args.js +9 -0
  38. package/dist/cli/registry.d.ts +8 -0
  39. package/dist/cli/registry.d.ts.map +1 -1
  40. package/dist/components/auto-release.d.ts +5 -2
  41. package/dist/components/auto-release.d.ts.map +1 -1
  42. package/dist/components/auto-release.js +9 -4
  43. package/dist/components/capability.d.ts +10 -0
  44. package/dist/components/capability.d.ts.map +1 -1
  45. package/dist/components/deploy-units.d.ts +12 -0
  46. package/dist/components/deploy-units.d.ts.map +1 -1
  47. package/dist/components/deploy-units.js +20 -1
  48. package/dist/components/pr-pipeline.d.ts +64 -2
  49. package/dist/components/pr-pipeline.d.ts.map +1 -1
  50. package/dist/components/pr-pipeline.js +66 -5
  51. package/dist/components/product-pipeline.d.ts +18 -1
  52. package/dist/components/product-pipeline.d.ts.map +1 -1
  53. package/dist/components/product-pipeline.js +8 -2
  54. package/dist/components/row-lease.d.ts +22 -1
  55. package/dist/components/row-lease.d.ts.map +1 -1
  56. package/dist/components/row-lease.js +32 -6
  57. package/dist/e2e-harness/driver.d.ts.map +1 -1
  58. package/dist/e2e-harness/driver.js +97 -0
  59. package/dist/e2e-harness/forgejo.d.ts +5 -1
  60. package/dist/e2e-harness/forgejo.d.ts.map +1 -1
  61. package/dist/e2e-harness/forgejo.js +35 -0
  62. package/dist/e2e-harness/index.d.ts +7 -0
  63. package/dist/e2e-harness/index.d.ts.map +1 -1
  64. package/dist/e2e-harness/index.js +11 -2
  65. package/dist/e2e-harness/ports.d.ts +31 -0
  66. package/dist/e2e-harness/ports.d.ts.map +1 -1
  67. package/dist/e2e-harness/scenario.d.ts.map +1 -1
  68. package/dist/e2e-harness/scenario.js +9 -5
  69. package/dist/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  70. package/dist/e2e-harness/schemas/index.d.ts +22 -1
  71. package/dist/e2e-harness/schemas/index.d.ts.map +1 -1
  72. package/dist/e2e-harness/schemas/index.js +1 -1
  73. package/dist/e2e-harness/steps.d.ts.map +1 -1
  74. package/dist/e2e-harness/steps.js +4 -0
  75. package/dist/lexicon.d.ts +9 -0
  76. package/dist/lexicon.d.ts.map +1 -1
  77. package/dist/lifecycle/git.d.ts +39 -3
  78. package/dist/lifecycle/git.d.ts.map +1 -1
  79. package/dist/lifecycle/git.js +223 -15
  80. package/dist/lifecycle/lock-rows.d.ts +23 -0
  81. package/dist/lifecycle/lock-rows.d.ts.map +1 -1
  82. package/dist/lifecycle/lock-rows.js +47 -8
  83. package/dist/lifecycle/resource-lock.d.ts +70 -0
  84. package/dist/lifecycle/resource-lock.d.ts.map +1 -1
  85. package/dist/lifecycle/resource-lock.js +241 -5
  86. package/dist/mcp/types.d.ts +9 -0
  87. package/dist/mcp/types.d.ts.map +1 -1
  88. package/dist/op/gate.js +21 -4
  89. package/dist/op/op-waves-release-port.js +1 -1
  90. package/dist/op/op-waves-release.d.ts +2 -1
  91. package/dist/op/op-waves-release.d.ts.map +1 -1
  92. package/dist/op/op-waves-run.d.ts +8 -0
  93. package/dist/op/op-waves-run.d.ts.map +1 -1
  94. package/dist/op/op-waves-run.js +101 -29
  95. package/dist/op/op-waves.d.ts +18 -0
  96. package/dist/op/op-waves.d.ts.map +1 -1
  97. package/dist/op/op-waves.js +16 -0
  98. package/dist/pr-loop.d.ts.map +1 -1
  99. package/dist/pr-loop.js +1 -2
  100. package/dist/release-floors.d.ts +1 -1
  101. package/dist/release-floors.js +1 -1
  102. package/dist/template-request/index.d.ts +9 -0
  103. package/dist/template-request/index.d.ts.map +1 -0
  104. package/dist/template-request/index.js +8 -0
  105. package/dist/template-request/request-body.d.ts +21 -0
  106. package/dist/template-request/request-body.d.ts.map +1 -0
  107. package/dist/template-request/request-body.js +86 -0
  108. package/dist/template-request/template-request.d.ts +100 -0
  109. package/dist/template-request/template-request.d.ts.map +1 -0
  110. package/dist/template-request/template-request.js +150 -0
  111. package/dist/template-request/template-request.schema.json +100 -0
  112. package/dist/template-request/template-spec.d.ts +83 -0
  113. package/dist/template-request/template-spec.d.ts.map +1 -0
  114. package/dist/template-request/template-spec.js +146 -0
  115. package/dist/template-request/template.schema.json +114 -0
  116. package/dist/template-request/validate.d.ts +4 -0
  117. package/dist/template-request/validate.d.ts.map +1 -0
  118. package/dist/template-request/validate.js +21 -0
  119. package/dist/wave-runtime.mjs +310 -300
  120. package/package.json +8 -1
  121. package/src/ci-audit/index.ts +1 -2
  122. package/src/ci-product-words.test.ts +23 -0
  123. package/src/ci-product-words.ts +68 -3
  124. package/src/ci-product.ts +36 -6
  125. package/src/cli/commands/init.ts +3 -1
  126. package/src/cli/handlers/build.ts +5 -1
  127. package/src/cli/handlers/init.ts +18 -0
  128. package/src/cli/handlers/lifecycle.ts +13 -0
  129. package/src/cli/handlers/pr-before-merge.test.ts +1 -1
  130. package/src/cli/handlers/pr-deploy-inputs.test.ts +1 -1
  131. package/src/cli/handlers/pr-endpoint.test.ts +1 -1
  132. package/src/cli/handlers/pr-green.test.ts +1 -1
  133. package/src/cli/handlers/pr-plan-comment-targets.test.ts +1 -1
  134. package/src/cli/handlers/pr-plan-flags.test.ts +1 -1
  135. package/src/cli/handlers/pr-plan-targets.test.ts +1 -1
  136. package/src/cli/handlers/pr-record.test.ts +34 -2
  137. package/src/cli/handlers/pr-waves-blocked.test.ts +1 -1
  138. package/src/cli/handlers/pr-waves.test.ts +1 -1
  139. package/src/cli/handlers/pr.test.ts +1 -1
  140. package/src/cli/handlers/pr.ts +86 -31
  141. package/src/cli/handlers/serve.ts +9 -0
  142. package/src/cli/main.ts +6 -2
  143. package/src/cli/mcp/product-tools.test.ts +57 -1
  144. package/src/cli/mcp/product-tools.ts +67 -15
  145. package/src/cli/mcp/read-only.ts +2 -1
  146. package/src/cli/mcp/server.ts +20 -5
  147. package/src/cli/mcp-config.test.ts +52 -2
  148. package/src/cli/mcp-config.ts +6 -3
  149. package/src/cli/parse-args.ts +7 -0
  150. package/src/cli/registry.ts +8 -0
  151. package/src/components/auto-release.test.ts +4 -2
  152. package/src/components/auto-release.ts +9 -5
  153. package/src/components/capability.ts +10 -0
  154. package/src/components/deploy-units.test.ts +18 -1
  155. package/src/components/deploy-units.ts +26 -1
  156. package/src/components/pr-pipeline.ts +99 -5
  157. package/src/components/product-actions.test.ts +76 -0
  158. package/src/components/product-pipeline.ts +21 -2
  159. package/src/components/row-lease.test.ts +61 -1
  160. package/src/components/row-lease.ts +48 -7
  161. package/src/e2e-harness/driver.test.ts +163 -0
  162. package/src/e2e-harness/driver.ts +86 -1
  163. package/src/e2e-harness/forgejo.ts +42 -1
  164. package/src/e2e-harness/index.ts +12 -2
  165. package/src/e2e-harness/ports.ts +33 -0
  166. package/src/e2e-harness/scenario.ts +8 -6
  167. package/src/e2e-harness/schemas/README.md +11 -2
  168. package/src/e2e-harness/schemas/e2e-scenario.schema.json +43 -3
  169. package/src/e2e-harness/schemas/index.ts +5 -1
  170. package/src/e2e-harness/schemas.test.ts +44 -1
  171. package/src/e2e-harness/steps.ts +4 -0
  172. package/src/lexicon.ts +9 -0
  173. package/src/lifecycle/git.test.ts +155 -0
  174. package/src/lifecycle/git.ts +213 -17
  175. package/src/lifecycle/lock-rows.test.ts +6 -1
  176. package/src/lifecycle/lock-rows.ts +58 -7
  177. package/src/lifecycle/resource-lock-wait.test.ts +292 -0
  178. package/src/lifecycle/resource-lock.ts +261 -7
  179. package/src/mcp/types.ts +9 -0
  180. package/src/op/gate.test.ts +7 -5
  181. package/src/op/gate.ts +20 -4
  182. package/src/op/op-waves-after-plan.test.ts +1 -2
  183. package/src/op/op-waves-ledger-lock.test.ts +208 -0
  184. package/src/op/op-waves-release-port.ts +1 -1
  185. package/src/op/op-waves-release.ts +1 -1
  186. package/src/op/op-waves-run.ts +104 -29
  187. package/src/op/op-waves.ts +18 -0
  188. package/src/pr-loop-bundle.test.ts +0 -2
  189. package/src/pr-loop.ts +1 -2
  190. package/src/release-floors.ts +1 -1
  191. package/src/template-request/__fixtures__/request-body.md +41 -0
  192. package/src/template-request/index.ts +8 -0
  193. package/src/template-request/request-body.ts +91 -0
  194. package/src/template-request/template-request.schema.json +100 -0
  195. package/src/template-request/template-request.test.ts +316 -0
  196. package/src/template-request/template-request.ts +235 -0
  197. package/src/template-request/template-spec.ts +176 -0
  198. package/src/template-request/template.schema.json +114 -0
  199. package/src/template-request/validate.ts +28 -0
@@ -53,14 +53,17 @@ export function detectPackageManager(dir?: string): "bun" | "npm" {
53
53
  * The MCP registration chant writes: one stdio server named `chant`. With
54
54
  * `readOnly` (`chant init --mcp-read-only`, chant#4543) it registers
55
55
  * `chant serve mcp --read-only`, which serves only the tools that change
56
- * nothing.
56
+ * nothing. With `readOnly` and `propose` (`chant init --mcp-read-only
57
+ * --propose`, chant#4655) it registers `chant serve mcp --read-only
58
+ * --propose`; `propose` without `readOnly` is refused.
57
59
  */
58
- export function generateMcpConfig(pm: "bun" | "npm", options: { readOnly?: boolean } = {}): string {
60
+ export function generateMcpConfig(pm: "bun" | "npm", options: { readOnly?: boolean; propose?: boolean } = {}): string {
61
+ if (options.propose && !options.readOnly) throw new Error("--propose is a tier of the read-only server: use --mcp-read-only --propose");
59
62
  const config = {
60
63
  mcpServers: {
61
64
  chant: {
62
65
  command: pm === "bun" ? "bunx" : "npx",
63
- args: ["chant", "serve", "mcp", ...(options.readOnly ? ["--read-only"] : [])],
66
+ args: ["chant", "serve", "mcp", ...(options.readOnly ? ["--read-only"] : []), ...(options.readOnly && options.propose ? ["--propose"] : [])],
64
67
  },
65
68
  },
66
69
  };
@@ -87,6 +87,7 @@ const BOOLEAN_FLAGS = new Set([
87
87
  "--skip-mcp",
88
88
  "--read-only",
89
89
  "--mcp-read-only",
90
+ "--propose",
90
91
  "--current",
91
92
  "--uncommitted",
92
93
  "--allow-code",
@@ -146,6 +147,7 @@ export function parseArgs(args: string[]): ParsedArgs {
146
147
  skipMcp: undefined,
147
148
  readOnly: undefined,
148
149
  mcpReadOnly: undefined,
150
+ propose: undefined,
149
151
  src: undefined,
150
152
  env: undefined,
151
153
  };
@@ -341,6 +343,8 @@ export function parseArgs(args: string[]): ParsedArgs {
341
343
  result.readOnly = true;
342
344
  } else if (arg === "--mcp-read-only") {
343
345
  result.mcpReadOnly = true;
346
+ } else if (arg === "--propose") {
347
+ result.propose = true;
344
348
  } else if (arg === "--src") {
345
349
  result.src = args[++i];
346
350
  } else if (arg === "--env") {
@@ -594,6 +598,9 @@ export function parseArgs(args: string[]): ParsedArgs {
594
598
  } else if (arg === "--apply-on-merge") {
595
599
  // `chant build --pr-loop --apply-on-merge` and `chant ci serve --apply-on-merge` (#4168): opt into applying on merge.
596
600
  result.applyOnMerge = true;
601
+ } else if (arg === "--action-job") {
602
+ // `chant build --pr-loop --action-job` (#4654): the job that answers the action comment and the action dispatch.
603
+ result.actionJob = true;
597
604
  } else if (arg === "--preview-comment") {
598
605
  // `chant build --pr-loop --preview-comment` (#4620): the job that answers `/<product> <plan word>` with a preview.
599
606
  result.previewComment = true;
@@ -137,6 +137,12 @@ export interface ParsedArgs {
137
137
  readOnly?: boolean;
138
138
  /** `chant init --mcp-read-only` (chant#4543): write `.mcp.json` registering `chant serve mcp --read-only`. */
139
139
  mcpReadOnly?: boolean;
140
+ /**
141
+ * `chant serve mcp --read-only --propose` and `chant init --mcp-read-only
142
+ * --propose` (chant#4655): the read-only server plus a product's tools that
143
+ * open pull requests (`forgeWrite`).
144
+ */
145
+ propose?: boolean;
140
146
  /** `chant import --type <ResourceType>` selector */
141
147
  selectType?: string;
142
148
  /** `chant import --name <name>` selector */
@@ -441,6 +447,8 @@ export interface ParsedArgs {
441
447
  applyBeforeMerge?: boolean;
442
448
  /** `chant build --pr-loop --preview-comment` (#4620): a job answers `/<product> <plan word>` by previewing the pull request's head again. */
443
449
  previewComment?: boolean;
450
+ /** `chant build --pr-loop --action-job` (#4654): a job answers `/<product> <action word> <member> <action>` and a dispatch with the two inputs by running the product's action verb. */
451
+ actionJob?: boolean;
444
452
  /** `chant build --pr-loop --pr-build` (#4088) — build and lint before pr-plan and pr-apply. */
445
453
  prBuild?: boolean;
446
454
  /** `chant build --pr-loop --pr-runner <stage>=<label>[,<label>...]` (#4625), repeatable: a stage's runner, plan, apply or default. */
@@ -7,8 +7,10 @@ const appendReleaseRecordMock = vi.fn();
7
7
 
8
8
  vi.mock("../lifecycle/git", () => ({
9
9
  getHeadCommit: (...args: unknown[]) => getHeadCommitMock(...args),
10
- pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
10
+ // plywood#22 finding 9: the release record pushes with fetch, replay and retry.
11
+ pushLifecycleRebasing: (...args: unknown[]) => pushLifecycleMock(...args),
11
12
  StaleLifecycleBranchError: class StaleLifecycleBranchError extends Error {},
13
+ LifecyclePushLostError: class LifecyclePushLostError extends Error {},
12
14
  }));
13
15
 
14
16
  vi.mock("../lifecycle/release-ledger", async () => {
@@ -66,7 +68,7 @@ describe("extractRunDigest", () => {
66
68
  describe("maybeRecordAutoRelease", () => {
67
69
  beforeEach(() => {
68
70
  getHeadCommitMock.mockReset().mockResolvedValue("abc123headsha");
69
- pushLifecycleMock.mockReset().mockResolvedValue(true);
71
+ pushLifecycleMock.mockReset().mockResolvedValue({ pushed: true });
70
72
  appendReleaseRecordMock.mockReset();
71
73
  delete process.env.GITHUB_ACTOR;
72
74
  delete process.env.GITLAB_USER_LOGIN;
@@ -25,7 +25,7 @@
25
25
  * (`--git-sha` defaults to HEAD, `--run-id`/`--actor` fall back to common CI
26
26
  * env vars, timestamp is a real `new Date()` taken at record time).
27
27
  */
28
- import { getHeadCommit, pushLifecycle, StaleLifecycleBranchError } from "../lifecycle/git";
28
+ import { getHeadCommit, LifecyclePushLostError, pushLifecycleRebasing, StaleLifecycleBranchError } from "../lifecycle/git";
29
29
  import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseAdmission, type ReleaseDigestKind, type ReleaseRecord, type RunOrigin } from "../lifecycle/release-ledger";
30
30
  import { changeSetDigest } from "../change-set";
31
31
  import type { DriverComponent, DriverStepRecord } from "./driver";
@@ -106,7 +106,7 @@ export type AutoReleaseSkipReason =
106
106
  export type AutoReleaseResult =
107
107
  | { recorded: true; commit: string; record: ReleaseRecord }
108
108
  | { recorded: false; reason: AutoReleaseSkipReason; detail?: string }
109
- | { recorded: false; reason: "error"; error: string };
109
+ | { recorded: false; reason: "error"; error: string; lost?: true };
110
110
 
111
111
  /** Input describing one component's completed run. */
112
112
  export interface AutoReleaseRunInfo {
@@ -189,8 +189,10 @@ function resolveActor(override?: string): string | undefined {
189
189
  * requirement; an unattributed record defeats the ledger's purpose.
190
190
  *
191
191
  * Git-sha resolution failure and ledger-write failures
192
- * (`InvalidReleaseRecordError`, `StaleLifecycleBranchError`, or any other
193
- * error `appendReleaseRecord`/`pushLifecycle` throw) are reported as `{
192
+ * (`InvalidReleaseRecordError`, `StaleLifecycleBranchError`,
193
+ * `LifecyclePushLostError` when the push never landed after its replays, or
194
+ * any other error `appendReleaseRecord`/`pushLifecycleRebasing` throw) are
195
+ * reported as `{
194
196
  * recorded: false, reason: "error", error }` rather than propagated — an
195
197
  * auto-recorded ledger write is a best-effort observability side effect of a
196
198
  * successful deploy; it must never turn a successful `chant run --components`
@@ -250,9 +252,11 @@ export async function maybeRecordAutoRelease(
250
252
  },
251
253
  { cwd: options.cwd },
252
254
  );
253
- await pushLifecycle({ cwd: options.cwd });
255
+ // plywood#22 finding 9: another writer's push replays this record on its tip and pushes again, in place of a stale refusal.
256
+ await pushLifecycleRebasing({ cwd: options.cwd });
254
257
  return { recorded: true, commit, record };
255
258
  } catch (err) {
259
+ if (err instanceof LifecyclePushLostError) return { recorded: false, reason: "error", error: err.message, lost: true };
256
260
  if (err instanceof InvalidReleaseRecordError || err instanceof StaleLifecycleBranchError) {
257
261
  return { recorded: false, reason: "error", error: err.message };
258
262
  }
@@ -268,6 +268,16 @@ export interface Capability<In = unknown, Out = unknown> {
268
268
  * ../lifecycle/lock-rows.ts). Absent: the resource grain is refused.
269
269
  */
270
270
  lockRows?(input: In, plan: CapabilityPlan): LockRow[] | Promise<LockRow[]>;
271
+ /**
272
+ * Optional (ruling for ci-products 2026-10-28, "Ledger lock"): the row of
273
+ * the whole target an apply on the `target` grain waits for on the
274
+ * ledger, oldest commit first, up to the job's timeout, in place of
275
+ * failing on the engine's own lock. The pulumi lexicon answers
276
+ * `stack <project>/<stack>` for stock Pulumi, the terraform lexicon
277
+ * `root <root>` for Terraform, tofu and Terragrunt. `plan`, when given, is
278
+ * the member's plan. Absent or undefined: the apply takes no row.
279
+ */
280
+ targetLockRow?(input: In, plan?: CapabilityPlan): LockRow | undefined | Promise<LockRow | undefined>;
271
281
  /**
272
282
  * Optional: the outputs `run` exposed when it last ran, read without
273
283
  * changing anything (#3183). A pull request's plan reads them for each
@@ -1,5 +1,5 @@
1
1
  import { describe, test, expect } from "vitest";
2
- import { deployUnits } from "./deploy-units";
2
+ import { deployUnits, pulumiStackUnit } from "./deploy-units";
3
3
  import type { Phase } from "./component";
4
4
 
5
5
  const phase = (name: string, steps: Phase["steps"]): Phase => ({ phase: name, steps });
@@ -48,6 +48,23 @@ describe("deployUnits (#1495 piece 1)", () => {
48
48
  expect(deployUnits(deploy)).toEqual([{ unit: "web", lexicon: "aws" }]);
49
49
  });
50
50
 
51
+ test("a pulumi-up step's unit is its stack qualified by the project's directory (plywood#22)", () => {
52
+ const deploy = [
53
+ phase("up", [
54
+ { kind: "pulumi-up", dir: ".", stack: "dev", member: "shop" },
55
+ { kind: "pulumi-up", dir: "./infra/", stack: "dev", member: "infra" },
56
+ { kind: "pulumi-up", dir: "infra", stack: "dev", member: "infra" },
57
+ { kind: "pulumi-up", dir: "infra" },
58
+ ]),
59
+ ];
60
+ expect(deployUnits(deploy)).toEqual([
61
+ { unit: "dev", lexicon: "pulumi" },
62
+ { unit: "infra/dev", lexicon: "pulumi" },
63
+ ]);
64
+ // The pulumi lexicon's changedUnits names stacks with the same strings.
65
+ expect([pulumiStackUnit(".", "prod-us"), pulumiStackUnit("", "prod-us"), pulumiStackUnit("apps/web", "qa")]).toEqual(["prod-us", "prod-us", "apps/web/qa"]);
66
+ });
67
+
51
68
  test("an unlisted kind contributes no unit — the registry is the rule", () => {
52
69
  const deploy = [phase("Apply", [{ kind: "gcloud-deploy", stack: "x" }])];
53
70
  expect(deployUnits(deploy)).toEqual([]);
@@ -34,6 +34,22 @@ export interface DeployUnitRule {
34
34
  field: string;
35
35
  /** The lexicon whose `describeStackStatus` reads this kind of unit. */
36
36
  lexicon: string;
37
+ /**
38
+ * The unit from the whole step, when `field` alone does not name it
39
+ * uniquely. Undefined skips the step, as a missing `field` does.
40
+ */
41
+ unitOf?: (step: Record<string, unknown>) => string | undefined;
42
+ }
43
+
44
+ /**
45
+ * A Pulumi stack's unit: `<dir>/<stack>`, or `<stack>` for a project at the
46
+ * project root. `dir` is where `Pulumi.yaml` is, relative to the project root,
47
+ * so two projects with a `dev` stack are two units. The pulumi lexicon's
48
+ * `changedUnits` answers with the same names.
49
+ */
50
+ export function pulumiStackUnit(dir: string, stack: string): string {
51
+ const d = dir.replace(/\\/g, "/").replace(/^(\.\/)+/, "").replace(/\/+$/, "");
52
+ return d === "" || d === "." ? stack : `${d}/${stack}`;
37
53
  }
38
54
 
39
55
  /**
@@ -68,6 +84,15 @@ export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
68
84
  // change signal naming the member puts the component in the change. No
69
85
  // lexicon observes it: the member's own pipeline reports its status.
70
86
  { kind: "member-outputs", field: "member", lexicon: "workspace" },
87
+ // A Pulumi stack (plywood#22). Its unit is the stack qualified by the
88
+ // project's directory (`pulumiStackUnit`), which the pulumi lexicon's
89
+ // `changedUnits` names for a changed stack config or program file.
90
+ {
91
+ kind: "pulumi-up",
92
+ field: "stack",
93
+ lexicon: "pulumi",
94
+ unitOf: (s) => (typeof s.stack === "string" && s.stack !== "" ? pulumiStackUnit(typeof s.dir === "string" ? s.dir : ".", s.stack) : undefined),
95
+ },
71
96
  ];
72
97
 
73
98
  /** One resolved unit a component's deploy composition targets. */
@@ -99,7 +124,7 @@ export function deployUnits(deploy: readonly UnitBearingPhase[]): DeployUnit[] {
99
124
  const s = step as { kind?: string } & Record<string, unknown>;
100
125
  const rule = s.kind ? byKind.get(s.kind) : undefined;
101
126
  if (!rule) continue;
102
- const unit = s[rule.field];
127
+ const unit = rule.unitOf ? rule.unitOf(s) : s[rule.field];
103
128
  if (typeof unit !== "string" || unit.length === 0) continue;
104
129
  const key = `${rule.lexicon}\0${unit}`;
105
130
  if (seen.has(key)) continue;
@@ -97,7 +97,8 @@ import { layerWaves } from "../gated-waves";
97
97
  import type { DriverComponent } from "./driver";
98
98
  import type { GatedWavePipelineOptions } from "./gated-wave-pipeline";
99
99
  import type { CloudTradeSpec, PipelineCloudIdentity } from "../ci-identity";
100
- import { commentLine, resolveProductWords, type CiProductWords, type CiProductWordsInput } from "../ci-product-words";
100
+ import { commandWord, commentLine, PRODUCT_ACTION_ENV, PRODUCT_ACTION_EVENT_FLAG, resolveProductWords, type CiProductWords, type CiProductWordsInput } from "../ci-product-words";
101
+ import { CHANT_EXIT } from "../exit-codes";
101
102
  import type { ControlTarget } from "../control/dispatch";
102
103
  import { CI_RESPOND_ENV, respondList, type CiResponses } from "../ci-respond";
103
104
 
@@ -306,6 +307,15 @@ export interface PrLoopPipelineOptions {
306
307
  * Default false.
307
308
  */
308
309
  previewComment?: boolean;
310
+ /**
311
+ * The action job (#4654): `/<product> <action word> <member> <action>` on
312
+ * an issue or pull request, or a dispatch of the workflow with the two
313
+ * inputs ({@link prActionJob}), runs the product's action verb at the
314
+ * target branch's commit under its gated request. GitHub and Forgejo only.
315
+ * The words must name an `action` command and a `bin`. Set from
316
+ * `--action-job` beside `--pr-loop`. Default off.
317
+ */
318
+ actionJob?: boolean | PrActionJobOptions;
309
319
  /**
310
320
  * Where the pull request loop's jobs run (#4625), by stage: `plan` for the
311
321
  * plan and the comment preview, `apply` for the apply jobs, the record
@@ -409,7 +419,7 @@ export function prLoopRunner(options: Pick<PrLoopPipelineOptions, "runners">, st
409
419
  export function prLoopJobStage(name: string, member?: string): PrLoopRunnerStage {
410
420
  const bare = member && name.startsWith(`${member}-`) ? name.slice(member.length + 1) : name;
411
421
  if (bare === "plan" || bare === PR_COMMENT_PREVIEW_JOB) return "plan";
412
- if (bare === "apply" || bare === "record" || /^apply-wave-\d+$/.test(bare) || bare === "env-up" || bare === "env-down" || bare === "env-sweep") return "apply";
422
+ if (bare === "apply" || bare === "record" || bare === PR_ACTION_JOB || /^apply-wave-\d+$/.test(bare) || bare === "env-up" || bare === "env-down" || bare === "env-sweep") return "apply";
413
423
  return "default";
414
424
  }
415
425
 
@@ -442,14 +452,23 @@ export function prLoopPassedEnv(forge: ForgeKind, options: Pick<PrLoopPipelineOp
442
452
  export const PR_LOCK_JOB = "lock";
443
453
  export const PR_UNLOCK_JOB = "unlock";
444
454
 
445
- /** `chant lock --from-report` for the plan's report in {@link PR_LOOP_REPORT_DIR}; reads `PR_NUMBER` and `HEAD_SHA`. */
446
- export function prLockCommand(forge: ForgeKind): string {
447
- return ["chant", "lock", "--from-report", `${PR_LOOP_REPORT_DIR}/pr-plan.json`, "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', "--stage", "plan", "--forge", forge].join(" ");
455
+ /**
456
+ * `chant lock --from-report` for the plan's report in {@link PR_LOOP_REPORT_DIR}; reads `PR_NUMBER` and `HEAD_SHA`.
457
+ * With a product's `bin` (its words), the line runs through it, as the comment lock jobs do
458
+ * (INTENTIUS/plywood#22): a product's job image need not carry `chant` on PATH.
459
+ */
460
+ export function prLockCommand(forge: ForgeKind, bin?: string): string {
461
+ return withProductBin(["chant", "lock", "--from-report", `${PR_LOOP_REPORT_DIR}/pr-plan.json`, "--pr", '"$PR_NUMBER"', "--head", '"$HEAD_SHA"', "--stage", "plan", "--forge", forge].join(" "), bin);
448
462
  }
449
463
 
450
464
  /** `chant unlock` for the pull request that closed; reads `PR_NUMBER`. */
451
465
  export const PR_UNLOCK_COMMAND = 'chant unlock --pr "$PR_NUMBER"';
452
466
 
467
+ /** {@link PR_UNLOCK_COMMAND} through a product's `bin`, as {@link prLockCommand} takes it. */
468
+ export function prUnlockCommand(bin?: string): string {
469
+ return withProductBin(PR_UNLOCK_COMMAND, bin);
470
+ }
471
+
453
472
  /** The job answering `/<product> lock` (#4588). */
454
473
  export const PR_COMMENT_LOCK_JOB = "comment-lock";
455
474
  /** The job answering `/<product> unlock` (#4588). */
@@ -507,6 +526,81 @@ export function prCommentLockJobs(forge: ForgeKind, options: Pick<PrLoopPipeline
507
526
  return out;
508
527
  }
509
528
 
529
+ /** The job answering the action comment and the action dispatch (#4654). */
530
+ export const PR_ACTION_JOB = "action";
531
+
532
+ /** The action job's settings (#4654). */
533
+ export interface PrActionJobOptions {
534
+ /** The dispatch inputs' names. Default the words' member noun (`stack`, `root`) and `action`. */
535
+ inputs?: { member?: string; action?: string };
536
+ }
537
+
538
+ /** The action job (#4654): what starts it, what it runs, and the values it reads. */
539
+ export interface PrActionJob {
540
+ jobName: typeof PR_ACTION_JOB;
541
+ /** The comment it answers, `/<product> <action word>`, followed by a member and an action. */
542
+ comment: string;
543
+ /** The dispatch inputs, by role: the member's input name and the action's. */
544
+ inputs: { member: string; action: string };
545
+ /**
546
+ * The command line: the product's action verb with
547
+ * {@link PRODUCT_ACTION_EVENT_FLAG}, which reads the comment or the inputs
548
+ * from {@link PRODUCT_ACTION_ENV}. A run that waits for an approval exits
549
+ * with chant's `waiting` code; {@link script} turns that into a green job.
550
+ */
551
+ command: string;
552
+ /** The step's script: the command, with chant's `waiting` exit taken as success, since a pending approval is the expected first answer. */
553
+ script: string;
554
+ /** The values it reads, as the forge spells them. */
555
+ env: Record<string, string>;
556
+ }
557
+
558
+ const INPUT_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
559
+
560
+ /**
561
+ * The action job (#4654), with `actionJob`: one job that answers the
562
+ * product's action comment and a dispatch of the workflow with a member and
563
+ * an action. It runs at the target branch's commit (an `issue_comment` run's
564
+ * checkout) or the dispatched ref, never a pull request's head, and runs the
565
+ * product's own action verb, which asks for the gated request and runs the
566
+ * action once an approval counts. The comment and the inputs reach the verb
567
+ * as variables ({@link PRODUCT_ACTION_ENV}), never as shell text.
568
+ *
569
+ * Undefined without `actionJob`. Throws on GitLab, which starts no pipeline
570
+ * on a note; for words that name no `action` command or no `bin`, since
571
+ * chant has no action verb of its own; and for input names that are not
572
+ * plain names or are the same.
573
+ */
574
+ export function prActionJob(forge: ForgeKind, options: Pick<PrLoopPipelineOptions, "actionJob" | "words"> = {}): PrActionJob | undefined {
575
+ if (!options.actionJob) return undefined;
576
+ if (forge === "gitlab") throw new Error("the action job runs on GitHub and Forgejo, whose workflows start on a comment and on a dispatch with inputs; on GitLab, run the product's action verb from a pipeline of its own");
577
+ const words = resolveProductWords(options.words);
578
+ const typed = commandWord(words, "action");
579
+ if (typed === undefined) throw new Error(`--action-job answers /${words.product} <action command>, and the words name no action command; name one in the words' commands, or drop --action-job`);
580
+ if (!words.bin) throw new Error("--action-job runs the product's action verb, and the words name no bin; chant has no action verb of its own");
581
+ const given = options.actionJob === true ? {} : options.actionJob.inputs ?? {};
582
+ const inputs = { member: given.member ?? words.noun[0], action: given.action ?? "action" };
583
+ for (const [role, name] of Object.entries(inputs)) {
584
+ if (!INPUT_NAME.test(name)) throw new Error(`the action job's ${role} input is a plain name, not ${JSON.stringify(name)}`);
585
+ }
586
+ if (inputs.member === inputs.action) throw new Error(`the action job's two inputs need two names, and both are ${inputs.action}`);
587
+ const command = withProductBin(["chant", typed, PRODUCT_ACTION_EVENT_FLAG].join(" "), words.bin);
588
+ return {
589
+ jobName: PR_ACTION_JOB,
590
+ comment: `/${words.product} ${typed}`,
591
+ inputs,
592
+ command,
593
+ script: ["set +e", command, 'code="$?"', `if [ "$code" -eq ${CHANT_EXIT.waiting} ]; then echo "The action waits for an approval."; exit 0; fi`, 'exit "$code"'].join("\n"),
594
+ env: {
595
+ [PRODUCT_ACTION_ENV.comment]: "${{ github.event.comment.body }}",
596
+ [PRODUCT_ACTION_ENV.member]: `\${{ github.event.inputs.${inputs.member} }}`,
597
+ [PRODUCT_ACTION_ENV.action]: `\${{ github.event.inputs.${inputs.action} }}`,
598
+ PR_NUMBER: "${{ github.event.issue.number }}",
599
+ GITHUB_TOKEN: GITHUB_JOB_TOKEN,
600
+ },
601
+ };
602
+ }
603
+
510
604
  /** The job answering `/<product> <plan word>` (#4620). */
511
605
  export const PR_COMMENT_PREVIEW_JOB = "comment-preview";
512
606
  /** The job that posts the comment preview's note and status (#4620). */
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Day-2 actions in the product pipeline (#4654): `actions: true` counts the
3
+ * `action` command as answered by the product's own workflow, and
4
+ * `actionJob` writes the job that answers the comment and a dispatch with a
5
+ * member and an action, running the product's action verb, which reads
6
+ * what was asked with `productActionFromEnv`.
7
+ */
8
+ import { describe, expect, test } from "vitest";
9
+ import { productPipelineJobs } from "./product-pipeline";
10
+ import { prActionJob, prLoopJobStage, PR_ACTION_JOB } from "./pr-pipeline";
11
+ import { assertProductWords, productActionFromEnv, PRODUCT_ACTION_ENV, PRODUCT_ACTION_EVENT_FLAG } from "../ci-product-words";
12
+ import { PLYWOOD, TERRAGUCCI } from "../__fixtures__/product-words";
13
+
14
+ const PW = { ...PLYWOOD, commands: { preview: "plan" as const, action: "action" as const } };
15
+ const TG = { ...TERRAGUCCI, commands: { plan: "plan" as const, action: "action" as const }, aliases: [], bin: "terragucci" };
16
+
17
+ describe("the action command in the product pipeline (#4654)", () => {
18
+ test("refused without actions, counted with it, and named among the comments", () => {
19
+ expect(() => productPipelineJobs("github", "production", { words: TG })).toThrow(/commands.action needs a action job/);
20
+ const tg = productPipelineJobs("github", "production", { words: TG, actions: true });
21
+ expect(tg.comments.action).toBe("/terragucci action");
22
+ // The product's own workflow answers it: no job here.
23
+ expect(tg.action).toBeUndefined();
24
+ });
25
+
26
+ test("actionJob writes the job, answering the comment and a dispatch with the stack and action inputs", () => {
27
+ const pw = productPipelineJobs("github", "production", { words: PW, actionJob: true });
28
+ expect(pw.comments.action).toBe("/plywood action");
29
+ expect(pw.action).toMatchObject({ jobName: PR_ACTION_JOB, comment: "/plywood action", inputs: { member: "stack", action: "action" } });
30
+ expect(pw.action!.command).toBe(`npx --no-install plywood action ${PRODUCT_ACTION_EVENT_FLAG}`);
31
+ expect(pw.action!.env).toMatchObject({
32
+ [PRODUCT_ACTION_ENV.comment]: "${{ github.event.comment.body }}",
33
+ [PRODUCT_ACTION_ENV.member]: "${{ github.event.inputs.stack }}",
34
+ [PRODUCT_ACTION_ENV.action]: "${{ github.event.inputs.action }}",
35
+ });
36
+ // A pending approval is the expected first answer, so chant's waiting exit is a green job.
37
+ expect(pw.action!.script).toContain('if [ "$code" -eq 3 ]; then');
38
+ expect(prLoopJobStage(PR_ACTION_JOB)).toBe("apply");
39
+ });
40
+
41
+ test("the inputs can be named, and the job is refused where it cannot run", () => {
42
+ expect(prActionJob("forgejo", { words: TG, actionJob: { inputs: { member: "root", action: "address" } } })!.inputs).toEqual({ member: "root", action: "address" });
43
+ expect(prActionJob("github", { words: PW })).toBeUndefined();
44
+ expect(() => prActionJob("gitlab", { words: PW, actionJob: true })).toThrow(/GitHub and Forgejo/);
45
+ expect(() => prActionJob("github", { words: { ...PW, commands: { preview: "plan" as const } }, actionJob: true })).toThrow(/name no action command/);
46
+ expect(() => prActionJob("github", { words: { ...PW, bin: undefined }, actionJob: true })).toThrow(/no bin/);
47
+ expect(() => prActionJob("github", { words: PW, actionJob: { inputs: { member: "a b" } } })).toThrow(/plain name/);
48
+ expect(() => prActionJob("github", { words: PW, actionJob: { inputs: { member: "action" } } })).toThrow(/two names/);
49
+ });
50
+ });
51
+
52
+ describe("what an action job was asked for (#4654)", () => {
53
+ const words = assertProductWords(PW, { jobs: ["plan", "action"] });
54
+
55
+ test("a comment, parsed as a comment is", () => {
56
+ expect(productActionFromEnv(words, { [PRODUCT_ACTION_ENV.comment]: "/plywood action shop/prod-us rotate" })).toEqual({ kind: "action", member: "shop/prod-us", address: "rotate", from: "comment" });
57
+ expect(productActionFromEnv(words, { [PRODUCT_ACTION_ENV.comment]: "/plywood action shop/prod-us" })).toMatchObject({ kind: "refused" });
58
+ expect(productActionFromEnv(words, { [PRODUCT_ACTION_ENV.comment]: "/plywood preview" })).toMatchObject({ kind: "refused", reason: expect.stringContaining("/plywood action <stack> <action>") });
59
+ });
60
+
61
+ test("a dispatch's two inputs, checked by the same rules", () => {
62
+ expect(productActionFromEnv(words, { [PRODUCT_ACTION_ENV.member]: "shop/prod-us", [PRODUCT_ACTION_ENV.action]: "rotate", [PRODUCT_ACTION_ENV.comment]: "" })).toEqual({
63
+ kind: "action",
64
+ member: "shop/prod-us",
65
+ address: "rotate",
66
+ from: "dispatch",
67
+ });
68
+ for (const [member, action] of [["", "rotate"], ["shop/prod-us", ""], ["../etc", "rotate"], ["shop/prod-us", "rotate; id"], ["shop/prod-us", "$(id)"], ["shop prod", "rotate"]]) {
69
+ expect(productActionFromEnv(words, { [PRODUCT_ACTION_ENV.member]: member, [PRODUCT_ACTION_ENV.action]: action })).toMatchObject({ kind: "refused" });
70
+ }
71
+ });
72
+
73
+ test("words with no action command answer no action", () => {
74
+ expect(productActionFromEnv(assertProductWords(PLYWOOD), { [PRODUCT_ACTION_ENV.member]: "s", [PRODUCT_ACTION_ENV.action]: "a" })).toMatchObject({ kind: "refused", reason: expect.stringMatching(/no action command/) });
75
+ });
76
+ });
@@ -34,7 +34,7 @@ import {
34
34
  type CiProductWords,
35
35
  type CiProductWordsInput,
36
36
  } from "../ci-product-words";
37
- import { prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prStaleJob, withProductBin, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
37
+ import { prActionJob, prCommentLockJobs, prCommentPreviewJob, prLoopJobs, prLoopPostJob, prLoopRunner, prStaleJob, withProductBin, type PrActionJob, type PrCommentLockJob, type PrCommentPreviewJob, type PrLoopJob, type PrLoopPipelineOptions } from "./pr-pipeline";
38
38
  import type { DriverComponent } from "./driver";
39
39
  import type { ScheduledOpSpec } from "../lexicon";
40
40
  import type { CiRunner } from "../ci-jobs";
@@ -70,6 +70,15 @@ export interface ProductPipelineOptions extends Omit<PrLoopPipelineOptions, "wor
70
70
  * scheduled Ops.
71
71
  */
72
72
  agent?: boolean | ProductAgentOptions;
73
+ /**
74
+ * The product answers its `action` command (#4654) from a workflow of its
75
+ * own, such as terragucci's action workflow: `true` counts the command as
76
+ * answered, so words that map a word onto `action` are not refused, and
77
+ * `comments.action` names the comment. The pipeline writes no job for it.
78
+ * A product with no workflow of its own sets `actionJob` instead, and the
79
+ * pipeline writes the job ({@link ProductPipelineJobs.action}).
80
+ */
81
+ actions?: boolean;
73
82
  /**
74
83
  * The apply on merge from the component graph (#4588), when `waves` is
75
84
  * absent: the spec `pr-apply --wave-gate` runs, a wave per layer of
@@ -143,6 +152,12 @@ export interface ProductPipelineJobs {
143
152
  * job with the write token.
144
153
  */
145
154
  agent?: { comment: string; name: string; spec: ScheduledOpSpec };
155
+ /**
156
+ * The action job (#4654), with `actionJob`: the comment and the dispatch
157
+ * inputs it answers, and the product's action verb it runs. The GitHub and
158
+ * Forgejo lexicons render the same job.
159
+ */
160
+ action?: PrActionJob & { runner?: CiRunner };
146
161
  }
147
162
 
148
163
  /** An agent's settings as a product passes them (#4616): {@link OpAgentSpec} without the trigger, which the pipeline names. */
@@ -204,12 +219,14 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
204
219
  if (options.applyBeforeMerge || options.waves || options.componentWaves) jobs.push("apply");
205
220
  if (options.locks === "plan") jobs.push("lock", "unlock");
206
221
  if (options.agent) jobs.push("agent");
222
+ // #4654: the action command, answered by the product's own workflow (`actions`) or by the pipeline's action job.
223
+ if (options.actions || options.actionJob) jobs.push("action");
207
224
  // #4601: the note's merge sentence follows the jobs built here: waves on merge, an apply before merge, else a record for a release.
208
225
  // Words that ask for before-merge keep it when the pipeline has that job beside its waves.
209
226
  const built: CiProductApplyMode = options.waves || options.componentWaves ? "on-merge" : options.applyBeforeMerge ? "before-merge" : "release";
210
227
  const applyMode: CiProductApplyMode = options.words.applyMode === "before-merge" && options.applyBeforeMerge ? "before-merge" : built;
211
228
  const words = assertProductWords({ ...options.words, applyMode }, { jobs });
212
- const { waves: given, wavesSpecFile, member, agent: _agent, componentWaves, ...loop } = options;
229
+ const { waves: given, wavesSpecFile, member, agent: _agent, actions: _actions, componentWaves, ...loop } = options;
213
230
  const { respond } = options;
214
231
  // #4629: the pull request loop puts the responses on the apply and note jobs, as `chant build --pr-loop --respond` does.
215
232
  const prLoop: PrLoopPipelineOptions = { ...loop, words, gate: options.gate ?? words.prGate };
@@ -234,6 +251,8 @@ export function productPipelineJobs(forge: ForgeKind, env: string, options: Prod
234
251
  };
235
252
  const locks = prCommentLockJobs(forge, { locks: options.locks, words });
236
253
  if (locks.length > 0) out.locks = locks.map((job) => ({ ...job, ...defaultRunner }));
254
+ const action = prActionJob(forge, prLoop);
255
+ if (action) out.action = { ...action, ...(prLoopRunner(options, "apply") !== undefined ? { runner: prLoopRunner(options, "apply")! } : {}) };
237
256
  const stale = prStaleJob(forge, env, prLoop, member);
238
257
  if (stale) out.stale = { ...stale, ...defaultRunner };
239
258
  const preview = prCommentPreviewJob(forge, env, prLoop, member);
@@ -20,7 +20,7 @@ import { planFanOut } from "./fan-out";
20
20
  import { runFanOut } from "./fan-out-run";
21
21
  import { componentSetFanOut, groupFanOut, planAndRunComponentGroup, planComponentGroup, runComponentGroup } from "./groups";
22
22
  import { applyPrSet, approvalOf, decidePrGate, planPrSet, readOnlyLedger, type PrPlanSet } from "./pr-run";
23
- import { ledgerRowLease, leaseCapabilityStep, LockRowsHeldError, isLockRowsHeldError, type RowLeasePort } from "./row-lease";
23
+ import { ledgerRowLease, leaseCapabilityStep, LockRowsHeldError, LockWaitTimeoutError, isLockRowsHeldError, type RowLeasePort } from "./row-lease";
24
24
  import { memoryGateLedgerPort } from "../op/gate";
25
25
  import { computePlanDigest } from "../lifecycle/plan-digest";
26
26
  import { lockGrainBeforePlan, type LockGrain, type LockRow } from "../lifecycle/lock-rows";
@@ -487,4 +487,64 @@ describe("the ledger port", () => {
487
487
  expect(isLockRowsHeldError(err)).toBe(true);
488
488
  expect((err as Error).message).toContain("run 200 (https://forge.example/runs/200)");
489
489
  });
490
+
491
+ test("a waiting take that reaches its deadline throws LockWaitTimeoutError, still a held error, and leaves the queue", async () => {
492
+ const cwd = repo();
493
+ const other = ledgerRowLease("pr-apply", { cwd, holder: { run: "400", at: NOW }, alive: async () => "alive", log: quiet });
494
+ await other.take([row("stack shop/staging")], "staging");
495
+ const mine = ledgerRowLease("pr-apply", { cwd, holder: { run: "500", at: NOW }, alive: async () => "alive", log: quiet, waitSeconds: 0, pollMs: 1 });
496
+ const err = await mine.take([row("stack shop/staging")], "staging", { wait: true }).catch((e: unknown) => e);
497
+ expect(err).toBeInstanceOf(LockWaitTimeoutError);
498
+ expect(isLockRowsHeldError(err)).toBe(true);
499
+ expect((err as Error).message).toMatch(/^staging: LockWaitTimeoutError: waited \d+s for stack shop\/staging of pr-apply/);
500
+ expect((await readLockRows("pr-apply", { cwd })).waiting).toBeUndefined();
501
+ });
502
+ });
503
+
504
+ describe("the ruling for ci-products (2026-10-28): a step on the target or repo grain waits for its row", () => {
505
+ /** A capability on `grain` whose lexicon names the target's row. */
506
+ function targetCap(grain: LockGrain) {
507
+ const registry = new CapabilityRegistry().register({
508
+ kind: "fake-target",
509
+ defaultLockGrain: () => grain,
510
+ targetLockRow: (input: RootInput) => ({ key: `root ${input.root}`, target: input.root, address: input.root }),
511
+ async plan(_ctx: DeployContext, input: RootInput) {
512
+ return { member: input.root, planDigest: "sha256:" + "1".repeat(64) };
513
+ },
514
+ async run() {
515
+ return {};
516
+ },
517
+ } as never);
518
+ return registry.resolve("fake-target");
519
+ }
520
+ function waitingPort() {
521
+ const takes: Array<{ label: string; keys: string[]; wait: boolean }> = [];
522
+ const port: RowLeasePort = {
523
+ async take(rows, label, opts) {
524
+ takes.push({ label, keys: rows.map((r) => r.key), wait: opts?.wait === true });
525
+ return { release: async () => true };
526
+ },
527
+ };
528
+ return { port, takes };
529
+ }
530
+
531
+ test("the target grain takes the root row with a wait, before anything plans", async () => {
532
+ const { port, takes } = waitingPort();
533
+ const leased = await leaseCapabilityStep(targetCap("target"), { env: "prod", component: "net", rowLease: port }, { root: "net" });
534
+ expect(takes).toEqual([{ label: "net", keys: ["root net"], wait: true }]);
535
+ expect(leased.ctx.plans).toBeUndefined();
536
+ });
537
+
538
+ test("the repo grain waits for the repo row", async () => {
539
+ const { port, takes } = waitingPort();
540
+ await leaseCapabilityStep(targetCap("repo"), { env: "prod", component: "net", rowLease: port }, { root: "net" });
541
+ expect(takes).toEqual([{ label: "net", keys: ["repo"], wait: true }]);
542
+ });
543
+
544
+ test("the resource grain takes its rows with no wait, as before", async () => {
545
+ const w = world();
546
+ const { port, takes } = waitingPort();
547
+ await leaseCapabilityStep(w.registry.resolve("fake-res"), { env: "prod", component: "net", rowLease: port, lockGrain: "resource" }, { root: "net" });
548
+ expect(takes).toEqual([{ label: "net", keys: ["row net"], wait: false }]);
549
+ });
490
550
  });