auditkit 0.1.0

package/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "auditkit"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+anyhow = "1.0"
+chrono = { version = "0.4", default-features = false, features = ["clock"] }
+clap = { version = "4.5", features = ["derive"] }
+colored = "3.0"
+indicatif = "0.18"
+regex = "1.12"
+reqwest = { version = "0.12", features = ["blocking", "rustls-tls"], default-features = false }
+serde_json = "1.0"
+url = "2.5"
+
+[dev-dependencies]
+tempfile = "3.23"

package/README.md

@@ -0,0 +1,153 @@
+# Audit Kit
+
+Local hybrid CLI for agency website audits.
+
+Rust runs the core workflow: audit folders, quick HTML checks, security checks, and report generation. Node is used only for Lighthouse because Lighthouse is a Node tool.
+
+## Install
+
+Global install from npm/Bun:
+
+```bash
+bun install -g auditkit
+```
+
+NPM also works:
+
+```bash
+npm install -g auditkit
+```
+
+Run without installing globally:
+
+```bash
+bunx auditkit --help
+```
+
+Local development install from this project folder:
+
+```bash
+npm install
+npm link
+```
+
+Prerequisites:
+
+- Rust toolchain with `cargo`
+- Node.js 24+
+- Helium, Chrome, Chromium, Brave, or Edge for Lighthouse
+
+## Basic Workflow
+
+```bash
+ak new
+ak inspect latest
+ak report latest
+```
+
+`ak new` creates a workspace in `audits/`. Fill in:
+
+- `findings.md`
+- `scorecard.md`
+- `pages/*.md`
+- `raw-notes.md`
+
+Then `ak report latest` creates:
+
+- `final-report.md`
+- `client-email.md`
+
+## Commands
+
+- `ak new` - create a new audit folder
+- `ak check latest` - run automated feedback for the latest audit and save it
+- `ak security latest` - run security header check for the latest audit and save it
+- `ak lighthouse latest` - run Lighthouse for the latest audit and save markdown + JSON
+- `ak inspect latest` - run automated feedback, security, and Lighthouse
+- `ak check <url>` - fetch a website and print quick feedback
+- `ak security <url>` - fetch a website and print security feedback
+- `ak lighthouse <url>` - run Lighthouse for a website
+- `ak check <url> --save <audit-folder>` - fetch a website and save feedback into an audit
+- `ak security <url> --save <audit-folder>` - save security feedback into an audit
+- `ak lighthouse <url> --save <audit-folder>` - save Lighthouse output into an audit
+- `ak report latest` - generate `final-report.md` and `client-email.md`
+- `ak list` - list existing audits
+
+Long form also works:
+
+- `auditkit new`
+- `auditkit check latest`
+- `auditkit report latest`
+- `auditkit list`
+
+NPM scripts:
+
+- `npm run audit -- new` - create a new audit folder
+- `npm run audit -- check latest` - run automated feedback for the latest audit and save it
+- `npm run audit -- check <url>` - fetch a website and print quick feedback
+- `npm run audit -- check <url> --save <audit-folder>` - fetch a website and save feedback into an audit
+- `npm run audit -- report latest` - generate `final-report.md` and `client-email.md`
+- `npm run audit -- list` - list existing audits
+
+## Quick Website Check
+
+```bash
+ak check https://example.com
+```
+
+The check is intentionally lightweight. It reviews basic HTML signals:
+
+- title tag
+- meta description
+- H1 count
+- image alt text
+- viewport tag
+- canonical link
+- obvious CTA language
+- initial response time and HTML size
+
+## Lighthouse Requirement
+
+`ak lighthouse` and `ak inspect` need a Chrome-family browser installed:
+
+- Helium
+- Google Chrome
+- Chromium
+- Brave
+- Microsoft Edge
+
+If none is installed, Lighthouse cannot run.
+
+Audit Kit auto-detects Helium at:
+
+```text
+/Applications/Helium.app/Contents/MacOS/Helium
+```
+
+Override browser path when needed:
+
+```bash
+AUDITKIT_BROWSER_PATH="/path/to/browser" ak lighthouse https://example.com
+```
+
+## Development
+
+Run all tests:
+
+```bash
+npm test
+```
+
+Rust-only:
+
+```bash
+cargo test
+```
+
+Node Lighthouse helper only:
+
+```bash
+npm run test:node
+```
+
+Architecture notes live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

