@apollo/client-ai-apps 0.5.3 → 0.6.0

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

@@ -1,16 +1,17 @@
 import { beforeEach, describe, expect, test, vi } from "vitest";
+import { spyOnConsole } from "../../testing/internal/index.js";
 import fs from "node:fs";
 import { gql, type DocumentNode } from "@apollo/client";
-import { print } from "@apollo/client/utilities";
+import { getMainDefinition, print } from "@apollo/client/utilities";
 import { getOperationName } from "@apollo/client/utilities/internal";
 import { vol } from "memfs";
 import { apolloClientAiApps } from "../apolloClientAiApps.js";
 import { buildApp, setupServer } from "./utilities/build.js";
-import type {
-  ApplicationManifest,
-  ManifestWidgetSettings,
-} from "../../types/application-manifest.js";
+import type { ApplicationManifest } from "../../types/application-manifest.js";
 import { explorer } from "../utilities/config.js";
+import { invariant } from "@apollo/client/utilities/invariant";
+import { Kind } from "graphql";
+import type { ApolloClientAiAppsConfig } from "../../config/types.js";
 
 beforeEach(() => {
   explorer.clearCaches();
@@ -27,12 +28,19 @@ describe("operations", () => {
               invoked: "Tested global!",
             },
           },
+          csp: {
+            baseUriDomains: ["https://base.example.com"],
+            connectDomains: ["https://connect.example.com"],
+            frameDomains: ["https://frame.example.com"],
+            redirectDomains: ["https://redirect.example.com"],
+            resourceDomains: ["https://resource.example.com"],
+          },
           widgetSettings: {
             description: "Test",
             domain: "https://example.com",
             prefersBorder: true,
-          } satisfies ManifestWidgetSettings,
-        },
+          },
+        } satisfies ApolloClientAiAppsConfig.Config,
       }),
       "src/my-component.tsx": declareOperation(gql`
         query HelloWorldQuery($name: string!)
@@ -59,7 +67,9 @@ describe("operations", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -68,10 +78,21 @@ describe("operations", () => {
       {
         "appVersion": "1.0.0",
         "csp": {
-          "connectDomains": [],
-          "frameDomains": [],
-          "redirectDomains": [],
-          "resourceDomains": [],
+          "baseUriDomains": [
+            "https://base.example.com",
+          ],
+          "connectDomains": [
+            "https://connect.example.com",
+          ],
+          "frameDomains": [
+            "https://frame.example.com",
+          ],
+          "redirectDomains": [
+            "https://redirect.example.com",
+          ],
+          "resourceDomains": [
+            "https://resource.example.com",
+          ],
         },
         "format": "apollo-ai-app-manifest",
         "hash": "abc",
@@ -79,6 +100,7 @@ describe("operations", () => {
           "toolInvocation/invoked": "Tested global!",
           "toolInvocation/invoking": "Testing global...",
         },
+        "name": "my-app",
         "operations": [
           {
             "body": "query HelloWorldQuery($name: string!) {
@@ -121,6 +143,181 @@ describe("operations", () => {
     `);
   });
 
