@elytracms/cli 0.0.88 → 0.0.91

package/README.md

@@ -62,15 +62,33 @@ project inspection, no process spawned, no network call, no write. `elytra dev
 --help` never starts a server; `elytra doctor --help` never runs the network
 diagnostic; `elytra build --help` never validates a target.
 
+## Project layout
+
+The studio app, the frontend app and the theme are found at `studio/`,
+`frontend/` and `components/theme.css` — the scaffold layout — unless the
+repo-root `package.json` (beside `elytra.config.ts`) declares otherwise:
+
+```json
+{ "elytra": { "studio": "./apps/editor", "frontend": "./apps/site", "theme": "./styles/site.css" } }
+```
+
+Every key is optional. An invalid section or a declared path that does not
+exist is reported (`elytra doctor` fails `project-layout`; the other commands
+refuse to start) — never silently replaced by the default. Full rules:
+`docs/guide/06-cli-reference.md`.
+
 ## Mode-aware
 
-The CLI reads the studio's `.env` (the same backend signal the studio itself
-uses):
+The CLI reads the studio app's env files — the ones Vite loads for it
+(`.env`, `.env.local`, `.env.<mode>`, `.env.<mode>.local`) — through the SAME
+backend-mode parser the studio runs, so the two never disagree:
 
 - **Playground** (`VITE_ELYTRA_MODE=playground`) — runs the studio + frontend
   only; no Convex.
 - **Connected** (`VITE_CONVEX_URL` set) — also runs `convex dev` (or deploys on
   build) once a deployment is provisioned (`CONVEX_DEPLOYMENT` present).
+- Any other `VITE_ELYTRA_MODE` value is the studio's boot error, and the CLI
+  names it the same way.
 
 It orchestrates and owns the process lifecycle; it does not reimplement Vite,
 Next, or Convex — each step shells out to the underlying tool and inherits its
@@ -119,20 +137,20 @@ set on the wrong plane:
      the AI provider key (`ANTHROPIC_API_KEY`, or the Vercel AI Gateway) for
      the studio's AI route — a host/server env, never `VITE_`-prefixed.
    - _Frontend project:_ `ELYTRA_CONVEX_URL`, `ELYTRA_PROJECT_ID`,
-     `REVALIDATE_SECRET`, `STUDIO_ORIGIN`, `DRAFT_PREVIEW_TOKEN` — see the
-     scaffold's CONNECT.md for what each pairs with.
+     `REVALIDATE_SECRET`, `DRAFT_PREVIEW_TOKEN` — see the scaffold's
+     CONNECT.md for what each pairs with.
 3. **Convex deployment env** — set with `npx convex env set` (from `studio/`);
    lives on the deployment itself, visible in the Convex dashboard but in no
    file: the auth signing keys (`JWT_PRIVATE_KEY`, `JWKS` — set via
-   `npx @convex-dev/auth`), `SITE_URL`, the instant-publish trio
-   `CANVAS_PROJECT_SCOPE` / `CANVAS_REVALIDATE_ENDPOINT` /
-   `CANVAS_REVALIDATE_SECRET`, and `DRAFT_PREVIEW_TOKEN` (each of the latter
-   four must match its frontend-plane counterpart). `elytra doctor` diagnoses
-   this plane's readiness.
+   `npx @convex-dev/auth`), `SITE_URL`, the instant-publish pair
+   `CANVAS_REVALIDATE_ENDPOINT` / `CANVAS_REVALIDATE_SECRET`, and
+   `DRAFT_PREVIEW_TOKEN` (the secret and the token must match their
+   frontend-plane counterparts). `elytra doctor` diagnoses this plane's
+   readiness.
 
 Because plane 3 lives in no file, it is the easiest to overlook — `elytra
 doctor` therefore enumerates the expected vars there (auth keys, `SITE_URL`,
-the instant-publish trio, the draft-preview token, plus the AI provider key
+the instant-publish pair, the draft-preview token, plus the AI provider key
 on the studio-host plane when the AI route is present) and reports each one
 **set or missing, by name only**: the doctor parses names out of `npx convex
 env list` and discards every value on the spot — values are never stored,
@@ -142,31 +160,28 @@ the draft-preview token) is a named warning that doesn't change the exit
 code. The studio's boot-time "Deployment setup" screen lists the same
 expected vars, so the CLI and the studio tell one story.
 
