@elytracms/cli 0.0.88 → 0.0.90

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,
         }