@iamu-dev/iamu 0.2.0-beta.9 → 0.3.0-beta.1

package/dist/build-info.d.ts

@@ -0,0 +1,53 @@
+import { type BuildMetadata } from "@iamu-dev/protocol";
+import { type WorktreeDetector } from "./worktree-state.js";
+/** Environment variables, as `process.env` holds them. */
+export type Env = Record<string, string | undefined>;
+/** Runs `git <args>` in `cwd`; returns trimmed stdout or null. */
+export type GitRunner = (args: string[], cwd: string) => string | null;
+/** `git` via execFile, silent and bounded; null when git is absent or fails. */
+export declare const runGit: GitRunner;
+interface CiInfo {
+    git_sha?: string;
+    git_branch?: string;
+    base_sha?: string;
+    ci?: {
+        provider: string;
+        run_url: string;
+    };
+}
+/**
+ * What the CI environment says about the build. Recognizes GitHub
+ * Actions and Azure Pipelines; an empty object anywhere else.
+ */
+export declare function detectCi(env: Env): CiInfo;
+export interface DetectBuildOptions {
+    /** `--build <label>`. */
+    label?: string;
+    /** Directory to ask git about. */
+    cwd: string;
+    env?: Env;
+    git?: GitRunner;
+    /**
+     * Uncommitted changes outside `iamu/` (`git_dirty`, `worktree_hash`).
+     * Recorded alongside a `--build` label, not instead of it.
+     */
+    worktree?: WorktreeDetector;
+}
+/**
+ * Build metadata for a run started now. Flags win over CI variables,
+ * CI variables over the local checkout. Returns undefined when nothing
+ * at all is known.
+ *
+ * @example
+ * ```ts
+ * const build = detectBuild({ cwd: projectRoot, label: "2.4.0" });
+ * // { label: "2.4.0", git_sha: "3f9c2a1…", git_branch: "main", git_dirty: false }
+ * ```
+ */
+export declare function detectBuild(opts: DetectBuildOptions): BuildMetadata | undefined;
+/**
+ * The run's environment: `--env <name>` when given, otherwise the
+ * target URL's origin.
+ */
+export declare function resolveEnvironment(explicit: string | undefined, targetUrl: string): string | undefined;
+export {};

package/dist/cloud-url.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves cloud web dashboard URLs for projects and walkthrough runs.
+ */
+/**
+ * Resolves the web dashboard base URL from an API URL or environment variable.
+ *
+ * Precedence:
+ * 1. IAMU_WEB_URL environment variable (explicit override)
+ * 2. If apiUrl targets api.iamu.dev -> https://app.iamu.dev
+ * 3. If apiUrl targets localhost:3000 -> http://localhost:3001 (standard local dev split)
+ *    unless overridden by IAMU_WEB_URL
+ * 4. If apiUrl starts with https://api. -> https://app.
+ * 5. Fallback: apiUrl without trailing slash
+ */
+export declare function getCloudWebBase(apiUrl?: string | null): string;
+/**
+ * Builds the cloud dashboard URL for a project or specific walkthrough run.
+ */
+export declare function getCloudDashboardUrl(apiUrl: string | null | undefined, projectId: string, walkthroughId?: string): string;

package/dist/commands/auth-http.d.ts

