headhunt 1.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 imharris24
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software for non-commercial purposes only, including without limitation the rights
+to use, copy, modify, merge, publish, and distribute
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+1. The Software may not be used for commercial purposes, including but not limited to selling the Software or using it in a commercial product or service.
+2. The Software may not be sublicensed for commercial purposes.
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# HeadHunt-CLI 🎯
+
+> The terminal-first SEO metadata hunter. Scrape, score, and audit any website's SEO health directly from the command line.
+
+[![npm version](https://img.shields.io/npm/v/headhunt)](https://www.npmjs.com/package/headhunt)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org/)
+
+---
+
+## ✨ Features
+
+### 🔍 Comprehensive SEO Extraction
+- **Basic Metadata** — title, meta description, canonical, robots, viewport, charset, language
+- **Open Graph** — full og: tag detection for social sharing
+- **Twitter Cards** — twitter: card, title, description, image
+- **Schema.org** — JSON-LD & Microdata parsing with type detection
+- **Technical SEO** — doctype, hreflang, pagination, sitemap, RSS, AMP, manifest
+
+### 📊 Intelligent Scoring Engine
+- **100-point SEO score** across 14 weighted categories
+- **Letter grade** (A+ to F) with contextual summary
+- **Priority-ranked recommendations** with impact & effort estimates
+
+### 🔗 Link & Content Analysis
+- Internal vs external link classification
+- Nofollow, sponsored, UGC rel attribute detection
+- Empty anchor text detection
+- Heading hierarchy validation (H1–H6) with skip detection
+- Image alt-text coverage & lazy-loading audit
+- Word count, paragraph count & keyword density estimation
+
+### 🛡️ Security & Performance Signals
+- HTTPS, HSTS, CSP, X-Frame-Options, X-Content-Type-Options
+- Render-blocking script detection
+- HTML payload size & fetch time analysis
+- Estimated total page weight
+
+### 📈 Professional Output Modes
+- **Terminal Report** — beautifully formatted with color-coded scores
+- **JSON Export** — full structured data for pipelines (`--json`, `--json-file`)
+- **Score-Only** — CI-friendly single-line output (`--score-only`)
+- **Deep Audit** — verbose recommendations with impact/effort badges (`--audit`)
+- **Side-by-Side Comparison** — compare two URLs (`--compare`)
+
+---
+
+## 🚀 Installation
+
+### Via npm (recommended)
+
+```bash
+npm install -g headhunt
+```
+
+Then run from anywhere:
+
+```bash
+headhunt https://example.com
+```
+
+### Via npx (no install)
+
+```bash
+npx headhunt https://example.com
+```
+
+### From Source
+
+```bash
+git clone https://github.com/imharris24/HeadHunt.git
+cd HeadHunt
+npm install
+chmod +x headhunt.js
+node headhunt.js https://example.com
+```
+
+---
+
+## 📖 Usage
+
+### Basic Scan
+
+```bash
+headhunt https://example.com
+```
+
+### Output Modes
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Print full raw JSON to stdout |
+| `--json-file` | Save JSON report to `seo-report-<hostname>-<timestamp>.json` |
+| `--score-only` | Print `Score: 78/100  Grade: B+` (CI-friendly) |
+| `--audit` | Show full recommendations with impact & effort badges |
+
+```bash
+# CI pipeline check
+headhunt --score-only https://example.com
+
+# Deep audit with actionable fixes
+headhunt --audit https://example.com
+
+# Export full JSON for further processing
+headhunt --json-file https://example.com
+```
+
+### Skip Analysis (Faster)
+
+| Flag | Description |
+|------|-------------|
+| `--no-links` | Skip link analysis |
+| `--no-images` | Skip image analysis |
+
+```bash
+headhunt --no-links --no-images https://example.com
+```
+
+### Compare Two URLs
+
+```bash
+headhunt https://site-a.com --compare https://site-b.com
+```
+
+Generates a side-by-side comparison table with a declared winner.
+
+---
+
+## 📋 Example Output
+
+```
+════════════════════════════════════════════════════════════════════
+
+  TARGET   https://example.com
+  SCANNED  5/23/2026, 10:30:00 AM
+  PLATFORM WordPress
+
+────────────────────────────────────────────────────────────────────
+
+  OVERALL SEO SCORE
+
+    ██████████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░  78/100  Grade: B+
+
+  Solid SEO signals present. Primary opportunities in Image Optimization
+  and Structured Data — addressing these could meaningfully boost rankings.
+
+────────────────────────────────────────────────────────────────────
+
+  CATEGORY BREAKDOWN
+
+  ✓ Title Tag              ████████████████░░░░░░  15/15
+  ✓ Meta Description       ████████████░░░░░░░░░░  10/12
+  ~ Heading Structure      ████████░░░░░░░░░░░░░░   6/10
+  ✓ Canonical URL          █████░░░░░░░░░░░░░░░░░   5/5
+  ...
+
+  QUICK STATS
+
+  Title                        "Example Domain — A pla..." (47c)
+  Meta Description             155 chars
+  Canonical                    Present
+  H1 Tags                      1 (ideal)
+  Word Count                   ~1,240 words (7 min read)
+  Images                       12 total, 67% have alt
+  HTTPS                        Yes
+  Response Time                420ms
+
+  RECOMMENDATIONS  (7 items)
+
+  01. ● HIGH      Image Optimization
+      Issue: 4 image(s) missing alt text (33% uncovered).
+      Fix:  Add descriptive alt attributes to all meaningful images...
+
+  02. ● MEDIUM    Structured Data
+      Issue: No structured data (schema.org) found.
+      Fix:  Implement JSON-LD structured data appropriate to your content type...
+
+════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+HeadHuntSEO
+├── Fetch Engine       → axios with custom headers & redirect handling
+├── Parser Layer       → cheerio for fast server-side HTML parsing
+├── Extractors         → modular metadata, schema, link, image, content
+├── Scoring Engine     → weighted rubric across 14 SEO categories
+├── Recommendations    → priority-ranked, impact/effort tagged advice
+└── Display Engine     → ANSI-colored terminal reports & JSON serializers
+```
+
+---
+
+## 🔧 Development
+
+```bash
+# Clone & setup
+git clone https://github.com/imharris24/HeadHunt.git
+cd HeadHunt
+npm install
+
+# Run locally
+node headhunt.js https://example.com --audit
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+---
+
+## 🗺️ Roadmap
+
+| Feature | Status |
+|---------|--------|
+| Core metadata extraction | ✅ |
+| Intelligent scoring engine | ✅ |
+| Terminal reporting | ✅ |
+| JSON export modes | ✅ |
+| URL comparison | ✅ |
+| npm global install | ✅ |
+| **JavaScript rendering** (Puppeteer/Playwright) | 🚧 |
+| **Bulk URL processing** | 🚧 |
+| **Broken link checking** | 🚧 |
+| **CSV / Markdown export** | 🚧 |
+| **Proxy & bot-protection bypass** | 🚧 |
+| **Core Web Vitals integration** | 🚧 |
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🐛 Support
+
+Found a bug or have a feature request? Please [open an issue](https://github.com/imharris24/HeadHunt/issues).
+
+Built with 💻 by [imharris24](https://github.com/imharris24)

package/headhunt.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+const SEOScraper = require('./src/scraper');
+const main = require('./src/cli');
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = SEOScraper;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "headhunt",
+  "version": "1.0.0",
+  "description": "The terminal-first SEO metadata hunter. Scrape, structure, and visualize website <head> tags in JSON format.",
+  "main": "headhunt.js",
+  "bin": {
+    "headhunt": "./headhunt.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imharris24/HeadHunt-CLI.git"
+  },
+  "keywords": [
+    "seo",
+    "scraper",
+    "cli",
+    "metadata",
+    "open-graph",
+    "seo-audit",
+    "headhunt"
+  ],
+  "author": "imharris24",
+  "license": "MIT",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/imharris24/HeadHunt-CLI/issues"
+  },
+  "homepage": "https://github.com/imharris24/HeadHunt-CLI#readme",
+  "dependencies": {
+    "axios": "^1.13.2",
+    "cheerio": "^1.1.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,114 @@
+const { URL } = require('url');
+const fs = require('fs');
+const { fmt } = require('./colors');
+const SEOScraper = require('./scraper');
+const { printBanner, printReport, printComparison } = require('./reporter');
+
+async function main() {
+    const args = process.argv.slice(2);
+
+    if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+        printBanner();
+        console.log(`  ${fmt.bold('USAGE')}`);
+        console.log(`  headhunt [options] <url>`);
+        console.log();
+        console.log(`  ${fmt.bold('OPTIONS')}`);
+        console.log(`  ${fmt.cyan('--json')}          Output raw JSON to stdout`);
+        console.log(`  ${fmt.cyan('--json-file')}     Save full JSON report to file`);
+        console.log(`  ${fmt.cyan('--no-links')}      Skip link crawl (faster)`);
+        console.log(`  ${fmt.cyan('--no-images')}     Skip image analysis`);
+        console.log(`  ${fmt.cyan('--score-only')}    Print score and grade only`);
+        console.log(`  ${fmt.cyan('--audit')}         Full recommendations with impact/effort`);
+        console.log(`  ${fmt.cyan('--compare <url>')} Compare two URLs side by side`);
+        console.log();
+        process.exit(0);
+    }
+
+    const options = {
+        json: args.includes('--json'),
+        jsonFile: args.includes('--json-file'),
+        noLinks: args.includes('--no-links'),
+        noImages: args.includes('--no-images'),
+        scoreOnly: args.includes('--score-only'),
+        audit: args.includes('--audit'),
+    };
+
+    const compareIdx = args.indexOf('--compare');
+    const compareUrl = compareIdx !== -1 ? args[compareIdx + 1] : null;
+
+    const urls = args.filter(a => !a.startsWith('--') && a !== compareUrl && (a.startsWith('http://') || a.startsWith('https://')));
+
+    if (urls.length === 0) {
+        console.error(fmt.red('  \u2717  No valid URL provided. URLs must start with http:// or https://'));
+        process.exit(1);
+    }
+
+    const targetUrl = urls[0];
+
+    try { new URL(targetUrl); } catch { console.error(fmt.red('  \u2717  Invalid URL.')); process.exit(1); }
+
+    if (!options.json && !options.scoreOnly) printBanner();
+
+    try {
+        if (!compareUrl) {
+            const scraper = new SEOScraper(targetUrl, options);
+            if (!options.json && !options.scoreOnly) console.log(`  ${fmt.bold('SCANNING...')}\n`);
+            await scraper.fetchPage();
+            await scraper.analyze();
+            const meta = scraper.metadata;
+
+            if (options.json) {
+                console.log(JSON.stringify(meta, null, 2));
+                return;
+            }
+
+            if (options.scoreOnly) {
+                console.log(`Score: ${meta.overallScore}/100  Grade: ${meta.grade}`);
+                return;
+            }
+
+            printReport(meta, options);
+
+            if (options.jsonFile) {
+                const fname = `seo-report-${new URL(targetUrl).hostname}-${Date.now()}.json`;
+                fs.writeFileSync(fname, JSON.stringify(meta, null, 2));
+                console.log(`  ${fmt.green('\u2713')}  JSON report saved \u2192 ${fmt.cyan(fname)}`);
+                console.log();
+            }
+        } else {
+            try { new URL(compareUrl); } catch { console.error(fmt.red('  \u2717  Invalid compare URL.')); process.exit(1); }
+
+            console.log(`  ${fmt.bold('SCANNING A...')}\n`);
+            const scraperA = new SEOScraper(targetUrl, options);
+            await scraperA.fetchPage();
+            await scraperA.analyze();
+
+            console.log();
+            console.log(`  ${fmt.bold('SCANNING B...')}\n`);
+            const scraperB = new SEOScraper(compareUrl, options);
+            await scraperB.fetchPage();
+            await scraperB.analyze();
+
+            console.log();
+            printComparison(scraperA.metadata, scraperB.metadata);
+
+            if (options.jsonFile) {
+                const fname = `seo-compare-${Date.now()}.json`;
+                fs.writeFileSync(fname, JSON.stringify({ a: scraperA.metadata, b: scraperB.metadata }, null, 2));
+                console.log(`  ${fmt.green('\u2713')}  Comparison JSON saved \u2192 ${fmt.cyan(fname)}`);
+            }
+        }
+    } catch (error) {
+        console.error(`\n  ${fmt.red('\u2717  Error:')} ${error.message}`);
+        if (error.code === 'ECONNREFUSED') console.error(fmt.dim('     Connection refused \u2014 is the server running?'));
+        if (error.code === 'ETIMEDOUT') console.error(fmt.dim('     Request timed out \u2014 try again or check network.'));
+        if (error.response?.status === 403) console.error(fmt.dim('     403 Forbidden \u2014 server is blocking automated requests.'));
+        process.exit(1);
+    }
+}
+
+if (require.main === module) {
+    main();
+}
+
+module.exports = main;

package/src/colors.js

@@ -0,0 +1,50 @@
+const C = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+
+    black: '\x1b[30m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    cyan: '\x1b[36m',
+    white: '\x1b[37m',
+    gray: '\x1b[90m',
+
+    bgRed: '\x1b[41m',
+    bgGreen: '\x1b[42m',
+    bgYellow: '\x1b[43m',
+    bgBlue: '\x1b[44m',
+    bgMagenta: '\x1b[45m',
+    bgCyan: '\x1b[46m',
+
+    brightRed: '\x1b[91m',
+    brightGreen: '\x1b[92m',
+    brightYellow: '\x1b[93m',
+    brightBlue: '\x1b[94m',
+    brightMagenta: '\x1b[95m',
+    brightCyan: '\x1b[96m',
+    brightWhite: '\x1b[97m',
+};
+
+const fmt = {
+    bold: (s) => `${C.bold}${s}${C.reset}`,
+    dim: (s) => `${C.dim}${s}${C.reset}`,
+    green: (s) => `${C.green}${s}${C.reset}`,
+    red: (s) => `${C.red}${s}${C.reset}`,
+    yellow: (s) => `${C.yellow}${s}${C.reset}`,
+    cyan: (s) => `${C.cyan}${s}${C.reset}`,
+    magenta: (s) => `${C.magenta}${s}${C.reset}`,
+    blue: (s) => `${C.blue}${s}${C.reset}`,
+    gray: (s) => `${C.gray}${s}${C.reset}`,
+    brightGreen: (s) => `${C.brightGreen}${s}${C.reset}`,
+    brightRed: (s) => `${C.brightRed}${s}${C.reset}`,
+    brightYellow: (s) => `${C.brightYellow}${s}${C.reset}`,
+    brightCyan: (s) => `${C.brightCyan}${s}${C.reset}`,
+};
+
+module.exports = { C, fmt };

package/src/constants.js

@@ -0,0 +1,31 @@
+const https = require('https');
+
+const httpsAgent = new https.Agent({ rejectUnauthorized: false });
+const USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+const SCORE_WEIGHTS = {
+    title: { max: 15, label: 'Title Tag' },
+    description: { max: 12, label: 'Meta Description' },
+    headings: { max: 10, label: 'Heading Structure' },
+    canonical: { max: 5, label: 'Canonical URL' },
+    robots: { max: 3, label: 'Robots Meta' },
+    openGraph: { max: 8, label: 'Open Graph Tags' },
+    twitterCard: { max: 5, label: 'Twitter Card' },
+    schema: { max: 8, label: 'Structured Data' },
+    images: { max: 8, label: 'Image Optimization' },
+    mobile: { max: 5, label: 'Mobile Readiness' },
+    performance: { max: 7, label: 'Page Performance' },
+    links: { max: 5, label: 'Link Structure' },
+    security: { max: 5, label: 'Security Signals' },
+    content: { max: 4, label: 'Content Quality' },
+};
+
+const PRIORITY = {
+    CRITICAL: { label: '\u{1F534} CRITICAL', color: '\x1b[91m' },
+    HIGH: { label: '\u{1F7E0} HIGH', color: '\x1b[33m' },
+    MEDIUM: { label: '\u{1F7E1} MEDIUM', color: '\x1b[93m' },
+    LOW: { label: '\u{1F535} LOW', color: '\x1b[36m' },
+    GOOD: { label: '\u2705 PASSED', color: '\x1b[92m' },
+};
+
+module.exports = { httpsAgent, USER_AGENT, SCORE_WEIGHTS, PRIORITY };

package/src/logger.js

@@ -0,0 +1,10 @@
+const { fmt } = require('./colors');
+
+const log = {
+    info: (msg) => console.log(`  ${fmt.blue('\u2139')}  ${msg}`),
+    ok: (msg) => console.log(`  ${fmt.green('\u2713')}  ${fmt.dim(msg)}`),
+    warn: (msg) => console.log(`  ${fmt.yellow('\u26A0')}  ${msg}`),
+    err: (msg) => console.log(`  ${fmt.red('\u2717')}  ${msg}`),
+};
+
+module.exports = log;