@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/skills/impeccable/scripts/live-inject.mjs

@@ -7,6 +7,11 @@
  * every subsequent run, this script handles insert/remove deterministically
  * with zero LLM involvement.
  *
+ * Framework knowledge lives in `live/frameworks/` — detection order, adapters,
+ * the generic tag strategy, and the per-extension authoring traits live-wrap
+ * reads. This file is the CLI around it: resolve config, resolve the
+ * framework, heal orphaned artifacts, apply or remove, record the journal.
+ *
  * Usage:
  *   node live-inject.mjs --port PORT [--token TOKEN]  # Insert the live script tag
  *   node live-inject.mjs --remove                     # Remove the live script tag
@@ -23,22 +28,37 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveLiveConfigPath } from './lib/impeccable-paths.mjs';
 import {
-  applySvelteKitLiveAdapter,
-  detectSvelteKitProject,
-  removeSvelteKitLiveAdapter,
-} from './live/sveltekit-adapter.mjs';
+  describeInjectArtifacts,
+  frameworkIgnorePatterns,
+  resolveFramework,
+  resolveSourceTraits,
+} from './live/frameworks/index.mjs';
+import {
+  clearInjectJournal,
+  healInjectJournal,
+  recordInjection,
+} from './live/frameworks/journal.mjs';
 import {
-  applyTanStackLiveAdapter,
-  detectTanStackStartProject,
-  removeTanStackLiveAdapter,
-} from './live/tanstack-adapter.mjs';
+  buildTagBlock,
+  insertTag,
+  patchCspMeta,
+  removeTag,
+  revertCspMeta,
+} from './live/frameworks/tag-strategy.mjs';
+import { buildLiveScriptSrc } from './live/frameworks/script-src.mjs';
+import { assertSafeProjectRelative, resolveProjectPath, writeProjectFileAtomic } from './live/frameworks/detect-utils.mjs';
+import { enterLiveRoot, validateRootsManifest } from './live/roots.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const CONFIG_PATH = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
-const MARKER_OPEN_TEXT = 'impeccable-live-start';
-const MARKER_CLOSE_TEXT = 'impeccable-live-end';
-const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
-const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
+// Resolved lazily so the enterLiveRoot() chdir in the CLI guard below takes
+// effect first; module scope runs before the guard.
+let CONFIG_PATH_CACHED = null;
+function CONFIG_PATH_GET() {
+  if (!CONFIG_PATH_CACHED) {
+    CONFIG_PATH_CACHED = resolveLiveConfigPath({ cwd: process.cwd(), scriptsDir: __dirname });
+  }
+  return CONFIG_PATH_CACHED;
+}
 const IGNORE_MARKER_OPEN = '# impeccable-live-ignore-start';
 const IGNORE_MARKER_CLOSE = '# impeccable-live-ignore-end';
 
@@ -46,6 +66,9 @@ export const LIVE_IGNORE_PATTERNS = Object.freeze([
   '.impeccable/hook.cache.json',
   '.impeccable/config.local.json',
   '.impeccable/live/server.json',
+  '.impeccable/live/roots.json',
+  '.impeccable/live/app-root.json',
+  '.impeccable/live/inject-journal.json',
   '.impeccable/live/sessions/',
   '.impeccable/live/previews/',
   '.impeccable/live/annotations/',
@@ -101,133 +124,162 @@ Output (JSON):
   }
 
   if (args.includes('--check')) {
-    if (!fs.existsSync(CONFIG_PATH)) {
-      console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
+    // Deliberately read-only: --check runs from status paths and must never
+    // mutate the tree. Journal reconciliation happens on the inject run.
+    if (!fs.existsSync(CONFIG_PATH_GET())) {
+      console.log(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
       process.exit(0);
     }
     let cfg;
     try {
-      cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+      cfg = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
     } catch (err) {
-      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
+      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
       return;
     }
     try {
       validateConfig(cfg);
     } catch (err) {
-      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH }));
+      console.log(JSON.stringify({ ok: false, error: 'config_invalid', message: err.message, path: CONFIG_PATH_GET() }));
       return;
     }
-    console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH }));
+    console.log(JSON.stringify({ ok: true, config: cfg, path: CONFIG_PATH_GET() }));
     return;
   }
 
   // Load config
