cssprobe-cli 0.2.26 → 0.3.1

package/dist/installer/skill-template.js

@@ -127,6 +127,49 @@ function buildSkillMd() {
         'cssprobe-cli close                         # stop browser + daemon',
         BT3,
         '',
+        '## Multi-step UI Flows',
+        '',
+        'Beyond inspection, cssprobe-cli drives the page: click, hover, type, wait, and',
+        'run scripted flows -- all in the same session.',
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli click ".layout-switch"            # real mouse click (auto-scroll + actionability wait)',
+        'cssprobe-cli click ".item" --nth 2             # 1-based match index; multi-match without --nth fails (strict)',
+        'cssprobe-cli hover ".menu-item"',
+        'cssprobe-cli type ".block-title input" "Hi" --press Enter    # fill by default',
+        'cssprobe-cli type ".editor" "text" --sequential --clear      # real key events for custom editors',
+        'cssprobe-cli wait-for ".modal" --state visible --timeout 5000',
+        'cssprobe-cli wait-for --js "() => ready === true"',
+        'cssprobe-cli wait-for --network-idle',
+        BT3,
+        '',
+        '### Scripted flows: ' + BT + 'run <file>' + BT,
+        '',
+        'A flow script default-exports an async function receiving the API object and',
+        'runs inside the daemon session:',
+        '',
+        BT3 + 'js',
+        'export default async ({ page, click, hover, type, waitFor, inspect, screenshot, log }) => {',
+        '  await waitFor(".editor-canvas");',
+        '  await click(".layout-switch", { nth: 1 });',
+        '  await type(".block-title input", "Hello", { press: "Enter", sequential: true, clear: true });',
+        '  await waitFor({ networkIdle: true });',
+        '  const { findings } = await inspect(".block-grid", { format: "json" });',
+        '  await screenshot({ path: "./after.png" });',
+        '  return { findings: findings.length };',
+        '};',
+        BT3,
+        '',
+        BT3 + 'bash',
+        'cssprobe-cli run ./flow.js        # --timeout ms (default 300000, 0 = unlimited)',
+        BT3,
+        '',
+        'Notes:',
+        '',
+        '- Scripts run on your machine with full Node privileges -- only run trusted scripts.',
+        '- ' + BT + 'screenshot' + BT + ' relative paths resolve against the script directory.',
+        '- On failure the command exits 1, prints collected logs, and keeps the session alive.',
+        '',
         '## Output Modes',
         '',
         'Pass ' + BT + '--json' + BT + ' when consuming output programmatically:',

package/dist/installer/toml.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tiny TOML helpers — just enough to inject / replace / remove a single
+ * dotted-key table block (`[mcp_servers.cssprobe-cli]`) inside an existing
+ * `~/.codex/config.toml`. We deliberately do NOT try to be a general TOML
+ * parser/serializer.
+ *
+ * Strategy: treat the file as text. Find the header line, splice it (and the
+ * lines that follow it until the next `[...]` header or EOF) in or out.
+ * Everything outside that block is preserved verbatim.
+ */
+export declare function serializeTomlTableBody(values: Record<string, string | string[]>): string;
+export declare function buildTomlTable(header: string, values: Record<string, string | string[]>): string;
+export declare function upsertTomlTable(fileContent: string, header: string, block: string): {
+    content: string;
+    action: 'inserted' | 'replaced' | 'unchanged';
+};
+export declare function removeTomlTable(fileContent: string, header: string): {
+    content: string;
+    action: 'removed' | 'not-found';
+};

package/dist/installer/toml.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Tiny TOML helpers — just enough to inject / replace / remove a single
+ * dotted-key table block (`[mcp_servers.cssprobe-cli]`) inside an existing
+ * `~/.codex/config.toml`. We deliberately do NOT try to be a general TOML
+ * parser/serializer.
+ *
+ * Strategy: treat the file as text. Find the header line, splice it (and the
+ * lines that follow it until the next `[...]` header or EOF) in or out.
+ * Everything outside that block is preserved verbatim.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeTomlTableBody = serializeTomlTableBody;
+exports.buildTomlTable = buildTomlTable;
+exports.upsertTomlTable = upsertTomlTable;
+exports.removeTomlTable = removeTomlTable;
+function serializeTomlTableBody(values) {
+    const lines = [];
+    for (const [key, value] of Object.entries(values)) {
+        if (typeof value === 'string') {
+            lines.push(`${key} = ${quoteString(value)}`);
+        }
+        else if (Array.isArray(value) && value.every((v) => typeof v === 'string')) {
+            const parts = value.map(quoteString).join(', ');
+            lines.push(`${key} = [${parts}]`);
+        }
+        else {
+            throw new Error(`Unsupported TOML value type for key "${key}"`);
+        }
+    }
+    return lines.join('\n');
+}
+function quoteString(s) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+function buildTomlTable(header, values) {
+    return `[${header}]\n${serializeTomlTableBody(values)}`;
+}
+function upsertTomlTable(fileContent, header, block) {
+    const headerLine = `[${header}]`;
+    const headerIdx = findHeaderIndex(fileContent, headerLine);
+    if (headerIdx === -1) {
+        const trimmed = fileContent.trimEnd();
+        const sep = trimmed.length > 0 ? '\n\n' : '';
+        return {
+            content: trimmed + sep + block + '\n',
+            action: 'inserted',
+        };
+    }
+    const blockEnd = findNextTableHeader(fileContent, headerIdx + headerLine.length);
+    const existingBlock = fileContent.substring(headerIdx, blockEnd).replace(/\n+$/, '');
+    if (existingBlock === block) {
+        return { content: fileContent, action: 'unchanged' };
+    }
+    const before = fileContent.substring(0, headerIdx);
+    const after = fileContent.substring(blockEnd);
+    const beforeClean = before.replace(/\n+$/, '');
+    const afterClean = after.replace(/^\n+/, '');
+    const sepBefore = beforeClean.length > 0 ? '\n\n' : '';
+    const sepAfter = afterClean.length > 0 ? '\n\n' : '\n';
+    return {
+        content: beforeClean + sepBefore + block + sepAfter + afterClean,
+        action: 'replaced',
+    };
+}
+function removeTomlTable(fileContent, header) {
+    const headerLine = `[${header}]`;
+    const headerIdx = findHeaderIndex(fileContent, headerLine);
+    if (headerIdx === -1)
+        return { content: fileContent, action: 'not-found' };
+    const blockEnd = findNextTableHeader(fileContent, headerIdx + headerLine.length);
+    const before = fileContent.substring(0, headerIdx).replace(/\n+$/, '');
+    const after = fileContent.substring(blockEnd).replace(/^\n+/, '');
+    const joined = before + (before && after ? '\n\n' : '') + after;
+    return { content: joined, action: 'removed' };
+}
+function findHeaderIndex(content, headerLine) {
+    if (content.startsWith(headerLine))
+        return 0;
+    const needle = '\n' + headerLine;
+    const idx = content.indexOf(needle);
+    return idx === -1 ? -1 : idx + 1;
+}
+function findNextTableHeader(content, from) {
+    let i = from;
+    while (i < content.length) {
+        const nlIdx = content.indexOf('\n[', i);
+        if (nlIdx === -1)
+            return content.length;
+        if (content[nlIdx + 2] === '[') {
+            i = nlIdx + 2;
+            continue;
+        }
+        return nlIdx + 1;
+    }
+    return content.length;
+}
+//# sourceMappingURL=toml.js.map

package/dist/mcp/index.d.ts

@@ -0,0 +1,15 @@
+export declare class MCPServer {
+    private rl;
+    private handler;
+    private version;
+    private pending;
+    private closing;
+    private queue;
+    constructor();
+    run(): Promise<void>;
+    handleMessage(message: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+    private handleToolCall;
+    private executeTool;
+    private send;
+}
+export declare function runMcpServer(): Promise<void>;

package/dist/mcp/index.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPServer = void 0;
+exports.runMcpServer = runMcpServer;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const readline = __importStar(require("readline"));
+const server_instructions_1 = require("./server-instructions");
+const tools_1 = require("./tools");
+const PROTOCOL_VERSION = '2024-11-05';
+class MCPServer {
+    rl = null;
+    handler = new tools_1.MCPToolHandler();
+    version;
+    pending = 0;
+    closing = false;
+    queue = Promise.resolve();
+    constructor() {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', '..', 'package.json'), 'utf-8'));
+            this.version = pkg.version || '0.0.0';
+        }
+        catch {
+            this.version = '0.0.0';
+        }
+    }
+    async run() {
+        this.rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false,
+        });
+        process.stderr.write('cssprobe-cli MCP server started\n');
+        // Requests are serialized: tool calls share one browser session, so an
+        // inspect racing an in-flight open must be queued, not run concurrently.
+        this.rl.on('line', (line) => {
+            this.pending++;
+            this.queue = this.queue.then(async () => {
+                try {
+                    const message = JSON.parse(line);
+                    const response = await this.handleMessage(message);
+                    if (response)
+                        this.send(response);
+                }
+                catch {
+                    // ignore malformed lines
+                }
+                finally {
+                    this.pending--;
+                    if (this.closing && this.pending === 0)
+                        process.exit(0);
+                }
+            });
+        });
+        // Exit only after in-flight requests drain, so a client that closes
+        // stdin immediately after sending still receives its responses.
+        this.rl.on('close', () => {
+            this.closing = true;
+            if (this.pending === 0)
+                process.exit(0);
+        });
+        process.on('SIGTERM', () => process.exit(0));
+        process.on('SIGINT', () => process.exit(0));
+    }
+    async handleMessage(message) {
+        const method = message['method'];
+        const id = message['id'];
+        if (!method)
+            return undefined;
+        // Notifications (no id) never receive a response.
+        if (id === undefined)
+            return undefined;
+        switch (method) {
+            case 'initialize':
+                return {
+                    jsonrpc: '2.0',
+                    id,
+                    result: {
+                        protocolVersion: PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: 'cssprobe-cli', version: this.version },
+                        instructions: server_instructions_1.SERVER_INSTRUCTIONS,
+                    },
+                };
+            case 'ping':
+                return { jsonrpc: '2.0', id, result: {} };
+            case 'tools/list':
+                return { jsonrpc: '2.0', id, result: { tools: (0, tools_1.getToolDefinitions)() } };
+            case 'tools/call':
+                return this.handleToolCall(message, id);
+            default:
+                return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
+        }
+    }
+    async handleToolCall(message, id) {
+        const params = message['params'];
+        const toolName = params?.['name'];
+        const args = params?.['arguments'] ?? {};
+        if (!toolName) {
+            return { jsonrpc: '2.0', id, error: { code: -32602, message: 'Missing tool name' } };
+        }
+        try {
+            const text = await this.executeTool(toolName, args);
+            return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }] } };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                jsonrpc: '2.0',
+                id,
+                result: {
+                    content: [{ type: 'text', text: `cssprobe-cli internal error: ${msg}\n\nThis is an unexpected error — please report it.` }],
+                    isError: true,
+                },
+            };
+        }
+    }
+    executeTool(name, args) {
+        switch (name) {
+            case 'cssprobe_open': return this.handler.open(args);
+            case 'cssprobe_inspect': return this.handler.inspect(args);
+            case 'cssprobe_tree': return this.handler.tree(args);
+            case 'cssprobe_layout': return this.handler.layout(args);
+            case 'cssprobe_findings': return this.handler.findings(args);
+            case 'cssprobe_eval': return this.handler.evalExpression(args);
+            case 'cssprobe_screenshot': return this.handler.screenshot(args);
+            case 'cssprobe_inject_css': return this.handler.injectCss(args);
+            case 'cssprobe_close': return this.handler.close(args);
+            case 'cssprobe_status': return this.handler.status();
+            default: return Promise.resolve(`Unknown tool: ${name}`);
+        }
+    }
+    send(message) {
+        process.stdout.write(JSON.stringify(message) + '\n');
+    }
+}
+exports.MCPServer = MCPServer;
+async function runMcpServer() {
+    await new MCPServer().run();
+}
+//# sourceMappingURL=index.js.map

