cssprobe-cli 0.3.1 → 0.4.0

package/dist/browser/sampler.d.ts

@@ -0,0 +1,43 @@
+import type { Frame } from 'playwright-core';
+export interface SamplePoint {
+    t: number;
+    value: unknown;
+    visibility: string;
+    error?: string;
+}
+export interface SampleSummary {
+    samples: number;
+    durationMs: number;
+    first: SamplePoint | null;
+    last: SamplePoint | null;
+    min: number | null;
+    max: number | null;
+    numeric: Array<[number, number]>;
+    changes: number;
+    hiddenMs: number;
+    tail: {
+        fromT: number;
+        min: number | null;
+        max: number | null;
+        windowMs: number;
+    };
+}
+export declare function extractNumber(value: unknown, key?: string): number | null;
+export declare function summarizeSamples(points: SamplePoint[], key?: string, tailWindowMs?: number, tailFromMs?: number): SampleSummary;
+export declare function isWithinTolerance(previous: unknown, next: unknown, tolerance: number): boolean;
+export declare function sampleFrame(frame: Frame, expression: string, opts: {
+    intervalMs: number;
+    durationMs: number;
+    ignoreErrors?: boolean;
+}): Promise<SamplePoint[]>;
+export declare function waitForStableValue(frame: Frame, expression: string, opts: {
+    toleranceMs?: number;
+    windowMs?: number;
+    timeoutMs?: number;
+    intervalMs?: number;
+    tolerance?: number;
+}): Promise<{
+    elapsedMs: number;
+    value: unknown;
+    samples: number;
+}>;