-The **instant-publish trio** — `CANVAS_PROJECT_SCOPE`,
-`CANVAS_REVALIDATE_ENDPOINT`, and `CANVAS_REVALIDATE_SECRET` — gets special
-treatment, because the publish path **silently no-ops** while any of the
-three is unset: `CANVAS_PROJECT_SCOPE` gates the write-chokepoint trigger
-that *schedules* the revalidate webhook (checked FIRST, before the pair is
-even consulted), and the pair then gates whether the scheduled webhook
-actually *delivers*. Either way, publishes never update the live site until
-a redeploy, with no error anywhere. All three missing is a warning carrying
-exactly that consequence (a project without a delivery frontend may
-legitimately leave them unset); **any partial subset — one or two of the
-three set — fails** the run, because a half-configured trio has no
+The **instant-publish pair** — `CANVAS_REVALIDATE_ENDPOINT` and
+`CANVAS_REVALIDATE_SECRET` — gets special treatment, because the publish path
+**silently no-ops** while either is unset: the write-chokepoint trigger
+schedules the revalidate webhook, and the action delivers it, only while both
+are set. Publishes then never update the live site until a redeploy, with no
+error anywhere. Both missing is a warning carrying exactly that consequence (a
+project without a delivery frontend may legitimately leave them unset); **one
+of the two set fails** the run, because a half-configured pair has no
 legitimate reading (documented together in the scaffold's CONNECT.md, set in
 one shell block, so a partial state is far more likely an interrupted setup
-than a deliberate choice). When the pair (`CANVAS_REVALIDATE_ENDPOINT` +
-`CANVAS_REVALIDATE_SECRET`) IS set, the doctor goes one step further and
-proves the chain end to end: it POSTs a **signed no-op ping** (an empty tag
-list — the route revalidates nothing) to the endpoint. A 200
-`{"revalidated":[]}` passes (endpoint reachable, and the frontend's
-`REVALIDATE_SECRET` matches); a 401 fails as a secret mismatch between
-Convex and the frontend host; a network error only warns (unreachable from
-your machine is not the same as broken — Convex may still reach it). The
-pair's values are read in-process for the ping only and never printed. The
-ping proves only the pair's reachability/secret-match, not scheduling — a
-missing `CANVAS_PROJECT_SCOPE` still fails its own row (and the run)
-independently, even when the ping passes.
+than a deliberate choice). When the pair IS set, the doctor goes one step
+further and proves the chain end to end: it POSTs a **signed no-op ping** (the
+`probe` event — the one event that derives no cache tags) to the endpoint. A
+200 `{"revalidated":[]}` passes (endpoint reachable, the frontend's
+`REVALIDATE_SECRET` matches, and the frontend speaks this engine's event
+wire); a 401 fails as a secret mismatch between Convex and the frontend host;
+a 400 fails as a version skew (the frontend runs a different Elytra version);
+a network error only warns (unreachable from your machine is not the same as
+broken — Convex may still reach it). The pair's values are read in-process
+for the ping only and never printed. (There is no third, scope var any more:
+the webhook carries the event, and the frontend derives its cache tags with
+its own `ELYTRA_PROJECT_ID`.)
 
 The **draft-preview token** — `DRAFT_PREVIEW_TOKEN` — gates the deployment's
 `draftSnapshot` query and must equal the frontend host's own
@@ -184,10 +199,14 @@ reports it: two routes that would match the exact same URLs fail the run with
 the offending ids and patterns named. Nothing about this needs a deployment —
 the check runs in playground mode too.
 
-The doctor reads the route set from your project's `cms/index.ts` (the
-`collections` + `routes` your `elytra.config.ts` passes through). That tree is
-plain, React-free TypeScript by convention, so the CLI imports it natively —
-no bundler, no Vite, no dev server. Two consequences worth knowing:
+When the studio's deps are installed, the doctor executes `elytra.config.ts`
+through the studio's own Vite and judges the routes it resolved — exactly what
+the studio and delivery serve. Without them it falls back to reading your
+project's `cms/index.ts` natively (the `collections` + `routes` the scaffold's
+`elytra.config.ts` passes through), and the `route-conflicts` row says which
+of the two it judged. That tree is plain, React-free TypeScript by convention,
+so the CLI imports it natively — no bundler, no Vite, no dev server. Two
+consequences of the fallback worth knowing:
 
 - It needs a Node that runs TypeScript natively (**≥22.18**). On an older Node
   the check reports "not checked here" and names the version — never a false

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.88",
+  "version": "0.0.91",
   "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.88"
