@strav/spring 0.4.31 → 1.0.0-alpha.29

package/src/prompts.ts

@@ -1,135 +1,57 @@
-const ESC = '\x1b'
-const ARROW_UP = `${ESC}[A`
-const ARROW_DOWN = `${ESC}[B`
-const ENTER = '\r'
-
-interface Choice {
+/**
+ * Minimal interactive prompts for `bunx @strav/spring`. Two functions:
+ * `select` for picking from a small fixed list, `input` for a free string.
+ *
+ * No external dependency: spring's whole point is to bootstrap a project
+ * with `bunx` and a pinned framework version — we don't want a chain of
+ * peer deps to install before the user has typed their first thing.
+ *
+ * Tested through the bin (not unit-tested) because the value here is the
+ * interactive I/O surface, not the parsing.
+ */
+
+import * as readline from 'node:readline/promises'
+
+export interface SelectOption<T extends string> {
+  value: T
   label: string
-  value: string
-  description: string
+  description?: string
 }
 
-export async function select(message: string, choices: Choice[]): Promise<string> {
-  let selected = 0
-
-  const render = () => {
-    // Move cursor up to overwrite previous render (except first time)
-    process.stdout.write(`\x1b[${choices.length}A`)
-    for (let i = 0; i < choices.length; i++) {
-      const prefix = i === selected ? '\x1b[36m>\x1b[0m' : ' '
-      const choice = choices[i]!
-      const label = i === selected ? `\x1b[1m${choice.label}\x1b[0m` : choice.label
-      const desc = `\x1b[2m${choice.description}\x1b[0m`
-      process.stdout.write(`\x1b[2K  ${prefix} ${label}  ${desc}\n`)
+export async function select<T extends string>(
+  question: string,
+  options: readonly SelectOption<T>[],
+): Promise<T> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    process.stdout.write(`\n  ${question}\n`)
+    for (let i = 0; i < options.length; i++) {
+      const opt = options[i] as SelectOption<T>
+      const tail = opt.description ? `  \x1b[2m— ${opt.description}\x1b[0m` : ''
+      process.stdout.write(`    \x1b[2m${i + 1})\x1b[0m ${opt.label}${tail}\n`)
     }
-  }
-
-  process.stdout.write(`  \x1b[1m${message}\x1b[0m\n`)
-  // Print initial lines so render() can overwrite them
-  for (const choice of choices) {
-    process.stdout.write('\n')
-  }
-  render()
-
-  return new Promise(resolve => {
-    const stdin = process.stdin
-    stdin.setRawMode(true)
-    stdin.resume()
-    stdin.setEncoding('utf8')
-
-    let buffer = ''
-
-    const onData = (data: string) => {
-      buffer += data
-
-      // Check for Ctrl+C
-      if (buffer.includes('\x03')) {
-        stdin.setRawMode(false)
-        stdin.pause()
-        stdin.removeListener('data', onData)
-        process.stdout.write('\n')
-        process.exit(0)
-      }
-
-      // Process escape sequences
-      while (buffer.length > 0) {
-        if (buffer.startsWith(ARROW_UP)) {
-          selected = (selected - 1 + choices.length) % choices.length
-          render()
-          buffer = buffer.slice(ARROW_UP.length)
-        } else if (buffer.startsWith(ARROW_DOWN)) {
-          selected = (selected + 1) % choices.length
-          render()
-          buffer = buffer.slice(ARROW_DOWN.length)
-        } else if (buffer.startsWith(ENTER)) {
-          stdin.setRawMode(false)
-          stdin.pause()
-          stdin.removeListener('data', onData)
-          resolve(choices[selected]!.value)
-          buffer = ''
-          return
-        } else if (buffer.startsWith(ESC)) {
-          // Incomplete escape sequence, wait for more data
-          break
-        } else {
-          // Discard unrecognized input
-          buffer = buffer.slice(1)
-        }
+    while (true) {
+      const answer = (await rl.question(`\n  > `)).trim()
+      const numeric = Number.parseInt(answer, 10)
+      if (Number.isInteger(numeric) && numeric >= 1 && numeric <= options.length) {
+        return (options[numeric - 1] as SelectOption<T>).value
       }
+      const match = options.find((o) => o.value === answer || o.label === answer)
+      if (match) return match.value
+      process.stdout.write(`  \x1b[31m✗\x1b[0m enter a number 1–${options.length} or the label\n`)
     }
-
-    stdin.on('data', onData)
-  })
+  } finally {
+    rl.close()
+  }
 }
 
-export async function input(message: string, defaultValue: string): Promise<string> {
-  process.stdout.write(`  \x1b[1m${message}\x1b[0m \x1b[2m(${defaultValue})\x1b[0m `)
-
-  return new Promise(resolve => {
-    const stdin = process.stdin
-    stdin.setRawMode(true)
-    stdin.resume()
-    stdin.setEncoding('utf8')
-
-    let value = ''
-
-    const onData = (data: string) => {
-      for (const char of data) {
-        if (char === '\x03') {
-          // Ctrl+C
-          stdin.setRawMode(false)
-          stdin.pause()
-          stdin.removeListener('data', onData)
-          process.stdout.write('\n')
-          process.exit(0)
-        }
-
-        if (char === '\r' || char === '\n') {
-          stdin.setRawMode(false)
-          stdin.pause()
-          stdin.removeListener('data', onData)
-          process.stdout.write('\n')
-          resolve(value || defaultValue)
-          return
-        }
-
-        if (char === '\x7f' || char === '\b') {
-          // Backspace
-          if (value.length > 0) {
-            value = value.slice(0, -1)
-            process.stdout.write('\b \b')
-          }
-          continue
-        }
-
-        // Printable characters
-        if (char >= ' ') {
-          value += char
-          process.stdout.write(char)
-        }
-      }
-    }
-
-    stdin.on('data', onData)
-  })
-}
+export async function input(question: string, fallback?: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const suffix = fallback !== undefined ? ` \x1b[2m(${fallback})\x1b[0m` : ''
+    const answer = (await rl.question(`  ${question}${suffix}: `)).trim()
+    return answer === '' && fallback !== undefined ? fallback : answer
+  } finally {
+    rl.close()
+  }
+}

package/src/scaffold.ts

@@ -1,54 +1,133 @@
-import { readdirSync, mkdirSync, statSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import pkg from '../package.json'
+/**
+ * Scaffolder. Walks the template tree under `src/templates/{shared,<template>}/`,
+ * copies each file to `dest`, and applies a tiny `{{token}}` pass to `.tt`
+ * files. Plain files are copied byte-for-byte.
+ *
+ * Conventions baked in:
+ *   - Files named with a leading `_dot_` are written with a leading `.`. This
+ *     avoids npm-publish edge cases where dotfiles inside `src/` can be ignored
+ *     by registries' implicit ignore lists.
+ *   - The `.tt` suffix marks a file with `{{token}}` interpolation. The suffix
+ *     is stripped on write. `{{token}}` is a literal replace — no conditionals,
+ *     no loops.
+ *   - Overlay order: `shared/` is copied first, then `<template>/` is copied
+ *     on top, with overlay files overwriting matching paths.
+ */
+
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, relative } from 'node:path'
+import { SpringError } from './spring_error.ts'
+
+const TEMPLATES_ROOT = join(import.meta.dir, 'templates')
 
 export interface ScaffoldOptions {
   projectName: string
   template: 'api' | 'web'
   dbName: string
+  /** Absolute path the project is written to. */
+  dest: string
+  /**
+   * Override the framework version string injected into the generated
+   * `package.json`. Tests pass `'workspace:*'` so the scaffolded app can
+   * boot inside this monorepo without `bun install`. Defaults to the
+   * pinned constant from `version.ts`.
+   */
+  stravVersion?: string
 }
 
-export async function scaffold(root: string, opts: ScaffoldOptions): Promise<void> {
-  const templatesDir = join(import.meta.dir, 'templates')
-  const appKey = crypto.randomUUID()
+export interface ScaffoldResult {
+  /** Project-root-relative paths of every file written. */
+  files: readonly string[]
+}
 
-  const replacements: Record<string, string> = {
-    __PROJECT_NAME__: opts.projectName,
-    __DB_NAME__: opts.dbName,
-    __APP_KEY__: appKey,
-    __STRAV_VERSION__: `^${pkg.version}`,
+export async function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult> {
+  const tokens = {
+    projectName: opts.projectName,
+    dbName: opts.dbName,
+    stravVersion: opts.stravVersion ?? (await defaultStravVersion()),
   }
 
-  // Copy shared files first, then template-specific (may override shared)
-  await copyDir(join(templatesDir, 'shared'), root, replacements)
-  await copyDir(join(templatesDir, opts.template), root, replacements)
-}
+  const written: string[] = []
+  const overlayLayers = [join(TEMPLATES_ROOT, 'shared'), join(TEMPLATES_ROOT, opts.template)]
 
-async function copyDir(
-  srcDir: string,
-  destDir: string,
-  replacements: Record<string, string>
-): Promise<void> {
-  const entries = readdirSync(srcDir)
+  for (const layer of overlayLayers) {
+    if (!(await pathExists(layer))) {
+      // The overlay for a given template may be absent (e.g., --api has no
+      // overlay in slice A — everything ships in shared/). Skip silently.
+      continue
+    }
+    for await (const sourceFile of walk(layer)) {
+      const rel = relative(layer, sourceFile)
+      const targetRel = applyDotPrefix(stripTemplateSuffix(rel))
+      const targetAbs = join(opts.dest, targetRel)
+      await mkdir(dirname(targetAbs), { recursive: true })
 
+      if (sourceFile.endsWith('.tt')) {
+        const raw = await readFile(sourceFile, 'utf8')
+        await writeFile(targetAbs, interpolate(raw, tokens), 'utf8')
+      } else {
+        const buf = await readFile(sourceFile)
+        await writeFile(targetAbs, buf)
+      }
+      written.push(targetRel)
+    }
+  }
+
+  // .gitkeep files don't have a real purpose in the generated tree — they
+  // exist only so empty template directories survive git/npm. Strip from
+  // the result manifest so tests see a clean list, but leave on disk so
+  // `make:*` commands can target the directories.
+  return { files: written.sort() }
+}
+
+async function* walk(dir: string): AsyncIterable<string> {
+  const entries = await readdir(dir, { withFileTypes: true })
   for (const entry of entries) {
-    const srcPath = join(srcDir, entry)
-    const destPath = join(destDir, entry.replace(/\.tpl$/, ''))
-
-    if (statSync(srcPath).isDirectory()) {
-      await copyDir(srcPath, destPath, replacements)
-    } else {
-      mkdirSync(dirname(destPath), { recursive: true })
-      const content = await Bun.file(srcPath).text()
-      await Bun.write(destPath, applyReplacements(content, replacements))
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      yield* walk(full)
+    } else if (entry.isFile()) {
+      yield full
     }
   }
 }
 
-function applyReplacements(content: string, replacements: Record<string, string>): string {
-  let result = content
-  for (const [placeholder, value] of Object.entries(replacements)) {
-    result = result.replaceAll(placeholder, value)
+async function pathExists(p: string): Promise<boolean> {
+  try {
+    await stat(p)
+    return true
+  } catch {
+    return false
   }
-  return result
-}
+}
+
+function stripTemplateSuffix(path: string): string {
+  return path.endsWith('.tt') ? path.slice(0, -3) : path
+}
+
+const DOT_PREFIX = '_dot_'
+
+function applyDotPrefix(path: string): string {
+  // Apply per-segment so nested files like `_dot_github/workflows/x.yml` work.
+  return path
+    .split('/')
+    .map((seg) => (seg.startsWith(DOT_PREFIX) ? `.${seg.slice(DOT_PREFIX.length)}` : seg))
+    .join('/')
+}
+
+const TOKEN_RE = /\{\{\s*([a-zA-Z][a-zA-Z0-9_]*)\s*\}\}/g
+
+function interpolate(source: string, tokens: Record<string, string>): string {
+  return source.replace(TOKEN_RE, (_, name: string) => {
+    const value = tokens[name]
+    if (value === undefined) {
+      throw new SpringError(`template references unknown token {{${name}}}`)
+    }
+    return value
+  })
+}
+
+async function defaultStravVersion(): Promise<string> {
+  const { STRAV_VERSION } = await import('./version.ts')
+  return STRAV_VERSION
+}

package/src/spring_error.ts

@@ -0,0 +1,11 @@
+/**
+ * `SpringError` — error class local to `@strav/spring`.
+ *
+ * Spring has zero `@strav/*` runtime dependencies (see the template-strategy
+ * ADR), so it cannot use `StravError` from `@strav/kernel`. This is a small
+ * local equivalent: a typed error so the CLI top-level can distinguish
+ * expected user-facing errors from unexpected bugs.
+ */
+export class SpringError extends Error {
+  override readonly name = 'SpringError'
+}

package/src/templates/shared/README.md.tt

@@ -0,0 +1,37 @@
+# {{projectName}}
+
+A Strav 1.0 application scaffolded by `@strav/spring`.
+
+## Run
+
+```bash
+bun install
+bun strav serve              # HTTP server on http://localhost:3000
+bun strav                    # list every available command
+bun strav key:generate       # generate a real APP_KEY
+```
+
+## Layout
+
+This project follows the layout in `spec/directory-structure.md`:
+
+- `app/` — your application code (`http/`, `models/`, `providers/`, …)
+- `bin/strav.ts` — single dispatcher; `bun strav <command>` invokes it
+- `bootstrap/` — `app.ts` (Application factory) + `providers.ts` (provider list)
+- `config/` — typed config files; one per package, each exports `default`
+- `routes/` — route declarations
+- `tests/feature/` — HTTP-level integration tests
+- `tests/unit/` — pure unit tests
+
+## Adding more packages
+
+The scaffolded app starts with the minimum stack (`@strav/{kernel,http,cli}`).
+Add `@strav/database`, `@strav/auth`, `@strav/queue`, … as you need them:
+
+```bash
+bun add @strav/database
+```
+
+Then create the matching `config/<name>.ts` file, add the provider to
+`bootstrap/providers.ts`, and (for `@strav/database`) wire `DB_*` env vars
+in `.env`.

package/src/templates/shared/_dot_env.example.tt

@@ -0,0 +1,12 @@
+APP_NAME={{projectName}}
+APP_ENV=local
+APP_KEY=
+APP_URL=http://localhost:3000
+LOG_LEVEL=info
+
+# Database — uncomment + fill in when you add @strav/database
+# DB_HOST=127.0.0.1
+# DB_PORT=5432
+# DB_USER=
+# DB_PASSWORD=
+# DB_DATABASE={{dbName}}

package/src/templates/shared/_dot_env.tt

@@ -0,0 +1,12 @@
+APP_NAME={{projectName}}
+APP_ENV=local
+APP_KEY=change-me-with-key-generate
+APP_URL=http://localhost:3000
+LOG_LEVEL=info
+
+# Database — uncomment + fill in when you add @strav/database
+# DB_HOST=127.0.0.1
+# DB_PORT=5432
+# DB_USER=strav
+# DB_PASSWORD=strav
+# DB_DATABASE={{dbName}}

package/src/templates/shared/_dot_gitignore

@@ -0,0 +1,12 @@
+node_modules
+.env
+.env.local
+storage/cache/*
+!storage/cache/.gitkeep
+storage/logs/*
+!storage/logs/.gitkeep
+storage/uploads/*
+!storage/uploads/.gitkeep
+public/assets
+*.log
+.DS_Store

package/src/templates/shared/app/providers/app_provider.ts

@@ -0,0 +1,18 @@
+import { Router } from '@strav/http'
+import { type Application, ServiceProvider } from '@strav/kernel'
+import { registerApiRoutes } from '../../routes/api.ts'
+
+/**
+ * Application-level wiring: registers routes, app-owned bindings, custom
+ * middleware. Runs in `register()` (not `boot()`) so the router still
+ * accepts route additions — `HttpProvider.boot()` compiles the trie and
+ * locks the registry.
+ */
+export class AppProvider extends ServiceProvider {
+  override readonly name = 'app'
+  override readonly dependencies = ['http']
+
+  override register(app: Application): void {
+    registerApiRoutes(app.resolve(Router))
+  }
+}

package/src/templates/shared/bin/strav.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+/**
+ * Single entry point for every role. `ConsoleKernel` (via `runCli`) parses
+ * the subcommand and resolves the right kernel — `serve` for `HttpKernel`,
+ * `make:*` for one-shot scaffolders, etc. Add new commands by listing a
+ * `ConsoleProvider` subclass in `bootstrap/providers.ts`; `runCli`
+ * auto-collects their `commands` arrays.
+ */
+
+// `@strav/kernel` imports `reflect-metadata` internally; consumers don't need to.
+import { runCli } from '@strav/cli'
+import { createApp } from '../bootstrap/app.ts'
+import { providers } from '../bootstrap/providers.ts'
+
+const exitCode = await runCli({
+  argv: process.argv.slice(2),
+  defaultProviders: await providers(),
+  app: createApp(),
+})
+
+process.exit(exitCode)

package/src/templates/shared/bootstrap/app.ts

@@ -0,0 +1,13 @@
+import { Application } from '@strav/kernel'
+
+/**
+ * Build the `Application` instance. Providers are NOT attached here —
+ * `runCli` (in `bin/strav.ts`) picks the right subset for the requested
+ * command from `bootstrap/providers.ts` and registers them on this app.
+ *
+ * App-level hooks (env detection, custom singletons that don't belong in
+ * a provider) can be added here later without touching every command.
+ */
+export function createApp(): Application {
+  return new Application()
+}

package/src/templates/shared/bootstrap/providers.ts

@@ -0,0 +1,24 @@
+import { HttpConsoleProvider, HttpProvider } from '@strav/http'
+import { ConfigProvider, LoggerProvider, type ServiceProvider } from '@strav/kernel'
+import { AppProvider } from '../app/providers/app_provider.ts'
+
+/**
+ * Default provider list. Order is not load-bearing — the container does a
+ * dependency-aware topo sort at boot. Keep providers grouped by package
+ * for readability.
+ *
+ * `ConfigProvider.fromDirectory('config')` auto-discovers every
+ * `config/*.ts` file and keys them by basename — `config/app.ts` →
+ * `config('app.*')`, `config/http.ts` → `config('http.*')`, etc. To add
+ * a new config slot, drop a file with a `default export` into
+ * `config/`. No edits to this list required.
+ */
+export async function providers(): Promise<ServiceProvider[]> {
+  return [
+    await ConfigProvider.fromDirectory('config'),
+    new LoggerProvider(),
+    new HttpProvider(),
+    new HttpConsoleProvider(),
+    new AppProvider(),
+  ]
+}

package/src/templates/shared/config/app.ts.tt

@@ -0,0 +1,13 @@
+import { env } from '@strav/kernel'
+
+export default {
+  name: env('APP_NAME', '{{projectName}}'),
+  env: env('APP_ENV', 'local'),
+  /**
+   * Encryption + signing key. Generate one with `bun strav key:generate`
+   * and copy the value into `.env`. The placeholder below is fine for
+   * `bun strav serve` smoke-tests but MUST be replaced before deploying.
+   */
+  key: env('APP_KEY', 'change-me-with-key-generate'),
+  url: env('APP_URL', 'http://localhost:3000'),
+}

package/src/templates/shared/config/http.ts

@@ -0,0 +1,9 @@
+import { env } from '@strav/kernel'
+
+export default {
+  /**
+   * Expose stack traces in error responses. Convenient locally; never
+   * leave this on in production.
+   */
+  exposeStackTrace: env('APP_ENV', 'local') !== 'production',
+}

package/src/templates/shared/config/logger.ts

@@ -0,0 +1,9 @@
+import { env } from '@strav/kernel'
+
+export default {
+  default: 'stderr',
+  level: env('LOG_LEVEL', 'info'),
+  channels: {
+    stderr: { driver: 'stderr' },
+  },
+}

package/src/templates/shared/package.json.tt

@@ -0,0 +1,22 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "strav": "bun bin/strav.ts",
+    "dev": "bun --hot bin/strav.ts serve",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@strav/cli": "{{stravVersion}}",
+    "@strav/http": "{{stravVersion}}",
+    "@strav/kernel": "{{stravVersion}}"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/templates/shared/routes/api.ts

@@ -0,0 +1,11 @@
+import type { Router } from '@strav/http'
+
+/**
+ * Wire JSON routes. Imported and called from `app/providers/app_provider.ts`.
+ *
+ * The router is a registry until boot, so this function only declares routes;
+ * the actual trie compile happens inside `HttpProvider.boot()`.
+ */
+export function registerApiRoutes(router: Router): void {
+  router.get('/healthz', () => Response.json({ ok: true }))
+}

package/src/templates/shared/routes/console.ts

@@ -0,0 +1,10 @@
+/**
+ * Custom console commands and scheduled tasks. Register them by adding a
+ * `ConsoleProvider` subclass to `bootstrap/providers.ts` whose `commands`
+ * array lists your `Command` classes.
+ *
+ * This file is intentionally empty in the scaffold — it's a documentation
+ * anchor so the layout matches `spec/directory-structure.md`. Add wiring
+ * here once you create your first custom command (`bun strav make:command`).
+ */
+export {}