@strav/spring 0.4.30 → 1.0.0-alpha.28

package/src/templates/shared/tests/feature/healthz.test.ts.tt

@@ -0,0 +1,19 @@
+import { describe, expect, test } from 'bun:test'
+import { HttpKernel } from '@strav/http'
+import { createApp } from '../../bootstrap/app.ts'
+import { providers } from '../../bootstrap/providers.ts'
+
+describe('GET /healthz', () => {
+  test('returns 200 { ok: true }', async () => {
+    const app = createApp()
+    app.useProviders(providers())
+    await app.start()
+
+    const kernel = app.resolve(HttpKernel)
+    const res = await kernel.handle(new Request('http://localhost/healthz'))
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ ok: true })
+
+    await app.shutdown()
+  })
+})

package/src/templates/shared/tsconfig.json

@@ -1,20 +1,30 @@
 {
+  "$schema": "https://json.schemastore.org/tsconfig",
   "compilerOptions": {
-    "strict": true,
-    "target": "ES2022",
+    "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "lib": ["ESNext"],
+    "types": ["bun"],
+
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+
     "allowImportingTsExtensions": true,
-    "noEmit": true,
-    "composite": false,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
     "skipLibCheck": true,
-    "allowSyntheticDefaultImports": true,
     "forceConsistentCasingInFileNames": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "useDefineForClassFields": false,
-    "types": ["bun-types"]
+
+    "noEmit": true
   },
   "include": ["**/*.ts"],
-  "exclude": ["node_modules", "dist"]
-}
+  "exclude": ["node_modules", "storage"]
+}

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

@@ -0,0 +1,42 @@
+# {{projectName}}
+
+A Strav 1.0 full-stack application scaffolded by `@strav/spring --web`.
+
+## Run
+
+```bash
+bun install
+bun strav view:build     # compile resources/ts/islands/ into public/assets/islands/
+bun strav serve          # HTTP server on http://localhost:3000
+```
+
+Open `http://localhost:3000/` — the page at `resources/views/pages/index.strav`
+renders, with the Vue 3 island defined in `resources/ts/islands/counter.vue`
+hydrating on load.
+
+## Layout
+
+This project follows the layout in `spec/directory-structure.md`:
+
+- `app/` — application code (`http/`, `models/`, `providers/`, …).
+- `bin/strav.ts` — single dispatcher; `bun strav <command>` invokes it.
+- `bootstrap/{app,providers}.ts` — Application factory + provider list.
+- `config/` — typed config; one file per package, each exports `default`.
+- `routes/{api,web,console}.ts` — declared route entry points.
+- `resources/`
+  - `views/pages/**/*.strav` — auto-routed pages via `@strav/view`.
+  - `views/layouts/`, `views/components/`, `views/errors/` — the rest of the templates.
+  - `ts/islands/*.vue` + `setup.ts` — Vue 3 islands. Bundled into one
+    `islands.js` by `bun strav view:build`.
+  - `css/app.css` — base stylesheet (plain CSS; swap in Tailwind /
+    vanilla-extract / your choice).
+- `public/` — static assets served by `routes/web.ts`. `public/assets/`
+  receives the islands bundle output.
+- `tests/feature/` — HTTP-level integration tests.
+- `tests/browser/` — Playwright-driven (you install Playwright when you need it).
+
+## Adding more packages
+
+The scaffolded app starts with `@strav/{kernel,http,view,cli}`. Add
+`@strav/database`, `@strav/auth`, `@strav/queue`, `@strav/broadcast` (and
+their config + provider entries in `bootstrap/providers.ts`) as you need them.

package/src/templates/web/_dot_gitignore

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

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

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

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

