@ulpi/browse 2.3.3 → 2.4.0

package/dist/types/automation/command.d.ts

@@ -0,0 +1,138 @@
+/**
+ * CommandSpec — the single source of truth for command identity and metadata.
+ *
+ * Every command in the system is described by a CommandSpec. The registry
+ * derives category sets, CLI help, MCP tool definitions, and future plugin
+ * registration from these specs. No hand-maintained duplicated sets.
+ */
+import type { CommandCategory } from './events';
+/** MCP tool schema for commands exposed via Model Context Protocol */
+export interface McpToolSpec {
+    /** Tool description shown to LLMs */
+    description: string;
+    /** JSON Schema for tool input parameters */
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    /**
+     * Decode MCP tool params into CLI args array.
+     * If omitted, the default decoder collects string param values positionally.
+     */
+    argDecode?: (params: Record<string, unknown>) => string[];
+    /**
+     * Override the command name routed to by the MCP dispatcher.
+     * Used by virtual tools (e.g. 'perf-audit-save' routes to 'perf-audit').
+     * If omitted, the MCP tool name (after prefix/underscore conversion) is used.
+     */
+    commandName?: string;
+}
+export interface CommandSpec {
+    /** Command name (e.g. 'goto', 'click', 'snapshot') */
+    name: string;
+    /** Routing category */
+    category: CommandCategory;
+    /** Short description for CLI help */
+    description: string;
+    /** Argument format for CLI help (e.g. '<url>', '<sel> <val>') */
+    usage?: string;
+    /** Skip action context enrichment on this write command */
+    skipContext?: boolean;
+    /** Skip recording this command in record sessions */
+    skipRecording?: boolean;
+    /** Safe to auto-retry after server restart (read-only / idempotent) */
+    safeToRetry?: boolean;
+    /** Returns page-derived content (for --content-boundaries wrapping) */
+    pageContent?: boolean;
+    /**
+     * Which automation target types this command supports.
+     * - 'browser': only available for browser sessions
+     * - 'app': only available for app (native) sessions
+     * - 'any': available for all target types (default)
+     */
+    targetSupport?: 'browser' | 'app' | 'any';
+    /** MCP tool metadata. Omit for commands not exposed via MCP. */
+    mcp?: McpToolSpec;
+}
+/** Context passed to command execute functions by the executor */
+export interface CommandContext {
+    /** Command arguments from the caller */
+    args: string[];
+    /** The session's automation target */
+    target: import('../automation/target').AutomationTarget;
+    /** Per-session buffers (console, network) */
+    buffers: import('../network/buffers').SessionBuffers;
+    /** Domain filter for the session (may be null) */
+    domainFilter?: import('../security/domain-filter').DomainFilter | null;
+    /** Session reference for commands that need session-level state */
+    session?: import('../session/manager').Session;
+    /** Shutdown callback for server-control commands */
+    shutdown?: () => Promise<void> | void;
+    /** Session manager reference for multi-session commands */
+    sessionManager?: import('../session/manager').SessionManager;
+    /** Transport lifecycle hooks, threaded for sub-command dispatch (flow/chain) */
+    lifecycle?: import('./events').CommandLifecycle;
+}
+/**
+ * CommandDefinition — executable command registration.
+ *
+ * This is the durable shape for built-in commands now and plugin commands later.
+ * It combines metadata (CommandSpec) with execution logic and optional MCP
+ * arg-decoding so the registry owns both discovery and dispatch.
+ */
+export interface CommandDefinition {
+    /** Command metadata (category, description, usage, behavioral flags, MCP schema) */
+    spec: CommandSpec;
+    /** Execute the command. Returns the result string. */
+    execute: (ctx: CommandContext) => Promise<string>;
+    /**
+     * Optional MCP arg-decoding: transforms MCP tool params into CLI args.
+     * If omitted, the default decoder is used (simple positional mapping).
+     */
+    mcpArgDecode?: (params: Record<string, unknown>) => string[];
+}
+/**
+ * Typed command registry — single authoritative source for command metadata.
+ *
+ * Server routing, MCP tool definitions, CLI help, and future plugin
+ * registration all derive from this registry instead of maintaining
+ * separate hand-edited sets.
+ */
+export declare class CommandRegistry {
+    private specs;
+    private definitions;
+    /** Register a metadata-only command spec. */
+    register(spec: CommandSpec): void;
+    /** Register multiple metadata-only command specs. */
+    registerAll(specs: CommandSpec[]): void;
+    /** Register an executable command definition (spec + execute + optional MCP arg-decode). */
+    define(def: CommandDefinition): void;
+    /** Register multiple executable command definitions. */
+    defineAll(defs: CommandDefinition[]): void;
+    /** Look up a command spec by name. */
+    get(name: string): CommandSpec | undefined;
+    /** Look up a command definition by name. Returns undefined if spec-only (not yet migrated). */
+    getDefinition(name: string): CommandDefinition | undefined;
+    /** Check if a command is registered. */
+    has(name: string): boolean;
+    /** Check if a command has a full definition (not just metadata). */
+    hasDefined(name: string): boolean;
+    /** Get the category of a command. */
+    getCategory(name: string): CommandCategory | undefined;
+    /** Get all specs in a category. */
+    byCategory(category: CommandCategory): CommandSpec[];
+    /** Get command names in a category as a Set (backward-compatible). */
+    categorySet(category: CommandCategory): Set<string>;
+    /** Get all registered specs. */
+    all(): CommandSpec[];
+    /** Get all registered command definitions. */
+    allDefinitions(): CommandDefinition[];
+    /** Get all registered command names. */
+    names(): string[];
+    /** Number of registered commands. */
+    get size(): number;
+    /** Number of commands with full definitions. */
+    get definedCount(): number;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/types/automation/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/automation/command.ts"],"names":[],"mappings":"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"}

package/dist/types/automation/events.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Command lifecycle hook contracts.
+ *
+ * Used by the executor pipeline (TASK-003) to centralize cross-cutting
+ * concerns: context capture, recording, error shaping.
+ *
+ * Design constraints:
+ *   - No imports from server, session, transport, or Playwright.
+ *   - Hooks are pure contracts — implementations live in the executor.
+ *   - BeforeCommandHook can abort execution (e.g. policy denial).
+ *   - AfterCommandHook can enrich the result (e.g. action context).
+ *   - CommandErrorHook can transform error messages (e.g. AI-friendly rewriting).
+ */
+/** Command category for routing and lifecycle decisions */
+export type CommandCategory = 'read' | 'write' | 'meta';
+/** Immutable event payload shared by all lifecycle hooks */
+export interface CommandEvent {
+    /** Command name (e.g. 'goto', 'click', 'snapshot') */
+    readonly command: string;
+    /** Command arguments */
+    readonly args: readonly string[];
+    /** Resolved command category */
+    readonly category: CommandCategory;
+}
+/** Payload for after-command hooks — includes execution result and timing */
+export interface AfterCommandEvent extends CommandEvent {
+    /** Raw command result before enrichment */
+    readonly result: string;
+    /** Wall-clock execution duration in milliseconds */
+    readonly durationMs: number;
+    /** The resolved command spec (for checking skipRecording, pageContent, etc.) */
+    readonly spec?: import('./command').CommandSpec;
+}
+/** Payload for error hooks — includes the thrown error */
+export interface CommandErrorEvent extends CommandEvent {
+    /** The error thrown during command execution */
+    readonly error: Error;
+}
+/**
+ * Invoked before command execution.
+ * Return void to proceed, or return an abort signal to short-circuit
+ * execution with a predetermined result (e.g. policy denial message).
+ */
+export type BeforeCommandHook = (event: CommandEvent) => Promise<void | {
+    abort: true;
+    result: string;
+}>;
+/**
+ * Invoked after successful command execution.
+ * Receives the result and returns an optionally enriched version
+ * (e.g. with action context appended).
+ */
+export type AfterCommandHook = (event: AfterCommandEvent) => Promise<string>;
+/**
+ * Invoked when command execution throws.
+ * Returns a transformed error message (e.g. AI-friendly rewriting).
+ */
+export type CommandErrorHook = (event: CommandErrorEvent) => Promise<string>;
+/**
+ * Lifecycle hook collection for the executor pipeline.
+ *
+ * All arrays are optional. When present, hooks execute in order:
+ *   - before: first abort wins, remaining hooks are skipped
+ *   - after: each receives the previous hook's output (pipeline)
+ *   - onError: each receives the previous hook's output (pipeline)
+ */
+export interface CommandLifecycle {
+    before?: BeforeCommandHook[];
+    after?: AfterCommandHook[];
+    onError?: CommandErrorHook[];
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/types/automation/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/automation/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAIxD,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACpC;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,WAAW,EAAE,WAAW,CAAC;CACjD;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,gDAAgD;IAChD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAID;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,IAAI,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,iBAAiB,KACrB,OAAO,CAAC,MAAM,CAAC,CAAC;AAErB;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,iBAAiB,KACrB,OAAO,CAAC,MAAM,CAAC,CAAC;AAIrB;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC7B,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAC9B"}

package/dist/types/automation/executor.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Command executor pipeline — single execution path for all commands.
+ *
+ * Centralizes:
+ *   - Command lookup via registry (definition or spec)
+ *   - Lifecycle hooks (before/after/onError)
+ *   - Action context enrichment for write commands
+ *   - Recording hooks
+ *   - Error shaping
+ *
+ * Used by both HTTP server and MCP server.
+ * Future flow/retry/watch execution (v2.1) and plugins (v2.2) will also use this.
+ */
+import type { CommandSpec, CommandContext } from './command';
+import type { CommandLifecycle } from './events';
+/** Options passed to executeCommand by the transport layer */
+export interface ExecuteOptions {
+    /** Lifecycle hooks to apply (transport-specific) */
+    lifecycle?: CommandLifecycle;
+    /** Execution context for definition-backed commands */
+    context?: CommandContext;
+}
+/** Result of command execution */
+export interface ExecuteResult {
+    /** Final command output (after lifecycle enrichment) */
+    output: string;
+    /** The resolved command spec */
+    spec: CommandSpec;
+    /** Execution duration in milliseconds */
+    durationMs: number;
+}
+/**
+ * Execute a command through the shared pipeline.
+ *
+ * Looks up the command's registered CommandDefinition and calls its execute().
+ * If no definition exists, throws.
+ */
+export declare function executeCommand(command: string, args: string[], opts?: ExecuteOptions): Promise<ExecuteResult>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/types/automation/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/automation/executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAsD,MAAM,UAAU,CAAC;AAGrG,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,uDAAuD;IACvD,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,aAAa,CAAC,CAwFxB"}

package/dist/types/automation/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Automation domain — target-neutral execution contracts.
+ *
+ * Public API for the automation layer. Consumers import from here
+ * rather than reaching into individual files.
+ */
+export { type AutomationTarget, type TargetCapabilities, UnsupportedCapabilityError, requireCapability, hasCapability, } from './target';
+export { type CommandCategory, type CommandEvent, type AfterCommandEvent, type CommandErrorEvent, type BeforeCommandHook, type AfterCommandHook, type CommandErrorHook, type CommandLifecycle, } from './events';
+export { type CommandSpec, type McpToolSpec, type CommandDefinition, type CommandContext, CommandRegistry, } from './command';
+export { executeCommand, type ExecuteOptions, type ExecuteResult, } from './executor';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/automation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/automation/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,0BAA0B,EAC1B,iBAAiB,EACjB,aAAa,GACd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,eAAe,GAChB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC"}

package/dist/types/automation/registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Command registry — single source of truth for all browse commands.
+ *
+ * Replaces hand-maintained READ/WRITE/META sets with typed CommandSpec
+ * registrations. Server routing, MCP exposure, CLI help, and future
+ * plugin registration all derive from this registry.
+ */
+import { CommandRegistry } from './command';
+export declare const registry: CommandRegistry;
+export declare const READ_COMMANDS: Set<string>;
+export declare const WRITE_COMMANDS: Set<string>;
+export declare const META_COMMANDS: Set<string>;
+/** Commands safe to auto-retry after server restart */
+export declare const SAFE_TO_RETRY: Set<string>;
+/** Commands excluded from recording */
+export declare const RECORDING_SKIP: Set<string>;
+/** Commands returning page content (for --content-boundaries) */
+export declare const PAGE_CONTENT_COMMANDS: Set<string>;
+/**
+ * Rewrite Playwright error messages into actionable hints for AI agents.
+ * Raw errors like "locator.click: Timeout 5000ms exceeded" are unhelpful.
+ */
+export declare function rewriteError(msg: string): string;
+/**
+ * Generate CLI help text derived from the command registry.
+ * Commands are grouped by category (read, write, meta).
+ * This is the single source of truth for the --help output.
+ */
+export declare function generateHelp(): string;
+/**
+ * Lazily register all command definitions.
+ * Called once on first executeCommand() invocation.
+ * Uses dynamic imports to avoid circular dependency issues at module load time.
+ */
+export declare function ensureDefinitionsRegistered(): Promise<void>;
+export type { CommandSpec, CommandRegistry, CommandDefinition } from './command';
+export type { CommandCategory } from './events';
+//# sourceMappingURL=registry.d.ts.map

package/dist/types/automation/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/automation/registry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAoB,MAAM,WAAW,CAAC;AAK9D,eAAO,MAAM,QAAQ,iBAAwB,CAAC;AA07B9C,eAAO,MAAM,aAAa,aAA+B,CAAC;AAC1D,eAAO,MAAM,cAAc,aAAgC,CAAC;AAC5D,eAAO,MAAM,aAAa,aAA+B,CAAC;AAE1D,uDAAuD;AACvD,eAAO,MAAM,aAAa,aAEzB,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,cAAc,aAE1B,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,aAEjC,CAAC;AAIF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAmChD;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAsErC;AAQD;;;;GAIG;AACH,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,IAAI,CAAC,CAWjE;AAGD,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACjF,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}

package/dist/types/automation/rules.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Custom audit rules — project-local declarative audit extensions.
+ *
+ * Loads .browse/rules/*.json and applies them alongside built-in audit checks.
+ * Rules are declarative JSON, not executable code — no eval/plugin hooks.
+ *
+ * Supported rule kinds:
+ *   - metric-threshold: for perf-audit (e.g., "LCP must be under 2000ms")
+ *   - selector-count: for a11y-audit (e.g., "no more than 0 images without alt")
+ */
+export interface CustomRule {
+    /** Rule version (currently 1) */
+    version: 1;
+    /** Human-readable rule name */
+    name: string;
+    /** Which audit this rule extends */
+    target: 'perf-audit' | 'a11y-audit';
+    /** Rule kind */
+    kind: 'metric-threshold' | 'selector-count';
+    /** For metric-threshold: metric key (e.g., 'lcp') */
+    metric?: string;
+    /** For metric-threshold: maximum allowed value */
+    threshold?: number;
+    /** For selector-count: CSS selector to count */
+    selector?: string;
+    /** For selector-count: maximum allowed count (0 = must not exist) */
+    maxCount?: number;
+    /** Severity when the rule fails */
+    severity?: 'critical' | 'warning';
+}
+export interface RuleResult {
+    rule: CustomRule;
+    passed: boolean;
+    actual: string;
+    source: string;
+}
+/**
+ * Load custom rules from .browse/rules/*.json
+ */
+export declare function loadCustomRules(localDir: string): {
+    rules: CustomRule[];
+    warnings: string[];
+};
+/**
+ * Evaluate metric-threshold rules against perf-audit metrics.
+ */
+export declare function evaluateMetricRules(rules: CustomRule[], metrics: Record<string, number | null>): RuleResult[];
+/**
+ * Evaluate selector-count rules against page state.
+ */
+export declare function evaluateSelectorRules(rules: CustomRule[], page: any): Promise<RuleResult[]>;
+//# sourceMappingURL=rules.d.ts.map

package/dist/types/automation/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../src/automation/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,OAAO,EAAE,CAAC,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,MAAM,EAAE,YAAY,GAAG,YAAY,CAAC;IACpC,gBAAgB;IAChB,IAAI,EAAE,kBAAkB,GAAG,gBAAgB,CAAC;IAC5C,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAoC7F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GACrC,UAAU,EAAE,CAWd;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,UAAU,EAAE,EACnB,IAAI,EAAE,GAAG,GACR,OAAO,CAAC,UAAU,EAAE,CAAC,CAYvB"}

package/dist/types/automation/target.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Automation target contracts — target-neutral automation abstractions.
+ *
+ * BrowserManager is the first implementation (TASK-004).
+ * Future targets: AppManager (v2.0), FlowTarget (v2.1), plugins (v2.2).
+ *
+ * Design constraints:
+ *   - No imports from browser-manager, session-manager, or Playwright types.
+ *   - Keep the core contract minimal — an AppManager for native mobile
+ *     must be able to implement AutomationTarget without faking browser APIs.
+ *   - Domain-specific behavior lives behind capability interfaces that
+ *     implementations opt into and consumers narrow to at runtime.
+ */
+/** Runtime capability query — each flag maps to a capability interface. */
+export interface TargetCapabilities {
+    /** Navigate to URLs or deep links */
+    navigation: boolean;
+    /** Multiple tabs or windows */
+    tabs: boolean;
+    /** @ref selector resolution from accessibility snapshots */
+    refs: boolean;
+    /** Screenshot and PDF capture */
+    screenshots: boolean;
+    /** In-context JavaScript evaluation */
+    javascript: boolean;
+    /** Device profile emulation (viewport, UA, touch) */
+    deviceEmulation: boolean;
+    /** Sub-frame or sub-container targeting */
+    frames: boolean;
+}
+/**
+ * Thrown when a command requires a capability that the current
+ * automation target does not support.
+ *
+ * Command handlers throw this instead of type-casting or branching
+ * on concrete manager types. The executor pipeline catches it and
+ * returns a clear error to the caller.
+ */
+export declare class UnsupportedCapabilityError extends Error {
+    readonly capability: keyof TargetCapabilities;
+    readonly targetType: string;
+    constructor(capability: keyof TargetCapabilities, targetType: string);
+}
+/**
+ * AutomationTarget — the minimal target-neutral automation contract.
+ *
+ * Every automation backend implements this surface. It covers identity,
+ * capability discovery, location, health, and cleanup — nothing more.
+ *
+ * Browser-specific APIs (page, context, locators) are accessed through
+ * capability interfaces that BrowserManager also implements. Consumers
+ * check getCapabilities() and narrow via requireCapability() before
+ * calling capability-specific methods.
+ */
+export interface AutomationTarget {
+    /** Identifies the target kind (e.g. 'browser', 'app') */
+    readonly targetType: string;
+    /** Runtime capability query */
+    getCapabilities(): TargetCapabilities;
+    /** Current location — URL for browser, screen for app, step for flow */
+    getCurrentLocation(): string;
+    /** Whether the target is connected and operational */
+    isReady(): boolean;
+    /** Release all resources */
+    close(): Promise<void>;
+}
+/**
+ * Assert that a target supports a capability.
+ * Throws UnsupportedCapabilityError if it does not.
+ */
+export declare function requireCapability(target: AutomationTarget, capability: keyof TargetCapabilities): void;
+/**
+ * Check whether a target supports a capability (no throw).
+ */
+export declare function hasCapability(target: AutomationTarget, capability: keyof TargetCapabilities): boolean;
+//# sourceMappingURL=target.d.ts.map

package/dist/types/automation/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../../src/automation/target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,UAAU,EAAE,OAAO,CAAC;IACpB,+BAA+B;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;IACd,iCAAiC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,uCAAuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,qDAAqD;IACrD,eAAe,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,MAAM,EAAE,OAAO,CAAC;CACjB;AAID;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,kBAAkB,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,kBAAkB,EAAE,UAAU,EAAE,MAAM;CASrE;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,+BAA+B;IAC/B,eAAe,IAAI,kBAAkB,CAAC;IAEtC,wEAAwE;IACxE,kBAAkB,IAAI,MAAM,CAAC;IAE7B,sDAAsD;IACtD,OAAO,IAAI,OAAO,CAAC;IAEnB,4BAA4B;IAC5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,kBAAkB,GACnC,IAAI,CAIN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,kBAAkB,GACnC,OAAO,CAET"}

package/dist/types/browser/consent.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Consent dialog auto-dismiss -- clicks away cookie banners, GDPR overlays, etc.
+ * Runtime-agnostic. Best-effort: never throws, never blocks navigation.
+ * Gated by BROWSE_CONSENT_DISMISS env var (default '1' = enabled).
+ */
+import type { Page } from 'playwright';
+/**
+ * Try to dismiss a consent dialog on the page. Best-effort, never throws.
+ * Tries each selector with a 150ms visibility timeout. Clicks the first visible one and returns.
+ * Only dismisses one dialog per call (avoid cascading clicks).
+ */
+export declare function dismissConsentDialog(page: Page): Promise<boolean>;
+//# sourceMappingURL=consent.d.ts.map

package/dist/types/browser/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../../src/browser/consent.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AA+BvC;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAevE"}

package/dist/types/browser/cookie-import.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Chromium browser cookie import — read and decrypt cookies from real browsers.
+ *
+ * Supports macOS Chromium-based browsers: Chrome, Arc, Brave, Edge.
+ * Pure logic module — no Playwright dependency, no HTTP concerns.
+ *
+ * Decryption pipeline (Chromium macOS "v10" format):
+ *
+ *   1. Keychain: `security find-generic-password -s "<svc>" -w`
+ *      → base64 password string
+ *
+ *   2. Key derivation:
+ *      PBKDF2(password, salt="saltysalt", iter=1003, len=16, sha1)
+ *      → 16-byte AES key
+ *
+ *   3. For each cookie with encrypted_value starting with "v10":
+ *      - Ciphertext = encrypted_value[3:]
+ *      - IV = 16 bytes of 0x20 (space character)
+ *      - Plaintext = AES-128-CBC-decrypt(key, iv, ciphertext)
+ *      - Remove PKCS7 padding
+ *      - Skip first 32 bytes (HMAC-SHA256 authentication tag)
+ *      - Remaining bytes = cookie value (UTF-8)
+ *
+ *   4. If encrypted_value is empty but `value` field is set,
+ *      use value directly (unencrypted cookie)
+ *
+ *   5. Chromium epoch: microseconds since 1601-01-01
+ *      Unix seconds = (epoch - 11644473600000000) / 1000000
+ *
+ *   6. sameSite: 0→"None", 1→"Lax", 2→"Strict", else→"Lax"
+ */
+export interface BrowserInfo {
+    name: string;
+    dataDir: string;
+    keychainService: string;
+    aliases: string[];
+}
+export interface DomainEntry {
+    domain: string;
+    count: number;
+}
+export interface ImportResult {
+    cookies: PlaywrightCookie[];
+    count: number;
+    failed: number;
+    domainCounts: Record<string, number>;
+}
+export interface PlaywrightCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    secure: boolean;
+    httpOnly: boolean;
+    sameSite: 'Strict' | 'Lax' | 'None';
+}
+export declare class CookieImportError extends Error {
+    code: string;
+    action?: "retry" | undefined;
+    constructor(message: string, code: string, action?: "retry" | undefined);
+}
+/**
+ * Parse a Netscape-format cookie file (.txt) into Playwright cookie objects.
+ *
+ * Format: domain\tincludeSubdomains\tpath\tsecure\texpires\tname\tvalue
+ * Lines starting with # are comments, except #HttpOnly_ prefix marks httpOnly cookies.
+ * This is the standard format exported by browser extensions like "cookies.txt".
+ */
+export declare function parseNetscapeCookieFile(content: string): Array<{
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    httpOnly: boolean;
+    secure: boolean;
+}>;
+/**
+ * Find which Chromium browsers are installed (have a cookie DB on disk).
+ */
+export declare function findInstalledBrowsers(): BrowserInfo[];
+/**
+ * List unique cookie domains + counts from a browser's DB. No decryption needed.
+ */
+export declare function listDomains(browserName: string, profile?: string): {
+    domains: DomainEntry[];
+    browser: string;
+};
+/**
+ * Decrypt and return Playwright-compatible cookies for specified domains.
+ */
+export declare function importCookies(browserName: string, domains: string[], profile?: string): Promise<ImportResult>;
+//# sourceMappingURL=cookie-import.d.ts.map

