@elytracms/cli 0.0.10 → 0.0.12

package/README.md

@@ -16,6 +16,18 @@ elytra dev      Start the studio + frontend (and Convex in connected mode)
 
 elytra build    Build the studio + frontend (and deploy Convex in connected
                 mode), in order — failing as a whole if any step fails.
+                Optional target (the per-app Vercel build commands):
+                  elytra build studio     Convex deploy coupled with the studio
+                                          build (functions + client in lockstep)
+                  elytra build frontend   frontend build only
+
+elytra init     First-run setup: provision Convex, generate the auth signing
+                keys, verify readiness. Idempotent — safe to re-run.
+
+elytra doctor   Diagnose the active deployment's readiness and print each fix.
+                Includes the expected deployment env vars, reported set/missing
+                by NAME only — values are never read into the report or printed.
+                Read-only; exits non-zero if any check fails.
 
 elytra help     Show help
 elytra version  Show version
@@ -36,3 +48,58 @@ uses):
 It orchestrates and owns the process lifecycle; it does not reimplement Vite,
 Next, or Convex — each step shells out to the underlying tool and inherits its
 watch/HMR/build behaviour.
+
+## Deploying (Vercel)
+
+Deploys are git-push-driven — there is no `elytra deploy`. A consuming repo
+deploys as **two Vercel projects** on the same git repo, plus the Convex
+deployment that the studio build pushes functions to:
+
+| Vercel project | Root Directory | Build command                     |
+| -------------- | -------------- | --------------------------------- |
+| studio         | `studio`       | `pnpm exec elytra build studio`   |
+| frontend       | `frontend`     | `pnpm exec elytra build frontend` |
+
+`elytra build studio` wraps Convex's recommended Vercel integration: it runs
+`convex deploy --cmd 'pnpm run build'`, which pushes your Convex functions and
+then runs the studio build with the deployment URL injected into its env
+(`VITE_CONVEX_URL`). The built studio always matches the functions it was
+deployed with, and there is no hand-set URL to drift out of sync with the
+deploy key's target. `elytra build frontend` runs the Next.js build only — the
+frontend reads its Convex URL at runtime, not at build time.
+
+### Which env lives on which plane
+
+Env lives on three planes. Keep them apart — most misconfiguration is a value
+set on the wrong plane:
+
+1. **Local `.env` files** (`studio/.env`, `frontend/.env`) — local development
+   only. Gitignored; they never reach Vercel or the Convex deployment.
+2. **Vercel project env** — build- and runtime-env per Vercel project:
+   - _Studio project:_ `CONVEX_DEPLOY_KEY` (a production deploy key generated
+     in the Convex dashboard — it selects **and** authorizes the deployment).
+     Do not hand-set `VITE_CONVEX_URL`; the build injects it (above). Optional:
+     the AI provider key (`ANTHROPIC_API_KEY`, or the Vercel AI Gateway) for
+     the studio's AI route — a host/server env, never `VITE_`-prefixed.
+   - _Frontend project:_ `ELYTRA_CONVEX_URL`, `ELYTRA_PROJECT_ID`,
+     `REVALIDATE_SECRET`, `STUDIO_ORIGIN`, `DRAFT_PREVIEW_TOKEN` — see the
+     scaffold's CONNECT.md for what each pairs with.
+3. **Convex deployment env** — set with `npx convex env set` (from `studio/`);
+   lives on the deployment itself, visible in the Convex dashboard but in no
+   file: the auth signing keys (`JWT_PRIVATE_KEY`, `JWKS` — set via
+   `npx @convex-dev/auth`), `SITE_URL`, and the publish/draft pair
+   `CANVAS_PROJECT_SCOPE` / `CANVAS_REVALIDATE_ENDPOINT` /
+   `CANVAS_REVALIDATE_SECRET` and `DRAFT_PREVIEW_TOKEN` (each must match its
+   frontend-plane counterpart). `elytra doctor` diagnoses this plane's
+   readiness.
+
+Because plane 3 lives in no file, it is the easiest to overlook — `elytra
+doctor` therefore enumerates the expected vars there (auth keys, `SITE_URL`,
+plus the AI provider key on the studio-host plane when the AI route is
+present) and reports each one **set or missing, by name only**: the doctor
+parses names out of `npx convex env list` and discards every value on the
+spot — values are never stored, printed, or logged. A missing required var
+(the auth keys) fails the run with its exact fix line; a missing recommended
+var (`SITE_URL`, the AI key) is a named warning that doesn't change the exit
+code. The studio's boot-time "Deployment setup" screen lists the same
+expected vars, so the CLI and the studio tell one story.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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": ">=20"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.62"
+    "@elytracms/core": "^0.0.64"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -17,11 +17,16 @@ Commands:
              One Ctrl-C stops everything.
   build      Build the studio + frontend (and deploy Convex in connected mode),
              in order, failing as a whole if any step fails.