@@ -0,0 +1,34 @@
+import { HttpConsoleProvider, HttpProvider } from '@strav/http'
+import { ConfigProvider, LoggerProvider, type ServiceProvider } from '@strav/kernel'
+import { ViewConsoleProvider, ViewProvider } from '@strav/view'
+import { AppProvider } from '../app/providers/app_provider.ts'
+import appConfig from '../config/app.ts'
+import httpConfig from '../config/http.ts'
+import loggerConfig from '../config/logger.ts'
+import viewConfig from '../config/view.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.
+ *
+ * `ViewProvider` discovers `.strav` files under `resources/views/pages/`
+ * and registers a route for each at boot. `ViewConsoleProvider` adds the
+ * `view:build` / `view:cache` / `view:clear` commands.
+ */
+export function providers(): ServiceProvider[] {
+  return [
+    new ConfigProvider({
+      app: appConfig,
+      http: httpConfig,
+      logger: loggerConfig,
+      view: viewConfig,
+    }),
+    new LoggerProvider(),
+    new HttpProvider(),
+    new HttpConsoleProvider(),
+    new ViewProvider(),
+    new ViewConsoleProvider(),
+    new AppProvider(),
+  ]
+}

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

@@ -1,11 +1,20 @@
 import { env } from '@strav/kernel'
 
 export default {
-  host: env('HOST', '0.0.0.0'),
-  port: env.int('PORT', 3000),
-  domain: env('DOMAIN', 'localhost'),
-  public: './public',
-
-  // Full application URL (optional - will be constructed from host/port/domain if not set)
-  app_url: env('APP_URL'),
-}
+  /**
+   * Expose stack traces in error responses. Convenient locally; never
+   * leave this on in production.
+   */
+  exposeStackTrace: env('APP_ENV', 'local') !== 'production',
+  /**
+   * Static-asset root. GET / HEAD requests that no route handles fall
+   * through to a file lookup under this directory before the 404 path
+   * runs. Path traversal (`..`) is rejected by the kernel.
+   *
+   * `bun strav view:build` writes the islands bundle into
+   * `public/assets/islands/` — make sure your stylesheet build does the
+   * same so the layout's `<link rel="stylesheet" href="/assets/app.css">`
+   * resolves.
+   */
+  publicDir: 'public',
+}

package/src/templates/web/config/view.ts

@@ -1,12 +1,12 @@
 import { env } from '@strav/kernel'
+import type { ViewConfig } from '@strav/view'
 
 export default {
   directory: 'resources/views',
-  cache: env.bool('VIEW_CACHE', true),
-  assets: ['css/app.css', 'builds/islands.js'],
+  cache: env('APP_ENV', 'local') === 'production',
+  islandsDir: 'resources/ts/islands',
+  islandsOut: 'public/assets/islands',
   pages: {
-    directory: 'pages',
-    enabled: true,
-    indexFile: 'index.strav'
-  }
-}
+    autoRoute: true,
+  },
+} satisfies ViewConfig

package/src/templates/web/package.json.tt

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

package/src/templates/web/resources/css/app.css

@@ -0,0 +1,41 @@
+/* Bare-bones starter styles. Swap for Tailwind, vanilla-extract, or your
+ * stylesheet of choice — just point the <link rel="stylesheet"> in
+ * `resources/views/layouts/app.strav` at the right built output. */
+
+:root {
+  --bg: #ffffff;
+  --fg: #111111;
+  --accent: #3b82f6;
+  font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+  line-height: 1.5;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0f0f10;
+    --fg: #f5f5f5;
+  }
+}
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+}
+
+main {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 2rem 1.25rem;
+}
+
+button {
+  cursor: pointer;
+  border-radius: 0.375rem;
+  border: 1px solid var(--accent);
+  background: var(--accent);
+  color: #fff;
+  padding: 0.5rem 1rem;
+  font: inherit;
+}

package/src/templates/web/resources/ts/islands/counter.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = defineProps<{ start?: number }>()
+// biome-ignore lint/correctness/noUnusedVariables: bound by the <template> below
+const count = ref(props.start ?? 0)
+</script>
+
+<template>
+  <button @click="count++">Count is {{ count }}</button>
+</template>

package/src/templates/web/resources/ts/islands/setup.ts

