@jackwener/opencli 1.7.8 → 1.7.10

package/dist/src/execution.js

@@ -9,22 +9,32 @@
  * 5. Lazy-loading of TS modules from manifest
  * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
  */
-import { getRegistry, fullName } from './registry.js';
+import { getRegistry, fullName, } from './registry.js';
 import { pathToFileURL } from 'node:url';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import { executePipeline } from './pipeline/index.js';
-import { AdapterLoadError, ArgumentError, CommandExecutionError, getErrorMessage } from './errors.js';
-import { isDiagnosticEnabled, collectDiagnostic, emitDiagnostic } from './diagnostic.js';
+import { adapterLoadError, ArgumentError, CommandExecutionError, attachTraceReceipt, getErrorMessage } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
+import { resolveProfileContextId } from './browser/profile.js';
 import { emitHook } from './hooks.js';
+import { log } from './logger.js';
 import { isElectronApp } from './electron-apps.js';
 import { probeCDP, resolveElectronEndpoint } from './launcher.js';
+import { ObservationSession, exportObservationSession } from './observation/index.js';
+import { resolveAdapterSourcePath } from './adapter-source.js';
 const _loadedModules = new Map();
 /** Track mtime of loaded user adapter files for hot-reload in daemon mode. */
 const _moduleMtimes = new Map();
 const _userClisDir = `${os.homedir()}/.opencli/clis/`;
+function normalizeTraceMode(raw) {
+    if (raw === undefined || raw === null || raw === '' || raw === 'off')
+        return 'off';
+    if (raw === 'on' || raw === 'retain-on-failure')
+        return raw;
+    throw new ArgumentError(`--trace must be one of: off, on, retain-on-failure. Received: "${String(raw)}"`);
+}
 export function coerceAndValidateArgs(cmdArgs, kwargs) {
     const result = { ...kwargs };
     for (const argDef of cmdArgs) {
@@ -94,27 +104,32 @@ async function runCommand(cmd, page, kwargs, debug) {
                 catch { }
             }, (err) => {
                 _loadedModules.delete(modulePath);
-                throw new AdapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
+                throw adapterLoadError(`Failed to load adapter module ${modulePath}: ${getErrorMessage(err)}`, 'Check that the adapter file exists and has no syntax errors.');
             });
             _loadedModules.set(modulePath, loadPromise);
         }
         await _loadedModules.get(modulePath);
         const updated = getRegistry().get(fullName(cmd));
         if (updated?.func) {
-            if (!page && updated.browser !== false) {
-                throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
-            }
-            return updated.func(page, kwargs, debug);
+            return runCommandFunc(updated, page, kwargs, debug);
         }
         if (updated?.pipeline)
             return executePipeline(page, updated.pipeline, { args: kwargs, debug });
     }
     if (cmd.func)
-        return cmd.func(page, kwargs, debug);
+        return runCommandFunc(cmd, page, kwargs, debug);
     if (cmd.pipeline)
         return executePipeline(page, cmd.pipeline, { args: kwargs, debug });
     throw new CommandExecutionError(`Command ${fullName(cmd)} has no func or pipeline`, 'This is likely a bug in the adapter definition. Please report this issue.');
 }
+function runCommandFunc(cmd, page, kwargs, debug) {
+    if (cmd.browser === false)
+        return cmd.func(kwargs, debug);
+    if (!page) {
+        throw new CommandExecutionError(`Command ${fullName(cmd)} requires a browser session but none was provided`);
+    }
+    return cmd.func(page, kwargs, debug);
+}
 function resolvePreNav(cmd) {
     if (cmd.navigateBefore === false)
         return null;
@@ -142,6 +157,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             throw err;
         throw new ArgumentError(getErrorMessage(err));
     }
+    const traceMode = normalizeTraceMode(opts.trace);
     const hookCtx = {
         command: fullName(cmd),
         args: kwargs,
@@ -149,7 +165,6 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
     };
     await emitHook('onBeforeExecute', hookCtx);
     let result;
