@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/tui.js

@@ -0,0 +1,179 @@
+/**
+ * tui.ts — Zero-dependency interactive TUI components
+ *
+ * Uses raw stdin mode + ANSI escape codes for interactive prompts.
+ */
+import { EXIT_CODES } from './errors.js';
+/**
+ * Interactive multi-select checkbox prompt.
+ *
+ * Controls:
+ *   ↑/↓ or j/k  — navigate
+ *   Space        — toggle selection
+ *   a            — toggle all
+ *   Enter        — confirm
+ *   q/Esc        — cancel (returns empty)
+ */
+export async function checkboxPrompt(items, opts = {}) {
+    if (items.length === 0)
+        return [];
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY) {
+        // Non-interactive: return all checked items
+        return items.filter(i => i.checked).map(i => i.value);
+    }
+    let cursor = 0;
+    const state = items.map(i => ({ ...i }));
+    function render() {
+        // Move cursor to start and clear
+        let out = '';
+        if (opts.title) {
+            out += `\n${opts.title}\n\n`;
+        }
+        for (let i = 0; i < state.length; i++) {
+            const item = state[i];
+            const pointer = i === cursor ? '❯' : ' ';
+            const checkbox = item.checked ? '◉' : '○';
+            const status = item.status ?? '';
+            out += `  ${pointer} ${checkbox} ${item.label}${status ? `  ${status}` : ''}\n`;
+        }
+        out += `\n  Up/Down navigate | Space toggle | a all | Enter confirm | q cancel\n`;
+        return out;
+    }
+    return new Promise((resolve) => {
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdout.write('\x1b[?25l'); // Hide cursor
+        let firstDraw = true;
+        function draw() {
+            // Clear previous render (skip on first draw)
+            if (!firstDraw) {
+                const lines = render().split('\n').length;
+                stdout.write(`\x1b[${lines}A\x1b[J`);
+            }
+            firstDraw = false;
+            stdout.write(render());
+        }
+        function cleanup() {
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            stdin.removeListener('data', onData);
+            // Clear the TUI and restore cursor
+            const lines = render().split('\n').length;
+            stdout.write(`\x1b[${lines}A\x1b[J`);
+            stdout.write('\x1b[?25h'); // Show cursor
+        }
+        function onData(data) {
+            const key = data.toString();
+            // Arrow up / k
+            if (key === '\x1b[A' || key === 'k') {
+                cursor = (cursor - 1 + state.length) % state.length;
+                draw();
+                return;
+            }
+            // Arrow down / j
+            if (key === '\x1b[B' || key === 'j') {
+                cursor = (cursor + 1) % state.length;
+                draw();
+                return;
+            }
+            // Space — toggle
+            if (key === ' ') {
+                state[cursor].checked = !state[cursor].checked;
+                draw();
+                return;
+            }
+            // Tab — toggle and move down
+            if (key === '\t') {
+                state[cursor].checked = !state[cursor].checked;
+                cursor = (cursor + 1) % state.length;
+                draw();
+                return;
+            }
+            // 'a' — toggle all
+            if (key === 'a') {
+                const allChecked = state.every(i => i.checked);
+                for (const item of state)
+                    item.checked = !allChecked;
+                draw();
+                return;
+            }
+            // Enter — confirm
+            if (key === '\r' || key === '\n') {
+                cleanup();
+                const selected = state.filter(i => i.checked).map(i => i.value);
+                // Show summary
+                stdout.write(`  ✓ ${selected.length} file(s) selected\n\n`);
+                resolve(selected);
+                return;
+            }
+            // q / Esc — cancel
+            if (key === 'q' || key === '\x1b') {
+                cleanup();
+                stdout.write(`  ✗ Cancelled\n\n`);
+                resolve([]);
+                return;
+            }
+            // Ctrl+C — exit process
+            if (key === '\x03') {
+                cleanup();
+                process.exit(EXIT_CODES.INTERRUPTED);
+            }
+        }
+        stdin.on('data', onData);
+        draw();
+    });
+}
+/**
+ * Simple yes/no confirmation prompt.
+ *
+ * In non-TTY environments, returns `defaultYes` (defaults to true) without blocking.
+ * In TTY, waits for a single keypress: y/Enter → true, n/Esc/q → false.
+ */
+export async function confirmPrompt(message, defaultYes = true) {
+    const { stdin, stdout } = process;
+    if (!stdin.isTTY)
+        return defaultYes;
+    const hint = defaultYes ? '[Y/n]' : '[y/N]';
+    stdout.write(`  ${message} ${hint} `);
+    return new Promise((resolve) => {
+        const wasRaw = stdin.isRaw;
+        stdin.setRawMode(true);
+        stdin.resume();
+        function cleanup() {
+            stdin.setRawMode(wasRaw ?? false);
+            stdin.pause();
+            stdin.removeListener('data', onData);
+            stdout.write('\n');
+        }
+        function onData(data) {
+            const key = data.toString();
+            // Ctrl+C
+            if (key === '\x03') {
+                cleanup();
+                process.exit(EXIT_CODES.INTERRUPTED);
+            }
+            // Enter — use default
+            if (key === '\r' || key === '\n') {
+                cleanup();
+                resolve(defaultYes);
+                return;
+            }
+            // y/Y — yes
+            if (key === 'y' || key === 'Y') {
+                cleanup();
+                resolve(true);
+                return;
+            }
+            // n/N/q/Esc — no
+            if (key === 'n' || key === 'N' || key === 'q' || key === '\x1b') {
+                cleanup();
+                resolve(false);
+                return;
+            }
+            // Ignore other keys
+        }
+        stdin.on('data', onData);
+    });
+}

