@jackwener/opencli 1.7.8 → 1.7.10

package/dist/src/doctor.test.js

@@ -23,15 +23,32 @@ describe('doctor report rendering', () => {
     });
     it('renders OK-style report when daemon and extension connected', () => {
         const text = strip(renderBrowserDoctorReport({
+            cliVersion: '1.7.9',
             daemonRunning: true,
+            daemonVersion: '1.7.9',
             extensionConnected: true,
             extensionVersion: '1.6.8',
             issues: [],
         }));
         expect(text).toContain('[OK] Daemon: running on port 19825');
+        expect(text).toContain('(v1.7.9)');
         expect(text).toContain('[OK] Extension: connected (v1.6.8)');
         expect(text).toContain('Everything looks good!');
     });
+    it('renders a warning when daemon version is stale', () => {
+        const text = strip(renderBrowserDoctorReport({
+            cliVersion: '1.7.9',
+            daemonRunning: true,
+            daemonVersion: '1.7.6',
+            daemonStale: true,
+            extensionConnected: true,
+            extensionVersion: '1.0.3',
+            issues: ['Stale daemon detected: daemon v1.7.6 != CLI v1.7.9.\n  Run: opencli daemon restart'],
+        }));
+        expect(text).toContain('[WARN] Daemon: running on port 19825 (v1.7.6, stale; CLI v1.7.9)');
+        expect(text).toContain('Run: opencli daemon restart');
+        expect(text).not.toContain('Everything looks good!');
+    });
     it('renders MISSING when daemon not running', () => {
         const text = strip(renderBrowserDoctorReport({
             daemonRunning: false,
@@ -78,6 +95,64 @@ describe('doctor report rendering', () => {
         }));
         expect(text).toContain('[SKIP] Connectivity: skipped (--no-live)');
     });
+    it('renders sessions with tab leases and no idle timer', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: true,
+            issues: [],
+            sessions: [
+                {
+                    workspace: 'bound:default',
+                    windowId: 2,
+                    preferredTabId: 42,
+                    ownership: 'borrowed',
+                    surface: 'borrowed-user-tab',
+                    tabCount: 1,
+                    idleMsRemaining: null,
+                },
+            ],
+        }));
+        expect(text).toContain('bound:default → tab 42, mode=borrowed, surface=borrowed-user-tab, tabs=1, idle=none');
+    });
+    it('renders connected profiles and groups sessions by profile', () => {
+        const text = strip(renderBrowserDoctorReport({
+            daemonRunning: true,
+            extensionConnected: false,
+            profiles: [
+                { contextId: 'work', extensionConnected: true, extensionVersion: '1.2.3', pending: 0 },
+                { contextId: 'personal', extensionConnected: true, extensionVersion: '1.2.3', pending: 0 },
+            ],
+            issues: [],
+            sessions: [
+                {
+                    contextId: 'work',
+                    workspace: 'bound:default',
+                    windowId: 2,
+                    preferredTabId: 42,
+                    ownership: 'borrowed',
+                    surface: 'borrowed-user-tab',
+                    tabCount: 1,
+                    idleMsRemaining: null,
+                },
+                {
+                    contextId: 'personal',
+                    workspace: 'site:foo',
+                    windowId: 1,
+                    preferredTabId: 10,
+                    ownership: 'owned',
+                    surface: 'dedicated-container',
+                    tabCount: 1,
+                    idleMsRemaining: 1000,
+                },
+            ],
+        }));
+        expect(text).toContain('Profiles:');
+        expect(text).toContain('work: connected v1.2.3');
+        expect(text).toContain('[profile: work]');
+        expect(text).toContain('[profile: personal]');
+        expect(text).toContain('bound:default → tab 42');
+        expect(text).toContain('site:foo → tab 10');
+    });
     it('renders unstable extension state when live connectivity and status disagree', () => {
         const text = strip(renderBrowserDoctorReport({
             daemonRunning: true,
@@ -142,16 +217,19 @@ describe('doctor report rendering', () => {
     });
     it('uses the fast default timeout for live connectivity checks', async () => {
         let timeoutSeen;
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
         mockConnect.mockImplementationOnce(async (opts) => {
             timeoutSeen = opts?.timeout;
             return {
                 evaluate: vi.fn().mockResolvedValue(2),
+                closeWindow,
             };
         });
         mockClose.mockResolvedValueOnce(undefined);
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'ready', status: { extensionConnected: true } });
         await runBrowserDoctor({ live: true });
         expect(timeoutSeen).toBe(8);
+        expect(closeWindow).toHaveBeenCalledTimes(1);
     });
     it('skips auto-start in no-live mode when daemon is already running', async () => {
         mockGetDaemonHealth.mockResolvedValueOnce({ state: 'no-extension', status: { extensionConnected: false } });
@@ -177,4 +255,43 @@ describe('doctor report rendering', () => {
             expect.stringContaining('did not report a version'),
         ]));
     });
+    it('reports an issue when daemon version differs from CLI version', async () => {
+        const status = {
+            state: 'ready',
+            status: {
+                daemonVersion: '1.7.6',
+                extensionConnected: true,
+                extensionVersion: '1.0.3',
+            },
+        };
+        mockGetDaemonHealth
+            .mockResolvedValueOnce(status)
+            .mockResolvedValueOnce(status);
+        const report = await runBrowserDoctor({ live: false, cliVersion: '1.7.9' });
+        expect(report.daemonStale).toBe(true);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Stale daemon detected: daemon v1.7.6 != CLI v1.7.9'),
+        ]));
+    });
+    it('reports profile-required when multiple profiles are connected without a selection', async () => {
+        const status = {
+            state: 'profile-required',
+            status: {
+                extensionConnected: false,
+                profileRequired: true,
+                profiles: [
+                    { contextId: 'work', extensionConnected: true, pending: 0 },
+                    { contextId: 'personal', extensionConnected: true, pending: 0 },
+                ],
+            },
+        };
+        mockGetDaemonHealth
+            .mockResolvedValueOnce(status)
+            .mockResolvedValueOnce(status);
+        const report = await runBrowserDoctor({ live: false });
+        expect(report.profiles).toHaveLength(2);
+        expect(report.issues).toEqual(expect.arrayContaining([
+            expect.stringContaining('Multiple Chrome profiles are connected'),
+        ]));
+    });
 });

