donobu 5.57.1 → 5.60.0

package/dist/cli/donobu-cli.js

@@ -1177,6 +1177,10 @@ async function postProcessTriageRun(context, originalPlaywrightArgs, reportPath)
         entries = await fs_1.promises.readdir(context.runDir);
     }
     catch (error) {
+        if (error.code === 'ENOENT') {
+            Logger_1.appLogger.info(`No failure evidence found in ${context.runDir}.`);
+            return generatedPlans;
+        }
         Logger_1.appLogger.error(`Unable to read test-failure triage directory ${context.runDir}.`, error);
         return generatedPlans;
     }

package/dist/codegen/CodeGenerator.js

@@ -76,6 +76,7 @@ const SummarizeLearningsTool_1 = require("../tools/SummarizeLearningsTool");
 const WaitTool_1 = require("../tools/WaitTool");
 const JsonUtils_1 = require("../utils/JsonUtils");
 const MiscUtils_1 = require("../utils/MiscUtils");
+const TargetCodeGenerator_1 = require("./TargetCodeGenerator");
 function getLocalPlaywrightVersion() {
     const pkgPath = require.resolve('playwright/package.json');
     const pkgJson = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
@@ -112,6 +113,28 @@ function computeRuntimeCacheKeyFields(toolCalls, defaultToolNames, minimalToolNa
         maxToolCalls: resolvedMaxToolCalls,
     };
 }
