auditkit 0.1.1 → 0.1.4

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "auditkit"
-version = "0.1.1"
+version = "0.1.4"
 edition = "2021"
 description = "Local hybrid CLI for agency website audits."
 license = "MIT"
@@ -11,7 +11,9 @@ 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/README.md

@@ -2,7 +2,7 @@
 
 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
 
@@ -31,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditkit",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Local hybrid CLI for agency website audits.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
     "audit:security": "cargo run --quiet -- security",
     "audit:lighthouse": "cargo run --quiet -- lighthouse",
     "audit:inspect": "cargo run --quiet -- inspect",
+    "postinstall": "node scripts/auditkit/postinstall.mjs",
     "test": "npm run test:node && npm run test:rust",
     "test:node": "node --test",
     "test:rust": "cargo test"

package/scripts/auditkit/ak

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

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

@@ -0,0 +1,71 @@
+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/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)]

package/src/lighthouse.rs

@@ -7,6 +7,7 @@ use anyhow::{Context, Result};
 pub struct LighthousePaths {
     pub markdown_path: PathBuf,
     pub json_path: PathBuf,
+    pub cli_output: String,
 }
 
 pub fn run_lighthouse(
@@ -36,14 +37,16 @@ pub fn run_lighthouse(
         .map(PathBuf::from)
         .unwrap_or_else(|| output_folder.unwrap_or(root).join("lighthouse.json"));
 
-    for line in stdout.lines() {
-        if !line.contains("LIGHTHOUSE_MD:") && !line.contains("LIGHTHOUSE_JSON:") {
-            println!("{line}");
-        }
-    }
+    let cli_output = stdout
+        .lines()
+        .filter(|line| !line.contains("LIGHTHOUSE_MD:") && !line.contains("LIGHTHOUSE_JSON:"))
+        .collect::<Vec<_>>()
+        .join("\n");
+
     Ok(LighthousePaths {
         markdown_path,
         json_path,
+        cli_output,
     })
 }