@esimplicitylabs/katalyst-xspec 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,881 @@
+import * as playwright_bdd from 'playwright-bdd';
+export { test as baseTest } from 'playwright-bdd';
+import * as _playwright_test from '@playwright/test';
+import { APIResponse, PlaywrightTestArgs, PlaywrightWorkerArgs, APIRequestContext, Page } from '@playwright/test';
+export { isFlagEnabled, registerAllSteps, registerApiAssertionSteps, registerApiAuthSteps, registerApiHttpSteps, registerApiSteps, registerDebugSteps, registerFlagSteps, registerFormSteps, registerHybridSteps, registerHybridSuite, registerLayoutSteps, registerSharedCleanupSteps, registerSharedSteps, registerSharedVarSteps, registerTuiBasicSteps, registerTuiSteps, registerTuiWizardSteps, registerUiAuthSteps, registerUiBasicSteps, registerUiSteps, registerWizardSteps, setFlag } from './steps/index.js';
+
+type CleanupItem = {
+    method: 'DELETE' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+};
+type World = {
+    vars: Record<string, string>;
+    headers: Record<string, string>;
+    cleanup: CleanupItem[];
+    skipCleanup?: boolean;
+    lastResponse?: APIResponse;
+    lastStatus?: number;
+    lastText?: string;
+    lastJson?: unknown;
+    lastHeaders?: Record<string, string>;
+    lastContentType?: string;
+};
+declare function initWorld(): World;
+
+type ApiResult = {
+    status: number;
+    text: string;
+    json?: unknown;
+    headers: Record<string, string>;
+    contentType?: string;
+    response: APIResponse;
+};
+type ApiMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+interface ApiPort {
+    sendJson(method: ApiMethod, path: string, body?: unknown, headers?: Record<string, string>): Promise<ApiResult>;
+    sendForm(method: 'POST' | 'PUT' | 'PATCH', path: string, form: Record<string, string>, headers?: Record<string, string>): Promise<ApiResult>;
+}
+
+type UiClickMode = 'click' | 'dispatch click' | 'force click' | 'force dispatch click';
+type UiInputMode = 'type' | 'fill' | 'choose';
+type UiUrlAssertMode = 'contains' | 'doesntContain' | 'equals';
+type UiLocatorMethod = 'text' | 'label' | 'placeholder' | 'role' | 'test ID' | 'alternative text' | 'title' | 'locator';
+type UiElementState = 'visible' | 'hidden' | 'editable' | 'disabled' | 'enabled' | 'read-only';
+interface UiPort {
+    goto(path: string): Promise<void>;
+    clickButton(name: string): Promise<void>;
+    clickLink(name: string): Promise<void>;
+    fillPlaceholder(placeholder: string, value: string): Promise<void>;
+    fillLabel(label: string, value: string): Promise<void>;
+    expectText(text: string): Promise<void>;
+    expectUrlContains(part: string): Promise<void>;
+    goBack(): Promise<void>;
+    reload(): Promise<void>;
+    waitSeconds(seconds: number): Promise<void>;
+    waitForPageLoad(): Promise<void>;
+    getCurrentUrl(): Promise<string>;
+    zoomTo(scale: number): Promise<void>;
+    typeText(text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    clickElementThatContains(clickMode: UiClickMode, elementType: string, text: string): Promise<void>;
+    clickElementWith(clickMode: UiClickMode, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    fillDropdown(value: string, dropdownLabel: string): Promise<void>;
+    inputInElement(action: UiInputMode, value: string, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    expectUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectNewTabUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectElementWithTextVisible(elementType: string, text: string, shouldBeVisible: boolean): Promise<void>;
+    expectElementState(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState): Promise<void>;
+    expectElementStateWithin(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState, seconds: number): Promise<void>;
+}
+
+interface AuthPort {
+    apiLoginAsAdmin(world: World): Promise<void>;
+    apiLoginAsUser(world: World): Promise<void>;
+    apiSetBearer(world: World, token: string): void;
+    uiLoginAsAdmin(world: World): Promise<void>;
+    uiLoginAsUser(world: World): Promise<void>;
+}
+
+interface CleanupPort {
+    registerFromVar(world: World, varName: string, id: unknown, meta?: unknown): void;
+}
+
+/**
+ * TUI Port Interface
+ *
+ * Defines the contract for terminal user interface testing operations.
+ * Aligned with UiPort patterns for consistency across testing approaches.
+ */
+/** Keyboard modifier keys for key combinations */
+type TuiKeyModifiers = {
+    ctrl?: boolean;
+    alt?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+};
+/** Options for wait operations */
+type TuiWaitOptions = {
+    /** Maximum time to wait in milliseconds */
+    timeout?: number;
+    /** Polling interval in milliseconds */
+    interval?: number;
+};
+/** Captured screen state */
+type TuiScreenCapture = {
+    /** Full screen text content */
+    text: string;
+    /** Screen content split by lines */
+    lines: string[];
+    /** Timestamp when capture was taken */
+    timestamp: number;
+    /** Terminal dimensions */
+    size: {
+        cols: number;
+        rows: number;
+    };
+};
+/** Result of snapshot comparison */
+type TuiSnapshotResult = {
+    /** Whether the snapshot matched */
+    pass: boolean;
+    /** Diff output if snapshot didn't match */
+    diff?: string;
+    /** Path to the snapshot file */
+    snapshotPath?: string;
+};
+/** Mouse button types */
+type TuiMouseButton = 'left' | 'right' | 'middle';
+/** Mouse event types */
+type TuiMouseEventType = 'click' | 'down' | 'up' | 'drag' | 'scroll';
+/** Mouse event configuration */
+type TuiMouseEvent = {
+    type: TuiMouseEventType;
+    position: {
+        x: number;
+        y: number;
+    };
+    button?: TuiMouseButton;
+};
+/** Configuration for TUI adapter initialization */
+type TuiConfig = {
+    /** Command to start the TUI application (e.g., ['node', 'cli.js']) */
+    command: string[];
+    /** Terminal size (defaults to 80x24) */
+    size?: {
+        cols: number;
+        rows: number;
+    };
+    /** Working directory for the command */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Enable debug output */
+    debug?: boolean;
+    /** Directory for snapshot storage */
+    snapshotDir?: string;
+    /** Shell to use (defaults to system shell) */
+    shell?: string;
+};
+/**
+ * Port interface for terminal user interface testing.
+ *
+ * This interface follows the same patterns as UiPort to enable:
+ * - Consistent step definitions across UI and TUI tests
+ * - Easy mental model for test authors
+ * - Potential for shared/hybrid testing scenarios
+ */
+interface TuiPort {
+    /**
+     * Start the TUI application.
+     * Creates a new terminal session and launches the configured command.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the TUI application.
+     * Terminates the terminal session and cleans up resources.
+     */
+    stop(): Promise<void>;
+    /**
+     * Restart the TUI application.
+     * Equivalent to stop() followed by start().
+     */
+    restart(): Promise<void>;
+    /**
+     * Check if the TUI application is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Type text into the terminal.
+     * Similar to UiPort.typeText - sends characters one by one.
+     * @param text - The text to type
+     * @param options - Optional typing options
+     */
+    typeText(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    /**
+     * Press a keyboard key, optionally with modifiers.
+     * Similar to UiPort.pressKey.
+     * @param key - Key name (e.g., 'enter', 'tab', 'up', 'down', 'f1')
+     * @param modifiers - Optional modifier keys
+     */
+    pressKey(key: string, modifiers?: TuiKeyModifiers): Promise<void>;
+    /**
+     * Send raw text without any interpretation.
+     * Useful for pasting content or sending special sequences.
+     * @param text - Raw text to send
+     */
+    sendText(text: string): Promise<void>;
+    /**
+     * Fill a labeled field in the TUI.
+     * Navigates to the field and enters the value.
+     * Similar to UiPort.fillLabel.
+     * @param fieldLabel - The label or identifier of the field
+     * @param value - The value to enter
+     */
+    fillField(fieldLabel: string, value: string): Promise<void>;
+    /**
+     * Select an option/menu item.
+     * Similar to UiPort.clickButton conceptually.
+     * @param option - The option text to select
+     */
+    selectOption(option: string): Promise<void>;
+    /**
+     * Send a mouse event to the terminal.
+     * Only works if the TUI application supports mouse input.
+     * @param event - Mouse event configuration
+     */
+    sendMouse(event: TuiMouseEvent): Promise<void>;
+    /**
+     * Click at a specific position.
+     * @param x - Column position (0-based)
+     * @param y - Row position (0-based)
+     * @param button - Mouse button (defaults to 'left')
+     */
+    click(x: number, y: number, button?: TuiMouseButton): Promise<void>;
+    /**
+     * Click on text content in the terminal.
+     * Finds the text and clicks on its position.
+     * @param text - The text to find and click
+     */
+    clickOnText(text: string): Promise<void>;
+    /**
+     * Assert that text is visible on the screen.
+     * Waits for the text to appear within timeout.
+     * Similar to UiPort.expectText.
+     * @param text - The expected text
+     * @param options - Wait options
+     */
+    expectText(text: string, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Assert that text matching a pattern is visible.
+     * @param pattern - Regular expression to match
+     * @param options - Wait options
+     */
+    expectPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Assert that text is NOT visible on the screen.
+     * @param text - The text that should not be present
+     */
+    expectNotText(text: string): Promise<void>;
+    /**
+     * Assert the screen contains specific text (immediate check, no wait).
+     * @param text - The expected text
+     */
+    assertScreenContains(text: string): Promise<void>;
+    /**
+     * Assert the screen matches a regular expression.
+     * @param pattern - Regular expression to match against screen content
+     */
+    assertScreenMatches(pattern: RegExp): Promise<void>;
+    /**
+     * Wait for text to appear on screen.
+     * @param text - Text to wait for
+     * @param options - Wait options
+     */
+    waitForText(text: string, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Wait for text matching pattern to appear.
+     * @param pattern - Regular expression to match
+     * @param options - Wait options
+     */
+    waitForPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    /**
+     * Wait for the application to be ready.
+     * Implementation-specific (e.g., wait for prompt, initial screen).
+     */
+    waitForReady(): Promise<void>;
+    /**
+     * Wait for a specific duration.
+     * Similar to UiPort.waitSeconds.
+     * @param seconds - Duration to wait in seconds
+     */
+    waitSeconds(seconds: number): Promise<void>;
+    /**
+     * Capture the current screen state.
+     * @returns Screen capture with text content and metadata
+     */
+    captureScreen(): Promise<TuiScreenCapture>;
+    /**
+     * Get the current screen text content.
+     * @returns Plain text representation of the screen
+     */
+    getScreenText(): Promise<string>;
+    /**
+     * Get screen content as lines.
+     * @returns Array of screen lines
+     */
+    getScreenLines(): Promise<string[]>;
+    /**
+     * Take a snapshot of the current screen state.
+     * Saves to the configured snapshot directory.
+     * @param name - Snapshot identifier
+     */
+    takeSnapshot(name: string): Promise<void>;
+    /**
+     * Compare current screen against a saved snapshot.
+     * @param name - Snapshot identifier to compare against
+     * @returns Comparison result with pass/fail and diff
+     */
+    matchSnapshot(name: string): Promise<TuiSnapshotResult>;
+    /**
+     * Clear the terminal screen.
+     */
+    clear(): Promise<void>;
+    /**
+     * Resize the terminal.
+     * @param size - New dimensions
+     */
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    /**
+     * Get the current terminal size.
+     */
+    getSize(): {
+        cols: number;
+        rows: number;
+    };
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): TuiConfig;
+}
+
+/**
+ * Callback type for obtaining admin auth headers for cleanup operations.
+ * Consumers can provide their own implementation (e.g., Keycloak, Auth0, Okta)
+ * via the `getCleanupAuth` option in createBddTest().
+ */
+type CleanupAuthProvider = (request: APIRequestContext) => Promise<Record<string, string>>;
+type CreateContext = PlaywrightTestArgs & PlaywrightWorkerArgs & {
+    apiRequest: APIRequestContext;
+    page: Page;
+};
+/**
+ * Factory function type for creating a TUI adapter.
+ * Returns undefined if TUI testing is not configured.
+ */
+type TuiFactory = () => TuiPort | undefined;
+type CreateBddTestOptions = {
+    createApi?: (ctx: CreateContext) => ApiPort;
+    createUi?: (ctx: CreateContext) => UiPort;
+    createAuth?: (ctx: CreateContext & {
+        api: ApiPort;
+        ui: UiPort;
+    }) => AuthPort;
+    createCleanup?: (ctx: CreateContext) => CleanupPort;
+    /**
+     * Custom auth provider for cleanup operations.
+     * Return a record of headers (e.g., { Authorization: 'Bearer ...' }) to
+     * authenticate cleanup API calls.
+     *
+     * Use this to integrate with any auth provider (Keycloak, Auth0, Okta, etc.)
+     * without coupling the framework to a specific identity provider.
+     *
+     * If not provided, the default provider attempts a form-based login using
+     * DEFAULT_ADMIN_USERNAME / DEFAULT_ADMIN_PASSWORD env vars, or uses
+     * CLEANUP_AUTH_TOKEN if set. If no credentials are configured, cleanup
+     * runs unauthenticated.
+     */
+    getCleanupAuth?: CleanupAuthProvider;
+    /**
+     * Factory function for creating a TUI adapter.
+     * Unlike other adapters, this is a simple factory that doesn't receive context,
+     * as TUI testing operates independently of Playwright's browser context.
+     *
+     * @example
+     * ```typescript
+     * createTui: () => new TuiTesterAdapter({
+     *   command: ['node', 'dist/cli.js'],
+     *   size: { cols: 100, rows: 30 },
+     * }),
+     * ```
+     */
+    createTui?: TuiFactory;
+    worldFactory?: () => World;
+};
+declare function createBddTest(options?: CreateBddTestOptions): {
+    test: _playwright_test.TestType<PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & playwright_bdd.BddTestFixtures & {
+        world: World;
+        api: ApiPort;
+        ui: UiPort;
+        auth: AuthPort;
+        cleanup: CleanupPort;
+        tui: TuiPort | undefined;
+        apiRequest: APIRequestContext;
+    }, PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions & playwright_bdd.BddWorkerFixtures>;
+    expect: _playwright_test.Expect<{}>;
+};
+
+declare function interpolate(template: string, vars: Record<string, string>): string;
+declare function tryParseJson(text: string): unknown;
+declare function selectPath(root: unknown, path: string): unknown;
+declare function parseExpected(input: string, world: World): unknown;
+declare function assertMasked(val: unknown): void;
+declare function registerCleanup(world: World, item: {
+    method?: 'DELETE' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+    body?: unknown;
+}): void;
+
+declare class PlaywrightApiAdapter implements ApiPort {
+    private readonly request;
+    constructor(request: APIRequestContext);
+    sendJson(method: ApiMethod, path: string, body?: unknown, headers?: Record<string, string>): Promise<ApiResult>;
+    sendForm(method: 'POST' | 'PUT' | 'PATCH', path: string, form: Record<string, string>, headers?: Record<string, string>): Promise<ApiResult>;
+}
+
+declare class PlaywrightUiAdapter implements UiPort {
+    private readonly page;
+    constructor(page: Page);
+    goto(path: string): Promise<void>;
+    clickButton(name: string): Promise<void>;
+    clickLink(name: string): Promise<void>;
+    fillPlaceholder(placeholder: string, value: string): Promise<void>;
+    fillLabel(label: string, value: string): Promise<void>;
+    expectText(text: string): Promise<void>;
+    expectUrlContains(part: string): Promise<void>;
+    goBack(): Promise<void>;
+    reload(): Promise<void>;
+    waitSeconds(seconds: number): Promise<void>;
+    waitForPageLoad(): Promise<void>;
+    getCurrentUrl(): Promise<string>;
+    zoomTo(scale: number): Promise<void>;
+    typeText(text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    clickElementThatContains(clickMode: UiClickMode, elementType: string, text: string): Promise<void>;
+    clickElementWith(clickMode: UiClickMode, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    fillDropdown(value: string, dropdownLabel: string): Promise<void>;
+    inputInElement(action: UiInputMode, value: string, ordinal: string, text: string, method: UiLocatorMethod): Promise<void>;
+    expectUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectNewTabUrl(mode: UiUrlAssertMode, expected: string): Promise<void>;
+    expectElementWithTextVisible(elementType: string, text: string, shouldBeVisible: boolean): Promise<void>;
+    expectElementState(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState): Promise<void>;
+    expectElementStateWithin(ordinal: string, text: string, method: UiLocatorMethod, state: UiElementState, seconds: number): Promise<void>;
+    private parseOrdinal;
+    private locatorBy;
+    private performClick;
+    private expectState;
+    private assertUrlAgainst;
+}
+
+declare class UniversalAuthAdapter implements AuthPort {
+    private readonly deps;
+    constructor(deps: {
+        api: ApiPort;
+        ui: UiPort;
+    });
+    apiSetBearer(world: World, token: string): void;
+    apiLoginAsAdmin(world: World): Promise<void>;
+    apiLoginAsUser(world: World): Promise<void>;
+    private apiLogin;
+    uiLoginAsAdmin(world: World): Promise<void>;
+    uiLoginAsUser(world: World): Promise<void>;
+    private uiLogin;
+}
+
+type CleanupRule = {
+    varMatch: string;
+    method?: 'DELETE' | 'POST' | 'PATCH' | 'PUT';
+    path: string;
+    body?: unknown;
+};
+declare class DefaultCleanupAdapter implements CleanupPort {
+    private readonly rules;
+    private readonly allowHeuristic;
+    constructor(input?: {
+        rules?: CleanupRule[];
+        allowHeuristic?: boolean;
+    });
+    registerFromVar(world: World, varName: string, id: unknown, meta?: unknown): void;
+}
+
+/**
+ * TUI Tester Adapter
+ *
+ * Implements TuiPort using the tui-tester library (https://github.com/luxquant/tui-tester).
+ * Provides end-to-end testing capabilities for terminal user interfaces via tmux.
+ */
+
+declare class TuiTesterAdapter implements TuiPort {
+    private tester;
+    private config;
+    private running;
+    private tuiTesterModule;
+    constructor(config: TuiConfig);
+    /**
+     * Lazily load the tui-tester module to support optional dependency
+     */
+    private loadTuiTester;
+    /**
+     * Get the tester instance, throwing if not started
+     */
+    private getTester;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    isRunning(): boolean;
+    typeText(text: string, options?: {
+        delay?: number;
+    }): Promise<void>;
+    pressKey(key: string, modifiers?: TuiKeyModifiers): Promise<void>;
+    sendText(text: string): Promise<void>;
+    fillField(fieldLabel: string, value: string): Promise<void>;
+    selectOption(option: string): Promise<void>;
+    sendMouse(event: TuiMouseEvent): Promise<void>;
+    click(x: number, y: number, button?: TuiMouseButton): Promise<void>;
+    clickOnText(text: string): Promise<void>;
+    expectText(text: string, options?: TuiWaitOptions): Promise<void>;
+    expectPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    expectNotText(text: string): Promise<void>;
+    assertScreenContains(text: string): Promise<void>;
+    assertScreenMatches(pattern: RegExp): Promise<void>;
+    waitForText(text: string, options?: TuiWaitOptions): Promise<void>;
+    waitForPattern(pattern: RegExp, options?: TuiWaitOptions): Promise<void>;
+    waitForReady(): Promise<void>;
+    waitSeconds(seconds: number): Promise<void>;
+    captureScreen(): Promise<TuiScreenCapture>;
+    getScreenText(): Promise<string>;
+    getScreenLines(): Promise<string[]>;
+    takeSnapshot(name: string): Promise<void>;
+    matchSnapshot(name: string): Promise<TuiSnapshotResult>;
+    clear(): Promise<void>;
+    resize(size: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    getSize(): {
+        cols: number;
+        rows: number;
+    };
+    getConfig(): TuiConfig;
+}
+
+/**
+ * Fetch Intercept Auth Adapter
+ *
+ * Provides UI authentication by intercepting fetch requests and injecting headers.
+ * Useful for testing UIs that communicate with APIs using fetch.
+ */
+
+interface FetchInterceptAuthData {
+    userId: string;
+    tenantId?: string;
+    roles: string[];
+    token?: string;
+}
+interface FetchInterceptConfig {
+    /**
+     * URL pattern to match for header injection.
+     * If not provided, headers are added to all fetch requests.
+     */
+    urlPattern?: string | RegExp;
+    /**
+     * Headers to inject. Can be static values or functions that receive auth data.
+     */
+    headers: Record<string, string | ((data: FetchInterceptAuthData) => string)>;
+    /**
+     * Key in localStorage to store auth data for UI components to read.
+     */
+    localStorageKey?: string;
+}
+/**
+ * Default configuration for bypass auth mode.
+ */
+declare const defaultBypassConfig: FetchInterceptConfig;
+/**
+ * Default configuration for bearer token auth.
+ */
+declare const defaultBearerConfig: FetchInterceptConfig;
+/**
+ * Set up fetch interception on a page.
+ *
+ * @param page - Playwright page
+ * @param authData - Authentication data to inject
+ * @param config - Configuration for interception
+ */
+declare function setupFetchIntercept(page: Page, authData: FetchInterceptAuthData, config?: FetchInterceptConfig): Promise<void>;
+/**
+ * Clear fetch interception setup (by reloading the page).
+ * Note: There's no clean way to remove addInitScript, so we reload.
+ */
+declare function clearFetchIntercept(page: Page): Promise<void>;
+/**
+ * Helper to set up bypass auth for a page.
+ */
+declare function setupBypassAuth(page: Page, userId: string, roles: string[], tenantId?: string): Promise<void>;
+/**
+ * Helper to set up bearer token auth for a page.
+ */
+declare function setupBearerAuth(page: Page, token: string): Promise<void>;
+
+/**
+ * Configuration for OIDC-based cleanup authentication.
+ *
+ * Reads from env vars by default:
+ * - OIDC_TOKEN_URL: Full token endpoint URL (required)
+ * - OIDC_CLIENT_ID: OAuth2 client ID (required)
+ * - OIDC_CLIENT_SECRET: OAuth2 client secret (optional, for confidential clients)
+ * - OIDC_GRANT_TYPE: Grant type (default: 'client_credentials')
+ * - OIDC_SCOPE: Requested scopes (optional)
+ * - OIDC_USERNAME: Username for password grant (optional)
+ * - OIDC_PASSWORD: Password for password grant (optional)
+ * - OIDC_EXTRA_HEADERS: JSON object of additional headers to include (optional)
+ */
+interface OidcCleanupAuthConfig {
+    /** Full URL to the OIDC token endpoint. */
+    tokenUrl?: string;
+    /** OAuth2 client ID. */
+    clientId?: string;
+    /** OAuth2 client secret (for confidential clients). */
+    clientSecret?: string;
+    /** Grant type. Defaults to 'client_credentials'. */
+    grantType?: string;
+    /** Requested scopes (space-separated). */
+    scope?: string;
+    /** Username for 'password' grant type. */
+    username?: string;
+    /** Password for 'password' grant type. */
+    password?: string;
+    /**
+     * Additional headers to include in cleanup API requests
+     * (e.g., { 'x-user-roles': 'admin' }).
+     */
+    extraHeaders?: Record<string, string>;
+}
+/**
+ * Creates an OIDC-based cleanup auth provider.
+ *
+ * Works with any OIDC-compliant provider (Keycloak, Auth0, Okta, Azure AD, etc.)
+ * by configuring the token endpoint URL and client credentials.
+ *
+ * @example Keycloak with password grant:
+ * ```typescript
+ * import { createBddTest, createOidcCleanupAuth } from '@esimplicitylabs/katalyst-xspec';
+ *
+ * // Set env vars: OIDC_TOKEN_URL, OIDC_CLIENT_ID, OIDC_USERNAME, OIDC_PASSWORD
+ * const test = createBddTest({
+ *   getCleanupAuth: createOidcCleanupAuth({
+ *     grantType: 'password',
+ *     extraHeaders: { 'x-user-roles': 'admin' },
+ *   }),
+ * });
+ * ```
+ *
+ * @example Auth0 with client_credentials grant:
+ * ```typescript
+ * const test = createBddTest({
+ *   getCleanupAuth: createOidcCleanupAuth({
+ *     tokenUrl: 'https://your-tenant.auth0.com/oauth/token',
+ *     clientId: 'your-client-id',
+ *     clientSecret: 'your-secret',
+ *     scope: 'delete:resources',
+ *   }),
+ * });
+ * ```
+ */
+declare function createOidcCleanupAuth(config?: OidcCleanupAuthConfig): CleanupAuthProvider;
+/**
+ * Reset the cached OIDC token (useful for testing or when tokens expire).
+ */
+declare function resetOidcCleanupAuth(): void;
+
+type TagsForProjectInput = {
+    projectTag: string;
+    extraTags?: string;
+    defaultExcludes?: string;
+};
+declare function tagsForProject({ projectTag, extraTags, defaultExcludes }: TagsForProjectInput): string;
+declare function resolveExtraTags(raw?: string | null): string | undefined;
+
+/**
+ * Options for configuring worker resolution.
+ */
+type ResolveWorkersOptions = {
+    /**
+     * The type of test being run.
+     * When set to `'tui'`, workers is always forced to `1` (TUI tests require sequential execution).
+     */
+    testType?: 'api' | 'ui' | 'tui' | 'hybrid';
+    /**
+     * Number of workers to use in CI environments (when `CI` env var is truthy).
+     * @default 1
+     */
+    ciWorkers?: number;
+    /**
+     * Default number of workers for local development.
+     * Set to `undefined` (default) to let Playwright decide (50% of CPU cores).
+     * Set to a number to override.
+     */
+    defaultWorkers?: number;
+};
+/**
+ * Resolves the number of Playwright workers based on environment variables,
+ * test type, and CI detection.
+ *
+ * **Environment variable:** `WORKERS`
+ * - `'auto'` or unset — uses smart defaults (Playwright decides locally, 1 in CI)
+ * - A positive integer (e.g. `'4'`) — uses that exact worker count
+ * - `'50%'` style percentage strings are passed through as strings for Playwright
+ *
+ * **Precedence:**
+ * 1. `testType: 'tui'` always returns `1`
+ * 2. `WORKERS` env var with a valid number overrides everything else
+ * 3. CI environment defaults to `ciWorkers` (default: `1`)
+ * 4. Otherwise returns `defaultWorkers` (default: `undefined`, letting Playwright decide)
+ *
+ * @example
+ * ```ts
+ * import { resolveWorkers } from '@esimplicitylabs/katalyst-xspec';
+ *
+ * export default defineConfig({
+ *   workers: resolveWorkers(),
+ *   projects: [
+ *     { name: 'api', ...apiBdd },
+ *     { name: 'tui', ...tuiBdd, workers: resolveWorkers({ testType: 'tui' }) },
+ *   ],
+ * });
+ * ```
+ */
+declare function resolveWorkers(options?: ResolveWorkersOptions): number | undefined;
+/**
+ * Returns the number of available CPU cores on the current machine.
+ * Useful for logging or making informed decisions about worker counts.
+ */
+declare function getCpuCount(): number;
+
+/**
+ * Options for resolving the features directory path.
+ */
+type ResolveFeaturesOptions = {
+    /**
+     * Default path to use when `FEATURES_DIR` env var is not set.
+     * @default 'features'
+     */
+    defaultDir?: string;
+};
+/**
+ * Options for resolving the custom steps directory path.
+ */
+type ResolveStepsOptions = {
+    /**
+     * Default path to use when `CUSTOM_STEPS_DIR` env var is not set.
+     * @default 'features/steps'
+     */
+    defaultDir?: string;
+};
+/**
+ * Resolves the path to the BDD features directory.
+ *
+ * **Environment variable:** `FEATURES_DIR`
+ * - When set, returns the value as-is (relative or absolute)
+ * - When unset, returns `defaultDir` (default: `'features'`)
+ *
+ * Use this in `playwright.config.ts` with `defineBddProject()` to make
+ * feature file locations configurable per-environment.
+ *
+ * @example
+ * ```ts
+ * import { resolveFeatures } from '@esimplicitylabs/katalyst-xspec';
+ * import { defineBddProject } from 'playwright-bdd';
+ *
+ * const apiBdd = defineBddProject({
+ *   name: 'api',
+ *   features: `${resolveFeatures()}/api/**\/*.feature`,
+ *   steps: `${resolveSteps()}/**\/*.ts`,
+ * });
+ * ```
+ *
+ * @example
+ * ```bash
+ * # Run from the layer directory (default)
+ * just test-bdd-run dev
+ *
+ * # Override via env var (used by just recipes in multi-layer repos)
+ * FEATURES_DIR=../../claims-api/tests/features just test-bdd-run dev
+ * ```
+ */
+declare function resolveFeatures(options?: ResolveFeaturesOptions): string;
+/**
+ * Resolves the path to the custom step definitions directory.
+ *
+ * **Environment variable:** `CUSTOM_STEPS_DIR`
+ * - When set, returns the value as-is (relative or absolute)
+ * - When unset, returns `defaultDir` (default: `'features/steps'`)
+ *
+ * Custom steps are layer-specific Given/When/Then definitions that extend
+ * the library's pre-built steps. They live alongside the feature files in
+ * each test layer.
+ *
+ * @example
+ * ```ts
+ * import { resolveSteps } from '@esimplicitylabs/katalyst-xspec';
+ * import { defineBddProject } from 'playwright-bdd';
+ *
+ * const apiBdd = defineBddProject({
+ *   name: 'api',
+ *   features: `${resolveFeatures()}/api/**\/*.feature`,
+ *   steps: `${resolveSteps()}/**\/*.ts`,
+ * });
+ * ```
+ */
+declare function resolveSteps(options?: ResolveStepsOptions): string;
+/**
+ * Builds glob patterns for use with `defineBddProject()` based on resolved paths.
+ *
+ * A convenience wrapper combining `resolveFeatures()` and `resolveSteps()` into
+ * the shape expected by playwright-bdd's `defineBddProject()`.
+ *
+ * @example
+ * ```ts
+ * import { resolveBddPaths } from '@esimplicitylabs/katalyst-xspec';
+ * import { defineBddProject } from 'playwright-bdd';
+ *
+ * const { features, steps } = resolveBddPaths({ tag: 'api' });
+ * const apiBdd = defineBddProject({ name: 'api', features, steps });
+ * ```
+ */
+declare function resolveBddPaths(options?: {
+    /**
+     * Test tag to scope feature file glob (e.g., 'api', 'ui').
+     * Creates pattern: `{featuresDir}/{tag}/**\/*.feature`
+     * If omitted, uses `{featuresDir}/**\/*.feature`
+     */
+    tag?: string;
+    /** Options for features resolution */
+    featuresOptions?: ResolveFeaturesOptions;
+    /** Options for steps resolution */
+    stepsOptions?: ResolveStepsOptions;
+}): {
+    features: string;
+    steps: string;
+};
+
+/**
+ * Network target resolution for the API request context.
+ *
+ * macOS resolves `*.localhost` to `::1` (IPv6) first, but a local kind cluster
+ * binds its ingress on `0.0.0.0` (IPv4 only), so requests to `::1` fail with
+ * ECONNRESET. For plain-http `*.localhost` targets we connect to `127.0.0.1`
+ * instead and send the original host as the `Host` header so host-based
+ * ingress routing (Istio Gateway/VirtualService, nginx, etc.) still matches.
+ *
+ * Deliberately NOT rewritten:
+ * - bare `localhost`: local dev servers (Vite, Node >=17) often bind `::1` only.
+ * - `https:`: TLS SNI and certificate checks use the URL host, so connecting to
+ *   127.0.0.1 would break verification regardless of the Host header.
+ *
+ * Disable entirely with `KATALYST_XSPEC_FORCE_IPV4=false` (or `0`). The
+ * pre-rename `STACK_TESTS_FORCE_IPV4` is still honoured.
+ */
+type ApiRequestTarget = {
+    baseURL: string;
+    extraHTTPHeaders?: Record<string, string>;
+};
+declare function resolveApiRequestTarget(baseURL: string, env?: Record<string, string | undefined>): ApiRequestTarget;
+
+export { type ApiMethod, type ApiPort, type ApiRequestTarget, type ApiResult, type AuthPort, type CleanupAuthProvider, type CleanupItem, type CleanupPort, type CleanupRule, type CreateBddTestOptions, DefaultCleanupAdapter, type FetchInterceptAuthData, type FetchInterceptConfig, type OidcCleanupAuthConfig, PlaywrightApiAdapter, PlaywrightUiAdapter, type ResolveFeaturesOptions, type ResolveStepsOptions, type ResolveWorkersOptions, type TuiConfig, type TuiFactory, type TuiKeyModifiers, type TuiMouseButton, type TuiMouseEvent, type TuiMouseEventType, type TuiPort, type TuiScreenCapture, type TuiSnapshotResult, TuiTesterAdapter, type TuiWaitOptions, type UiClickMode, type UiElementState, type UiInputMode, type UiLocatorMethod, type UiPort, type UiUrlAssertMode, UniversalAuthAdapter, type World, assertMasked, clearFetchIntercept, createBddTest, createOidcCleanupAuth, defaultBearerConfig, defaultBypassConfig, getCpuCount, initWorld, interpolate, parseExpected, registerCleanup, resetOidcCleanupAuth, resolveApiRequestTarget, resolveBddPaths, resolveExtraTags, resolveFeatures, resolveSteps, resolveWorkers, selectPath, setupBearerAuth, setupBypassAuth, setupFetchIntercept, tagsForProject, tryParseJson };