quiver-cli 1.2.0 → 1.3.1

package/template/.agents/skills/design/impeccable/scripts/lib/staleness.mjs

@@ -47,18 +47,33 @@ import {
 
 // Top-level keys any reader honors: `hook` and `detector` subtrees (hook-lib's
 // readConfig), `updateCheck` (context.mjs), `projectRoots` (context.mjs's
-// monorepo resolution), plus `stalenessCheck` below. `$schema` and `version`
-// are allowed as conventional metadata nobody reads.
+// monorepo resolution), `buildPath` (context.mjs's build-path directive), plus
+// `stalenessCheck` below. `$schema` and `version` are allowed as conventional
+// metadata nobody reads.
 const KNOWN_CONFIG_KEYS = new Set([
   'hook',
   'detector',
   'updateCheck',
   'stalenessCheck',
   'projectRoots',
+  'buildPath',
   '$schema',
   'version',
 ]);
 
+// The only two values context.mjs and new-work honor. A near miss reads as a
+// working preference and silently rides the opposite path, so it is worth
+// reporting rather than coercing.
+const BUILD_PATH_VALUES = Object.freeze(['comp', 'code']);
+
+// Evidence that this project does the kind of work `buildPath` governs. A
+// project that only ever ran polish or audit has no use for the setting and
+// should never be told it exists. Two stats, so Tier 1 can afford it.
+const DIRECTION_WORK_PATHS = Object.freeze([
+  path.join('.impeccable', 'surfaces'),
+  path.join('.impeccable', 'mocks', 'decision'),
+]);
+
 // `detector` is a closed set, so a typo here is worth reporting. `hook` is not
 // checked: it carries runtime settings from several writers and the false
 // positive rate would outweigh the catch.
@@ -325,6 +340,20 @@ export function checkConfig({ projectRoot, repoRoot }) {
         }));
       }
 
