@jackwener/opencli 1.7.5 → 1.7.6

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/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/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.6",
   "publishConfig": {
     "access": "public"
   },