@wcag-audit/cli 1.0.0-alpha.3

package/src/commands/init.js

@@ -0,0 +1,126 @@
+import enquirer from "enquirer";
+import { randomUUID } from "crypto";
+import { validateLicense } from "../license/validate.js";
+import { writeGlobalConfig } from "../config/global.js";
+
+const CLI_VERSION = "1.0.0-alpha.3";
+
+// runInit can be called two ways:
+//   1. Interactive (no answers) — uses enquirer to prompt
+//   2. Non-interactive (answers provided) — used by tests and CI
+export async function runInit({ answers, log = console.log } = {}) {
+  log("");
+  log("Welcome to WCAG Audit CLI");
+  log("");
+
+  const resolved = answers || (await promptUser());
+
+  // 1. Validate license
+  const machineId = randomUUID();
+  const license = await validateLicense(resolved.licenseKey, {
+    machineId,
+    source: "cli",
+    version: CLI_VERSION,
+  });
+
+  if (!license.valid) {
+    log(`✗ License check failed: ${license.error}`);
+    return { ok: false, error: license.error };
+  }
+
+  const credits = license.creditsRemaining?.total ?? "unlimited";
+  log(`✓ License valid (${license.tier} plan, ${credits} credits remaining)`);
+
+  // 2. Write config
+  const aiConfig = resolved.enableAi
+    ? {
+        enabled: true,
+        provider: resolved.aiProvider,
+        apiKey: resolved.aiApiKey,
+        model: defaultModelFor(resolved.aiProvider),
+        groups: resolved.aiGroups || ["visual", "structure", "language"],
+      }
+    : {
+        enabled: false,
+        provider: "anthropic",
+        apiKey: null,
+        model: null,
+        groups: [],
+      };
+
+  await writeGlobalConfig({
+    licenseKey: resolved.licenseKey,
+    ai: aiConfig,
+  });
+
+  log("✓ Config saved to ~/.wcagauditrc (chmod 600)");
+  log("  Run `npx wcag-audit scan` in your project directory to start.");
+  log("");
+
+  return { ok: true, tier: license.tier };
+}
+
+function defaultModelFor(provider) {
+  return {
+    anthropic: "claude-sonnet-4-6",
+    openai: "gpt-4.1-mini",
+    google: "gemini-2.5-flash",
+  }[provider] || "claude-sonnet-4-6";
+}
+
+async function promptUser() {
+  const answers = await enquirer.prompt([
+    {
+      type: "input",
+      name: "licenseKey",
+      message: "Paste your WCAG Audit license key:",
+      validate(value) {
+        if (!/^WCAG-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}$/i.test(value?.trim())) {
+          return "Expected format: WCAG-XXXX-XXXX-XXXX-XXXX";
+        }
+        return true;
+      },
+      result: (v) => v.trim().toUpperCase(),
+    },
+    {
+      type: "confirm",
+      name: "enableAi",
+      message: "Enable AI vision review? (uses your own LLM API key)",
+      initial: true,
+    },
+  ]);
+
+  if (!answers.enableAi) return answers;
+
+  const aiAnswers = await enquirer.prompt([
+    {
+      type: "select",
+      name: "aiProvider",
+      message: "Choose AI provider:",
+      choices: [
+        { name: "anthropic", message: "Anthropic Claude (recommended)" },
+        { name: "openai", message: "OpenAI GPT" },
+        { name: "google", message: "Google Gemini" },
+      ],
+    },
+    {
+      type: "password",
+      name: "aiApiKey",
+      message: "Paste your API key:",
+      validate: (v) => (v && v.length > 10 ? true : "API key seems too short"),
+    },
+    {
+      type: "multiselect",
+      name: "aiGroups",
+      message: "Which AI review groups to enable?",
+      choices: [
+        { name: "visual", message: "Visual quality (color, layout, hierarchy)" },
+        { name: "structure", message: "Structure & navigation" },
+        { name: "language", message: "Reading & language" },
+      ],
+      initial: [0, 1, 2],
+    },
+  ]);
+
+  return { ...answers, ...aiAnswers };
+}

package/src/commands/init.test.js

