⚡ Halo — URL Auditing Terminal Tool

Halo (Health + Analytics + Links + Optimization) is a fast, zero-config CLI tool that crawls any website and audits its routes, SEO quality, and performance analytics — directly from your terminal.

Features

| Module | What it does | |---|---| | 🔗 Routes | BFS crawl of all internal links · HTTP status codes · TTFB · redirect chains · broken link detection | | 🔍 SEO | 13-point SEO score per page · title, meta description, headings, OG, Twitter Card, canonical, alt text, structured data, viewport, lang | | 📊 Analytics | Script/image/stylesheet counts · render-blocking scripts · external domains · 8 security headers · SSL check | | ⚡ Core Web Vitals | FCP, LCP, CLS, TTI via headless Puppeteer (opt-in with --headless) | | 📄 Reports | JSON or Markdown report export |

Install

git clone https://github.com/yourname/halo
cd halo
npm install
npm run build
npm link          # makes `halo` available globally

Or one-liner:

cd halo && npm install && npm run build && npm link

Usage

halo <url> [options]

Options

| Flag | Default | Description | |---|---|---| | -s, --seo | off | Run SEO analysis | | -r, --routes | off | Show detailed routes table | | -a, --analytics | off | Run performance + security analytics | | --all | off | Enable all modules | | --headless | off | Core Web Vitals via Puppeteer (slow) | | -d, --depth <n> | 3 | Crawl depth | | -c, --concurrency <n> | 5 | Parallel requests | | -t, --timeout <n> | 10000 | Per-request timeout (ms) | | -v, --verbose | off | Detailed tables for all modules run | | -o, --output <file> | — | Save report to .json or .md |

Examples

# Quick scan (compact output, no modules)
halo https://example.com

# Full audit — all modules, verbose
halo https://example.com --all -v

# SEO only
halo https://example.com --seo

# Performance analytics + security headers
halo https://example.com --analytics -v

# Core Web Vitals (requires puppeteer)
halo https://example.com --headless

# Deep crawl with report export
halo https://example.com --all --depth 5 -o report.json

# Faster crawl with 10 parallel requests
halo https://example.com --all -c 10

SEO Checks

| Check | Weight | What's measured | |---|---|---| | Title tag | 15 | Present, 30–70 chars | | Meta description | 12 | Present, 80–165 chars | | H1 tag | 10 | Exactly one, not empty | | Image alt attributes | 9 | All <img> have alt | | Canonical URL | 8 | <link rel="canonical"> present | | Heading hierarchy | 7 | No skipped levels (h1→h3) | | Open Graph | 7 | og:title, og:description, og:image, og:url | | Viewport meta | 6 | <meta name="viewport"> present | | Structured data | 6 | JSON-LD block present | | Robots meta | 5 | Not noindexed | | HTML lang | 5 | <html lang="..."> set | | Twitter Card | 4 | twitter:card meta present |

Security Headers Checked

strict-transport-security · content-security-policy · x-frame-options · x-content-type-options · referrer-policy · permissions-policy · x-xss-protection · cross-origin-opener-policy

Output Formats

Terminal (default)

Real-time compact line per page during crawl, then full tables per module after.

JSON (--output report.json)

Machine-readable full report with all page results, SEO checks, analytics, and broken links.

Markdown (--output report.md)

Human-readable tables for sharing with a team.

Requirements

• Node.js 20+
• puppeteer is optional — only needed for --headless mode. When you first use --headless, Puppeteer will download a bundled Chromium (~300 MB).

Project Structure

halo/
├── src/
│   ├── bin/
│   │   └── halo.ts              # CLI entrypoint — Commander flags & argument parsing
│   ├── modules/
│   │   ├── crawler.ts           # BFS link discovery engine (p-limit concurrency)
│   │   ├── seo.ts               # 13-point SEO analyzer — weighted 0–100 score
│   │   ├── analytics.ts         # Performance metrics + 8 security header checks
│   │   ├── routes.ts            # robots.txt fetcher + sitemap.xml parser
│   │   └── headless.ts          # Puppeteer Core Web Vitals (FCP, LCP, CLS, TTI)
│   └── utils/
│       ├── types.ts             # All shared TypeScript interfaces
│       ├── http.ts              # axios HTTP client with TTFB measurement
│       ├── score.ts             # Rating + formatting helpers
│       ├── reporter.ts          # Terminal output — compact lines, tables, summary box
│       └── index.ts             # Main orchestrator — ties all modules together
├── dist/
│   └── halo.js                  # Compiled single-file ESM bundle (36 KB)
├── .notes/                      # Personal dev notes (gitignored)
│   └── how-it-works.md
├── .gitignore
├── package.json
├── tsconfig.json
├── tsup.config.ts               # Build config — shebang banner, puppeteer external
└── README.md

Tech Stack

| Package | Purpose | |---|---| | commander | CLI argument parsing | | axios | HTTP client with TTFB measurement | | cheerio | Server-side HTML parsing | | p-limit | Concurrency-limited BFS crawl | | chalk | Terminal colors | | ora | Spinners | | cli-table3 | Terminal tables | | boxen | Summary boxes | | puppeteer | Headless Chrome (optional) | | TypeScript | Type safety throughout | | tsup | Single-file ESM build |

License

MIT