quiver-cli 0.8.0 → 1.0.0

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

@@ -7,6 +7,7 @@
  * actual live UI remains the shared plain-DOM browser chrome.
  */
 
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
@@ -14,6 +15,28 @@ export const SVELTE_LIVE_ROOT_COMPONENT = 'src/lib/impeccable/ImpeccableLiveRoot
 export const SVELTE_LAYOUT_MARKER_OPEN = '<!-- impeccable-live-svelte-start -->';
 export const SVELTE_LAYOUT_MARKER_CLOSE = '<!-- impeccable-live-svelte-end -->';
 export const SVELTE_ROOT_IMPORT = "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte';";
+// Matches the import at ANY revision (or none). [ \t]* bounds only, never
+// \s*: a greedy \s* after the statement swallowed the next line's
+// indentation on removal, leaving a formatting scar in user layouts.
+const SVELTE_ROOT_IMPORT_LINE_RE = /^[ \t]*import ImpeccableLiveRoot from '\$lib\/impeccable\/ImpeccableLiveRoot\.svelte(?:\?[^']*)?';[ \t]*\r?\n?/gm;
+
+/**
+ * The import specifier carries a token-derived revision query. The adapter
+ * component embeds the helper token, and Vite (client AND SSR) can keep
+ * serving a stale compiled module after the file is rewritten on a helper
+ * restart; the browser then requests /live.js with a rotated-out token and
+ * gets a 401 with no picker. A changed specifier is a different module id,
+ * which no cache survives.
+ */
+export function svelteRootImportLine(rev) {
+  if (!rev) return SVELTE_ROOT_IMPORT;
+  return "import ImpeccableLiveRoot from '$lib/impeccable/ImpeccableLiveRoot.svelte?impeccable-live=" + rev + "';";
+}
+
+export function svelteAdapterRev(token) {
+  if (!token) return null;
+  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 8);
+}
 
 export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   const appHtml = findSvelteKitAppHtml(cwd, config);
@@ -36,21 +59,21 @@ export function detectSvelteKitProject(cwd = process.cwd(), config = null) {
   };
 }
 
