@bastani/atomic 0.9.13 → 0.9.14-alpha.2

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

@@ -17,11 +17,13 @@ import { isGeneratedFile } from './lib/is-generated.mjs';
 import { resolveLiveTemplateExtensions } from './lib/template-extensions.mjs';
 import { readBuffer as readManualEditsBuffer } from './live/manual-edits-buffer.mjs';
 import { findSourceFile } from './live/source-search.mjs';
+import { resolveSourceTraits } from './live/frameworks/index.mjs';
 import {
   buildSvelteComponentCssAuthoring,
   scaffoldSvelteComponentSession,
   shouldUseSvelteComponentInjection,
 } from './live/svelte-component.mjs';
+import { enterLiveRoot } from './live/roots.mjs';
 
 export async function wrapCli() {
   const args = process.argv.slice(2);
@@ -293,8 +295,10 @@ The agent should insert variant HTML at insertLine.`);
     .join('\n');
   const originalIndented = reindentOriginal('    ');
   const relTargetFile = path.relative(process.cwd(), targetFile).split(path.sep).join('/');
-  const useSvelteComponent = shouldUseSvelteComponentInjection(targetFile);
-  const useFrameworkComponent = useSvelteComponent;
+  // The registry says which files get component preview; the svelte-component
+  // module keeps the env escape hatch that turns it off.
+  const useSvelteComponent = resolveSourceTraits(targetFile).preview === 'component'
+    && shouldUseSvelteComponentInjection(targetFile);
 
   // Wrapper attributes differ by syntax. HTML allows plain string attrs;
   // JSX requires object-literal style and parses string attrs as HTML (which
@@ -343,12 +347,18 @@ The agent should insert variant HTML at insertLine.`);
   let svelteSession = null;
   let deferredWrapper = null;
 
