@jackwener/opencli 1.5.9 → 1.6.0

package/dist/browser/daemon-client.test.js

@@ -0,0 +1,77 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fetchDaemonStatus, isDaemonRunning, isExtensionConnected, requestDaemonShutdown, } from './daemon-client.js';
+describe('daemon-client', () => {
+    beforeEach(() => {
+        vi.stubGlobal('fetch', vi.fn());
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('fetchDaemonStatus sends the shared status request and returns parsed data', async () => {
+        const status = {
+            ok: true,
+            pid: 123,
+            uptime: 10,
+            extensionConnected: true,
+            extensionVersion: '1.2.3',
+            pending: 0,
+            lastCliRequestTime: Date.now(),
+            memoryMB: 32,
+            port: 19825,
+        };
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve(status),
+        });
+        await expect(fetchDaemonStatus()).resolves.toEqual(status);
+        expect(fetchMock).toHaveBeenCalledWith(expect.stringMatching(/\/status$/), expect.objectContaining({
+            headers: expect.objectContaining({ 'X-OpenCLI': '1' }),
+        }));
+    });
+    it('fetchDaemonStatus returns null on network failure', async () => {
+        vi.mocked(fetch).mockRejectedValue(new Error('ECONNREFUSED'));
+        await expect(fetchDaemonStatus()).resolves.toBeNull();
+    });
+    it('requestDaemonShutdown POSTs to the shared shutdown endpoint', async () => {
+        const fetchMock = vi.mocked(fetch);
+        fetchMock.mockResolvedValue({ ok: true });
+        await expect(requestDaemonShutdown()).resolves.toBe(true);
+        expect(fetchMock).toHaveBeenCalledWith(expect.stringMatching(/\/shutdown$/), expect.objectContaining({
+            method: 'POST',
+            headers: expect.objectContaining({ 'X-OpenCLI': '1' }),
+        }));
+    });
+    it('isDaemonRunning reflects shared status availability', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({
+                ok: true,
+                pid: 123,
+                uptime: 10,
+                extensionConnected: false,
+                pending: 0,
+                lastCliRequestTime: Date.now(),
+                memoryMB: 16,
+                port: 19825,
+            }),
+        });
+        await expect(isDaemonRunning()).resolves.toBe(true);
+    });
+    it('isExtensionConnected reflects shared status payload', async () => {
+        vi.mocked(fetch).mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({
+                ok: true,
+                pid: 123,
+                uptime: 10,
+                extensionConnected: false,
+                pending: 0,
+                lastCliRequestTime: Date.now(),
+                memoryMB: 16,
+                port: 19825,
+            }),
+        });
+        await expect(isExtensionConnected()).resolves.toBe(false);
+    });
+});

package/dist/browser/discover.js

@@ -1,30 +1,19 @@
 /**
  * Daemon discovery — checks if the daemon is running.
  */
