@ai-lighthouse/cli 1.0.0

package/WIZARD_GUIDE.md

@@ -0,0 +1,340 @@
+# AI Lighthouse Interactive Wizard Guide
+
+The AI Lighthouse CLI now features an **interactive setup wizard** that simplifies configuration by asking you questions instead of requiring complex command-line flags!
+
+## Quick Start
+
+### Option 1: Wizard with URL
+
+```bash
+ai-lighthouse wizard https://example.com
+```
+
+or use the short alias:
+
+```bash
+ai-lighthouse w https://example.com
+```
+
+### Option 2: Wizard without URL (asks you for it)
+
+```bash
+ai-lighthouse wizard
+```
+
+## How It Works
+
+The wizard guides you through a simple, step-by-step configuration process:
+
+### Step 1: URL Input (if not provided)
+
+```
+🚨 AI Lighthouse Setup Wizard
+Configure your audit settings
+
+Enter the URL to audit:
+URL: _
+```
+
+Type your URL and press Enter.
+
+### Step 2: Feature Selection
+
+```
+Select features to enable:
+Selected: None (basic audit only)
+
+  🧠 AI Understanding (LLM Analysis)
+  📄 Content Chunking Analysis
+  🔄 Extractability Analysis
+  ⚠️  Hallucination Detection
+  ✅ Continue with selected features
+
+Use ↑↓ to navigate, Enter to toggle/continue
+```
+
+- Use **↑** and **↓** arrow keys to navigate
+- Press **Enter** to toggle features on/off (✓ appears when selected)
+- Select **✅ Continue** when ready
+
+### Step 3: LLM Provider Selection (if LLM features enabled)
+
+```
+Select LLM provider:
+
+  OpenAI (GPT-4, GPT-3.5)
+  Anthropic (Claude)
+  Ollama (Local)
+  Custom/Local Provider
+
+Use ↑↓ to navigate, Enter to select
+```
+
+Choose your preferred LLM provider.
+
+### Step 4: Model Name
+
+```
+Enter LLM model name:
+Model: _
+
+Leave empty for default, or press Enter to continue
+```
+
+**Defaults:**
+- OpenAI: `gpt-4o-mini`
+- Anthropic: `claude-3-5-sonnet-20241022`
+- Ollama: `qwen2.5:0.5b` (or any installed model)
+
+### Step 5: API Key (for OpenAI/Anthropic)
+
+```
+Enter API key:
+API Key: ****
+
+Your API key will not be stored
+```
+
+Type your API key (it will be masked with `*` for security).
+
+### Step 6: Base URL (optional, for Ollama/Custom)
+
+```
+Enter API base URL (optional):
+Base URL: _
+
+Press Enter to continue (leave empty for default)
+```
+
+**Defaults:**
+- Ollama: `http://localhost:11434` (auto-filled)
+- Custom: You specify
+
+### Step 7: Running the Audit
+
+```
+✓ Configuration Complete
+Starting audit...
+```
+
+The wizard automatically transitions to the audit UI!
+
+## Wizard vs. Traditional Commands
+
+### With Wizard (Simplified)
+
+```bash
+# Just run the wizard
+ai-lighthouse wizard https://example.com
+
+# Then follow the prompts:
+# 1. Select "AI Understanding (LLM Analysis)" ✓
+# 2. Select "Hallucination Detection" ✓
+# 3. Select "Continue"
+# 4. Choose "Ollama (Local)"
+# 5. Enter model: "qwen2.5:0.5b"
+# 6. Confirm base URL: "http://localhost:11434"
+# Done!
+```
+
+### Without Wizard (Traditional)
+
+```bash
+ai-lighthouse audit https://example.com \
+  --enable-llm \
+  --enable-hallucination \
+  --llm-provider ollama \
+  --llm-model qwen2.5:0.5b \
+  --llm-base-url http://localhost:11434
+```
+
+The wizard is **much easier** for beginners and interactive use!
+
+## Feature Matrix
+
+When you select features in the wizard:
+
+| Feature Selected | What It Enables |
+|-----------------|-----------------|
+| 🧠 AI Understanding | LLM-powered page analysis, entity extraction, FAQ suggestions |
+| 📄 Content Chunking | Shows how your content is divided for AI processing |
+| 🔄 Extractability | Analyzes how well AI can extract your content |
+| ⚠️ Hallucination Detection | Identifies potential hallucination triggers (requires AI Understanding) |
+
+## Tips & Tricks
+
+### Quick Basic Audit
+
+```bash
+# Wizard with URL, select "Continue" without features
+ai-lighthouse w https://example.com
+```
+
+### Full-Featured Audit
+
+```bash
+# Enable all features in the wizard
+ai-lighthouse wizard https://example.com
+# Then select all 4 features before continuing
+```
+
+### Skip Wizard for Automation
+
+For scripts and CI/CD, use the traditional `audit` command with flags:
+
+```bash
+ai-lighthouse audit https://example.com --output json
+```
+
+## Common Workflows
+
+### First-Time User
+
+1. Run wizard: `ai-lighthouse wizard`
+2. Enter your website URL
+3. Try without features first (press "Continue")
+4. Review the basic report
+5. Run again with features to see more insights
+
+### Using Local Ollama
+
+1. Start Ollama: `ollama serve`
+2. Pull a small model: `ollama pull qwen2.5:0.5b`
+3. Run wizard: `ai-lighthouse w https://example.com`
+4. Select "AI Understanding" ✓
+5. Choose "Ollama (Local)"
+6. Enter model name: `qwen2.5:0.5b`
+7. Confirm default URL
+
+### Using OpenAI
+
+1. Get API key from https://platform.openai.com/api-keys
+2. Run wizard: `ai-lighthouse w https://example.com`
+3. Select desired features
+4. Choose "OpenAI (GPT-4, GPT-3.5)"
+5. Enter model: (leave empty for default or type `gpt-4o-mini`)
+6. Paste API key when prompted
+
+### Using Anthropic Claude
+
+1. Get API key from https://console.anthropic.com/
+2. Run wizard: `ai-lighthouse w https://example.com`
+3. Select features
+4. Choose "Anthropic (Claude)"
+5. Enter model: (leave empty for default)
+6. Paste API key when prompted
+
+## Keyboard Shortcuts in Wizard
+
+- **↑** / **↓** - Navigate options
+- **Enter** - Select/toggle option
+- **Type** - Input text in text fields
+- **Ctrl+C** - Cancel and exit
+
+## Benefits of Using the Wizard
+
+✅ **No memorization** - Don't need to remember complex flags
+✅ **Visual feedback** - See your selections with checkmarks
+✅ **Smart defaults** - Suggests appropriate defaults for each provider
+✅ **Guided flow** - Only asks relevant questions
+✅ **Error prevention** - Validates inputs as you go
+✅ **Security** - Masks sensitive API keys
+✅ **Quick setup** - Faster than typing long commands
+
+## When to Use Each Mode
+
+### Use the Wizard When:
+- You're learning the tool
+- You want to try different configurations
+- You don't remember all the flags
+- You're doing interactive analysis
+- You want a guided experience
+
+### Use Direct Commands When:
+- You're automating audits (CI/CD)
+- You're writing scripts
+- You know exactly what you want
+- You're running batch operations
+- You want to pipe output to other tools
+
+## Examples
+
+### Example 1: Quick Test Run
+
+```bash
+$ ai-lighthouse w
+
+🚨 AI Lighthouse Setup Wizard
+Configure your audit settings
+
+Enter the URL to audit:
+URL: https://example.com
+
+Select features to enable:
+Selected: None (basic audit only)
+> ✅ Continue with selected features
+
+✓ Configuration Complete
+Starting audit...
+
+[Beautiful audit UI appears]
+```
+
+### Example 2: Full Analysis with Ollama
+
+```bash
+$ ai-lighthouse wizard https://mysite.com
+
+🚨 AI Lighthouse Setup Wizard
+Configure your audit settings
+
+Select features to enable:
+Selected: 🧠, 📄, 🔄, ⚠️
+> ✅ Continue with selected features
+
+Select LLM provider:
+> Ollama (Local)
+
+Enter LLM model name:
+Model: llama2
+
+Enter API base URL (optional):
+Base URL: http://localhost:11434
+
+✓ Configuration Complete
+Starting audit...
+
+[Comprehensive audit with all features]
+```
+
+## Troubleshooting
+
+### Wizard doesn't start
+- Make sure you're using `wizard` or `w` command
+- Check that you have Node.js 18+ installed
+
+### API key not working
+- Verify your API key is correct
+- Check that you have credits/access
+- Ensure you selected the right provider
+
+### Ollama connection fails
+- Verify Ollama is running: `ollama list`
+- Check the base URL is correct (default: `http://localhost:11434`)
+- Ensure the model is pulled: `ollama pull modelname`
+
+### Features not showing data
+- Make sure you enabled the features in the wizard
+- Check that LLM analysis completed successfully
+- Some features require LLM to be enabled
+
+## Next Steps
+
+After using the wizard a few times, you might want to:
+
+1. **Save common configurations** - Use the traditional command with flags in a script
+2. **Explore all options** - Check `ai-lighthouse audit --help` for advanced flags
+3. **Automate audits** - Integrate into your CI/CD pipeline
+4. **Compare results** - Run audits regularly to track improvements
+
+Happy auditing! 🚨✨

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../src/index.ts');

