@apollo/client-ai-apps 0.6.0 → 0.6.2

package/dist/vite/apolloClientAiApps.js

@@ -2,20 +2,25 @@ import { defaultClientConditions, } from "vite";
 import { createHash } from "node:crypto";
 import path from "node:path";
 import fs from "node:fs";
+import * as recast from "recast";
+import typescriptParser from "recast/parsers/typescript.js";
 import { ApolloClient, ApolloLink } from "@apollo/client";
 import { InMemoryCache } from "@apollo/client";
+import { equal } from "@wry/equality";
 import { gqlPluckFromCodeStringSync } from "@graphql-tools/graphql-tag-pluck";
 import { glob } from "glob";
 import { print } from "@apollo/client/utilities";
 import { removeDirectivesFromDocument } from "@apollo/client/utilities/internal";
 import { of } from "rxjs";
-import { Kind, OperationTypeNode, parse } from "graphql";
+import { Kind, OperationTypeNode, parse, visit } from "graphql";
 import { getArgumentValue, getDirectiveArgument, getTypeName, maybeGetArgumentValue, } from "./utilities/graphql.js";
 import { invariant } from "../utilities/invariant.js";
 import { explorer } from "./utilities/config.js";
 import { ApolloClientAiAppsConfigSchema } from "../config/schema.js";
 import { z } from "zod";
 import { createFragmentRegistry } from "@apollo/client/cache";
