@elytracms/cli 0.0.90 → 0.0.92

package/package.json

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

package/src/cli.js

@@ -1,5 +1,10 @@
 import { spawnSync } from 'node:child_process'
 import { stdout } from 'node:process'
+import {
+  DEV_FRONTEND_BASE_PORT,
+  DEV_FRONTEND_URL_ENV,
+  devFrontendUrl,
+} from '@elytracms/core/export-sync/deployment-ready'
 import { resolveInstalledEngineVersion, runDoctor } from './doctor.js'
 import { appDisplay } from './layout.js'
 import { runPreviews } from './previews.js'
@@ -215,15 +220,22 @@ export function planDev(project) {
   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.
-  const studioEnv = { ELYTRA_DEV_PORT_OFFSET: String(offset) }
-  // The frontend's port is resolved HERE instead, and handed over as `PORT` (which
+  // The frontend's port is resolved HERE, once, and handed over as `PORT` (which
   // Next reads from the process env natively). That keeps the scaffold's `dev`
   // script a plain `next dev`: computing the port inside the npm script needs POSIX
   // arithmetic (`$(( ))`), which silently breaks `pnpm dev` under cmd.exe on
   // Windows — every other template script is shell-agnostic and this one stays so.
-  const frontendEnv = { ELYTRA_DEV_PORT_OFFSET: String(offset), PORT: String(3000 + offset) }
+  const frontendPort = DEV_FRONTEND_BASE_PORT + offset
+  // The studio's `vite.config.ts` resolves the offset itself, in JS (`loadEnv`) —
+  // portable anywhere, so forward the lever as-is. EC-583 — Q15 RATIFIED (EC-565
+  // Round 5, 5b): this process starts the frontend and is the one that KNOWS its
+  // port, so it hands the studio the dev frontend URL its live links use; the studio
+  // prefers it in a dev runtime only, and `elytra.config.ts` keeps reading no env.
+  const studioEnv = {
+    ELYTRA_DEV_PORT_OFFSET: String(offset),
+    ...(project.apps.frontend ? { [DEV_FRONTEND_URL_ENV]: devFrontendUrl(offset) } : {}),
+  }
+  const frontendEnv = { ELYTRA_DEV_PORT_OFFSET: String(offset), PORT: String(frontendPort) }
 
   if (project.apps.studio && project.mode === 'connected') {
     if (project.convexProvisioned && !project.isProdDeployment) {

package/src/config-harness.js

@@ -3,6 +3,7 @@ import { createRequire } from 'node:module'
 import { createServer as createNetServer } from 'node:net'
 import { join, relative, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
+import { WORKSPACE_CONFIG_FILE } from '@elytracms/core/config'
 
 /**
  * The consumer-Vite harness (EC-495) — the ONE mechanism by which this CLI
@@ -33,8 +34,8 @@ import { pathToFileURL } from 'node:url'
 
 // --- Shared plumbing ---------------------------------------------------------------
 
-/** Conventional config file name at the project root (mirrors `WORKSPACE_CONFIG_FILE`). */
-export const CONFIG_FILE = 'elytra.config.ts'
+/** The config file name at the project root — core's one declaration (EC-583, RESIDUE-4d). */
+export const CONFIG_FILE = WORKSPACE_CONFIG_FILE
 
 /** Resolve a module specifier from a directory's own node_modules world. */
 export function resolveFromDir(dir, specifier) {

package/src/doctor.js

@@ -1,6 +1,3 @@
-import { readFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { dirname, join } from 'node:path'
 import { orphanedCollections } from '@elytracms/core/cms-core'
 import {
   REVALIDATE_ENV_ENDPOINT,
@@ -19,7 +16,7 @@ import { aiRouteDoctorChecks, executeWorkspaceConfig, readStudioAiRoute } from '
 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'
+import { routesDoctorChecks } from './routes-check.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -145,26 +142,13 @@ export async function gatherFacts(target, { fetchImpl = fetch, installedEngineVe
 }
 
 /**
- * Resolve the engine version of the `@elytracms/studio` package INSTALLED in the
- * consumer's studio app (EC-552) — the `expected` half of the version handshake.
- * Deliberately resolved through the `convex/delivery` export and its adjacent
- * `package.json`: that is the very source file the consumer's `convex deploy`
- * bundles, so the version read here is by construction the version a redeploy
- * would stamp. (The consumer's own `package.json` only carries a RANGE.)
- * `undefined` when the deps aren't installed → the fact is omitted → the check
- * reports an honest `unknown`, matching the config checks' opportunistic contract.
+ * The engine version of the `@elytracms/studio` package INSTALLED in the consumer's
+ * studio app (EC-552) — the `expected` half of the version handshake. `undefined` when
+ * the deps aren't installed → the fact is omitted → the check reports an honest
+ * `unknown`. The one CLI resolver lives in `engine-version.js` (EC-583, RESIDUE-4e);
+ * re-exported here for the doctor's existing importers.
  */
-export function resolveInstalledEngineVersion(studioDir) {
-  if (!studioDir) return undefined
-  try {
-    const req = createRequire(join(studioDir, 'package.json'))
-    const deliverySource = req.resolve('@elytracms/studio/convex/delivery')
-    const pkg = JSON.parse(readFileSync(join(dirname(deliverySource), '..', 'package.json'), 'utf8'))
-    return typeof pkg.version === 'string' ? pkg.version : undefined
-  } catch {
-    return undefined
-  }
-}
+export { resolveInstalledEngineVersion } from './engine-version.js'
 
 // --- Config facts via the consumer-Vite harness (EC-495) -------------------------------
 
@@ -475,26 +459,34 @@ export function formatReport(report) {
 }
 
 /**
- * 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.
+ * What the doctor's route checks judge (EC-590; RESIDUE-4a/4b): the RESOLVED project's
+ * routes, collections and locales — the same records the studio mounts and delivery
+ * serves — and, when the deployment's public delivery snapshot was read, the enabled
+ * editorial redirects it serves. No resolved config → `unavailable`, with the reason:
+ * there is no second reading of the routes (the native `cms/index.ts` floor is gone).
+ * Pure; never throws.
  */
-export async function routeFactsFor({ outcome, configFacts = {}, routeFacts, root }) {
+export function routeFactsFor({ outcome, configFacts = {}, snapshot }) {
   const project = resolvedProjectOf(outcome)
-  if (project && Array.isArray(project.routes)) {
-    return {
+  if (!project || !Array.isArray(project.routes)) {
+    const reason =
+      configFacts.config !== undefined && !configFacts.config.valid
+        ? 'fix the workspace config issues first (see config-valid).'
+        : (configFacts.configUnavailableDetail ?? 'elytra.config.ts was not evaluated here.')
+    return { unavailable: `Routes were not checked — ${reason}` }
+  }
+  return {
+    project: {
       routes: project.routes,
-      routeCount: project.routes.length,
       ...(Array.isArray(project.collections) ? { collections: project.collections } : {}),
-      source: 'config',
-    }
+      ...(project.locales ? { locales: project.locales } : {}),
+    },
+    ...(snapshot?.status === 'answered'
+      ? { redirects: snapshot.redirects }
+      : snapshot
+        ? { redirectsUnavailable: `Redirects were not read from the deployment — ${snapshot.detail}` }
+        : {}),
   }
-  const loaded = routeFacts ?? (await loadProjectRoutes(root))
-  const enriched = configFacts.collections ? { ...loaded, collections: configFacts.collections } : loaded
-  return { ...enriched, source: 'native' }
 }
 
 // --- Command -----------------------------------------------------------------
@@ -553,6 +545,12 @@ export async function routeFactsFor({ outcome, configFacts = {}, routeFacts, roo
  *  - 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-620: the doctor checks NO Next flag. Caching is the host's — the delivery kit holds
+ * no cache scope, so a frontend builds with `cacheComponents`, `experimental.useCache`
+ * or neither. (EC-515's `frontend-cache-components` row, which failed a frontend without
+ * `cacheComponents`, is deleted.) The engine's part — the invalidation signal — is the
+ * revalidate probe above.
  */
 export async function runDoctor({
   env = {},
@@ -621,11 +619,18 @@ export async function runDoctor({
 
   // EC-606: published documents of undeclared collections — one more request on the
   // same public query API, made only when the config resolved (it needs the declared set).
+  // EC-590: the SAME snapshot read carries the deployment's redirects for the route checks.
+  const project = resolvedProjectOf(outcome)
+  const snapshot =
+    target?.kind === 'convex' && project && Array.isArray(project.collections)
+      ? await probeDeliverySnapshot(target.url, project.slug, fetchImpl)
+      : undefined
   const publishedOrphans = await gatherPublishedOrphans({
     target,
-    project: resolvedProjectOf(outcome),
+    project,
     configFacts,
     fetchImpl,
+    ...(snapshot ? { probe: async () => snapshot } : {}),
   })
   if (publishedOrphans) facts.publishedOrphans = publishedOrphans
 
@@ -643,17 +648,14 @@ export async function runDoctor({
     ...aiRouteDoctorChecks(aiRoute, { studioLabel }),
   ])
 
-  // 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-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) {
+  // EC-469/EC-590: the route checks — the one router's issue set over the resolved
+  // project (and the deployment's redirects when the snapshot was read), spliced into the
+  // `app` bucket. Routes are CODE, so the rows run in playground mode too.
+  if (root !== undefined || routeFacts !== undefined || configOutcome !== undefined) {
     checks = spliceBucketChecks(
       checks,
       'app',
-      routesDoctorChecks(await routeFactsFor({ outcome, configFacts, routeFacts, root })),
+      routesDoctorChecks(routeFacts ?? routeFactsFor({ outcome, configFacts, snapshot })),
     )
   }
 

package/src/engine-version.js

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+
+/**
+ * The ONE "installed engine version" resolver of the CLI (EC-583, RESIDUE-4e) — read by
+ * `elytra doctor`/`init` (the `expected` half of the EC-552 version handshake) and by
+ * `elytra previews` (the version recorded on the manifest). The two used to resolve the
+ * same fact two ways: the doctor through the `@elytracms/studio/convex/delivery` export,
+ * previews through hand-joined `node_modules` paths with a silent `@elytracms/core`
+ * fallback.
+ *
+ * Resolved through the `convex/delivery` export and its adjacent `package.json`: that is
+ * the very source file the consumer's `convex deploy` bundles, so the version read here
+ * is by construction the version a redeploy would stamp. (The consumer's own
+ * `package.json` only carries a RANGE.) `undefined` when the studio's deps are not
+ * installed — callers report an honest `unknown`, never a guessed version.
+ *
+ * @param {string | undefined | null} studioDir the resolved studio app (EC-603 layout)
+ * @returns {string | undefined}
+ */
+export function resolveInstalledEngineVersion(studioDir) {
+  if (!studioDir) return undefined
+  try {
+    const req = createRequire(join(studioDir, 'package.json'))
+    const deliverySource = req.resolve('@elytracms/studio/convex/delivery')
+    const pkg = JSON.parse(readFileSync(join(dirname(deliverySource), '..', 'package.json'), 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
+}

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 { resolveInstalledEngineVersion } from './engine-version.js'
 import { appDisplay, resolveProjectLayout } from './layout.js'
 
 /**
@@ -558,28 +559,6 @@ export function previewsDoctorChecks(artifacts) {
 
 // --- Impure plumbing ---------------------------------------------------------------
 
-/**
- * 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, 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')
-      if (!existsSync(path)) continue
-      try {
-        const version = JSON.parse(readFileSync(path, 'utf8')).version
-        if (typeof version === 'string' && version.length > 0) return version
-      } catch {
-        // fall through to the next candidate
-      }
-    }
-  }
-  return 'unknown'
-}
 
 /**
  * The consumer theme entry the harness page imports: the studio's canvas
@@ -671,7 +650,7 @@ async function startHarnessServer({ root, studioDir, layout, port }) {
   const tailwindEntry = resolveFromDir(studioDir, '@tailwindcss/vite')
   const tailwind = (await import(pathToFileURL(tailwindEntry).href)).default
 
-  const configPath = join(root, 'elytra.config.ts')
+  const configPath = join(root, CONFIG_FILE)
   const themePath = themeStylesheetPath(root, layout)
   if (!themePath) {
     const studio = appDisplay(layout, 'studio')
@@ -813,7 +792,8 @@ export async function runPreviews(project, { check = false, port, log = (l) => c
   const layout = project.layout ?? resolveProjectLayout(root)
   const studioDir = layout.entries.studio.path
   const studioLabel = layout.entries.studio.display
-  const engine = resolveEngineVersion(root, studioDir)
+  // EC-583 (RESIDUE-4e): the CLI's one installed-engine-version resolver.
+  const engine = resolveInstalledEngineVersion(studioDir) ?? 'unknown'
   const manifestPath = join(studioDir, PREVIEWS_MANIFEST_FILE)
   const imagesDir = join(studioDir, PREVIEWS_DIR)
 

package/src/project.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
+import { WORKSPACE_CONFIG_FILE } from '@elytracms/core/config'
 import { parseBackendMode } from '@elytracms/core/export-sync/deployment-ready'
 import { appDisplay, resolveProjectLayout } from './layout.js'
 
@@ -34,7 +35,7 @@ import { appDisplay, resolveProjectLayout } from './layout.js'
 export function findRepoRoot(start) {
   let dir = start
   for (;;) {
-    if (existsSync(join(dir, 'elytra.config.ts'))) return dir
+    if (existsSync(join(dir, WORKSPACE_CONFIG_FILE))) return dir
     const parent = dirname(dir)
     if (parent === dir) return null
     dir = parent

package/src/provision.js

@@ -1,5 +1,6 @@
 import { spawnSync } from 'node:child_process'
 import { generateKeyPairSync } from 'node:crypto'
+import { AUTH_SIGNING_KEY_ENV } from '@elytracms/core/export-sync/deployment-ready'
 
 /**
  * First-run auto-provisioning for the Elytra CLI (EC-259). Folds the Convex Auth
@@ -42,8 +43,8 @@ export function generateAuthKeys() {
   const jwk = publicKey.export({ format: 'jwk' })
   return {
     // Match @convex-dev/auth: PKCS#8 PEM, trailing whitespace trimmed, newlines → spaces.
-    JWT_PRIVATE_KEY: pkcs8.trimEnd().replace(/\n/g, ' '),
-    JWKS: JSON.stringify({ keys: [{ use: 'sig', ...jwk }] }),
+    [AUTH_SIGNING_KEY_ENV.privateKey]: pkcs8.trimEnd().replace(/\n/g, ' '),
+    [AUTH_SIGNING_KEY_ENV.publicKeys]: JSON.stringify({ keys: [{ use: 'sig', ...jwk }] }),
   }
 }
 
@@ -83,8 +84,8 @@ export function convexEnvSet(name, value, { cwd, exec = defaultConvexExec } = {}
 /** Which of the two auth signing-key vars are already present on the deployment. */
 export function detectKeyState({ cwd, exec } = {}) {
   return {
-    jwt: convexEnvGet('JWT_PRIVATE_KEY', { cwd, exec }) !== '',
-    jwks: convexEnvGet('JWKS', { cwd, exec }) !== '',
+    jwt: convexEnvGet(AUTH_SIGNING_KEY_ENV.privateKey, { cwd, exec }) !== '',
+    jwks: convexEnvGet(AUTH_SIGNING_KEY_ENV.publicKeys, { cwd, exec }) !== '',
   }
 }
 
@@ -110,8 +111,9 @@ export function ensureAuthKeys({ cwd, exec, log = () => {}, generate = generateA
     return { action: 'partial', state }
   }
   const keys = generate()
-  convexEnvSet('JWT_PRIVATE_KEY', keys.JWT_PRIVATE_KEY, { cwd, exec })
-  convexEnvSet('JWKS', keys.JWKS, { cwd, exec })
+  for (const name of [AUTH_SIGNING_KEY_ENV.privateKey, AUTH_SIGNING_KEY_ENV.publicKeys]) {
+    convexEnvSet(name, keys[name], { cwd, exec })
+  }
   log('✓ Generated and set the Convex Auth signing keys (JWT_PRIVATE_KEY + JWKS).')
   return { action: 'generated', state }
 }

package/src/routes-check.js

@@ -1,329 +1,50 @@
-import { existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import {
-  createRouter,
-  declaredMounts,
-  hierarchyMountConflicts,
-  isHierarchyTemplate,
-  routeRecordSchema,
-  routeReachabilityIssues,
-} from '@elytracms/core/cms-core'
+import { createRouter, declaredMounts } from '@elytracms/core/cms-core'
 
 /**
- * `elytra doctor`'s route check (EC-469) — the CODE side of route validation.
- *
- * `createRouter` computes real structural issues and, before this, no surface showed
- * them: the studio has had no Routes screen since EC-303 (correctly — routes are
- * code), and doctor deferred structure to "the studio boot and `elytra build`",
- * neither of which checked routes. A route conflict shipped silently.
- *
- * **What lives here and why only this.** `createRouter` produces exactly two codes —
- * `route-conflict` (from routes alone) and `redirect-loop` (from redirects). Since
- * EC-303 redirects are editorial DATA in the backend, so a bundler-less, session-less
- * CLI cannot see them; and `unknown-route-target` is not a router issue at all — the
- * *resolver* raises it per URL against the documents that exist
- * (`core/src/content/client.ts`). So the honest CLI-side answer is **route conflicts**,
- * and the other two are the studio's (which holds both the routes and the redirects).
- * The `redirect-loops` check below says exactly that, as an `unknown` — the same
- * convention `config-valid` already uses for a fact the CLI cannot gather.
- *
- * EC-482 adds the half the router structurally cannot see: **hierarchy mounts**. They
- * are filtered OUT of the router (below, and identically in delivery), so two mounts
- * fighting over the same URLs were invisible to every surface. `hierarchyMountConflicts`
- * judges them by declaration instead of by pattern shape; the second check row reports
- * it. Both checks are code-side and mutually exclusive by construction — a mount never
- * reaches the router, an ordinary route never reaches the mount detector.
- *
- * EC-484 adds the third row, `unreachable-routes`, for the case where nothing is in
- * conflict and the declaration simply does not work: a `/:slug`-shaped route that
- * matches every URL at a depth the mount serves (so the mount is never reached and
- * existing pages 404), a mount whose collection cannot compose nested paths, and a
- * catch-all with a dynamic prefix that every router drops and no mount is built from.
- * All three were measured to resolve `notFound` with zero issues on every surface.
- *
- * **Loading the routes.** This check runs with NO bundler and NO installed deps: a
- * project's `cms/` tree is React-free by convention — measured across `apps/demo`, the
- * scaffold template, and both real consumer repos: every external import is
- * `import type`, erased by Node's own TypeScript support. So doctor imports
- * `cms/index.ts` natively and reads the same `collections` + `routes` that
- * `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 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:
- *
- * 1. **Node floor.** Native TS needs Node ≥22.18 (measured: 22.13 → `ERR_UNKNOWN_
- *    FILE_EXTENSION`, 22.21 → loads). Below the floor the check reports `unknown`
- *    with the version as its reason — the CLI's own `engines` promise (>=20) is not
- *    quietly broken.
- * 2. **Bundler-style specifiers.** Real `cms/` trees write `from './collections'` —
- *    extensionless, and a directory at that. Plain Node ESM resolves neither, at any
- *    version. {@link withBundlerResolution} registers a *fallback* resolve hook that
- *    supplies the extension/index a bundler would, and only after Node's own
- *    resolution has already failed — so it can never hijack a specifier that already
- *    resolves.
- *
- * Executing consumer code in a tool that otherwise only does HTTP is a change in
- * kind, so it is bounded: one conventional file, read-only, no writes, and every
- * failure mode (missing file, throwing module, unresolvable import, non-erasable TS,
- * a `routes` export of the wrong shape, a derive that throws) degrades to a reported
- * `unknown` carrying its reason. There is no path here that crashes the doctor and
- * none that reports a pass it did not establish.
- */
-
-// --- Loading the project's routes (impure) -----------------------------------
-
-/** Where the route set is read from, by convention (AD-11: structure is code, in-repo). */
-export const CMS_ENTRY = join('cms', 'index.ts')
-
-/** Relative-specifier suffixes a bundler would try, in the order it tries them. */
-const RESOLVE_CANDIDATES = ['.ts', '.tsx', '/index.ts', '/index.tsx', '.js', '.mjs', '/index.js']
-
-/**
- * Run `load` with a FALLBACK module-resolution hook that supplies the extension or
- * `/index` a bundler would for a relative specifier — but only for specifiers Node
- * itself could not resolve, so an already-valid specifier is never rewritten. The
- * hook is deregistered before returning, in success and in failure alike: doctor
- * never leaves process-wide resolution patched.
- *
- * `module.registerHooks` is Node ≥22.15. Where it is absent the load simply runs
- * unhooked (a `cms/` tree with explicit extensions still works) — never an error.
- */
-export async function withBundlerResolution(load) {
-  let handle
-  try {
-    const { registerHooks } = await import('node:module')
-    if (typeof registerHooks === 'function') {
-      handle = registerHooks({
-        resolve(specifier, context, nextResolve) {
-          try {
-            return nextResolve(specifier, context)
-          } catch (error) {
-            if (!specifier.startsWith('./') && !specifier.startsWith('../')) throw error
-            if (!context.parentURL) throw error
-            for (const suffix of RESOLVE_CANDIDATES) {
-              const url = new URL(specifier + suffix, context.parentURL)
-              if (url.protocol === 'file:' && existsSync(fileURLToPath(url))) {
-                return { url: url.href, shortCircuit: true }
-              }
-            }
-            throw error
-          }
-        },
-      })
-    }
-  } catch {
-    // No resolve-hook support in this runtime — load unhooked.
-  }
-  try {
-    return await load()
-  } finally {
-    handle?.deregister()
-  }
-}
-
-/**
- * Silence ONE Node warning for the duration of `run`:
- * `MODULE_TYPELESS_PACKAGE_JSON`, which fires for every consumer repo whose root
- * `package.json` omits `"type": "module"` (both real ones). It is unrelated to route
- * validity and would print into the middle of the doctor report. Every other warning
- * still prints, and the original listeners are restored unconditionally.
+ * `elytra doctor`'s route checks (EC-469, EC-482, EC-484) — READING the one router's
+ * issue set (EC-590; EC-565 Round 3, 3h).
+ *
+ * `createRouter` (cms-core `router.ts`) owns the project's ONE route issue set — exact
+ * ties between ordinary routes (`route-conflict`), the one normalised redirect set
+ * (`redirect-loop`, `invalid-redirect`), hierarchy-mount ties, and reachability — and
+ * the studio and the delivery host read the same set. This module only reports it, in
+ * the four rows a reader needs, from the router's `issueGroups`.
+ *
+ * **The routes are the resolved config's** (EC-583/EC-590, RESIDUE-4a/4b): the routes and
+ * collections `elytra.config.ts` resolves to through the consumer studio's own Vite
+ * (EC-495) — what the studio mounts and delivery serves. The bundler-free `cms/index.ts`
+ * floor (a native import of the scaffold's own convention, with its own copy of the
+ * routes materialisation) is gone: when the config cannot be resolved here, the rows say
+ * so as `unknown`, never a judgement over a second reading of the routes.
+ *
+ * **The redirects are the deployment's** (EC-590): the enabled editorial redirects the
+ * public delivery snapshot serves, read on the same request `published-orphans` makes.
+ * Without a deployment to read (playground, no URL) `redirect-loops` is an honest
+ * `unknown`.
  */
-async function withoutTypelessModuleWarning(run) {
-  const listeners = process.listeners('warning')
-  process.removeAllListeners('warning')
-  const passthrough = (warning) => {
-    if (warning?.code === 'MODULE_TYPELESS_PACKAGE_JSON') return
-    for (const listener of listeners) listener(warning)
-  }
-  process.on('warning', passthrough)
-  try {
-    return await run()
-  } finally {
-    process.off('warning', passthrough)
-    for (const listener of listeners) process.on('warning', listener)
-  }
-}
-
-/** The first line of an error, safe for a one-line report row. */
-function reason(error) {
-  const text = error instanceof Error ? error.message : String(error)
-  return text.split('\n')[0].trim()
-}
 
 /**
- * Materialize a `routes` config value against the declared collections — the same
- * rule `studio-core`'s `materializeRecords` applies (EC-207): a derive function runs
- * once, a static array passes through. Both real consumer repos declare the array
- * form; the demo and the scaffold declare the derive.
+ * @typedef {{ routes: readonly import('@elytracms/core/cms-core').RouteRecord[];
+ *   collections?: readonly import('@elytracms/core/cms-core').CollectionDef[];
+ *   locales?: import('@elytracms/core/cms-core').LocaleConfig }} RouteProject
+ * @typedef {{ project: RouteProject;
+ *   redirects?: readonly import('@elytracms/core/cms-core').RedirectRecord[];
+ *   redirectsUnavailable?: string } | { unavailable: string; fix?: string }} RouteFacts
  */
-function materializeRoutes(routes, collections) {
-  return typeof routes === 'function' ? routes(collections) : [...routes]
-}
-
-/**
- * Load the project's declared route set. Returns either `{ routes, routeCount }` or
- * `{ unavailable, fix? }` — an honest reason the routes could not be read. Never
- * throws.
- *
- * `importModule` is injectable for tests (the default is a native dynamic import).
- */
-export async function loadProjectRoutes(root, { importModule } = {}) {
-  const entry = join(root, CMS_ENTRY)
-  if (!existsSync(entry)) {
-    return {
-      // EC-533: state what this FALLBACK looked for, not what a project must contain.
-      // Elytra requires one thing of a repo — an `elytra.config.ts` of the right shape
-      // — and no blessed module paths (EC-532). `cms/index.ts` is the scaffold's own
-      // convention, which is all this bundler-free loader can find on its own; where
-      // the project's deps are installed, EC-495's Vite harness executes the real
-      // config and this floor is never reached.
-      unavailable: `Routes not checked: no ${CMS_ENTRY} to read without a bundler (this is the scaffold's convention, not a requirement — your routes may be declared elsewhere).`,
-    }
-  }
-
-  const load = importModule ?? ((path) => import(pathToFileURL(path).href))
-  let mod
-  try {
-    mod = await withoutTypelessModuleWarning(() => withBundlerResolution(() => load(entry)))
-  } catch (error) {
-    if (error?.code === 'ERR_UNKNOWN_FILE_EXTENSION') {
-      return {
-        unavailable: `${CMS_ENTRY} could not be read: this Node (${process.version}) does not run TypeScript natively.`,
-        fix: 'Use Node >=22.18 (the version the engine targets) to have `elytra doctor` check routes.',
-      }
-    }
-    if (error?.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
-      return {
-        unavailable: `${CMS_ENTRY} uses TypeScript syntax Node cannot strip (${reason(error)}).`,
-        fix: 'Keep cms/ to erasable TypeScript (no enum/namespace/parameter properties) so build-time tools can read your structure.',
-      }
-    }
-    return { unavailable: `${CMS_ENTRY} could not be loaded: ${reason(error)}` }
-  }
-
-  if (mod?.routes === undefined) {
-    return {
-      unavailable: `${CMS_ENTRY} exports no \`routes\` — the route set was not checked here.`,
-    }
-  }
-  if (typeof mod.routes !== 'function' && !Array.isArray(mod.routes)) {
-    return {
-      unavailable: `${CMS_ENTRY} exports \`routes\` that is neither a RouteRecord[] nor a (collections) => RouteRecord[].`,
-    }
-  }
-  // Distinguish "exports no collections" from "exports an empty array": the
-  // reachability check must report NOT CHECKED rather than a pass when it cannot see
-  // the collection set (a mount's target is judged against it).
-  const collections = Array.isArray(mod.collections) ? mod.collections : undefined
-
-  let records
-  try {
-    records = materializeRoutes(mod.routes, collections ?? [])
-  } catch (error) {
-    return { unavailable: `The \`routes\` derive in ${CMS_ENTRY} threw: ${reason(error)}` }
-  }
-  if (!Array.isArray(records)) {
-    return { unavailable: `The \`routes\` derive in ${CMS_ENTRY} did not return an array.` }
-  }
-
-  // Shape-validate before handing records to the router: a malformed record (no
-  // pattern) would otherwise fault inside pattern compilation. Config validity is
-  // the studio boot's job, so this reports rather than duplicating that check.
-  const invalid = records.filter((record) => !routeRecordSchema.safeParse(record).success)
-  if (invalid.length > 0) {
-    return {
-      unavailable: `${invalid.length} of ${records.length} route record(s) are not valid RouteRecords — config validation reports the details.`,
-      fix: 'Open the studio (or run your build) to see the config validation issues, then re-run `elytra doctor`.',
-    }
-  }
-
-  return {
-    routes: records,
-    routeCount: records.length,
-    ...(collections ? { collections } : {}),
-  }
-}
-
-// --- Detection (pure) --------------------------------------------------------
-
-/**
- * The router issues of a declared route set — route conflicts, since a CLI passes
- * no redirects.
- *
- * Hierarchy-mount templates (`/:path*`, EC-218) are filtered out first, exactly as
- * the delivery resolver does (`core/src/content/client.ts:230`): a mount is resolved
- * per-request against the parent chain, not by the router, so counting it as a route
- * would report conflicts the runtime does not have. Running the same filter is what
- * makes doctor unable to disagree with delivery.
- *
- * The filter is NOT widened to cover EC-482 — {@link mountIssuesOf} answers that
- * question about the routes this one removes. Widening the router's signature
- * comparison instead would reinstate the `/:slug` + `/:path*` false positive the
- * filter exists to prevent (pinned in both this package's and cms-core's tests).
- */
-export function routeIssuesOf(routes) {
-  return createRouter(routes.filter((route) => !isHierarchyTemplate(route)), []).issues
-}
-
-/**
- * The conflicts BETWEEN hierarchy mounts (EC-482) — the routes {@link routeIssuesOf}
- * filters away. `error` for two mounts on the same path (identical URL space, split
- * only by declaration order), `warning` for a nested pair (a real shadow, but only
- * where the outer collection's page tree actually reaches into the inner prefix — a
- * content fact a CLI cannot see).
- */
-export function mountIssuesOf(routes) {
-  return hierarchyMountConflicts(routes)
-}
-
-/**
- * The declarations that can never serve content (EC-484) — the third question, after
- * "do two routes fight" and "do two mounts fight": **does this declaration work at
- * all?** An all-dynamic route (`/:slug`) matching every URL at a depth the mount
- * serves, a mount whose collection has no `parent` self-relation (or is not declared),
- * and a catch-all with a dynamic prefix (`/:lang/:path*`) that every router drops and
- * no mount is built from. All three were measured to resolve `notFound` with ZERO
- * issues anywhere before this.
- *
- * `collections` is passed through when the project exported them; without them the
- * mount-target half is skipped and {@link routesDoctorChecks} reports `unknown`
- * instead of a pass it did not establish.
- */
-export function reachabilityIssuesOf(routes, collections) {
-  return routeReachabilityIssues(routes, collections)
-}
-
-// --- Doctor checks (pure) ----------------------------------------------------
 
 const CONFLICT_FIX =
-  'Two routes match the same URLs — give one a distinct pattern (or delete it) in cms/routes.ts.'
+  'Two routes match the same URLs in the same locale scope — give one a distinct pattern (or delete it) where your routes are declared.'
 
 const MOUNT_CONFLICT_FIX =
-  'Two collections cannot be served from the same URL space — give one mount a distinct prefix (e.g. "/docs/:path*") in cms/routes.ts, or drop it.'
-
-const MOUNT_SHADOW_FIX =
-  'Mounts resolve in declaration order, not by specificity — declare the more specific mount first, and keep the outer collection\'s page tree clear of that prefix.'
+  'Two collections cannot be served from the same URL space in the same locale scope — give one mount a distinct prefix (e.g. "/docs/:path*"), or drop it.'
 
 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.'
+  'Give an all-dynamic route a static segment (e.g. "/blog/:slug"), mount only collections with a parent role, and keep a mount prefix static.'
 
-/**
- * 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.)`,
-}
+const REDIRECT_FIX =
+  'Edit the redirects in the studio’s Redirects rail: break the loop, or delete one of the duplicate `from`s (`/old` and `/old/` are one URL).'
 
-/** An `unknown` check row carrying the reason the routes could not be read. */
+/** An `unknown` check row carrying the reason the routes could not be judged. */
 function unavailableCheck(id, facts) {
   return {
     id,
@@ -335,90 +56,84 @@ function unavailableCheck(id, facts) {
 }
 
 /**
- * The doctor's route checks, for the `app` bucket. Consumes the already-loaded facts
- * (the {@link loadProjectRoutes} result) so the reporting shape is pure and directly
- * testable, like `formatReport` and `previewsDoctorChecks`.
+ * The doctor's route checks, for the `app` bucket — pure over the gathered facts (the
+ * resolved project and, when a deployment was read, its redirects), like `formatReport`.
  *
- * Four rows, in the order a reader needs them: the router's own conflicts, the
- * mount-vs-mount conflicts the router cannot see (EC-482), the declarations that serve
- * nothing at all (EC-484), then the redirects a CLI cannot see at all.
+ * `route-conflicts`, `mount-conflicts` and `redirect-loops` can FAIL (deterministic
+ * structural faults); `unreachable-routes` fails on a declaration that can never serve
+ * and warns on a precedence that depends on content (EC-488).
  *
- * `route-conflicts`, `mount-conflicts` and `unreachable-routes` are the checks here
- * that can FAIL — all deterministic in code, so failing the exit code is safe for CI.
- * The latter two can also `warn`, in both cases for the same reason: the finding only
- * costs content where a collection's tree actually reaches that far, which is CONTENT
- * a CLI cannot see, so naming it is honest where failing a build would not be.
- * `redirect-loops` is always `unknown`: they are editorial data, and saying so is how
- * the report stays honest about what a CLI can and cannot see.
+ * @param {RouteFacts | undefined} facts
  */
 export function routesDoctorChecks(facts) {
-  const redirects = {
-    id: 'redirect-loops',
-    bucket: 'app',
-    status: 'unknown',
-    detail:
-      'Redirect loops were not evaluated here — redirects are editorial data in the backend; the studio checks them.',
-  }
-
-  if (!facts || facts.unavailable) {
+  if (!facts || 'unavailable' in facts) {
     return [
       unavailableCheck('route-conflicts', facts),
       unavailableCheck('mount-conflicts', facts),
       unavailableCheck('unreachable-routes', facts),
-      redirects,
+      unavailableCheck('redirect-loops', facts),
     ]
   }
-
-  const count = facts.routeCount ?? facts.routes.length
+  const router = createRouter(facts.project, { redirects: facts.redirects ?? [] })
+  const routes = facts.project.routes
+  const count = 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 conflicts = router.issueGroups.routes
   const routeConflicts =
     conflicts.length === 0
-      ? {
-          id: 'route-conflicts',
-          bucket: 'app',
-          status: 'ok',
-          detail: `${count} declared route${plural}, no URL conflicts.${source}`,
-        }
+      ? { id: 'route-conflicts', bucket: 'app', status: 'ok', detail: `${count} declared route${plural}, no URL conflicts.` }
       : {
           id: 'route-conflicts',
           bucket: 'app',
           status: 'fail',
           detail:
             `${conflicts.length} route conflict(s) among ${count} declared route${plural}. ` +
-            conflicts.map((issue) => issue.message).join(' ') +
-            source,
+            conflicts.map((issue) => issue.message).join(' '),
           fix: CONFLICT_FIX,
         }
 
   return [
     routeConflicts,
-    mountConflictsCheck(facts.routes),
-    unreachableRoutesCheck(facts.routes, facts.collections),
-    redirects,
+    mountConflictsCheck(routes, router.issueGroups.mounts),
+    unreachableRoutesCheck(routes, router.issueGroups.reachability),
+    redirectLoopsCheck(facts, router.issueGroups.redirects),
   ]
 }
 
+/** The `redirect-loops` row: the deployment's redirects through the one normalised set. */
+function redirectLoopsCheck(facts, issues) {
+  const base = { id: 'redirect-loops', bucket: 'app' }
+  if (facts.redirects === undefined) {
+    return {
+      ...base,
+      status: 'unknown',
+      detail:
+        facts.redirectsUnavailable ??
+        'Redirects were not evaluated here — they are editorial data on the deployment, and no deployment was read.',
+    }
+  }
+  const n = facts.redirects.length
+  const scope = `${n} enabled redirect${n === 1 ? '' : 's'} on the deployment`
+  if (issues.length === 0) return { ...base, status: 'ok', detail: `${scope}, no loops or duplicates.` }
+  return {
+    ...base,
+    status: 'fail',
+    detail: `${issues.length} redirect issue(s) among ${scope}. ` + issues.map((issue) => issue.message).join(' '),
+    fix: REDIRECT_FIX,
+  }
+}
+
 /**
- * The `unreachable-routes` row (EC-484): declarations that resolve to nothing.
- *
- * Like `mount-conflicts` it states what it LOOKED at when it passes — a bare "ok"
- * reads the same whether the check examined the mounts or skipped them. And when the
- * project exported no collections it reports `unknown` rather than `ok`: the
- * mount-target half could not run, and a pass it did not establish would be exactly
- * the silent failure this ticket exists to remove.
+ * The `unreachable-routes` row (EC-484): declarations that resolve to nothing. States what
+ * it LOOKED at when it passes — a bare "ok" reads the same whether it examined the mounts
+ * or skipped them.
  */
-function unreachableRoutesCheck(routes, collections) {
+function unreachableRoutesCheck(routes, issues) {
   const mounts = declaredMounts(routes)
   const scope = `${routes.length} declared route${routes.length === 1 ? '' : 's'}, ${mounts.length} hierarchy mount${mounts.length === 1 ? '' : 's'}`
   const base = { id: 'unreachable-routes', bucket: 'app' }
-
-  const issues = reachabilityIssuesOf(routes, collections)
   const errors = issues.filter((issue) => issue.severity === 'error')
   const warnings = issues.filter((issue) => issue.severity !== 'error')
-
   if (errors.length > 0) {
     return {
       ...base,
@@ -433,65 +148,31 @@ function unreachableRoutesCheck(routes, collections) {
     return {
       ...base,
       status: 'warn',
-      detail:
-        `${warnings.length} partially shadowed declaration(s), among ${scope}. ` +
-        warnings.map((issue) => issue.message).join(' '),
+      detail: `${warnings.length} partially shadowed declaration(s), among ${scope}. ` + warnings.map((issue) => issue.message).join(' '),
       fix: UNREACHABLE_FIX,
     }
   }
-  if (mounts.length > 0 && !collections) {
-    return {
-      ...base,
-      status: 'unknown',
-      detail: `${scope}: no route shadows a mount, but mount targets were not checked — ${CMS_ENTRY} exports no \`collections\`.`,
-      fix: `Export \`collections\` from ${CMS_ENTRY} (the shape elytra.config.ts re-exports) so mounts can be checked against them.`,
-    }
-  }
   return { ...base, status: 'ok', detail: `${scope} — every declaration can serve content.` }
 }
 
 /**
- * The `mount-conflicts` row (EC-482). Reports the mount COUNT even when clean — a row
- * that says "1 hierarchy mount, no overlap" proves the check looked at the mounts,
- * where a bare "ok" would read the same whether it examined them or skipped them.
+ * The `mount-conflicts` row (EC-482, re-derived by EC-590): exact ties between mounts. Reports
+ * the mount COUNT even when clean, so a pass proves the check looked at the mounts.
  */
-function mountConflictsCheck(routes) {
+function mountConflictsCheck(routes, issues) {
   const mounts = declaredMounts(routes)
   const mountPlural = mounts.length === 1 ? '' : 's'
   const base = { id: 'mount-conflicts', bucket: 'app' }
-
-  if (mounts.length === 0) {
-    return { ...base, status: 'ok', detail: 'No hierarchy mounts declared.' }
-  }
-
-  const issues = mountIssuesOf(routes)
-  const errors = issues.filter((issue) => issue.severity === 'error')
-  const warnings = issues.filter((issue) => issue.severity !== 'error')
-  const among = `among ${mounts.length} hierarchy mount${mountPlural}`
-
-  if (errors.length > 0) {
+  if (mounts.length === 0) return { ...base, status: 'ok', detail: 'No hierarchy mounts declared.' }
+  if (issues.length > 0) {
     return {
       ...base,
       status: 'fail',
       detail:
-        `${errors.length} conflicting mount pair(s) ${among}. ` +
-        [...errors, ...warnings].map((issue) => issue.message).join(' '),
+        `${issues.length} conflicting mount pair(s) among ${mounts.length} hierarchy mount${mountPlural}. ` +
+        issues.map((issue) => issue.message).join(' '),
       fix: MOUNT_CONFLICT_FIX,
     }
   }
-  if (warnings.length > 0) {
-    return {
-      ...base,
-      status: 'warn',
-      detail:
-        `${warnings.length} overlapping mount pair(s) ${among}. ` +
-        warnings.map((issue) => issue.message).join(' '),
-      fix: MOUNT_SHADOW_FIX,
-    }
-  }
-  return {
-    ...base,
-    status: 'ok',
-    detail: `${mounts.length} hierarchy mount${mountPlural}, no overlapping mounts.`,
-  }
+  return { ...base, status: 'ok', detail: `${mounts.length} hierarchy mount${mountPlural}, no conflicting mounts.` }
 }