package/dist/mcp/server-instructions.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_INSTRUCTIONS = "cssprobe-cli \u2014 runtime CSS probe for AI agents.\n\nIt opens a real browser session and answers questions that static code cannot:\nwhy an element overflows, where its scroll chain goes, what it actually renders\nas. Findings carry a confidence level (DEFINITE / INDEFINITE / UNVERIFIABLE) \u2014\nreport UNVERIFIABLE items as \"needs verification\", never as conclusions.\n\nTypical workflow:\n1. cssprobe_open \u2014 start a session (optionally with a URL; headed: true when a\n   login is needed, then ask the user to sign in manually).\n2. cssprobe_inspect / cssprobe_layout / cssprobe_findings \u2014 query a selector.\n   inspect returns DOM tree + layout + findings; layout is the ASCII diagram;\n   findings lists only issues/warnings/errors.\n3. cssprobe_eval / cssprobe_inject_css \u2014 probe or patch the live page.\n4. cssprobe_screenshot \u2014 capture the current page to a PNG file.\n5. cssprobe_close \u2014 stop the session when done.\n\nNotes:\n- One shared \"default\" session: open once, run many queries, close at the end.\n- Any command without an open session returns guidance instead of failing.\n- Pair with cssgraph (static CSS knowledge graph MCP) for the full picture:\n  cssgraph finds where styles come from, cssprobe shows what they render as.\n- Prefer narrow selectors (\".card > .title\") to keep output small.";

