@elytracms/cli 0.0.1 → 0.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -16,8 +16,11 @@
   "engines": {
     "node": ">=20"
   },
+  "dependencies": {
+    "@elytracms/core": "^0.0.54"
+  },
   "devDependencies": {
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "start": "node ./index.js",

package/src/cli.js

@@ -1,6 +1,9 @@
+import { spawnSync } from 'node:child_process'
 import { join } from 'node:path'
 import { stdout } from 'node:process'
-import { inspectProject } from './project.js'
+import { runDoctor } from './doctor.js'
+import { inspectProject, resolveStudioEnv } from './project.js'
+import { ensureAuthKeys } from './provision.js'
 import { runGroup, runSequential } from './run.js'
 
 const HELP = `
@@ -14,6 +17,11 @@ 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.
+  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>.
   help       Show this help
   version    Show version
 
@@ -29,14 +37,20 @@ function reportIssues(issues) {
   for (const issue of issues) log(`  • ${issue}`)
 }
 
-/** Build the dev process group from a project inspection. */
+/**
+ * Build the dev process group from a project inspection. `convex dev` (the continuous
+ * dev-sync watcher — it pushes local function code to the target on every save) is only
+ * ever added for a provisioned, non-prod deployment: against a `prod:` selector (EC-356)
+ * it is never started, prod-safety-critical, regardless of how the studio/frontend are
+ * configured. `describeMode` explains why to the developer.
+ */
 export function planDev(project) {
   const procs = []
   const studioDir = join(project.root, 'studio')
   const frontendDir = join(project.root, 'frontend')
 
   if (project.apps.studio && project.mode === 'connected') {
-    if (project.convexProvisioned) {
+    if (project.convexProvisioned && !project.isProdDeployment) {
       procs.push({ name: 'convex', command: 'pnpm', args: ['run', 'convex:dev'], cwd: studioDir })
     }
   }
@@ -67,23 +81,140 @@ export function planBuild(project) {
   return steps
 }
 
-function noteMode(project) {
+/**
+ * The mode note to print before `dev`/`build`, or `null` when the mode needs no comment
+ * (a provisioned, non-prod connected deployment — the ordinary happy path). Pure — a
+ * direct sibling of {@link formatReport} in `doctor.js` — so the prod-safety message
+ * (EC-356) is unit-testable without going through `run()`'s process-spawning commands.
+ */
+export function describeMode(project) {
   if (project.mode === 'playground') {
-    log('Mode: playground (in-memory, no backend). Convex is not started.')
-  } else if (project.mode === 'connected' && !project.convexProvisioned) {
-    log(
+    return 'Mode: playground (in-memory, no backend). Convex is not started.'
+  }
+  if (project.mode === 'connected' && project.isProdDeployment) {
+    return (
+      'Mode: connected to a `prod:` Convex deployment. `convex dev` (the continuous dev-sync\n' +
+      'watcher, which pushes local function code on every save) is never started against\n' +
+      'production. Studio and frontend still start and talk to it over the client SDK. To push\n' +
+      'function changes, deploy explicitly: `cd studio && npx convex deploy`.'
+    )
+  }
+  if (project.mode === 'connected' && !project.convexProvisioned) {
+    return (
       'Mode: connected, but no Convex deployment is provisioned yet. Skipping the\n' +
-        'backend — run `cd studio && npx convex dev` once to provision it. See CONNECT.md.',
+      'backend — run `cd studio && npx convex dev` once to provision it. See CONNECT.md.'
     )
-  } else if (project.mode === 'unconfigured') {
-    log(
+  }
+  if (project.mode === 'unconfigured') {
+    return (
       'Backend not configured. Defaulting to the frontends only. Set VITE_ELYTRA_MODE=\n' +
-        'playground or VITE_CONVEX_URL in studio/.env. See CONNECT.md.',
+      'playground or VITE_CONVEX_URL in studio/.env. See CONNECT.md.'
+    )
+  }
+  return null
+}
+
+function noteMode(project) {
+  const note = describeMode(project)
+  if (note) log(note)
+}
+
+/** Read a `--name value` or `--name=value` flag from argv. */
+function flagValue(argv, name) {
+  const i = argv.indexOf(name)
+  if (i !== -1 && i + 1 < argv.length) return argv[i + 1]
+  const eq = argv.find((a) => a.startsWith(`${name}=`))
+  return eq ? eq.slice(name.length + 1) : undefined
+}
+
+/** Provision a Convex deployment once (foreground; convex drives its own account UX). */
+function provisionConvexOnce(studioDir) {
+  const res = spawnSync('npx', ['convex', 'dev', '--once'], { cwd: studioDir, stdio: 'inherit' })
+  return res.status ?? 1
+}
+
+/**
+ * `elytra init` — ordered, idempotent first-run setup: provision → ensure auth keys →
+ * verify → checklist. Re-runnable safely: every already-satisfied step is a no-op. The
+ * decisions mirror {@link planSetup}; `provision`/`exec`/`fetchImpl` are injectable.
+ */
+export async function runInit(project, { log: emit = log, fetchImpl, exec, provision = provisionConvexOnce } = {}) {
+  const studioDir = join(project.root, 'studio')
+  emit('Elytra first-run setup')
+  emit('')
+
+  // 1. Provision a backend deployment.
+  if (project.mode === 'unconfigured') {
+    emit('1. Provision — cannot continue: no backend configured.')
+    emit('   Set VITE_CONVEX_URL, or VITE_ELYTRA_MODE=playground, in studio/.env. See CONNECT.md.')
+    return 1
+  }
+  if (project.mode === 'playground') {
+    emit('1. Provision — skipped (playground mode; in-memory, no backend deployment).')
+  } else if (project.convexProvisioned) {
+    // EC-356: a `prod:` deployment is still "already provisioned" (skip is correct), but
+    // say so explicitly — `convex dev` is never the right next step against production.
+    emit(
+      project.isProdDeployment
+        ? '1. Provision — a prod: Convex deployment is already provisioned. `convex dev` is never ' +
+            'run against it — deploy function changes explicitly with `npx convex deploy`.'
+        : '1. Provision — a Convex deployment is already provisioned.',
     )
+  } else if (project.isProdDeployment) {
+    // EC-356: no deployment is linked locally (CONVEX_DEPLOYMENT unset), but a prod:
+    // selector is present some other way (e.g. CONVEX_DEPLOY_KEY) — provisioning via the
+    // dev-sync watcher (`convex dev --once`) is never safe to run against it automatically.
+    emit('1. Provision — cannot continue safely: a prod: selector is set, but no deployment is linked here.')
+    emit('   Provisioning via `convex dev` is skipped against production. Link and deploy explicitly: `cd studio && npx convex deploy`.')
+    return 1
+  } else {
+    emit('1. Provision — provisioning a Convex deployment (convex dev --once)…')
+    const code = provision(studioDir)
+    const reinspected = inspectProject(project.root)
+    if (code !== 0 || !reinspected.convexProvisioned) {
+      emit('   Provisioning did not complete. Run `cd studio && npx convex dev` once, then re-run `elytra init`.')
+      return 1
+    }
+    project = reinspected
+  }
+
+  // 2. Ensure the Convex Auth signing keys (idempotent; never overwrites).
+  if (project.mode !== 'playground' && project.convexProvisioned) {
+    emit('')
+    emit('2. Auth signing keys —')
+    try {
+      const result = ensureAuthKeys({ cwd: studioDir, exec, log: (l) => emit(`   ${l}`) })
+      if (result.action === 'partial') return 1
+    } catch (error) {
+      emit(`   Could not set the keys: ${error.message}`)
+      return 1
+    }
+  } else {
+    emit('')
+    emit('2. Auth signing keys — skipped (no provisioned Convex deployment).')
+  }
+
+  // 3. Verify readiness (the shared elytra doctor check).
+  emit('')
+  emit('3. Verify —')
+  const env = resolveStudioEnv(project.root)
+  const code = await runDoctor({ env, fetchImpl, log: (l) => emit(`   ${l}`) })
+
+  // 4. Ready checklist.
+  emit('')
+  if (project.mode === 'playground') {
+    emit('✅ ready — run `elytra dev`, open the studio, and sign in with the seeded dev users.')
+    return 0
   }
+  if (code === 0) {
+    emit('✅ ready — run `elytra dev`, open the studio and sign in; first sign-in is admin.')
+  } else {
+    emit('Setup incomplete — resolve the failing checks above, then re-run `elytra init`.')
+  }
+  return code
 }
 
-export async function run(argv, { cwd = process.cwd(), env = process.env } = {}) {
+export async function run(argv, { cwd = process.cwd(), env = process.env, emit = log, exec, fetchImpl } = {}) {
   const command = argv[0] ?? 'help'
 
   if (command === 'help' || command === '-h' || command === '--help') {
@@ -98,6 +229,27 @@ export async function run(argv, { cwd = process.cwd(), env = process.env } = {})
     return 0
   }
 
+  // `doctor` is a read-only diagnostic: it needs the repo root + env + network, but not
+  // installed deps — so it is not blocked by a missing node_modules.
+  if (command === 'doctor') {
+    const project = inspectProject(cwd, env)
+    if (!project.root) {
+      reportIssues(project.issues)
+      return 1
+    }
+    const studioEnv = resolveStudioEnv(project.root, env)
+    return runDoctor({ env: studioEnv, fetchImpl, log: emit, url: flagValue(argv, '--url') })
+  }
+
+  if (command === 'init') {
+    const project = inspectProject(cwd, env)
+    if (project.issues.length > 0) {
+      reportIssues(project.issues)
+      return 1
+    }
+    return runInit(project, { log: emit, fetchImpl, exec })
+  }
+
   if (command !== 'dev' && command !== 'build') {
     log(`Unknown command: ${command}\n`)
     log(HELP)
@@ -112,6 +264,15 @@ export async function run(argv, { cwd = process.cwd(), env = process.env } = {})
   noteMode(project)
 
   if (command === 'dev') {
+    // First-run safety net: ensure the auth signing keys exist before starting the
+    // backend (idempotent — a no-op when they're already set). Never blocks dev.
+    if (project.mode === 'connected' && project.convexProvisioned) {
+      try {
+        ensureAuthKeys({ cwd: join(project.root, 'studio'), exec, log: (l) => log(`[setup] ${l}`) })
+      } catch (error) {
+        log(`[setup] auth-keys preflight skipped: ${error.message}`)
+      }
+    }
     const procs = planDev(project)
     if (procs.length === 0) {
       log('Nothing to run — no studio/ or frontend/ app found.')

package/src/doctor.js

@@ -0,0 +1,148 @@
+import {
+  backendSiteUrl,
+  checkDeploymentReady,
+  probeAuthSigningKeys,
+} from '@elytracms/core/export-sync/deployment-ready'
+
+/**
+ * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
+ * `DeploymentSetupGate`. It runs the SAME shared `checkDeploymentReady()` contract
+ * (EC-258) against the active deployment from **node**, so a developer can diagnose a
+ * half-provisioned env without opening the studio — and, crucially, gets a *definitive*
+ * `auth-signing-keys` answer the browser can't produce (the JWKS route sets no CORS, so
+ * the studio reports it `unknown`; node has no such limit).
+ *
+ * Read-only: it only fetches the deployment's public URL and its public JWKS endpoint.
+ * It never writes env, never provisions. Facts it can't gather from a bundler-less CLI
+ * (config validity, resolved collections, the auth session) are omitted → `unknown`.
+ */
+
+// --- Target resolution -------------------------------------------------------
+
+/**
+ * Decide which deployment the doctor diagnoses from the resolved studio env.
+ *
+ * A configured `VITE_CONVEX_URL` is preferred over the `VITE_ELYTRA_MODE=playground`
+ * run-mode flag: that flag only selects the studio's in-memory *adapter*, whereas the
+ * doctor's job is to validate the real deployment you configured. So a repo that runs
+ * playground locally but points at a Convex deployment (e.g. the demo) is diagnosed
+ * against that deployment — with a note that the studio itself runs in-memory.
+ */
+export function resolveDoctorTarget(env = {}, { url } = {}) {
+  const explicit = url && url.trim() !== '' ? url.trim() : undefined
+  const envUrl = env.VITE_CONVEX_URL || env.CONVEX_URL
+  const chosenUrl = explicit || envUrl
+  const playgroundFlag = env.VITE_ELYTRA_MODE === 'playground'
+
+  if (chosenUrl) {
+    return {
+      kind: 'convex',
+      url: chosenUrl,
+      siteUrl: env.VITE_CONVEX_SITE_URL || env.CONVEX_SITE_URL,
+      playgroundFlagAlsoSet: playgroundFlag && !explicit,
+    }
+  }
+  if (playgroundFlag) return { kind: 'playground' }
+  return {
+    kind: 'unconfigured',
+    detail: 'No VITE_CONVEX_URL is set, and VITE_ELYTRA_MODE is not "playground", in studio/.env.',
+  }
+}
+
+// --- Probes (node) -----------------------------------------------------------
+
+/**
+ * Reachability probe: any HTTP response means the deployment answered; a thrown fetch
+ * (DNS/connection) means it did not. (The studio uses `adapter.status()`; the CLI has
+ * no convex client, so a plain GET to the deployment's client URL is the node analogue.)
+ */
+export async function probeReachable(url, fetchImpl = fetch) {
+  try {
+    const res = await fetchImpl(url, { method: 'GET' })
+    return { available: true, detail: `HTTP ${res.status}` }
+  } catch (error) {
+    return { available: false, detail: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/**
+ * Gather the readiness facts a node CLI can definitively produce for a target. The
+ * app/user facts are intentionally omitted (the CLI doesn't execute `elytra.config.ts`
+ * and has no auth session) → the contract renders them `unknown`.
+ */
+export async function gatherFacts(target, { fetchImpl = fetch } = {}) {
+  if (target.kind === 'playground') return { backend: { kind: 'playground' } }
+  if (target.kind === 'unconfigured') return { backend: { kind: 'unconfigured', detail: target.detail } }
+
+  const reachable = await probeReachable(target.url, fetchImpl)
+  const siteUrl = backendSiteUrl(target.url, target.siteUrl)
+  const authKeys = await probeAuthSigningKeys(siteUrl, fetchImpl)
+  return {
+    backend: { kind: 'convex', url: target.url },
+    reachable,
+    authKeys,
+    // A configured URL means a deployment is wired; leave `provisioned` unset (→ ok).
+    // config/collections/session omitted → the app + user checks surface as `unknown`.
+  }
+}
+
+// --- Formatting (pure) -------------------------------------------------------
+
+const GLYPH = { ok: '✓', fail: '✗', unknown: '?' }
+const BUCKET_TITLE = { deployment: 'Deployment', 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.
+ */
+export function formatReport(report) {
+  const lines = []
+  let currentBucket = null
+  for (const check of report.checks) {
+    if (check.bucket !== currentBucket) {
+      currentBucket = check.bucket
+      lines.push('')
+      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}`)
+  }
+
+  const counts = { ok: 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).`)
+  } else {
+    lines.push(`✗ ${counts.fail} check(s) failed — fix the items above, then re-run \`elytra doctor\`.`)
+  }
+  return lines.join('\n')
+}
+
+// --- Command -----------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export async function runDoctor({ env = {}, fetchImpl = fetch, log = (l) => console.log(l), url } = {}) {
+  const target = resolveDoctorTarget(env, { url })
+
+  log('Elytra deployment doctor')
+  if (target.kind === 'convex') {
+    log(`Checking Convex deployment: ${target.url}`)
+    if (target.playgroundFlagAlsoSet) {
+      log('Note: VITE_ELYTRA_MODE=playground is set — the studio runs in-memory; this report checks the configured Convex deployment.')
+    }
+  } else if (target.kind === 'playground') {
+    log('Playground mode (VITE_ELYTRA_MODE=playground) — in-memory, seeded, no backend deployment to check.')
+  } else {
+    log('No backend configured.')
+  }
+
+  const facts = await gatherFacts(target, { fetchImpl })
+  const report = checkDeploymentReady(facts)
+  log(formatReport(report))
+  return report.ok ? 0 : 1
+}