-    let diagnosticEmitted = false;
     try {
         if (shouldUseBrowserSession(cmd)) {
             const electron = isElectronApp(cmd.site);
@@ -170,9 +185,38 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
             }
             ensureRequiredEnv(cmd);
             const BrowserFactory = getBrowserFactory(cmd.site);
+            const contextId = resolveProfileContextId(opts.profile);
+            const internal = cmd;
             result = await browserSession(BrowserFactory, async (page) => {
+                const observation = traceMode === 'off'
+                    ? null
+                    : new ObservationSession({
+                        scope: {
+                            contextId,
+                            workspace: `site:${cmd.site}`,
+                            target: page.getActivePage?.(),
+                            site: cmd.site,
+                            command: fullName(cmd),
+                            adapterSourcePath: resolveAdapterSourcePath(internal),
+                        },
+                    });
+                if (observation) {
+                    observation.record({
+                        stream: 'action',
+                        name: 'command',
+                        phase: 'start',
+                        data: { args: kwargs },
+                    });
+                    await page.startNetworkCapture?.().catch(() => false);
+                }
                 const preNavUrl = resolvePreNav(cmd);
                 if (preNavUrl) {
+                    observation?.record({
+                        stream: 'action',
+                        name: 'pre_navigate',
+                        phase: 'start',
+                        data: { url: preNavUrl },
+                    });
                     // Navigate directly — the extension's handleNavigate already has a fast-path
                     // that skips navigation if the tab is already at the target URL.
                     // This avoids an extra exec round-trip (getCurrentUrl) on first command and
@@ -180,9 +224,33 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     // instead of about:blank.
                     try {
                         await page.goto(preNavUrl);
+                        observation?.record({
+                            stream: 'action',
+                            name: 'pre_navigate',
+                            phase: 'end',
+                            data: { url: preNavUrl },
+                        });
                     }
                     catch (err) {
-                        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.');
+                        observation?.record({
+                            stream: 'action',
+                            name: 'pre_navigate',
+                            phase: 'error',
+                            data: { url: preNavUrl, error: err instanceof Error ? err.message : String(err) },
+                        });
+                        const wrapped = 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.');
+                        if (observation && (traceMode === 'on' || traceMode === 'retain-on-failure')) {
+                            observation.record({
+                                stream: 'error',
+                                message: wrapped.message,
+                                stack: wrapped.stack,
+                                code: wrapped.code,
+                                hint: wrapped.hint,
+                            });
+                            await collectObservationEvidence(observation, page).catch(() => { });
+                            exportTraceArtifact(observation, 'failure', wrapped, opts.onTraceExport);
+                        }
+                        throw wrapped;
                     }
                 }
                 // --live / OPENCLI_LIVE=1 keeps the automation window open after the
@@ -193,6 +261,15 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
                         label: fullName(cmd),
                     });
+                    observation?.record({
+                        stream: 'action',
+                        name: 'command',
+                        phase: 'end',
+                    });
+                    if (observation && traceMode === 'on') {
+                        await collectObservationEvidence(observation, page).catch(() => { });
+                        exportTraceArtifact(observation, 'success', undefined, opts.onTraceExport);
+                    }
                     // Adapter commands are one-shot — close the automation window immediately
                     // instead of waiting for the 30s idle timeout.
                     if (!keepOpen)
@@ -200,12 +277,22 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                     return result;
                 }
                 catch (err) {
-                    // Collect diagnostic while page is still alive (before closing the window).
-                    if (isDiagnosticEnabled()) {
-                        const internal = cmd;
-                        const ctx = await collectDiagnostic(err, internal, page);
-                        emitDiagnostic(ctx);
-                        diagnosticEmitted = true;
+                    if (observation) {
+                        observation.record({
+                            stream: 'action',
+                            name: 'command',
+                            phase: 'error',
+                            data: { error: err instanceof Error ? err.message : String(err) },
+                        });
+                        observation.record({
+                            stream: 'error',
+                            message: err instanceof Error ? err.message : String(err),
+                            stack: err instanceof Error ? err.stack : undefined,
+                        });
+                        if (traceMode === 'on' || traceMode === 'retain-on-failure') {
+                            await collectObservationEvidence(observation, page).catch(() => { });
+                            exportTraceArtifact(observation, 'failure', err, opts.onTraceExport);
+                        }
                     }
                     // Close the automation window on failure too — without this, the window
                     // lingers until the extension's idle timer fires (unreliable on Windows
@@ -214,7 +301,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
                         await page.closeWindow?.().catch(() => { });
                     throw err;
                 }
-            }, { workspace: `site:${cmd.site}`, cdpEndpoint });
+            }, { workspace: `site:${cmd.site}`, cdpEndpoint, contextId });
         }
         else {
             // Non-browser commands: apply timeout only when explicitly configured.
@@ -232,13 +319,6 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
         }
     }
     catch (err) {
-        // Emit diagnostic if not already emitted (browser session emits with page state;
-        // this fallback covers non-browser commands and pre-session failures like BrowserConnectError).
-        if (isDiagnosticEnabled() && !diagnosticEmitted) {
-            const internal = cmd;
-            const ctx = await collectDiagnostic(err, internal, null);
-            emitDiagnostic(ctx);
-        }
         hookCtx.error = err;
         hookCtx.finishedAt = Date.now();
         await emitHook('onAfterExecute', hookCtx);
@@ -248,6 +328,74 @@ export async function executeCommand(cmd, rawKwargs, debug = false, opts = {}) {
     await emitHook('onAfterExecute', hookCtx, result);
     return result;
 }
+async function collectObservationEvidence(session, page) {
+    const target = page.getActivePage?.() ?? session.scope.target;
+    const [url, snapshot, networkEntries, consoleMessages, screenshot] = await Promise.all([
+        page.getCurrentUrl?.().catch(() => null) ?? Promise.resolve(null),
+        page.snapshot().catch(() => undefined),
+        page.readNetworkCapture?.().catch(() => []) ?? Promise.resolve([]),
+        page.consoleMessages('all').catch(() => []),
+        page.screenshot({ format: 'png' }).catch(() => undefined),
+    ]);
+    if (snapshot !== undefined || url !== undefined) {
+        session.record({ stream: 'state', url, target, snapshot, label: 'final' });
+    }
+    for (const entry of Array.isArray(networkEntries) ? networkEntries : []) {
+        const record = entry;
+        session.record({
+            stream: 'network',
+            url: String(record.url ?? ''),
+            method: typeof record.method === 'string' ? record.method : undefined,
+            status: typeof record.responseStatus === 'number' ? record.responseStatus : undefined,
+            contentType: typeof record.responseContentType === 'string' ? record.responseContentType : undefined,
+            size: typeof record.responseBodyFullSize === 'number' ? record.responseBodyFullSize : undefined,
+            requestHeaders: record.requestHeaders,
+            responseHeaders: record.responseHeaders,
+            requestBody: record.requestBodyPreview,
+            responseBody: record.responsePreview,
+            ts: typeof record.timestamp === 'number' ? record.timestamp : undefined,
+        });
+    }
+    for (const message of Array.isArray(consoleMessages) ? consoleMessages : []) {
+        if (message && typeof message === 'object') {
+            const record = message;
+            session.record({
+                stream: 'console',
+                level: String(record.type ?? record.level ?? 'log'),
+                text: String(record.text ?? record.message ?? ''),
+                ts: typeof record.timestamp === 'number' ? record.timestamp : undefined,
+            });
+        }
+        else {
+            session.record({ stream: 'console', level: 'log', text: String(message) });
+        }
+    }
+    if (typeof screenshot === 'string' && screenshot) {
+        session.record({ stream: 'screenshot', format: 'png', data: screenshot, label: 'final' });
+    }
+}
+function exportTraceArtifact(session, status, error, onTraceExport) {
+    try {
+        const trace = exportObservationSession(session, { error, status });
+        if (status === 'failure' && error !== undefined) {
+            attachTraceReceipt(error, trace.receipt);
+        }
+        else {
+            process.stderr.write(`OpenCLI trace artifact: ${trace.dir}\n`);
+        }
+        try {
+            onTraceExport?.(trace);
+        }
+        catch (err) {
+            log.warn(`[trace] Trace export callback failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return trace;
+    }
+    catch (err) {
+        log.warn(`[trace] Failed to export trace artifact: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+}
 export function prepareCommandArgs(cmd, rawKwargs) {
     const kwargs = coerceAndValidateArgs(cmd.args, rawKwargs);
     cmd.validateArgs?.(kwargs);

package/dist/src/execution.test.js

@@ -1,6 +1,9 @@
 import { describe, expect, it, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
 import { executeCommand, prepareCommandArgs } from './execution.js';
-import { TimeoutError } from './errors.js';
+import { TimeoutError, toEnvelope } from './errors.js';
 import { cli, Strategy } from './registry.js';
 import { withTimeoutMs } from './runtime.js';
 import * as runtime from './runtime.js';
@@ -130,4 +133,171 @@ describe('executeCommand — non-browser timeout', () => {
         await executeCommand(cmd, kwargs, false, { prepared: true });
         expect(validateArgs).toHaveBeenCalledTimes(1);
     });
+    it('exports a profile-scoped trace artifact on browser command failure when requested', async () => {
+        const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-exec-trace-'));
+        const prevConfigDir = process.env.OPENCLI_CONFIG_DIR;
+        process.env.OPENCLI_CONFIG_DIR = baseDir;
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            startNetworkCapture: vi.fn().mockResolvedValue(true),
+            readNetworkCapture: vi.fn().mockResolvedValue([
+                {
+                    url: 'https://api.example.com/data?token=secret',
+                    method: 'GET',
+                    responseStatus: 500,
+                    responseContentType: 'application/json',
+                    responsePreview: JSON.stringify({ password: 'secret', ok: false }),
+                    requestHeaders: { authorization: 'Bearer secret' },
+                    timestamp: Date.now(),
+                },
+            ]),
+            consoleMessages: vi.fn().mockResolvedValue([{ type: 'error', text: 'boom password=secret', timestamp: Date.now() }]),
+            snapshot: vi.fn().mockResolvedValue({ html: '<input type="password" value="secret">' }),
+            screenshot: vi.fn().mockResolvedValue(Buffer.from('png').toString('base64')),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://api.example.com/app'),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-trace-failure',
+                description: 'test trace export',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => { throw new Error('adapter failure'); },
+            });
+            const thrown = await executeCommand(cmd, {}, false, { trace: 'retain-on-failure' }).catch((err) => err);
+            expect(thrown).toBeInstanceOf(Error);
+            expect(thrown.message).toContain('adapter failure');
+            const tracesRoot = path.join(baseDir, 'profiles', 'default', 'traces');
+            const traceId = fs.readdirSync(tracesRoot)[0];
+            const traceDir = path.join(tracesRoot, traceId);
+            expect(fs.existsSync(path.join(traceDir, 'trace.jsonl'))).toBe(true);
+            expect(fs.existsSync(path.join(traceDir, 'receipt.json'))).toBe(true);
+            const trace = fs.readFileSync(path.join(traceDir, 'trace.jsonl'), 'utf-8');
+            expect(trace).toContain('token=[REDACTED]');
+            expect(trace).toContain('"authorization":"[REDACTED]"');
+            expect(trace).not.toContain('password=secret');
+            expect(stderrSpy.mock.calls.flat().join('\n')).not.toContain('___OPENCLI_TRACE___');
+            expect(toEnvelope(thrown).trace).toMatchObject({
+                traceId,
+                dir: traceDir,
+                summaryPath: path.join(traceDir, 'summary.md'),
+                receiptPath: path.join(traceDir, 'receipt.json'),
+                status: 'failure',
+            });
+            expect(closeWindow).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            if (prevConfigDir === undefined)
+                delete process.env.OPENCLI_CONFIG_DIR;
+            else
+                process.env.OPENCLI_CONFIG_DIR = prevConfigDir;
+            stderrSpy.mockRestore();
+            fs.rmSync(baseDir, { recursive: true, force: true });
+            vi.restoreAllMocks();
+        }
+    });
+    it('exports a trace receipt on browser command success when trace is on', async () => {
+        const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-exec-trace-success-'));
+        const prevConfigDir = process.env.OPENCLI_CONFIG_DIR;
+        process.env.OPENCLI_CONFIG_DIR = baseDir;
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const onTraceExport = vi.fn();
+        const closeWindow = vi.fn().mockResolvedValue(undefined);
+        const mockPage = {
+            closeWindow,
+            startNetworkCapture: vi.fn().mockResolvedValue(true),
+            readNetworkCapture: vi.fn().mockResolvedValue([]),
+            consoleMessages: vi.fn().mockResolvedValue([]),
+            snapshot: vi.fn().mockResolvedValue('snapshot'),
+            screenshot: vi.fn().mockResolvedValue(Buffer.from('png').toString('base64')),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://example.com'),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-trace-success',
+                description: 'test trace export on success',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => [{ ok: true }],
+            });
+            await expect(executeCommand(cmd, {}, false, { trace: 'on', onTraceExport })).resolves.toEqual([{ ok: true }]);
+            const stderr = stderrSpy.mock.calls.flat().join('\n');
+            expect(stderr).toContain('OpenCLI trace artifact:');
+            const tracesRoot = path.join(baseDir, 'profiles', 'default', 'traces');
+            const traceId = fs.readdirSync(tracesRoot)[0];
+            const receipt = JSON.parse(fs.readFileSync(path.join(tracesRoot, traceId, 'receipt.json'), 'utf-8'));
+            expect(receipt.status).toBe('success');
+            expect(receipt.traceDir).toContain(path.join(baseDir, 'profiles', 'default', 'traces'));
+            expect(receipt.scope).toMatchObject({
+                site: 'test-execution',
+                command: 'test-execution/browser-trace-success',
+            });
+            expect(receipt.error).toBeUndefined();
+            expect(onTraceExport).toHaveBeenCalledWith(expect.objectContaining({
+                traceId,
+                receipt: expect.objectContaining({ status: 'success' }),
+            }));
+            expect(closeWindow).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            if (prevConfigDir === undefined)
+                delete process.env.OPENCLI_CONFIG_DIR;
+            else
+                process.env.OPENCLI_CONFIG_DIR = prevConfigDir;
+            stderrSpy.mockRestore();
+            fs.rmSync(baseDir, { recursive: true, force: true });
+            vi.restoreAllMocks();
+        }
+    });
+    it('keeps the original adapter error when trace export fails', async () => {
+        const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-exec-trace-fail-'));
+        const blockedPath = path.join(baseDir, 'not-a-dir');
+        fs.writeFileSync(blockedPath, 'file');
+        const prevConfigDir = process.env.OPENCLI_CONFIG_DIR;
+        process.env.OPENCLI_CONFIG_DIR = blockedPath;
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const mockPage = {
+            closeWindow: vi.fn().mockResolvedValue(undefined),
+            startNetworkCapture: vi.fn().mockResolvedValue(true),
+            readNetworkCapture: vi.fn().mockResolvedValue([]),
+            consoleMessages: vi.fn().mockResolvedValue([]),
+            snapshot: vi.fn().mockResolvedValue('snapshot'),
+            screenshot: vi.fn().mockResolvedValue(Buffer.from('png').toString('base64')),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://example.com'),
+            getActivePage: vi.fn().mockReturnValue('tab-1'),
+        };
+        vi.spyOn(capRouting, 'shouldUseBrowserSession').mockReturnValue(true);
+        vi.spyOn(runtime, 'browserSession').mockImplementation(async (_Factory, fn) => fn(mockPage));
+        try {
+            const cmd = cli({
+                site: 'test-execution',
+                name: 'browser-trace-export-fails',
+                description: 'test trace export failure handling',
+                browser: true,
+                strategy: Strategy.PUBLIC,
+                func: async () => { throw new Error('adapter failure'); },
+            });
+            await expect(executeCommand(cmd, {}, false, { trace: 'retain-on-failure' })).rejects.toThrow('adapter failure');
+            expect(stderrSpy.mock.calls.flat().join('\n')).toContain('[trace] Failed to export trace artifact');
+        }
+        finally {
+            if (prevConfigDir === undefined)
+                delete process.env.OPENCLI_CONFIG_DIR;
+            else
+                process.env.OPENCLI_CONFIG_DIR = prevConfigDir;
+            stderrSpy.mockRestore();
+            fs.rmSync(baseDir, { recursive: true, force: true });
+            vi.restoreAllMocks();
+        }
+    });
 });