package/dist/mcp/server-instructions.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS = void 0;
+exports.SERVER_INSTRUCTIONS = `cssprobe-cli — runtime CSS probe for AI agents.
+
+It opens a real browser session and answers questions that static code cannot:
+why an element overflows, where its scroll chain goes, what it actually renders
+as. Findings carry a confidence level (DEFINITE / INDEFINITE / UNVERIFIABLE) —
+report UNVERIFIABLE items as "needs verification", never as conclusions.
+
+Typical workflow:
+1. cssprobe_open — start a session (optionally with a URL; headed: true when a
+   login is needed, then ask the user to sign in manually).
+2. cssprobe_inspect / cssprobe_layout / cssprobe_findings — query a selector.
+   inspect returns DOM tree + layout + findings; layout is the ASCII diagram;
+   findings lists only issues/warnings/errors.
+3. cssprobe_eval / cssprobe_inject_css — probe or patch the live page.
+4. cssprobe_screenshot — capture the current page to a PNG file.
+5. cssprobe_close — stop the session when done.
+
+Notes:
+- One shared "default" session: open once, run many queries, close at the end.
+- Any command without an open session returns guidance instead of failing.
+- Pair with cssgraph (static CSS knowledge graph MCP) for the full picture:
+  cssgraph finds where styles come from, cssprobe shows what they render as.
+- Prefer narrow selectors (".card > .title") to keep output small.`;
+//# sourceMappingURL=server-instructions.js.map