@@ -0,0 +1,83 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtemp, rm, readFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { runInit } from "./init.js";
+
+let tmpHome;
+
+beforeEach(async () => {
+  tmpHome = await mkdtemp(join(tmpdir(), "wcaginit-"));
+  process.env.HOME = tmpHome;
+  global.fetch = vi.fn();
+});
+
+afterEach(async () => {
+  await rm(tmpHome, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe("runInit", () => {
+  it("writes licenseKey + AI config when validation passes", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ valid: true, tier: "pro", creditsRemaining: { total: 100 } }),
+    });
+    const logs = [];
+    const result = await runInit({
+      answers: {
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        enableAi: true,
+        aiProvider: "anthropic",
+        aiApiKey: "sk-ant-x",
+        aiGroups: ["visual", "structure"],
+      },
+      log: (msg) => logs.push(msg),
+    });
+    expect(result.ok).toBe(true);
+    const raw = await readFile(join(tmpHome, ".wcagauditrc"), "utf8");
+    const cfg = JSON.parse(raw);
+    expect(cfg.licenseKey).toBe("WCAG-TEST-AAAA-BBBB-CCCC");
+    expect(cfg.ai.enabled).toBe(true);
+    expect(cfg.ai.provider).toBe("anthropic");
+    expect(cfg.ai.apiKey).toBe("sk-ant-x");
+    expect(cfg.ai.groups).toEqual(["visual", "structure"]);
+    expect(logs.join("\n")).toMatch(/Config saved/);
+  });
+
+  it("rejects and exits when license validation fails", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: false,
+      status: 403,
+      json: async () => ({ valid: false, error: "License revoked" }),
+    });
+    const result = await runInit({
+      answers: {
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        enableAi: false,
+      },
+      log: () => {},
+    });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/revoked/i);
+  });
+
+  it("does not write AI config when enableAi is false", async () => {
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ valid: true, tier: "pro", creditsRemaining: { total: 100 } }),
+    });
+    const result = await runInit({
+      answers: {
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        enableAi: false,
+      },
+      log: () => {},
+    });
+    expect(result.ok).toBe(true);
+    const raw = await readFile(join(tmpHome, ".wcagauditrc"), "utf8");
+    const cfg = JSON.parse(raw);
+    expect(cfg.ai.enabled).toBe(false);
+    expect(cfg.ai.apiKey).toBe(null);
+  });
+});

package/src/commands/scan.js

