@elytracms/cli 0.0.77 → 0.0.79

package/README.md

@@ -56,6 +56,11 @@ elytra version  Show version
 
 Run from anywhere inside an Elytra project (a directory with `elytra.config.ts`).
 
+Every subcommand accepts `--help`/`-h` and prints its own usage — inertly: no
+project inspection, no process spawned, no network call, no write. `elytra dev
+--help` never starts a server; `elytra doctor --help` never runs the network
+diagnostic; `elytra build --help` never validates a target.
+
 ## Mode-aware
 
 The CLI reads the studio's `.env` (the same backend signal the studio itself
@@ -70,6 +75,16 @@ 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.
 
+## Dev ports
+
+The studio defaults to `:5180`, the frontend to `:3000`. One lever moves both
+together — set `ELYTRA_DEV_PORT_OFFSET` in `studio/.env` (e.g. `100` → studio
+`:5280`, frontend `:3100`) to run a second Elytra project alongside this one
+without a clash. `elytra dev` reads it from `studio/.env` and forwards it to
+both child processes; the studio's own `vite.config.ts` also reads it directly
+(so `vite dev` run standalone honors it too). Unset (the default) leaves both
+ports exactly as they are today.
+
 ## Deploying (Vercel)
 
 Deploys are git-push-driven — there is no `elytra deploy`. A consuming repo

package/package.json

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

package/src/cli.js

@@ -44,12 +44,124 @@ Commands:
   version    Show version
 
 Run from anywhere inside an Elytra project (a directory with elytra.config.ts).
