@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/browser/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for browser operations
+ */
+type EvaluateFunction = (...args: never[]) => unknown;
+/**
+ * Serialize a function-form page.evaluate call for CDP Runtime.evaluate.
+ *
+ * Functions execute in the browser page context, so they cannot close over
+ * Node-side variables. Pass external values as JSON-serializable args instead.
+ */
+export declare function serializeFunctionForEval(fn: EvaluateFunction, args?: readonly unknown[]): string;
+/**
+ * Wrap JS code for CDP Runtime.evaluate:
+ * - Already an IIFE `(...)()` → send as-is
+ * - Arrow/function literal → wrap as IIFE `(code)()`
+ * - `new Promise(...)` or raw expression → send as-is (expression)
+ */
+export declare function wrapForEval(js: string): string;
+export declare function buildEvaluateExpression(input: string | EvaluateFunction, args?: readonly unknown[]): string;
+export {};

package/dist/src/browser/utils.js

@@ -0,0 +1,64 @@
+/**
+ * Utility functions for browser operations
+ */
+function describeJsonError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Serialize a function-form page.evaluate call for CDP Runtime.evaluate.
+ *
+ * Functions execute in the browser page context, so they cannot close over
+ * Node-side variables. Pass external values as JSON-serializable args instead.
+ */
+export function serializeFunctionForEval(fn, args = []) {
+    const source = fn.toString().trim();
+    const isFunctionSource = /^(async\s+)?function[\s(]/.test(source)
+        || /^(async\s*)?(\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>/.test(source);
+    if (!isFunctionSource || source.includes('[native code]')) {
+        throw new Error('page.evaluate(fn) requires a serializable arrow/function expression');
+    }
+    let serializedArgs;
+    try {
+        serializedArgs = JSON.stringify(args);
+    }
+    catch (err) {
+        throw new Error(`page.evaluate arguments must be JSON-serializable: ${describeJsonError(err)}`);
+    }
+    if (serializedArgs === undefined) {
+        throw new Error('page.evaluate arguments must be JSON-serializable');
+    }
+    return `(${source})(...${serializedArgs})`;
+}
+/**
+ * Wrap JS code for CDP Runtime.evaluate:
+ * - Already an IIFE `(...)()` → send as-is
+ * - Arrow/function literal → wrap as IIFE `(code)()`
+ * - `new Promise(...)` or raw expression → send as-is (expression)
+ */
+export function wrapForEval(js) {
+    if (typeof js !== 'string')
+        return 'undefined';
+    const code = js.trim();
+    if (!code)
+        return 'undefined';
+    // Already an IIFE: `(async () => { ... })()` or `(function() {...})()`
+    if (/^\([\s\S]*\)\s*\(.*\)\s*$/.test(code))
+        return code;
+    // Arrow function: `() => ...` or `async () => ...`
+    if (/^(async\s+)?(\([^)]*\)|[A-Za-z_]\w*)\s*=>/.test(code))
+        return `(${code})()`;
+    // Function declaration: `function ...` or `async function ...`
+    if (/^(async\s+)?function[\s(]/.test(code))
+        return `(${code})()`;
+    // Everything else: bare expression, `new Promise(...)`, etc. → evaluate directly
+    return code;
+}
+export function buildEvaluateExpression(input, args = []) {
+    if (typeof input === 'function') {
+        return serializeFunctionForEval(input, args);
+    }
+    if (args.length > 0) {
+        throw new Error('page.evaluate string input does not accept args; use page.evaluate(fn, ...args) instead');
+    }
+    return wrapForEval(input);
+}

package/dist/src/browser/utils.test.d.ts

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

package/dist/src/browser/utils.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { buildEvaluateExpression, wrapForEval } from './utils.js';
+describe('browser eval utils', () => {
+    it('keeps existing string eval wrapping behavior', () => {
+        expect(wrapForEval('21 + 21')).toBe('21 + 21');
+        expect(wrapForEval('() => 42')).toBe('(() => 42)()');
+    });
+    it('serializes function eval arguments as JSON', () => {
+        const code = buildEvaluateExpression((selector) => {
+            return document.querySelector(selector)?.textContent ?? null;
+        }, ['.title']);
+        expect(code).toContain('document.querySelector(selector)');
+        expect(code).toContain('(...[".title"])');
+    });
+    it('accepts compact async arrow functions', () => {
+        const fn = new Function('return async()=>42')();
+        expect(buildEvaluateExpression(fn)).toBe('(async()=>42)(...[])');
+    });
+    it('rejects string eval with stray args', () => {
+        expect(() => buildEvaluateExpression('document.title', ['ignored']))
+            .toThrow('use page.evaluate(fn, ...args)');
+    });
+    it('rejects non-JSON-serializable function args', () => {
+        const circular = {};
+        circular.self = circular;
+        expect(() => buildEvaluateExpression((value) => value, [circular]))
+            .toThrow('JSON-serializable');
+    });
+});

package/dist/src/browser/verify-fixture.d.ts

@@ -0,0 +1,65 @@
+export type FixtureExpect = {
+    rowCount?: {
+        min?: number;
+        max?: number;
+    };
+    columns?: string[];
+    types?: Record<string, string>;
+    patterns?: Record<string, string>;
+    notEmpty?: string[];
+    /**
+     * Substrings/regex fragments that MUST NOT appear in the column value.
+     *
+     * Catches silent content contamination that `notEmpty` alone misses —
+     * e.g. a `description` field that accidentally carries "address: ..." /
+     * "category: ..." fragments from sibling DOM nodes, or a `title` that
+     * bled in a navigation-breadcrumb prefix. Each entry is matched as a
+     * plain substring against the stringified column value.
+     */
+    mustNotContain?: Record<string, string[]>;
+    /**
+     * Columns whose values must be truthy. Complements `notEmpty` (which
+     * only rejects empty-string/null/undefined) by also catching silent
+     * `|| 0` / `|| false` fallbacks in numeric/boolean fields. Fires when
+     * the value coerces to `false` in JS.
+     */
+    mustBeTruthy?: string[];
+};
+export type FixtureArgs = Record<string, unknown> | unknown[];
+export type Fixture = {
+    args?: FixtureArgs;
+    expect?: FixtureExpect;
+};
+export type ValidationFailure = {
+    rule: 'rowCount' | 'column' | 'type' | 'pattern' | 'notEmpty' | 'mustNotContain' | 'mustBeTruthy' | 'shapeKeyCount' | 'shapeDepth' | 'shapeNestedId';
+    detail: string;
+    rowIndex?: number;
+};
+export type Row = Record<string, unknown>;
+export type RowShapeOptions = {
+    maxTopLevelKeys?: number;
+    maxNestedDepth?: number;
+};
+export declare function fixturePath(site: string, command: string): string;
+export declare function loadFixture(site: string, command: string): Fixture | null;
+export declare function writeFixture(site: string, command: string, fixture: Fixture): string;
+/**
+ * Derive a reasonable fixture from sample output. Used by `--write-fixture`
+ * to seed a first draft the author can hand-tune.
+ *
+ * Heuristics:
+ * - rowCount.min = 1 if rows non-empty, else 0
+ * - columns = keys from the first row
+ * - types = typeof of the first row's values, with "number|string" for mixed
+ * - no auto patterns / notEmpty — author should add those deliberately
+ */
+export declare function deriveFixture(rows: Row[], args?: FixtureArgs): Fixture;
+export declare function validateRows(rows: Row[], fixture: Fixture): ValidationFailure[];
+export declare function validateRowShape(rows: Row[], opts?: RowShapeOptions): ValidationFailure[];
+/**
+ * Convert fixture args into argv tokens appended after the command name.
+ * - Array form is passed through verbatim (stringified), supporting positional subjects.
+ * - Object form is expanded to `--key value` pairs.
+ */
+export declare function expandFixtureArgs(args: FixtureArgs | undefined): string[];
+export declare function parseSeedArgs(raw: string | undefined): FixtureArgs | undefined;

package/dist/src/browser/verify-fixture.js

@@ -0,0 +1,318 @@
+/**
+ * Verify fixture: structural expectations for `webcmd browser verify` output.
+ *
+ * The adapter-author skill runbook says every published adapter must write a
+ * fixture under `~/.webcmd/sites/<site>/verify/<command>.json` so later verify
+ * runs can catch shape regressions (missing columns, wrong types, bleeding
+ * values) without relying on exact content match — BBS / news / market data is
+ * too volatile for value equality.
+ *
+ * Schema:
+ *   {
+ *     // args can be either:
+ *     //   - an object of named flags: { "limit": 3 }  → expands to `--limit 3`
+ *     //   - a raw argv array:         ["123", "--limit", "3"]  → passed verbatim
+ *     // Use the array form for adapters that take positional subjects (e.g. <tid>, <url>, <query>).
+ *     "args": { "limit": 3 },
+ *     "expect": {
+ *       "rowCount": { "min": 1, "max": 10 },  // inclusive bounds
+ *       "columns":  ["a", "b"],                // every row must have these keys
+ *       "types":    { "a": "string", "b": "number|string" },
+ *       "patterns": { "url": "^https?://" },
+ *       "notEmpty": ["title", "url"],          // trimmed string must be non-empty
+ *       "mustNotContain": {                     // catch content-contamination bleed
+ *         "description": ["address:", "category:"]
+ *       },
+ *       "mustBeTruthy": ["count"]               // catch silent `|| 0` fallbacks
+ *     }
+ *   }
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+const DEFAULT_MAX_TOP_LEVEL_KEYS = 12;
+const DEFAULT_MAX_NESTED_DEPTH = 1;
+const ID_SHAPED_KEY_PATTERNS = [
+    /^id$/i,
+    /_id$/i,
+    /Id$/,
+    /^short_id$/i,
+    /^bvid$/i,
+    /^aid$/i,
+    /^tid$/i,
+    /^asin$/i,
+    /^sku$/i,
+    /^isbn$/i,
+    /^doi$/i,
+    /^slug$/i,
+    /^hn_id$/i,
+    /^username$/i,
+    /^handle$/i,
+    /^uri$/i,
+];
+export function fixturePath(site, command) {
+    return path.join(os.homedir(), '.webcmd', 'sites', site, 'verify', `${command}.json`);
+}
+export function loadFixture(site, command) {
+    const p = fixturePath(site, command);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = fs.readFileSync(p, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`Failed to parse fixture ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function writeFixture(site, command, fixture) {
+    const p = fixturePath(site, command);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, `${JSON.stringify(fixture, null, 2)}\n`, 'utf-8');
+    return p;
+}
+/**
+ * Derive a reasonable fixture from sample output. Used by `--write-fixture`
+ * to seed a first draft the author can hand-tune.
+ *
+ * Heuristics:
+ * - rowCount.min = 1 if rows non-empty, else 0
+ * - columns = keys from the first row
+ * - types = typeof of the first row's values, with "number|string" for mixed
+ * - no auto patterns / notEmpty — author should add those deliberately
+ */
+export function deriveFixture(rows, args) {
+    const expect = {};
+    if (rows.length === 0) {
+        expect.rowCount = { min: 0 };
+        return { ...(args ? { args } : {}), expect };
+    }
+    expect.rowCount = { min: 1 };
+    const first = rows[0];
+    const columns = Object.keys(first);
+    expect.columns = columns;
+    const types = {};
+    for (const col of columns) {
+        const observed = new Set();
+        for (const row of rows) {
+            const v = row[col];
+            observed.add(jsType(v));
+        }
+        types[col] = [...observed].sort().join('|');
+    }
+    expect.types = types;
+    return { ...(args ? { args } : {}), expect };
+}
+export function validateRows(rows, fixture) {
+    const failures = [];
+    const expect = fixture.expect;
+    if (!expect)
+        return failures;
+    if (expect.rowCount) {
+        const { min, max } = expect.rowCount;
+        if (typeof min === 'number' && rows.length < min) {
+            failures.push({ rule: 'rowCount', detail: `got ${rows.length} rows, expected at least ${min}` });
+        }
+        if (typeof max === 'number' && rows.length > max) {
+            failures.push({ rule: 'rowCount', detail: `got ${rows.length} rows, expected at most ${max}` });
+        }
+    }
+    const columns = expect.columns ?? [];
+    const types = expect.types ?? {};
+    const patterns = expect.patterns ?? {};
+    const notEmpty = expect.notEmpty ?? [];
+    const compiledPatterns = {};
+    for (const [col, src] of Object.entries(patterns)) {
+        try {
+            compiledPatterns[col] = new RegExp(src);
+        }
+        catch (err) {
+            failures.push({ rule: 'pattern', detail: `pattern for "${col}" invalid: ${err instanceof Error ? err.message : String(err)}` });
+        }
+    }
+    rows.forEach((row, i) => {
+        for (const col of columns) {
+            if (!(col in row)) {
+                failures.push({ rule: 'column', detail: `missing column "${col}"`, rowIndex: i });
+            }
+        }
+        for (const [col, declared] of Object.entries(types)) {
+            if (!(col in row))
+                continue;
+            const actual = jsType(row[col]);
+            if (!typeMatches(actual, declared)) {
+                failures.push({
+                    rule: 'type',
+                    detail: `"${col}" is ${actual}, expected ${declared}`,
+                    rowIndex: i,
+                });
+            }
+        }
+        for (const [col, re] of Object.entries(compiledPatterns)) {
+            if (!(col in row))
+                continue;
+            const v = row[col];
+            if (v === null || v === undefined)
+                continue;
+            if (!re.test(String(v))) {
+                failures.push({
+                    rule: 'pattern',
+                    detail: `"${col}"=${JSON.stringify(String(v).slice(0, 60))} does not match /${re.source}/`,
+                    rowIndex: i,
+                });
+            }
+        }
+        for (const col of notEmpty) {
+            const v = row[col];
+            if (v === null || v === undefined || String(v).trim() === '') {
+                failures.push({ rule: 'notEmpty', detail: `"${col}" is empty`, rowIndex: i });
+            }
+        }
+        for (const [col, needles] of Object.entries(expect.mustNotContain ?? {})) {
+            if (!(col in row))
+                continue;
+            const v = row[col];
+            if (v === null || v === undefined)
+                continue;
+            const haystack = String(v);
+            for (const needle of needles) {
+                if (haystack.includes(needle)) {
+                    failures.push({
+                        rule: 'mustNotContain',
+                        detail: `"${col}" contains forbidden substring ${JSON.stringify(needle)}`,
+                        rowIndex: i,
+                    });
+                }
+            }
+        }
+        for (const col of expect.mustBeTruthy ?? []) {
+            if (!(col in row))
+                continue;
+            if (!row[col]) {
+                failures.push({
+                    rule: 'mustBeTruthy',
+                    detail: `"${col}" is falsy (${JSON.stringify(row[col])}) — likely silent fallback`,
+                    rowIndex: i,
+                });
+            }
+        }
+    });
+    return failures;
+}
+export function validateRowShape(rows, opts = {}) {
+    const failures = [];
+    const maxTopLevelKeys = opts.maxTopLevelKeys ?? DEFAULT_MAX_TOP_LEVEL_KEYS;
+    const maxNestedDepth = opts.maxNestedDepth ?? DEFAULT_MAX_NESTED_DEPTH;
+    rows.forEach((row, i) => {
+        const keys = Object.keys(row);
+        if (keys.length > maxTopLevelKeys) {
+            failures.push({
+                rule: 'shapeKeyCount',
+                detail: `row has ${keys.length} top-level keys, expected at most ${maxTopLevelKeys}`,
+                rowIndex: i,
+            });
+        }
+        for (const [key, value] of Object.entries(row)) {
+            const depth = nestedDepth(value);
+            if (depth > maxNestedDepth) {
+                failures.push({
+                    rule: 'shapeDepth',
+                    detail: `"${key}" nesting depth is ${depth}, expected at most ${maxNestedDepth}`,
+                    rowIndex: i,
+                });
+            }
+            for (const path of nestedIdPaths(value, key)) {
+                failures.push({
+                    rule: 'shapeNestedId',
+                    detail: `id-shaped field "${path}" must be a top-level row key`,
+                    rowIndex: i,
+                });
+            }
+        }
+    });
+    return failures;
+}
+/**
+ * Convert fixture args into argv tokens appended after the command name.
+ * - Array form is passed through verbatim (stringified), supporting positional subjects.
+ * - Object form is expanded to `--key value` pairs.
+ */
+export function expandFixtureArgs(args) {
+    if (!args)
+        return [];
+    if (Array.isArray(args))
+        return args.map((v) => String(v));
+    const out = [];
+    for (const [k, v] of Object.entries(args)) {
+        out.push(`--${k}`, String(v));
+    }
+    return out;
+}
+export function parseSeedArgs(raw) {
+    if (raw === undefined)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed !== null && typeof parsed === 'object')
+            return parsed;
+        return [parsed];
+    }
+    catch {
+        return [raw];
+    }
+}
+function jsType(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+function nestedDepth(value) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return 0;
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return 1;
+        return 1 + Math.max(...value.map(nestedDepth));
+    }
+    const values = Object.values(value);
+    if (values.length === 0)
+        return 1;
+    return 1 + Math.max(...values.map(nestedDepth));
+}
+function nestedIdPaths(value, prefix) {
+    if (value === null || value === undefined || typeof value !== 'object')
+        return [];
+    const paths = [];
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            paths.push(...nestedIdPaths(item, `${prefix}[${index}]`));
+        });
+        return paths;
+    }
+    for (const [key, nested] of Object.entries(value)) {
+        const childPath = `${prefix}.${key}`;
+        if (isIdShapedKey(key))
+            paths.push(childPath);
+        paths.push(...nestedIdPaths(nested, childPath));
+    }
+    return paths;
+}
+function isIdShapedKey(key) {
+    return ID_SHAPED_KEY_PATTERNS.some((pattern) => pattern.test(key));
+}
+function typeMatches(actual, declared) {
+    const allowed = declared.split('|').map((s) => s.trim()).filter(Boolean);
+    if (allowed.length === 0)
+        return true;
+    if (allowed.includes('any'))
+        return true;
+    return allowed.includes(actual);
+}

package/dist/src/browser/verify-fixture.test.d.ts

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