package/dist/types/browser/cookie-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-import.d.ts","sourceRoot":"","sources":["../../../src/browser/cookie-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAWH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CACrC;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAGjC,IAAI,EAAE,MAAM;IACZ,MAAM,CAAC,EAAE,OAAO;gBAFvB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,YAAA;CAK1B;AAoBD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC,CAuCD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,EAAE,CAMrD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,SAAY,GAAG;IAAE,OAAO,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiBjH;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,SAAY,GAClB,OAAO,CAAC,YAAY,CAAC,CAuCvB"}

package/dist/types/browser/detection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Google block detection — detect when Google shows captcha/block page.
+ * Runtime-agnostic. Used by goto handler and snapshot to warn agents.
+ */
+import type { Page } from 'playwright';
+/**
+ * Check if a URL is a Google Search page.
+ * Narrow match: only www.google.* or google.* with /search path.
+ * Does NOT match mail.google.com, docs.google.com, etc.
+ */
+export declare function isGoogleSearchUrl(url: string): boolean;
+/**
+ * Check if the current page is a Google block/captcha page.
+ * Only runs DOM checks on actual Google Search or Sorry pages.
+ * Best-effort, never throws.
+ */
+export declare function isGoogleBlocked(page: Page): Promise<boolean>;
+/**
+ * Format a user-friendly error message for a Google block.
+ */
+export declare function formatGoogleBlockError(url: string): string;
+//# sourceMappingURL=detection.d.ts.map

