@elytracms/cli 0.0.86 → 0.0.87

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.86",
+  "version": "0.0.87",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "node": ">=22.18.0"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.86"
+    "@elytracms/core": "^0.0.87"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/previews.js

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
+import { CONFIG_FILE, pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
 
 /**
  * `elytra previews` (EC-440) — build-time fixture-preview generation.
@@ -18,14 +18,19 @@ import { pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } fro
  *     the blocks-panel tile);
  *   - a previews manifest to `studio/elytra-previews.json` (importable next to
  *     `studio.config.tsx`) carrying per entry: componentId, fixture, URL, and
- *     an input hash (manifest prop/slot shape + fixture props) — no
- *     timestamps, so unchanged inputs re-serialize to the same bytes.
+ *     an input hash (manifest prop/slot shape + fixture props) — plus ONE
+ *     manifest-level `renderDeps` list (EC-600): a content hash per project
+ *     source file the config imports and per stylesheet in the theme's
+ *     `@import` chain. No timestamps, so unchanged inputs re-serialize to the
+ *     same bytes.
  *
- * Idempotence: an entry whose input hash matches the existing manifest AND
- * whose image file exists is skipped entirely (screenshots are not guaranteed
- * byte-stable, so "skip unchanged" is the mechanism, not re-render-and-
- * compare); the manifest is only written when its bytes change. A re-run with
- * unchanged inputs therefore rewrites nothing.
+ * Idempotence: an entry is skipped entirely when its input hash matches the
+ * existing manifest, its image file exists, AND the render dependencies are
+ * unchanged (screenshots are not guaranteed byte-stable, so "skip unchanged" is
+ * the mechanism, not re-render-and-compare). A changed render dependency
+ * re-renders every entry — nothing can say which pixels it touched. The
+ * manifest is only written when its bytes change. A re-run with unchanged
+ * inputs therefore rewrites nothing.
  *
  * Harness: the shared consumer-Vite boot (`config-harness.js`, EC-495 — one
  * mechanism for this command and `elytra doctor`'s config check) plus a
@@ -57,8 +62,11 @@ export const PREVIEWS_URL_PREFIX = '/elytra-previews/'
  * `2` (EC-502): the entry hash no longer includes the engine version, so v1 hashes
  * are not comparable with v2 ones — a version mismatch is reported as itself
  * ("regenerate"), never as N bogus `stale` entries.
+ * `3` (EC-600): the manifest carries `renderDeps` (see {@link renderDepsOf}); a v2
+ * manifest has none, so its freshness cannot be judged — reported once as
+ * `manifest-version`, and one regeneration renders everything against the deps.
  */
-export const PREVIEWS_MANIFEST_VERSION = 2
+export const PREVIEWS_MANIFEST_VERSION = 3
 
 /** Capture geometry: 1280×800 CSS pixels (a desktop render), shot at 0.5 → 640×400 (16/10). */
 export const CAPTURE = { width: 1280, height: 800, scale: 0.5 }
@@ -109,11 +117,22 @@ function sortValue(value) {
 }
 
 /**
- * The staleness input hash: sha-256 over the stable-serialized render inputs —
- * the manifest's prop/slot shape + the fixture's own props/slotChildren (from
- * the studio's `previewEntriesForConfig`). Implementation and theme drift are
- * deliberately NOT hashed (the ratified EC-440 split: those are caught by
- * regeneration runs, e.g. in the consumer's build).
+ * The PER-ENTRY staleness hash: sha-256 over the stable-serialized DECLARED
+ * inputs — the manifest's prop/slot shape + the fixture's own props/slotChildren
+ * (from the studio's `previewEntriesForConfig`). A change here is local to one
+ * entry: that entry re-renders and `--check` names exactly it.
+ *
+ * The component implementation and the theme are NOT in this hash — they have
+ * no per-entry identity (a config arrives evaluated; the theme is one stylesheet
+ * for everything). Until EC-600 this comment claimed regeneration caught drift
+ * there. It did not: regeneration rendered only `!fresh` jobs and `fresh` was
+ * decided by this hash alone, so a changed implementation or theme kept BOTH the
+ * check green and the images stale (measured on apps/demo 2026-10-09: an
+ * appended export in `hero.tsx` and a new `:root` rule in `theme.css` each left
+ * `--check` at exit 0; a fixture edit flipped it to `stale`). They are covered
+ * now by the manifest-level `renderDeps` ({@link renderDepsOf}): any change there
+ * re-renders everything and reports ONE `render-deps` problem — never N
+ * per-entry `stale` lines (the EC-502 lesson below).
  *
  * **EC-502 — the engine version was removed from this hash.** It made every
  * release invalidate every committed preview in every repo, so `elytra previews
@@ -135,11 +154,141 @@ export function previewEntryHash(hashInput) {
   return createHash('sha256').update(stableStringify({ input: hashInput }), 'utf8').digest('hex')
 }
 
+// --- Render dependencies (EC-600) ------------------------------------------------
+
+/**
+ * Root-relative POSIX path of an absolute file under `root` and not under a
+ * `node_modules` directory; `null` otherwise (virtual ids, installed packages,
+ * engine sources that resolve outside the project).
+ */
+function projectPath(root, file) {
+  if (typeof file !== 'string' || !isAbsolute(file)) return null
+  const rel = relative(root, file)
+  if (rel.length === 0 || rel.startsWith('..') || isAbsolute(rel)) return null
+  const posix = rel.split(sep).join('/')
+  return posix.split('/').includes('node_modules') ? null : posix
+}
+
+/**
+ * The project source files a Vite module graph loaded: every module with a real
+ * file under `root` that is not under `node_modules` — exactly what
+ * `elytra.config.ts` transitively imports, wherever the consumer keeps it
+ * (components, their helpers, imported assets, `cms/`). No directory
+ * convention is assumed (AGENTS.md §4: capability, never structure). Virtual
+ * modules have no file; installed packages sit under node_modules (in this
+ * monorepo they resolve to workspace packages outside the project) — the
+ * engine category the manifest's `engine` field and the engine-drift warning
+ * already cover. Absolute paths, sorted, unique.
+ */
+export function projectSourceFiles(moduleFiles, root) {
+  const out = new Set()
+  for (const file of moduleFiles) if (projectPath(root, file) !== null) out.add(file)
+  return [...out].sort()
+}
+
+const CSS_COMMENT = /\/\*[\s\S]*?\*\//g
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?(?:(['"])([^'"]+)\1|([^'")\s;]+))/g
+
+/**
+ * The theme entry plus every stylesheet it reaches through RELATIVE `@import`s,
+ * recursively (each file once; an extension-less `./tokens` resolves to
+ * `./tokens.css` the way postcss-import does). Bare specifiers (`tailwindcss`,
+ * a package's CSS) are installed code and are not followed; a relative target
+ * that does not exist is skipped here — the importing file, whose text names
+ * it, is hashed regardless, and the render itself fails loudly on it. Absolute
+ * paths, in import order.
+ */
+export function themeImportChain(entryPath, { readFile = readFileSync, exists = existsSync } = {}) {
+  const chain = []
+  const seen = new Set()
+  const visit = (file) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    if (!exists(file)) return
+    chain.push(file)
+    const text = String(readFile(file)).replace(CSS_COMMENT, '')
+    for (const match of text.matchAll(CSS_IMPORT)) {
+      const spec = match[2] ?? match[3]
+      if (!spec || spec.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(spec)) continue
+      const target = join(dirname(file), spec)
+      if (exists(target)) visit(target)
+      else if (spec.startsWith('.') && exists(`${target}.css`)) visit(`${target}.css`)
+    }
+  }
+  visit(entryPath)
+  return chain
+}
+
+/**
+ * Content-hash the render dependencies — the manifest's `renderDeps`:
+ * `[{ path, hash }]`, root-relative POSIX paths, sha-256 of the bytes, sorted by
+ * path, deduped. Byte-deterministic for unchanged files.
+ */
+export function renderDepsOf(root, files, { readFile = readFileSync } = {}) {
+  const byPath = new Map()
+  for (const file of files) {
+    const path = relative(root, file).split(sep).join('/')
+    if (byPath.has(path)) continue
+    byPath.set(path, createHash('sha256').update(readFile(file)).digest('hex'))
+  }
+  return [...byPath.entries()]
+    .map(([path, hash]) => ({ path, hash }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+}
+
+/**
+ * The paths whose hash differs / are new / are gone between two `renderDeps`
+ * lists (each sorted). A missing list (a pre-EC-600 manifest) counts as empty,
+ * so every current dependency shows up as `added`.
+ */
+export function diffRenderDeps(prior, current) {
+  const before = new Map((prior ?? []).map((d) => [d.path, d.hash]))
+  const after = new Map((current ?? []).map((d) => [d.path, d.hash]))
+  const changed = []
+  const added = []
+  const removed = []
+  for (const [path, hash] of after) {
+    if (!before.has(path)) added.push(path)
+    else if (before.get(path) !== hash) changed.push(path)
+  }
+  for (const path of before.keys()) if (!after.has(path)) removed.push(path)
+  return { changed: changed.sort(), added: added.sort(), removed: removed.sort() }
+}
+
+/** `true` when nothing changed, was added, or was removed. */
+export function renderDepsEqual(prior, current) {
+  const { changed, added, removed } = diffRenderDeps(prior, current)
+  return changed.length + added.length + removed.length === 0
+}
+
+/** The changed/added/removed paths as one short list (`+new`, `-gone`), capped. */
+function summarizeRenderDeps(diff, cap = 6) {
+  const paths = [...diff.changed, ...diff.added.map((x) => `+${x}`), ...diff.removed.map((x) => `-${x}`)]
+  const shown = paths.slice(0, cap).join(', ') + (paths.length > cap ? `, … +${paths.length - cap} more` : '')
+  return { count: paths.length, shown }
+}
+
+/**
+ * What the render-dependency coverage IS and IS NOT — printed on every run, so
+ * "fresh" is read as exactly the claim it makes: a visible caveat, not a
+ * comment (AGENTS.md §4).
+ */
+export function describeRenderDeps({ sourceCount, themeCount, themeEntry }) {
+  return [
+    `Render dependencies: ${sourceCount} project source file(s) imported by ${CONFIG_FILE} ` +
+      `+ ${themeCount} theme stylesheet(s) (the @import chain of ${themeEntry}). ` +
+      'A change in any of them re-renders every preview.',
+    '  Not seen: modules loaded only at render time (dynamic imports), assets referenced by URL, ' +
+      'installed packages (the engine version is reported separately, as a warning).',
+  ]
+}
+
 /** Serialize the previews manifest deterministically (sorted entry keys, LF, trailing newline). */
-export function serializePreviewsManifest({ engine, entries }) {
+export function serializePreviewsManifest({ engine, entries, renderDeps = [] }) {
   const doc = {
     version: PREVIEWS_MANIFEST_VERSION,
     engine,
+    renderDeps: renderDeps.map((d) => ({ path: d.path, hash: d.hash })),
     entries: entries.map((e) => ({
       componentId: e.componentId,
       fixture: e.fixture,
@@ -167,16 +316,19 @@ const fileOfUrl = (url) => (typeof url === 'string' ? url.split('/').pop() : und
 
 /**
  * Decide which entries need rendering. `specs` carry a computed `hash`;
- * an entry is FRESH (skipped) when the existing manifest has the same hash for
- * it and the image file it names is present. Fresh entries keep their existing
- * URL verbatim (a prior PNG-fallback file stays a PNG until its inputs change).
+ * an entry is FRESH (skipped) when the render dependencies are unchanged
+ * (EC-600 — `renderDeps` against the manifest's; a changed dependency makes
+ * EVERY entry stale), the existing manifest has the same hash for it, and the
+ * image file it names is present. Fresh entries keep their existing URL
+ * verbatim (a prior PNG-fallback file stays a PNG until its inputs change).
  */
-export function planPreviewRun({ specs, existing, files }) {
+export function planPreviewRun({ specs, existing, files, renderDeps }) {
   const priorByKey = new Map((existing?.entries ?? []).map((e) => [key(e), e]))
+  const depsFresh = renderDepsEqual(existing?.renderDeps, renderDeps)
   return specs.map((spec) => {
     const prior = priorByKey.get(key(spec))
     const priorFile = prior ? fileOfUrl(prior.url) : undefined
-    const fresh = Boolean(prior && prior.hash === spec.hash && priorFile && files.includes(priorFile))
+    const fresh = Boolean(depsFresh && prior && prior.hash === spec.hash && priorFile && files.includes(priorFile))
     return fresh ? { ...spec, fresh: true, url: prior.url } : { ...spec, fresh: false }
   })
 }
@@ -188,9 +340,11 @@ export function planPreviewRun({ specs, existing, files }) {
  * Two channels, and the distinction is the whole point (EC-502):
  *
  *   - **problems** fail the gate (exit 1). Each one means an artifact does not
- *     match what the config declares: a fixture with no preview, a preview whose
+ *     match what the code declares: a fixture with no preview, a preview whose
  *     declared inputs changed, a manifest entry whose image is gone, an entry or
- *     file nothing enumerates any more.
+ *     file nothing enumerates any more — and, ONCE for the whole set, a render
+ *     dependency (a config-imported source file or a theme stylesheet) whose
+ *     content changed since the images were rendered (EC-600).
  *   - **warnings** are reported and do NOT fail. Today that is exactly one:
  *     `engine-drift` — these images were rendered by a different engine version.
  *     True and worth saying, but it is implementation drift, the same category
@@ -203,7 +357,7 @@ export function planPreviewRun({ specs, existing, files }) {
  * `stale` line per entry. Say the real thing once, and skip the hash comparison
  * (entry-set and file checks still run — they are version-independent).
  */
-export function checkPreviews({ specs, manifest, files, engine }) {
+export function checkPreviews({ specs, manifest, files, engine, renderDeps }) {
   const problems = []
   const warnings = []
   if (!manifest) {
@@ -217,6 +371,10 @@ export function checkPreviews({ specs, manifest, files, engine }) {
   const comparableHashes = version === PREVIEWS_MANIFEST_VERSION
   if (!comparableHashes) {
     problems.push({ kind: 'manifest-version', from: version, to: PREVIEWS_MANIFEST_VERSION })
+  } else {
+    // One problem for the whole set — which files, never N bogus per-entry `stale` rows.
+    const deps = diffRenderDeps(manifest.renderDeps, renderDeps)
+    if (!renderDepsEqual(manifest.renderDeps, renderDeps)) problems.push({ kind: 'render-deps', ...deps })
   }
   if (engine !== undefined && manifest.engine !== undefined && manifest.engine !== engine) {
     warnings.push({ kind: 'engine-drift', from: manifest.engine, to: engine })
@@ -265,6 +423,13 @@ export function formatCheckProblems(problems) {
     if (p.kind === 'manifest-version') {
       return `  ✗ manifest   written in format v${p.from}, this CLI writes v${p.to} — hashes are not comparable; regenerate`
     }
+    if (p.kind === 'render-deps') {
+      const { count, shown } = summarizeRenderDeps(p)
+      return (
+        `  ✗ render deps ${count} render dependenc${count === 1 ? 'y' : 'ies'} changed since these previews ` +
+        `were rendered (${shown}) — every preview re-renders`
+      )
+    }
     return p.kind === 'orphan-file'
       ? `  ✗ ${label[p.kind]} ${p.file}`
       : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`
@@ -509,7 +674,27 @@ async function startHarnessServer({ root, studioDir, port }) {
     port,
     plugins: [tailwind(), ...harnessPlugins({ configPath, themePath })],
   })
-  return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}` }
+  return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}`, themePath }
+}
+
+/**
+ * The render dependencies of a booted harness (EC-600): the project source files
+ * the SSR module graph loaded while enumerating (what `elytra.config.ts`
+ * imports) plus the theme's `@import` chain, content-hashed. Call AFTER
+ * `ssrLoadModule` has run, or the graph is empty.
+ */
+function collectRenderDeps(harness, root) {
+  const graph = harness.server.environments?.ssr?.moduleGraph ?? harness.server.moduleGraph
+  const sources = projectSourceFiles([...graph.idToModuleMap.values()].map((m) => m.file), root)
+  const theme = themeImportChain(harness.themePath)
+  return {
+    renderDeps: renderDepsOf(root, [...sources, ...theme]),
+    description: describeRenderDeps({
+      sourceCount: sources.length,
+      themeCount: theme.length,
+      themeEntry: relative(root, harness.themePath).split(sep).join('/'),
+    }),
+  }
 }
 
 const PLAYWRIGHT_INSTALL_HELP = [
@@ -636,7 +821,11 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
       fixture: entry.fixture,
       hash: previewEntryHash(entry.hashInput),
     }))
-    log(`Enumerated ${specs.length} fixture preview(s) from elytra.config.ts.`)
+    log(`Enumerated ${specs.length} fixture preview(s) from ${CONFIG_FILE}.`)
+    // EC-600: what the config imported while enumerating + the theme chain — and,
+    // visibly, what that does NOT cover.
+    const { renderDeps, description } = collectRenderDeps(harness, root)
+    for (const line of description) log(line)
 
     const artifacts = gatherPreviewsArtifacts(studioDir)
     const existing = parsePreviewsManifest(artifacts.manifestText)
@@ -647,12 +836,15 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
         manifest: existing,
         files: artifacts.files,
         engine,
+        renderDeps,
       })
       // Warnings print on BOTH verdicts — a green run that still has something to
       // say says it, and a red run does not swallow it.
       for (const line of formatCheckWarnings(warnings)) log(line)
       if (ok) {
-        log(`✓ ${specs.length} preview(s) up to date (hashes match, all files present).`)
+        log(
+          `✓ ${specs.length} preview(s) up to date (declared inputs and render dependencies unchanged, all files present).`,
+        )
         return 0
       }
       log(`✗ ${problems.length} problem(s):`)
@@ -661,7 +853,11 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
       return 1
     }
 
-    const jobs = planPreviewRun({ specs, existing, files: artifacts.files })
+    if (existing && !renderDepsEqual(existing.renderDeps, renderDeps)) {
+      const { shown } = summarizeRenderDeps(diffRenderDeps(existing.renderDeps, renderDeps))
+      log(`Render dependencies changed (${shown}) — every preview re-renders.`)
+    }
+    const jobs = planPreviewRun({ specs, existing, files: artifacts.files, renderDeps })
     const toRender = jobs.filter((j) => !j.fresh)
     log(`${jobs.length - toRender.length} unchanged (skipped), ${toRender.length} to render.`)
 
@@ -717,7 +913,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
 
     // Manifest: every successful entry (fresh or rendered), enumeration order.
     const finalEntries = jobs.filter((j) => typeof j.url === 'string')
-    const manifestText = serializePreviewsManifest({ engine, entries: finalEntries })
+    const manifestText = serializePreviewsManifest({ engine, entries: finalEntries, renderDeps })
     const manifestChanged = artifacts.manifestText !== manifestText
     if (manifestChanged) {
       mkdirSync(studioDir, { recursive: true })