@webpresso/agent-kit 0.21.0

package/dist/esm/e2e/config.d.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod';
+export declare const WEBPRESSO_CONFIG_FILE_NAME = "webpresso.config.ts";
+export declare const WEBPRESSO_CONFIG_EXPORT_NAME = "webpressoConfig";
+declare const webpressoConfigSchema: z.ZodObject<{
+    e2e: z.ZodOptional<z.ZodObject<{
+        hostAdapterModule: z.ZodString;
+        hostAdapterExport: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WebpressoConfig = z.infer<typeof webpressoConfigSchema>;
+export type WebpressoE2eConfig = NonNullable<WebpressoConfig['e2e']>;
+export declare class WebpressoConfigValidationError extends Error {
+    readonly configPath: string;
+    readonly issues: Array<{
+        path: string;
+        message: string;
+    }>;
+    constructor(configPath: string, issues: Array<{
+        path: string;
+        message: string;
+    }>);
+}
+export declare function defineWebpressoConfig<TConfig extends WebpressoConfig>(config: TConfig): TConfig;
+export declare function validateWebpressoConfig(config: unknown, configPath: string): WebpressoConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/esm/e2e/config.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export const WEBPRESSO_CONFIG_FILE_NAME = 'webpresso.config.ts';
+export const WEBPRESSO_CONFIG_EXPORT_NAME = 'webpressoConfig';
+const e2eWebpressoConfigSchema = z
+    .object({
+    hostAdapterModule: z.string().min(1, 'e2e.hostAdapterModule must not be empty.'),
+    hostAdapterExport: z.string().min(1, 'e2e.hostAdapterExport must not be empty.').optional(),
+})
+    .strict();
+const webpressoConfigSchema = z
+    .object({
+    e2e: e2eWebpressoConfigSchema.optional(),
+})
+    .strict();
+export class WebpressoConfigValidationError extends Error {
+    configPath;
+    issues;
+    constructor(configPath, issues) {
+        const formattedIssues = issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join('\n');
+        super(`Invalid webpresso config at ${configPath}:\n${formattedIssues}`);
+        this.configPath = configPath;
+        this.name = 'WebpressoConfigValidationError';
+        this.issues = issues;
+    }
+}
+export function defineWebpressoConfig(config) {
+    return config;
+}
+export function validateWebpressoConfig(config, configPath) {
+    const result = webpressoConfigSchema.safeParse(config);
+    if (!result.success) {
+        throw new WebpressoConfigValidationError(configPath, result.error.issues.map((issue) => ({
+            path: issue.path.join('.') || '<root>',
+            message: issue.message,
+        })));
+    }
+    return result.data;
+}
+//# sourceMappingURL=config.js.map

package/dist/esm/e2e/execution.d.ts

@@ -0,0 +1,14 @@
+import type { CommandConfig, PlannedE2eRunGroup } from './types.js';
+import type { GenericE2ePlanInput } from './run-planner.js';
+export declare function createE2eExecutionPlan(input: GenericE2ePlanInput, cwd?: string): Promise<PlannedE2eRunGroup[]>;
+export declare function plannedGroupsToCommandConfigs(groups: readonly PlannedE2eRunGroup[]): CommandConfig[];
+export declare function formatShellCommand(config: CommandConfig): string;
+export interface CommandExecutionSummary {
+    passed: boolean;
+    exitCode: number;
+    output: string;
+}
+export declare function runCommandConfigs(commands: readonly CommandConfig[], options?: {
+    signal?: AbortSignal;
+}): Promise<CommandExecutionSummary>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/esm/e2e/execution.js

@@ -0,0 +1,148 @@
+import { spawn } from 'node:child_process';
+import { loadConfiguredHostAdapter } from './load-host-adapter.js';
+import { planE2eRun, planGenericE2eRun } from './run-planner.js';
+export async function createE2eExecutionPlan(input, cwd = process.cwd()) {
+    // Explicit runner/config requests are generic-by-intent. Bypass host adapters
+    // so MCP callers can force a specific runner without inheriting suite defaults
+    // (e.g. host Playwright config when runner=vitest).
+    if (input.runner || input.config) {
+        return planGenericE2eRun({
+            suite: input.suite,
+            runner: input.runner,
+            config: input.config,
+            files: toArray(input.files),
+            headed: input.headed,
+            debug: input.debug,
+            reuseReset: input.reuseReset,
+            noSupervisor: input.noSupervisor,
+            workers: input.workers,
+            testList: input.testList,
+            passthrough: input.passthrough,
+        });
+    }
+    const hostAdapter = await loadConfiguredHostAdapter(cwd);
+    const files = toArray(input.files);
+    if (!hostAdapter?.adapter) {
+        return planGenericE2eRun({
+            suite: input.suite,
+            runner: input.runner,
+            config: input.config,
+            files,
+            headed: input.headed,
+            debug: input.debug,
+            reuseReset: input.reuseReset,
+            noSupervisor: input.noSupervisor,
+            workers: input.workers,
+            testList: input.testList,
+            passthrough: input.passthrough,
+        });
+    }
+    if (hostAdapter.adapter.buildExecutionPlan) {
+        return hostAdapter.adapter.buildExecutionPlan({
+            suite: input.suite,
+            file: files,
+            files,
+            headed: input.headed,
+            debug: input.debug,
+            reuseReset: input.reuseReset,
+            noSupervisor: input.noSupervisor,
+            workers: input.workers,
+            testList: input.testList,
+            passthrough: input.passthrough,
+        });
+    }
+    return planE2eRun({
+        hostAdapter: hostAdapter.adapter,
+        suite: input.suite,
+        file: files,
+        headed: input.headed,
+        debug: input.debug,
+        workers: input.workers,
+        testList: input.testList,
+        passthrough: input.passthrough,
+    });
+}
+export function plannedGroupsToCommandConfigs(groups) {
+    return groups.flatMap((group) => group.runs.map((run) => ({
+        command: run.command,
+        args: run.args,
+        env: normalizeEnv({ ...group.env, ...run.env }),
+    })));
+}
+export function formatShellCommand(config) {
+    return [config.command, ...config.args].map(shellQuote).join(' ');
+}
+export async function runCommandConfigs(commands, options = {}) {
+    let combinedOutput = '';
+    for (const command of commands) {
+        const result = await runCommand(command, options);
+        combinedOutput += result.output;
+        if (result.exitCode !== 0) {
+            return {
+                passed: false,
+                exitCode: result.exitCode,
+                output: combinedOutput,
+            };
+        }
+    }
+    return {
+        passed: true,
+        exitCode: 0,
+        output: combinedOutput,
+    };
+}
+async function runCommand(command, options) {
+    return new Promise((resolve) => {
+        const child = spawn(command.command, command.args, {
+            env: { ...process.env, ...command.env },
+            signal: options.signal,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (error) => {
+            const message = error.message || String(error);
+            resolve({
+                exitCode: 1,
+                output: [stdout, stderr, message].filter(Boolean).join(''),
+            });
+        });
+        child.on('close', (code, signal) => {
+            const exitCode = code ?? exitCodeFromSignal(signal);
+            resolve({
+                exitCode,
+                output: [stdout, stderr].filter(Boolean).join(''),
+            });
+        });
+    });
+}
+function exitCodeFromSignal(signal) {
+    if (!signal)
+        return 1;
+    const codeBySignal = {
+        SIGINT: 2,
+        SIGKILL: 9,
+        SIGTERM: 15,
+    };
+    return 128 + (codeBySignal[signal] ?? 15);
+}
+function shellQuote(value) {
+    return /^[A-Za-z0-9_./:=@+-]+$/u.test(value) ? value : `'${value.replace(/'/gu, "'\\''")}'`;
+}
+function toArray(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === 'string' ? [value] : [...value];
+}
+function normalizeEnv(env) {
+    if (!env || Object.keys(env).length === 0) {
+        return undefined;
+    }
+    return env;
+}
+//# sourceMappingURL=execution.js.map

package/dist/esm/e2e/host-adapter.d.ts

@@ -0,0 +1,6 @@
+import type { E2eHostAdapter } from './types.js';
+export declare const DEFAULT_HOST_ADAPTER_EXPORT_NAME = "webpressoE2eHostAdapter";
+export declare const LEGACY_HOST_ADAPTER_EXPORT_NAME = "webpressoE2eHostAdapter";
+export declare const FALLBACK_HOST_ADAPTER_EXPORT_NAMES: readonly ["webpressoE2eHostAdapter", "webpressoE2eHostAdapter", "default"];
+export declare function isE2eHostAdapter(value: unknown): value is E2eHostAdapter;
+//# sourceMappingURL=host-adapter.d.ts.map

package/dist/esm/e2e/host-adapter.js

@@ -0,0 +1,22 @@
+export const DEFAULT_HOST_ADAPTER_EXPORT_NAME = 'webpressoE2eHostAdapter';
+export const LEGACY_HOST_ADAPTER_EXPORT_NAME = 'webpressoE2eHostAdapter';
+export const FALLBACK_HOST_ADAPTER_EXPORT_NAMES = [
+    DEFAULT_HOST_ADAPTER_EXPORT_NAME,
+    LEGACY_HOST_ADAPTER_EXPORT_NAME,
+    'default',
+];
+export function isE2eHostAdapter(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.listSuites === 'function' &&
+        typeof candidate.resolveSuiteId === 'function' &&
+        (candidate.resolveSuiteGroup === undefined ||
+            typeof candidate.resolveSuiteGroup === 'function') &&
+        typeof candidate.normalizeFilePath === 'function' &&
+        typeof candidate.resolveSuiteForFile === 'function' &&
+        (candidate.buildExecutionPlan === undefined ||
+            typeof candidate.buildExecutionPlan === 'function'));
+}
+//# sourceMappingURL=host-adapter.js.map

package/dist/esm/e2e/index.d.ts

@@ -0,0 +1,9 @@
+export { defineWebpressoConfig, type WebpressoConfig } from './config.js';
+export { buildE2eCommand } from './command-builder.js';
+export { cloneE2eStepDefinition, cloneE2eSuiteDefinition, createCommandE2eHostAdapter, type CommandHostAdapterGroupDefinition, type CommandHostAdapterRunDefinition, type CreateCommandE2eHostAdapterOptions, } from './command-host-adapter.js';
+export { findWebpressoConfigPath, getWebpressoConfigPath, loadWebpressoConfig, loadWebpressoConfigSafe, loadConfiguredHostAdapter, loadHostAdapter, resolveWebpressoConfigPath, type LoadedHostAdapter, } from './load-host-adapter.js';
+export { DEFAULT_HOST_ADAPTER_EXPORT_NAME, FALLBACK_HOST_ADAPTER_EXPORT_NAMES, LEGACY_HOST_ADAPTER_EXPORT_NAME, isE2eHostAdapter, } from './host-adapter.js';
+export { defineE2eSuite, normalizeE2ePath, resolveE2eSuiteForPath, resolveE2eSuiteId, type NormalizeE2ePathOptions, } from './suite-registry.js';
+export { groupPlannedE2eRuns, normalizeRequestedFiles, planE2eRun, planGenericE2eRun, type GenericE2ePlanInput, } from './run-planner.js';
+export type { CommandConfig, E2eCommandRequest, E2eExecutionRequest, E2eHostAdapter, E2eRunPlannerOptions, E2eRunnerKind, E2eStepCommandOptions, E2eStepDefinition, E2eSuiteDefinition, PlannedE2eRunGroup, PlannedE2eRunStep, ResolvedE2eFile, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/e2e/index.js

@@ -0,0 +1,8 @@
+export { defineWebpressoConfig } from './config.js';
+export { buildE2eCommand } from './command-builder.js';
+export { cloneE2eStepDefinition, cloneE2eSuiteDefinition, createCommandE2eHostAdapter, } from './command-host-adapter.js';
+export { findWebpressoConfigPath, getWebpressoConfigPath, loadWebpressoConfig, loadWebpressoConfigSafe, loadConfiguredHostAdapter, loadHostAdapter, resolveWebpressoConfigPath, } from './load-host-adapter.js';
+export { DEFAULT_HOST_ADAPTER_EXPORT_NAME, FALLBACK_HOST_ADAPTER_EXPORT_NAMES, LEGACY_HOST_ADAPTER_EXPORT_NAME, isE2eHostAdapter, } from './host-adapter.js';
+export { defineE2eSuite, normalizeE2ePath, resolveE2eSuiteForPath, resolveE2eSuiteId, } from './suite-registry.js';
+export { groupPlannedE2eRuns, normalizeRequestedFiles, planE2eRun, planGenericE2eRun, } from './run-planner.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/e2e/load-host-adapter.d.ts

@@ -0,0 +1,43 @@
+import type { E2eHostAdapter } from './types.js';
+import { type WebpressoConfig } from './config.js';
+export interface LoadWebpressoConfigOptions {
+    cwd?: string;
+}
+export interface LoadedWebpressoConfig {
+    config: WebpressoConfig;
+    configPath: string;
+}
+export interface LoadedHostAdapter extends LoadedWebpressoConfig {
+    adapter: E2eHostAdapter;
+    exportName: string;
+    moduleSpecifier: string;
+}
+export declare class WebpressoConfigLoadError extends Error {
+    readonly configPath: string;
+    readonly cause: Error;
+    constructor(configPath: string, cause: Error);
+}
+export declare class WebpressoConfigExportError extends Error {
+    readonly configPath: string;
+    constructor(configPath: string);
+}
+export declare class HostAdapterModuleLoadError extends Error {
+    readonly moduleSpecifier: string;
+    readonly configPath: string;
+    readonly cause: Error;
+    constructor(moduleSpecifier: string, configPath: string, cause: Error);
+}
+export declare class HostAdapterExportError extends Error {
+    readonly moduleSpecifier: string;
+    readonly availableExports: readonly string[];
+    readonly attemptedExports: readonly string[];
+    constructor(moduleSpecifier: string, availableExports: readonly string[], attemptedExports: readonly string[]);
+}
+export declare function getWebpressoConfigPath(cwd?: string): string;
+export declare function resolveWebpressoConfigPath(cwd?: string): string;
+export declare function findWebpressoConfigPath(cwd?: string): string | null;
+export declare function loadWebpressoConfig(options?: LoadWebpressoConfigOptions): Promise<LoadedWebpressoConfig>;
+export declare function loadWebpressoConfigSafe(options?: LoadWebpressoConfigOptions): Promise<LoadedWebpressoConfig | null>;
+export declare function loadHostAdapter(options?: LoadWebpressoConfigOptions): Promise<LoadedHostAdapter | null>;
+export declare function loadConfiguredHostAdapter(cwd?: string): Promise<LoadedHostAdapter | null>;
+//# sourceMappingURL=load-host-adapter.d.ts.map

package/dist/esm/e2e/load-host-adapter.js

@@ -0,0 +1,150 @@
+import { existsSync } from 'node:fs';
+import { dirname, resolve, parse } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { WEBPRESSO_CONFIG_EXPORT_NAME, WEBPRESSO_CONFIG_FILE_NAME, validateWebpressoConfig, } from './config.js';
+import { FALLBACK_HOST_ADAPTER_EXPORT_NAMES, isE2eHostAdapter } from './host-adapter.js';
+export class WebpressoConfigLoadError extends Error {
+    configPath;
+    cause;
+    constructor(configPath, cause) {
+        super(`Failed to load ${WEBPRESSO_CONFIG_FILE_NAME} at ${configPath}: ${cause.message}`, cause instanceof Error ? { cause } : undefined);
+        this.configPath = configPath;
+        this.cause = cause;
+        this.name = 'WebpressoConfigLoadError';
+    }
+}
+export class WebpressoConfigExportError extends Error {
+    configPath;
+    constructor(configPath) {
+        super(`Expected ${WEBPRESSO_CONFIG_FILE_NAME} at ${configPath} to export ${WEBPRESSO_CONFIG_EXPORT_NAME}.`);
+        this.configPath = configPath;
+        this.name = 'WebpressoConfigExportError';
+    }
+}
+export class HostAdapterModuleLoadError extends Error {
+    moduleSpecifier;
+    configPath;
+    cause;
+    constructor(moduleSpecifier, configPath, cause) {
+        super(`Failed to load E2E host adapter module "${moduleSpecifier}" from ${configPath}: ${cause.message}`, cause instanceof Error ? { cause } : undefined);
+        this.moduleSpecifier = moduleSpecifier;
+        this.configPath = configPath;
+        this.cause = cause;
+        this.name = 'HostAdapterModuleLoadError';
+    }
+}
+export class HostAdapterExportError extends Error {
+    moduleSpecifier;
+    availableExports;
+    attemptedExports;
+    constructor(moduleSpecifier, availableExports, attemptedExports) {
+        const availableSummary = availableExports.length > 0 ? availableExports.join(', ') : '<no exports>';
+        const attemptedSummary = attemptedExports.join(', ');
+        super(`E2E host adapter module "${moduleSpecifier}" does not export a valid adapter. Tried ${attemptedSummary}. Available exports: ${availableSummary}.`);
+        this.moduleSpecifier = moduleSpecifier;
+        this.availableExports = availableExports;
+        this.attemptedExports = attemptedExports;
+        this.name = 'HostAdapterExportError';
+    }
+}
+export function getWebpressoConfigPath(cwd = process.cwd()) {
+    return resolve(cwd, WEBPRESSO_CONFIG_FILE_NAME);
+}
+export function resolveWebpressoConfigPath(cwd = process.cwd()) {
+    return findWebpressoConfigPath(cwd) ?? getWebpressoConfigPath(cwd);
+}
+export function findWebpressoConfigPath(cwd = process.cwd()) {
+    for (const searchDir of getSearchDirectories(cwd)) {
+        const configPath = getWebpressoConfigPath(searchDir);
+        if (existsSync(configPath)) {
+            return configPath;
+        }
+    }
+    return null;
+}
+export async function loadWebpressoConfig(options = {}) {
+    const configPath = resolveWebpressoConfigPath(options.cwd);
+    const configModule = await loadModuleNamespace(pathToFileURL(configPath).href, (cause) => {
+        throw new WebpressoConfigLoadError(configPath, cause);
+    });
+    if (!(WEBPRESSO_CONFIG_EXPORT_NAME in configModule)) {
+        throw new WebpressoConfigExportError(configPath);
+    }
+    return {
+        config: validateWebpressoConfig(configModule[WEBPRESSO_CONFIG_EXPORT_NAME], configPath),
+        configPath,
+    };
+}
+export async function loadWebpressoConfigSafe(options = {}) {
+    const configPath = findWebpressoConfigPath(options.cwd);
+    if (!configPath) {
+        return null;
+    }
+    return loadWebpressoConfig({ cwd: dirname(configPath) });
+}
+export async function loadHostAdapter(options = {}) {
+    const loadedConfig = await loadWebpressoConfigSafe(options);
+    if (!loadedConfig?.config.e2e) {
+        return null;
+    }
+    const moduleSpecifier = resolveModuleSpecifier(loadedConfig.config.e2e.hostAdapterModule, loadedConfig.configPath);
+    const hostAdapterModule = await loadModuleNamespace(moduleSpecifier, (cause) => {
+        throw new HostAdapterModuleLoadError(moduleSpecifier, loadedConfig.configPath, cause);
+    });
+    const exportNames = getHostAdapterExportLookupOrder(loadedConfig.config.e2e.hostAdapterExport);
+    for (const exportName of exportNames) {
+        if (!(exportName in hostAdapterModule)) {
+            continue;
+        }
+        const candidate = hostAdapterModule[exportName];
+        if (isE2eHostAdapter(candidate)) {
+            return {
+                ...loadedConfig,
+                adapter: candidate,
+                exportName,
+                moduleSpecifier,
+            };
+        }
+    }
+    throw new HostAdapterExportError(moduleSpecifier, Object.keys(hostAdapterModule), exportNames);
+}
+export async function loadConfiguredHostAdapter(cwd = process.cwd()) {
+    return loadHostAdapter({ cwd });
+}
+function getHostAdapterExportLookupOrder(explicitExportName) {
+    return explicitExportName
+        ? [explicitExportName, ...FALLBACK_HOST_ADAPTER_EXPORT_NAMES]
+        : [...FALLBACK_HOST_ADAPTER_EXPORT_NAMES];
+}
+function getSearchDirectories(cwd) {
+    const absoluteStart = resolve(cwd);
+    const rootDir = parse(absoluteStart).root;
+    const directories = [];
+    let current = absoluteStart;
+    while (true) {
+        directories.push(current);
+        if (current === rootDir) {
+            return directories;
+        }
+        current = dirname(current);
+    }
+}
+function resolveModuleSpecifier(moduleSpecifier, configPath) {
+    if (moduleSpecifier.startsWith('file:')) {
+        return moduleSpecifier;
+    }
+    if (moduleSpecifier.startsWith('.') || moduleSpecifier.startsWith('/')) {
+        return pathToFileURL(resolve(dirname(configPath), moduleSpecifier)).href;
+    }
+    return moduleSpecifier;
+}
+async function loadModuleNamespace(moduleSpecifier, onError) {
+    try {
+        const moduleNamespace = await import(moduleSpecifier);
+        return moduleNamespace;
+    }
+    catch (error) {
+        onError(error);
+    }
+}
+//# sourceMappingURL=load-host-adapter.js.map

package/dist/esm/e2e/run-planner.d.ts

@@ -0,0 +1,11 @@
+import type { E2eCommandRequest, E2eHostAdapter, E2eRunPlannerOptions, E2eStepDefinition, PlannedE2eRunGroup, PlannedE2eRunStep } from './types.js';
+export interface GenericE2ePlanInput extends E2eCommandRequest {
+    suite?: string;
+    runner?: E2eStepDefinition['runner'];
+    config?: string;
+}
+export declare function planGenericE2eRun(input: GenericE2ePlanInput): PlannedE2eRunGroup[];
+export declare function planE2eRun(options: E2eRunPlannerOptions): PlannedE2eRunGroup[];
+export declare function groupPlannedE2eRuns(runs: readonly PlannedE2eRunStep[]): PlannedE2eRunGroup[];
+export declare function normalizeRequestedFiles(files: readonly string[], hostAdapter?: E2eHostAdapter): string[];
+//# sourceMappingURL=run-planner.d.ts.map

package/dist/esm/e2e/run-planner.js

@@ -0,0 +1,186 @@
+import { buildE2eCommand } from './command-builder.js';
+import { defineE2eSuite, normalizeE2ePath } from './suite-registry.js';
+function defaultConfigPathForRunner(runner) {
+    switch (runner) {
+        case 'vitest':
+            return 'vitest.config.ts';
+        case 'command':
+            return undefined;
+        case 'playwright':
+        default:
+            return 'playwright.config.ts';
+    }
+}
+export function planGenericE2eRun(input) {
+    const runner = input.runner ?? 'playwright';
+    const suite = defineE2eSuite({
+        id: input.suite ?? 'default',
+        fileMatchers: [],
+        batchKey: input.suite ?? 'default',
+        steps: [
+            {
+                runner,
+                logName: input.suite ?? 'default',
+                configPath: input.config ?? defaultConfigPathForRunner(runner),
+                supportsHeaded: runner !== 'vitest' && runner !== 'command',
+                supportsDebug: runner !== 'vitest' && runner !== 'command',
+            },
+        ],
+    });
+    return planE2eRunsFromSuites({
+        suites: [suite],
+        requestedSuiteIds: [suite.id],
+        normalizedFilesBySuite: new Map([[suite.id, [...(input.files ?? [])]]]),
+        hasRequestedFiles: (input.files?.length ?? 0) > 0,
+        request: input,
+    });
+}
+export function planE2eRun(options) {
+    const requestedSuiteIds = resolveRequestedSuiteIds(options);
+    const normalizedFilesBySuite = new Map();
+    for (const file of options.file ?? []) {
+        const resolved = options.hostAdapter.resolveSuiteForFile(file);
+        if (!resolved) {
+            throw new Error(`Unknown E2E file path: ${file}`);
+        }
+        const currentFiles = normalizedFilesBySuite.get(resolved.suiteId) ?? [];
+        currentFiles.push(resolved.normalizedPath);
+        normalizedFilesBySuite.set(resolved.suiteId, currentFiles);
+    }
+    return planE2eRunsFromSuites({
+        suites: options.hostAdapter.listSuites(),
+        requestedSuiteIds,
+        normalizedFilesBySuite,
+        hasRequestedFiles: (options.file?.length ?? 0) > 0,
+        request: options,
+    });
+}
+function planE2eRunsFromSuites(options) {
+    const runs = [];
+    for (const suiteId of options.requestedSuiteIds) {
+        const suite = options.suites.find((candidate) => candidate.id === suiteId);
+        if (!suite) {
+            throw new Error(`Unknown E2E suite: ${suiteId}`);
+        }
+        assertRunnerFlagsSupported(suite, options.request);
+        for (const step of suite.steps) {
+            const selectedFiles = selectStepFiles(step, suite, options.normalizedFilesBySuite.get(suite.id) ?? []);
+            if (options.hasRequestedFiles && selectedFiles.length === 0) {
+                continue;
+            }
+            const command = buildE2eCommand({
+                step,
+                files: selectedFiles,
+                headed: options.request.headed,
+                debug: options.request.debug,
+                workers: options.request.workers,
+                testList: options.request.testList,
+                passthrough: options.request.passthrough,
+            });
+            runs.push({
+                suiteId: suite.id,
+                batchKey: step.batchKey ?? suite.batchKey,
+                envProfile: step.envProfile ?? suite.envProfile,
+                runner: step.runner,
+                logName: step.logName,
+                reportDir: step.reportDir,
+                command: command.command,
+                args: command.args,
+                env: normalizeEnv({ ...suite.env, ...step.env, ...command.env }),
+            });
+        }
+    }
+    return groupPlannedE2eRuns(runs);
+}
+function resolveRequestedSuiteIds(options) {
+    if ((options.file?.length ?? 0) > 0) {
+        const requestedSuites = new Set();
+        for (const file of options.file ?? []) {
+            const resolved = options.hostAdapter.resolveSuiteForFile(file);
+            if (!resolved) {
+                throw new Error(`Unknown E2E file path: ${file}`);
+            }
+            requestedSuites.add(resolved.suiteId);
+        }
+        return options.hostAdapter
+            .listSuites()
+            .map((suite) => suite.id)
+            .filter((suiteId) => requestedSuites.has(suiteId));
+    }
+    if (options.suite) {
+        const group = options.hostAdapter.resolveSuiteGroup?.(options.suite);
+        if (group?.length) {
+            return [...group];
+        }
+        const suiteId = options.hostAdapter.resolveSuiteId(options.suite);
+        if (!suiteId) {
+            throw new Error(`Unknown E2E suite: ${options.suite}`);
+        }
+        return [suiteId];
+    }
+    return options.hostAdapter
+        .listSuites()
+        .slice(0, 1)
+        .map((suite) => suite.id);
+}
+function assertRunnerFlagsSupported(suite, request) {
+    if (request.headed && !suite.steps.some((step) => step.supportsHeaded)) {
+        throw new Error(`--headed is only supported for headed-capable suites. Received suite: ${suite.id}`);
+    }
+    if (request.debug && !suite.steps.some((step) => step.supportsDebug)) {
+        throw new Error(`--debug is only supported for debug-capable suites. Received suite: ${suite.id}`);
+    }
+}
+function selectStepFiles(step, suite, selectedFiles) {
+    if (selectedFiles.length === 0) {
+        return step.fixedFiles ? [...step.fixedFiles] : [];
+    }
+    if (step.fixedFiles?.length) {
+        return selectedFiles.filter((file) => step.fixedFiles?.includes(file));
+    }
+    const otherFixedFiles = new Set(suite.steps
+        .filter((candidate) => candidate !== step)
+        .flatMap((candidate) => candidate.fixedFiles ?? []));
+    if (otherFixedFiles.size > 0) {
+        return selectedFiles.filter((file) => !otherFixedFiles.has(file));
+    }
+    return [...selectedFiles];
+}
+export function groupPlannedE2eRuns(runs) {
+    const groups = new Map();
+    for (const run of runs) {
+        const key = `${run.batchKey}::${run.envProfile ?? 'none'}::${stableEnvKey(run.env)}`;
+        const existing = groups.get(key);
+        if (existing) {
+            existing.runs.push(run);
+            continue;
+        }
+        groups.set(key, {
+            batchKey: run.batchKey,
+            envProfile: run.envProfile,
+            env: normalizeEnv(run.env),
+            runs: [run],
+        });
+    }
+    return [...groups.values()];
+}
+export function normalizeRequestedFiles(files, hostAdapter) {
+    return hostAdapter
+        ? files.map((file) => hostAdapter.normalizeFilePath(file))
+        : files.map((file) => normalizeE2ePath(file));
+}
+function stableEnvKey(env) {
+    if (!env || Object.keys(env).length === 0) {
+        return 'none';
+    }
+    return JSON.stringify(Object.keys(env)
+        .toSorted()
+        .map((key) => [key, env[key]]));
+}
+function normalizeEnv(env) {
+    if (!env || Object.keys(env).length === 0) {
+        return undefined;
+    }
+    return env;
+}
+//# sourceMappingURL=run-planner.js.map