@apollo/client-ai-apps 0.6.0 → 0.6.2

package/src/vite/__tests__/apolloClientAiApps.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { spyOnConsole } from "../../testing/internal/index.js";
+import { spyOnConsole, wait } from "../../testing/internal/index.js";
 import fs from "node:fs";
 import { gql, type DocumentNode } from "@apollo/client";
 import { getMainDefinition, print } from "@apollo/client/utilities";
@@ -676,11 +676,11 @@ describe("@prefetch", () => {
 });
 
 describe("@tool validation", () => {
-  test("errors when tool name is not provided", async () => {
+  test("errors when tool name is not provided on anonymous operation", async () => {
     vol.fromJSON({
       "package.json": mockPackageJson(),
       "src/my-component.tsx": declareOperation(gql`
-        query HelloWorldQuery @tool {
+        query @tool {
           helloWorld
         }
       `),
@@ -694,11 +694,11 @@ describe("@tool validation", () => {
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: 'name' argument must be supplied for @tool]`
+      `[Error: Anonymous operations cannot use @tool without providing a 'name' argument]`
     );
   });
 
-  test("errors when tool description is not provided", async () => {
+  test("errors when tool description is not provided and operation has no description", async () => {
     vol.fromJSON({
       "package.json": mockPackageJson(),
       "src/my-component.tsx": declareOperation(gql`
@@ -716,10 +716,110 @@ describe("@tool validation", () => {
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: 'description' argument must be supplied for @tool]`
+      `[Error: Operations using @tool without a 'description' argument must have a description on the operation definition]`
     );
   });
 
+  test("uses operation name as tool name when name is omitted from @tool", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery @tool(description: "A greeting tool") {
+          helloWorld
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const manifest = readManifestFile();
+    expect(manifest.operations[0].tools).toMatchInlineSnapshot(`
+      [
+        {
+          "description": "A greeting tool",
+          "name": "HelloWorldQuery",
+        },
+      ]
+    `);
+  });
+
+  test("uses operation description as tool description when description is omitted from @tool", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        """
+        A greeting tool
+        """
+        query HelloWorldQuery @tool(name: "hello-world") {
+          helloWorld
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const manifest = readManifestFile();
+    expect(manifest.operations[0].tools).toMatchInlineSnapshot(`
+      [
+        {
+          "description": "A greeting tool",
+          "name": "hello-world",
+        },
+      ]
+    `);
+    expect(manifest.operations[0].body).toMatchInlineSnapshot(`
+      "query HelloWorldQuery {
+        helloWorld
+      }"
+    `);
+  });
+
+  test("uses operation name and description when both are omitted from @tool", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        """
+        A greeting tool
+        """
+        query HelloWorldQuery @tool {
+          helloWorld
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const manifest = readManifestFile();
+    expect(manifest.operations[0].tools).toMatchInlineSnapshot(`
+      [
+        {
+          "description": "A greeting tool",
+          "name": "HelloWorldQuery",
+        },
+      ]
+    `);
+    expect(manifest.operations[0].body).toMatchInlineSnapshot(`
+      "query HelloWorldQuery {
+        helloWorld
+      }"
+    `);
+  });
+
   test("errors when tool name contains spaces", async () => {
     vol.fromJSON({
       "package.json": mockPackageJson(),
@@ -839,6 +939,54 @@ describe("@tool validation", () => {
       `[Error: Error when parsing directive values: unexpected type 'FloatValue']`
     );
   });
+
+  test("errors when multiple @tool directives are used and one is missing a name", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(name: "tool-a", description: "Tool A")
+        @tool(description: "Tool B") {
+          helloWorld
+        }
+      `),
+    });
+
+    await expect(async () => {
+      await using server = await setupServer({
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
+      });
+      await server.listen();
+    }).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Operations with multiple @tool directives must provide a 'name' argument on each @tool]`
+    );
+  });
+
+  test("errors when multiple @tool directives are used and one is missing a description", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(name: "tool-a", description: "Tool A")
+        @tool(name: "tool-b") {
+          helloWorld
+        }
+      `),
+    });
+
+    await expect(async () => {
+      await using server = await setupServer({
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
+      });
+      await server.listen();
+    }).rejects.toThrowErrorMatchingInlineSnapshot(
+      `[Error: Operations with multiple @tool directives must provide a 'description' argument on each @tool]`
+    );
+  });
 });
 
 describe("config validation", () => {
@@ -1473,6 +1621,71 @@ describe("entry points", () => {
       true
     );
   });
+
+  test("generates .application-manifest.d.json.ts at root in build mode", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(name: "hello-world", description: "This is an awesome tool!") {
+          helloWorld
+        }
+      `),
+    });
+
+    await buildApp({
+      mode: "production",
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+
+    expect(vol.existsSync(".application-manifest.d.json.ts")).toBe(true);
+  });
+
+  test("generates .application-manifest.d.json.ts at root in serve mode", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(name: "hello-world", description: "This is an awesome tool!") {
+          helloWorld
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    expect(vol.existsSync(".application-manifest.d.json.ts")).toBe(true);
+  });
+
+  test("does not write .application-manifest.json.d.ts to appsOutDir", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery
+        @tool(name: "hello-world", description: "This is an awesome tool!") {
+          helloWorld
+        }
+      `),
+    });
+
+    await buildApp({
+      mode: "production",
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+
+    expect(
+      vol.existsSync("dist/apps/my-app/.application-manifest.json.d.ts")
+    ).toBe(false);
+  });
 });
 
 describe("appsOutDir", () => {
@@ -1695,6 +1908,541 @@ describe("file watching", () => {
   });
 });
 
