@jackwener/opencli 1.6.6 → 1.6.7

package/dist/src/diagnostic.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Structured diagnostic output for AI-driven adapter repair.
+ *
+ * When OPENCLI_DIAGNOSTIC=1, failed commands emit a JSON RepairContext to stderr
+ * containing the error, adapter source, and browser state (DOM snapshot, network
+ * requests, console errors). AI Agents consume this to diagnose and fix adapters.
+ */
+import type { IPage } from './types.js';
+import type { InternalCliCommand } from './registry.js';
+export interface RepairContext {
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+        stack?: string;
+    };
+    adapter: {
+        site: string;
+        command: string;
+        sourcePath?: string;
+        source?: string;
+    };
+    page?: {
+        url: string;
+        snapshot: string;
+        networkRequests: unknown[];
+        consoleErrors: unknown[];
+    };
+    timestamp: string;
+}
+/** Whether diagnostic mode is enabled. */
+export declare function isDiagnosticEnabled(): boolean;
+/** Build a RepairContext from an error, command metadata, and optional page state. */
+export declare function buildRepairContext(err: unknown, cmd: InternalCliCommand, pageState?: RepairContext['page']): RepairContext;
+/** Collect full diagnostic context including page state. */
+export declare function collectDiagnostic(err: unknown, cmd: InternalCliCommand, page: IPage | null): Promise<RepairContext>;
+/** Emit diagnostic JSON to stderr. */
+export declare function emitDiagnostic(ctx: RepairContext): void;

package/dist/src/diagnostic.js

