@elytracms/cli 0.0.91 → 0.0.93

package/package.json

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

package/src/cli.js

@@ -1,6 +1,12 @@
 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 { formatDoctorChecksHelp } from './doctor-checks.js'
 import { appDisplay } from './layout.js'
 import { runPreviews } from './previews.js'
 import { inspectProject, resolveStudioEnv } from './project.js'
@@ -24,16 +30,10 @@ Commands:
                elytra build frontend   frontend build only
   init       First-run setup: provision Convex, generate the auth signing keys,
              verify readiness. Idempotent — safe to re-run at any point.
-  doctor     Diagnose the active deployment's readiness (URL, reachability, auth
-             signing keys, expected deployment env vars — set/missing by NAME,
-             values never shown — config, membership) and print each fix. When the
-             instant-publish revalidate pair is set, also sends a signed no-op ping
-             to the endpoint to prove the publish → live chain end to end. Also
-             checks your routes for URL conflicts, the project layout
-             (package.json#elytra), the AI route your studio's vite.config.ts
-             mounts, and reports the generated-previews artifacts (manifest/files
-             present; hash staleness lives in \`elytra previews --check\`). Exit
-             non-zero if any check fails. Read-only. Optional: --url <convex url>.
+  doctor     Diagnose the deployment, its env, your config, routes, project layout
+             and generated previews, and print each fix. 'elytra doctor --help'
+             lists every check. Exit non-zero if any check fails. Read-only.
+             Optional: --url <convex url>.
   previews   Render every canvas-eligible component's fixtures against YOUR theme
              (headless Chromium via Playwright — an optional install) and write
              committed preview images (studio/public/elytra-previews/) plus an
@@ -112,27 +112,23 @@ First-run setup: provision Convex, generate the auth signing keys, verify
 readiness. Idempotent — safe to re-run at any point. No flags.
 `.trim(),
 
+  // EC-599: the check list is rendered from the one declaration (`doctor-checks.js`) —
+  // this text used to restate it by hand, and had drifted from what the doctor does.
   doctor: `
 Usage: elytra doctor [--url <convex url>]
 
-Diagnose the active deployment's readiness (URL, reachability, auth signing
-keys, expected deployment env vars — set/missing by NAME, values never shown
-— config, membership) and print each fix. When the instant-publish
-revalidate pair is set, also sends a signed no-op ping to the endpoint to
-prove the publish → live chain end to end. Also checks your route set for
-URL conflicts (routes are code — redirect loops are editorial data and are
-checked in the studio), and reports the generated-previews artifacts
-(manifest/files present; hash staleness lives in \`elytra previews --check\`).
-With studio/ deps installed, config validity is checked for real: doctor
-executes elytra.config.ts through your studio's own Vite (takes a few
-seconds), and the route checks judge the routes it resolved; without deps
-it stays an honest "unknown" with the reason and the routes are read from
-cms/index.ts. With the config resolved, it also reads the public delivery
-snapshot and warns about published documents whose collection the config
-does not declare. It reports the project layout it resolved
-(package.json#elytra — a declared path that does not exist fails) and the AI
-route your studio's vite.config.ts mounts (which decides whether an AI
-provider key is expected). Exit non-zero if any check fails. Read-only.
+Diagnose the active deployment and this project, and print a copy-pasteable
+fix for every failing or warning check. Read-only: it reads the studio env,
+the deployment's public endpoints and the names of the deployment's env vars;
+no value is ever printed (the revalidate pair's are read in-process, only to
+sign the probe ping). With the studio's dependencies installed it also
+executes elytra.config.ts through your studio's own Vite (a few seconds), so
+the config, collection and route checks get real answers; without them those
+checks say "unknown" with the reason. Exit non-zero if any check fails —
+warnings and unknowns never change the exit code.
+
+Checks, in report order:
+${formatDoctorChecksHelp()}
 
 Options:
   --url <convex url>   Diagnose this deployment instead of the one resolved
@@ -215,15 +211,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-checks.js

@@ -0,0 +1,261 @@
+import { expectedDeploymentEnv } from '@elytracms/core/export-sync/deployment-ready'
+
+/**
+ * Every check `elytra doctor` can print, declared ONCE (EC-599), in report order.
+ *
+ * The doctor's capabilities used to be written down three times by hand — the guide's
+ * table, `elytra --help` and `elytra doctor --help` — and two of them drifted: the help
+ * text still said redirect loops are "checked in the studio" and that the routes are read
+ * from `cms/index.ts`, long after EC-590 moved both. Now there is one list and three
+ * readers: `elytra doctor --help` ({@link formatDoctorChecksHelp}), the guide's check
+ * table (`docs/guide/06-cli-reference.md`, a region `pnpm check:guide` regenerates and
+ * fails on when stale — {@link formatDoctorChecksMarkdown}), and the report's bucket
+ * headings ({@link DOCTOR_BUCKET_TITLES}). `test/doctor-checks.test.js` runs the doctor
+ * and holds the ids it prints equal to this list, both directions, bucket by bucket — a
+ * check added without an entry, or an entry left behind by a removed check, fails there.
+ *
+ * Each entry: `id` (as printed; `env:*` stands for the one row per expected variable),
+ * `bucket`, `summary` (what it looks at — one sentence, printed by `--help`), and
+ * `outcome` (when it fails / warns / stays unknown — the guide prints it too).
+ */
+
+/** The report's buckets, in report order, with the heading each prints under. */
+export const DOCTOR_BUCKETS = [
+  { bucket: 'deployment', title: 'Deployment' },
+  { bucket: 'deployment-env', title: 'Deployment env' },
+  { bucket: 'app', title: 'App' },
+  { bucket: 'user', title: 'Per-user' },
+  { bucket: 'previews', title: 'Previews' },
+]
+
+/** Bucket id → its heading in the printed report. */
+export const DOCTOR_BUCKET_TITLES = Object.fromEntries(DOCTOR_BUCKETS.map(({ bucket, title }) => [bucket, title]))
+
+export const DOCTOR_CHECKS = [
+  // --- deployment -----------------------------------------------------------------
+  {
+    id: 'backend-url',
+    bucket: 'deployment',
+    summary:
+      'A backend is configured: `VITE_CONVEX_URL` (or `CONVEX_URL`) in the studio env, read by the parser the studio runs, or `--url`.',
+    outcome:
+      'Fails with neither, and on a `VITE_ELYTRA_MODE` other than `playground`. A configured URL is diagnosed even when the studio itself runs playground.',
+  },
+  {
+    id: 'backend-reachable',
+    bucket: 'deployment',
+    summary: 'The deployment answers its query API as a Convex deployment — not merely any HTTP response.',
+    outcome: 'Fails when it does not (a nonexistent deployment’s empty 404 included).',
+  },
+  {
+    id: 'auth-signing-keys',
+    bucket: 'deployment',
+    summary:
+      'The deployment’s public JWKS endpoint serves a signing key set — definitive from node (the browser cannot read it: the endpoint sets no CORS).',
+    outcome: 'Fails when the deployment publishes no key set (`JWKS` / `JWT_PRIVATE_KEY` unset) — every sign-in fails.',
+  },
+  {
+    id: 'deployment-provisioned',
+    bucket: 'deployment',
+    summary: 'A deployment is wired for the active project.',
+    outcome: 'Passes whenever a backend URL is configured (a URL is a wired deployment); `unknown` with none.',
+  },
+  {
+    id: 'functions-version',
+    bucket: 'deployment',
+    summary:
+      'The engine version the deployed functions were stamped with, against the `@elytracms/studio` your studio has installed.',
+    outcome:
+      'Fails when they differ or the stamp is missing; `unknown` when the installed studio version cannot be read here.',
+  },
+  // --- deployment env -------------------------------------------------------------
+  {
+    id: 'env:*',
+    bucket: 'deployment-env',
+    summary:
+      'One row per expected variable, by name only — the deployment’s (`npx convex env list` on the linked deployment) and, when the studio mounts an AI route, the studio host’s provider key. No value reaches the report.',
+    outcome:
+      'A required variable unset fails, a recommended one warns; a half-set group (one of the revalidate pair) fails. `unknown` with no linked deployment, or under `--url`.',
+  },
+  {
+    id: 'revalidate-probe',
+    bucket: 'deployment-env',
+    summary:
+      'When the revalidate pair is set: a signed no-op `probe` event POSTed to the endpoint, proving the publish → live chain end to end.',
+    outcome:
+      'Fails on any answer but the route’s `200 {"revalidated":[]}` — a secret mismatch or an unset frontend secret (401), a frontend on another Elytra version (400), no route (404). Warns when the endpoint cannot be reached from this machine.',
+  },
+  // --- app ------------------------------------------------------------------------
+  {
+    id: 'config-valid',
+    bucket: 'app',
+    summary:
+      '`elytra.config.ts` executed through your studio’s own Vite (needs the studio’s dependencies installed) and run through the one resolver the studio boots through.',
+    outcome:
+      'Fails with every located issue (`projects.0.slug: …`); `unknown`, with the reason, when it cannot be executed here. The checks below that read the config are `unknown` then too.',
+  },
+  {
+    id: 'asset-collection',
+    bucket: 'app',
+    summary: 'A project whose collections declare asset fields resolves an asset collection.',
+    outcome: 'Fails when none resolves.',
+  },
+  {
+    id: 'presentation-targets',
+    bucket: 'app',
+    summary: 'Every collection’s `presentation.body` names fields the collection declares.',
+    outcome: 'Fails on a name the collection does not have.',
+  },
+  {
+    id: 'published-orphans',
+    bucket: 'app',
+    summary:
+      'Published documents of collections the config does not declare, read from the deployment’s public delivery snapshot.',
+    outcome: 'Warns, naming each collection and count. Printed only against a deployment, with the config resolved.',
+  },
+  {
+    id: 'project-layout',
+    bucket: 'app',
+    summary:
+      'The studio, frontend and theme locations the CLI resolved from `package.json#elytra`, and whether each was declared or defaulted.',
+    outcome: 'Fails on an invalid section or a declared path that does not exist.',
+  },
+  {
+    id: 'ai-route',
+    bucket: 'app',
+    summary:
+      'The AI route your studio’s `vite.config.ts` mounts (`createAiDevPlugin`, read from the loaded config) — it decides whether an AI provider key is expected.',
+    outcome: 'Fails when the mounted `handlerModulePath` does not exist.',
+  },
+  {
+    id: 'route-conflicts',
+    bucket: 'app',
+    summary:
+      'Two routes tied on specificity, locale scope and shape — the one router’s issue set (the same set the studio and the delivery host read), over the routes your config resolved.',
+    outcome: 'Fails on a tie; `unknown` when the config could not be resolved here (as are the next three).',
+  },
+  {
+    id: 'mount-conflicts',
+    bucket: 'app',
+    summary: 'Two hierarchy mounts on the same path in the same locale scope.',
+    outcome: 'Fails on a tie.',
+  },
+  {
+    id: 'unreachable-routes',
+    bucket: 'app',
+    summary:
+      'A declaration that can never serve content — an all-dynamic route such as `/:slug` shadowing a mount’s whole depth, a mount on a collection with no parent role, a catch-all with a dynamic prefix like `/:lang/:path*`.',
+    outcome: 'Fails on such a declaration; warns on a precedence that depends on content.',
+  },
+  {
+    id: 'redirect-loops',
+    bucket: 'app',
+    summary:
+      'The deployment’s real redirects — the enabled ones its public delivery snapshot serves, read on the same request as `published-orphans`.',
+    outcome: 'Fails on a loop or a duplicate `from` (`/old` = `/old/`); `unknown` when no deployment was read.',
+  },
+  // --- per-user -------------------------------------------------------------------
+  {
+    id: 'authenticated',
+    bucket: 'user',
+    summary: 'The signed-in session.',
+    outcome: 'Always `unknown` here — the studio boot checks it.',
+  },
+  {
+    id: 'member-role',
+    bucket: 'user',
+    summary: 'The signed-in user’s membership of the project.',
+    outcome: 'Always `unknown` here — the studio boot checks it.',
+  },
+  // --- previews -------------------------------------------------------------------
+  {
+    id: 'previews-artifacts',
+    bucket: 'previews',
+    summary: 'Printed alone when the studio holds no generated previews at all (they are optional).',
+    outcome: 'Always ok.',
+  },
+  {
+    id: 'previews-manifest',
+    bucket: 'previews',
+    summary: 'The generated previews manifest (`<studio>/elytra-previews.json`) is present and parses.',
+    outcome: 'Warns otherwise.',
+  },
+  {
+    id: 'previews-files',
+    bucket: 'previews',
+    summary: 'Every manifest entry’s image file is present.',
+    outcome: 'Warns, naming the first missing file.',
+  },
+  {
+    id: 'previews-orphans',
+    bucket: 'previews',
+    summary: 'Image files no manifest entry references.',
+    outcome: 'Warns, naming the first.',
+  },
+  {
+    id: 'previews-staleness',
+    bucket: 'previews',
+    summary: 'Input-hash staleness needs the component registry, so it is not judged here.',
+    outcome: 'Always `unknown` — run `elytra previews --check`.',
+  },
+]
+
+/** Is a printed check id the catalogue entry `entry`? (`env:*` covers every `env:<NAME>` row.) */
+export function isCheckOf(entry, id) {
+  return entry.id.endsWith(':*') ? id.startsWith(entry.id.slice(0, -1)) : entry.id === id
+}
+
+/** The expected deployment variables, read from core's one declaration (every one the doctor may list). */
+function expectedEnvNames() {
+  return expectedDeploymentEnv({ aiRouteConfigured: true }).map((expected) =>
+    expected.anyOf ? expected.anyOf.join(' / ') : expected.name,
+  )
+}
+
+/** Wrap prose to `width` columns, every line prefixed with `indent`. */
+function wrap(text, indent, width = 80) {
+  const lines = []
+  let line = ''
+  for (const word of text.split(/\s+/)) {
+    if (line && indent.length + line.length + 1 + word.length > width) {
+      lines.push(indent + line)
+      line = word
+    } else {
+      line = line ? `${line} ${word}` : word
+    }
+  }
+  if (line) lines.push(indent + line)
+  return lines.join('\n')
+}
+
+/** The check list `elytra doctor --help` prints, grouped by bucket. Pure. */
+export function formatDoctorChecksHelp() {
+  const out = []
+  for (const { bucket, title } of DOCTOR_BUCKETS) {
+    out.push(`  ${title}:`)
+    for (const check of DOCTOR_CHECKS.filter((entry) => entry.bucket === bucket)) {
+      out.push(`    ${check.id}`)
+      const summary =
+        check.id === 'env:*' ? `${check.summary} Expected: ${expectedEnvNames().join(', ')}.` : check.summary
+      out.push(wrap(summary.replace(/`/g, ''), '      '))
+    }
+  }
+  return out.join('\n')
+}
+
+/** The guide's check table (`docs/guide/06-cli-reference.md`, a generated region). Pure. */
+export function formatDoctorChecksMarkdown() {
+  const out = ['| Bucket | Check | What it looks at | Outcome |', '| --- | --- | --- | --- |']
+  for (const { bucket, title } of DOCTOR_BUCKETS) {
+    DOCTOR_CHECKS.filter((entry) => entry.bucket === bucket).forEach((check, index) => {
+      const summary =
+        check.id === 'env:*'
+          ? `${check.summary} Expected: ${expectedEnvNames()
+              .map((name) => `\`${name}\``)
+              .join(', ')}.`
+          : check.summary
+      out.push(`| ${index === 0 ? `**${title}**` : ''} | \`${check.id}\` | ${summary} | ${check.outcome} |`)
+    })
+  }
+  return out.join('\n')
+}