+             Optional target — the per-app Vercel build commands (EC-410):
+               elytra build studio     Convex deploy coupled with the studio build
+                                       (functions + client stay in lockstep)
+               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, config, membership) and print each fix. Exit non-zero
-             if any check fails. Read-only. Optional: --url <convex url>.
+             signing keys, expected deployment env vars — set/missing by NAME,
+             values never shown — config, membership) and print each fix. Exit
+             non-zero if any check fails. Read-only. Optional: --url <convex url>.
   help       Show this help
   version    Show version
 
@@ -63,20 +68,76 @@ export function planDev(project) {
   return procs
 }
 
-/** Build the ordered build steps from a project inspection. */
-export function planBuild(project) {
+/** The valid `elytra build` targets (EC-410). No target = the whole repo. */
+export const BUILD_TARGETS = ['studio', 'frontend']
+
+/**
+ * Should a studio build run the Convex deploy coupling? Same conditions as the bare
+ * build (connected + provisioned) — including against a `prod:` deployment: EC-356
+ * only forbids the continuous dev-sync watcher (`convex dev`) against production; an
+ * explicit `convex deploy` IS the correct prod path. Plus the CI/Vercel form of
+ * "connected" (EC-410): a CONVEX_DEPLOY_KEY selects and authorizes a deployment
+ * without a local link (`CONVEX_DEPLOYMENT`) or a hand-set `VITE_CONVEX_URL` — on
+ * Vercel the studio's gitignored `.env` doesn't exist, so the key is the whole
+ * signal. An explicit playground mode always wins: it never deploys anything.
+ */
+function couplesConvexDeploy(project) {
+  if (project.mode === 'playground') return false
+  return (project.mode === 'connected' && project.convexProvisioned) || Boolean(project.hasDeployKey)
+}
+
+/**
+ * Build the ordered build steps from a project inspection, optionally scoped to one
+ * target (EC-410). Bare `elytra build` (no target) keeps the whole-repo sequence
+ * unchanged: convex deploy (connected + provisioned) → studio build → frontend build.
+ *
+ * `elytra build studio` is shaped to be the studio Vercel project's build command:
+ * when the Convex coupling applies it runs Convex's recommended single-command
+ * integration — `convex deploy --cmd 'pnpm run build'` — which pushes the functions
+ * and then runs the studio build with the deployment URL injected into its env
+ * (`--cmd-url-env-var-name VITE_CONVEX_URL`). The built client therefore always
+ * matches the functions it was deployed with; there is no hand-set duplicate URL to
+ * drift (the exact hazard EC-410 names).
+ *
+ * `elytra build frontend` builds the frontend only: its Convex URL
+ * (`ELYTRA_CONVEX_URL`) is runtime env, not a build-time coupling.
+ */
+export function planBuild(project, target) {
   const steps = []
   const studioDir = join(project.root, 'studio')
   const frontendDir = join(project.root, 'frontend')
+  const studioBuild = { name: 'studio build', command: 'pnpm', args: ['run', 'build'], cwd: studioDir }
+  const frontendBuild = { name: 'frontend build', command: 'pnpm', args: ['run', 'build'], cwd: frontendDir }
+
+  if (target === 'frontend') {
+    if (project.apps.frontend) steps.push(frontendBuild)
+    return steps
+  }
+
+  if (target === 'studio') {
+    if (!project.apps.studio) return steps
+    if (couplesConvexDeploy(project)) {
+      steps.push({
+        name: 'convex deploy + studio build',
+        command: 'pnpm',
+        args: ['exec', 'convex', 'deploy', '--cmd-url-env-var-name', 'VITE_CONVEX_URL', '--cmd', 'pnpm run build'],
+        cwd: studioDir,
+      })
+    } else {
+      steps.push(studioBuild)
+    }
+    return steps
+  }
 
+  // Bare `elytra build` — the whole-repo sequence, byte-for-byte as before EC-410.
   if (project.mode === 'connected' && project.convexProvisioned) {
     steps.push({ name: 'convex deploy', command: 'pnpm', args: ['exec', 'convex', 'deploy'], cwd: studioDir })
   }
   if (project.apps.studio) {
-    steps.push({ name: 'studio build', command: 'pnpm', args: ['run', 'build'], cwd: studioDir })
+    steps.push(studioBuild)
   }
   if (project.apps.frontend) {
-    steps.push({ name: 'frontend build', command: 'pnpm', args: ['run', 'build'], cwd: frontendDir })
+    steps.push(frontendBuild)
   }
   return steps
 }
@@ -114,9 +175,28 @@ export function describeMode(project) {
   return null
 }
 
-function noteMode(project) {
-  const note = describeMode(project)
-  if (note) log(note)
+/**
+ * The mode note for `elytra build [target]` (EC-410) — pure, like {@link describeMode}.
+ * The frontend target makes no backend decision (its Convex URL is runtime env), so it
+ * gets no note. The studio target adds the deploy-key case — a CONVEX_DEPLOY_KEY is how
+ * a CI/Vercel build is "connected" without a locally linked deployment, so the generic
+ * "not provisioned"/"not configured" notes would be wrong — and otherwise falls back to
+ * {@link describeMode}, keeping the bare build's output unchanged.
+ */
+export function describeBuildMode(project, target) {
+  if (target === 'frontend') return null
+  if (
+    target === 'studio' &&
+    project.mode !== 'playground' &&
+    project.hasDeployKey &&
+    !(project.mode === 'connected' && project.convexProvisioned)
+  ) {
+    return (
+      'Mode: connected via CONVEX_DEPLOY_KEY (CI/Vercel). `convex deploy` pushes the Convex\n' +
+      'functions and injects the deployment URL into the studio build (VITE_CONVEX_URL).'
+    )
+  }
+  return describeMode(project)
 }
 
 /** Read a `--name value` or `--name=value` flag from argv. */
@@ -238,7 +318,17 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       return 1
     }
     const studioEnv = resolveStudioEnv(project.root, env)
-    return runDoctor({ env: studioEnv, fetchImpl, log: emit, url: flagValue(argv, '--url') })
+    return runDoctor({
+      env: studioEnv,
+      fetchImpl,
+      log: emit,
+      url: flagValue(argv, '--url'),
+      // EC-399: where `convex env list` runs (name enumeration — presence only),
+      // and whether the AI provider-key expectation applies.
+      studioDir: project.apps.studio ? join(project.root, 'studio') : undefined,
+      aiRouteConfigured: project.hasAiRoute,
+      exec,
+    })
   }
 
   if (command === 'init') {
@@ -256,12 +346,22 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
     return 1
   }
 
