@elytracms/cli 0.0.80 → 0.0.82

package/src/engine-build-failure.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs'
+
+/**
+ * EC-503 — attribute "the engine has no build output" to its real cause.
+ *
+ * This CLI loads the engine's COMPILED output under plain Node: `doctor.js`
+ * imports `@elytracms/core/export-sync/deployment-ready` and `routes-check.js`
+ * imports `@elytracms/core/cms-core`, both of which resolve to
+ * `@elytracms/core/dist/...` (no bundler, no `development` export condition).
+ * Those are static imports at the top of `src/cli.js`'s graph, so when that dist
+ * is absent or half-written NOTHING runs — `elytra --help` itself dies with a raw
+ * `ERR_MODULE_NOT_FOUND` stack naming a compiled file the developer never wrote
+ * (measured 2026-08-01: moved `dist/export-sync/deployment-ready.js` aside, ran
+ * `elytra --help`, got the stack and exit 1).
+ *
+ * The state is easy to reach and has nothing to do with the person who hits it:
+ * every package build starts by DELETING dist (`rmSync('dist')` then `tsc`), so
+ * any `pnpm build` / `pnpm verify` / `pnpm typecheck` that dies partway — for a
+ * reason anywhere in the workspace — leaves the tree in it. The tool you would
+ * reach for to find out what is wrong is the tool that stops working, and its
+ * error names the wrong thing.
+ *
+ * So the CLI's job here is not to recover — it genuinely cannot run without the
+ * engine — but to FAIL WITH THE TRUE CAUSE AND ONE COMMAND. This module is the
+ * pure decision core; `index.js` is the impure shell that catches and prints it.
+ */
+
+/** `ERR_MODULE_NOT_FOUND` carries the unresolvable file on `url`; older shapes only in the message. */
+function missingUrlOf(error) {
+  if (typeof error?.url === 'string') return error.url
+  const match = /Cannot find module '([^']+)'/.exec(String(error?.message ?? ''))
+  return match ? match[1] : undefined
+}
+
+/**
+ * Split an `@elytracms/<pkg>/…/dist/…` path into the package name and the
+ * package root. Returns `undefined` for anything that is not an engine dist
+ * path — a missing module elsewhere is somebody else's bug and must keep its
+ * own error verbatim.
+ */
+export function parseEngineDistPath(path) {
+  if (typeof path !== 'string') return undefined
+  const match = /(.*\/@elytracms\/([^/]+))\/dist\//.exec(path.replace(/^file:\/\//, ''))
+  if (!match) return undefined
+  return { packageName: `@elytracms/${match[2]}`, packageRoot: decodeURIComponent(match[1]) }
+}
+
+/**
+ * Is this package a LINKED workspace checkout rather than an installed tarball?
+ * Discriminated by what the published artifact contains: `@elytracms/core` ships
+ * `files: ["dist"]` and `@elytracms/studio` ships `["dist","convex","src/styles"]`
+ * — neither publishes `src/lib`, so its presence means a source checkout. Path
+ * shape is NOT usable here: pnpm's workspace link makes a linked package resolve
+ * through `node_modules/@elytracms/…` exactly like an installed one (measured —
+ * the failing url was `packages/cli/node_modules/@elytracms/core/dist/…`).
+ */
+export function isLinkedWorkspacePackage(packageRoot, exists = existsSync) {
+  return exists(`${packageRoot}/src/lib`) || exists(`${packageRoot}/src/index.ts`) || exists(`${packageRoot}/tsconfig.build.json`)
+}
+
+/**
+ * The attributed message for an engine-dist load failure, or `null` when the
+ * error is anything else (which must then propagate untouched — swallowing a
+ * real bug behind a friendly line is the failure mode this whole file exists to
+ * avoid at one level up).
+ */
+export function engineBuildFailureMessage(error, { exists = existsSync } = {}) {
+  if (error?.code !== 'ERR_MODULE_NOT_FOUND') return null
+  const parsed = parseEngineDistPath(missingUrlOf(error))
+  if (!parsed) return null
+  const { packageName, packageRoot } = parsed
+  const fix = isLinkedWorkspacePackage(packageRoot, exists)
+    ? `  pnpm --filter ${packageName} build`
+    : '  pnpm install --force        (the installed package is incomplete)'
+  return [
+    `elytra: ${packageName} has no usable build output, so no elytra command can run.`,
+    '',
+    `  missing: ${missingUrlOf(error)}`,
+    '',
+    'The CLI loads the engine’s compiled output under plain Node. A package build',
+    'DELETES its dist before writing it, so any interrupted `pnpm build` / `pnpm verify`',
+    '— for any reason, anywhere in the workspace — leaves it missing or half-written.',
+    '',
+    'Fix:',
+    fix,
+    '',
+  ].join('\n')
+}

