create-top-secret-starter 0.1.0 → 0.2.1

package/index.js

@@ -5,21 +5,28 @@ import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { cancel, intro, isCancel, outro, select, text } from '@clack/prompts'
 
-// lesson 001: the package manager that launched us sets npm_config_user_agent
+// the package manager that launched us sets npm_config_user_agent
 const agent = process.env.npm_config_user_agent ?? ''
 const detectedPm = agent.split('/')[0] || 'npm'
 
 const PMS = ['bun', 'pnpm', 'npm']
-const ROUTERS = ['router', 'start']
+const ROUTER_LABELS = { router: 'TanStack Router', start: 'TanStack Start' }
+const ROUTERS = Object.keys(ROUTER_LABELS)
 const NAME_RE = /^[a-z0-9][a-z0-9._-]*$/
+// web-side runtime deps the backend variant adds (the api types come in as a devDep)
+const BACKEND_WEB_DEPS = { '@elysia/eden': '^1.4.10', 'better-auth': '^1.7.2' }
 
-// lesson 002 §6: flags bypass prompts so the CLI works in CI
+// flags bypass prompts so the CLI works in CI
 const { values: flags, positionals } = parseArgs({
   args: process.argv.slice(2),
   allowPositionals: true,
   options: {
     pm: { type: 'string' },
-    router: { type: 'string' }
+    router: { type: 'string' },
+    backend: { type: 'boolean' },
+    'no-backend': { type: 'boolean' },
+    redis: { type: 'boolean' },
+    'no-redis': { type: 'boolean' }
   }
 })
 