-export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, config = null } = {}) {
+export function applySvelteKitLiveAdapter({ cwd = process.cwd(), port, token, config = null } = {}) {
   if (!Number.isFinite(Number(port))) {
     throw new Error('SvelteKit live adapter requires a numeric port');
   }
   const detected = detectSvelteKitProject(cwd, config);
   if (!detected) return null;
 
-  ensureSvelteLiveRootComponent(cwd, Number(port));
+  ensureSvelteLiveRootComponent(cwd, Number(port), token);
 
   const layoutRel = detected.layoutFile;
   const layoutAbs = path.join(cwd, layoutRel);
   fs.mkdirSync(path.dirname(layoutAbs), { recursive: true });
   const layoutExisted = fs.existsSync(layoutAbs);
   const before = layoutExisted ? fs.readFileSync(layoutAbs, 'utf-8') : defaultSvelteLayout();
-  const after = patchSvelteLayout(before);
+  const after = patchSvelteLayout(before, { rev: svelteAdapterRev(token) });
   fs.writeFileSync(layoutAbs, after, 'utf-8');
 
   return {
@@ -94,15 +117,27 @@ export function removeSvelteKitLiveAdapter({ cwd = process.cwd(), config = null
   };
 }
 
-export function patchSvelteLayout(content) {
+export function patchSvelteLayout(content, { rev = null } = {}) {
   let out = String(content || '');
-  if (!out.includes(SVELTE_ROOT_IMPORT)) {
-    const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
-    if (scriptMatch) {
-      const insertAt = scriptMatch.index + scriptMatch[0].length;
-      out = out.slice(0, insertAt) + '\n  ' + SVELTE_ROOT_IMPORT + out.slice(insertAt);
-    } else {
-      out = `<script>\n  ${SVELTE_ROOT_IMPORT}\n</script>\n\n` + out;
+  const importLine = svelteRootImportLine(rev);
+  if (!out.includes(importLine)) {
+    // An import at an older revision is replaced in place, keeping its
+    // indentation; only a layout with no impeccable import gets an insert.
+    let replaced = false;
+    out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, (line) => {
+      if (replaced) return '';
+      replaced = true;
+      const indent = (line.match(/^[ \t]*/) || [''])[0];
+      return indent + importLine + '\n';
+    });
+    if (!replaced) {
+      const scriptMatch = out.match(/<script(?:\s[^>]*)?>/i);
+      if (scriptMatch) {
+        const insertAt = scriptMatch.index + scriptMatch[0].length;
+        out = out.slice(0, insertAt) + '\n  ' + importLine + out.slice(insertAt);
+      } else {
+        out = `<script>\n  ${importLine}\n</script>\n\n` + out;
+      }
     }
   }
 
@@ -131,23 +166,25 @@ export function unpatchSvelteLayout(content) {
     'g',
   );
   out = out.replace(blockRe, '$1');
-  out = out.replace(new RegExp('^\\s*' + escapeRegExp(SVELTE_ROOT_IMPORT) + '\\s*\\n?', 'gm'), '');
-  out = out.replace(/<script>\s*<\/script>\s*\n?/g, '');
+  out = out.replace(SVELTE_ROOT_IMPORT_LINE_RE, '');
+  out = out.replace(/<script>\s*<\/script>[ \t]*\r?\n?/g, '');
   return out.replace(/\n{3,}/g, '\n\n');
 }
 
-export function ensureSvelteLiveRootComponent(cwd, port) {
+export function ensureSvelteLiveRootComponent(cwd, port, token) {
   const file = path.join(cwd, SVELTE_LIVE_ROOT_COMPONENT);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, buildSvelteLiveRootComponent(port), 'utf-8');
+  fs.writeFileSync(file, buildSvelteLiveRootComponent(port, token), 'utf-8');
   return file;
 }
 
-export function buildSvelteLiveRootComponent(port) {
+export function buildSvelteLiveRootComponent(port, token) {
+  const liveUrl = 'http://localhost:' + Number(port) + '/live.js'
+    + (token ? '?token=' + encodeURIComponent(token) : '');
   return `<script>
   import { onMount } from 'svelte';
 
-  const LIVE_URL = 'http://localhost:${Number(port)}/live.js';
+  const LIVE_URL = '${liveUrl}';
   const HOST_ID = 'impeccable-live-root';
 
   onMount(() => {
@@ -191,6 +228,11 @@ export function buildSvelteLiveRootComponent(port) {
     script.src = LIVE_URL;
     script.async = true;
     script.dataset.impeccableLiveScript = 'true';
+    script.onerror = () => console.error(
+      '[impeccable] live.js failed to load from ' + LIVE_URL
+      + ' (helper down, or the token rotated while a stale adapter module was cached).'
+      + ' Re-run the live boot, then reload this page.'
+    );
     document.head.appendChild(script);
 
     return () => {

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

@@ -0,0 +1,280 @@
+/**
+ * TanStack Start live-mode adapter.
+ *
+ * TanStack Start is SSR: there is no static index.html to patch. The document
+ * shell is a React component (`shellComponent`/`component`) defined in the root
+ * route file, `src/routes/__root.tsx`, which renders `<html>…<body>{children}
+ * <Scripts /></body></html>`.
+ *
+ * A raw `<script src>` placed in that JSX is server-rendered into the streamed
+ * HTML, but React's script handling and hydration make it an unreliable place
+ * to load a cross-origin dev bundle. So, like the Nuxt and SvelteKit adapters,
+ * this keeps the injected code in a dev-only managed component that appends the
+ * live script on mount (client-only, after hydration). The adapter mounts that
+ * component from the root document and removes it cleanly on stop.
+ *
+ * The managed component lives OUTSIDE `src/routes/` (in `src/impeccable/`) so
+ * the TanStack Router file-based route generator never treats it as a route.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildLiveScriptSrc } from './frameworks/script-src.mjs';
+
+export const TANSTACK_MARKER_OPEN = '{/* impeccable-live-tanstack-start */}';
+export const TANSTACK_MARKER_CLOSE = '{/* impeccable-live-tanstack-end */}';
+export const TANSTACK_COMPONENT_DIR = 'src/impeccable';
+export const TANSTACK_COMPONENT_BASENAME = 'ImpeccableLiveRoot';
+
+const ROOT_ROUTE_CANDIDATES = [
+  'src/routes/__root.tsx',
+  'src/routes/__root.jsx',
+  'src/routes/__root.ts',
+  'src/routes/__root.js',
+  'app/routes/__root.tsx',
+  'app/routes/__root.jsx',
+];
+
+const START_PACKAGES = [
+  '@tanstack/react-start',
+  '@tanstack/solid-start',
+  '@tanstack/start',
+];
+
+export function detectTanStackStartProject(cwd = process.cwd()) {
+  if (!packageHasTanStackStart(cwd)) return null;
+  const rootRoute = findRootRouteFile(cwd);
+  if (!rootRoute) return null;
+
+  const ext = path.extname(rootRoute);
+  const componentExt = ext === '.jsx' || ext === '.js' ? '.jsx' : '.tsx';
+  const componentFile = `${TANSTACK_COMPONENT_DIR}/${TANSTACK_COMPONENT_BASENAME}${componentExt}`;
+  const componentImport = relativeImportSpecifier(rootRoute, componentFile);
+
+  return { rootRoute, componentFile, componentImport, ext };
+}
+
+export function applyTanStackLiveAdapter({ cwd = process.cwd(), port, token, project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  if (!Number.isFinite(Number(port))) {
+    throw new Error('TanStack Start live adapter requires a numeric port');
+  }
+
+  // Write the managed mount component.
+  const componentAbs = path.join(cwd, project.componentFile);
+  const componentBody = buildTanStackLiveRootComponent(Number(port), token);
+  const componentExisted = fs.existsSync(componentAbs);
+  if (componentExisted && !isManagedComponent(fs.readFileSync(componentAbs, 'utf-8'))) {
+    // A non-Impeccable file already sits at our managed path — refuse to clobber.
+    return {
+      file: project.componentFile,
+      error: 'tanstack_component_conflict',
+      hint: `${project.componentFile} already exists and is not managed by Impeccable Live`,
+    };
+  }
+  fs.mkdirSync(path.dirname(componentAbs), { recursive: true });
+  fs.writeFileSync(componentAbs, componentBody, 'utf-8');
+
+  // Patch the root document to import + render the mount component.
+  const rootAbs = path.join(cwd, project.rootRoute);
+  const before = fs.readFileSync(rootAbs, 'utf-8');
+  const after = patchTanStackRoot(before, project.componentImport);
+  const changed = after !== before;
+  if (changed) fs.writeFileSync(rootAbs, after, 'utf-8');
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    inserted: changed || !componentExisted,
+    componentFile: project.componentFile,
+    devOnly: true,
+  };
+}
+
+export function removeTanStackLiveAdapter({ cwd = process.cwd(), project = detectTanStackStartProject(cwd) } = {}) {
+  if (!project) return { error: 'tanstack_not_detected' };
+  let removed = false;
+
+  const rootAbs = path.join(cwd, project.rootRoute);
+  if (fs.existsSync(rootAbs)) {
+    const before = fs.readFileSync(rootAbs, 'utf-8');
+    const after = unpatchTanStackRoot(before);
+    if (after !== before) {
+      fs.writeFileSync(rootAbs, after, 'utf-8');
+      removed = true;
+    }
+  }
+
+  const componentAbs = path.join(cwd, project.componentFile);
+  if (fs.existsSync(componentAbs)) {
+    fs.rmSync(componentAbs, { force: true });
+    removed = true;
+  }
+  pruneEmptyDir(path.dirname(componentAbs), path.join(cwd, 'src'));
+
+  return {
+    file: project.rootRoute,
+    adapter: 'tanstack-start',
+    removed,
+    componentFile: project.componentFile,
+  };
+}
+
+export function patchTanStackRoot(content, componentImport) {
+  let out = String(content || '');
+  const importStatement = `import ImpeccableLiveRoot from '${componentImport}';`;
+
+  if (!out.includes(importStatement)) {
+    out = insertAfterLastImport(out, importStatement);
+  }
+
+  if (!out.includes(TANSTACK_MARKER_OPEN)) {
+    const block =
+      `${TANSTACK_MARKER_OPEN}\n`
+      + `        <ImpeccableLiveRoot />\n`
+      + `        ${TANSTACK_MARKER_CLOSE}\n        `;
+    // Anchor before <Scripts …/> (the stable TanStack Start document marker);
+    // fall back to before </body>.
+    const scriptsMatch = out.match(/<Scripts\b/);
+    if (scriptsMatch) {
+      out = out.slice(0, scriptsMatch.index) + block + out.slice(scriptsMatch.index);
+    } else {
+      const bodyClose = out.lastIndexOf('</body>');
+      if (bodyClose !== -1) {
+        out = out.slice(0, bodyClose) + block + out.slice(bodyClose);
+      }
+    }
+  }
+
+  return out;
+}
+
+export function unpatchTanStackRoot(content) {
+  let out = String(content || '');
+  // Remove exactly the inserted block (open marker → component → close marker →
+  // trailing newline + the indent that leads back to the anchor). Leaving the
+  // leading indent before the open marker intact hands it back to the anchor
+  // (e.g. `<Scripts />`) so the file round-trips byte-for-byte.
+  const blockRe = new RegExp(
+    escapeRegExp(TANSTACK_MARKER_OPEN)
+    + '\\s*<ImpeccableLiveRoot\\s*/>\\s*'
+    + escapeRegExp(TANSTACK_MARKER_CLOSE)
+    + '\\r?\\n?[ \\t]*',
+    'g',
+  );
+  out = out.replace(blockRe, '');
+  // Remove only the managed import line — not any following blank line.
+  out = out.replace(
+    new RegExp("^import ImpeccableLiveRoot from '[^']*';[ \\t]*\\r?\\n", 'gm'),
+    '',
+  );
+  return out;
+}
+
+export function buildTanStackLiveRootComponent(port, token) {
+  const liveSrc = buildLiveScriptSrc(Number(port), token);
+  return `/* impeccable-live-tanstack-start */
+import { useEffect } from 'react';
+
+const LIVE_SRC = '${liveSrc}';
+const LIVE_SELECTOR = 'script[data-impeccable-live-tanstack]';
+
+// Dev-only mount for Impeccable Live. TanStack Start server-renders the root
+// document, so this appends the live-mode bundle from the client after
+// hydration (mirrors the Nuxt/SvelteKit adapters). Renders nothing on the
+// server, so there is no hydration mismatch.
+export default function ImpeccableLiveRoot() {
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const expected = new URL(LIVE_SRC, window.location.href).href;
+    let script = document.querySelector(LIVE_SELECTOR);
+    if (script && script.src === expected) return;
+    if (script) script.remove();
+
+    script = document.createElement('script');
+    script.src = LIVE_SRC;
+    script.async = true;
+    script.setAttribute('data-impeccable-live-tanstack', '');
+    script.setAttribute('data-impeccable-live-script', 'true');
+    document.head.appendChild(script);
+
+    return () => {
+      if (script && script.isConnected) script.remove();
+    };
+  }, []);
+
+  return null;
+}
+`;
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// The managed mount component carries the `impeccable-live-tanstack` marker in
+// its leading comment and its script data-attribute; user files never do.
+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('/')),
+    toFile.split(path.sep).join('/'),
+  ).replace(/\.(tsx|ts|jsx|js)$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function insertAfterLastImport(content, importStatement) {
+  const importRe = /^import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importRe.exec(content)) !== null) {
+    lastEnd = m.index + m[0].length;
+  }
+  if (lastEnd === -1) {
+    return `${importStatement}\n${content}`;
+  }
+  return content.slice(0, lastEnd) + importStatement + '\n' + content.slice(lastEnd);
+}
+
+function pruneEmptyDir(dir, stopDir) {
+  let current = dir;
+  while (current.startsWith(stopDir) && current !== stopDir) {
+    try {
+      if (fs.readdirSync(current).length > 0) return;
+      fs.rmdirSync(current);
+      current = path.dirname(current);
+    } catch {
+      return;
+    }
+  }
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/template/.agents/skills/design/impeccable/scripts/live/vocabulary.mjs

@@ -34,3 +34,138 @@ export const LIVE_COMMANDS = [
 
 // Action values accepted by the live event protocol, in palette order.
 export const VISUAL_ACTIONS = LIVE_COMMANDS.map((c) => c.value);
+
+/*
+ * ---------------------------------------------------------------------------
+ * Protocol vocabulary
+ * ---------------------------------------------------------------------------
+ * The enums below are the wire contract between the browser overlay, the live
+ * helper server, and the durable session journal. They live here rather than in
+ * the modules that use them so a value cannot be added to the validator without
+ * the store and the server seeing it too.
+ *
+ * live-browser.js still cannot import this file (it is served raw and injected
+ * as an IIFE), so its local phase table repeats the agent-phase names. Anything
+ * the server can broadcast must appear in AGENT_PHASES here first.
+ */
+
+/**
+ * Phases the live server broadcasts as `agent_phase`, in lifecycle order.
+ * Every one of these is emitted by `recordAgentPhase()` in live-server.mjs;
+ * the validator rejects anything else, so a typo in a phase name fails loudly
+ * instead of quietly ranking as an unknown phase in the browser's progress bar.
+ */
+export const AGENT_PHASES = Object.freeze([
+  'picked_up',
+  'scaffolding',
+  'source_ready',
+  'scaffold_fallback',
+  'generation_ready',
+  'first_reviewable',
+  'second_reviewable',
+  'all_variants_ready',
+]);
+
+/** Event types the helper server accepts from the browser over POST /events. */
+export const CLIENT_EVENT_TYPES = Object.freeze([
+  'generate',
+  'accept',
+  'discard',
+  'checkpoint',
+  'agent_phase',
+  'variant_mounted',
+  'variant_mount_failed',
+  'exit',
+  'prefetch',
+  'manual_edits',
+  'steer',
+  'carbonize_cleanup',
+]);
+
+/**
+ * Event types the durable journal applies. A superset of CLIENT_EVENT_TYPES:
+ * the agent-side helpers (live-poll, live-complete) and the server itself
+ * append the rest. An event type missing here lands as `unknown_event_type`
+ * in the snapshot diagnostics.
+ */
+export const JOURNAL_EVENT_TYPES = Object.freeze([
+  'generate',
+  'variant_plan',
+  'detector_waivers',
+  'agent_phase',
+  'variants_ready',
+  'agent_done',
+  'variant_mounted',
+  'variant_mount_failed',
+  'checkpoint',
+  'accept',
+  'accept_intent',
+  'manual_edit_apply',
+  'steer',
+  'steer_done',
+  'carbonize_cleanup',
+  'discard',
+  'discarded',
+  'complete',
+  'agent_error',
+]);
+
+/** Phases the session store assigns to a snapshot. */
+export const SESSION_PHASES = Object.freeze([
+  'new',
+  'generate_requested',
+  'variants_ready',
+  'carbonize_required',
+  'carbonize_cleanup_requested',
+  'manual_edit_apply_requested',
+  'steer_requested',
+  'steer_done',
+  'accept_requested',
+  'discard_requested',
+  'discarded',
+  'completed',
+  'agent_error',
+]);
+
+/** Phases that retire a session from the active list. */
+export const COMPLETED_SESSION_PHASES = Object.freeze(['completed', 'discarded']);
+
+/**
+ * Phases after which a late generation write is a ghost from a canceled cycle.
+ * The store journals such an event as a diagnostic instead of applying it.
+ */
+export const GENERATION_FENCED_SESSION_PHASES = Object.freeze([
+  'accept_requested',
+  'discard_requested',
+  'carbonize_required',
+  'completed',
+  'discarded',
+]);
+
+/**
+ * `reason` values carried on checkpoint events. Not validated (an unknown
+ * reason is journaled, never rejected) because the reason is diagnostic
+ * breadcrumb, not control flow. Two exceptions drive behavior and are split
+ * out below.
+ */
+export const CHECKPOINT_REASONS = Object.freeze([
+  'generate_started',
+  'variants_progress',
+  'variants_ready',
+  'browser_resumed',
+  'browser_resumed_svelte_component',
+  'param_changed',
+  'variant_anchor_missing',
+  'component_preview_anchor_missing',
+  'steer_input_focused',
+  'steer_submitted',
+  'steer_send_failed',
+  'steer_done',
+  'steer_error',
+]);
+
+/** Checkpoint reasons the server reads as variant-publication progress. */
+export const VARIANT_PROGRESS_CHECKPOINT_REASONS = Object.freeze([
+  'variants_progress',
+  'variants_ready',
+]);