+  test("handles operations with fragments in the same file", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery($name: string!)
+        @tool(name: "hello-world", description: "This is an awesome tool!") {
+          greeting {
+            message
+            recipient {
+              ...RecipientFragment
+            }
+          }
+        }
+
+        fragment RecipientFragment on Recipient {
+          id
+          name
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const manifest = readManifestFile();
+    expect(manifest).toMatchInlineSnapshot(`
+      {
+        "appVersion": "1.0.0",
+        "csp": {
+          "baseUriDomains": [],
+          "connectDomains": [],
+          "frameDomains": [],
+          "redirectDomains": [],
+          "resourceDomains": [],
+        },
+        "format": "apollo-ai-app-manifest",
+        "hash": "abc",
+        "name": "my-app",
+        "operations": [
+          {
+            "body": "query HelloWorldQuery {
+        greeting {
+          message
+          recipient {
+            ...RecipientFragment
+            __typename
+          }
+          __typename
+        }
+      }
+
+      fragment RecipientFragment on Recipient {
+        id
+        name
+        __typename
+      }",
+            "id": "1646a86ae2ff5ad75457161be5cff80f3ba5172da573a0fc796b268870119020",
+            "name": "HelloWorldQuery",
+            "prefetch": false,
+            "tools": [
+              {
+                "description": "This is an awesome tool!",
+                "name": "hello-world",
+              },
+            ],
+            "type": "query",
+            "variables": {
+              "name": "string",
+            },
+          },
+        ],
+        "resource": "http://localhost:3333",
+        "version": "1",
+      }
+    `);
+  });
+
+  test("handles operations with fragments in other files", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+      "src/first-recipient.tsx": declareFragment(gql`
+        fragment OtherRecipientFragment on Recipient {
+          name
+        }
+      `),
+      "src/my-component.tsx": declareOperation(gql`
+        query HelloWorldQuery($name: string!)
+        @tool(name: "hello-world", description: "This is an awesome tool!") {
+          greeting {
+            message
+            recipient {
+              ...RecipientFragment
+              ...OtherRecipientFragment
+            }
+          }
+        }
+      `),
+      "src/my-fragment.tsx": declareFragment(gql`
+        fragment RecipientFragment on Recipient {
+          id
+          name
+        }
+      `),
+    });
+
+    await using server = await setupServer({
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+    await server.listen();
+
+    const manifest = readManifestFile();
+    expect(manifest).toMatchInlineSnapshot(`
+      {
+        "appVersion": "1.0.0",
+        "csp": {
+          "baseUriDomains": [],
+          "connectDomains": [],
+          "frameDomains": [],
+          "redirectDomains": [],
+          "resourceDomains": [],
+        },
+        "format": "apollo-ai-app-manifest",
+        "hash": "abc",
+        "name": "my-app",
+        "operations": [
+          {
+            "body": "query HelloWorldQuery {
+        greeting {
+          message
+          recipient {
+            ...RecipientFragment
+            ...OtherRecipientFragment
+            __typename
+          }
+          __typename
+        }
+      }
+
+      fragment OtherRecipientFragment on Recipient {
+        name
+        __typename
+      }
+
+      fragment RecipientFragment on Recipient {
+        id
+        name
+        __typename
+      }",
+            "id": "c65cb5ec2dc76bbfa992cd2a98c05ab3f909349f3f1478e608a7f16ae29bdd4a",
+            "name": "HelloWorldQuery",
+            "prefetch": false,
+            "tools": [
+              {
+                "description": "This is an awesome tool!",
+                "name": "hello-world",
+              },
+            ],
+            "type": "query",
+            "variables": {
+              "name": "string",
+            },
+          },
+        ],
+        "resource": "http://localhost:3333",
+        "version": "1",
+      }
+    `);
+  });
+
   test("does not write to dev application manifest file when using a build command", async () => {
     vol.fromJSON({
       "package.json": mockPackageJson(),
@@ -134,7 +331,9 @@ describe("operations", () => {
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -151,7 +350,9 @@ describe("operations", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -160,6 +361,7 @@ describe("operations", () => {
       {
         "appVersion": "1.0.0",
         "csp": {
+          "baseUriDomains": [],
           "connectDomains": [],
           "frameDomains": [],
           "redirectDomains": [],
@@ -167,6 +369,7 @@ describe("operations", () => {
         },
         "format": "apollo-ai-app-manifest",
         "hash": "abc",
+        "name": "my-app",
         "operations": [],
         "resource": "http://localhost:3333",
         "version": "1",
@@ -185,7 +388,9 @@ describe("operations", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -194,6 +399,7 @@ describe("operations", () => {
       {
         "appVersion": "1.0.0",
         "csp": {
+          "baseUriDomains": [],
           "connectDomains": [],
           "frameDomains": [],
           "redirectDomains": [],
@@ -201,6 +407,7 @@ describe("operations", () => {
         },
         "format": "apollo-ai-app-manifest",
         "hash": "abc",
+        "name": "my-app",
         "operations": [
           {
             "body": "query HelloWorldQuery {
@@ -232,7 +439,9 @@ describe("operations", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -241,6 +450,7 @@ describe("operations", () => {
       {
         "appVersion": "1.0.0",
         "csp": {
+          "baseUriDomains": [],
           "connectDomains": [],
           "frameDomains": [],
           "redirectDomains": [],
@@ -248,6 +458,7 @@ describe("operations", () => {
         },
         "format": "apollo-ai-app-manifest",
         "hash": "abc",
+        "name": "my-app",
         "operations": [
           {
             "body": "mutation HelloWorldQuery {
@@ -285,11 +496,13 @@ describe("operations", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
-      `[Error: Found an unsupported operation type. Only Query and Mutation are supported.]`
+      `[Error: Found unsupported operation type 'subscription'. Only queries and mutations are supported.]`
     );
   });
 
@@ -313,7 +526,9 @@ describe("operations", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -322,6 +537,7 @@ describe("operations", () => {
       {
         "appVersion": "1.0.0",
         "csp": {
+          "baseUriDomains": [],
           "connectDomains": [],
           "frameDomains": [],
           "redirectDomains": [],
@@ -329,6 +545,7 @@ describe("operations", () => {
         },
         "format": "apollo-ai-app-manifest",
         "hash": "abc",
+        "name": "my-app",
         "operations": [
           {
             "body": "query HelloWorldQuery {
@@ -388,7 +605,9 @@ describe("@prefetch", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -397,6 +616,7 @@ describe("@prefetch", () => {
       {
         "appVersion": "1.0.0",
         "csp": {
+          "baseUriDomains": [],
           "connectDomains": [],
           "frameDomains": [],
           "redirectDomains": [],
@@ -404,6 +624,7 @@ describe("@prefetch", () => {
         },
         "format": "apollo-ai-app-manifest",
         "hash": "abc",
+        "name": "my-app",
         "operations": [
           {
             "body": "query HelloWorldQuery {
@@ -443,7 +664,9 @@ describe("@prefetch", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -465,7 +688,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -485,7 +710,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -506,7 +733,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -529,7 +758,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -549,7 +780,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -570,7 +803,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -595,7 +830,9 @@ describe("@tool validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -623,7 +860,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -652,7 +891,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -681,7 +922,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -705,7 +948,9 @@ describe("config validation", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -733,7 +978,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -761,7 +1008,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -792,7 +1041,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -820,7 +1071,9 @@ describe("config validation", () => {
 
     await expect(async () => {
       await using server = await setupServer({
-        plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+        ],
       });
       await server.listen();
     }).rejects.toThrowErrorMatchingInlineSnapshot(
@@ -843,7 +1096,9 @@ describe("config validation", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -872,7 +1127,9 @@ describe("entry points", () => {
 
     await using server = await setupServer({
       mode: "staging",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -901,7 +1158,13 @@ describe("entry points", () => {
 
     await using server = await setupServer({
       mode: "staging",
-      plugins: [apolloClientAiApps({ targets: ["mcp"], devTarget: "mcp" })],
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp"],
+          devTarget: "mcp",
+          appsOutDir: "dist/apps",
+        }),
+      ],
     });
     await server.listen();
 
@@ -922,7 +1185,9 @@ describe("entry points", () => {
 
     await using server = await setupServer({
       server: { https: {}, port: 5678 },
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -943,7 +1208,9 @@ describe("entry points", () => {
 
     await using server = await setupServer({
       server: { port: 5678, host: "0.0.0.0" },
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -970,7 +1237,9 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "staging",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -999,7 +1268,12 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "staging",
-      plugins: [apolloClientAiApps({ targets: ["mcp", "openai"] })],
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp", "openai"],
+          appsOutDir: "dist/apps",
+        }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1028,7 +1302,12 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "staging",
-      plugins: [apolloClientAiApps({ targets: ["mcp", "openai"] })],
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp", "openai"],
+          appsOutDir: "dist/apps",
+        }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1059,7 +1338,9 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "staging",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1081,7 +1362,9 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1101,7 +1384,12 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp", "openai"] })],
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp", "openai"],
+          appsOutDir: "dist/apps",
+        }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1126,7 +1414,9 @@ describe("entry points", () => {
       async () =>
         await buildApp({
           mode: "staging",
-          plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+          plugins: [
+            apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+          ],
         })
     ).rejects.toThrowError(
       `[@apollo/client-ai-apps/vite] No entry point found for mode "staging". Entry points other than "development" and "production" must be defined in package.json file.`
@@ -1146,11 +1436,15 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     expect(vol.existsSync(".application-manifest.json")).toBe(true);
-    expect(vol.existsSync("dist/.application-manifest.json")).toBe(true);
+    expect(vol.existsSync("dist/apps/my-app/.application-manifest.json")).toBe(
+      true
+    );
   });
 
   test("writes to both locations when running in build mode with multiple targets", async () => {
@@ -1166,11 +1460,90 @@ describe("entry points", () => {
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp", "openai"] })],
+      plugins: [
+        apolloClientAiApps({
+          targets: ["mcp", "openai"],
+          appsOutDir: "dist/apps",
+        }),
+      ],
     });
 
     expect(vol.existsSync(".application-manifest.json")).toBe(true);
-    expect(vol.existsSync("dist/.application-manifest.json")).toBe(true);
+    expect(vol.existsSync("dist/apps/my-app/.application-manifest.json")).toBe(
+      true
+    );
+  });
+});
+
+describe("appsOutDir", () => {
+  test("errors when last segment is not `apps`", () => {
+    expect(() =>
+      apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/output" })
+    ).toThrowError(
+      "`appsOutDir` must end with `apps` as the final path segment (e.g. `path/to/apps`)."
+    );
+  });
+
+  test("accepts trailing slash", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+    });
+
+    await expect(
+      buildApp({
+        mode: "production",
+        build: { write: false },
+        plugins: [
+          apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps/" }),
+        ],
+      })
+    ).resolves.not.toThrowError();
+  });
+
+  test("warns when `build.outDir` is set", async () => {
+    vol.fromJSON({
+      "package.json": mockPackageJson(),
+    });
+
+    using _ = spyOnConsole("warn");
+
+    await buildApp({
+      mode: "production",
+      build: { outDir: "custom-out", write: false },
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
+    });
+
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        "`build.outDir` is set in your Vite config but will be ignored"
+      )
+    );
+  });
+
+  test("places output under `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")).toBe(
+      true
+    );
+    expect(vol.existsSync(".application-manifest.json")).toBe(true);
   });
 });
 
@@ -1218,7 +1591,9 @@ export default config;
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1254,7 +1629,9 @@ export default config;
 
     await buildApp({
       mode: "production",
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const manifest = readManifestFile();
@@ -1288,7 +1665,9 @@ describe("file watching", () => {
     });
 
     await using server = await setupServer({
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
     await server.listen();
 
@@ -1326,7 +1705,9 @@ describe("html transforms", () => {
       server: {
         origin: "http://localhost:3000",
       },
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const html = `<html><head><script type="module" src="/@vite/client"></script></head><body><script module src="/assets/main.ts?t=12345"></script></body></html>`;
@@ -1350,7 +1731,9 @@ describe("html transforms", () => {
       server: {
         port: 3000,
       },
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     await server.listen();
@@ -1378,7 +1761,9 @@ window.$RefreshSig$ = () => (type) => type;</script></head></html>`;
       server: {
         origin: "http://localhost:3000",
       },
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     const html = `<html><head>    <script type="module">import { injectIntoGlobalHook } from "/@react-refresh";
@@ -1404,7 +1789,9 @@ window.$RefreshSig$ = () => (type) => type;</script></head></html>`;
       server: {
         port: 3000,
       },
-      plugins: [apolloClientAiApps({ targets: ["mcp"] })],
+      plugins: [
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
+      ],
     });
 
     await server.listen();
@@ -1435,7 +1822,7 @@ window.$RefreshSig$ = () => (type) => type;</script></head></html>`;
         origin: "http://localhost:3000",
       },
       plugins: [
-        apolloClientAiApps({ targets: ["mcp"] }),
+        apolloClientAiApps({ targets: ["mcp"], appsOutDir: "dist/apps" }),
         {
           name: "capture-html",
           transformIndexHtml: {
@@ -1461,8 +1848,20 @@ function declareOperation(operation: DocumentNode) {
   return `const ${varName} = gql\`\n${print(operation)}\n\``;
 }
 
+function declareFragment(fragment: DocumentNode) {
+  const definition = getMainDefinition(fragment);
+  invariant(
+    definition.kind === Kind.FRAGMENT_DEFINITION,
+    "declareFragment must receive a fragment definition"
+  );
+
+  const name = definition.name.value;
+  const varName = name.replace(/([a-z])([A-Z])/g, "$1_$2").toUpperCase();
+  return `const ${varName} = gql\`\n${print(fragment)}\n\``;
+}
+
 function mockPackageJson(config?: Record<string, unknown>) {
-  return JSON.stringify({ version: "1.0.0", ...config });
+  return JSON.stringify({ version: "1.0.0", name: "my-app", ...config });
 }
 
 function readManifestFile(