package/src/previews.js

@@ -1,9 +1,8 @@
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { createServer as createNetServer } from 'node:net'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
 
 /**
  * `elytra previews` (EC-440) — build-time fixture-preview generation.
@@ -19,9 +18,8 @@ import { pathToFileURL } from 'node:url'
  *     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 + engine
- *     version) — no timestamps, so unchanged inputs re-serialize to the same
- *     bytes.
+ *     an input hash (manifest prop/slot shape + fixture props) — 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
@@ -29,10 +27,9 @@ import { pathToFileURL } from 'node:url'
  * compare); the manifest is only written when its bytes change. A re-run with
  * unchanged inputs therefore rewrites nothing.
  *
- * Harness: the CLI boots the consumer studio app's own Vite PROGRAMMATICALLY
- * (resolved from the studio dir; a minimal inline config — the studio's
- * `vite.config.ts`, with its app plugins/env, is deliberately NOT loaded) and
- * serves a DATA-FREE render page that imports exactly the consumer registry
+ * Harness: the shared consumer-Vite boot (`config-harness.js`, EC-495 — one
+ * mechanism for this command and `elytra doctor`'s config check) plus a
+ * DATA-FREE render page that imports exactly the consumer registry
  * (`elytra.config.ts`) and the consumer theme. Enumeration + hashing run
  * node-side through the same Vite (`ssrLoadModule`), so `--check` needs no
  * browser; rendering drives headless Chromium via Playwright — an ON-DEMAND
@@ -53,8 +50,13 @@ export const PREVIEWS_DIR = join('public', 'elytra-previews')
 export const PREVIEWS_MANIFEST_FILE = 'elytra-previews.json'
 /** Root-relative URL prefix the manifest entries carry. */
 export const PREVIEWS_URL_PREFIX = '/elytra-previews/'
-/** Manifest format version (mirrors `@elytracms/studio`'s PREVIEWS_MANIFEST_VERSION). */
-export const PREVIEWS_MANIFEST_VERSION = 1
+/**
+ * Manifest format version (mirrors `@elytracms/studio`'s PREVIEWS_MANIFEST_VERSION).
+ * `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.
+ */
+export const PREVIEWS_MANIFEST_VERSION = 2
 
 /** 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 }
@@ -107,14 +109,28 @@ 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`) + the installed engine version.
- * Implementation and theme drift are deliberately NOT hashed (the ratified
- * split: those are caught by regeneration runs, e.g. in the consumer's build).
+ * 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).
+ *
+ * **EC-502 — the engine version was removed from this hash.** It made every
+ * release invalidate every committed preview in every repo, so `elytra previews
+ * --check` was red on a healthy tree for a reason that had nothing to do with any
+ * entry. Measured on `apps/demo` 2026-08-01: all 23 committed hashes reproduced
+ * byte-identically at the manifest's recorded engine (0.0.70) against today's
+ * inputs — 0 entries had drifted, yet all 23 reported `stale`, burying the ONE
+ * real problem (a new fixture with no image) at line 12 of 24.
+ *
+ * The engine version is engine IMPLEMENTATION, and implementation is the exact
+ * category the ratified split already puts outside `--check`'s remit; treating the
+ * engine's as an ERROR while a consumer component's is not even a warning was
+ * incoherent, and the incoherence is what produced the permanent red. It is still
+ * recorded in the manifest (which engine rendered these images) and still reported
+ * on every `--check` run — as a WARNING that does not fail the gate. See
+ * {@link checkPreviews}.
  */
