@jackwener/opencli 0.1.0

package/dist/pipeline.js

@@ -0,0 +1,315 @@
+/**
+ * YAML pipeline executor.
+ * Steps: fetch, navigate, evaluate, map, filter, sort, limit, select, snapshot, click, type, wait, press, intercept.
+ */
+import chalk from 'chalk';
+export async function executePipeline(page, pipeline, ctx = {}) {
+    const args = ctx.args ?? {};
+    const debug = ctx.debug ?? false;
+    let data = null;
+    const total = pipeline.length;
+    for (let i = 0; i < pipeline.length; i++) {
+        const step = pipeline[i];
+        if (!step || typeof step !== 'object')
+            continue;
+        for (const [op, params] of Object.entries(step)) {
+            if (debug)
+                debugStepStart(i + 1, total, op, params);
+            data = await executeStep(page, op, params, data, args);
+            if (debug)
+                debugStepResult(op, data);
+        }
+    }
+    return data;
+}
+function normalizeEvaluateSource(source) {
+    const stripped = source.trim();
+    if (!stripped)
+        return '() => undefined';
+    if (stripped.startsWith('(') && stripped.endsWith(')()'))
+        return `() => (${stripped})`;
+    if (/^(async\s+)?\([^)]*\)\s*=>/.test(stripped))
+        return stripped;
+    if (/^(async\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=>/.test(stripped))
+        return stripped;
+    if (stripped.startsWith('function ') || stripped.startsWith('async function '))
+        return stripped;
+    return `() => (${stripped})`;
+}
+function debugStepStart(stepNum, total, op, params) {
+    let preview = '';
+    if (typeof params === 'string') {
+        preview = params.length <= 80 ? ` → ${params}` : ` → ${params.slice(0, 77)}...`;
+    }
+    else if (params && typeof params === 'object' && !Array.isArray(params)) {
+        preview = ` (${Object.keys(params).join(', ')})`;
+    }
+    process.stderr.write(`  ${chalk.dim(`[${stepNum}/${total}]`)} ${chalk.bold.cyan(op)}${preview}\n`);
+}
+function debugStepResult(op, data) {
+    if (data === null || data === undefined) {
+        process.stderr.write(`       ${chalk.dim('→ (no data)')}\n`);
+    }
+    else if (Array.isArray(data)) {
+        process.stderr.write(`       ${chalk.dim(`→ ${data.length} items`)}\n`);
+    }
+    else if (typeof data === 'object') {
+        const keys = Object.keys(data).slice(0, 5);
+        process.stderr.write(`       ${chalk.dim(`→ dict (${keys.join(', ')}${Object.keys(data).length > 5 ? '...' : ''})`)}\n`);
+    }
+    else if (typeof data === 'string') {
+        const p = data.slice(0, 60).replace(/\n/g, '\\n');
+        process.stderr.write(`       ${chalk.dim(`→ "${p}${data.length > 60 ? '...' : ''}"`)}\n`);
+    }
+    else {
+        process.stderr.write(`       ${chalk.dim(`→ ${typeof data}`)}\n`);
+    }
+}
+// Single URL fetch helper
+async function fetchSingle(page, url, method, queryParams, headers, args, data) {
+    const renderedParams = {};
+    for (const [k, v] of Object.entries(queryParams))
+        renderedParams[k] = String(render(v, { args, data }));
+    const renderedHeaders = {};
+    for (const [k, v] of Object.entries(headers))
+        renderedHeaders[k] = String(render(v, { args, data }));
+    let finalUrl = url;
+    if (Object.keys(renderedParams).length > 0) {
+        const qs = new URLSearchParams(renderedParams).toString();
+        finalUrl = `${finalUrl}${finalUrl.includes('?') ? '&' : '?'}${qs}`;
+    }
+    if (page === null) {
+        const resp = await fetch(finalUrl, { method: method.toUpperCase(), headers: renderedHeaders });
+        return resp.json();
+    }
+    const headersJs = JSON.stringify(renderedHeaders);
+    const escapedUrl = finalUrl.replace(/"/g, '\\"');
+    return page.evaluate(`
+    async () => {
+      const resp = await fetch("${escapedUrl}", {
+        method: "${method}", headers: ${headersJs}, credentials: "include"
+      });
+      return await resp.json();
+    }
+  `);
+}
+async function executeStep(page, op, params, data, args) {
+    switch (op) {
+        case 'navigate': {
+            const url = render(params, { args, data });
+            await page.goto(String(url));
+            return data;
+        }
+        case 'fetch': {
+            const urlOrObj = typeof params === 'string' ? params : (params?.url ?? '');
+            const method = params?.method ?? 'GET';
+            const queryParams = params?.params ?? {};
+            const headers = params?.headers ?? {};
+            const urlTemplate = String(urlOrObj);
+            // Per-item fetch when data is array and URL references item
+            if (Array.isArray(data) && urlTemplate.includes('item')) {
+                const results = [];
+                for (let i = 0; i < data.length; i++) {
+                    const itemUrl = String(render(urlTemplate, { args, data, item: data[i], index: i }));
+                    results.push(await fetchSingle(page, itemUrl, method, queryParams, headers, args, data));
+                }
+                return results;
+            }
+            const url = render(urlOrObj, { args, data });
+            return fetchSingle(page, String(url), method, queryParams, headers, args, data);
+        }
+        case 'select': {
+            const pathStr = String(render(params, { args, data }));
+            if (data && typeof data === 'object') {
+                let current = data;
+                for (const part of pathStr.split('.')) {
+                    if (current && typeof current === 'object' && !Array.isArray(current))
+                        current = current[part];
+                    else if (Array.isArray(current) && /^\d+$/.test(part))
+                        current = current[parseInt(part, 10)];
+                    else
+                        return null;
+                }
+                return current;
+            }
+            return data;
+        }
+        case 'evaluate': {
+            const js = String(render(params, { args, data }));
+            return page.evaluate(normalizeEvaluateSource(js));
+        }
+        case 'snapshot': {
+            const opts = (typeof params === 'object' && params) ? params : {};
+            return page.snapshot({ interactive: opts.interactive ?? false, compact: opts.compact ?? false, maxDepth: opts.max_depth, raw: opts.raw ?? false });
+        }
+        case 'click': {
+            await page.click(String(render(params, { args, data })).replace(/^@/, ''));
+            return data;
+        }
+        case 'type': {
+            if (typeof params === 'object' && params) {
+                const ref = String(render(params.ref ?? '', { args, data })).replace(/^@/, '');
+                const text = String(render(params.text ?? '', { args, data }));
+                await page.typeText(ref, text);
+                if (params.submit)
+                    await page.pressKey('Enter');
+            }
+            return data;
+        }
+        case 'wait': {
+            if (typeof params === 'number')
+                await page.wait(params);
+            else if (typeof params === 'object' && params) {
+                if ('text' in params) {
+                    const timeout = params.timeout ?? 10;
+                    const start = Date.now();
+                    while ((Date.now() - start) / 1000 < timeout) {
+                        const snap = await page.snapshot({ raw: true });
+                        if (typeof snap === 'string' && snap.includes(params.text))
+                            break;
+                        await page.wait(0.5);
+                    }
+                }
+                else if ('time' in params)
+                    await page.wait(Number(params.time));
+            }
+            else if (typeof params === 'string')
+                await page.wait(Number(render(params, { args, data })));
+            return data;
+        }
+        case 'press': {
+            await page.pressKey(String(render(params, { args, data })));
+            return data;
+        }
+        case 'map': {
+            if (!data || typeof data !== 'object')
+                return data;
+            let items = Array.isArray(data) ? data : [data];
+            if (!Array.isArray(data) && typeof data === 'object' && 'data' in data)
+                items = data.data;
+            const result = [];
+            for (let i = 0; i < items.length; i++) {
+                const item = items[i];
+                const row = {};
+                for (const [key, template] of Object.entries(params))
+                    row[key] = render(template, { args, data, item, index: i });
+                result.push(row);
+            }
+            return result;
+        }
+        case 'filter': {
+            if (!Array.isArray(data))
+                return data;
+            return data.filter((item, i) => evalExpr(String(params), { args, item, index: i }));
+        }
+        case 'sort': {
+            if (!Array.isArray(data))
+                return data;
+            const key = typeof params === 'object' ? (params.by ?? '') : String(params);
+            const reverse = typeof params === 'object' ? params.order === 'desc' : false;
+            return [...data].sort((a, b) => { const va = a[key] ?? ''; const vb = b[key] ?? ''; const cmp = va < vb ? -1 : va > vb ? 1 : 0; return reverse ? -cmp : cmp; });
+        }
+        case 'limit': {
+            if (!Array.isArray(data))
+                return data;
+            return data.slice(0, Number(render(params, { args, data })));
+        }
+        case 'intercept': return data;
+        default: return data;
+    }
+}
+function render(template, ctx) {
+    if (typeof template !== 'string')
+        return template;
+    const fullMatch = template.match(/^\$\{\{\s*(.*?)\s*\}\}$/);
+    if (fullMatch)
+        return evalExpr(fullMatch[1].trim(), ctx);
+    return template.replace(/\$\{\{\s*(.*?)\s*\}\}/g, (_m, expr) => String(evalExpr(expr.trim(), ctx)));
+}
+function evalExpr(expr, ctx) {
+    const args = ctx.args ?? {};
+    const item = ctx.item ?? {};
+    const data = ctx.data;
+    const index = ctx.index ?? 0;
+    // Default filter: args.limit | default(20)
+    if (expr.includes('|') && expr.includes('default(')) {
+        const [mainExpr, rest] = expr.split('|', 2);
+        const defaultMatch = rest.match(/default\((.+?)\)/);
+        const defaultVal = defaultMatch ? defaultMatch[1] : null;
+        const result = resolvePath(mainExpr.trim(), { args, item, data, index });
+        if (result === null || result === undefined) {
+            if (defaultVal !== null) {
+                const intVal = parseInt(defaultVal, 10);
+                if (!isNaN(intVal) && String(intVal) === defaultVal.trim())
+                    return intVal;
+                return defaultVal.replace(/^['"]|['"]$/g, '');
+            }
+        }
+        return result;
+    }
+    // Arithmetic: index + 1
+    const arithMatch = expr.match(/^([\w][\w.]*)\s*([+\-*/])\s*(\d+)$/);
+    if (arithMatch) {
+        const [, varName, op, numStr] = arithMatch;
+        const val = resolvePath(varName, { args, item, data, index });
+        if (val !== null && val !== undefined) {
+            const numVal = Number(val);
+            const num = Number(numStr);
+            if (!isNaN(numVal)) {
+                switch (op) {
+                    case '+': return numVal + num;
+                    case '-': return numVal - num;
+                    case '*': return numVal * num;
+                    case '/': return num !== 0 ? numVal / num : 0;
+                }
+            }
+        }
+    }
+    // JS-like fallback expression: item.tweetCount || 'N/A'
+    const orMatch = expr.match(/^(.+?)\s*\|\|\s*(.+)$/);
+    if (orMatch) {
+        const left = evalExpr(orMatch[1].trim(), ctx);
+        if (left)
+            return left;
+        const right = orMatch[2].trim();
+        return right.replace(/^['"]|['"]$/g, '');
+    }
+    return resolvePath(expr, { args, item, data, index });
+}
+function resolvePath(pathStr, ctx) {
+    const args = ctx.args ?? {};
+    const item = ctx.item ?? {};
+    const data = ctx.data;
+    const index = ctx.index ?? 0;
+    const parts = pathStr.split('.');
+    const rootName = parts[0];
+    let obj;
+    let rest;
+    if (rootName === 'args') {
+        obj = args;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'item') {
+        obj = item;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'data') {
+        obj = data;
+        rest = parts.slice(1);
+    }
+    else if (rootName === 'index')
+        return index;
+    else {
+        obj = item;
+        rest = parts;
+    }
+    for (const part of rest) {
+        if (obj && typeof obj === 'object' && !Array.isArray(obj))
+            obj = obj[part];
+        else if (Array.isArray(obj) && /^\d+$/.test(part))
+            obj = obj[parseInt(part, 10)];
+        else
+            return null;
+    }
+    return obj;
+}

package/dist/promote.d.ts

@@ -0,0 +1 @@
+export declare function promoteCandidate(opts: any): any;

package/dist/promote.js

@@ -0,0 +1,3 @@
+/** Promote verified drafts. */
+import { registerCandidates } from './register.js';
+export function promoteCandidate(opts) { return registerCandidates(opts); }

package/dist/register.d.ts

@@ -0,0 +1,2 @@
+/** Register candidates, promote, scaffold, generate — stubs with exports. */
+export declare function registerCandidates(opts: any): any;

package/dist/register.js

@@ -0,0 +1,2 @@
+/** Register candidates, promote, scaffold, generate — stubs with exports. */
+export function registerCandidates(opts) { return { ok: true, count: 0 }; }

package/dist/registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ */
+export declare enum Strategy {
+    PUBLIC = "public",
+    COOKIE = "cookie",
+    HEADER = "header",
+    INTERCEPT = "intercept",
+    UI = "ui"
+}
+export interface Arg {
+    name: string;
+    type?: string;
+    default?: any;
+    required?: boolean;
+    help?: string;
+    choices?: string[];
+}
+export interface CliCommand {
+    site: string;
+    name: string;
+    description: string;
+    domain?: string;
+    strategy?: Strategy;
+    browser?: boolean;
+    args: Arg[];
+    columns?: string[];
+    func?: (page: any, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
+    pipeline?: any[];
+    timeoutSeconds?: number;
+    source?: string;
+}
+export interface CliOptions {
+    site: string;
+    name: string;
+    description?: string;
+    domain?: string;
+    strategy?: Strategy;
+    browser?: boolean;
+    args?: Arg[];
+    columns?: string[];
+    func?: (page: any, kwargs: Record<string, any>, debug?: boolean) => Promise<any>;
+    pipeline?: any[];
+    timeoutSeconds?: number;
+}
+export declare function cli(opts: CliOptions): CliCommand;
+export declare function getRegistry(): Map<string, CliCommand>;
+export declare function fullName(cmd: CliCommand): string;
+export declare function strategyLabel(cmd: CliCommand): string;
+export declare function registerCommand(cmd: CliCommand): void;

package/dist/registry.js

@@ -0,0 +1,42 @@
+/**
+ * Core registry: Strategy enum, Arg/CliCommand interfaces, cli() registration.
+ */
+export var Strategy;
+(function (Strategy) {
+    Strategy["PUBLIC"] = "public";
+    Strategy["COOKIE"] = "cookie";
+    Strategy["HEADER"] = "header";
+    Strategy["INTERCEPT"] = "intercept";
+    Strategy["UI"] = "ui";
+})(Strategy || (Strategy = {}));
+const _registry = new Map();
+export function cli(opts) {
+    const cmd = {
+        site: opts.site,
+        name: opts.name,
+        description: opts.description ?? '',
+        domain: opts.domain,
+        strategy: opts.strategy ?? (opts.browser === false ? Strategy.PUBLIC : Strategy.COOKIE),
+        browser: opts.browser ?? (opts.strategy === Strategy.PUBLIC ? false : true),
+        args: opts.args ?? [],
+        columns: opts.columns,
+        func: opts.func,
+        pipeline: opts.pipeline,
+        timeoutSeconds: opts.timeoutSeconds,
+    };
+    const key = fullName(cmd);
+    _registry.set(key, cmd);
+    return cmd;
+}
+export function getRegistry() {
+    return _registry;
+}
+export function fullName(cmd) {
+    return `${cmd.site}/${cmd.name}`;
+}
+export function strategyLabel(cmd) {
+    return cmd.strategy ?? 'public';
+}
+export function registerCommand(cmd) {
+    _registry.set(fullName(cmd), cmd);
+}

package/dist/runtime.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Runtime utilities: timeouts and browser session management.
+ */
+export declare const DEFAULT_BROWSER_CONNECT_TIMEOUT: number;
+export declare const DEFAULT_BROWSER_COMMAND_TIMEOUT: number;
+export declare const DEFAULT_BROWSER_EXPLORE_TIMEOUT: number;
+export declare const DEFAULT_BROWSER_SMOKE_TIMEOUT: number;
+export declare function runWithTimeout<T>(promise: Promise<T>, opts: {
+    timeout: number;
+    label?: string;
+}): Promise<T>;
+export declare function browserSession<T>(BrowserFactory: new () => any, fn: (page: any) => Promise<T>): Promise<T>;

package/dist/runtime.js

@@ -0,0 +1,27 @@
+/**
+ * Runtime utilities: timeouts and browser session management.
+ */
+export const DEFAULT_BROWSER_CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
+export const DEFAULT_BROWSER_COMMAND_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_COMMAND_TIMEOUT ?? '45', 10);
+export const DEFAULT_BROWSER_EXPLORE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_EXPLORE_TIMEOUT ?? '120', 10);
+export const DEFAULT_BROWSER_SMOKE_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_SMOKE_TIMEOUT ?? '60', 10);
+export async function runWithTimeout(promise, opts) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${opts.label ?? 'Operation'} timed out after ${opts.timeout}s`));
+        }, opts.timeout * 1000);
+        promise
+            .then((result) => { clearTimeout(timer); resolve(result); })
+            .catch((err) => { clearTimeout(timer); reject(err); });
+    });
+}
+export async function browserSession(BrowserFactory, fn) {
+    const mcp = new BrowserFactory();
+    try {
+        const page = await mcp.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT });
+        return await fn(page);
+    }
+    finally {
+        await mcp.close().catch(() => { });
+    }
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,2 @@
+/** Scaffold a draft CLI from endpoint evidence. */
+export declare function scaffoldCli(opts: any): any;

package/dist/scaffold.js

@@ -0,0 +1,2 @@
+/** Scaffold a draft CLI from endpoint evidence. */
+export function scaffoldCli(opts) { return { ok: true }; }

package/dist/smoke.d.ts

@@ -0,0 +1,2 @@
+/** Smoke testing, verification, register, promote, explore, synthesize, scaffold, generate — stubs. */
+export declare function runSmoke(cmd: any, page: any, args?: any): Promise<any>;

package/dist/smoke.js

@@ -0,0 +1,2 @@
+/** Smoke testing, verification, register, promote, explore, synthesize, scaffold, generate — stubs. */
+export async function runSmoke(cmd, page, args) { return { ok: true, result: null }; }

package/dist/snapshotFormatter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Aria snapshot formatter: parses Playwright MCP snapshot text into clean format.
+ */
+export interface FormatOptions {
+    interactive?: boolean;
+    compact?: boolean;
+    maxDepth?: number;
+}
+export declare function formatSnapshot(raw: string, opts?: FormatOptions): string;

package/dist/snapshotFormatter.js

@@ -0,0 +1,41 @@
+/**
+ * Aria snapshot formatter: parses Playwright MCP snapshot text into clean format.
+ */
+export function formatSnapshot(raw, opts = {}) {
+    if (!raw || typeof raw !== 'string')
+        return '';
+    const lines = raw.split('\n');
+    const result = [];
+    let refCounter = 0;
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const indent = line.length - line.trimStart().length;
+        const depth = Math.floor(indent / 2);
+        if (opts.maxDepth && depth > opts.maxDepth)
+            continue;
+        let content = line.trimStart();
+        // Skip non-interactive elements in interactive mode
+        if (opts.interactive) {
+            const interactiveRoles = ['button', 'link', 'textbox', 'checkbox', 'radio', 'combobox', 'tab', 'menuitem', 'option'];
+            const role = content.split(/[\s[]/)[0]?.toLowerCase() ?? '';
+            if (!interactiveRoles.some(r => role.includes(r)) && depth > 1)
+                continue;
+        }
+        // Compact: strip verbose role descriptions
+        if (opts.compact) {
+            content = content
+                .replace(/\s*\[.*?\]\s*/g, ' ')
+                .replace(/\s+/g, ' ')
+                .trim();
+        }
+        // Assign refs to interactive elements
+        const interactivePattern = /^(button|link|textbox|checkbox|radio|combobox|tab|menuitem|option)\b/i;
+        if (interactivePattern.test(content)) {
+            refCounter++;
+            content = `[@${refCounter}] ${content}`;
+        }
+        result.push('  '.repeat(depth) + content);
+    }
+    return result.join('\n');
+}

package/dist/synthesize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Synthesize: turn explore capabilities into ready-to-use CLI definitions.
+ *
+ * Takes the structured capabilities from Deep Explore and generates
+ * YAML pipeline files that can be directly registered as CLI commands.
+ *
+ * This is the bridge between discovery (explore) and usability (CLI).
+ */
+export declare function synthesizeFromExplore(target: string, opts?: any): any;
+export declare function renderSynthesizeSummary(r: any): string;