@@ -0,0 +1,13 @@
+import type { App } from 'vue'
+
+/**
+ * Shared setup for every Vue island on the page. Runs once on the single
+ * `createApp(Root)` that the `@strav/view` islands bundler produces, so
+ * plugins (Pinia, vue-router, i18n, …) and global directives go here.
+ *
+ * Export a default function. The bundler invokes it with the app instance.
+ */
+export default (app: App): void => {
+  // Example: app.use(createPinia())
+  void app
+}

package/src/templates/web/resources/views/errors/404.strav

@@ -0,0 +1,8 @@
+@extends('layouts.app')
+
+@set('title', 'Not found')
+
+@section('content')
+  <h1>404 — Not found</h1>
+  <p>The page you asked for doesn't exist.</p>
+@endsection

package/src/templates/web/resources/views/errors/500.strav

@@ -0,0 +1,8 @@
+@extends('layouts.app')
+
+@set('title', 'Server error')
+
+@section('content')
+  <h1>500 — Something went wrong</h1>
+  <p>An unexpected error occurred. Please try again shortly.</p>
+@endsection

package/src/templates/web/resources/views/layouts/app.strav.tt

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>@yield('title', '{{projectName}}')</title>
+  <link rel="stylesheet" href="/assets/app.css" />
+</head>
+<body>
+  <main>
+    @yield('content')
+  </main>
+  <script type="module" src="/assets/islands/islands.js" defer></script>
+</body>
+</html>

package/src/templates/web/resources/views/pages/index.strav.tt

@@ -0,0 +1,12 @@
+@extends('layouts.app')
+
+@set('title', '{{projectName}}')
+
+@section('content')
+  <h1>Welcome to {{projectName}}</h1>
+  <p>You're looking at <code>resources/views/pages/index.strav</code>.</p>
+
+  <p>The button below is a Vue 3 island — see <code>resources/ts/islands/counter.vue</code>. Run <code>bun strav view:build</code> to compile islands into <code>public/assets/islands/</code>.</p>
+
+  @island('Counter', { start: 0 })
+@endsection

package/src/templates/web/routes/broadcast.ts

@@ -0,0 +1,9 @@
+/**
+ * SSE / broadcast channel declarations. Empty until the app installs
+ * `@strav/broadcast` and declares its first channel — at which point
+ * a `Broadcaster` instance + per-channel authorize callbacks live here.
+ *
+ * Spec anchor (`spec/directory-structure.md` lists `routes/broadcast.ts`)
+ * but slice B doesn't ship the `@strav/broadcast` integration.
+ */
+export {}

package/src/templates/web/routes/web.ts

@@ -0,0 +1,19 @@
+import type { Router } from '@strav/http'
+
+/**
+ * HTML / browser-facing routes that need to be hand-declared (login forms,
+ * dynamic redirects, sitemap.xml — anything that can't be a static
+ * `.strav` page).
+ *
+ * Two things you may NOT need to wire here:
+ *
+ *   1. **Auto-routed pages** — `@strav/view` registers a GET route for
+ *      every `.strav` file under `resources/views/pages/` automatically.
+ *   2. **Static assets** — set `publicDir: 'public'` in `config/http.ts`
+ *      (already wired in the scaffolded config) and the HTTP kernel will
+ *      serve files from `public/` for any unrouted GET / HEAD request.
+ *      Path traversal is rejected; routed paths still win over disk.
+ */
+export function registerWebRoutes(_router: Router): void {
+  // Hand-declared web routes go here.
+}

package/src/version.ts

@@ -0,0 +1,9 @@
+/**
+ * Framework version that scaffolded apps pin to in their generated
+ * `package.json`. Bumped manually at release; see the template-strategy ADR.
+ *
+ * Spring's own `package.json` version tracks the workspace alpha for now,
+ * but this constant is what *generated apps* depend on — keep them in sync
+ * on each release until spring formally cuts independent versions.
+ */
+export const STRAV_VERSION = '^1.0.0-alpha.28'

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

@@ -1,15 +0,0 @@
-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/api/app/controllers/user_controller.ts

@@ -1,69 +0,0 @@
-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/database.ts