+  // `elytra build [studio|frontend]` (EC-410). Validated before project inspection so
+  // a typo'd target fails the same clear way everywhere (CI included).
+  const target = command === 'build' ? argv[1] : undefined
+  if (target !== undefined && !BUILD_TARGETS.includes(target)) {
+    log(`Unknown build target: ${target}`)
+    log(`Valid targets: ${BUILD_TARGETS.join(', ')} — or no target to build the whole repo.`)
+    return 1
+  }
+
   const project = inspectProject(cwd, env)
   if (project.issues.length > 0) {
     reportIssues(project.issues)
     return 1
   }
-  noteMode(project)
+  const note = command === 'build' ? describeBuildMode(project, target) : describeMode(project)
+  if (note) log(note)
 
   if (command === 'dev') {
     // First-run safety net: ensure the auth signing keys exist before starting the
@@ -283,9 +383,13 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
   }
 
   // build
-  const steps = planBuild(project)
+  const steps = planBuild(project, target)
   if (steps.length === 0) {
-    log('Nothing to build — no studio/ or frontend/ app found.')
+    log(
+      target
+        ? `Nothing to build — no ${target}/ app found.`
+        : 'Nothing to build — no studio/ or frontend/ app found.',
+    )
     return 1
   }
   const code = await runSequential(steps)

