@elytracms/cli 0.0.88 → 0.0.91

package/src/doctor.js

@@ -6,14 +6,17 @@ import {
   REVALIDATE_ENV_ENDPOINT,
   REVALIDATE_ENV_SECRET,
   backendSiteUrl,
+  backendUrlOf,
   checkDeploymentReady,
   expectedDeploymentEnv,
+  parseBackendMode,
   probeAuthSigningKeys,
   probeDeliverySnapshot,
   probeDeployedFunctionsVersion,
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
-import { executeWorkspaceConfig } from './config-harness.js'
+import { aiRouteDoctorChecks, executeWorkspaceConfig, readStudioAiRoute } from './config-harness.js'
+import { appDisplay, layoutDoctorChecks } from './layout.js'
 import { convexEnvGet, defaultConvexExec } from './provision.js'
 import { gatherPreviewsArtifacts, previewsDoctorChecks } from './previews.js'
 import { loadProjectRoutes, routesDoctorChecks } from './routes-check.js'
@@ -40,17 +43,29 @@ import { loadProjectRoutes, routesDoctorChecks } from './routes-check.js'
 /**
  * Decide which deployment the doctor diagnoses from the resolved studio env.
  *
- * A configured `VITE_CONVEX_URL` is preferred over the `VITE_ELYTRA_MODE=playground`
- * run-mode flag: that flag only selects the studio's in-memory *adapter*, whereas the
- * doctor's job is to validate the real deployment you configured. So a repo that runs
+ * The mode is judged by the ONE parser the studio runs (core's `parseBackendMode`,
+ * EC-603), so a padded flag is playground here exactly as it is in the studio, and an
+ * unknown mode is the studio's own boot error — a failing `backend-url` naming the
+ * value, never silently overridden by a URL beside it.
+ *
+ * A configured `VITE_CONVEX_URL` is preferred over a VALID `VITE_ELYTRA_MODE=playground`
+ * flag: that flag only selects the studio's in-memory *adapter*, whereas the doctor's
+ * job is to validate the real deployment you configured. So a repo that runs
  * playground locally but points at a Convex deployment (e.g. the demo) is diagnosed
- * against that deployment — with a note that the studio itself runs in-memory.
+ * against that deployment — with a note that the studio itself runs in-memory. An
+ * explicit `--url` diagnoses that deployment whatever the env says.
+ *
+ * `envSource` names where the env was read, for the unconfigured detail (`studio/.env`).
  */
-export function resolveDoctorTarget(env = {}, { url } = {}) {
+export function resolveDoctorTarget(env = {}, { url, envSource = 'studio/.env' } = {}) {
   const explicit = url && url.trim() !== '' ? url.trim() : undefined
-  const envUrl = env.VITE_CONVEX_URL || env.CONVEX_URL
+  const backend = parseBackendMode(env)
+  if (!explicit && backend.kind === 'misconfigured' && backend.reason === 'unknown-mode') {
+    return { kind: 'unconfigured', detail: `${backend.detail} (in ${envSource})` }
+  }
+  const envUrl = backendUrlOf(env)
   const chosenUrl = explicit || envUrl
-  const playgroundFlag = env.VITE_ELYTRA_MODE === 'playground'
+  const playgroundFlag = backend.kind === 'playground'
 
   if (chosenUrl) {
     return {
@@ -67,7 +82,7 @@ export function resolveDoctorTarget(env = {}, { url } = {}) {
   if (playgroundFlag) return { kind: 'playground' }
   return {
     kind: 'unconfigured',
-    detail: 'No VITE_CONVEX_URL is set, and VITE_ELYTRA_MODE is not "playground", in studio/.env.',
+    detail: `No VITE_CONVEX_URL is set, and VITE_ELYTRA_MODE is not "playground", in ${envSource}.`,
   }
 }
 
@@ -345,7 +360,7 @@ export function gatherDeploymentEnvFacts({ env = {}, target, studioDir, aiRouteC
     facts.unavailableDetail =
       '--url overrides the linked deployment; env names are only read from the deployment this repo is linked to.'
   } else if (!studioDir) {
-    facts.unavailableDetail = 'No studio/ app found — deployment env names not enumerated.'
+    facts.unavailableDetail = 'No studio app found — deployment env names not enumerated.'
   } else if (!env.CONVEX_DEPLOYMENT && !env.CONVEX_DEPLOY_KEY) {
     facts.unavailableDetail =
       'No linked deployment (CONVEX_DEPLOYMENT / CONVEX_DEPLOY_KEY unset) — `npx convex env list` needs one.'
@@ -360,10 +375,10 @@ export function gatherDeploymentEnvFacts({ env = {}, target, studioDir, aiRouteC
 // --- Signed revalidate ping (EC-421) -------------------------------------------
 //
 // When the presence checks say the instant-publish pair IS set, the doctor proves the
-// chain end to end: a POST to the endpoint signed with the secret, carrying an EMPTY
-// tag list — by the receiving route's own semantics a harmless no-op answering 200
-// `{"revalidated":[]}`. Default-on (no flag): the ping is read-only in effect and the
-// silent-failure class it catches (secret mismatch — publishes rejected with 401
+// chain end to end: a POST to the endpoint signed with the secret, carrying the `probe`
+// event (EC-579), which derives no cache tags — by the receiving route's own semantics a
+// harmless no-op answering 200 `{"revalidated":[]}`. Default-on (no flag): the ping is
+// read-only in effect and the silent-failure class it catches (secret mismatch — publishes rejected with 401
 // forever, no error anywhere) is exactly what the doctor exists for.
 //
 // The ping needs the pair's VALUES — the one sanctioned value read: captured
@@ -459,6 +474,96 @@ export function formatReport(report) {
   return lines.join('\n')
 }
 
+/**
+ * The route set the doctor's route checks judge (EC-603, RESIDUE-4): the RESOLVED
+ * config's routes + collections when the harness resolved it validly — the same records
+ * the studio mounts and delivery serves, whatever file they were declared in — else the
+ * native `cms/index.ts` floor ({@link loadProjectRoutes}, or the injected `routeFacts`),
+ * with the resolved collections swapped in when there are some. `source` says which, so
+ * the report can. Never throws.
+ */
+export async function routeFactsFor({ outcome, configFacts = {}, routeFacts, root }) {
+  const project = resolvedProjectOf(outcome)
+  if (project && Array.isArray(project.routes)) {
+    return {
+      routes: project.routes,
+      routeCount: project.routes.length,
+      ...(Array.isArray(project.collections) ? { collections: project.collections } : {}),
+      source: 'config',
+    }
+  }
+  const loaded = routeFacts ?? (await loadProjectRoutes(root))
+  const enriched = configFacts.collections ? { ...loaded, collections: configFacts.collections } : loaded
+  return { ...enriched, source: 'native' }
+}
+
+// --- Frontend: `cacheComponents` (EC-515) --------------------------------------
+
+/** The `next.config` file names Next itself resolves, in its order. */
+export const NEXT_CONFIG_FILES = ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.mts', 'next.config.cjs']
+
+/**
+ * Read the frontend's `next.config` for the `cacheComponents` check — the file name and
+ * its text, or `{ configFile: null }` when the app has none. `undefined` when there is no
+ * frontend app to read (a studio-only repo: no row at all). Text only: the CLI runs
+ * without the consumer's `node_modules`, and a `next.config` imports Next-side modules.
+ * `readFile` is injectable for tests.
+ */
+export function gatherFrontendCacheComponents(frontendDir, readFile = (p) => readFileSync(p, 'utf8')) {
+  if (!frontendDir) return undefined
+  for (const name of NEXT_CONFIG_FILES) {
+    try {
+      return { configFile: name, text: readFile(join(frontendDir, name)) }
+    } catch {
+      // not this name — try the next
+    }
+  }
+  return { configFile: null, text: '' }
+}
+
+/**
+ * The `frontend-cache-components` row (`app` bucket). Since EC-515 the delivery kit's
+ * cache is a `'use cache'` entry, which Next compiles only with `cacheComponents: true`
+ * — without it `next build` fails under both bundlers (measured: "To use "use cache",
+ * please enable the feature flag `cacheComponents`"). So a missing flag is a `fail`:
+ * deterministic in the repo, and the build would fail anyway — so is a literal `false`. A
+ * `cacheComponents` key that is neither literal (computed from env, say) is a `warn` —
+ * the doctor reads text and cannot evaluate it. No frontend → no row. Pure.
+ */
+export function cacheComponentsDoctorChecks(facts, { frontendLabel = 'frontend' } = {}) {
+  if (!facts) return []
+  const base = { id: 'frontend-cache-components', bucket: 'app' }
+  const fix = `Set \`cacheComponents: true\` in ${frontendLabel}/next.config.mjs, and export \`generateStaticParams = route.generateStaticParams\` from the canvas catch-all page (see the upgrading notes for EC-515).`
+  if (facts.configFile === null) {
+    return [{ ...base, status: 'fail', detail: `${frontendLabel} has no next.config — the delivery kit needs \`cacheComponents: true\`.`, fix }]
+  }
+  const where = `${frontendLabel}/${facts.configFile}`
+  if (/\bcacheComponents\s*:\s*true\b/.test(facts.text)) {
+    return [{ ...base, status: 'ok', detail: `${where} enables \`cacheComponents\` (the kit's 'use cache' delivery cache).` }]
+  }
+  if (/\bcacheComponents\s*:\s*false\b/.test(facts.text)) {
+    return [{ ...base, status: 'fail', detail: `${where} sets \`cacheComponents: false\` — \`next build\` fails on the delivery kit's 'use cache' cache.`, fix }]
+  }
+  if (/\bcacheComponents\b/.test(facts.text)) {
+    return [
+      {
+        ...base,
+        status: 'warn',
+        detail: `${where} sets \`cacheComponents\` to something other than the literal \`true\` — the doctor cannot evaluate it. \`next build\` fails if it is not true.`,
+        fix,
+      },
+    ]
+  }
+  return [
+    {
+      ...base,
+      status: 'fail',
+      detail: `${where} does not enable \`cacheComponents\` — \`next build\` fails on the delivery kit's 'use cache' cache.`,
+      fix,
+    },
+  ]
+}
+
 // --- Command -----------------------------------------------------------------
 
 /**
@@ -502,6 +607,25 @@ export function formatReport(report) {
  * published documents whose collection the resolved config does not declare — read
  * from the public delivery snapshot ({@link gatherPublishedOrphans}). A `warn` at most,
  * so the exit code never changes; without a resolved config it is an honest `unknown`.
+ *
+ * EC-603: three more facts, all read from DECLARATIONS rather than fixed paths:
+ *  - `layout` (the CLI entry passes `inspectProject`'s resolved `package.json#elytra`
+ *    layout) → the `project-layout` row: what was resolved, declared or defaulted, and a
+ *    `fail` for an invalid section or a declared path that does not exist;
+ *  - the AI route → read from the studio's own resolved Vite config
+ *    ({@link readStudioAiRoute}) when a `root` is known — it decides the AI-key
+ *    expectation and gets its own `ai-route` row. `aiRoute` (an outcome) and
+ *    `aiRouteConfigured` (a boolean) are test seams; without either and without a root
+ *    no AI expectation is added;
+ *  - the route checks run over the RESOLVED config's routes whenever the harness
+ *    resolved it (the routes the studio and delivery actually serve); the native
+ *    `cms/index.ts` read is the fallback only when it could not, and the row says which.
+ *
+ * EC-515: when the layout resolved a frontend app, the `app` bucket reports
+ * `frontend-cache-components` — whether its `next.config` enables `cacheComponents`,
+ * which the delivery kit's `'use cache'` cache requires ({@link
+ * cacheComponentsDoctorChecks}). `frontendCacheComponents` (the gathered facts) is the
+ * test seam.
  */
 export async function runDoctor({
   env = {},
@@ -510,14 +634,18 @@ export async function runDoctor({
   url,
   studioDir,
   root,
-  aiRouteConfigured = false,
+  layout,
+  aiRoute: aiRouteOutcome,
+  aiRouteConfigured,
   exec,
   previewsArtifacts,
   routeFacts,
   configOutcome,
   installedEngineVersion,
+  frontendCacheComponents,
 } = {}) {
-  const target = resolveDoctorTarget(env, { url })
+  const studioLabel = appDisplay(layout, 'studio')
+  const target = resolveDoctorTarget(env, { url, envSource: `${studioLabel}/.env` })
 
   log('Elytra deployment doctor')
   if (target.kind === 'convex') {
@@ -536,8 +664,14 @@ export async function runDoctor({
   // entry resolves it via `resolveInstalledEngineVersion`; runDoctor itself never
   // touches the filesystem for it, staying pure/injected like every gatherer here).
   const facts = await gatherFacts(target, { fetchImpl, installedEngineVersion })
+
+  // EC-603: the AI route from the studio's resolved Vite config — gathered before the
+  // deployment-env facts, whose AI-key expectation it decides.
+  const aiRoute = aiRouteOutcome ?? (root !== undefined ? await readStudioAiRoute({ studioDir }) : undefined)
+  const aiExpected = aiRouteConfigured ?? aiRoute?.kind === 'mounted'
+
   if (target.kind === 'convex') {
-    facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured, exec })
+    facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured: aiExpected, exec })
     // EC-421: default-on signed no-op ping whenever the revalidate pair is present.
     const revalidateProbe = await gatherRevalidateProbe({
       envFacts: facts.deploymentEnv,
@@ -577,14 +711,30 @@ export async function runDoctor({
   const artifacts = previewsArtifacts ?? (studioDir ? gatherPreviewsArtifacts(studioDir) : undefined)
   let checks = artifacts ? [...report.checks, ...previewsDoctorChecks(artifacts)] : [...report.checks]
 
+  // EC-603: the layout and AI-route rows, in the `app` bucket (both repo facts).
+  // EC-515: the frontend's `cacheComponents` flag — a repo fact, any backend mode.
+  const frontend = layout?.entries?.frontend
+  checks = spliceBucketChecks(checks, 'app', [
+    ...layoutDoctorChecks(layout),
+    ...aiRouteDoctorChecks(aiRoute, { studioLabel }),
+    ...cacheComponentsDoctorChecks(
+      frontendCacheComponents ?? gatherFrontendCacheComponents(frontend?.found ? frontend.path : undefined),
+      { frontendLabel: appDisplay(layout, 'frontend') },
+    ),
+  ])
+
   // EC-469: the route-conflict check, spliced into the `app` bucket it belongs to.
   // Backend-independent (routes are CODE) — it runs in playground mode too.
-  // EC-495: a resolved config supersedes the `cms/index.ts` collections re-export —
-  // the route checks judge mounts against the same collections the studio mounts.
+  // EC-603 (RESIDUE-4): when the harness resolved the config, the checks run over ITS
+  // routes and collections — what the studio and delivery serve; the native
+  // `cms/index.ts` read is the fallback for when it could not (EC-495 had swapped in the
+  // resolved collections only, so the routes still came from `cms/index.ts`).
   if (root !== undefined || routeFacts !== undefined) {
-    const loaded = routeFacts ?? (await loadProjectRoutes(root))
-    const enriched = configFacts.collections ? { ...loaded, collections: configFacts.collections } : loaded
-    checks = spliceBucketChecks(checks, 'app', routesDoctorChecks(enriched))
+    checks = spliceBucketChecks(
+      checks,
+      'app',
+      routesDoctorChecks(await routeFactsFor({ outcome, configFacts, routeFacts, root })),
+    )
   }
 
   // One rule for the exit code, the same one `checkDeploymentReady` applies: a

package/src/layout.js

@@ -0,0 +1,288 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/**
+ * The CLI layout contract (EC-603, RATIFIED 2026-10-24) — where a project's studio app,
+ * frontend app and theme stylesheet live, declared in the repo-root `package.json`:
+ *
+ *   "elytra": { "studio": "./studio", "frontend": "./frontend", "theme": "./components/theme.css" }
+ *
+ * `package.json` because it is the one file the CLI can read before ANY toolchain runs —
+ * `elytra.config.ts` (the structure) is executed through the studio app's own Vite,
+ * which needs the studio's location first (the chicken-and-egg EC-565 Round 5 settled;
+ * a plain-TS loader was measured not viable). Every key is optional and DEFAULTS TO THE
+ * SCAFFOLD LAYOUT, so a scaffolded project declares nothing and nothing changes for it.
+ *
+ * The engine supplies capability, never structure (AGENTS.md §4): with this section a
+ * project can reorganise its directories freely and still satisfy the CLI.
+ *
+ * This module is the ONE declaration of the section's shape ({@link LAYOUT_ENTRIES}) and
+ * its ONE reader ({@link resolveProjectLayout}); every CLI path that needs a location
+ * (`inspectProject`, `dev`/`build`, the config harness, `previews`, `doctor`) takes it
+ * from the resolved layout. Validation is explicit — an unknown key, a non-string value,
+ * an absolute path, a path escaping the repo, a theme that is not a file, a declared path
+ * that does not exist — each is a named issue, never a silent fall-back to the default.
+ * Its only reader is the CLI (the studio and the engine never read it), so it lives here,
+ * in plain JS with no dependency, rather than as a core schema.
+ */
+
+/** Where the section lives, as the issues name it. */
+export const LAYOUT_SECTION = 'package.json#elytra'
+
+/**
+ * The section's keys — THE declaration. `default` is the scaffold layout; `kind` is what
+ * the path must be (`app`: a directory with a `package.json`; `file`: a file).
+ */
+export const LAYOUT_ENTRIES = {
+  studio: { default: './studio', kind: 'app', label: 'studio app' },
+  frontend: { default: './frontend', kind: 'app', label: 'frontend app' },
+  theme: { default: './components/theme.css', kind: 'file', label: 'theme stylesheet' },
+}
+
+const KEYS = Object.keys(LAYOUT_ENTRIES)
+
+/** A root-relative POSIX path for display (`apps/editor`, `.` for the root itself). */
+export function displayPath(root, absolute) {
+  const rel = relative(root, absolute)
+  return rel === '' ? '.' : rel.split(sep).join('/')
+}
+
+function issue(key, code, message, fix) {
+  return { key, code, message, ...(fix ? { fix } : {}) }
+}
+
+/**
+ * PURE core: parse the root `package.json` text (or `undefined` when there is none) into
+ * the declared values and the SHAPE issues. Existence is checked separately
+ * ({@link resolveProjectLayout}) so this stays filesystem-free.
+ *
+ * Returns `{ declared: { [key]: string }, invalid: Set<key>, issues }` — a key in
+ * `invalid` has NO usable value (it is neither the declared one nor the default: an
+ * invalid declaration must never quietly turn into the scaffold path).
+ */
+export function parseLayoutSection(root, packageJsonText) {
+  const declared = {}
+  const invalid = new Set()
+  const issues = []
+  if (packageJsonText === undefined) return { declared, invalid, issues }
+
+  let pkg
+  try {
+    pkg = JSON.parse(packageJsonText)
+  } catch (error) {
+    for (const key of KEYS) invalid.add(key)
+    issues.push(
+      issue(
+        null,
+        'layout-package-json-invalid',
+        `The repo-root package.json is not valid JSON (${error.message}) — the project layout (${LAYOUT_SECTION}) cannot be read.`,
+        'Fix the JSON syntax of the repo-root package.json.',
+      ),
+    )
+    return { declared, invalid, issues }
+  }
+
+  const section = pkg?.elytra
+  if (section === undefined) return { declared, invalid, issues }
+  if (section === null || typeof section !== 'object' || Array.isArray(section)) {
+    for (const key of KEYS) invalid.add(key)
+    issues.push(
+      issue(
+        null,
+        'layout-invalid-section',
+        `${LAYOUT_SECTION} must be an object of paths ({ "studio": "./studio", … }), not ${section === null ? 'null' : Array.isArray(section) ? 'an array' : typeof section}.`,
+        `Make ${LAYOUT_SECTION} an object with any of ${KEYS.join(', ')} — or remove it to use the scaffold layout.`,
+      ),
+    )
+    return { declared, invalid, issues }
+  }
+
+  for (const key of Object.keys(section)) {
+    if (!Object.hasOwn(LAYOUT_ENTRIES, key)) {
+      issues.push(
+        issue(
+          key,
+          'layout-unknown-key',
+          `${LAYOUT_SECTION} has an unknown key "${key}" — the known keys are ${KEYS.join(', ')}.`,
+          `Rename or remove "${key}" in ${LAYOUT_SECTION}.`,
+        ),
+      )
+    }
+  }
+
+  for (const key of KEYS) {
+    if (!Object.hasOwn(section, key)) continue
+    const value = section[key]
+    const entry = LAYOUT_ENTRIES[key]
+    const fix = `Set ${LAYOUT_SECTION}.${key} to the ${entry.label}'s path relative to the repo root (default "${entry.default}"), or remove the key to use the default.`
+    if (typeof value !== 'string' || value.trim() === '') {
+      invalid.add(key)
+      issues.push(
+        issue(key, 'layout-invalid-path', `${LAYOUT_SECTION}.${key} must be a non-empty path string, not ${JSON.stringify(value)}.`, fix),
+      )
+      continue
+    }
+    if (isAbsolute(value)) {
+      invalid.add(key)
+      issues.push(
+        issue(
+          key,
+          'layout-invalid-path',
+          `${LAYOUT_SECTION}.${key} is the absolute path "${value}" — layout paths are relative to the repo root, so the project works wherever it is checked out.`,
+          fix,
+        ),
+      )
+      continue
+    }
+    const rel = relative(root, resolve(root, value))
+    if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+      invalid.add(key)
+      issues.push(
+        issue(key, 'layout-invalid-path', `${LAYOUT_SECTION}.${key} ("${value}") points outside the repo root.`, fix),
+      )
+      continue
+    }
+    if (rel === '' && entry.kind === 'app') {
+      // The root package is the one that runs `elytra` — an app there would make
+      // `elytra dev` spawn itself.
+      invalid.add(key)
+      issues.push(
+        issue(key, 'layout-invalid-path', `${LAYOUT_SECTION}.${key} ("${value}") is the repo root itself — the ${entry.label} must be its own directory.`, fix),
+      )
+      continue
+    }
+    declared[key] = value
+  }
+  return { declared, invalid, issues }
+}
+
+/** Default filesystem probes — injectable for tests. */
+const defaultFs = {
+  readFile: (path) => (existsSync(path) ? readFileSync(path, 'utf8') : undefined),
+  kindOf: (path) => {
+    try {
+      const stat = statSync(path)
+      return stat.isDirectory() ? 'dir' : stat.isFile() ? 'file' : 'other'
+    } catch {
+      return 'missing'
+    }
+  },
+}
+
+/**
+ * Resolve a project's layout: the declared-or-default path of every entry, whether it
+ * exists, and every issue. Never throws.
+ *
+ * Returns
+ *   {
+ *     source: 'declared' | 'defaults',   // was anything declared in package.json#elytra?
+ *     entries: { studio, frontend, theme }, each
+ *       { key, path: <absolute> | null, display: 'apps/editor' | null,
+ *         declared: boolean, found: boolean },
+ *     issues: [{ key, code, message, fix? }],
+ *   }
+ *
+ * `path` is `null` only for an INVALID declaration — the entry is then unusable, never
+ * the default. A DECLARED path that does not exist (or a theme that is not a file) is an
+ * issue; a DEFAULT path that does not exist is not (a frontend-only or studio-only repo
+ * is legitimate) — it is simply `found: false`.
+ */
+export function resolveProjectLayout(root, fs = defaultFs) {
+  const { declared, invalid, issues } = parseLayoutSection(root, fs.readFile(join(root, 'package.json')))
+  const entries = {}
+  for (const key of KEYS) {
+    const entry = LAYOUT_ENTRIES[key]
+    if (invalid.has(key)) {
+      entries[key] = { key, path: null, display: null, declared: true, found: false }
+      continue
+    }
+    const isDeclared = Object.hasOwn(declared, key)
+    const path = resolve(root, isDeclared ? declared[key] : entry.default)
+    const display = displayPath(root, path)
+    let found
+    if (entry.kind === 'app') {
+      found = fs.kindOf(join(path, 'package.json')) === 'file'
+      if (isDeclared && !found) {
+        issues.push(
+          issue(
+            key,
+            'layout-path-missing',
+            fs.kindOf(path) === 'missing'
+              ? `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} does not exist.`
+              : `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} has no package.json — it is not an app.`,
+            `Point ${LAYOUT_SECTION}.${key} at the ${entry.label}'s directory (the one with its package.json), relative to the repo root.`,
+          ),
+        )
+      }
+    } else {
+      const kind = fs.kindOf(path)
+      found = kind === 'file'
+      if (isDeclared && kind === 'missing') {
+        issues.push(
+          issue(
+            key,
+            'layout-path-missing',
+            `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} does not exist.`,
+            `Point ${LAYOUT_SECTION}.${key} at the ${entry.label} file, relative to the repo root.`,
+          ),
+        )
+      } else if (isDeclared && kind !== 'file') {
+        issues.push(
+          issue(
+            key,
+            'layout-not-a-file',
+            `${LAYOUT_SECTION}.${key} is "${declared[key]}", but ${display} is ${kind === 'dir' ? 'a directory' : 'not a regular file'} — the theme is one stylesheet.`,
+            `Point ${LAYOUT_SECTION}.${key} at the theme's entry stylesheet (e.g. "./components/theme.css").`,
+          ),
+        )
+      }
+    }
+    entries[key] = { key, path, display, declared: isDeclared, found }
+  }
+  const source = KEYS.some((key) => entries[key].declared) ? 'declared' : 'defaults'
+  return { source, entries, issues }
+}
+
+/**
+ * The root-relative display path of an entry for prose and fix lines (`apps/editor`,
+ * `studio`) — the resolved one, or the scaffold default's when no layout was resolved
+ * (an invalid declaration, or a hand-built project object). Display only: no command
+ * ever SPAWNS or READS from this fallback.
+ */
+export function appDisplay(layout, key) {
+  return layout?.entries?.[key]?.display ?? LAYOUT_ENTRIES[key].default.replace(/^\.\//, '')
+}
+
+// --- Doctor row (pure) ---------------------------------------------------------------
+
+/**
+ * The doctor's `project-layout` row for the `app` bucket: what the CLI resolved and where
+ * from, so "which studio did it look at?" is never a guess. `fail` on any layout issue
+ * (an invalid section or a declared path that does not exist — both deterministic in the
+ * repo, so failing the exit code is safe for CI); otherwise `ok`, listing each location
+ * and whether it was declared or defaulted.
+ */
+export function layoutDoctorChecks(layout) {
+  if (!layout) return []
+  const base = { id: 'project-layout', bucket: 'app' }
+  if (layout.issues.length > 0) {
+    return [
+      {
+        ...base,
+        status: 'fail',
+        detail: `${layout.issues.length} problem(s) with the project layout. ${layout.issues.map((i) => i.message).join(' ')}`,
+        fix: layout.issues.find((i) => i.fix)?.fix ?? `Fix ${LAYOUT_SECTION} in the repo-root package.json.`,
+      },
+    ]
+  }
+  const parts = KEYS.map((key) => {
+    const entry = layout.entries[key]
+    const where = entry.found ? entry.display : `${entry.display} (not present)`
+    return `${key} → ${where}`
+  })
+  const origin =
+    layout.source === 'declared'
+      ? `declared in ${LAYOUT_SECTION} (undeclared keys use the scaffold defaults)`
+      : `the scaffold defaults — nothing declared in ${LAYOUT_SECTION}`
+  return [{ ...base, status: 'ok', detail: `${parts.join(', ')} — ${origin}.` }]
+}