package/dist/src/main.js

@@ -20,6 +20,7 @@ import { getCompletionsFromManifest, hasAllManifests, printCompletionScriptFast
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 import { PKG_VERSION } from './version.js';
 import { EXIT_CODES } from './errors.js';
+import { isSupportedNodeVersion, MIN_SUPPORTED_NODE_MAJOR } from './runtime-detect.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // Adapters are JS-first and live at <package-root>/clis/.
@@ -45,6 +46,15 @@ const USER_CLIS = path.join(os.homedir(), '.opencli', 'clis');
 // ── 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);
+if (typeof globalThis.Bun === 'undefined' && !isSupportedNodeVersion(process.version)) {
+    process.stderr.write([
+        `OpenCLI requires Node.js >= ${MIN_SUPPORTED_NODE_MAJOR}.0.0.`,
+        `Current runtime: ${process.version}`,
+        'Upgrade Node.js, then retry the same command.',
+        '',
+    ].join('\n'));
+    process.exit(EXIT_CODES.CONFIG_ERROR);
+}
 // Fast path: --version (only when it's the top-level intent, not passed to a subcommand)
 // e.g. `opencli --version` or `opencli -V`, but NOT `opencli gh --version`
 if (argv[0] === '--version' || argv[0] === '-V') {

package/dist/src/observation/artifact.d.ts

@@ -0,0 +1,16 @@
+import type { ObservationExportResult, ObservationExportStatus, ObservationTraceReceipt } from './events.js';
+import { ObservationSession } from './session.js';
+import { type TraceRetentionPolicyInput } from './retention.js';
+export interface ExportObservationOptions {
+    baseDir?: string;
+    error?: unknown;
+    status?: ObservationExportStatus;
+    retentionPolicy?: TraceRetentionPolicyInput;
+}
+export declare function getTraceDirectory(contextId: string | undefined, traceId: string, baseDir?: string): string;
+export declare function exportObservationSession(session: ObservationSession, opts?: ExportObservationOptions): ObservationExportResult;
+export declare function buildTraceReceipt(result: Pick<ObservationExportResult, 'traceId' | 'dir' | 'summaryPath' | 'receiptPath'>, status: ObservationExportStatus, error?: unknown, opts?: {
+    createdAt?: string;
+    scope?: ObservationSession['scope'];
+    retentionPolicy?: TraceRetentionPolicyInput;
+}): ObservationTraceReceipt;