@@ -38,18 +45,24 @@ function validateName(v) {
 
 intro('create-top-secret-starter')
 
-let name = positionals[0]
-if (name && validateName(name)) {
+// `.` / `./` scaffold into the current directory; the package name is then the
+// directory's basename
+const target =
+  positionals.at(0) ??
+  must(
+    await text({
+      message: 'Project name (or . for the current directory)?',
+      placeholder: 'my-ai-app',
+      validate: v => (v ? undefined : 'Project name is required')
+    })
+  )
+const targetDir = path.resolve(process.cwd(), target)
+const inPlace = targetDir === process.cwd()
+const name = path.basename(targetDir)
+if (validateName(name)) {
   cancel(`Invalid project name "${name}": ${validateName(name)}`)
   process.exit(1)
 }
-name ??= must(
-  await text({
-    message: 'Project name?',
-    placeholder: 'my-ai-app',
-    validate: validateName
-  })
-)
 
 let pm = flags.pm
 if (pm && !PMS.includes(pm)) {
@@ -73,45 +86,236 @@ router ??= must(
   await select({
     message: 'Routing?',
     options: [
-      { value: 'router', label: 'TanStack Router', hint: 'SPA' },
-      { value: 'start', label: 'TanStack Start', hint: 'SSR, full-stack' }
+      { value: 'router', label: ROUTER_LABELS.router, hint: 'SPA' },
+      { value: 'start', label: ROUTER_LABELS.start, hint: 'SSR, full-stack' }
     ]
   })
 )
 
-const targetDir = path.resolve(process.cwd(), name)
-if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0) {
-  cancel(`Directory "${name}" already exists and is not empty.`)
+// Elysia runs on Bun, so the backend is only offered when bun is the package manager.
+const flagPair = (on, off) => {
+  if (on) return true
+  if (off) return false
+  return undefined
+}
+
+let backend = flagPair(flags.backend, flags['no-backend'])
+if (backend && pm !== 'bun') {
+  cancel('The backend (Elysia) requires bun: pass --pm bun.')
+  process.exit(1)
+}
+if (backend === undefined && pm === 'bun') {
+  backend = must(
+    await select({
+      message: 'Backend?',
+      options: [
+        { value: false, label: 'None', hint: 'SPA only, mock API in dev' },
+        { value: true, label: 'Elysia + Drizzle + Better Auth', hint: 'Postgres, bun workspace' }
+      ]
+    })
+  )
+}
+backend ??= false
+
+// Redis (Bun's built-in client) as Better Auth's secondary storage: sessions and
+// rate-limit counters survive restarts and are shared across instances.
+let redis = flagPair(flags.redis, flags['no-redis'])
+if (redis && !backend) {
+  cancel('--redis requires the backend: pass --backend.')
   process.exit(1)
 }
+if (redis === undefined && backend) {
+  redis = must(
+    await select({
+      message: 'Redis?',
+      options: [
+        { value: false, label: 'None', hint: 'sessions in Postgres, rate limit per process' },
+        { value: true, label: 'Redis', hint: 'Better Auth secondary storage, bun.redis' }
+      ]
+    })
+  )
+}
+redis ??= false
 
-// lesson 003 §4: variant A — one full template per router choice
-const templateDir = path.join(
-  path.dirname(fileURLToPath(import.meta.url)),
-  'templates',
-  `template-${router}`
-)
+// a fresh `git init` is fine, anything else would be overwritten
+const existing = fs.existsSync(targetDir)
+  ? fs.readdirSync(targetDir).filter(entry => entry !== '.git')
+  : []
+if (existing.length > 0) {
+  cancel(`Directory "${target}" is not empty.`)
+  process.exit(1)
+}
+
+// one full template per router choice
+const cliRoot = path.dirname(fileURLToPath(import.meta.url))
+const templateDir = path.join(cliRoot, 'templates', `template-${router}`)
 if (!fs.existsSync(templateDir)) {
-  cancel(`The ${router === 'start' ? 'TanStack Start' : router} template is not available yet.`)
+  cancel(`The ${ROUTER_LABELS[router]} template is not available yet.`)
   process.exit(1)
 }
-fs.cpSync(templateDir, targetDir, { recursive: true })
+// npm strips .gitignore from packages, so it ships as _gitignore
+const restoreGitignore = dir => {
+  const src = path.join(dir, '_gitignore')
+  if (fs.existsSync(src)) fs.renameSync(src, path.join(dir, '.gitignore'))
+}
+const patchFile = (file, fn) => fs.writeFileSync(file, fn(fs.readFileSync(file, 'utf8')))
+// The api source keeps Redis-only code between `redis:start` / `redis:end` marker
+// comments, so one source tree serves both answers to the Redis prompt.
+const REDIS_MARKER = /^[ \t]*(\/\/|#|<!--) redis:(start|end)( -->)?\n/gm
+const REDIS_BLOCK =
+  /^[ \t]*(\/\/|#|<!--) redis:start( -->)?\n[\s\S]*?^[ \t]*(\/\/|#|<!--) redis:end( -->)?\n/gm
+// each removal site is marked so the comma repair below stays local to it
+const HOLE = '__REDIS_HOLE__'
+
+const applyRedisMarkers = (file, keep) =>
+  patchFile(file, source =>
+    source
+      .replace(keep ? REDIS_MARKER : REDIS_BLOCK, HOLE)
+      // dropping the last entry of an object or call leaves a dangling comma
+      .replace(new RegExp(`,(\\s*)${HOLE}(\\s*[)}\\]])`, 'g'), '$1$2')
+      .replaceAll(HOLE, '')
+      .replace(/\n{3,}/g, '\n\n')
+  )
+
+// walk rather than a hardcoded list: marked code may live in any api file
+const filesWithRedisMarkers = dir =>
+  fs
+    .readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter(entry => entry.isFile())
+    .map(entry => path.join(entry.parentPath, entry.name))
+    .filter(file => fs.readFileSync(file, 'utf8').includes('redis:start'))
+
+const editJson = (file, fn) => {
+  const value = JSON.parse(fs.readFileSync(file, 'utf8'))
+  fn(value)
+  fs.writeFileSync(file, JSON.stringify(value, null, 2) + '\n')
+}
+
+const webDir = backend ? path.join(targetDir, 'apps', 'web') : targetDir
+fs.cpSync(templateDir, webDir, { recursive: true })
+
+// The backend variant is the flat template plus an overlay: files the Eden/Better
+// Auth stack replaces are deleted, the rest is copied over, and the workspace root
+// is laid down around it.
+const applyBackendOverlay = () => {
+  const overlay = path.join(cliRoot, 'backend-overlay')
+
+  for (const file of JSON.parse(fs.readFileSync(path.join(overlay, 'remove.json'), 'utf8'))) {
+    fs.rmSync(path.join(webDir, file), { recursive: true, force: true })
+  }
+  fs.cpSync(path.join(overlay, 'web'), webDir, { recursive: true })
+  fs.cpSync(path.join(overlay, `web-${router}`), webDir, { recursive: true })
+  // one .gitignore, at the workspace root
+  fs.rmSync(path.join(webDir, '_gitignore'), { force: true })
+
+  // dev proxy: same origin for the session cookie
+  patchFile(path.join(webDir, 'vite.config.ts'), source =>
+    source.replace(
+      'export default defineConfig({\n',
+      "export default defineConfig({\n  server: { proxy: { '/api': 'http://localhost:3000' } },\n"
+    )
+  )
+
+  const templatePkg = JSON.parse(fs.readFileSync(path.join(webDir, 'package.json'), 'utf8'))
+  editJson(path.join(webDir, 'package.json'), pkg => {
+    pkg.name = '@repo/web'
+    delete pkg.dependencies.ky
+    Object.assign(pkg.dependencies, BACKEND_WEB_DEPS)
+    pkg.dependencies = Object.fromEntries(
+      Object.entries(pkg.dependencies).sort(([a], [b]) => a.localeCompare(b))
+    )
+    // type-only import (Eden); as a runtime dep it would drag elysia/drizzle into
+    // the web app's production dependency graph
+    pkg.devDependencies['@repo/api'] = 'workspace:*'
+    pkg.devDependencies = Object.fromEntries(
+      Object.entries(pkg.devDependencies).sort(([a], [b]) => a.localeCompare(b))
+    )
+    // lint and format run once, from the workspace root
+    for (const script of ['lint', 'lint:fix', 'format', 'format:check']) delete pkg.scripts[script]
+    delete pkg.trustedDependencies
+  })
+
+  const apiDir = path.join(targetDir, 'apps', 'api')
+  fs.cpSync(path.join(cliRoot, 'templates', 'template-api'), apiDir, { recursive: true })
+  if (!redis) fs.rmSync(path.join(apiDir, 'src', 'redis.ts'))
+  for (const file of filesWithRedisMarkers(apiDir)) applyRedisMarkers(file, redis)
+  // an unbalanced marker would otherwise ship Redis code into a --no-redis project
+  const leftover = filesWithRedisMarkers(apiDir)
+  if (leftover.length > 0) {
+    cancel(`Unbalanced redis: markers in ${leftover.join(', ')} - this is a template bug.`)
+    process.exit(1)
+  }
+  fs.cpSync(path.join(overlay, 'root'), targetDir, { recursive: true })
+  restoreGitignore(targetDir)
+
+  // Claude Code config belongs to the workspace root, not the web app
+  for (const file of ['.claude', '.mcp.json', 'CLAUDE.md']) {
+    fs.renameSync(path.join(webDir, file), path.join(targetDir, file))
+  }
+  patchFile(
+    path.join(targetDir, 'CLAUDE.md'),
+    source =>
+      source
+        .replace('`@/` → `src/`.', '`@/` → `apps/web/src/`.')
+        .replaceAll('`src/', '`apps/web/src/') +
+      '\n## Backend\n\n`apps/api` (Elysia + Drizzle + Better Auth) has its own `CLAUDE.md`. The web app talks to it through the Eden client; the Vite dev proxy keeps the session cookie first-party.\n'
+  )
+
+  for (const file of ['.oxfmtrc.json', '.oxlintrc.json']) {
+    const dest = path.join(targetDir, file)
+    fs.renameSync(path.join(webDir, file), dest)
+    // textual edit: re-serialising would break the oxfmt style the file itself enforces
+    patchFile(dest, source => source.replaceAll('"src/', '"apps/web/src/'))
+  }
+  editJson(path.join(targetDir, 'package.json'), pkg => {
+    pkg.name = name
+    pkg.devDependencies.oxfmt = templatePkg.devDependencies.oxfmt
+    pkg.devDependencies.oxlint = templatePkg.devDependencies.oxlint
+  })
+
+  for (const file of [
+    'README.md',
+    path.join('apps', 'web', 'src', 'routes', '_authenticated', 'index.tsx')
+  ]) {
+    patchFile(path.join(targetDir, file), source => source.replaceAll('PLACEHOLDER', name))
+  }
+}
 
-// lesson 003 §2: npm strips .gitignore from packages, so it ships as _gitignore
-const renameFiles = { _gitignore: '.gitignore' }
-for (const [from, to] of Object.entries(renameFiles)) {
-  const src = path.join(targetDir, from)
-  if (fs.existsSync(src)) fs.renameSync(src, path.join(targetDir, to))
+if (backend) {
+  applyBackendOverlay()
+} else {
+  restoreGitignore(targetDir)
+  editJson(path.join(targetDir, 'package.json'), pkg => {
+    pkg.name = name
+  })
+  // textual edits: re-serialising would break the oxfmt style the project enforces
+  if (pm !== 'bun') {
+    patchFile(path.join(targetDir, '.claude', 'launch.json'), source =>
+      source.replace('"runtimeExecutable": "bun"', `"runtimeExecutable": "${pm}"`)
+    )
+    // MCP servers start through the pm's package runner
+    patchFile(path.join(targetDir, '.mcp.json'), source =>
+      pm === 'pnpm'
+        ? source
+            .replaceAll('"command": "bunx"', '"command": "pnpm"')
+            .replaceAll('"args": [', '"args": ["dlx", ')
+        : source.replaceAll('"command": "bunx"', '"command": "npx"')
+    )
+  }
 }
 
-const pkgPath = path.join(targetDir, 'package.json')
-const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
-pkg.name = name
-fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+const label = `${ROUTER_LABELS[router]}${backend ? ' + Elysia/Drizzle/Better Auth' : ''}${redis ? ' + Redis' : ''}`
+const steps = backend
+  ? [
+      ...(inPlace ? [] : [`cd ${target}`]),
+      'bun install',
+      `cp apps/api/.env.example apps/api/.env   # set DATABASE_URL${redis ? ', REDIS_URL' : ''}, BETTER_AUTH_SECRET`,
+      'bun run db:migrate',
+      'bun run dev'
+    ]
+  : [...(inPlace ? [] : [`cd ${target}`]), `${pm} install`, `${pm} run dev`]
 
-outro(`✔ ${name} created (${router === 'start' ? 'TanStack Start' : 'TanStack Router'})
+outro(`✔ ${name} created (${label})
 
 Next steps:
-  cd ${name}
-  ${pm} install
-  ${pm} run dev`)
+${steps.map(s => `  ${s}`).join('\n')}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-top-secret-starter",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Scaffold a Vite + React 19 + TypeScript + shadcn starter with TanStack Router",
   "keywords": [
     "create",
@@ -28,6 +28,6 @@
     "@clack/prompts": "^1.7.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.12"
   }
 }

package/templates/template-api/.env.example

@@ -0,0 +1,13 @@
+DATABASE_URL=postgres://user:password@host:5432/dbname
+# openssl rand -base64 32
+BETTER_AUTH_SECRET=
+# public origin the browser talks to — the Vite dev server when proxying /api;
+# https in production (also enables secure cookies)
+BETTER_AUTH_URL=http://localhost:5173
+PORT=3000
+# comma-separated extra origins; leave empty when the SPA is served from the same origin
+CORS_ORIGINS=
+# redis:start
+# optional: sessions + rate-limit counters in Redis instead of Postgres/memory
+REDIS_URL=redis://localhost:6379
+# redis:end

package/templates/template-api/CLAUDE.md

@@ -0,0 +1,32 @@
+# apps/api
+
+Elysia + Drizzle (Postgres via postgres.js) + Better Auth. Bun workspace member;
+root `verify` covers it. Tests run on PGlite with the committed migrations — no
+server needed.
+
+- Feature layout per [Elysia best practices](https://elysiajs.com/essential/best-practice):
+  `src/modules/<feature>/{index,service,model}.ts` — controller / plain static-class
+  service / `t` schemas. Services never touch `Context`; one Elysia instance is one
+  controller.
+- `src/app.ts` is the Eden boundary: no Bun globals, no `process.env`, deps injected
+  via `createApp`.
+- Wire values are JSON-shaped (`createdAt` is an ISO string, not `Date`) so Eden's
+  types match what the client receives.
+- `src/db/auth-schema.ts` is hand-maintained in the better-auth **1.7** shape
+  (`account.issuer`). `@better-auth/cli generate` lags the library — don't use it.
+- Elysia's `status(204)` works under Bun but 500s under Node (vitest); return
+  `new Response(null, { status: 204 })` so tests pass.
+- Schema change → `bun run db:generate`, commit `drizzle/`.
+
+<!-- redis:start -->
+
+- `REDIS_URL` is optional: when set, `src/redis.ts` (Bun's built-in `RedisClient`)
+  becomes Better Auth's `secondaryStorage` for sessions and rate limiting.
+
+<!-- redis:end -->
+
+- Deploy target is Railway (Railpack, no Dockerfile): service root `apps/api`,
+  `start` runs migrations then serves. `BETTER_AUTH_URL` must be the public https
+  origin — Better Auth derives the secure cookie flag from it.
+- `@repo/api` is a **dev**Dependency of the web app: the import is type-only, and as
+  a runtime dep it drags elysia/drizzle into the web production graph.

package/templates/template-api/drizzle/0000_damp_taskmaster.sql

@@ -0,0 +1,64 @@
+CREATE TABLE "note" (
+	"id" text PRIMARY KEY NOT NULL,
+	"title" text NOT NULL,
+	"user_id" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "account" (
+	"id" text PRIMARY KEY NOT NULL,
+	"issuer" text NOT NULL,
+	"account_id" text NOT NULL,
+	"provider_id" text NOT NULL,
+	"user_id" text NOT NULL,
+	"access_token" text,
+	"refresh_token" text,
+	"id_token" text,
+	"access_token_expires_at" timestamp,
+	"refresh_token_expires_at" timestamp,
+	"scope" text,
+	"password" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "session" (
+	"id" text PRIMARY KEY NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"token" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp NOT NULL,
+	"ip_address" text,
+	"user_agent" text,
+	"user_id" text NOT NULL,
+	CONSTRAINT "session_token_unique" UNIQUE("token")
+);
+--> statement-breakpoint
+CREATE TABLE "user" (
+	"id" text PRIMARY KEY NOT NULL,
+	"name" text NOT NULL,
+	"email" text NOT NULL,
+	"email_verified" boolean DEFAULT false NOT NULL,
+	"image" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "user_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE "verification" (
+	"id" text PRIMARY KEY NOT NULL,
+	"identifier" text NOT NULL,
+	"value" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "note" ADD CONSTRAINT "note_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "account" ADD CONSTRAINT "account_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "session" ADD CONSTRAINT "session_user_id_user_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."user"("id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "note_userId_idx" ON "note" USING btree ("user_id");--> statement-breakpoint
+CREATE UNIQUE INDEX "account_issuer_accountId_uidx" ON "account" USING btree ("issuer","account_id");--> statement-breakpoint
+CREATE INDEX "account_userId_idx" ON "account" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "session_userId_idx" ON "session" USING btree ("user_id");--> statement-breakpoint
+CREATE INDEX "verification_identifier_idx" ON "verification" USING btree ("identifier");