@apollo/client-ai-apps 0.5.4 → 0.6.1

package/src/vite/apolloClientAiApps.ts

@@ -1,14 +1,16 @@
 import {
   defaultClientConditions,
-  type Environment,
   type Plugin,
   type ResolvedConfig,
 } 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, type DocumentNode } 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";
@@ -31,6 +33,16 @@ import type { ApolloClientAiAppsConfig } from "../config/index.js";
 import { ApolloClientAiAppsConfigSchema } from "../config/schema.js";
 import { z } from "zod";
 import { createFragmentRegistry } from "@apollo/client/cache";
+import {
+  buildImportStatement,
+  buildPropertySignature,
+  buildKeywordLiteral,
+  printRecast,
+  type TSInterfaceBody,
+} from "./utilities/recast.js";
+import type { TypeScriptDocumentsPluginConfig } from "@graphql-codegen/typescript-operations";
+
+const b = recast.types.builders;
 
 export declare namespace apolloClientAiApps {
   export type Target = ApolloClientAiAppsConfig.AppTarget;
@@ -38,6 +50,8 @@ export declare namespace apolloClientAiApps {
   export interface Options {
     targets: Target[];
     devTarget?: Target | undefined;
+    appsOutDir: string;
+    schema?: string | undefined;
   }
 }
 
@@ -65,19 +79,331 @@ export function devTarget(target: string | undefined) {
 }
 
 interface FileCache {
-  file: string;
   hash: string;
   sources: DocumentNode[];
 }
 
+function md5(contents: string) {
+  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: TSInterfaceBody) {
+  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: ManifestOperation) {
+  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,
+}: {
+  operations: ManifestOperation[];
+  schema: string | undefined;
+  /**
+   * Used during dev to avoid failing the build and instead output the error
+   * to the console. When providing an error, the error message is generated as
+   * a literal type value in the `register.d.ts` file so that users can see the
+   * error message when hovering over the type.
+   */
+  flagSchemaBuildError?: false | Error;
+}) {
+  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<string>();
+  const toolInputsValue: recast.types.namedTypes.TSPropertySignature[] = [];
+
+  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:
+        | recast.types.namedTypes.TSTypeReference
+        | recast.types.namedTypes.TSIntersectionType = 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: string,
+  documents: string[]
+): Promise<string> {
+  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,
+          } satisfies TypeScriptDocumentsPluginConfig,
+        },
+      },
+      silent: true,
+    } as Parameters<typeof generate>[0],
+    false
+  );
+
+  const content = (output as { filename: string; content: string }[])[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: recast.types.namedTypes.Statement
+): string | undefined {
+  if (statement.type !== "ExportNamedDeclaration") return;
+
+  const declaration = (
+    statement as recast.types.namedTypes.ExportNamedDeclaration
+  ).declaration;
+
+  if (!declaration || declaration.type !== "TSTypeAliasDeclaration") return;
+
+  const alias = declaration as recast.types.namedTypes.TSTypeAliasDeclaration;
+  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: string,
+  rootTypeNames: Set<string>
+): string {
+  const ast = recast.parse(content, { parser: typescriptParser });
+  const statements: recast.types.namedTypes.Statement[] = ast.program.body;
+  const typeMap = new Map<
+    string,
+    recast.types.namedTypes.TSTypeAliasDeclaration
+  >();
+
+  for (const statement of statements) {
+    const name = getExportedTypeAliasName(statement);
+
+    if (name) {
+      typeMap.set(
+        name,
+        (statement as recast.types.namedTypes.ExportNamedDeclaration)
+          .declaration as recast.types.namedTypes.TSTypeAliasDeclaration
+      );
+    }
+  }
+
+  const reachable = new Set<string>(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 as string | undefined;
+
+        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: apolloClientAiApps.Options
 ): Plugin {
   const targets = Array.from(new Set(options.targets));
-  const { devTarget = targets.length === 1 ? targets[0] : undefined } = options;
-  const cache = new Map<string, FileCache>();
-
-  let packageJson!: Record<string, any>;
+  const {
+    devTarget = targets.length === 1 ? targets[0] : undefined,
+    appsOutDir,
+    schema,
+  } = options;
   let config!: ResolvedConfig;
 
   const fragments = createFragmentRegistry();
@@ -92,41 +418,28 @@ export function apolloClientAiApps(
     `All targets must be one of: ${VALID_TARGETS.join(", ")}`
   );
 
+  invariant(
+    path.basename(path.normalize(appsOutDir)) === "apps",
+    "`appsOutDir` must end with `apps` as the final path segment (e.g. `path/to/apps`)."
+  );
+
   const client = new ApolloClient({
     cache: new InMemoryCache({ fragments }),
     link: processQueryLink,
   });
 
-  async function processFile(file: string) {
-    const code = fs.readFileSync(file, "utf-8");
-
-    if (!code.includes("gql")) return;
+  let sources: DocumentNode[] = [];
 
-    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,
-    });
+  function recomputeSources(cache: Map<string, FileCache>) {
+    sources = Array.from(cache.values()).flatMap((entry) => entry.sources);
   }
 
-  async function generateManifest(environment?: Environment) {
-    const appsConfig = await getAppsConfig();
-    const sources = Array.from(cache.values()).flatMap(
-      (entry) => entry.sources
-    );
+  async function getManifestOperations() {
+    if (sources === getManifestOperations.cache.sources) {
+      return getManifestOperations.cache.manifestOperations;
+    }
 
-    const operations: ManifestOperation[] = [];
+    const manifestOperations = [];
     for (const source of sources) {
       const operationDef = source.definitions.find(
         (d) => d.kind === Kind.OPERATION_DEFINITION
@@ -141,7 +454,7 @@ export function apolloClientAiApps(
             fetchPolicy: "no-cache",
           });
 
-          operations.push(result.data!);
+          manifestOperations.push(result.data!);
           break;
         }
         case OperationTypeNode.MUTATION: {
@@ -150,7 +463,7 @@ export function apolloClientAiApps(
             fetchPolicy: "no-cache",
           });
 
-          operations.push(result.data!);
+          manifestOperations.push(result.data!);
           break;
         }
         default:
@@ -160,6 +473,50 @@ export function apolloClientAiApps(
       }
     }
 
+    getManifestOperations.cache = { sources, manifestOperations };
+
+    return manifestOperations;
+  }
+
+  getManifestOperations.cache = {
+    sources,
+    manifestOperations: [] as ManifestOperation[],
+  };
+
+  async function processFile(file: string) {
+    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<string, FileCache>();
+
+  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`."
@@ -193,6 +550,14 @@ export function apolloClientAiApps(
       ) as { mcp?: string; openai?: string };
     }
 
+    const packageJson = readPackageJson();
+    const appName = appsConfig.name ?? packageJson.name;
+
+    invariant(
+      appName,
+      "Error generating application manifest. Could not determine app name. Set `name` in your apollo-client-ai-apps config or `package.json`."
+    );
+
     const manifest: ApplicationManifest = {
       format: "apollo-ai-app-manifest",
       version: "1",
@@ -203,6 +568,7 @@ export function apolloClientAiApps(
       operations,
       resource,
       csp: {
+        baseUriDomains: appsConfig.csp?.baseUriDomains ?? [],
         connectDomains: appsConfig.csp?.connectDomains ?? [],
         frameDomains: appsConfig.csp?.frameDomains ?? [],
         redirectDomains: appsConfig.csp?.redirectDomains ?? [],
@@ -218,30 +584,104 @@ export function apolloClientAiApps(
       manifest.labels = appsConfig.labels;
     }
 
-    // We create mcp and openai environments in order to write to
-    // subdirectories, but we want the manifest to be in the root outDir. If we
-    // are running in a different environment, we'll put it in the configured
-    // outDir directly instead.
-    const outDir =
-      environment?.name === "mcp" || environment?.name === "openai" ?
-        path.resolve(config.build.outDir, "../")
-      : config.build.outDir;
+    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),
+      ]) as recast.types.namedTypes.VariableDeclaration & { declare: boolean };
+      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 | Error = 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 as Error;
+        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 = [] as ManifestOperation[] | undefined;
+
   return {
     name: "@apollo/client-ai-apps/vite",
     async buildStart() {
-      // Read package.json on start
-      packageJson = JSON.parse(fs.readFileSync("package.json", "utf-8"));
-
       // Scan all files on startup
       const files = await glob("./src/**/*.{ts,tsx,js,jsx}", { fs });
 
@@ -252,37 +692,52 @@ export function apolloClientAiApps(
 
       // 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;
     },
-    configEnvironment(name, { build }) {
+    async configEnvironment(name) {
       if (!targets.includes(name as any)) return;
 
+      const appsConfig = await getAppsConfig();
+      const appName = appsConfig.name ?? readPackageJson().name;
+
+      invariant(
+        appName,
+        "Could not determine app name. Set `name` in your apollo-client-ai-apps config or `package.json`."
+      );
+
       return {
         build: {
-          outDir: path.join(build?.outDir ?? "dist", name),
+          outDir: path.join(appsOutDir, appName, name),
         },
       };
     },
     configureServer(server) {
       server.watcher.on("change", async (file) => {
         if (file.endsWith("package.json")) {
-          packageJson = JSON.parse(fs.readFileSync("package.json", "utf-8"));
+          readPackageJson.resetCache();
           await generateManifest();
         } else if (file.match(/\.?apollo-client-ai-apps\.config\.\w+$/)) {
           explorer.clearCaches();
           await generateManifest();
         } else if (file.match(/\.(jsx?|tsx?)$/)) {
           await processFile(file);
-          await generateManifest();
+          await Promise.all([generateManifest(), generateTypesFiles()]);
         }
       });
     },
 
-    config(_, { command }) {
+    config(userConfig, { command }) {
+      if (userConfig.build?.outDir) {
+        console.warn(
+          "[@apollo/client-ai-apps/vite] `build.outDir` is set in your Vite config but will be " +
+            "ignored. Use `appsOutDir` in the plugin options to control the output location."
+        );
+      }
+
       if (command === "serve") {
         invariant(
           isValidTarget(devTarget) || targets.length === 1,
@@ -343,7 +798,7 @@ export function apolloClientAiApps(
       );
     },
     async writeBundle() {
-      await generateManifest(this.environment);
+      await Promise.all([generateManifest(), generateTypesFiles()]);
     },
   } satisfies Plugin;
 }
@@ -379,35 +834,63 @@ const processQueryLink = new ApolloLink((operation) => {
   // 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 result = ToolDirectiveSchema.safeParse({
-        name: getArgumentValue(
-          getDirectiveArgument("name", directive, { required: true }),
-          Kind.STRING
-        ),
-        description: getArgumentValue(
-          getDirectiveArgument("description", directive, { required: true }),
-          Kind.STRING
-        ),
-        extraInputs: maybeGetArgumentValue(
-          getDirectiveArgument("extraInputs", directive),
-          Kind.LIST
-        ),
-        labels: maybeGetArgumentValue(
-          getDirectiveArgument("labels", directive),
-          Kind.OBJECT
-        ),
-      });
+  const toolDirectives =
+    directives?.filter((d) => d.name.value === "tool") ?? [];
 
-      if (result.error) {
-        throw z.prettifyError(result.error);
-      }
+  const tools = toolDirectives.map((directive) => {
+    const nameArg = getDirectiveArgument("name", directive);
+    const descriptionArg = getDirectiveArgument("description", directive);
+
+    let name: string;
+    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;
+    }
 
-      return result.data;
+    let description: string;
+    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,
+      description,
+      extraInputs: maybeGetArgumentValue(
+        getDirectiveArgument("extraInputs", directive),
+        Kind.LIST
+      ),
+      labels: maybeGetArgumentValue(
+        getDirectiveArgument("labels", directive),
+        Kind.OBJECT
+      ),
     });
 
+    if (result.error) {
+      throw z.prettifyError(result.error);
+    }
+
+    return result.data;
+  });
+
   // TODO: Make this object satisfy the `ManifestOperation` type. Currently
   // it errors because we need more validation on a few of these fields
   return of({
@@ -503,6 +986,46 @@ function getResourceFromConfig(
   return typeof config === "string" ? config : config[target];
 }
 
+function readPackageJson(): Record<string, any> {
+  if (readPackageJson.cache) {
+    return readPackageJson.cache;
+  }
+
+  return (readPackageJson.cache = JSON.parse(
+    fs.readFileSync("package.json", "utf-8")
+  ));
+}
+
+readPackageJson.cache = undefined as Record<string, any> | undefined;
+readPackageJson.resetCache = () => {
+  readPackageJson.cache = undefined;
+};
+
+function writeFileSync(
+  filepath: string,
+  content: string,
+  options: { cache?: boolean } = {}
+) {
+  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<string, string>();
+
 const ToolDirectiveSchema = z.strictObject({
   name: z.stringFormat("toolName", (value) => value.indexOf(" ") === -1, {
     error: (iss) => `Tool with name "${iss.input}" must not contain spaces`,