@jackwener/opencli 1.6.5 → 1.6.7

package/dist/clis/yollomi/background.js

@@ -2,9 +2,9 @@
  * Yollomi AI background generator — POST /api/ai/ai-background-generator
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -22,7 +22,7 @@ cli({
     func: async (page, kwargs) => {
         const imageUrl = kwargs.image;
         const prompt = kwargs.prompt;
-        process.stderr.write(chalk.dim('Generating background...\n'));
+        log.status('Generating background...');
         const data = await yollomiPost(page, '/api/ai/ai-background-generator', {
             images: [imageUrl],
             prompt: prompt || undefined,

package/dist/clis/yollomi/edit.js

@@ -3,9 +3,9 @@
  * Matches frontend workspace-generator.tsx for qwen-image-edit model.
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -33,7 +33,7 @@ cli({
             body = { image: imageInput, prompt, go_fast: true, output_format: 'png' };
         }
         const apiPath = modelId === 'qwen-image-edit-plus' ? '/api/ai/qwen-image-edit-plus' : '/api/ai/qwen-image-edit';
-        process.stderr.write(chalk.dim(`Editing with ${modelId}...\n`));
+        log.status(`Editing with ${modelId}...`);
         const data = await yollomiPost(page, apiPath, body);
         const images = data.images || (data.image ? [data.image] : []);
         if (!images.length)
@@ -46,7 +46,7 @@ cli({
             const filename = `yollomi_edit_${Date.now()}.png`;
             const { path: fp, size } = await downloadOutput(url, kwargs.output, filename);
             if (credits !== undefined)
-                process.stderr.write(chalk.dim(`Credits remaining: ${credits}\n`));
+                log.status(`Credits remaining: ${credits}`);
             return [{ status: 'saved', file: path.relative('.', fp), size: fmtBytes(size), credits: credits ?? '-', url }];
         }
         catch {

package/dist/clis/yollomi/face-swap.js

@@ -3,9 +3,9 @@
  * Uses swap_image / input_image field names matching the frontend.
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -21,7 +21,7 @@ cli({
     ],
     columns: ['status', 'file', 'size', 'url'],
     func: async (page, kwargs) => {
-        process.stderr.write(chalk.dim('Swapping faces...\n'));
+        log.status('Swapping faces...');
         const data = await yollomiPost(page, '/api/ai/face-swap', {
             swap_image: kwargs.source,
             input_image: kwargs.target,

package/dist/clis/yollomi/generate.js

@@ -7,9 +7,9 @@
  *   POST /api/ai/flux-2-pro     { prompt, aspectRatio, imageUrl?, ... }
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes, MODEL_ROUTES } from './utils.js';
 function getDimensions(ratio) {
     const map = {
@@ -63,7 +63,7 @@ cli({
             if (kwargs.image)
                 body.imageUrl = kwargs.image;
         }
-        process.stderr.write(chalk.dim(`Generating with ${modelId}...\n`));
+        log.status(`Generating with ${modelId}...`);
         const data = await yollomiPost(page, apiPath, body);
         const images = data.images || (data.image ? [data.image] : []);
         if (!images.length)
@@ -94,7 +94,7 @@ cli({
             }
         }
         if (data.remainingCredits !== undefined)
-            process.stderr.write(chalk.dim(`Credits remaining: ${data.remainingCredits}\n`));
+            log.status(`Credits remaining: ${data.remainingCredits}`);
         return results;
     },
 });

package/dist/clis/yollomi/object-remover.js

@@ -2,9 +2,9 @@
  * Yollomi object remover — POST /api/ai/object-remover
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -20,7 +20,7 @@ cli({
     ],
     columns: ['status', 'file', 'size', 'url'],
     func: async (page, kwargs) => {
-        process.stderr.write(chalk.dim('Removing object...\n'));
+        log.status('Removing object...');
         const data = await yollomiPost(page, '/api/ai/object-remover', {
             image: kwargs.image,
             mask: kwargs.mask,

package/dist/clis/yollomi/remove-bg.js

@@ -2,9 +2,9 @@
  * Yollomi background removal — POST /api/ai/remove-bg (free, 0 credits)
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -19,7 +19,7 @@ cli({
     ],
     columns: ['status', 'file', 'size', 'url'],
     func: async (page, kwargs) => {
-        process.stderr.write(chalk.dim('Removing background...\n'));
+        log.status('Removing background...');
         const data = await yollomiPost(page, '/api/ai/remove-bg', { imageUrl: kwargs.image });
         const url = data.image || (data.images?.[0]);
         if (!url)

package/dist/clis/yollomi/restore.js

@@ -2,9 +2,9 @@
  * Yollomi photo restoration — POST /api/ai/photo-restoration
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -19,7 +19,7 @@ cli({
     ],
     columns: ['status', 'file', 'size', 'url'],
     func: async (page, kwargs) => {
-        process.stderr.write(chalk.dim('Restoring photo...\n'));
+        log.status('Restoring photo...');
         const data = await yollomiPost(page, '/api/ai/photo-restoration', { imageUrl: kwargs.image });
         const url = data.image || (data.images?.[0]);
         if (!url)

package/dist/clis/yollomi/try-on.js

@@ -2,9 +2,9 @@
  * Yollomi virtual try-on — POST /api/ai/virtual-try-on
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -21,7 +21,7 @@ cli({
     ],
     columns: ['status', 'file', 'size', 'url'],
     func: async (page, kwargs) => {
-        process.stderr.write(chalk.dim('Processing virtual try-on...\n'));
+        log.status('Processing virtual try-on...');
         const data = await yollomiPost(page, '/api/ai/virtual-try-on', {
             person_image: kwargs.person,
             cloth_image: kwargs.cloth,

package/dist/clis/yollomi/upload.js

@@ -6,9 +6,9 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, ensureOnYollomi, fmtBytes } from './utils.js';
 const MIME_MAP = {
     '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
@@ -42,7 +42,7 @@ cli({
             throw new CliError('FILE_TOO_LARGE', `File too large: ${fmtBytes(data.length)}`, `Max ${mime.startsWith('video/') ? '20MB' : '10MB'} (upload larger videos from a URL)`);
         const b64 = data.toString('base64');
         const fileName = path.basename(filePath);
-        process.stderr.write(chalk.dim(`Uploading ${fileName} (${fmtBytes(data.length)})...\n`));
+        log.status(`Uploading ${fileName} (${fmtBytes(data.length)})...`);
         await ensureOnYollomi(page);
         const result = await page.evaluate(`
       (async () => {
@@ -65,7 +65,7 @@ cli({
             throw new CliError('UPLOAD_ERROR', result?.data?.error || 'Upload failed', 'Make sure you are logged in to yollomi.com');
         }
         const url = result.data.url;
-        process.stderr.write(chalk.green(`Uploaded! Use this URL as input for other commands.\n`));
+        log.success('Uploaded! Use this URL as input for other commands.');
         return [{ status: 'uploaded', file: fileName, size: fmtBytes(data.length), url }];
     },
 });

package/dist/clis/yollomi/upscale.js

@@ -2,9 +2,9 @@
  * Yollomi image upscaling — POST /api/ai/image-upscaler
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -21,7 +21,7 @@ cli({
     columns: ['status', 'file', 'size', 'scale', 'url'],
     func: async (page, kwargs) => {
         const scale = parseInt(kwargs.scale, 10);
-        process.stderr.write(chalk.dim(`Upscaling ${scale}x...\n`));
+        log.status(`Upscaling ${scale}x...`);
         const data = await yollomiPost(page, '/api/ai/image-upscaler', {
             imageUrl: kwargs.image,
             scale,
@@ -43,7 +43,7 @@ cli({
             const filename = `yollomi_upscale_${scale}x_${Date.now()}${ext}`;
             const { path: fp, size } = await downloadOutput(url, kwargs.output, filename);
             if (data.remainingCredits !== undefined)
-                process.stderr.write(chalk.dim(`Credits remaining: ${data.remainingCredits}\n`));
+                log.status(`Credits remaining: ${data.remainingCredits}`);
             return [{ status: 'saved', file: path.relative('.', fp), size: fmtBytes(size), scale: `${scale}x`, url }];
         }
         catch {

package/dist/clis/yollomi/video.js

@@ -3,9 +3,9 @@
  * Matches the frontend video-generator.tsx request format exactly.
  */
 import * as path from 'node:path';
-import chalk from 'chalk';
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CliError } from '@jackwener/opencli/errors';
+import { log } from '@jackwener/opencli/logger';
 import { YOLLOMI_DOMAIN, yollomiPost, downloadOutput, fmtBytes } from './utils.js';
 cli({
     site: 'yollomi',
@@ -31,7 +31,7 @@ cli({
         if (kwargs.image)
             inputs.image = kwargs.image;
         const body = { modelId, prompt, inputs };
-        process.stderr.write(chalk.dim(`Generating video with ${modelId} (may take a while)...\n`));
+        log.status(`Generating video with ${modelId} (may take a while)...`);
         const data = await yollomiPost(page, '/api/ai/video', body);
         const videoUrl = data.video || '';
         if (!videoUrl)
@@ -46,7 +46,7 @@ cli({
             const filename = `yollomi_${modelId}_${Date.now()}.mp4`;
             const { path: fp, size } = await downloadOutput(videoUrl, outputDir, filename);
             if (credits !== undefined)
-                process.stderr.write(chalk.dim(`Credits remaining: ${credits}\n`));
+                log.status(`Credits remaining: ${credits}`);
             return [{ status: 'saved', file: path.relative('.', fp), size: fmtBytes(size), credits: credits ?? '-', url: videoUrl }];
         }
         catch {

package/dist/clis/yuanbao/ask.js

@@ -1,5 +1,5 @@
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import TurndownService from 'turndown';
+import { htmlToMarkdown } from '@jackwener/opencli/utils';
 import { CommandExecutionError, TimeoutError } from '@jackwener/opencli/errors';
 import { YUANBAO_DOMAIN, IS_VISIBLE_JS, authRequired, isOnYuanbao, ensureYuanbaoPage, hasLoginGate } from './shared.js';
 const YUANBAO_RESPONSE_POLL_INTERVAL_SECONDS = 2;
@@ -20,57 +20,40 @@ function normalizeBooleanFlag(value, fallback) {
     const normalized = String(value).trim().toLowerCase();
     return normalized === 'true' || normalized === '1' || normalized === 'yes' || normalized === 'on';
 }
-function createYuanbaoTurndown() {
-    const td = new TurndownService({
-        headingStyle: 'atx',
-        codeBlockStyle: 'fenced',
-        bulletListMarker: '-',
-    });
-    td.addRule('linebreak', {
-        filter: 'br',
-        replacement: () => '\n',
-    });
-    td.addRule('table', {
-        filter: 'table',
-        replacement: (content) => `\n\n${content}\n\n`,
-    });
-    td.addRule('tableSection', {
-        filter: ['thead', 'tbody', 'tfoot'],
-        replacement: (content) => content,
-    });
-    td.addRule('tableRow', {
-        filter: 'tr',
-        replacement: (content, node) => {
-            const element = node;
-            const cells = Array.from(element.children);
-            const isHeaderRow = element.parentElement?.tagName === 'THEAD'
-                || (cells.length > 0 && cells.every((cell) => cell.tagName === 'TH'));
-            const row = `${content}\n`;
-            if (!isHeaderRow)
-                return row;
-            const separator = `| ${cells.map(() => '---').join(' | ')} |\n`;
-            return `${row}${separator}`;
-        },
-    });
-    td.addRule('tableCell', {
-        filter: ['th', 'td'],
-        replacement: (content, node) => {
-            const element = node;
-            const index = element.parentElement ? Array.from(element.parentElement.children).indexOf(element) : 0;
-            const prefix = index === 0 ? '| ' : ' ';
-            return `${prefix}${content.trim()} |`;
-        },
-    });
-    return td;
-}
-const yuanbaoTurndown = createYuanbaoTurndown();
 export function convertYuanbaoHtmlToMarkdown(value) {
-    const markdown = yuanbaoTurndown.turndown(value || '');
-    return markdown
-        .replace(/\u00a0/g, ' ')
-        .replace(/\n{4,}/g, '\n\n\n')
-        .replace(/[ \t]+$/gm, '')
-        .trim();
+    return htmlToMarkdown(value, (td) => {
+        td.addRule('table', {
+            filter: 'table',
+            replacement: (content) => `\n\n${content}\n\n`,
+        });
+        td.addRule('tableSection', {
+            filter: ['thead', 'tbody', 'tfoot'],
+            replacement: (content) => content,
+        });
+        td.addRule('tableRow', {
+            filter: 'tr',
+            replacement: (content, node) => {
+                const element = node;
+                const cells = Array.from(element.children);
+                const isHeaderRow = element.parentElement?.tagName === 'THEAD'
+                    || (cells.length > 0 && cells.every((cell) => cell.tagName === 'TH'));
+                const row = `${content}\n`;
+                if (!isHeaderRow)
+                    return row;
+                const separator = `| ${cells.map(() => '---').join(' | ')} |\n`;
+                return `${row}${separator}`;
+            },
+        });
+        td.addRule('tableCell', {
+            filter: ['th', 'td'],
+            replacement: (content, node) => {
+                const element = node;
+                const index = element.parentElement ? Array.from(element.parentElement.children).indexOf(element) : 0;
+                const prefix = index === 0 ? '| ' : ' ';
+                return `${prefix}${content.trim()} |`;
+            },
+        });
+    });
 }
 export function sanitizeYuanbaoResponseText(value, promptText) {
     let sanitized = value

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/discovery.js

@@ -78,12 +78,10 @@ export async function ensureUserCliCompatShims(baseDir = USER_OPENCLI_DIR) {
         catch { /* doesn't exist */ }
         if (needsUpdate) {
             await fs.promises.mkdir(symlinkDir, { recursive: true });
-            // Use rm instead of unlink — handles both symlinks and stale directories
             try {
                 await fs.promises.rm(symlinkPath, { recursive: true, force: true });
             }
             catch { /* doesn't exist */ }
-            // Use 'junction' on Windows — doesn't require admin/Developer Mode privileges
             const symlinkType = process.platform === 'win32' ? 'junction' : 'dir';
             await fs.promises.symlink(opencliRoot, symlinkPath, symlinkType);
         }

package/dist/src/engine.test.js

@@ -82,6 +82,7 @@ cli({
             await fs.promises.writeFile(commandPath, `
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { CommandExecutionError } from '@jackwener/opencli/errors';
+import { htmlToMarkdown } from '@jackwener/opencli/utils';
 
 cli({
   site: 'legacy-site',
@@ -89,13 +90,13 @@ cli({
   description: 'hello command',
   strategy: Strategy.PUBLIC,
   browser: false,
-  func: async () => [{ ok: true, errorName: new CommandExecutionError('boom').name }],
+  func: async () => [{ ok: true, errorName: new CommandExecutionError('boom').name, markdown: htmlToMarkdown('<p>hello</p>') }],
 });
 `);
             await discoverClis(userClisDir);
             const cmd = getRegistry().get('legacy-site/hello');
             expect(cmd).toBeDefined();
-            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true, errorName: 'CommandExecutionError' }]);
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true, errorName: 'CommandExecutionError', markdown: 'hello' }]);
         }
         finally {
             await fs.promises.rm(tempOpencliRoot, { recursive: true, force: true });

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/dist/src/logger.d.ts

@@ -7,6 +7,10 @@
 export declare const log: {
     /** Informational message (always shown) */
     info(msg: string): void;
+    /** Lightweight status line for adapter progress updates */
+    status(msg: string): void;
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg: string): void;
     /** Warning (always shown) */
     warn(msg: string): void;
     /** Error (always shown) */

package/dist/src/logger.js

@@ -16,6 +16,14 @@ export const log = {
     info(msg) {
         process.stderr.write(`${chalk.blue('ℹ')}  ${msg}\n`);
     },
+    /** Lightweight status line for adapter progress updates */
+    status(msg) {
+        process.stderr.write(`${chalk.dim(msg)}\n`);
+    },
+    /** Positive completion/status line without the heavier info prefix */
+    success(msg) {
+        process.stderr.write(`${chalk.green(msg)}\n`);
+    },
     /** Warning (always shown) */
     warn(msg) {
         process.stderr.write(`${chalk.yellow('⚠')}  ${msg}\n`);

package/dist/src/package-exports.test.js

@@ -8,24 +8,41 @@
 import { describe, it, expect } from 'vitest';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { builtinModules } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
 const CLIS_DIR = path.join(ROOT, 'clis');
 /** Recursively collect all .ts files in a directory. */
-function collectTsFiles(dir) {
+function collectTsFiles(dir, opts) {
     const results = [];
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, entry.name);
         if (entry.isDirectory()) {
-            results.push(...collectTsFiles(full));
+            results.push(...collectTsFiles(full, opts));
         }
         else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+            if (opts?.excludeTests && (entry.name.endsWith('.test.ts') || entry.name === 'test-utils.ts'))
+                continue;
             results.push(full);
         }
     }
     return results;
 }
+const ALLOWED_BARE_IMPORTS = new Set([
+    '@jackwener/opencli',
+    ...builtinModules.flatMap((name) => name.startsWith('node:')
+        ? [name, name.slice(5)]
+        : [name, `node:${name}`]),
+]);
+function isAllowedImport(specifier) {
+    return specifier.startsWith('./')
+        || specifier.startsWith('../')
+        || specifier.startsWith('/')
+        || specifier.startsWith('@jackwener/opencli/')
+        || ALLOWED_BARE_IMPORTS.has(specifier);
+}
 /** Forbidden relative import patterns that should have been replaced.
  * Uses (?:\.\./)+ to catch any depth of ../ traversal.
  * Covers: import/export from, vi.mock(), vi.importActual(). */
@@ -37,6 +54,7 @@ const FORBIDDEN_PATTERNS = [
 ];
 describe('adapter imports use package exports', () => {
     const adapterFiles = collectTsFiles(CLIS_DIR);
+    const runtimeAdapterFiles = collectTsFiles(CLIS_DIR, { excludeTests: true });
     it('found adapter files to check', () => {
         expect(adapterFiles.length).toBeGreaterThan(100);
     });
@@ -54,6 +72,25 @@ describe('adapter imports use package exports', () => {
         }
         expect(violations).toEqual([]);
     });
+    it('non-test adapters only import node builtins, relative modules, or opencli public APIs', () => {
+        const violations = [];
+        for (const file of runtimeAdapterFiles) {
+            const source = fs.readFileSync(file, 'utf-8');
+            const module = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+            for (const stmt of module.statements) {
+                if (!ts.isImportDeclaration(stmt) && !ts.isExportDeclaration(stmt))
+                    continue;
+                const specifier = stmt.moduleSpecifier?.getText(module).slice(1, -1);
+                if (specifier && !isAllowedImport(specifier)) {
+                    violations.push({
+                        file: path.relative(ROOT, file),
+                        specifier,
+                    });
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
 });
 describe('package.json exports resolve to real files', () => {
     const pkgJson = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf-8'));

package/dist/src/utils.d.ts

@@ -1,6 +1,7 @@
 /**
  * Shared utility functions used across the codebase.
  */
+import TurndownService from 'turndown';
 /** Type guard: checks if a value is a non-null, non-array object. */
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /** Simple async concurrency limiter. */
@@ -9,3 +10,5 @@ export declare function mapConcurrent<T, R>(items: T[], limit: number, fn: (item
 export declare function sleep(ms: number): Promise<void>;
 /** Save a base64-encoded string to a file, creating parent directories as needed. */
 export declare function saveBase64ToFile(base64: string, filePath: string): Promise<void>;
+export declare function createMarkdownConverter(configure?: (td: TurndownService) => void): TurndownService;
+export declare function htmlToMarkdown(value: string, configure?: (td: TurndownService) => void): string;

package/dist/src/utils.js

@@ -3,6 +3,7 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import TurndownService from 'turndown';
 /** Type guard: checks if a value is a non-null, non-array object. */
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -31,3 +32,24 @@ export async function saveBase64ToFile(base64, filePath) {
     await fs.promises.mkdir(dir, { recursive: true });
     await fs.promises.writeFile(filePath, Buffer.from(base64, 'base64'));
 }
+export function createMarkdownConverter(configure) {
+    const td = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+    });
+    td.addRule('linebreak', {
+        filter: 'br',
+        replacement: () => '\n',
+    });
+    if (configure)
+        configure(td);
+    return td;
+}
+export function htmlToMarkdown(value, configure) {
+    return createMarkdownConverter(configure).turndown(value || '')
+        .replace(/\u00a0/g, ' ')
+        .replace(/\n{4,}/g, '\n\n\n')
+        .replace(/[ \t]+$/gm, '')
+        .trim();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.6.5",
+  "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': {