auditkit 0.1.0 → 0.1.3

package/Cargo.toml

@@ -1,14 +1,19 @@
 [package]
 name = "auditkit"
-version = "0.1.0"
+version = "0.1.3"
 edition = "2021"
+description = "Local hybrid CLI for agency website audits."
+license = "MIT"
+repository = "https://github.com/Danilaa1/auditkit"
 
 [dependencies]
 anyhow = "1.0"
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
 clap = { version = "4.5", features = ["derive"] }
 colored = "3.0"
+crossterm = "0.29.0"
 indicatif = "0.18"
+ratatui = { version = "0.30.0", default-features = false, features = ["crossterm"] }
 regex = "1.12"
 reqwest = { version = "0.12", features = ["blocking", "rustls-tls"], default-features = false }
 serde_json = "1.0"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel
+
+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 without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+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

@@ -2,32 +2,15 @@
 
 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.
+Rust runs the core workflow: audit folders, quick HTML checks, security checks, and report generation. Node is used only for Lighthouse.
 
 ## 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:
+From this project folder:
 
 ```bash
 npm install
+cargo build
 npm link
 ```
 
@@ -48,9 +31,7 @@ ak report latest
 `ak new` creates a workspace in `audits/`. Fill in:
 
 - `findings.md`
-- `scorecard.md`
-- `pages/*.md`
-- `raw-notes.md`
+- `workspace.md`
 
 Then `ak report latest` creates:
 

package/audits/.gitkeep

@@ -0,0 +1 @@
+

package/package.json