+import { buildImportStatement, buildPropertySignature, buildKeywordLiteral, printRecast, } from "./utilities/recast.js";
+const b = recast.types.builders;
 const root = process.cwd();
 const VALID_TARGETS = ["openai", "mcp"];
 function isValidTarget(target) {
@@ -28,10 +33,208 @@ export function devTarget(target) {
     invariant(target === undefined || isValidTarget(target), `devTarget '${target}' is not a valid dev target. Must be one of ${VALID_TARGETS.join(", ")}.`);
     return target;
 }
+function md5(contents) {
+    return createHash("md5").update(contents).digest("hex");
+}
+/**
+ * Builds the AST for the comment used at the top of a generated file from this
+ * plugin.
+ *
+ * @remarks
+ * This comment informs users that generated files from this plugin should not
+ * be edited since it is autogenerated by this plugin.
+ */
+function buildHeaderComment() {
+    return b.commentLine(" This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.", true, false);
+}
+/**
+ * Builds the `@apollo/client-ai-apps` ambient module declaration for the
+ * `register.d.ts` file.
+ *
+ * @param registerInterfaceBody - The interface body for the `Register`
+ * interface
+ *
+ * @example
+ * ```ts
+ * buildAmbientModuleDeclaration(interfaceBody);
+ * // =>
+ * // declare namespace "@apollo/client-ai-apps" {
+ * //   interface Register {
+ * //     // ...interfaceBody
+ * //   }
+ * // }
+ * ```
+ */
+function buildAmbientModuleDeclaration(registerInterfaceBody) {
+    const interfaceDeclaration = b.tsInterfaceDeclaration(b.identifier("Register"), b.tsInterfaceBody(registerInterfaceBody));
+    const moduleDeclaration = b.tsModuleDeclaration(b.stringLiteral("@apollo/client-ai-apps"), b.tsModuleBlock([interfaceDeclaration]));
+    moduleDeclaration.declare = true;
+    return moduleDeclaration;
+}
+/**
+ * Gets the variables type name for an operation. GraphQL Codegen creates
+ * variables types with the combination of operationName + operationType +
+ * "Variables"
+ *
+ * @example
+ * ```ts
+ * getVariablesTypeName({ name: "GetProduct", type: "query" });
+ * // => "GetProductQueryVariables"
+ * ````
+ */
+function getVariablesTypeName(operation) {
+    const { name, type } = operation;
+    return `${name}${type.charAt(0).toUpperCase()}${type.slice(1)}Variables`;
+}
+/**
+ * Returns the code string written to the `.apollo-client-ai-apps/types/register.d.ts` files
+ * for a given set of operations.
+ */
+function getRegisteredTypeContents({ operations, schema, flagSchemaBuildError = false, }) {
+    if (flagSchemaBuildError) {
+        const message = `[@apollo/client-ai-apps/vite]: There was an error building generated types. See the vite build output for more details.\n\n${flagSchemaBuildError.message}`;
+        const importBaseStatement = buildImportStatement([], "@apollo/client-ai-apps");
+        importBaseStatement.comments = [buildHeaderComment()];
+        const typeAnnotation = b.tsLiteralType(b.stringLiteral(message));
+        return printRecast(b.program([
+            importBaseStatement,
+            buildAmbientModuleDeclaration([
+                buildPropertySignature("toolName", typeAnnotation),
+                buildPropertySignature("toolInputs", b.tsTypeLiteral([buildPropertySignature(message, typeAnnotation)])),
+            ]),
+        ]));
+    }
+    const toolNames = operations.flatMap((op) => op.tools.map((t) => t.name));
+    if (toolNames.length === 0) {
+        const emptyExport = b.exportNamedDeclaration(null);
+        emptyExport.comments = [buildHeaderComment()];
+        return printRecast(b.program([emptyExport]));
+    }
+    const importBaseStatement = buildImportStatement([], "@apollo/client-ai-apps");
+    importBaseStatement.comments = [buildHeaderComment()];
+    const toolNameProp = buildPropertySignature("toolName", b.tsUnionType(toolNames.map((n) => b.tsLiteralType(b.stringLiteral(n)))));
+    if (!schema) {
+        return printRecast(b.program([
+            importBaseStatement,
+            buildAmbientModuleDeclaration([toolNameProp]),
+        ]));
+    }
+    const importedVariableTypes = new Set();
+    const toolInputsValue = [];
+    for (const operation of operations) {
+        const variablesTypeName = getVariablesTypeName(operation);
+        if (operation.tools.length) {
+            importedVariableTypes.add(variablesTypeName);
+        }
+        for (const tool of operation.tools) {
+            const variablesTypeRef = b.tsTypeReference(b.identifier(variablesTypeName));
+            let typeExpression = variablesTypeRef;
+            if (tool.extraInputs?.length) {
+                const extraInputsType = tool.extraInputs.map((ei) => {
+                    return buildPropertySignature(ei.name, buildKeywordLiteral(ei.type), true);
+                });
+                typeExpression = b.tsIntersectionType([
+                    variablesTypeRef,
+                    b.tsTypeLiteral(extraInputsType),
+                ]);
+            }
+            toolInputsValue.push(buildPropertySignature(tool.name, typeExpression));
+        }
+    }
+    return printRecast(b.program([
+        importBaseStatement,
+        buildImportStatement(Array.from(importedVariableTypes), "./operation-types.js", "type"),
+        buildAmbientModuleDeclaration([
+            toolNameProp,
+            buildPropertySignature("toolInputs", b.tsTypeLiteral(toolInputsValue)),
+        ]),
+    ]));
+}
+/**
+ * Generates and returns the code string written to the
+ * `.apollo-client-ai-apps/types/operation-types.d.ts` file. Uses GraphQL
+ * Codegen to introspect the given schema and extract variable types.
+ */
+async function generateOperationTypes(schema, documents) {
+    const { generate } = await import("@graphql-codegen/cli");
+    if (documents.length === 0) {
+        return `// Auto-generated by @apollo/client-ai-apps. Do not edit manually.\nexport {};\n`;
+    }
+    const output = await generate({
+        schema,
+        documents,
+        generates: {
+            "operation-types.d.ts": {
+                plugins: ["typescript", "typescript-operations"],
+                config: {
+                    nonOptionalTypename: true,
+                    skipTypeNameForRoot: true,
+                },
+            },
+        },
+        silent: true,
+    }, false);
+    const content = output[0]
+        .content;
+    return `// Auto-generated by @apollo/client-ai-apps. Do not edit manually.\n${content}`;
+}
+/**
+ * Gets the name of an exported type (e.g. `export type x`) from a TypeScript
+ * AST statement.
+ */
+function getExportedTypeAliasName(statement) {
+    if (statement.type !== "ExportNamedDeclaration")
+        return;
+    const declaration = statement.declaration;
+    if (!declaration || declaration.type !== "TSTypeAliasDeclaration")
+        return;
+    const alias = declaration;
+    return typeof alias.id.name === "string" ? alias.id.name : undefined;
+}
+/**
+ * Removes all non-`*Variables` types from the `operation-types.d.ts` file.
+ * The `typescript` and `typescript-operations` codegen plugins add full schema
+ * types and operation types. This function ensures those unused types are
+ * removed.
+ */
+function filterOperationTypes(content, rootTypeNames) {
+    const ast = recast.parse(content, { parser: typescriptParser });
+    const statements = ast.program.body;
+    const typeMap = new Map();
+    for (const statement of statements) {
+        const name = getExportedTypeAliasName(statement);
+        if (name) {
+            typeMap.set(name, statement
+                .declaration);
+        }
+    }
+    const reachable = new Set(rootTypeNames);
+    const queue = Array.from(rootTypeNames);
+    while (queue.length > 0) {
+        const name = queue.shift();
+        const node = typeMap.get(name);
+        if (!node)
+            continue;
+        recast.visit(node, {
+            visitTSTypeReference(path) {
+                const typeName = path.value.typeName?.name;
+                if (typeName && !reachable.has(typeName)) {
+                    reachable.add(typeName);
+                    queue.push(typeName);
+                }
+                this.traverse(path);
+            },
+        });
+    }
+    ast.program.body = statements.filter((statement) => {
+        const name = getExportedTypeAliasName(statement);
+        return name === undefined || reachable.has(name);
+    });
+    return printRecast(ast);
+}
 export function apolloClientAiApps(options) {
     const targets = Array.from(new Set(options.targets));
-    const { devTarget = targets.length === 1 ? targets[0] : undefined, appsOutDir, } = options;
-    const cache = new Map();
+    const { devTarget = targets.length === 1 ? targets[0] : undefined, appsOutDir, schema, } = options;
     let config;
     const fragments = createFragmentRegistry();
     invariant(Array.isArray(targets) && targets.length > 0, "The `targets` option must be a non-empty array");
@@ -41,30 +244,15 @@ export function apolloClientAiApps(options) {
         cache: new InMemoryCache({ fragments }),
         link: processQueryLink,
     });
-    async function processFile(file) {
-        const code = fs.readFileSync(file, "utf-8");
-        if (!code.includes("gql"))
-            return;
-        const fileHash = createHash("md5").update(code).digest("hex");
-        if (cache.get(file)?.hash === fileHash)
-            return;
-        const sources = gqlPluckFromCodeStringSync(file, code, {
-            modules: [
-                { name: "graphql-tag", identifier: "gql" },
-                { name: "@apollo/client", identifier: "gql" },
-            ],
-        }).map((source) => parse(source.body));
-        fragments.register(...sources);
-        cache.set(file, {
-            file: file,
-            hash: fileHash,
-            sources,
-        });
+    let sources = [];
+    function recomputeSources(cache) {
+        sources = Array.from(cache.values()).flatMap((entry) => entry.sources);
     }
-    async function generateManifest(environment) {
-        const appsConfig = await getAppsConfig();
-        const sources = Array.from(cache.values()).flatMap((entry) => entry.sources);
-        const operations = [];
+    async function getManifestOperations() {
+        if (sources === getManifestOperations.cache.sources) {
+            return getManifestOperations.cache.manifestOperations;
+        }
+        const manifestOperations = [];
         for (const source of sources) {
             const operationDef = source.definitions.find((d) => d.kind === Kind.OPERATION_DEFINITION);
             if (!operationDef)
@@ -75,7 +263,7 @@ export function apolloClientAiApps(options) {
                         query: source,
                         fetchPolicy: "no-cache",
                     });
-                    operations.push(result.data);
+                    manifestOperations.push(result.data);
                     break;
                 }
                 case OperationTypeNode.MUTATION: {
@@ -83,13 +271,46 @@ export function apolloClientAiApps(options) {
                         mutation: source,
                         fetchPolicy: "no-cache",
                     });
-                    operations.push(result.data);
+                    manifestOperations.push(result.data);
                     break;
                 }
                 default:
                     throw new Error(`Found unsupported operation type '${operationDef.operation}'. Only queries and mutations are supported.`);
             }
         }
