@iflow-mcp/jakeliume-webpeel 0.22.0

package/dist/cli/commands/monitor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Monitor command: content change detection for URLs
+ *
+ * Usage:
+ *   webpeel monitor <url>                    - Fetch & snapshot (or diff if prev exists)
+ *   webpeel monitor <url> --interval 300     - Watch mode: re-check every 5 minutes
+ *   webpeel monitor <url> --json             - JSON output for automation
+ *   webpeel monitor <url> --render           - Use browser rendering
+ *   webpeel monitor <url> --selector <css>   - Monitor specific section only
+ */
+import type { Command } from 'commander';
+export declare function registerMonitorCommands(program: Command): void;

package/dist/cli/commands/monitor.js

@@ -0,0 +1,197 @@
+/**
+ * Monitor command: content change detection for URLs
+ *
+ * Usage:
+ *   webpeel monitor <url>                    - Fetch & snapshot (or diff if prev exists)
+ *   webpeel monitor <url> --interval 300     - Watch mode: re-check every 5 minutes
+ *   webpeel monitor <url> --json             - JSON output for automation
+ *   webpeel monitor <url> --render           - Use browser rendering
+ *   webpeel monitor <url> --selector <css>   - Monitor specific section only
+ */
+import { createHash } from 'crypto';
+import ora from 'ora';
+import { peel, cleanup } from '../../index.js';
+import { trackChange, getSnapshot } from '../../core/change-tracking.js';
+// ─── helpers ─────────────────────────────────────────────────────────────────
+function fingerprint(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+function formatTimestamp(iso) {
+    return new Date(iso).toLocaleString();
+}
+/** Run a single monitor check. Returns exit code (0 = ok, 1 = error). */
+async function runMonitorCheck(url, options) {
+    const spinner = options.silent || options.json ? null : ora(`Checking ${url}...`).start();
+    try {
+        const peelOptions = {
+            render: options.render || false,
+            selector: options.selector,
+            format: 'markdown',
+            timeout: options.timeout,
+            raw: false,
+        };
+        const result = await peel(url, peelOptions);
+        const content = result.content ?? '';
+        const fp = fingerprint(content);
+        if (spinner)
+            spinner.succeed(`Fetched in ${result.elapsed ?? 0}ms`);
+        const changeResult = await trackChange(url, content, fp);
+        if (options.json) {
+            const out = {
+                success: true,
+                url,
+                changeStatus: changeResult.changeStatus,
+                previousScrapeAt: changeResult.previousScrapeAt,
+                checkedAt: new Date().toISOString(),
+            };
+            if (changeResult.diff) {
+                out.diff = {
+                    additions: changeResult.diff.additions,
+                    deletions: changeResult.diff.deletions,
+                    text: changeResult.diff.text,
+                };
+            }
+            process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+            return { exitCode: 0, changed: changeResult.changeStatus === 'changed' };
+        }
+        // Human-readable output
+        switch (changeResult.changeStatus) {
+            case 'new': {
+                console.log(`📸 Baseline snapshot saved for ${url}`);
+                break;
+            }
+            case 'same': {
+                const since = changeResult.previousScrapeAt
+                    ? formatTimestamp(changeResult.previousScrapeAt)
+                    : 'last check';
+                console.log(`✅ No changes detected since ${since}`);
+                break;
+            }
+            case 'changed': {
+                const since = changeResult.previousScrapeAt
+                    ? formatTimestamp(changeResult.previousScrapeAt)
+                    : 'last check';
+                console.log(`\n🔔 Changes detected since ${since}:`);
+                console.log('');
+                if (changeResult.diff) {
+                    const { additions, deletions, text } = changeResult.diff;
+                    // Print unified diff with color
+                    if (text) {
+                        for (const line of text.split('\n')) {
+                            if (line.startsWith('+')) {
+                                process.stdout.write(`\x1b[32m${line}\x1b[0m\n`);
+                            }
+                            else if (line.startsWith('-')) {
+                                process.stdout.write(`\x1b[31m${line}\x1b[0m\n`);
+                            }
+                            else if (line.startsWith('@')) {
+                                process.stdout.write(`\x1b[36m${line}\x1b[0m\n`);
+                            }
+                            else {
+                                process.stdout.write(`${line}\n`);
+                            }
+                        }
+                    }
+                    console.log('');
+                    console.log(`📊 Summary: \x1b[32m+${additions} lines added\x1b[0m, \x1b[31m-${deletions} lines removed\x1b[0m`);
+                }
+                break;
+            }
+        }
+        return { exitCode: 0, changed: changeResult.changeStatus === 'changed' };
+    }
+    catch (error) {
+        if (spinner)
+            spinner.fail('Monitor check failed');
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        if (options.json) {
+            process.stdout.write(JSON.stringify({ success: false, url, error: msg }) + '\n');
+        }
+        else {
+            console.error(`\nError: ${msg}`);
+        }
+        return { exitCode: 1, changed: false };
+    }
+}
+// ─── registerMonitorCommands ──────────────────────────────────────────────────
+export function registerMonitorCommands(program) {
+    program
+        .command('monitor <url>')
+        .description('Monitor a URL for content changes (saves snapshots, shows diffs)')
+        .option('-r, --render', 'Use headless browser (for JS-heavy sites)')
+        .option('--selector <css>', 'CSS selector — only monitor this section of the page')
+        .option('-i, --interval <seconds>', 'Watch mode: re-check every N seconds', parseInt)
+        .option('--json', 'Output as JSON (for automation/scripting)')
+        .option('-s, --silent', 'Silent mode (no spinner)')
+        .option('-t, --timeout <ms>', 'Request timeout (ms)', (v) => parseInt(v, 10), 30000)
+        .addHelpText('after', `
+Examples:
+  webpeel monitor https://example.com/pricing        # First run: save baseline
+  webpeel monitor https://example.com/pricing        # Second run: show diff
+  webpeel monitor https://example.com/pricing --interval 300   # Watch every 5 min
+  webpeel monitor https://example.com/pricing --render         # JS-rendered page
+  webpeel monitor https://example.com/pricing --json           # JSON output
+  webpeel monitor https://example.com/pricing --selector .price # Monitor prices only
+    `)
+        .action(async (url, options) => {
+        // Validate URL
+        try {
+            const parsed = new URL(url);
+            if (!['http:', 'https:'].includes(parsed.protocol)) {
+                console.error('Error: Only HTTP and HTTPS protocols are allowed');
+                process.exit(1);
+            }
+        }
+        catch {
+            console.error(`Error: Invalid URL format: ${url}`);
+            process.exit(1);
+        }
+        const checkOptions = {
+            json: options.json || false,
+            render: options.render || false,
+            selector: options.selector,
+            silent: options.silent || false,
+            timeout: options.timeout,
+        };
+        const intervalSec = options.interval;
+        if (!intervalSec) {
+            // Single run
+            const { exitCode } = await runMonitorCheck(url, checkOptions);
+            await cleanup();
+            process.exit(exitCode);
+        }
+        else {
+            // Watch mode
+            if (intervalSec < 5) {
+                console.error('Error: --interval must be at least 5 seconds');
+                process.exit(1);
+            }
+            if (!options.json && !options.silent) {
+                const prev = await getSnapshot(url);
+                const baselineNote = prev
+                    ? `(baseline exists from ${formatTimestamp(new Date(prev.timestamp).toISOString())})`
+                    : '(no baseline yet — first run will save it)';
+                console.log(`👁  Watching ${url} every ${intervalSec}s ${baselineNote}`);
+                console.log('Press Ctrl+C to stop.\n');
+            }
+            // Initial check immediately
+            await runMonitorCheck(url, checkOptions);
+            // Then loop
+            const loop = setInterval(async () => {
+                if (!options.json && !options.silent) {
+                    console.log(`\n⏰ ${new Date().toLocaleTimeString()} — checking...`);
+                }
+                await runMonitorCheck(url, checkOptions);
+            }, intervalSec * 1000);
+            // Graceful shutdown
+            process.on('SIGINT', async () => {
+                clearInterval(loop);
+                if (!options.json && !options.silent) {
+                    console.log('\n👋 Stopped monitoring.');
+                }
+                await cleanup();
+                process.exit(0);
+            });
+        }
+    });
+}

package/dist/cli/commands/observe.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Observe command: structured page observation for AI agents
+ *
+ * Usage:
+ *   webpeel observe <url>                  - List all interactive elements
+ *   webpeel observe <url> --json           - JSON output for agents
+ *   webpeel observe <url> --screenshot     - Include screenshot
+ *   webpeel observe <url> --selector main  - Scope to a section
+ *   webpeel observe <url> --viewport mobile - Mobile viewport
+ */
+import type { Command } from 'commander';
+export declare function registerObserveCommand(program: Command): void;

package/dist/cli/commands/observe.js

@@ -0,0 +1,158 @@
+/**
+ * Observe command: structured page observation for AI agents
+ *
+ * Usage:
+ *   webpeel observe <url>                  - List all interactive elements
+ *   webpeel observe <url> --json           - JSON output for agents
+ *   webpeel observe <url> --screenshot     - Include screenshot
+ *   webpeel observe <url> --selector main  - Scope to a section
+ *   webpeel observe <url> --viewport mobile - Mobile viewport
+ */
+import ora from 'ora';
+import { writeFileSync } from 'fs';
+import { cleanup } from '../../index.js';
+import { writeStdout } from '../utils.js';
+export function registerObserveCommand(program) {
+    program
+        .command('observe <url>')
+        .alias('obs')
+        .description('Observe a page — list interactive elements (links, buttons, inputs, forms) for agent use')
+        .option('--json', 'Output as JSON (default for piped output)')
+        .option('-s, --silent', 'Silent mode (no spinner)')
+        .option('--selector <css>', 'CSS selector to scope observation')
+        .option('--viewport <v>', 'Viewport: desktop (default), mobile, tablet, or WxH', 'desktop')
+        .option('--screenshot', 'Include a screenshot')
+        .option('--screenshot-full-page', 'Full-page screenshot')
+        .option('--screenshot-output <path>', 'Save screenshot to file instead of base64 in JSON')
+        .option('--max-elements <n>', 'Max elements per category (default: 50)', (v) => parseInt(v, 10), 50)
+        .option('-t, --timeout <ms>', 'Request timeout in ms', (v) => parseInt(v, 10), 30000)
+        .option('--stealth', 'Stealth mode for bot-protected sites')
+        .addHelpText('after', `
+Examples:
+  webpeel observe https://news.ycombinator.com             # See all interactive elements
+  webpeel observe https://github.com --json                # JSON for agent consumption
+  webpeel observe https://amazon.com/dp/... --selector main  # Scope to main content
+  webpeel observe https://example.com --viewport mobile    # Mobile viewport
+  webpeel observe https://example.com --screenshot -o snap.png  # With screenshot
+    `)
+        .action(async (url, options) => {
+        // Validate URL
+        try {
+            const parsed = new URL(url);
+            if (!['http:', 'https:'].includes(parsed.protocol)) {
+                console.error('Error: Only HTTP and HTTPS protocols are allowed');
+                process.exit(1);
+            }
+        }
+        catch {
+            console.error(`Error: Invalid URL format: ${url}`);
+            process.exit(1);
+        }
+        const spinner = options.silent ? null : ora('Observing page...').start();
+        try {
+            const { observe } = await import('../../core/observe.js');
+            // Parse viewport
+            let viewport = 'desktop';
+            const vpArg = options.viewport;
+            if (vpArg === 'mobile' || vpArg === 'tablet') {
+                viewport = vpArg;
+            }
+            else if (vpArg && vpArg.includes('x')) {
+                const [w, h] = vpArg.split('x').map(Number);
+                if (w && h)
+                    viewport = { width: w, height: h };
+            }
+            const result = await observe({
+                url,
+                selector: options.selector,
+                viewport,
+                screenshot: options.screenshot || false,
+                screenshotFullPage: options.screenshotFullPage || false,
+                maxElements: options.maxElements,
+                timeout: options.timeout,
+                stealth: options.stealth || false,
+            });
+            if (spinner) {
+                spinner.succeed(`Observed ${result.totalElements} elements in ${result.elapsed}ms`);
+            }
+            // Save screenshot to file if requested
+            if (result.screenshot && options.screenshotOutput) {
+                const buf = Buffer.from(result.screenshot, 'base64');
+                writeFileSync(options.screenshotOutput, buf);
+                if (!options.silent) {
+                    console.error(`Screenshot saved to: ${options.screenshotOutput} (${(buf.length / 1024).toFixed(1)} KB)`);
+                }
+                // Don't include screenshot in JSON output when saved to file
+                delete result.screenshot;
+            }
+            if (options.json) {
+                await writeStdout(JSON.stringify(result, null, 2) + '\n');
+            }
+            else {
+                // Human-readable output
+                console.log(`\n🔍 ${result.title}`);
+                console.log(`   ${result.url}`);
+                console.log(`   Viewport: ${result.viewport.width}×${result.viewport.height} | Page: ${result.scroll.width}×${result.scroll.height}\n`);
+                const { elements } = result;
+                if (elements.links.length > 0) {
+                    console.log(`📎 Links (${elements.links.length}):`);
+                    for (const el of elements.links.slice(0, 15)) {
+                        const vp = el.inViewport ? '👁' : '  ';
+                        const href = el.attributes.href ? ` → ${el.attributes.href.slice(0, 60)}` : '';
+                        console.log(`  ${vp} [${el.ref}] ${el.text || '(no text)'}${href}`);
+                    }
+                    if (elements.links.length > 15) {
+                        console.log(`  ... and ${elements.links.length - 15} more`);
+                    }
+                    console.log('');
+                }
+                if (elements.buttons.length > 0) {
+                    console.log(`🔘 Buttons (${elements.buttons.length}):`);
+                    for (const el of elements.buttons) {
+                        const vp = el.inViewport ? '👁' : '  ';
+                        console.log(`  ${vp} [${el.ref}] "${el.text || '(no text)'}" — selector: ${el.selector}`);
+                    }
+                    console.log('');
+                }
+                if (elements.inputs.length > 0) {
+                    console.log(`✏️  Inputs (${elements.inputs.length}):`);
+                    for (const el of elements.inputs) {
+                        const vp = el.inViewport ? '👁' : '  ';
+                        const type = el.attributes.type || 'text';
+                        const label = el.text || el.attributes.placeholder || el.attributes.name || 'unnamed';
+                        console.log(`  ${vp} [${el.ref}] ${label} (${type}) — selector: ${el.selector}`);
+                    }
+                    console.log('');
+                }
+                if (elements.selects.length > 0) {
+                    console.log(`📋 Selects (${elements.selects.length}):`);
+                    for (const el of elements.selects) {
+                        const vp = el.inViewport ? '👁' : '  ';
+                        const opts = el.attributes.options || '';
+                        console.log(`  ${vp} [${el.ref}] ${el.text || el.attributes.name || 'dropdown'}${opts ? ` [${opts}]` : ''}`);
+                    }
+                    console.log('');
+                }
+                if (elements.forms.length > 0) {
+                    console.log(`📝 Forms (${elements.forms.length}):`);
+                    for (const el of elements.forms) {
+                        const fields = el.attributes.fields || '?';
+                        const action = el.attributes.action || '';
+                        console.log(`  [${el.ref}] ${el.text || 'form'} — ${fields} fields${action ? ` → ${action.slice(0, 60)}` : ''}`);
+                    }
+                    console.log('');
+                }
+                console.log(`📊 Summary: ${result.summary}`);
+            }
+            await cleanup();
+            process.exit(0);
+        }
+        catch (error) {
+            if (spinner)
+                spinner.fail('Observation failed');
+            console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            await cleanup();
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/commands/screenshot.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Screenshot commands: screenshot, brand, design-compare
+ */
+import type { Command } from 'commander';
+export declare function registerScreenshotCommands(program: Command): void;

package/dist/cli/commands/screenshot.js

@@ -0,0 +1,282 @@
+/**
+ * Screenshot commands: screenshot, brand, design-compare
+ */
+import ora from 'ora';
+import { writeFileSync } from 'fs';
+import { cleanup } from '../../index.js';
+import { checkUsage, showUsageFooter } from '../../cli-auth.js';
+import { parseActions, extractColors, extractFonts } from '../utils.js';
+import { peel } from '../../index.js';
+export function registerScreenshotCommands(program) {
+    // ── screenshot command ────────────────────────────────────────────────────
+    program
+        .command('screenshot <url>')
+        .alias('snap')
+        .description('Take a screenshot of a URL and save as PNG/JPEG')
+        .option('--full-page', 'Capture full page (not just viewport)')
+        .option('--width <px>', 'Viewport width in pixels (default: 1280)', parseInt)
+        .option('--height <px>', 'Viewport height in pixels (default: 720)', parseInt)
+        .option('--format <fmt>', 'Image format: png (default) or jpeg', 'png')
+        .option('--quality <n>', 'JPEG quality 1-100 (ignored for PNG)', parseInt)
+        .option('-w, --wait <ms>', 'Wait time after page load (ms)', parseInt)
+        .option('-t, --timeout <ms>', 'Request timeout (ms)', (v) => parseInt(v, 10), 30000)
+        .option('--stealth', 'Use stealth mode to bypass bot detection')
+        .option('--action <actions...>', 'Page actions before screenshot (e.g., "click:.btn" "wait:2000")')
+        .option('--scroll-through', 'Auto-scroll page before screenshot (triggers lazy content + scroll animations)')
+        .option('-o, --output <path>', 'Output file path (default: screenshot.png)')
+        .option('-s, --silent', 'Silent mode (no spinner)')
+        .option('--json', 'Output base64 JSON instead of binary file')
+        .action(async (url, options) => {
+        // Validate URL
+        try {
+            const parsed = new URL(url);
+            if (!['http:', 'https:'].includes(parsed.protocol)) {
+                console.error('Error: Only HTTP and HTTPS protocols are allowed');
+                process.exit(1);
+            }
+        }
+        catch {
+            console.error(`Error: Invalid URL format: ${url}`);
+            process.exit(1);
+        }
+        // Check usage quota
+        const usageCheck = await checkUsage();
+        if (!usageCheck.allowed) {
+            console.error(usageCheck.message);
+            process.exit(1);
+        }
+        const spinner = options.silent ? null : ora('Taking screenshot...').start();
+        try {
+            // Validate format
+            const format = options.format?.toLowerCase();
+            if (format && !['png', 'jpeg', 'jpg'].includes(format)) {
+                console.error('Error: --format must be png, jpeg, or jpg');
+                process.exit(1);
+            }
+            // Parse actions
+            let actions;
+            if (options.action && options.action.length > 0) {
+                try {
+                    actions = parseActions(options.action);
+                }
+                catch (e) {
+                    console.error(`Error: ${e.message}`);
+                    process.exit(1);
+                }
+            }
+            const { takeScreenshot } = await import('../../core/screenshot.js');
+            const result = await takeScreenshot(url, {
+                fullPage: options.fullPage || false,
+                width: options.width,
+                height: options.height,
+                format: format || 'png',
+                quality: options.quality,
+                waitFor: options.wait,
+                timeout: options.timeout,
+                stealth: options.stealth || false,
+                actions,
+                scrollThrough: options.scrollThrough || false,
+            });
+            if (spinner) {
+                spinner.succeed(`Screenshot taken (${result.format})`);
+            }
+            // Show usage footer for free/anonymous users
+            if (usageCheck.usageInfo && !options.silent) {
+                showUsageFooter(usageCheck.usageInfo, usageCheck.isAnonymous || false, true);
+            }
+            if (options.json) {
+                // Output JSON with base64
+                const jsonStr = JSON.stringify({
+                    url: result.url,
+                    format: result.format,
+                    contentType: result.contentType,
+                    screenshot: result.screenshot,
+                }, null, 2);
+                await new Promise((resolve, reject) => {
+                    process.stdout.write(jsonStr + '\n', (err) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve();
+                    });
+                });
+            }
+            else {
+                // Save to file
+                const ext = result.format === 'jpeg' ? 'jpg' : 'png';
+                const outputPath = options.output || `screenshot.${ext}`;
+                const buffer = Buffer.from(result.screenshot, 'base64');
+                writeFileSync(outputPath, buffer);
+                if (!options.silent) {
+                    console.error(`Screenshot saved to: ${outputPath} (${(buffer.length / 1024).toFixed(1)} KB)`);
+                }
+            }
+            await cleanup();
+            process.exit(0);
+        }
+        catch (error) {
+            if (spinner) {
+                spinner.fail('Screenshot failed');
+            }
+            if (error instanceof Error) {
+                const msg = error.message;
+                // Detect missing browser binary and give an actionable error
+                if (msg.includes("Executable doesn't exist") || msg.includes('browserType.launch') || msg.includes('Chromium is not installed')) {
+                    console.error('\n\x1b[31m❌  Browser not installed.\x1b[0m');
+                    console.error('\x1b[36m   Run: npx playwright install chromium\x1b[0m');
+                    console.error('\x1b[36m   Then retry your screenshot command.\x1b[0m');
+                }
+                else {
+                    console.error(`\nError: ${msg}`);
+                }
+            }
+            else {
+                console.error('\nError: Unknown error occurred');
+            }
+            await cleanup();
+            process.exit(1);
+        }
+    });
+    // ── brand command ─────────────────────────────────────────────────────────
+    program
+        .command('brand <url>')
+        .description('Extract branding and design system from a URL')
+        .option('-s, --silent', 'Silent mode (no spinner)')
+        .option('--json', 'Output as JSON (default)')
+        .action(async (url, options) => {
+        const spinner = options.silent ? null : ora('Extracting branding...').start();
+        try {
+            const result = await peel(url, {
+                extract: {
+                    selectors: {
+                        primaryColor: 'meta[name="theme-color"]',
+                        title: 'title',
+                        logo: 'img[class*="logo"], img[alt*="logo"]',
+                    },
+                },
+            });
+            if (spinner) {
+                spinner.succeed(`Extracted branding in ${result.elapsed}ms`);
+            }
+            // Extract branding data from metadata and page
+            const branding = {
+                url: result.url,
+                title: result.title,
+                colors: extractColors(result.content),
+                fonts: extractFonts(result.content),
+                extracted: result.extracted,
+                metadata: result.metadata,
+            };
+            console.log(JSON.stringify(branding, null, 2));
+            await cleanup();
+            process.exit(0);
+        }
+        catch (error) {
+            if (spinner)
+                spinner.fail('Branding extraction failed');
+            console.error(`Error: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            await cleanup();
+            process.exit(1);
+        }
+    });
+    // ── design-compare command ────────────────────────────────────────────────
+    program
+        .command('design-compare <url>')
+        .description('Compare the design of a subject URL against a reference URL')
+        .option('--ref <url>', 'Reference URL to compare against (required)')
+        .option('--width <px>', 'Viewport width in pixels (default: 1440)', parseInt)
+        .option('--height <px>', 'Viewport height in pixels (default: 900)', parseInt)
+        .option('-o, --output <path>', 'Save comparison report to a JSON file')
+        .option('-s, --silent', 'Silent mode (no spinner)')
+        .option('--json', 'Output comparison as JSON to stdout')
+        .action(async (url, options) => {
+        // Validate subject URL
+        try {
+            const parsed = new URL(url);
+            if (!['http:', 'https:'].includes(parsed.protocol)) {
+                console.error('Error: Only HTTP and HTTPS protocols are allowed');
+                process.exit(1);
+            }
+        }
+        catch {
+            console.error(`Error: Invalid URL format: ${url}`);
+            process.exit(1);
+        }
+        // Validate --ref
+        if (!options.ref) {
+            console.error('Error: --ref <url> is required');
+            process.exit(1);
+        }
+        try {
+            const parsedRef = new URL(options.ref);
+            if (!['http:', 'https:'].includes(parsedRef.protocol)) {
+                console.error('Error: --ref must be an HTTP or HTTPS URL');
+                process.exit(1);
+            }
+        }
+        catch {
+            console.error(`Error: Invalid --ref URL format: ${options.ref}`);
+            process.exit(1);
+        }
+        const spinner = options.silent ? null : ora(`Comparing designs: ${url} vs ${options.ref}...`).start();
+        try {
+            const { takeDesignComparison } = await import('../../core/screenshot.js');
+            const result = await takeDesignComparison(url, options.ref, {
+                width: options.width,
+                height: options.height,
+            });
+            if (spinner)
+                spinner.succeed('Design comparison complete');
+            const { comparison } = result;
+            const output = {
+                subjectUrl: result.subjectUrl,
+                referenceUrl: result.referenceUrl,
+                score: comparison.score,
+                summary: comparison.summary,
+                gaps: comparison.gaps,
+                subjectAnalysis: comparison.subjectAnalysis,
+                referenceAnalysis: comparison.referenceAnalysis,
+            };
+            if (options.output) {
+                writeFileSync(options.output, JSON.stringify(output, null, 2));
+                if (!options.silent)
+                    console.error(`Report saved to: ${options.output}`);
+            }
+            if (options.json || !options.output) {
+                const jsonStr = JSON.stringify(output, null, 2);
+                await new Promise((resolve, reject) => {
+                    process.stdout.write(jsonStr + '\n', (err) => {
+                        if (err)
+                            reject(err);
+                        else
+                            resolve();
+                    });
+                });
+            }
+            else if (!options.silent) {
+                // Human-readable summary
+                console.log(`\n🎨 Design Comparison`);
+                console.log(`Subject:   ${result.subjectUrl}`);
+                console.log(`Reference: ${result.referenceUrl}`);
+                console.log(`Score:     ${comparison.score}/10`);
+                console.log(`\n${comparison.summary}`);
+                if (comparison.gaps.length > 0) {
+                    console.log(`\nGaps (${comparison.gaps.length}):`);
+                    for (const gap of comparison.gaps) {
+                        const sev = gap.severity === 'high' ? '🔴' : gap.severity === 'medium' ? '🟡' : '🟢';
+                        console.log(`  ${sev} ${gap.property}: ${gap.description}`);
+                        console.log(`     Subject:    ${gap.subject}`);
+                        console.log(`     Reference:  ${gap.reference}`);
+                        console.log(`     Suggestion: ${gap.suggestion}`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (spinner)
+                spinner.fail('Design comparison failed');
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/commands/search.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Search commands: search, sites, batch, crawl, map
+ */
+import type { Command } from 'commander';
+export declare function registerSearchCommands(program: Command): void;