@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/impeccable/scripts/live/frameworks/journal.mjs

@@ -0,0 +1,197 @@
+/**
+ * Crash-safe injection journal.
+ *
+ * Injection writes into the user's source tree: generated components, a Nuxt
+ * client plugin, marker blocks inside a layout, a patched CSP meta tag. The
+ * clean path removes all of it on stop. The unclean paths do not:
+ *
+ *   - the dev server is SIGKILLed, so `--remove` never runs;
+ *   - the project changes shape between start and stop (a nuxt.config appears,
+ *     a package.json is edited), so detection resolves a different framework
+ *     and the old framework's artifacts are nobody's business;
+ *   - stop runs from a different directory than start did.
+ *
+ * So every inject records what it wrote to `.impeccable/live/inject-journal.json`
+ * before the next one runs, and both inject and `--remove` reconcile that
+ * record against the tree.
+ *
+ * **The journal is a claim of ownership, not a to-do list.** Healing an
+ * artifact only ever removes what still carries our marker; a generated file
+ * the user has since replaced, or a layout they have since un-patched by hand,
+ * is dropped from the journal untouched.
+ *
+ * **Path resolution is appRoot-relative.** Live entry scripts chdir onto the
+ * roots manifest (`enterLiveRoot`) before doing anything, so a journal written
+ * by a session started in the app root is found by a stop issued from any
+ * directory inside the repo.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { PATCH_UNDOERS } from './index.mjs';
+
+export const INJECT_JOURNAL_VERSION = 1;
+export const INJECT_JOURNAL_RELPATH = '.impeccable/live/inject-journal.json';
+
+export function injectJournalPath(cwd = process.cwd()) {
+  return path.join(cwd, ...INJECT_JOURNAL_RELPATH.split('/'));
+}
+
+export function readInjectJournal(cwd = process.cwd()) {
+  const file = injectJournalPath(cwd);
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.artifacts)) return null;
+  return raw;
+}
+
+export function clearInjectJournal(cwd = process.cwd()) {
+  try { fs.unlinkSync(injectJournalPath(cwd)); } catch { /* already gone */ }
+}
+
+function writeInjectJournal(cwd, journal) {
+  const file = injectJournalPath(cwd);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(journal, null, 2) + '\n', 'utf-8');
+  return file;
+}
+
+/**
+ * Record the artifacts an injection just wrote. Replaces any previous record:
+ * callers heal first (see healInjectJournal), so nothing survivable is lost.
+ */
+export function recordInjection(cwd = process.cwd(), { framework, port, artifacts = [] } = {}) {
+  if (!artifacts.length) {
+    clearInjectJournal(cwd);
+    return null;
+  }
+  return writeInjectJournal(cwd, {
+    version: INJECT_JOURNAL_VERSION,
+    appRoot: path.resolve(cwd),
+    framework: framework || null,
+    port: Number.isFinite(Number(port)) ? Number(port) : null,
+    pid: process.pid,
+    recordedAt: new Date().toISOString(),
+    artifacts,
+  });
+}
+
+function normalizeRel(cwd, rel) {
+  return path.resolve(cwd, String(rel || '')).split(path.sep).join('/');
+}
+
+function readIfPresent(abs) {
+  try {
+    return fs.readFileSync(abs, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function pruneEmptyDirs(dir, stopDir) {
+  let current = path.resolve(dir);
+  const stop = path.resolve(stopDir);
+  while (current !== stop && current.startsWith(stop + path.sep)) {
+    try {
+      if (fs.readdirSync(current).length > 0) return;
+      fs.rmdirSync(current);
+    } catch {
+      return;
+    }
+    current = path.dirname(current);
+  }
+}
+
+function insideProject(cwd, abs) {
+  const rel = path.relative(path.resolve(cwd), path.resolve(abs));
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function healArtifact(cwd, artifact, undoers) {
+  const abs = path.resolve(cwd, artifact.path);
+  // The journal is a project-local file, i.e. attacker-writable input in a
+  // cloned repo. Never touch anything outside the project tree, whatever the
+  // journal claims to own.
+  if (!insideProject(cwd, abs)) return { path: artifact.path, action: 'refused_outside_project' };
+  const content = readIfPresent(abs);
+  if (content === null) return { path: artifact.path, action: 'absent' };
+
+  if (artifact.kind === 'created') {
+    // Only reclaim a generated file that still carries our marker; a created
+    // artifact with no marker at all is unverifiable and stays untouched.
+    if (!artifact.marker || !content.includes(artifact.marker)) {
+      return { path: artifact.path, action: 'disowned' };
+    }
+    try { fs.rmSync(abs, { force: true }); } catch { return null; }
+    if (artifact.pruneTo !== undefined) {
+      const pruneRoot = path.resolve(cwd, artifact.pruneTo || '.');
+      if (insideProject(cwd, pruneRoot) || pruneRoot === path.resolve(cwd)) {
+        pruneEmptyDirs(path.dirname(abs), pruneRoot);
+      }
+    }
+    return { path: artifact.path, action: 'removed' };
+  }
+
+  if (artifact.kind === 'patched') {
+    const markers = Array.isArray(artifact.markers) ? artifact.markers : [];
+    // No marker left means the patch is already gone; never run an undo over
+    // a file we no longer recognize (the undoers normalize whitespace).
+    if (markers.length && !markers.some((marker) => content.includes(marker))) {
+      return { path: artifact.path, action: 'disowned' };
+    }
+    const undo = undoers[artifact.patch];
+    if (typeof undo !== 'function') return null;
+    const next = undo(content);
+    if (next === content) return { path: artifact.path, action: 'disowned' };
+    try { fs.writeFileSync(abs, next, 'utf-8'); } catch { return null; }
+    return { path: artifact.path, action: 'unpatched' };
+  }
+
+  return null;
+}
+
+/**
+ * Reconcile the journal against the tree.
+ *
+ * `keep` is the set of paths the current operation legitimately owns — the
+ * artifacts an inject is about to (re)write. Everything else in the journal is
+ * an orphan of a session that is gone, and gets healed. This keeps a repeat
+ * inject byte-idempotent: the artifacts it is about to rewrite are kept, not
+ * torn down and rebuilt.
+ *
+ * Returns `{ healed, kept }`. `healed` lists only artifacts whose file was
+ * actually changed or removed, so callers can stay silent when nothing was
+ * orphaned. Idempotent: a second call finds an empty journal.
+ */
+export function healInjectJournal(cwd = process.cwd(), { keep = [], undoers = PATCH_UNDOERS } = {}) {
+  const journal = readInjectJournal(cwd);
+  if (!journal) return { healed: [], kept: [] };
+
+  const keepSet = new Set(keep.map((rel) => normalizeRel(cwd, rel)));
+  const healed = [];
+  const kept = [];
+
+  for (const artifact of journal.artifacts) {
+    if (!artifact || typeof artifact.path !== 'string') continue;
+    if (keepSet.has(normalizeRel(cwd, artifact.path))) {
+      kept.push(artifact);
+      continue;
+    }
+    const outcome = healArtifact(cwd, artifact, undoers);
+    if (outcome && (outcome.action === 'removed' || outcome.action === 'unpatched')) {
+      healed.push(outcome);
+    }
+  }
+
+  if (kept.length) {
+    writeInjectJournal(cwd, { ...journal, artifacts: kept });
+  } else {
+    clearInjectJournal(cwd);
+  }
+
+  return { healed, kept };
+}

package/skills/impeccable/scripts/live/frameworks/nextjs.mjs

@@ -0,0 +1,49 @@
+/**
+ * Next.js registry entry.
+ *
+ * Next takes the generic tag strategy: the App Router's root layout renders
+ * `<html>…<body>` in JSX, so the marker-wrapped script block goes in there
+ * verbatim. Nothing about injection differs from a plain Vite app, which is
+ * why live-inject.mjs never had a Next branch. The entry exists so the
+ * registry can name what it is looking at.
+ */
+
+import { fileExists, findConfigFile, hasAnyDependency } from './detect-utils.mjs';
+
+const NEXT_CONFIG_RE = /^next\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+const ROUTER_ENTRY_CANDIDATES = [
+  'app/layout.tsx', 'app/layout.jsx', 'app/layout.ts', 'app/layout.js',
+  'src/app/layout.tsx', 'src/app/layout.jsx', 'src/app/layout.ts', 'src/app/layout.js',
+  'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.ts', 'pages/_app.js',
+  'pages/_document.tsx', 'pages/_document.jsx',
+  'src/pages/_app.tsx', 'src/pages/_app.jsx',
+];
+
+export function detectNextProject(cwd = process.cwd()) {
+  const configFile = findConfigFile(cwd, NEXT_CONFIG_RE);
+  if (configFile) return { configFile, via: 'config' };
+  if (hasAnyDependency(cwd, ['next'])) return { configFile: null, via: 'package' };
+  // Next's file conventions are distinctive enough to stand alone: a root
+  // `app/layout.*` or `pages/_app.*` is not a shape other bundlers produce.
+  const entry = ROUTER_ENTRY_CANDIDATES.find((rel) => fileExists(cwd, rel));
+  if (entry) return { configFile: null, via: 'router-entry', entry };
+  return null;
+}
+
+export const nextjs = {
+  name: 'nextjs',
+
+  detect(cwd) {
+    return detectNextProject(cwd);
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.tsx', '.jsx'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'jsx',
+  },
+};

package/skills/impeccable/scripts/live/frameworks/nuxt.mjs

@@ -0,0 +1,161 @@
+/**
+ * Nuxt registry entry, and the Nuxt adapter itself.
+ *
+ * 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.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from './script-src.mjs';
+import { findConfigFile } from './detect-utils.mjs';
+
+export const NUXT_PLUGIN_MARKER = 'impeccable-live-nuxt-plugin';
+export const NUXT_PLUGIN_NAME = 'impeccable-live.client.ts';
+
+const NUXT_CONFIG_RE = /^nuxt\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+export function detectNuxtProject(cwd = process.cwd()) {
+  const configFile = findConfigFile(cwd, NUXT_CONFIG_RE);
+  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 };
+}
+
+export const nuxt = {
+  name: 'nuxt',
+
+  detect(cwd) {
+    return detectNuxtProject(cwd);
+  },
+
+  inject: {
+    kind: 'adapter',
+
+    apply({ cwd, port, token, project }) {
+      return applyNuxtLiveAdapter({ cwd, port, token, project });
+    },
+
+    remove({ cwd, project }) {
+      return removeNuxtLiveAdapter({ cwd, project });
+    },
+
+    // The plugin path depends on the resolved srcDir, so it cannot live in the
+    // static ignore list the way the SvelteKit paths do.
+    ignorePatterns(project) {
+      return project?.pluginFile ? [project.pluginFile] : [];
+    },
+
+    artifacts({ project }) {
+      if (!project?.pluginFile) return [];
+      return [{
+        kind: 'created',
+        path: project.pluginFile,
+        marker: NUXT_PLUGIN_MARKER,
+        // Mirrors removeNuxtLiveAdapter: the generated `plugins/` directory
+        // goes when it empties, its parent stays.
+        pruneTo: path.posix.dirname(path.posix.dirname(project.pluginFile)),
+      }];
+    },
+  },
+
+  source: {
+    extensions: ['.vue'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'html',
+  },
+};

package/skills/impeccable/scripts/live/frameworks/script-src.mjs

@@ -0,0 +1,17 @@
+/**
+ * The one place that builds the `/live.js` URL the browser loads.
+ *
+ * Every injection path needs it (the generic script tag, the Nuxt client
+ * plugin, the SvelteKit root component, the TanStack mount component), and a
+ * separate module keeps that shared leaf free of import cycles: the framework
+ * entries import it, and nothing here imports a framework entry.
+ */
+
+/**
+ * When a token is supplied it rides as a `?token=...` query param so the
+ * server's token-gated /live.js handler authorizes the fetch.
+ */
+export function buildLiveScriptSrc(port, token) {
+  const base = 'http://localhost:' + port + '/live.js';
+  return token ? base + '?token=' + encodeURIComponent(token) : base;
+}

package/skills/impeccable/scripts/live/frameworks/static-html.mjs

@@ -0,0 +1,26 @@
+/**
+ * Static HTML registry entry: the terminal fallback.
+ *
+ * Hand-written pages, a multi-page site emitted by a generator, anything with
+ * no bundler config at the app root. `detect` always matches, so this entry
+ * must stay last in FRAMEWORKS. Its behavior is the plain tag strategy, which
+ * is what live-inject.mjs did for every unrecognized project before the
+ * registry existed.
+ */
+
+export const staticHtml = {
+  name: 'static-html',
+
+  detect() {
+    return { via: 'fallback' };
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.html', '.htm'],
+    preview: 'source',
+    styleMode: 'scoped',
+    commentSyntax: 'html',
+  },
+};

package/skills/impeccable/scripts/live/frameworks/sveltekit.mjs

@@ -0,0 +1,71 @@
+/**
+ * SvelteKit registry entry.
+ *
+ * Detection and the apply/remove pair are the existing adapter's
+ * (`../sveltekit-adapter.mjs`); this file only declares them to the registry
+ * and names the artifacts the journal has to be able to heal.
+ */
+
+import {
+  SVELTE_LAYOUT_MARKER_OPEN,
+  SVELTE_LIVE_ROOT_COMPONENT,
+  applySvelteKitLiveAdapter,
+  detectSvelteKitProject,
+  removeSvelteKitLiveAdapter,
+  unpatchSvelteLayout,
+} from '../sveltekit-adapter.mjs';
+
+export const sveltekit = {
+  name: 'sveltekit',
+
+  detect(cwd, config) {
+    return detectSvelteKitProject(cwd, config);
+  },
+
+  inject: {
+    kind: 'adapter',
+
+    apply({ cwd, port, token, config }) {
+      return applySvelteKitLiveAdapter({ cwd, port, token, config });
+    },
+
+    remove({ cwd, config }) {
+      return removeSvelteKitLiveAdapter({ cwd, config });
+    },
+
+    // The generated root component and the `src/lib/impeccable/` runtime paths
+    // are already in the static LIVE_IGNORE_PATTERNS list, so nothing extra.
+    ignorePatterns() {
+      return [];
+    },
+
+    artifacts({ project }) {
+      return [
+        {
+          kind: 'created',
+          path: SVELTE_LIVE_ROOT_COMPONENT,
+          marker: 'impeccable-live-root',
+          pruneTo: 'src',
+        },
+        {
+          kind: 'patched',
+          path: project?.layoutFile || 'src/routes/+layout.svelte',
+          patch: 'sveltekit-layout',
+          markers: [SVELTE_LAYOUT_MARKER_OPEN],
+        },
+      ];
+    },
+
+    unpatch: {
+      'sveltekit-layout': unpatchSvelteLayout,
+    },
+  },
+
+  source: {
+    extensions: ['.svelte'],
+    // Svelte resets component-local state on markup HMR updates, so variants
+    // are mounted from generated components rather than written into the route.
+    preview: 'component',
+    commentSyntax: 'html',
+  },
+};