package/dist/browser/sampler.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractNumber = extractNumber;
+exports.summarizeSamples = summarizeSamples;
+exports.isWithinTolerance = isWithinTolerance;
+exports.sampleFrame = sampleFrame;
+exports.waitForStableValue = waitForStableValue;
+function extractNumber(value, key) {
+    if (key) {
+        let current = value;
+        for (const part of key.split('.')) {
+            if (current === null || current === undefined)
+                return null;
+            current = current[part];
+        }
+        return typeof current === 'number' && Number.isFinite(current) ? current : null;
+    }
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function summarizeSamples(points, key, tailWindowMs = 5000, tailFromMs) {
+    const numeric = [];
+    for (const point of points) {
+        const n = extractNumber(point.value, key);
+        if (n !== null)
+            numeric.push([point.t, n]);
+    }
+    const tailFrom = Math.max(0, tailFromMs ?? (points.length ? points[points.length - 1].t - tailWindowMs : 0));
+    const tailNumeric = numeric.filter(([t]) => t >= tailFrom).map(([, value]) => value);
+    let changes = 0;
+    let hiddenMs = 0;
+    for (let i = 0; i < points.length; i++) {
+        if (i > 0 && JSON.stringify(points[i].value) !== JSON.stringify(points[i - 1].value))
+            changes++;
+        if (i < points.length - 1 && points[i].visibility !== 'visible') {
+            hiddenMs += points[i + 1].t - points[i].t;
+        }
+    }
+    return {
+        samples: points.length,
+        durationMs: points.length ? points[points.length - 1].t : 0,
+        first: points[0] ?? null,
+        last: points[points.length - 1] ?? null,
+        min: numeric.length ? Math.min(...numeric.map(item => item[1])) : null,
+        max: numeric.length ? Math.max(...numeric.map(item => item[1])) : null,
+        numeric,
+        changes,
+        hiddenMs,
+        tail: {
+            fromT: tailFrom,
+            min: tailNumeric.length ? Math.min(...tailNumeric) : null,
+            max: tailNumeric.length ? Math.max(...tailNumeric) : null,
+            windowMs: tailWindowMs,
+        },
+    };
+}
+function isWithinTolerance(previous, next, tolerance) {
+    if (typeof previous === 'number' && typeof next === 'number') {
+        if (Number.isNaN(previous) || Number.isNaN(next))
+            return false;
+        return Math.abs(next - previous) <= tolerance;
+    }
+    return JSON.stringify(previous) === JSON.stringify(next);
+}
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+async function readValue(frame, expression) {
+    return frame.evaluate(`(async () => ({ value: await (${expression}), visibility: document.visibilityState }))()`);
+}
+async function sampleFrame(frame, expression, opts) {
+    const intervalMs = Math.max(1, Math.floor(opts.intervalMs));
+    const started = Date.now();
+    const points = [];
+    while (Date.now() - started < opts.durationMs) {
+        const t = Date.now() - started;
+        try {
+            const { value, visibility } = await readValue(frame, expression);
+            points.push({ t, value, visibility });
+        }
+        catch (error) {
+            if (!opts.ignoreErrors)
+                throw error;
+            points.push({ t, value: null, visibility: 'unknown', error: error.message });
+        }
+        await sleep(intervalMs);
+    }
+    return points;
+}
+async function waitForStableValue(frame, expression, opts) {
+    const intervalMs = Math.max(1, opts.intervalMs ?? 200);
+    const windowMs = Math.max(1, opts.windowMs ?? 1500);
+    const timeoutMs = Math.max(1, opts.timeoutMs ?? 30000);
+    const tolerance = opts.tolerance ?? 0;
+    const started = Date.now();
+    let previous;
+    let stableSince = started;
+    let samples = 0;
+    while (Date.now() - started < timeoutMs) {
+        const { value } = await readValue(frame, expression);
+        samples++;
+        const now = Date.now();
+        if (samples === 1 || !isWithinTolerance(previous, value, tolerance)) {
+            previous = value;
+            stableSince = now;
+        }
+        else if (now - stableSince >= windowMs) {
+            return { elapsedMs: now - started, value, samples };
+        }
+        await sleep(intervalMs);
+    }
+    throw new Error(`wait-stable timed out after ${timeoutMs}ms; last value: ${JSON.stringify(previous)}`);
+}
+//# sourceMappingURL=sampler.js.map

package/dist/cli/commands.d.ts

@@ -14,14 +14,17 @@ export declare const inspectCommand: import("./command").CommandSchema<z.ZodObje
     brief: z.ZodOptional<z.ZodBoolean>;
     layout: z.ZodOptional<z.ZodBoolean>;
     depth: z.ZodOptional<z.ZodEffects<z.ZodNumber, number, unknown>>;
+    frame: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     json?: boolean | undefined;
     brief?: boolean | undefined;
     layout?: boolean | undefined;
     depth?: number | undefined;
+    frame?: string | undefined;
 }, {
     json?: boolean | undefined;
     brief?: boolean | undefined;
     layout?: boolean | undefined;
     depth?: unknown;
+    frame?: string | undefined;
 }>>;

package/dist/cli/commands.js