+      if (Object.prototype.hasOwnProperty.call(raw, 'buildPath')
+        && !BUILD_PATH_VALUES.includes(raw.buildPath)) {
+        findings.push(finding({
+          id: 'config-invalid-build-path',
+          artifact: 'config.json',
+          filePath: rel,
+          severity: 'mention',
+          summary: `${rel} sets \`buildPath\` to ${JSON.stringify(raw.buildPath)}, which nothing reads. `
+            + `The values are ${BUILD_PATH_VALUES.map((value) => `\`${value}\``).join(' and ')}.`,
+          fix: 'Report the value. An unread `buildPath` does not fall back to the other path; '
+            + 'it falls back to the default, so a project meaning `code` has been building comp-led.',
+        }));
+      }
+
       const detector = raw.detector;
       if (detector && typeof detector === 'object' && !Array.isArray(detector)) {
         const unknownDetector = Object.keys(detector).filter((key) => !KNOWN_DETECTOR_KEYS.has(key));
@@ -345,6 +374,47 @@ export function checkConfig({ projectRoot, repoRoot }) {
   return findings;
 }
 
+/**
+ * No recorded build-path preference on a project that plainly does visual
+ * direction work. Not drift in the usual sense: the setting is newer than the
+ * project, so every project that predates it lands here at once. That is why
+ * it is gated twice, on a product record and on evidence of the work the
+ * setting governs, and why it says the choice rather than assuming a harness
+ * can make it. Image generation is the real precondition and this module
+ * cannot see it: a harness-native image tool leaves no trace on disk, so the
+ * finding hands the question to the one reader that knows.
+ */
+export function checkBuildPathUnset({ projectRoot, repoRoot, product }) {
+  if (!projectRoot || !product) return [];
+  const roots = [...new Set([projectRoot, repoRoot].filter(Boolean).map((root) => path.resolve(root)))];
+
+  for (const root of roots) {
+    for (const name of ['config.json', 'config.local.json']) {
+      const raw = readJson(path.join(root, '.impeccable', name));
+      // Any declared value ends this, valid or not: an invalid one already has
+      // its own finding and two reports of one key is noise.
+      if (raw && Object.prototype.hasOwnProperty.call(raw, 'buildPath')) return [];
+    }
+  }
+
+  const evidence = DIRECTION_WORK_PATHS.filter((rel) => fs.existsSync(path.join(projectRoot, rel)));
+  if (!evidence.length) return [];
+
+  return [finding({
+    id: 'config-build-path-unset',
+    artifact: 'config.json',
+    filePath: '.impeccable/config.json',
+    severity: 'mention',
+    summary: 'This project has run visual direction work but records no `buildPath`, '
+      + 'so every direction round takes the comp-first default without anyone having chosen it.',
+    fix: 'Only when image generation exists in your tool surface, offer the choice once: '
+      + '**comp-first** (an image sets the bar before any code; bolder composition, slower) or '
+      + '**code-first** (build directly; ambition carried by the direction contract; leaner, faster). '
+      + 'Write the answer to `.impeccable/config.json` as `"buildPath": "comp"` or `"buildPath": "code"`, '
+      + 'merging with the keys already there. Without image generation there is no choice to record: stay silent.',
+  })];
+}
+
 // ─── Surface briefs ────────────────────────────────────────────────────────
 
 /**
@@ -418,40 +488,46 @@ export function describeWorkspaceContext(candidates = []) {
 // ─── Tier 1 orchestration ──────────────────────────────────────────────────
 
 /**
- * Everything a boot can afford. `ctx` is the loadContext result; `extras`
- * carries values the caller already computed so nothing is recomputed here.
+ * Everything a boot can afford, grouped by artifact so deeper reports can
+ * interleave their own checks without rebuilding this policy. `ctx` is the
+ * loadContext result; `extras` carries values the caller already computed so
+ * nothing is recomputed here.
  */
-export function collectBootFindings(ctx, extras = {}) {
-  if (!ctx) return [];
+export function collectBootFindingGroups(ctx, extras = {}) {
+  if (!ctx) return {};
   const projectRoot = ctx.projectRoot || process.cwd();
-  const absProductPath = extras.absProductPath || null;
   const absDesignPath = extras.absDesignPath || null;
 
-  return [
-    ...checkProduct(ctx.product, ctx.productPath || 'PRODUCT.md'),
+  return {
+    product: checkProduct(ctx.product, ctx.productPath || 'PRODUCT.md'),
     // Only checked once a PRODUCT.md exists. Without one the boot already
     // emits NO_PRODUCT_MD and routes into init, which asks for the platform
     // directly; a second signal saying the same thing is noise.
-    ...(ctx.product
+    nativePlatform: ctx.product
       ? checkNativePlatformEvidence({
           projectRoot,
           platform: ctx.platform,
           product: ctx.product,
           productPath: ctx.productPath,
         })
-      : []),
-    ...checkDesignSidecar({
+      : [],
+    designSidecar: checkDesignSidecar({
       designPath: absDesignPath,
       sidecarCandidates: extras.sidecarCandidates || [],
       projectRoot,
     }),
-    ...checkConfig({ projectRoot, repoRoot: ctx.repoRoot }),
-    ...checkSurfaceBriefs({ candidates: ctx.surfaceBriefCandidates, projectRoot }),
-    ...(extras.projectRootPatterns
+    config: checkConfig({ projectRoot, repoRoot: ctx.repoRoot }),
+    buildPath: checkBuildPathUnset({ projectRoot, repoRoot: ctx.repoRoot, product: ctx.product }),
+    surfaceBriefs: checkSurfaceBriefs({ candidates: ctx.surfaceBriefCandidates, projectRoot }),
+    projectRoots: extras.projectRootPatterns
       ? checkProjectRoots({
           patterns: extras.projectRootPatterns,
           candidates: extras.targetCandidates || [],
         })
-      : []),
-  ];
+      : [],
+  };
+}
+
+export function collectBootFindings(ctx, extras = {}) {
+  return Object.values(collectBootFindingGroups(ctx, extras)).flat();
 }

package/template/.agents/skills/design/impeccable/scripts/lib/surface-briefs.mjs

@@ -8,6 +8,12 @@ export function getSurfaceBriefDir(projectRoot) {
   return path.join(projectRoot, '.impeccable', 'surfaces');
 }
 
+function normalizeRouteTarget(route) {
+  if (!route.startsWith('/') || route.includes('..')) return null;
+  const normalized = route.split(/[?#]/, 1)[0].replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+  return `route:${normalized}`;
+}
+
 export function normalizeSurfaceTarget(target, { projectRoot = process.cwd() } = {}) {
   if (!target || typeof target !== 'string' || !target.trim()) return null;
   const trimmed = target.trim();
@@ -21,21 +27,13 @@ export function normalizeSurfaceTarget(target, { projectRoot = process.cwd() } =
       return null;
     }
   }
-  if (/^route:/i.test(trimmed)) {
-    const route = trimmed.slice(trimmed.indexOf(':') + 1).trim();
-    if (!route.startsWith('/') || route.includes('..')) return null;
-    const normalizedRoute = route.split(/[?#]/, 1)[0].replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
-    return `route:${normalizedRoute}`;
-  }
-  if (trimmed === '/') return 'route:/';
+  if (/^route:/i.test(trimmed)) return normalizeRouteTarget(trimmed.slice(trimmed.indexOf(':') + 1).trim());
+  if (trimmed === '/') return normalizeRouteTarget(trimmed);
   if (trimmed.startsWith('/')) {
     const absolute = path.resolve(trimmed);
     const relativeToProject = path.relative(projectRoot, absolute);
     const isProjectFile = relativeToProject && !relativeToProject.startsWith('..') && !path.isAbsolute(relativeToProject);
-    if (!isProjectFile && !fs.existsSync(absolute) && !trimmed.includes('..')) {
-      const normalizedRoute = trimmed.split(/[?#]/, 1)[0].replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
-      return `route:${normalizedRoute}`;
-    }
+    if (!isProjectFile && !fs.existsSync(absolute)) return normalizeRouteTarget(trimmed);
   }
   const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(projectRoot, trimmed);
   const rel = path.relative(projectRoot, abs);

package/template/.agents/skills/design/impeccable/scripts/live/browser-script-parts.mjs

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { LIVE_CHROME_MOUNT_CONTRACT, LIVE_UI_SURFACES } from './ui-surfaces.mjs';
+
 export const LIVE_BROWSER_SCRIPT_PARTS = Object.freeze([
   Object.freeze({ name: 'session-state', file: 'live-browser-session.js' }),
   Object.freeze({ name: 'dom-helpers', file: 'live-browser-dom.js' }),
+  Object.freeze({ name: 'project-ignores', file: 'live-browser-ignores.js' }),
   Object.freeze({ name: 'browser-ui', file: 'live-browser.js' }),
 ]);
 
@@ -32,7 +35,25 @@ export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.re
   }));
 }
 
-export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', appRoot = null, parts }) {
+export function assembleLiveBrowserScript({
+  token,
+  port,
+  vocabulary,
+  commandPrefix = '/',
+  appRoot = null,
+  parts,
+  // Defaulted rather than threaded through live-server.mjs: the browser bundle
+  // must always carry the canonical inventory, and a default makes that true by
+  // construction instead of by every caller remembering to pass it. Overridable
+  // so tests can assemble with a stand-in.
+  uiSurfaces = LIVE_UI_SURFACES,
+  mountContract = LIVE_CHROME_MOUNT_CONTRACT,
+  // Project detector waivers ({ ignoreRules, ignoreValues, roots }), read from
+  // .impeccable config by live-server.mjs. live-browser-ignores.js resolves
+  // them against the page when a detect scan starts, so the overlay filters
+  // the same findings the CLI and the edit hook do (issue #639).
+  projectIgnores = null,
+}) {
   const prelude =
     `window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
     `window.__IMPECCABLE_PORT__ = ${port};\n` +
@@ -44,7 +65,15 @@ export function assembleLiveBrowserScript({ token, port, vocabulary, commandPref
     `window.__IMPECCABLE_COMMAND_PREFIX__ = ${JSON.stringify(commandPrefix)};\n` +
     // Canonical command vocabulary (values + labels + icons). live-browser.js
     // builds its action picker from this instead of an inline copy.
-    `window.__IMPECCABLE_VOCAB__ = ${JSON.stringify(vocabulary)};\n`;
+    `window.__IMPECCABLE_VOCAB__ = ${JSON.stringify(vocabulary)};\n` +
+    // Canonical Live chrome inventory from live/ui-surfaces.mjs. live-browser.js
+    // is a classic script and cannot import an ES module at runtime, so the list
+    // is serialized here and read off the global there. Node consumers (this
+    // repo's tests, the impeccable-site Live UI lab) import the module directly,
+    // which is what keeps the two from drifting.
+    `window.__IMPECCABLE_LIVE_UI_SURFACES__ = ${JSON.stringify(uiSurfaces)};\n` +
+    `window.__IMPECCABLE_LIVE_MOUNT_CONTRACT__ = ${JSON.stringify(mountContract)};\n` +
+    `window.__IMPECCABLE_PROJECT_IGNORES__ = ${JSON.stringify(projectIgnores)};\n`;
 
   const body = parts.map((part) => {
     const file = part.file || path.basename(part.path || '');

package/template/.agents/skills/design/impeccable/scripts/live/project-ignores.mjs

@@ -0,0 +1,139 @@
+/**
+ * Project detector waivers for the live overlay (issue #639, hardened in the
+ * PR #645 follow-up). One place decides what the /live.js prelude serializes
+ * as window.__IMPECCABLE_PROJECT_IGNORES__:
+ *
+ *   ignoreRules   detector.ignoreRules, unioned across every live root.
+ *   ignoreValues  detector.ignoreValues entries ({rule, value, files?}),
+ *                 deduped across roots; createdAt/reason stay local.
+ *   ignoreFiles   detector.ignoreFiles globs, unioned across roots, so a
+ *                 wholly waived page scans to zero findings in the overlay
+ *                 just as it reports nothing through the CLI and the hook.
+ *   roots         served-root prefixes derived from the inject config's own
+ *                 `files` globs. Never derived from the ignore globs: one
+ *                 entry scoped to prototype/library/** would lend
+ *                 prototype/library/ as a candidate prefix to every page,
+ *                 and that rule would suppress site-wide (issue #639).
+ *   pageFiles     the inject config's `files` expanded to real project
+ *                 files, so the browser can resolve a URL to the one file it
+ *                 actually serves instead of trying every root (PR #645
+ *                 review: with src/ and public/ both served, /foo.html must
+ *                 not borrow src/foo.html's waivers while actually serving
+ *                 public/foo.html).
+ *
+ * Config is read from every root the live session spans: the appRoot the
+ * server chdir'd onto, plus contextRoot and repoRoot when they differ. The
+ * edit hook keys the same config at the session cwd (the repo root in a
+ * monorepo, via resolveCacheCwd), and `impeccable detect` reads it from its
+ * invocation cwd, so reading only the appRoot silently dropped every waiver
+ * in exactly the monorepo layouts the roots manifest exists for. Reading is
+ * additive across roots, matching readConfig's own union of config.json and
+ * config.local.json.
+ *
+ * In a monorepo, roots and pageFiles are serialized repo-relative (the
+ * appRoot's path inside the repo is prefixed), so waivers spelled from
+ * either root match through the resolver's suffix expansion.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readConfig } from '../hook-lib.mjs';
+import { resolveFiles } from '../live-inject.mjs';
+import { resolveLiveConfigPath } from '../lib/impeccable-paths.mjs';
+
+// Serializing thousands of page identities into every /live.js response
+// helps nobody; past this cap pageFiles is omitted and the resolver falls
+// back to the served-root common ancestor, which is correct, just less
+// precise about cross-root duplicates.
+const PAGE_FILES_CAP = 500;
+
+export function collectProjectDetectorIgnores({ appRoot, contextRoot, repoRoot, scriptsDir } = {}) {
+  const configRoots = [];
+  for (const dir of [appRoot, contextRoot, repoRoot]) {
+    if (typeof dir !== 'string' || !dir) continue;
+    const resolved = path.resolve(dir);
+    if (!configRoots.includes(resolved)) configRoots.push(resolved);
+  }
+  if (configRoots.length === 0) configRoots.push(process.cwd());
+
+  const ignoreRules = new Set();
+  const ignoreFiles = new Set();
+  const valueEntries = new Map();
+  for (const dir of configRoots) {
+    // readConfig merges config.json with the gitignored config.local.json
+    // and type-checks both, exactly as the edit hook reads the same pair.
+    const config = readConfig(dir);
+    for (const rule of Array.isArray(config.ignoreRules) ? config.ignoreRules : []) {
+      if (typeof rule === 'string' && rule.trim()) ignoreRules.add(rule);
+    }
+    for (const glob of Array.isArray(config.ignoreFiles) ? config.ignoreFiles : []) {
+      if (typeof glob === 'string' && glob.trim()) ignoreFiles.add(glob);
+    }
+    for (const entry of Array.isArray(config.ignoreValues) ? config.ignoreValues : []) {
+      if (!entry || typeof entry !== 'object') continue;
+      // readConfig already normalized rule/value and folded `file` into
+      // `files`; serve only what the browser matches on.
+      const serialized = {
+        rule: entry.rule,
+        value: entry.value,
+        ...(Array.isArray(entry.files) && entry.files.length > 0 ? { files: entry.files } : {}),
+      };
+      const key = JSON.stringify([serialized.rule, serialized.value,
+        Array.isArray(serialized.files) ? [...serialized.files].sort() : []]);
+      if (!valueEntries.has(key)) valueEntries.set(key, serialized);
+    }
+  }
+
+  const served = readLiveServedPages({ appRoot: configRoots[0], repoRoot, scriptsDir });
+  return {
+    ignoreRules: [...ignoreRules],
+    ignoreValues: [...valueEntries.values()],
+    ignoreFiles: [...ignoreFiles],
+    roots: served.roots,
+    pageFiles: served.pageFiles,
+  };
+}
+
+function readLiveServedPages({ appRoot, repoRoot, scriptsDir }) {
+  let live = null;
+  try {
+    const configPath = resolveLiveConfigPath({ cwd: appRoot, scriptsDir });
+    live = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } catch {
+    // No readable inject config: the browser matches URL paths as-is.
+    return { roots: [], pageFiles: [] };
+  }
+  const files = Array.isArray(live?.files)
+    ? live.files.filter((glob) => typeof glob === 'string' && glob)
+    : [];
+
+  // A monorepo appRoot serializes identities repo-relative, so waivers
+  // spelled from either root match through the resolver's suffix expansion.
+  let prefix = '';
+  if (typeof repoRoot === 'string' && repoRoot) {
+    const rel = path.relative(path.resolve(repoRoot), path.resolve(appRoot)).split(path.sep).join('/');
+    if (rel && !rel.startsWith('..') && !path.isAbsolute(rel)) prefix = `${rel}/`;
+  }
+
+  const roots = [...new Set(files.map((glob) => {
+    const wildcardAt = glob.search(/[*?{]/);
+    const head = wildcardAt === -1 ? glob : glob.slice(0, wildcardAt);
+    const cut = head.lastIndexOf('/');
+    return prefix + (cut > -1 ? head.slice(0, cut + 1) : '');
+  }))];
+
+  let pageFiles = [];
+  try {
+    pageFiles = resolveFiles(appRoot, { ...live, files })
+      .filter((rel) => {
+        // resolveFiles passes literal entries through even when they do not
+        // exist; a missing file is nobody's identity.
+        try { return fs.statSync(path.join(appRoot, rel)).isFile(); } catch { return false; }
+      })
+      .map((rel) => prefix + rel);
+  } catch {
+    pageFiles = [];
+  }
+  if (pageFiles.length > PAGE_FILES_CAP) pageFiles = [];
+
+  return { roots, pageFiles };
+}

package/template/.agents/skills/design/impeccable/scripts/live/svelte-ast.mjs

@@ -933,9 +933,17 @@ function collectFreeIdentifierRanges(node, scopes, emit) {
  * Build the preview component's script block from a v2 contract, with
  * defaults that keep an unhydrated mount rendering instead of crashing.
  */
+// `/** @type {...} */` directly before a destructuring declaration is also
+// JSDoc's cast syntax, and Svelte 5.50+ re-emits the annotation in cast form
+// onto the template's own declaration: `var /** @type {...} */ (h1) = root()`.
+// That is a syntax error, so the browser's dynamic import of the variant dies
+// with "Unexpected token '('" and nothing renders. `@typedef` carries the same
+// shape without being a cast. Keep it a typedef;
+// tests/live-svelte-props-script.test.mjs compiles what these builders emit
+// and parses the result.
 export function buildPropsScriptV2(contract) {
   if (!contract || contract.length === 0) {
-    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
+    return '<script>\n  /** @typedef {Record<string, never>} Props */\n  let {} = $props();\n</script>\n';
   }
   const defaults = {
     text: "''",
@@ -957,5 +965,5 @@ export function buildPropsScriptV2(contract) {
   const typeFields = contract
     .map((c) => `    ${c.prop}?: ${types[c.kind] ?? 'string'};`)
     .join('\n');
-  return `<script>\n  /** @type {{\n${typeFields}\n  }} */\n  let { ${names} } = $props();\n</script>\n`;
+  return `<script>\n  /** @typedef {{\n${typeFields}\n  }} Props */\n  let { ${names} } = $props();\n</script>\n`;
 }

package/template/.agents/skills/design/impeccable/scripts/live/svelte-component.mjs

@@ -154,13 +154,19 @@ export function parseSvelteComponentFile(content) {
   return { markup, cssLines, styleBlock };
 }
 
+// A JSDoc `@type` directly before a destructuring declaration is JSDoc cast
+// syntax, and Svelte 5.50+ re-emits it onto the template's own declaration as
+// `var /** @type {...} */ (h1) = root()`, which does not parse. The browser's
+// import of the variant then fails with "Unexpected token '('" and the session
+// shows nothing. `@typedef` documents the same shape without being a cast.
+// tests/live-svelte-props-script.test.mjs compiles and parses what this emits.
 function buildPropsScript(contract) {
   if (contract.length === 0) {
-    return '<script>\n  /** @type {Record<string, never>} */\n  let {} = $props();\n</script>\n';
+    return '<script>\n  /** @typedef {Record<string, never>} Props */\n  let {} = $props();\n</script>\n';
   }
   const names = contract.map((c) => c.prop).join(', ');
   const typeFields = contract.map((c) => `    ${c.prop}: string;`).join('\n');
-  return `<script>\n  /** @type {{\n${typeFields}\n  }} */\n  let { ${names} } = $props();\n</script>\n`;
+  return `<script>\n  /** @typedef {{\n${typeFields}\n  }} Props */\n  let { ${names} } = $props();\n</script>\n`;
 }
 
 function buildVariantStub(variantNum, originalWithProps, contract) {
@@ -1111,6 +1117,24 @@ export function removeSvelteComponentSession(id, cwd = process.cwd()) {
  * seeded one) used to surface as a red Vite overlay in the user's page plus
  * a mount-failure round trip; bounced at publish time it is a private
  * agent-side fix with the exact file and line.
+ *
+ * What this deliberately does NOT prove is that the emitted module is valid
+ * JavaScript, and issue #580 was exactly that gap: valid .svelte source whose
+ * generated JS did not parse, so this check passed and the browser's import
+ * failed with "Unexpected token '('". Two reasons it cannot close the gap, both
+ * structural rather than oversights:
+ *
+ *   - `generate: false` produces no JS to inspect, and generating it here would
+ *     spend a full codegen per variant on the publish path.
+ *   - `loadSvelteCompiler` reaches the compiler through createRequire, which
+ *     Svelte's export map routes to a prebuilt CJS build. The dev server
+ *     imports `src/compiler` instead, and only that path uses the app's
+ *     installed printer (esrap). The two can disagree, so even a generated
+ *     check here would be checking a different compiler than the one whose
+ *     output the browser runs.
+ *
+ * tests/live-svelte-props-script.test.mjs covers the emitted JS, importing the
+ * compiler as ESM so it sees what the dev server sees.
  */
 export function compileCheckVariants(id, cwd = process.cwd()) {
   const manifest = findSvelteComponentManifest(id, cwd);

package/template/.agents/skills/design/impeccable/scripts/live/sveltekit-adapter.mjs

@@ -11,6 +11,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { firstExistingFile, hasAnyDependency } from './frameworks/detect-utils.mjs';
+
 export const SVELTE_LIVE_ROOT_COMPONENT = 'src/lib/impeccable/ImpeccableLiveRoot.svelte';
 export const SVELTE_LAYOUT_MARKER_OPEN = '<!-- impeccable-live-svelte-start -->';
 export const SVELTE_LAYOUT_MARKER_CLOSE = '<!-- impeccable-live-svelte-end -->';
@@ -45,11 +47,17 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
     && fileIncludes(path.join(cwd, appHtml), '%sveltekit.head%');
   if (!hasTemplateMarkers) return null;
 
-  const hasSvelteConfig = fs.existsSync(path.join(cwd, 'svelte.config.js'))
-    || fs.existsSync(path.join(cwd, 'svelte.config.mjs'))
-    || fs.existsSync(path.join(cwd, 'svelte.config.cjs'))
-    || fs.existsSync(path.join(cwd, 'svelte.config.ts'));
-  const hasKitPackage = packageHasSvelteKit(cwd);
+  const hasSvelteConfig = Boolean(firstExistingFile(cwd, [
+    'svelte.config.js',
+    'svelte.config.mjs',
+    'svelte.config.cjs',
+    'svelte.config.ts',
+  ]));
+  const hasKitPackage = hasAnyDependency(cwd, [
+    '@sveltejs/kit',
+    '@sveltejs/vite-plugin-svelte',
+    'svelte',
+  ]);
   if (!hasSvelteConfig && !hasKitPackage) return null;
 
   return {
@@ -260,36 +268,16 @@ function findSvelteKitAppHtml(cwd, config) {
 }
 
 function findSvelteKitLayout(cwd) {
-  const candidates = [
+  return firstExistingFile(cwd, [
     'src/routes/+layout.svelte',
     'src/routes/(app)/+layout.svelte',
-  ];
-  for (const rel of candidates) {
-    if (fs.existsSync(path.join(cwd, rel))) return rel;
-  }
-  return 'src/routes/+layout.svelte';
+  ]) || 'src/routes/+layout.svelte';
 }
 
 function defaultSvelteLayout() {
   return `<script>\n  let { children } = $props();\n</script>\n\n{@render children?.()}\n`;
 }
 
-function packageHasSvelteKit(cwd) {
-  const file = path.join(cwd, 'package.json');
-  if (!fs.existsSync(file)) return false;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
-    const deps = {
-      ...(pkg.dependencies || {}),
-      ...(pkg.devDependencies || {}),
-      ...(pkg.peerDependencies || {}),
-    };
-    return Boolean(deps['@sveltejs/kit'] || deps['@sveltejs/vite-plugin-svelte'] || deps.svelte);
-  } catch {
-    return false;
-  }
-}
-
 function fileIncludes(file, text) {
   try {
     return fs.readFileSync(file, 'utf-8').includes(text);

package/template/.agents/skills/design/impeccable/scripts/live/tanstack-adapter.mjs

@@ -19,6 +19,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+
+import { firstExistingFile, hasAnyDependency } from './frameworks/detect-utils.mjs';
 import { buildLiveScriptSrc } from './frameworks/script-src.mjs';
 
 export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
@@ -42,8 +44,8 @@ const START_PACKAGES = [
 ];
 
 export function detectTanStackStartProject(cwd = process.cwd()) {
-  if (!packageHasTanStackStart(cwd)) return null;
-  const rootRoute = findRootRouteFile(cwd);
+  if (!hasAnyDependency(cwd, START_PACKAGES)) return null;
+  const rootRoute = firstExistingFile(cwd, ROOT_ROUTE_CANDIDATES);
   if (!rootRoute) return null;
 
   const ext = path.extname(rootRoute);
@@ -218,29 +220,6 @@ function isManagedComponent(content) {
   return String(content || '').includes('impeccable-live-tanstack');
 }
 
-function findRootRouteFile(cwd) {
-  for (const rel of ROOT_ROUTE_CANDIDATES) {
-    if (fs.existsSync(path.join(cwd, rel))) return rel;
-  }
-  return null;
-}
-
-function packageHasTanStackStart(cwd) {
-  const file = path.join(cwd, 'package.json');
-  if (!fs.existsSync(file)) return false;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
-    const deps = {
-      ...(pkg.dependencies || {}),
-      ...(pkg.devDependencies || {}),
-      ...(pkg.peerDependencies || {}),
-    };
-    return START_PACKAGES.some((name) => Boolean(deps[name]));
-  } catch {
-    return false;
-  }
-}
-
 function relativeImportSpecifier(fromFile, toFile) {
   const rel = path.posix.relative(
     path.posix.dirname(fromFile.split(path.sep).join('/')),