@@ -1,9 +0,0 @@
-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/api/config/http.ts

@@ -1,17 +0,0 @@
-import { env } from '@strav/kernel'
-
-export default {
-  host: env('HOST', '0.0.0.0'),
-  port: env.int('PORT', 3000),
-  domain: env('DOMAIN', 'localhost'),
-  public: './public',
-
-  // Full application URL (optional - will be constructed from host/port/domain if not set)
-  app_url: env('APP_URL'),
-
-  cors: {
-    enabled: true,
-    origin: ['http://localhost:3000', 'http://localhost:5173'],
-    credentials: true,
-  },
-}

package/src/templates/api/database/factories/user_factory.ts

@@ -1,11 +0,0 @@
-import { Factory } from '@strav/testing'
-import User from '../../app/models/user.ts'
-
-export const UserFactory = Factory.define(User, (seq) => ({
-  id: crypto.randomUUID(),
-  email: `user-${seq}@example.com`,
-  name: `User ${seq}`,
-  password_hash: '$2b$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi', // password
-  email_verified_at: new Date(),
-  remember_token: null,
-}))

package/src/templates/api/database/schemas/user.ts

@@ -1,13 +0,0 @@
-import { defineSchema, t, Archetype } from '@strav/database'
-
-export default defineSchema('user', {
-  archetype: Archetype.Entity,
-  fields: {
-    id: t.uuid().primaryKey(),
-    email: t.string().email().unique().required(),
-    name: t.string().required(),
-    password_hash: t.string().required(),
-    email_verified_at: t.timestamp().nullable(),
-    remember_token: t.string(100).nullable(),
-  },
-})

package/src/templates/api/database/seeders/database_seeder.ts

@@ -1,8 +0,0 @@
-import { Seeder } from '@strav/database'
-import UserSeeder from './user_seeder.ts'
-
-export default class DatabaseSeeder extends Seeder {
-  async run(): Promise<void> {
-    await this.call(UserSeeder)
-  }
-}

package/src/templates/api/database/seeders/user_seeder.ts

@@ -1,15 +0,0 @@
-import { Seeder } from '@strav/database'
-import { UserFactory } from '../factories/user_factory.ts'
-
-export default class UserSeeder extends Seeder {
-  async run(): Promise<void> {
-    // Create admin user
-    await UserFactory.create({
-      email: 'admin@example.com',
-      name: 'Admin User',
-    })
-
-    // Create test users
-    await UserFactory.createMany(10)
-  }
-}

package/src/templates/api/index.ts

@@ -1,11 +0,0 @@
-import 'reflect-metadata'
-import { app } from '@strav/kernel'
-import { providers } from './start/providers'
-
-// Register service providers
-app.useProviders(providers)
-
-// Load routes
-await import('./start/routes')
-
-await app.start()

package/src/templates/api/package.json

@@ -1,24 +0,0 @@
-{
-  "name": "__PROJECT_NAME__",
-  "version": "0.1.0",
-  "type": "module",
-  "private": true,
-  "scripts": {
-    "dev": "bun --hot index.ts",
-    "start": "bun index.ts",
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@strav/kernel": "__STRAV_VERSION__",
-    "@strav/http": "__STRAV_VERSION__",
-    "@strav/database": "__STRAV_VERSION__",
-    "@strav/cli": "__STRAV_VERSION__",
-    "reflect-metadata": "^0.2.2"
-  },
-  "devDependencies": {
-    "@types/bun": "latest",
-    "@strav/testing": "__STRAV_VERSION__",
-    "typescript": "^5.9.3"
-  }
-}

package/src/templates/api/start/providers.ts

@@ -1,10 +0,0 @@
-import { DatabaseProvider } from "@strav/database"
-import { HttpProvider } from "@strav/http"
-import { ConfigProvider, EncryptionProvider, ServiceProvider } from "@strav/kernel"
-
-export const providers: ServiceProvider[] = [
-  new ConfigProvider(),
-  new HttpProvider(),
-  new DatabaseProvider(),
-  new EncryptionProvider(),
-]