-  if (!fs.existsSync(CONFIG_PATH)) {
-    console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH }));
+  if (!fs.existsSync(CONFIG_PATH_GET())) {
+    console.error(JSON.stringify({ ok: false, error: 'config_missing', path: CONFIG_PATH_GET() }));
     process.exit(1);
   }
-  const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+  const config = JSON.parse(fs.readFileSync(CONFIG_PATH_GET(), 'utf-8'));
   validateConfig(config);
 
-  const resolvedFiles = resolveFiles(process.cwd(), config);
-  const svelteKit = detectSvelteKitProject(process.cwd(), config);
-  const nuxt = detectNuxtProject(process.cwd());
-  const tanstack = svelteKit || nuxt ? null : detectTanStackStartProject(process.cwd());
+  const cwd = process.cwd();
+  const resolvedFiles = resolveFiles(cwd, config);
+  const resolved = resolveFramework(cwd, config);
+  const isAdapter = resolved?.framework.inject.kind === 'adapter';
 
   if (args.includes('--remove')) {
-    if (svelteKit) {
-      const adapterResult = removeSvelteKitLiveAdapter({ cwd: process.cwd(), config });
-      console.log(JSON.stringify({ ok: true, adapter: 'sveltekit', results: [adapterResult] }));
-      return;
-    }
-    if (tanstack) {
-      const adapterResult = removeTanStackLiveAdapter({ cwd: process.cwd(), project: tanstack });
-      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'tanstack-start', results: [adapterResult] }));
-      if (adapterResult.error) process.exitCode = 1;
-      return;
-    }
-    if (nuxt) {
-      const adapterResult = removeNuxtLiveAdapter({ cwd: process.cwd(), project: nuxt });
-      console.log(JSON.stringify({ ok: !adapterResult.error, adapter: 'nuxt', results: [adapterResult] }));
-      if (adapterResult.error) process.exitCode = 1;
+    if (isAdapter) {
+      const adapterResult = resolved.framework.inject.remove({ cwd, config, project: resolved.project });
+      const ok = !(adapterResult && adapterResult.error);
+      // Anything the adapter could not reach (its detection may have shifted
+      // since the session started) is still on the journal.
+      const { healed } = healInjectJournal(cwd);
+      clearInjectJournal(cwd);
+      console.log(JSON.stringify({
+        ok,
+        adapter: resolved.framework.name,
+        results: [adapterResult],
+        healed: healed.length ? healed : undefined,
+      }));
+      if (!ok) process.exitCode = 1;
       return;
     }
     const results = resolvedFiles.map((relFile) => {
-      const absFile = path.resolve(process.cwd(), relFile);
-      if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
+      let absFile;
+      try {
+        absFile = resolveProjectPath(cwd, relFile, { mustExist: true, kind: 'file' });
+      } catch (error) {
+        return { file: relFile, error: 'unsafe_file_path', message: error.message };
+      }
       const content = fs.readFileSync(absFile, 'utf-8');
       const detagged = removeTag(content, config.commentSyntax);
       const updated = revertCspMeta(detagged);
       if (updated === content) return { file: relFile, removed: false, note: 'no tag present' };
-      fs.writeFileSync(absFile, updated, 'utf-8');
+      writeProjectFileAtomic(cwd, relFile, updated);
       return {
         file: relFile,
         removed: detagged !== content,
         cspReverted: updated !== detagged,
       };
     });
-    console.log(JSON.stringify({ ok: true, results }));
+    const { healed } = healInjectJournal(cwd);
+    clearInjectJournal(cwd);
+    console.log(JSON.stringify({ ok: true, results, healed: healed.length ? healed : undefined }));
     return;
   }
 
   // Insert mode — need --port
   const portIdx = args.indexOf('--port');
-  const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : NaN;
-  if (!Number.isFinite(port)) {
-    console.error(JSON.stringify({ ok: false, error: 'missing_port' }));
+  const port = portIdx !== -1 ? Number(args[portIdx + 1]) : NaN;
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    console.error(JSON.stringify({ ok: false, error: 'missing_or_invalid_port' }));
     process.exit(1);
   }
   // Optional server token: appended to the /live.js src so the token-gated
