create-elytra 0.0.0 → 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

@@ -1,7 +1,48 @@
 # create-elytra
 
-Placeholder package for the future Elytra CMS project initializer.
+Scaffold a new [Elytra](https://www.npmjs.com/package/@elytracms/core) project —
+the code-first web CMS with a native visual page builder.
 
-This package reserves the `npm create elytra` command while Elytra CMS is in
-early development. The real initializer will replace this placeholder before
-public release.
+```bash
+npm create elytra@latest my-site
+# or: pnpm create elytra my-site
+```
+
+This generates a pnpm workspace with a visual **studio** (Vite + TanStack Start)
+and a delivery **frontend** (Next.js App Router) over one canonical project
+graph. It starts in **playground mode** — in-memory, seeded, no signup — so you
+can edit immediately, then connect a Convex deployment when you're ready
+(`CONNECT.md` in the generated project).
+
+## Usage
+
+```
+npm create elytra@latest [directory] [options]
+
+Options:
+  --name <name>    Project name (default: derived from the directory)
+  --mode <mode>    playground (default) | connected
+  --playground     Start in in-memory playground mode (no signup)
+  --connected      Scaffold wired for a Convex deployment (you provision it)
+  -y, --yes        Accept defaults, skip prompts
+```
+
+## What you get
+
+```
+my-site/
+├── elytra.config.ts     # project config-as-code
+├── cms/                 # collections, routes, redirects (your content model)
+├── components/          # your page-builder components
+├── studio/              # the visual builder
+└── frontend/            # the delivery site
+```
+
+Then:
+
+```bash
+cd my-site
+pnpm install
+pnpm --filter studio dev      # edit immediately, no signup
+pnpm --filter frontend dev    # the delivery site
+```

package/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import { argv, exit } from 'node:process'
+import { run } from './src/cli.js'
 
-console.error("Elytra CMS is not released yet.");
-console.error("This package reserves the future `npm create elytra` initializer.");
-console.error("Follow the project for release updates before using this command.");
-
-process.exitCode = 1;
+run(argv.slice(2))
+  .then((code) => exit(code))
+  .catch((error) => {
+    console.error(`\ncreate-elytra failed: ${error?.message ?? error}`)
+    exit(1)
+  })

package/package.json

@@ -1,20 +1,27 @@
 {
   "name": "create-elytra",
-  "version": "0.0.0",
+  "author": "finaldream <hi@finaldream.de>",
+  "version": "0.0.1",
   "description": "Project initializer for Elytra CMS.",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "type": "module",
   "bin": {
     "create-elytra": "./index.js"
   },
   "files": [
     "index.js",
+    "src",
+    "template",
     "README.md"
   ],
   "engines": {
     "node": ">=20"
   },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  },
   "scripts": {
-    "start": "node ./index.js"
+    "start": "node ./index.js",
+    "test": "vitest run"
   }
-}
+}

package/src/args.js

@@ -0,0 +1,93 @@
+/**
+ * Argument parsing for `create-elytra` (EC-198). Zero-dependency, deterministic,
+ * unit-testable. Supports:
+ *
+ *   npm create elytra@latest [directory] [options]
+ *
+ * Options:
+ *   --name <name>      Human-readable project name (default: derived from directory)
+ *   --mode <mode>      'playground' (default) | 'connected'
+ *   --playground       Shorthand for --mode playground
+ *   --connected        Shorthand for --mode connected
+ *   -y, --yes          Skip prompts; accept defaults
+ *   -h, --help         Print usage
+ *   --version          Print version
+ */
+
+export const MODES = ['playground', 'connected']
+
+export function parseArgs(argv) {
+  const result = {
+    directory: undefined,
+    name: undefined,
+    mode: undefined,
+    yes: false,
+    help: false,
+    version: false,
+    errors: [],
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    switch (arg) {
+      case '-h':
+      case '--help':
+        result.help = true
+        break
+      case '--version':
+        result.version = true
+        break
+      case '-y':
+      case '--yes':
+        result.yes = true
+        break
+      case '--playground':
+        result.mode = 'playground'
+        break
+      case '--connected':
+        result.mode = 'connected'
+        break
+      case '--name':
+        result.name = argv[++i]
+        if (result.name === undefined) result.errors.push('--name requires a value')
+        break
+      case '--mode': {
+        const value = argv[++i]
+        if (value === undefined) result.errors.push('--mode requires a value')
+        else if (!MODES.includes(value)) result.errors.push(`--mode must be one of: ${MODES.join(', ')}`)
+        else result.mode = value
+        break
+      }
+      default:
+        if (arg.startsWith('-')) {
+          result.errors.push(`Unknown option: ${arg}`)
+        } else if (result.directory === undefined) {
+          result.directory = arg
+        } else {
+          result.errors.push(`Unexpected argument: ${arg}`)
+        }
+    }
+  }
+
+  return result
+}
+
+export const HELP_TEXT = `
+create-elytra — scaffold a new Elytra CMS project
+
+Usage:
+  npm create elytra@latest [directory] [options]
+
+Options:
+  --name <name>    Project name (default: derived from the directory)
+  --mode <mode>    playground (default) | connected
+  --playground     Start in in-memory playground mode (no signup, edit immediately)
+  --connected      Scaffold wired for a Convex deployment (you provision it)
+  -y, --yes        Accept defaults, skip prompts
+  -h, --help       Show this help
+  --version        Show version
+
+Examples:
+  npm create elytra@latest my-site
+  npm create elytra@latest my-site --connected
+`.trimStart()

