@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/skills/impeccable/scripts/live/browser-script-parts.mjs

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { LIVE_CHROME_MOUNT_CONTRACT, LIVE_UI_SURFACES } from './ui-surfaces.mjs';
+
 export const LIVE_BROWSER_SCRIPT_PARTS = Object.freeze([
   Object.freeze({ name: 'session-state', file: 'live-browser-session.js' }),
   Object.freeze({ name: 'dom-helpers', file: 'live-browser-dom.js' }),
@@ -32,14 +34,39 @@ export function readLiveBrowserScriptParts(parts, readFile = (filePath) => fs.re
   }));
 }
 
-export function assembleLiveBrowserScript({ token, port, vocabulary, commandPrefix = '/', parts }) {
+export function assembleLiveBrowserScript({
+  token,
+  port,
+  vocabulary,
+  commandPrefix = '/',
+  appRoot = null,
+  parts,
+  // Defaulted rather than threaded through live-server.mjs: the browser bundle
+  // must always carry the canonical inventory, and a default makes that true by
+  // construction instead of by every caller remembering to pass it. Overridable
+  // so tests can assemble with a stand-in.
+  uiSurfaces = LIVE_UI_SURFACES,
+  mountContract = LIVE_CHROME_MOUNT_CONTRACT,
+}) {
   const prelude =
     `window.__IMPECCABLE_TOKEN__ = '${token}';\n` +
     `window.__IMPECCABLE_PORT__ = ${port};\n` +
+    // Project identity for browser-side session storage. localStorage is
+    // keyed by ORIGIN, and two projects routinely share a localhost port
+    // across time; saved sessions carry this value so a resume can tell a
+    // foreign project's leftovers from its own.
+    `window.__IMPECCABLE_APP_ROOT__ = ${JSON.stringify(appRoot)};\n` +
     `window.__IMPECCABLE_COMMAND_PREFIX__ = ${JSON.stringify(commandPrefix)};\n` +
     // Canonical command vocabulary (values + labels + icons). live-browser.js
     // builds its action picker from this instead of an inline copy.
-    `window.__IMPECCABLE_VOCAB__ = ${JSON.stringify(vocabulary)};\n`;
+    `window.__IMPECCABLE_VOCAB__ = ${JSON.stringify(vocabulary)};\n` +
+    // Canonical Live chrome inventory from live/ui-surfaces.mjs. live-browser.js
+    // is a classic script and cannot import an ES module at runtime, so the list
+    // is serialized here and read off the global there. Node consumers (this
+    // repo's tests, the impeccable-site Live UI lab) import the module directly,
+    // which is what keeps the two from drifting.
+    `window.__IMPECCABLE_LIVE_UI_SURFACES__ = ${JSON.stringify(uiSurfaces)};\n` +
+    `window.__IMPECCABLE_LIVE_MOUNT_CONTRACT__ = ${JSON.stringify(mountContract)};\n`;
 
   const body = parts.map((part) => {
     const file = part.file || path.basename(part.path || '');

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

@@ -5,17 +5,26 @@
 
 import { canCreateInsert } from './insert-ui.mjs';
 
-// The accepted visual action values come from the canonical vocabulary so the
-// validator, the picker UI, and the marketing demo never drift. Imported (not
-// just re-exported) so it is also in scope for the validators below.
-import { VISUAL_ACTIONS } from './vocabulary.mjs';
-export { VISUAL_ACTIONS };
+// The accepted protocol values come from the canonical vocabulary so the
+// validator, the store, the server, and the picker UI never drift. Imported
+// (not just re-exported) so they are also in scope for the validators below.
+import { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS } from './vocabulary.mjs';
+export { AGENT_PHASES, CLIENT_EVENT_TYPES, VISUAL_ACTIONS };
+
+const AGENT_PHASE_SET = new Set(AGENT_PHASES);
 
 const ID_PATTERN = /^[0-9a-f]{8}$/;
 const VARIANT_ID_PATTERN = /^[0-9]{1,3}$/;
 const INSERT_POSITIONS = new Set(['before', 'after']);
 const FORBIDDEN_MANUAL_EDIT_TEXT_CHARS = ['<', '{', '}', '`'];
 
+// Mount acknowledgements carry a module URL and a raw exception message from
+// the page. Both are attacker-adjacent (any script on the page can POST them
+// with the token it can already read), so they are length-capped before they
+// reach the journal.
+export const MOUNT_URL_MAX_LENGTH = 2000;
+export const MOUNT_ERROR_MAX_LENGTH = 1000;
+
 function isValidId(v) { return typeof v === 'string' && ID_PATTERN.test(v); }
 function isValidVariantId(v) { return typeof v === 'string' && VARIANT_ID_PATTERN.test(v); }
 
@@ -92,6 +101,36 @@ function validateManualEditEvent(msg, label) {
   return null;
 }
 
+function isValidMountVariant(value) {
+  return Number.isInteger(value) && value >= 1 && value <= 999;
+}
+
+/**
+ * Mount acknowledgements are the browser's answer to "did the thing you
+ * published actually render". They are validated strictly because the render
+ * truth in the session snapshot is built from them: a malformed ack that slid
+ * through would report a variant as mounted that never was.
+ */
+function validateMountAck(msg) {
+  if (!isValidId(msg.id)) return 'variant_mounted: missing or malformed id';
+  if (!isValidMountVariant(msg.variant)) return 'variant_mounted: variant must be an integer 1-999';
+  if (msg.url !== undefined) {
+    if (typeof msg.url !== 'string') return 'variant_mounted: url must be string';
+    if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mounted: url too long';
+  }
+  return null;
+}
+
+function validateMountFailure(msg) {
+  if (!isValidId(msg.id)) return 'variant_mount_failed: missing or malformed id';
+  if (!isValidMountVariant(msg.variant)) return 'variant_mount_failed: variant must be an integer 1-999';
+  if (typeof msg.url !== 'string' || !msg.url.trim()) return 'variant_mount_failed: url required';
+  if (msg.url.length > MOUNT_URL_MAX_LENGTH) return 'variant_mount_failed: url too long';
+  if (typeof msg.error !== 'string' || !msg.error.trim()) return 'variant_mount_failed: error required';
+  if (msg.error.length > MOUNT_ERROR_MAX_LENGTH) return 'variant_mount_failed: error too long';
+  return null;
+}
+
 export function validateEvent(msg) {
   if (!msg || typeof msg !== 'object' || !msg.type) return 'Missing or invalid message';
   switch (msg.type) {
@@ -120,13 +159,21 @@ export function validateEvent(msg) {
       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 (typeof msg.phase !== 'string' || !msg.phase) return 'agent_phase: missing phase';
+      // The enum, not a shape pattern. A phase the browser cannot rank is a
+      // phase the progress bar cannot show, so accepting an arbitrary
+      // lowercase word only defers the failure to the UI.
+      if (!AGENT_PHASE_SET.has(msg.phase)) {
+        return 'agent_phase: unknown phase ' + msg.phase + ' (expected one of ' + AGENT_PHASES.join(', ') + ')';
       }
       if (msg.durationMs !== undefined && (!Number.isFinite(msg.durationMs) || msg.durationMs < 0)) {
         return 'agent_phase: durationMs must be a non-negative number';
       }
       return null;
+    case 'variant_mounted':
+      return validateMountAck(msg);
+    case 'variant_mount_failed':
+      return validateMountFailure(msg);
     case 'exit':
       return null;
     case 'prefetch':

package/dist/builtin/workflows/skills/impeccable/scripts/live/frameworks/astro.mjs

@@ -0,0 +1,47 @@
+/**
+ * Astro registry entry.
+ *
+ * Astro takes the generic tag strategy, with two Astro-specific values that
+ * used to sit as inline `endsWith('.astro')` branches in live-inject.mjs and
+ * live-wrap.mjs:
+ *
+ *   injectScriptAttrs  Astro processes <script> tags by default and rewrites
+ *                      src to its own bundled URL; is:inline opts out.
+ *   styleMode          Astro scopes component styles, which strips preview CSS
+ *                      off the generated variant wrappers, so preview rules are
+ *                      authored global and prefixed instead of @scope'd.
+ */
+
+import { findConfigFile, hasAnyDependency, literalConfigFiles } from './detect-utils.mjs';
+
+const ASTRO_CONFIG_RE = /^astro\.config\.(?:js|mjs|cjs|ts|mts|cts)$/;
+
+export function detectAstroProject(cwd = process.cwd(), config = null) {
+  const configFile = findConfigFile(cwd, ASTRO_CONFIG_RE);
+  if (configFile) return { configFile, via: 'config' };
+  if (hasAnyDependency(cwd, ['astro'])) return { configFile: null, via: 'package' };
+  // A tree of .astro entry templates with no astro.config still belongs to
+  // Astro; the configured injection target names it.
+  const entry = literalConfigFiles(cwd, config).find((rel) => rel.endsWith('.astro'));
+  if (entry) return { configFile: null, via: 'config-files', entry };
+  return null;
+}
+
+export const astro = {
+  name: 'astro',
+
+  detect(cwd, config) {
+    return detectAstroProject(cwd, config);
+  },
+
+  inject: { kind: 'tag' },
+
+  source: {
+    extensions: ['.astro'],
+    preview: 'source',
+    styleMode: 'astro-global-prefixed',
+    styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
+    commentSyntax: 'html',
+    injectScriptAttrs: 'is:inline ',
+  },
+};

package/dist/builtin/workflows/skills/impeccable/scripts/live/frameworks/detect-utils.mjs

@@ -0,0 +1,157 @@
+/**
+ * Small read-only probes the framework entries share.
+ *
+ * Every helper here is cheap and failure-tolerant: detection runs on every
+ * inject, against project trees that may be half-installed, so a missing or
+ * malformed file means "not this framework", never a throw.
+ */
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u;
+
+export function assertSafeProjectRelative(value, label = 'project path', { allowGlob = false } = {}) {
+  if (typeof value !== 'string' || value.length === 0 || CONTROL_CHARACTERS.test(value)) {
+    throw new Error(`${label} must be a safe project-relative path`);
+  }
+  if (path.isAbsolute(value) || /^[A-Za-z]:/u.test(value) || value.startsWith('\\')) {
+    throw new Error(`${label} must be project-relative`);
+  }
+  const segments = value.split(/[\\/]+/u);
+  if (segments.includes('..') || (!allowGlob && segments.some((part) => /[*?[]/u.test(part)))) {
+    throw new Error(`${label} must not escape the project root`);
+  }
+  return value.split('\\').join('/');
+}
+
+function insideOrEqual(candidate, root) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+export function resolveProjectPath(cwd, relativePath, { mustExist = false, kind = null } = {}) {
+  const normalized = assertSafeProjectRelative(relativePath);
+  const root = fs.realpathSync(cwd);
+  const absolute = path.resolve(root, normalized);
+  if (!insideOrEqual(absolute, root)) throw new Error('project path escapes the project root');
+  let current = root;
+  for (const segment of path.relative(root, absolute).split(path.sep).filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink()) throw new Error('project path contains a symbolic link');
+    } catch (error) {
+      if (error?.code === 'ENOENT') break;
+      throw error;
+    }
+  }
+  if (fs.existsSync(absolute)) {
+    const real = fs.realpathSync(absolute);
+    if (!insideOrEqual(real, root)) throw new Error('project path resolves outside the project root');
+    const stat = fs.statSync(real);
+    if (kind === 'file' && !stat.isFile()) throw new Error('project path must be a regular file');
+    if (kind === 'directory' && !stat.isDirectory()) throw new Error('project path must be a directory');
+  } else if (mustExist) {
+    throw new Error('project path does not exist');
+  }
+  return absolute;
+}
+
+function ensureProjectDirectory(cwd, relativeDirectory) {
+  const root = fs.realpathSync(cwd);
+  const normalized = relativeDirectory === '.' ? '' : assertSafeProjectRelative(relativeDirectory, 'project directory');
+  let current = root;
+  for (const segment of normalized.split('/').filter(Boolean)) {
+    current = path.join(current, segment);
+    try {
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error('project directory is not a safe directory');
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      fs.mkdirSync(current, { mode: 0o755 });
+    }
+  }
+  return current;
+}
+
+export function writeProjectFileAtomic(cwd, relativePath, contents) {
+  const normalized = assertSafeProjectRelative(relativePath);
+  const absolute = resolveProjectPath(cwd, normalized);
+  ensureProjectDirectory(cwd, path.posix.dirname(normalized));
+  const temporary = `${absolute}.tmp-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+  try {
+    fs.writeFileSync(temporary, contents, { encoding: typeof contents === 'string' ? 'utf-8' : undefined, mode: 0o644, flag: 'wx' });
+    fs.renameSync(temporary, absolute);
+  } catch (error) {
+    try { fs.unlinkSync(temporary); } catch { /* best effort */ }
+    throw error;
+  }
+  return absolute;
+}
+
+/** Merged dependency names from package.json, or an empty object. */
+export function readPackageDeps(cwd) {
+  try {
+    const file = resolveProjectPath(cwd, 'package.json', { mustExist: true, kind: 'file' });
+    const pkg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    return {
+      ...(pkg.dependencies || {}),
+      ...(pkg.devDependencies || {}),
+      ...(pkg.peerDependencies || {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function hasAnyDependency(cwd, names) {
+  const deps = readPackageDeps(cwd);
+  return names.some((name) => Boolean(deps[name]));
+}
+
+/** First top-level file name matching `re`, or null. */
+export function findConfigFile(cwd, re) {
+  try {
+    return fs.readdirSync(cwd, { withFileTypes: true })
+      .find((entry) => entry.isFile() && re.test(entry.name))
+      ?.name ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export function fileExists(cwd, rel) {
+  try {
+    return fs.existsSync(resolveProjectPath(cwd, rel, { kind: 'file' }));
+  } catch {
+    return false;
+  }
+}
+
+export function firstExistingFile(cwd, candidates) {
+  for (const rel of candidates) {
+    if (fileExists(cwd, rel)) return rel;
+  }
+  return null;
+}
+
+/**
+ * Literal (non-glob) entries of `config.files` that exist on disk. Several
+ * detectors read the configured injection target as a signal, which is how the
+ * bare fixtures — a tree of `.astro` files with no astro.config — still resolve
+ * to the framework that authored them.
+ */
+export function literalConfigFiles(cwd, config) {
+  const files = Array.isArray(config?.files) ? config.files : [];
+  const out = [];
+  for (const rel of files) {
+    if (typeof rel !== 'string' || rel.includes('*') || rel.includes('?')) continue;
+    try {
+      const normalized = assertSafeProjectRelative(rel);
+      if (fileExists(cwd, normalized)) out.push(normalized);
+    } catch { /* unsafe configured paths are never framework signals */ }
+  }
+  return out;
+}

package/dist/builtin/workflows/skills/impeccable/scripts/live/frameworks/index.mjs

@@ -0,0 +1,143 @@
+/**
+ * The live-mode framework registry.
+ *
+ * Before this existed, framework knowledge was smeared across live-inject.mjs
+ * (detection order, the Nuxt adapter, the Astro `is:inline` branch), the two
+ * adapter modules, and live-wrap.mjs (which extension gets component preview,
+ * which gets Astro's global-prefixed CSS, which gets JSX comments). Adding or
+ * fixing a framework meant reading all of them.
+ *
+ * One entry per framework now declares everything the live scripts need:
+ *
+ *   name        stable identifier; also the `adapter` value in inject JSON.
+ *   detect      (cwd, config) → falsy when this is not the project, otherwise
+ *               a truthy project descriptor that apply/remove/artifacts read.
+ *               Order in FRAMEWORKS is priority order; first truthy wins.
+ *   inject      { kind: 'adapter', apply, remove, ignorePatterns, artifacts,
+ *               unpatch } for frameworks that server-render their document
+ *               shell, or { kind: 'tag' } for the generic marker-wrapped
+ *               <script src> block.
+ *   source      how live-wrap treats files this framework authors:
+ *               extensions, preview ('source' | 'component'), styleMode,
+ *               styleTag, commentSyntax, injectScriptAttrs. Anything omitted
+ *               falls back to SOURCE_TRAIT_DEFAULTS.
+ *
+ * Two rules hold the thing together:
+ *
+ * 1. **Detection order is injection priority.** SvelteKit → Nuxt → TanStack
+ *    Start → Astro → Next → Vite → static HTML, exactly the order
+ *    live-inject.mjs used to hard-code. static-html always matches, so
+ *    resolveFramework never returns null.
+ * 2. **Source traits resolve by file extension, not by project.** A SvelteKit
+ *    project's injection target is `src/app.html`; a Vite app can contain
+ *    `.astro` partials. live-wrap has always keyed these off the target file,
+ *    and resolveSourceTraits keeps it that way. Several entries may claim the
+ *    same extension (`.tsx` belongs to three); when they do, the values must
+ *    agree, which tests/live-frameworks.test.mjs asserts.
+ */
+
+import path from 'node:path';
+
+import { sveltekit } from './sveltekit.mjs';
+import { nuxt } from './nuxt.mjs';
+import { tanstackStart } from './tanstack-start.mjs';
+import { astro } from './astro.mjs';
+import { nextjs } from './nextjs.mjs';
+import { viteGeneric } from './vite-generic.mjs';
+import { staticHtml } from './static-html.mjs';
+import { TAG_PATCH_MARKERS, unpatchTagFile } from './tag-strategy.mjs';
+
+/** Priority order. Do not reorder without re-reading rule 1 above. */
+export const FRAMEWORKS = Object.freeze([
+  sveltekit,
+  nuxt,
+  tanstackStart,
+  astro,
+  nextjs,
+  viteGeneric,
+  staticHtml,
+]);
+
+export const PREVIEW_MODES = Object.freeze(['source', 'component']);
+export const STYLE_MODES = Object.freeze(['scoped', 'astro-global-prefixed']);
+export const COMMENT_SYNTAXES = Object.freeze(['html', 'jsx']);
+export const INJECT_KINDS = Object.freeze(['adapter', 'tag']);
+
+export const SOURCE_TRAIT_DEFAULTS = Object.freeze({
+  preview: 'source',
+  styleMode: 'scoped',
+  styleTag: '<style data-impeccable-css="SESSION_ID">',
+  commentSyntax: 'html',
+  injectScriptAttrs: '',
+});
+
+/** The patch kind the generic tag strategy records in the journal. */
+export const TAG_PATCH_KIND = 'live-tag';
+
+/**
+ * Undo functions keyed by the `patch` value an artifact carries. Built from
+ * the entries so a new adapter registers its own undo alongside its apply.
+ */
+export const PATCH_UNDOERS = Object.freeze(Object.assign(
+  { [TAG_PATCH_KIND]: unpatchTagFile },
+  ...FRAMEWORKS.map((framework) => framework.inject.unpatch || {}),
+));
+
+/**
+ * First entry whose detect() matches. Returns { framework, project } where
+ * project is the detector's descriptor (adapters read it; tag frameworks
+ * mostly ignore it).
+ */
+export function resolveFramework(cwd = process.cwd(), config = null) {
+  for (const framework of FRAMEWORKS) {
+    const project = framework.detect(cwd, config);
+    if (project) return { framework, project };
+  }
+  // Unreachable while static-html stays terminal, but a caller that reorders
+  // the array should get a diagnosable null rather than a silent tag inject.
+  return null;
+}
+
+/**
+ * Source-authoring traits for one file, merged over SOURCE_TRAIT_DEFAULTS.
+ * `framework` names the entry that claimed the extension, or null.
+ */
+export function resolveSourceTraits(filePath) {
+  const ext = path.extname(String(filePath || '')).toLowerCase();
+  for (const framework of FRAMEWORKS) {
+    const source = framework.source;
+    if (!source || !source.extensions.includes(ext)) continue;
+    const { extensions, ...traits } = source;
+    return { framework: framework.name, ...SOURCE_TRAIT_DEFAULTS, ...traits };
+  }
+  return { framework: null, ...SOURCE_TRAIT_DEFAULTS };
+}
+
+/**
+ * Extra gitignore patterns the resolved framework needs beyond the static
+ * LIVE_IGNORE_PATTERNS list (paths that depend on a detected srcDir or file
+ * extension and so cannot be written down ahead of time).
+ */
+export function frameworkIgnorePatterns(resolved) {
+  const fn = resolved?.framework?.inject?.ignorePatterns;
+  return typeof fn === 'function' ? (fn(resolved.project) || []) : [];
+}
+
+/**
+ * The files this injection will create or patch, in journal-artifact form.
+ * Adapters declare their own; the tag strategy patches exactly the resolved
+ * config files.
+ */
+export function describeInjectArtifacts(resolved, { cwd = process.cwd(), files = [] } = {}) {
+  if (!resolved) return [];
+  const { framework, project } = resolved;
+  if (framework.inject.kind === 'adapter') {
+    return (framework.inject.artifacts?.({ cwd, project }) || []).filter((a) => a && a.path);
+  }
+  return files.map((file) => ({
+    kind: 'patched',
+    path: file,
+    patch: TAG_PATCH_KIND,
+    markers: [...TAG_PATCH_MARKERS],
+  }));
+}