-import { DEFAULT_DAEMON_PORT } from '../constants.js';
-import { isDaemonRunning } from './daemon-client.js';
+import { fetchDaemonStatus, isDaemonRunning } from './daemon-client.js';
 export { isDaemonRunning };
 /**
  * Check daemon status and return connection info.
  */
 export async function checkDaemonStatus(opts) {
-    try {
-        const port = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), opts?.timeout ?? 2000);
-        try {
-            const res = await fetch(`http://127.0.0.1:${port}/status`, {
-                headers: { 'X-OpenCLI': '1' },
-                signal: controller.signal,
-            });
-            const data = await res.json();
-            return { running: true, extensionConnected: data.extensionConnected, extensionVersion: data.extensionVersion };
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-    catch {
+    const status = await fetchDaemonStatus({ timeout: opts?.timeout ?? 2000 });
+    if (!status) {
         return { running: false, extensionConnected: false };
     }
+    return {
+        running: true,
+        extensionConnected: status.extensionConnected,
+        extensionVersion: status.extensionVersion,
+    };
 }

package/dist/browser/page.d.ts

@@ -50,4 +50,8 @@ export declare class Page extends BasePage {
      * payload size limits of base64-in-evaluate.
      */
     setFileInput(files: string[], selector?: string): Promise<void>;
+    cdp(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    nativeClick(x: number, y: number): Promise<void>;
+    nativeType(text: string): Promise<void>;
+    nativeKeyPress(key: string, modifiers?: string[]): Promise<void>;
 }

package/dist/browser/page.js

@@ -171,5 +171,52 @@ export class Page extends BasePage {
             throw new Error('setFileInput returned no count — command may not be supported by the extension');
         }
     }
+    async cdp(method, params = {}) {
+        return sendCommand('cdp', {
+            cdpMethod: method,
+            cdpParams: params,
+            ...this._cmdOpts(),
+        });
+    }
+    async nativeClick(x, y) {
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mousePressed',
+            x, y,
+            button: 'left',
+            clickCount: 1,
+        });
+        await this.cdp('Input.dispatchMouseEvent', {
+            type: 'mouseReleased',
+            x, y,
+            button: 'left',
+            clickCount: 1,
+        });
+    }
+    async nativeType(text) {
+        // Use Input.insertText for reliable Unicode/CJK text insertion
+        await this.cdp('Input.insertText', { text });
+    }
+    async nativeKeyPress(key, modifiers = []) {
+        let modifierFlags = 0;
+        for (const mod of modifiers) {
+            if (mod === 'Alt')
+                modifierFlags |= 1;
+            if (mod === 'Ctrl')
+                modifierFlags |= 2;
+            if (mod === 'Meta')
+                modifierFlags |= 4;
+            if (mod === 'Shift')
+                modifierFlags |= 8;
+        }
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyDown',
+            key,
+            modifiers: modifierFlags,
+        });
+        await this.cdp('Input.dispatchKeyEvent', {
+            type: 'keyUp',
+            key,
+            modifiers: modifierFlags,
+        });
+    }
 }
-// (End of file)

package/dist/cli.js

@@ -16,6 +16,12 @@ import { loadExternalClis, executeExternalCli, installExternalCli, registerExter
 import { registerAllCommands } from './commanderAdapter.js';
 import { EXIT_CODES, getErrorMessage } from './errors.js';
 import { daemonStatus, daemonStop, daemonRestart } from './commands/daemon.js';
+/** Create a browser page for operate commands. Uses 'operate' workspace for session persistence. */
+async function getOperatePage() {
+    const { BrowserBridge } = await import('./browser/index.js');
+    const bridge = new BrowserBridge();
+    return bridge.connect({ timeout: 30, workspace: 'operate:default' });
+}
 export function runCli(BUILTIN_CLIS, USER_CLIS) {
     const program = new Command();
     // enablePositionalOptions: prevents parent from consuming flags meant for subcommands;
@@ -210,6 +216,392 @@ export function runCli(BUILTIN_CLIS, USER_CLIS) {
         }, { workspace });
         console.log(renderCascadeResult(result));
     });