+describe("tool input types", () => {
+  const schema = `
+    type Query {
+      todo(id: ID!): Todo
+    }
+
+    type Mutation {
+      createTodo(title: String!, description: String): Todo
+      deleteTodo(id: ID!): Boolean
+    }
+
+    type Todo {
+      id: ID!
+      title: String!
+      description: String
+    }
+  `;
+
+  test("generates operation-types.d.ts with variable types when schema is provided", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!, $description: String)
+        @tool(name: "CreateTodo", description: "Creates a todo") {
+          createTodo(title: $title, description: $description) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/operation-types.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// Auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      export type Maybe<T> = T | null;
+
+      export type InputMaybe<T> = Maybe<T>;
+
+      export type Exact<T extends {
+        [key: string]: unknown;
+      }> = {
+        [K in keyof T]: T[K];
+      };
+
+      /** All built-in and custom scalars, mapped to their actual values */
+      export type Scalars = {
+        ID: {
+          input: string;
+          output: string;
+        };
+        String: {
+          input: string;
+          output: string;
+        };
+        Boolean: {
+          input: boolean;
+          output: boolean;
+        };
+        Int: {
+          input: number;
+          output: number;
+        };
+        Float: {
+          input: number;
+          output: number;
+        };
+      };
+
+      export type CreateTodoMutationVariables = Exact<{
+        title: Scalars["String"]["input"];
+        description?: InputMaybe<Scalars["String"]["input"]>;
+      }>;"
+    `);
+  });
+
+  test("generates register.d.ts with toolInputs when schema is provided", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!, $description: String)
+        @tool(name: "CreateTodo", description: "Creates a todo") {
+          createTodo(title: $title, description: $description) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/register.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      import type { CreateTodoMutationVariables } from "./operation-types.js";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "CreateTodo";
+          toolInputs: {
+            CreateTodo: CreateTodoMutationVariables;
+          };
+        }
+      }"
+    `);
+  });
+
+  test("generates register.d.ts with operations that contain fragments", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!, $description: String)
+        @tool(name: "CreateTodo", description: "Creates a todo") {
+          createTodo(title: $title, description: $description) {
+            id
+            ...TodoFragment
+          }
+        }
+      `),
+      "src/todo-fragment.tsx": declareFragment(gql`
+        fragment TodoFragment on Todo {
+          title
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    expect(
+      fs.readFileSync(".apollo-client-ai-apps/types/register.d.ts", "utf-8")
+    ).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      import type { CreateTodoMutationVariables } from "./operation-types.js";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "CreateTodo";
+          toolInputs: {
+            CreateTodo: CreateTodoMutationVariables;
+          };
+        }
+      }"
+    `);
+    expect(
+      fs.readFileSync(
+        ".apollo-client-ai-apps/types/operation-types.d.ts",
+        "utf-8"
+      )
+    ).toMatchInlineSnapshot(`
+      "// Auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      export type Maybe<T> = T | null;
+
+      export type InputMaybe<T> = Maybe<T>;
+
+      export type Exact<T extends {
+        [key: string]: unknown;
+      }> = {
+        [K in keyof T]: T[K];
+      };
+
+      /** All built-in and custom scalars, mapped to their actual values */
+      export type Scalars = {
+        ID: {
+          input: string;
+          output: string;
+        };
+        String: {
+          input: string;
+          output: string;
+        };
+        Boolean: {
+          input: boolean;
+          output: boolean;
+        };
+        Int: {
+          input: number;
+          output: number;
+        };
+        Float: {
+          input: number;
+          output: number;
+        };
+      };
+
+      export type CreateTodoMutationVariables = Exact<{
+        title: Scalars["String"]["input"];
+        description?: InputMaybe<Scalars["String"]["input"]>;
+      }>;"
+    `);
+  });
+
+  test("tool with no extraInputs uses only the Variables type", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation DeleteTodo($id: ID!)
+        @tool(name: "DeleteTodo", description: "Deletes a todo") {
+          deleteTodo(id: $id)
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/register.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      import type { DeleteTodoMutationVariables } from "./operation-types.js";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "DeleteTodo";
+          toolInputs: {
+            DeleteTodo: DeleteTodoMutationVariables;
+          };
+        }
+      }"
+    `);
+  });
+
+  test("tool with extraInputs adds properties to tool input type", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!)
+        @tool(
+          name: "CreateTodo"
+          description: "Creates a todo"
+          extraInputs: [
+            { name: "priority", type: "string", description: "Priority" }
+            { name: "urgent", type: "boolean", description: "Is urgent?" }
+            {
+              name: "odd-name"
+              type: "boolean"
+              description: "Test of odd name"
+            }
+          ]
+        ) {
+          createTodo(title: $title) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/register.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      import type { CreateTodoMutationVariables } from "./operation-types.js";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "CreateTodo";
+          toolInputs: {
+            CreateTodo: CreateTodoMutationVariables & {
+              priority?: string;
+              urgent?: boolean;
+              "odd-name"?: boolean;
+            };
+          };
+        }
+      }"
+    `);
+  });
+
+  test("multiple @tool directives on an operation each get their own toolInputs entry", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!)
+        @tool(name: "CreateTodo", description: "Creates a todo")
+        @tool(name: "AddTask", description: "Adds a task") {
+          createTodo(title: $title) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/register.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      import type { CreateTodoMutationVariables } from "./operation-types.js";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "CreateTodo" | "AddTask";
+          toolInputs: {
+            CreateTodo: CreateTodoMutationVariables;
+            AddTask: CreateTodoMutationVariables;
+          };
+        }
+      }"
+    `);
+  });
+
+  test("operation-types.d.ts is not rewritten when operation content has not changed", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!)
+        @tool(name: "CreateTodo", description: "Creates a todo") {
+          createTodo(title: $title) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/operation-types.d.ts",
+      "utf-8"
+    );
+    const mtime = fs.statSync(
+      ".apollo-client-ai-apps/types/operation-types.d.ts"
+    ).mtimeMs;
+
+    // Trigger another manifest generation (simulating a file change to an unrelated file)
+    server.watcher.emit("change", "package.json");
+    await wait(100);
+
+    expect(
+      fs.readFileSync(
+        ".apollo-client-ai-apps/types/operation-types.d.ts",
+        "utf-8"
+      )
+    ).toBe(content);
+
+    expect(
+      fs.statSync(".apollo-client-ai-apps/types/operation-types.d.ts").mtimeMs
+    ).toBe(mtime);
+  });
+
+  test("does not generate operation-types.d.ts when schema is not provided", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!)
+        @tool(name: "CreateTodo", description: "Creates a todo") {
+          createTodo(title: $title) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    expect(
+      fs.existsSync(".apollo-client-ai-apps/types/operation-types.d.ts")
+    ).toBe(false);
+  });
+
+  test("generates register.d.ts with error message when schema build fails in dev mode", async () => {
+    using _ = spyOnConsole("error");
+
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query GetNonExistent
+        @tool(name: "GetNonExistent", description: "A tool") {
+          nonExistentField
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          appsOutDir: "dist/apps",
+          schema,
+        }),
+      ],
+    });
+    await server.listen();
+
+    expect(console.error).toHaveBeenCalledOnce();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/register.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "[@apollo/client-ai-apps/vite]: There was an error building generated types. See the vite build output for more details.\\n\\nGraphQL Document Validation failed with 1 errors;\\n  Error 0: Cannot query field \\"nonExistentField\\" on type \\"Query\\".\\n    at 116185304.graphql:2:3";
+          toolInputs: {
+            "[@apollo/client-ai-apps/vite]: There was an error building generated types. See the vite build output for more details.\\n\\nGraphQL Document Validation failed with 1 errors;\\n  Error 0: Cannot query field \\"nonExistentField\\" on type \\"Query\\".\\n    at 116185304.graphql:2:3": "[@apollo/client-ai-apps/vite]: There was an error building generated types. See the vite build output for more details.\\n\\nGraphQL Document Validation failed with 1 errors;\\n  Error 0: Cannot query field \\"nonExistentField\\" on type \\"Query\\".\\n    at 116185304.graphql:2:3";
+          };
+        }
+      }"
+    `);
+  });
+
+  test("generates register.d.ts without toolInputs when schema is not provided", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        mutation CreateTodo($title: String!)
+        @tool(name: "CreateTodo", description: "Creates a todo") {
+          createTodo(title: $title) {
+            id
+          }
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const content = fs.readFileSync(
+      ".apollo-client-ai-apps/types/register.d.ts",
+      "utf-8"
+    );
+    expect(content).toMatchInlineSnapshot(`
+      "// This file is auto-generated by @apollo/client-ai-apps. Do not edit manually.
+      import "@apollo/client-ai-apps";
+
+      declare module "@apollo/client-ai-apps" {
+        interface Register {
+          toolName: "CreateTodo";
+        }
+      }"
+    `);
+  });
+});
+
 describe("html transforms", () => {
   test("replaces root relative scripts with full url when origin is provided", async () => {
     vol.fromJSON({