+/**
+ * Built-in code generator for the web (Playwright) target. Owns the full web
+ * spec/cache output; non-web targets (API, mobile, …) register their own
+ * generators, which may emit an entirely different shape.
+ */
+const webCodeGenerator = {
+    targetType: 'web',
+    generateClassicScript: (ctx) => getFlowAsPlaywrightScript(ctx.flowMetadata, ctx.toolCalls, ctx.options, ctx.toolRegistry),
+    generateAiScript: (ctx) => getFlowAsAiPlaywrightScript(ctx.flowMetadata, ctx.toolCalls, ctx.options, ctx.toolRegistry),
+    buildCacheEntry: (ctx) => cacheEntryBuilder_1.PageAiCacheEntryBuilder.fromMetadata(ctx.pageUrl, ctx.metadata, ctx.toolCalls),
+    cachePageUrl: (metadata) => {
+        const website = metadata.web?.targetWebsite ?? '';
+        try {
+            return new URL(website).hostname;
+        }
+        catch {
+            return website;
+        }
+    },
+    requiresBrowserInstall: () => true,
+};
+(0, TargetCodeGenerator_1.registerCodeGenerator)(webCodeGenerator);
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
 async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options = {}, toolRegistry) {
     // These tools are not supported in the generated script because they have
@@ -166,12 +189,10 @@ async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options = {},
             .replace(/\n/g, '\\n')
             // Escape carriage returns.
             .replace(/\r/g, '\\r')
-        : `Test for ${flowMetadata.web?.targetWebsite ?? 'flow'}`;
+        : `Test for ${getFlowTargetLabel(flowMetadata)}`;
     const scriptedToolCalls = toolCalls
         .filter((toolCall) => !unsupportedToolsByName.has(toolCall.name))
-        .map((toolCall) => {
-        return convertProposedToolCallToPlaywrightCode(toolCall);
-    })
+        .map((toolCall) => convertProposedToolCallToPlaywrightCode(toolCall))
         .join('\n\n');
     const annotationsLiteral = combinedAnnotations.length > 0
         ? JSON.stringify({ annotation: combinedAnnotations }, null, 2)
@@ -185,7 +206,7 @@ const extractedObject = await page.ai.extract(
 testInfo.attach('extracted-object', { body: JSON.stringify(extractedObject), contentType: 'application/json' });`
         : '';
     const needsExpectImport = toolCalls.some((toolCall) => toolCall.name === AssertPageTool_1.AssertPageTool.NAME);
-    const needsJsonSchemaToZodImport = flowMetadata.resultJsonSchema;
+    const needsJsonSchemaToZodImport = !!flowMetadata.resultJsonSchema;
     const preamble = gptSetupNote.trim().length > 0
         ? `/**
 ${gptSetupNote}*/`
@@ -207,9 +228,10 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, too
     const [firstToolCall, ...remaingToolCalls] = toolCalls;
     // If the first tool call is "GoToWebpage", then we peel it off and treat it
     // specially.
-    const specialCaseGoto = firstToolCall.name === GoToWebpageTool_1.GoToWebpageTool.NAME && remaingToolCalls.length > 0;
+    const specialCaseGoto = firstToolCall?.name === GoToWebpageTool_1.GoToWebpageTool.NAME && remaingToolCalls.length > 0;
     const cachePath = (0, cacheLocator_1.relativePageAiCachePathForSource)(node_path_1.default.join('tests', getTestFileName(flowMetadata)));
-    const gptSetupNote = ` * This test replays a recorded Donobu flow via \`page.ai(...)\` using the cached
+    const aiHelper = 'page.ai';
+    const gptSetupNote = ` * This test replays a recorded Donobu flow via \`${aiHelper}(...)\` using the cached
  * tool calls stored for this spec in \`${cachePath}\`.
  * If the cache entry is missing or the parameters change, the run falls back
  * to autonomous mode and will require a GPT API key (e.g. DONOBU_API_KEY,
@@ -225,10 +247,10 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, too
             .replace(/\n/g, '\\n')
             // Escape carriage returns.
             .replace(/\r/g, '\\r')
-        : `Test for ${flowMetadata.web?.targetWebsite ?? 'flow'}`;
+        : `Test for ${getFlowTargetLabel(flowMetadata)}`;
     const instructionSource = flowMetadata.overallObjective?.trim()
         ? flowMetadata.overallObjective
-        : `Replay the recorded flow for ${flowMetadata.web?.targetWebsite ?? 'flow'}`;
+        : `Replay the recorded flow for ${getFlowTargetLabel(flowMetadata)}`;
     const sanitizedInstruction = sanitizeForTemplateLiteral(instructionSource);
     const annotations = [
         ...(options?.flowAnnotations?.[flowMetadata.id] ?? []),
@@ -265,8 +287,8 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, too
     }
     const aiOptionsLiteral = optionsLines.length > 0 ? `{${optionsLines.join(',')}}` : '';
     const aiCallExpression = optionsLines.length > 0
-        ? `page.ai(\`${sanitizedInstruction}\`, ${aiOptionsLiteral})`
-        : `page.ai(\`${sanitizedInstruction}\`)`;
+        ? `${aiHelper}(\`${sanitizedInstruction}\`, ${aiOptionsLiteral})`
+        : `${aiHelper}(\`${sanitizedInstruction}\`)`;
     const needsTestInfo = flowMetadata.resultJsonSchema !== null;
     const aiInvocation = needsTestInfo
         ? `const extractedObj = await ${aiCallExpression};
@@ -479,29 +501,29 @@ async function buildCacheContents(flowsWithToolCalls, toolRegistry) {
     const defaultToolNames = new Set(toolRegistry.defaultTools().map((tool) => tool.name));
     const minimalToolNames = new Set(toolRegistry.minimalTools().map((t) => t.name));
     const entries = flowsWithToolCalls
-        // We can only create page.ai caches for flows that have an objective.
-        .filter(({ metadata }) => metadata.overallObjective?.trim() &&
+        // We can only create ai caches for targets that codegen knows how to
+        // replay (web + any plugin with a registered generator), with an objective.
+        .filter(({ metadata }) => (0, TargetCodeGenerator_1.hasCodeGenerator)(metadata.target) &&
+        metadata.overallObjective?.trim() &&
         (metadata.runMode === 'AUTONOMOUS' ||
             metadata.runMode === 'SUPERVISED'))
         .map(({ metadata, toolCalls }) => {
+        // Filtered above on hasCodeGenerator, so this is defined.
+        const generator = (0, TargetCodeGenerator_1.getCodeGenerator)(metadata.target);
         const [firstToolCall, ...remaingToolCalls] = toolCalls;
-        // If the first tool call is "GoToWebpage", then we peel it off and treat it
-        // specially (i.e. it will be an explicit tool call in the generated test file).
+        // A leading GoToWebpage is peeled off (it becomes an explicit nav in the
+        // generated spec). Naturally a no-op for non-web targets, which never
+        // emit GoToWebpage.
         const specialCaseGoto = firstToolCall?.name === GoToWebpageTool_1.GoToWebpageTool.NAME &&
             remaingToolCalls.length > 0;
         const toolCallsForCache = specialCaseGoto ? remaingToolCalls : toolCalls;
-        // Extract hostname from URL for cache key to allow caching across different
-        // paths and query parameters on the same domain
-        let pageUrlForCache;
-        try {
-            const url = new URL(metadata.web?.targetWebsite ?? '');
-            pageUrlForCache = url.hostname;
-        }
-        catch {
-            // Fallback to full URL if parsing fails
-            pageUrlForCache = metadata.web?.targetWebsite ?? '';
-        }
-        const cacheEntry = cacheEntryBuilder_1.PageAiCacheEntryBuilder.fromMetadata(pageUrlForCache, metadata, toolCallsForCache);
+        // Cache key pageUrl (e.g. hostname) is target-specific.
+        const pageUrlForCache = generator.cachePageUrl(metadata);
+        const cacheEntry = generator.buildCacheEntry({
+            pageUrl: pageUrlForCache,
+            metadata,
+            toolCalls: toolCallsForCache,
+        });
         // Compute allowedTools and maxToolCalls as the runtime will see them,
         // so the cache lock file keys match the keys built by PageAi.buildDescriptor
         // when the generated test code is executed.
@@ -738,13 +760,18 @@ async function generatePlaywrightConfig(flows, storageStatePaths, options) {
         projects.push(generateProjectConfig(projectName, flow, storageStatePath));
     }
     const { areElementIdsVolatile, disableSelectorFailover, runInHeadedMode, slowMotionDelay, } = options;
-    const useConfig = {
-        screenshot: 'on',
-        video: 'on',
-        ...(runInHeadedMode && { headless: !runInHeadedMode }),
-        ...(slowMotionDelay &&
-            slowMotionDelay > 0 && { launchOptions: { slowMo: slowMotionDelay } }),
-    };
+    const hasBrowserFlows = flows.some((flow) => (0, TargetCodeGenerator_1.getCodeGenerator)(flow.target)?.requiresBrowserInstall(flow) ?? false);
+    const useConfig = hasBrowserFlows
+        ? {
+            screenshot: 'on',
+            video: 'on',
+            ...(runInHeadedMode && { headless: !runInHeadedMode }),
+            ...(slowMotionDelay &&
+                slowMotionDelay > 0 && {
+                launchOptions: { slowMo: slowMotionDelay },
+            }),
+        }
+        : {};
     const selfHealingOptions = {
         areElementIdsVolatile,
         disableSelectorFailover,
@@ -783,6 +810,14 @@ function generateProjectConfig(projectName, flow, storageStatePath) {
     // Round up to the nearest 10000ms
     const timeoutMilliseconds = Math.max(minimumTimeoutMilliseconds, Math.ceil(calculatedTimeout / 10000) * 10000);
     const testMatch = `tests/${getTestFileName(flow)}`;
+    if (!((0, TargetCodeGenerator_1.getCodeGenerator)(flow.target)?.requiresBrowserInstall(flow) ?? true)) {
+        return `{
+  name: '${projectName}',
+  testMatch: '${testMatch}',
+  use: {},
+  timeout: ${timeoutMilliseconds}
+}`;
+    }
     // Get device name from flow config, default to 'Desktop Chromium'
     const deviceName = flow.web?.browser?.using?.type === 'device'
         ? flow.web.browser.using.deviceName || 'Desktop Chromium'
@@ -804,12 +839,19 @@ async function generateTestFiles(flowsWithToolCalls, options, toolRegistry) {
     const files = [];
     const scriptVariant = options.playwrightScriptVariant === 'classic' ? 'classic' : 'ai';
     for (const { metadata, toolCalls } of flowsWithToolCalls) {
+        const generator = (0, TargetCodeGenerator_1.getCodeGenerator)(metadata.target) ?? webCodeGenerator;
         const fileName = getTestFileName(metadata);
+        const ctx = {
+            flowMetadata: metadata,
+            toolCalls,
+            options,
+            toolRegistry,
+        };
         const content = scriptVariant === 'classic' ||
             !metadata.overallObjective?.trim() ||
             (metadata.runMode !== 'AUTONOMOUS' && metadata.runMode !== 'SUPERVISED')
-            ? await getFlowAsPlaywrightScript(metadata, toolCalls, options, toolRegistry)
-            : await getFlowAsAiPlaywrightScript(metadata, toolCalls, options, toolRegistry);
+            ? await generator.generateClassicScript(ctx)
+            : await generator.generateAiScript(ctx);
         files.push({
             path: `tests/${fileName}`,
             content,
@@ -827,7 +869,7 @@ function generatePackageJson(options) {
     return JSON.stringify({
         name: 'playwright-tests',
         version: '1.0.0',
-        description: 'Playwright-based website tests made with Donobu',
+        description: 'Playwright-based tests made with Donobu',
         scripts: {
             test: `donobu test${selfHealingArg}`,
         },
@@ -856,7 +898,7 @@ Some tests depend on pre-existing browser state (cookies, localStorage, etc.) fr
         : '';
     return `# Playwright Tests
 
-This project contains [Playwright](https://playwright.dev/)-based tests made with [Donobu](https://www.donobu.com/).
+This project contains [Playwright](https://playwright.dev/)-based web and API tests made with [Donobu](https://www.donobu.com/).
 
 ## Installation
 
@@ -879,6 +921,9 @@ npm test
 \`\`\`
 ${browserStatesSection}`;
 }
+function getFlowTargetLabel(flow) {
+    return flow.web?.targetWebsite ?? 'flow';
+}
 /**
  * Gets a project name for a flow
  */

package/dist/codegen/TargetCodeGenerator.d.ts

@@ -0,0 +1,54 @@
+import type { PageAiCacheEntry } from '../lib/ai/cache/cache';
+import type { ToolRegistry } from '../managers/ToolRegistry';
+import type { CodeGenerationOptions } from '../models/CodeGenerationOptions';
+import type { FlowMetadata } from '../models/FlowMetadata';
+import type { ProposedToolCall } from '../models/ProposedToolCall';
+/**
+ * Inputs for generating one flow's replay spec.
+ */
+export interface CodeGenContext {
+    flowMetadata: FlowMetadata;
+    toolCalls: ProposedToolCall[];
+    options: CodeGenerationOptions;
+    toolRegistry: ToolRegistry;
+}
+export interface CacheEntryContext {
+    pageUrl: string;
+    metadata: FlowMetadata;
+    toolCalls: ProposedToolCall[];
+}
+/**
+ * A target's code generator. This is an opaque, whole-artifact contract: core
+ * asks a generator to produce a flow's replay spec / cache entry and makes NO
+ * assumptions about the artifact's internals. Web (Playwright specs) is the
+ * built-in; other targets (API, mobile, …) register their own and are free to
+ * emit a completely different shape — or none. Deliberately NOT parameterized
+ * with web-spec knobs (fixtures, AI helpers, etc.): those would presume every
+ * target produces a Playwright test, which they do not.
+ */
+export interface TargetCodeGenerator {
+    readonly targetType: string;
+    /** Produce the deterministic ("classic") replay spec for one flow. */
+    generateClassicScript(ctx: CodeGenContext): Promise<string>;
+    /** Produce the AI/cache-backed replay spec for one flow. */
+    generateAiScript(ctx: CodeGenContext): Promise<string>;
+    /** Build the AI-cache entry (runSource) for one flow. */
+    buildCacheEntry(ctx: CacheEntryContext): PageAiCacheEntry;
+    /** Cache-key pageUrl for a flow of this target. */
+    cachePageUrl(metadata: FlowMetadata): string;
+    /**
+     * Whether flows of this target require a browser install in the generated
+     * project (drives CI setup and the Playwright project `use` block). A coarse
+     * capability question, not a directive about spec contents.
+     */
+    requiresBrowserInstall(metadata: FlowMetadata): boolean;
+}
+/** Register a target's code generator. Core registers `web`; plugins register
+ * their own at startup. */
+export declare function registerCodeGenerator(generator: TargetCodeGenerator): void;
+/** Resolve the generator for a target type, or `undefined` if none is
+ * registered (the caller decides how to handle unsupported targets). */
+export declare function getCodeGenerator(targetType: string): TargetCodeGenerator | undefined;
+/** Whether a code generator is registered for the given target type. */
+export declare function hasCodeGenerator(targetType: string): boolean;
+//# sourceMappingURL=TargetCodeGenerator.d.ts.map

package/dist/codegen/TargetCodeGenerator.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCodeGenerator = registerCodeGenerator;
+exports.getCodeGenerator = getCodeGenerator;
+exports.hasCodeGenerator = hasCodeGenerator;
+const registry = new Map();
+/** Register a target's code generator. Core registers `web`; plugins register
+ * their own at startup. */
+function registerCodeGenerator(generator) {
+    registry.set(generator.targetType, generator);
+}
+/** Resolve the generator for a target type, or `undefined` if none is
+ * registered (the caller decides how to handle unsupported targets). */
+function getCodeGenerator(targetType) {
+    return registry.get(targetType);
+}
+/** Whether a code generator is registered for the given target type. */
+function hasCodeGenerator(targetType) {
+    return registry.has(targetType);
+}
+//# sourceMappingURL=TargetCodeGenerator.js.map

package/dist/esm/cli/donobu-cli.js

@@ -1177,6 +1177,10 @@ async function postProcessTriageRun(context, originalPlaywrightArgs, reportPath)
         entries = await fs_1.promises.readdir(context.runDir);
     }
     catch (error) {
+        if (error.code === 'ENOENT') {
+            Logger_1.appLogger.info(`No failure evidence found in ${context.runDir}.`);
+            return generatedPlans;
+        }
         Logger_1.appLogger.error(`Unable to read test-failure triage directory ${context.runDir}.`, error);
         return generatedPlans;
     }

package/dist/esm/codegen/CodeGenerator.js

@@ -76,6 +76,7 @@ const SummarizeLearningsTool_1 = require("../tools/SummarizeLearningsTool");
 const WaitTool_1 = require("../tools/WaitTool");
 const JsonUtils_1 = require("../utils/JsonUtils");
 const MiscUtils_1 = require("../utils/MiscUtils");
+const TargetCodeGenerator_1 = require("./TargetCodeGenerator");
 function getLocalPlaywrightVersion() {
     const pkgPath = require.resolve('playwright/package.json');
     const pkgJson = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
@@ -112,6 +113,28 @@ function computeRuntimeCacheKeyFields(toolCalls, defaultToolNames, minimalToolNa
         maxToolCalls: resolvedMaxToolCalls,
     };
 }
+/**
+ * Built-in code generator for the web (Playwright) target. Owns the full web
+ * spec/cache output; non-web targets (API, mobile, …) register their own
+ * generators, which may emit an entirely different shape.
+ */
+const webCodeGenerator = {
+    targetType: 'web',
+    generateClassicScript: (ctx) => getFlowAsPlaywrightScript(ctx.flowMetadata, ctx.toolCalls, ctx.options, ctx.toolRegistry),
+    generateAiScript: (ctx) => getFlowAsAiPlaywrightScript(ctx.flowMetadata, ctx.toolCalls, ctx.options, ctx.toolRegistry),
+    buildCacheEntry: (ctx) => cacheEntryBuilder_1.PageAiCacheEntryBuilder.fromMetadata(ctx.pageUrl, ctx.metadata, ctx.toolCalls),
+    cachePageUrl: (metadata) => {
+        const website = metadata.web?.targetWebsite ?? '';
+        try {
+            return new URL(website).hostname;
+        }
+        catch {
+            return website;
+        }
+    },
+    requiresBrowserInstall: () => true,
+};
+(0, TargetCodeGenerator_1.registerCodeGenerator)(webCodeGenerator);
 /** Creates a Node.js Microsoft Playwright script to replay the given flow. */
 async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options = {}, toolRegistry) {
     // These tools are not supported in the generated script because they have
@@ -166,12 +189,10 @@ async function getFlowAsPlaywrightScript(flowMetadata, toolCalls, options = {},
             .replace(/\n/g, '\\n')
             // Escape carriage returns.
             .replace(/\r/g, '\\r')
-        : `Test for ${flowMetadata.web?.targetWebsite ?? 'flow'}`;
+        : `Test for ${getFlowTargetLabel(flowMetadata)}`;
     const scriptedToolCalls = toolCalls
         .filter((toolCall) => !unsupportedToolsByName.has(toolCall.name))
-        .map((toolCall) => {
-        return convertProposedToolCallToPlaywrightCode(toolCall);
-    })
+        .map((toolCall) => convertProposedToolCallToPlaywrightCode(toolCall))
         .join('\n\n');
     const annotationsLiteral = combinedAnnotations.length > 0
         ? JSON.stringify({ annotation: combinedAnnotations }, null, 2)
@@ -185,7 +206,7 @@ const extractedObject = await page.ai.extract(
 testInfo.attach('extracted-object', { body: JSON.stringify(extractedObject), contentType: 'application/json' });`
         : '';
     const needsExpectImport = toolCalls.some((toolCall) => toolCall.name === AssertPageTool_1.AssertPageTool.NAME);
-    const needsJsonSchemaToZodImport = flowMetadata.resultJsonSchema;
+    const needsJsonSchemaToZodImport = !!flowMetadata.resultJsonSchema;
     const preamble = gptSetupNote.trim().length > 0
         ? `/**
 ${gptSetupNote}*/`
@@ -207,9 +228,10 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, too
     const [firstToolCall, ...remaingToolCalls] = toolCalls;
     // If the first tool call is "GoToWebpage", then we peel it off and treat it
     // specially.
-    const specialCaseGoto = firstToolCall.name === GoToWebpageTool_1.GoToWebpageTool.NAME && remaingToolCalls.length > 0;
+    const specialCaseGoto = firstToolCall?.name === GoToWebpageTool_1.GoToWebpageTool.NAME && remaingToolCalls.length > 0;
     const cachePath = (0, cacheLocator_1.relativePageAiCachePathForSource)(node_path_1.default.join('tests', getTestFileName(flowMetadata)));
-    const gptSetupNote = ` * This test replays a recorded Donobu flow via \`page.ai(...)\` using the cached
+    const aiHelper = 'page.ai';
+    const gptSetupNote = ` * This test replays a recorded Donobu flow via \`${aiHelper}(...)\` using the cached
  * tool calls stored for this spec in \`${cachePath}\`.
  * If the cache entry is missing or the parameters change, the run falls back
  * to autonomous mode and will require a GPT API key (e.g. DONOBU_API_KEY,
@@ -225,10 +247,10 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, too
             .replace(/\n/g, '\\n')
             // Escape carriage returns.
             .replace(/\r/g, '\\r')
-        : `Test for ${flowMetadata.web?.targetWebsite ?? 'flow'}`;
+        : `Test for ${getFlowTargetLabel(flowMetadata)}`;
     const instructionSource = flowMetadata.overallObjective?.trim()
         ? flowMetadata.overallObjective
-        : `Replay the recorded flow for ${flowMetadata.web?.targetWebsite ?? 'flow'}`;
+        : `Replay the recorded flow for ${getFlowTargetLabel(flowMetadata)}`;
     const sanitizedInstruction = sanitizeForTemplateLiteral(instructionSource);
     const annotations = [
         ...(options?.flowAnnotations?.[flowMetadata.id] ?? []),
@@ -265,8 +287,8 @@ async function getFlowAsAiPlaywrightScript(flowMetadata, toolCalls, options, too
     }
     const aiOptionsLiteral = optionsLines.length > 0 ? `{${optionsLines.join(',')}}` : '';
     const aiCallExpression = optionsLines.length > 0
-        ? `page.ai(\`${sanitizedInstruction}\`, ${aiOptionsLiteral})`
-        : `page.ai(\`${sanitizedInstruction}\`)`;
+        ? `${aiHelper}(\`${sanitizedInstruction}\`, ${aiOptionsLiteral})`
+        : `${aiHelper}(\`${sanitizedInstruction}\`)`;
     const needsTestInfo = flowMetadata.resultJsonSchema !== null;
     const aiInvocation = needsTestInfo
         ? `const extractedObj = await ${aiCallExpression};
@@ -479,29 +501,29 @@ async function buildCacheContents(flowsWithToolCalls, toolRegistry) {
     const defaultToolNames = new Set(toolRegistry.defaultTools().map((tool) => tool.name));
     const minimalToolNames = new Set(toolRegistry.minimalTools().map((t) => t.name));
     const entries = flowsWithToolCalls
-        // We can only create page.ai caches for flows that have an objective.
-        .filter(({ metadata }) => metadata.overallObjective?.trim() &&
+        // We can only create ai caches for targets that codegen knows how to
+        // replay (web + any plugin with a registered generator), with an objective.
+        .filter(({ metadata }) => (0, TargetCodeGenerator_1.hasCodeGenerator)(metadata.target) &&
+        metadata.overallObjective?.trim() &&
         (metadata.runMode === 'AUTONOMOUS' ||
             metadata.runMode === 'SUPERVISED'))
         .map(({ metadata, toolCalls }) => {
+        // Filtered above on hasCodeGenerator, so this is defined.
+        const generator = (0, TargetCodeGenerator_1.getCodeGenerator)(metadata.target);
         const [firstToolCall, ...remaingToolCalls] = toolCalls;
-        // If the first tool call is "GoToWebpage", then we peel it off and treat it
-        // specially (i.e. it will be an explicit tool call in the generated test file).
+        // A leading GoToWebpage is peeled off (it becomes an explicit nav in the
+        // generated spec). Naturally a no-op for non-web targets, which never
+        // emit GoToWebpage.
         const specialCaseGoto = firstToolCall?.name === GoToWebpageTool_1.GoToWebpageTool.NAME &&
             remaingToolCalls.length > 0;
         const toolCallsForCache = specialCaseGoto ? remaingToolCalls : toolCalls;
-        // Extract hostname from URL for cache key to allow caching across different
-        // paths and query parameters on the same domain
-        let pageUrlForCache;
-        try {
-            const url = new URL(metadata.web?.targetWebsite ?? '');
-            pageUrlForCache = url.hostname;
-        }
-        catch {
-            // Fallback to full URL if parsing fails
-            pageUrlForCache = metadata.web?.targetWebsite ?? '';
-        }
-        const cacheEntry = cacheEntryBuilder_1.PageAiCacheEntryBuilder.fromMetadata(pageUrlForCache, metadata, toolCallsForCache);
+        // Cache key pageUrl (e.g. hostname) is target-specific.
+        const pageUrlForCache = generator.cachePageUrl(metadata);
+        const cacheEntry = generator.buildCacheEntry({
+            pageUrl: pageUrlForCache,
+            metadata,
+            toolCalls: toolCallsForCache,
+        });
         // Compute allowedTools and maxToolCalls as the runtime will see them,
         // so the cache lock file keys match the keys built by PageAi.buildDescriptor
         // when the generated test code is executed.
@@ -738,13 +760,18 @@ async function generatePlaywrightConfig(flows, storageStatePaths, options) {
         projects.push(generateProjectConfig(projectName, flow, storageStatePath));
     }
     const { areElementIdsVolatile, disableSelectorFailover, runInHeadedMode, slowMotionDelay, } = options;
-    const useConfig = {
-        screenshot: 'on',
-        video: 'on',
-        ...(runInHeadedMode && { headless: !runInHeadedMode }),
-        ...(slowMotionDelay &&
-            slowMotionDelay > 0 && { launchOptions: { slowMo: slowMotionDelay } }),
-    };
+    const hasBrowserFlows = flows.some((flow) => (0, TargetCodeGenerator_1.getCodeGenerator)(flow.target)?.requiresBrowserInstall(flow) ?? false);
+    const useConfig = hasBrowserFlows
+        ? {
+            screenshot: 'on',
+            video: 'on',
+            ...(runInHeadedMode && { headless: !runInHeadedMode }),
+            ...(slowMotionDelay &&
+                slowMotionDelay > 0 && {
+                launchOptions: { slowMo: slowMotionDelay },
+            }),
+        }
+        : {};
     const selfHealingOptions = {
         areElementIdsVolatile,
         disableSelectorFailover,
@@ -783,6 +810,14 @@ function generateProjectConfig(projectName, flow, storageStatePath) {
     // Round up to the nearest 10000ms
     const timeoutMilliseconds = Math.max(minimumTimeoutMilliseconds, Math.ceil(calculatedTimeout / 10000) * 10000);
     const testMatch = `tests/${getTestFileName(flow)}`;
+    if (!((0, TargetCodeGenerator_1.getCodeGenerator)(flow.target)?.requiresBrowserInstall(flow) ?? true)) {
+        return `{
+  name: '${projectName}',
+  testMatch: '${testMatch}',
+  use: {},
+  timeout: ${timeoutMilliseconds}
+}`;
+    }
     // Get device name from flow config, default to 'Desktop Chromium'
     const deviceName = flow.web?.browser?.using?.type === 'device'
         ? flow.web.browser.using.deviceName || 'Desktop Chromium'
@@ -804,12 +839,19 @@ async function generateTestFiles(flowsWithToolCalls, options, toolRegistry) {
     const files = [];
     const scriptVariant = options.playwrightScriptVariant === 'classic' ? 'classic' : 'ai';
     for (const { metadata, toolCalls } of flowsWithToolCalls) {
+        const generator = (0, TargetCodeGenerator_1.getCodeGenerator)(metadata.target) ?? webCodeGenerator;
         const fileName = getTestFileName(metadata);
+        const ctx = {
+            flowMetadata: metadata,
+            toolCalls,
+            options,
+            toolRegistry,
+        };
         const content = scriptVariant === 'classic' ||
             !metadata.overallObjective?.trim() ||
             (metadata.runMode !== 'AUTONOMOUS' && metadata.runMode !== 'SUPERVISED')
-            ? await getFlowAsPlaywrightScript(metadata, toolCalls, options, toolRegistry)
-            : await getFlowAsAiPlaywrightScript(metadata, toolCalls, options, toolRegistry);
+            ? await generator.generateClassicScript(ctx)
+            : await generator.generateAiScript(ctx);
         files.push({
             path: `tests/${fileName}`,
             content,
@@ -827,7 +869,7 @@ function generatePackageJson(options) {
     return JSON.stringify({
         name: 'playwright-tests',
         version: '1.0.0',
-        description: 'Playwright-based website tests made with Donobu',
+        description: 'Playwright-based tests made with Donobu',
         scripts: {
             test: `donobu test${selfHealingArg}`,
         },
@@ -856,7 +898,7 @@ Some tests depend on pre-existing browser state (cookies, localStorage, etc.) fr
         : '';
     return `# Playwright Tests
 
-This project contains [Playwright](https://playwright.dev/)-based tests made with [Donobu](https://www.donobu.com/).
+This project contains [Playwright](https://playwright.dev/)-based web and API tests made with [Donobu](https://www.donobu.com/).
 
 ## Installation
 
@@ -879,6 +921,9 @@ npm test
 \`\`\`
 ${browserStatesSection}`;
 }
+function getFlowTargetLabel(flow) {
+    return flow.web?.targetWebsite ?? 'flow';
+}
 /**
  * Gets a project name for a flow
  */

package/dist/esm/codegen/TargetCodeGenerator.d.ts

@@ -0,0 +1,54 @@
+import type { PageAiCacheEntry } from '../lib/ai/cache/cache';
+import type { ToolRegistry } from '../managers/ToolRegistry';
+import type { CodeGenerationOptions } from '../models/CodeGenerationOptions';
+import type { FlowMetadata } from '../models/FlowMetadata';
+import type { ProposedToolCall } from '../models/ProposedToolCall';
+/**
+ * Inputs for generating one flow's replay spec.
+ */
+export interface CodeGenContext {
+    flowMetadata: FlowMetadata;
+    toolCalls: ProposedToolCall[];
+    options: CodeGenerationOptions;
+    toolRegistry: ToolRegistry;
+}
+export interface CacheEntryContext {
+    pageUrl: string;
+    metadata: FlowMetadata;
+    toolCalls: ProposedToolCall[];
+}
+/**
+ * A target's code generator. This is an opaque, whole-artifact contract: core
+ * asks a generator to produce a flow's replay spec / cache entry and makes NO
+ * assumptions about the artifact's internals. Web (Playwright specs) is the
+ * built-in; other targets (API, mobile, …) register their own and are free to
+ * emit a completely different shape — or none. Deliberately NOT parameterized
+ * with web-spec knobs (fixtures, AI helpers, etc.): those would presume every
+ * target produces a Playwright test, which they do not.
+ */
+export interface TargetCodeGenerator {
+    readonly targetType: string;
+    /** Produce the deterministic ("classic") replay spec for one flow. */
+    generateClassicScript(ctx: CodeGenContext): Promise<string>;
+    /** Produce the AI/cache-backed replay spec for one flow. */
+    generateAiScript(ctx: CodeGenContext): Promise<string>;
+    /** Build the AI-cache entry (runSource) for one flow. */
+    buildCacheEntry(ctx: CacheEntryContext): PageAiCacheEntry;
+    /** Cache-key pageUrl for a flow of this target. */
+    cachePageUrl(metadata: FlowMetadata): string;
+    /**
+     * Whether flows of this target require a browser install in the generated
+     * project (drives CI setup and the Playwright project `use` block). A coarse
+     * capability question, not a directive about spec contents.
+     */
+    requiresBrowserInstall(metadata: FlowMetadata): boolean;
+}
+/** Register a target's code generator. Core registers `web`; plugins register
+ * their own at startup. */
+export declare function registerCodeGenerator(generator: TargetCodeGenerator): void;
+/** Resolve the generator for a target type, or `undefined` if none is
+ * registered (the caller decides how to handle unsupported targets). */
+export declare function getCodeGenerator(targetType: string): TargetCodeGenerator | undefined;
+/** Whether a code generator is registered for the given target type. */
+export declare function hasCodeGenerator(targetType: string): boolean;
+//# sourceMappingURL=TargetCodeGenerator.d.ts.map

package/dist/esm/codegen/TargetCodeGenerator.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCodeGenerator = registerCodeGenerator;
+exports.getCodeGenerator = getCodeGenerator;
+exports.hasCodeGenerator = hasCodeGenerator;
+const registry = new Map();
+/** Register a target's code generator. Core registers `web`; plugins register
+ * their own at startup. */
+function registerCodeGenerator(generator) {
+    registry.set(generator.targetType, generator);
+}
+/** Resolve the generator for a target type, or `undefined` if none is
+ * registered (the caller decides how to handle unsupported targets). */
+function getCodeGenerator(targetType) {
+    return registry.get(targetType);
+}
+/** Whether a code generator is registered for the given target type. */
+function hasCodeGenerator(targetType) {
+    return registry.has(targetType);
+}
+//# sourceMappingURL=TargetCodeGenerator.js.map