+  let sveltePreviewFallback = null;
   if (useSvelteComponent) {
     // Svelte/SvelteKit resets component-local state on markup HMR updates.
     // Keep generation source-neutral: agents write real variant components
     // under the generated componentDir, the browser mounts them into the live
     // DOM, and live-accept.mjs inlines the accepted variant back into the route.
-    svelteSession = scaffoldSvelteComponentSession({
+    //
+    // The scaffold is AST-based and refuses markup a detached preview cannot
+    // support (component tags, bind:/use:, await blocks, bound nested each).
+    // Refusal falls back to the plain source-preview wrapper below: an
+    // HMR-resetting but CORRECT preview beats a detached wrong one.
+    const scaffolded = scaffoldSvelteComponentSession({
       id,
       count,
       sourceFile: relTargetFile,
@@ -357,10 +367,18 @@ The agent should insert variant HTML at insertLine.`);
       originalLines,
       cwd: process.cwd(),
     });
-    outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
-    outputStartLine = 1;
-    outputEndLine = 1;
-    insertLine = 1;
+    if (scaffolded && scaffolded.fallback === 'source-preview') {
+      sveltePreviewFallback = scaffolded.reason || 'unsupported markup';
+    } else {
+      svelteSession = scaffolded;
+      outputFile = path.resolve(process.cwd(), svelteSession.manifestFile);
+      outputStartLine = 1;
+      outputEndLine = 1;
+      insertLine = 1;
+    }
+  }
+  if (svelteSession) {
+    // component preview: outputs already set above
   } else if (deferSourceWrite) {
     // Deferred source write: compute the scaffold text but leave source
     // untouched. The agent replaces the picked element's source range with
@@ -396,15 +414,19 @@ The agent should insert variant HTML at insertLine.`);
 
   const outputRelFile = path.relative(process.cwd(), outputFile).split(path.sep).join('/');
 
-  const svelteComponentAuthoring = useSvelteComponent ? buildSvelteComponentCssAuthoring(count) : null;
+  const componentPreviewActive = !!svelteSession;
+  const svelteComponentAuthoring = componentPreviewActive ? buildSvelteComponentCssAuthoring(count) : null;
   const componentSession = svelteSession;
-  const componentPreviewMode = useSvelteComponent ? 'svelte-component' : undefined;
+  const componentPreviewMode = componentPreviewActive ? 'svelte-component' : undefined;
   const previewMode = componentPreviewMode;
 
   console.log(JSON.stringify({
     file: outputRelFile,
-    sourceFile: useFrameworkComponent ? relTargetFile : undefined,
+    sourceFile: componentPreviewActive ? relTargetFile : undefined,
     previewMode,
+    previewFallback: sveltePreviewFallback
+      ? { from: 'svelte-component', reason: sveltePreviewFallback }
+      : undefined,
     // Deferred source write: the wrapper is NOT yet in source. The agent
     // replaces [replaceStartLine, replaceEndLine] with `wrapperBlock` (variants
     // spliced at the "insert below this line" marker) in one atomic edit.
@@ -414,8 +436,9 @@ The agent should insert variant HTML at insertLine.`);
     replaceEndLine: deferredWrapper ? deferredWrapper.replaceEndLine : undefined,
     componentDir: componentSession?.componentDir,
     propContract: componentSession?.propContract,
-    sourceStartLine: useFrameworkComponent ? startLine + 1 : undefined,
-    sourceEndLine: useFrameworkComponent ? endLine + 1 : undefined,
+    componentStubMarkup: componentSession?.stubMarkup,
+    sourceStartLine: componentPreviewActive ? startLine + 1 : undefined,
+    sourceEndLine: componentPreviewActive ? endLine + 1 : undefined,
     startLine: outputStartLine,       // 1-indexed for the agent
     // wrapperLines is an array but one element (the original-content slot)
     // is a `\n`-joined multi-line string, so the actual file-row count is
@@ -426,8 +449,8 @@ The agent should insert variant HTML at insertLine.`);
     insertLine,            // 1-indexed: where variants go
     commentSyntax: commentSyntax,
     styleMode: componentPreviewMode || styleMode.mode,
-    styleTag: useFrameworkComponent ? null : styleMode.styleTag,
-    cssSelectorPrefixExamples: useFrameworkComponent ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
+    styleTag: componentPreviewActive ? null : styleMode.styleTag,
+    cssSelectorPrefixExamples: componentPreviewActive ? [] : buildCssSelectorPrefixExamples(styleMode.mode, count),
     cssAuthoring: svelteComponentAuthoring || buildCssAuthoring(styleMode, count),
     originalLineCount: originalLines.length,
   }));
@@ -630,27 +653,22 @@ function attrEscapeDouble(str) {
     .replace(/>/g, '>');
 }
 
+/**
+ * Comment syntax, style mode, and preview strategy all come from the framework
+ * registry, keyed on the target file's extension: `.jsx`/`.tsx` author JSX
+ * comments, `.astro` needs global-prefixed preview CSS because Astro scopes
+ * component styles away from the generated wrappers, `.svelte` gets component
+ * preview. See live/frameworks/index.mjs for why extension and not project.
+ */
 function detectCommentSyntax(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === '.jsx' || ext === '.tsx') {
-    return { open: '{/*', close: '*/}' };
-  }
-  // HTML, Vue, Svelte, Astro all use HTML comments
-  return { open: '<!--', close: '-->' };
+  return resolveSourceTraits(filePath).commentSyntax === 'jsx'
+    ? { open: '{/*', close: '*/}' }
+    : { open: '<!--', close: '-->' };
 }
 
 function detectStyleMode(filePath) {
-  const ext = path.extname(filePath).toLowerCase();
-  if (ext === '.astro') {
-    return {
-      mode: 'astro-global-prefixed',
-      styleTag: '<style is:inline data-impeccable-css="SESSION_ID">',
-    };
-  }
-  return {
-    mode: 'scoped',
-    styleTag: '<style data-impeccable-css="SESSION_ID">',
-  };
+  const traits = resolveSourceTraits(filePath);
+  return { mode: traits.styleMode, styleTag: traits.styleTag };
 }
 
 function buildCssSelectorPrefixExamples(styleMode, count) {
@@ -890,6 +908,7 @@ function findClosingLine(lines, start) {
 // Auto-execute when run directly (node live-wrap.mjs ...)
 const _running = process.argv[1];
 if (_running?.endsWith('live-wrap.mjs') || _running?.endsWith('live-wrap.mjs/')) {
+  enterLiveRoot();
   wrapCli();
 }
 

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

@@ -17,14 +17,17 @@
  *   node live.mjs --help
  */
 
-import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { loadContext, resolveTargetSelection } from './context.mjs';
+import { resolveTargetSelection } from './context.mjs';
 import { resolveFiles } from './live-inject.mjs';
 import { readLiveServerInfo } from './lib/impeccable-paths.mjs';
+import { resolveSurfaceBrief } from './lib/surface-briefs.mjs';
 import { resolveLiveTarget } from './live-target.mjs';
+import { bootInstructions } from './live/instructions.mjs';
+import { resolveRoots, writeRootsManifest } from './live/roots.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -60,6 +63,8 @@ The agent should then:
     process.exit(0);
   }
 
+  // Legacy workspace-monorepo selection first: it carries richer candidate
+  // metadata (context inheritance status) than the roots scan.
   const targetSelection = resolveTargetSelection(liveTarget.originalCwd, liveTarget.targetOptions);
   if (targetSelection) {
     console.log(JSON.stringify({
@@ -71,11 +76,31 @@ The agent should then:
     process.exit(0);
   }
 
-  const ctx = loadContext(liveTarget.originalCwd, liveTarget.targetOptions);
-  const activeCwd = ctx.projectRoot;
+  const rootsResult = resolveRoots({
+    cwd: liveTarget.originalCwd,
+    targetPath: liveTarget.absoluteTargetPath,
+  });
+  if (rootsResult.selection) {
+    console.log(JSON.stringify({
+      ok: false,
+      error: 'target_selection_required',
+      targetCandidates: rootsResult.selection.candidates,
+      hint: 'Several apps with a dev-server config exist. Ask the user which one to use, then rerun with --target <path into that app>.',
+    }, null, 2));
+    process.exit(0);
+  }
+  const roots = rootsResult.manifest;
+  const activeCwd = roots.appRoot;
   const outputTargetPath = liveTarget.targetPath || null;
 
-  const missingContext = missingLiveContext(ctx);
+  // Gate on readable CONTENT, not path existence, so an empty or unreadable
+  // PRODUCT.md routes to init instead of passing the gate and then reporting
+  // hasProduct: false in the same payload.
+  const product = safeRead(roots.productPath);
+  const design = safeRead(roots.designPath);
+  const missingContext = [];
+  if (!product) missingContext.push('PRODUCT.md');
+  if (!design) missingContext.push('DESIGN.md');
   if (missingContext.length > 0) {
     console.log(JSON.stringify({
       ok: false,
@@ -83,14 +108,18 @@ The agent should then:
       missing: missingContext,
       nextCommand: missingContext.includes('PRODUCT.md') ? 'init' : 'document',
       targetPath: outputTargetPath,
-      projectRoot: ctx.projectRoot,
-      repoRoot: ctx.repoRoot,
-      productPath: ctx.productPath,
-      designPath: ctx.designPath,
+      projectRoot: roots.appRoot,
+      repoRoot: roots.repoRoot,
+      productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
+      designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
     }, null, 2));
     process.exit(0);
   }
 
+  // Persist the decision before anything else spawns, so every helper the
+  // agent runs later (from any cwd inside the repo) lands on the same roots.
+  writeRootsManifest(roots);
+
   // 1. Check config (fail fast if missing — no point starting anything else)
   const checkOut = runScript('live-inject.mjs', ['--check'], { cwd: activeCwd });
   const checkResult = safeParse(checkOut);
@@ -98,8 +127,8 @@ The agent should then:
     console.log(JSON.stringify({
       ...(checkResult || { ok: false, error: 'check_failed', raw: checkOut }),
       targetPath: outputTargetPath,
-      projectRoot: ctx.projectRoot,
-      repoRoot: ctx.repoRoot,
+      projectRoot: roots.appRoot,
+      repoRoot: roots.repoRoot,
     }));
     process.exit(0);
   }
@@ -134,7 +163,28 @@ The agent should then:
   const resolvedFiles = resolveFiles(activeCwd, checkResult.config);
   const drift = scanForDrift(activeCwd, resolvedFiles, checkResult.config);
 
-  // 5. Emit everything the agent needs
+  // 5. Emit everything the agent needs. The surface brief rides along so the
+  //    agent does not spend three more tool calls (and a --help miss) on
+  //    surface-brief.mjs before the first poll.
+  let surfaceBrief = null;
+  let surfaceBriefPath = null;
+  try {
+    // Briefs live under .impeccable/surfaces, which in a nested-app repo sits
+    // at the CONTEXT or repo root, not the app root; context.mjs already finds
+    // them there, and live must not report "no brief" for the same project.
+    const briefRoots = [roots.appRoot, roots.contextRoot, roots.repoRoot]
+      .filter(Boolean)
+      .filter((dir, i, arr) => arr.findIndex((other) => path.resolve(other) === path.resolve(dir)) === i);
+    for (const briefRoot of briefRoots) {
+      const resolvedBrief = resolveSurfaceBrief(briefRoot, liveTarget.absoluteTargetPath || null);
+      if (!resolvedBrief?.brief) continue;
+      surfaceBrief = resolvedBrief.brief.text ?? safeRead(resolvedBrief.brief.path);
+      surfaceBriefPath = resolvedBrief.brief.path
+        ? path.relative(liveTarget.originalCwd, resolvedBrief.brief.path)
+        : null;
+      break;
+    }
+  } catch { /* briefs are optional context */ }
   console.log(JSON.stringify({
     ok: true,
     serverPort: serverInfo.port,
@@ -143,22 +193,29 @@ The agent should then:
     liveConfigPath: checkResult.path,
     configDrift: drift,
     targetPath: outputTargetPath,
-    projectRoot: ctx.projectRoot,
-    repoRoot: ctx.repoRoot,
-    hasProduct: ctx.hasProduct,
-    product: ctx.product,
-    productPath: ctx.productPath,
-    hasDesign: ctx.hasDesign,
-    design: ctx.design,
-    designPath: ctx.designPath,
+    projectRoot: roots.appRoot,
+    repoRoot: roots.repoRoot,
+    roots,
+    hasProduct: !!product,
+    product,
+    productPath: relOrNull(liveTarget.originalCwd, roots.productPath),
+    hasDesign: !!design,
+    design,
+    designPath: relOrNull(liveTarget.originalCwd, roots.designPath),
+    hasSurfaceBrief: !!surfaceBrief,
+    surfaceBrief,
+    surfaceBriefPath,
+    _instructions: bootInstructions({ scriptsPath: __dirname }),
   }, null, 2));
 }
 
-function missingLiveContext(ctx) {
-  const missing = [];
-  if (!ctx.hasProduct) missing.push('PRODUCT.md');
-  if (!ctx.hasDesign) missing.push('DESIGN.md');
-  return missing;
+function safeRead(p) {
+  if (!p) return null;
+  try { return fs.readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+function relOrNull(base, p) {
+  return p ? path.relative(base, p) : null;
 }
 
 /**
@@ -259,11 +316,17 @@ function globToRegex(pattern) {
 
 function runScript(name, args, options = {}) {
   const scriptPath = path.join(__dirname, name);
-  const cmd = `node "${scriptPath}" ${args.map(a => `"${a}"`).join(' ')}`;
   try {
-    return execSync(cmd, { encoding: 'utf-8', cwd: options.cwd || process.cwd(), timeout: 15_000 });
+    // argv form, never a shell: string interpolation into double quotes would
+    // let a `"` or `$(...)` in any future caller's arg escape into the shell
+    // (issue #476).
+    return execFileSync(process.execPath, [scriptPath, ...args], {
+      encoding: 'utf-8',
+      cwd: options.cwd || process.cwd(),
+      timeout: 15_000,
+    });
   } catch (err) {
-    // execSync throws on non-zero exit; return stdout if any
+    // execFileSync throws on non-zero exit; return stdout if any
     return err.stdout || err.message || '';
   }
 }

package/dist/builtin/workflows/skills/impeccable/scripts/pin.mjs

@@ -21,7 +21,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // All known harness directories
 const HARNESS_DIRS = [
-  '.claude', '.gemini', '.codex', '.agents', '.github', '.grok',
+  '.claude', '.gemini', '.codex', '.agents', '.agent', '.github', '.grok',
+  '.hermes',
   '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev', '.vibe', '.qoder',
 ];
 
@@ -93,15 +94,17 @@ function commandPrefixForSkillsDir(skillsDir) {
   return CODEX_HARNESSES.has(basename(dirname(skillsDir))) ? '$' : '/';
 }
 
-function generatePinnedSkill(command, metadata, commandPrefix) {
+function generatePinnedSkill(command, metadata, commandPrefix, isCodex) {
   const desc = metadata[command]?.description || `Shortcut for ${commandPrefix}impeccable ${command}.`;
   const hint = metadata[command]?.argumentHint || '[target]';
+  const providerFrontmatter = isCodex
+    ? `metadata:\n  argument-hint: "${hint}"`
+    : `argument-hint: "${hint}"\nuser-invocable: true`;
 
   return `---
 name: ${command}
 description: "${desc}"
-argument-hint: "${hint}"
-user-invocable: true
+${providerFrontmatter}
 ---
 
 ${PIN_MARKER}
@@ -128,7 +131,7 @@ function pin(command, projectRoot) {
 
   for (const skillsDir of harnessDirs) {
     const commandPrefix = commandPrefixForSkillsDir(skillsDir);
-    const content = generatePinnedSkill(command, metadata, commandPrefix);
+    const content = generatePinnedSkill(command, metadata, commandPrefix, commandPrefix === '$');
     // Check if skill already exists (and isn't a pin)
     const skillDir = join(skillsDir, command);
     if (existsSync(skillDir)) {