@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
@@ -0,0 +1,91 @@
1
+ /**
2
+ * The pull request body for a template request (#4651), and the read that
3
+ * recovers the request from it. The body names the template, the version,
4
+ * each input on its own row, the requester (and the claimed requester, when
5
+ * the client names one) and where the request came from,
6
+ * and says that nothing was applied or approved. The request itself follows
7
+ * in a fenced block whose info string is `json` and the schema id, so behold
8
+ * and an audit read it from the pull request without a second file.
9
+ */
10
+
11
+ import { activeProductWords, type CiProductWords } from "../ci-product-words";
12
+ import { TEMPLATE_REQUEST_SCHEMA_ID, templateName, validateTemplateRequest, type TemplateRequest, type TemplateRequestVia } from "./template-request";
13
+
14
+ const VIA: Record<TemplateRequestVia, string> = {
15
+ form: "the request form",
16
+ mcp: "an agent over MCP",
17
+ cli: "the command line",
18
+ };
19
+
20
+ /** Text in a table cell's code span, with `|` escaped so the row holds and a fence longer than any backticks inside. */
21
+ function code(text: string): string {
22
+ const escaped = text.replace(/\|/g, "\\|").replace(/\n/g, " ");
23
+ const ticks = Math.max(0, ...[...escaped.matchAll(/`+/g)].map((m) => m[0].length));
24
+ const fence = "`".repeat(ticks + 1);
25
+ return ticks > 0 ? `${fence} ${escaped} ${fence}` : `${fence}${escaped}${fence}`;
26
+ }
27
+
28
+ /** A fence longer than any run of backticks in `text`, at least three. */
29
+ function fenceFor(text: string): string {
30
+ const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
31
+ return "`".repeat(Math.max(3, longest + 1));
32
+ }
33
+
34
+ /** The request's pull request body, in the product's words (default: the active ones). */
35
+ export function requestBody(request: TemplateRequest, words: CiProductWords = activeProductWords()): string {
36
+ const what = request.kind === "addon" && request.addon !== undefined ? `add-on ${code(request.addon)} for app ${code(request.app)}` : `app ${code(request.app)}`;
37
+ const lines: string[] = [
38
+ `### ${words.product} request: ${what} from ${templateName(request.template)}`,
39
+ "",
40
+ "| | |",
41
+ "| --- | --- |",
42
+ `| Template | ${code(request.template)} |`,
43
+ `| Version | ${code(request.version)} |`,
44
+ `| Requested by | ${code(request.requestedBy)} |`,
45
+ ...(request.claimedBy !== undefined ? [`| Claimed by (as given by the client; the forge does not vouch for it) | ${code(request.claimedBy)} |`] : []),
46
+ `| Through | ${VIA[request.via]} |`,
47
+ "",
48
+ ];
49
+ const names = Object.keys(request.inputs).sort();
50
+ if (names.length > 0) {
51
+ lines.push("| Input | Value |", "| --- | --- |");
52
+ for (const name of names) lines.push(`| ${code(name)} | ${code(JSON.stringify(request.inputs[name]) ?? "null")} |`);
53
+ } else {
54
+ lines.push("The request gives no inputs; every input takes its default.");
55
+ }
56
+ const [, applied] = words.verbs.apply;
57
+ const [, planned] = words.verbs.plan;
58
+ lines.push(
59
+ "",
60
+ `Nothing was ${applied} or approved. This pull request only adds files; it is ${planned} like any other, and a person reviews and merges it.`,
61
+ "",
62
+ );
63
+ const json = JSON.stringify(request, null, 2);
64
+ const fence = fenceFor(json);
65
+ lines.push(`${fence}json ${TEMPLATE_REQUEST_SCHEMA_ID}`, json, fence, "");
66
+ return lines.join("\n");
67
+ }
68
+
69
+ /**
70
+ * The request a pull request body carries: the first fenced block whose info
71
+ * string is `json` and the template-request/v1 schema id, parsed and
72
+ * checked against the schema. Undefined when the body has no such block, or
73
+ * the block is not a valid request.
74
+ */
75
+ export function parseRequestBody(body: string): TemplateRequest | undefined {
76
+ const lines = body.replace(/\r\n/g, "\n").split("\n");
77
+ for (let i = 0; i < lines.length; i++) {
78
+ const open = /^(`{3,})json[ \t]+(\S+)[ \t]*$/.exec(lines[i]!);
79
+ if (!open || open[2] !== TEMPLATE_REQUEST_SCHEMA_ID) continue;
80
+ const fence = open[1]!;
81
+ const end = lines.findIndex((l, j) => j > i && l.trimEnd() === fence);
82
+ if (end < 0) return undefined;
83
+ try {
84
+ const doc: unknown = JSON.parse(lines.slice(i + 1, end).join("\n"));
85
+ return validateTemplateRequest(doc).length === 0 ? (doc as TemplateRequest) : undefined;
86
+ } catch {
87
+ return undefined;
88
+ }
89
+ }
90
+ return undefined;
91
+ }
@@ -0,0 +1,100 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json",
4
+ "title": "chant template request",
5
+ "description": "A request for an app, or an add-on to an app, made from one version of a template in a release catalog, version 1 of its contract. A product turns it into a pull request on the branch requestBranch names, with requestBody as the body; the body carries this document in a fenced block whose info string is `json` and this schema's id, so a reader recovers it from the pull request alone. checkTemplateRequest refuses a request against the catalog and the version's template.yml (template.schema.json). Readers ignore fields they do not know; a field is only ever added within a version.",
6
+ "type": "object",
7
+ "required": [
8
+ "$schema",
9
+ "contract",
10
+ "kind",
11
+ "template",
12
+ "version",
13
+ "app",
14
+ "inputs",
15
+ "requestedBy",
16
+ "via"
17
+ ],
18
+ "properties": {
19
+ "$schema": {
20
+ "const": "https://intentius.io/chant/schemas/template-request/v1/template-request.schema.json"
21
+ },
22
+ "contract": {
23
+ "const": 1
24
+ },
25
+ "kind": {
26
+ "enum": [
27
+ "app",
28
+ "addon"
29
+ ],
30
+ "description": "app: a new app. addon: an add-on to the app named in `app`, which must exist."
31
+ },
32
+ "template": {
33
+ "type": "string",
34
+ "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(/[A-Za-z0-9][A-Za-z0-9._-]*)*$",
35
+ "description": "The template's address, such as `acme/bucket/aws` (namespace, name, system). The branch uses its name: the second-to-last segment of an address with three or more, else the last."
36
+ },
37
+ "version": {
38
+ "type": "string",
39
+ "minLength": 1,
40
+ "description": "The version in the catalog, or its digest for a release that names no version."
41
+ },
42
+ "app": {
43
+ "type": "string",
44
+ "pattern": "^[a-z][a-z0-9-]{0,39}$",
45
+ "description": "The app's name: a lowercase letter, then up to 39 lowercase letters, digits and -."
46
+ },
47
+ "addon": {
48
+ "type": "string",
49
+ "pattern": "^[a-z][a-z0-9-]{0,39}$",
50
+ "description": "For kind addon: the add-on's name, with the same rule as `app`."
51
+ },
52
+ "inputs": {
53
+ "type": "object",
54
+ "description": "The values given, by input name. An input left out takes its default. A sensitive input is never here. In an add-on request, a string `app.<output>` names an output of the app's module, for an input of any kind; the engine's renderer resolves it. In an app request it is a plain string and is checked against the input's kind.",
55
+ "additionalProperties": true
56
+ },
57
+ "requestedBy": {
58
+ "type": "string",
59
+ "minLength": 1,
60
+ "description": "Who asked, as the forge vouches for it: the login of the run's actor, a person or the identity an agent runs as."
61
+ },
62
+ "claimedBy": {
63
+ "type": "string",
64
+ "minLength": 1,
65
+ "description": "The person the client says filled the form or asked the agent, when it names one. The forge does not vouch for it, so a reader shows it as claimed, next to requestedBy."
66
+ },
67
+ "via": {
68
+ "enum": [
69
+ "form",
70
+ "mcp",
71
+ "cli"
72
+ ],
73
+ "description": "Where the request came from: a form, an agent over MCP, or the command line."
74
+ }
75
+ },
76
+ "allOf": [
77
+ {
78
+ "if": {
79
+ "properties": {
80
+ "kind": {
81
+ "const": "addon"
82
+ }
83
+ }
84
+ },
85
+ "then": {
86
+ "properties": {
87
+ "addon": true
88
+ },
89
+ "required": [
90
+ "addon"
91
+ ]
92
+ },
93
+ "else": {
94
+ "properties": {
95
+ "addon": false
96
+ }
97
+ }
98
+ }
99
+ ]
100
+ }
@@ -0,0 +1,316 @@
1
+ /**
2
+ * template-request/v1 and template.yml/v1 (#4651): the schemas, one test per
3
+ * refusal code, the branch, and the pull request body's golden and
4
+ * round trip.
5
+ */
6
+ import { describe, expect, test } from "vitest";
7
+ import Ajv2020 from "ajv/dist/2020";
8
+ import requestSchema from "./template-request.schema.json";
9
+ import templateSchema from "./template.schema.json";
10
+ import pkg from "../../package.json";
11
+ import { buildReleaseCatalog } from "../lifecycle/release-catalog";
12
+ import type { ReleaseRecord } from "../lifecycle/release-ledger";
13
+ import { NEXT_RELEASE } from "../release-floors";
14
+ import { resolveProductWords } from "../ci-product-words";
15
+ import {
16
+ checkTemplateRequest,
17
+ inputKindProblem,
18
+ isAppOutputRef,
19
+ makeTemplateRequest,
20
+ parseRequestBody,
21
+ parseTemplateSpec,
22
+ requestBody,
23
+ requestBranch,
24
+ TEMPLATE_INPUT_KINDS,
25
+ TEMPLATE_REQUEST_FLOOR,
26
+ TEMPLATE_REQUEST_SCHEMA_ID,
27
+ TEMPLATE_SPEC_SCHEMA_ID,
28
+ TemplateSpecError,
29
+ templateName,
30
+ templateSpecProblems,
31
+ validateTemplateRequest,
32
+ type TemplateRequest,
33
+ type TemplateRequestRefusalCode,
34
+ } from "./index";
35
+
36
+ const rec = (over: Partial<ReleaseRecord>): ReleaseRecord => ({
37
+ version: 1,
38
+ component: "acme/bucket/aws",
39
+ env: "registry",
40
+ digest: "sha256:aaa",
41
+ gitSha: "1111111111111111111111111111111111111111",
42
+ runId: "run-1",
43
+ timestamp: "2026-10-01T00:00:00.000Z",
44
+ actor: "ci",
45
+ ...over,
46
+ });
47
+
48
+ const catalog = buildReleaseCatalog(
49
+ {
50
+ releases: [
51
+ rec({ releaseVersion: "1.0.0", digest: "sha256:v1", timestamp: "2026-10-01T00:00:00.000Z" }),
52
+ rec({ releaseVersion: "1.1.0", digest: "sha256:v11", timestamp: "2026-10-05T00:00:00.000Z" }),
53
+ rec({ releaseVersion: "1.2.0", digest: "sha256:v12", timestamp: "2026-10-09T00:00:00.000Z" }),
54
+ rec({ releaseVersion: "2.0.0", digest: "sha256:v2", timestamp: "2026-10-10T00:00:00.000Z" }),
55
+ ],
56
+ statuses: [{ component: "acme/bucket/aws", digest: "sha256:v11", status: "yanked", reason: "leaks", replacement: "1.2.0", actor: "ops", timestamp: "2026-10-06T00:00:00.000Z" }],
57
+ attestations: [
58
+ { component: "acme/bucket/aws", digest: "sha256:v1", state: "signed" },
59
+ { component: "acme/bucket/aws", digest: "sha256:v11", state: "signed" },
60
+ { component: "acme/bucket/aws", digest: "sha256:v2", state: "verified" },
61
+ ],
62
+ },
63
+ { generatedAt: "2026-10-27T00:00:00.000Z", chant: "0.0.0-test" },
64
+ );
65
+
66
+ const TEMPLATE_YML = `contract: 1
67
+ description: An object store bucket for one app.
68
+ inputs:
69
+ - name: bucket_name
70
+ kind: string
71
+ label: Bucket name
72
+ - name: versioning
73
+ kind: bool
74
+ default: true
75
+ - name: retention_days
76
+ kind: number
77
+ default: 30
78
+ - name: tags
79
+ kind: map
80
+ of: string
81
+ default: {}
82
+ - name: readers
83
+ kind: list
84
+ of: string
85
+ required: false
86
+ - name: kms_key
87
+ kind: string
88
+ sensitive: true
89
+ `;
90
+
91
+ const spec = parseTemplateSpec(TEMPLATE_YML);
92
+
93
+ const base = (over: Partial<TemplateRequest> = {}): TemplateRequest =>
94
+ ({
95
+ ...makeTemplateRequest({
96
+ kind: "app",
97
+ template: "acme/bucket/aws",
98
+ version: "1.0.0",
99
+ app: "orders",
100
+ inputs: { bucket_name: "orders-data", tags: { team: "payments" } },
101
+ requestedBy: "alice",
102
+ via: "form",
103
+ }),
104
+ ...over,
105
+ }) as TemplateRequest;
106
+
107
+ describe("schemas", () => {
108
+ test("both are valid draft 2020-12 documents under template-request/v1", () => {
109
+ const ajv = new Ajv2020({ strict: true, allErrors: true });
110
+ expect(ajv.validateSchema(requestSchema)).toBe(true);
111
+ expect(ajv.validateSchema(templateSchema)).toBe(true);
112
+ expect(requestSchema.$id).toBe(TEMPLATE_REQUEST_SCHEMA_ID);
113
+ expect(TEMPLATE_REQUEST_SCHEMA_ID.endsWith("template-request/v1/template-request.schema.json")).toBe(true);
114
+ expect(TEMPLATE_SPEC_SCHEMA_ID.endsWith("template-request/v1/template.schema.json")).toBe(true);
115
+ expect(Object.keys(requestSchema.properties).sort()).toEqual(["$schema", "addon", "app", "claimedBy", "contract", "inputs", "kind", "requestedBy", "template", "version", "via"]);
116
+ });
117
+
118
+ test("the input kinds are the schema's, and each is documented there", () => {
119
+ expect(templateSchema.$defs.kind.enum).toEqual([...TEMPLATE_INPUT_KINDS]);
120
+ for (const k of TEMPLATE_INPUT_KINDS) expect(templateSchema.$defs.kind.description).toContain(`${k}:`);
121
+ });
122
+
123
+ test("the floor is the next release", () => {
124
+ expect(TEMPLATE_REQUEST_FLOOR).toBe(NEXT_RELEASE);
125
+ });
126
+
127
+ test("the package exports ./template-request and its schemas", () => {
128
+ const exports = pkg.exports as Record<string, unknown>;
129
+ expect(exports["./template-request"]).toMatchObject({ development: "./src/template-request/index.ts", import: "./dist/template-request/index.js" });
130
+ expect(exports["./template-request/*.schema.json"]).toBe("./src/template-request/*.schema.json");
131
+ });
132
+ });
133
+
134
+ describe("template.yml", () => {
135
+ test("parses, with required read from the default", () => {
136
+ expect(spec.inputs.map((i) => i.name)).toEqual(["bucket_name", "versioning", "retention_days", "tags", "readers", "kms_key"]);
137
+ });
138
+
139
+ test("refuses a repeated name, a default of the wrong kind, a required input with a default, and `of` on a scalar", () => {
140
+ const doc = {
141
+ contract: 1,
142
+ description: "x",
143
+ inputs: [
144
+ { name: "a", kind: "number", default: "3" },
145
+ { name: "a", kind: "string" },
146
+ { name: "b", kind: "bool", default: false, required: true },
147
+ ],
148
+ };
149
+ const problems = templateSpecProblems(doc);
150
+ expect(problems).toEqual([
151
+ '/inputs/0 (a) default is string, and the input is a number',
152
+ '/inputs/1 (a) repeats the name "a"',
153
+ "/inputs/2 (b) is required and has a default; an input with a default is optional",
154
+ ]);
155
+ expect(templateSpecProblems({ contract: 1, description: "x", inputs: [{ name: "c", kind: "string", of: "string" }] }).length).toBeGreaterThan(0);
156
+ expect(templateSpecProblems({ contract: 1, description: "x", inputs: [{ name: "c", kind: "tuple" }] }).length).toBeGreaterThan(0);
157
+ expect(() => parseTemplateSpec("contract: 1\n")).toThrow(TemplateSpecError);
158
+ expect(() => parseTemplateSpec("a: [\n")).toThrow(/not YAML/);
159
+ });
160
+
161
+ test("kind checks", () => {
162
+ expect(inputKindProblem({ kind: "number" }, Number.NaN)).toBeDefined();
163
+ expect(inputKindProblem({ kind: "list", of: "number" }, [1, "2"])).toBe("is a list whose element 1 is string, and the input is a list of number");
164
+ expect(inputKindProblem({ kind: "list" }, [1, "2"])).toBeUndefined();
165
+ expect(inputKindProblem({ kind: "map", of: "bool" }, { a: true, b: 1 })).toBe('is a map whose "b" is number, and the input is a map of bool');
166
+ expect(inputKindProblem({ kind: "object" }, [])).toBe("is list, and the input is a object");
167
+ expect(inputKindProblem({ kind: "string" }, null)).toBe("is null, and the input is a string");
168
+ });
169
+ });
170
+
171
+ describe("checkTemplateRequest", () => {
172
+ test("accepts a request the catalog and template allow", () => {
173
+ expect(checkTemplateRequest(base(), catalog, spec)).toEqual({ ok: true, request: base() });
174
+ });
175
+
176
+ const cases: Array<[TemplateRequestRefusalCode, unknown, string, RegExp]> = [
177
+ ["unknown-version", base({ version: "9.9.9" }), "version", /version "9\.9\.9" of acme\/bucket\/aws is not in the catalog/],
178
+ ["not-active", base({ version: "1.1.0" }), "version", /version 1\.1\.0 of acme\/bucket\/aws is yanked; use 1\.2\.0/],
179
+ ["unsigned", base({ version: "1.2.0" }), "version", /version 1\.2\.0 of acme\/bucket\/aws is unsigned, and requests need signed/],
180
+ ["unknown-input", base({ inputs: { bucket_name: "b", colour: "red" } }), "inputs.colour", /inputs\.colour: .* has no input "colour"/],
181
+ ["missing-input", base({ inputs: {} }), "inputs.bucket_name", /inputs\.bucket_name is required/],
182
+ ["sensitive-input", base({ inputs: { bucket_name: "b", kms_key: "k" } }), "inputs.kms_key", /inputs\.kms_key is sensitive/],
183
+ ["input-type", base({ inputs: { bucket_name: "b", retention_days: "30" } }), "inputs.retention_days", /inputs\.retention_days is string, and the input is a number/],
184
+ ["bad-name", base({ app: "Orders" }), "app", /app "Orders" is not a name/],
185
+ ];
186
+ test.each(cases)("%s", (code, request, field, reason) => {
187
+ const out = checkTemplateRequest(request, catalog, spec);
188
+ expect(out.ok).toBe(false);
189
+ if (out.ok) return;
190
+ expect(out.refusals).toHaveLength(1);
191
+ expect(out.refusals[0]).toMatchObject({ code, field });
192
+ expect(out.refusals[0]!.reason).toMatch(reason);
193
+ expect(out.refusals[0]!.reason).toContain(field);
194
+ });
195
+
196
+ test("bad-name covers the add-on, and a deprecated version is not active either", () => {
197
+ const addon = checkTemplateRequest(base({ kind: "addon", addon: "9cache" }), catalog, spec);
198
+ expect(addon.ok ? [] : addon.refusals.map((r) => [r.code, r.field])).toEqual([["bad-name", "addon"]]);
199
+ const deprecated = buildReleaseCatalog(
200
+ { releases: [rec({ releaseVersion: "1.0.0" })], statuses: [{ component: "acme/bucket/aws", digest: "sha256:aaa", status: "deprecated", actor: "ops", timestamp: "2026-10-02T00:00:00.000Z" }], attestations: [{ component: "acme/bucket/aws", digest: "sha256:aaa", state: "signed" }] },
201
+ { generatedAt: "2026-10-27T00:00:00.000Z", chant: "0.0.0-test" },
202
+ );
203
+ const out = checkTemplateRequest(base(), deprecated, spec);
204
+ expect(out.ok ? [] : out.refusals.map((r) => r.code)).toEqual(["not-active"]);
205
+ });
206
+
207
+ test("a template the catalog does not list is unknown-version; `component` names it", () => {
208
+ const out = checkTemplateRequest(base({ template: "acme/queue/aws" }), catalog, spec);
209
+ expect(out.ok ? [] : out.refusals.map((r) => r.code)).toEqual(["unknown-version"]);
210
+ expect(checkTemplateRequest(base({ template: "registry.example/acme/bucket/aws" }), catalog, spec, { component: "acme/bucket/aws" }).ok).toBe(true);
211
+ });
212
+
213
+ test("require: unsigned accepts any attestation, verified refuses signed", () => {
214
+ expect(checkTemplateRequest(base({ version: "1.2.0" }), catalog, spec, { require: "unsigned" }).ok).toBe(true);
215
+ const out = checkTemplateRequest(base(), catalog, spec, { require: "verified" });
216
+ expect(out.ok ? [] : out.refusals.map((r) => r.code)).toEqual(["unsigned"]);
217
+ expect(checkTemplateRequest(base({ version: "2.0.0" }), catalog, spec, { require: "verified" }).ok).toBe(true);
218
+ });
219
+
220
+ test("an add-on's app.<output> is accepted for any kind; an app request checks it as a string", () => {
221
+ const refs = { bucket_name: "app.bucket_id", retention_days: "app.retention", readers: "app.reader_arns", tags: "app.tags" };
222
+ const addon = base({ kind: "addon", addon: "cache", inputs: refs });
223
+ expect(checkTemplateRequest(addon, catalog, spec)).toEqual({ ok: true, request: addon });
224
+ const app = checkTemplateRequest(base({ inputs: refs }), catalog, spec);
225
+ expect(app.ok ? [] : app.refusals.map((r) => [r.code, r.field])).toEqual([
226
+ ["input-type", "inputs.retention_days"],
227
+ ["input-type", "inputs.readers"],
228
+ ["input-type", "inputs.tags"],
229
+ ]);
230
+ for (const r of app.ok ? [] : app.refusals) expect(r.reason).toMatch(/reads as an app output, and only an add-on request can name one/);
231
+ const notRef = checkTemplateRequest(base({ kind: "addon", addon: "cache", inputs: { bucket_name: "b", retention_days: "app.9x" } }), catalog, spec);
232
+ expect(notRef.ok ? [] : notRef.refusals.map((r) => [r.code, r.reason.includes("app output")])).toEqual([["input-type", false]]);
233
+ });
234
+
235
+ test("isAppOutputRef", () => {
236
+ expect(["app.private_subnets", "app.x", "app._a-b"].every(isAppOutputRef)).toBe(true);
237
+ expect(["app.", "app.9x", "app.a.b", "module.app.x", " app.x", 3, null, ["app.x"]].some(isAppOutputRef)).toBe(false);
238
+ });
239
+
240
+ test("a document the schema refuses is invalid", () => {
241
+ const { via: _via, ...noVia } = base();
242
+ const out = checkTemplateRequest(noVia, catalog, spec);
243
+ expect(out.ok ? [] : out.refusals.map((r) => r.code)).toEqual(["invalid"]);
244
+ const appWithAddon = checkTemplateRequest(base({ addon: "cache" }), catalog, spec);
245
+ expect(appWithAddon.ok).toBe(false);
246
+ const addonWithout = checkTemplateRequest(base({ kind: "addon" }), catalog, spec);
247
+ expect(addonWithout.ok).toBe(false);
248
+ });
249
+ });
250
+
251
+ describe("requestBranch", () => {
252
+ test("request/<template-name>/<app>[/<addon>]", () => {
253
+ expect(requestBranch({ kind: "app", template: "acme/bucket/aws", app: "orders" })).toBe("request/bucket/orders");
254
+ expect(requestBranch({ kind: "app", template: "acme/bucket/aws", app: "orders", addon: "cache" })).toBe("request/bucket/orders/cache");
255
+ expect(requestBranch({ kind: "addon", template: "acme/bucket/aws", app: "orders", addon: "cache" })).toBe("request/bucket/orders/cache");
256
+ });
257
+
258
+ test("the template name of an address", () => {
259
+ expect(templateName("registry.example/acme/bucket/aws")).toBe("bucket");
260
+ expect(templateName("acme/bucket")).toBe("bucket");
261
+ expect(templateName("bucket")).toBe("bucket");
262
+ });
263
+ });
264
+
265
+ describe("requestBody", () => {
266
+ const words = resolveProductWords({ product: "terragucci" });
267
+ const request = makeTemplateRequest({
268
+ kind: "app",
269
+ template: "acme/bucket/aws",
270
+ version: "1.0.0",
271
+ app: "orders",
272
+ inputs: { bucket_name: "orders-data", tags: { team: "pay|ments" }, readers: ["svc-a", "svc-b"] },
273
+ requestedBy: "alice",
274
+ claimedBy: "bob",
275
+ via: "mcp",
276
+ });
277
+
278
+ test("matches the golden", async () => {
279
+ await expect(requestBody(request, words)).toMatchFileSnapshot("./__fixtures__/request-body.md");
280
+ });
281
+
282
+ test("names the template, version, every input, the requester, via, and that nothing was applied", () => {
283
+ const body = requestBody(request, words);
284
+ for (const s of ["`acme/bucket/aws`", "`1.0.0`", "`alice`", "an agent over MCP", "| `bucket_name` |", "| `readers` |", "| `tags` |", "Nothing was applied or approved."]) expect(body).toContain(s);
285
+ expect(requestBody(request, resolveProductWords({ product: "plywood", verbs: { plan: ["preview", "previewed"], apply: ["update", "updated"] } }))).toContain("Nothing was updated or approved.");
286
+ });
287
+
288
+ test("the fenced block parses back to the request", () => {
289
+ expect(parseRequestBody(requestBody(request, words))).toEqual(request);
290
+ const addon = base({ kind: "addon", addon: "cache", inputs: { note: "a ```fence``` inside" } });
291
+ const body = requestBody(addon, words);
292
+ expect(body).toContain("add-on `cache` for app `orders`");
293
+ expect(parseRequestBody(body)).toEqual(addon);
294
+ expect(parseRequestBody(body.replace(/\n/g, "\r\n"))).toEqual(addon);
295
+ });
296
+
297
+ test("a claimed requester gets its own row, labelled as claimed, only when set", () => {
298
+ const body = requestBody(request, words);
299
+ expect(body).toContain("| Claimed by (as given by the client; the forge does not vouch for it) | `bob` |");
300
+ expect(parseRequestBody(body)?.claimedBy).toBe("bob");
301
+ const without = base();
302
+ expect(without).not.toHaveProperty("claimedBy");
303
+ const plain = requestBody(without, words);
304
+ expect(plain).not.toContain("Claimed by");
305
+ expect(parseRequestBody(plain)).toEqual(without);
306
+ expect(parseRequestBody(plain)).not.toHaveProperty("claimedBy");
307
+ expect(validateTemplateRequest({ ...without, claimedBy: "" }).length).toBeGreaterThan(0);
308
+ expect(validateTemplateRequest({ ...without, claimedBy: 7 }).length).toBeGreaterThan(0);
309
+ });
310
+
311
+ test("a body without the block, or with a broken one, carries no request", () => {
312
+ expect(parseRequestBody("no request here")).toBeUndefined();
313
+ expect(parseRequestBody(`\`\`\`json ${TEMPLATE_REQUEST_SCHEMA_ID}\n{"x":1}\n\`\`\`\n`)).toBeUndefined();
314
+ expect(parseRequestBody(`\`\`\`json ${TEMPLATE_REQUEST_SCHEMA_ID}\n{not json\n\`\`\`\n`)).toBeUndefined();
315
+ });
316
+ });