+Any subcommand accepts --help/-h for its own usage (never does the command's work).
+
+Dev ports: studio 5180, frontend 3000 by default. Set ELYTRA_DEV_PORT_OFFSET in
+studio/.env to shift BOTH together (e.g. to run a second Elytra project alongside
+this one without a clash) — 'elytra dev' forwards it to both processes.
 `.trimStart()
 
 function log(line = '') {
   stdout.write(`${line}\n`)
 }
 
+// --- Uniform inert `--help`/`-h` (EC-464) -------------------------------------
+//
+// Two builders (one external) independently hit `elytra <subcommand> --help`
+// DOING the subcommand's work instead of just describing it — `dev --help`
+// started real dev servers (attempting the shared default ports, 5180/3000),
+// `doctor --help` ran the full network diagnostic, `build --help` rejected as
+// an unknown build target. The fix is one central gate in `run()`, checked
+// BEFORE any subcommand branch does anything: every entry in `SUBCOMMAND_HELP`
+// is inert under `--help`/`-h` by construction — no project inspection, no
+// process spawned, no network call, no write. A future subcommand inherits
+// this for free by adding its usage text here; nothing per-command to
+// remember.
+
+/** Per-subcommand usage text — each documents that subcommand's real flags. */
+export const SUBCOMMAND_HELP = {
+  dev: `
+Usage: elytra dev
+
+Start the studio + frontend (and Convex in connected mode) together as one
+supervised process group. One Ctrl-C stops everything; if any process exits
+on its own, the rest are torn down.
+
+No flags. The dev ports (studio 5180, frontend 3000) move together via the
+ELYTRA_DEV_PORT_OFFSET lever — see studio/.env.
+`.trim(),
+
+  build: `
+Usage: elytra build [target]
+
+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
+
+No target builds the whole repo in order: convex deploy (connected mode) →
+studio build → frontend build.
+`.trim(),
+
+  init: `
+Usage: elytra init
+
+First-run setup: provision Convex, generate the auth signing keys, verify
+readiness. Idempotent — safe to re-run at any point. No flags.
+`.trim(),
+
+  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 reports the
+generated-previews artifacts (manifest/files present; hash staleness lives
+in \`elytra previews --check\`). Exit non-zero if any check fails. Read-only.
+
+Options:
+  --url <convex url>   Diagnose this deployment instead of the one resolved
+                        from studio/.env.
+`.trim(),
+
+  previews: `
+Usage: elytra previews [--check] [--port <n>]
+
+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
+importable manifest (studio/elytra-previews.json) for the insert menu.
+Re-running with unchanged inputs rewrites nothing.
+
+Options:
+  --check      Verify freshness (input hashes) without rendering; exit
+               non-zero when previews are missing/stale.
+  --port <n>   Harness dev-server port (default: first free 5440+).
+`.trim(),
+}
+
+/** Does this subcommand's own argv (everything after argv[0]) ask for help? */
+function hasHelpFlag(subArgs) {
+  return subArgs.includes('--help') || subArgs.includes('-h')
+}
+
+/**
+ * Pure dispatch decision (EC-464): does this invocation want top-level help,
+ * a subcommand's inert help, the version, or should the subcommand actually
+ * run? Centralizes the `--help`/`-h` gate so every subcommand is inert under
+ * help BY CONSTRUCTION — table-testable directly, independent of `run()`'s
+ * process-spawning/network/fs side effects. The regression this pins is
+ * "`--help` did real work".
+ */
+export function decideAction(argv) {
+  const command = argv[0] ?? 'help'
+  if (command === 'help' || command === '-h' || command === '--help') {
+    return { action: 'help', subcommand: 'help' }
+  }
+  if (command === 'version' || command === '--version') {
+    return { action: 'version', subcommand: 'version' }
+  }
+  if (Object.hasOwn(SUBCOMMAND_HELP, command) && hasHelpFlag(argv.slice(1))) {
+    return { action: 'help', subcommand: command }
+  }
+  return { action: 'run', subcommand: command }
+}
+
 function reportIssues(issues) {
   log('Cannot continue:')
   for (const issue of issues) log(`  • ${issue}`)
@@ -61,11 +173,28 @@ function reportIssues(issues) {
  * 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.
+ *
+ * EC-464 dev-port lever: `project.devPortOffset` (resolved by `inspectProject` from
+ * studio/.env's `ELYTRA_DEV_PORT_OFFSET`) is forwarded as an env var to BOTH the
+ * studio and frontend child processes — the studio's own `vite.config.ts` reads it
+ * directly (so it also applies when running `vite dev` standalone), and the
+ * frontend's `dev` script reads it from its process env (which only `elytra dev`
+ * can supply, since dotenv files aren't shell-sourced) — one lever, moves both.
  */
 export function planDev(project) {
   const procs = []
   const studioDir = join(project.root, 'studio')
   const frontendDir = join(project.root, '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
+  // 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) }
 
   if (project.apps.studio && project.mode === 'connected') {
     if (project.convexProvisioned && !project.isProdDeployment) {
@@ -73,10 +202,10 @@ export function planDev(project) {
     }
   }
   if (project.apps.studio) {
-    procs.push({ name: 'studio', command: 'pnpm', args: ['run', 'dev'], cwd: studioDir })
+    procs.push({ name: 'studio', command: 'pnpm', args: ['run', 'dev'], cwd: studioDir, env: studioEnv })
   }
   if (project.apps.frontend) {
-    procs.push({ name: 'frontend', command: 'pnpm', args: ['run', 'dev'], cwd: frontendDir })
+    procs.push({ name: 'frontend', command: 'pnpm', args: ['run', 'dev'], cwd: frontendDir, env: frontendEnv })
   }
   return procs
 }
@@ -308,19 +437,21 @@ export async function runInit(project, { log: emit = log, fetchImpl, exec, provi
 }
 
 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') {
-    log(HELP)
+  // EC-464: the ONE gate — decide before touching fs/network/processes. `help` and
+  // every per-subcommand `--help`/`-h` short-circuit here, inertly, by construction.
+  const decision = decideAction(argv)
+  if (decision.action === 'help') {
+    log(decision.subcommand === 'help' ? HELP : SUBCOMMAND_HELP[decision.subcommand])
     return 0
   }
-  if (command === 'version' || command === '--version') {
+  if (decision.action === 'version') {
     const { readFileSync } = await import('node:fs')
     const { fileURLToPath } = await import('node:url')
     const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url))
     log(JSON.parse(readFileSync(pkgPath, 'utf8')).version)
     return 0
   }
+  const command = decision.subcommand
 
   // `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.

package/src/project.js

@@ -92,10 +92,26 @@ export function isProdDeploymentSelector(env = {}) {
   )
 }
 
+/**
+ * Parse the EC-464 dev-port-offset lever from the resolved studio env: a single
+ * integer that shifts BOTH the studio's and the frontend's dev port together (the
+ * studio's own `vite.config.ts` reads it directly; `elytra dev` forwards it to the
+ * frontend child too, since a dotenv file isn't shell-sourced for its `next dev`
+ * script) — one lever, so a second Elytra project can run alongside this one
+ * without a port clash. Unset/blank/non-numeric → 0, the current 5180/3000
+ * defaults, byte-for-byte unchanged for every existing scaffold.
+ */
+export function resolveDevPortOffset(env = {}) {
+  const raw = env.ELYTRA_DEV_PORT_OFFSET
+  if (raw === undefined || String(raw).trim() === '') return 0
+  const n = Number(raw)
+  return Number.isFinite(n) ? Math.trunc(n) : 0
+}
+
 /**
  * Inspect a consuming repo. Returns:
  *   { root, apps: {studio, frontend}, mode, convexProvisioned, isProdDeployment,
- *     hasDeployKey, hasAiRoute, issues }
+ *     hasDeployKey, hasAiRoute, devPortOffset, issues }
  * `issues` are actionable, human-readable prerequisite problems (empty = ok).
  */
 export function inspectProject(cwd, processEnv = {}) {
@@ -109,6 +125,7 @@ export function inspectProject(cwd, processEnv = {}) {
       isProdDeployment: false,
       hasDeployKey: false,
       hasAiRoute: false,
+      devPortOffset: 0,
       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`).',
       ],
@@ -151,5 +168,8 @@ export function inspectProject(cwd, processEnv = {}) {
   // `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 }
+  // EC-464: the one dev-port lever, read from the same studio env as everything else here.
+  const devPortOffset = resolveDevPortOffset(studioEnv)
+
+  return { root, apps, mode, convexProvisioned, isProdDeployment, hasDeployKey, hasAiRoute, devPortOffset, issues }
 }

package/src/run.js

@@ -34,7 +34,10 @@ function pipePrefixed(stream, label, color) {
  * Ctrl-C (SIGINT/SIGTERM) tears all of them down; if any child exits on its own,
  * the rest are killed and the group resolves with that child's exit code.
  *
- * `procs`: [{ name, command, args, cwd }]. Returns the group's exit code.
+ * `procs`: [{ name, command, args, cwd, env? }] — an optional `env` is merged
+ * OVER `process.env` for that one child only (EC-464: how `planDev` forwards the
+ * dev-port-offset lever to the studio/frontend children without changing every
+ * other process's environment). Returns the group's exit code.
  */
 export function runGroup(procs) {
   return new Promise((resolve) => {
@@ -69,7 +72,7 @@ export function runGroup(procs) {
       stdout.write(`${paint(`[${proc.name}]`, color)} ${proc.command} ${proc.args.join(' ')}\n`)
       const child = spawn(proc.command, proc.args, {
         cwd: proc.cwd,
-        env: process.env,
+        env: proc.env ? { ...process.env, ...proc.env } : process.env,
         stdio: ['ignore', 'pipe', 'pipe'],
       })
       children.push(child)