@elytracms/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 finaldream
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @elytracms/cli
+
+The Elytra CLI — run an [Elytra](https://www.npmjs.com/package/@elytracms/core)
+consuming repo's studio, delivery frontend, and Convex backend under one command.
+
+Installed as a devDependency in projects scaffolded by
+[`create-elytra`](https://www.npmjs.com/package/create-elytra); its `dev`/`build`
+scripts call `elytra`.
+
+## Commands
+
+```
+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, the rest are torn down.
+
+elytra build    Build the studio + frontend (and deploy Convex in connected
+                mode), in order — failing as a whole if any step fails.
+
+elytra help     Show help
+elytra version  Show version
+```
+
+Run from anywhere inside an Elytra project (a directory with `elytra.config.ts`).
+
+## Mode-aware
+
+The CLI reads the studio's `.env` (the same backend signal the studio itself
+uses):
+
+- **Playground** (`VITE_ELYTRA_MODE=playground`) — runs the studio + frontend
+  only; no Convex.
+- **Connected** (`VITE_CONVEX_URL` set) — also runs `convex dev` (or deploys on
+  build) once a deployment is provisioned (`CONVEX_DEPLOYMENT` present).
+
+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.

package/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { argv, exit } from 'node:process'
+import { run } from './src/cli.js'
+
+run(argv.slice(2))
+  .then((code) => exit(code))
+  .catch((error) => {
+    console.error(`\nelytra failed: ${error?.message ?? error}`)
+    exit(1)
+  })

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@elytracms/cli",
+  "author": "finaldream <hi@finaldream.de>",
+  "version": "0.0.1",
+  "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "elytra": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "start": "node ./index.js",
+    "test": "vitest run"
+  }
+}

package/src/cli.js

@@ -0,0 +1,133 @@
+import { join } from 'node:path'
+import { stdout } from 'node:process'
+import { inspectProject } from './project.js'
+import { runGroup, runSequential } from './run.js'
+
+const HELP = `
+elytra — run an Elytra project's studio, frontend, and backend under one command
+
+Usage:
+  elytra <command>
+
+Commands:
+  dev        Start the studio + frontend (and Convex in connected mode) together.
+             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.
+  help       Show this help
+  version    Show version
+
+Run from anywhere inside an Elytra project (a directory with elytra.config.ts).
+`.trimStart()
+
+function log(line = '') {
+  stdout.write(`${line}\n`)
+}
+
+function reportIssues(issues) {
+  log('Cannot continue:')
+  for (const issue of issues) log(`  • ${issue}`)
+}
+
+/** Build the dev process group from a project inspection. */
+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) {
+      procs.push({ name: 'convex', command: 'pnpm', args: ['run', 'convex:dev'], cwd: studioDir })
+    }
+  }
+  if (project.apps.studio) {
+    procs.push({ name: 'studio', command: 'pnpm', args: ['run', 'dev'], cwd: studioDir })
+  }
+  if (project.apps.frontend) {
+    procs.push({ name: 'frontend', command: 'pnpm', args: ['run', 'dev'], cwd: frontendDir })
+  }
+  return procs
+}
+
+/** Build the ordered build steps from a project inspection. */
+export function planBuild(project) {
+  const steps = []
+  const studioDir = join(project.root, 'studio')
+  const frontendDir = join(project.root, 'frontend')
+
+  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 })
+  }
+  if (project.apps.frontend) {
+    steps.push({ name: 'frontend build', command: 'pnpm', args: ['run', 'build'], cwd: frontendDir })
+  }
+  return steps
+}
+
+function noteMode(project) {
+  if (project.mode === 'playground') {
+    log('Mode: playground (in-memory, no backend). Convex is not started.')
+  } else if (project.mode === 'connected' && !project.convexProvisioned) {
+    log(
+      '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.',
+    )
+  } else if (project.mode === 'unconfigured') {
+    log(
+      'Backend not configured. Defaulting to the frontends only. Set VITE_ELYTRA_MODE=\n' +
+        'playground or VITE_CONVEX_URL in studio/.env. See CONNECT.md.',
+    )
+  }
+}
+
+export async function run(argv, { cwd = process.cwd(), env = process.env } = {}) {
+  const command = argv[0] ?? 'help'
+
+  if (command === 'help' || command === '-h' || command === '--help') {
+    log(HELP)
+    return 0
+  }
+  if (command === 'version' || command === '--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
+  }
+
+  if (command !== 'dev' && command !== 'build') {
+    log(`Unknown command: ${command}\n`)
+    log(HELP)
+    return 1
+  }
+
+  const project = inspectProject(cwd, env)
+  if (project.issues.length > 0) {
+    reportIssues(project.issues)
+    return 1
+  }
+  noteMode(project)
+
+  if (command === 'dev') {
+    const procs = planDev(project)
+    if (procs.length === 0) {
+      log('Nothing to run — no studio/ or frontend/ app found.')
+      return 1
+    }
+    log('Starting (Ctrl-C to stop everything)…\n')
+    return runGroup(procs)
+  }
+
+  // build
+  const steps = planBuild(project)
+  if (steps.length === 0) {
+    log('Nothing to build — no studio/ or frontend/ app found.')
+    return 1
+  }
+  const code = await runSequential(steps)
+  log(code === 0 ? '\n✓ Build complete.' : '\n✗ Build failed.')
+  return code
+}