+    "@elytracms/core": "^0.0.91"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -1,7 +1,7 @@
 import { spawnSync } from 'node:child_process'
-import { join } from 'node:path'
 import { stdout } from 'node:process'
 import { resolveInstalledEngineVersion, runDoctor } from './doctor.js'
+import { appDisplay } from './layout.js'
 import { runPreviews } from './previews.js'
 import { inspectProject, resolveStudioEnv } from './project.js'
 import { ensureAuthKeys } from './provision.js'
@@ -29,10 +29,11 @@ Commands:
              values never shown — config, membership) and print each fix. When the
              instant-publish revalidate pair is set, also sends a signed no-op ping
              to the endpoint to prove the publish → live chain end to end. Also
-             checks your cms/ routes for URL conflicts, and reports the
-             generated-previews artifacts (manifest/files present; hash staleness
-             lives in \`elytra previews --check\`). Exit non-zero if any check
-             fails. Read-only. Optional: --url <convex url>.
+             checks your routes for URL conflicts, the project layout
+             (package.json#elytra), the AI route your studio's vite.config.ts
+             mounts, and reports the generated-previews artifacts (manifest/files
+             present; hash staleness lives in \`elytra previews --check\`). Exit
+             non-zero if any check fails. Read-only. Optional: --url <convex url>.
   previews   Render every canvas-eligible component's fixtures against YOUR theme
              (headless Chromium via Playwright — an optional install) and write
              committed preview images (studio/public/elytra-previews/) plus an
@@ -47,6 +48,13 @@ Commands:
 Run from anywhere inside an Elytra project (a directory with elytra.config.ts).
 Any subcommand accepts --help/-h for its own usage (never does the command's work).
 
+Layout: the studio app, frontend app and theme are found at studio/, frontend/
+and components/theme.css by default. A project laid out differently declares
+its paths in the repo-root package.json:
+  "elytra": { "studio": "./apps/editor", "frontend": "./apps/site",
+              "theme": "./styles/site.css" }
+Every key is optional; a declared path that does not exist is reported.
+
 Dev ports: studio 5180, frontend 3000 by default. Set ELYTRA_DEV_PORT_OFFSET in
 studio/.env to shift BOTH together (e.g. to run a second Elytra project alongside
 this one without a clash) — 'elytra dev' forwards it to both processes.
@@ -111,16 +119,20 @@ Diagnose the active deployment's readiness (URL, reachability, auth signing
 keys, expected deployment env vars — set/missing by NAME, values never shown
 — config, membership) and print each fix. When the instant-publish
 revalidate pair is set, also sends a signed no-op ping to the endpoint to
-prove the publish → live chain end to end. Also checks the route set in your
-cms/ for URL conflicts (routes are code — redirect loops are editorial data
-and are checked in the studio), and reports the generated-previews artifacts
+prove the publish → live chain end to end. Also checks your route set for
+URL conflicts (routes are code — redirect loops are editorial data and are
+checked in the studio), and reports the generated-previews artifacts
 (manifest/files present; hash staleness lives in \`elytra previews --check\`).
 With studio/ deps installed, config validity is checked for real: doctor
 executes elytra.config.ts through your studio's own Vite (takes a few
-seconds); without deps it stays an honest "unknown" with the reason. With
-the config resolved, it also reads the public delivery snapshot and warns
-about published documents whose collection the config does not declare.
-Exit non-zero if any check fails. Read-only.
+seconds), and the route checks judge the routes it resolved; without deps
+it stays an honest "unknown" with the reason and the routes are read from
+cms/index.ts. With the config resolved, it also reads the public delivery
+snapshot and warns about published documents whose collection the config
+does not declare. It reports the project layout it resolved
+(package.json#elytra — a declared path that does not exist fails) and the AI
+route your studio's vite.config.ts mounts (which decides whether an AI
+provider key is expected). Exit non-zero if any check fails. Read-only.
 
 Options:
   --url <convex url>   Diagnose this deployment instead of the one resolved
@@ -175,6 +187,15 @@ function reportIssues(issues) {
   for (const issue of issues) log(`  • ${issue}`)
 }
 
+/**
+ * The resolved directory of an app (EC-603) — from `package.json#elytra`, else the
+ * scaffold default, as `inspectProject` resolved it. The ONE place a command learns
+ * where to spawn; no command joins a conventional directory name itself.
+ */
+function appDir(project, key) {
+  return project.layout.entries[key].path
+}
+
 /**
  * Build the dev process group from a project inspection. `convex dev` (the continuous
  * dev-sync watcher — it pushes local function code to the target on every save) is only
@@ -191,8 +212,8 @@ function reportIssues(issues) {
  */
 export function planDev(project) {
   const procs = []
-  const studioDir = join(project.root, 'studio')
-  const frontendDir = join(project.root, 'frontend')
+  const studioDir = appDir(project, 'studio')
+  const frontendDir = appDir(project, 'frontend')
   const offset = Number(project.devPortOffset ?? 0) || 0
   // The studio's `vite.config.ts` resolves the offset itself, in JS (`loadEnv`) —
   // portable anywhere, so forward the lever as-is.
@@ -254,8 +275,8 @@ function couplesConvexDeploy(project) {
  */
 export function planBuild(project, target) {
   const steps = []
-  const studioDir = join(project.root, 'studio')
-  const frontendDir = join(project.root, 'frontend')
+  const studioDir = appDir(project, 'studio')
+  const frontendDir = appDir(project, 'frontend')
   const studioBuild = { name: 'studio build', command: 'pnpm', args: ['run', 'build'], cwd: studioDir }
   const frontendBuild = { name: 'frontend build', command: 'pnpm', args: ['run', 'build'], cwd: frontendDir }
 
@@ -299,6 +320,8 @@ export function planBuild(project, target) {
  * (EC-356) is unit-testable without going through `run()`'s process-spawning commands.
  */
 export function describeMode(project) {
+  // EC-603: the studio's location as the project laid it out (`studio/` by default).
+  const studio = appDisplay(project.layout, 'studio')
   if (project.mode === 'playground') {
     return 'Mode: playground (in-memory, no backend). Convex is not started.'
   }
@@ -307,19 +330,24 @@ export function describeMode(project) {
       'Mode: connected to a `prod:` Convex deployment. `convex dev` (the continuous dev-sync\n' +
       'watcher, which pushes local function code on every save) is never started against\n' +
       'production. Studio and frontend still start and talk to it over the client SDK. To push\n' +
-      'function changes, deploy explicitly: `cd studio && npx convex deploy`.'
+      `function changes, deploy explicitly: \`cd ${studio} && npx convex deploy\`.`
     )
   }
   if (project.mode === 'connected' && !project.convexProvisioned) {
     return (
       'Mode: connected, but no Convex deployment is provisioned yet. Skipping the\n' +
-      'backend — run `cd studio && npx convex dev` once to provision it. See CONNECT.md.'
+      `backend — run \`cd ${studio} && npx convex dev\` once to provision it. See CONNECT.md.`
     )
   }
   if (project.mode === 'unconfigured') {
+    // EC-603: an unknown mode is the studio's own boot error — say it in its words, so
+    // the CLI and the studio never disagree about what is wrong.
+    if (project.backend?.kind === 'misconfigured' && project.backend.reason === 'unknown-mode') {
+      return `Backend misconfigured: ${project.backend.detail} (read from ${studio}/.env*). The studio will not boot until it is fixed.`
+    }
     return (
       'Backend not configured. Defaulting to the frontends only. Set VITE_ELYTRA_MODE=\n' +
-      'playground or VITE_CONVEX_URL in studio/.env. See CONNECT.md.'
+      `playground or VITE_CONVEX_URL in ${studio}/.env. See CONNECT.md.`
     )
   }
   return null
@@ -335,6 +363,11 @@ export function describeMode(project) {
  */
 export function describeBuildMode(project, target) {
   if (target === 'frontend') return null
+  // EC-603: an unknown mode is named before anything else — a deploy key does not make
+  // a studio that will refuse to boot any less broken.
+  if (project.backend?.kind === 'misconfigured' && project.backend.reason === 'unknown-mode') {
+    return describeMode(project)
+  }
   if (
     target === 'studio' &&
     project.mode !== 'playground' &&
@@ -369,14 +402,21 @@ function provisionConvexOnce(studioDir) {
  * decisions mirror {@link planSetup}; `provision`/`exec`/`fetchImpl` are injectable.
  */
 export async function runInit(project, { log: emit = log, fetchImpl, exec, provision = provisionConvexOnce } = {}) {
-  const studioDir = join(project.root, 'studio')
+  const studioDir = appDir(project, 'studio')
+  const studio = appDisplay(project.layout, 'studio')
   emit('Elytra first-run setup')
   emit('')
 
   // 1. Provision a backend deployment.
   if (project.mode === 'unconfigured') {
+    // EC-603: an unknown mode is named in the studio's own words, never as "not configured".
+    if (project.backend?.kind === 'misconfigured' && project.backend.reason === 'unknown-mode') {
+      emit(`1. Provision — cannot continue: ${project.backend.detail}`)
+      emit(`   Fix it in ${studio}/.env (or .env.local). See CONNECT.md.`)
+      return 1
+    }
     emit('1. Provision — cannot continue: no backend configured.')
-    emit('   Set VITE_CONVEX_URL, or VITE_ELYTRA_MODE=playground, in studio/.env. See CONNECT.md.')
+    emit(`   Set VITE_CONVEX_URL, or VITE_ELYTRA_MODE=playground, in ${studio}/.env. See CONNECT.md.`)
     return 1
   }
   if (project.mode === 'playground') {
@@ -395,14 +435,14 @@ export async function runInit(project, { log: emit = log, fetchImpl, exec, provi
     // selector is present some other way (e.g. CONVEX_DEPLOY_KEY) — provisioning via the
     // dev-sync watcher (`convex dev --once`) is never safe to run against it automatically.
     emit('1. Provision — cannot continue safely: a prod: selector is set, but no deployment is linked here.')
-    emit('   Provisioning via `convex dev` is skipped against production. Link and deploy explicitly: `cd studio && npx convex deploy`.')
+    emit(`   Provisioning via \`convex dev\` is skipped against production. Link and deploy explicitly: \`cd ${studio} && npx convex deploy\`.`)
     return 1
   } else {
     emit('1. Provision — provisioning a Convex deployment (convex dev --once)…')
     const code = provision(studioDir)
     const reinspected = inspectProject(project.root)
     if (code !== 0 || !reinspected.convexProvisioned) {
-      emit('   Provisioning did not complete. Run `cd studio && npx convex dev` once, then re-run `elytra init`.')
+      emit(`   Provisioning did not complete. Run \`cd ${studio} && npx convex dev\` once, then re-run \`elytra init\`.`)
       return 1
     }
     project = reinspected
@@ -427,11 +467,11 @@ export async function runInit(project, { log: emit = log, fetchImpl, exec, provi
   // 3. Verify readiness (the shared elytra doctor check).
   emit('')
   emit('3. Verify —')
-  const env = resolveStudioEnv(project.root)
+  const env = resolveStudioEnv(project)
   // EC-552: with the studio dir known, the verify step includes the version
   // handshake — right after a provision is exactly when a stale-functions state
   // should be loud. Resolution happens HERE (the entry), keeping runDoctor injected.
-  const verifyStudioDir = project.apps.studio ? join(project.root, 'studio') : undefined
+  const verifyStudioDir = project.apps.studio ? appDir(project, 'studio') : undefined
   const code = await runDoctor({
     env,
     fetchImpl,
@@ -481,22 +521,23 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       reportIssues(project.issues)
       return 1
     }
-    const studioEnv = resolveStudioEnv(project.root, env)
-    const doctorStudioDir = project.apps.studio ? join(project.root, 'studio') : undefined
+    const studioEnv = resolveStudioEnv(project, env)
+    const doctorStudioDir = project.apps.studio ? appDir(project, 'studio') : undefined
     return runDoctor({
       env: studioEnv,
       fetchImpl,
       log: emit,
       url: flagValue(argv, '--url'),
-      // EC-399: where `convex env list` runs (name enumeration — presence only),
-      // and whether the AI provider-key expectation applies.
+      // EC-399: where `convex env list` runs (name enumeration — presence only).
+      // EC-603: also where the AI route is read from — the studio's own Vite config.
       studioDir: doctorStudioDir,
       // EC-552: the installed engine version — resolved at the entry so runDoctor
       // stays pure/injected; unresolvable (deps not installed) → honest `unknown`.
       installedEngineVersion: resolveInstalledEngineVersion(doctorStudioDir),
       // EC-469: where the project's `cms/` route set is read from (code, not backend).
       root: project.root,
-      aiRouteConfigured: project.hasAiRoute,
+      // EC-603: the resolved package.json#elytra layout — reported as `project-layout`.
+      layout: project.layout,
       exec,
     })
   }
@@ -519,7 +560,9 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       return 1
     }
     if (!project.apps.studio) {
-      log('No studio/ app found — `elytra previews` renders through the studio app’s Vite.')
+      log(
+        `No studio app found at ${appDisplay(project.layout, 'studio')}/ — \`elytra previews\` renders through the studio app’s Vite.`,
+      )
       return 1
     }
     return runPreviews(project, {
@@ -544,7 +587,9 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
     return 1
   }
 
-  const project = inspectProject(cwd, env)
+  // EC-603: read the studio env files of the Vite mode the spawned studio runs in —
+  // `vite build` reads `.env.production*`, `vite dev` `.env.development*`.
+  const project = inspectProject(cwd, env, { viteMode: command === 'build' ? 'production' : 'development' })
   if (project.issues.length > 0) {
     reportIssues(project.issues)
     return 1
@@ -557,14 +602,14 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
     // backend (idempotent — a no-op when they're already set). Never blocks dev.
     if (project.mode === 'connected' && project.convexProvisioned) {
       try {
-        ensureAuthKeys({ cwd: join(project.root, 'studio'), exec, log: (l) => log(`[setup] ${l}`) })
+        ensureAuthKeys({ cwd: appDir(project, 'studio'), exec, log: (l) => log(`[setup] ${l}`) })
       } catch (error) {
         log(`[setup] auth-keys preflight skipped: ${error.message}`)
       }
     }
     const procs = planDev(project)
     if (procs.length === 0) {
-      log('Nothing to run — no studio/ or frontend/ app found.')
+      log(`Nothing to run — no ${appDisplay(project.layout, 'studio')}/ or ${appDisplay(project.layout, 'frontend')}/ app found.`)
       return 1
     }
     log('Starting (Ctrl-C to stop everything)…\n')
@@ -576,8 +621,8 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
   if (steps.length === 0) {
     log(
       target
-        ? `Nothing to build — no ${target}/ app found.`
-        : 'Nothing to build — no studio/ or frontend/ app found.',
+        ? `Nothing to build — no ${appDisplay(project.layout, target)}/ app found.`
+        : `Nothing to build — no ${appDisplay(project.layout, 'studio')}/ or ${appDisplay(project.layout, 'frontend')}/ app found.`,
     )
     return 1
   }

package/src/config-harness.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { createServer as createNetServer } from 'node:net'
-import { join } from 'node:path'
+import { join, relative, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 /**
@@ -21,6 +21,11 @@ import { pathToFileURL } from 'node:url'
  * config by `/@fs/` path, and `ssrLoadModule`s them node-side. The consumer's
  * own toolchain does the executing; the CLI never grows a bundler dependency.
  *
+ * EC-603 adds one READ of the studio's own `vite.config.ts` — evaluated through
+ * Vite's `loadConfigFromFile`, never used to boot anything — solely to learn the
+ * AI route it mounts ({@link readStudioAiRoute}); the harness boot above still
+ * never loads it.
+ *
  * Everything here is opportunistic by contract: the CLI works without
  * installed deps (`cli.js` — doctor is not blocked by a missing
  * node_modules), so every "can't" degrades to a reason string, never a crash.
@@ -227,7 +232,8 @@ export function configHarnessPrecondition({ configPath, studioDir, exists, resol
       kind: 'unavailable',
       reason:
         `No studio/ app found — doctor executes ${CONFIG_FILE} through the studio app's own Vite; ` +
-        'the studio boot and `elytra build` validate it too.',
+        'the studio boot and `elytra build` validate it too. (A studio laid out elsewhere is declared in ' +
+        'package.json#elytra.studio.)',
     }
   }
   for (const dep of REQUIRED_CONSUMER_DEPS) {
@@ -237,7 +243,7 @@ export function configHarnessPrecondition({ configPath, studioDir, exists, resol
       return {
         kind: 'unavailable',
         reason:
-          `The studio's dependencies are not installed (${dep} could not be resolved from studio/) — ` +
+          `The studio's dependencies are not installed (${dep} could not be resolved from the studio app) — ` +
           'run `pnpm install`, then re-run `elytra doctor` for a real config check.',
       }
     }
@@ -245,6 +251,170 @@ export function configHarnessPrecondition({ configPath, studioDir, exists, resol
   return null
 }
 
+// --- The AI route, from the studio's resolved Vite config (EC-603) -------------------
+
+/**
+ * The AI dev plugin's `name` (`@elytracms/studio/lib/ai/vite`'s `AI_ROUTE_PLUGIN_NAME`).
+ * Mirrored as a literal because the CLI must not import the studio package; the
+ * plugin's own test pins the value, and this module's test pins the mirror against it.
+ */
+export const AI_ROUTE_PLUGIN_NAME = 'elytra-ai-route'
+
+/**
+ * Load the studio app's OWN Vite config the way Vite itself does — Vite's discovery of
+ * `vite.config.*` in the studio root, via the consumer's installed `vite`
+ * (`loadConfigFromFile`, the documented API). That evaluates the config module and its
+ * plugin factories only: no server, no `configResolved`/`buildStart` hooks, no route
+ * generation. Measured 2026-10-25 on `apps/demo/studio` and a scaffold-shaped studio:
+ * no file written outside Vite's own `node_modules/.vite-temp` bundle, 0.2–0.9 s.
+ * `null` when the studio has no Vite config file.
+ */
+export async function loadStudioViteConfig(studioDir) {
+  const vite = await import(pathToFileURL(resolveFromDir(studioDir, 'vite')).href)
+  return vite.loadConfigFromFile(
+    { command: 'serve', mode: 'development', isSsrBuild: false, isPreview: false },
+    undefined,
+    studioDir,
+    'silent',
+  )
+}
+
+/** Flatten a Vite `plugins` option (nested arrays, promises, falsy entries) into plugin objects. */
+export async function flattenPlugins(option) {
+  const out = []
+  const walk = async (value) => {
+    const resolved = await value
+    if (!resolved) return
+    if (Array.isArray(resolved)) {
+      for (const item of resolved) await walk(item)
+      return
+    }
+    out.push(resolved)
+  }
+  await walk(option)
+  return out
+}
+
+/**
+ * PURE decision core: the AI-route fact from a loaded Vite config (`loaded` is
+ * `loadConfigFromFile`'s result, or `null` for no config file).
+ *
+ * The route is read from the declaration that MOUNTS it — `createAiDevPlugin({
+ * handlerModulePath, route })` in the studio's Vite config — never guessed from a fixed
+ * file path (the old `studio/src/server/ai-handler.ts` probe, RATIFIED away by EC-603).
+ * Its presence means this project serves its own AI route, whose handler is what reads
+ * the provider key — so it is what decides the doctor's AI-key expectation. The studio
+ * config's `ai` block was measured too and rejected as the source: nothing declares
+ * where that file lives (the studio entry imports it — Konditorei keeps it at
+ * `studio/src/studio.config.tsx`, the scaffold at `studio/studio.config.tsx`), so
+ * reading it would need exactly the fixed path the ruling forbids.
+ *
+ * Returns one of
+ *   - `{ kind: 'mounted', source, route?, handlerModulePath?, handlerPath?, handlerExists? }`
+ *     — the plugin is configured; the route details are present when the installed
+ *     engine exposes them on the plugin's `api` (EC-603+), and `handlerExists` says
+ *     whether the module it will `ssrLoadModule` exists;
+ *   - `{ kind: 'none', source }` — a Vite config without the plugin (`source: null`
+ *     when the studio has no Vite config file at all).
+ */
+export function aiRouteFromViteConfig({ studioDir, loaded, plugins, exists = existsSync }) {
+  const source = loaded?.path ? relative(studioDir, loaded.path).split(sep).join('/') : null
+  const plugin = plugins.find((p) => p && p.name === AI_ROUTE_PLUGIN_NAME)
+  if (!plugin) return { kind: 'none', source }
+  const declared = plugin.api?.elytraAiRoute
+  if (!declared || typeof declared.handlerModulePath !== 'string') return { kind: 'mounted', source }
+  const { route, handlerModulePath } = declared
+  // Vite resolves a `/`-prefixed id against its root first, then as an absolute fs path.
+  const candidates = handlerModulePath.startsWith('/')
+    ? [join(studioDir, handlerModulePath), handlerModulePath]
+    : [resolve(studioDir, handlerModulePath)]
+  const handlerPath = candidates.find((candidate) => exists(candidate)) ?? candidates[0]
+  return {
+    kind: 'mounted',
+    source,
+    route,
+    handlerModulePath,
+    handlerPath,
+    handlerExists: candidates.some((candidate) => exists(candidate)),
+  }
+}
+
+/**
+ * Read the studio's AI route from its resolved Vite config (EC-603). Never throws:
+ * every "can't" is `{ kind: 'unavailable', reason }` → the doctor's `ai-route` row is an
+ * honest `unknown` and no AI-key expectation is added (a fact not established is not
+ * assumed — and never re-guessed from a file path).
+ */
+export async function readStudioAiRoute({ studioDir, exists = existsSync, loadConfig = loadStudioViteConfig } = {}) {
+  if (!studioDir || !exists(join(studioDir, 'package.json'))) {
+    return { kind: 'unavailable', reason: 'No studio app found — the AI route was not determined here.' }
+  }
+  let loaded
+  try {
+    loaded = await loadConfig(studioDir)
+  } catch (error) {
+    return {
+      kind: 'unavailable',
+      reason: `The studio's Vite config could not be loaded (${errorSummary(error)}) — the AI route was not determined here.`,
+    }
+  }
+  try {
+    const plugins = await flattenPlugins(loaded?.config?.plugins)
+    return aiRouteFromViteConfig({ studioDir, loaded, plugins, exists })
+  } catch (error) {
+    return {
+      kind: 'unavailable',
+      reason: `The studio's Vite plugins could not be read (${errorSummary(error)}) — the AI route was not determined here.`,
+    }
+  }
+}
+
+/**
+ * The doctor's `ai-route` row (pure, `app` bucket): which AI route the studio mounts, read
+ * from where — so the AI-key expectation in the deployment-env bucket is never a mystery.
+ * `fail` only when the config mounts a handler module that does not exist (every request
+ * to the route answers 500 — deterministic in the repo); otherwise `ok` or `unknown`.
+ */
+export function aiRouteDoctorChecks(aiRoute, { studioLabel = 'studio' } = {}) {
+  if (!aiRoute) return []
+  const base = { id: 'ai-route', bucket: 'app' }
+  if (aiRoute.kind === 'unavailable') return [{ ...base, status: 'unknown', detail: aiRoute.reason }]
+  const where = aiRoute.source ? `${studioLabel}/${aiRoute.source}` : `${studioLabel}/ (no Vite config file)`
+  if (aiRoute.kind === 'none') {
+    return [
+      {
+        ...base,
+        status: 'ok',
+        detail: `No AI route is mounted (${where} has no createAiDevPlugin) — no AI provider key is expected.`,
+      },
+    ]
+  }
+  if (aiRoute.handlerExists === false) {
+    return [
+      {
+        ...base,
+        status: 'fail',
+        detail:
+          `${where} mounts the AI route${aiRoute.route ? ` at ${aiRoute.route}` : ''} with handlerModulePath ` +
+          `"${aiRoute.handlerModulePath}", but that module does not exist — every request to the route answers 500.`,
+        fix:
+          'Point createAiDevPlugin({ handlerModulePath }) at your handler module (Vite-root-relative, ' +
+          "e.g. '/src/server/ai-handler.ts'), or remove the plugin to ship without AI.",
+      },
+    ]
+  }
+  const details = aiRoute.handlerModulePath
+    ? ` (${aiRoute.route ?? 'its route'} → ${aiRoute.handlerModulePath})`
+    : ''
+  return [
+    {
+      ...base,
+      status: 'ok',
+      detail: `The studio mounts its AI route${details}, read from ${where} — the AI provider-key expectation applies.`,
+    },
+  ]
+}
+
 /** An error's message, newline-collapsed and capped — legible in a one-line report row, never a stack dump. */
 function errorSummary(error) {
   const message = error instanceof Error ? error.message : String(error)