quiver-cli 0.8.0 → 1.0.0

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

@@ -26,6 +26,7 @@ import {
   scaffoldSvelteComponentInsertSession,
   shouldUseSvelteComponentInjection,
 } from './live/svelte-component.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 const INSERT_POSITIONS = new Set(['before', 'after']);
 
@@ -131,6 +132,9 @@ Output (JSON):
   const query = argVal(args, '--query');
   const filePath = argVal(args, '--file');
   const text = argVal(args, '--text');
+  // See live-wrap.mjs: preflight computes the scaffold but leaves source
+  // untouched so the agent's single edit is the only framework reload.
+  const deferSourceWrite = args.includes('--defer-source-write');
 
   if (!id) { console.error('Missing --id'); process.exit(1); }
   if (!position) { console.error('Missing --position (before | after)'); process.exit(1); }
@@ -244,12 +248,23 @@ Output (JSON):
     isJsx,
   });
 
-  const newLines = [
-    ...lines.slice(0, spliceIndex),
-    ...wrapperLines,
-    ...lines.slice(spliceIndex),
-  ];
-  fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  let deferredWrapper = null;
+  if (deferSourceWrite) {
+    // Insert-as-empty-range: the agent inserts `wrapperBlock` (variants spliced
+    // at the marker) at spliceIndex without removing any source line.
+    deferredWrapper = {
+      block: wrapperLines.join('\n'),
+      replaceStartLine: spliceIndex + 1,
+      replaceEndLine: spliceIndex, // empty range (endLine < startLine) => insertion
+    };
+  } else {
+    const newLines = [
+      ...lines.slice(0, spliceIndex),
+      ...wrapperLines,
+      ...lines.slice(spliceIndex),
+    ];
+    fs.writeFileSync(targetFile, newLines.join('\n'), 'utf-8');
+  }
 
   const insertLine = spliceIndex + 3;
 
@@ -257,6 +272,10 @@ Output (JSON):
     mode: 'insert',
     position,
     file: relTargetFile,
+    sourceWritten: deferredWrapper ? false : undefined,
+    wrapperBlock: deferredWrapper ? deferredWrapper.block : undefined,
+    replaceStartLine: deferredWrapper ? deferredWrapper.replaceStartLine : undefined,
+    replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     insertLine: insertLine + 1,
     commentSyntax,
     styleMode: styleMode.mode,
@@ -268,5 +287,6 @@ Output (JSON):
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-insert.mjs') || _running?.endsWith('live-insert.mjs/')) {
+  enterLiveRoot();
   insertCli();
 }

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

@@ -14,7 +14,12 @@ import { isGeneratedFile } from './lib/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 TEXT_EXTENSIONS = new Set([
+  '.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro', '.js', '.mjs', '.ts',
+  // Phoenix keeps `~H"""` markup in .ex alongside standalone .heex/.eex
+  // templates, so copy edits land in all three.
+  '.ex', '.heex', '.eex',
+]);
 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;

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

@@ -14,6 +14,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { completionAckForAcceptResult, completionTypeForAcceptResult } from './live/completion.mjs';
 import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
+import { instructionsForEvent } from './live/instructions.mjs';
 
 // Absolute path to a sibling script in this skill's scripts dir, so runtime
 // error hints print a directly-runnable command instead of a placeholder.
@@ -27,7 +29,7 @@ const scriptCmd = (name) => `node "${path.join(SELF_DIR, name)}"`;
 export const PER_REQUEST_TIMEOUT_MS = 270_000;
 export const DEFAULT_EVENT_LEASE_MS = 600_000;
 
