squirrelscan 0.0.17

package/README.md

@@ -0,0 +1,148 @@
+![squirrelscan](https://mintcdn.com/squirrelscan/CCMTmLbI4xfnpJbQ/logo/light.svg?fit=max&auto=format&n=CCMTmLbI4xfnpJbQ&q=85&s=1303484a4ea3c154c29dd5f6245e55cd)
+
+# squirrelscan
+
+**CLI Website Audits for Humans, Agents & LLMs**
+
+A comprehensive website audit tool for SEO, performance, accessibility, content, and more. Built from the ground up for AI coding agents and developer workflows.
+
+## Features
+
+- **149+ Audit Rules** across 20 categories (SEO, accessibility, performance, security, E-E-A-T)
+- **AI-Native Design** with LLM-optimized output formats for Claude Code, Cursor, and other agents
+- **Smart Incremental Crawling** with ETag, Last-Modified, and content hashing
+- **Multiple Output Formats** including console, JSON, HTML reports, and text for piping to LLMs
+- **Single Binary** with zero dependencies
+- **Shell Completions** for bash, zsh, fish
+- **Self-Updating** with built-in version management
+
+## Three Ways to Use
+
+### 1. CLI for Humans
+
+Run audits directly in your terminal:
+
+```bash
+squirrel audit example.com
+```
+
+### 2. Pipe to AI
+
+Pipe clean output to any AI assistant:
+
+```bash
+squirrel audit example.com --format text | claude
+```
+
+### 3. AI Agent Skill
+
+Install the skill for autonomous workflows:
+
+```bash
+npx skills install squirrelscan/skills
+```
+
+Then prompt your AI agent:
+```
+Use the audit-website skill to audit this site and fix all issues
+```
+
+## Installation
+
+**npm (all platforms):**
+```bash
+npm install -g squirrelscan
+```
+
+Or run without installing:
+```bash
+npx squirrelscan audit example.com
+```
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://squirrelscan.com/install | bash
+```
+
+**Windows:**
+```powershell
+iwr -useb https://squirrelscan.com/install.ps1 | iex
+```
+
+## Quick Start
+
+```bash
+# Audit a website
+squirrel audit https://example.com
+
+# Generate HTML report
+squirrel audit https://example.com -f html -o report.html
+
+# Pipe to Claude for AI analysis
+squirrel audit https://example.com --format text | claude
+
+# Limit pages for faster results
+squirrel audit https://example.com -m 10
+```
+
+## Resources
+
+- **Website:** [squirrelscan.com](https://squirrelscan.com)
+- **Documentation:** [docs.squirrelscan.com](https://docs.squirrelscan.com)
+- **AI Agent Skills:** [github.com/squirrelscan/skills](https://github.com/squirrelscan/skills)
+
+## Rule Categories
+
+| Category | Examples |
+|----------|----------|
+| **Core SEO** | Meta tags, canonical URLs, h1, robots meta |
+| **Accessibility** | ARIA labels, focus indicators, landmarks |
+| **Performance** | Core Web Vitals (LCP, CLS, INP) |
+| **Security** | HTTPS, CSP, leaked secrets (96 patterns) |
+| **E-E-A-T** | Author bylines, expertise signals, trust indicators |
+| **Content** | Word count, readability, freshness |
+| **Images** | Alt text, modern formats, lazy loading |
+| **Links** | Broken links, redirect chains, anchor text |
+| **Schema** | JSON-LD structured data validation |
+| **Mobile** | Viewport, tap targets, responsive design |
+
+And 10 more categories covering video, analytics, i18n, local SEO, and more.
+
+## AI Agent Integration
+
+squirrelscan is designed for autonomous AI workflows:
+
+```bash
+# Install the skill for Claude Code, Cursor, etc.
+npx skills install squirrelscan/skills
+```
+
+Example AI prompts:
+- "Use the audit-website skill to audit example.com and fix all high-severity issues"
+- "Audit this site, enter plan mode, and create a comprehensive fix strategy"
+- "Use audit-website skill to check for regressions after my recent changes"
+
+See [AI Agent Integration docs](https://docs.squirrelscan.com/agents) for advanced workflows.
+
+## Output Formats
+
+| Format | Flag | Use Case |
+|--------|------|----------|
+| Console | (default) | Human-readable terminal output |
+| JSON | `-f json` | CI/CD, programmatic processing |
+| HTML | `-f html` | Visual reports for sharing |
+| Markdown | `-f markdown` | Documentation, GitHub |
+| Text | `-f text` | Clean output for piping to LLMs |
+
+## Development Status
+
+squirrelscan is in **active beta**. Expect rapid iteration and breaking changes. Feedback and issue reports welcome!
+
+## Links
+
+- [Website](https://squirrelscan.com)
+- [Documentation](https://docs.squirrelscan.com)
+- [AI Agent Skills](https://github.com/squirrelscan/skills)
+- [Share Feedback](https://squirrelscan.com/feedback)
+- [Bugs, Issues & Feature Requests](https://github.com/squirrelscan/squirrelscan/issues)
+- [Twitter/X](https://x.com/squirrelscan_)

package/bin/squirrel.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * squirrel CLI wrapper
+ * Executes the platform-specific binary downloaded during npm install
+ */
+
+const { execFileSync, spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+const { getBinaryExtension } = require("../lib/platform");
+
+const binaryName = `squirrel${getBinaryExtension()}`;
+const binaryPath = path.join(__dirname, binaryName);
+
+// Check if binary exists
+if (!fs.existsSync(binaryPath)) {
+  console.error("Error: squirrelscan binary not found.");
+  console.error("");
+  console.error("The binary should have been downloaded during npm install.");
+  console.error("Try reinstalling: npm install -g squirrelscan");
+  console.error("");
+  console.error("Or install directly:");
+  console.error("  curl -fsSL https://squirrelscan.com/install | bash");
+  process.exit(1);
+}
+
+// Execute binary with all arguments
+const args = process.argv.slice(2);
+
+try {
+  // Use spawnSync for proper signal handling and stdio inheritance
+  const result = spawnSync(binaryPath, args, {
+    stdio: "inherit",
+    windowsHide: true,
+  });
+
+  // Forward exit code
+  if (result.status !== null) {
+    process.exit(result.status);
+  }
+
+  // Handle signal termination
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+} catch (err) {
+  console.error(`Error executing squirrel: ${err.message}`);
+  process.exit(1);
+}

package/lib/platform.js

@@ -0,0 +1,101 @@
+/**
+ * Platform detection for squirrelscan binary downloads
+ * Mirrors logic from install.sh
+ */
+
+const os = require("os");
+const fs = require("fs");
+
+/**
+ * Detect if running on musl libc (Alpine, etc.)
+ * @returns {boolean}
+ */
+function isMusl() {
+  // Check for musl loader
+  try {
+    const files = fs.readdirSync("/lib");
+    if (files.some((f) => f.startsWith("ld-musl-"))) {
+      return true;
+    }
+  } catch {
+    // /lib doesn't exist or not readable
+  }
+
+  // Check for Alpine
+  try {
+    if (fs.existsSync("/etc/alpine-release")) {
+      return true;
+    }
+  } catch {
+    // Not Alpine
+  }
+
+  return false;
+}
+
+/**
+ * Get platform identifier for binary download
+ * @returns {string} Platform identifier (e.g., "darwin-arm64", "linux-x64-musl")
+ */
+function getPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  let osName;
+  switch (platform) {
+    case "darwin":
+      osName = "darwin";
+      break;
+    case "linux":
+      osName = "linux";
+      break;
+    case "win32":
+      osName = "windows";
+      break;
+    default:
+      throw new Error(`Unsupported platform: ${platform}`);
+  }
+
+  let archName;
+  switch (arch) {
+    case "x64":
+      archName = "x64";
+      break;
+    case "arm64":
+      archName = "arm64";
+      break;
+    default:
+      throw new Error(`Unsupported architecture: ${arch}`);
+  }
+
+  // Add musl suffix for Linux if needed
+  const libc = osName === "linux" && isMusl() ? "-musl" : "";
+
+  return `${osName}-${archName}${libc}`;
+}
+
+/**
+ * Get binary filename for current platform
+ * @param {string} version - Version string (e.g., "0.0.17")
+ * @returns {string} Binary filename
+ */
+function getBinaryFilename(version) {
+  const platform = getPlatform();
+  const ext = os.platform() === "win32" ? ".exe" : "";
+  return `squirrel-${version}-${platform}${ext}`;
+}
+
+/**
+ * Get extension for current platform
+ * @returns {string} ".exe" on Windows, "" otherwise
+ */
+function getBinaryExtension() {
+  return os.platform() === "win32" ? ".exe" : "";
+}
+
+module.exports = {
+  getPlatform,
+  getBinaryFilename,
+  getBinaryExtension,
+  isMusl,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "squirrelscan",
+  "version": "0.0.17",
+  "description": "CLI website audits for humans, agents and LLMs",
+  "bin": {
+    "squirrel": "bin/squirrel.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/squirrelscan/squirrelscan.git"
+  },
+  "homepage": "https://squirrelscan.com",
+  "bugs": {
+    "url": "https://github.com/squirrelscan/squirrelscan/issues"
+  },
+  "keywords": [
+    "seo",
+    "audit",
+    "cli",
+    "website",
+    "llm",
+    "accessibility",
+    "performance",
+    "security",
+    "crawler"
+  ],
+  "author": "squirrelscan",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "README.md"
+  ]
+}

package/scripts/postinstall.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+
+/**
+ * postinstall script for squirrelscan npm package
+ * Downloads the platform-specific binary from GitHub releases
+ */
+
+const https = require("https");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { getPlatform, getBinaryExtension } = require("../lib/platform");
+
+const REPO = "squirrelscan/squirrelscan";
+const pkg = require("../package.json");
+const VERSION = `v${pkg.version}`;
+
+// Colors for terminal output
+const supportsColor = process.stdout.isTTY;
+const green = (s) => (supportsColor ? `\x1b[32m${s}\x1b[0m` : s);
+const yellow = (s) => (supportsColor ? `\x1b[33m${s}\x1b[0m` : s);
+const red = (s) => (supportsColor ? `\x1b[31m${s}\x1b[0m` : s);
+const blue = (s) => (supportsColor ? `\x1b[34m${s}\x1b[0m` : s);
+
+const log = (msg) => console.log(`${green("==>")} ${msg}`);
+const info = (msg) => console.log(`${blue("::")} ${msg}`);
+const warn = (msg) => console.log(`${yellow("Warning:")} ${msg}`);
+const error = (msg) => {
+  console.error(`${red("Error:")} ${msg}`);
+  process.exit(1);
+};
+
+/**
+ * HTTPS GET with redirect following
+ * @param {string} url
+ * @returns {Promise<{data: Buffer, statusCode: number}>}
+ */
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { "User-Agent": "squirrelscan-npm" } }, (res) => {
+      // Follow redirects
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return httpsGet(res.headers.location).then(resolve).catch(reject);
+      }
+
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}: ${url}`));
+        return;
+      }
+
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve({ data: Buffer.concat(chunks), statusCode: res.statusCode }));
+      res.on("error", reject);
+    });
+
+    request.on("error", reject);
+    request.setTimeout(120000, () => {
+      request.destroy();
+      reject(new Error("Request timeout"));
+    });
+  });
+}
+
+/**
+ * Fetch with retry
+ * @param {string} url
+ * @param {number} attempts
+ * @returns {Promise<Buffer>}
+ */
+async function fetchWithRetry(url, attempts = 3) {
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      const { data } = await httpsGet(url);
+      return data;
+    } catch (err) {
+      if (i < attempts) {
+        warn(`Download failed, retrying (${i}/${attempts})...`);
+        await new Promise((r) => setTimeout(r, 2000));
+      } else {
+        throw err;
+      }
+    }
+  }
+}
+
+/**
+ * Compute SHA256 hash of buffer
+ * @param {Buffer} buffer
+ * @returns {string}
+ */
+function sha256(buffer) {
+  return crypto.createHash("sha256").update(buffer).digest("hex");
+}
+
+async function main() {
+  const platform = getPlatform();
+  const binDir = path.join(__dirname, "..", "bin");
+  const binaryName = `squirrel${getBinaryExtension()}`;
+  const binaryPath = path.join(binDir, binaryName);
+
+  log(`Installing squirrelscan ${VERSION} for ${platform}...`);
+
+  // Ensure bin directory exists
+  if (!fs.existsSync(binDir)) {
+    fs.mkdirSync(binDir, { recursive: true });
+  }
+
+  // Fetch manifest
+  const releaseUrl = `https://github.com/${REPO}/releases/download/${VERSION}`;
+  const manifestUrl = `${releaseUrl}/manifest.json`;
+
+  info("Fetching manifest...");
+  let manifest;
+  try {
+    const manifestData = await fetchWithRetry(manifestUrl);
+    manifest = JSON.parse(manifestData.toString());
+  } catch (err) {
+    error(`Failed to fetch manifest: ${err.message}\n  URL: ${manifestUrl}`);
+  }
+
+  // Get binary info for platform
+  const binaryInfo = manifest.binaries?.[platform];
+  if (!binaryInfo) {
+    error(`No binary available for platform: ${platform}\n  See: https://github.com/${REPO}/releases/tag/${VERSION}`);
+  }
+
+  const { filename, sha256: expectedSha256 } = binaryInfo;
+
+  // Download binary
+  const binaryUrl = `${releaseUrl}/${filename}`;
+  info(`Downloading ${filename}...`);
+
+  let binaryData;
+  try {
+    binaryData = await fetchWithRetry(binaryUrl);
+  } catch (err) {
+    error(`Failed to download binary: ${err.message}\n  URL: ${binaryUrl}`);
+  }
+
+  // Verify checksum
+  info("Verifying checksum...");
+  const actualSha256 = sha256(binaryData);
+  if (actualSha256 !== expectedSha256) {
+    error(`Checksum mismatch!\n  Expected: ${expectedSha256}\n  Actual:   ${actualSha256}`);
+  }
+  info(`Checksum verified: ${expectedSha256.slice(0, 16)}...`);
+
+  // Write binary
+  fs.writeFileSync(binaryPath, binaryData);
+
+  // Make executable (Unix only)
+  if (process.platform !== "win32") {
+    fs.chmodSync(binaryPath, 0o755);
+  }
+
+  log("Installation complete!");
+  info(`Binary: ${binaryPath}`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});