package/src/doctor.js

@@ -1,8 +1,10 @@
 import {
   backendSiteUrl,
   checkDeploymentReady,
+  expectedDeploymentEnv,
   probeAuthSigningKeys,
 } from '@elytracms/core/export-sync/deployment-ready'
+import { defaultConvexExec } from './provision.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -40,6 +42,10 @@ export function resolveDoctorTarget(env = {}, { url } = {}) {
       url: chosenUrl,
       siteUrl: env.VITE_CONVEX_SITE_URL || env.CONVEX_SITE_URL,
       playgroundFlagAlsoSet: playgroundFlag && !explicit,
+      // EC-399: an explicit --url that differs from the env-resolved deployment means
+      // `convex env list` (which reads the LINKED deployment) would enumerate the
+      // wrong deployment's env — the env checks then stay `unknown`, never wrong.
+      urlOverridesEnv: Boolean(explicit) && explicit !== envUrl,
     }
   }
   if (playgroundFlag) return { kind: 'playground' }
@@ -86,14 +92,106 @@ export async function gatherFacts(target, { fetchImpl = fetch } = {}) {
   }
 }
 
+// --- Deployment env-var presence (EC-399) --------------------------------------
+//
+// The Convex deployment's own env (`npx convex env set …`) lives in NO file a
+// developer can see — the invisible plane the owner named. The doctor enumerates
+// which of the EXPECTED vars are set. PRESENCE ONLY, by hard rule: names are parsed
+// out and every value is discarded in the same pass; no value is ever stored on a
+// fact, printed, or logged.
+
+/**
+ * Parse `npx convex env list` output into the NAMES of set vars — values are
+ * discarded at the parse boundary and never leave this function. Non-matching
+ * lines (headers, notices) are ignored.
+ */
+export function parseEnvListNames(stdout) {
+  const names = []
+  for (const line of String(stdout).split('\n')) {
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(line)
+    if (match) names.push(match[1])
+  }
+  return names
+}
+
+/** Strip everything after `=` per line — safe error text that can never carry a value. */
+function stripValues(text) {
+  return String(text)
+    .split('\n')
+    .map((line) => line.replace(/=.*$/, '=…'))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+/**
+ * Enumerate the linked deployment's set env-var NAMES via `npx convex env list`
+ * (read-only; the convex CLI resolves the deployment from `studio/.env.local` /
+ * `CONVEX_DEPLOY_KEY` itself). Returns `{ names }` on success, `{ detail }` (safe,
+ * value-stripped) when the command failed — the checks then surface `unknown`.
+ */
+export function gatherDeploymentEnvNames({ cwd, exec = defaultConvexExec } = {}) {
+  const { status, stdout, stderr, error } = exec(['env', 'list'], { cwd })
+  if (status !== 0) {
+    const reason = stripValues(error ? error.message : stderr).slice(0, 200)
+    return { detail: `\`npx convex env list\` failed${reason ? ` (${reason})` : ''} — deployment env names not enumerated.` }
+  }
+  return { names: parseEnvListNames(stdout) }
+}
+
+/**
+ * Build the expected-env facts for a convex target (EC-399): the engine contract
+ * (auth always; AI when the studio ships the AI route), the studio-host presence
+ * booleans from the resolved studio env, and — when the target IS the linked
+ * deployment — the deployment's set names. Every ungathered source carries an
+ * honest reason and surfaces as `unknown`, never a wrong answer.
+ */
+export function gatherDeploymentEnvFacts({ env = {}, target, studioDir, aiRouteConfigured = false, exec } = {}) {
+  const expected = expectedDeploymentEnv({ aiRouteConfigured })
+
+  // Studio-host plane: reduce the resolved studio env to presence booleans
+  // (the EC-410 `hasDeployKey` house style — values never reach a variable that lives on).
+  const hostPresence = {}
+  for (const expectation of expected) {
+    if (expectation.plane !== 'studio-host') continue
+    for (const name of expectation.anyOf ?? [expectation.name]) {
+      hostPresence[name] = Boolean(env[name] && String(env[name]).trim() !== '')
+    }
+  }
+  const facts = { expected, hostPresence }
+
+  // Deployment plane: only for the linked deployment, and only when there is one.
+  if (target?.urlOverridesEnv) {
+    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.'
+  } 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.'
+  } else {
+    const { names, detail } = gatherDeploymentEnvNames({ cwd: studioDir, exec })
+    if (names) facts.deploymentSetNames = names
+    else facts.unavailableDetail = detail
+  }
+  return facts
+}
+
 // --- Formatting (pure) -------------------------------------------------------
 