-const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply']);
+const EVENT_TYPES_NEEDING_AGENT_REPLY = new Set(['generate', 'steer', 'manual_edit_apply', 'carbonize_cleanup', 'variant_mount_failed']);
 
 function readServerInfo() {
   const record = readLiveServerInfo(process.cwd());
@@ -38,8 +40,8 @@ function readServerInfo() {
   return record.info;
 }
 
-export function buildPollReplyPayload(token, { id, type, message, file, data }) {
-  return { token, id, type, message, file, data };
+export function buildPollReplyPayload(token, { id, type, message, file, data, sourceEventType }) {
+  return { token, id, type, message, file, data, sourceEventType };
 }
 
 export function manualApplyPollBanner(event = {}) {
@@ -117,8 +119,11 @@ export async function postReply(base, token, reply) {
   });
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
-    const parts = [body.error || res.statusText, body.reason, body.hint].filter(Boolean);
-    throw new Error(parts.join(': '));
+    const failureLines = Array.isArray(body.failures)
+      ? body.failures.map((f) => `  ${f.file}${f.line != null ? `:${f.line}` : ''} ${f.message}`).join('\n')
+      : null;
+    const parts = [body.error || res.statusText, body.reason, body.hint, failureLines, body._instructions].filter(Boolean);
+    throw new Error(parts.join('\n'));
   }
 }
 
