@strav/spring 0.3.0

package/README.md

@@ -0,0 +1,61 @@
+# @strav/spring
+
+Flagship framework scaffolding tool for the Strav ecosystem - the Laravel of the Bun ecosystem.
+
+## Usage
+
+```bash
+bunx @strav/spring my-app --web   # full-stack with Vue islands
+bunx @strav/spring my-app --api   # headless REST API
+bunx @strav/spring my-app         # interactive prompt
+```
+
+## Templates
+
+- **api** — Headless REST API with CORS enabled
+- **web** — Full-stack with .strav views, Vue islands, and sessions
+
+## Options
+
+```
+bunx @strav/spring <project-name> [options]
+
+--api                     Headless REST API template
+--web                     Full-stack template with Vue islands
+--template, -t api|web    Alias for --api / --web
+--db <name>               Database name (default: project name)
+-h, --help                Show help
+```
+
+## What's scaffolded
+
+```
+my-app/
+├── app/
+│   ├── controllers/      # HTTP controllers
+│   ├── models/           # Database models (generated from schemas)
+│   ├── middleware/       # Custom middleware
+│   ├── providers/        # Service providers
+│   ├── policies/         # Authorization policies
+│   ├── jobs/             # Queue jobs
+│   └── services/         # Business logic services
+├── config/               # Configuration files
+├── database/
+│   ├── schemas/public/   # Schema definitions
+│   ├── migrations/public/ # Generated migrations
+│   ├── seeders/          # Database seeders
+│   └── factories/        # Model factories
+├── resources/
+│   ├── views/            # .strav templates
+│   ├── css/              # Stylesheets
+│   └── ts/islands/       # Vue.js islands
+├── routes/               # Route definitions
+├── tests/                # Test files
+├── index.ts              # Application entry point
+├── strav.ts              # CLI tool
+└── .env                  # Environment variables
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@strav/spring",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Flagship framework scaffolding tool for the Strav ecosystem.",
+  "license": "MIT",
+  "keywords": [
+    "strav",
+    "bun",
+    "framework",
+    "scaffold",
+    "create",
+    "laravel",
+    "typescript",
+    "vue"
+  ],
+  "bin": {
+    "@strav/spring": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "package.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@strav/kernel": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+#!/usr/bin/env bun
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { select, input } from './prompts.ts'
+import { scaffold, type ScaffoldOptions } from './scaffold.ts'
+import pkg from '../package.json'
+
+const VERSION = pkg.version
+
+// ── Colors ──────────────────────────────────────────────────────────
+
+const bold = (s: string) => `\x1b[1m${s}\x1b[0m`
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`
+const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`
+
+// ── Arg parsing ─────────────────────────────────────────────────────
+
+interface ParsedArgs {
+  projectName?: string
+  template?: 'api' | 'web'
+  db?: string
+  help?: boolean
+}
+
+function parseArgs(): ParsedArgs {
+  const args = process.argv.slice(2)
+  const result: ParsedArgs = {}
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+
+    if (arg === '--help' || arg === '-h') {
+      result.help = true
+    } else if (arg === '--api') {
+      result.template = 'api'
+    } else if (arg === '--web') {
+      result.template = 'web'
+    } else if (arg === '--template' || arg === '-t') {
+      const val = args[++i]
+      if (val === 'api' || val === 'web') {
+        result.template = val
+      } else {
+        console.error(red(`  Invalid template: ${val}. Use "api" or "web".`))
+        process.exit(1)
+      }
+    } else if (arg === '--db') {
+      result.db = args[++i]
+    } else if (arg && !arg.startsWith('-') && !result.projectName) {
+      result.projectName = arg
+    }
+  }
+
+  return result
+}
+
+function printUsage(): void {
+  console.log(`
+  ${bold('@strav/spring')} ${dim(`v${VERSION}`)}
+  ${dim('The Laravel of the Bun ecosystem')}
+
+  ${bold('Usage:')}
+    bunx @strav/spring ${cyan('<project-name>')} [options]
+
+  ${bold('Options:')}
+    --api                     Headless REST API template
+    --web                     Full-stack template with Vue islands and views
+    --template, -t ${dim('api|web')}    Alias for --api / --web
+    --db ${dim('<name>')}               Database name (default: project name)
+    -h, --help                Show this help message
+
+  ${bold('Examples:')}
+    bunx @strav/spring my-blog --web
+    bunx @strav/spring my-api --api
+    bunx @strav/spring my-app              ${dim('# interactive prompt')}
+  `)
+}
+
+function toSnakeCase(name: string): string {
+  return name
+    .replace(/([A-Z])/g, '_$1')
+    .toLowerCase()
+    .replace(/[-\s]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .replace(/_+/g, '_')
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const args = parseArgs()
+
+  if (args.help) {
+    printUsage()
+    process.exit(0)
+  }
+
+  console.log()
+  console.log(`  ${bold('@strav/spring')} ${dim(`v${VERSION}`)}`)
+  console.log(`  ${dim('The Laravel of the Bun ecosystem')}`)
+  console.log()
+
+  // Project name
+  if (!args.projectName) {
+    printUsage()
+    process.exit(1)
+  }
+
+  const projectName = args.projectName
+  const root = resolve(projectName)
+
+  // Validate
+  if (existsSync(root)) {
+    console.error(red(`  Directory "${projectName}" already exists.`))
+    process.exit(1)
+  }
+
+  if (!/^[a-zA-Z0-9_-]+$/.test(projectName)) {
+    console.error(
+      red(`  Invalid project name. Use only letters, numbers, hyphens, and underscores.`)
+    )
+    process.exit(1)
+  }
+
+  // Template
+  let template = args.template
+  if (!template) {
+    template = (await select('Which template?', [
+      { label: 'web', value: 'web', description: 'Full-stack with Vue islands, views, and sessions' },
+      { label: 'api', value: 'api', description: 'Headless REST API with CORS enabled' },
+    ])) as 'api' | 'web'
+  }
+
+  // Database name
+  const defaultDb = toSnakeCase(projectName)
+  const dbName = args.db ?? defaultDb
+
+  console.log()
+
+  // Scaffold
+  const opts: ScaffoldOptions = { projectName, template, dbName }
+  await scaffold(root, opts)
+  console.log(`  ${green('+')} Scaffolded project files`)
+
+  // Install dependencies
+  console.log(`  ${dim('...')} Installing dependencies`)
+  const install = Bun.spawn(['bun', 'install'], { cwd: root, stdout: 'ignore', stderr: 'pipe' })
+  const exitCode = await install.exited
+
+  if (exitCode !== 0) {
+    const stderr = await new Response(install.stderr).text()
+    console.error(red(`  Failed to install dependencies:`))
+    console.error(dim(`  ${stderr}`))
+    process.exit(1)
+  }
+
+  console.log(`  ${green('+')} Installed dependencies`)
+
+  // Done
+  console.log()
+  console.log(`  ${green('Project created successfully!')}`)
+  console.log()
+  console.log(`  Next steps:`)
+  console.log()
+  console.log(`    ${dim('$')} cd ${projectName}`)
+  console.log(`    ${dim('$')} bun --hot index.ts`)
+  console.log()
+  console.log(`  ${dim('Then open http://localhost:3000')}`)
+  console.log()
+}
+
+main().catch(err => {
+  console.error(red(`  Error: ${err instanceof Error ? err.message : err}`))
+  process.exit(1)
+})

package/src/prompts.ts

@@ -0,0 +1,135 @@
+const ESC = '\x1b'
+const ARROW_UP = `${ESC}[A`
+const ARROW_DOWN = `${ESC}[B`
+const ENTER = '\r'
+
+interface Choice {
+  label: string
+  value: 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`)
+    }
+  }
+
+  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)
+        }
+      }
+    }
+
+    stdin.on('data', onData)
+  })
+}
+
+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)
+  })
+}