@@ -1,26 +1,27 @@
 {
   "name": "auditkit",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Local hybrid CLI for agency website audits.",
   "type": "module",
-  "private": false,
-  "bin": {
-    "auditkit": "scripts/auditkit/ak",
-    "ak": "scripts/auditkit/ak"
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/Danilaa1/auditkit.git"
   },
   "files": [
-    "Cargo.toml",
     "Cargo.lock",
-    "src/",
-    "scripts/auditkit/",
+    "Cargo.toml",
+    "LICENSE",
+    "README.md",
     "auditkit.config.json",
-    "docs/ARCHITECTURE.md"
+    "audits/.gitkeep",
+    "docs",
+    "scripts",
+    "src"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=24"
+  "bin": {
+    "auditkit": "scripts/auditkit/ak",
+    "ak": "scripts/auditkit/ak"
   },
   "scripts": {
     "audit": "cargo run --quiet --",
@@ -32,9 +33,6 @@
     "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"

package/scripts/auditkit/ak

@@ -1,18 +1,19 @@
-#!/usr/bin/env sh
-set -eu
+#!/usr/bin/env zsh
+set -euo pipefail
 
 SOURCE="$0"
 while [ -L "$SOURCE" ]; do
-  DIR="$(CDPATH= cd -- "$(dirname -- "$SOURCE")" && pwd)"
+  DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
   TARGET="$(readlink "$SOURCE")"
-  case "$TARGET" in
-    /*) SOURCE="$TARGET" ;;
-    *) SOURCE="$DIR/$TARGET" ;;
-  esac
+  if [[ "$TARGET" == /* ]]; then
+    SOURCE="$TARGET"
+  else
+    SOURCE="$DIR/$TARGET"
+  fi
 done
 
-SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$SOURCE")" && pwd)"
-ROOT_DIR="$(CDPATH= cd -- "$SCRIPT_DIR/../.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
 BINARY="$ROOT_DIR/target/debug/auditkit"
 
 if [ ! -x "$BINARY" ]; then

package/scripts/auditkit/lighthouse-runner.mjs

@@ -25,16 +25,135 @@ const browserCandidates = [
   "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
 ];
 
-function section(title) {
-  return `\n== ${title} ==`;
+const colorEnabled = !process.env.NO_COLOR;
+
+function color(code, value) {
+  return colorEnabled ? `\x1b[${code}m${value}\x1b[0m` : value;
+}
+
+function positive(value) {
+  return color("1;32", value);
+}
+
+function warning(value) {
+  return color("1;33", value);
+}
+
+function critical(value) {
+  return color("1;31", value);
+}
+
+function frame(value) {
+  return color("1;36", value);
+}
+
+function dim(value) {
+  return color("2", value);
+}
+
+function toneIcon(tone) {
+  if (tone === "positive") {
+    return positive("✓");
+  }
+
+  if (tone === "warning") {
+    return warning("◆");
+  }
+
+  return critical("●");
+}
+
+function scoreTone(score) {
+  if (typeof score !== "number") {
+    return "warning";
+  }
+
+  if (score >= 85) {
+    return "positive";
+  }
+
+  if (score >= 65) {
+    return "warning";
+  }
+
+  return "critical";
+}
+
+function numericMetric(value) {
+  const match = String(value).match(/[0-9]+(?:\.[0-9]+)?/);
+  return match ? Number(match[0]) : null;
+}
+
+function lcpTone(value) {
+  const metric = numericMetric(value);
+  if (metric === null) {
+    return "warning";
+  }
+
+  if (metric <= 2.5) {
+    return "positive";
+  }
+
+  if (metric <= 4) {
+    return "warning";
+  }
+
+  return "critical";
 }
 
-function formatKeyValue(label, value) {
-  return `${label}: ${value}`;
+function clsTone(value) {
+  const metric = numericMetric(value);
+  if (metric === null) {
+    return "warning";
+  }
+
+  if (metric <= 0.1) {
+    return "positive";
+  }
+
+  if (metric <= 0.25) {
+    return "warning";
+  }
+
+  return "critical";
 }
 
-function bullet(value) {
-  return `- ${value}`;
+function tbtTone(value) {
+  const metric = numericMetric(value);
+  if (metric === null) {
+    return "warning";
+  }
+
+  if (metric <= 200) {
+    return "positive";
+  }
+
+  if (metric <= 600) {
+    return "warning";
+  }
+
+  return "critical";
+}
+
+function toneValue(tone, value) {
+  if (tone === "positive") {
+    return positive(value);
+  }
+
+  if (tone === "warning") {
+    return warning(value);
+  }
+
+  return critical(value);
+}
+
+function signalLine(label, value, tone) {
+  return `  ${toneIcon(tone)} ${dim(label.padEnd(21))} ${toneValue(tone, value)}`;
+}
+
+function feedbackLine(tone, value) {
+  const label = tone === "critical" ? critical("FIX") : warning("WATCH");
+  return `  ${toneIcon(tone)} ${label} ${toneValue(tone, value)}`;
 }
 
 export function findBrowserPath({ env = process.env, config = {}, exists = existsSync } = {}) {
@@ -92,21 +211,30 @@ export function summarizeLighthouse(lhr) {
 }
 
 export function formatLighthouseCli(summary) {
+  const opportunityLines = summary.opportunities.length
+    ? summary.opportunities.map((item) =>
+        feedbackLine(
+          item.score < 50 ? "critical" : "warning",
+          `${item.title}${item.displayValue ? ` — ${item.displayValue}` : ""}`,
+        ),
+      )
+    : [signalLine("Opportunities", "No major Lighthouse opportunities found.", "positive")];
+
   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.")]),
+    "",
+    frame("╭─ Lighthouse Check"),
+    `${frame("│ URL  ")} ${summary.url}`,
+    frame("╰─ Signals"),
+    signalLine("Performance", `${summary.scores.performance ?? "n/a"}/100`, scoreTone(summary.scores.performance)),
+    signalLine("Accessibility", `${summary.scores.accessibility ?? "n/a"}/100`, scoreTone(summary.scores.accessibility)),
+    signalLine("Best practices", `${summary.scores.bestPractices ?? "n/a"}/100`, scoreTone(summary.scores.bestPractices)),
+    signalLine("SEO", `${summary.scores.seo ?? "n/a"}/100`, scoreTone(summary.scores.seo)),
+    signalLine("LCP", summary.vitals.lcp, lcpTone(summary.vitals.lcp)),
+    signalLine("CLS", summary.vitals.cls, clsTone(summary.vitals.cls)),
+    signalLine("TBT", summary.vitals.tbt, tbtTone(summary.vitals.tbt)),
+    "",
+    frame("Feedback"),
+    ...opportunityLines,
   ].join("\n");
 }
 

package/scripts/auditkit/lighthouse.test.mjs

@@ -5,6 +5,7 @@ import {
   formatLighthouseReport,
   summarizeLighthouse,
 } from "./lighthouse-runner.mjs";
+import { shouldShowWelcome, welcomeMessage } from "./postinstall.mjs";
 
 const lhr = {
   finalDisplayedUrl: "https://example.com/",
@@ -76,3 +77,19 @@ test("findBrowserPath falls back to Helium app path", () => {
     "/Applications/Helium.app/Contents/MacOS/Helium",
   );
 });
+
+test("postinstall welcome explains first commands", () => {
+  const message = welcomeMessage();
+  const plainMessage = welcomeMessage({ NO_COLOR: "1" });
+
+  assert.match(message, /Audit Kit/);
+  assert.match(message, /ak new/);
+  assert.match(message, /ak inspect latest/);
+  assert.match(message, /\x1b\[/);
+  assert.doesNotMatch(plainMessage, /\x1b\[/);
+  assert.match(plainMessage, /Audit Kit/);
+  assert.equal(shouldShowWelcome({}), true);
+  assert.equal(shouldShowWelcome({ CI: "true" }), false);
+  assert.equal(shouldShowWelcome({ AUDITKIT_SKIP_WELCOME: "1" }), false);
+  assert.equal(shouldShowWelcome({ npm_config_loglevel: "silent" }), false);
+});

package/scripts/auditkit/postinstall.mjs

@@ -1,31 +1,71 @@
-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"));
+import { pathToFileURL } from "node:url";
+
+export function shouldShowWelcome(env = process.env) {
+  return !env.CI && !env.AUDITKIT_SKIP_WELCOME && env.npm_config_loglevel !== "silent";
+}
+
+export function welcomeMessage(env = process.env) {
+  const colors = !env.NO_COLOR;
+  const rows = [
+    line("                                                            ", colors),
+    line(`   ${paint("Audit Kit", 96, colors)}                                                `, colors),
+    line(`   ${paint("Local website audits from your terminal.", 90, colors)}                 `, colors),
+    line("                                                            ", colors),
+    divider(colors),
+    line(`   ${paint("Try first", 97, colors)}                                                `, colors),
+    line("                                                            ", colors),
+    commandLine("ak new", "create an audit workspace", colors),
+    commandLine("ak inspect latest", "run check, security, Lighthouse", colors),
+    commandLine("ak report latest", "generate report + client email", colors),
+    commandLine("ak list", "show saved audits", colors),
+    line("                                                            ", colors),
+  ];
+
+  return [
+    "",
+    glow("    · ✦ ·        ·          · ✧ ·          ·        · ✦ ·", colors),
+    `${corner("╭", colors)}${gradient("────────────────────────────────────────────────────────────", colors)}${corner("╮", colors)}`,
+    ...rows,
+    `${corner("╰", colors)}${gradient("────────────────────────────────────────────────────────────", colors)}${corner("╯", colors)}`,
+    glow("      ·        · ✧ ·          ·        · ✦ ·        ·", colors),
+  ].join("\n");
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href && shouldShowWelcome()) {
+  console.log(welcomeMessage());
+}
+
+function commandLine(command, description, colors) {
+  return line(`   ${paint(command.padEnd(18), 36, colors)} ${paint(description.padEnd(34), 90, colors)}    `, colors);
+}
+
+function line(content, colors) {
+  return `${border("│", colors)}${content}${border("│", colors)}`;
+}
+
+function divider(colors) {
+  return `${border("├", colors)}${gradient("────────────────────────────────────────────────────────────", colors)}${border("┤", colors)}`;
+}
+
+function gradient(value, colors) {
+  const palette = [36, 96, 35, 93, 95, 94];
+  return [...value]
+    .map((character, index) => paint(character, palette[index % palette.length], colors))
+    .join("");
+}
+
+function border(value, colors) {
+  return paint(value, 96, colors);
+}
+
+function corner(value, colors) {
+  return paint(value, 95, colors);
+}
+
+function glow(value, colors) {
+  return paint(value, 90, colors);
+}
+
+function paint(value, code, colors) {
+  return colors ? `\x1b[${code}m${value}\x1b[0m` : value;
+}

package/scripts/lighthouse.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  formatLighthouseCli,
+  formatLighthouseReport,
+  runLighthouse,
+} from "./auditkit/lighthouse-runner.mjs";
+
+const url = process.argv[2];
+const outIndex = process.argv.indexOf("--out");
+const outDir = outIndex >= 0 ? process.argv[outIndex + 1] : null;
+
+if (!url) {
+  console.error("Usage: node scripts/lighthouse.mjs <url> [--out <folder>]");
+  process.exit(1);
+}
+
+try {
+  const result = await runLighthouse(url);
+  console.log(formatLighthouseCli(result.summary));
+
+  const folder = outDir ?? process.cwd();
+  await mkdir(folder, { recursive: true });
+
+  const markdownPath = path.join(folder, "lighthouse.md");
+  const jsonPath = path.join(folder, "lighthouse.json");
+
+  await writeFile(markdownPath, formatLighthouseReport(result.summary), "utf8");
+  await writeFile(jsonPath, result.json, "utf8");
+
+  console.log(`LIGHTHOUSE_MD: ${markdownPath}`);
+  console.log(`LIGHTHOUSE_JSON: ${jsonPath}`);
+} catch (error) {
+  console.error(error.message);
+  process.exit(1);
+}

package/src/html_check.rs

@@ -1,7 +1,7 @@
 use anyhow::Result;
 use regex::Regex;
 
-use crate::ui::score_status;
+use crate::ui::{self, score_status, FeedbackTone};
 
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct HtmlCheck {
@@ -201,13 +201,65 @@ pub fn check_url(input_url: &str) -> Result<HtmlCheck> {
 
 pub fn format_cli(result: &HtmlCheck) -> String {
     let mut output = format!(
-        "\n== Audit Kit Check ==\nURL: {}\nScore: {}/100 ({})\n\n== Signals ==\nStatus: {}\nResponse: {} bytes\nTitle: {}\nMeta description: {}\nH1 count: {}\nImages missing alt: {}/{}\n\n== Feedback ==\n",
+        "\n{}\n{} {}\n{} {}\n{}\n{}\n{}\n{}\n{}\n{}\n{}\n\n{}\n",
+        ui::frame_line("╭─ Audit Kit Check"),
+        ui::frame_line("│ URL  "),
+        result.url,
+        ui::frame_line("│ Score"),
+        ui::score_badge(result.score),
+        ui::frame_line("╰─ Signals"),
+        ui::signal_line("Status", result.status, status_tone(result.status)),
+        ui::signal_line(
+            "Response",
+            format!("{} bytes", result.bytes),
+            response_tone(result.bytes)
+        ),
+        ui::signal_line("Title", title_value(result), title_tone(result)),
+        ui::signal_line(
+            "Meta description",
+            if result.meta_description_present {
+                "present"
+            } else {
+                "missing"
+            },
+            if result.meta_description_present {
+                FeedbackTone::Positive
+            } else {
+                FeedbackTone::Critical
+            }
+        ),
+        ui::signal_line("H1 count", result.h1_count, h1_tone(result.h1_count)),
+        ui::signal_line(
+            "Images missing alt",
+            format!("{}/{}", result.image_missing_alt, result.image_total),
+            if result.image_missing_alt == 0 {
+                FeedbackTone::Positive
+            } else {
+                FeedbackTone::Critical
+            }
+        ),
+        ui::frame_line("Feedback")
+    );
+
+    for item in &result.feedback {
+        output.push_str(&format!(
+            "{}\n",
+            ui::feedback_line(feedback_tone(item), item)
+        ));
+    }
+
+    output
+}
+
+pub fn format_markdown(result: &HtmlCheck) -> String {
+    let mut output = format!(
+        "# Automated Check\n\nURL: {}\nScore: {}/100 ({})\n\n## Signals\n\n- Status: {}\n- Response: {} bytes\n- Title: {}\n- Meta description: {}\n- H1 count: {}\n- Images missing alt: {}/{}\n\n## Feedback\n\n",
         result.url,
         result.score,
         score_status(result.score),
         result.status,
         result.bytes,
-        if result.title.is_empty() { "missing" } else { &result.title },
+        title_value(result),
         if result.meta_description_present { "present" } else { "missing" },
         result.h1_count,
         result.image_missing_alt,
@@ -221,8 +273,64 @@ pub fn format_cli(result: &HtmlCheck) -> String {
     output
 }
 
-pub fn format_markdown(result: &HtmlCheck) -> String {
-    format!("# Automated Check\n\n{}\n", format_cli(result))
+fn title_value(result: &HtmlCheck) -> &str {
+    if result.title.is_empty() {
+        "missing"
+    } else {
+        &result.title
+    }
+}
+
+fn status_tone(status: u16) -> FeedbackTone {
+    if (200..400).contains(&status) {
+        FeedbackTone::Positive
+    } else {
+        FeedbackTone::Critical
+    }
+}
+
+fn response_tone(bytes: usize) -> FeedbackTone {
+    if bytes > 200_000 {
+        FeedbackTone::Warning
+    } else {
+        FeedbackTone::Positive
+    }
+}
+
+fn title_tone(result: &HtmlCheck) -> FeedbackTone {
+    if result.title.is_empty() {
+        FeedbackTone::Critical
+    } else if result.title.len() < 10 || result.title.len() > 65 {
+        FeedbackTone::Warning
+    } else {
+        FeedbackTone::Positive
+    }
+}
+
+fn h1_tone(count: usize) -> FeedbackTone {
+    match count {
+        1 => FeedbackTone::Positive,
+        0 => FeedbackTone::Critical,
+        _ => FeedbackTone::Warning,
+    }
+}
+
+fn feedback_tone(value: &str) -> FeedbackTone {
+    let value = value.to_lowercase();
+    if value.starts_with("missing")
+        || value.starts_with("no obvious")
+        || value.contains("missing alt")
+    {
+        FeedbackTone::Critical
+    } else if value.starts_with("no canonical")
+        || value.starts_with("title length")
+        || value.starts_with("multiple")
+        || value.contains("large")
+    {
+        FeedbackTone::Warning
+    } else {
+        FeedbackTone::Positive
+    }
 }
 
 #[cfg(test)]