@dropins/mcp 0.1.0

package/dist/operations/scaffold-extension.js

@@ -0,0 +1,346 @@
+import { z } from "zod";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+import { getExtensionRegistry } from "../common/registry-loader.js";
+import { projectDirGuard } from "../common/project-reader.js";
+import { validateExtensionId, validateUrl, escapeJsString, sanitizeForComment, } from "../common/sanitize.js";
+export const ScaffoldExtensionSchema = z.object({
+    extensionName: z
+        .string()
+        .describe('Human-readable name (e.g. "Stripe Payment")'),
+    extensionId: z
+        .string()
+        .describe('Unique ID (e.g. "stripe-payment"). Used as folder name and id field.'),
+    hooks: z
+        .array(z.string())
+        .describe('Hook names to implement (e.g. ["checkout/payment-methods", "checkout/validate", "checkout/place-order"])'),
+    externalScripts: z
+        .array(z.string())
+        .optional()
+        .describe('External script URLs to load (e.g. ["https://js.stripe.com/v3/"])'),
+    externalStyles: z
+        .array(z.string())
+        .optional()
+        .describe("External stylesheet URLs to load"),
+    projectDir: z
+        .string()
+        .describe("Absolute path to the merchant storefront project root"),
+});
+function generateHookStub(hook) {
+    const contextFields = Object.entries(hook.contextShape ?? {})
+        .map(([key, type]) => `     *   ${key}: ${type}`)
+        .join("\n");
+    const contextDoc = contextFields ? `\n     * Context:\n${contextFields}` : "";
+    switch (hook.name) {
+        case "checkout/validate":
+            return `    /**
+     * Validation hook — set context.isValid = false to block order placement${contextDoc}
+     */
+    'checkout/validate': async ({ context }) => {
+      const { code } = context;
+
+      // Only handle your payment method
+      if (code !== 'YOUR_PAYMENT_CODE') return;
+
+      // Perform custom validation
+      const isValid = true; // Replace with actual validation
+      if (!isValid) {
+        context.isValid = false;
+        return;
+      }
+    },`;
+        case "checkout/payment-methods":
+            return `    /**
+     * Payment methods hook — add your payment method to context.paymentMethods${contextDoc}
+     */
+    'checkout/payment-methods': async ({ context }) => {
+      context.paymentMethods.YOUR_PAYMENT_CODE = {
+        autoSync: false,
+        render: (ctx) => {
+          const container = document.createElement('div');
+          container.className = 'custom-payment-method';
+
+          const title = document.createElement('h3');
+          title.textContent = 'Your Payment Method';
+
+          const description = document.createElement('p');
+          description.textContent = 'Payment method description here.';
+
+          container.appendChild(title);
+          container.appendChild(description);
+          ctx.replaceHTML(container);
+        },
+      };
+    },`;
+        case "checkout/place-order":
+            return `    /**
+     * Place order hook — handle payment processing${contextDoc}
+     */
+    'checkout/place-order': async ({ context }) => {
+      const { cartId, code } = context;
+
+      // Only handle your payment method
+      if (code !== 'YOUR_PAYMENT_CODE') return;
+
+      // Prevent default order placement
+      context.preventDefault = true;
+
+      // Process payment with your provider
+      // const paymentResult = await processPayment(cartId);
+
+      // Place order via API
+      // const { placeOrder } = await import('@dropins/storefront-order/api.js');
+      // await placeOrder(cartId);
+    },`;
+        case "checkout/payment-response":
+            return `    /**
+     * Payment response hook — runs before checkout renders, detect redirect returns here${contextDoc}
+     */
+    'checkout/payment-response': async ({ context }) => {
+      const { block, shouldExit } = context;
+
+      // Detect a returning payment redirect (e.g. check URL params or session state)
+      const isReturningFromRedirect = false; // replace with your detection logic
+
+      if (isReturningFromRedirect) {
+        context.shouldExit = true; // stop normal checkout flow
+        // Handle the gateway response here
+      }
+    },`;
+        case "checkout/address-form-render":
+            return `    /**
+     * Address form render hook — wrap context.render() to augment address form behavior${contextDoc}
+     */
+    'checkout/address-form-render': async ({ context }) => {
+      const { container, addressType, render } = context;
+
+      // addressType is 'shipping' or 'billing'
+      // Wrap the default render to inject custom behavior before/after
+      context.render = (props) => {
+        render(props); // call the original render first
+        // Add custom fields or post-render logic here
+        // const customField = document.createElement('input');
+        // container.appendChild(customField);
+      };
+    },`;
+        default:
+            return `    /**
+     * ${hook.name} hook
+     * ${hook.description ?? ""}${contextDoc}
+     */
+    '${hook.name}': async ({ context }) => {
+      // Implement hook logic here
+    },`;
+    }
+}
+function generateExtensionFile(extensionName, extensionId, hookDefs, externalScripts, externalStyles) {
+    const hookStubs = hookDefs.map(generateHookStub).join("\n\n");
+    const scriptsProp = externalScripts?.length
+        ? `\n  externalScripts: [\n    ${externalScripts.map((s) => `'${escapeJsString(s)}'`).join(",\n    ")},\n  ],`
+        : "";
+    const stylesProp = externalStyles?.length
+        ? `\n  externalStyles: [\n    ${externalStyles.map((s) => `'${escapeJsString(s)}'`).join(",\n    ")},\n  ],`
+        : "";
+    return `/**
+ * ${sanitizeForComment(extensionName)}
+ *
+ * Checkout extension that implements: ${hookDefs.map((h) => h.name).join(", ")}
+ */
+
+export default {
+  id: '${escapeJsString(extensionId)}',
+  name: '${escapeJsString(extensionName)}',${scriptsProp}${stylesProp}
+
+  hooks: {
+${hookStubs}
+  },
+};
+`;
+}
+function generateExtensionsIndex(extensionId) {
+    return `/**
+ * Commerce Checkout Extensions
+ *
+ * Import and register all extensions here.
+ * ADD new extensions — do not replace this file.
+ */
+
+import ${toCamelCase(extensionId)} from './${extensionId}/${extensionId}.js';
+
+export default [
+  ${toCamelCase(extensionId)},
+];
+`;
+}
+function generateIndexMergeSnippet(extensionId) {
+    return {
+        importLine: `import ${toCamelCase(extensionId)} from './${extensionId}/${extensionId}.js';`,
+        exportEntry: `  ${toCamelCase(extensionId)},`,
+    };
+}
+function generateExtensionManager() {
+    return `/**
+ * Extension Manager
+ *
+ * Singleton manager that loads extensions and executes hooks.
+ */
+
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    if (document.querySelector(\`script[src="\${src}"]\`)) {
+      resolve();
+      return;
+    }
+    const script = document.createElement('script');
+    script.src = src;
+    script.onload = resolve;
+    script.onerror = () => reject(new Error(\`Failed to load script: \${src}\`));
+    document.head.appendChild(script);
+  });
+}
+
+function loadStyle(href) {
+  return new Promise((resolve) => {
+    if (document.querySelector(\`link[href="\${href}"]\`)) {
+      resolve();
+      return;
+    }
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = href;
+    link.onload = resolve;
+    document.head.appendChild(link);
+  });
+}
+
+let extensionManagerInstance = null;
+let initializationPromise = null;
+
+async function createExtensionManager() {
+  const extensions = [];
+
+  try {
+    const extensionsModule = await import('./extensions/index.js');
+    extensions.push(...(extensionsModule.default || []));
+
+    const scripts = extensions.flatMap((ext) => ext.externalScripts || []);
+    const styles = extensions.flatMap((ext) => ext.externalStyles || []);
+
+    await Promise.all([
+      ...scripts.map(loadScript),
+      ...styles.map(loadStyle),
+    ]);
+  } catch (e) {
+    console.error('[ExtensionManager] Failed to load extensions:', e.message);
+  }
+
+  return {
+    async executeHook(hookName, context = {}) {
+      for (const ext of extensions) {
+        if (ext.hooks?.[hookName]) {
+          try {
+            await ext.hooks[hookName]({ context });
+          } catch (error) {
+            console.error(\`[ExtensionManager] Error in \${hookName} for \${ext.name}:\`, error);
+            throw error;
+          }
+        }
+      }
+    },
+  };
+}
+
+/** Returns the extension manager boilerplate code for loading and executing hooks. */
+export async function getExtensionManager() {
+  if (extensionManagerInstance) return extensionManagerInstance;
+  if (!initializationPromise) initializationPromise = createExtensionManager();
+  extensionManagerInstance = await initializationPromise;
+  return extensionManagerInstance;
+}
+`;
+}
+function toCamelCase(str) {
+    return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+export async function scaffoldExtension(params) {
+    try {
+        const extIdError = validateExtensionId(params.extensionId);
+        if (extIdError) {
+            return formatSuccessResponse("Invalid extension ID", {
+                error: extIdError,
+            });
+        }
+        if (params.externalScripts) {
+            for (const url of params.externalScripts) {
+                const urlError = validateUrl(url, "external script URL");
+                if (urlError) {
+                    return formatSuccessResponse("Invalid external script URL", {
+                        error: urlError,
+                    });
+                }
+            }
+        }
+        if (params.externalStyles) {
+            for (const url of params.externalStyles) {
+                const urlError = validateUrl(url, "external stylesheet URL");
+                if (urlError) {
+                    return formatSuccessResponse("Invalid external stylesheet URL", {
+                        error: urlError,
+                    });
+                }
+            }
+        }
+        const guard = projectDirGuard(params.projectDir);
+        if (guard)
+            return guard;
+        const registry = getExtensionRegistry();
+        const availableHooks = registry.hooks.map((h) => h.name);
+        const invalidHooks = params.hooks.filter((h) => !availableHooks.includes(h));
+        if (invalidHooks.length > 0) {
+            return formatSuccessResponse("Invalid hook names", {
+                invalidHooks,
+                availableHooks,
+            });
+        }
+        const hookDefs = params.hooks
+            .map((hookName) => registry.hooks.find((h) => h.name === hookName))
+            .filter((h) => h !== undefined);
+        const extensionFile = generateExtensionFile(params.extensionName, params.extensionId, hookDefs, params.externalScripts, params.externalStyles);
+        const indexFile = generateExtensionsIndex(params.extensionId);
+        const indexMergeSnippet = generateIndexMergeSnippet(params.extensionId);
+        const managerFile = generateExtensionManager();
+        const blockBase = "blocks/commerce-checkout";
+        const extDir = `${blockBase}/extensions/${params.extensionId}`;
+        const extFile = `${extDir}/${params.extensionId}.js`;
+        const extIndex = `${blockBase}/extensions/index.js`;
+        const extManager = `${blockBase}/extensions.js`;
+        return formatSuccessResponse(`Extension "${params.extensionName}" scaffolded successfully`, {
+            files: {
+                [extFile]: extensionFile,
+                [extIndex]: indexFile,
+                [extManager]: managerFile,
+            },
+            indexMergeSnippet,
+            instructions: [
+                `Create directory: ${extDir}/`,
+                `Write extension file: ${extFile}`,
+                `If ${extIndex} does NOT exist: write the full indexFile content above`,
+                `If ${extIndex} already EXISTS: add only indexMergeSnippet.importLine near the top and indexMergeSnippet.exportEntry inside the export default array — do NOT replace the file`,
+                `Write extension manager (if not exists): ${extManager}`,
+                "Replace YOUR_PAYMENT_CODE with your actual payment method code",
+                params.externalScripts?.length
+                    ? `External scripts will be auto-loaded: ${params.externalScripts.join(", ")}`
+                    : "No external scripts configured",
+                "Import getExtensionManager in your checkout block to use extensions",
+                'Call extensionManager.executeHook("hookName", context) at the appropriate lifecycle points',
+            ],
+            hooksSummary: hookDefs.map((h) => ({
+                name: h?.name,
+                description: h?.description,
+                whenFired: h?.whenFired,
+            })),
+        });
+    }
+    catch (error) {
+        return formatExceptionResponse(error, "scaffolding extension");
+    }
+}

package/dist/operations/scaffold-slot.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const ScaffoldSlotSchema: z.ZodObject<{
+    containerName: z.ZodString;
+    slotName: z.ZodString;
+    dropin: z.ZodOptional<z.ZodString>;
+    projectDir: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    projectDir: string;
+    containerName: string;
+    slotName: string;
+    dropin?: string | undefined;
+}, {
+    projectDir: string;
+    containerName: string;
+    slotName: string;
+    dropin?: string | undefined;
+}>;
+export declare function scaffoldSlot(params: z.infer<typeof ScaffoldSlotSchema>): Promise<{
+    success: boolean;
+    message: string;
+    data: unknown;
+}>;

package/dist/operations/scaffold-slot.js

@@ -0,0 +1,189 @@
+import { z } from "zod";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+import { getSlotRegistry, getContainerRegistry, } from "../common/registry-loader.js";
+import { projectDirGuard } from "../common/project-reader.js";
+export const ScaffoldSlotSchema = z.object({
+    containerName: z
+        .string()
+        .describe('Container name (e.g. "MiniCart", "ShippingMethods")'),
+    slotName: z
+        .string()
+        .describe('Slot name to scaffold (e.g. "Thumbnail", "ShippingMethodItem")'),
+    dropin: z
+        .string()
+        .optional()
+        .describe('Dropin package name (e.g. "storefront-cart"). Provide to resolve ambiguity when the same slot name exists in multiple dropins.'),
+    projectDir: z
+        .string()
+        .describe("Absolute path to the merchant storefront project root"),
+});
+function extractContextProps(contextType) {
+    if (!contextType || contextType === "DefaultSlotContext")
+        return [];
+    if (!contextType.includes("{"))
+        return [];
+    const matches = [...contextType.matchAll(/^\s*(\w+)\s*:/gm)];
+    return matches.map((m) => m[1]);
+}
+function toKebabCase(str) {
+    return str.replace(/([A-Z])/g, (_, c, i) => (i > 0 ? "-" : "") + c.toLowerCase());
+}
+function buildSlotCodeParts(slot, registry) {
+    const contextType = slot.contextType ?? "DefaultSlotContext";
+    const customMethods = slot.customMethods ?? [];
+    const defaultMethods = registry.defaultSlotMethods ?? {};
+    const contextProps = extractContextProps(contextType);
+    const allMethods = [
+        ...Object.entries(defaultMethods).map(([name, desc]) => ({ name, desc })),
+        ...customMethods
+            .filter((m) => !(m in defaultMethods))
+            .map((m) => ({ name: m, desc: "" })),
+    ];
+    const allMethodNames = allMethods.map(({ name }) => name);
+    const methodComments = allMethods
+        .map(({ name, desc }) => desc ? `  //   ctx.${name}(...)  - ${desc}` : `  //   ctx.${name}(...)`)
+        .join("\n");
+    const contextDestructure = contextProps.length > 0
+        ? `  const { ${contextProps.join(", ")} } = ctx;\n`
+        : "";
+    if (customMethods.includes("appendAgreement")) {
+        return {
+            contextProps,
+            allMethodNames,
+            slotCode: `${slot.name}: (ctx) => {
+  ctx.appendAgreement(() => ({
+    name: 'custom-agreement',
+    mode: 'manual',
+    translationId: 'Custom.Agreement.Label',
+  }));
+},`,
+        };
+    }
+    return {
+        contextProps,
+        allMethodNames,
+        slotCode: `${slot.name}: (ctx) => {
+  // Available methods:
+${methodComments}
+${contextDestructure}
+  const element = document.createElement('div');
+  element.className = 'custom-${toKebabCase(slot.name)}';
+
+  // Build your custom content here
+  element.textContent = 'Custom content';
+
+  ctx.appendChild(element);
+},`,
+    };
+}
+function generateScaffold(slotCode, match) {
+    return `// 1. Imports
+import { render as provider } from '${match.renderImport}';
+import ${match.containerName} from '${match.containerImportPath}';
+
+// 2. Render the container with the slot
+const container = document.querySelector('.block-placeholder');
+if (container) {
+  provider.render(${match.containerName}, {
+    slots: {
+      ${slotCode}
+    },
+  })(container);
+}`;
+}
+export async function scaffoldSlot(params) {
+    try {
+        const guard = projectDirGuard(params.projectDir);
+        if (guard)
+            return guard;
+        const slotRegistry = getSlotRegistry();
+        const containerRegistry = getContainerRegistry();
+        const matches = [];
+        const searchDropins = params.dropin
+            ? [params.dropin]
+            : Object.keys(slotRegistry.dropins);
+        const containerLower = params.containerName.toLowerCase();
+        const slotLower = params.slotName.toLowerCase();
+        for (const dropinName of searchDropins) {
+            const dropinSlotData = slotRegistry.dropins[dropinName];
+            if (!dropinSlotData)
+                continue;
+            for (const [cName, cData] of Object.entries(dropinSlotData.containers)) {
+                if (cName.toLowerCase() !== containerLower)
+                    continue;
+                const slot = cData.slots.find((s) => s.name.toLowerCase() === slotLower);
+                if (!slot)
+                    continue;
+                const dropinContainerData = containerRegistry.dropins[dropinName];
+                const containerEntry = dropinContainerData?.containers.find((c) => c.name.toLowerCase() === containerLower);
+                matches.push({
+                    dropin: dropinName,
+                    containerName: cName,
+                    slot,
+                    renderImport: dropinContainerData?.renderImport ??
+                        `@dropins/${dropinName}/render.js`,
+                    containerImportPath: containerEntry?.importPath ??
+                        `@dropins/${dropinName}/containers/${cName}.js`,
+                });
+            }
+        }
+        if (matches.length === 0) {
+            const knownContainers = Object.entries(slotRegistry.dropins)
+                .flatMap(([d, data]) => Object.keys(data.containers).map((c) => `${d} → ${c}`))
+                .slice(0, 12);
+            return formatSuccessResponse(`Slot "${params.slotName}" not found in container "${params.containerName}"`, {
+                error: "Slot not found",
+                searched: params.dropin ?? "all dropins",
+                hint: `Use list_slots to browse available slots. Sample known containers: ${knownContainers.join(", ")}`,
+            });
+        }
+        if (matches.length > 1) {
+            return formatSuccessResponse(`Slot "${params.slotName}" exists in multiple dropins - specify the dropin parameter`, {
+                ambiguousMatches: matches.map((m) => ({
+                    dropin: m.dropin,
+                    containerName: m.containerName,
+                    slotName: m.slot.name,
+                })),
+            });
+        }
+        const match = matches[0];
+        const { contextProps, allMethodNames, slotCode } = buildSlotCodeParts(match.slot, slotRegistry);
+        const codeScaffold = generateScaffold(slotCode, match);
+        return formatSuccessResponse(`Slot "${match.slot.name}" scaffolded for ${match.containerName} (${match.dropin})`, {
+            dropin: match.dropin,
+            containerName: match.containerName,
+            slotName: match.slot.name,
+            description: match.slot.description || "(no description)",
+            contextType: match.slot.contextType,
+            contextProps: contextProps.length > 0
+                ? contextProps
+                : match.slot.contextType &&
+                    match.slot.contextType !== "DefaultSlotContext"
+                    ? [
+                        `named type: ${match.slot.contextType} - use list_slots to inspect its shape`,
+                    ]
+                    : ["no typed props - default slot context"],
+            availableMethods: allMethodNames,
+            customMethods: match.slot.customMethods ?? [],
+            isDynamic: match.slot.dynamic,
+            codeScaffold,
+            instructions: [
+                `Import render from: ${match.renderImport} (aliased as provider)`,
+                `Import container from: ${match.containerImportPath}`,
+                "Pass the slot function inside the slots prop of provider.render(Container, { slots: {...} })(element)",
+                contextProps.length > 0
+                    ? `Destructure context props from ctx: { ${contextProps.join(", ")} }`
+                    : "Use ctx.appendChild(element) to inject content into the slot",
+                match.slot.customMethods?.length
+                    ? `Extra methods on ctx: ${match.slot.customMethods.join(", ")}`
+                    : "Only default slot methods are available on ctx",
+                match.slot.dynamic
+                    ? "Dynamic slot: this function is called once per item in a list (e.g. per product, per shipping method)"
+                    : "Static slot: this function is called once per container instance",
+            ],
+        });
+    }
+    catch (error) {
+        return formatExceptionResponse(error, "scaffolding slot");
+    }
+}

package/dist/operations/search-commerce-docs.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const SearchCommerceDocsSchema: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    maxResults?: number | undefined;
+}, {
+    query: string;
+    maxResults?: number | undefined;
+}>;
+export declare function searchCommerceDocs(params: z.infer<typeof SearchCommerceDocsSchema>): Promise<{
+    success: boolean;
+    message: string;
+    data: unknown;
+}>;