package/dist/src/engine.test.js

@@ -137,6 +137,7 @@ describe('discoverPlugins', () => {
     const symlinkTargetDir = path.join(os.tmpdir(), '__test-plugin-symlink-target__');
     const symlinkPluginDir = path.join(PLUGINS_DIR, '__test-plugin-symlink__');
     const brokenSymlinkDir = path.join(PLUGINS_DIR, '__test-plugin-broken__');
+    const dirSymlinkType = process.platform === 'win32' ? 'junction' : 'dir';
     afterEach(async () => {
         try {
             await fs.promises.rm(testPluginDir, { recursive: true });
@@ -183,14 +184,14 @@ description: Test plugin greeting via symlink
 strategy: public
 browser: false
 `);
-        await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, 'dir');
+        await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, dirSymlinkType);
         await discoverPlugins();
         const cmd = getRegistry().get('__test-plugin-symlink__/hello');
         expect(cmd).toBeUndefined();
     });
     it('skips broken plugin symlinks without throwing', async () => {
         await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
-        await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, 'dir');
+        await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, dirSymlinkType);
         await expect(discoverPlugins()).resolves.not.toThrow();
         expect(getRegistry().get('__test-plugin-broken__/hello')).toBeUndefined();
     });
@@ -210,7 +211,7 @@ describe('executeCommand', () => {
             args: [
                 { name: 'note-id', required: true, help: 'Note ID' },
             ],
-            func: async (_page, kwargs) => [{ noteId: kwargs['note-id'] }],
+            func: async (kwargs) => [{ noteId: kwargs['note-id'] }],
         });
         const result = await executeCommand(cmd, { 'note-id': 'abc123' });
         expect(result).toEqual([{ noteId: 'abc123' }]);
@@ -222,7 +223,7 @@ describe('executeCommand', () => {
             description: 'test command with func',
             browser: false,
             strategy: Strategy.PUBLIC,
-            func: async (_page, kwargs) => {
+            func: async (kwargs) => {
                 return [{ title: kwargs.query ?? 'default' }];
             },
         });
@@ -260,7 +261,7 @@ describe('executeCommand', () => {
             name: 'debug-test',
             description: 'debug test',
             browser: false,
-            func: async (_page, _kwargs, debug) => {
+            func: async (_kwargs, debug) => {
                 receivedDebug = debug ?? false;
                 return [];
             },

package/dist/src/errors.d.ts

@@ -13,12 +13,13 @@
  *   1   Generic / unexpected error
  *   2   Argument / usage error          (ArgumentError)
  *  66   No input / empty result         (EmptyResultError)
- *  69   Service unavailable             (BrowserConnectError, AdapterLoadError)
+ *  69   Service unavailable             (BrowserConnectError, adapter load failures)
  *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
  *  77   Permission denied / auth needed (AuthRequiredError)
  *  78   Configuration error             (ConfigError)
  * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
  */
+import type { ObservationTraceReceipt } from './observation/events.js';
 export declare const EXIT_CODES: {
     readonly SUCCESS: 0;
     readonly GENERIC_ERROR: 1;
@@ -40,14 +41,13 @@ export declare class CliError extends Error {
     readonly exitCode: ExitCode;
     constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
 }
-export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
+export declare function attachTraceReceipt(err: unknown, receipt: ObservationTraceReceipt): void;
+export declare function getTraceReceipt(err: unknown): ObservationTraceReceipt | undefined;
+export type BrowserConnectKind = 'daemon-not-running' | 'extension-not-connected' | 'profile-required' | 'profile-disconnected' | 'command-failed' | 'unknown';
 export declare class BrowserConnectError extends CliError {
     readonly kind: BrowserConnectKind;
     constructor(message: string, hint?: string, kind?: BrowserConnectKind);
 }
-export declare class AdapterLoadError extends CliError {
-    constructor(message: string, hint?: string);
-}
 export declare class CommandExecutionError extends CliError {
     constructor(message: string, hint?: string);
 }
@@ -67,9 +67,8 @@ export declare class ArgumentError extends CliError {
 export declare class EmptyResultError extends CliError {
     constructor(command: string, hint?: string);
 }
-export declare class SelectorError extends CliError {
-    constructor(selector: string, hint?: string);
-}
+export declare function adapterLoadError(message: string, hint?: string): CliError;
+export declare function selectorError(selector: string, hint?: string): CliError;
 export declare class PluginError extends CliError {
     constructor(message: string, hint?: string);
 }
@@ -84,6 +83,13 @@ export interface ErrorEnvelope {
         stack?: string;
         cause?: string;
     };
+    trace?: {
+        traceId: string;
+        dir: string;
+        summaryPath: string;
+        receiptPath: string;
+        status: ObservationTraceReceipt['status'];
+    };
 }
 /** Extract a human-readable message from an unknown caught value. */
 export declare function getErrorMessage(error: unknown): string;

package/dist/src/errors.js

@@ -1,24 +1,3 @@
-/**
- * Unified error types for opencli.
- *
- * All errors thrown by the framework should extend CliError so that
- * the top-level handler in commanderAdapter.ts can render consistent,
- * helpful output with emoji-coded severity and actionable hints.
- *
- * ## Exit codes
- *
- * opencli follows Unix conventions (sysexits.h) for process exit codes:
- *
- *   0   Success
- *   1   Generic / unexpected error
- *   2   Argument / usage error          (ArgumentError)
- *  66   No input / empty result         (EmptyResultError)
- *  69   Service unavailable             (BrowserConnectError, AdapterLoadError)
- *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
- *  77   Permission denied / auth needed (AuthRequiredError)
- *  78   Configuration error             (ConfigError)
- * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
- */
 // ── Exit code table ──────────────────────────────────────────────────────────
 export const EXIT_CODES = {
     SUCCESS: 0,
@@ -47,6 +26,27 @@ export class CliError extends Error {
         this.exitCode = exitCode;
     }
 }
+const TRACE_RECEIPT_SYMBOL = Symbol.for('opencli.traceReceipt');
+export function attachTraceReceipt(err, receipt) {
+    if (!err || (typeof err !== 'object' && typeof err !== 'function'))
+        return;
+    try {
+        Object.defineProperty(err, TRACE_RECEIPT_SYMBOL, {
+            value: receipt,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    catch {
+        // Non-extensible thrown objects are rare; trace export should never mask the
+        // original adapter error just because metadata attachment failed.
+    }
+}
+export function getTraceReceipt(err) {
+    if (!err || (typeof err !== 'object' && typeof err !== 'function'))
+        return undefined;
+    return err[TRACE_RECEIPT_SYMBOL];
+}
 export class BrowserConnectError extends CliError {
     kind;
     constructor(message, hint, kind = 'unknown') {
@@ -54,11 +54,6 @@ export class BrowserConnectError extends CliError {
         this.kind = kind;
     }
 }
-export class AdapterLoadError extends CliError {
-    constructor(message, hint) {
-        super('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
-    }
-}
 export class CommandExecutionError extends CliError {
     constructor(message, hint) {
         super('COMMAND_EXEC', message, hint, EXIT_CODES.GENERIC_ERROR);
@@ -91,10 +86,11 @@ export class EmptyResultError extends CliError {
         super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in', EXIT_CODES.EMPTY_RESULT);
     }
 }
-export class SelectorError extends CliError {
-    constructor(selector, hint) {
-        super('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.', EXIT_CODES.GENERIC_ERROR);
-    }
+export function adapterLoadError(message, hint) {
+    return new CliError('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+}
+export function selectorError(selector, hint) {
+    return new CliError('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.', EXIT_CODES.GENERIC_ERROR);
 }
 export class PluginError extends CliError {
     constructor(message, hint) {
@@ -121,6 +117,14 @@ function serializeCause(cause, depth = 0) {
 /** Build an ErrorEnvelope from any caught value. */
 export function toEnvelope(err) {
     const cause = err instanceof Error && err.cause ? serializeCause(err.cause) : undefined;
+    const traceReceipt = getTraceReceipt(err);
+    const trace = traceReceipt ? {
+        traceId: traceReceipt.traceId,
+        dir: traceReceipt.traceDir,
+        summaryPath: traceReceipt.summaryPath,
+        receiptPath: traceReceipt.receiptPath,
+        status: traceReceipt.status,
+    } : undefined;
     if (err instanceof CliError) {
         return {
             ok: false,
@@ -131,6 +135,7 @@ export function toEnvelope(err) {
                 exitCode: err.exitCode,
                 ...(cause ? { cause } : {}),
             },
+            ...(trace ? { trace } : {}),
         };
     }
     const msg = getErrorMessage(err);
@@ -142,5 +147,6 @@ export function toEnvelope(err) {
             exitCode: EXIT_CODES.GENERIC_ERROR,
             ...(cause ? { cause } : {}),
         },
+        ...(trace ? { trace } : {}),
     };
 }

package/dist/src/errors.test.js

@@ -1,17 +1,17 @@
 import { describe, it, expect } from 'vitest';
-import { CliError, BrowserConnectError, AdapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, SelectorError, toEnvelope, } from './errors.js';
+import { CliError, BrowserConnectError, adapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, selectorError, toEnvelope, } from './errors.js';
 describe('Error type hierarchy', () => {
     it('all error types extend CliError', () => {
         const errors = [
             new BrowserConnectError('test'),
-            new AdapterLoadError('test'),
+            adapterLoadError('test'),
             new CommandExecutionError('test'),
             new ConfigError('test'),
             new AuthRequiredError('example.com'),
             new TimeoutError('test', 30),
             new ArgumentError('test'),
             new EmptyResultError('test/cmd'),
-            new SelectorError('.btn'),
+            selectorError('.btn'),
         ];
         for (const err of errors) {
             expect(err).toBeInstanceOf(CliError);
@@ -46,8 +46,8 @@ describe('Error type hierarchy', () => {
         expect(err.message).toBe('hackernews/top returned no data');
         expect(err.hint).toBeTruthy();
     });
-    it('SelectorError has default hint about page changes', () => {
-        const err = new SelectorError('.submit-btn');
+    it('selectorError has default hint about page changes', () => {
+        const err = selectorError('.submit-btn');
         expect(err.code).toBe('SELECTOR');
         expect(err.message).toContain('.submit-btn');
         expect(err.hint).toContain('report');

package/dist/src/execution.d.ts

@@ -10,8 +10,12 @@
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
 import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
+import { type ObservationExportResult } from './observation/index.js';
 export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
 export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean, opts?: {
     prepared?: boolean;
+    profile?: string;
+    trace?: string;
+    onTraceExport?: (trace: ObservationExportResult) => void;
 }): Promise<unknown>;
 export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;