-const GLYPH = { ok: '✓', fail: '✗', unknown: '?' }
-const BUCKET_TITLE = { deployment: 'Deployment', app: 'App', user: 'Per-user' }
+const GLYPH = { ok: '✓', warn: '!', fail: '✗', unknown: '?' }
+const BUCKET_TITLE = {
+  deployment: 'Deployment',
+  'deployment-env': 'Deployment env',
+  app: 'App',
+  user: 'Per-user',
+}
 
 /**
  * Render a `DeploymentReadinessReport` as the bucketed doctor report (pure — no I/O,
- * no color, so it's directly testable). Failing checks print their copy-pasteable fix.
+ * no color, so it's directly testable). Failing AND warning checks print their
+ * copy-pasteable fix (EC-399: a `warn` is a named, remediated finding that never
+ * fails the exit code).
  */
 export function formatReport(report) {
   const lines = []
@@ -105,14 +203,15 @@ export function formatReport(report) {
       lines.push(`${BUCKET_TITLE[currentBucket] ?? currentBucket}:`)
     }
     lines.push(`  ${GLYPH[check.status] ?? '?'} ${check.id.padEnd(22)} ${check.detail}`)
-    if (check.status === 'fail' && check.fix) lines.push(`      fix: ${check.fix}`)
+    if ((check.status === 'fail' || check.status === 'warn') && check.fix) lines.push(`      fix: ${check.fix}`)
   }
 
-  const counts = { ok: 0, fail: 0, unknown: 0 }
+  const counts = { ok: 0, warn: 0, fail: 0, unknown: 0 }
   for (const c of report.checks) counts[c.status] = (counts[c.status] ?? 0) + 1
   lines.push('')
   if (report.ok) {
-    lines.push(`✓ No blocking problems (${counts.ok} ok, ${counts.unknown} not checked here).`)
+    const warnPart = counts.warn > 0 ? `, ${counts.warn} warning(s)` : ''
+    lines.push(`✓ No blocking problems (${counts.ok} ok${warnPart}, ${counts.unknown} not checked here).`)
   } else {
     lines.push(`✗ ${counts.fail} check(s) failed — fix the items above, then re-run \`elytra doctor\`.`)
   }