@@ -0,0 +1,71 @@
+/**
+ * Structured diagnostic output for AI-driven adapter repair.
+ *
+ * When OPENCLI_DIAGNOSTIC=1, failed commands emit a JSON RepairContext to stderr
+ * containing the error, adapter source, and browser state (DOM snapshot, network
+ * requests, console errors). AI Agents consume this to diagnose and fix adapters.
+ */
+import * as fs from 'node:fs';
+import { CliError, getErrorMessage } from './errors.js';
+import { fullName } from './registry.js';
+// ── Diagnostic collection ────────────────────────────────────────────────────
+/** Whether diagnostic mode is enabled. */
+export function isDiagnosticEnabled() {
+    return process.env.OPENCLI_DIAGNOSTIC === '1';
+}
+/** Safely collect page diagnostic state. Individual failures are swallowed. */
+async function collectPageState(page) {
+    try {
+        const [url, snapshot, networkRequests, consoleErrors] = await Promise.all([
+            page.getCurrentUrl?.().catch(() => null) ?? Promise.resolve(null),
+            page.snapshot().catch(() => '(snapshot unavailable)'),
+            page.networkRequests().catch(() => []),
+            page.consoleMessages('error').catch(() => []),
+        ]);
+        return { url: url ?? 'unknown', snapshot, networkRequests, consoleErrors };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read adapter source file content. */
+function readAdapterSource(modulePath) {
+    if (!modulePath)
+        return undefined;
+    try {
+        return fs.readFileSync(modulePath, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Build a RepairContext from an error, command metadata, and optional page state. */
+export function buildRepairContext(err, cmd, pageState) {
+    const isCliError = err instanceof CliError;
+    return {
+        error: {
+            code: isCliError ? err.code : 'UNKNOWN',
+            message: getErrorMessage(err),
+            hint: isCliError ? err.hint : undefined,
+            stack: err instanceof Error ? err.stack : undefined,
+        },
+        adapter: {
+            site: cmd.site,
+            command: fullName(cmd),
+            sourcePath: cmd._modulePath,
+            source: readAdapterSource(cmd._modulePath),
+        },
+        page: pageState,
+        timestamp: new Date().toISOString(),
+    };
+}
+/** Collect full diagnostic context including page state. */
+export async function collectDiagnostic(err, cmd, page) {
+    const pageState = page ? await collectPageState(page) : undefined;
+    return buildRepairContext(err, cmd, pageState);
+}
+/** Emit diagnostic JSON to stderr. */
+export function emitDiagnostic(ctx) {
+    const marker = '___OPENCLI_DIAGNOSTIC___';
+    process.stderr.write(`\n${marker}\n${JSON.stringify(ctx)}\n${marker}\n`);
+}

package/dist/src/diagnostic.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/diagnostic.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { buildRepairContext, isDiagnosticEnabled, emitDiagnostic } from './diagnostic.js';
+import { SelectorError, CommandExecutionError } from './errors.js';
+function makeCmd(overrides = {}) {
+    return {
+        site: 'test-site',
+        name: 'test-cmd',
+        description: 'test',
+        args: [],
+        ...overrides,
+    };
+}
+describe('isDiagnosticEnabled', () => {
+    const origEnv = process.env.OPENCLI_DIAGNOSTIC;
+    afterEach(() => {
+        if (origEnv === undefined)
+            delete process.env.OPENCLI_DIAGNOSTIC;
+        else
+            process.env.OPENCLI_DIAGNOSTIC = origEnv;
+    });
+    it('returns false when env not set', () => {
+        delete process.env.OPENCLI_DIAGNOSTIC;
+        expect(isDiagnosticEnabled()).toBe(false);
+    });
+    it('returns true when env is "1"', () => {
+        process.env.OPENCLI_DIAGNOSTIC = '1';
+        expect(isDiagnosticEnabled()).toBe(true);
+    });
+    it('returns false for other values', () => {
+        process.env.OPENCLI_DIAGNOSTIC = 'true';
+        expect(isDiagnosticEnabled()).toBe(false);
+    });
+});
+describe('buildRepairContext', () => {
+    it('captures CliError fields', () => {
+        const err = new SelectorError('.missing-element', 'Element removed');
+        const ctx = buildRepairContext(err, makeCmd());
+        expect(ctx.error.code).toBe('SELECTOR');
+        expect(ctx.error.message).toContain('.missing-element');
+        expect(ctx.error.hint).toBe('Element removed');
+        expect(ctx.error.stack).toBeDefined();
+        expect(ctx.adapter.site).toBe('test-site');
+        expect(ctx.adapter.command).toBe('test-site/test-cmd');
+        expect(ctx.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+    });
+    it('handles non-CliError errors', () => {
+        const err = new TypeError('Cannot read property "x" of undefined');
+        const ctx = buildRepairContext(err, makeCmd());
+        expect(ctx.error.code).toBe('UNKNOWN');
+        expect(ctx.error.message).toContain('Cannot read property');
+        expect(ctx.error.hint).toBeUndefined();
+    });
+    it('includes page state when provided', () => {
+        const pageState = {
+            url: 'https://example.com/page',
+            snapshot: '<div>...</div>',
+            networkRequests: [{ url: '/api/data', status: 200 }],
+            consoleErrors: ['Uncaught TypeError'],
+        };
+        const ctx = buildRepairContext(new CommandExecutionError('boom'), makeCmd(), pageState);
+        expect(ctx.page).toEqual(pageState);
+    });
+    it('omits page when not provided', () => {
+        const ctx = buildRepairContext(new Error('boom'), makeCmd());
+        expect(ctx.page).toBeUndefined();
+    });
+});
+describe('emitDiagnostic', () => {
+    it('writes delimited JSON to stderr', () => {
+        const writeSpy = vi.spyOn(process.stderr, 'write').mockReturnValue(true);
+        const ctx = buildRepairContext(new CommandExecutionError('test error'), makeCmd());
+        emitDiagnostic(ctx);
+        const output = writeSpy.mock.calls.map(c => c[0]).join('');
+        expect(output).toContain('___OPENCLI_DIAGNOSTIC___');
+        expect(output).toContain('"code":"COMMAND_EXEC"');
+        expect(output).toContain('"message":"test error"');
+        // Verify JSON is parseable between markers
+        const match = output.match(/___OPENCLI_DIAGNOSTIC___\n(.*)\n___OPENCLI_DIAGNOSTIC___/);
+        expect(match).toBeTruthy();
+        const parsed = JSON.parse(match[1]);
+        expect(parsed.error.code).toBe('COMMAND_EXEC');
+        writeSpy.mockRestore();
+    });
+});

package/dist/src/execution.js

@@ -13,6 +13,7 @@ import { Strategy, getRegistry, fullName } from './registry.js';
 import { pathToFileURL } from 'node:url';
 import { executePipeline } from './pipeline/index.js';
 import { AdapterLoadError, ArgumentError, BrowserConnectError, CommandExecutionError, getErrorMessage } from './errors.js';
+import { isDiagnosticEnabled, collectDiagnostic, emitDiagnostic } from './diagnostic.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';
 import { emitHook } from './hooks.js';
@@ -129,6 +130,7 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
     };
     await emitHook('onBeforeExecute', hookCtx);
     let result;
+    let diagnosticEmitted = false;
     try {
         if (shouldUseBrowserSession(cmd)) {
             const electron = isElectronApp(cmd.site);
@@ -176,10 +178,22 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
                             log.debug(`[pre-nav] Failed to navigate to ${preNavUrl}: ${err instanceof Error ? err.message : err}`);
                     }
                 }
-                return runWithTimeout(runCommand(cmd, page, kwargs, debug), {
-                    timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
-                    label: fullName(cmd),
-                });
+                try {
+                    return await runWithTimeout(runCommand(cmd, page, kwargs, debug), {
+                        timeout: cmd.timeoutSeconds ?? DEFAULT_BROWSER_COMMAND_TIMEOUT,
+                        label: fullName(cmd),
+                    });
+                }
+                catch (err) {
+                    // Collect diagnostic while page is still alive (before browserSession closes it).
+                    if (isDiagnosticEnabled()) {
+                        const internal = cmd;
+                        const ctx = await collectDiagnostic(err, internal, page);
+                        emitDiagnostic(ctx);
+                        diagnosticEmitted = true;
+                    }
+                    throw err;
+                }
             }, { workspace: `site:${cmd.site}`, cdpEndpoint });
         }
         else {
@@ -198,6 +212,13 @@ export async function executeCommand(cmd, rawKwargs, debug = false) {
         }
     }
     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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "publishConfig": {
     "access": "public"
   },

package/scripts/postinstall.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * postinstall script — automatically install shell completion files.
+ * postinstall script — install shell completion files and print setup instructions.
  *
  * Detects the user's default shell and writes the completion script to the
- * standard system completion directory so that tab-completion works immediately
- * after `npm install -g`.
+ * standard completion directory.  For zsh and bash, the script prints manual
+ * instructions instead of modifying rc files (~/.zshrc, ~/.bashrc) — this
+ * avoids breaking multi-line shell commands and other fragile rc structures.
+ * Fish completions work automatically without rc changes.
  *
  * Supported shells: bash, zsh, fish.
  *
@@ -13,7 +15,7 @@
  * the main source tree) so that it can run without a build step.
  */
 
-import { mkdirSync, writeFileSync, existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 
@@ -69,54 +71,6 @@ function ensureDir(dir) {
   }
 }
 
-/**
- * Ensure fpath contains the custom completions directory in .zshrc.
- *
- * Key detail: the fpath line MUST appear BEFORE the first `compinit` call,
- * otherwise compinit won't scan our completions directory.  This is critical
- * for oh-my-zsh users (source $ZSH/oh-my-zsh.sh calls compinit internally).
- */
-function ensureZshFpath(completionsDir, zshrcPath) {
-  const fpathLine = `fpath=(${completionsDir} $fpath)`;
-  const autoloadLine = `autoload -Uz compinit && compinit`;
-  const marker = '# opencli completion';
-
-  if (!existsSync(zshrcPath)) {
-    writeFileSync(zshrcPath, `${marker}\n${fpathLine}\n${autoloadLine}\n`, 'utf8');
-    return;
-  }
-
-  const content = readFileSync(zshrcPath, 'utf8');
-
-  // Already configured — nothing to do
-  if (content.includes(completionsDir)) {
-    return;
-  }
-
-  // Find the first line that triggers compinit (direct call or oh-my-zsh source)
-  const lines = content.split('\n');
-  let insertIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    // Skip comment-only lines
-    if (trimmed.startsWith('#')) continue;
-    if (/compinit/.test(trimmed) || /source\s+.*oh-my-zsh\.sh/.test(trimmed)) {
-      insertIdx = i;
-      break;
-    }
-  }
-
-  if (insertIdx !== -1) {
-    // Insert fpath BEFORE the compinit / oh-my-zsh source line
-    lines.splice(insertIdx, 0, marker, fpathLine);
-    writeFileSync(zshrcPath, lines.join('\n'), 'utf8');
-  } else {
-    // No compinit found — append fpath + compinit at the end
-    let addition = `\n${marker}\n${fpathLine}\n${autoloadLine}\n`;
-    appendFileSync(zshrcPath, addition, 'utf8');
-  }
-}
-
 // ── Main ───────────────────────────────────────────────────────────────────
 
 function main() {
@@ -147,35 +101,28 @@ function main() {
         ensureDir(completionsDir);
         writeFileSync(completionFile, ZSH_COMPLETION, 'utf8');
 
-        // Ensure fpath is set up in .zshrc
-        const zshrcPath = join(home, '.zshrc');
-        ensureZshFpath(completionsDir, zshrcPath);
-
         console.log(`✓ Zsh completion installed to ${completionFile}`);
-        console.log(`  Restart your shell or run: source ~/.zshrc`);
+        console.log('');
+        console.log('  \x1b[1mTo enable, add these lines to your ~/.zshrc:\x1b[0m');
+        console.log(`    fpath=(${completionsDir} $fpath)`);
+        console.log('    autoload -Uz compinit && compinit');
+        console.log('');
+        console.log('  If you already have compinit (oh-my-zsh, zinit, etc.), just add the fpath line \x1b[1mbefore\x1b[0m it.');
+        console.log('  Then restart your shell or run: \x1b[36mexec zsh\x1b[0m');
         break;
       }
       case 'bash': {
-        // Try system-level first, fall back to user-level
         const userCompDir = join(home, '.bash_completion.d');
         const completionFile = join(userCompDir, 'opencli');
         ensureDir(userCompDir);
         writeFileSync(completionFile, BASH_COMPLETION, 'utf8');
 
-        // Ensure .bashrc sources the completion directory
-        const bashrcPath = join(home, '.bashrc');
-        if (existsSync(bashrcPath)) {
-          const content = readFileSync(bashrcPath, 'utf8');
-          if (!content.includes('.bash_completion.d/opencli')) {
-            appendFileSync(bashrcPath,
-              `\n# opencli completion\n[ -f "${completionFile}" ] && source "${completionFile}"\n`,
-              'utf8'
-            );
-          }
-        }
-
         console.log(`✓ Bash completion installed to ${completionFile}`);
-        console.log(`  Restart your shell or run: source ~/.bashrc`);
+        console.log('');
+        console.log('  \x1b[1mTo enable, add this line to your ~/.bashrc:\x1b[0m');
+        console.log(`    [ -f "${completionFile}" ] && source "${completionFile}"`);
+        console.log('');
+        console.log('  Then restart your shell or run: \x1b[36msource ~/.bashrc\x1b[0m');
         break;
       }
       case 'fish': {