-  // /live.js handler authorizes the browser fetch. `live.mjs` always passes it.
+  // /live.js handler authorizes the browser fetch. `live.mjs` always passes
+  // it; a manual `--port`-only invocation reads the running helper's token
+  // from server.json instead of writing an unauthenticated URL that 401s.
   const tokenIdx = args.indexOf('--token');
-  const token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
-  const gitIgnore = ensureLiveGitIgnores(
-    process.cwd(),
-    nuxt ? [nuxt.pluginFile] : tanstack ? [tanstack.componentFile] : [],
-  );
-
-  if (svelteKit) {
-    const adapterResult = applySvelteKitLiveAdapter({ cwd: process.cwd(), port, token, config });
-    console.log(JSON.stringify({ ok: true, port, adapter: 'sveltekit', gitIgnore, results: [adapterResult] }));
-    return;
+  let token = tokenIdx !== -1 ? args[tokenIdx + 1] : undefined;
+  if (!token) {
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'server.json'), 'utf-8'));
+      // A record for a DIFFERENT port is a stale or foreign helper; its token
+      // would 401 just the same, so only adopt a matching one.
+      if (info?.token && Number(info.port) === port) token = info.token;
+    } catch { /* no running helper recorded; keep legacy tokenless behavior */ }
   }
-  if (tanstack) {
-    const adapterResult = applyTanStackLiveAdapter({ cwd: process.cwd(), port, token, project: tanstack });
-    console.log(JSON.stringify({
-      ok: !adapterResult.error,
+
+  // Reconcile before writing anything. Artifacts this run is about to own are
+  // kept (so a repeat inject stays byte-idempotent); artifacts left behind by
+  // a session that never got to stop are healed.
+  const plannedArtifacts = describeInjectArtifacts(resolved, { cwd, files: resolvedFiles });
+  const { healed } = healInjectJournal(cwd, { keep: plannedArtifacts.map((a) => a.path) });
+
+  const gitIgnore = ensureLiveGitIgnores(cwd, frameworkIgnorePatterns(resolved));
+  // In a nested-app repo the roots pointer lives at the REPO root, outside the
+  // reach of the appRoot-relative ignore block above; give that directory its
+  // own local excludes so the pointer (absolute host paths) never gets staged.
+  try {
+    const rootsManifest = validateRootsManifest(JSON.parse(fs.readFileSync(path.join(cwd, '.impeccable', 'live', 'roots.json'), 'utf-8')));
+    if (path.resolve(rootsManifest.repoRoot) !== path.resolve(cwd)) {
+      ensureLiveGitIgnores(rootsManifest.repoRoot);
+    }
+  } catch { /* no valid manifest: single-root project */ }
+
+  if (isAdapter) {
+    const adapterResult = resolved.framework.inject.apply({
+      cwd,
       port,
-      adapter: 'tanstack-start',
-      gitIgnore,
-      results: [adapterResult],
-    }));
-    if (adapterResult.error) process.exitCode = 1;
-    return;
-  }
-  if (nuxt) {
-    const adapterResult = applyNuxtLiveAdapter({ cwd: process.cwd(), port, token, project: nuxt });
+      token,
+      config,
+      project: resolved.project,
+    });
+    const ok = !(adapterResult && adapterResult.error);
+    if (ok) recordInjection(cwd, { framework: resolved.framework.name, port, artifacts: plannedArtifacts });
     console.log(JSON.stringify({
-      ok: !adapterResult.error,
+      ok,
       port,
-      adapter: 'nuxt',
+      adapter: resolved.framework.name,
       gitIgnore,
       results: [adapterResult],
+      healed: healed.length ? healed : undefined,
     }));
-    if (adapterResult.error) process.exitCode = 1;
+    if (!ok) process.exitCode = 1;
     return;
   }
 
   const results = resolvedFiles.map((relFile) => {
-    const absFile = path.resolve(process.cwd(), relFile);
-    if (!fs.existsSync(absFile)) return { file: relFile, error: 'file_not_found' };
+    let absFile;
+    try {
+      absFile = resolveProjectPath(cwd, relFile, { mustExist: true, kind: 'file' });
+    } catch (error) {
+      return { file: relFile, error: 'unsafe_file_path', message: error.message };
+    }
     const content = fs.readFileSync(absFile, 'utf-8');
     const withoutOld = revertCspMeta(removeTag(content, config.commentSyntax));
-    const withTag = insertTag(withoutOld, config, port, relFile, token);
+    // Per-file, not per-project: a Vite app can hold an .astro partial, and a
+    // framework project's entry template is often plain HTML.
+    const scriptAttrs = resolveSourceTraits(relFile).injectScriptAttrs;
+    const withTag = insertTag(withoutOld, config, port, token, scriptAttrs);
     if (withTag === withoutOld) {
       return { file: relFile, error: 'insertion_point_not_found', anchor: config.insertBefore || config.insertAfter };
     }
     const updated = patchCspMeta(withTag, port);
-    fs.writeFileSync(absFile, updated, 'utf-8');
+    writeProjectFileAtomic(cwd, relFile, updated);
     return {
       file: relFile,
       inserted: true,
@@ -235,7 +287,19 @@ Output (JSON):
     };
   });
   const anyInserted = results.some((r) => r.inserted);
-  console.log(JSON.stringify({ ok: anyInserted, port, gitIgnore, results }));
+  const writtenFiles = new Set(results.filter((r) => r.inserted).map((r) => r.file));
+  recordInjection(cwd, {
+    framework: resolved?.framework.name,
+    port,
+    artifacts: plannedArtifacts.filter((a) => writtenFiles.has(a.path)),
+  });
+  console.log(JSON.stringify({
+    ok: anyInserted,
+    port,
+    gitIgnore,
+    results,
+    healed: healed.length ? healed : undefined,
+  }));
   if (!anyInserted) process.exit(1);
 }
 
