quiver-cli 0.1.0

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

@@ -0,0 +1,272 @@
+/**
+ * CLI helper: find an anchor element in source and splice an insert-variant
+ * wrapper before or after it (no original variant — net-new content).
+ *
+ * Usage:
+ *   node live-insert.mjs --id SESSION_ID --count N --position after \
+ *     --classes "hero" --tag section [--file path]
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGeneratedFile } from './is-generated.mjs';
+import {
+  buildSearchQueries,
+  findElement,
+  findAllElements,
+  filterByText,
+  findFileWithQuery,
+  detectCommentSyntax,
+  detectStyleMode,
+  buildCssAuthoring,
+  buildCssSelectorPrefixExamples,
+} from './live-wrap.mjs';
+import {
+  buildSvelteComponentCssAuthoring,
+  scaffoldSvelteComponentInsertSession,
+  shouldUseSvelteComponentInjection,
+} from './live-svelte-component.mjs';
+
+const INSERT_POSITIONS = new Set(['before', 'after']);
+
+export function isInsertPosition(value) {
+  return INSERT_POSITIONS.has(value);
+}
+
+export function computeInsertLine(startLine, endLine, position) {
+  return position === 'before' ? startLine : endLine + 1;
+}
+
+export function buildInsertWrapperLines({ id, count, indent, commentSyntax, isJsx }) {
+  const styleContents = isJsx ? 'style={{ display: "contents" }}' : 'style="display: contents"';
+  const attrs =
+    'data-impeccable-variants="' + id + '" ' +
+    'data-impeccable-mode="insert" ' +
+    'data-impeccable-variant-count="' + count + '" ' +
+    styleContents;
+
+  if (isJsx) {
+    return [
+      indent + '<div ' + attrs + '>',
+      indent + '  ' + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+      indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+      indent + '  ' + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+      indent + '</div>',
+    ];
+  }
+
+  return [
+    indent + commentSyntax.open + ' impeccable-variants-start ' + id + ' ' + commentSyntax.close,
+    indent + '<div ' + attrs + '>',
+    indent + '  ' + commentSyntax.open + ' Variants: insert below this line ' + commentSyntax.close,
+    indent + '</div>',
+    indent + commentSyntax.open + ' impeccable-variants-end ' + id + ' ' + commentSyntax.close,
+  ];
+}
+
+function argVal(args, flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && idx + 1 < args.length ? args[idx + 1] : null;
+}
+
+function resolveElementMatch({ lines, queries, tag, text }) {
+  if (text) {
+    const candidates = [];
+    for (const q of queries) {
+      const all = findAllElements(lines, q, tag);
+      for (const c of all) {
+        if (!candidates.some((x) => x.startLine === c.startLine)) candidates.push(c);
+      }
+      if (candidates.length === 1) break;
+    }
+    if (candidates.length === 0) return { error: 'element_not_found' };
+    if (candidates.length === 1) return { match: candidates[0] };
+    const filtered = filterByText(candidates, lines, text);
+    if (filtered.length === 1) return { match: filtered[0] };
+    if (filtered.length === 0) return { match: candidates[0] };
+    return { error: 'element_ambiguous', candidates: filtered };
+  }
+
+  for (const q of queries) {
+    const match = findElement(lines, q, tag);
+    if (match) return { match };
+  }
+  return { error: 'element_not_found' };
+}
+
+export async function insertCli() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`Usage: node live-insert.mjs [options]
+
+Find an anchor element in source and splice an insert-variant wrapper.
+
+Required:
+  --id ID            Session ID for the variant wrapper
+  --count N          Number of expected variants (1-8)
+  --position POS     before | after (relative to the anchor element)
+
+Element identification (at least one required):
+  --element-id ID    HTML id attribute of the anchor element
+  --classes A,B,C    Comma-separated CSS class names
+  --tag TAG          Tag name (div, section, etc.)
+  --query TEXT       Fallback: raw text to search for
+
+Optional:
+  --file PATH        Source file to search in (skips auto-detection)
+  --text TEXT        Anchor textContent for disambiguation (~80 chars)
+
+Output (JSON):
+  { mode: "insert", file, position, insertLine, commentSyntax, styleMode, styleTag, cssAuthoring }`);
+    process.exit(0);
+  }
+
+  const id = argVal(args, '--id');
+  const count = parseInt(argVal(args, '--count') || '3', 10);
+  const position = argVal(args, '--position');
+  const elementId = argVal(args, '--element-id');
+  const classes = argVal(args, '--classes');
+  const tag = argVal(args, '--tag');
+  const query = argVal(args, '--query');
+  const filePath = argVal(args, '--file');
+  const text = argVal(args, '--text');
+
+  if (!id) { console.error('Missing --id'); process.exit(1); }
+  if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
+  if (!isInsertPosition(position)) { console.error('Invalid --position: ' + position); process.exit(1); }
+  if (!elementId && !classes && !query) {
+    console.error('Need at least one of: --element-id, --classes, --query');
+    process.exit(1);
+  }
+
+  const queries = buildSearchQueries(elementId, classes, tag, query);
+  const genOpts = { cwd: process.cwd() };
+
+  let targetFile = filePath;
+  if (!targetFile) {
+    for (const q of queries) {
+      targetFile = findFileWithQuery(q, process.cwd(), genOpts);
+      if (targetFile) break;
+    }
+    if (!targetFile) {
+      let generatedHit = null;
+      for (const q of queries) {
+        generatedHit = findFileWithQuery(q, process.cwd(), { ...genOpts, includeGenerated: true });
+        if (generatedHit) break;
+      }
+      console.error(JSON.stringify({
+        error: generatedHit ? 'element_not_in_source' : 'element_not_found',
+        fallback: 'agent-driven',
+        hint: 'See "Handle fallback" in live.md.',
+      }));
+      process.exit(1);
+    }
+  } else if (isGeneratedFile(targetFile, genOpts)) {
+    console.error(JSON.stringify({
+      error: 'file_is_generated',
+      fallback: 'agent-driven',
+      file: path.relative(process.cwd(), path.resolve(process.cwd(), targetFile)),
+    }));
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(targetFile, 'utf-8');
+  const lines = content.split('\n');
+  const resolved = resolveElementMatch({ lines, queries, tag, text });
+
+  if (resolved.error === 'element_ambiguous') {
+    console.error(JSON.stringify({
+      error: 'element_ambiguous',
+      fallback: 'agent-driven',
+      file: path.relative(process.cwd(), targetFile),
+      candidates: resolved.candidates.map((c) => ({
+        startLine: c.startLine + 1,
+        endLine: c.endLine + 1,
+      })),
+    }));
+    process.exit(1);
+  }
+  if (!resolved.match) {
+    console.error(JSON.stringify({ error: 'element_not_found', fallback: 'agent-driven' }));
+    process.exit(1);
+  }
+
+  const { startLine, endLine } = resolved.match;
+  const commentSyntax = detectCommentSyntax(targetFile);
+  const styleMode = detectStyleMode(targetFile);
+  const isJsx = commentSyntax.open === '{/*';
+  const spliceIndex = computeInsertLine(startLine, endLine, position);
+  const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
+
+  if (shouldUseSvelteComponentInjection(targetFile)) {
+    const session = scaffoldSvelteComponentInsertSession({
+      id,
+      count,
+      sourceFile: relTargetFile,
+      insertLine: spliceIndex + 1,
+      position,
+      anchorStartLine: startLine + 1,
+      anchorEndLine: endLine + 1,
+      anchorLines: lines.slice(startLine, endLine + 1),
+      cwd: process.cwd(),
+    });
+    console.log(JSON.stringify({
+      mode: 'insert',
+      position,
+      file: session.manifestFile,
+      sourceFile: relTargetFile,
+      previewMode: 'svelte-component',
+      componentDir: session.componentDir,
+      propContract: session.propContract,
+      insertLine: 1,
+      sourceInsertLine: spliceIndex + 1,
+      anchorStartLine: startLine + 1,
+      anchorEndLine: endLine + 1,
+      commentSyntax,
+      styleMode: 'svelte-component',
+      styleTag: null,
+      cssSelectorPrefixExamples: [],
+      cssAuthoring: buildSvelteComponentCssAuthoring(count),
+    }));
+    return;
+  }
+
+  const indent = lines[spliceIndex]?.match(/^(\s*)/)?.[1]
+    ?? lines[startLine]?.match(/^(\s*)/)?.[1]
+    ?? '';
+
+  const wrapperLines = buildInsertWrapperLines({
+    id,
+    count,
+    indent,
+    commentSyntax,
+    isJsx,
+  });
+
+  const newLines = [
+    ...lines.slice(0, spliceIndex),
+    ...wrapperLines,
+    ...lines.slice(spliceIndex),
+  ];
+  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+
+  const insertLine = spliceIndex + 3;
+
+  console.log(JSON.stringify({
+    mode: 'insert',
+    position,
+    file: relTargetFile,
+    insertLine: insertLine + 1,
+    commentSyntax,
+    styleMode: styleMode.mode,
+    styleTag: styleMode.styleTag,
+    cssSelectorPrefixExamples: buildCssSelectorPrefixExamples(styleMode.mode, count),
+    cssAuthoring: buildCssAuthoring(styleMode, count),
+  }));
+}
+
+const _running = process.argv[1];
+if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
+  insertCli();
+}

package/template/.agents/skills/design/impeccable/scripts/live-manual-edit-evidence.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Collect evidence for pending live copy edits.
+ *
+ * This module intentionally does not edit source files and does not choose a
+ * winner. It gathers staged browser edits, rendered context, framework source
+ * hints, and likely source candidates so the AI copy-edit batch runner can make
+ * source changes with full repo context.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { isGeneratedFile } from './is-generated.mjs';
+import { readBuffer, getBufferPath } from './live-manual-edits-buffer.mjs';
+
+const EVIDENCE_VERSION = 1;
+const TEXT_EXTENSIONS = new Set(['.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro', '.js', '.mjs', '.ts']);
+const SEARCH_DIRS = ['src', 'app', 'pages', 'components', 'public', 'views', 'templates', 'site', 'lib', 'data'];
+const STRONG_LITERAL_MATCH_LIMIT = 8;
+const WEAK_LITERAL_MATCH_LIMIT = 4;
+const OBJECT_KEY_MATCH_LIMIT = 8;
+const LOCATOR_MATCH_LIMIT = 4;
+const CONTEXT_MATCH_LIMIT = 8;
+const CONTEXT_MATCH_PER_HINT = 2;
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  '.impeccable',
+  '.astro',
+  '.next',
+  '.nuxt',
+  '.svelte-kit',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+]);
+
+export function buildManualEditEvidence({ cwd = process.cwd(), pageUrl = null } = {}) {
+  const buffer = readBuffer(cwd);
+  const entries = pageUrl
+    ? buffer.entries.filter((entry) => entry.pageUrl === pageUrl)
+    : buffer.entries;
+  const opCount = countOps(entries);
+
+  if (opCount === 0) {
+    return {
+      pageUrl,
+      count: 0,
+      entries: [],
+      ops: [],
+      candidates: [],
+    };
+  }
+
+  const searchFiles = collectSearchFiles(cwd);
+  const ops = flattenOps(entries);
+  const candidates = ops.map((op) => buildCandidatesForOp(op, cwd, searchFiles));
+  return {
+    version: EVIDENCE_VERSION,
+    pageUrl: pageUrl || null,
+    count: opCount,
+    entries,
+    ops,
+    context: {
+      cwd,
+      bufferPath: path.relative(cwd, getBufferPath(cwd)),
+      totalEntries: entries.length,
+      totalOps: opCount,
+    },
+    candidates,
+  };
+}
+
+function countOps(entries) {
+  let count = 0;
+  for (const entry of entries) count += Array.isArray(entry.ops) ? entry.ops.length : 0;
+  return count;
+}
+
+function flattenOps(entries) {
+  const out = [];
+  for (const entry of entries) {
+    const contextHintsByRef = buildContextHintsByRef(entry);
+    for (const op of entry.ops || []) {
+      out.push({
+        entryId: entry.id,
+        pageUrl: entry.pageUrl,
+        ref: op.ref,
+        contextRef: op.contextRef || null,
+        tag: op.tag,
+        elementId: op.elementId || null,
+        classes: Array.isArray(op.classes) ? op.classes : [],
+        originalText: op.originalText,
+        newText: op.newText,
+        deleted: op.deleted === true,
+        sourceHint: op.sourceHint || null,
+        leaf: op.leaf || null,
+        nearbyEditableTexts: Array.isArray(op.nearbyEditableTexts) ? op.nearbyEditableTexts : [],
+        container: op.container || null,
+        contextHints: contextHintsByRef.get(op.ref) || [],
+      });
+    }
+  }
+  return out;
+}
+
+function buildContextHintsByRef(entry) {
+  const map = new Map();
+  for (const op of entry.ops || []) {
+    const hints = new Set();
+    const add = (value) => {
+      const text = normalizeText(decodeBasicHtml(String(value || '')));
+      if (text.length < 3 || text.length > 160) return;
+      if (text === normalizeText(op.originalText) || text === normalizeText(op.newText)) return;
+      hints.add(text);
+    };
+
+    for (const item of op.nearbyEditableTexts || []) {
+      add(typeof item === 'string' ? item : item?.text);
+    }
+    const outer = typeof entry.element?.outerHTML === 'string' ? entry.element.outerHTML : '';
+    for (const match of outer.matchAll(/data-impeccable-original-text="([^"]*)"/g)) add(match[1]);
+    if (typeof entry.element?.textContent === 'string') {
+      for (const chunk of entry.element.textContent.split(/\s{2,}|\n|\t/)) add(chunk);
+    }
+    map.set(op.ref, [...hints].slice(0, 16));
+  }
+  return map;
+}
+
+function buildCandidatesForOp(op, cwd, searchFiles) {
+  const originalText = String(op.originalText || '');
+  const contextNeedles = op.contextHints || [];
+  return {
+    entryId: op.entryId,
+    ref: op.ref,
+    originalText,
+    sourceHint: analyzeSourceHint(op, cwd),
+    textMatches: originalText ? findLiteralMatches(searchFiles, originalText, { max: literalMatchLimit(originalText) }) : [],
+    objectKeyMatches: originalText ? findObjectKeyMatches(searchFiles, originalText, { max: OBJECT_KEY_MATCH_LIMIT }) : [],
+    locatorMatches: findLocatorMatches(searchFiles, op, { max: LOCATOR_MATCH_LIMIT }),
+    contextTextMatches: findContextMatches(searchFiles, contextNeedles, { maxPerHint: CONTEXT_MATCH_PER_HINT, max: CONTEXT_MATCH_LIMIT }),
+  };
+}
+
+function literalMatchLimit(text) {
+  return isWeakSourceNeedle(text) ? WEAK_LITERAL_MATCH_LIMIT : STRONG_LITERAL_MATCH_LIMIT;
+}
+
+function isWeakSourceNeedle(text) {
+  const normalized = normalizeText(text);
+  return normalized.length < 4 || /^[\d.,+\-%\s]+$/.test(normalized);
+}
+
+function analyzeSourceHint(op, cwd) {
+  const hint = normalizeSourceHint(op.sourceHint);
+  if (!hint.file) return null;
+  const file = path.resolve(cwd, hint.file);
+  const relativeFile = path.relative(cwd, file);
+  if (!isPathInsideOrEqual(cwd, file)) {
+    return { ...hint, status: 'outside_cwd', relativeFile: hint.file };
+  }
+  if (!fs.existsSync(file)) {
+    return { ...hint, status: 'file_missing', relativeFile };
+  }
+  if (isGeneratedFile(file, { cwd })) {
+    return { ...hint, status: 'generated', relativeFile };
+  }
+
+  const content = fs.readFileSync(file, 'utf-8');
+  const lines = content.split('\n');
+  const line = hint.line || 1;
+  const start = Math.max(0, line - 4);
+  const end = Math.min(lines.length, line + 3);
+  const windowText = lines.slice(start, end).join('\n');
+  const containsOriginalText = typeof op.originalText === 'string' && windowText.includes(op.originalText);
+  return {
+    ...hint,
+    status: containsOriginalText ? 'ok' : 'text_not_found_near_hint',
+    relativeFile,
+    excerpt: lines.slice(start, end).map((text, index) => ({
+      line: start + index + 1,
+      text: text.slice(0, 240),
+    })),
+  };
+}
+
+function normalizeSourceHint(hint) {
+  if (!hint || typeof hint !== 'object') return {};
+  let line = Number.isFinite(Number(hint.line)) ? Number(hint.line) : null;
+  let column = Number.isFinite(Number(hint.column)) ? Number(hint.column) : null;
+  if ((!line || !column) && typeof hint.loc === 'string') {
+    const match = hint.loc.match(/^(\d+)(?::(\d+))?/);
+    if (match) {
+      line = Number(match[1]);
+      if (match[2]) column = Number(match[2]);
+    }
+  }
+  return {
+    file: typeof hint.file === 'string' ? hint.file : '',
+    loc: typeof hint.loc === 'string' ? hint.loc : '',
+    line,
+    column,
+  };
+}
+
+function collectSearchFiles(cwd) {
+  const out = [];
+  const seenDirs = new Set();
+  const seenFiles = new Set();
+  for (const dir of SEARCH_DIRS) {
+    scanDir(path.join(cwd, dir), cwd, seenDirs, seenFiles, out, 0);
+  }
+  scanRootFiles(cwd, seenFiles, out);
+  return out;
+}
+
+function scanDir(dir, cwd, seenDirs, seenFiles, out, depth) {
+  if (depth > 7 || !fs.existsSync(dir)) return;
+  let realDir;
+  try { realDir = fs.realpathSync(dir); } catch { return; }
+  if (seenDirs.has(realDir)) return;
+  seenDirs.add(realDir);
+
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      scanDir(fullPath, cwd, seenDirs, seenFiles, out, depth + 1);
+      continue;
+    }
+    if (!entry.isFile() || !TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) continue;
+    maybeAddSearchFile(fullPath, cwd, seenFiles, out);
+  }
+}
+
+function scanRootFiles(cwd, seenFiles, out) {
+  let entries;
+  try { entries = fs.readdirSync(cwd, { withFileTypes: true }); } catch { return; }
+  for (const entry of entries) {
+    if (!entry.isFile() || !TEXT_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) continue;
+    maybeAddSearchFile(path.join(cwd, entry.name), cwd, seenFiles, out);
+  }
+}
+
+function maybeAddSearchFile(file, cwd, seenFiles, out) {
+  let realFile;
+  try { realFile = fs.realpathSync(file); } catch { return; }
+  if (seenFiles.has(realFile)) return;
+  seenFiles.add(realFile);
+  if (isGeneratedFile(file, { cwd })) return;
+  let content;
+  try { content = fs.readFileSync(file, 'utf-8'); } catch { return; }
+  out.push({ file, relativeFile: path.relative(cwd, file), content, lines: content.split('\n') });
+}
+
+function findLiteralMatches(searchFiles, needle, { max }) {
+  return findMatches(searchFiles, needle, { kind: 'text', max });
+}
+
+function findObjectKeyMatches(searchFiles, text, { max }) {
+  const re = new RegExp('(["\\\'`])' + escapeRegExp(text) + '\\1(?=\\s*:)', 'g');
+  const out = [];
+  for (const file of searchFiles) {
+    for (const match of file.content.matchAll(re)) {
+      out.push(matchForIndex(file, match.index, 'object_key', text));
+      if (out.length >= max) return out;
+    }
+  }
+  return out;
+}
+
+function findLocatorMatches(searchFiles, op, { max }) {
+  const needles = [];
+  if (op.elementId) needles.push({ kind: 'id', needle: op.elementId });
+  for (const cls of op.classes || []) {
+    if (cls) needles.push({ kind: 'class', needle: cls });
+  }
+  if (op.tag) needles.push({ kind: 'tag', needle: '<' + op.tag });
+
+  const out = [];
+  const seen = new Set();
+  for (const { kind, needle } of needles) {
+    for (const match of findMatches(searchFiles, needle, { kind, max })) {
+      const key = match.file + ':' + match.line + ':' + kind + ':' + needle;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ ...match, needle });
+      if (out.length >= max) return out;
+    }
+  }
+  return out;
+}
+
+function findContextMatches(searchFiles, hints, { maxPerHint, max }) {
+  const out = [];
+  const seen = new Set();
+  for (const hint of hints || []) {
+    for (const match of findMatches(searchFiles, hint, { kind: 'context', max: maxPerHint })) {
+      const key = match.file + ':' + match.line + ':' + hint;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ ...match, needle: hint });
+      if (out.length >= max) return out;
+    }
+  }
+  return out;
+}
+
+function findMatches(searchFiles, needle, { kind, max }) {
+  const text = String(needle || '');
+  if (!text) return [];
+  const out = [];
+  for (const file of searchFiles) {
+    let index = 0;
+    while (out.length < max) {
+      index = file.content.indexOf(text, index);
+      if (index === -1) break;
+      out.push(matchForIndex(file, index, kind, text));
+      index += Math.max(1, text.length);
+    }
+    if (out.length >= max) break;
+  }
+  return out;
+}
+
+function matchForIndex(file, index, kind, needle) {
+  const line = file.content.slice(0, index).split('\n').length;
+  const lineText = file.lines[line - 1] || '';
+  return {
+    kind,
+    file: file.relativeFile,
+    line,
+    needle,
+    excerpt: lineText.trim().slice(0, 240),
+  };
+}
+
+function isPathInsideOrEqual(cwd, file) {
+  const rel = path.relative(path.resolve(cwd), path.resolve(file));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function normalizeText(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function decodeBasicHtml(value) {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>');
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}