+        getManifestOperations.cache = { sources, manifestOperations };
+        return manifestOperations;
+    }
+    getManifestOperations.cache = {
+        sources,
+        manifestOperations: [],
+    };
+    async function processFile(file) {
+        const code = fs.readFileSync(file, "utf-8");
+        if (!code.includes("gql"))
+            return;
+        const fileHash = md5(code);
+        if (processFile.cache.get(file)?.hash === fileHash)
+            return;
+        const sources = gqlPluckFromCodeStringSync(file, code, {
+            modules: [
+                { name: "graphql-tag", identifier: "gql" },
+                { name: "@apollo/client", identifier: "gql" },
+            ],
+        }).map((source) => parse(source.body));
+        const previousSources = processFile.cache.get(file)?.sources;
+        if (previousSources && equal(sources, previousSources)) {
+            processFile.cache.set(file, { hash: fileHash, sources: previousSources });
+            return;
+        }
+        fragments.register(...sources);
+        processFile.cache.set(file, { hash: fileHash, sources });
+        recomputeSources(processFile.cache);
+    }
+    processFile.cache = new Map();
+    async function generateManifest() {
+        const appsConfig = await getAppsConfig();
+        const operations = await getManifestOperations();
         invariant(operations.filter((o) => o.prefetch).length <= 1, "Found multiple operations marked as `@prefetch`. You can only mark 1 operation with `@prefetch`.");
         function getBuildResourceForTarget(target) {
             const entryPoint = getResourceFromConfig(appsConfig, config.mode, target);
@@ -137,14 +358,54 @@ export function apolloClientAiApps(options) {
         if (isNonEmptyObject(appsConfig.labels)) {
             manifest.labels = appsConfig.labels;
         }
-        const outDir = path.join(appsOutDir, appName);
+        const manifestContents = JSON.stringify(manifest);
         // Always write to build directory so the MCP server picks it up
-        const dest = path.resolve(root, outDir, ".application-manifest.json");
-        fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, JSON.stringify(manifest));
+        writeFileSync(path.resolve(root, appsOutDir, appName, ".application-manifest.json"), manifestContents);
         // Always write to the dev location so that the app can bundle the manifest content
-        fs.writeFileSync(".application-manifest.json", JSON.stringify(manifest));
+        writeFileSync(".application-manifest.json", manifestContents);
+        const manifestTypesFilepath = ".application-manifest.d.json.ts";
+        if (!fs.existsSync(manifestTypesFilepath)) {
+            const manifestImport = b.importDeclaration([b.importSpecifier(b.identifier("ApplicationManifest"))], b.stringLiteral("@apollo/client-ai-apps"), "type");
+            const manifestId = b.identifier("manifest");
+            manifestId.typeAnnotation = b.tsTypeAnnotation(b.tsTypeReference(b.identifier("ApplicationManifest"), null));
+            const manifestDeclaration = b.variableDeclaration("const", [
+                b.variableDeclarator(manifestId, null),
+            ]);
+            manifestDeclaration.declare = true;
+            const exportDefault = b.exportDefaultDeclaration(b.identifier("manifest"));
+            const content = printRecast(b.program([manifestImport, manifestDeclaration, exportDefault]));
+            writeFileSync(manifestTypesFilepath, content);
+        }
+    }
+    async function generateTypesFiles() {
+        let flagSchemaBuildError = false;
+        const operations = await getManifestOperations();
+        if (operations === generateTypesFiles.cache) {
+            return;
+        }
+        generateTypesFiles.cache = operations;
+        if (schema) {
+            try {
+                const opTypesContent = await generateOperationTypes(schema, operations.map((op) => op.body));
+                const rootTypeNames = new Set(operations.flatMap((op) => op.tools.length > 0 ? [getVariablesTypeName(op)] : []));
+                writeFileSync(path.resolve(root, ".apollo-client-ai-apps/types/operation-types.d.ts"), filterOperationTypes(opTypesContent, rootTypeNames), { cache: true });
+            }
+            catch (e) {
+                if (config.command === "build") {
+                    throw e;
+                }
+                flagSchemaBuildError = e;
+                console.error("[@apollo/client-ai-apps/vite]:", e);
+            }
+        }
+        const typesFileContents = getRegisteredTypeContents({
+            operations,
+            schema,
+            flagSchemaBuildError,
+        });
+        writeFileSync(path.resolve(root, ".apollo-client-ai-apps/types/register.d.ts"), typesFileContents, { cache: true });
     }
+    generateTypesFiles.cache = [];
     return {
         name: "@apollo/client-ai-apps/vite",
         async buildStart() {
@@ -156,13 +417,13 @@ export function apolloClientAiApps(options) {
             }
             // We don't want to do this here on builds cause it just gets overwritten anyways. We'll call it on writeBundle instead.
             if (config.command === "serve") {
-                await generateManifest(this.environment);
+                await Promise.all([generateManifest(), generateTypesFiles()]);
             }
         },
         configResolved(resolvedConfig) {
             config = resolvedConfig;
         },
-        async configEnvironment(name, { build }) {
+        async configEnvironment(name) {
             if (!targets.includes(name))
                 return;
             const appsConfig = await getAppsConfig();
@@ -186,7 +447,7 @@ export function apolloClientAiApps(options) {
                 }
                 else if (file.match(/\.(jsx?|tsx?)$/)) {
                     await processFile(file);
-                    await generateManifest();
+                    await Promise.all([generateManifest(), generateTypesFiles()]);
                 }
             });
         },
@@ -238,12 +499,12 @@ export function apolloClientAiApps(options) {
                 .replace(/(src=["'])\/([^"']+)/gi, `$1${baseUrl}/$2`));
         },
         async writeBundle() {
-            await generateManifest(this.environment);
+            await Promise.all([generateManifest(), generateTypesFiles()]);
         },
     };
 }
 const processQueryLink = new ApolloLink((operation) => {
-    const body = print(removeManifestDirectives(sortTopLevelDefinitions(operation.query)));
+    const body = print(removeOperationDescription(removeManifestDirectives(sortTopLevelDefinitions(operation.query))));
     const name = operation.operationName;
     const definition = operation.query.definitions.find((d) => d.kind === "OperationDefinition");
     // Use `operation.query` so that the error reflects the end-user defined
@@ -258,12 +519,31 @@ const processQueryLink = new ApolloLink((operation) => {
     const id = createHash("sha256").update(body).digest("hex");
     // TODO: For now, you can only have 1 operation marked as prefetch. In the future, we'll likely support more than 1, and the "prefetchId" will be defined on the `@prefetch` itself as an argument
     const prefetchID = prefetch ? "__anonymous" : undefined;
-    const tools = directives
-        ?.filter((d) => d.name.value === "tool")
-        .map((directive) => {
+    const toolDirectives = directives?.filter((d) => d.name.value === "tool") ?? [];
+    const tools = toolDirectives.map((directive) => {
+        const nameArg = getDirectiveArgument("name", directive);
+        const descriptionArg = getDirectiveArgument("description", directive);
+        let name;
+        if (nameArg) {
+            name = getArgumentValue(nameArg, Kind.STRING);
+        }
+        else {
+            invariant(toolDirectives.length === 1, `Operations with multiple @tool directives must provide a 'name' argument on each @tool`);
+            invariant(definition.name?.value, `Anonymous operations cannot use @tool without providing a 'name' argument`);
+            name = definition.name.value;
+        }
+        let description;
+        if (descriptionArg) {
+            description = getArgumentValue(descriptionArg, Kind.STRING);
+        }
+        else {
+            invariant(toolDirectives.length === 1, `Operations with multiple @tool directives must provide a 'description' argument on each @tool`);
+            invariant(definition.description?.value, `Operations using @tool without a 'description' argument must have a description on the operation definition`);
+            description = definition.description.value;
+        }
         const result = ToolDirectiveSchema.safeParse({
-            name: getArgumentValue(getDirectiveArgument("name", directive, { required: true }), Kind.STRING),
-            description: getArgumentValue(getDirectiveArgument("description", directive, { required: true }), Kind.STRING),
+            name,
+            description,
             extraInputs: maybeGetArgumentValue(getDirectiveArgument("extraInputs", directive), Kind.LIST),
             labels: maybeGetArgumentValue(getDirectiveArgument("labels", directive), Kind.OBJECT),
         });
@@ -278,6 +558,13 @@ const processQueryLink = new ApolloLink((operation) => {
         data: { id, name, type, body, variables, prefetch, prefetchID, tools },
     });
 });
+function removeOperationDescription(doc) {
+    return visit(doc, {
+        OperationDefinition(node) {
+            return { ...node, description: undefined };
+        },
+    });
+}
 function removeManifestDirectives(doc) {
     return removeDirectivesFromDocument([{ name: "prefetch" }, { name: "tool" }], doc);
 }
@@ -352,6 +639,22 @@ readPackageJson.cache = undefined;
 readPackageJson.resetCache = () => {
     readPackageJson.cache = undefined;
 };
+function writeFileSync(filepath, content, options = {}) {
+    function writeFile() {
+        fs.mkdirSync(path.dirname(filepath), { recursive: true });
+        fs.writeFileSync(filepath, content, "utf-8");
+    }
+    if (!options.cache) {
+        return writeFile();
+    }
+    const hash = md5(content);
+    const cachedHash = writeFileSync.cache.get(filepath);
+    if (hash !== cachedHash || !fs.existsSync(filepath)) {
+        writeFileSync.cache.set(filepath, hash);
+        writeFile();
+    }
+}
+writeFileSync.cache = new Map();
 const ToolDirectiveSchema = z.strictObject({
     name: z.stringFormat("toolName", (value) => value.indexOf(" ") === -1, {
         error: (iss) => `Tool with name "${iss.input}" must not contain spaces`,