@@ -57,6 +57,8 @@ const open = (0, command_1.declareCommand)({
         headed: z.boolean().optional().describe('show the browser window'),
         viewport: z.string().optional().describe('viewport size as WxH (e.g. 1280x720)'),
         state: z.string().optional().describe('path to saved state file (cookies + localStorage)'),
+        'expect-url': z.string().optional().describe('regex the final page URL must match'),
+        'fail-on-login': z.boolean().optional().describe('fail when the page redirects to a login URL'),
     }),
 });
 const close = (0, command_1.declareCommand)({
@@ -72,6 +74,37 @@ const status = (0, command_1.declareCommand)({
     category: 'core',
     description: 'Show current session status',
 });
+const framesCmd = (0, command_1.declareCommand)({
+    name: 'frames',
+    category: 'core',
+    description: 'List frames in the current page',
+});
+const scenarioCmd = (0, command_1.declareCommand)({
+    name: 'scenario',
+    category: 'core',
+    description: 'Run a JSON scenario suite (regression cases, artifacts, JUnit)',
+    args: z.object({
+        action: z.literal('run').describe('only "run" is supported'),
+        file: z.string().describe('scenario suite JSON path'),
+    }),
+    options: z.object({
+        state: z.string().optional().describe('fallback state file when the suite/case does not set one'),
+        artifacts: z.string().optional().describe('artifact directory (default: ~/.cssprobe-cli/scenario-runs/<suite>-<timestamp>)'),
+        junit: z.string().optional().describe('write a JUnit XML report to this path'),
+        bail: z.boolean().optional().describe('stop after the first failing case'),
+        headed: z.boolean().optional().describe('show the browser window'),
+        browser: z.enum(['chromium', 'firefox', 'webkit']).optional().describe('browser engine (default chromium)'),
+        viewport: z.string().optional().describe('viewport size as WxH (default: suite defaults or 1280x720)'),
+    }),
+});
+const doctor = (0, command_1.declareCommand)({
+    name: 'doctor',
+    category: 'core',
+    description: 'Diagnose browser installation and Playwright revision mismatch',
+    options: z.object({
+        engine: z.string().optional().describe('browser engine: chromium, firefox, webkit (default: chromium)'),
+    }),
+});
 // ── cssprobe commands ──
 const inspect = (0, command_1.declareCommand)({
     name: 'inspect',
@@ -85,6 +118,7 @@ const inspect = (0, command_1.declareCommand)({
         brief: z.boolean().optional().describe('compact output: tree sketch + warnings/errors only'),
         layout: z.boolean().optional().describe('ASCII layout diagram showing element positions and sizes'),
         depth: numberArg.optional().describe('DOM tree depth (default: auto, max 20)'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
     }),
 });
 const tree = (0, command_1.declareCommand)({
@@ -96,6 +130,7 @@ const tree = (0, command_1.declareCommand)({
     }),
     options: z.object({
         depth: numberArg.optional().describe('tree depth (default: auto, max 20)'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
     }),
 });
 const layout = (0, command_1.declareCommand)({
@@ -105,6 +140,9 @@ const layout = (0, command_1.declareCommand)({
     args: z.object({
         selector: z.string().describe('CSS selector for the root element'),
     }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
 });
 const findings = (0, command_1.declareCommand)({
     name: 'findings',
@@ -113,6 +151,9 @@ const findings = (0, command_1.declareCommand)({
     args: z.object({
         selector: z.string().describe('CSS selector for the root element'),
     }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
 });
 const injectCss = (0, command_1.declareCommand)({
     name: 'inject-css',
@@ -121,6 +162,9 @@ const injectCss = (0, command_1.declareCommand)({
     args: z.object({
         css: z.string().describe('CSS code to inject'),
     }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
 });
 // ── browser commands ──
 const screenshot = (0, command_1.declareCommand)({
@@ -146,7 +190,10 @@ const evalCmd = (0, command_1.declareCommand)({
     category: 'core',
     description: 'Evaluate JavaScript expression on the page (browser context)',
     args: z.object({
-        expression: z.string().describe('JavaScript expression to evaluate'),
+        expression: z.string().describe('JavaScript expression, or @file / - (stdin) for long scripts'),
+    }),
+    options: z.object({
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
     }),
 });
 const playwrightCmd = (0, command_1.declareCommand)({
@@ -154,7 +201,7 @@ const playwrightCmd = (0, command_1.declareCommand)({
     category: 'core',
     description: 'Execute Playwright API call (Node.js context)',
     args: z.object({
-        call: z.string().describe('Playwright API call, e.g. "page.setViewportSize({width: 1280, height: 720})"'),
+        call: z.string().describe('Playwright API call, or @file / - (stdin); e.g. "page.setViewportSize({width: 1280, height: 720})"'),
     }),
 });
 // ── interaction ──
@@ -215,6 +262,37 @@ const waitForCmd = (0, command_1.declareCommand)({
         timeout: numberArg.optional().describe('timeout in ms (default 30000)'),
     }),
 });
+const sampleCmd = (0, command_1.declareCommand)({
+    name: 'sample',
+    category: 'core',
+    description: 'Sample a JS expression over time and return a timeline with summary stats',
+    args: z.object({
+        expression: z.string().describe('JS expression sampled on an interval'),
+    }),
+    options: z.object({
+        interval: numberArg.optional().describe('sampling interval in ms (default 250)'),
+        duration: numberArg.optional().describe('total sampling duration in ms (default 5000)'),
+        key: z.string().optional().describe('dot path for numeric extraction, e.g. "top" or "box.y"'),
+        'tail-from': numberArg.optional().describe('tail starts at this elapsed ms (default: last 5000ms)'),
+        'ignore-errors': z.boolean().optional().describe('record evaluation errors as sample points instead of aborting'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
+});
+const waitStableCmd = (0, command_1.declareCommand)({
+    name: 'wait-stable',
+    category: 'core',
+    description: 'Wait until a JS expression stops changing (tolerance + stable window)',
+    args: z.object({
+        expression: z.string().describe('JS expression polled until stable'),
+    }),
+    options: z.object({
+        tolerance: numberArg.optional().describe('absolute tolerance for numeric values (default 0)'),
+        window: numberArg.optional().describe('stable window in ms (default 1500)'),
+        timeout: numberArg.optional().describe('timeout in ms (default 30000)'),
+        interval: numberArg.optional().describe('polling interval in ms (default 200)'),
+        frame: z.string().optional().describe('target frame: index, name, or URL substring (default: main frame)'),
+    }),
+});
 const runCmd = (0, command_1.declareCommand)({
     name: 'run',
     category: 'core',
@@ -248,6 +326,15 @@ const stateSave = (0, command_1.declareCommand)({
         name: z.string().optional().describe('state file name (default: session)'),
     }),
 });
+const stateCheck = (0, command_1.declareCommand)({
+    name: 'state-check',
+    category: 'core',
+    description: 'Validate a saved state file: cookies, expiry, and target domain coverage',
+    options: z.object({
+        state: z.string().optional().describe('state file path (default: ~/.cssprobe-cli/states/session.json)'),
+        url: z.string().optional().describe('target URL whose hostname must be covered by the cookies'),
+    }),
+});
 // ── config ──
 const configShow = (0, command_1.declareCommand)({
     name: 'config-show',
@@ -343,15 +430,15 @@ const mcpUninstall = (0, command_1.declareCommand)({
 // ── export ──
 const commandsArray = [
     // session management
-    open, close, status,
+    open, close, status, framesCmd, doctor, scenarioCmd,
     // cssprobe
     inspect, tree, layout, findings, injectCss,
     // browser
     resize, evalCmd, playwrightCmd, screenshot,
     // interaction
-    click, hover, typeCmd, waitForCmd, runCmd,
+    click, hover, typeCmd, waitForCmd, sampleCmd, waitStableCmd, runCmd,
     // state
-    stateImport, stateSave,
+    stateImport, stateSave, stateCheck,
     // config
     configShow, configSet, configList, configUse, configNew, configPath,
     // skill

package/dist/cli/input.d.ts

@@ -0,0 +1,6 @@
+export interface InputSource {
+    readFile?: (file: string) => string;
+    readStdin?: () => string;
+    exists?: (file: string) => boolean;
+}
+export declare function resolveInputArg(value: string, source?: InputSource): string;

package/dist/cli/input.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInputArg = resolveInputArg;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function resolveInputArg(value, source = {}) {
+    const exists = source.exists ?? fs_1.default.existsSync;
+    const readFile = source.readFile ?? ((file) => fs_1.default.readFileSync(file, 'utf-8'));
+    if (value === '-') {
+        const readStdin = source.readStdin ?? (() => fs_1.default.readFileSync(0, 'utf-8'));
+        return readStdin();
+    }
+    if (value.startsWith('@')) {
+        const file = path_1.default.resolve(value.slice(1));
+        if (!exists(file))
+            throw new Error(`File not found: ${file}`);
+        return readFile(file);
+    }
+    return value;
+}
+//# sourceMappingURL=input.js.map

package/dist/cli/program.js

@@ -9,11 +9,17 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const minimist_1 = require("./minimist");
 const command_1 = require("./command");
+const input_1 = require("./input");
 const commands_1 = require("./commands");
 const output_1 = require("./output");
 const config_1 = require("../config/config");
 const session_1 = require("../daemon/session");
 const session_ops_1 = require("./session-ops");
+const state_check_1 = require("./state-check");
+const launcher_1 = require("../browser/launcher");
+const schema_1 = require("../scenario/schema");
+const runner_1 = require("../scenario/runner");
+const reporters_1 = require("../scenario/reporters");
 const mcp_1 = require("../mcp");
 const globalOptions = ['json', 'raw', 'help', 'h', 'version', 'v', 'p', 'profile'];
 const booleanGlobalOptions = ['help', 'json', 'raw', 'version', 'v', 'h'];
@@ -52,15 +58,25 @@ async function program() {
         case 'close':
             await handleClose(command, rawArgs, output);
             return;
+        case 'doctor':
+            handleDoctor(command, rawArgs, output);
+            return;
+        case 'scenario':
+            await handleScenario(command, rawArgs, output);
+            return;
         case 'status':
             await handleStatus(output);
             return;
         case 'state-import':
             await handleStateImport(command, rawArgs, output);
             return;
+        case 'state-check':
+            handleStateCheck(command, rawArgs, output);
+            return;
         case 'state-save':
             await handleStateSave(command, rawArgs, output);
             return;
+        case 'frames':
         case 'inspect':
         case 'tree':
         case 'layout':
@@ -74,6 +90,8 @@ async function program() {
         case 'hover':
         case 'type':
         case 'wait-for':
+        case 'sample':
+        case 'wait-stable':
             await handleSessionCommand(commandName, command, rawArgs, output);
             return;
         case 'run':
@@ -148,6 +166,8 @@ async function handleOpen(command, args, output) {
             headed: !!parsed.headed,
             viewport,
             state: parsed.state,
+            expectUrl: parsed['expect-url'],
+            failOnLogin: !!parsed['fail-on-login'],
         });
         if (output.json) {
             console.log(JSON.stringify(result, null, 2));
@@ -183,11 +203,100 @@ async function handleClose(command, args, output) {
         output.error(e instanceof Error ? e.message : String(e));
     }
 }
+async function handleScenario(command, args, output) {
+    try {
+        const cmdArgs = splitArgs(args);
+        const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+        const file = path_1.default.resolve(parsed.file);
+        if (!fs_1.default.existsSync(file))
+            output.error(`Scenario suite not found: ${file}`);
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+        const validation = schema_1.suiteSchema.safeParse(raw);
+        if (!validation.success) {
+            const issues = validation.error.issues
+                .map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+                .join('\n');
+            output.error(`Invalid scenario suite:\n${issues}`);
+        }
+        let viewport;
+        const viewportStr = parsed.viewport;
+        if (viewportStr) {
+            const parts = viewportStr.split('x');
+            const width = parseInt(parts[0], 10);
+            const height = parseInt(parts[1], 10);
+            if (parts.length !== 2 || isNaN(width) || isNaN(height)) {
+                output.error('Invalid viewport format. Use WxH (e.g. 1280x720)');
+            }
+            viewport = { width, height };
+        }
+        const result = await (0, runner_1.runScenario)(validation.data, file, {
+            artifactsDir: parsed.artifacts,
+            junitPath: parsed.junit,
+            bail: !!parsed.bail,
+            headed: !!parsed.headed,
+            browser: parsed.browser,
+            viewport,
+            state: parsed.state,
+        });
+        if (output.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log((0, reporters_1.formatConsole)(result.suite, result.results));
+            console.log(`Artifacts: ${result.artifactsDir}`);
+            if (parsed.junit)
+                console.log(`JUnit: ${path_1.default.resolve(parsed.junit)}`);
+        }
+        if (!result.ok)
+            process.exit(1);
+    }
+    catch (e) {
+        output.error(e instanceof Error ? e.message : String(e));
+    }
+}
+function handleDoctor(command, args, output) {
+    try {
+        const cmdArgs = splitArgs(args);
+        const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+        const diagnosis = (0, launcher_1.diagnoseBrowser)(parsed.engine);
+        if (output.json) {
+            console.log(JSON.stringify(diagnosis, null, 2));
+            return;
+        }
+        console.log(`Platform: ${diagnosis.platform}`);
+        console.log(`Cache roots: ${diagnosis.cacheRoots.join(', ')}`);
+        console.log(`Expected: chromium ${diagnosis.expected.chromium ?? 'unknown'}, headless-shell ${diagnosis.expected.headlessShell ?? 'unknown'} (playwright-core ${diagnosis.expected.playwrightVersion ?? 'unknown'})`);
+        if (diagnosis.installs.length) {
+            console.log('Installed:');
+            for (const install of diagnosis.installs) {
+                console.log(`  ${install.kind}-${install.revision}${install.executable ? '' : ' (no executable)'} ${install.dir}`);
+            }
+        }
+        else {
+            console.log('Installed: none');
+        }
+        console.log(`Status: ${diagnosis.status}`);
+        if (diagnosis.hint)
+            console.log(`Hint: ${diagnosis.hint}`);
+    }
+    catch (e) {
+        output.error(e instanceof Error ? e.message : String(e));
+    }
+}
 async function handleStatus(output) {
     try {
         const result = await (0, session_ops_1.getSessionStatus)();
+        let page = null;
+        if (result.alive) {
+            try {
+                page = await (0, session_ops_1.getPageInfo)();
+            }
+            catch {
+                page = null;
+            }
+        }
         if (output.json) {
-            console.log(JSON.stringify(result, null, 2));
+            console.log(JSON.stringify({ ...result, page }, null, 2));
             return;
         }
         if (!result.config) {
@@ -198,7 +307,42 @@ async function handleStatus(output) {
         console.log(`Status: ${result.alive ? 'alive' : 'dead'}`);
         if (result.alive) {
             console.log(`Browser: ${result.config.browser.browserName}`);
+            if (page) {
+                console.log(`URL: ${page.url}`);
+                console.log(`Title: ${page.title}`);
+                console.log(`Frames: ${page.frames}`);
+            }
+        }
+    }
+    catch (e) {
+        output.error(e instanceof Error ? e.message : String(e));
+    }
+}
+function handleStateCheck(command, args, output) {
+    try {
+        const cmdArgs = splitArgs(args);
+        const parsed = (0, command_1.parseCommand)(command, cmdArgs);
+        const file = path_1.default.resolve(parsed.state ??
+            path_1.default.join(os_1.default.homedir(), '.cssprobe-cli', 'states', 'session.json'));
+        if (!fs_1.default.existsSync(file))
+            output.error(`State file not found: ${file}`);
+        const raw = JSON.parse(fs_1.default.readFileSync(file, 'utf-8'));
+        if (!raw || !Array.isArray(raw.cookies))
+            throw new Error(`Invalid state file (missing cookies): ${file}`);
+        const report = (0, state_check_1.analyzeState)(raw, parsed.url);
+        if (output.json) {
+            console.log(JSON.stringify({ file, ...report }, null, 2));
+            return;
+        }
+        console.log(`State: ${file}`);
+        console.log(`Cookies: ${report.cookies} (${report.sessionCookies} session)`);
+        console.log(`Domains: ${report.domains.join(', ') || '(none)'}`);
+        if (report.targetMatches !== null) {
+            console.log(`Target match: ${report.targetMatches ? 'yes' : 'no'}`);
         }
+        console.log(`Status: ${report.ok ? 'ok' : 'attention'}`);
+        for (const warning of report.warnings)
+            console.log(`Warning: ${warning}`);
     }
     catch (e) {
         output.error(e instanceof Error ? e.message : String(e));
@@ -217,6 +361,13 @@ async function handleRun(command, args, output) {
 async function handleSessionCommand(commandName, command, args, output) {
     try {
         const cmdArgs = splitArgs(args);
+        if (commandName === 'eval' || commandName === 'playwright') {
+            const input = cmdArgs._[1];
+            if (typeof input === 'string') {
+                cmdArgs._ = cmdArgs._.slice();
+                cmdArgs._[1] = (0, input_1.resolveInputArg)(input);
+            }
+        }
         const parsed = (0, command_1.parseCommand)(command, cmdArgs);
         const result = await (0, session_ops_1.runSessionCommand)(commandName, command, parsed, !!args.json);
         // Screenshot: save the base64 data URL to a file and report the path

package/dist/cli/session-ops.d.ts

@@ -11,6 +11,8 @@ export interface OpenOptions {
         height: number;
     };
     state?: string;
+    expectUrl?: string;
+    failOnLogin?: boolean;
 }
 export interface OpenResult {
     sessionId: string;
@@ -21,6 +23,12 @@ export interface OpenResult {
         height: number;
     };
 }
+export interface PageInfo {
+    url: string;
+    title: string;
+    frames: number;
+}
+export declare function getPageInfo(): Promise<PageInfo>;
 export declare function openSession(opts: OpenOptions): Promise<OpenResult>;
 export declare function waitForSession(timeoutMs: number): Promise<Session | undefined>;
 export interface CloseResult {

package/dist/cli/session-ops.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.saveScreenshotFile = void 0;
+exports.getPageInfo = getPageInfo;
 exports.openSession = openSession;
 exports.waitForSession = waitForSession;
 exports.closeSession = closeSession;
@@ -8,8 +9,16 @@ exports.getSessionStatus = getSessionStatus;
 exports.buildDaemonArgs = buildDaemonArgs;
 exports.runSessionCommand = runSessionCommand;
 const session_1 = require("../daemon/session");
+const url_guard_1 = require("./url-guard");
 var screenshot_1 = require("../utils/screenshot");
 Object.defineProperty(exports, "saveScreenshotFile", { enumerable: true, get: function () { return screenshot_1.saveScreenshotFile; } });
+async function getPageInfo() {
+    const session = await (0, session_1.loadSession)();
+    if (!session)
+        throw new Error('No active session. Run: cssprobe-cli open <url>');
+    const result = await session.run({ _: ['page-info'] });
+    return JSON.parse(result.text);
+}
 async function openSession(opts) {
     const url = opts.url || 'about:blank';
     const browser = opts.browser || 'chromium';
@@ -24,10 +33,24 @@ async function openSession(opts) {
     if (!session)
         throw new Error('Daemon failed to become ready within 5s. Check the daemon log for errors.');
     await session.run({ _: ['goto', url] });
+    const info = await getPageInfo();
+    const guardError = (() => {
+        if (opts.failOnLogin && (0, url_guard_1.looksLikeLoginUrl)(info.url)) {
+            return `Login required: page redirected to ${info.url}. Refresh the state file or log in manually.`;
+        }
+        if (opts.expectUrl && !(0, url_guard_1.matchesUrlPattern)(opts.expectUrl, info.url)) {
+            return `Expected URL to match ${opts.expectUrl}, got ${info.url}`;
+        }
+        return null;
+    })();
+    if (guardError) {
+        await closeSession();
+        throw new Error(guardError);
+    }
     return {
         sessionId: 'default',
         pid,
-        url,
+        url: info.url,
         viewport: opts.viewport || { width: 1280, height: 720 },
     };
 }