package/src/scaffold.ts

@@ -0,0 +1,54 @@
+import { readdirSync, mkdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import pkg from '../package.json'
+
+export interface ScaffoldOptions {
+  projectName: string
+  template: 'api' | 'web'
+  dbName: string
+}
+
+export async function scaffold(root: string, opts: ScaffoldOptions): Promise<void> {
+  const templatesDir = join(import.meta.dir, 'templates')
+  const appKey = crypto.randomUUID()
+
+  const replacements: Record<string, string> = {
+    __PROJECT_NAME__: opts.projectName,
+    __DB_NAME__: opts.dbName,
+    __APP_KEY__: appKey,
+    __STRAV_VERSION__: `^${pkg.version}`,
+  }
+
+  // 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)
+}
+
+async function copyDir(
+  srcDir: string,
+  destDir: string,
+  replacements: Record<string, string>
+): Promise<void> {
+  const entries = readdirSync(srcDir)
+
+  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))
+    }
+  }
+}
+
+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)
+  }
+  return result
+}

package/src/templates/api/app/controllers/user_controller.ts

@@ -0,0 +1,69 @@
+import type { Context } from '@strav/http'
+import { Controller } from './controller.ts'
+import User from '../models/user.ts'
+
+export default class UserController extends Controller {
+  async index(ctx: Context) {
+    const users = await User.all()
+    return this.respond(ctx, { users })
+  }
+
+  async show(ctx: Context) {
+    const { id } = ctx.params
+    const user = await User.find(id)
+
+    if (!user) {
+      return this.notFound(ctx, 'User not found')
+    }
+
+    return this.respond(ctx, { user })
+  }
+
+  async store(ctx: Context) {
+    const { email, name, password } = await ctx.request.json()
+
+    if (!email || !name || !password) {
+      return this.error(ctx, 'Email, name, and password are required')
+    }
+
+    const user = await User.create({
+      id: crypto.randomUUID(),
+      email,
+      name,
+      password_hash: await Bun.password.hash(password),
+    })
+
+    return this.respond(ctx, { user }, 201)
+  }
+
+  async update(ctx: Context) {
+    const { id } = ctx.params
+    const user = await User.find(id)
+
+    if (!user) {
+      return this.notFound(ctx, 'User not found')
+    }
+
+    const { email, name } = await ctx.request.json()
+
+    if (email) user.email = email
+    if (name) user.name = name
+
+    await user.save()
+
+    return this.respond(ctx, { user })
+  }
+
+  async destroy(ctx: Context) {
+    const { id } = ctx.params
+    const user = await User.find(id)
+
+    if (!user) {
+      return this.notFound(ctx, 'User not found')
+    }
+
+    await user.delete()
+
+    return this.respond(ctx, { message: 'User deleted successfully' })
+  }
+}

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