package/dist/types/browser/detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detection.d.ts","sourceRoot":"","sources":["../../../src/browser/detection.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAWtD;AAgBD;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAelE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D"}

package/dist/types/browser/emulation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Device emulation data and standalone resolution functions.
+ *
+ * The BrowserManager methods that perform context recreation (emulateDevice,
+ * recreateContext, applyUserAgent) remain in manager.ts because they depend on
+ * many private BrowserManager fields (context, browser, pages, tabSnapshots,
+ * refMap, activeFramePerTab, userRoutes, domainFilter, etc.).
+ *
+ * TODO: When BrowserManager is further decomposed, move emulateDevice /
+ * recreateContext / setViewport here as well.
+ */
+export interface DeviceDescriptor {
+    viewport: {
+        width: number;
+        height: number;
+    };
+    userAgent: string;
+    deviceScaleFactor: number;
+    isMobile: boolean;
+    hasTouch: boolean;
+}
+/** Shorthand aliases for common devices → Playwright device names */
+export declare const DEVICE_ALIASES: Record<string, string>;
+/** Custom device descriptors for devices not yet in Playwright's built-in list */
+export declare const CUSTOM_DEVICES: Record<string, DeviceDescriptor>;
+/** Resolve a device name (alias or Playwright name or custom) to a descriptor, or null */
+export declare function resolveDevice(name: string): DeviceDescriptor | null;
+/** List all available device names */
+export declare function listDevices(): string[];
+//# sourceMappingURL=emulation.d.ts.map

package/dist/types/browser/emulation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulation.d.ts","sourceRoot":"","sources":["../../../src/browser/emulation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qEAAqE;AACrE,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAuBjD,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CA2C3D,CAAC;AAEF,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAwBnE;AAED,sCAAsC;AACtC,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAMtC"}