@jackwener/opencli 1.7.5 → 1.7.7

package/dist/src/download/index.js

@@ -60,94 +60,79 @@ export function requiresYtdlp(url) {
  */
 export async function httpDownload(url, destPath, options = {}, redirectCount = 0) {
     const { cookies, headers = {}, timeout = 30000, onProgress, maxRedirects = 10 } = options;
-    return new Promise((resolve) => {
-        const requestHeaders = {
-            'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
-            ...headers,
-        };
-        if (cookies) {
-            requestHeaders['Cookie'] = cookies;
+    const requestHeaders = {
+        'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36',
+        ...headers,
+    };
+    if (cookies) {
+        requestHeaders['Cookie'] = cookies;
+    }
+    const tempPath = `${destPath}.tmp`;
+    const cleanupTempFile = async () => {
+        try {
+            await fs.promises.rm(tempPath, { force: true });
         }
-        const tempPath = `${destPath}.tmp`;
-        let settled = false;
-        const finish = (result) => {
-            if (settled)
-                return;
-            settled = true;
-            resolve(result);
-        };
-        const cleanupTempFile = async () => {
-            try {
-                await fs.promises.rm(tempPath, { force: true });
-            }
-            catch {
-                // Ignore cleanup errors so the original failure is preserved.
-            }
-        };
-        void (async () => {
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), timeout);
-            try {
-                const response = await fetchWithNodeNetwork(url, {
-                    headers: requestHeaders,
-                    signal: controller.signal,
-                    redirect: 'manual',
-                });
-                clearTimeout(timer);
-                // Handle redirects before creating any file handles.
-                if (response.status >= 300 && response.status < 400) {
-                    const location = response.headers.get('location');
-                    if (location) {
-                        if (redirectCount >= maxRedirects) {
-                            finish({ success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` });
-                            return;
-                        }
-                        const redirectUrl = resolveRedirectUrl(url, location);
-                        const originalHost = new URL(url).hostname;
-                        const redirectHost = new URL(redirectUrl).hostname;
-                        const redirectOptions = originalHost === redirectHost
-                            ? options
-                            : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
-                        finish(await httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1));
-                        return;
-                    }
-                }
-                if (response.status !== 200) {
-                    finish({ success: false, size: 0, error: `HTTP ${response.status}` });
-                    return;
-                }
-                if (!response.body) {
-                    finish({ success: false, size: 0, error: 'Empty response body' });
-                    return;
-                }
-                const totalSize = parseInt(response.headers.get('content-length') || '0', 10);
-                let received = 0;
-                const progressStream = new Transform({
-                    transform(chunk, _encoding, callback) {
-                        received += chunk.length;
-                        if (onProgress)
-                            onProgress(received, totalSize);
-                        callback(null, chunk);
-                    },
-                });
-                try {
-                    await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
-                    await pipeline(Readable.fromWeb(response.body), progressStream, fs.createWriteStream(tempPath));
-                    await fs.promises.rename(tempPath, destPath);
-                    finish({ success: true, size: received });
-                }
-                catch (err) {
-                    await cleanupTempFile();
-                    finish({ success: false, size: 0, error: getErrorMessage(err) });
+        catch {
+            // Ignore cleanup errors so the original failure is preserved.
+        }
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetchWithNodeNetwork(url, {
+            headers: requestHeaders,
+            signal: controller.signal,
+            redirect: 'manual',
+        });
+        clearTimeout(timer);
+        // Handle redirects before creating any file handles.
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (location) {
+                if (redirectCount >= maxRedirects) {
+                    return { success: false, size: 0, error: `Too many redirects (> ${maxRedirects})` };
                 }
+                const redirectUrl = resolveRedirectUrl(url, location);
+                const originalHost = new URL(url).hostname;
+                const redirectHost = new URL(redirectUrl).hostname;
+                const redirectOptions = originalHost === redirectHost
+                    ? options
+                    : { ...options, cookies: undefined, headers: stripCookieHeaders(options.headers) };
+                return httpDownload(redirectUrl, destPath, redirectOptions, redirectCount + 1);
             }
-            catch (err) {
-                clearTimeout(timer);
-                await cleanupTempFile();
-                finish({ success: false, size: 0, error: err instanceof Error ? err.message : String(err) });
-            }
-        })();
-    });
+        }
+        if (response.status !== 200) {
+            return { success: false, size: 0, error: `HTTP ${response.status}` };
+        }
+        if (!response.body) {
+            return { success: false, size: 0, error: 'Empty response body' };
+        }
+        const totalSize = parseInt(response.headers.get('content-length') || '0', 10);
+        let received = 0;
+        const progressStream = new Transform({
+            transform(chunk, _encoding, callback) {
+                received += chunk.length;
+                if (onProgress)
+                    onProgress(received, totalSize);
+                callback(null, chunk);
+            },
+        });
+        try {
+            await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+            await pipeline(Readable.fromWeb(response.body), progressStream, fs.createWriteStream(tempPath));
+            await fs.promises.rename(tempPath, destPath);
+            return { success: true, size: received };
+        }
+        catch (err) {
+            await cleanupTempFile();
+            return { success: false, size: 0, error: getErrorMessage(err) };
+        }
+    }
+    catch (err) {
+        clearTimeout(timer);
+        await cleanupTempFile();
+        return { success: false, size: 0, error: err instanceof Error ? err.message : String(err) };
+    }
 }
 export function resolveRedirectUrl(currentUrl, location) {
     return new URL(location, currentUrl).toString();
@@ -172,7 +157,9 @@ export function exportCookiesToNetscape(cookies, filePath) {
         const includeSubdomains = 'TRUE';
         const cookiePath = cookie.path || '/';
         const secure = cookie.secure ? 'TRUE' : 'FALSE';
-        const expiry = Math.floor(Date.now() / 1000) + 86400 * 365; // 1 year from now
+        const expiry = typeof cookie.expirationDate === 'number' && cookie.expirationDate > 0
+            ? Math.floor(cookie.expirationDate)
+            : Math.floor(Date.now() / 1000) + 86400 * 365; // fallback: 1 year from now
         const safeName = cookie.name.replace(/[\t\n\r]/g, '');
         const safeValue = cookie.value.replace(/[\t\n\r]/g, '');
         lines.push(`${domain}\t${includeSubdomains}\t${cookiePath}\t${secure}\t${expiry}\t${safeName}\t${safeValue}`);

package/dist/src/errors.js

@@ -107,11 +107,13 @@ export function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
 /** Serialize an error cause chain into a readable string. */
-function serializeCause(cause) {
+function serializeCause(cause, depth = 0) {
+    if (depth > 10)
+        return '(cause chain truncated)';
     if (cause instanceof Error) {
         const parts = [cause.message];
         if (cause.cause)
-            parts.push(`  caused by: ${serializeCause(cause.cause)}`);
+            parts.push(`  caused by: ${serializeCause(cause.cause, depth + 1)}`);
         return parts.join('\n');
     }
     return String(cause);

package/dist/src/errors.test.js

@@ -93,4 +93,17 @@ describe('toEnvelope', () => {
         expect(envelope.error.code).toBe('UNKNOWN');
         expect(envelope.error.message).toBe('string error');
     });
+    it('serializes deep cause chains without stack overflow', () => {
+        // Build a 20-level deep cause chain — should truncate at depth 10
+        let deepErr = new Error('root');
+        for (let i = 0; i < 20; i++) {
+            deepErr = new Error(`level-${i}`, { cause: deepErr });
+        }
+        const topErr = new CommandExecutionError('top');
+        topErr.cause = deepErr;
+        const envelope = toEnvelope(topErr);
+        const causeStr = envelope.error.cause ?? '';
+        expect(causeStr).toContain('(cause chain truncated)');
+        expect(causeStr).not.toContain('root'); // root is beyond depth 10
+    });
 });

package/dist/src/execution.js

@@ -185,6 +185,9 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         throw new CommandExecutionError(`Pre-navigation to ${preNavUrl} failed: ${err instanceof Error ? err.message : err}`, 'Check that the site is reachable and the browser extension is running.');
                     }
                 }
+                // --live / OPENCLI_LIVE=1 keeps the automation window open after the
+                // command finishes, so agents (or humans) can inspect the page state.
+                const keepOpen = process.env.OPENCLI_LIVE === '1' || process.env.OPENCLI_LIVE === 'true';
                 try {
                     const result = await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
                         timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
@@ -192,7 +195,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     });
                     // Adapter commands are one-shot — close the automation window immediately
                     // instead of waiting for the 30s idle timeout.
-                    await page.closeWindow?.().catch(() => { });
+                    if (!keepOpen)
+                        await page.closeWindow?.().catch(() => { });
                     return result;
                 }
                 catch (err) {
@@ -206,7 +210,8 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     // Close the automation window on failure too — without this, the window
                     // lingers until the extension's idle timer fires (unreliable on Windows
                     // where MV3 service workers may be suspended before setTimeout triggers).
-                    await page.closeWindow?.().catch(() => { });
+                    if (!keepOpen)
+                        await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
             }, { workspace: `site:${cmd.site}`, cdpEndpoint });

package/dist/src/execution.test.js

@@ -60,6 +60,60 @@ describe('executeCommand — non-browser timeout', () => {
         expect(closeWindow).toHaveBeenCalledTimes(1);
         vi.restoreAllMocks();
     });
+    it('skips closeWindow when OPENCLI_LIVE=1 (success path)', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const prev = process.env.OPENCLI_LIVE;
+        process.env.OPENCLI_LIVE = '1';
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-live-success',
+                description: 'test closeWindow skipped with --live on success',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => [{ ok: true }],
+            });
+            await executeCommand(cmd, {});
+            expect(closeWindow).not.toHaveBeenCalled();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.OPENCLI_LIVE;
+            else
+                process.env.OPENCLI_LIVE = prev;
+            vi.restoreAllMocks();
+        }
+    });
+    it('skips closeWindow when OPENCLI_LIVE=1 (failure path)', async () => {
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = { closeWindow };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        const prev = process.env.OPENCLI_LIVE;
+        process.env.OPENCLI_LIVE = '1';
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-live-failure',
+                description: 'test closeWindow skipped with --live on failure',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => { throw new Error('adapter failure'); },
+            });
+            await expect(executeCommand(cmd, {})).rejects.toThrow('adapter failure');
+            expect(closeWindow).not.toHaveBeenCalled();
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.OPENCLI_LIVE;
+            else
+                process.env.OPENCLI_LIVE = prev;
+            vi.restoreAllMocks();
+        }
+    });
     it('does not re-run custom validation when args are already prepared', async () => {
         const validateArgs = vi.fn();
         const cmd = {

package/dist/src/launcher.d.ts

@@ -22,7 +22,7 @@ export declare function detectProcess(processName: string): boolean;
 /**
  * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
  */
-export declare function killProcess(processName: string): void;
+export declare function killProcess(processName: string): Promise<void>;
 /**
  * Discover the app installation path on macOS.
  * Uses osascript to resolve the app name to a POSIX path.

package/dist/src/launcher.js

@@ -52,7 +52,7 @@ export function detectProcess(processName) {
 /**
  * Kill a process by name. Sends SIGTERM first, then SIGKILL after grace period.
  */
-export function killProcess(processName) {
+export async function killProcess(processName) {
     if (process.platform === 'win32')
         return; // pkill not available on Windows
     try {
@@ -65,7 +65,7 @@ export function killProcess(processName) {
     while (Date.now() < deadline) {
         if (!detectProcess(processName))
             return;
-        execFileSync('sleep', ['0.2'], { stdio: 'pipe' });
+        await new Promise((r) => setTimeout(r, 200));
     }
     try {
         execFileSync('pkill', ['-9', '-x', processName], { stdio: 'pipe' });
@@ -190,7 +190,7 @@ export async function resolveElectronEndpoint(site) {
             throw new CommandExecutionError(`${label} needs to be restarted with CDP enabled.`, `Manually restart: kill the app and relaunch with --remote-debugging-port=${port}`);
         }
         process.stderr.write(`  Restarting ${label}...\n`);
-        killProcess(processName);
+        await killProcess(processName);
     }
     // Step 3: Discover path
     const appPath = discoverAppPath(label);

package/dist/src/main.js

@@ -26,6 +26,22 @@ const __dirname = path.dirname(__filename);
 // Use findPackageRoot so the path works both in dev (src/main.ts) and prod (dist/src/main.js).
 const BUILTIN_CLIS = path.join(findPackageRoot(__filename), 'clis');
 const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
+// ── Session lifecycle flags ──────────────────────────────────────────────
+// `--live` / `--focus` are top-level-ish toggles that tweak the automation
+// window's lifecycle. We strip them from argv before Commander runs so they
+// can be placed anywhere and work on any subcommand (adapter or browser).
+{
+    const liveIdx = process.argv.indexOf('--live');
+    if (liveIdx !== -1) {
+        process.env.OPENCLI_LIVE = '1';
+        process.argv.splice(liveIdx, 1);
+    }
+    const focusIdx = process.argv.indexOf('--focus');
+    if (focusIdx !== -1) {
+        process.env.OPENCLI_WINDOW_FOCUSED = '1';
+        process.argv.splice(focusIdx, 1);
+    }
+}
 // ── Ultra-fast path: lightweight commands bypass full discovery ──────────
 // These are high-frequency or trivial paths that must not pay the startup tax.
 const argv = process.argv.slice(2);

package/dist/src/output.js

@@ -74,7 +74,7 @@ function renderTable(data, opts) {
     console.log(table.toString());
     const footer = [];
     footer.push(`${rows.length} items`);
-    if (opts.elapsed)
+    if (opts.elapsed !== undefined)
         footer.push(`${opts.elapsed.toFixed(1)}s`);
     if (opts.source)
         footer.push(opts.source);

package/dist/src/output.test.js

@@ -30,6 +30,12 @@ describe('output TTY detection', () => {
         const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
         expect(JSON.parse(out)).toEqual([{ name: 'alice' }]);
     });
+    it('shows elapsed time when elapsed is 0', () => {
+        Object.defineProperty(process.stdout, 'isTTY', { value: true, writable: true });
+        render([{ name: 'alice' }], { fmt: 'table', columns: ['name'], elapsed: 0 });
+        const out = logSpy.mock.calls.map((c) => c[0]).join('\n');
+        expect(out).toContain('0.0s');
+    });
     it('explicit -f table overrides non-TTY auto-downgrade', () => {
         Object.defineProperty(process.stdout, 'isTTY', { value: false, writable: true });
         render([{ name: 'alice' }], { fmt: 'table', fmtExplicit: true, columns: ['name'] });

package/dist/src/types.d.ts

@@ -51,10 +51,25 @@ export interface IPage {
         url?: string;
     }): Promise<BrowserCookie[]>;
     snapshot(opts?: SnapshotOptions): Promise<any>;
-    click(ref: string): Promise<void>;
-    typeText(ref: string, text: string): Promise<void>;
+    click(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
+    typeText(ref: string, text: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<{
+        matches_n: number;
+        match_level: 'exact' | 'stable' | 'reidentified';
+    }>;
     pressKey(key: string): Promise<void>;
-    scrollTo(ref: string): Promise<any>;
+    scrollTo(ref: string, opts?: {
+        nth?: number;
+        firstOnMulti?: boolean;
+    }): Promise<any>;
     getFormState(): Promise<any>;
     wait(options: number | WaitOptions): Promise<void>;
     tabs(): Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "publishConfig": {
     "access": "public"
   },
@@ -74,18 +74,22 @@
     "url": "git+https://github.com/jackwener/opencli.git"
   },
   "dependencies": {
+    "@mozilla/readability": "^0.6.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
     "js-yaml": "^4.1.0",
     "turndown": "^7.2.2",
+    "turndown-plugin-gfm": "^1.0.2",
     "undici": "^8.0.2",
     "ws": "^8.18.0"
   },
   "devDependencies": {
+    "@types/jsdom": "^27.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.2",
     "@types/turndown": "^5.0.6",
     "@types/ws": "^8.5.13",
+    "jsdom": "^29.0.2",
     "tsx": "^4.19.3",
     "typescript": "^6.0.2",
     "vitepress": "^1.6.4",