package/dist/mcp/tools.d.ts

@@ -0,0 +1,261 @@
+export declare function getToolDefinitions(): ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            url: {
+                type: "string";
+                description: string;
+            };
+            headed: {
+                type: "boolean";
+                description: string;
+            };
+            viewport: {
+                type: "string";
+                description: string;
+            };
+            browser: {
+                type: "string";
+                enum: string[];
+                description: string;
+            };
+            state: {
+                type: "string";
+                description: string;
+            };
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            selector: {
+                type: "string";
+                description: string;
+            };
+            depth: {
+                type: "number";
+                description: string;
+            };
+            brief: {
+                type: "boolean";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            selector: {
+                type: "string";
+                description: string;
+            };
+            depth: {
+                type: "number";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            selector: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            expression: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            full_page: {
+                type: "boolean";
+                description: string;
+            };
+            out: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            css: {
+                type: "string";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            all?: undefined;
+        };
+        required: string[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            all: {
+                type: "boolean";
+                description: string;
+            };
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+        };
+        required: never[];
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            url?: undefined;
+            headed?: undefined;
+            viewport?: undefined;
+            browser?: undefined;
+            state?: undefined;
+            selector?: undefined;
+            depth?: undefined;
+            brief?: undefined;
+            expression?: undefined;
+            full_page?: undefined;
+            out?: undefined;
+            css?: undefined;
+            all?: undefined;
+        };
+        required: never[];
+    };
+})[];
+export declare class MCPToolHandler {
+    private runSession;
+    open(args: Record<string, unknown>): Promise<string>;
+    inspect(args: Record<string, unknown>): Promise<string>;
+    tree(args: Record<string, unknown>): Promise<string>;
+    layout(args: Record<string, unknown>): Promise<string>;
+    findings(args: Record<string, unknown>): Promise<string>;
+    evalExpression(args: Record<string, unknown>): Promise<string>;
+    screenshot(args: Record<string, unknown>): Promise<string>;
+    injectCss(args: Record<string, unknown>): Promise<string>;
+    close(args: Record<string, unknown>): Promise<string>;
+    status(): Promise<string>;
+}