svelte-vitals 0.26.0 → 0.28.0

package/README.md

@@ -3,17 +3,17 @@
 [![npm](https://img.shields.io/npm/v/svelte-vitals)](https://www.npmjs.com/package/svelte-vitals)
 [![MIT](https://img.shields.io/npm/l/svelte-vitals)](https://opensource.org/licenses/MIT)
 
-> **A SvelteKit SEO checker — not a runtime Web Vitals reporter.**
-> Diagnose your project's SEO health by statically analyzing your source code, before it ships. No browser, no build server, no headless Chrome.
+> **A static SvelteKit code-health scanner — not a runtime Web Vitals reporter.**
+> Diagnose your project's SEO, Performance, Correctness, Security, and Architecture health by statically analyzing your source code, before it ships. No browser, no build server, no headless Chrome.
 >
-> **ESM-only** (Node 18+). Ships ES modules only; `require()` is unsupported by design.
+> **ESM-only** (Node 22.13+). Ships ES modules only; `require()` is unsupported by design.
 
 ```bash
 npx svelte-vitals@latest
 ```
 
-> [!NOTE]
-> **Early development.** Currently ships static-mode analysis and the first SEO rule (`<title>` presence). More rules, scoring, and a build-time plugin are on the roadmap. Output may change before `1.0`.
+> [!WARNING]
+> **Pre-1.0.** APIs, rule IDs, scoring, and output formats can change at any time, including breaking changes between minor releases.
 
 ## Usage
 
@@ -25,15 +25,31 @@ npx svelte-vitals@latest ./apps/web   # or a specific path
 ```
 
 ```
-Svelte Vitals  ·  SEO (static mode)
+Svelte Vitals  ·  static mode
 
-Critical (1)
+Health: 76/100
+SEO Score: 51/100   (route avg 61 · site −10)
+Architecture Score: 100/100   (route avg 100)
+
+Critical (2)
 ────────────────────────
 ✗ SEO001  Missing <title>
-            /none
-            src/routes/none/+page.svelte
+            /
+            src/routes/+page.svelte
+✗ SEO002  Missing <meta name="description">
+            /
+            src/routes/+page.svelte
+
+Warnings (10)
+────────────────────────
+✗ SEO003  Missing <link rel="canonical">
+            /
+            src/routes/+page.svelte
+            …and 1 more
+…and 1 more rule affected — run with --verbose to see all
 
-Passed (3)
+Passed (11)
+────────────────────────
 
 ↯ = set dynamically (verified at runtime).
 ```
@@ -44,14 +60,34 @@ On an interactive terminal wide enough for the mascot (20+ columns), a small lin
 
 ### Exit codes
 
-| Code | Meaning                                                         |
-| ---- | --------------------------------------------------------------- |
-| `0`  | No failing findings                                             |
-| `1`  | A critical finding is present                                   |
-| `2`  | Execution error (not a SvelteKit project, internal error, etc.) |
+| Code | Meaning                                                                     |
+| ---- | --------------------------------------------------------------------------- |
+| `0`  | No failing findings                                                         |
+| `1`  | Critical finding present, or `--fail-on` / `--min-health` threshold reached |
+| `2`  | Execution error (not a SvelteKit project, internal error, etc.)             |
 
 Useful as a CI gate.
 
+### Reporters
+
+`--reporter <fmt>` selects the output format: `console` (default), `json`, `agent`, `sarif`, `github`, `html` (self-contained, `--out-file`), and `md` (compact, for PR comments/job summaries). `agent` auto-selects inside known AI-agent harnesses (e.g. Claude Code); `github` auto-selects under GitHub Actions.
+
+### Ramping up on an existing project
+
+`--diff [ref]` / `--staged` scope findings to changed/staged files; `--baseline <ref>` scopes to findings that are genuinely new versus a ref; `--update-suppressions` records today's findings once so only newly-introduced issues gate the build afterward. `--rules`/`--ignore`/`--category` select which rules run, `--weights` reweights the combined Health score, and `--min-health`/`--score` gate or print just the number. A `svelte-vitals.config.{mjs,js,ts}` file (scaffolded via `svelte-vitals install --client config-file`) can set any of these once instead of repeating flags.
+
+### `svelte-vitals install`
+
+An interactive wizard that wires up the [MCP server](https://www.npmjs.com/package/@svelte-vitals/mcp), the [Vite plugin](https://www.npmjs.com/package/@svelte-vitals/vite)'s live dashboard, Agent Skills (`/svelte-vitals`, `/improve-svelte`) for Claude Code, Cursor, and Codex, and a GitHub Actions CI workflow — grouped by category in the picker so it's clear what each target is for:
+
+```bash
+npx svelte-vitals@latest install
+```
+
+### CI integration
+
+`svelte-vitals ci install` scaffolds a GitHub Actions workflow around `@svelte-vitals/action` — inline PR annotations, a job summary, and a sticky PR comment, no YAML to hand-write. The same workflow is also a selectable `ci-workflow` target inside `svelte-vitals install`, so it can be set up in the same pass as everything else. See [CI integration](https://oekazuma.github.io/svelte-vitals/guides/ci/).
+
 ### Agent-native output
 
 `svelte-vitals --reporter agent` emits a Markdown remediation document an AI coding agent can act on directly: each failing finding lists its location, a concrete fix (with a code snippet), and an acceptance check.
@@ -64,7 +100,7 @@ svelte-vitals resolves the effective `<head>` of every route by walking the layo
 
 A dynamic title such as `<title>{data.title}</title>` — the most common, correct SvelteKit pattern — is **never** flagged as missing; it passes with a `↯` marker. Only genuinely missing or empty metadata is penalized.
 
-See the [project README](https://github.com/oekazuma/svelte-vitals#readme) for the full picture and roadmap.
+See the [full documentation](https://oekazuma.github.io/svelte-vitals/) for every flag, rule, and reporter, or the [project README](https://github.com/oekazuma/svelte-vitals#readme) for the full picture and roadmap.
 
 ## License
 

package/dist/bin.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import {
+  CONFIG_FILENAMES,
   buildRulesConfig,
+  discoverApps,
   findUnknownRuleIds,
   isReporterName,
   knownRuleIds,
   readCoreVersion,
   readPackageVersion,
   run
-} from "./chunk-OCLDCX4Y.js";
+} from "./chunk-O5VMXV2Q.js";
 
 // src/bin.ts
 import mri3 from "mri";
@@ -183,7 +185,7 @@ import mri from "mri";
 import * as p from "@clack/prompts";
 
 // src/install/index.ts
-import { join as join3 } from "path";
+import { join as join4 } from "path";
 
 // src/install/clients.ts
 import { join } from "path";
@@ -292,21 +294,29 @@ function isViteTargetId(id) {
 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"
+    label: "Agent skill: svelte-vitals",
+    hint: "Teaches the agent svelte-vitals rules + when to run the scanner (Claude Code, Codex, Cursor)",
+    relPaths: [
+      ".claude/skills/svelte-vitals/SKILL.md",
+      ".agents/skills/svelte-vitals/SKILL.md",
+      ".cursor/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"
+    relPaths: [".cursor/rules/svelte-vitals.mdc"]
   },
   {
     id: "claude-skill-improve",
-    label: "Claude Code improve-svelte skill",
-    hint: "Senior-advisor audit \u2192 implementation plans (read-only), for a project-wide improvement roadmap",
-    relPath: ".claude/skills/improve-svelte/SKILL.md"
+    label: "Agent skill: improve-svelte",
+    hint: "Senior-advisor audit \u2192 implementation plans (read-only), for a project-wide improvement roadmap (Claude Code, Codex, Cursor)",
+    relPaths: [
+      ".claude/skills/improve-svelte/SKILL.md",
+      ".agents/skills/improve-svelte/SKILL.md",
+      ".cursor/skills/improve-svelte/SKILL.md"
+    ]
   }
 ];
 function agentTargetById(id) {
@@ -321,8 +331,7 @@ var CONFIG_TARGETS = [
   {
     id: "config-file",
     label: "Config file",
-    hint: "Scaffolds svelte-vitals.config.mjs with every option commented out",
-    relPath: "svelte-vitals.config.mjs"
+    hint: "Scaffolds svelte-vitals.config.{mjs,ts} (auto-picks the best one) with every option commented out"
   }
 ];
 function configTargetById(id) {
@@ -332,6 +341,60 @@ function isConfigTargetId(id) {
   return CONFIG_TARGETS.some((t) => t.id === id);
 }
 
+// src/ci/workflow.ts
+var WORKFLOW_PATH = ".github/workflows/svelte-vitals.yml";
+var CHECKOUT_SHA = "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0";
+var CHECKOUT_VERSION = "v7.0.0";
+function planWorkflowWrite(existing, force) {
+  if (existing === void 0) return { status: "created" };
+  if (!force) return { status: "exists" };
+  return { status: "updated" };
+}
+function buildWorkflowYaml(opts) {
+  const { actionSha, actionVersion } = opts;
+  return [
+    "# Generated by svelte-vitals (`ci install` or `install --client ci-workflow`).",
+    "# 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@${CHECKOUT_SHA} # ${CHECKOUT_VERSION}`,
+    "        with:",
+    "          fetch-depth: 0",
+    `      - uses: oekazuma/svelte-vitals/packages/action@${actionSha} # @svelte-vitals/action@${actionVersion}`,
+    "        with:",
+    "          diff: origin/${{ github.base_ref }}",
+    "          baseline: origin/${{ github.base_ref }}",
+    ""
+  ].join("\n");
+}
+
+// src/install/ci-targets.ts
+var CI_TARGETS = [
+  {
+    id: "ci-workflow",
+    label: "GitHub Actions CI",
+    hint: "Scaffolds a workflow that runs @svelte-vitals/action on pull requests \u2014 inline annotations, job summary, sticky PR comment",
+    relPath: WORKFLOW_PATH
+  }
+];
+function ciTargetById(id) {
+  return CI_TARGETS.find((t) => t.id === id);
+}
+function isCiTargetId(id) {
+  return CI_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"];
@@ -722,18 +785,71 @@ measure), say so and suggest the runtime check instead of guessing.
 }
 
 // src/install/config-content.ts
-function buildConfigFileTemplate() {
-  return `// svelte-vitals config file \u2014 https://oekazuma.github.io/svelte-vitals/guides/configuration/
-export default {
-  // treatDynamicAs: 'pass', // 'pass' | 'warn' | 'fail' \u2014 how {data.title}-style dynamic values are scored
+function buildConfigFileTemplate(opts = {}) {
+  const header = "// svelte-vitals config file \u2014 https://oekazuma.github.io/svelte-vitals/guides/configuration/\n";
+  const options = `  // treatDynamicAs: 'pass', // 'pass' | 'warn' | 'fail' \u2014 how {data.title}-style dynamic values are scored
   // metaComponents: ['Seo'], // component names that resolve SEO tags into <head>
   // rules: {}, // e.g. { SEO001: 'off' } to disable a rule
   // failOn: 'critical', // 'critical' | 'warning' | 'info'
-  // weights: {} // e.g. { seo: 2 } \u2014 per-category weight for the combined Health score
+  // weights: {} // e.g. { seo: 2 } \u2014 per-category weight for the combined Health score`;
+  if (opts.useDefineConfig) {
+    return `${header}import { defineConfig } from 'svelte-vitals';
+
+export default defineConfig({
+${options}
+});
+`;
+  }
+  if (opts.useCommonJs) {
+    return `${header}module.exports = {
+${options}
+};
+`;
+  }
+  return `${header}export default {
+${options}
 };
 `;
 }
 
+// src/install/config-file-format.ts
+import { join as join2 } from "path";
+function nodeSupportsNativeTypeScript(version) {
+  const match = /^v?(\d+)\.(\d+)/.exec(version);
+  if (!match) return false;
+  const major = Number(match[1]);
+  const minor = Number(match[2]);
+  return major > 23 || major === 23 && minor >= 6 || major === 22 && minor >= 18;
+}
+function findExistingConfigFile(readFile, cwd) {
+  return CONFIG_FILENAMES.find((rel) => readFile(join2(cwd, rel)) !== void 0);
+}
+function hasSvelteVitalsDependency(readFile, cwd) {
+  const raw = readFile(join2(cwd, "package.json"));
+  if (raw === void 0) return false;
+  try {
+    const pkg = JSON.parse(raw);
+    return Boolean(pkg.dependencies?.["svelte-vitals"] ?? pkg.devDependencies?.["svelte-vitals"]);
+  } catch {
+    return false;
+  }
+}
+function isEsmProject(readFile, cwd) {
+  const raw = readFile(join2(cwd, "package.json"));
+  if (raw === void 0) return false;
+  try {
+    return JSON.parse(raw).type === "module";
+  } catch {
+    return false;
+  }
+}
+function detectBestConfigExtension(opts) {
+  if (!nodeSupportsNativeTypeScript(opts.nodeVersion)) return "mjs";
+  const looksTypeScript = opts.readFile(join2(opts.cwd, "tsconfig.json")) !== void 0 || opts.readFile(join2(opts.cwd, "vite.config.ts")) !== void 0;
+  if (!looksTypeScript) return "mjs";
+  return hasSvelteVitalsDependency(opts.readFile, opts.cwd) ? "ts" : "mjs";
+}
+
 // src/install/codemod-vite-config.ts
 import { parseModule, generateCode, builders, MagicastError } from "magicast";
 var MANUAL_SNIPPET = `import { svelteVitals } from '@svelte-vitals/vite';
@@ -840,21 +956,25 @@ function codemodHooksServer(existing) {
 }
 
 // src/install/package-manager.ts
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 var LOCKFILE_TO_PM = {
   "pnpm-lock.yaml": "pnpm",
   "yarn.lock": "yarn",
   "bun.lock": "bun",
-  "bun.lockb": "bun"
+  "bun.lockb": "bun",
+  "package-lock.json": "npm"
 };
-function detectPackageManager(io) {
+function detectPackageManagerFromLockfile(io) {
   for (const [file, pm] of Object.entries(LOCKFILE_TO_PM)) {
-    if (io.readFile(join2(io.cwd, file)) !== void 0) return pm;
+    if (io.readFile(join3(io.cwd, file)) !== void 0) return pm;
   }
-  return "npm";
+  return void 0;
+}
+function detectPackageManager(io) {
+  return detectPackageManagerFromLockfile(io) ?? "npm";
 }
 function hasVitePackage(io) {
-  const raw = io.readFile(join2(io.cwd, "package.json"));
+  const raw = io.readFile(join3(io.cwd, "package.json"));
   if (raw === void 0) return false;
   try {
     const pkg = JSON.parse(raw);
@@ -868,7 +988,7 @@ function installCommand(pm) {
   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"));
+  const raw = io.readFile(join3(io.cwd, "node_modules/@svelte-vitals/vite/package.json"));
   if (raw === void 0) return void 0;
   try {
     return JSON.parse(raw).version;
@@ -877,28 +997,35 @@ function readInstalledViteVersion(io) {
   }
 }
 
+// src/ci/action-pin.generated.ts
+var ACTION_SHA = "90b7538b5bed65ac123f46d77511dd4b48fa69bb";
+var ACTION_VERSION = "0.3.3";
+
 // src/install/index.ts
+function detectPackageManagerNear(io, appDir) {
+  return detectPackageManagerFromLockfile({ ...io, cwd: appDir }) ?? detectPackageManager(io);
+}
 function planForClient(client, scope, io, force) {
   const path = client.resolvePath(scope, io.cwd, io.home);
   const existing = io.readFile(path);
   const merged = client.format === "toml" ? mergeToml(existing, MCP_ENTRY, force) : mergeJson(existing, MCP_ENTRY, force);
   return { id: client.id, label: client.label, scope, path, status: merged.status, content: merged.content };
 }
-function resolveCandidate(io, candidates) {
+function resolveCandidate(io, baseDir, candidates) {
   for (const rel of candidates) {
-    const path = join3(io.cwd, rel);
+    const path = join4(baseDir, rel);
     const content = io.readFile(path);
     if (content !== void 0) return { path, content };
   }
-  return { path: join3(io.cwd, candidates[0]), content: void 0 };
+  return { path: join4(baseDir, candidates[0]), content: void 0 };
 }
-function planForVitePlugin(io) {
-  const { path, content } = resolveCandidate(io, ["vite.config.ts", "vite.config.js", "vite.config.mjs"]);
+function planForVitePlugin(io, appDir) {
+  const { path, content } = resolveCandidate(io, appDir, ["vite.config.ts", "vite.config.js", "vite.config.mjs"]);
   const result = codemodViteConfig(content);
   return { id: "vite-plugin", label: viteTargetById("vite-plugin").label, path, ...result };
 }
-function planForViteHooks(io) {
-  const { path, content } = resolveCandidate(io, ["src/hooks.server.ts", "src/hooks.server.js"]);
+function planForViteHooks(io, appDir) {
+  const { path, content } = resolveCandidate(io, appDir, ["src/hooks.server.ts", "src/hooks.server.js"]);
   const result = codemodHooksServer(content);
   return { id: "vite-hooks", label: viteTargetById("vite-hooks").label, path, ...result };
 }
@@ -917,18 +1044,40 @@ function agentTargetContent(id, version) {
   }
 }
 function planForAgentTarget(target, io, force, version) {
-  const path = join3(io.cwd, target.relPath);
-  const existing = io.readFile(path);
   const content = agentTargetContent(target.id, version);
-  const status = existing === void 0 ? "created" : force ? "updated" : "exists";
-  return { id: target.id, label: target.label, path, status, content };
+  return target.relPaths.map((relPath) => {
+    const path = join4(io.cwd, relPath);
+    const existing = io.readFile(path);
+    const status = existing === void 0 ? "created" : force ? "updated" : "exists";
+    return { id: target.id, label: target.label, path, status, content };
+  });
 }
-function planForConfigTarget(target, io, force) {
-  const path = join3(io.cwd, target.relPath);
+function planForConfigTarget(target, io, force, appDir) {
+  const existingRel = findExistingConfigFile(io.readFile, appDir);
+  if (existingRel !== void 0) {
+    const path2 = join4(appDir, existingRel);
+    const status = force ? "updated" : "exists";
+    const content2 = force ? buildConfigFileTemplate({
+      useDefineConfig: existingRel.endsWith(".ts") && hasSvelteVitalsDependency(io.readFile, appDir),
+      useCommonJs: existingRel.endsWith(".js") && !isEsmProject(io.readFile, appDir)
+    }) : void 0;
+    return { id: target.id, label: target.label, path: path2, status, content: content2 };
+  }
+  const ext = detectBestConfigExtension({
+    readFile: io.readFile,
+    cwd: appDir,
+    nodeVersion: io.nodeVersion ?? process.version
+  });
+  const path = join4(appDir, `svelte-vitals.config.${ext}`);
+  const content = buildConfigFileTemplate({ useDefineConfig: ext === "ts" });
+  return { id: target.id, label: target.label, path, status: "created", content };
+}
+function planForCiTarget(target, io, force) {
+  const path = join4(io.cwd, target.relPath);
   const existing = io.readFile(path);
-  const content = buildConfigFileTemplate();
-  const status = existing === void 0 ? "created" : force ? "updated" : "exists";
-  return { id: target.id, label: target.label, path, status, content };
+  const plan = planWorkflowWrite(existing, force);
+  const content = plan.status === "exists" ? void 0 : buildWorkflowYaml({ actionSha: ACTION_SHA, actionVersion: ACTION_VERSION });
+  return { id: target.id, label: target.label, path, status: plan.status, content };
 }
 function indent(text) {
   return text.split("\n").map((l) => `      ${l}`).join("\n");
@@ -942,19 +1091,16 @@ async function runRefresh(io, flags, version) {
   let hadFailure = false;
   const rows = [];
   for (const target of AGENT_TARGETS) {
-    const path = join3(io.cwd, target.relPath);
-    try {
-      if (io.readFile(path) === void 0) continue;
-      rows.push(planForAgentTarget(
-        target,
-        io,
-        /* force */
-        true,
-        version
-      ));
-    } catch (err) {
-      hadFailure = true;
-      io.errorLog(`svelte-vitals: failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    const content = agentTargetContent(target.id, version);
+    for (const relPath of target.relPaths) {
+      const path = join4(io.cwd, relPath);
+      try {
+        if (io.readFile(path) === void 0) continue;
+        rows.push({ id: target.id, label: target.label, path, status: "updated", content });
+      } catch (err) {
+        hadFailure = true;
+        io.errorLog(`svelte-vitals: failed to read ${path}: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
   }
   if (rows.length === 0) {
@@ -1004,26 +1150,31 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
       (c) => c.scopes.some((s) => configExists(c.resolvePath(s, io.cwd, io.home)))
     ).map((c) => c.id);
     const viteConfigExists = ["vite.config.ts", "vite.config.js", "vite.config.mjs"].some(
-      (f) => configExists(join3(io.cwd, f))
+      (f) => configExists(join4(io.cwd, f))
     );
-    const claudeSkillDetected = configExists(join3(io.cwd, ".claude", "settings.json"));
-    const cursorRulesDetected = configExists(join3(io.cwd, ".cursor", "mcp.json"));
+    const claudeSkillDetected = configExists(join4(io.cwd, ".claude", "settings.json"));
+    const cursorRulesDetected = configExists(join4(io.cwd, ".cursor", "mcp.json"));
     const detectedAgents = [
       ...claudeSkillDetected ? ["claude-skill"] : [],
       ...cursorRulesDetected ? ["cursor-rules"] : []
     ];
+    const ciWorkflowDetected = configExists(join4(io.cwd, CI_TARGETS[0].relPath));
+    const configFileDetected = findExistingConfigFile((p3) => configExists(p3) ? "" : void 0, io.cwd) !== void 0;
     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 })),
-      ...AGENT_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
-      ...CONFIG_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
+      ...detectedAgents,
+      ...ciWorkflowDetected ? CI_TARGETS.map((t) => t.id) : [],
+      ...configFileDetected ? CONFIG_TARGETS.map((t) => t.id) : []
     ];
-    const picked = await prompts.selectClients(options, detected);
+    const groups = {
+      "MCP server": CLIENTS.map((c) => ({ id: c.id, label: c.label })),
+      "Vite integration": VITE_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+      "Agent Skills & rules": AGENT_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+      "CI (GitHub Actions)": CI_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint })),
+      "Config file": CONFIG_TARGETS.map((t) => ({ id: t.id, label: t.label, hint: t.hint }))
+    };
+    const picked = await prompts.selectClients(groups, detected);
     if (picked === null) {
       io.log("Cancelled.");
       return 0;
@@ -1031,7 +1182,7 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     ids = picked;
   } else {
     io.errorLog(
-      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file> to install non-interactively."
+      "svelte-vitals: no TTY; pass --client <claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file,ci-workflow> to install non-interactively."
     );
     return 2;
   }
@@ -1039,10 +1190,49 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
   const viteIds = ids.filter(isViteTargetId);
   const agentIds = ids.filter(isAgentTargetId);
   const configIds = ids.filter(isConfigTargetId);
-  if (clients.length === 0 && viteIds.length === 0 && agentIds.length === 0 && configIds.length === 0) {
+  const ciIds = ids.filter(isCiTargetId);
+  if (clients.length === 0 && viteIds.length === 0 && agentIds.length === 0 && configIds.length === 0 && ciIds.length === 0) {
     io.errorLog("svelte-vitals: no valid clients or targets selected.");
     return 2;
   }
+  const hasSvelteConfig = (dir) => {
+    try {
+      return io.readFile(join4(dir, "svelte.config.js")) !== void 0 || io.readFile(join4(dir, "svelte.config.ts")) !== void 0;
+    } catch {
+      return false;
+    }
+  };
+  const needsApp = viteIds.length > 0 || configIds.length > 0;
+  let appDir = io.cwd;
+  if (needsApp) {
+    if (flags.app) {
+      const candidate = join4(io.cwd, flags.app);
+      if (!hasSvelteConfig(candidate)) {
+        io.errorLog(`svelte-vitals: --app '${flags.app}' is not a SvelteKit app (no svelte.config.{js,ts} there).`);
+        return 2;
+      }
+      appDir = candidate;
+    } else if (!hasSvelteConfig(io.cwd)) {
+      const apps = await (io.discoverApps ?? discoverApps)(io.cwd);
+      if (apps.length === 1) {
+        io.errorLog(`svelte-vitals: detected SvelteKit app at ${apps[0]}; targeting it for the Vite/config targets.`);
+        appDir = join4(io.cwd, apps[0]);
+      } else if (apps.length > 1) {
+        if (io.isTTY) {
+          const picked = await prompts.selectApp(apps);
+          if (picked === null) {
+            io.log("Cancelled.");
+            return 0;
+          }
+          appDir = join4(io.cwd, picked);
+        } else {
+          io.errorLog(`svelte-vitals: multiple SvelteKit apps found: ${apps.join(", ")}.`);
+          io.errorLog(`svelte-vitals: pass one with --app, e.g. \`svelte-vitals install --app ${apps[0]}\`.`);
+          return 2;
+        }
+      }
+    }
+  }
   const rows = [];
   for (const client of clients) {
     let scope;
@@ -1071,15 +1261,40 @@ async function runInstall(flags, io, prompts, version = "0.0.0") {
     }
   }
   for (const viteId of viteIds) {
-    rows.push(viteId === "vite-plugin" ? planForVitePlugin(io) : planForViteHooks(io));
+    rows.push(viteId === "vite-plugin" ? planForVitePlugin(io, appDir) : planForViteHooks(io, appDir));
   }
   for (const agentId of agentIds) {
     const target = agentTargetById(agentId);
-    rows.push(planForAgentTarget(target, io, flags.force ?? false, version));
+    try {
+      rows.push(...planForAgentTarget(target, io, flags.force ?? false, version));
+    } catch (err) {
+      io.errorLog(
+        `svelte-vitals: could not check existing agent target ${target.id}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return 2;
+    }
   }
   for (const configId of configIds) {
     const target = configTargetById(configId);
-    rows.push(planForConfigTarget(target, io, flags.force ?? false));
+    try {
+      rows.push(planForConfigTarget(target, io, flags.force ?? false, appDir));
+    } catch (err) {
+      io.errorLog(
+        `svelte-vitals: could not check existing config file: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return 2;
+    }
+  }
+  for (const ciId of ciIds) {
+    const target = ciTargetById(ciId);
+    try {
+      rows.push(planForCiTarget(target, io, flags.force ?? false));
+    } catch (err) {
+      io.errorLog(
+        `svelte-vitals: could not check existing workflow at ${join4(io.cwd, target.relPath)}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return 2;
+    }
   }
   const planText = rows.map(rowLine).join("\n");
   io.log("Plan:");
@@ -1112,22 +1327,28 @@ ${indent(r.snippet ?? "")}`);
       io.writeFile(r.path, r.content ?? "");
       io.log(`\u2713 ${r.label}: ${r.status} ${r.path}`);
       if (isViteTargetId(r.id)) viteWasWritten = true;
+      if (isConfigTargetId(r.id) && r.path.endsWith(".ts")) {
+        io.log(
+          "svelte-vitals: note \u2014 a .ts config needs Node 22.18+ (or 23.6+) everywhere svelte-vitals runs, CI included; rename to .mjs if that is not guaranteed."
+        );
+      }
     } catch (err) {
       hadFailure = true;
       io.errorLog(`svelte-vitals: failed to write ${r.path}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
-  if (viteWasWritten && io.runCommand && !hasVitePackage(io)) {
-    const pm = detectPackageManager(io);
+  const appIo = { ...io, cwd: appDir };
+  if (viteWasWritten && io.runCommand && !hasVitePackage(appIo)) {
+    const pm = appDir === io.cwd ? detectPackageManager(io) : detectPackageManagerNear(io, appDir);
     const { command, args } = installCommand(pm);
     io.log(`Installing @svelte-vitals/vite via ${pm}...`);
-    const code = io.runCommand(command, args, io.cwd);
+    const code = io.runCommand(command, args, appDir);
     if (code !== 0) {
       io.errorLog(
         `svelte-vitals: failed to install @svelte-vitals/vite (${command} ${args.join(" ")} exited ${code}). Install it manually.`
       );
     } else {
-      const installedVersion = readInstalledViteVersion(io);
+      const installedVersion = readInstalledViteVersion(appIo) ?? 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)."
       );
@@ -1145,7 +1366,9 @@ ${indent(r.snippet ?? "")}`);
 var VALID_TARGETS = [
   ...CLIENTS.map((c) => c.id),
   ...VITE_TARGETS.map((t) => t.id),
-  ...AGENT_TARGETS.map((t) => t.id)
+  ...AGENT_TARGETS.map((t) => t.id),
+  ...CONFIG_TARGETS.map((t) => t.id),
+  ...CI_TARGETS.map((t) => t.id)
 ];
 var EXPECTED_TARGETS = VALID_TARGETS.join("|");
 function resolveInstallArgs(argv) {
@@ -1169,18 +1392,20 @@ function resolveInstallArgs(argv) {
     if (rawScope === "project" || rawScope === "global") scope = rawScope;
     else errors.push(`svelte-vitals: unknown --scope '${rawScope}'; expected project|global.`);
   }
+  const app = typeof argv.app === "string" && argv.app.trim() !== "" ? argv.app.trim() : void 0;
   const refresh = Boolean(argv.refresh);
   if (refresh && rawClients.length > 0) {
     errors.push("svelte-vitals: --refresh regenerates existing files and cannot be combined with --client.");
   }
   if (errors.length > 0) return { flags: null, warnings, errors };
-  if (refresh && (scope !== void 0 || Boolean(argv.yes) || Boolean(argv.force))) {
-    warnings.push("svelte-vitals: --scope, --yes, and --force are ignored with --refresh.");
+  if (refresh && (scope !== void 0 || Boolean(argv.yes) || Boolean(argv.force) || app !== void 0)) {
+    warnings.push("svelte-vitals: --scope, --yes, --force, and --app are ignored with --refresh.");
   }
   return {
     flags: {
       ...client.length > 0 ? { client } : {},
       ...scope ? { scope } : {},
+      ...app !== void 0 && !refresh ? { app } : {},
       yes: Boolean(argv.yes),
       dryRun: Boolean(argv["dry-run"]),
       force: Boolean(argv.force),
@@ -1192,27 +1417,45 @@ function resolveInstallArgs(argv) {
 }
 
 // src/install/cli.ts
-var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals MCP server, Vite integration, and agent skills/rules
+var INSTALL_HELP = `svelte-vitals install \u2014 set up the svelte-vitals MCP server, Vite integration, agent skills/rules, and CI
 
 Usage:
   svelte-vitals install [options]
 
 Options:
-  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file
-                    (skips the interactive picker)
+  --client <ids>    Comma-separated: claude-code,cursor,codex,vite-plugin,vite-hooks,claude-skill,cursor-rules,claude-skill-improve,config-file,ci-workflow
+                    (skips the interactive picker; the picker groups these by category \u2014
+                    MCP server, Vite integration, Agent Skills & rules, CI, Config file)
                     vite-plugin registers the build-mode plugin in vite.config.{ts,js,mjs}; vite-hooks
                     wires up the svelteVitalsHandle hook in src/hooks.server.{ts,js}, which improves the
                     live dashboard's per-route accuracy as you browse. --force does not apply
                     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.
-                    claude-skill-improve writes a second, read-only Claude Code skill
-                    (.claude/skills/improve-svelte/SKILL.md) that audits the whole project and writes
-                    implementation plans instead of a run-after-every-edit playbook; also supports --force.
-                    config-file scaffolds svelte-vitals.config.mjs with every option commented out;
-                    supports --force to regenerate.
+                    claude-skill writes an agent skill (Claude Code, Codex, and Cursor \u2014
+                    .claude/skills/, .agents/skills/, and .cursor/skills/ under svelte-vitals/);
+                    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.
+                    claude-skill-improve writes a second, read-only agent skill (same three
+                    locations, under improve-svelte/) that audits the whole project and writes
+                    implementation plans instead of a run-after-every-edit playbook; also
+                    supports --force.
+                    config-file scaffolds svelte-vitals.config.{mjs,ts} with every option commented
+                    out, auto-picking .ts (with defineConfig) when the current Node supports it, the
+                    project looks TypeScript-oriented (tsconfig.json or vite.config.ts present), and
+                    svelte-vitals is a declared dependency (defineConfig's import resolves at load
+                    time); else the safe .mjs default. Supports --force to regenerate the file
+                    that's already there (its extension never changes on --force).
+                    ci-workflow scaffolds .github/workflows/svelte-vitals.yml, the same file
+                    \`svelte-vitals ci install\` writes standalone \u2014 pick it here to set it up in
+                    the same pass as everything else; supports --force to regenerate. \`svelte-vitals
+                    ci upgrade\` remains the way to bump an existing workflow's pinned action version.
   --scope <scope>   project | global (applies to all selected clients; codex is always global)
+  --app <dir>       Monorepo: the SvelteKit app directory the vite-plugin/vite-hooks/config-file
+                    targets write into (e.g. --app apps/web). Without it, when the current
+                    directory isn't itself a SvelteKit app, one detected app is used
+                    automatically (with a notice), several prompt a picker on a TTY, and
+                    non-interactive runs exit 2 asking for --app. All other targets (MCP
+                    configs, skills, ci-workflow) always write at the current directory \u2014
+                    the repo root is their correct home.
   --yes, -y         Skip the confirmation prompt
   --dry-run         Print the planned changes and exit without writing
   --force           Overwrite an existing svelte-vitals entry
@@ -1237,6 +1480,7 @@ function realIO() {
     cwd: process.cwd(),
     home: homedir(),
     isTTY: Boolean(process.stdout.isTTY),
+    nodeVersion: process.version,
     log: (line) => console.log(line),
     errorLog: (line) => console.error(line),
     runCommand: (command, args, cwd) => {
@@ -1260,10 +1504,15 @@ function realIO() {
 }
 function clackPrompts() {
   return {
-    selectClients: async (all, defaults) => {
-      const res = await p.multiselect({
+    selectClients: async (groups, defaults) => {
+      const res = await p.groupMultiselect({
         message: "Which clients/targets should svelte-vitals be installed for?",
-        options: all.map((o) => ({ value: o.id, label: o.label, hint: o.hint })),
+        options: Object.fromEntries(
+          Object.entries(groups).map(([group, opts]) => [
+            group,
+            opts.map((o) => ({ value: o.id, label: o.label, hint: o.hint }))
+          ])
+        ),
         initialValues: defaults,
         required: true
       });
@@ -1277,6 +1526,14 @@ function clackPrompts() {
       });
       return p.isCancel(res) ? null : res;
     },
+    selectApp: async (apps) => {
+      const res = await p.select({
+        message: "Multiple SvelteKit apps found \u2014 which one should the Vite/config targets go into?",
+        options: apps.map((a) => ({ value: a, label: a })),
+        initialValue: apps[0]
+      });
+      return p.isCancel(res) ? null : res;
+    },
     confirm: async (planText) => {
       const res = await p.confirm({ message: `Apply this plan?
 ${planText}` });
@@ -1287,7 +1544,7 @@ ${planText}` });
 async function runInstallCli(args) {
   const argv = mri(args, {
     boolean: ["yes", "dry-run", "force", "refresh", "help"],
-    string: ["client", "scope"],
+    string: ["client", "scope", "app"],
     alias: { y: "yes", h: "help" }
   });
   if (argv.help) {
@@ -1302,47 +1559,9 @@ async function runInstallCli(args) {
 }
 
 // src/ci/cli.ts
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import mri2 from "mri";
 
-// src/ci/workflow.ts
-var WORKFLOW_PATH = ".github/workflows/svelte-vitals.yml";
-var CHECKOUT_SHA = "9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0";
-var CHECKOUT_VERSION = "v7.0.0";
-function planWorkflowWrite(existing, force) {
-  if (existing === void 0) return { status: "created" };
-  if (!force) return { status: "exists" };
-  return { status: "updated" };
-}
-function buildWorkflowYaml(opts) {
-  const { actionSha, actionVersion } = opts;
-  return [
-    "# Generated by `svelte-vitals ci install`.",
-    "# 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@${CHECKOUT_SHA} # ${CHECKOUT_VERSION}`,
-    "        with:",
-    "          fetch-depth: 0",
-    `      - uses: oekazuma/svelte-vitals/packages/action@${actionSha} # @svelte-vitals/action@${actionVersion}`,
-    "        with:",
-    "          diff: origin/${{ github.base_ref }}",
-    "          baseline: origin/${{ github.base_ref }}",
-    ""
-  ].join("\n");
-}
-
 // src/ci/upgrade.ts
 var ACTION_USES_LINE = /^(?<indent>\s*-\s*uses:\s*(?:&\S+\s+)?oekazuma\/svelte-vitals\/packages\/action@)(?<ref>[^\s#]+)(?<comment>\s*#.*)?$/;
 function upgradeActionPin(content, sha, version) {
@@ -1371,10 +1590,6 @@ function upgradeActionPin(content, sha, version) {
   return { status: "upgraded", content: next.join("\n"), replaced, from };
 }
 
-// src/ci/action-pin.generated.ts
-var ACTION_SHA = "e30438c8facc8aabac6d4ce00455e29ec02ad9af";
-var ACTION_VERSION = "0.3.1";
-
 // src/ci/cli.ts
 var CI_HELP = `svelte-vitals ci \u2014 scaffold CI integration
 
@@ -1416,7 +1631,7 @@ async function runCiCli(args, io = realIO()) {
     io.log(CI_HELP);
     return 0;
   }
-  const path = join4(io.cwd, WORKFLOW_PATH);
+  const path = join5(io.cwd, WORKFLOW_PATH);
   const existing = io.readFile(path);
   const plan = planWorkflowWrite(existing, Boolean(argv.force));
   io.log("Plan:");
@@ -1450,7 +1665,7 @@ async function runCiUpgrade(args, io) {
     io.log(CI_HELP);
     return 0;
   }
-  const path = join4(io.cwd, WORKFLOW_PATH);
+  const path = join5(io.cwd, WORKFLOW_PATH);
   const existing = io.readFile(path);
   if (existing === void 0) {
     io.errorLog(`svelte-vitals: no ${WORKFLOW_PATH} found \u2014 run \`svelte-vitals ci install\` first.`);

package/dist/{chunk-OCLDCX4Y.js → chunk-O5VMXV2Q.js}

@@ -1546,12 +1546,14 @@ async function run(opts = {}) {
 
 export {
   ProjectError,
+  discoverApps,
   readPackageVersion,
   readCoreVersion,
   isReporterName,
   findUnknownRuleIds,
   knownRuleIds,
   buildRulesConfig,
+  CONFIG_FILENAMES,
   loadConfigFile,
   spinnerEnabled,
   routeMatcher,

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   routeMatcher,
   run,
   spinnerEnabled
-} from "./chunk-OCLDCX4Y.js";
+} from "./chunk-O5VMXV2Q.js";
 export {
   ProjectError,
   analyzeProject,

package/package.json

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