+    // ── Built-in: operate (browser control for Claude Code skill) ───────────────
+    //
+    // Make websites accessible for AI agents.
+    // All commands wrapped in operateAction() for consistent error handling.
+    const operate = program
+        .command('operate')
+        .description('Browser control — navigate, click, type, extract, wait (no LLM needed)');
+    /** Wrap operate actions with error handling and optional --json output */
+    function operateAction(fn) {
+        return async (...args) => {
+            try {
+                const page = await getOperatePage();
+                await fn(page, ...args);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes('Extension not connected') || msg.includes('Daemon')) {
+                    console.error(`Browser not connected. Run 'opencli doctor' to diagnose.`);
+                }
+                else if (msg.includes('attach failed') || msg.includes('chrome-extension://')) {
+                    console.error(`Browser attach failed — another extension may be interfering. Try disabling 1Password.`);
+                }
+                else {
+                    console.error(`Error: ${msg}`);
+                }
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+            }
+        };
+    }
+    // ── Navigation ──
+    /** Network interceptor JS — injected on every open/navigate to capture fetch/XHR */
+    const NETWORK_INTERCEPTOR_JS = `(function(){if(window.__opencli_net)return;window.__opencli_net=[];var M=200,B=50000,F=window.fetch;window.fetch=async function(){var r=await F.apply(this,arguments);try{var ct=r.headers.get('content-type')||'';if(ct.includes('json')||ct.includes('text')){var c=r.clone(),t=await c.text();if(window.__opencli_net.length<M){var b=null;if(t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:r.url||(arguments[0]&&arguments[0].url)||String(arguments[0]),method:(arguments[1]&&arguments[1].method)||'GET',status:r.status,size:t.length,ct:ct,body:b})}}}catch(e){}return r};var X=XMLHttpRequest.prototype,O=X.open,S=X.send;X.open=function(m,u){this._om=m;this._ou=u;return O.apply(this,arguments)};X.send=function(){var x=this;x.addEventListener('load',function(){try{var ct=x.getResponseHeader('content-type')||'';if((ct.includes('json')||ct.includes('text'))&&window.__opencli_net.length<M){var t=x.responseText,b=null;if(t&&t.length<=B)try{b=JSON.parse(t)}catch(e){b=t}window.__opencli_net.push({url:x._ou,method:x._om||'GET',status:x.status,size:t?t.length:0,ct:ct,body:b})}}catch(e){}});return S.apply(this,arguments)}})()`;
+    operate.command('open').argument('<url>').description('Open URL in automation window')
+        .action(operateAction(async (page, url) => {
+        await page.goto(url);
+        await page.wait(2);
+        // Auto-inject network interceptor for API discovery
+        try {
+            await page.evaluate(NETWORK_INTERCEPTOR_JS);
+        }
+        catch { /* non-fatal */ }
+        console.log(`Navigated to: ${await page.getCurrentUrl?.() ?? url}`);
+    }));
+    operate.command('back').description('Go back in browser history')
+        .action(operateAction(async (page) => {
+        await page.evaluate('history.back()');
+        await page.wait(2);
+        console.log('Navigated back');
+    }));
+    operate.command('scroll').argument('<direction>', 'up or down').option('--amount <pixels>', 'Pixels to scroll', '500')
+        .description('Scroll page')
+        .action(operateAction(async (page, direction, opts) => {
+        if (direction !== 'up' && direction !== 'down') {
+            console.error(`Invalid direction "${direction}". Use "up" or "down".`);
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        await page.scroll(direction, parseInt(opts.amount, 10));
+        console.log(`Scrolled ${direction}`);
+    }));
+    // ── Inspect ──
+    operate.command('state').description('Page state: URL, title, interactive elements with [N] indices')
+        .action(operateAction(async (page) => {
+        const snapshot = await page.snapshot({ viewportExpand: 800 });
+        const url = await page.getCurrentUrl?.() ?? '';
+        console.log(`URL: ${url}\n`);
+        console.log(typeof snapshot === 'string' ? snapshot : JSON.stringify(snapshot, null, 2));
+    }));
+    operate.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)')
+        .description('Take screenshot')
+        .action(operateAction(async (page, path) => {
+        if (path) {
+            await page.screenshot({ path });
+            console.log(`Screenshot saved to: ${path}`);
+        }
+        else {
+            console.log(await page.screenshot({ format: 'png' }));
+        }
+    }));
+    // ── Get commands (structured data extraction) ──
+    const get = operate.command('get').description('Get page properties');
+    get.command('title').description('Page title')
+        .action(operateAction(async (page) => {
+        console.log(await page.evaluate('document.title'));
+    }));
+    get.command('url').description('Current page URL')
+        .action(operateAction(async (page) => {
+        console.log(await page.getCurrentUrl?.() ?? await page.evaluate('location.href'));
+    }));
+    get.command('text').argument('<index>', 'Element index').description('Element text content')
+        .action(operateAction(async (page, index) => {
+        const text = await page.evaluate(`document.querySelector('[data-opencli-ref="${index}"]')?.textContent?.trim()`);
+        console.log(text ?? '(empty)');
+    }));
+    get.command('value').argument('<index>', 'Element index').description('Input/textarea value')
+        .action(operateAction(async (page, index) => {
+        const val = await page.evaluate(`document.querySelector('[data-opencli-ref="${index}"]')?.value`);
+        console.log(val ?? '(empty)');
+    }));
+    get.command('html').option('--selector <css>', 'CSS selector scope').description('Page HTML (or scoped)')
+        .action(operateAction(async (page, opts) => {
+        const sel = opts.selector ? JSON.stringify(opts.selector) : 'null';
+        const html = await page.evaluate(`(${sel} ? document.querySelector(${sel})?.outerHTML : document.documentElement.outerHTML)?.slice(0, 50000)`);
+        console.log(html ?? '(empty)');
+    }));
+    get.command('attributes').argument('<index>', 'Element index').description('Element attributes')
+        .action(operateAction(async (page, index) => {
+        const attrs = await page.evaluate(`JSON.stringify(Object.fromEntries([...document.querySelector('[data-opencli-ref="${index}"]')?.attributes].map(a=>[a.name,a.value])))`);
+        console.log(attrs ?? '{}');
+    }));
+    // ── Interact ──
+    operate.command('click').argument('<index>', 'Element index from state').description('Click element by index')
+        .action(operateAction(async (page, index) => {
+        await page.click(index);
+        console.log(`Clicked element [${index}]`);
+    }));
+    operate.command('type').argument('<index>', 'Element index').argument('<text>', 'Text to type')
+        .description('Click element, then type text')
+        .action(operateAction(async (page, index, text) => {
+        await page.click(index);
+        await page.wait(0.3);
+        await page.typeText(index, text);
+        console.log(`Typed "${text}" into element [${index}]`);
+    }));
+    operate.command('select').argument('<index>', 'Element index of <select>').argument('<option>', 'Option text')
+        .description('Select dropdown option')
+        .action(operateAction(async (page, index, option) => {
+        const result = await page.evaluate(`
+        (function() {
+          var sel = document.querySelector('[data-opencli-ref="${index}"]');
+          if (!sel || sel.tagName !== 'SELECT') return { error: 'Not a <select>' };
+          var match = Array.from(sel.options).find(o => o.text.trim() === ${JSON.stringify(option)} || o.value === ${JSON.stringify(option)});
+          if (!match) return { error: 'Option not found', available: Array.from(sel.options).map(o => o.text.trim()) };
+          var setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, 'value')?.set;
+          if (setter) setter.call(sel, match.value); else sel.value = match.value;
+          sel.dispatchEvent(new Event('input', {bubbles:true}));
+          sel.dispatchEvent(new Event('change', {bubbles:true}));
+          return { selected: match.text };
+        })()
+      `);
+        if (result?.error) {
+            console.error(`Error: ${result.error}${result.available ? ` — Available: ${result.available.join(', ')}` : ''}`);
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        }
+        else {
+            console.log(`Selected "${result?.selected}" in element [${index}]`);
+        }
+    }));
+    operate.command('keys').argument('<key>', 'Key to press (Enter, Escape, Tab, Control+a)')
+        .description('Press keyboard key')
+        .action(operateAction(async (page, key) => {
+        await page.pressKey(key);
+        console.log(`Pressed: ${key}`);
+    }));
+    // ── Wait commands ──
+    operate.command('wait')
+        .argument('<type>', 'selector, text, or time')
+        .argument('[value]', 'CSS selector, text string, or seconds')
+        .option('--timeout <ms>', 'Timeout in milliseconds', '10000')
+        .description('Wait for selector, text, or time (e.g. wait selector ".loaded", wait text "Success", wait time 3)')
+        .action(operateAction(async (page, type, value, opts) => {
+        const timeout = parseInt(opts.timeout, 10);
+        if (type === 'time') {
+            const seconds = parseFloat(value ?? '2');
+            await page.wait(seconds);
+            console.log(`Waited ${seconds}s`);
+        }
+        else if (type === 'selector') {
+            if (!value) {
+                console.error('Missing CSS selector');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            await page.wait({ selector: value, timeout: timeout / 1000 });
+            console.log(`Element "${value}" appeared`);
+        }
+        else if (type === 'text') {
+            if (!value) {
+                console.error('Missing text');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            await page.wait({ text: value, timeout: timeout / 1000 });
+            console.log(`Text "${value}" appeared`);
+        }
+        else {
+            console.error(`Unknown wait type "${type}". Use: selector, text, or time`);
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+        }
+    }));
+    // ── Extract ──
+    operate.command('eval').argument('<js>', 'JavaScript code').description('Execute JS in page context, return result')
+        .action(operateAction(async (page, js) => {
+        const result = await page.evaluate(js);
+        if (typeof result === 'string')
+            console.log(result);
+        else
+            console.log(JSON.stringify(result, null, 2));
+    }));
+    // ── Network (API discovery) ──
+    operate.command('network')
+        .option('--detail <index>', 'Show full response body of request at index')
+        .option('--all', 'Show all requests including static resources')
+        .description('Show captured network requests (auto-captured since last open)')
+        .action(operateAction(async (page, opts) => {
+        const requests = await page.evaluate(`(function(){
+        var reqs = window.__opencli_net || [];
+        return JSON.stringify(reqs);
+      })()`);
+        let items = [];
+        try {
+            items = JSON.parse(requests);
+        }
+        catch {
+            console.log('No network data captured. Run "operate open <url>" first.');
+            return;
+        }
+        if (items.length === 0) {
+            console.log('No requests captured.');
+            return;
+        }
+        // Filter out static resources unless --all
+        if (!opts.all) {
+            items = items.filter(r => (r.ct?.includes('json') || r.ct?.includes('xml') || r.ct?.includes('text/plain')) &&
+                !/\.(js|css|png|jpg|gif|svg|woff|ico|map)(\?|$)/i.test(r.url) &&
+                !/analytics|tracking|telemetry|beacon|pixel|gtag|fbevents/i.test(r.url));
+        }
+        if (opts.detail !== undefined) {
+            const idx = parseInt(opts.detail, 10);
+            const req = items[idx];
+            if (!req) {
+                console.error(`Request #${idx} not found. ${items.length} requests available.`);
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            console.log(`${req.method} ${req.url}`);
+            console.log(`Status: ${req.status} | Size: ${req.size} | Type: ${req.ct}`);
+            console.log('---');
+            console.log(typeof req.body === 'string' ? req.body : JSON.stringify(req.body, null, 2));
+        }
+        else {
+            console.log(`Captured ${items.length} API requests:\n`);
+            items.forEach((r, i) => {
+                const bodyPreview = r.body ? (typeof r.body === 'string' ? r.body.slice(0, 60) : JSON.stringify(r.body).slice(0, 60)) : '';
+                console.log(`  [${i}] ${r.method} ${r.status} ${r.url.slice(0, 80)}`);
+                if (bodyPreview)
+                    console.log(`      ${bodyPreview}...`);
+            });
+            console.log(`\nUse --detail <index> to see full response body.`);
+        }
+    }));
+    // ── Init (adapter scaffolding) ──
+    operate.command('init')
+        .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
+        .description('Generate adapter scaffold in ~/.opencli/clis/')
+        .action(async (name) => {
+        try {
+            const parts = name.split('/');
+            if (parts.length !== 2 || !parts[0] || !parts[1]) {
+                console.error('Name must be site/command format (e.g. hn/top)');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const [site, command] = parts;
+            if (!/^[a-zA-Z0-9_-]+$/.test(site) || !/^[a-zA-Z0-9_-]+$/.test(command)) {
+                console.error('Name parts must be alphanumeric/dash/underscore only');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const os = await import('node:os');
+            const fs = await import('node:fs');
+            const path = await import('node:path');
+            const dir = path.join(os.homedir(), '.opencli', 'clis', site);
+            const filePath = path.join(dir, `${command}.ts`);
+            if (fs.existsSync(filePath)) {
+                console.log(`Adapter already exists: ${filePath}`);
+                return;
+            }
+            // Try to detect domain from last operate session
+            let domain = site;
+            try {
+                const page = await getOperatePage();
+                const url = await page.getCurrentUrl?.();
+                if (url) {
+                    try {
+                        domain = new URL(url).hostname;
+                    }
+                    catch { }
+                }
+            }
+            catch { /* no active session */ }
+            const template = `import { cli, Strategy } from '@jackwener/opencli/registry';
+
+cli({
+  site: '${site}',
+  name: '${command}',
+  description: '', // TODO: describe what this command does
+  domain: '${domain}',
+  strategy: Strategy.PUBLIC, // TODO: PUBLIC (no auth), COOKIE (needs login), UI (DOM interaction)
+  browser: false,            // TODO: set true if needs browser
+  args: [
+    { name: 'limit', type: 'int', default: 10, help: 'Number of items' },
+  ],
+  columns: [], // TODO: field names for table output (e.g. ['title', 'score', 'url'])
+  func: async (page, kwargs) => {
+    // TODO: implement data fetching
+    // Prefer API calls (fetch) over browser automation
+    // page is available if browser: true
+    return [];
+  },
+});
+`;
+            fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(filePath, template, 'utf-8');
+            console.log(`Created: ${filePath}`);
+            console.log(`Edit the file to implement your adapter, then run: opencli operate verify ${name}`);
+        }
+        catch (err) {
+            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        }
+    });
+    // ── Verify (test adapter) ──
+    operate.command('verify')
+        .argument('<name>', 'Adapter name in site/command format (e.g. hn/top)')
+        .description('Execute an adapter and show results')
+        .action(async (name) => {
+        try {
+            const parts = name.split('/');
+            if (parts.length !== 2) {
+                console.error('Name must be site/command format');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const [site, command] = parts;
+            if (!/^[a-zA-Z0-9_-]+$/.test(site) || !/^[a-zA-Z0-9_-]+$/.test(command)) {
+                console.error('Name parts must be alphanumeric/dash/underscore only');
+                process.exitCode = EXIT_CODES.USAGE_ERROR;
+                return;
+            }
+            const { execSync } = await import('node:child_process');
+            const os = await import('node:os');
+            const path = await import('node:path');
+            const filePath = path.join(os.homedir(), '.opencli', 'clis', site, `${command}.ts`);
+            const fs = await import('node:fs');
+            if (!fs.existsSync(filePath)) {
+                console.error(`Adapter not found: ${filePath}`);
+                console.error(`Run "opencli operate init ${name}" to create it.`);
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+                return;
+            }
+            console.log(`🔍 Verifying ${name}...\n`);
+            console.log(`  Loading: ${filePath}`);
+            try {
+                const output = execSync(`node dist/main.js ${site} ${command} --limit 3`, {
+                    cwd: path.join(path.dirname(import.meta.url.replace('file://', '')), '..'),
+                    timeout: 30000,
+                    encoding: 'utf-8',
+                    env: process.env,
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                });
+                console.log(`  Executing: opencli ${site} ${command} --limit 3\n`);
+                console.log(output);
+                console.log(`\n  ✓ Adapter works!`);
+            }
+            catch (err) {
+                console.log(`  Executing: opencli ${site} ${command} --limit 3\n`);
+                if (err.stdout)
+                    console.log(err.stdout);
+                if (err.stderr)
+                    console.error(err.stderr.slice(0, 500));
+                console.log(`\n  ✗ Adapter failed. Fix the code and try again.`);
+                process.exitCode = EXIT_CODES.GENERIC_ERROR;
+            }
+        }
+        catch (err) {
+            console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        }
+    });
+    // ── Session ──
+    operate.command('close').description('Close the automation window')
+        .action(operateAction(async (page) => {
+        await page.closeWindow?.();
+        console.log('Automation window closed');
+    }));
     // ── Built-in: doctor / completion ──────────────────────────────────────────
     program
         .command('doctor')

package/dist/clis/twitter/article.js

@@ -14,11 +14,38 @@ cli({
     ],
     columns: ['title', 'author', 'content', 'url'],
     func: async (page, kwargs) => {
-        // Extract tweet ID from URL if needed
+        // Extract tweet ID from URL if needed.
+        // Article URLs (x.com/i/article/{articleId}) use a different ID than
+        // tweet status URLs — the GraphQL endpoint needs the parent tweet ID.
         let tweetId = kwargs['tweet-id'];
+        const isArticleUrl = /\/article\/\d+/.test(tweetId);
         const urlMatch = tweetId.match(/\/(?:status|article)\/(\d+)/);
         if (urlMatch)
             tweetId = urlMatch[1];
+        if (isArticleUrl) {
+            // Navigate to the article page and resolve the parent tweet ID from DOM
+            await page.goto(`https://x.com/i/article/${tweetId}`);
+            await page.wait(3);
+            const resolvedId = await page.evaluate(`
+        (function() {
+          var links = document.querySelectorAll('a[href*="/status/"]');
+          for (var i = 0; i < links.length; i++) {
+            var m = links[i].href.match(/\\/status\\/(\\d+)/);
+            if (m) return m[1];
+          }
+          var og = document.querySelector('meta[property="og:url"]');
+          if (og && og.content) {
+            var m2 = og.content.match(/\\/status\\/(\\d+)/);
+            if (m2) return m2[1];
+          }
+          return null;
+        })()
+      `);
+            if (!resolvedId || typeof resolvedId !== 'string') {
+                throw new CommandExecutionError(`Could not resolve article ${tweetId} to a tweet ID. The article page may not contain a linked tweet.`);
+            }
+            tweetId = resolvedId;
+        }
         // Navigate to the tweet page for cookie context
         await page.goto(`https://x.com/i/status/${tweetId}`);
         await page.wait(3);

package/dist/clis/xiaohongshu/note.js

@@ -19,6 +19,7 @@ cli({
     columns: ['field', 'value'],
     func: async (page, kwargs) => {
         const raw = String(kwargs['note-id']);
+        const isBareNoteId = !/^https?:\/\//.test(raw.trim());
         const noteId = parseNoteId(raw);
         const url = buildNoteUrl(raw);
         await page.goto(url);
@@ -60,6 +61,16 @@ cli({
         // XHS renders placeholder text like "赞"/"收藏"/"评论" when count is 0;
         // normalize to '0' unless the value looks numeric.
         const numOrZero = (v) => /^\d+/.test(v) ? v : '0';
+        // XHS sometimes renders an empty shell page for bare /explore/<id> visits
+        // when the request lacks a valid xsec_token.  Title + author are always
+        // present on a real note, so their absence is the simplest reliable signal.
+        const emptyShell = !d.title && !d.author;
+        if (emptyShell) {
+            if (isBareNoteId) {
+                throw new EmptyResultError('xiaohongshu/note', 'Pass the full search_result URL with xsec_token, for example from `opencli xiaohongshu search`, instead of a bare note ID.');
+            }
+            throw new EmptyResultError('xiaohongshu/note', 'The note page loaded without visible content. Retry with a fresh URL or run with --verbose; if it persists, the page structure may have changed.');
+        }
         const rows = [
             { field: 'title', value: d.title || '' },
             { field: 'author', value: d.author || '' },