svelte-vitals 0.19.0 → 0.21.0

package/dist/bin.js

@@ -4,12 +4,14 @@ import {
   findUnknownRuleIds,
   isReporterName,
   knownRuleIds,
+  readCoreVersion,
   readPackageVersion,
   run
-} from "./chunk-ZE3M3T6U.js";
+} from "./chunk-B3RVLTZY.js";
 
 // src/bin.ts
-import mri2 from "mri";
+import mri3 from "mri";
+import * as p2 from "@clack/prompts";
 
 // src/resolve-args.ts
 var CATEGORIES = ["seo", "performance", "correctness", "security", "architecture"];
@@ -55,6 +57,26 @@ function parseWeights(raw, errors) {
   }
   return weights;
 }
+function parseCategories(raw, errors) {
+  if (typeof raw !== "string" || raw.trim() === "") return void 0;
+  const categories = [];
+  const unknownCategories = [];
+  for (const entry of raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+    if (!CATEGORIES.includes(entry)) {
+      unknownCategories.push(entry);
+      continue;
+    }
+    if (!categories.includes(entry)) categories.push(entry);
+  }
+  if (unknownCategories.length > 0) {
+    errors.push(`svelte-vitals: unknown category(ies) in --category: ${unknownCategories.join(", ")}`);
+    errors.push(`Known categories: ${CATEGORIES.join(", ")}`);
+  }
+  if (unknownCategories.length === 0 && categories.length === 0) {
+    errors.push("svelte-vitals: --category was passed but contains no categories.");
+  }
+  return categories;
+}
 var toList = (v) => typeof v === "string" ? v.split(",").map((s) => s.trim()).filter(Boolean) : [];
 function resolveArgs(argv) {
   const warnings = [];
@@ -71,6 +93,14 @@ function resolveArgs(argv) {
   const route = typeof argv.route === "string" ? argv.route : void 0;
   const diffBase = typeof argv.diff === "string" ? argv.diff || "HEAD" : void 0;
   const staged = Boolean(argv.staged);
+  let baselineRef;
+  if (typeof argv.baseline === "string") {
+    if (argv.baseline.trim() === "") {
+      errors.push("svelte-vitals: --baseline requires a git ref (e.g. --baseline origin/main).");
+    } else {
+      baselineRef = argv.baseline;
+    }
+  }
   const allow = toList(argv.rules);
   const ignore = toList(argv.ignore);
   const unknown = findUnknownRuleIds([...allow, ...ignore]);
@@ -84,7 +114,7 @@ function resolveArgs(argv) {
   } else if (typeof argv.reporter === "string") {
     if (!isReporterName(argv.reporter)) {
       errors.push(
-        `svelte-vitals: unknown reporter '${argv.reporter}'. Valid values: console, json, agent, sarif, github, html.`
+        `svelte-vitals: unknown reporter '${argv.reporter}'. Valid values: console, json, agent, sarif, github, html, md.`
       );
     } else {
       reporter = argv.reporter;
@@ -99,12 +129,20 @@ function resolveArgs(argv) {
   }
   const failOn = argv["fail-on-warning"] ? "warning" : failOnValid ? failOnRaw : void 0;
   const weights = parseWeights(argv.weights, errors);
+  const categories = parseCategories(argv.category, errors);
+  const score = Boolean(argv.score);
+  if (score && (argv.json || typeof argv.reporter === "string")) {
+    warnings.push("svelte-vitals: --score overrides --reporter; reporter output suppressed.");
+  }
   const rulesConfig = buildRulesConfig(allow, ignore);
   const rules = Object.keys(rulesConfig).length > 0 ? rulesConfig : void 0;
   if (errors.length > 0) return { options: null, warnings, errors };
   return {
     options: {
       cwd: positional ?? process.cwd(),
+      // Never reinterpret an explicit target (design doc 2026-07-08-monorepo-app-picker-design.md,
+      // decision 1): the monorepo picker in run() only triggers when this is false.
+      explicitPath: positional !== void 0,
       metaComponents,
       treatDynamicAs,
       route,
@@ -114,8 +152,11 @@ function resolveArgs(argv) {
       failOn,
       rules,
       ...weights !== void 0 ? { weights } : {},
+      ...categories !== void 0 ? { categories } : {},
+      ...score ? { score } : {},
       ...diffBase !== void 0 ? { diffBase } : {},
-      ...staged ? { staged } : {}
+      ...staged ? { staged } : {},
+      ...baselineRef !== void 0 ? { baseline: baselineRef } : {}
     },
     warnings,
     errors
@@ -236,6 +277,93 @@ function isViteTargetId(id) {
   return VITE_TARGETS.some((t) => t.id === id);
 }
 
+// src/install/agent-targets.ts
+var AGENT_TARGETS = [
+  {
+    id: "claude-skill",
+    label: "Claude Code skill",
+    hint: "Teaches the agent svelte-vitals rules + when to run the scanner",
+    relPath: ".claude/skills/svelte-vitals/SKILL.md"
+  },
+  {
+    id: "cursor-rules",
+    label: "Cursor rules",
+    hint: "Project rules file so Cursor avoids flagged patterns up front",
+    relPath: ".cursor/rules/svelte-vitals.mdc"
+  }
+];
+function agentTargetById(id) {
+  return AGENT_TARGETS.find((t) => t.id === id);
+}
+function isAgentTargetId(id) {
+  return AGENT_TARGETS.some((t) => t.id === id);
+}
+
+// src/install/skill-content.ts
+import { allRules, docsUrlFor } from "@svelte-vitals/core";
+var CATEGORY_ORDER = ["seo", "performance", "correctness", "security", "architecture"];
+var CATEGORY_LABELS = {
+  seo: "SEO",
+  performance: "Performance",
+  correctness: "Correctness",
+  security: "Security",
+  architecture: "Architecture"
+};
+function oneLine(text) {
+  return text.replace(/\r?\n+/g, " ").trim();
+}
+function ruleLine(rule) {
+  const fixPart = rule.fix?.description ? ` Fix: ${oneLine(rule.fix.description)}` : "";
+  return `- **${rule.id} \u2014 ${oneLine(rule.title)}** (${rule.severity}): ${oneLine(rule.rationale)}${fixPart} ([docs](${docsUrlFor(rule.id)}))`;
+}
+function ruleDigest() {
+  return CATEGORY_ORDER.map((category) => {
+    const lines = allRules.filter((r) => r.category === category).map(ruleLine).join("\n");
+    return `### ${CATEGORY_LABELS[category]}
+
+${lines}`;
+  }).join("\n\n");
+}
+function sharedBody(version) {
+  return `<!-- Generated by \`svelte-vitals install\` (svelte-vitals ${version}). Re-run with --force to refresh. -->
+
+# svelte-vitals
+
+## When to use
+
+Use this whenever you are writing or reviewing SvelteKit route files (\`+page.svelte\`, \`+layout.svelte\`) or components in this project \u2014 svelte-vitals statically checks SEO, performance, correctness, security, and architecture patterns.
+
+## Playbook
+
+1. After writing or editing code, run \`npx svelte-vitals . --diff --reporter agent\` and fix any findings it reports.
+2. Before committing, run \`npx svelte-vitals . --staged\` as a pre-commit gate.
+3. For a rule's full rationale and fix examples, use the \`explain_rule\` MCP tool (svelte-vitals MCP server) or open its docs link below.
+
+## Rule digest
+
+${ruleDigest()}
+`;
+}
+function buildSkillMarkdown(version) {
+  const frontmatter = `---
+name: svelte-vitals
+description: Use when writing or reviewing SvelteKit routes/components \u2014 svelte-vitals rule knowledge (SEO, performance, correctness, security, architecture) and how to run the scanner.
+---`;
+  return `${frontmatter}
+
+${sharedBody(version)}`;
+}
+function buildCursorRules(version) {
+  const frontmatter = `---
+description: svelte-vitals code-health rules for SvelteKit (SEO, performance, correctness, security, architecture)
+globs: ["**/*.svelte", "src/routes/**"]
+alwaysApply: false
+---`;
+  return `${frontmatter}
+
+${sharedBody(version)}`;
+}
+
 // src/install/codemod-vite-config.ts
 import { parseModule, generateCode, builders, MagicastError } from "magicast";
 var MANUAL_SNIPPET = `import { svelteVitals } from '@svelte-vitals/vite';
@@ -252,7 +380,7 @@ function codemodViteConfig(existing) {
       return { status: "manual", snippet: MANUAL_SNIPPET };
     }
     const already = configObj.plugins.find(
-      (p2) => p2?.$type === "function-call" && p2?.$callee === "svelteVitals"
+      (p3) => p3?.$type === "function-call" && p3?.$callee === "svelteVitals"
     );
     if (already !== void 0) {
       return { status: "exists" };
@@ -369,6 +497,15 @@ function installCommand(pm) {
   const action = pm === "npm" ? "install" : "add";
   return { command: pm, args: [action, "-D", "@svelte-vitals/vite"] };
 }
+function readInstalledViteVersion(io) {
+  const raw = io.readFile(join2(io.cwd, "node_modules/@svelte-vitals/vite/package.json"));
+  if (raw === void 0) return void 0;
+  try {
+    return JSON.parse(raw).version;
+  } catch {
+    return void 0;
+  }
+}
 
 // src/install/index.ts
 function planForClient(client, scope, io, force) {
@@ -395,6 +532,13 @@ function planForDevOverlay(io) {
   const result = codemodHooksServer(content);
   return { id: "vite-dev-overlay", label: viteTargetById("vite-dev-overlay").label, path, ...result };
 }
+function planForAgentTarget(target, io, force, version) {
+  const path = join3(io.cwd, target.relPath);
+  const existing = io.readFile(path);
+  const content = target.id === "claude-skill" ? buildSkillMarkdown(version) : buildCursorRules(version);
+  const status = existing === void 0 ? "created" : force ? "updated" : "exists";
+  return { id: target.id, label: target.label, path, status, content };
+}
 function indent(text) {
   return text.split("\n").map((l) => `      ${l}`).join("\n");
 }
@@ -403,7 +547,7 @@ function rowLine(r) {
   return r.status === "manual" && r.snippet ? `${head}
 ${indent(r.snippet)}` : head;
 }
-async function runInstall(flags, io, prompts) {
+async function runInstall(flags, io, prompts, version = "0.0.0") {
   let ids;
   if (flags.client && flags.client.length > 0) {
     ids = flags.client;
@@ -421,10 +565,21 @@ async function runInstall(flags, io, prompts) {
     const viteConfigExists = ["vite.config.ts", "vite.config.js", "vite.config.mjs"].some(
       (f) => configExists(join3(io.cwd, f))
     );
-    const detected = [...detectedClients, ...viteConfigExists ? VITE_TARGETS.map((t) => t.id) : []];
+    const claudeSkillDetected = configExists(join3(io.cwd, ".claude", "settings.json"));
+    const cursorRulesDetected = configExists(join3(io.cwd, ".cursor", "mcp.json"));
+    const detectedAgents = [
+      ...claudeSkillDetected ? ["claude-skill"] : [],
+      ...cursorRulesDetected ? ["cursor-rules"] : []
+    ];
+    const detected = [
+      ...detectedClients,
+      ...viteConfigExists ? VITE_TARGETS.map((t) => t.id) : [],
+      ...detectedAgents
+    ];
     const options = [
       ...CLIENTS.map((c) => ({ id: c.id, label: c.label })),
-      ...VITE_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
+      ...VITE_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+      ...AGENT_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
     ];
     const picked = await prompts.selectClients(options, detected);
     if (picked === null) {
@@ -434,13 +589,14 @@ async function runInstall(flags, io, prompts) {
     ids = picked;
   } else {
     io.errorLog(
-      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-dev-overlay> to install non-interactively."
+      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-dev-overlay,claude-skill,cursor-rules> to install non-interactively."
     );
     return 2;
   }
   const clients = ids.map(clientById).filter((c) => c !== void 0);
   const viteIds = ids.filter(isViteTargetId);
-  if (clients.length === 0 && viteIds.length === 0) {
+  const agentIds = ids.filter(isAgentTargetId);
+  if (clients.length === 0 && viteIds.length === 0 && agentIds.length === 0) {
     io.errorLog("svelte-vitals: no valid clients or targets selected.");
     return 2;
   }
@@ -474,6 +630,10 @@ async function runInstall(flags, io, prompts) {
   for (const viteId of viteIds) {
     rows.push(viteId === "vite-plugin" ? planForVitePlugin(io) : planForDevOverlay(io));
   }
+  for (const agentId of agentIds) {
+    const target = agentTargetById(agentId);
+    rows.push(planForAgentTarget(target, io, flags.force ?? false, version));
+  }
   const planText = rows.map(rowLine).join("\n");
   io.log("Plan:");
   io.log(planText);
@@ -519,6 +679,11 @@ ${indent(r.snippet ?? "")}`);
       io.errorLog(
         `svelte-vitals: failed to install @svelte-vitals/vite (${command} ${args.join(" ")} exited ${code}). Install it manually.`
       );
+    } else {
+      const installedVersion = readInstalledViteVersion(io);
+      io.log(
+        installedVersion ? `svelte-vitals: installed @svelte-vitals/vite@${installedVersion} \u2014 compare against \`svelte-vitals --version\`'s core number if findings ever seem out of sync.` : "svelte-vitals: installed @svelte-vitals/vite (could not read the installed version from node_modules)."
+      );
     }
   }
   if (hadFailure) return 2;
@@ -530,7 +695,11 @@ ${indent(r.snippet ?? "")}`);
 }
 
 // src/install/args.ts
-var VALID_TARGETS = [...CLIENTS.map((c) => c.id), ...VITE_TARGETS.map((t) => t.id)];
+var VALID_TARGETS = [
+  ...CLIENTS.map((c) => c.id),
+  ...VITE_TARGETS.map((t) => t.id),
+  ...AGENT_TARGETS.map((t) => t.id)
+];
 var EXPECTED_TARGETS = VALID_TARGETS.join("|");
 function resolveInstallArgs(argv) {
   const warnings = [];
@@ -568,16 +737,20 @@ function resolveInstallArgs(argv) {
 }
 
 // src/install/cli.ts
-var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals MCP server for your AI-agent clients
+var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals MCP server, Vite integration, and agent skills/rules
 
 Usage:
   svelte-vitals install [options]
 
 Options:
-  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-dev-overlay (skips the interactive picker)
+  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-dev-overlay,claude-skill,cursor-rules
+                    (skips the interactive picker)
                     vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-dev-overlay
                     wires up the dev-overlay hook in src/hooks.server.{ts,js}. --force does not apply
-                    to either \u2014 an existing registration is always left as-is.
+                    to either of these two \u2014 an existing registration is always left as-is.
+                    claude-skill writes a Claude Code skill (.claude/skills/svelte-vitals/SKILL.md); cursor-rules
+                    writes a Cursor rules file (.cursor/rules/svelte-vitals.mdc). Both are generated from the
+                    current rule set and support --force to regenerate.
   --scope <scope>   project | global (applies to all selected clients; codex is always global)
   --yes, -y         Skip the confirmation prompt
   --dry-run         Print the planned changes and exit without writing
@@ -661,7 +834,143 @@ async function runInstallCli(args) {
   for (const w of warnings) console.error(w);
   for (const e of errors) console.error(e);
   if (!flags) return 2;
-  return runInstall(flags, realIO(), clackPrompts());
+  return runInstall(flags, realIO(), clackPrompts(), readPackageVersion());
+}
+
+// src/ci/cli.ts
+import { join as join4 } from "path";
+import mri2 from "mri";
+
+// src/ci/workflow.ts
+var WORKFLOW_PATH = ".github/workflows/svelte-vitals.yml";
+function planWorkflowWrite(existing, force) {
+  if (existing === void 0) return { status: "created" };
+  if (!force) return { status: "exists" };
+  return { status: "updated" };
+}
+function buildWorkflowYaml(opts) {
+  const v = opts.version;
+  return [
+    `# Generated by \`svelte-vitals ci install\` (svelte-vitals ${v}).`,
+    "# Re-run with --force to regenerate.",
+    "name: svelte-vitals",
+    "",
+    "on:",
+    "  pull_request:",
+    "",
+    "permissions:",
+    "  contents: read",
+    "  pull-requests: write",
+    "",
+    "jobs:",
+    "  svelte-vitals:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "      - uses: actions/setup-node@v4",
+    "        with:",
+    "          node-version: 24",
+    "      - name: Scan (inline annotations + gate)",
+    "        id: scan",
+    "        continue-on-error: true",
+    "        run: >",
+    `          npx -y svelte-vitals@${v} .`,
+    "          --diff origin/${{ github.base_ref }}",
+    "          --baseline origin/${{ github.base_ref }}",
+    "          --reporter github",
+    "      - name: Markdown summary",
+    "        run: >",
+    `          npx -y svelte-vitals@${v} .`,
+    "          --diff origin/${{ github.base_ref }}",
+    "          --baseline origin/${{ github.base_ref }}",
+    "          --reporter md > svelte-vitals-report.md || true",
+    "      - name: Job summary",
+    '        run: cat svelte-vitals-report.md >> "$GITHUB_STEP_SUMMARY"',
+    "      - name: PR comment (sticky)",
+    "        if: github.event.pull_request.head.repo.full_name == github.repository",
+    "        continue-on-error: true",
+    "        uses: actions/github-script@v7",
+    "        with:",
+    "          script: |",
+    "            const fs = require('fs');",
+    "            const marker = '<!-- svelte-vitals-report -->';",
+    "            const body = marker + '\\n' + fs.readFileSync('svelte-vitals-report.md', 'utf8');",
+    "            const { data: comments } = await github.rest.issues.listComments({",
+    "              ...context.repo, issue_number: context.issue.number, per_page: 100",
+    "            });",
+    "            const mine = comments.find(c => c.body && c.body.startsWith(marker));",
+    "            if (mine) {",
+    "              await github.rest.issues.updateComment({ ...context.repo, comment_id: mine.id, body });",
+    "            } else {",
+    "              await github.rest.issues.createComment({ ...context.repo, issue_number: context.issue.number, body });",
+    "            }",
+    "      - name: Gate",
+    "        if: steps.scan.outcome == 'failure'",
+    "        run: |",
+    '          echo "svelte-vitals found blocking issues (see annotations above)."',
+    "          exit 1",
+    ""
+  ].join("\n");
+}
+
+// src/ci/cli.ts
+var CI_HELP = `svelte-vitals ci \u2014 scaffold CI integration
+
+Usage:
+  svelte-vitals ci install [options]
+
+Adds a GitHub Actions workflow (${WORKFLOW_PATH}) that scans pull requests, posts inline
+annotations + a job summary, and maintains a sticky PR comment with the findings.
+
+Options:
+  --force       Overwrite an existing workflow file
+  --dry-run     Print the plan and exit without writing
+  -h, --help    Show this help`;
+async function runCiCli(args, io = realIO()) {
+  const sub = args[0];
+  if (sub === "--help" || sub === "-h") {
+    io.log(CI_HELP);
+    return 0;
+  }
+  if (sub !== "install") {
+    io.log(CI_HELP);
+    return 2;
+  }
+  const argv = mri2(args.slice(1), {
+    boolean: ["force", "dry-run", "help"],
+    alias: { h: "help" }
+  });
+  if (argv.help) {
+    io.log(CI_HELP);
+    return 0;
+  }
+  const path = join4(io.cwd, WORKFLOW_PATH);
+  const existing = io.readFile(path);
+  const plan = planWorkflowWrite(existing, Boolean(argv.force));
+  io.log("Plan:");
+  io.log(`  ${WORKFLOW_PATH}  [${plan.status}]`);
+  if (argv["dry-run"]) {
+    io.log("Dry run \u2014 no files written.");
+    return 0;
+  }
+  if (plan.status === "exists") {
+    io.log(`= already installed (${WORKFLOW_PATH}) \u2014 use --force to regenerate.`);
+  } else {
+    const version = readPackageVersion();
+    try {
+      io.writeFile(path, buildWorkflowYaml({ version }));
+      io.log(`\u2713 ${plan.status} ${WORKFLOW_PATH}`);
+    } catch (err) {
+      io.errorLog(
+        `svelte-vitals: failed to write ${WORKFLOW_PATH}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return 2;
+    }
+  }
+  io.log("Done. Commit the workflow file and open a PR to see it in action.");
+  return 0;
 }
 
 // src/bin.ts
@@ -669,7 +978,8 @@ var HELP = `svelte-vitals \u2014 a deterministic SvelteKit code-health scanner (
 
 Usage:
   svelte-vitals [path] [options]
-  svelte-vitals install          Set up the MCP server for Claude Code / Cursor / Codex
+  svelte-vitals install          Set up the MCP server, Vite integration, or agent skills/rules
+  svelte-vitals ci install       Add a GitHub Actions PR gate (annotations + summary comment)
 
 Options:
   --meta-components <names>   Comma-separated component names that emit head metadata
@@ -677,8 +987,9 @@ Options:
   --route <glob>              Only analyze routes matching this glob
   --diff [ref]                Report only findings in files changed vs ref (default HEAD; e.g. --diff main)
   --staged                    Report only findings in files staged for commit (pre-commit gate)
+  --baseline <ref>            Report only findings not present at ref (compare against e.g. origin/main)
   --by-route                  Show per-route score breakdown in console output
-  --reporter <fmt>            console | json | agent | sarif | github | html (auto: agent under AI-agent envs, github under GitHub Actions)
+  --reporter <fmt>            console | json | agent | sarif | github | html | md (auto: agent under AI-agent envs, github under GitHub Actions)
   --out-file <path>           Output path for --reporter html (default: svelte-vitals-report.html; '-' for stdout)
   --json                      Alias for --reporter=json
   --fail-on <severity>        Fail (exit 1) when any finding reaches this severity: critical | warning | info
@@ -686,7 +997,9 @@ Options:
   --min-health <0-100>        Fail (exit 1) when the combined Health score is below this value
   --rules <ids>               Comma-separated rule ids to enable (all others disabled)
   --ignore <ids>              Comma-separated rule ids to disable
+  --category <cats>           Comma-separated categories to analyze: seo | performance | correctness | security | architecture
   --weights <pairs>           Per-category Health weight overrides, e.g. seo=2,performance=1 (unlisted categories default to 1)
+  --score                     Print only the combined Health score (works with --min-health for gating)
   --no-color                  Disable ANSI color in console output
   -h, --help                  Show this help
   -v, --version               Show version
@@ -699,15 +1012,26 @@ Exit codes:
   1  critical finding present (or --fail-on threshold reached)
   2  execution error (not a SvelteKit project / internal error)`;
 var VERSION = readPackageVersion();
+async function selectApp(apps) {
+  const res = await p2.select({
+    message: "Multiple SvelteKit apps found \u2014 which one should svelte-vitals analyze?",
+    options: apps.map((a) => ({ value: a, label: a }))
+  });
+  return p2.isCancel(res) ? null : res;
+}
 async function main() {
   const rawArgs = process.argv.slice(2);
   if (rawArgs[0] === "install") {
     const code2 = await runInstallCli(rawArgs.slice(1));
     process.exit(code2);
   }
-  const argv = mri2(process.argv.slice(2), {
+  if (rawArgs[0] === "ci") {
+    const code2 = await runCiCli(rawArgs.slice(1));
+    process.exit(code2);
+  }
+  const argv = mri3(process.argv.slice(2), {
     alias: { h: "help", v: "version" },
-    boolean: ["by-route", "json", "fail-on-warning", "staged", "no-color"],
+    boolean: ["by-route", "json", "fail-on-warning", "staged", "no-color", "score"],
     string: [
       "meta-components",
       "treat-dynamic-as",
@@ -719,7 +1043,9 @@ async function main() {
       "min-health",
       "out-file",
       "diff",
-      "weights"
+      "baseline",
+      "weights",
+      "category"
     ]
   });
   if (argv.help) {
@@ -727,7 +1053,7 @@ async function main() {
     process.exit(0);
   }
   if (argv.version) {
-    console.log(VERSION);
+    console.log(`${VERSION} (core ${readCoreVersion()})`);
     process.exit(0);
   }
   const { options, warnings, errors } = resolveArgs(argv);
@@ -744,7 +1070,7 @@ async function main() {
     }
     minHealth = n;
   }
-  const code = await run({ ...options, minHealth, noColor: argv["no-color"] });
+  const code = await run({ ...options, minHealth, noColor: argv["no-color"], selectApp });
   process.exit(code);
 }
 void main();

package/dist/{chunk-ZE3M3T6U.js → chunk-B3RVLTZY.js}

@@ -1,6 +1,6 @@
 // src/index.ts
 import { mkdirSync, writeFileSync } from "fs";
-import { dirname } from "path";
+import { dirname as dirname2, join as join5 } from "path";
 import {
   allRules as allRules2,
   runRules,
@@ -10,6 +10,7 @@ import {
   formatSarifReport,
   formatGithubReport,
   formatHtmlReport,
+  formatMarkdownReport,
   summarize,
   hasFailureAtOrAbove,
   computeHealth,
@@ -73,7 +74,7 @@ async function detectProject(rt, cwd) {
   const hasRoutes = await rt.exists(rt.join(cwd, ROUTES_DIR));
   if (hasKitDep || hasConfig && hasRoutes) return;
   throw new ProjectError(
-    "No SvelteKit project found in the current directory. Run this inside a SvelteKit app, or pass --config."
+    "No SvelteKit project found in the current directory. Run this inside a SvelteKit app, or pass a path (e.g. npx svelte-vitals apps/web)."
   );
 }
 async function enumerateRoutePages(rt, cwd) {
@@ -650,6 +651,23 @@ async function collectRoutes(rt, cwd, config = defaultConfig) {
 // src/providers/source/components.ts
 import { collectComponentFacts } from "@svelte-vitals/core";
 
+// src/discover-apps.ts
+import { existsSync } from "fs";
+import { join as join2, dirname } from "path";
+import { glob } from "tinyglobby";
+async function discoverApps(cwd) {
+  const configs = await glob("**/svelte.config.{js,ts}", {
+    cwd,
+    dot: false,
+    deep: 4,
+    ignore: ["**/node_modules/**", "**/.svelte-kit/**", "**/build/**", "**/dist/**", "**/.git/**"]
+  });
+  const dirs = [...new Set(configs.map((c) => dirname(c)))].filter(
+    (d) => d !== "." && existsSync(join2(cwd, d, "src", "routes"))
+  );
+  return dirs.sort();
+}
+
 // src/version.ts
 import { readFileSync } from "fs";
 function readPackageVersion() {
@@ -660,11 +678,20 @@ function readPackageVersion() {
     return "0.0.0";
   }
 }
+function readCoreVersion() {
+  try {
+    const entry = import.meta.resolve("@svelte-vitals/core");
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", entry), "utf8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 
 // src/reporter-resolve.ts
 var AGENT_ENV_VARS = ["CLAUDECODE", "SVELTE_VITALS_AGENT"];
 function isReporterName(value) {
-  return value === "console" || value === "json" || value === "agent" || value === "sarif" || value === "github" || value === "html";
+  return value === "console" || value === "json" || value === "agent" || value === "sarif" || value === "github" || value === "html" || value === "md";
 }
 function isAgentEnv(env = process.env) {
   return AGENT_ENV_VARS.some((key) => {
@@ -711,6 +738,58 @@ function filterToChangedFiles(results, changed) {
   return results.filter((r) => r.location !== void 0 && changed.has(r.location));
 }
 
+// src/baseline.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join as join3 } from "path";
+function git2(args, cwd) {
+  return execFileSync2("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+}
+function findingKey(r) {
+  return `${r.id}::${r.route ?? ""}::${r.location ?? ""}`;
+}
+function checkoutBaseline(cwd, ref) {
+  let tmp;
+  try {
+    const repoRoot = git2(["rev-parse", "--show-toplevel"], cwd).trim();
+    const showPrefix = git2(["rev-parse", "--show-prefix"], cwd).trim().replace(/\/+$/, "");
+    tmp = mkdtempSync(join3(tmpdir(), "svelte-vitals-baseline-"));
+    const wt = join3(tmp, "wt");
+    git2(["worktree", "add", "--detach", wt, ref], repoRoot);
+    const analyzeCwd = showPrefix ? join3(wt, showPrefix) : wt;
+    const tmpDir = tmp;
+    const cleanup = () => {
+      try {
+        execFileSync2("git", ["worktree", "remove", "--force", wt], {
+          cwd: repoRoot,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "ignore"]
+        });
+      } catch {
+        try {
+          execFileSync2("git", ["worktree", "prune"], {
+            cwd: repoRoot,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+          });
+        } catch {
+        }
+      } finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+      }
+    };
+    return { analyzeCwd, cleanup };
+  } catch {
+    if (tmp !== void 0) rmSync(tmp, { recursive: true, force: true });
+    return void 0;
+  }
+}
+function filterToNewFindings(results, baselineResults) {
+  const baselineKeys = new Set(baselineResults.map(findingKey));
+  return results.filter((r) => !baselineKeys.has(findingKey(r)));
+}
+
 // src/color.ts
 import { noColorPalette } from "@svelte-vitals/core";
 var wrap = (open, close = 0) => (s) => `\x1B[${open}m${s}\x1B[${close}m`;
@@ -754,8 +833,8 @@ function startSpinner(text, opts) {
 }
 
 // src/config-file.ts
-import { existsSync } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { join as join4 } from "path";
 import { pathToFileURL } from "url";
 
 // src/rules-config.ts
@@ -852,7 +931,7 @@ function validateConfigFile(raw, path) {
   return { config, warnings };
 }
 async function loadConfigFile(cwd) {
-  const found = CONFIG_FILENAMES.map((name) => join2(cwd, name)).find((path) => existsSync(path));
+  const found = CONFIG_FILENAMES.map((name) => join4(cwd, name)).find((path) => existsSync2(path));
   if (!found) return void 0;
   let mod;
   try {
@@ -879,9 +958,9 @@ import { defineConfig as defineConfig2 } from "@svelte-vitals/core";
 function spinnerEnabled(opts) {
   return opts.reporter === "console" && opts.stderrIsTTY && !isAutoDetectedAgent(opts.rawReporter, opts.env) && colorEnabled({ reporter: opts.reporter, isTTY: opts.stderrIsTTY, env: opts.env, noColorFlag: opts.noColorFlag });
 }
-function routeMatcher(glob) {
-  if (!glob) return () => true;
-  const body = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, " ").replace(/\*/g, "[^/]*").replace(/\/ $/g, "(?:/.*)?").replace(/^ \//g, "(?:.*/)?").replace(/ \//g, "(?:.*/)?").replace(/\/ /g, "(?:/.*)?").replace(/ /g, ".*");
+function routeMatcher(glob2) {
+  if (!glob2) return () => true;
+  const body = glob2.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, " ").replace(/\*/g, "[^/]*").replace(/\/ $/g, "(?:/.*)?").replace(/^ \//g, "(?:.*/)?").replace(/ \//g, "(?:.*/)?").replace(/\/ /g, "(?:/.*)?").replace(/ /g, ".*");
   const re = new RegExp(`^${body}$`);
   return (route) => re.test(route.replace(/^\//, ""));
 }
@@ -907,7 +986,8 @@ async function analyzeProject(opts = {}) {
   const headings = collected.headings.filter((h) => matches(h.route));
   const project = await collectProjectFacts(rt, cwd);
   const components = opts.route ? [] : await collectComponentFacts(rt, cwd);
-  const rules = selectRules(allRules2, config);
+  const selected = selectRules(allRules2, config);
+  const rules = opts.categories ? selected.filter((r) => opts.categories.includes(r.category)) : selected;
   const results = applyRuleSeverities(
     await runRules(rules, { heads, images, headings, components, project, config }),
     config
@@ -924,7 +1004,7 @@ async function run(opts = {}) {
   const env = opts.env ?? process.env;
   const reporter = resolveReporter(opts.reporter, env);
   const spinner = startSpinner("Analyzing\u2026", {
-    enabled: spinnerEnabled({
+    enabled: !opts.score && spinnerEnabled({
       reporter,
       rawReporter: opts.reporter,
       stderrIsTTY: opts.stderrIsTTY ?? !!process.stderr.isTTY,
@@ -932,25 +1012,75 @@ async function run(opts = {}) {
       noColorFlag: opts.noColor
     })
   });
+  let cwd = opts.cwd ?? process.cwd();
   let analysis;
   try {
     analysis = await analyzeProject({
-      cwd: opts.cwd ?? process.cwd(),
+      cwd,
       metaComponents: opts.metaComponents,
       treatDynamicAs: opts.treatDynamicAs,
       route: opts.route,
       failOn: opts.failOn,
       rules: opts.rules,
-      weights: opts.weights
+      weights: opts.weights,
+      categories: opts.categories
     });
   } catch (err) {
     spinner.stop();
     if (err instanceof ProjectError) {
-      errorLog(err.message);
+      if (opts.explicitPath) {
+        errorLog(err.message);
+        return 2;
+      }
+      const apps = await discoverApps(cwd);
+      if (apps.length === 0) {
+        errorLog(err.message);
+        return 2;
+      }
+      let chosen;
+      if (apps.length === 1) {
+        errorLog(`svelte-vitals: detected SvelteKit app at ${apps[0]}; analyzing it.`);
+        chosen = apps[0];
+      } else if (
+        // clack reads from stdin and renders to stdout, so both must be interactive —
+        // a piped/redirected stdin would leave the prompt hanging for input that never comes.
+        (opts.stdinIsTTY ?? !!process.stdin.isTTY) && (opts.stdoutIsTTY ?? !!process.stdout.isTTY) && opts.selectApp
+      ) {
+        const selection = await opts.selectApp(apps);
+        if (selection === null) {
+          log("Cancelled.");
+          return 0;
+        }
+        chosen = selection;
+      } else {
+        errorLog(`svelte-vitals: multiple SvelteKit apps found: ${apps.join(", ")}.`);
+        errorLog(`svelte-vitals: pass one as a path, e.g. \`npx svelte-vitals ${apps[0]}\`.`);
+        return 2;
+      }
+      cwd = join5(cwd, chosen);
+      try {
+        analysis = await analyzeProject({
+          cwd,
+          metaComponents: opts.metaComponents,
+          treatDynamicAs: opts.treatDynamicAs,
+          route: opts.route,
+          failOn: opts.failOn,
+          rules: opts.rules,
+          weights: opts.weights,
+          categories: opts.categories
+        });
+      } catch (err2) {
+        if (err2 instanceof ProjectError) {
+          errorLog(err2.message);
+          return 2;
+        }
+        errorLog(`svelte-vitals: ${err2 instanceof Error ? err2.message : String(err2)}`);
+        return 2;
+      }
+    } else {
+      errorLog(`svelte-vitals: ${err instanceof Error ? err.message : String(err)}`);
       return 2;
     }
-    errorLog(`svelte-vitals: ${err instanceof Error ? err.message : String(err)}`);
-    return 2;
   }
   spinner.stop();
   for (const w of analysis.warnings) errorLog(`svelte-vitals: ${w}`);
@@ -958,7 +1088,6 @@ async function run(opts = {}) {
     const { config, version } = analysis;
     let results = analysis.results;
     if (opts.staged || opts.diffBase !== void 0) {
-      const cwd = opts.cwd ?? process.cwd();
       const changed = opts.staged ? getChangedFiles(cwd, { staged: true }) : getChangedFiles(cwd, { base: opts.diffBase });
       if (changed === void 0) {
         errorLog(
@@ -968,46 +1097,78 @@ async function run(opts = {}) {
         results = filterToChangedFiles(results, changed);
       }
     }
-    if (reporter === "agent" && isAutoDetectedAgent(opts.reporter, env)) {
-      errorLog(
-        "svelte-vitals: agent reporter auto-selected (AI-agent env detected); override with --reporter console|json."
-      );
-    }
-    if (reporter === "github" && isAutoDetectedGithub(opts.reporter, env)) {
-      errorLog(
-        "svelte-vitals: github reporter auto-selected (GitHub Actions detected); override with --reporter console|json|sarif."
-      );
+    if (opts.baseline !== void 0) {
+      const checkout = checkoutBaseline(cwd, opts.baseline);
+      if (checkout === void 0) {
+        errorLog(
+          `svelte-vitals: could not analyze baseline '${opts.baseline}' (not a git repo, git unavailable, or bad ref); reporting all findings.`
+        );
+      } else {
+        try {
+          const base = await analyzeProject({
+            cwd: checkout.analyzeCwd,
+            metaComponents: opts.metaComponents,
+            treatDynamicAs: opts.treatDynamicAs,
+            route: opts.route,
+            failOn: opts.failOn,
+            rules: opts.rules,
+            weights: opts.weights,
+            categories: opts.categories
+          });
+          results = filterToNewFindings(results, base.results);
+        } catch {
+          errorLog(`svelte-vitals: baseline analysis of '${opts.baseline}' failed; reporting all findings.`);
+        } finally {
+          checkout.cleanup();
+        }
+      }
     }
-    if (reporter === "json") {
-      log(formatJsonReport(results, config, { version }));
-    } else if (reporter === "agent") {
-      log(formatAgentReport(results, config));
-    } else if (reporter === "sarif") {
-      log(formatSarifReport(results, config, { version }));
-    } else if (reporter === "github") {
-      const output = formatGithubReport(results, config);
-      if (output) log(output);
-    } else if (reporter === "html") {
-      const html = formatHtmlReport(results, config, { version });
-      if (opts.outFile === "-") {
-        log(html);
+    if (opts.score) {
+      log(String(computeHealth(results, config).health));
+    } else {
+      if (reporter === "agent" && isAutoDetectedAgent(opts.reporter, env)) {
+        errorLog(
+          "svelte-vitals: agent reporter auto-selected (AI-agent env detected); override with --reporter console|json."
+        );
+      }
+      if (reporter === "github" && isAutoDetectedGithub(opts.reporter, env)) {
+        errorLog(
+          "svelte-vitals: github reporter auto-selected (GitHub Actions detected); override with --reporter console|json|sarif."
+        );
+      }
+      if (reporter === "json") {
+        log(formatJsonReport(results, config, { version }));
+      } else if (reporter === "agent") {
+        log(formatAgentReport(results, config));
+      } else if (reporter === "sarif") {
+        log(formatSarifReport(results, config, { version }));
+      } else if (reporter === "github") {
+        const output = formatGithubReport(results, config);
+        if (output) log(output);
+      } else if (reporter === "html") {
+        const html = formatHtmlReport(results, config, { version, coreVersion: readCoreVersion() });
+        if (opts.outFile === "-") {
+          log(html);
+        } else {
+          const path = opts.outFile || "svelte-vitals-report.html";
+          const write = opts.writeFile ?? ((p, c) => {
+            mkdirSync(dirname2(p), { recursive: true });
+            writeFileSync(p, c);
+          });
+          write(path, html);
+          errorLog(`svelte-vitals: wrote report to ${path}`);
+        }
+      } else if (reporter === "md") {
+        log(formatMarkdownReport(results, config, { version }));
       } else {
-        const path = opts.outFile || "svelte-vitals-report.html";
-        const write = opts.writeFile ?? ((p, c) => {
-          mkdirSync(dirname(p), { recursive: true });
-          writeFileSync(p, c);
+        const colorOn = colorEnabled({
+          reporter,
+          isTTY: opts.stdoutIsTTY ?? !!process.stdout.isTTY,
+          env,
+          noColorFlag: opts.noColor
         });
-        write(path, html);
-        errorLog(`svelte-vitals: wrote report to ${path}`);
+        log(formatConsoleReport(results, config, { byRoute: opts.byRoute ?? false, palette: paletteFor(colorOn) }));
       }
-    } else {
-      const colorOn = colorEnabled({
-        reporter,
-        isTTY: opts.stdoutIsTTY ?? !!process.stdout.isTTY,
-        env,
-        noColorFlag: opts.noColor
-      });
-      log(formatConsoleReport(results, config, { byRoute: opts.byRoute ?? false, palette: paletteFor(colorOn) }));
     }
     const summary = summarize(results, config);
     const failBySeverity = hasFailureAtOrAbove(summary, config.failOn);
@@ -1022,6 +1183,7 @@ async function run(opts = {}) {
 export {
   ProjectError,
   readPackageVersion,
+  readCoreVersion,
   isReporterName,
   findUnknownRuleIds,
   knownRuleIds,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { RuleSetting, Config, Severity, Category, Result } from '@svelte-vitals/core';
 export { defineConfig } from '@svelte-vitals/core';
 
-type ReporterName = 'console' | 'json' | 'agent' | 'sarif' | 'github' | 'html';
+type ReporterName = 'console' | 'json' | 'agent' | 'sarif' | 'github' | 'html' | 'md';
 
 /** Thrown when the target directory is not a SvelteKit project (CLI maps to exit 2). */
 declare class ProjectError extends Error {
@@ -59,10 +59,14 @@ interface RunOptions {
     rules?: Record<string, RuleSetting>;
     /** Per-category weights for the combined Health score (flag > config file > default 1 each). */
     weights?: Partial<Record<Category, number>>;
+    /** Restrict analysis to rules in these categories (applied after rules/ignore selection). */
+    categories?: Category[];
     /** Override process.env for reporter auto-detection (mainly useful in tests). */
     env?: NodeJS.ProcessEnv;
     /** Fail (exit 1) when the combined Health score is below this value (0–100). */
     minHealth?: number;
+    /** Print only the combined Health score (integer) to stdout. */
+    score?: boolean;
     /** Output path for --reporter html (default 'svelte-vitals-report.html'; '-' = stdout). */
     outFile?: string;
     /** Injected file writer for --reporter html (defaults to node:fs writeFileSync). Mainly for tests. */
@@ -71,12 +75,20 @@ interface RunOptions {
     diffBase?: string;
     /** Report only findings in files staged for commit. Takes precedence over `diffBase`. */
     staged?: boolean;
+    /** Report only findings not present when analyzing this git ref (e.g. the PR base). */
+    baseline?: string;
     /** Disable ANSI color in console output. */
     noColor?: boolean;
     /** Override stdout TTY detection (tests). */
     stdoutIsTTY?: boolean;
     /** Override stderr TTY detection (tests). */
     stderrIsTTY?: boolean;
+    /** Override stdin TTY detection (tests). */
+    stdinIsTTY?: boolean;
+    /** True when the user passed a path argument — discovery must not run (design: never reinterpret an explicit target). */
+    explicitPath?: boolean;
+    /** Injected picker for the monorepo app selector (bin.ts wires a clack implementation; null = cancelled). */
+    selectApp?: (apps: string[]) => Promise<string | null>;
 }
 /**
  * Whether the "Analyzing…" spinner should run. Unlike color, the spinner animates
@@ -103,6 +115,8 @@ interface AnalyzeOptions {
     rules?: Record<string, RuleSetting>;
     /** Per-category weights for the combined Health score (flag > config file > default 1 each). */
     weights?: Partial<Record<Category, number>>;
+    /** Restrict analysis to rules in these categories (applied after rules/ignore selection). */
+    categories?: Category[];
 }
 interface AnalyzeResult {
     results: Result[];

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   routeMatcher,
   run,
   spinnerEnabled
-} from "./chunk-ZE3M3T6U.js";
+} from "./chunk-B3RVLTZY.js";
 export {
   ProjectError,
   analyzeProject,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-vitals",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "A SvelteKit SEO checker — not a runtime Web Vitals reporter. Static analysis of your routes' head metadata.",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "smol-toml": "^1.7.0",
     "svelte": "^5.56.4",
     "tinyglobby": "^0.2.17",
-    "@svelte-vitals/core": "0.20.0"
+    "@svelte-vitals/core": "0.22.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.2"