Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

generate.ts

552 lines19.4 KB

1#!/usr/bin/env node
2​
3import * as NodeRuntime from "@effect/platform-node/NodeRuntime";
4import * as NodeServices from "@effect/platform-node/NodeServices";
5import { make as makeJsonSchemaGenerator } from "@effect/openapi-generator/JsonSchemaGenerator";
6import * as Effect from "effect/Effect";
7import * as FileSystem from "effect/FileSystem";
8import * as Layer from "effect/Layer";
9import * as Logger from "effect/Logger";
10import * as Path from "effect/Path";
11import * as Schema from "effect/Schema";
12import { Command, Flag } from "effect/cli";
13import { FetchHttpClient, HttpClient, HttpClientResponse } from "effect/http";
14import { ChildProcess, ChildProcessSpawner } from "effect/process";
15​
16const V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.3";
17const V1_SCHEMA_RELEASE = "schema-v1.21.0";
18​
19interface GenerateCommandError {
20 readonly _tag: "GenerateCommandError";
21 readonly message: string;
23​
24interface GeneratedPaths {
25 readonly generatedDir: string;
26 readonly upstreamSchemaPath: string;
27 readonly upstreamMetaPath: string;
28 readonly upstreamV1SchemaPath: string;
29 readonly upstreamV1MetaPath: string;
30 readonly schemaOutputPath: string;
31 readonly v1SchemaOutputPath: string;
32 readonly metaOutputPath: string;
34​
35const UpstreamJsonSchemaSchema = Schema.Struct({
36 $defs: Schema.Record(Schema.String, Schema.Json),
37});
38const MetaJsonSchema = Schema.Struct({
39 agentMethods: Schema.Record(Schema.String, Schema.String),
40 clientMethods: Schema.Record(Schema.String, Schema.String),
41 version: Schema.Union([Schema.Number, Schema.String]),
42});
43const encodeAgentMethods = Schema.encodeEffect(
44 Schema.fromJsonString(MetaJsonSchema.fields.agentMethods),
45);
46const encodeClientMethods = Schema.encodeEffect(
47 Schema.fromJsonString(MetaJsonSchema.fields.clientMethods),
48);
49const encodeVersion = Schema.encodeEffect(Schema.fromJsonString(MetaJsonSchema.fields.version));
50​
51const decodeUpstreamSchema = Schema.decodeEffect(Schema.fromJsonString(UpstreamJsonSchemaSchema));
52const decodeMetaJson = Schema.decodeEffect(Schema.fromJsonString(MetaJsonSchema));
53​
54const getGeneratedPaths = Effect.fn("getGeneratedPaths")(function* () {
55 const path = yield* Path.Path;
56 const generatedDir = path.join(import.meta.dirname, "..", "src", "_generated");
57 return {
58 generatedDir,
59 upstreamSchemaPath: path.join(generatedDir, "upstream-schema.json"),
60 upstreamMetaPath: path.join(generatedDir, "upstream-meta.json"),
61 upstreamV1SchemaPath: path.join(generatedDir, "upstream-schema-v1.json"),
62 upstreamV1MetaPath: path.join(generatedDir, "upstream-meta-v1.json"),
63 schemaOutputPath: path.join(generatedDir, "schema.gen.ts"),
64 v1SchemaOutputPath: path.join(generatedDir, "schema-v1.gen.ts"),
65 metaOutputPath: path.join(generatedDir, "meta.gen.ts"),
66 } satisfies GeneratedPaths;
67});
68​
69const ensureGeneratedDir = Effect.fn("ensureGeneratedDir")(function* () {
70 const fs = yield* FileSystem.FileSystem;
71 const { generatedDir } = yield* getGeneratedPaths();
72​
73 yield* fs.makeDirectory(generatedDir, { recursive: true });
74});
75​
76const downloadFile = Effect.fn("downloadFile")(function* (url: string, outputPath: string) {
77 const fs = yield* FileSystem.FileSystem;
78 const path = yield* Path.Path;
79​
80 yield* fs.makeDirectory(path.dirname(outputPath), { recursive: true });
81​
82 const text = yield* HttpClient.get(url).pipe(
83 Effect.flatMap(HttpClientResponse.filterStatusOk),
84 Effect.flatMap((response) => response.text),
85 );
86​
87 yield* fs.writeFileString(outputPath, text);
88});
89​
90const downloadSchemas = Effect.fn("downloadSchemas")(function* (
91 tag: string,
92 paths: { readonly schema: string; readonly meta: string },
93) {
94 const fs = yield* FileSystem.FileSystem;
95 const baseUrl = `https://github.com/agentclientprotocol/agent-client-protocol/releases/download/${tag}`;
96​
97 yield* Effect.all(
98 [
99 downloadFile(`${baseUrl}/schema.unstable.json`, paths.schema),
100 downloadFile(`${baseUrl}/meta.unstable.json`, paths.meta),
101 ],
102 { concurrency: 2 },
103 );
104​
105 yield* Effect.addFinalizer(() =>
106 Effect.all([fs.remove(paths.schema), fs.remove(paths.meta)]).pipe(
107 Effect.ignoreCause({ log: true }),
108 ),
109 );
110});
111​
112const readFileString = Effect.fn("readJsonFile")(function* (filePath: string) {
113 const fs = yield* FileSystem.FileSystem;
114 return yield* fs.readFileString(filePath);
115});
116​
117const writeGeneratedFiles = Effect.fn("writeGeneratedFiles")(function* (
118 schemaOutput: string,
119 v1SchemaOutput: string,
120 metaOutput: string,
121) {
122 const fs = yield* FileSystem.FileSystem;
123 const { metaOutputPath, schemaOutputPath, v1SchemaOutputPath } = yield* getGeneratedPaths();
124​
125 yield* fs.writeFileString(schemaOutputPath, schemaOutput);
126 yield* fs.writeFileString(v1SchemaOutputPath, v1SchemaOutput);
127 yield* fs.writeFileString(metaOutputPath, metaOutput);
128});
129​
130function collectSchemaEntries(
131 chunk: string,
132): ReadonlyArray<{ readonly name: string; readonly code: string }> {
133 const lines = chunk
134 .split("\n")
135 .map((line) => line.trim())
136 .filter((line) => line.length > 0 && !line.startsWith("//"));
137 const entries: Array<{ name: string; code: string }> = [];
138​
139 for (let index = 0; index < lines.length; index += 1) {
140 const typeLine = lines[index];
141 if (!typeLine?.startsWith("export type ")) {
142 continue;
143 }
144​
145 const constLine = lines[index + 1];
146 if (!constLine?.startsWith("export const ")) {
147 throw new Error(`Malformed generator output near: ${typeLine}`);
148 }
149​
150 const match = /^export type ([A-Za-z0-9_]+)/.exec(typeLine);
151 if (!match?.[1]) {
152 throw new Error(`Could not extract schema name from: ${typeLine}`);
153 }
154​
155 entries.push({
156 name: match[1],
157 code: `${typeLine}\n${constLine}`,
158 });
159 index += 1;
160 }
161​
162 return entries;
164​
165function isJsonArray(value: Schema.Json | undefined): value is ReadonlyArray<Schema.Json> {
166 return Array.isArray(value);
168​
169// Keywords whose values are literal JSON data, not schemas.
170const DATA_KEYWORDS = new Set(["const", "default", "enum", "examples"]);
171​
172// Applies `transform` to every subschema of a schema object. `properties` maps names to
173// schemas, so its keys stay property names: ACP has properties named `anyOf`, `oneOf`, and
174// `type` that must not be read as keywords. Literal data values are left untouched.
175function mapSubschemas(
176 value: { readonly [key: string]: Schema.Json },
177 transform: (schema: Schema.Json) => Schema.Json,
178): Record<string, Schema.Json> {
179 return Object.fromEntries(
180 Object.entries(value).map(([key, child]) => {
181 if (DATA_KEYWORDS.has(key)) return [key, child];
182 if (
183 key === "properties" &&
184 child !== null &&
185 typeof child === "object" &&
186 !isJsonArray(child)
187 ) {
188 return [
189 key,
190 Object.fromEntries(
191 Object.entries(child).map(([name, schema]) => [name, transform(schema)]),
192 ),
193 ];
194 }
195 return [key, isJsonArray(child) ? child.map(transform) : transform(child)];
196 }),
197 );
199​
200function normalizeSchemaKeywords(value: Schema.Json): Schema.Json {
201 if (isJsonArray(value)) {
202 return value.map(normalizeSchemaKeywords);
203 }
204 if (value === null || typeof value !== "object") {
205 return value;
206 }
207​
208 const normalizedObject = mapSubschemas(value, normalizeSchemaKeywords);
209 // ACP's forward-compatible variants exclude known discriminator values.
210 // The Effect generator does not support `not`; express this exact exclusion
211 // as a string pattern while preserving validation of the known variants.
212 if (normalizedObject.not !== undefined) {
213 const exclusion = normalizedObject.not;
214 if (
215 exclusion === null ||
216 typeof exclusion !== "object" ||
217 isJsonArray(exclusion) ||
218 !isJsonArray(exclusion.anyOf)
219 ) {
220 throw new Error("Unsupported ACP schema exclusion");
221 }
222 const excluded = exclusion.anyOf.map((variant) => {
223 if (variant === null || typeof variant !== "object" || isJsonArray(variant))
224 throw new Error("Invalid ACP excluded variant");
225 const properties = variant.properties;
226 if (properties === null || typeof properties !== "object" || isJsonArray(properties))
227 throw new Error("Invalid ACP excluded properties");
228 const entries = Object.entries(properties);
229 const entry = entries[0];
230 if (entries.length !== 1 || entry === undefined) throw new Error("Invalid ACP discriminator");
231 const [key, schema] = entry;
232 if (
233 schema === null ||
234 typeof schema !== "object" ||
235 isJsonArray(schema) ||
236 typeof schema.const !== "string"
237 )
238 throw new Error("Invalid ACP discriminator value");
239 return { key, value: schema.const };
240 });
241 const discriminator = excluded[0]?.key;
242 const properties = normalizedObject.properties;
243 if (
244 discriminator === undefined ||
245 excluded.some((entry) => entry.key !== discriminator) ||
246 properties === null ||
247 typeof properties !== "object" ||
248 isJsonArray(properties)
249 )
250 throw new Error("Unsupported ACP discriminator exclusion");
251 const property = properties[discriminator];
252 if (property === null || typeof property !== "object" || isJsonArray(property))
253 throw new Error("Missing ACP discriminator property");
254 normalizedObject.properties = {
255 ...properties,
256 [discriminator]: {
257 ...property,
258 pattern: `^(?!(?:${excluded.map(({ value }) => RegExp.escape(value)).join("|")})$)[\\s\\S]*$`,
259 },
260 };
261 delete normalizedObject.not;
262 }
263 if (normalizedObject.unevaluatedProperties !== undefined) {
264 if (normalizedObject.unevaluatedProperties !== true)
265 throw new Error("Unsupported ACP unevaluated properties constraint");
266 normalizedObject.additionalProperties = true;
267 delete normalizedObject.unevaluatedProperties;
268 }
269 if (isJsonArray(normalizedObject.oneOf)) {
270 const discriminator = normalizedObject.discriminator;
271 const propertyName =
272 discriminator !== null && typeof discriminator === "object" && !isJsonArray(discriminator)
273 ? discriminator.propertyName
274 : undefined;
275 const values = normalizedObject.oneOf.map((entry) => {
276 if (entry === null || typeof entry !== "object" || isJsonArray(entry)) return undefined;
277 if (typeof entry.const === "string") return entry.const;
278 const properties = entry.properties;
279 if (
280 typeof propertyName !== "string" ||
281 properties === null ||
282 typeof properties !== "object" ||
283 isJsonArray(properties)
284 )
285 return undefined;
286 const property = properties[propertyName];
287 return property !== null && typeof property === "object" && !isJsonArray(property)
288 ? property.const
289 : undefined;
290 });
291 if (
292 values.every((entry) => typeof entry === "string") &&
293 new Set(values).size === values.length
294 ) {
295 normalizedObject.anyOf = normalizedObject.oneOf;
296 delete normalizedObject.oneOf;
297 }
298 }
299 const typeValue = normalizedObject.type;
300​
301 if (!isJsonArray(typeValue)) {
302 return normalizedObject;
303 }
304​
305 const normalizedTypes = typeValue.filter((entry): entry is string => typeof entry === "string");
306 if (normalizedTypes.length !== typeValue.length || !normalizedTypes.includes("null")) {
307 return normalizedObject;
308 }
309​
310 const nonNullTypes = normalizedTypes.filter((entry) => entry !== "null");
311 if (nonNullTypes.length !== 1) {
312 return normalizedObject;
313 }
314 const nonNullType = nonNullTypes[0]!;
315​
316 const nextObject: Record<string, Schema.Json> = {};
317 for (const [key, child] of Object.entries(normalizedObject)) {
318 if (key !== "type") {
319 nextObject[key] = child;
320 }
321 }
322​
323 return {
324 anyOf: [
325 {
326 ...nextObject,
327 type: nonNullType,
328 },
329 { type: "null" },
330 ],
331 };
333​
334const isAnnotationKeyword = (key: string): boolean =>
335 ["description", "title", "$comment", "default", "examples", "discriminator"].includes(key) ||
336 key.startsWith("x-");
337​
338// Distribute object intersections over unions before handing schemas to Effect.
339// ACP uses sibling `properties`/`anyOf` and `allOf` references for elicitation scopes.
340function flattenCompositions(
341 value: Schema.Json,
342 definitions: Readonly<Record<string, Schema.Json>>,
343): Schema.Json {
344 if (isJsonArray(value)) return value.map((child) => flattenCompositions(child, definitions));
345 if (value === null || typeof value !== "object") return value;
346 const normalized = mapSubschemas(value, (child) => flattenCompositions(child, definitions));
347 const { allOf, anyOf, ...base } = normalized;
348 const merge = (left: Schema.Json, right: Schema.Json): Schema.Json => {
349 if (
350 left === null ||
351 typeof left !== "object" ||
352 isJsonArray(left) ||
353 right === null ||
354 typeof right !== "object" ||
355 isJsonArray(right)
356 )
357 throw new Error("Unsupported ACP schema intersection");
358 if (typeof right.$ref === "string") {
359 // Keep references when the sibling only describes the referenced schema.
360 // Inlining these repeats entire protocol unions in every request schema.
361 if (Object.keys(left).every(isAnnotationKeyword)) return { ...right, ...left };
362 const target = definitions[right.$ref.replace("#/$defs/", "")];
363 if (target === undefined) throw new Error(`Missing ACP definition ${right.$ref}`);
364 return merge(left, flattenCompositions(normalizeSchemaKeywords(target), definitions));
365 }
366 if (isJsonArray(left.anyOf)) return { anyOf: left.anyOf.map((branch) => merge(branch, right)) };
367 if (isJsonArray(right.anyOf))
368 return { anyOf: right.anyOf.map((branch) => merge(left, branch)) };
369 for (const key of Object.keys(left)) {
370 if (key === "properties" || key === "required" || isAnnotationKeyword(key)) continue;
371 if (right[key] !== undefined && JSON.stringify(left[key]) !== JSON.stringify(right[key])) {
372 throw new Error(`Unsupported conflicting ACP schema constraint: ${key}`);
373 }
374 }
375 const result = { ...left, ...right };
376 if (
377 left.properties &&
378 right.properties &&
379 typeof left.properties === "object" &&
380 !isJsonArray(left.properties) &&
381 typeof right.properties === "object" &&
382 !isJsonArray(right.properties)
383 ) {
384 for (const key of Object.keys(left.properties)) {
385 if (
386 right.properties[key] !== undefined &&
387 JSON.stringify(left.properties[key]) !== JSON.stringify(right.properties[key])
388 ) {
389 throw new Error(`Unsupported overlapping ACP schema property: ${key}`);
390 }
391 }
392 result.properties = { ...left.properties, ...right.properties };
393 }
394 if (isJsonArray(left.required) || isJsonArray(right.required)) {
395 result.required = [
396 ...new Set([
397 ...(isJsonArray(left.required) ? left.required : []),
398 ...(isJsonArray(right.required) ? right.required : []),
399 ]),
400 ];
401 }
402 return result;
403 };
404 let combined: Schema.Json = base;
405 if (isJsonArray(allOf)) for (const part of allOf) combined = merge(combined, part);
406 if (isJsonArray(anyOf) && !isJsonArray(allOf) && Object.keys(base).every(isAnnotationKeyword)) {
407 return { ...base, anyOf };
408 }
409 return isJsonArray(anyOf) ? merge(combined, { anyOf }) : combined;
411​
412function generateSchemaOutput(
413 upstreamSchema: { readonly $defs: Readonly<Record<string, Schema.Json>> },
414 release: string,
415): { readonly output: string; readonly count: number } {
416 const normalizedDefinitions = Object.fromEntries(
417 Object.entries(upstreamSchema.$defs).map(([name, schema]) => [
418 name,
419 flattenCompositions(normalizeSchemaKeywords(schema), upstreamSchema.$defs),
420 ]),
421 );
422 const sortedEntries = Object.entries(normalizedDefinitions).toSorted(([left], [right]) =>
423 left.localeCompare(right),
424 );
425 const generatedEntries = new Map<string, string>();
426 const generator = makeJsonSchemaGenerator();
427​
428 for (const [name, schema] of sortedEntries) {
429 generator.addSchema(name, schema as never);
430 }
431​
432 const generated = generator.generate("openapi-3.1", normalizedDefinitions as never, false).trim();
433 if (generated.length > 0) {
434 for (const entry of collectSchemaEntries(generated)) {
435 if (!generatedEntries.has(entry.name)) {
436 generatedEntries.set(entry.name, entry.code);
437 }
438 }
439 }
440​
441 return {
442 output: [
443 "// This file is generated by the effect-acp package. Do not edit manually.",
444 `// Current ACP schema release: ${release}`,
445 "",
446 'import * as Schema from "effect/Schema";',
447 "",
448 [...generatedEntries.values()].join("\n\n"),
449 "",
450 ].join("\n"),
451 count: generatedEntries.size,
452 };
454​
455const generateSchemas = Effect.fn("generateSchemas")(function* (skipDownload: boolean) {
456 const { upstreamMetaPath, upstreamSchemaPath, upstreamV1MetaPath, upstreamV1SchemaPath } =
457 yield* getGeneratedPaths();
458​
459 yield* ensureGeneratedDir();
460​
461 if (!skipDownload) {
462 yield* Effect.log(
463 `Downloading ACP schema assets for ${V2_SCHEMA_RELEASE} and ${V1_SCHEMA_RELEASE}`,
464 );
465 yield* Effect.all(
466 [
467 downloadSchemas(V2_SCHEMA_RELEASE, {
468 schema: upstreamSchemaPath,
469 meta: upstreamMetaPath,
470 }),
471 downloadSchemas(V1_SCHEMA_RELEASE, {
472 schema: upstreamV1SchemaPath,
473 meta: upstreamV1MetaPath,
474 }),
475 ],
476 { concurrency: 2 },
477 );
478 }
479​
480 const upstreamSchema = yield* readFileString(upstreamSchemaPath).pipe(
481 Effect.flatMap(decodeUpstreamSchema),
482 );
483 const upstreamV1Schema = yield* readFileString(upstreamV1SchemaPath).pipe(
484 Effect.flatMap(decodeUpstreamSchema),
485 );
486 const upstreamMeta = yield* readFileString(upstreamMetaPath).pipe(Effect.flatMap(decodeMetaJson));
487 const v2Schema = generateSchemaOutput(upstreamSchema, V2_SCHEMA_RELEASE);
488 const v1Schema = generateSchemaOutput(upstreamV1Schema, V1_SCHEMA_RELEASE);
489​
490 const prelude = [
491 `// This file is generated by the effect-acp package. Do not edit manually.`,
492 `// Current ACP schema release: ${V2_SCHEMA_RELEASE}`,
493 "",
494 ];
495​
496 const metaOutput = [
497 ...prelude,
498 `export const AGENT_METHODS = ${yield* encodeAgentMethods(upstreamMeta.agentMethods)} as const;`,
499 "",
500 `export const CLIENT_METHODS = ${yield* encodeClientMethods(upstreamMeta.clientMethods)} as const;`,
501 "",
502 `export const PROTOCOL_VERSION = ${yield* encodeVersion(upstreamMeta.version)} as const;`,
503 "",
504 ].join("\n");
505​
506 yield* writeGeneratedFiles(v2Schema.output, v1Schema.output, metaOutput);
507 yield* Effect.log(
508 `Generated ${v2Schema.count} ACP v2 schemas and ${v1Schema.count} ACP v1 compatibility schemas`,
509 );
510​
511 const { generatedDir } = yield* getGeneratedPaths();
512 yield* Effect.service(ChildProcessSpawner.ChildProcessSpawner).pipe(
513 Effect.flatMap((spawner) =>
514 spawner.spawn(
515 ChildProcess.make("pnpm", ["exec", "vp", "fmt", generatedDir], {
516 stdin: "ignore",
517 stdout: "inherit",
518 stderr: "inherit",
519 }),
520 ),
521 ),
522 Effect.flatMap((child) => child.exitCode),
523 Effect.tap((code) =>
524 code === 0
525 ? Effect.void
526 : Effect.fail<GenerateCommandError>({
527 _tag: "GenerateCommandError",
528 message: `oxfmt failed with exit code ${code}`,
529 }),
530 ),
531 );
532});
533​
534const generateCommand = Command.make(
535 "generate",
536 {
537 skipDownload: Flag.Boolean("skip-download").pipe(Flag.withDefault(false)),
538 },
539 ({ skipDownload }) => generateSchemas(skipDownload),
540).pipe(Command.withDescription("Generate Effect ACP schemas from the pinned ACP release assets."));
541​
542const layerRuntime = Layer.mergeAll(
543 Logger.layer([Logger.consolePretty()]),
544 NodeServices.layer,
545 FetchHttpClient.layer,
546);
547​
548Command.run(generateCommand, { version: "0.0.0" }).pipe(
549 Effect.scoped,
550 Effect.provide(layerRuntime),
551 NodeRuntime.runMain,
552);