@@ -270,115 +334,6 @@ export function ensureLiveGitIgnores(cwd = process.cwd(), extraPatterns = []) {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Nuxt adapter
-//
-// A script element placed in app.vue is compiled as Vue-rendered DOM and is
-// not executed. Nuxt instead auto-discovers client plugins. Keep the adapter
-// generated, dev-only, and outside user-authored source: Live creates one
-// marked .client.ts plugin on start and removes it on stop.
-// ---------------------------------------------------------------------------
-
-export function detectNuxtProject(cwd = process.cwd()) {
-  const configFile = fs.readdirSync(cwd, { withFileTypes: true })
-    .find((entry) => entry.isFile() && /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/.test(entry.name))
-    ?.name;
-  if (!configFile) return null;
-
-  const config = fs.readFileSync(path.join(cwd, configFile), 'utf-8');
-  const literalSrcDir = config.match(/\bsrcDir\s*:\s*(['"])([^'"]+)\1/);
-  let appDir = '';
-  if (literalSrcDir) {
-    const candidate = literalSrcDir[2]
-      .replace(/\\/g, '/')
-      .replace(/^\.\//, '')
-      .replace(/\/+$/, '');
-    const normalized = path.posix.normalize(candidate);
-    if (normalized !== '..' && !normalized.startsWith('../') && !path.isAbsolute(normalized)) {
-      appDir = normalized === '.' ? '' : normalized;
-    }
-  } else if (
-    fs.existsSync(path.join(cwd, 'app', 'app.vue'))
-    || fs.existsSync(path.join(cwd, 'app', 'pages'))
-  ) {
-    appDir = 'app';
-  }
-
-  const pluginFile = [appDir, 'plugins', NUXT_PLUGIN_NAME].filter(Boolean).join('/');
-  return { configFile, appDir, pluginFile };
-}
-
-export function buildNuxtPlugin(port, token) {
-  return `/* ${NUXT_PLUGIN_MARKER} */
-const liveSrc = '${buildLiveScriptSrc(port, token)}';
-const liveSelector = 'script[data-impeccable-live-nuxt]';
-
-export default defineNuxtPlugin(() => {
-  if (!import.meta.dev || typeof document === 'undefined') return;
-
-  const expectedSrc = new URL(liveSrc, window.location.href).href;
-  let script = document.querySelector(liveSelector);
-  if (script?.src === expectedSrc) return;
-  script?.remove();
-
-  script = document.createElement('script');
-  script.src = liveSrc;
-  script.async = true;
-  script.dataset.impeccableLiveNuxt = '';
-  document.head.appendChild(script);
-
-  import.meta.hot?.dispose(() => {
-    if (script?.isConnected) script.remove();
-  });
-});
-/* /${NUXT_PLUGIN_MARKER} */
-`;
-}
-
-export function applyNuxtLiveAdapter({ cwd = process.cwd(), port, token, project = detectNuxtProject(cwd) }) {
-  if (!project) return { error: 'nuxt_not_detected' };
-  const absFile = path.join(cwd, project.pluginFile);
-  const existing = fs.existsSync(absFile) ? fs.readFileSync(absFile, 'utf-8') : null;
-  if (existing !== null && !existing.includes(NUXT_PLUGIN_MARKER)) {
-    return {
-      file: project.pluginFile,
-      error: 'nuxt_plugin_conflict',
-      hint: `${project.pluginFile} already exists and is not managed by Impeccable Live`,
-    };
-  }
-
-  const content = buildNuxtPlugin(port, token);
-  fs.mkdirSync(path.dirname(absFile), { recursive: true });
-  if (content !== existing) fs.writeFileSync(absFile, content, 'utf-8');
-  return {
-    file: project.pluginFile,
-    inserted: true,
-    changed: content !== existing,
-    devOnly: true,
-  };
-}
-
-export function removeNuxtLiveAdapter({ cwd = process.cwd(), project = detectNuxtProject(cwd) }) {
-  if (!project) return { error: 'nuxt_not_detected' };
-  const absFile = path.join(cwd, project.pluginFile);
-  if (!fs.existsSync(absFile)) {
-    return { file: project.pluginFile, removed: false, note: 'no adapter present' };
-  }
-  const content = fs.readFileSync(absFile, 'utf-8');
-  if (!content.includes(NUXT_PLUGIN_MARKER)) {
-    return {
-      file: project.pluginFile,
-      removed: false,
-      error: 'nuxt_plugin_conflict',
-      hint: `${project.pluginFile} is not managed by Impeccable Live`,
-    };
-  }
-  fs.unlinkSync(absFile);
-  const pluginDir = path.dirname(absFile);
-  if (fs.readdirSync(pluginDir).length === 0) fs.rmdirSync(pluginDir);
-  return { file: project.pluginFile, removed: true };
-}
-
 function resolveIgnoreTarget(cwd) {
   const gitExcludePath = resolveGitInfoExcludePath(cwd);
   if (gitExcludePath) {
@@ -425,26 +380,28 @@ export function resolveFiles(rootDir, config) {
   const seen = new Set();
   const out = [];
   for (const pat of patterns) {
-    if (!isGlob(pat)) {
+    const normalizedPattern = assertSafeProjectRelative(pat, 'config.files entry', { allowGlob: true });
+    if (!isGlob(normalizedPattern)) {
       // Literal path — include even if it doesn't exist yet; the caller
       // reports file_not_found per-entry. Exclude list doesn't apply to
       // explicit literal entries (user named it on purpose).
-      if (!seen.has(pat)) {
-        seen.add(pat);
-        out.push(pat);
+      if (!seen.has(normalizedPattern)) {
+        seen.add(normalizedPattern);
+        out.push(normalizedPattern);
       }
       continue;
     }
     let matches;
     try {
-      matches = fs.globSync(pat, { cwd: rootDir, withFileTypes: true });
+      matches = fs.globSync(normalizedPattern, { cwd: rootDir, withFileTypes: true });
     } catch {
       continue;
     }
     for (const ent of matches) {
       if (!ent.isFile || !ent.isFile()) continue;
       const abs = path.join(ent.parentPath || ent.path || rootDir, ent.name);
-      const rel = path.relative(rootDir, abs).split(path.sep).join('/');
+      const rel = assertSafeProjectRelative(path.relative(rootDir, abs).split(path.sep).join('/'));
+      try { resolveProjectPath(rootDir, rel, { mustExist: true, kind: 'file' }); } catch { continue; }
       if (isExcluded(rel)) continue;
       if (seen.has(rel)) continue;
       seen.add(rel);
@@ -507,6 +464,7 @@ function validateConfig(cfg) {
   if (!cfg.files.every((f) => typeof f === 'string' && f.length > 0)) {
     throw new Error('config.files must contain only non-empty strings');
   }
+  for (const file of cfg.files) assertSafeProjectRelative(file, 'config.files entry', { allowGlob: true });
   if (cfg.exclude !== undefined) {
     if (!Array.isArray(cfg.exclude)) {
       throw new Error('config.exclude, if present, must be a string array');
@@ -514,6 +472,7 @@ function validateConfig(cfg) {
     if (!cfg.exclude.every((f) => typeof f === 'string' && f.length > 0)) {
       throw new Error('config.exclude must contain only non-empty strings');
     }
+    for (const file of cfg.exclude) assertSafeProjectRelative(file, 'config.exclude entry', { allowGlob: true });
   }
   if (typeof cfg.insertBefore !== 'string' && typeof cfg.insertAfter !== 'string') {
     throw new Error('config.insertBefore or config.insertAfter (string) required');
@@ -526,242 +485,31 @@ function validateConfig(cfg) {
   }
 }
 
-function commentOpen(syntax) { return syntax === 'jsx' ? '{/*' : '<!--'; }
-function commentClose(syntax) { return syntax === 'jsx' ? '*/}' : '-->'; }
-
-/**
- * Build the /live.js src the browser loads. When a token is supplied it rides
- * as a `?token=...` query param so the server's token-gated /live.js handler
- * authorizes the fetch. Shared by every injection path (HTML/JSX script tag,
- * the Nuxt plugin, the SvelteKit root component) so they stay in sync.
- */
-export function buildLiveScriptSrc(port, token) {
-  const base = 'http://localhost:' + port + '/live.js';
-  return token ? base + '?token=' + encodeURIComponent(token) : base;
-}
-
-function buildTagBlock(syntax, port, filePath, token) {
-  const open = commentOpen(syntax);
-  const close = commentClose(syntax);
-  // Astro processes <script> tags by default and rewrites src to its own
-  // bundled URL. is:inline opts out so the literal external src survives.
-  const isAstro = typeof filePath === 'string' && filePath.endsWith('.astro');
-  const scriptAttrs = isAstro ? 'is:inline ' : '';
-  return (
-    open + ' ' + MARKER_OPEN_TEXT + ' ' + close + '\n' +
-    '<script ' + scriptAttrs + 'src="' + buildLiveScriptSrc(port, token) + '"></script>\n' +
-    open + ' ' + MARKER_CLOSE_TEXT + ' ' + close + '\n'
-  );
-}
-
-function detectLineEnding(content) {
-  if (content.includes('\r\n')) return '\r\n';
-  if (content.includes('\r')) return '\r';
-  return '\n';
-}
-
-function normalizeLineEndings(content, lineEnding) {
-  return lineEnding === '\n' ? content : content.replace(/\n/g, lineEnding);
-}
-
-function readLineEndingAt(content, index) {
-  if (content[index] === '\r' && content[index + 1] === '\n') return '\r\n';
-  if (content[index] === '\n') return '\n';
-  if (content[index] === '\r') return '\r';
-  return '';
-}
-
-function insertTag(content, config, port, filePath, token) {
-  const lineEnding = detectLineEnding(content);
-  const block = normalizeLineEndings(buildTagBlock(config.commentSyntax, port, filePath, token), lineEnding);
-  // insertBefore: match the LAST occurrence. Anchors like `</body>` naturally
-  // belong at the end, and the same literal can appear earlier in code blocks
-  // within rendered documentation pages.
-  if (config.insertBefore) {
-    const idx = content.lastIndexOf(config.insertBefore);
-    if (idx === -1) return content;
-    return content.slice(0, idx) + block + content.slice(idx);
-  }
-  // insertAfter: match the FIRST occurrence — typical anchors like `<head>` or
-  // `<body>` open near the top of the document.
-  const idx = content.indexOf(config.insertAfter);
-  if (idx === -1) return content;
-  const after = idx + config.insertAfter.length;
-  // Preserve an existing trailing newline if the anchor already has one.
-  // Slice the remainder from the original anchor offset, not prefix.length:
-  // in the no-newline case prefix is one char longer than the anchor (the
-  // appended '\n'), so slicing by prefix.length would drop the first real
-  // character after the anchor (#227).
-  const existingNewline = readLineEndingAt(content, after);
-  const prefix = content.slice(0, after) + (existingNewline || lineEnding);
-  const rest = content.slice(after + existingNewline.length);
-  return prefix + block + rest;
-}
-
-/**
- * Remove the live script block. Matches either HTML or JSX comment markers
- * regardless of config (so stale tags from a wrong config can still be cleaned).
- *
- * Indent-preserving: captures any whitespace immediately preceding the opener
- * marker and re-emits it in place of the removed block. `insertTag` inserted
- * the block *after* the original line's indent and *before* the anchor (e.g.
- * `</body>`), which moved the indent onto the opener line and left the anchor
- * unindented. Replacing the whole block (plus its trailing newline) with just
- * the captured indent hands the indent back to the anchor that follows.
- */
-function removeTag(content, _syntax) {
-  const patterns = [
-    /([ \t]*)<!--\s*impeccable-live-start\s*-->[\s\S]*?<!--\s*impeccable-live-end\s*-->([ \t]*(?:\r\n|\n|\r|$)?)/,
-    /([ \t]*)\{\/\*\s*impeccable-live-start\s*\*\/\}[\s\S]*?\{\/\*\s*impeccable-live-end\s*\*\/\}([ \t]*(?:\r\n|\n|\r|$)?)/,
-  ];
-  for (const pat of patterns) {
-    let changed = false;
-    let next = content;
-    do {
-      content = next;
-      next = content.replace(pat, (_match, leadingIndent, trailing = '') => {
-        if (/[\r\n]/.test(trailing)) return leadingIndent;
-        return leadingIndent || trailing || '';
-      });
-      if (next !== content) changed = true;
-    } while (next !== content);
-    if (changed) return next;
-  }
-  return content;
-}
-
-// ---------------------------------------------------------------------------
-// Content-Security-Policy meta-tag patcher
-//
-// When the user's HTML carries `<meta http-equiv="Content-Security-Policy">`,
-// the cross-origin load of /live.js (and the SSE/POST connection back to
-// localhost:PORT) is blocked unless the CSP explicitly allows that origin.
-//
-// On insert: append `http://localhost:PORT` to `script-src` and `connect-src`,
-// and stash the original `content` value in a `data-impeccable-csp-original`
-// attribute (base64) so revert is exact.
-//
-// On remove: detect the marker attribute, decode it, restore the original
-// content value verbatim, drop the marker.
-//
-// Header-based CSP (Next.js headers, Nuxt routeRules, SvelteKit kit.csp,
-// shared helpers) is NOT patched here — those need framework-specific config
-// edits and are handled via the existing detect-csp.mjs reference output.
-// Only the in-source meta-tag form gets the auto-patch.
-// ---------------------------------------------------------------------------
-
-const CSP_MARKER_ATTR = 'data-impeccable-csp-original';
-
-function findCspMetaTags(content) {
-  const out = [];
-  const tagRe = /<meta\s+([^>]*?)\/?>/gis;
-  let m;
-  while ((m = tagRe.exec(content)) !== null) {
-    const attrs = m[1];
-    if (!/(http-equiv|httpEquiv)\s*=\s*(['"])Content-Security-Policy\2/i.test(attrs)) continue;
-    out.push({ start: m.index, end: m.index + m[0].length, full: m[0], attrs });
-  }
-  return out;
-}
-
-function getAttr(attrs, name) {
-  const re = new RegExp(`\\b${name}\\s*=\\s*(['"])([\\s\\S]*?)\\1`, 'i');
-  const m = attrs.match(re);
-  return m ? { quote: m[1], value: m[2], full: m[0] } : null;
-}
-
-function appendOriginToDirective(csp, directive, origin) {
-  const re = new RegExp(`(^|;)(\\s*)(${directive})\\s+([^;]*)`, 'i');
-  const m = csp.match(re);
-  if (m) {
-    const tokens = m[4].trim().split(/\s+/);
-    if (tokens.includes(origin)) return csp;
-    return csp.replace(re, `${m[1]}${m[2]}${m[3]} ${[...tokens, origin].join(' ')}`);
-  }
-  // Directive missing — add it. Use 'self' + origin so we don't inadvertently
-  // narrow the policy compared to the default-src fallback (most users with
-  // an explicit CSP have 'self' there).
-  return csp.trim().replace(/;?\s*$/, '') + `; ${directive} 'self' ${origin}`;
-}
-
-export function patchCspMeta(content, port) {
-  const tags = findCspMetaTags(content);
-  if (tags.length === 0) return content;
-  const origin = `http://localhost:${port}`;
-
-  // Walk last-to-first so prior splices don't invalidate later indices.
-  let result = content;
-  for (let i = tags.length - 1; i >= 0; i--) {
-    const tag = tags[i];
-    const attrs = tag.attrs;
-    if (getAttr(attrs, CSP_MARKER_ATTR)) continue; // already patched
-    const contentAttr = getAttr(attrs, 'content');
-    if (!contentAttr) continue;
-
-    const original = contentAttr.value;
-    let patched = original;
-    patched = appendOriginToDirective(patched, 'script-src', origin);
-    patched = appendOriginToDirective(patched, 'connect-src', origin);
-    // The shader overlay during 'generating' creates a screenshot via
-    // URL.createObjectURL, producing a `blob:` URL — img-src 'self' rejects
-    // those. Add `blob:` so the overlay doesn't throw a CSP violation.
-    patched = appendOriginToDirective(patched, 'img-src', 'blob:');
-    if (patched === original) continue;
-
-    const newContentAttr = `content=${contentAttr.quote}${patched}${contentAttr.quote}`;
-    const marker = `${CSP_MARKER_ATTR}="${Buffer.from(original, 'utf-8').toString('base64')}"`;
-    // The tagRe captures any whitespace between the last attribute and the
-    // closing `/>` as part of `attrs`. Naively appending ` ${marker}` after
-    // a replace would land it BEFORE that trailing space, leaving a double
-    // space inside attrs and clobbering the space before `/>`. Split off
-    // the trailing whitespace, splice the marker into the attribute body,
-    // and re-append the original trailing whitespace so a self-closing
-    // `<meta … />` round-trips byte-for-byte.
-    const trailingWs = (attrs.match(/[ \t]*$/) || [''])[0];
-    const attrsBody = attrs.slice(0, attrs.length - trailingWs.length);
-    const newAttrs = attrsBody.replace(contentAttr.full, newContentAttr) + ' ' + marker + trailingWs;
-    const newTag = tag.full.replace(attrs, newAttrs);
-
-    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
-  }
-  return result;
-}
-
-export function revertCspMeta(content) {
-  const tags = findCspMetaTags(content);
-  if (tags.length === 0) return content;
-
-  let result = content;
-  for (let i = tags.length - 1; i >= 0; i--) {
-    const tag = tags[i];
-    const origAttr = getAttr(tag.attrs, CSP_MARKER_ATTR);
-    if (!origAttr) continue;
-    const contentAttr = getAttr(tag.attrs, 'content');
-    if (!contentAttr) continue;
-
-    let originalValue;
-    try { originalValue = Buffer.from(origAttr.value, 'base64').toString('utf-8'); }
-    catch { continue; }
-
-    const newContentAttr = `content=${contentAttr.quote}${originalValue}${contentAttr.quote}`;
-    let newAttrs = tag.attrs.replace(contentAttr.full, newContentAttr);
-    // Drop the marker attribute and any single space immediately preceding it.
-    newAttrs = newAttrs.replace(new RegExp(`\\s*${origAttr.full}`), '');
-    const newTag = tag.full.replace(tag.attrs, newAttrs);
-
-    result = result.slice(0, tag.start) + newTag + result.slice(tag.end);
-  }
-  return result;
-}
-
 // ---------------------------------------------------------------------------
 // Auto-execute
 // ---------------------------------------------------------------------------
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-inject.mjs') || _running?.endsWith('live-inject.mjs/')) {
+  enterLiveRoot();
   injectCli();
 }
 
-export { insertTag, removeTag, validateConfig, buildTagBlock };
-// patchCspMeta + revertCspMeta are exported above where they're defined.
+// Re-exported so long-standing importers (live.mjs, the adapter modules, the
+// test suites) keep their entry points while the implementations live in
+// live/frameworks/.
+export {
+  buildLiveScriptSrc,
+  buildTagBlock,
+  insertTag,
+  patchCspMeta,
+  removeTag,
+  revertCspMeta,
+  validateConfig,
+};
+export {
+  applyNuxtLiveAdapter,
+  buildNuxtPlugin,
+  detectNuxtProject,
+  removeNuxtLiveAdapter,
+} from './live/frameworks/nuxt.mjs';