@@ -0,0 +1,10 @@
+import { env } from '@strav/kernel'
+
+export default {
+  port: env.int('APP_PORT', 3000),
+  cors: {
+    enabled: true,
+    origin: ['http://localhost:3000', 'http://localhost:5173'],
+    credentials: true,
+  },
+}

package/src/templates/api/index.ts

@@ -0,0 +1,33 @@
+import 'reflect-metadata'
+import { app } from '@strav/kernel'
+import { router } from '@strav/http'
+import { ConfigProvider, EncryptionProvider } from '@strav/kernel'
+import { DatabaseProvider } from '@strav/database'
+import BaseModel from '@strav/database/orm/base_model'
+import Database from '@strav/database/database/database'
+import Server from '@strav/http/server'
+import { ExceptionHandler } from '@strav/kernel'
+
+// Register service providers
+app
+  .use(new ConfigProvider())
+  .use(new DatabaseProvider())
+  .use(new EncryptionProvider())
+
+// Boot services (loads config, connects database, derives encryption keys)
+await app.start()
+
+// Initialize ORM
+new BaseModel(app.resolve(Database))
+
+// Configure router for API
+router.useExceptionHandler(new ExceptionHandler(true))
+router.cors()
+
+// Load routes
+await import('./routes/routes')
+
+// Start HTTP server
+app.singleton(Server)
+const server = app.resolve(Server)
+server.start(router)

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

