cssprobe-cli 0.3.0 → 0.4.0

package/dist/daemon/daemon.js

@@ -17,6 +17,11 @@ const launcher_1 = require("../browser/launcher");
 const analyzer_1 = require("../engine/analyzer");
 const renderer_1 = require("../engine/renderer");
 const dom_tree_1 = require("../engine/renderers/dom-tree");
+const interactions_1 = require("../browser/interactions");
+const evalSerializer_1 = require("../engine/evalSerializer");
+const flowRunner_1 = require("./flowRunner");
+const frames_1 = require("../browser/frames");
+const sampler_1 = require("../browser/sampler");
 const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
 async function startDaemon(sessionName, clientInfo, options) {
     const sessionConfig = createSessionConfig(clientInfo, sessionName, options);
@@ -74,6 +79,18 @@ async function executeCommand(launcher, args) {
     const command = args._[0];
     const params = args._.slice(1);
     switch (command) {
+        case 'frames': {
+            const frames = (0, frames_1.describeFrames)(requirePage(launcher));
+            if (args.json)
+                return { text: JSON.stringify(frames, null, 2) };
+            return { text: (0, frames_1.formatFrames)(frames) };
+        }
+        case 'page-info': {
+            const page = requirePage(launcher);
+            return {
+                text: JSON.stringify({ url: page.url(), title: await page.title(), frames: (0, frames_1.describeFrames)(page).length }, null, 2),
+            };
+        }
         case 'goto': {
             const url = params[0] || 'about:blank';
             await launcher.open(url);
@@ -88,7 +105,7 @@ async function executeCommand(launcher, args) {
                 downDepth: args.depth || 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             const findings = (0, analyzer_1.analyze)(snapshot);
             if (args.json) {
                 return { text: JSON.stringify((0, renderer_1.renderJSON)(snapshot, findings, args.brief), null, 2) };
@@ -106,7 +123,7 @@ async function executeCommand(launcher, args) {
                 downDepth: args.depth || 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             // Render tree only
             const lines = [];
             lines.push(`## DOM tree (${snapshot.downDepth} levels deep)`);
@@ -124,7 +141,7 @@ async function executeCommand(launcher, args) {
                 downDepth: 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             const findings = (0, analyzer_1.analyze)(snapshot);
             return { text: (0, renderer_1.renderMarkdown)(snapshot, findings, false, true) };
         }
@@ -137,7 +154,7 @@ async function executeCommand(launcher, args) {
                 downDepth: 6,
                 maxNodes: 60,
                 upTo: 'html',
-            });
+            }, (0, frames_1.resolveFrame)(requirePage(launcher), args.frame));
             const findings = (0, analyzer_1.analyze)(snapshot);
             const important = findings.filter(f => f.level === 'warning' || f.level === 'error');
             if (important.length === 0) {
@@ -152,11 +169,9 @@ async function executeCommand(launcher, args) {
             const css = params[0];
             if (!css)
                 throw new Error('CSS is required for inject-css command');
-            const page = launcher.getPage();
-            if (!page)
-                throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
-            await page.addStyleTag({ content: css });
-            return { text: JSON.stringify({ success: true }) };
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            await frame.addStyleTag({ content: css });
+            return { text: JSON.stringify({ success: true, frame: frame.name() || frame.url() }) };
         }
         case 'screenshot': {
             const page = launcher.getPage();
@@ -170,15 +185,25 @@ async function executeCommand(launcher, args) {
             const expression = params[0];
             if (!expression)
                 throw new Error('Expression is required for eval command');
-            const page = launcher.getPage();
-            if (!page)
-                throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
-            const result = await page.evaluate(expression);
-            if (typeof result === 'string')
-                return { text: result };
-            if (result === undefined)
-                return { text: 'undefined' };
-            return { text: JSON.stringify(result, null, 2) };
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            const handle = await frame.evaluateHandle(expression);
+            try {
+                const resolved = await handle.evaluateHandle((value) => Promise.resolve(value));
+                try {
+                    const result = await resolved.evaluate(evalSerializer_1.serializeEvalResult);
+                    if (typeof result === 'string')
+                        return { text: result };
+                    if (result === undefined)
+                        return { text: 'undefined' };
+                    return { text: JSON.stringify(result, null, 2) };
+                }
+                finally {
+                    await resolved.dispose();
+                }
+            }
+            finally {
+                await handle.dispose();
+            }
         }
         case 'resize': {
             const width = parseInt(params[0], 10);
@@ -206,6 +231,111 @@ async function executeCommand(launcher, args) {
                 return { text: JSON.stringify({ ok: true, value: null, note: 'call returned no value' }) };
             return { text: JSON.stringify(result, null, 2) };
         }
+        case 'click':
+        case 'hover': {
+            const selector = params[0];
+            if (!selector)
+                throw new Error(`Selector is required for ${command} command`);
+            const page = requirePage(launcher);
+            const opts = { nth: args.nth, force: args.force, timeout: args.timeout };
+            const result = command === 'click'
+                ? await (0, interactions_1.clickElement)(page, selector, opts)
+                : await (0, interactions_1.hoverElement)(page, selector, opts);
+            if (args.json) {
+                return { text: JSON.stringify({ ok: true, selector, matches: result.matches, nth: result.nth }, null, 2) };
+            }
+            return { text: formatTargetAction(command === 'click' ? 'Clicked' : 'Hovered', selector, result) };
+        }
+        case 'type': {
+            const selector = params[0];
+            const text = params[1];
+            if (!selector || text === undefined)
+                throw new Error('Usage: type <selector> <text>');
+            await (0, interactions_1.typeInto)(requirePage(launcher), selector, text, {
+                press: args.press,
+                sequential: args.sequential,
+                clear: args.clear,
+                delay: args.delay,
+                nth: args.nth,
+                timeout: args.timeout,
+            });
+            if (args.json) {
+                const payload = { ok: true, selector, length: text.length };
+                if (args.press)
+                    payload.pressed = args.press;
+                return { text: JSON.stringify(payload, null, 2) };
+            }
+            const pressedNote = args.press ? ` then pressed ${args.press}` : '';
+            return { text: `Typed ${text.length} chars into ${selector}${pressedNote}` };
+        }
+        case 'wait-for': {
+            // selector is read from the parsed object: option flags are appended to
+            // the argv array after positional args, so params[0] is not reliable here.
+            const selector = args.selector;
+            const timeout = args.timeout ?? 30000;
+            const target = (0, interactions_1.resolveWaitTarget)(selector, {
+                js: args.js,
+                networkIdle: args['network-idle'],
+                state: args.state,
+            });
+            let elapsedMs;
+            try {
+                elapsedMs = await (0, interactions_1.waitForCondition)(requirePage(launcher), target, timeout);
+            }
+            catch (e) {
+                throw new Error(`wait-for failed for ${(0, interactions_1.describeWaitTarget)(target)} within ${timeout}ms: ${e.message}`);
+            }
+            if (args.json) {
+                const payload = {
+                    ok: true,
+                    waitedFor: target.kind === 'networkIdle' ? 'networkidle' : target.kind,
+                    elapsedMs,
+                };
+                if (target.kind === 'selector')
+                    payload.state = target.state;
+                return { text: JSON.stringify(payload, null, 2) };
+            }
+            const label = target.kind === 'selector' ? `${selector} (${target.state})` : (0, interactions_1.describeWaitTarget)(target);
+            return { text: `Wait satisfied: ${label} (${elapsedMs}ms)` };
+        }
+        case 'sample': {
+            const expression = params[0];
+            if (!expression)
+                throw new Error('Expression is required for sample command');
+            const interval = args.interval ?? 250;
+            const duration = args.duration ?? 5000;
+            if (duration <= 0)
+                throw new Error('--duration must be greater than 0');
+            if (interval <= 0)
+                throw new Error('--interval must be greater than 0');
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            const points = await (0, sampler_1.sampleFrame)(frame, expression, {
+                intervalMs: interval,
+                durationMs: duration,
+                ignoreErrors: !!args['ignore-errors'],
+            });
+            const summary = (0, sampler_1.summarizeSamples)(points, args.key, 5000, args['tail-from']);
+            return { text: JSON.stringify({ expression, intervalMs: interval, summary, series: points }, null, 2) };
+        }
+        case 'wait-stable': {
+            const expression = params[0];
+            if (!expression)
+                throw new Error('Expression is required for wait-stable command');
+            const frame = (0, frames_1.resolveFrame)(requirePage(launcher), args.frame);
+            const result = await (0, sampler_1.waitForStableValue)(frame, expression, {
+                tolerance: args.tolerance,
+                windowMs: args.window,
+                timeoutMs: args.timeout,
+                intervalMs: args.interval,
+            });
+            return { text: JSON.stringify({ ok: true, expression, ...result }, null, 2) };
+        }
+        case 'run': {
+            const absPath = params[0];
+            if (!absPath)
+                throw new Error('Flow script path is required');
+            return await (0, flowRunner_1.runFlow)(launcher, absPath, { timeout: args.timeout, json: !!args.json });
+        }
         case 'state-save': {
             const context = launcher.getContext();
             if (!context)
@@ -217,6 +347,20 @@ async function executeCommand(launcher, args) {
             throw new Error(`Unknown command: ${command}`);
     }
 }
+function requirePage(launcher) {
+    const page = launcher.getPage();
+    if (!page)
+        throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
+    return page;
+}
+function formatTargetAction(verb, selector, result) {
+    const descriptor = result.descriptor
+        ? ` → ${result.descriptor.tag}${result.descriptor.classes.map(c => `.${c}`).join('')}${result.descriptor.text ? ` "${result.descriptor.text}"` : ''}`
+        : '';
+    const matchNote = result.matches === 1 ? '1 match' : `${result.matches} matches`;
+    const nthNote = result.matches > 1 ? `, used #${result.nth}` : '';
+    return `${verb} ${selector}${descriptor} (${matchNote}${nthNote})`;
+}
 async function socketExists(socketPath) {
     try {
         const stat = await fs_1.default.promises.stat(socketPath);

package/dist/daemon/expect.d.ts

@@ -0,0 +1,8 @@
+export interface Matchers {
+    toBe(expected: unknown, label?: string): void;
+    toBeWithin(expected: number, tolerance: number, label?: string): void;
+    toMatch(pattern: RegExp | string, label?: string): void;
+    toHaveHash(hash: string, label?: string): void;
+    toBeSelected(index: number, label?: string): void;
+}
+export declare function expect(actual: unknown): Matchers;

package/dist/daemon/expect.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expect = expect;
+function labelSuffix(label) {
+    return label ? ` (${label})` : '';
+}
+function fail(label, message) {
+    throw new Error(`expect${labelSuffix(label)}: ${message}`);
+}
+function expect(actual) {
+    return {
+        toBe(expected, label) {
+            if (actual !== expected) {
+                fail(label, `expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}`);
+            }
+        },
+        toBeWithin(expected, tolerance, label) {
+            if (typeof actual !== 'number' || !Number.isFinite(actual)) {
+                fail(label, `expected a finite number near ${expected}, received ${JSON.stringify(actual)}`);
+            }
+            if (Math.abs(actual - expected) > tolerance) {
+                fail(label, `expected ${expected} ±${tolerance}, received ${actual}`);
+            }
+        },
+        toMatch(pattern, label) {
+            if (typeof actual !== 'string') {
+                fail(label, `expected a string, received ${JSON.stringify(actual)}`);
+            }
+            const regex = typeof pattern === 'string' ? new RegExp(pattern) : pattern;
+            if (!regex.test(actual)) {
+                fail(label, `expected ${JSON.stringify(actual)} to match ${regex}`);
+            }
+        },
+        toHaveHash(hash, label) {
+            const expected = hash.startsWith('#') ? hash : `#${hash}`;
+            if (actual !== expected) {
+                fail(label, `expected hash ${expected}, received ${JSON.stringify(actual)}`);
+            }
+        },
+        toBeSelected(index, label) {
+            if (actual !== index) {
+                fail(label, `expected selected index ${index}, received ${JSON.stringify(actual)}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=expect.js.map

package/dist/daemon/flowRunner.d.ts

@@ -0,0 +1,73 @@
+import type { BrowserContext, Page } from 'playwright-core';
+import type { BrowserLauncher } from '../browser/launcher';
+import { type TargetResult, type TypeOptions, type WaitState } from '../browser/interactions';
+import type { Finding, Snapshot } from '../engine/types';
+import { type FrameInfo } from '../browser/frames';
+import { type Matchers } from './expect';
+export interface FlowPageError {
+    message: string;
+    stack?: string;
+}
+export interface FlowEnvelope {
+    ok: boolean;
+    logs: string[];
+    result?: unknown;
+    error?: string;
+    elapsedMs: number;
+    pageErrors?: FlowPageError[];
+}
+export interface WaitForOptions {
+    state?: WaitState;
+    timeout?: number;
+}
+export interface WaitOutcome {
+    waitedFor: 'selector' | 'js' | 'networkidle';
+    state?: WaitState;
+    elapsedMs: number;
+}
+export interface FlowApi {
+    page: Page;
+    context: BrowserContext;
+    frames(): FrameInfo[];
+    newPage(): Promise<Page>;
+    expect(actual: unknown): Matchers;
+    click(selector: string, opts?: {
+        nth?: number;
+        force?: boolean;
+        timeout?: number;
+    }): Promise<TargetResult>;
+    hover(selector: string, opts?: {
+        nth?: number;
+        force?: boolean;
+        timeout?: number;
+    }): Promise<TargetResult>;
+    type(selector: string, text: string, opts?: TypeOptions): Promise<void>;
+    waitFor(target: string | {
+        js: string;
+        timeout?: number;
+    } | {
+        networkIdle: true;
+        timeout?: number;
+    }, opts?: WaitForOptions): Promise<WaitOutcome>;
+    inspect(selector: string, opts?: {
+        format?: 'json' | 'markdown';
+    }): Promise<{
+        snapshot: Snapshot;
+        findings: Finding[];
+    } | string>;
+    screenshot(opts?: {
+        path?: string;
+        fullPage?: boolean;
+    }): Promise<string>;
+    log(...args: unknown[]): void;
+}
+type FlowFn = (api: FlowApi) => Promise<unknown> | unknown;
+export declare function loadFlowScript(absPath: string): Promise<FlowFn>;
+export declare function runFlow(launcher: BrowserLauncher, absPath: string, opts?: {
+    timeout?: number;
+    json?: boolean;
+}): Promise<{
+    text: string;
+    exitCode: number;
+}>;
+export {};

package/dist/daemon/flowRunner.js

@@ -0,0 +1,177 @@
+"use strict";
+// Flow script runner: loads a user script in the daemon process, injects the
+// interaction API, captures console output and returns a result envelope.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadFlowScript = loadFlowScript;
+exports.runFlow = runFlow;
+const path_1 = __importDefault(require("path"));
+const util_1 = __importDefault(require("util"));
+const url_1 = require("url");
+const interactions_1 = require("../browser/interactions");
+const analyzer_1 = require("../engine/analyzer");
+const renderer_1 = require("../engine/renderer");
+const evalSerializer_1 = require("../engine/evalSerializer");
+const screenshot_1 = require("../utils/screenshot");
+const frames_1 = require("../browser/frames");
+const expect_1 = require("./expect");
+const FLOW_DEFAULT_TIMEOUT = 300_000;
+const CAPTURED_CONSOLE_METHODS = ['log', 'info', 'warn', 'error'];
+// tsc compiles `import()` to `require()` under module=commonjs, which cannot
+// load ESM scripts; a Function-constructed import keeps the native loader.
+const nativeImport = new Function('p', 'return import(p)');
+async function loadFlowScript(absPath) {
+    const mod = await nativeImport(`${(0, url_1.pathToFileURL)(absPath).href}?v=${Date.now()}`);
+    const fn = mod?.default;
+    if (typeof fn !== 'function')
+        throw new Error(`Flow script must default-export an async function: ${absPath}`);
+    return fn;
+}
+function captureConsole(logs) {
+    const originals = new Map();
+    for (const method of CAPTURED_CONSOLE_METHODS) {
+        originals.set(method, console[method]);
+        console[method] = (...args) => {
+            logs.push(`[${method}] ${util_1.default.format(...args)}`);
+        };
+    }
+    return () => {
+        for (const [method, original] of originals) {
+            console[method] = original;
+        }
+    };
+}
+async function withTimeout(promise, timeoutMs) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return promise;
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Flow timed out after ${timeoutMs}ms (best-effort abort)`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function requirePage(launcher) {
+    const page = launcher.getPage();
+    if (!page)
+        throw new Error('Browser is not open. Run: cssprobe-cli open <url>');
+    return page;
+}
+async function flowWaitFor(page, target, opts) {
+    if (typeof target === 'string') {
+        const state = opts?.state ?? 'visible';
+        const timeout = opts?.timeout ?? 30_000;
+        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'selector', selector: target, state }, timeout);
+        return { waitedFor: 'selector', state, elapsedMs };
+    }
+    if ('js' in target) {
+        const timeout = target.timeout ?? 30_000;
+        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'js', expression: target.js }, timeout);
+        return { waitedFor: 'js', elapsedMs };
+    }
+    if (target.networkIdle) {
+        const timeout = target.timeout ?? 30_000;
+        const elapsedMs = await (0, interactions_1.waitForCondition)(page, { kind: 'networkIdle' }, timeout);
+        return { waitedFor: 'networkidle', elapsedMs };
+    }
+    throw new Error('waitFor requires a selector string, { js }, or { networkIdle: true }');
+}
+function buildFlowApi(launcher, logs, baseDir) {
+    const page = requirePage(launcher);
+    return {
+        page,
+        click: (selector, opts) => (0, interactions_1.clickElement)(page, selector, opts),
+        hover: (selector, opts) => (0, interactions_1.hoverElement)(page, selector, opts),
+        type: (selector, text, opts) => (0, interactions_1.typeInto)(page, selector, text, opts),
+        waitFor: (target, opts) => flowWaitFor(page, target, opts),
+        inspect: async (selector, opts) => {
+            const snapshot = await launcher.collect({
+                rootSelector: selector,
+                downDepth: 6,
+                maxNodes: 60,
+                upTo: 'html',
+            });
+            const findings = (0, analyzer_1.analyze)(snapshot);
+            if (opts?.format === 'markdown')
+                return (0, renderer_1.renderMarkdown)(snapshot, findings);
+            return { snapshot, findings };
+        },
+        context: page.context(),
+        frames: () => (0, frames_1.describeFrames)(page),
+        newPage: () => page.context().newPage(),
+        expect: (actual) => (0, expect_1.expect)(actual),
+        screenshot: async (opts) => {
+            const buffer = await page.screenshot({ fullPage: opts?.fullPage });
+            const out = opts?.path ? path_1.default.resolve(baseDir, opts.path) : undefined;
+            return (0, screenshot_1.saveScreenshotFile)(`data:image/png;base64,${buffer.toString('base64')}`, out);
+        },
+        log: (...args) => {
+            logs.push(util_1.default.format(...args));
+        },
+    };
+}
+function renderEnvelope(env) {
+    const lines = [];
+    if (env.ok) {
+        lines.push(`Flow completed in ${env.elapsedMs}ms`);
+        if (env.result !== undefined)
+            lines.push(`Result: ${JSON.stringify(env.result, null, 2)}`);
+    }
+    else {
+        lines.push(`Flow failed in ${env.elapsedMs}ms: ${env.error}`);
+    }
+    if (env.pageErrors?.length) {
+        lines.push('', `Page errors (${env.pageErrors.length}):`);
+        lines.push(...env.pageErrors.map(error => `  - ${error.message}`));
+    }
+    if (env.logs.length) {
+        lines.push('', 'Logs:');
+        lines.push(...env.logs.map(line => `  ${line}`));
+    }
+    return lines.join('\n');
+}
+async function runFlow(launcher, absPath, opts = {}) {
+    const logs = [];
+    const started = Date.now();
+    const restore = captureConsole(logs);
+    const pageErrors = [];
+    const page = launcher.getPage();
+    const onPageError = (error) => {
+        pageErrors.push({
+            message: error.message,
+            stack: error.stack?.split('\n').slice(0, 6).join('\n'),
+        });
+    };
+    page?.on('pageerror', onPageError);
+    let env;
+    try {
+        const fn = await loadFlowScript(absPath);
+        const api = buildFlowApi(launcher, logs, path_1.default.dirname(absPath));
+        const result = await withTimeout(Promise.resolve(fn(api)), opts.timeout ?? FLOW_DEFAULT_TIMEOUT);
+        env = { ok: true, logs, elapsedMs: Date.now() - started };
+        if (result !== undefined)
+            env.result = (0, evalSerializer_1.serializeEvalResult)(result);
+    }
+    catch (e) {
+        env = { ok: false, logs, error: e.message, elapsedMs: Date.now() - started };
+    }
+    finally {
+        page?.off('pageerror', onPageError);
+        restore();
+    }
+    if (pageErrors.length)
+        env.pageErrors = pageErrors;
+    return {
+        text: opts.json ? JSON.stringify(env, null, 2) : renderEnvelope(env),
+        exitCode: env.ok ? 0 : 1,
+    };
+}
+//# sourceMappingURL=flowRunner.js.map

package/dist/engine/evalSerializer.d.ts

@@ -0,0 +1 @@
+export declare function serializeEvalResult(value: unknown): unknown;

package/dist/engine/evalSerializer.js

@@ -0,0 +1,43 @@
+"use strict";
+// Self-contained serializer for eval results.
+// Runs inside the page via JSHandle.evaluate (function source is transferred),
+// and is unit-testable in Node — keep it free of external references.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeEvalResult = serializeEvalResult;
+function serializeEvalResult(value) {
+    const seen = new WeakSet();
+    const walk = (v, depth) => {
+        if (v === null || typeof v !== 'object') {
+            if (typeof v === 'function')
+                return `[Function: ${v.name || 'anonymous'}]`;
+            if (typeof v === 'bigint')
+                return `${v}n`;
+            return v;
+        }
+        if (typeof Node !== 'undefined' && v instanceof Node) {
+            if (v.nodeType === 1) {
+                const el = v;
+                return {
+                    tag: el.tagName.toLowerCase(),
+                    id: el.id,
+                    classes: Array.from(el.classList),
+                    text: (el.textContent ?? '').trim().slice(0, 120),
+                };
+            }
+            return `[${v.nodeName}]`;
+        }
+        if (seen.has(v))
+            return '[Circular]';
+        if (depth >= 6)
+            return '[Depth limit]';
+        seen.add(v);
+        if (Array.isArray(v))
+            return Array.from(v, item => (item === undefined ? null : walk(item, depth + 1)));
+        const out = {};
+        for (const [key, val] of Object.entries(v))
+            out[key] = val === undefined ? null : walk(val, depth + 1);
+        return out;
+    };
+    return walk(value, 0);
+}
+//# sourceMappingURL=evalSerializer.js.map