package/auditkit.config.json

@@ -0,0 +1,10 @@
+{
+  "agencyName": "Origin",
+  "auditorName": "Daniel White",
+  "defaultCurrency": "GBP",
+  "services": {
+    "audit": "Starting at £299",
+    "refresh": "Starting at £1,999",
+    "growth": "Starting at £499/mo"
+  }
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,44 @@
+# Architecture
+
+Audit Kit is a hybrid CLI.
+
+## Rust Core
+
+Rust owns the workflow that should be fast, predictable, and easy to inspect:
+
+- command routing
+- audit folder creation
+- HTML checks
+- security header checks
+- report and email generation
+- terminal output
+
+Rust source lives in `src/`.
+
+## Node Lighthouse Helper
+
+Lighthouse is a Node ecosystem tool, so Audit Kit keeps that part in Node:
+
+- `scripts/lighthouse.mjs`
+- `scripts/auditkit/lighthouse-runner.mjs`
+
+Rust calls the Node helper as a subprocess only when running:
+
+```bash
+ak lighthouse latest
+ak inspect latest
+```
+
+## Module Map
+
+- `src/main.rs`: command router
+- `src/audit.rs`: audit input helpers
+- `src/workspace.rs`: paths, generated audit files, folder lookup
+- `src/templates.rs`: starter markdown files
+- `src/html_check.rs`: lightweight HTML feedback
+- `src/security.rs`: security header feedback
+- `src/report.rs`: final report and client email
+- `src/lighthouse.rs`: bridge to the Node Lighthouse helper
+- `src/ui.rs`: terminal output helpers
+
+The code is intentionally plain. Each file owns one small part of the workflow.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "auditkit",
+  "version": "0.1.0",
+  "description": "Local hybrid CLI for agency website audits.",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "auditkit": "scripts/auditkit/ak",
+    "ak": "scripts/auditkit/ak"
+  },
+  "files": [
+    "Cargo.toml",
+    "Cargo.lock",
+    "src/",
+    "scripts/auditkit/",
+    "auditkit.config.json",
+    "docs/ARCHITECTURE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "audit": "cargo run --quiet --",
+    "audit:new": "cargo run --quiet -- new",
+    "audit:list": "cargo run --quiet -- list",
+    "audit:check": "cargo run --quiet -- check",
+    "audit:report": "cargo run --quiet -- report",
+    "audit:security": "cargo run --quiet -- security",
+    "audit:lighthouse": "cargo run --quiet -- lighthouse",
+    "audit:inspect": "cargo run --quiet -- inspect",
+    "postinstall": "node scripts/auditkit/postinstall.mjs",
+    "site:dev": "npm --prefix site run dev",
+    "site:build": "npm --prefix site run build",
+    "site:preview": "npm --prefix site run preview",
+    "test": "npm run test:node && npm run test:rust",
+    "test:node": "node --test",
+    "test:rust": "cargo test"
+  },
+  "dependencies": {
+    "chrome-launcher": "^1.2.1",
+    "lighthouse": "^13.3.0"
+  }
+}

package/scripts/auditkit/ak