package/src/project.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/**
+ * Project detection for the Elytra CLI (EC-235). Convention-aware, not config-
+ * executing: a consuming repo's layout (`studio/`, `frontend/`, root
+ * `elytra.config.ts`) and its `.env` are the source of truth — the same `.env`
+ * the studio itself reads to resolve its backend (`VITE_ELYTRA_MODE` /
+ * `VITE_CONVEX_URL`). We deliberately do NOT load the TS config (no TS runtime
+ * dependency); the paths are conventional and the operative backend signal lives
+ * in env regardless.
+ */
+
+/** Walk up from `start` until a directory containing `elytra.config.ts` is found. */
+export function findRepoRoot(start) {
+  let dir = start
+  for (;;) {
+    if (existsSync(join(dir, 'elytra.config.ts'))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** Parse a dotenv file into a flat record. Missing file → {}. */
+function readEnvFile(path) {
+  if (!existsSync(path)) return {}
+  const out = {}
+  for (const rawLine of readFileSync(path, 'utf8').split('\n')) {
+    const line = rawLine.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq === -1) continue
+    const key = line.slice(0, eq).trim()
+    let value = line.slice(eq + 1).trim()
+    // Strip an inline comment and surrounding quotes.
+    value = value.replace(/\s+#.*$/, '').replace(/^['"]|['"]$/g, '')
+    out[key] = value
+  }
+  return out
+}
+
+/** Merge a package's `.env` then `.env.local` (local wins), then process.env. */
+function resolveEnv(appDir, processEnv) {
+  return {
+    ...readEnvFile(join(appDir, '.env')),
+    ...readEnvFile(join(appDir, '.env.local')),
+    ...processEnv,
+  }
+}
+
+function isApp(root, name) {
+  return existsSync(join(root, name, 'package.json'))
+}
+
+/**
+ * Inspect a consuming repo. Returns:
+ *   { root, apps: {studio, frontend}, mode, convexProvisioned, issues }
+ * `issues` are actionable, human-readable prerequisite problems (empty = ok).
+ */
+export function inspectProject(cwd, processEnv = {}) {
+  const root = findRepoRoot(cwd)
+  if (!root) {
+    return {
+      root: null,
+      apps: { studio: false, frontend: false },
+      mode: 'unknown',
+      convexProvisioned: 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`).',
+      ],
+    }
+  }
+
+  const apps = { studio: isApp(root, 'studio'), frontend: isApp(root, 'frontend') }
+  const issues = []
+  if (!apps.studio && !apps.frontend) {
+    issues.push('No `studio/` or `frontend/` app found next to elytra.config.ts.')
+  }
+  if (!existsSync(join(root, 'node_modules'))) {
+    issues.push('Dependencies are not installed. Run `pnpm install` first.')
+  }
+
+  // Backend mode is read from the studio app's env, mirroring the studio's own
+  // resolveBackendConfig: explicit playground flag wins; otherwise a Convex URL
+  // means connected; neither means it still needs configuring.
+  const studioEnv = apps.studio ? resolveEnv(join(root, 'studio'), processEnv) : processEnv
+  let mode
+  if (studioEnv.VITE_ELYTRA_MODE === 'playground') mode = 'playground'
+  else if (studioEnv.VITE_CONVEX_URL) mode = 'connected'
+  else mode = 'unconfigured'
+
+  // 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)
+
+  return { root, apps, mode, convexProvisioned, issues }
+}

package/src/run.js

@@ -0,0 +1,132 @@
+import { spawn } from 'node:child_process'
+import { stdout } from 'node:process'
+
+/**
+ * Process orchestration for the Elytra CLI (EC-235). We own the lifecycle but
+ * never reimplement Vite/Next/Convex — each step shells out to the underlying
+ * tool and inherits its watch/HMR/build behaviour.
+ */
+
+const COLORS = ['36', '35', '33', '32', '34'] // cyan, magenta, yellow, green, blue
+const useColor = !process.env.NO_COLOR && stdout.isTTY
+
+function paint(text, code) {
+  return useColor ? `[${code}m${text}` : text
+}
+
+/** Prefix every line of a child's output with its labeled, colored tag. */
+function pipePrefixed(stream, label, color) {
+  let buffer = ''
+  const tag = paint(`[${label}]`, color)
+  stream.on('data', (chunk) => {
+    buffer += chunk.toString()
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) stdout.write(`${tag} ${line}\n`)
+  })
+  stream.on('end', () => {
+    if (buffer.length) stdout.write(`${tag} ${buffer}\n`)
+  })
+}
+
+/**
+ * Run a set of long-lived processes as one supervised group (`elytra dev`).
+ * 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.
+ */
+export function runGroup(procs) {
+  return new Promise((resolve) => {
+    const children = []
+    let shuttingDown = false
+    let resultCode = 0
+
+    const killAll = (signal) => {
+      for (const child of children) {
+        if (child.exitCode === null && child.signalCode === null) {
+          try {
+            child.kill(signal)
+          } catch {
+            /* already gone */
+          }
+        }
+      }
+    }
+
+    const shutdown = (code) => {
+      if (shuttingDown) return
+      shuttingDown = true
+      resultCode = code
+      killAll('SIGTERM')
+      // Hard stop if a child ignores SIGTERM.
+      const hard = setTimeout(() => killAll('SIGKILL'), 4000)
+      hard.unref?.()
+    }
+
+    procs.forEach((proc, i) => {
+      const color = COLORS[i % COLORS.length]
+      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,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      children.push(child)
+      pipePrefixed(child.stdout, proc.name, color)
+      pipePrefixed(child.stderr, proc.name, color)
+
+      child.on('error', (err) => {
+        stdout.write(`${paint(`[${proc.name}]`, color)} failed to start: ${err.message}\n`)
+        shutdown(1)
+      })
+      child.on('exit', (code, signal) => {
+        if (!shuttingDown) {
+          // An unexpected exit takes the whole group down.
+          stdout.write(
+            `${paint(`[${proc.name}]`, color)} exited (${signal ?? code}); stopping the group.\n`,
+          )
+          shutdown(code ?? (signal ? 1 : 0))
+        }
+        if (children.every((c) => c.exitCode !== null || c.signalCode !== null)) {
+          resolve(resultCode)
+        }
+      })
+    })
+
+    const onSignal = () => shutdown(130)
+    process.once('SIGINT', onSignal)
+    process.once('SIGTERM', onSignal)
+  })
+}
+
+/**
+ * Run steps in order, failing the whole command on the first non-zero exit
+ * (`elytra build`). No silent partial builds. Returns the failing step's exit
+ * code, or 0 if all pass.
+ */
+export function runSequential(steps) {
+  return new Promise((resolve) => {
+    let i = 0
+    const next = () => {
+      if (i >= steps.length) return resolve(0)
+      const step = steps[i++]
+      stdout.write(`\n${paint(`▸ ${step.name}`, '36')}\n`)
+      const child = spawn(step.command, step.args, {
+        cwd: step.cwd,
+        env: process.env,
+        stdio: 'inherit',
+      })
+      child.on('error', (err) => {
+        stdout.write(`${step.name} failed to start: ${err.message}\n`)
+        resolve(1)
+      })
+      child.on('exit', (code, signal) => {
+        if (code === 0) return next()
+        stdout.write(`\n${step.name} failed (exit ${signal ?? code}). Stopping.\n`)
+        resolve(code ?? 1)
+      })
+    }
+    next()
+  })
+}