-export function previewEntryHash(hashInput, engineVersion) {
-  return createHash('sha256')
-    .update(stableStringify({ engine: engineVersion, input: hashInput }), 'utf8')
-    .digest('hex')
+export function previewEntryHash(hashInput) {
+  return createHash('sha256').update(stableStringify({ input: hashInput }), 'utf8').digest('hex')
 }
 
 /** Serialize the previews manifest deterministically (sorted entry keys, LF, trailing newline). */
@@ -165,17 +181,45 @@ export function planPreviewRun({ specs, existing, files }) {
 
 /**
  * `--check` verdicts: compare the enumerated entry set (+ fresh hashes)
- * against the committed manifest + image files. Every problem names its
- * entry; an empty list is green.
+ * against the committed manifest + image 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
+ *     declared inputs changed, a manifest entry whose image is gone, an entry or
+ *     file nothing enumerates any more.
+ *   - **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
+ *     the ratified EC-440 split already leaves to regeneration runs; as a failure
+ *     it fired on every entry of every repo on every release and taught people
+ *     that red means nothing.
+ *
+ * A manifest written by an older FORMAT version is its own problem: its hashes were
+ * computed under different semantics, so comparing them would print one meaningless
+ * `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 }) {
+export function checkPreviews({ specs, manifest, files, engine }) {
   const problems = []
+  const warnings = []
   if (!manifest) {
     for (const spec of specs) {
       problems.push({ kind: 'missing', componentId: spec.componentId, fixture: spec.fixture })
     }
-    return { ok: specs.length === 0, problems }
+    return { ok: specs.length === 0, problems, warnings }
+  }
+
+  const version = typeof manifest.version === 'number' ? manifest.version : 0
+  const comparableHashes = version === PREVIEWS_MANIFEST_VERSION
+  if (!comparableHashes) {
+    problems.push({ kind: 'manifest-version', from: version, to: PREVIEWS_MANIFEST_VERSION })
+  }
+  if (engine !== undefined && manifest.engine !== undefined && manifest.engine !== engine) {
+    warnings.push({ kind: 'engine-drift', from: manifest.engine, to: engine })
   }
+
   const entryByKey = new Map(manifest.entries.map((e) => [key(e), e]))
   const specKeys = new Set(specs.map((s) => key(s)))
 
@@ -186,7 +230,7 @@ export function checkPreviews({ specs, manifest, files }) {
       continue
     }
     const file = fileOfUrl(entry.url)
-    if (entry.hash !== spec.hash) {
+    if (comparableHashes && entry.hash !== spec.hash) {
       problems.push({ kind: 'stale', componentId: spec.componentId, fixture: spec.fixture })
     } else if (!file || !files.includes(file)) {
       problems.push({ kind: 'missing-file', componentId: spec.componentId, fixture: spec.fixture, file })
@@ -203,7 +247,7 @@ export function checkPreviews({ specs, manifest, files }) {
       problems.push({ kind: 'orphan-file', file })
     }
   }
-  return { ok: problems.length === 0, problems }
+  return { ok: problems.length === 0, problems, warnings }
 }
 
 /** One line per problem, stable order, for `--check` output. */
@@ -215,10 +259,24 @@ export function formatCheckProblems(problems) {
     'orphan-entry': 'orphaned  ',
     'orphan-file': 'stray file',
   }
-  return problems.map((p) =>
-    p.kind === 'orphan-file'
+  return problems.map((p) => {
+    if (p.kind === 'manifest-version') {
+      return `  ✗ manifest   written in format v${p.from}, this CLI writes v${p.to} — hashes are not comparable; regenerate`
+    }
+    return p.kind === 'orphan-file'
       ? `  ✗ ${label[p.kind]} ${p.file}`
-      : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`,
+      : `  ✗ ${label[p.kind]} ${p.componentId} · ${p.fixture}${p.file ? ` (${p.file})` : ''}`
+  })
+}
+
+/** One line per warning — reported, never fatal (EC-502). */
+export function formatCheckWarnings(warnings) {
+  return warnings.map((w) =>
+    w.kind === 'engine-drift'
+      ? `  ! engine     these images were rendered by engine ${w.from}; installed is ${w.to}. ` +
+        'Declared inputs are unchanged, so this does not fail the check — ' +
+        'run `elytra previews` when you want the images re-rendered.'
+      : `  ! ${w.kind}`,
   )
 }
 
@@ -332,11 +390,6 @@ export function previewsDoctorChecks(artifacts) {
 
 // --- Impure plumbing ---------------------------------------------------------------
 
-/** Resolve a module specifier from a directory's own node_modules world. */
-function resolveFromDir(dir, specifier) {
-  return createRequire(join(dir, 'package.json')).resolve(specifier)
-}
-
 /**
  * The engine version for the input hash — read from the `@elytracms/studio`
  * (fallback `@elytracms/core`) package the CONSUMER has installed, never
@@ -390,68 +443,52 @@ const HARNESS_HTML = `<!doctype html>
 `
 
 /**
- * The inline Vite plugin serving the DATA-FREE harness: two virtual modules
- * (the browser render entry; the node-side enumeration) that import exactly
- * the consumer config + theme + the studio previews modules — no studio app
- * code, no persistence, no auth, no env.
+ * The inline Vite plugins serving the DATA-FREE harness: two virtual modules
+ * (the browser render entry; the node-side enumeration — via the shared
+ * {@link virtualModulesPlugin}) that import exactly the consumer config +
+ * theme + the studio previews modules — no studio app code, no persistence,
+ * no auth, no env — plus the middleware serving the render page itself.
  */
-function harnessPlugin({ configPath, themePath }) {
+function harnessPlugins({ configPath, themePath }) {
   const configImport = `/@fs/${configPath}`
   const themeImport = `/@fs/${themePath}`
-  return {
-    name: 'elytra-previews-harness',
-    resolveId(id) {
-      return id === ENTRY_ID || id === ENUMERATE_ID ? id : null
-    },
-    load(id) {
-      if (id === ENTRY_ID) {
-        return [
-          `import '${themeImport}'`,
-          `import config from '${configImport}'`,
-          `import { mountPreviewHarness } from '@elytracms/studio/previews/harness'`,
-          `mountPreviewHarness(config)`,
-        ].join('\n')
-      }
-      if (id === ENUMERATE_ID) {
-        return [
-          `import config from '${configImport}'`,
-          `import { previewEntriesForConfig } from '@elytracms/studio/previews/enumerate'`,
-          `export const entries = previewEntriesForConfig(config)`,
-        ].join('\n')
-      }
-      return null
-    },
-    configureServer(server) {
-      server.middlewares.use((req, res, next) => {
-        if (!req.url || req.url.split('?')[0] !== HARNESS_PATH) return next()
-        server
-          .transformIndexHtml(req.url, HARNESS_HTML)
-          .then((html) => {
-            res.setHeader('content-type', 'text/html')
-            res.end(html)
-          })
-          .catch(next)
-      })
+  return [
+    virtualModulesPlugin('elytra-previews-harness', {
+      [ENTRY_ID]: [
+        `import '${themeImport}'`,
+        `import config from '${configImport}'`,
+        `import { mountPreviewHarness } from '@elytracms/studio/previews/harness'`,
+        `mountPreviewHarness(config)`,
+      ].join('\n'),
+      [ENUMERATE_ID]: [
+        `import config from '${configImport}'`,
+        `import { previewEntriesForConfig } from '@elytracms/studio/previews/enumerate'`,
+        `export const entries = previewEntriesForConfig(config)`,
+      ].join('\n'),
+    }),
+    {
+      name: 'elytra-previews-harness-page',
+      configureServer(server) {
+        server.middlewares.use((req, res, next) => {
+          if (!req.url || req.url.split('?')[0] !== HARNESS_PATH) return next()
+          server
+            .transformIndexHtml(req.url, HARNESS_HTML)
+            .then((html) => {
+              res.setHeader('content-type', 'text/html')
+              res.end(html)
+            })
+            .catch(next)
+        })
+      },
     },
-  }
-}
-
-/** First free port in [start, start+span) — never a hardcoded single port. */
-async function pickPort(start = 5440, span = 30) {
-  for (let port = start; port < start + span; port += 1) {
-    const free = await new Promise((resolve) => {
-      const probe = createNetServer()
-      probe.once('error', () => resolve(false))
-      probe.listen(port, '127.0.0.1', () => probe.close(() => resolve(true)))
-    })
-    if (free) return port
-  }
-  throw new Error(`No free port in ${start}–${start + span - 1}.`)
+  ]
 }
 
-/** Boot the consumer studio's Vite with the minimal inline harness config. */
+/** Boot the shared consumer-Vite harness with the previews page + modules. */
 async function startHarnessServer({ root, studioDir, port }) {
-  const vite = await import(pathToFileURL(resolveFromDir(studioDir, 'vite')).href)
+  // Resolve vite first so a missing toolchain names vite (the same failure
+  // order as before the boot moved to the shared config-harness).
+  resolveFromDir(studioDir, 'vite')
   const tailwindEntry = resolveFromDir(studioDir, '@tailwindcss/vite')
   const tailwind = (await import(pathToFileURL(tailwindEntry).href)).default
 
@@ -464,22 +501,12 @@ async function startHarnessServer({ root, studioDir, port }) {
     )
   }
 
-  const server = await vite.createServer({
-    configFile: false,
-    root: studioDir,
-    mode: 'development',
-    appType: 'custom',
-    logLevel: 'warn',
-    plugins: [tailwind(), harnessPlugin({ configPath, themePath })],
-    server: {
-      port,
-      strictPort: true,
-      host: '127.0.0.1',
-      fs: { allow: [vite.searchForWorkspaceRoot(studioDir), root] },
-    },
-    esbuild: { jsx: 'automatic' },
+  const server = await startConsumerVite({
+    root,
+    studioDir,
+    port,
+    plugins: [tailwind(), ...harnessPlugins({ configPath, themePath })],
   })
-  await server.listen()
   return { server, url: `http://127.0.0.1:${port}${HARNESS_PATH}` }
 }
 
@@ -587,7 +614,8 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
   const imagesDir = join(studioDir, PREVIEWS_DIR)
 
   log(`Elytra previews — fixture preview ${check ? 'staleness check' : 'generation'}`)
-  log(`Engine version (hash input): ${engine}`)
+  // EC-502: recorded on the manifest, NOT hashed into the entries.
+  log(`Engine version (recorded on the manifest): ${engine}`)
 
   const chosenPort = port ? Number(port) : await pickPort()
   let harness
@@ -604,7 +632,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
     const specs = entries.map((entry) => ({
       componentId: entry.componentId,
       fixture: entry.fixture,
-      hash: previewEntryHash(entry.hashInput, engine),
+      hash: previewEntryHash(entry.hashInput),
     }))
     log(`Enumerated ${specs.length} fixture preview(s) from elytra.config.ts.`)
 
@@ -612,7 +640,15 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
     const existing = parsePreviewsManifest(artifacts.manifestText)
 
     if (check) {
-      const { ok, problems } = checkPreviews({ specs, manifest: existing, files: artifacts.files })
+      const { ok, problems, warnings } = checkPreviews({
+        specs,
+        manifest: existing,
+        files: artifacts.files,
+        engine,
+      })
+      // 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).`)
         return 0

package/src/project.js

@@ -6,9 +6,12 @@ import { dirname, join } from 'node:path'
  * executing: a consuming repo's layout (`studio/`, `frontend/`, root
  * `elytra.config.ts`) and its `.env` are the source of truth — the same `.env`
  * the studio itself reads to resolve its backend (`VITE_ELYTRA_MODE` /
- * `VITE_CONVEX_URL`). We deliberately do NOT load the TS config (no TS runtime
- * dependency); the paths are conventional and the operative backend signal lives
- * in env regardless.
+ * `VITE_CONVEX_URL`). Detection deliberately does NOT load the config: it must work
+ * before `pnpm install`, the paths are conventional, and the operative backend signal
+ * lives in env regardless. (Commands that need the config's CONTENTS execute it
+ * through the consumer's own Vite instead — `config-harness.js`, EC-440/EC-495 — and
+ * degrade honestly when that is unavailable. Node-native TS is not an option: real
+ * configs import `.tsx` barrels, EC-474.)
  */
 
 /** Walk up from `start` until a directory containing `elytra.config.ts` is found. */