@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,235 @@
1
+ /**
2
+ * The template request, template-request/v1 (#4651): "an app named orders
3
+ * from template X at version Y with these inputs", as one JSON document.
4
+ * terragucci, plywood and behold all turn one into a pull request, and this
5
+ * module is where they agree on the document, its refusals and its branch.
6
+ * ./request-body.ts writes the pull request body that carries it.
7
+ *
8
+ * {@link checkTemplateRequest} reads the release catalog for the version's
9
+ * status and attestation, and the version's template.yml (./template-spec.ts)
10
+ * for its inputs. It reads no engine field: the inputs' kinds are
11
+ * engine-neutral.
12
+ */
13
+
14
+ import schema from "./template-request.schema.json" with { type: "json" };
15
+ import { NEXT_RELEASE } from "../release-floors";
16
+ import { catalogVersion, type AttestationState, type CatalogComponent, type ReleaseCatalog } from "../lifecycle/release-catalog";
17
+ import { inputKindProblem, inputRequired, isAppOutputRef, type TemplateSpec } from "./template-spec";
18
+ import { schemaProblems } from "./validate";
19
+
20
+ /** The first chant that writes and reads template-request/v1 and template.yml/v1 (#4651). */
21
+ export const TEMPLATE_REQUEST_FLOOR = NEXT_RELEASE;
22
+
23
+ /** The request document's `$schema`. */
24
+ export const TEMPLATE_REQUEST_SCHEMA_ID: string = schema.$id;
25
+
26
+ /** The request's contract version. */
27
+ export const TEMPLATE_REQUEST_CONTRACT = 1;
28
+
29
+ /** An app or add-on name: a lowercase letter, then up to 39 lowercase letters, digits and -. */
30
+ export const REQUEST_NAME_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
31
+
32
+ /** Where a request came from. */
33
+ export type TemplateRequestVia = "form" | "mcp" | "cli";
34
+
35
+ /** A template request. */
36
+ export interface TemplateRequest {
37
+ $schema: string;
38
+ contract: 1;
39
+ kind: "app" | "addon";
40
+ /** The template's address, such as `acme/bucket/aws`. */
41
+ template: string;
42
+ /** The version in the catalog, or a digest for a release that names none. */
43
+ version: string;
44
+ app: string;
45
+ /** For kind `addon`: the add-on's name. */
46
+ addon?: string;
47
+ /** The values given, by input name. */
48
+ inputs: Record<string, unknown>;
49
+ /** Who asked, as the forge vouches for it: the login of the run's actor. */
50
+ requestedBy: string;
51
+ /**
52
+ * The person the client says filled the form or asked the agent, when it
53
+ * names one. The forge does not vouch for it; it is shown as claimed.
54
+ */
55
+ claimedBy?: string;
56
+ via: TemplateRequestVia;
57
+ }
58
+
59
+ /** The fields a caller gives {@link makeTemplateRequest}; `$schema` and `contract` are filled in. */
60
+ export type TemplateRequestInput = Omit<TemplateRequest, "$schema" | "contract">;
61
+
62
+ /**
63
+ * Why a request is refused. `invalid` is a document the schema refuses for
64
+ * a reason no other code names (a missing field, a `via` it does not know).
65
+ */
66
+ export type TemplateRequestRefusalCode =
67
+ | "unknown-version"
68
+ | "not-active"
69
+ | "unsigned"
70
+ | "unknown-input"
71
+ | "missing-input"
72
+ | "sensitive-input"
73
+ | "input-type"
74
+ | "bad-name"
75
+ | "invalid";
76
+
77
+ /** Every refusal code, in the order {@link checkTemplateRequest} checks them. */
78
+ export const TEMPLATE_REQUEST_REFUSAL_CODES: readonly TemplateRequestRefusalCode[] = [
79
+ "bad-name",
80
+ "invalid",
81
+ "unknown-version",
82
+ "not-active",
83
+ "unsigned",
84
+ "unknown-input",
85
+ "sensitive-input",
86
+ "input-type",
87
+ "missing-input",
88
+ ];
89
+
90
+ /** One refusal: its code, the request field it is about, and a sentence naming that field. */
91
+ export interface TemplateRequestRefusal {
92
+ code: TemplateRequestRefusalCode;
93
+ /** `app`, `addon`, `version`, `inputs.<name>`, or the schema path for `invalid`. */
94
+ field: string;
95
+ reason: string;
96
+ }
97
+
98
+ export type TemplateRequestCheck = { ok: true; request: TemplateRequest } | { ok: false; refusals: TemplateRequestRefusal[] };
99
+
100
+ export interface CheckTemplateRequestOptions {
101
+ /**
102
+ * The catalog component the template is. Absent: the component named
103
+ * `request.template`. A product that lists components by path looks the
104
+ * address up itself and passes the name here.
105
+ */
106
+ component?: string;
107
+ /** The lowest attestation a version may have. Default `signed`; `unsigned` accepts any. */
108
+ require?: AttestationState;
109
+ }
110
+
111
+ const ATTESTATION_RANK: Record<AttestationState, number> = { unsigned: 0, signed: 1, verified: 2 };
112
+
113
+ /** Fill `$schema` and `contract` into a request. */
114
+ export function makeTemplateRequest(input: TemplateRequestInput): TemplateRequest {
115
+ const { kind, template, version, app, addon, inputs, requestedBy, claimedBy, via } = input;
116
+ return {
117
+ $schema: TEMPLATE_REQUEST_SCHEMA_ID,
118
+ contract: TEMPLATE_REQUEST_CONTRACT,
119
+ kind,
120
+ template,
121
+ version,
122
+ app,
123
+ ...(addon !== undefined ? { addon } : {}),
124
+ inputs,
125
+ requestedBy,
126
+ ...(claimedBy !== undefined ? { claimedBy } : {}),
127
+ via,
128
+ };
129
+ }
130
+
131
+ /** The schema problems of a request document, one line each; empty when it is valid. */
132
+ export function validateTemplateRequest(doc: unknown): string[] {
133
+ return schemaProblems(TEMPLATE_REQUEST_SCHEMA_ID, doc);
134
+ }
135
+
136
+ const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
137
+
138
+ /**
139
+ * Check a request against the catalog and the version's template.yml.
140
+ * Returns every refusal, each with its code and a reason naming the field.
141
+ * A bad name or a document the schema refuses stops the check there, and so
142
+ * does a version the catalog does not list; past that, the version's status
143
+ * and attestation and each input are all checked.
144
+ */
145
+ export function checkTemplateRequest(
146
+ request: unknown,
147
+ catalog: ReleaseCatalog,
148
+ templateSpec: TemplateSpec,
149
+ options: CheckTemplateRequestOptions = {},
150
+ ): TemplateRequestCheck {
151
+ const refused = (refusals: TemplateRequestRefusal[]): TemplateRequestCheck => ({ ok: false, refusals });
152
+
153
+ // Names first, so a bad one reads as bad-name and not as a schema pattern.
154
+ const names: TemplateRequestRefusal[] = [];
155
+ const probe: Record<string, unknown> = isRecord(request) ? { ...request } : {};
156
+ for (const field of ["app", "addon"] as const) {
157
+ const v = probe[field];
158
+ if (typeof v !== "string" || REQUEST_NAME_PATTERN.test(v)) continue;
159
+ names.push({
160
+ code: "bad-name",
161
+ field,
162
+ reason: `${field} ${JSON.stringify(v)} is not a name: a lowercase letter, then up to 39 lowercase letters, digits and -`,
163
+ });
164
+ probe[field] = "x";
165
+ }
166
+ if (names.length > 0) return refused(names);
167
+
168
+ const problems = validateTemplateRequest(isRecord(request) ? probe : request);
169
+ if (problems.length > 0) {
170
+ return refused(problems.map((p) => ({ code: "invalid", field: p.split(" ")[0]!, reason: `the request ${p}` })));
171
+ }
172
+ const req = request as TemplateRequest;
173
+
174
+ const componentName = options.component ?? req.template;
175
+ const component: CatalogComponent | undefined = catalog.components.find((c) => c.name === componentName);
176
+ if (!component) {
177
+ return refused([{ code: "unknown-version", field: "version", reason: `version ${JSON.stringify(req.version)}: the catalog lists no template ${JSON.stringify(componentName)}` }]);
178
+ }
179
+ const version = catalogVersion(catalog, component.name, req.version);
180
+ if (!version) {
181
+ const listed = component.versions.map((v) => v.version ?? v.digest).join(", ") || "none";
182
+ return refused([{ code: "unknown-version", field: "version", reason: `version ${JSON.stringify(req.version)} of ${req.template} is not in the catalog (it lists ${listed})` }]);
183
+ }
184
+
185
+ const refusals: TemplateRequestRefusal[] = [];
186
+ if (version.status.state !== "active") {
187
+ const instead = version.status.replacement ? `; use ${version.status.replacement}` : "";
188
+ refusals.push({ code: "not-active", field: "version", reason: `version ${req.version} of ${req.template} is ${version.status.state}${instead}` });
189
+ }
190
+ const require = options.require ?? "signed";
191
+ if (ATTESTATION_RANK[version.attestation.state] < ATTESTATION_RANK[require]) {
192
+ refusals.push({ code: "unsigned", field: "version", reason: `version ${req.version} of ${req.template} is ${version.attestation.state}, and requests need ${require}` });
193
+ }
194
+
195
+ const byName = new Map(templateSpec.inputs.map((i) => [i.name, i]));
196
+ for (const [name, value] of Object.entries(req.inputs)) {
197
+ const field = `inputs.${name}`;
198
+ const input = byName.get(name);
199
+ if (!input) {
200
+ refusals.push({ code: "unknown-input", field, reason: `${field}: ${req.template} ${req.version} has no input ${JSON.stringify(name)}` });
201
+ continue;
202
+ }
203
+ if (input.sensitive) {
204
+ refusals.push({ code: "sensitive-input", field, reason: `${field} is sensitive, and a request is written into a pull request; the app reads it from its secret store` });
205
+ continue;
206
+ }
207
+ // An add-on's `app.<output>` names the app module's output; the renderer resolves it.
208
+ if (req.addon !== undefined && isAppOutputRef(value)) continue;
209
+ const p = inputKindProblem(input, value);
210
+ if (!p) continue;
211
+ const why = isAppOutputRef(value) ? `; ${JSON.stringify(value)} reads as an app output, and only an add-on request can name one` : "";
212
+ refusals.push({ code: "input-type", field, reason: `${field} ${p}${why}` });
213
+ }
214
+ for (const input of templateSpec.inputs) {
215
+ if (input.sensitive || !inputRequired(input) || input.name in req.inputs) continue;
216
+ refusals.push({ code: "missing-input", field: `inputs.${input.name}`, reason: `inputs.${input.name} is required by ${req.template} ${req.version} and the request gives none` });
217
+ }
218
+
219
+ return refusals.length > 0 ? refused(refusals) : { ok: true, request: req };
220
+ }
221
+
222
+ /**
223
+ * A template's name as a branch uses it: the second-to-last segment of an
224
+ * address with three or more (`acme/bucket/aws` is `bucket`), else the last.
225
+ */
226
+ export function templateName(template: string): string {
227
+ const parts = template.split("/").filter(Boolean);
228
+ return (parts.length >= 3 ? parts[parts.length - 2] : parts[parts.length - 1]) ?? template;
229
+ }
230
+
231
+ /** The request's branch: `request/<template-name>/<app>`, and `/<addon>` after it for an add-on. */
232
+ export function requestBranch(request: Pick<TemplateRequest, "template" | "app"> & Partial<Pick<TemplateRequest, "kind" | "addon">>): string {
233
+ const base = `request/${templateName(request.template)}/${request.app}`;
234
+ return request.addon !== undefined ? `${base}/${request.addon}` : base;
235
+ }
@@ -0,0 +1,176 @@
1
+ /**
2
+ * template.yml, version 1 (#4651, ruling B of #4642): what a template asks
3
+ * for when someone requests an app or an add-on from it. The file sits in
4
+ * the template's signed release; a form shows one field per input, and an
5
+ * agent or a command line reads the same list.
6
+ *
7
+ * Each input has an engine-neutral kind (`string`, `number`, `bool`,
8
+ * `list`, `map`, `object`, with `of` naming a list's or map's element kind).
9
+ * Core checks request values against the kind and never parses an engine's
10
+ * own type syntax; an engine maps the kinds to its types (the terraform
11
+ * lexicon, #4652).
12
+ *
13
+ * In an add-on request, a value `app.<output>` names an output of the app's
14
+ * own module, whatever the input's kind. Core accepts it as is and leaves
15
+ * the engine's renderer to resolve it and refuse an output the module lacks.
16
+ */
17
+
18
+ import schema from "./template.schema.json" with { type: "json" };
19
+ import { parseYAMLDocument, YAMLParseError } from "../yaml";
20
+ import { schemaProblems } from "./validate";
21
+
22
+ /** The template.yml `$schema`, when the file names one. */
23
+ export const TEMPLATE_SPEC_SCHEMA_ID: string = schema.$id;
24
+
25
+ /** The template.yml contract version. */
26
+ export const TEMPLATE_SPEC_CONTRACT = 1;
27
+
28
+ /** A kind whose values are JSON scalars. */
29
+ export type TemplateScalarKind = "string" | "number" | "bool";
30
+
31
+ /** An input's engine-neutral kind. */
32
+ export type TemplateInputKind = TemplateScalarKind | "list" | "map" | "object";
33
+
34
+ /** Every input kind, in the order the schema lists them. */
35
+ export const TEMPLATE_INPUT_KINDS: readonly TemplateInputKind[] = ["string", "number", "bool", "list", "map", "object"];
36
+
37
+ /** One input of a template. */
38
+ export interface TemplateInput {
39
+ name: string;
40
+ kind: TemplateInputKind;
41
+ /** For a list or a map: the kind of each element or value. Absent: any JSON value. */
42
+ of?: TemplateScalarKind;
43
+ /** The form field's label. Absent: the name. */
44
+ label?: string;
45
+ description?: string;
46
+ /** The value a request that gives none takes. */
47
+ default?: unknown;
48
+ /** Absent: true when there is no default. */
49
+ required?: boolean;
50
+ /** A secret, which a request never carries. */
51
+ sensitive?: boolean;
52
+ }
53
+
54
+ /** A parsed template.yml. */
55
+ export interface TemplateSpec {
56
+ $schema?: string;
57
+ contract: 1;
58
+ /** Absent: `app`. */
59
+ kind?: "app" | "addon";
60
+ description: string;
61
+ inputs: TemplateInput[];
62
+ }
63
+
64
+ /** Thrown when a template.yml is not valid, with one line per problem. */
65
+ export class TemplateSpecError extends Error {
66
+ constructor(public readonly problems: string[]) {
67
+ super(`template.yml is not valid: ${problems.join("; ")}`);
68
+ this.name = "TemplateSpecError";
69
+ }
70
+ }
71
+
72
+ /** Whether a request must give `input`: its own `required`, else true when it has no default. */
73
+ export function inputRequired(input: TemplateInput): boolean {
74
+ return input.required ?? !("default" in input);
75
+ }
76
+
77
+ /** The JSON type a value has, as a problem line names it. */
78
+ export function jsonKindOf(value: unknown): string {
79
+ if (value === null) return "null";
80
+ if (Array.isArray(value)) return "list";
81
+ if (typeof value === "boolean") return "bool";
82
+ if (typeof value === "object") return "object";
83
+ return typeof value;
84
+ }
85
+
86
+ const isPlainObject = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
87
+
88
+ function scalarFits(kind: TemplateScalarKind, value: unknown): boolean {
89
+ if (kind === "string") return typeof value === "string";
90
+ if (kind === "number") return typeof value === "number" && Number.isFinite(value);
91
+ return typeof value === "boolean";
92
+ }
93
+
94
+ /** An app-output reference, `app.<output>`, with the output in group 1. */
95
+ export const APP_OUTPUT_REF: RegExp = /^app\.([A-Za-z_][A-Za-z0-9_-]*)$/;
96
+
97
+ /** The output an `app.<output>` value names, or undefined when `value` is not one. */
98
+ export function appOutputRef(value: unknown): string | undefined {
99
+ return typeof value === "string" ? APP_OUTPUT_REF.exec(value)?.[1] : undefined;
100
+ }
101
+
102
+ /** True when `value` is an app-output reference, `app.<output>`. */
103
+ export function isAppOutputRef(value: unknown): value is string {
104
+ return appOutputRef(value) !== undefined;
105
+ }
106
+
107
+ /**
108
+ * Why `value` is not of `input`'s kind, or undefined when it is. A null is
109
+ * never of a kind: a request that wants the default leaves the input out.
110
+ */
111
+ export function inputKindProblem(input: Pick<TemplateInput, "kind" | "of">, value: unknown): string | undefined {
112
+ const want = input.of ? `${input.kind} of ${input.of}` : input.kind;
113
+ const bad = (detail?: string) => `is ${detail ?? jsonKindOf(value)}, and the input is a ${want}`;
114
+ switch (input.kind) {
115
+ case "string":
116
+ case "number":
117
+ case "bool":
118
+ return scalarFits(input.kind, value) ? undefined : bad();
119
+ case "list": {
120
+ if (!Array.isArray(value)) return bad();
121
+ if (!input.of) return undefined;
122
+ const at = value.findIndex((v) => !scalarFits(input.of!, v));
123
+ return at < 0 ? undefined : bad(`a list whose element ${at} is ${jsonKindOf(value[at])}`);
124
+ }
125
+ case "map": {
126
+ if (!isPlainObject(value)) return bad();
127
+ if (!input.of) return undefined;
128
+ const key = Object.keys(value).find((k) => !scalarFits(input.of!, value[k]));
129
+ return key === undefined ? undefined : bad(`a map whose ${JSON.stringify(key)} is ${jsonKindOf(value[key])}`);
130
+ }
131
+ case "object":
132
+ return isPlainObject(value) ? undefined : bad();
133
+ }
134
+ }
135
+
136
+ /**
137
+ * Every problem with a template.yml document, one line each: the schema's,
138
+ * then two inputs with one name, a default that is not of its input's kind,
139
+ * and an input both required and given a default.
140
+ */
141
+ export function templateSpecProblems(doc: unknown): string[] {
142
+ const problems = schemaProblems(TEMPLATE_SPEC_SCHEMA_ID, doc);
143
+ if (problems.length > 0) return problems;
144
+ const spec = doc as TemplateSpec;
145
+ const seen = new Set<string>();
146
+ spec.inputs.forEach((input, i) => {
147
+ const where = `/inputs/${i} (${input.name})`;
148
+ if (seen.has(input.name)) problems.push(`${where} repeats the name ${JSON.stringify(input.name)}`);
149
+ seen.add(input.name);
150
+ if ("default" in input) {
151
+ const p = inputKindProblem(input, input.default);
152
+ if (p) problems.push(`${where} default ${p}`);
153
+ if (input.required === true) problems.push(`${where} is required and has a default; an input with a default is optional`);
154
+ }
155
+ });
156
+ return problems;
157
+ }
158
+
159
+ /**
160
+ * Read a template.yml from its YAML text or its parsed value. Throws
161
+ * {@link TemplateSpecError} when it does not parse or is not valid.
162
+ */
163
+ export function parseTemplateSpec(text: string | unknown): TemplateSpec {
164
+ let doc: unknown = text;
165
+ if (typeof text === "string") {
166
+ try {
167
+ doc = parseYAMLDocument(text);
168
+ } catch (e) {
169
+ if (e instanceof YAMLParseError) throw new TemplateSpecError([`not YAML: ${e.message}`]);
170
+ throw e;
171
+ }
172
+ }
173
+ const problems = templateSpecProblems(doc);
174
+ if (problems.length > 0) throw new TemplateSpecError(problems);
175
+ return doc as TemplateSpec;
176
+ }
@@ -0,0 +1,114 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://intentius.io/chant/schemas/template-request/v1/template.schema.json",
4
+ "title": "chant template",
5
+ "description": "template.yml, version 1 of its contract: what a template asks for when someone requests an app or an add-on from it. It sits in the template's signed release beside the code it describes. A form shows one field per input; an agent and a command line read the same list. Each input has an engine-neutral kind, and each engine maps the kinds to its own types. Readers ignore fields they do not know; a field is only ever added within a version.",
6
+ "type": "object",
7
+ "required": [
8
+ "contract",
9
+ "description",
10
+ "inputs"
11
+ ],
12
+ "properties": {
13
+ "$schema": {
14
+ "const": "https://intentius.io/chant/schemas/template-request/v1/template.schema.json"
15
+ },
16
+ "contract": {
17
+ "const": 1
18
+ },
19
+ "kind": {
20
+ "enum": [
21
+ "app",
22
+ "addon"
23
+ ],
24
+ "default": "app",
25
+ "description": "What a request makes from this template: a new app, or an add-on to an app that already exists."
26
+ },
27
+ "description": {
28
+ "type": "string",
29
+ "minLength": 1,
30
+ "description": "One or two sentences a person reads before requesting it."
31
+ },
32
+ "inputs": {
33
+ "type": "array",
34
+ "description": "The inputs, in the order a form shows them. Names are unique. An add-on request may give any input the string `app.<output>`, naming an output of the app's module, which the engine resolves.",
35
+ "items": {
36
+ "$ref": "#/$defs/input"
37
+ }
38
+ }
39
+ },
40
+ "$defs": {
41
+ "scalarKind": {
42
+ "enum": [
43
+ "string",
44
+ "number",
45
+ "bool"
46
+ ]
47
+ },
48
+ "kind": {
49
+ "description": "An input's engine-neutral kind. string: a JSON string. number: a finite JSON number. bool: true or false. list: a JSON array, each element of kind `of` when given. map: a JSON object, each value of kind `of` when given. object: a JSON object with any fields. An engine maps each kind to one of its own types (Terraform: string, number, bool, list(<of>), map(<of>), and any for object or for a list or map without `of`).",
50
+ "enum": [
51
+ "string",
52
+ "number",
53
+ "bool",
54
+ "list",
55
+ "map",
56
+ "object"
57
+ ]
58
+ },
59
+ "input": {
60
+ "type": "object",
61
+ "required": [
62
+ "name",
63
+ "kind"
64
+ ],
65
+ "properties": {
66
+ "name": {
67
+ "type": "string",
68
+ "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$",
69
+ "description": "The name a request gives the value under, and the variable the engine sets."
70
+ },
71
+ "kind": {
72
+ "$ref": "#/$defs/kind"
73
+ },
74
+ "of": {
75
+ "$ref": "#/$defs/scalarKind",
76
+ "description": "For a list or a map only: the kind of each element or value."
77
+ },
78
+ "label": {
79
+ "type": "string",
80
+ "minLength": 1,
81
+ "description": "The form field's label. Absent: the name."
82
+ },
83
+ "description": {
84
+ "type": "string",
85
+ "description": "Help text shown under the field."
86
+ },
87
+ "default": {
88
+ "description": "The value used when a request gives none. It must be of the input's kind. An input with a default is optional."
89
+ },
90
+ "required": {
91
+ "type": "boolean",
92
+ "description": "Whether a request must give a value. Absent: true when there is no default, false when there is. An input with a default cannot be required."
93
+ },
94
+ "sensitive": {
95
+ "type": "boolean",
96
+ "default": false,
97
+ "description": "A secret. A request never carries it, because the request is written into a pull request; the app reads it from its own secret store."
98
+ }
99
+ },
100
+ "dependentSchemas": {
101
+ "of": {
102
+ "properties": {
103
+ "kind": {
104
+ "enum": [
105
+ "list",
106
+ "map"
107
+ ]
108
+ }
109
+ }
110
+ }
111
+ }
112
+ }
113
+ }
114
+ }
@@ -0,0 +1,28 @@
1
+ /** One Ajv for the template-request/v1 schemas (template.yml and the request), compiled on first use. */
2
+
3
+ import requestSchema from "./template-request.schema.json" with { type: "json" };
4
+ import templateSchema from "./template.schema.json" with { type: "json" };
5
+ import { loadAjv2020 } from "../workspace/ajv2020";
6
+
7
+ type ValidateFn = ((data: unknown) => boolean) & { errors?: { instancePath: string; message?: string }[] | null };
8
+
9
+ interface AjvInstance {
10
+ addSchema(schema: object): unknown;
11
+ getSchema(id: string): unknown;
12
+ }
13
+
14
+ let ajv: AjvInstance | undefined;
15
+
16
+ /** The problems of `doc` against the schema `id`, one line each; empty when it is valid. */
17
+ export function schemaProblems(id: string, doc: unknown): string[] {
18
+ if (!ajv) {
19
+ const Ajv = loadAjv2020();
20
+ const made = new Ajv({ allErrors: true, strict: true }) as unknown as AjvInstance;
21
+ for (const s of [requestSchema, templateSchema]) made.addSchema(s);
22
+ ajv = made;
23
+ }
24
+ const fn = ajv.getSchema(id) as ValidateFn | undefined;
25
+ if (!fn) throw new Error(`no schema ${id}`);
26
+ if (fn(doc)) return [];
27
+ return (fn.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "is not valid"}`);
28
+ }