@@ -0,0 +1,322 @@
+import { readFile, writeFile } from "fs/promises";
+import { join, basename, resolve } from "path";
+import { randomUUID } from "crypto";
+import getPort from "get-port";
+
+import { readGlobalConfig } from "../config/global.js";
+import { readProjectConfig } from "../config/project.js";
+import { validateLicense } from "../license/validate.js";
+import { logUsage } from "../license/log-usage.js";
+import { detectFramework } from "../discovery/registry.js";
+import { loadManualRoutes } from "../discovery/manual.js";
+import { crawlRoutes } from "../discovery/crawl.js";
+import { expandDynamicRoutes } from "../discovery/dynamic-samples.js";
+import { startDevServer, detectDevCommand } from "../devserver/spawn.js";
+import { renderFindingsMarkdown } from "../output/markdown.js";
+import { renderCursorRules } from "../output/cursor-rules.js";
+import { upsertAgentsMd } from "../output/agents-md.js";
+import { hashContent, readCacheEntry, writeCacheEntry } from "../cache/route-cache.js";
+
+const CLI_VERSION = "1.0.0-alpha.3";
+
+export async function runScan({
+  cwd = process.cwd(),
+  dryRun = false,
+  noAi = false,
+  noCache = false,
+  urlMode = null,
+  routesFile = null,
+  crawlDepth = 2,
+  log = console.log,
+  runAuditForRoute,
+} = {}) {
+  // 1. Load global + project config
+  const globalCfg = await readGlobalConfig();
+  if (!globalCfg.licenseKey) {
+    return {
+      ok: false,
+      error: "No license key found. Run `npx wcag-audit init` first.",
+    };
+  }
+  const projectCfg = await readProjectConfig(cwd);
+
+  // 2-3. Detect framework + discover routes.
+  // Priority: --url crawl > --routes file > framework detection.
+  let framework = null;
+  let strategy = null;
+  let routes = [];
+
+  if (urlMode) {
+    framework = "crawl";
+    strategy = "url-crawl";
+    log(`✓ Crawl mode: starting at ${urlMode} (depth ${crawlDepth})`);
+    routes = await crawlRoutes(urlMode, {
+      maxDepth: crawlDepth,
+      excludePaths: projectCfg.excludePaths,
+    });
+  } else if (routesFile) {
+    framework = "manual";
+    strategy = "routes-file";
+    log(`✓ Manual routes: ${routesFile}`);
+    routes = await loadManualRoutes(routesFile, {
+      excludePaths: projectCfg.excludePaths,
+    });
+  } else {
+    const det = await detectFramework(cwd);
+    if (det) {
+      framework = det.framework;
+      strategy = det.strategy;
+      log(`✓ Detected ${framework} (${strategy})`);
+      routes = await det.discoverRoutes(cwd, {
+        excludePaths: projectCfg.excludePaths,
+      });
+      routes = expandDynamicRoutes(routes, projectCfg.dynamicRouteSamples || {});
+    }
+  }
+
+  if (routes.length === 0) {
+    return {
+      ok: false,
+      error:
+        "No routes discovered. Use --url to crawl a deployed site, --routes to provide a manual list, or add dynamicRouteSamples to .wcagauditrc.",
+    };
+  }
+  log(`✓ Discovered ${routes.length} route${routes.length === 1 ? "" : "s"}`);
+
+  // 4. Validate license + credit budget
+  const machineId = randomUUID();
+  const license = await validateLicense(globalCfg.licenseKey, {
+    machineId,
+    source: "cli",
+    version: CLI_VERSION,
+  });
+  if (!license.valid) {
+    return { ok: false, error: `License check failed: ${license.error}` };
+  }
+  const creditsRemaining = license.creditsRemaining?.total ?? Infinity;
+  const creditsNeeded = routes.length;
+
+  log(
+    `✓ License: ${license.tier} plan (${creditsRemaining === Infinity ? "unlimited" : creditsRemaining} credits remaining)`,
+  );
+  log("");
+  log("Scan preview:");
+  log(`  ${routes.length} routes × 1 credit/route = ${creditsNeeded} credits`);
+  if (creditsRemaining !== Infinity) {
+    log(`  Remaining after scan: ${creditsRemaining - creditsNeeded}`);
+  }
+  log("");
+
+  if (license.tier !== "enterprise" && creditsNeeded > creditsRemaining) {
+    return {
+      ok: false,
+      error: `Not enough credits (${creditsNeeded} needed, ${creditsRemaining} remaining). Top up at https://wcagaudit.io/checkout/topup`,
+      creditsNeeded,
+      creditsRemaining,
+      routes,
+      framework,
+    };
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      framework,
+      routes,
+      creditsNeeded,
+      creditsRemaining,
+      license,
+    };
+  }
+
+  // 5. Spawn dev server
+  const pkgJson = JSON.parse(await readFile(join(cwd, "package.json"), "utf8"));
+  const devCmd = projectCfg.devServer.command
+    ? { cmd: "sh", args: ["-c", projectCfg.devServer.command] }
+    : detectDevCommand(pkgJson);
+  if (!devCmd) {
+    return {
+      ok: false,
+      error: "Could not determine dev server command. Add `dev` script to package.json or set devServer.command in .wcagauditrc.",
+    };
+  }
+
+  const port = projectCfg.devServer.port || (await getPort({ port: 3000 }));
+  log(`Starting dev server on port ${port}...`);
+
+  let server;
+  try {
+    server = await startDevServer({
+      cwd,
+      cmd: devCmd.cmd,
+      args: devCmd.args,
+      port,
+      healthPath: projectCfg.devServer.healthCheck || "/",
+      startupTimeout: projectCfg.devServer.startupTimeout || 60000,
+    });
+    log(`✓ Server ready on ${server.url}`);
+    log("");
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+
+  // 6. Audit each route
+  const allFindings = [];
+  const runFn = runAuditForRoute || (await importAuditFn());
+  let newPagesCount = 0;
+  let cachedPagesCount = 0;
+  log("Auditing routes...");
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i];
+    const url = `http://localhost:${port}${route.path}`;
+    const label = `[${i + 1}/${routes.length}] ${route.path}`;
+    try {
+      // Fetch the rendered HTML once to compute the cache key. This is
+      // cheap (<100ms) compared to running the full checker pipeline.
+      const cacheHtml = await fetch(url).then((r) => r.text()).catch(() => "");
+      const hash = hashContent(cacheHtml, []);
+      const cached = noCache ? null : await readCacheEntry(cwd, route.path, hash);
+      if (cached) {
+        const tagged = cached.findings.map((f) => ({
+          ...f,
+          route: route.path,
+          sourceFile: route.sourceFile,
+        }));
+        allFindings.push(...tagged);
+        cachedPagesCount++;
+        log(`${label} → ${tagged.length} issues (cached)`);
+        continue;
+      }
+
+      const findings = await runFn({
+        url,
+        wcagVersion: globalCfg.defaults.wcagVersion,
+        levels: globalCfg.defaults.conformanceLevel,
+        maxPages: 1,
+        aiEnabled: !noAi && globalCfg.ai.enabled,
+        aiProvider: globalCfg.ai.provider,
+        aiModel: globalCfg.ai.model,
+        aiKey: globalCfg.ai.apiKey,
+        headed: false,
+        slowMo: 0,
+      });
+      const tagged = findings.map((f) => ({
+        ...f,
+        route: route.path,
+        sourceFile: route.sourceFile,
+      }));
+      allFindings.push(...tagged);
+      newPagesCount++;
+      // Store the bare findings (without route/sourceFile stamps) so
+      // re-tagging works even if route metadata changes.
+      await writeCacheEntry(cwd, route.path, hash, {
+        findings,
+        auditedAt: Date.now(),
+      });
+      log(`${label} → ${tagged.length} issues`);
+    } catch (err) {
+      log(`${label} → ERROR: ${err.message}`);
+    }
+  }
+
+  // 7. Cleanup dev server
+  await server.dispose();
+
+  // 8. Write outputs
+  const outputs = new Set(projectCfg.outputs || ["excel", "markdown"]);
+  const projectName = basename(cwd);
+
+  if (outputs.has("markdown")) {
+    const md = renderFindingsMarkdown({
+      projectName,
+      generator: `@wcagaudit/cli v${CLI_VERSION}`,
+      totalPages: routes.length,
+      wcagVersion: globalCfg.defaults.wcagVersion,
+      levels: globalCfg.defaults.conformanceLevel,
+      findings: allFindings,
+    });
+    await writeFile(resolve(cwd, "WCAG_FIXES.md"), md, "utf8");
+    log(`✓ WCAG_FIXES.md (${allFindings.length} findings)`);
+  }
+
+  if (outputs.has("cursor-rules")) {
+    const mdc = renderCursorRules({ projectName, findings: allFindings });
+    const dir = resolve(cwd, ".cursor/rules");
+    const { mkdir } = await import("fs/promises");
+    await mkdir(dir, { recursive: true });
+    await writeFile(resolve(dir, "wcag-fixes.mdc"), mdc, "utf8");
+    log(`✓ .cursor/rules/wcag-fixes.mdc`);
+  }
+
+  if (outputs.has("agents-md")) {
+    // Build a compact bulleted list for AGENTS.md — just the per-file
+    // summary, not the full finding detail (full detail lives in
+    // WCAG_FIXES.md).
+    const byFile = new Map();
+    for (const f of allFindings) {
+      const key = f.sourceFile || "(unknown)";
+      if (!byFile.has(key)) byFile.set(key, []);
+      byFile.get(key).push(f);
+    }
+    let body = "";
+    if (byFile.size === 0) {
+      body = "No outstanding WCAG issues from the last scan.\n";
+    } else {
+      for (const [file, items] of byFile.entries()) {
+        body += `### ${file}\n`;
+        for (const f of items.slice(0, 10)) {
+          const crit = Array.isArray(f.criteria) ? f.criteria.join(", ") : f.criteria || "?";
+          body += `- ${f.description || f.ruleId} — ${crit} (${f.impact || "minor"})\n`;
+        }
+        body += "\n";
+      }
+    }
+    await upsertAgentsMd(cwd, body);
+    log(`✓ AGENTS.md WCAG section updated`);
+  }
+
+  // Note: multi-page Excel is not yet supported. report.js is
+  // per-page only (expects meta.url, meta.startedAt, meta.scopeCriteria).
+  // Phase 1 ships markdown only; aggregate Excel comes in a later phase.
+  if (outputs.has("excel")) {
+    log("! Excel output skipped in Phase 1 — use `wcag-audit audit <url>` for per-page Excel.");
+  }
+
+  // 9. Log usage for billing
+  await logUsage({
+    licenseKey: globalCfg.licenseKey,
+    pagesCount: routes.length,
+    newPagesCount,
+    cachedPagesCount,
+    issuesFound: allFindings.length,
+    source: "cli",
+    cliVersion: CLI_VERSION,
+    framework,
+  });
+
+  log("");
+  log(`✓ Scan complete — ${allFindings.length} issues across ${routes.length} pages (${newPagesCount} audited, ${cachedPagesCount} cached)`);
+  return {
+    ok: true,
+    framework,
+    routes,
+    findings: allFindings,
+    creditsUsed: creditsNeeded,
+  };
+}
+
+async function importAuditFn() {
+  // runAuditCore returns { findings, meta } without writing any files.
+  // runAudit (the legacy wrapper) writes a per-page Excel and returns
+  // void, which loses the findings.
+  const { runAuditCore } = await import("../audit.js");
+  return async (opts) => {
+    const tmpScreens = `/tmp/wcag-screens-${Math.random().toString(36).slice(2)}`;
+    const result = await runAuditCore({
+      ...opts,
+      screenshotsDir: tmpScreens,
+    });
+    return result?.findings || [];
+  };
+}

