@ai-lighthouse/cli 1.0.0

package/README.md

@@ -0,0 +1,166 @@
+# AI Lighthouse CLI
+
+Command-line interface for auditing websites for AI readiness, SEO optimization, and content quality.
+
+## Installation
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Usage
+
+### Audit a single page
+
+```bash
+ai-lighthouse audit https://example.com --output html
+```
+
+### Audit with specific rules
+
+```bash
+ai-lighthouse audit https://example.com --rules strict --enable-llm
+```
+
+### Crawl multiple pages
+
+```bash
+ai-lighthouse crawl https://example.com --depth 2 --sitemap
+```
+
+### Generate report from saved results
+
+```bash
+ai-lighthouse report ./.ai-lighthouse/last_run.json --open
+```
+
+## Commands
+
+### `audit <url>`
+
+Audit a single webpage for AI readiness.
+
+**Options:**
+- `-o, --output <format>` - Output format: json, html, lhr, csv (default: json)
+- `-r, --rules <preset>` - Rule preset: default, strict, minimal (default: default)
+- `-d, --depth <number>` - Crawl depth for multi-page audits (default: 1)
+- `-p, --pages <urls>` - Comma-separated list of specific pages to audit
+- `--cache-ttl <seconds>` - Cache TTL in seconds to avoid re-fetching
+- `--threshold <score>` - Minimum score threshold (exit 1 if below)
+- `--max-chunk-tokens <number>` - Maximum tokens per content chunk (default: 1200)
+- `--chunking-strategy <strategy>` - Chunking strategy: auto, heading-based, paragraph-based (default: auto)
+- `--enable-chunking` - Enable detailed content chunking analysis
+- `--enable-extractability` - Enable extractability mapping
+- `--enable-hallucination` - Enable hallucination detection
+- `--enable-llm` - Enable LLM comprehension analysis
+- `--min-impact <number>` - Minimum impact score to include (default: 8)
+- `--min-confidence <number>` - Minimum confidence to include 0-1 (default: 0.7)
+- `--max-issues <number>` - Maximum issues to return (default: 20)
+- `--llm-provider <provider>` - LLM provider: openai, anthropic, ollama, local
+- `--llm-model <model>` - LLM model name
+- `--llm-base-url <url>` - LLM API base URL
+- `--llm-api-key <key>` - LLM API key
+
+**Examples:**
+
+```bash
+# Basic audit
+ai-lighthouse audit https://example.com
+
+# HTML report with all features enabled
+ai-lighthouse audit https://example.com \
+  --output html \
+  --enable-chunking \
+  --enable-extractability \
+  --enable-hallucination \
+  --enable-llm \
+  --llm-provider ollama \
+  --llm-model qwen2.5:0.5b
+
+# Force paragraph-based chunking for consistent chunk sizes
+ai-lighthouse audit https://example.com \
+  --enable-chunking \
+  --chunking-strategy paragraph-based \
+  --max-chunk-tokens 1000
+
+# Force heading-based chunking for semantic sections
+ai-lighthouse audit https://example.com \
+  --enable-chunking \
+  --chunking-strategy heading-based
+
+# CI/CD integration with score threshold
+ai-lighthouse audit https://example.com --threshold 80
+```
+
+### `crawl <url>`
+
+Crawl and audit multiple pages from a website.
+
+**Options:**
+- `-d, --depth <number>` - Maximum crawl depth (default: 2)
+- `--sitemap` - Parse sitemap.xml for URLs
+- `--max-pages <number>` - Maximum number of pages to crawl (default: 50)
+- `-o, --output <format>` - Output format: json, html (default: json)
+- `--follow-external` - Follow external links
+- `--respect-robots` - Respect robots.txt rules (default: true)
+
+**Examples:**
+
+```bash
+# Crawl with sitemap
+ai-lighthouse crawl https://example.com --sitemap --max-pages 100
+
+# Deep crawl with custom depth
+ai-lighthouse crawl https://example.com --depth 3 --output html
+```
+
+### `report <file>`
+
+Generate and view reports from saved audit results.
+
+**Options:**
+- `--open` - Open the report in browser
+- `-f, --format <format>` - Output format: html, json, csv (default: html)
+
+**Examples:**
+
+```bash
+# Generate and open HTML report
+ai-lighthouse report ./.ai-lighthouse/last_run.json --open
+
+# Export to CSV
+ai-lighthouse report ./.ai-lighthouse/crawl_*.json --format csv
+```
+
+## Output Formats
+
+### JSON
+Standard JSON format with all audit data, compatible with CI/CD pipelines.
+
+### HTML
+Beautiful, interactive HTML report with charts and detailed issue breakdowns.
+
+### LHR (Lighthouse Report)
+Lighthouse-compatible JSON format for integration with existing Lighthouse tooling.
+
+### CSV
+Comma-separated values for spreadsheet analysis.
+
+## CI/CD Integration
+
+Use the `--threshold` flag to fail builds when scores drop below a threshold:
+
+```yaml
+# GitHub Actions example
+- name: Audit site
+  run: ai-lighthouse audit ${{ env.SITE_URL }} --threshold 80
+```
+
+## Configuration
+
+Results are saved to `.ai-lighthouse/` directory in your project root.
+
+## License
+
+MIT