package/src/project.js

@@ -49,13 +49,52 @@ function resolveEnv(appDir, processEnv) {
   }
 }
 
+/**
+ * Resolve the studio app's effective env (`studio/.env` ← `.env.local` ← process.env) —
+ * the same signal the studio itself reads. Used by `elytra doctor` to find the Convex
+ * deployment to diagnose. Exported so the doctor and project inspection share one reader.
+ */
+export function resolveStudioEnv(root, processEnv = {}) {
+  return resolveEnv(join(root, 'studio'), processEnv)
+}
+
 function isApp(root, name) {
   return existsSync(join(root, name, 'package.json'))
 }
 
+/**
+ * Parse a Convex deployment selector's `<type>:` prefix (`dev:adjective-animal-123`,
+ * `prod:…`, `preview:…`) — the shape both `CONVEX_DEPLOYMENT` (written by `npx convex dev`)
+ * and `CONVEX_DEPLOY_KEY` (a CI-style deploy key, same prefix convention) use. Pure.
+ * Returns `null` for unset/empty values or a value with no recognized `<type>:` prefix (an
+ * older/bare deployment name) — never guessed as prod. Lower-cased so a hand-edited env
+ * value (`PROD:…`) still classifies correctly.
+ */
+export function deploymentSelectorType(value) {
+  if (!value) return null
+  const i = value.indexOf(':')
+  if (i <= 0) return null
+  return value.slice(0, i).toLowerCase()
+}
+
+/**
+ * Detect a `prod:` Convex target from the resolved studio env (EC-356). Checked against
+ * BOTH selectors the Convex CLI reads: `CONVEX_DEPLOYMENT` (a deployment linked locally by
+ * `npx convex dev`) and `CONVEX_DEPLOY_KEY` (a CI-style deploy key that targets a deployment
+ * WITHOUT ever linking one — so a repo can be pointed at prod through this var alone, with
+ * `CONVEX_DEPLOYMENT` unset). Used to keep `elytra dev`'s continuous dev-sync watcher, and
+ * `elytra init`'s provisioning step, from ever running against production.
+ */
+export function isProdDeploymentSelector(env = {}) {
+  return (
+    deploymentSelectorType(env.CONVEX_DEPLOYMENT) === 'prod' ||
+    deploymentSelectorType(env.CONVEX_DEPLOY_KEY) === 'prod'
+  )
+}
+
 /**
  * Inspect a consuming repo. Returns:
- *   { root, apps: {studio, frontend}, mode, convexProvisioned, issues }
+ *   { root, apps: {studio, frontend}, mode, convexProvisioned, isProdDeployment, issues }
  * `issues` are actionable, human-readable prerequisite problems (empty = ok).
  */
 export function inspectProject(cwd, processEnv = {}) {
@@ -66,6 +105,7 @@ export function inspectProject(cwd, processEnv = {}) {
       apps: { studio: false, frontend: false },
       mode: 'unknown',
       convexProvisioned: false,
+      isProdDeployment: 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`).',
       ],
@@ -93,6 +133,7 @@ export function inspectProject(cwd, processEnv = {}) {
   // A Convex dev/deploy step only makes sense once a deployment is provisioned
   // (`npx convex dev` writes CONVEX_DEPLOYMENT). Otherwise we skip it and say so.
   const convexProvisioned = Boolean(studioEnv.CONVEX_DEPLOYMENT)
+  const isProdDeployment = isProdDeploymentSelector(studioEnv)
 
-  return { root, apps, mode, convexProvisioned, issues }
+  return { root, apps, mode, convexProvisioned, isProdDeployment, issues }
 }

package/src/provision.js

@@ -0,0 +1,198 @@
+import { spawnSync } from 'node:child_process'
+import { generateKeyPairSync } from 'node:crypto'
+
+/**
+ * First-run auto-provisioning for the Elytra CLI (EC-259). Folds the Convex Auth
+ * signing-key generation into `elytra init`/`elytra dev` so a developer never has to
+ * discover the `npx @convex-dev/auth` incantation — the historic footgun whose absence
+ * silently breaks ALL sign-in (Konditorei, 2026-06-22).
+ *
+ * ## Why generate keys directly (not `npx @convex-dev/auth`)
+ *
+ * `@convex-dev/auth`'s wizard is interactive (prompts for SITE_URL + an overwrite
+ * confirmation) and does MORE than keys (rewrites `auth.config.ts`, checks git). We want
+ * exactly two deployment env vars, set idempotently with zero prompts and NEVER an
+ * overwrite. So we generate the keypair here and `convex env set` it directly.
+ *
+ * The generated values are **byte-compatible** with `@convex-dev/auth`'s own
+ * `generateKeys()` (verified against its source): RS256 / 2048-bit / e=65537, the private
+ * key as a PKCS#8 PEM with newlines collapsed to spaces, and the public key as a
+ * `{ keys: [{ use: 'sig', ...jwk }] }` JWKS. Node's built-in `crypto` produces the same
+ * bytes jose does (`exportPKCS8` / `exportJWK` are thin wrappers over the same Node
+ * exports), so no `jose` dependency is needed and the Convex Auth runtime imports them
+ * unchanged (`importPKCS8(JWT_PRIVATE_KEY, 'RS256')`).
+ *
+ * The convex invocation defaults to `npx convex …` (what `@convex-dev/auth` itself uses,
+ * and what resolves a repo's local convex binary). It is injectable for tests.
+ */
+
+// --- Key generation (pure) ---------------------------------------------------
+
+/**
+ * Generate a Convex Auth RS256 signing keypair in the exact shape the Convex Auth
+ * runtime expects. Returns `{ JWT_PRIVATE_KEY, JWKS }` (both strings, ready for
+ * `convex env set`). Pure — no I/O.
+ */
+export function generateAuthKeys() {
+  const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+    modulusLength: 2048,
+    publicExponent: 65537,
+  })
+  const pkcs8 = String(privateKey.export({ type: 'pkcs8', format: 'pem' }))
+  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 }] }),
+  }
+}
+
+// --- convex env get/set (I/O, injectable) ------------------------------------
+
+/**
+ * Default convex invocation: `npx convex <args>`. Returns a normalized result and
+ * never throws (spawnSync captures a non-zero exit — e.g. `env get` on a missing var).
+ */
+export function defaultConvexExec(args, { cwd } = {}) {
+  const res = spawnSync('npx', ['convex', ...args], { cwd, encoding: 'utf8' })
+  return {
+    status: res.status ?? 1,
+    stdout: res.stdout ?? '',
+    stderr: res.stderr ?? '',
+    error: res.error,
+  }
+}
+
+/** Read a deployment env var; '' when unset or the command failed. */
+export function convexEnvGet(name, { cwd, exec = defaultConvexExec } = {}) {
+  const { status, stdout } = exec(['env', 'get', name], { cwd })
+  if (status !== 0) return ''
+  return String(stdout).trim()
+}
+
+/** Set a deployment env var (arg array — no shell quoting of the long PEM value). */
+export function convexEnvSet(name, value, { cwd, exec = defaultConvexExec } = {}) {
+  const { status, stderr, error } = exec(['env', 'set', '--', name, value], { cwd })
+  if (status !== 0) {
+    throw new Error(
+      `convex env set ${name} failed${error ? ` (${error.message})` : ''}: ${String(stderr).trim()}`,
+    )
+  }
+}
+
+/** 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 }) !== '',
+  }
+}
+
+/**
+ * Idempotently ensure the Convex Auth signing keys exist on the target deployment.
+ * Never overwrites an existing key.
+ *
+ *  - both present  → no-op (`present`)
+ *  - both absent   → generate + set both (`generated`)
+ *  - exactly one   → leave it untouched, report for manual repair (`partial`)
+ *
+ * `exec` is injectable for tests; `generate` and `log` too.
+ */
+export function ensureAuthKeys({ cwd, exec, log = () => {}, generate = generateAuthKeys } = {}) {
+  const state = detectKeyState({ cwd, exec })
+  if (state.jwt && state.jwks) {
+    log('✓ Auth signing keys already set (JWT_PRIVATE_KEY + JWKS) — no change.')
+    return { action: 'present', state }
+  }
+  if (state.jwt || state.jwks) {
+    log('! Only one of JWT_PRIVATE_KEY/JWKS is set — leaving it untouched (setup never overwrites a key).')
+    log('  Repair manually: clear both and re-run `elytra init`, or run `npx @convex-dev/auth`.')
+    return { action: 'partial', state }
+  }
+  const keys = generate()
+  convexEnvSet('JWT_PRIVATE_KEY', keys.JWT_PRIVATE_KEY, { cwd, exec })
+  convexEnvSet('JWKS', keys.JWKS, { cwd, exec })
+  log('✓ Generated and set the Convex Auth signing keys (JWT_PRIVATE_KEY + JWKS).')
+  return { action: 'generated', state }
+}
+
+// --- Orchestration plan (pure) -----------------------------------------------
+
+/** @typedef {'skip'|'run'|'deferred'|'manual'|'blocked'} SetupStepStatus */
+
+function step(id, status, detail) {
+  return { id, status, detail }
+}
+
+/**
+ * The ordered, idempotent first-run setup plan (pure — the decision core `elytra init`
+ * executes and the tests pin). Given the project's resolved mode/provisioning and, when
+ * known, the deployment's key state, decide each step: provision → auth-keys → verify.
+ *
+ * Every decision is re-runnable: an already-satisfied step is `skip`, so re-running
+ * `elytra init` is safe at every point.
+ *
+ * `isProdDeployment` (EC-356) never changes a step's status here, only its message: a
+ * `prod:` deployment is provisioned exactly like any other (`skip`), and an unlinked prod
+ * selector is still refused exactly like an unconfigured backend (`blocked`) — but the
+ * detail text says so, because `convex dev` is never the right next step against
+ * production (`elytra init` prints the same distinction; see its `runInit`).
+ *
+ * @param {{ mode: string, convexProvisioned: boolean, isProdDeployment?: boolean }} project
+ * @param {{ jwt: boolean, jwks: boolean } | null} [keyState] deployment key state, or null when not yet knowable
+ */
+export function planSetup({ mode, convexProvisioned, isProdDeployment = false }, keyState = null) {
+  const steps = []
+
+  // 1. Provision a backend deployment.
+  if (mode === 'playground') {
+    steps.push(step('provision', 'skip', 'Playground mode — in-memory, no backend deployment to provision.'))
+  } else if (mode === 'unconfigured') {
+    steps.push(
+      step('provision', 'blocked', 'No backend configured. Set VITE_CONVEX_URL, or VITE_ELYTRA_MODE=playground, in studio/.env.'),
+    )
+  } else if (convexProvisioned) {
+    steps.push(
+      isProdDeployment
+        ? step(
+            'provision',
+            'skip',
+            'A prod: Convex deployment is already provisioned — `convex dev` is never run against it; deploy explicitly with `npx convex deploy`.',
+          )
+        : step('provision', 'skip', 'A Convex deployment is already provisioned.'),
+    )
+  } else if (isProdDeployment) {
+    steps.push(
+      step(
+        'provision',
+        'blocked',
+        'A prod: selector is set but no deployment is linked here — provisioning via `convex dev` is skipped against production; link and deploy explicitly with `npx convex deploy`.',
+      ),
+    )
+  } else {
+    steps.push(step('provision', 'run', 'Provision a Convex deployment (convex dev).'))
+  }
+
+  // 2. Ensure the Convex Auth signing keys.
+  if (mode === 'playground') {
+    steps.push(step('auth-keys', 'skip', 'Playground mode — sign-in uses the seeded local adapter (no JWT).'))
+  } else if (mode === 'unconfigured') {
+    steps.push(step('auth-keys', 'blocked', 'Configure the backend first.'))
+  } else if (!convexProvisioned) {
+    steps.push(step('auth-keys', 'deferred', 'Auth keys are set once the deployment is provisioned.'))
+  } else if (keyState && keyState.jwt && keyState.jwks) {
+    steps.push(step('auth-keys', 'skip', 'Auth signing keys (JWT_PRIVATE_KEY + JWKS) are already set.'))
+  } else if (keyState && (keyState.jwt || keyState.jwks)) {
+    steps.push(step('auth-keys', 'manual', 'Only one of JWT_PRIVATE_KEY/JWKS is set — fix manually; setup never overwrites a key.'))
+  } else {
+    // keyState null (unknown) or both absent → we will generate.
+    steps.push(step('auth-keys', 'run', 'Generate and set JWT_PRIVATE_KEY + JWKS.'))
+  }
+
+  // 3. Verify readiness (the elytra doctor check).
+  steps.push(
+    step('verify', mode === 'unconfigured' ? 'blocked' : 'run', 'Check deployment readiness (elytra doctor).'),
+  )
+
+  return steps
+}