package/dist/operations/search-commerce-docs.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { formatSuccessResponse, formatExceptionResponse, } from "../common/response-handling.js";
+const execFileAsync = promisify(execFile);
+const RAG_ENDPOINTS = {
+    prod: "https://commerce-docs-prod-endpoint-d0ctgyebe7bec8e6.a02.azurefd.net/api/query",
+    stage: "https://commerce-docs-dev-endpoint-hbe8ceethxh9d2g3.a02.azurefd.net/api/query",
+};
+export const SearchCommerceDocsSchema = z.object({
+    query: z
+        .string()
+        .describe('Natural language search query (e.g. "how to add a custom payment method", "CORS configuration for storefront")'),
+    maxResults: z
+        .number()
+        .optional()
+        .describe("Maximum number of results to return (default: 5)"),
+});
+async function getImsToken() {
+    const { stdout } = await execFileAsync("aio", ["config", "get", "ims.contexts.cli.access_token.token"], { timeout: 10000 });
+    const token = stdout.trim();
+    if (!token) {
+        throw new Error("No IMS token returned. Run: aio auth login");
+    }
+    return token;
+}
+async function getAioEnvironment() {
+    try {
+        const { stdout } = await execFileAsync("aio", ["config", "get", "cli.env"], { timeout: 5000 });
+        if (stdout.trim() === "stage")
+            return "stage";
+    }
+    catch {
+    }
+    return "prod";
+}
+export async function searchCommerceDocs(params) {
+    try {
+        const [token, env] = await Promise.all([
+            getImsToken(),
+            getAioEnvironment(),
+        ]);
+        const endpoint = RAG_ENDPOINTS[env];
+        const maxResults = params.maxResults ?? 5;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 30000);
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify({
+                    query: params.query,
+                    count: maxResults,
+                }),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+        if (!response.ok) {
+            if (response.status === 401) {
+                throw new Error("IMS token is expired or invalid. Run: aio auth login");
+            }
+            if (response.status === 429) {
+                throw new Error("Rate limit exceeded. Try again later.");
+            }
+            throw new Error(`Documentation service returned HTTP ${response.status}`);
+        }
+        const payload = (await response.json());
+        if (!payload.success || !payload.results) {
+            throw new Error("Invalid response from documentation service");
+        }
+        const results = payload.results.map((doc, i) => ({
+            rank: i + 1,
+            source: doc.metadata?.source ?? doc.source ?? "Unknown",
+            content: doc.content ?? "",
+            score: doc.score,
+            metadata: doc.metadata ?? {},
+        }));
+        return formatSuccessResponse(`Found ${results.length} result(s) for: "${params.query}"`, {
+            query: params.query,
+            index: payload.index,
+            indexSelection: payload.indexSelection ?? "backend-selected",
+            confidence: payload.confidence,
+            results,
+            note: "For structured dropin API data (slots, events, containers, GraphQL), use the dedicated registry tools instead.",
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("ENOENT") || message.includes("not found")) {
+            return formatExceptionResponse(new Error("The aio CLI is required for documentation search. Install it with: npm install -g @adobe/aio-cli && aio auth login"), "searching commerce documentation");
+        }
+        return formatExceptionResponse(error, "searching commerce documentation");
+    }
+}