package/src/cli.js

@@ -0,0 +1,113 @@
+import { fileURLToPath } from 'node:url'
+import { dirname, join, resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+import { stdout } from 'node:process'
+import { HELP_TEXT, parseArgs } from './args.js'
+import { prompt, promptChoice } from './prompts.js'
+import { isWritableTarget, scaffold, slugify } from './scaffold.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(here, '..')
+const templateDir = join(packageRoot, 'template')
+
+function log(line = '') {
+  stdout.write(`${line}\n`)
+}
+
+async function readVersion() {
+  try {
+    const pkg = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8'))
+    return pkg.version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+const MODE_CHOICES = [
+  { value: 'playground', label: 'Playground — in-memory, no signup, edit immediately (recommended)' },
+  { value: 'connected', label: 'Connected — wired for your own Convex deployment' },
+]
+
+/**
+ * Run the scaffolder. `argv` is the raw args after the node binary + script.
+ * `interactive` (default true) lets tests force the non-prompting path.
+ * Returns an exit code.
+ */
+export async function run(argv, { interactive = true } = {}) {
+  const args = parseArgs(argv)
+
+  if (args.help) {
+    log(HELP_TEXT)
+    return 0
+  }
+  if (args.version) {
+    log(await readVersion())
+    return 0
+  }
+  if (args.errors.length > 0) {
+    for (const error of args.errors) log(`error: ${error}`)
+    log('')
+    log(HELP_TEXT)
+    return 1
+  }
+
+  const canPrompt = interactive && !args.yes
+
+  let directory = args.directory
+  if (!directory) {
+    directory = canPrompt ? await prompt('Project directory', 'my-elytra-site') : 'my-elytra-site'
+  }
+
+  const targetDir = resolve(process.cwd(), directory)
+  if (!(await isWritableTarget(targetDir))) {
+    log(`error: target directory "${directory}" already exists and is not empty.`)
+    return 1
+  }
+
+  const name =
+    args.name ??
+    (canPrompt ? await prompt('Project name', directory) : directory)
+
+  const mode =
+    args.mode ??
+    (canPrompt ? await promptChoice('Backend mode', MODE_CHOICES, 'playground') : 'playground')
+
+  const slug = slugify(name)
+  const vars = {
+    projectName: name,
+    projectSlug: slug,
+    elytraMode: mode,
+    // The studio .env line: playground sets the flag; connected leaves it commented.
+    studioModeEnv:
+      mode === 'playground'
+        ? 'VITE_ELYTRA_MODE=playground'
+        : '# VITE_ELYTRA_MODE=playground\n# VITE_CONVEX_URL=https://<your-deployment>.convex.cloud',
+  }
+
+  log('')
+  log(`Scaffolding ${name} → ${directory} (${mode} mode)`)
+  const written = await scaffold({ templateDir, targetDir, vars })
+  log(`  ${written.length} files written.`)
+  log('')
+
+  printNextSteps({ directory, mode })
+  return 0
+}
+
+function printNextSteps({ directory, mode }) {
+  log('Next steps:')
+  log(`  cd ${directory}`)
+  log('  pnpm install')
+  if (mode === 'playground') {
+    log('  pnpm dev      # studio + frontend together (playground — edit immediately, no signup)')
+    log('')
+    log('Playground is in-memory: changes reset on reload. When ready to persist,')
+    log('see CONNECT.md to provision Convex and flip to connected mode.')
+  } else {
+    log('  # 1. Provision Convex:  cd studio && npx convex dev')
+    log('  # 2. Put the deployment URL in studio/.env and elytra.config.ts')
+    log('  pnpm dev      # studio + frontend + Convex together')
+    log('')
+    log('See CONNECT.md for the full Convex + Vercel walkthrough.')
+  }
+}

package/src/prompts.js

@@ -0,0 +1,40 @@
+import { createInterface } from 'node:readline/promises'
+import { stdin, stdout } from 'node:process'
+
+/**
+ * Minimal interactive prompts (EC-198) built on node:readline — no dependency.
+ * Used only to fill gaps the user did not pass as flags; `--yes` skips all of
+ * this. Designed to be bypassable so the scaffolder stays fully scriptable.
+ */
+
+export async function prompt(question, fallback) {
+  const rl = createInterface({ input: stdin, output: stdout })
+  try {
+    const suffix = fallback ? ` (${fallback})` : ''
+    const answer = (await rl.question(`${question}${suffix}: `)).trim()
+    return answer || fallback || ''
+  } finally {
+    rl.close()
+  }
+}
+
+export async function promptChoice(question, choices, fallback) {
+  const rl = createInterface({ input: stdin, output: stdout })
+  try {
+    const lines = choices.map((c, i) => `  ${i + 1}) ${c.label}`).join('\n')
+    const fallbackIndex = Math.max(
+      0,
+      choices.findIndex((c) => c.value === fallback),
+    )
+    const answer = (
+      await rl.question(`${question}\n${lines}\nChoose [${fallbackIndex + 1}]: `)
+    ).trim()
+    if (!answer) return choices[fallbackIndex].value
+    const num = Number.parseInt(answer, 10)
+    if (Number.isInteger(num) && num >= 1 && num <= choices.length) return choices[num - 1].value
+    const byValue = choices.find((c) => c.value === answer)
+    return byValue ? byValue.value : choices[fallbackIndex].value
+  } finally {
+    rl.close()
+  }
+}

package/src/scaffold.js

@@ -0,0 +1,96 @@
+import { cp, mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+/**
+ * The scaffolder core (EC-198). Pure-ish filesystem transform: copy a template
+ * tree into a target directory, substitute `{{token}}` placeholders in text
+ * files, and un-escape `dot-` prefixed names back to dotfiles. Kept dependency-
+ * free and separate from the CLI shell so it is unit-testable.
+ */
+
+/** Files we never run token substitution / dotfile-renaming over (binary-ish). */
+const BINARY_EXTENSIONS = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.ico',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.otf',
+])
+
+/** A template basename of `dot-foo` materializes as `.foo` (escapes npm's dotfile-strip on publish). */
+export function materializeName(name) {
+  return name.startsWith('dot-') ? `.${name.slice(4)}` : name
+}
+
+/** Replace every `{{key}}` occurrence from `vars`. Unknown tokens are left untouched. */
+export function applyTokens(content, vars) {
+  return content.replace(/\{\{(\w+)\}\}/g, (match, key) =>
+    Object.prototype.hasOwnProperty.call(vars, key) ? String(vars[key]) : match,
+  )
+}
+
+function isBinary(path) {
+  const dot = path.lastIndexOf('.')
+  return dot !== -1 && BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase())
+}
+
+/** True when the directory does not exist, or exists and is empty. */
+export async function isWritableTarget(dir) {
+  if (!existsSync(dir)) return true
+  const entries = await readdir(dir)
+  return entries.length === 0
+}
+
+/**
+ * Copy `templateDir` → `targetDir`, applying token substitution to text files and
+ * `dot-` → `.` renaming to every path segment. Returns the list of relative paths
+ * written (materialized names), sorted, for logging/tests.
+ */
+export async function scaffold({ templateDir, targetDir, vars = {} }) {
+  const written = []
+
+  async function walk(srcDir, destDir) {
+    await mkdir(destDir, { recursive: true })
+    const entries = await readdir(srcDir, { withFileTypes: true })
+    for (const entry of entries) {
+      const srcPath = join(srcDir, entry.name)
+      const destPath = join(destDir, materializeName(entry.name))
+      if (entry.isDirectory()) {
+        await walk(srcPath, destPath)
+      } else if (entry.isFile()) {
+        if (isBinary(srcPath)) {
+          await cp(srcPath, destPath)
+        } else {
+          const raw = await readFile(srcPath, 'utf8')
+          await writeFile(destPath, applyTokens(raw, vars))
+        }
+        written.push(relative(targetDir, destPath))
+      }
+    }
+  }
+
+  await walk(templateDir, targetDir)
+  written.sort()
+  return written
+}
+
+/** Derive a safe npm/package slug from a freeform project name. */
+export function slugify(name) {
+  return (
+    name
+      .toLowerCase()
+      .trim()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .replace(/-{2,}/g, '-') || 'elytra-site'
+  )
+}
+
+// Re-export node helpers used by the CLI shell so it imports from one place.
+export { rename, stat }

package/template/CONNECT.md

@@ -0,0 +1,89 @@
+# Connect {{projectName}} to a backend
+
+Playground mode is in-memory and ephemeral. To persist content, collaborate, and
+publish a live site, connect a [Convex](https://www.convex.dev) deployment
+(Convex holds your content; structure stays as code in this repo).
+
+## 1. Provision Convex
+
+```bash
+cd studio
+npx convex dev      # creates a dev deployment, prints its URL, generates convex/_generated
+```
+
+This walks you through Convex login/project creation and writes `CONVEX_DEPLOYMENT`
+for you. Note the deployment URL it prints, e.g.
+`https://your-deployment-123.convex.cloud`.
+
+## 2. Point the studio at it
+
+In `studio/.env`:
+
+```bash
+# Comment out playground mode:
+# VITE_ELYTRA_MODE=playground
+
+# Set your deployment URL:
+VITE_CONVEX_URL=https://your-deployment-123.convex.cloud
+```
+
+And in `elytra.config.ts`, uncomment and fill `convex.deployment`:
+
+```ts
+convex: { deployment: 'https://your-deployment-123.convex.cloud' },
+```
+
+Connected mode requires sign-in. Configure an auth provider in
+`studio/convex/auth.config.ts` (or use the dev-login env for local testing).
+
+## 3. Point the frontend at it
+
+In `frontend/.env`:
+
+```bash
+ELYTRA_CONVEX_URL=https://your-deployment-123.convex.cloud
+ELYTRA_PROJECT_ID=<your-project-id>
+```
+
+## 4. Instant publish
+
+A publish in the studio can refresh the live frontend within seconds (no
+rebuild). The revalidate route is already scaffolded at
+`frontend/app/api/revalidate/route.ts` — you only need to wire the env across the
+two systems. The pieces:
+
+**Frontend (host) env** — `frontend/.env` (and Vercel):
+
+```bash
+REVALIDATE_SECRET=<a shared secret you choose>
+STUDIO_ORIGIN=<your studio origin, e.g. https://studio.example.com>
+```
+
+**Studio Convex deployment env** — set with `convex env set` (from `studio/`):
+
+```bash
+npx convex env set CANVAS_PROJECT_SCOPE      <same value as ELYTRA_PROJECT_ID>
+npx convex env set CANVAS_REVALIDATE_ENDPOINT <your-frontend-url>/api/revalidate
+npx convex env set CANVAS_REVALIDATE_SECRET  <the same secret as REVALIDATE_SECRET>
+```
+
+`CANVAS_PROJECT_SCOPE` **must equal** the host's `ELYTRA_PROJECT_ID`, and
+`CANVAS_REVALIDATE_SECRET` **must equal** the host's `REVALIDATE_SECRET` — the
+scope must match the cache tags the host stamped, and the secret signs the
+webhook.
+
+> **The deploy-order trap.** Setting Convex env vars does **not** redeploy your
+> functions. If your deployment predates these vars (or a package bump), `publish`
+> keeps silently no-op'ing until you re-push: run `npx convex dev` (or
+> `pnpm dev`, which wraps it) so the functions pick up the new env. The studio
+> shows a **banner** when any of these three vars is unset, and the Publish button
+> reports failures — so a misconfigured pipeline is visible, not a silent success.
+
+**Verify the round-trip:** publish a change in the studio and confirm the host
+logs a `200` at `/api/revalidate` and the page updates within a few seconds.
+
+## 5. Deploy
+
+Both apps deploy as standard Vercel projects: the studio as a static SPA, the
+frontend as a Next.js app. Set the same env vars in each project's Vercel
+settings.

package/template/README.md

@@ -0,0 +1,51 @@
+# {{projectName}}
+
+A website built with [Elytra](https://www.npmjs.com/package/@elytracms/core) — the
+code-first web CMS with a native visual page builder. This repo is a pnpm
+workspace with two apps over one canonical project graph:
+
+```
+{{projectSlug}}/
+├── elytra.config.ts     # project config-as-code (identity, structure, components)
+├── cms/                 # collections, routes, redirects — your content model, in code
+├── components/          # your page-builder components (manifest + implementation)
+├── studio/              # the visual builder (Vite + TanStack Start)
+└── frontend/            # the delivery site (Next.js App Router)
+```
+
+The **database holds content only**. Your schema, routes, and components live in
+this repo as code — edit them here, jump-to-definition, version them in git.
+
+## Getting started
+
+```bash
+pnpm install
+pnpm dev      # starts the studio + frontend together (one Ctrl-C stops both)
+```
+
+`pnpm dev` runs [`elytra dev`](https://www.npmjs.com/package/@elytracms/cli),
+which supervises the studio (http://localhost:5180) and the delivery frontend
+(http://localhost:3000) as one process group — and, in connected mode, Convex too.
+
+The studio starts in **playground mode**: an in-memory, seeded starter project,
+no signup, editable immediately. Changes reset on reload — it's a sandbox to try
+the builder. The frontend renders the same starter content locally.
+
+```bash
+pnpm build    # `elytra build` — builds studio + frontend (deploys Convex when connected),
+              # failing as a whole if any step fails
+```
+
+## Make it real
+
+When you're ready to persist content and publish, follow
+[`CONNECT.md`](./CONNECT.md) to provision a Convex deployment and switch to
+**connected mode**. Then deploy the studio and frontend (e.g. to Vercel).
+
+## Editing your site
+
+- **Content model** — `cms/collections/*.ts`. Add fields, collections, relations.
+- **Routes** — `cms/routes.ts`. Map URLs to documents.
+- **Components** — `components/`. Your `project.*` blocks; the studio composes
+  pages from exactly these, so the editor preview matches what ships.
+- **Project config** — `elytra.config.ts`. Identity, locales, component set.

package/template/cms/blocks.ts

@@ -0,0 +1,17 @@
+/**
+ * The composition `allow` vocabulary — this project's code leash (AD-11). Editors
+ * compose pages and posts from these top-level blocks: the platform primitives plus
+ * this repo's own `project.*` components (defined in `../components/marketing`). The
+ * studio reads this from the project's `components` ref and composes against the
+ * repo's real components, not demo fixtures.
+ */
+export const PROJECT_BLOCKS = [
+  'base.primitives.Heading',
+  'base.primitives.Text',
+  'base.primitives.Image',
+  'base.primitives.Button',
+  'base.primitives.Stack',
+  'project.Hero',
+  'project.FeatureCard',
+  'project.Section',
+]

package/template/cms/collections/asset.ts

@@ -0,0 +1,13 @@
+import type { CollectionDef } from '@elytracms/core/cms-core'
+
+/** The asset collection (EC-017). */
+export const asset: CollectionDef = {
+  id: 'asset',
+  kind: 'asset',
+  titleField: 'filename',
+  fields: [
+    { name: 'filename', type: 'text', validation: { required: true } },
+    { name: 'alt', type: 'text', localized: true },
+    { name: 'url', type: 'text', validation: { required: true } },
+  ],
+}

package/template/cms/collections/author.ts

@@ -0,0 +1,12 @@
+import type { CollectionDef } from '@elytracms/core/cms-core'
+
+/** An author collection used as a relation target. */
+export const author: CollectionDef = {
+  id: 'author',
+  kind: 'document',
+  titleField: 'name',
+  fields: [
+    { name: 'name', type: 'text', filterable: true, validation: { required: true } },
+    { name: 'bio', type: 'richText' },
+  ],
+}

package/template/cms/collections/index.ts

@@ -0,0 +1,11 @@
+import type { CollectionDef } from '@elytracms/core/cms-core'
+import { asset } from './asset'
+import { author } from './author'
+import { post } from './post'
+import { page } from './page'
+import { settings } from './settings'
+
+export { asset, author, post, page, settings }
+
+/** This project's CMS collections (AD-11: structure is code, owned by this repo). */
+export const collections: CollectionDef[] = [asset, author, post, page, settings]