package/dist/src/tui.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tui.test.js

@@ -0,0 +1,19 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { confirmPrompt } from './tui.js';
+describe('confirmPrompt', () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns defaultYes when stdin is not TTY', async () => {
+        const result = await confirmPrompt('Restart?', true);
+        expect(result).toBe(true);
+    });
+    it('returns false when defaultYes is false and non-TTY', async () => {
+        const result = await confirmPrompt('Restart?', false);
+        expect(result).toBe(false);
+    });
+    it('defaults to true when defaultYes is omitted and non-TTY', async () => {
+        const result = await confirmPrompt('Restart?');
+        expect(result).toBe(true);
+    });
+});

package/dist/src/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Page interface: type-safe abstraction over browser page.
+ *
+ * All pipeline steps and CLI adapters should use this interface
+ * instead of `any` for browser interactions.
+ */
+export interface BrowserCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    expirationDate?: number;
+}
+export interface SnapshotOptions {
+    interactive?: boolean;
+    compact?: boolean;
+    maxDepth?: number;
+    raw?: boolean;
+    viewportExpand?: number;
+    maxTextLength?: number;
+    /** Observation backend. `dom` is the stable default; `ax` is an opt-in prototype. */
+    source?: 'dom' | 'ax';
+}
+export interface WaitOptions {
+    text?: string;
+    selector?: string;
+    time?: number;
+    timeout?: number;
+}
+export interface BrowserDownloadWaitResult {
+    downloaded: boolean;
+    id?: number;
+    filename?: string;
+    url?: string;
+    finalUrl?: string;
+    mime?: string;
+    totalBytes?: number;
+    state?: string;
+    danger?: string;
+    error?: string;
+    elapsedMs: number;
+}
+export interface ScreenshotOptions {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    fullPage?: boolean;
+    /** Overlay current browser-state refs on visible interactive elements. */
+    annotate?: boolean;
+    /** Override viewport width in CSS pixels for the screenshot only (cleared after). */
+    width?: number;
+    /** Override viewport height in CSS pixels for the screenshot only (ignored when fullPage). */
+    height?: number;
+    path?: string;
+}
+export interface FetchJsonOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeoutMs?: number;
+}
+export type BrowserEvaluateFunction<Args extends unknown[] = unknown[], Result = unknown> = (...args: Args) => Result | Promise<Result>;
+export interface IPage {
+    goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
+    evaluate<T = any>(js: string): Promise<T>;
+    evaluate<Args extends unknown[], T>(fn: BrowserEvaluateFunction<Args, T>, ...args: Args): Promise<Awaited<T>>;
+    /** Safely evaluate JS with pre-serialized arguments — prevents injection. */
+    evaluateWithArgs?(js: string, args: Record<string, unknown>): Promise<any>;
+    /**
+     * Fetch JSON from inside the browser context, carrying the page's cookies.
+     * This is intentionally narrow: browser-context JSON fetch, not a generic
+     * HTTP client.
+     */
+    fetchJson(url: string, opts?: FetchJsonOptions): Promise<unknown>;
+    getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    snapshot(opts?: SnapshotOptions): Promise<any>;
+    click(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    dblClick?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    hover?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    focus?(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        focused: boolean;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    setChecked?(ref: string, checked: boolean, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        checked: boolean;
+        changed: boolean;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        kind?: string;
+    }>;
+    uploadFiles?(ref: string, files: string[], opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        uploaded: boolean;
+        files: number;
+        file_names: string[];
+        target: string;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        multiple?: boolean;
+        accept?: string;
+    }>;
+    drag?(source: string, target: string, opts?: {
+        from?: {
+            nth?: number;
+            firstOnMulti?: boolean;
+        };
+        to?: {
+            nth?: number;
+            firstOnMulti?: boolean;
+        };
+    }): Promise<{
+        dragged: boolean;
+        source: string;
+        target: string;
+        source_matches_n: number;
+        target_matches_n: number;
+        source_match_level: 'exact' | 'stable' | 'reidentified';
+        target_match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    typeText(ref: string, text: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    fillText(ref: string, text: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        filled: boolean;
+        verified: boolean;
+        expected: string;
+        actual: string;
+        length: number;
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+        mode?: 'input' | 'textarea' | 'contenteditable';
+    }>;
+    pressKey(key: string): Promise<void>;
+    scrollTo(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<any>;
+    getFormState(): Promise<any>;
+    wait(options: number | WaitOptions): Promise<void>;
+    waitForDownload?(pattern?: string, timeoutMs?: number): Promise<BrowserDownloadWaitResult>;
+    tabs(): Promise<any>;
+    closeTab?(target?: number | string): Promise<void>;
+    newTab?(url?: string): Promise<string | undefined>;
+    selectTab(target: number | string): Promise<void>;
+    networkRequests(includeStatic?: boolean): Promise<any>;
+    consoleMessages(level?: string): Promise<any>;
+    scroll(direction?: string, amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<any[]>;
+    waitForCapture(timeout?: number): Promise<void>;
+    screenshot(options?: ScreenshotOptions): Promise<string>;
+    annotatedScreenshot?(options?: ScreenshotOptions): Promise<string>;
+    startNetworkCapture?(pattern?: string): Promise<boolean>;
+    readNetworkCapture?(): Promise<unknown[]>;
+    /**
+     * Set local file paths on a file input element via CDP DOM.setFileInputFiles.
+     * Chrome reads the files directly — no base64 encoding or payload size limits.
+     */
+    setFileInput?(files: string[], selector?: string): Promise<void>;
+    /**
+     * Insert text via native CDP Input.insertText into the currently focused element.
+     * Useful for rich editors that ignore synthetic DOM value/text mutations.
+     */
+    insertText?(text: string): Promise<void>;
+    closeWindow?(): Promise<void>;
+    /** Returns the current page URL, or null if unavailable. */
+    getCurrentUrl?(): Promise<string | null>;
+    /** Returns the active page identity (targetId), or undefined if not yet resolved. */
+    getActivePage?(): string | undefined;
+    /** Bind the page object to a specific page identity (targetId). */
+    setActivePage?(page?: string): void;
+    /** Send a raw CDP command via chrome.debugger passthrough. */
+    cdp?(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Accept or dismiss the currently open JavaScript alert/confirm/prompt dialog. */
+    handleJavaScriptDialog?(accept: boolean, promptText?: string): Promise<void>;
+    /** List cross-origin iframe targets in snapshot order. */
+    frames?(): Promise<Array<{
+        index: number;
+        frameId: string;
+        url: string;
+        name: string;
+    }>>;
+    /** Evaluate JavaScript inside a cross-origin iframe identified by its frame index. */
+    evaluateInFrame?(js: string, frameIndex: number): Promise<unknown>;
+    /** Click at native coordinates via CDP Input.dispatchMouseEvent. */
+    nativeClick?(x: number, y: number): Promise<void>;
+    /** Type text via CDP Input.insertText. */
+    nativeType?(text: string): Promise<void>;
+    /** Press a key via CDP Input.dispatchKeyEvent. */
+    nativeKeyPress?(key: string, modifiers?: string[]): Promise<void>;
+}

package/dist/src/types.js

@@ -0,0 +1,7 @@
+/**
+ * Page interface: type-safe abstraction over browser page.
+ *
+ * All pipeline steps and CLI adapters should use this interface
+ * instead of `any` for browser interactions.
+ */
+export {};

package/dist/src/update-check.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Non-blocking update checker.
+ *
+ * Pattern: register exit-hook + kick-off-background-fetch
+ * - On startup: kick off background fetch (non-blocking)
+ * - On process exit: read cache, print notice if newer version exists
+ * - Check interval: 24 hours
+ * - Notice appears AFTER command output, not before (same as npm/gh/yarn)
+ * - Never delays or blocks the CLI command
+ *
+ * Cache is shared between the CLI process (writes latestVersion / latestExtensionVersion
+ * via background fetch) and the daemon process (writes currentExtensionVersion /
+ * extensionLastSeenAt via `recordExtensionVersion` on each hello). Writes use a
+ * read-merge-write pattern so neither side clobbers the other.
+ */
+declare const EXTENSION_STALE_MS: number;
+interface UpdateCache {
+    lastCheck?: number;
+    latestVersion?: string;
+    latestExtensionVersion?: string;
+    currentExtensionVersion?: string;
+    extensionLastSeenAt?: number;
+}
+interface GitHubReleaseAsset {
+    name: string;
+}
+interface GitHubRelease {
+    tag_name: string;
+    assets?: GitHubReleaseAsset[];
+}
+interface NoticeInputs {
+    cliVersion: string;
+    cache: UpdateCache | null;
+    now: number;
+}
+interface NoticeLines {
+    cli?: string;
+    extension?: string;
+}
+/** Pure function: derive notice text from cache state. Exported for tests. */
+declare function buildUpdateNotices({ cliVersion, cache, now }: NoticeInputs): NoticeLines;
+/**
+ * Register a process exit hook that prints an update notice if a newer
+ * version was found on the last background check.
+ * Notice appears after command output — same pattern as npm/gh/yarn.
+ * Skipped during --get-completions to avoid polluting shell completion output.
+ */
+export declare function registerUpdateNoticeOnExit(): void;
+declare function extractLatestExtensionVersionFromReleases(releases: GitHubRelease[]): string | undefined;
+/**
+ * Kick off a background fetch to npm registry. Writes to cache for next run.
+ * Fully non-blocking — never awaited.
+ */
+export declare function checkForUpdateBackground(): void;
+/**
+ * Stash the current extension version into the shared cache. Called by the
+ * daemon on each hello handshake. Lets the next CLI process compare against
+ * the latest known release and print an exit notice without any extra I/O.
+ */
+export declare function recordExtensionVersion(version: string): void;
+/**
+ * Get the cached latest extension version (if available).
+ * Used by `webcmd doctor` to report extension updates.
+ */
+export declare function getCachedLatestExtensionVersion(): string | undefined;
+export { extractLatestExtensionVersionFromReleases as _extractLatestExtensionVersionFromReleases, buildUpdateNotices as _buildUpdateNotices, EXTENSION_STALE_MS as _EXTENSION_STALE_MS, };