@elytracms/cli 0.0.87 → 0.0.90

package/src/previews.js

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync
 import { dirname, isAbsolute, join, relative, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { CONFIG_FILE, pickPort, resolveFromDir, startConsumerVite, virtualModulesPlugin } from './config-harness.js'
+import { appDisplay, resolveProjectLayout } from './layout.js'
 
 /**
  * `elytra previews` (EC-440) — build-time fixture-preview generation.
@@ -561,9 +562,10 @@ export function previewsDoctorChecks(artifacts) {
  * The engine version for the input hash — read from the `@elytracms/studio`
  * (fallback `@elytracms/core`) package the CONSUMER has installed, never
  * hardcoded. Direct node_modules paths (pnpm keeps symlinks for direct deps).
+ * `studioDir` is the resolved studio app (EC-603 layout).
  */
-export function resolveEngineVersion(root) {
-  const bases = [join(root, 'studio'), root]
+export function resolveEngineVersion(root, studioDir) {
+  const bases = [studioDir, root]
   for (const pkg of ['@elytracms/studio', '@elytracms/core']) {
     for (const base of bases) {
       const path = join(base, 'node_modules', ...pkg.split('/'), 'package.json')
@@ -581,16 +583,26 @@ export function resolveEngineVersion(root) {
 
 /**
  * The consumer theme entry the harness page imports: the studio's canvas
- * stylesheet (`studio/src/styles/canvas.css` — the EC-414 shape: the site
- * theme plus any engine-required `@source` lines) when present, else the
- * shared theme entry itself (`components/theme.css`). `null` → no theme, the
- * command refuses (an unstyled preview would be a lying artifact).
+ * stylesheet (`<studio>/src/styles/canvas.css` — the EC-414 shape: the site
+ * theme plus any engine-required `@source` lines; the stylesheet the canvas
+ * iframe really links) when present, else the theme itself — `package.json#elytra
+ * .theme`, default `components/theme.css` (EC-603: the project's declaration, never
+ * a fixed path). `null` → no theme, the command refuses (an unstyled preview would
+ * be a lying artifact).
+ *
+ * The canvas stylesheet stays first so a conventional project's recorded render
+ * dependencies (its committed manifest) are byte-for-byte unchanged by EC-603. It is
+ * looked up relative to the RESOLVED studio app; a project without one falls back to
+ * the declared theme, so it is a preference, never a requirement.
  */
-export function themeStylesheetPath(root) {
-  for (const candidate of [
-    join(root, 'studio', 'src', 'styles', 'canvas.css'),
-    join(root, 'components', 'theme.css'),
-  ]) {
+export function themeStylesheetPath(root, layout = resolveProjectLayout(root)) {
+  const studio = layout.entries.studio
+  const theme = layout.entries.theme
+  const candidates = [
+    ...(studio.path ? [join(studio.path, 'src', 'styles', 'canvas.css')] : []),
+    ...(theme.path ? [theme.path] : []),
+  ]
+  for (const candidate of candidates) {
     if (existsSync(candidate)) return candidate
   }
   return null
@@ -652,7 +664,7 @@ function harnessPlugins({ configPath, themePath }) {
 }
 
 /** Boot the shared consumer-Vite harness with the previews page + modules. */
-async function startHarnessServer({ root, studioDir, port }) {
+async function startHarnessServer({ root, studioDir, layout, port }) {
   // 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')
@@ -660,11 +672,13 @@ async function startHarnessServer({ root, studioDir, port }) {
   const tailwind = (await import(pathToFileURL(tailwindEntry).href)).default
 
   const configPath = join(root, 'elytra.config.ts')
-  const themePath = themeStylesheetPath(root)
+  const themePath = themeStylesheetPath(root, layout)
   if (!themePath) {
+    const studio = appDisplay(layout, 'studio')
+    const theme = appDisplay(layout, 'theme')
     throw new Error(
-      'No theme stylesheet found (looked for studio/src/styles/canvas.css and components/theme.css) — ' +
-        'previews must render against the consumer theme.',
+      `No theme stylesheet found (looked for ${studio}/src/styles/canvas.css and ${theme} — ` +
+        'declare yours as package.json#elytra.theme) — previews must render against the consumer theme.',
     )
   }
 
@@ -708,8 +722,8 @@ const PLAYWRIGHT_INSTALL_HELP = [
 ].join('\n')
 
 /** Dynamic, on-demand Playwright load from the consumer repo. `null` = not installed. */
-async function loadPlaywright(root) {
-  for (const base of [join(root, 'studio'), root]) {
+async function loadPlaywright(root, studioDir) {
+  for (const base of [studioDir, root]) {
     let resolved
     try {
       resolved = resolveFromDir(base, 'playwright')
@@ -795,8 +809,11 @@ async function captureViewport(page, cdp) {
  */
 export async function runPreviews(project, { check = false, port, log = (l) => console.log(l) } = {}) {
   const root = project.root
-  const studioDir = join(root, 'studio')
-  const engine = resolveEngineVersion(root)
+  // EC-603: the studio app and theme where the project's layout says they are.
+  const layout = project.layout ?? resolveProjectLayout(root)
+  const studioDir = layout.entries.studio.path
+  const studioLabel = layout.entries.studio.display
+  const engine = resolveEngineVersion(root, studioDir)
   const manifestPath = join(studioDir, PREVIEWS_MANIFEST_FILE)
   const imagesDir = join(studioDir, PREVIEWS_DIR)
 
@@ -807,7 +824,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
   const chosenPort = port ? Number(port) : await pickPort()
   let harness
   try {
-    harness = await startHarnessServer({ root, studioDir, port: chosenPort })
+    harness = await startHarnessServer({ root, studioDir, layout, port: chosenPort })
   } catch (error) {
     log(`Could not start the render harness: ${error.message}`)
     return 1
@@ -863,7 +880,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
 
     const failures = []
     if (toRender.length > 0) {
-      const playwright = await loadPlaywright(root)
+      const playwright = await loadPlaywright(root, studioDir)
       if (!playwright) {
         log(PLAYWRIGHT_INSTALL_HELP)
         return 1
@@ -933,7 +950,7 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
     log(
       `Done: ${rendered} rendered, ${jobs.length - toRender.length} unchanged, ` +
         `${orphans.length} pruned, manifest ${manifestChanged ? 'written' : 'unchanged'} ` +
-        `(studio/${PREVIEWS_MANIFEST_FILE}).`,
+        `(${studioLabel}/${PREVIEWS_MANIFEST_FILE}).`,
     )
     if (failures.length > 0) {
       log(`✗ ${failures.length} fixture(s) failed to render — their entries were left out of the manifest.`)

package/src/project.js

@@ -1,20 +1,36 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { parseBackendMode } from '@elytracms/core/export-sync/deployment-ready'
+import { appDisplay, resolveProjectLayout } from './layout.js'
 
 /**
- * Project detection for the Elytra CLI (EC-235). Convention-aware, not config-
- * 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`). 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.)
+ * Project detection for the Elytra CLI (EC-235). Declaration-aware, not config-
+ * executing: the repo root is the directory holding `elytra.config.ts`; the LAYOUT —
+ * where the studio app, the frontend app and the theme live — is declared in the
+ * `package.json` beside it (`"elytra": { studio, frontend, theme }`, EC-603), every key
+ * defaulting to the scaffold layout (`./studio`, `./frontend`,
+ * `./components/theme.css`) — see `layout.js`. The backend mode comes from the studio
+ * app's env files, judged by the ONE parser the studio itself runs (core's
+ * `parseBackendMode`, EC-603).
+ *
+ * Detection deliberately does NOT load the config: it must work before `pnpm install`
+ * of the consuming repo (the CLI's own dependency, `@elytracms/core`, is installed WITH
+ * the CLI — this module imports exactly two of its built files, the bundler-free
+ * `export-sync/deployment-ready` and the parser it re-exports), 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. */
+/**
+ * Walk up from `start` until a directory containing `elytra.config.ts` is found.
+ *
+ * EC-603 kept this key: the config is the one file Elytra requires of a repo and it
+ * stays at the root, while the layout section is OPTIONAL (defaults declare nothing) —
+ * so a `package.json` can never mark the root on its own, and the studio/frontend apps'
+ * own `package.json`s sit on the walk up from inside them.
+ */
 export function findRepoRoot(start) {
   let dir = start
   for (;;) {
@@ -25,7 +41,14 @@ export function findRepoRoot(start) {
   }
 }
 
-/** Parse a dotenv file into a flat record. Missing file → {}. */
+/**
+ * Parse a dotenv file into a flat record. Missing file → {}.
+ *
+ * Deliberately small, and NOT Vite's dotenv: no variable expansion, and an inline
+ * ` #…` is stripped even inside quotes. Values the backend parser reads are trimmed by
+ * the parser itself, which covers the measured P21 case (quoted padding); the remaining
+ * dotenv-dialect differences are recorded in EC-603's Done section.
+ */
 function readEnvFile(path) {
   if (!existsSync(path)) return {}
   const out = {}
@@ -43,26 +66,51 @@ function readEnvFile(path) {
   return out
 }
 
-/** Merge a package's `.env` then `.env.local` (local wins), then process.env. */
-function resolveEnv(appDir, processEnv) {
-  return {
-    ...readEnvFile(join(appDir, '.env')),
-    ...readEnvFile(join(appDir, '.env.local')),
-    ...processEnv,
+/**
+ * The env files Vite loads for `mode`, lowest precedence first — the studio's own
+ * toolchain's file set (`vite dev` = `development`, `vite build` = `production`), so the
+ * CLI reads exactly the files the studio it starts will read (EC-603: a mode set only in
+ * `.env.development.local` used to be invisible here).
+ */
+export function viteEnvFiles(mode) {
+  return ['.env', '.env.local', `.env.${mode}`, `.env.${mode}.local`]
+}
+
+/** Merge an app's env files (Vite's order: later wins), then process.env over them. */
+function resolveEnv(appDir, processEnv, viteMode) {
+  let merged = {}
+  if (appDir) {
+    for (const file of viteEnvFiles(viteMode)) merged = { ...merged, ...readEnvFile(join(appDir, file)) }
   }
+  return { ...merged, ...processEnv }
 }
 
 /**
- * Resolve the studio app's effective env (`studio/.env` ← `.env.local` ← process.env) —
- * the same signal the studio itself reads. Used by `elytra doctor` to find the Convex
- * deployment to diagnose. Exported so the doctor and project inspection share one reader.
+ * Resolve the studio app's effective env (its env files for `viteMode` ← process.env) —
+ * the same signal the studio itself reads. Used by `elytra doctor` / `elytra init` to
+ * find the Convex deployment to diagnose. `rootOrProject` is the repo root (the layout
+ * is resolved from it) or an {@link inspectProject} result (its resolved layout is
+ * used). Exported so the doctor and project inspection share one reader.
  */
-export function resolveStudioEnv(root, processEnv = {}) {
-  return resolveEnv(join(root, 'studio'), processEnv)
+export function resolveStudioEnv(rootOrProject, processEnv = {}, { viteMode = 'development' } = {}) {
+  const layout =
+    typeof rootOrProject === 'string' ? resolveProjectLayout(rootOrProject) : rootOrProject.layout
+  const studio = layout.entries.studio
+  return resolveEnv(studio.found ? studio.path : null, processEnv, viteMode)
 }
 
-function isApp(root, name) {
-  return existsSync(join(root, name, 'package.json'))
+/**
+ * The CLI's vocabulary for the ONE parser's verdict (EC-603) — the single place the two
+ * vocabularies meet. The CLI keeps `connected` / `unconfigured` (its user-facing words:
+ * "connected mode", "Backend not configured") over the studio's `convex` /
+ * `misconfigured`; the mapping is 1:1, and an `unconfigured` project carries the
+ * parser's verdict (`project.backend`) so its notes can say WHY — a missing URL, or an
+ * unknown mode the studio will refuse to boot with.
+ */
+export function cliModeOf(backend) {
+  if (backend.kind === 'convex') return 'connected'
+  if (backend.kind === 'playground') return 'playground'
+  return 'unconfigured'
 }
 
 /**
@@ -113,21 +161,29 @@ export function resolveDevPortOffset(env = {}) {
 
 /**
  * Inspect a consuming repo. Returns:
- *   { root, apps: {studio, frontend}, mode, convexProvisioned, isProdDeployment,
- *     hasDeployKey, hasAiRoute, devPortOffset, issues }
- * `issues` are actionable, human-readable prerequisite problems (empty = ok).
+ *   { root, layout, apps: {studio, frontend}, backend, mode, convexProvisioned,
+ *     isProdDeployment, hasDeployKey, devPortOffset, issues }
+ * `layout` is the resolved `package.json#elytra` layout (`layout.js`); `backend` is the
+ * shared parser's verdict and `mode` its CLI name ({@link cliModeOf}). `issues` are
+ * actionable, human-readable prerequisite problems (empty = ok) — an invalid layout
+ * section or a declared path that does not exist is one of them, so no command runs
+ * against a layout the project did not mean.
+ *
+ * `viteMode` selects the studio env files read (Vite's set for that mode): `elytra build`
+ * runs `vite build`, so it inspects `production`; everything else `development`.
  */
-export function inspectProject(cwd, processEnv = {}) {
+export function inspectProject(cwd, processEnv = {}, { viteMode = 'development' } = {}) {
   const root = findRepoRoot(cwd)
   if (!root) {
     return {
       root: null,
+      layout: null,
       apps: { studio: false, frontend: false },
+      backend: null,
       mode: 'unknown',
       convexProvisioned: false,
       isProdDeployment: false,
       hasDeployKey: false,
-      hasAiRoute: false,
       devPortOffset: 0,
       issues: [
         'No elytra.config.ts found in this directory or any parent. Run `elytra` from inside an Elytra project (or scaffold one with `npm create elytra@latest`).',
@@ -135,23 +191,27 @@ export function inspectProject(cwd, processEnv = {}) {
     }
   }
 
-  const apps = { studio: isApp(root, 'studio'), frontend: isApp(root, 'frontend') }
-  const issues = []
-  if (!apps.studio && !apps.frontend) {
-    issues.push('No `studio/` or `frontend/` app found next to elytra.config.ts.')
+  const layout = resolveProjectLayout(root)
+  const apps = { studio: layout.entries.studio.found, frontend: layout.entries.frontend.found }
+  const issues = layout.issues.map((i) => i.message)
+  if (layout.issues.length === 0 && !apps.studio && !apps.frontend) {
+    issues.push(
+      `No studio or frontend app found (looked for ${appDisplay(layout, 'studio')}/package.json and ` +
+        `${appDisplay(layout, 'frontend')}/package.json` +
+        (layout.source === 'defaults' ? ' — the scaffold layout; declare yours in package.json#elytra).' : ').'),
+    )
   }
   if (!existsSync(join(root, 'node_modules'))) {
     issues.push('Dependencies are not installed. Run `pnpm install` first.')
   }
 
-  // Backend mode is read from the studio app's env, mirroring the studio's own
-  // resolveBackendConfig: explicit playground flag wins; otherwise a Convex URL
-  // means connected; neither means it still needs configuring.
-  const studioEnv = apps.studio ? resolveEnv(join(root, 'studio'), processEnv) : processEnv
-  let mode
-  if (studioEnv.VITE_ELYTRA_MODE === 'playground') mode = 'playground'
-  else if (studioEnv.VITE_CONVEX_URL) mode = 'connected'
-  else mode = 'unconfigured'
+  // Backend mode is read from the studio app's env through the ONE parser the studio
+  // itself runs (EC-603): explicit playground flag wins; an unknown mode is a visible
+  // misconfiguration; otherwise a Convex URL means connected; neither means it still
+  // needs configuring.
+  const studioEnv = resolveEnv(apps.studio ? layout.entries.studio.path : null, processEnv, viteMode)
+  const backend = parseBackendMode(studioEnv)
+  const mode = cliModeOf(backend)
 
   // A Convex dev/deploy step only makes sense once a deployment is provisioned
   // (`npx convex dev` writes CONVEX_DEPLOYMENT). Otherwise we skip it and say so.
@@ -165,14 +225,11 @@ export function inspectProject(cwd, processEnv = {}) {
   // so `elytra dev` and the bare `elytra build` are unchanged by its presence.
   const hasDeployKey = Boolean(studioEnv.CONVEX_DEPLOY_KEY)
 
-  // Is the studio's AI route present? (EC-399 — drives the AI provider-key env
-  // expectation in `elytra doctor`.) Convention-aware like everything here: the
-  // scaffold mounts the handler at `studio/src/server/ai-handler.ts` (the
-  // `createAiDevPlugin` default path); we never execute config to find out.
-  const hasAiRoute = apps.studio && existsSync(join(root, 'studio', 'src', 'server', 'ai-handler.ts'))
+  // EC-603: the AI route is no longer guessed from a fixed file path here — `elytra
+  // doctor` reads it from the studio's resolved Vite config (`config-harness.js`).
 
   // EC-464: the one dev-port lever, read from the same studio env as everything else here.
   const devPortOffset = resolveDevPortOffset(studioEnv)
 
-  return { root, apps, mode, convexProvisioned, isProdDeployment, hasDeployKey, hasAiRoute, devPortOffset, issues }
+  return { root, layout, apps, backend, mode, convexProvisioned, isProdDeployment, hasDeployKey, devPortOffset, issues }
 }

package/src/routes-check.js

@@ -50,8 +50,10 @@ import {
  * `elytra.config.ts` passes straight through. (`elytra.config.ts` itself is NOT
  * loadable this way — it imports `.tsx` component barrels, which no Node version
  * executes, EC-474. Where the consumer's deps ARE installed, EC-495's Vite harness
- * executes the full config and `runDoctor` hands the collections it resolved to these
- * checks in place of the `cms/index.ts` re-export; this loader stays the floor.)
+ * executes the full config and `runDoctor` hands the ROUTES and collections it resolved
+ * to these checks in place of the `cms/index.ts` re-export — EC-603; before, only the
+ * collections were swapped in. This loader stays the floor, and the first row says
+ * which of the two was judged.)
  *
  * Two things stand in the way, and both are handled rather than assumed away:
  *
@@ -311,6 +313,16 @@ const MOUNT_SHADOW_FIX =
 const UNREACHABLE_FIX =
   'Give an all-dynamic route a static segment (e.g. "/blog/:slug"), mount only collections with a `parent` self-relation, and keep a mount prefix static — in cms/routes.ts.'
 
+/**
+ * Where the judged route set came from (EC-603, RESIDUE-4), appended to the first row so
+ * the report says which reader it used: the executed config (what the studio and
+ * delivery serve) or the bundler-free `cms/index.ts` floor. No `source` → no note.
+ */
+const ROUTE_SOURCE_NOTE = {
+  config: ' (Routes from the executed elytra.config.ts.)',
+  native: ` (Routes read natively from ${CMS_ENTRY} — elytra.config.ts was not resolved here.)`,
+}
+
 /** An `unknown` check row carrying the reason the routes could not be read. */
 function unavailableCheck(id, facts) {
   return {
@@ -360,6 +372,7 @@ export function routesDoctorChecks(facts) {
   const count = facts.routeCount ?? facts.routes.length
   const plural = count === 1 ? '' : 's'
   const conflicts = routeIssuesOf(facts.routes).filter((issue) => issue.code === 'route-conflict')
+  const source = ROUTE_SOURCE_NOTE[facts.source] ?? ''
 
   const routeConflicts =
     conflicts.length === 0
@@ -367,7 +380,7 @@ export function routesDoctorChecks(facts) {
           id: 'route-conflicts',
           bucket: 'app',
           status: 'ok',
-          detail: `${count} declared route${plural}, no URL conflicts.`,
+          detail: `${count} declared route${plural}, no URL conflicts.${source}`,
         }
       : {
           id: 'route-conflicts',
@@ -375,7 +388,8 @@ export function routesDoctorChecks(facts) {
           status: 'fail',
           detail:
             `${conflicts.length} route conflict(s) among ${count} declared route${plural}. ` +
-            conflicts.map((issue) => issue.message).join(' '),
+            conflicts.map((issue) => issue.message).join(' ') +
+            source,
           fix: CONFLICT_FIX,
         }