@@ -0,0 +1,24 @@
+import type { Router } from '@strav/http'
+import UserController from '../app/controllers/user_controller.ts'
+
+export default function (router: Router) {
+  // Health check endpoint
+  router.get('/health', async (ctx) => {
+    return ctx.json({
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      app: '__PROJECT_NAME__',
+      version: '0.1.0'
+    })
+  })
+
+  // API routes
+  router.group('/api/v1', () => {
+    // User resource routes
+    router.get('/users', [UserController, 'index'])
+    router.get('/users/:id', [UserController, 'show'])
+    router.post('/users', [UserController, 'store'])
+    router.put('/users/:id', [UserController, 'update'])
+    router.delete('/users/:id', [UserController, 'destroy'])
+  })
+}

package/src/templates/shared/.env

@@ -0,0 +1,14 @@
+APP_ENV=local
+APP_KEY=__APP_KEY__
+APP_DEBUG=true
+APP_URL=http://localhost:3000
+APP_PORT=3000
+
+DB_HOST=127.0.0.1
+DB_PORT=5432
+DB_USER=liva
+DB_PASSWORD=password1234
+DB_DATABASE=__DB_NAME__
+
+SESSION_SECRET=__APP_KEY__
+SESSION_COOKIE_NAME=session

package/src/templates/shared/app/controllers/controller.ts

@@ -0,0 +1,15 @@
+import type { Context } from '@strav/http'
+
+export abstract class Controller {
+  protected async respond<T>(ctx: Context, data: T, status = 200) {
+    return ctx.json(data, status)
+  }
+
+  protected async error(ctx: Context, message: string, status = 400) {
+    return ctx.json({ error: message }, status)
+  }
+
+  protected async notFound(ctx: Context, message = 'Not found') {
+    return ctx.json({ error: message }, 404)
+  }
+}

package/src/templates/shared/app/models/user.ts

@@ -0,0 +1,30 @@
+import { Model, column } from '@strav/database'
+
+export default class User extends Model {
+  @column({ isPrimary: true })
+  declare id: string
+
+  @column()
+  declare email: string
+
+  @column()
+  declare name: string
+
+  @column()
+  declare password_hash: string
+
+  @column()
+  declare email_verified_at: Date | null
+
+  @column()
+  declare remember_token: string | null
+
+  @column()
+  declare created_at: Date
+
+  @column()
+  declare updated_at: Date
+
+  @column()
+  declare deleted_at: Date | null
+}

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

@@ -0,0 +1,10 @@
+import { env } from '@strav/kernel'
+
+export default {
+  name: '__PROJECT_NAME__',
+  env: env('APP_ENV', 'production'),
+  debug: env.bool('APP_DEBUG', false),
+  url: env('APP_URL', 'http://localhost:3000'),
+  port: env.int('APP_PORT', 3000),
+  key: env('APP_KEY'),
+}

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

@@ -0,0 +1,9 @@
+import { env } from '@strav/kernel'
+
+export default {
+  host: env('DB_HOST', 'localhost'),
+  port: env.int('DB_PORT', 5432),
+  database: env('DB_DATABASE', '__DB_NAME__'),
+  username: env('DB_USER', 'postgres'),
+  password: env('DB_PASSWORD', ''),
+}

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

@@ -0,0 +1,5 @@
+import { env } from '@strav/kernel'
+
+export default {
+  key: env('APP_KEY'),
+}