@bastani/atomic 0.9.10 → 0.9.11-alpha.10

package/dist/builtin/workflows/skills/impeccable/scripts/lib/surface-briefs.mjs

@@ -0,0 +1,151 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { slugFromTarget } from './target-slug.mjs';
+
+export const SURFACE_BRIEF_VERSION = 1;
+
+export function getSurfaceBriefDir(projectRoot) {
+  return path.join(projectRoot, '.impeccable', 'surfaces');
+}
+
+export function normalizeSurfaceTarget(target, { projectRoot = process.cwd() } = {}) {
+  if (!target || typeof target !== 'string' || !target.trim()) return null;
+  const trimmed = target.trim();
+  if (/^https?:\/\//i.test(trimmed)) {
+    try {
+      const url = new URL(trimmed);
+      url.hash = '';
+      url.search = '';
+      return url.toString().replace(/\/$/, '') || url.origin;
+    } catch {
+      return null;
+    }
+  }
+  if (/^route:/i.test(trimmed)) {
+    const route = trimmed.slice(trimmed.indexOf(':') + 1).trim();
+    if (!route.startsWith('/') || route.includes('..')) return null;
+    const normalizedRoute = route.split(/[?#]/, 1)[0].replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+    return `route:${normalizedRoute}`;
+  }
+  if (trimmed === '/') return 'route:/';
+  if (trimmed.startsWith('/')) {
+    const absolute = path.resolve(trimmed);
+    const relativeToProject = path.relative(projectRoot, absolute);
+    const isProjectFile = relativeToProject && !relativeToProject.startsWith('..') && !path.isAbsolute(relativeToProject);
+    if (!isProjectFile && !fs.existsSync(absolute) && !trimmed.includes('..')) {
+      const normalizedRoute = trimmed.split(/[?#]/, 1)[0].replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
+      return `route:${normalizedRoute}`;
+    }
+  }
+  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(projectRoot, trimmed);
+  const rel = path.relative(projectRoot, abs);
+  if (!rel || rel === '.' || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join('/');
+}
+
+export function surfaceBriefPathForTarget(target, { projectRoot = process.cwd() } = {}) {
+  const normalized = normalizeSurfaceTarget(target, { projectRoot });
+  if (!normalized) return null;
+  const slugInput = normalized.startsWith('route:') ? `route${normalized.slice('route:'.length)}` : normalized;
+  const slug = slugFromTarget(slugInput, { cwd: projectRoot });
+  return slug ? path.join(getSurfaceBriefDir(projectRoot), `${slug}.md`) : null;
+}
+
+export function parseSurfaceBrief(text, filePath = null) {
+  const match = String(text || '').match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  const meta = {};
+  if (match) {
+    for (const line of match[1].split(/\r?\n/)) {
+      const colon = line.indexOf(':');
+      if (colon < 0) continue;
+      const key = line.slice(0, colon).trim();
+      const raw = line.slice(colon + 1).trim();
+      if (!key) continue;
+      if (/^(?:\[|\{|\")/.test(raw) || /^(?:true|false|null|-?\d+(?:\.\d+)?)$/.test(raw)) {
+        try { meta[key] = JSON.parse(raw); continue; } catch { /* keep string */ }
+      }
+      meta[key] = raw.replace(/^['"]|['"]$/g, '');
+    }
+  }
+  const primaryTarget = typeof meta.primary_target === 'string' ? meta.primary_target : null;
+  const relatedTargets = Array.isArray(meta.related_targets)
+    ? meta.related_targets.filter((value) => typeof value === 'string')
+    : [];
+  return {
+    path: filePath,
+    text: String(text || ''),
+    body: match ? String(text || '').slice(match[0].length).trim() : String(text || '').trim(),
+    meta,
+    slug: typeof meta.slug === 'string' ? meta.slug : filePath ? path.basename(filePath, '.md') : null,
+    primaryTarget,
+    relatedTargets,
+    targets: [primaryTarget, ...relatedTargets].filter(Boolean),
+  };
+}
+
+export function listSurfaceBriefs(projectRoot = process.cwd()) {
+  const dir = getSurfaceBriefDir(projectRoot);
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((name) => name.endsWith('.md')).sort();
+  } catch {
+    return [];
+  }
+  return names.flatMap((name) => {
+    const filePath = path.join(dir, name);
+    try {
+      return [parseSurfaceBrief(fs.readFileSync(filePath, 'utf-8'), filePath)];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function resolveSurfaceBrief(projectRoot = process.cwd(), target = null) {
+  const briefs = listSurfaceBriefs(projectRoot);
+  if (!target) {
+    return {
+      brief: briefs.length === 1 ? briefs[0] : null,
+      candidates: briefs,
+      reason: briefs.length === 1 ? 'only-brief' : briefs.length > 1 ? 'ambiguous' : 'none',
+    };
+  }
+
+  const normalized = normalizeSurfaceTarget(target, { projectRoot });
+  if (!normalized) return { brief: null, candidates: briefs, reason: 'invalid-target' };
+  const exactPath = surfaceBriefPathForTarget(normalized, { projectRoot });
+  const exact = briefs.find((brief) => brief.path === exactPath && (!brief.targets.length || brief.targets.includes(normalized)));
+  if (exact) return { brief: exact, candidates: briefs, reason: 'slug' };
+  const mapped = briefs.filter((brief) => brief.targets.includes(normalized));
+  return {
+    brief: mapped.length === 1 ? mapped[0] : null,
+    candidates: mapped.length > 1 ? mapped : briefs,
+    reason: mapped.length === 1 ? 'mapping' : mapped.length > 1 ? 'ambiguous-target' : 'not-found',
+  };
+}
+
+export function writeSurfaceBrief({
+  projectRoot = process.cwd(),
+  primaryTarget,
+  relatedTargets = [],
+  body,
+}) {
+  const normalizedPrimary = normalizeSurfaceTarget(primaryTarget, { projectRoot });
+  if (!normalizedPrimary) throw new Error('surface brief requires a concrete project-relative primary target or URL');
+  const normalizedRelated = [...new Set(relatedTargets
+    .map((target) => normalizeSurfaceTarget(target, { projectRoot }))
+    .filter((target) => target && target !== normalizedPrimary))];
+  const slug = slugFromTarget(normalizedPrimary, { cwd: projectRoot });
+  const filePath = surfaceBriefPathForTarget(normalizedPrimary, { projectRoot });
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const frontmatter = [
+    '---',
+    `version: ${SURFACE_BRIEF_VERSION}`,
+    `slug: ${JSON.stringify(slug)}`,
+    `primary_target: ${JSON.stringify(normalizedPrimary)}`,
+    `related_targets: ${JSON.stringify(normalizedRelated)}`,
+    '---',
+  ].join('\n');
+  fs.writeFileSync(filePath, `${frontmatter}\n\n${String(body || '').trim()}\n`, 'utf-8');
+  return filePath;
+}

package/dist/builtin/workflows/skills/impeccable/scripts/lib/target-slug.mjs

@@ -0,0 +1,33 @@
+import path from 'node:path';
+
+const SLUG_MAX = 50;
+
+/** Derive one clone-stable slug from a concrete file path or URL. */
+export function slugFromTarget(resolved, { cwd = process.cwd() } = {}) {
+  if (!resolved || typeof resolved !== 'string') return null;
+  const trimmed = resolved.trim();
+  if (!trimmed) return null;
+
+  if (/^https?:\/\//i.test(trimmed)) {
+    let url;
+    try { url = new URL(trimmed); } catch { return null; }
+    return kebab(`${url.hostname}${url.pathname}`);
+  }
+
+  const abs = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+  let rel = path.relative(cwd, abs);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) rel = path.basename(abs);
+  if (!rel || rel === '.') return null;
+  return kebab(rel);
+}
+
+export function kebab(value) {
+  const slug = String(value || '')
+    .toLowerCase()
+    .replace(/[/\\.]+/g, '-')
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+  if (!slug) return null;
+  return slug.length <= SLUG_MAX ? slug : slug.slice(slug.length - SLUG_MAX).replace(/^-/, '');
+}

package/dist/builtin/workflows/skills/impeccable/scripts/lib/template-extensions.mjs

@@ -0,0 +1,146 @@
+/**
+ * One owner for "which file extensions hold UI markup".
+ *
+ * Before this module the answer was spelled out separately in hook-lib.mjs
+ * (`detector.extensions` config, issue #316) and in live-wrap.mjs /
+ * live-accept.mjs (a hardcoded `EXTENSIONS` array, duplicated verbatim in both).
+ * The lists drifted: the hook learned configurable server-template extensions
+ * while Live kept its six frontend defaults, so a Phoenix project got design
+ * findings on `.heex` files but `Session markers not found` on Accept (#374).
+ *
+ * Extensions are matched against the END OF THE FILENAME, not `path.extname`,
+ * so double extensions like `.blade.php`, `.html.erb`, and `.html.heex` work.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Built-in markup extensions for Live's wrap/accept source search.
+ *
+ * Elixir's `.ex` is here because Phoenix function components put `~H"""`
+ * templates directly in `lib/**\/*.ex`; `.heex` and `.eex` cover standalone
+ * templates. `.exs` is deliberately absent: those are Elixir *scripts*
+ * (`mix.exs`, `config/*.exs`, tests) and never hold markup, so including them
+ * only gives the wrap query a chance to match build config by accident.
+ */
+export const LIVE_TEMPLATE_EXTENSIONS = Object.freeze([
+  '.html', '.jsx', '.tsx', '.vue', '.svelte', '.astro',
+  '.ex', '.heex', '.eex',
+]);
+
+/**
+ * Normalize `detector.extensions` entries to `{ ext, engine }`.
+ *
+ * Accepts `{ ext, engine }` objects (engine 'html' | 'text', default 'html' —
+ * the common case for server-side templates) or bare strings as shorthand.
+ */
+export function normalizeExtensionEntries(entries) {
+  if (!Array.isArray(entries)) return [];
+  const out = [];
+  for (const entry of entries) {
+    const raw = typeof entry === 'string' ? entry : entry?.ext;
+    if (typeof raw !== 'string') continue;
+    let ext = raw.trim().toLowerCase();
+    if (!ext) continue;
+    if (!ext.startsWith('.')) ext = `.${ext}`;
+    const engine = (!(typeof entry === 'string') && entry?.engine === 'text') ? 'text' : 'html';
+    out.push({ ext, engine });
+  }
+  return out;
+}
+
+export function mergeExtensions(existing, incoming) {
+  const map = new Map();
+  for (const entry of normalizeExtensionEntries(existing)) map.set(entry.ext, entry);
+  for (const entry of normalizeExtensionEntries(incoming)) map.set(entry.ext, entry);
+  return Array.from(map.values());
+}
+
+export function matchConfiguredExtension(filePath, extensions) {
+  if (!Array.isArray(extensions) || extensions.length === 0) return null;
+  const name = path.basename(String(filePath || '')).toLowerCase();
+  if (!name) return null;
+  // The longest matching suffix wins, so `.blade.php` beats a broader `.php`
+  // entry regardless of config order.
+  let best = null;
+  for (const entry of normalizeExtensionEntries(extensions)) {
+    if (name.length > entry.ext.length && name.endsWith(entry.ext)
+      && (!best || entry.ext.length > best.ext.length)) {
+      best = entry;
+    }
+  }
+  return best;
+}
+
+/**
+ * Does this filename end in one of `extensions`?
+ *
+ * Suffix matching rather than `path.extname` equality, so a configured
+ * `.html.erb` matches `show.html.erb` (whose extname is only `.erb`). The
+ * `name.length > ext.length` guard keeps a file literally named `.heex` from
+ * counting as a template.
+ */
+export function matchesTemplateExtension(filePath, extensions) {
+  const name = path.basename(String(filePath || '')).toLowerCase();
+  if (!name) return false;
+  for (const ext of extensions) {
+    if (name.length > ext.length && name.endsWith(ext)) return true;
+  }
+  return false;
+}
+
+/**
+ * Built-in Live extensions plus any the project configured for the detector.
+ *
+ * Reading `detector.extensions` here is the point: a user who taught the design
+ * hook about `.blade.php` should not have to teach Live separately. Config
+ * parsing is intentionally minimal (own the shape, not the whole hook config)
+ * so this module stays importable from the Live CLI without pulling in
+ * hook-lib.mjs.
+ */
+export function resolveLiveTemplateExtensions(cwd = process.cwd()) {
+  const cached = extensionCache.get(cwd);
+  if (cached) return cached;
+  const resolved = readLiveTemplateExtensions(cwd);
+  extensionCache.set(cwd, resolved);
+  return resolved;
+}
+
+// live-wrap calls the resolver once per candidate query per pass (up to eight
+// times in one CLI run), and every call would otherwise re-read and re-parse
+// both config files. Keyed by cwd; a single CLI process never rewrites its own
+// config mid-run.
+const extensionCache = new Map();
+
+/** Test seam: drop the memoized config so a fixture can rewrite config.json. */
+export function clearTemplateExtensionCache() {
+  extensionCache.clear();
+}
+
+function readLiveTemplateExtensions(cwd) {
+  const configured = [];
+  for (const name of ['config.json', 'config.local.json']) {
+    const raw = safeReadJson(path.join(cwd, '.impeccable', name));
+    const detector = raw?.detector;
+    if (detector && typeof detector === 'object' && !Array.isArray(detector)) {
+      configured.push(...normalizeExtensionEntries(detector.extensions));
+    }
+  }
+  const seen = new Set(LIVE_TEMPLATE_EXTENSIONS);
+  const out = [...LIVE_TEMPLATE_EXTENSIONS];
+  for (const { ext } of configured) {
+    if (seen.has(ext)) continue;
+    seen.add(ext);
+    out.push(ext);
+  }
+  return out;
+}
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}

package/dist/builtin/workflows/skills/impeccable/scripts/live/completion.mjs

@@ -1,9 +1,18 @@
+// A preview whose variants live in component modules rather than in the user's
+// source. These leave no markers in the real file, so a failed accept gives the
+// agent nothing to hand-edit and must be reported as a failure rather than
+// reference/live.md's manual-cleanup handoff. Kept as a set: any future
+// component-module preview mode belongs here the day it lands.
+const PREVIEW_MODES_WITHOUT_SOURCE_MARKERS = new Set([
+  'svelte-component',
+]);
+
 export function completionTypeForAcceptResult(eventType, acceptResult) {
   if (eventType === 'discard') return acceptResult?.handled === true ? 'discarded' : 'error';
   if (acceptResult?.handled === true && acceptResult?.carbonize === true) return 'agent_done';
   if (acceptResult?.handled === true) return 'complete';
   if (acceptResult?.mode === 'error') return 'error';
-  if (eventType === 'accept' && acceptResult?.previewMode === 'svelte-component') return 'error';
+  if (eventType === 'accept' && PREVIEW_MODES_WITHOUT_SOURCE_MARKERS.has(acceptResult?.previewMode)) return 'error';
   return 'agent_done';
 }
 

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

@@ -118,6 +118,15 @@ export function validateEvent(msg) {
         return 'checkpoint: paramValues must be an object';
       }
       return null;
+    case 'agent_phase':
+      if (!isValidId(msg.id)) return 'agent_phase: missing or malformed id';
+      if (typeof msg.phase !== 'string' || !/^[a-z][a-z0-9_]{1,63}$/.test(msg.phase)) {
+        return 'agent_phase: missing or malformed phase';
+      }
+      if (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
+        return 'agent_phase: durationMs must be a non-negative number';
+      }
+      return null;
     case 'exit':
       return null;
     case 'prefetch':
@@ -131,6 +140,12 @@ export function validateEvent(msg) {
       if (msg.message.length > 4000) return 'steer: message too long';
       if (msg.pageUrl !== undefined && typeof msg.pageUrl !== 'string') return 'steer: pageUrl must be string';
       return null;
+    case 'carbonize_cleanup':
+      if (!isValidId(msg.id)) return 'carbonize_cleanup: missing or malformed id';
+      if (!isValidId(msg.sessionId)) return 'carbonize_cleanup: missing or malformed sessionId';
+      if (!msg.file || typeof msg.file !== 'string') return 'carbonize_cleanup: missing file';
+      if (!isValidVariantId(String(msg.variantId))) return 'carbonize_cleanup: missing or malformed variantId';
+      return null;
     default:
       return 'Unknown event type: ' + msg.type;
   }

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

@@ -0,0 +1,149 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const PREFLIGHT_TIMEOUT_MS = 15_000;
+
+// Per-target cache of the resolved source file. The wrap search walks the whole
+// project tree and was measured at ~7.6s on a large repo; it re-ran on every
+// generate for the same picked element (re-rolls, param passes). Keyed by the
+// target signature (locator + route), so it invalidates automatically when the
+// element or route changes; a failed resolution evicts its entry (see below).
+const sourceResolutionCache = new Map();
+
+/** Test/lifecycle hook: drop all cached source resolutions. */
+export function clearSourceResolutionCache() {
+  sourceResolutionCache.clear();
+}
+
+function targetSignature(event) {
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  return JSON.stringify({
+    mode: isInsert ? 'insert' : 'replace',
+    position: isInsert ? target.position : null,
+    elementId: target.elementId || null,
+    classes: target.classes || null,
+    tag: target.tag || null,
+    pageUrl: event.pageUrl || null,
+  });
+}
+
+export function buildGenerationPreflight(event, scriptsDir, { cache = null } = {}) {
+  if (!event || event.type !== 'generate' || !event.id) return null;
+
+  const isInsert = event.mode === 'insert';
+  const target = isInsert ? insertTarget(event) : replaceTarget(event);
+  if (!target.elementId && !target.classes) return null;
+
+  const script = path.join(scriptsDir, isInsert ? 'live-insert.mjs' : 'live-wrap.mjs');
+  const args = [script, '--id', event.id, '--count', String(event.count || 3)];
+  // Compute the scaffold but do not write it into source for source-preview
+  // targets. The agent writes wrapper + variants atomically; a premature
+  // server-side write reloads the framework and strands the browser at 0/N.
+  // No-op on the svelte-component path, which never writes the route source.
+  args.push('--defer-source-write');
+  if (isInsert) args.push('--position', target.position);
+  if (target.elementId) args.push('--element-id', target.elementId);
+  if (target.classes) args.push('--classes', target.classes);
+  if (target.tag) args.push('--tag', target.tag);
+  if (target.text) args.push('--text', target.text);
+  if (!isInsert && event.pageUrl) args.push('--page-url', event.pageUrl);
+  const signature = targetSignature(event);
+  // A cached resolution points the helper straight at the file, skipping the
+  // tree search. The helper still reads current content, so line ranges stay
+  // fresh; only discovery is cached.
+  const cachedFile = cache ? cache.get(signature) : null;
+  if (cachedFile) args.push('--file', cachedFile);
+  return { script, args, mode: isInsert ? 'insert' : 'replace', signature };
+}
+
+/**
+ * Scaffold the source for a generate event before handing it to an agent.
+ *
+ * Async on purpose. This spawns `live-wrap.mjs`, which walks the project's
+ * source tree and can take seconds (measured at ~7.6s on a large repo when the
+ * element is not found, with a 15s ceiling). The live server is single-threaded
+ * and calls this while leasing a poll, so a synchronous spawn froze the whole
+ * server for that entire window: Accept and Discard POSTs, SSE progress
+ * broadcasts, and every other poll stalled behind it.
+ */
+export async function runGenerationPreflight(event, {
+  cwd = process.cwd(),
+  scriptsDir,
+  execFileImpl = execFileAsync,
+  timeoutMs = PREFLIGHT_TIMEOUT_MS,
+  cache = sourceResolutionCache,
+} = {}) {
+  const command = buildGenerationPreflight(event, scriptsDir, { cache });
+  if (!command) {
+    return { ok: false, skipped: true, reason: 'insufficient_locator' };
+  }
+
+  const startedAt = performance.now();
+  try {
+    const { stdout } = await execFileImpl(process.execPath, command.args, {
+      cwd,
+      encoding: 'utf-8',
+      timeout: timeoutMs,
+    });
+    const line = String(stdout).trim().split('\n').filter(Boolean).pop();
+    if (!line) throw new Error('preflight returned no scaffold metadata');
+    const scaffold = JSON.parse(line);
+    // Cache the resolved SOURCE file (route source, not the svelte manifest) so
+    // the next generate on this target skips the tree search.
+    const resolvedSource = scaffold.sourceFile || scaffold.file;
+    if (cache && command.signature && typeof resolvedSource === 'string') {
+      cache.set(command.signature, resolvedSource);
+    }
+    return {
+      ok: true,
+      mode: command.mode,
+      durationMs: performance.now() - startedAt,
+      scaffold,
+    };
+  } catch (error) {
+    // Evict a stale/failed resolution so the next attempt does a full search
+    // (the element may have moved out of the previously cached file).
+    if (cache && command.signature) cache.delete(command.signature);
+    return {
+      ok: false,
+      mode: command.mode,
+      durationMs: performance.now() - startedAt,
+      error: compactError(error),
+    };
+  }
+}
+
+function replaceTarget(event) {
+  return normalizeTarget(event.element || {});
+}
+
+function insertTarget(event) {
+  return {
+    ...normalizeTarget(event.insert?.anchor || {}),
+    position: event.insert?.position === 'before' ? 'before' : 'after',
+  };
+}
+
+function normalizeTarget(target) {
+  const classes = Array.isArray(target.classes)
+    ? target.classes.join(' ')
+    : String(target.classes || '').trim();
+  const text = typeof target.textContent === 'string'
+    ? target.textContent.trim().slice(0, 80)
+    : '';
+  return {
+    elementId: target.id || target.elementId || undefined,
+    classes: classes || undefined,
+    tag: target.tagName || target.tag || undefined,
+    text: text || undefined,
+  };
+}
+
+function compactError(error) {
+  const stderr = error?.stderr ? String(error.stderr).trim() : '';
+  const message = stderr.split('\n').filter(Boolean).pop() || error?.message || 'preflight failed';
+  return String(message).slice(0, 500);
+}

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

@@ -0,0 +1,14 @@
+export function eventPriority(event = {}) {
+  if (event.type === 'accept' || event.type === 'discard' || event.type === 'exit') return 0;
+  if (event.type === 'manual_edit_apply' || event.type === 'steer' || event.type === 'carbonize_cleanup') return 1;
+  if (event.type === 'generate') return 2;
+  return 3;
+}
+
+export function selectAvailablePendingEvent(entries, { now = Date.now(), types = null } = {}) {
+  const allowed = types instanceof Set ? types : (Array.isArray(types) ? new Set(types) : null);
+  return entries
+    .filter((entry) => !(entry.leaseUntil && entry.leaseUntil > now))
+    .filter((entry) => !allowed || allowed.has(entry.event?.type))
+    .sort((a, b) => eventPriority(a.event) - eventPriority(b.event) || a.seq - b.seq)[0] || null;
+}