@@ -0,0 +1,37 @@
+/** Per-request budget for auth endpoints, headers plus body. */
+export declare const AUTH_REQUEST_TIMEOUT_MS = 10000;
+/** A fully read response from an auth endpoint. */
+export interface AuthHttpResponse {
+    status: number;
+    ok: boolean;
+    /** Raw body text. */
+    text: string;
+    /** Body parsed as JSON, or `null` when it is not JSON. */
+    json: unknown;
+}
+/** Request options for {@link requestAuthApi}. */
+export interface AuthRequestOptions {
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    /** Budget for this request; default {@link AUTH_REQUEST_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Call an auth endpoint and read the whole body within `timeoutMs`.
+ *
+ * @param url - Absolute endpoint URL.
+ * @param opts - Method, headers, body and timeout.
+ * @returns Status plus the body as text and (when parseable) JSON.
+ * @throws {@link IamuNetworkError} when the timeout fires; other fetch
+ *   failures propagate unchanged.
+ *
+ * @example
+ * ```ts
+ * const res = await requestAuthApi(`${apiUrl}/api/projects`, {
+ *   headers: { Authorization: `Bearer ${token}` },
+ * });
+ * if (res.ok) console.log(res.json);
+ * ```
+ */
+export declare function requestAuthApi(url: string, opts?: AuthRequestOptions): Promise<AuthHttpResponse>;

package/dist/commands/auth-project-choice.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Which cloud project `iamu auth login` links to. Pure, so every branch
+ * is testable without a TTY or network.
+ *
+ * Linking pushes every local entity to the chosen project, so a wrong
+ * guess leaks one product's data into another. The rules therefore
+ * never pick between several projects on the user's behalf.
+ */
+/** A cloud project as `GET /api/projects` lists it. */
+export interface CloudProjectSummary {
+    id: string;
+    name: string;
+    slug: string;
+}
+/** `--project` value that asks for a new cloud project. */
+export declare const CREATE_NEW_PROJECT = "new";
+/** Inputs to {@link decideCloudProject}. */
+export interface ProjectChoiceInput {
+    /** Projects the account can see. */
+    projects: readonly CloudProjectSummary[];
+    /** `--project` value, if given. */
+    requested?: string;
+    /** Project this repo is already linked to (credentials were lost). */
+    linkedProjectId?: string | null;
+    /** `--yes`: accept the only candidate. */
+    yes?: boolean;
+    /** Whether a human can be prompted. */
+    interactive: boolean;
+}
+/** Outcome of {@link decideCloudProject}. */
+export type ProjectDecision = {
+    kind: "link";
+    projectId: string;
+} | {
+    kind: "create";
+} | {
+    kind: "prompt";
+} | {
+    kind: "refuse";
+    reason: "ambiguous" | "unknown_project";
+};
+/**
+ * Decide the project to link.
+ *
+ * - `--project new` creates; `--project <id>` must be one of `projects`.
+ * - An existing link is kept.
+ * - No projects at all: create one named after the local project.
+ * - `--yes` links the single project when there is exactly one; with
+ *   several it does not pick, it falls through.
+ * - Otherwise prompt when interactive, refuse (and list) when not.
+ *
+ * @param input - Available projects plus flags and TTY state.
+ * @returns What to do next.
+ *
+ * @example
+ * ```ts
+ * const d = decideCloudProject({ projects, requested: "new", interactive: false });
+ * // { kind: "create" }
+ * ```
+ */
+export declare function decideCloudProject(input: ProjectChoiceInput): ProjectDecision;
+/**
+ * Narrow a `GET /api/projects` body to project summaries.
+ *
+ * @param body - Parsed JSON body.
+ * @returns The projects, or `null` when the body is not a project list.
+ *
+ * @example
+ * ```ts
+ * const projects = parseProjectList(res.json);
+ * if (!projects) throw new Error("unexpected response");
+ * ```
+ */
+export declare function parseProjectList(body: unknown): CloudProjectSummary[] | null;

package/dist/commands/auth-token-input.d.ts

@@ -0,0 +1,21 @@
+/** The readable side `readTokenFromStdin` needs. */
+export type TokenInputStream = AsyncIterable<string | Uint8Array> & {
+    isTTY?: boolean;
+};
+/**
+ * Read an API token piped on stdin (`--token-stdin`), so it never shows
+ * up in `ps`, shell history or CI logs the way `--token <value>` does.
+ * Surrounding whitespace (a trailing newline from `echo`) is dropped.
+ *
+ * @param stream - Input stream; defaults to `process.stdin`.
+ * @returns The token.
+ * @throws {@link IamuValidationError} when stdin is a terminal, empty,
+ *   oversized, or holds more than one word.
+ *
+ * @example
+ * ```ts
+ * // printf %s "$IAMU_CI_TOKEN" | iamu auth login --token-stdin
+ * const token = await readTokenFromStdin();
+ * ```
+ */
+export declare function readTokenFromStdin(stream?: TokenInputStream): Promise<string>;

package/dist/commands/auth.d.ts

@@ -0,0 +1,84 @@
+/** Launches a program with its arguments as an argv array — no shell. */
+export type CommandRunner = (file: string, args: readonly string[]) => void;
+/**
+ * Open `url` in the platform browser. The URL is always a separate argv
+ * element: interpolating it into a shell command line let a crafted
+ * login URL run commands.
+ *
+ * @param url - The URL to open.
+ * @param run - Process launcher; injectable so tests never spawn.
+ *
+ * @example
+ * ```ts
+ * openBrowser("https://iamu.dev/login");
+ * ```
+ */
+export declare function openBrowser(url: string, run?: CommandRunner): void;
+/** Flags of `iamu auth login`. */
+export interface AuthLoginOptions {
+    url?: string;
+    /** Accept the only candidate project; never picks between several. */
+    yes?: boolean;
+    /** Cloud project id to link, or `new` to create one. */
+    project?: string;
+    browser?: boolean;
+    local?: boolean | string | number;
+    staging?: boolean;
+    /** Token on argv. Visible to `ps` and shell history; prefer `tokenStdin`. */
+    token?: string;
+    /** Read the token from stdin instead of argv. */
+    tokenStdin?: boolean;
+    webUrl?: string;
+}
+/**
+ * Timing knobs for {@link authLogin}. Exposed so tests can shrink them.
+ *
+ * @internal
+ */
+export interface AuthLoginTiming {
+    /** Pause between token polls. */
+    pollIntervalMs: number;
+    /** Hard deadline for the whole browser login. */
+    pollTimeoutMs: number;
+    /** Budget for each HTTP request. */
+    requestTimeoutMs: number;
+}
+/**
+ * `iamu auth login`: obtain a token (flag, stdin, stored/env, or browser
+ * device flow), store it, then link the project to a cloud project.
+ * Every failure sets exit code 1 (2 for conflicting flags); in a
+ * non-interactive shell it never chooses between cloud projects.
+ *
+ * @param opts - Command flags.
+ * @param timing - Test-only timing overrides.
+ *
+ * @example
+ * ```ts
+ * await authLogin({ project: "new" });
+ * ```
+ */
+export declare function authLogin(opts?: AuthLoginOptions, timing?: Partial<AuthLoginTiming>): Promise<void>;
+/**
+ * `iamu auth disconnect`: unlink the project and forget the stored token
+ * for its API URL. Local entities are kept.
+ *
+ * @example
+ * ```ts
+ * await authDisconnect();
+ * ```
+ */
+export declare function authDisconnect(): Promise<void>;
+/**
+ * `iamu auth status`: whether a token is available and the project is
+ * linked. Never prints the token.
+ *
+ * @param opts - `json` prints a machine-readable object on stdout.
+ *
+ * @example
+ * ```ts
+ * await authStatus({ json: true });
+ * ```
+ */
+export declare function authStatus(opts?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/browse-actions.d.ts

@@ -0,0 +1,61 @@
+import type { Page } from "playwright-core";
+/** Options an action reads. */
+export interface ActionOptions {
+    /** Pick the nth (0-based) match instead of the first. */
+    nth?: string;
+    /** Press Enter after fill/select. */
+    submit?: boolean;
+}
+/**
+ * One page action: how it is called, what it targets (for the "nothing
+ * matches" error), and what it does.
+ *
+ * @public
+ */
+export interface PageAction {
+    /** Call shape after `iamu browse`, e.g. `click <role> "<name>" [--nth N]`. */
+    usage: string;
+    /** Positional arguments required after the action name. */
+    minArgs: number;
+    /** What the action looks for, named the way the error message says it. */
+    target?: (args: string[]) => string;
+    run(page: Page, args: string[], opts: ActionOptions): Promise<void>;
+}
+export interface IndexedElement {
+    index: number;
+    tag: string;
+    role: string;
+    name: string;
+    type?: string;
+    disabled?: boolean;
+}
+export declare const INDEXED_SELECTOR: string;
+export declare function markAndQueryIndexedElements(page: Page): Promise<IndexedElement[]>;
+/**
+ * Every page action, by name. `shot` does nothing to the page; the
+ * screenshot is taken after any action when one is asked for.
+ *
+ * @example
+ * ```ts
+ * const action = PAGE_ACTIONS.click;
+ * if (args.length >= action.minArgs) await action.run(page, args, {});
+ * ```
+ *
+ * @public
+ */
+export declare const PAGE_ACTIONS: Readonly<Record<string, PageAction>>;
+/**
+ * Look up a page action by name, own properties only (so `toString`
+ * and friends are not actions).
+ *
+ * @param name - The action name as typed.
+ * @returns The action, or undefined.
+ *
+ * @example
+ * ```ts
+ * findPageAction("click")?.usage; // 'click <role> "<name>" [--nth N]'
+ * ```
+ *
+ * @public
+ */
+export declare function findPageAction(name: string): PageAction | undefined;

package/dist/commands/browse-driver.d.ts

@@ -0,0 +1,121 @@
+import type { Page } from "playwright-core";
+/** A page size in CSS pixels. */
+export interface Size {
+    width: number;
+    height: number;
+}
+/**
+ * The page a command acts on, plus how to let go of it. Detaching
+ * disconnects from the browser; it never closes the page.
+ *
+ * @public
+ */
+export interface AttachedPage {
+    page: Page;
+    /** All non-devtools pages open in the context. */
+    pages?: Page[];
+    /** Dialog messages encountered while attached, e.g. `[alert] You must agree to terms`. */
+    dialogs?: string[];
+    detach(): Promise<void>;
+}
+/**
+ * What `iamu browse` needs from the machine and the browser — the real
+ * one spawns Chrome and speaks CDP; tests pass a fake.
+ *
+ * @public
+ */
+export interface BrowserDriver {
+    /** Is a browser answering CDP on this port? Must not hang. */
+    isRunning(port: number): Promise<boolean>;
+    /** Launch Chrome detached with these arguments; returns its PID. */
+    launch(chrome: string, args: string[]): number | undefined;
+    /**
+     * Fit the running window's content area to the viewport
+     * (`Browser.setWindowBounds`), so a person watching sees the
+     * persona's screen. Best effort: a window cannot be phone-narrow, and
+     * every command emulates the stored viewport on its page anyway.
+     */
+    resize(port: number, viewport: Size | null): Promise<void>;
+    /** Attach over CDP to the page the persona is on. Throws when nothing answers. */
+    attach(port: number, pageIndex?: number): Promise<AttachedPage>;
+    /** Ask the browser on this port to close (`Browser.close`). Best effort. */
+    closeBrowser(port: number): Promise<void>;
+    /** The full command line of `pid`, or null when it is gone or cannot be read. */
+    commandLine(pid: number): Promise<string | null>;
+    /** Send SIGTERM to `pid`. Never throws. */
+    kill(pid: number): void;
+}
+/** How long a CDP liveness probe may take before the port counts as dead. */
+export declare const CDP_PROBE_TIMEOUT_MS = 1000;
+/**
+ * Is a browser answering CDP on `port`? A process that accepts the
+ * connection but never answers (a hung Chrome, something else on the
+ * port) counts as not running once `timeoutMs` passes.
+ *
+ * @param port - CDP port on 127.0.0.1.
+ * @param timeoutMs - Give up after this long.
+ * @returns True when `/json/version` answers 2xx in time.
+ *
+ * @example
+ * ```ts
+ * if (!(await probeCdp(9333))) console.log("no browser");
+ * ```
+ *
+ * @public
+ */
+export declare function probeCdp(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * The command line of a running process, read without a shell:
+ * `/proc/<pid>/cmdline` on Linux, else `ps -ww -o args= -p <pid>`.
+ * Windows has no equivalent we trust, so it answers null there — and
+ * callers then leave the process alone.
+ *
+ * @param pid - Process ID to inspect.
+ * @param platform - Defaults to `process.platform`.
+ * @returns The arguments joined by spaces, or null.
+ *
+ * @example
+ * ```ts
+ * const cmd = await readProcessCommandLine(12345);
+ * ```
+ *
+ * @public
+ */
+export declare function readProcessCommandLine(pid: number, platform?: NodeJS.Platform): Promise<string | null>;
+/**
+ * Was this command line launched with exactly this `--user-data-dir`?
+ * The profile directory is ours alone, so a match means the PID is the
+ * Chrome `iamu browse start` launched, not a process that reused its PID.
+ *
+ * @param commandLine - From {@link readProcessCommandLine}.
+ * @param profileDir - The `--user-data-dir` we launched with.
+ * @returns True only on an exact flag match.
+ *
+ * @example
+ * ```ts
+ * isOurBrowser("chrome --user-data-dir=/h/.iamu/browse/profile", "/h/.iamu/browse/profile"); // true
+ * ```
+ *
+ * @public
+ */
+export declare function isOurBrowser(commandLine: string | null, profileDir: string): boolean;
+/**
+ * SIGTERM `pid` only if it is verifiably our Chrome (see
+ * {@link isOurBrowser}). PIDs get reused; anything else is left alone
+ * and Chrome's own profile lock guards a second launch.
+ *
+ * @param pid - PID recorded in the browse state.
+ * @param profileDir - The `--user-data-dir` it was launched with.
+ * @param driver - Supplies `commandLine` and `kill`.
+ * @returns True when the process was signalled.
+ *
+ * @example
+ * ```ts
+ * await reapBrowser(state.pid, profileDir, cdpDriver);
+ * ```
+ *
+ * @public
+ */
+export declare function reapBrowser(pid: number, profileDir: string, driver: Pick<BrowserDriver, "commandLine" | "kill">): Promise<boolean>;
+/** The real driver: spawns Chrome and speaks CDP through playwright-core. */
+export declare const cdpDriver: BrowserDriver;

package/dist/commands/browse.d.ts

@@ -0,0 +1,195 @@
+import type { Page } from "playwright-core";
+import { type BrowserDriver, type Size } from "./browse-driver.js";
+export type { BrowserDriver } from "./browse-driver.js";
+/** Parsed options for `iamu browse <command>`. */
+export interface BrowseOptions {
+    shot?: string;
+    nth?: string;
+    submit?: boolean;
+    full?: boolean;
+    viewport?: string;
+    width?: string;
+    height?: string;
+    headless?: boolean;
+    port?: string | number;
+    /** `start`: size the browser for this run's persona. */
+    run?: string;
+    action?: string;
+    note?: string;
+    surface?: string;
+    maxSteps?: string | number;
+    stepFile?: string;
+    json?: boolean;
+    /** Annotate snapshot with 1-based index numbers [#N] for click-index / fill-index */
+    indexed?: boolean;
+}
+interface BrowseState {
+    port: number;
+    viewport: Size | null;
+    pid?: number;
+    headless?: boolean;
+    activeTabIndex?: number;
+}
+/**
+ * The state `iamu browse start` left in `~/.iamu/browse/state.json`, or
+ * null when no browser was started (or the file is unreadable).
+ *
+ * @example
+ * ```ts
+ * const state = readBrowseState();
+ * if (state) console.log(`CDP on :${state.port}`);
+ * ```
+ *
+ * @public
+ */
+export declare function readBrowseState(): BrowseState | null;
+/**
+ * Parse `"390x844"` into a size.
+ *
+ * @param value - `WxH`, 2–5 digits each.
+ * @returns The size, or null when absent or malformed.
+ *
+ * @example
+ * ```ts
+ * parseViewport("390x844"); // { width: 390, height: 844 }
+ * ```
+ *
+ * @public
+ */
+export declare function parseViewport(value: string | undefined): Size | null;
+/**
+ * The installed Chrome/Chromium to drive: `IAMU_BROWSER`, else the
+ * usual install location for this platform.
+ *
+ * @example
+ * ```ts
+ * const chrome = findChrome();
+ * if (!chrome) console.error("Install Chrome or set IAMU_BROWSER");
+ * ```
+ *
+ * @public
+ */
+export declare function findChrome(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (p: string) => boolean): string | null;
+/**
+ * Should `start` launch without a window? `--headless` wins, then
+ * `IAMU_HEADLESS`, then CI or a Linux box with no `DISPLAY`.
+ *
+ * @example
+ * ```ts
+ * isHeadlessEnvironment({ headless: true }); // true
+ * ```
+ *
+ * @public
+ */
+export declare function isHeadlessEnvironment(opts?: BrowseOptions): boolean;
+/**
+ * Should Chrome run with `--no-sandbox`? Only when it cannot start
+ * otherwise — as root (Chrome refuses to sandbox as root, typical in
+ * containers) — or when explicitly asked via `IAMU_BROWSE_NO_SANDBOX=1`.
+ * Being headless or in CI is not a reason: the sandbox is what keeps a
+ * page the persona visits away from the machine.
+ *
+ * @param env - Defaults to `process.env`.
+ * @param uid - Effective user ID; defaults to `process.getuid()` (undefined on Windows).
+ * @returns True when `--no-sandbox` should be passed.
+ *
+ * @example
+ * ```ts
+ * shouldDisableSandbox({ IAMU_BROWSE_NO_SANDBOX: "1" }, 1000); // true
+ * shouldDisableSandbox({ CI: "true" }, 1000); // false
+ * ```
+ *
+ * @public
+ */
+export declare function shouldDisableSandbox(env?: NodeJS.ProcessEnv, uid?: number | undefined): boolean;
+/**
+ * Start the browser, or converge the one already running: a running
+ * browser is reused, and resized when the requested viewport differs
+ * from the one it was started with — never silently left at another
+ * persona's size.
+ *
+ * A PID left by an earlier `start` whose CDP no longer answers is
+ * terminated only when its command line shows our `--user-data-dir`;
+ * a PID the OS has since handed to another process is left alone.
+ *
+ * @param opts - `viewport`, `run`, `port`, `width`, `height`, `headless`, `json`.
+ * @param driver - Machine/browser seam; tests pass a fake.
+ *
+ * @example
+ * ```ts
+ * await start({ viewport: "390x844" });
+ * ```
+ *
+ * @public
+ */
+export declare function start(opts: BrowseOptions, driver?: BrowserDriver): Promise<void>;
+/** Where the page ended up after an action. */
+export interface PageResult {
+    url: string;
+    title: string;
+    /** Absolute path of the screenshot written, or null when none was asked for. */
+    screenshot: string | null;
+    /** Dialog messages encountered while attached (e.g. alerts/confirms auto-handled). */
+    dialog?: string;
+    /** Lightweight semantic text summary of page content for stagnation detection. */
+    contentSnippet?: string;
+    /** Detected anti-bot challenge (e.g. Cloudflare Turnstile, Google reCAPTCHA, hCaptcha). */
+    challenge?: string;
+}
+/** Compute a fast fingerprint of page URL and visible text to detect stagnation across steps. */
+export declare function computePageFingerprint(url: string, bodySnippet: string): string;
+/**
+ * Track page state across consecutive steps in a run.
+ * Emits a warning when 3 consecutive steps produce zero observable URL/DOM transition.
+ */
+export declare function checkAndRecordStagnation(projectRoot: string, runId: string, fingerprint: string, action: string): {
+    count: number;
+    warning?: string;
+};
+/**
+ * Wait for the page to visually settle before taking a screenshot.
+ *
+ * SPA actions (state updates, CSS transitions, element mounts) do not trigger
+ * a navigation, so `domcontentloaded` returns immediately. Rather than a blunt
+ * hardcoded sleep, this flushes the rendering pipeline via double
+ * `requestAnimationFrame` and waits for in-flight CSS/web animations to finish,
+ * bounded by `maxWaitMs` (default 300ms) to ensure it never hangs on continuous
+ * animations like spinners.
+ *
+ * @public
+ */
+export declare function waitForVisualStability(page: Page, maxWaitMs?: number): Promise<void>;
+/**
+ * Detect known anti-bot challenges (Cloudflare, reCAPTCHA, hCaptcha, Arkose, AWS WAF).
+ *
+ * @public
+ */
+export declare function detectAntiBotChallenge(page: Page, allowEvaluate?: boolean): Promise<string | undefined>;
+/**
+ * Attach to the running browser, run `fn` on the page the persona is
+ * on, optionally screenshot it, and return where the page is. Prints
+ * nothing on success — the caller decides the output shape. Detaching
+ * never closes the page.
+ *
+ * @public
+ */
+export declare function withPage(opts: BrowseOptions, driver: BrowserDriver, fn: (page: Page) => Promise<void>, 
+/** What the action looks for, named for the error message. */
+target?: string): Promise<PageResult | null>;
+/**
+ * `iamu browse <command> [args…]` — dispatch one browse subcommand.
+ * Failures print to stderr and set exit code 1.
+ *
+ * @param command - `start`, `stop`, `step`, `snapshot`, `shot`, or a page action.
+ * @param args - Positional arguments after the command.
+ * @param opts - Parsed CLI options.
+ * @param driver - Machine/browser seam; tests pass a fake.
+ *
+ * @example
+ * ```ts
+ * await browse("click", ["button", "Sign in"], { json: true });
+ * ```
+ *
+ * @public
+ */
+export declare function browse(command: string, args: string[], opts: BrowseOptions, driver?: BrowserDriver): Promise<void>;