package/src/commands/scan.test.js

@@ -0,0 +1,139 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtemp, rm, mkdir, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { runScan } from "./scan.js";
+
+let tmpHome;
+let projDir;
+
+async function touch(relPath) {
+  const abs = join(projDir, relPath);
+  await mkdir(join(abs, ".."), { recursive: true });
+  await writeFile(abs, "// test", "utf8");
+}
+
+beforeEach(async () => {
+  tmpHome = await mkdtemp(join(tmpdir(), "wcagscan-home-"));
+  projDir = await mkdtemp(join(tmpdir(), "wcagscan-proj-"));
+  process.env.HOME = tmpHome;
+  global.fetch = vi.fn();
+});
+
+afterEach(async () => {
+  await rm(tmpHome, { recursive: true, force: true });
+  await rm(projDir, { recursive: true, force: true });
+  vi.restoreAllMocks();
+});
+
+describe("runScan — dry run preview", () => {
+  it("fails when no config is found", async () => {
+    const result = await runScan({ cwd: projDir, dryRun: true, log: () => {} });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/init/i);
+  });
+
+  it("reports discovered routes and credit cost", async () => {
+    await writeFile(
+      join(tmpHome, ".wcagauditrc"),
+      JSON.stringify({
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        ai: { enabled: false, provider: "anthropic", apiKey: null },
+      }),
+      "utf8"
+    );
+
+    await writeFile(
+      join(projDir, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" }, scripts: { dev: "next dev" } }),
+      "utf8"
+    );
+    await touch("app/page.tsx");
+    await touch("app/about/page.tsx");
+    await touch("app/pricing/page.tsx");
+
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        valid: true,
+        tier: "pro",
+        creditsRemaining: { total: 200 },
+      }),
+    });
+
+    const logs = [];
+    const result = await runScan({
+      cwd: projDir,
+      dryRun: true,
+      log: (m) => logs.push(m),
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.framework).toBe("nextjs-app");
+    expect(result.routes.map((r) => r.path).sort()).toEqual([
+      "/",
+      "/about",
+      "/pricing",
+    ]);
+    expect(result.creditsNeeded).toBe(3);
+    expect(result.creditsRemaining).toBe(200);
+    const joined = logs.join("\n");
+    expect(joined).toMatch(/Detected nextjs-app/);
+    expect(joined).toMatch(/3 routes/);
+    expect(joined).toMatch(/3 credits/);
+  });
+
+  it("fails when credits insufficient", async () => {
+    await writeFile(
+      join(tmpHome, ".wcagauditrc"),
+      JSON.stringify({
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        ai: { enabled: false, provider: "anthropic", apiKey: null },
+      }),
+      "utf8"
+    );
+    await writeFile(
+      join(projDir, "package.json"),
+      JSON.stringify({ dependencies: { next: "15.0.0" } }),
+      "utf8"
+    );
+    await touch("app/page.tsx");
+    await touch("app/a/page.tsx");
+    await touch("app/b/page.tsx");
+    await touch("app/c/page.tsx");
+    await touch("app/d/page.tsx");
+
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({
+        valid: true,
+        tier: "pro",
+        creditsRemaining: { total: 2 },
+      }),
+    });
+
+    const result = await runScan({ cwd: projDir, dryRun: true, log: () => {} });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/not enough credits/i);
+  });
+
+  it("returns error when framework not detected", async () => {
+    await writeFile(
+      join(tmpHome, ".wcagauditrc"),
+      JSON.stringify({
+        licenseKey: "WCAG-TEST-AAAA-BBBB-CCCC",
+        ai: { enabled: false },
+      }),
+      "utf8"
+    );
+
+    global.fetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ valid: true, tier: "pro", creditsRemaining: { total: 100 } }),
+    });
+
+    const result = await runScan({ cwd: projDir, dryRun: true, log: () => {} });
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/routes discovered|framework/i);
+  });
+});