@elytracms/cli 0.0.91 → 0.0.93

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,
@@ -16,10 +13,11 @@ import {
   probeRevalidateEndpoint,
 } from '@elytracms/core/export-sync/deployment-ready'
 import { aiRouteDoctorChecks, executeWorkspaceConfig, readStudioAiRoute } from './config-harness.js'
+import { DOCTOR_BUCKET_TITLES } from './doctor-checks.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'
+import { routesDoctorChecks } from './routes-check.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -145,26 +143,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) -------------------------------
 
@@ -419,13 +404,8 @@ export async function gatherRevalidateProbe({
 // --- Formatting (pure) -------------------------------------------------------
 
 const GLYPH = { ok: '✓', warn: '!', fail: '✗', unknown: '?' }
-const BUCKET_TITLE = {
-  deployment: 'Deployment',
-  'deployment-env': 'Deployment env',
-  app: 'App',
-  user: 'Per-user',
-  previews: 'Previews',
-}
+// The bucket headings are declared once, with the checks (`doctor-checks.js`, EC-599).
+const BUCKET_TITLE = DOCTOR_BUCKET_TITLES
 
 /**
  * Splice extra checks into an existing bucket's run, right after that bucket's last
@@ -475,93 +455,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',
-    }
-  }
-  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,
+      ...(project.locales ? { locales: project.locales } : {}),
     },
-  ]
+    ...(snapshot?.status === 'answered'
+      ? { redirects: snapshot.redirects }
+      : snapshot
+        ? { redirectsUnavailable: `Redirects were not read from the deployment — ${snapshot.detail}` }
+        : {}),
+  }
 }
 
 // --- Command -----------------------------------------------------------------
@@ -621,11 +542,11 @@ export function cacheComponentsDoctorChecks(facts, { frontendLabel = 'frontend'
  *    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.
+ * 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 = {},
@@ -642,7 +563,6 @@ export async function runDoctor({
   routeFacts,
   configOutcome,
   installedEngineVersion,
-  frontendCacheComponents,
 } = {}) {
   const studioLabel = appDisplay(layout, 'studio')
   const target = resolveDoctorTarget(env, { url, envSource: `${studioLabel}/.env` })
@@ -695,11 +615,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
 
@@ -712,28 +639,19 @@ export async function runDoctor({
   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-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 }
 }