package/dist/commands/audit-interactive.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function auditInteractiveCommand(program: Command): void;

package/dist/commands/audit-interactive.js

@@ -0,0 +1,106 @@
+import { analyzeUrlWithRules } from 'scanner';
+import { calculateAIReadiness } from 'scanner';
+import { render } from 'ink';
+import React from 'react';
+import { AuditReportUI } from '../ui/AuditReportUI.js';
+export function auditInteractiveCommand(program) {
+    program
+        .command('audit-interactive')
+        .description('Audit a website for AI readiness with interactive UI')
+        .argument('<url>', 'URL to audit')
+        .option('-r, --rules <preset>', 'Rule preset: default, strict, minimal', 'default')
+        .option('-d, --depth <number>', 'Crawl depth (for multi-page audits)', parseInt, 1)
+        .option('-p, --pages <urls>', 'Comma-separated list of specific pages to audit')
+        .option('--cache-ttl <seconds>', 'Cache TTL in seconds to avoid re-fetching', parseInt)
+        .option('--threshold <score>', 'Minimum score threshold (exit 1 if below)', parseInt)
+        .option('--max-chunk-tokens <number>', 'Maximum tokens per content chunk', parseInt, 1200)
+        .option('--chunking-strategy <strategy>', 'Chunking strategy: auto, heading-based, paragraph-based', 'auto')
+        .option('--enable-chunking', 'Enable detailed content chunking analysis', false)
+        .option('--enable-extractability', 'Enable extractability mapping', false)
+        .option('--enable-hallucination', 'Enable hallucination detection', false)
+        .option('--enable-llm', 'Enable LLM comprehension analysis', false)
+        .option('--min-impact <number>', 'Minimum impact score to include', parseInt, 8)
+        .option('--min-confidence <number>', 'Minimum confidence to include (0-1)', parseFloat, 0.7)
+        .option('--max-issues <number>', 'Maximum issues to return', parseInt, 20)
+        .option('--llm-provider <provider>', 'LLM provider: openai, anthropic, ollama, local')
+        .option('--llm-model <model>', 'LLM model name')
+        .option('--llm-base-url <url>', 'LLM API base URL')
+        .option('--llm-api-key <key>', 'LLM API key')
+        .action(async (url, options) => {
+        // Show loading UI
+        const { waitUntilExit, clear, rerender } = render(React.createElement(AuditReportUI, {
+            url,
+            result: {},
+            aiReadiness: {},
+            loading: true,
+            currentStep: 'Starting audit...',
+        }));
+        try {
+            // Validate URL
+            const urlObj = new URL(url);
+            // Build scan options
+            const scanOptions = {
+                maxChunkTokens: options.maxChunkTokens,
+                chunkingStrategy: options.chunkingStrategy,
+                enableChunking: options.enableChunking,
+                enableExtractability: options.enableExtractability,
+                enableHallucinationDetection: options.enableHallucination,
+                enableLLM: options.enableLlm,
+                minImpactScore: options.minImpact,
+                minConfidence: options.minConfidence,
+                maxIssues: options.maxIssues,
+            };
+            // Configure LLM if enabled
+            if (options.enableLlm && options.llmProvider) {
+                scanOptions.llmConfig = {
+                    provider: options.llmProvider,
+                    model: options.llmModel,
+                    baseUrl: options.llmBaseUrl,
+                    apiKey: options.llmApiKey,
+                };
+            }
+            // Update loading step
+            rerender(React.createElement(AuditReportUI, {
+                url: urlObj.href,
+                result: {},
+                aiReadiness: {},
+                loading: true,
+                currentStep: 'Scanning page...',
+            }));
+            // Run the audit
+            const result = await analyzeUrlWithRules(url, scanOptions);
+            // Update loading step
+            rerender(React.createElement(AuditReportUI, {
+                url: urlObj.href,
+                result,
+                aiReadiness: {},
+                loading: true,
+                currentStep: 'Calculating AI readiness scores...',
+            }));
+            // Calculate AI readiness
+            const aiReadiness = calculateAIReadiness(result);
+            // Clear loading and show results
+            clear();
+            const finalRender = render(React.createElement(AuditReportUI, {
+                url: urlObj.href,
+                result,
+                aiReadiness,
+                loading: false,
+            }));
+            // Wait for user to exit
+            await finalRender.waitUntilExit();
+            // Check threshold
+            if (options.threshold !== undefined) {
+                const overallScore = aiReadiness.overall;
+                if (overallScore !== undefined && overallScore < options.threshold) {
+                    process.exit(1);
+                }
+            }
+        }
+        catch (error) {
+            clear();
+            console.error('Audit failed:', error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/audit-wizard.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function auditWizardCommand(program: Command): void;

package/dist/commands/audit-wizard.js

@@ -0,0 +1,110 @@
+import { render } from 'ink';
+import React from 'react';
+import { SetupWizard } from '../ui/SetupWizard.js';
+import { AuditReportUI } from '../ui/AuditReportUI.js';
+import { analyzeUrlWithRules, calculateAIReadiness } from 'scanner';
+export function auditWizardCommand(program) {
+    program
+        .command('wizard')
+        .alias('w')
+        .description('Interactive wizard to configure and run an audit')
+        .argument('[url]', 'Optional URL to audit (will prompt if not provided)')
+        .action(async (url) => {
+        // Suppress console.error and console.warn for cleaner UI
+        const originalConsoleError = console.error;
+        const originalConsoleWarn = console.warn;
+        console.error = () => { };
+        console.warn = () => { };
+        let auditConfig = null;
+        // Show setup wizard
+        const wizardRender = render(React.createElement(SetupWizard, {
+            initialUrl: url,
+            onComplete: (config) => {
+                auditConfig = config;
+            },
+        }));
+        // Wait for wizard to complete
+        await wizardRender.waitUntilExit();
+        if (!auditConfig) {
+            console.error = originalConsoleError;
+            console.warn = originalConsoleWarn;
+            console.log('\nAudit cancelled.');
+            process.exit(0);
+        }
+        // Start the audit with the configured options
+        const { clear, rerender } = render(React.createElement(AuditReportUI, {
+            url: auditConfig.url,
+            result: {},
+            aiReadiness: {},
+            loading: true,
+            currentStep: 'Starting audit...',
+        }));
+        try {
+            // Build scan options from config
+            const scanOptions = {
+                maxChunkTokens: 1200,
+                chunkingStrategy: 'auto',
+                enableChunking: auditConfig.enableChunking,
+                enableExtractability: auditConfig.enableExtractability,
+                enableHallucinationDetection: auditConfig.enableHallucination,
+                enableLLM: auditConfig.enableLlm,
+                minImpactScore: 8,
+                minConfidence: 0.7,
+                maxIssues: 20,
+            };
+            // Configure LLM if enabled
+            if (auditConfig.enableLlm && auditConfig.llmProvider) {
+                scanOptions.llmConfig = {
+                    provider: auditConfig.llmProvider,
+                    model: auditConfig.llmModel,
+                    baseUrl: auditConfig.llmBaseUrl,
+                    apiKey: auditConfig.llmApiKey,
+                };
+            }
+            // Update loading step
+            rerender(React.createElement(AuditReportUI, {
+                url: auditConfig.url,
+                result: {},
+                aiReadiness: {},
+                loading: true,
+                currentStep: 'Scanning page...',
+            }));
+            // Run the audit
+            const result = await analyzeUrlWithRules(auditConfig.url, scanOptions);
+            // Update loading step
+            rerender(React.createElement(AuditReportUI, {
+                url: auditConfig.url,
+                result,
+                aiReadiness: {},
+                loading: true,
+                currentStep: 'Calculating AI readiness scores...',
+            }));
+            // Calculate AI readiness
+            const aiReadiness = calculateAIReadiness(result);
+            // Clear loading and show results
+            clear();
+            const finalRender = render(React.createElement(AuditReportUI, {
+                url: auditConfig.url,
+                result,
+                aiReadiness,
+                loading: false,
+            }));
+            // Wait for user to exit
+            await finalRender.waitUntilExit();
+            // Restore console methods
+            console.error = originalConsoleError;
+            console.warn = originalConsoleWarn;
+        }
+        catch (error) {
+            // Restore console methods before showing error
+            console.error = originalConsoleError;
+            console.warn = originalConsoleWarn;
+            clear();
+            console.log('\n\x1b[1m\x1b[31m❌ Audit Failed\x1b[0m');
+            console.log('\x1b[31m' + '─'.repeat(70) + '\x1b[0m');
+            console.log('\x1b[31m' + (error instanceof Error ? error.message : String(error)) + '\x1b[0m');
+            console.log('\n\x1b[2mPlease check the URL and your configuration.\x1b[0m');
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/audit.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function auditCommand(program: Command): void;