package/USAGE.md

@@ -0,0 +1,264 @@
+# AI Lighthouse CLI - Quick Start Guide
+
+## Simplest Usage (Recommended for New Users)
+
+Just run with a URL - the wizard will guide you through the rest!
+
+```bash
+ai-lighthouse audit https://example.com
+```
+
+This will:
+1. **Ask you** which features to enable (AI Understanding, Chunking, etc.)
+2. **Guide you** through LLM provider setup if needed
+3. **Show results** in a beautiful interactive UI
+
+## How It Works
+
+### Basic Audit (No Additional Features)
+
+```bash
+ai-lighthouse audit https://example.com
+```
+
+When the wizard appears:
+- Just press **Enter** on "Continue with selected features"
+- You'll get a basic audit with core metrics
+
+### With AI Analysis
+
+```bash
+ai-lighthouse audit https://example.com
+```
+
+When the wizard appears:
+1. Select **🧠 AI Understanding** (press Enter to toggle)
+2. Select **Continue**
+3. Choose your LLM provider (e.g., **Ollama** for local)
+4. Enter model name (e.g., `qwen2.5:0.5b`)
+5. Confirm settings
+
+### Full-Featured Audit
+
+```bash
+ai-lighthouse audit https://example.com
+```
+
+In the wizard, select all features:
+- ✓ 🧠 AI Understanding
+- ✓ 📄 Content Chunking
+- ✓ 🔄 Extractability
+- ✓ ⚠️ Hallucination Detection
+- Continue
+
+Then configure your LLM provider.
+
+## Advanced Usage (Skip Wizard)
+
+If you know exactly what you want, you can skip the wizard with flags:
+
+### Quick Examples
+
+```bash
+# Basic audit, skip wizard, export as JSON
+ai-lighthouse audit https://example.com --output json
+
+# With Ollama (local LLM)
+ai-lighthouse audit https://example.com \
+  --enable-llm \
+  --llm-provider ollama \
+  --llm-model qwen2.5:0.5b
+
+# With OpenAI
+ai-lighthouse audit https://example.com \
+  --enable-llm \
+  --llm-provider openai \
+  --llm-api-key sk-...
+
+# Full-featured with Ollama
+ai-lighthouse audit https://example.com \
+  --enable-llm \
+  --enable-chunking \
+  --enable-extractability \
+  --enable-hallucination \
+  --llm-provider ollama \
+  --llm-model qwen2.5:0.5b
+```
+
+## When Does the Wizard Appear?
+
+The wizard **automatically shows** when:
+- ✅ You run `ai-lighthouse audit <url>` with NO feature flags
+- ✅ You just provide a URL
+
+The wizard **does NOT show** when:
+- ❌ You pass `--enable-llm` or other feature flags
+- ❌ You specify `--output json` (or html, pdf, csv)
+- ❌ You're using the command in a script/CI
+
+This means:
+- **Interactive use** = Wizard (easy!)
+- **Scripted use** = No wizard (predictable!)
+
+## Output Formats
+
+```bash
+# Interactive UI (default)
+ai-lighthouse audit https://example.com
+
+# JSON (for scripts/CI)
+ai-lighthouse audit https://example.com --output json
+
+# HTML report
+ai-lighthouse audit https://example.com --output html
+
+# PDF report
+ai-lighthouse audit https://example.com --output pdf
+
+# Lighthouse format
+ai-lighthouse audit https://example.com --output lhr
+
+# CSV export
+ai-lighthouse audit https://example.com --output csv
+```
+
+## Common Workflows
+
+### First Time Using the Tool
+
+```bash
+# Just run it!
+ai-lighthouse audit https://yoursite.com
+
+# The wizard will guide you through everything
+```
+
+### Regular Quick Check
+
+```bash
+# Run basic audit (press Enter when wizard appears)
+ai-lighthouse audit https://yoursite.com
+```
+
+### Deep Analysis
+
+```bash
+# Select all features in the wizard
+ai-lighthouse audit https://yoursite.com
+```
+
+### Automation / CI/CD
+
+```bash
+# Skip wizard with flags
+ai-lighthouse audit https://yoursite.com \
+  --output json \
+  --threshold 80
+```
+
+### Compare Before/After Changes
+
+```bash
+# Before changes
+ai-lighthouse audit https://yoursite.com --output json > before.json
+
+# Make changes to your site
+
+# After changes
+ai-lighthouse audit https://yoursite.com --output json > after.json
+
+# Compare the JSON files
+```
+
+## Tips
+
+### 🎯 For Beginners
+- Just use `ai-lighthouse audit <url>`
+- Let the wizard guide you
+- Start with basic audit (no features)
+- Enable features one at a time to learn
+
+### 🚀 For Power Users
+- Use flags to skip the wizard
+- Create shell aliases for common configs
+- Use `--output json` for scripting
+- Pipe output to `jq` for filtering
+
+### 🤖 For CI/CD
+- Always use `--output json`
+- Add `--threshold` to fail builds on low scores
+- Store API keys in environment variables
+- Use `--no-color` if needed
+
+## Examples by Use Case
+
+### Local Development with Ollama
+
+```bash
+# 1. Start Ollama
+ollama serve
+
+# 2. Pull a small model
+ollama pull qwen2.5:0.5b
+
+# 3. Run audit (wizard will auto-detect Ollama settings)
+ai-lighthouse audit http://localhost:3000
+```
+
+### Production Site Audit
+
+```bash
+# Let wizard guide you
+ai-lighthouse audit https://yourproductionsite.com
+
+# Or be specific
+ai-lighthouse audit https://yourproductionsite.com \
+  --enable-llm \
+  --enable-hallucination \
+  --llm-provider openai \
+  --llm-api-key $OPENAI_API_KEY
+```
+
+### CI/CD Pipeline
+
+```yaml
+# .github/workflows/audit.yml
+- name: Audit website
+  run: |
+    ai-lighthouse audit https://staging.example.com \
+      --output json \
+      --threshold 80
+```
+
+### Batch Auditing Multiple URLs
+
+```bash
+# audit-sites.sh
+for url in https://site1.com https://site2.com https://site3.com; do
+  ai-lighthouse audit $url --output json > "$(echo $url | sed 's/https:\/\///g').json"
+done
+```
+
+## Getting Help
+
+```bash
+# Main help
+ai-lighthouse --help
+
+# Command help
+ai-lighthouse audit --help
+
+# Version
+ai-lighthouse --version
+```
+
+## What's Next?
+
+After you've run a few audits:
+
+1. **Read the full guide**: See [WIZARD_GUIDE.md](./WIZARD_GUIDE.md) for detailed wizard usage
+2. **Explore the UI**: See [CLI_UI_README.md](./CLI_UI_README.md) for UI features
+3. **Learn the flags**: Run `ai-lighthouse audit --help` for all options
+4. **Automate**: Create scripts for regular audits
+
+Happy auditing! 🚨✨