@@ -152,7 +157,14 @@ export async function waitForEventAck(base, token, eventId, {
   return false;
 }
 
-export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
+export async function fetchNextEvent(base, token, {
+  totalDeadline,
+  types,
+  resolveTypes,
+  perRequestTimeoutMs = PER_REQUEST_TIMEOUT_MS,
+  leaseMs = DEFAULT_EVENT_LEASE_MS,
+  signal,
+} = {}) {
   while (true) {
     if (totalDeadline && Date.now() >= totalDeadline) {
       return { type: 'timeout' };
@@ -161,8 +173,15 @@ export async function fetchNextEvent(base, token, { totalDeadline } = {}) {
     const remaining = totalDeadline
       ? totalDeadline - Date.now()
       : PER_REQUEST_TIMEOUT_MS;
-    const slice = Math.min(Math.max(remaining, 1000), PER_REQUEST_TIMEOUT_MS);
-    const res = await fetch(`${base}/poll?token=${token}&timeout=${slice}&leaseMs=${DEFAULT_EVENT_LEASE_MS}`);
+    const slice = Math.min(Math.max(remaining, 1000), perRequestTimeoutMs);
+    const query = new URLSearchParams({
+      token,
+      timeout: String(slice),
+      leaseMs: String(leaseMs),
+    });
+    const normalizedTypes = normalizePollTypes(resolveTypes ? await resolveTypes() : types);
+    if (normalizedTypes.length > 0) query.set('types', normalizedTypes.join(','));
+    const res = await fetch(`${base}/poll?${query}`, { signal });
 
     if (res.status === 401) {
       const err = new Error('Authentication failed. The server token may have changed.');
@@ -202,11 +221,17 @@ export async function augmentEventWithAcceptHandling(event, base, token) {
     event._acceptResult = { handled: false, mode: 'error', error: err.message };
   }
 
+  await completeAcceptHandling(event, base, token);
+  return event;
+}
+
+export async function completeAcceptHandling(event, base, token) {
   const completionType = completionTypeForAcceptResult(event.type, event._acceptResult);
   try {
     await postReply(base, token, {
       id: event.id,
       type: completionType,
+      sourceEventType: event.type,
       message: event._acceptResult?.error,
       file: event._acceptResult?.file,
       data: event._acceptResult?.carbonize === true ? { carbonize: true } : undefined,
@@ -217,7 +242,6 @@ export async function augmentEventWithAcceptHandling(event, base, token) {
   if (!event._completionAck) {
     event._completionAck = completionAckForAcceptResult(event.id, completionType, event._acceptResult);
   }
-
   return event;
 }
 
@@ -242,12 +266,19 @@ export function writeCarbonizeBanner(event) {
 }
 
 export function printPollEvent(event) {
+  // Situational plumbing rides with the event itself: `_instructions` is the
+  // authoritative next step, with real ids and paths substituted, so the
+  // reference doc can stay lean and can never drift from script behavior.
+  if (event && typeof event === 'object' && !event._instructions) {
+    const instructions = instructionsForEvent(event, { scriptsPath: SELF_DIR });
+    if (instructions) event._instructions = instructions;
+  }
   console.log(JSON.stringify(event));
 }
 
-export async function runPollOnce(base, token, { totalTimeout = 600_000 } = {}) {
+export async function runPollOnce(base, token, { totalTimeout = 600_000, types, resolveTypes, perRequestTimeoutMs } = {}) {
   const deadline = Date.now() + totalTimeout;
-  const event = await fetchNextEvent(base, token, { totalDeadline: deadline });
+  const event = await fetchNextEvent(base, token, { totalDeadline: deadline, types, resolveTypes, perRequestTimeoutMs });
   await augmentEventWithAcceptHandling(event, base, token);
   writeCarbonizeBanner(event);
   printPollEvent(event);
@@ -258,11 +289,14 @@ export async function runPollStream(base, token, {
   ackTimeoutMs = 600_000,
   ackPollIntervalMs = 400,
   shouldContinue = () => true,
+  types,
+  resolveTypes,
+  perRequestTimeoutMs,
 } = {}) {
   process.stderr.write('[impeccable-poll] stream mode: one JSON object per line on stdout; use --reply while this process stays running\n');
 
   while (shouldContinue()) {
-    const event = await fetchNextEvent(base, token);
+    const event = await fetchNextEvent(base, token, { types, resolveTypes, perRequestTimeoutMs });
     await augmentEventWithAcceptHandling(event, base, token);
     writeCarbonizeBanner(event);
     printPollEvent(event);
@@ -322,14 +356,17 @@ Modes:
 
 Options:
   --timeout=MS        One-shot poll timeout in ms (default: 600000). Ignored in --stream mode
+  --types=A,B         Lease only these event types
   --ack-timeout=MS    Stream mode: max wait for --reply after generate/steer (default: 600000)
   --file PATH         Attach a source file path to the reply (generate/steer flow)
   --data JSON         Attach a JSON result object to the reply (manual_edit_apply flow). Must be valid JSON
   --help              Show this help message
 
 Harness note:
-  Default one-shot mode is the portable contract for Claude Code, Codex, and Cursor.
-  --stream is experimental for harnesses with fast incremental stdout; do not use on Cursor.`);
+  Default one-shot mode is the primary contract, including Codex foreground polling.
+  Claude Code may run it as a background task; Cursor uses a background terminal with exit notification.
+  --stream is retained for harnesses with measured, reliable incremental stdout.
+  Do not use --stream on Cursor.`);
     process.exit(0);
   }
 
@@ -360,25 +397,33 @@ Harness note:
   }
 
   const streamMode = args.includes('--stream');
+  const typesArg = args.find((a) => a.startsWith('--types='));
+  const types = normalizePollTypes(typesArg ? typesArg.slice('--types='.length) : null);
   const ackTimeoutArg = args.find((a) => a.startsWith('--ack-timeout='));
   const ackTimeoutMs = ackTimeoutArg ? parseInt(ackTimeoutArg.split('=')[1], 10) : 600_000;
 
   try {
     if (streamMode) {
-      await runPollStream(base, info.token, { ackTimeoutMs });
+      await runPollStream(base, info.token, { ackTimeoutMs, types });
       return;
     }
 
     const timeoutArg = args.find((a) => a.startsWith('--timeout='));
     const totalTimeout = timeoutArg ? parseInt(timeoutArg.split('=')[1], 10) : 600_000;
-    await runPollOnce(base, info.token, { totalTimeout });
+    await runPollOnce(base, info.token, { totalTimeout, types });
   } catch (err) {
     handlePollError(err);
   }
 }
 
+export function normalizePollTypes(value) {
+  const values = Array.isArray(value) ? value : String(value || '').split(',');
+  return [...new Set(values.map((type) => String(type).trim()).filter(Boolean))];
+}
+
 // Auto-execute when run directly
 const _running = process.argv[1];
 if (_running?.endsWith('live-poll.mjs') || _running?.endsWith('live-poll.mjs/')) {
+  enterLiveRoot();
   pollCli();
 }

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

@@ -4,6 +4,7 @@
  */
 
 import { createLiveSessionStore } from './live/session-store.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 function manualApplyReplyCommand(eventOrId = 'EVENT_ID') {
   const id = typeof eventOrId === 'string' ? eventOrId : eventOrId?.id || 'EVENT_ID';
@@ -49,6 +50,28 @@ function collectManualApplyFiles(batch) {
   return [...new Set(files.filter((file) => typeof file === 'string' && file.length > 0))].sort();
 }
 
+/**
+ * The browser's render truth, folded into a small block the agent reads before
+ * it decides what to do. `arrivedVariants` only says the agent published;
+ * `renderState` says whether any of it reached a screen.
+ */
+export function renderSummary(snapshot = {}) {
+  return {
+    renderState: snapshot.renderState ?? null,
+    mountedVariants: Array.isArray(snapshot.mountedVariants) ? snapshot.mountedVariants : [],
+    mountFailures: Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [],
+  };
+}
+
+export function mountFailureAction(snapshot = {}) {
+  const failures = Array.isArray(snapshot.mountFailures) ? snapshot.mountFailures : [];
+  const latest = failures[failures.length - 1];
+  if (!latest) return null;
+  const where = latest.url ? ` from ${latest.url}` : '';
+  const why = latest.error ? ` (${latest.error})` : '';
+  return `The browser failed to mount variant ${latest.variant}${where}${why}; nothing is on screen. Fix the variant files, then reply with live-poll.mjs --reply ${snapshot?.pendingEvent?.id || snapshot?.id || 'SESSION_ID'} done --file <manifest or source path> for the queued variant_mount_failed event (or republish) so the browser retries.`;
+}
+
 function parseArgs(argv) {
   const out = { id: null };
   for (let i = 0; i < argv.length; i++) {
@@ -75,20 +98,26 @@ export async function resumeCli() {
   }
 
   const pending = snapshot.pendingEvent || null;
-  const nextAction = pending
-    ? pending.type === 'manual_edit_apply'
-      ? manualApplyResumeHint(pending)
-      : `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
-    : snapshot.phase === 'carbonize_required'
-      ? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
-      : snapshot.phase === 'accept_requested'
-        ? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
-        : `Inspect ${snapshot.id}; no pending agent event is currently queued.`;
+  const render = renderSummary(snapshot);
+  // A failed render outranks the generic pending-event hint: the agent needs to
+  // know the user is staring at an error card, not at variants. A leased manual
+  // Apply still outranks both, because abandoning that lease loses user edits.
+  const mountAction = render.renderState === 'failed' ? mountFailureAction(snapshot) : null;
+  const nextAction = pending?.type === 'manual_edit_apply'
+    ? manualApplyResumeHint(pending)
+    : mountAction || (pending
+      ? `Run live-poll.mjs, handle ${pending.type} ${pending.id}, then acknowledge with live-poll.mjs --reply ${pending.id} done.`
+      : snapshot.phase === 'carbonize_required'
+        ? `Finish carbonize cleanup${snapshot.sourceFile ? ` in ${snapshot.sourceFile}` : ''}, then run live-complete.mjs --id ${snapshot.id}.`
+        : snapshot.phase === 'accept_requested'
+          ? `Run live-complete.mjs --id ${snapshot.id} after verifying the accepted variant is written.`
+          : `Inspect ${snapshot.id}; no pending agent event is currently queued.`);
 
-  console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, nextAction }, null, 2));
+  console.log(JSON.stringify({ active: true, snapshot, pendingEvent: pending, render, nextAction }, null, 2));
 }
 
 const _running = process.argv[1];
 if (_running?.endsWith('live-resume.mjs') || _running?.endsWith('live-resume.mjs/')) {
+  enterLiveRoot();
   resumeCli();
 }