@@ -0,0 +1,22 @@
+#!/usr/bin/env sh
+set -eu
+
+SOURCE="$0"
+while [ -L "$SOURCE" ]; do
+  DIR="$(CDPATH= cd -- "$(dirname -- "$SOURCE")" && pwd)"
+  TARGET="$(readlink "$SOURCE")"
+  case "$TARGET" in
+    /*) SOURCE="$TARGET" ;;
+    *) SOURCE="$DIR/$TARGET" ;;
+  esac
+done
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$SOURCE")" && pwd)"
+ROOT_DIR="$(CDPATH= cd -- "$SCRIPT_DIR/../.." && pwd)"
+BINARY="$ROOT_DIR/target/debug/auditkit"
+
+if [ ! -x "$BINARY" ]; then
+  cargo build --manifest-path "$ROOT_DIR/Cargo.toml" >/dev/null
+fi
+
+exec "$BINARY" "$@"

package/scripts/auditkit/lighthouse-runner.mjs

@@ -0,0 +1,183 @@
+import { existsSync } from "node:fs";
+
+const opportunityIds = [
+  "render-blocking-resources",
+  "unused-javascript",
+  "unused-css-rules",
+  "uses-optimized-images",
+  "modern-image-formats",
+  "uses-responsive-images",
+  "unminified-javascript",
+  "unminified-css",
+  "uses-text-compression",
+  "server-response-time",
+  "redirects",
+  "bootup-time",
+  "mainthread-work-breakdown",
+  "third-party-summary",
+];
+
+const browserCandidates = [
+  "/Applications/Helium.app/Contents/MacOS/Helium",
+  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+  "/Applications/Chromium.app/Contents/MacOS/Chromium",
+  "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+  "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+];
+
+function section(title) {
+  return `\n== ${title} ==`;
+}
+
+function formatKeyValue(label, value) {
+  return `${label}: ${value}`;
+}
+
+function bullet(value) {
+  return `- ${value}`;
+}
+
+export function findBrowserPath({ env = process.env, config = {}, exists = existsSync } = {}) {
+  const candidates = [
+    config.browserPath,
+    env.AUDITKIT_BROWSER_PATH,
+    env.CHROME_PATH,
+    ...browserCandidates,
+  ].filter(Boolean);
+
+  return candidates.find((candidate) => exists(candidate)) ?? null;
+}
+
+function categoryScore(category) {
+  if (!category || typeof category.score !== "number") {
+    return null;
+  }
+
+  return Math.round(category.score * 100);
+}
+
+function auditDisplayValue(audits, id) {
+  return audits?.[id]?.displayValue ?? "n/a";
+}
+
+export function summarizeLighthouse(lhr) {
+  const audits = lhr.audits ?? {};
+  const opportunities = opportunityIds
+    .map((id) => ({ id, ...audits[id] }))
+    .filter((audit) => audit.title && typeof audit.score === "number" && audit.score < 0.9)
+    .slice(0, 6)
+    .map((audit) => ({
+      id: audit.id,
+      title: audit.title,
+      score: Math.round(audit.score * 100),
+      displayValue: audit.displayValue ?? "",
+      description: audit.description ?? "",
+    }));
+
+  return {
+    url: lhr.finalDisplayedUrl ?? lhr.finalUrl ?? "",
+    scores: {
+      performance: categoryScore(lhr.categories?.performance),
+      accessibility: categoryScore(lhr.categories?.accessibility),
+      bestPractices: categoryScore(lhr.categories?.["best-practices"]),
+      seo: categoryScore(lhr.categories?.seo),
+    },
+    vitals: {
+      lcp: auditDisplayValue(audits, "largest-contentful-paint"),
+      cls: auditDisplayValue(audits, "cumulative-layout-shift"),
+      tbt: auditDisplayValue(audits, "total-blocking-time"),
+    },
+    opportunities,
+  };
+}
+
+export function formatLighthouseCli(summary) {
+  return [
+    section("Lighthouse Check"),
+    formatKeyValue("URL", summary.url),
+    formatKeyValue("Performance", `${summary.scores.performance ?? "n/a"}/100`),
+    formatKeyValue("Accessibility", `${summary.scores.accessibility ?? "n/a"}/100`),
+    formatKeyValue("Best practices", `${summary.scores.bestPractices ?? "n/a"}/100`),
+    formatKeyValue("SEO", `${summary.scores.seo ?? "n/a"}/100`),
+    section("Vitals"),
+    formatKeyValue("LCP", summary.vitals.lcp),
+    formatKeyValue("CLS", summary.vitals.cls),
+    formatKeyValue("TBT", summary.vitals.tbt),
+    section("Top Opportunities"),
+    ...(summary.opportunities.length
+      ? summary.opportunities.map((item) => bullet(`${item.title}${item.displayValue ? ` — ${item.displayValue}` : ""}`))
+      : [bullet("No major Lighthouse opportunities found.")]),
+  ].join("\n");
+}
+
+export function formatLighthouseReport(summary) {
+  return `# Lighthouse Check
+
+URL: ${summary.url}
+
+## Scores
+
+- Performance: ${summary.scores.performance ?? "n/a"}/100
+- Accessibility: ${summary.scores.accessibility ?? "n/a"}/100
+- Best practices: ${summary.scores.bestPractices ?? "n/a"}/100
+- SEO: ${summary.scores.seo ?? "n/a"}/100
+
+## Core Web Vitals
+
+- LCP: ${summary.vitals.lcp}
+- CLS: ${summary.vitals.cls}
+- TBT: ${summary.vitals.tbt}
+
+## Top Opportunities
+
+${
+  summary.opportunities.length
+    ? summary.opportunities
+        .map((item) => `- ${item.title}${item.displayValue ? `: ${item.displayValue}` : ""}`)
+        .join("\n")
+    : "- No major Lighthouse opportunities found."
+}
+`;
+}
+
+export async function runLighthouse(inputUrl, options = {}) {
+  const [{ default: lighthouse }, chromeLauncher] = await Promise.all([
+    import("lighthouse"),
+    import("chrome-launcher"),
+  ]);
+
+  const browserPath = findBrowserPath({ config: options });
+  let chrome;
+
+  try {
+    chrome = await chromeLauncher.launch({
+      chromePath: browserPath ?? undefined,
+      chromeFlags: ["--headless", "--no-sandbox", "--disable-gpu"],
+    });
+  } catch (error) {
+    if (String(error.message).includes("No Chrome installations found")) {
+      throw new Error(
+        "No Chrome-compatible browser found. Install Chrome/Chromium/Brave/Edge, or set AUDITKIT_BROWSER_PATH.",
+      );
+    }
+
+    throw error;
+  }
+
+  try {
+    const result = await lighthouse(inputUrl, {
+      port: chrome.port,
+      output: "json",
+      onlyCategories: ["performance", "accessibility", "best-practices", "seo"],
+    });
+
+    const lhr = result.lhr;
+    return {
+      lhr,
+      json: JSON.stringify(lhr, null, 2),
+      summary: summarizeLighthouse(lhr),
+    };
+  } finally {
+    await chrome.kill();
+  }
+}

package/scripts/auditkit/lighthouse.test.mjs

@@ -0,0 +1,78 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  findBrowserPath,
+  formatLighthouseReport,
+  summarizeLighthouse,
+} from "./lighthouse-runner.mjs";
+
+const lhr = {
+  finalDisplayedUrl: "https://example.com/",
+  categories: {
+    performance: { score: 0.87 },
+    accessibility: { score: 0.92 },
+    "best-practices": { score: 0.78 },
+    seo: { score: 1 },
+  },
+  audits: {
+    "largest-contentful-paint": { displayValue: "1.8 s" },
+    "cumulative-layout-shift": { displayValue: "0.02" },
+    "total-blocking-time": { displayValue: "120 ms" },
+    "render-blocking-resources": {
+      title: "Eliminate render-blocking resources",
+      description: "Resources are blocking first paint.",
+      score: 0.4,
+      displayValue: "Potential savings of 350 ms",
+    },
+    "uses-optimized-images": {
+      title: "Efficiently encode images",
+      description: "Images could be smaller.",
+      score: 0.7,
+      displayValue: "Potential savings of 120 KiB",
+    },
+  },
+};
+
+test("summarizeLighthouse extracts scores, vitals, and opportunities", () => {
+  const summary = summarizeLighthouse(lhr);
+
+  assert.deepEqual(summary.scores, {
+    performance: 87,
+    accessibility: 92,
+    bestPractices: 78,
+    seo: 100,
+  });
+  assert.equal(summary.vitals.lcp, "1.8 s");
+  assert.equal(summary.opportunities.length, 2);
+  assert.equal(summary.opportunities[0].title, "Eliminate render-blocking resources");
+});
+
+test("formatLighthouseReport renders markdown summary", () => {
+  const report = formatLighthouseReport(summarizeLighthouse(lhr));
+
+  assert.match(report, /# Lighthouse Check/);
+  assert.match(report, /Performance: 87\/100/);
+  assert.match(report, /Eliminate render-blocking resources/);
+});
+
+test("findBrowserPath prefers explicit config path", () => {
+  assert.equal(
+    findBrowserPath({
+      env: {},
+      config: { browserPath: "/Applications/Helium.app/Contents/MacOS/Helium" },
+      exists: () => true,
+    }),
+    "/Applications/Helium.app/Contents/MacOS/Helium",
+  );
+});
+
+test("findBrowserPath falls back to Helium app path", () => {
+  assert.equal(
+    findBrowserPath({
+      env: {},
+      config: {},
+      exists: (value) => value === "/Applications/Helium.app/Contents/MacOS/Helium",
+    }),
+    "/Applications/Helium.app/Contents/MacOS/Helium",
+  );
+});

package/scripts/auditkit/postinstall.mjs

@@ -0,0 +1,31 @@
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+
+const cyan = (value) => (useColor ? `\x1b[36m${value}\x1b[0m` : value);
+const green = (value) => (useColor ? `\x1b[32m${value}\x1b[0m` : value);
+const bold = (value) => (useColor ? `\x1b[1m${value}\x1b[0m` : value);
+const dim = (value) => (useColor ? `\x1b[2m${value}\x1b[0m` : value);
+
+const width = 54;
+const edge = cyan("│");
+const boxLine = (value = "", format = (text) => text) => {
+  const padded = value.padEnd(width - 4, " ");
+  return `${edge} ${format(value)}${" ".repeat(padded.length - value.length)} ${edge}`;
+};
+
+const lines = [
+  "",
+  cyan(`┌${"─".repeat(width - 2)}┐`),
+  boxLine("Welcome to Audit Kit", bold),
+  boxLine("Local audits, Lighthouse, and security checks."),
+  cyan(`└${"─".repeat(width - 2)}┘`),
+  "",
+  `${green("Next steps")}`,
+  `  ${bold("ak new")}                 create audit workspace`,
+  `  ${bold("ak inspect latest")}      run checks for latest audit`,
+  `  ${bold("ak report latest")}       generate final report`,
+  "",
+  `${dim("Tip: first run builds the Rust CLI, so it may take a few seconds.")}`,
+  "",
+];
+
+console.log(lines.join("\n"));

package/src/audit.rs

@@ -0,0 +1,59 @@
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuditInput {
+    pub client_name: String,
+    pub slug: String,
+    pub url: String,
+    pub business_type: String,
+    pub goal: String,
+    pub target_customer: String,
+    pub conversion_action: String,
+    pub pages: Vec<String>,
+    pub known_concerns: Vec<String>,
+    pub competitors: Vec<String>,
+    pub created_at: String,
+}
+
+pub fn slugify(value: &str) -> String {
+    let mut slug = String::new();
+    let mut previous_dash = false;
+
+    for character in value.trim().to_lowercase().chars() {
+        if character.is_ascii_alphanumeric() {
+            slug.push(character);
+            previous_dash = false;
+        } else if !previous_dash {
+            slug.push('-');
+            previous_dash = true;
+        }
+    }
+
+    slug.trim_matches('-').to_string()
+}
+
+pub fn split_comma_list(value: &str) -> Vec<String> {
+    value
+        .split(',')
+        .map(str::trim)
+        .filter(|item| !item.is_empty())
+        .map(ToOwned::to_owned)
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn slugify_makes_folder_safe_names() {
+        assert_eq!(slugify("Acme Dental Ltd"), "acme-dental-ltd");
+        assert_eq!(slugify("  My Kind_of Cruise! "), "my-kind-of-cruise");
+    }
+
+    #[test]
+    fn split_comma_list_ignores_empty_items() {
+        assert_eq!(
+            split_comma_list("/, /pricing, , /contact"),
+            vec!["/", "/pricing", "/contact"]
+        );
+    }
+}