@@ -124,9 +223,20 @@ export function formatReport(report) {
 /**
  * Run the doctor against a project's studio env. Returns the process exit code
  * (0 when the report has no failing check, 1 otherwise). `env`, `fetchImpl`, `log`,
- * and `url` are injectable for tests.
+ * `url`, and `exec` are injectable for tests. `studioDir` (where `convex env list`
+ * runs) and `aiRouteConfigured` enable the deployment-env bucket (EC-399); without a
+ * studio dir the env checks stay honest `unknown`s. Playground stays untouched — no
+ * deployment, no env bucket.
  */
-export async function runDoctor({ env = {}, fetchImpl = fetch, log = (l) => console.log(l), url } = {}) {
+export async function runDoctor({
+  env = {},
+  fetchImpl = fetch,
+  log = (l) => console.log(l),
+  url,
+  studioDir,
+  aiRouteConfigured = false,
+  exec,
+} = {}) {
   const target = resolveDoctorTarget(env, { url })
 
   log('Elytra deployment doctor')
@@ -142,6 +252,9 @@ export async function runDoctor({ env = {}, fetchImpl = fetch, log = (l) => cons
   }
 
   const facts = await gatherFacts(target, { fetchImpl })
+  if (target.kind === 'convex') {
+    facts.deploymentEnv = gatherDeploymentEnvFacts({ env, target, studioDir, aiRouteConfigured, exec })
+  }
   const report = checkDeploymentReady(facts)
   log(formatReport(report))
   return report.ok ? 0 : 1

package/src/project.js

@@ -94,7 +94,8 @@ export function isProdDeploymentSelector(env = {}) {
 
 /**
  * Inspect a consuming repo. Returns:
- *   { root, apps: {studio, frontend}, mode, convexProvisioned, isProdDeployment, issues }
+ *   { root, apps: {studio, frontend}, mode, convexProvisioned, isProdDeployment,
+ *     hasDeployKey, hasAiRoute, issues }
  * `issues` are actionable, human-readable prerequisite problems (empty = ok).
  */
 export function inspectProject(cwd, processEnv = {}) {
@@ -106,6 +107,8 @@ export function inspectProject(cwd, processEnv = {}) {
       mode: 'unknown',
       convexProvisioned: false,
       isProdDeployment: false,
+      hasDeployKey: false,
+      hasAiRoute: false,
       issues: [
         'No elytra.config.ts found in this directory or any parent. Run `elytra` from inside an Elytra project (or scaffold one with `npm create elytra@latest`).',
       ],
@@ -135,5 +138,18 @@ export function inspectProject(cwd, processEnv = {}) {
   const convexProvisioned = Boolean(studioEnv.CONVEX_DEPLOYMENT)
   const isProdDeployment = isProdDeploymentSelector(studioEnv)
 
-  return { root, apps, mode, convexProvisioned, isProdDeployment, issues }
+  // A CI-style deploy key (CONVEX_DEPLOY_KEY) selects AND authorizes a deployment
+  // without a local link — it is how a Vercel/CI build is "connected" (EC-410; the
+  // studio's `.env` is gitignored, so the key is often the ONLY backend signal
+  // there). Surfaced as its own fact: it never flips `mode`/`convexProvisioned`,
+  // so `elytra dev` and the bare `elytra build` are unchanged by its presence.
+  const hasDeployKey = Boolean(studioEnv.CONVEX_DEPLOY_KEY)
+
+  // Is the studio's AI route present? (EC-399 — drives the AI provider-key env
+  // expectation in `elytra doctor`.) Convention-aware like everything here: the
+  // scaffold mounts the handler at `studio/src/server/ai-handler.ts` (the
+  // `createAiDevPlugin` default path); we never execute config to find out.
+  const hasAiRoute = apps.studio && existsSync(join(root, 'studio', 'src', 'server', 'ai-handler.ts'))
+
+  return { root, apps, mode, convexProvisioned, isProdDeployment, hasDeployKey, hasAiRoute, issues }
 }