@strav/spring 0.4.31 → 1.0.0-alpha.29

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,31 @@
+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'
+
+/**
+ * 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/view.ts` →
+ * `config('view.*')`, and so on. To add a new config slot, drop a file
+ * with a `default export` into `config/`. No edits to this list
+ * required.
+ *
+ * `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 async function providers(): Promise<ServiceProvider[]> {
+  return [
+    await ConfigProvider.fromDirectory('config'),
+    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,31 @@
 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',
+
+  // CSS bundling — `view:build` reads each input, walks `@import`s
+  // via Bun's CSS bundler, and writes to `outputDir`. The layout's
+  // `@css` directive emits the matching `<link rel="stylesheet">`.
+  css: {
+    inputs: ['resources/css/app.css'],
+    outputDir: 'public/assets',
+    linkPath: 'app.css',
+  },
+
+  // Asset versioning for `@asset` / `@css`. `publicDir` mirrors the
+  // layout under `/assets/...` so `app.css` resolves to a file at
+  // `public/assets/app.css` and a URL at `/assets/app.css`.
+  // Versioning is mtime-based by default; drop a
+  // `public/assets/manifest.json` to switch to fingerprinted
+  // filenames.
+  assets: {
+    publicDir: 'public/assets',
+    prefix: '/assets/',
+  },
+
   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,32 @@
+/* Spring `--web` starter — vanilla CSS that pairs with the Tailwind
+ * CDN loaded by `resources/views/layouts/app.strav`. Everything below
+ * is what Tailwind doesn't cover: the body background grid, the
+ * fluid hero type, and the global text/background colour reset.
+ *
+ * Swap for your own stylesheet of choice — point the layout's `@css`
+ * directive (resolved via `config.view.css`) at whatever you build.
+ */
+
+body {
+  background-color: #ffffff;
+  color: #000000;
+}
+
+/* Faint red grid overlay across the page. The 40px cells line up
+ * with the Tailwind 8/12-step spacing rhythm. */
+.bg-grid-precision {
+  background-size: 40px 40px;
+  background-image:
+    linear-gradient(to right,  rgba(255, 68, 51, 0.05) 1px, transparent 1px),
+    linear-gradient(to bottom, rgba(255, 68, 51, 0.05) 1px, transparent 1px);
+}
+
+/* Fluid display type for the hero — clamps between 3rem at narrow
+ * widths and 5.5rem at wide. Letter-spacing tightens at scale; the
+ * line-height is sub-1 so the two stacked lines hug. */
+.text-huge {
+  font-size: clamp(3rem, 8vw, 5.5rem);
+  line-height: 0.95;
+  letter-spacing: -0.04em;
+  font-weight: 800;
+}

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,46 @@
+<!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>
+  <script src="https://cdn.tailwindcss.com?plugins=forms,container-queries"></script>
+  <script>
+    tailwind.config = {
+      theme: {
+        extend: {
+          colors: {
+            primary: '#ff4433',
+            'on-surface': '#000000',
+            'on-surface-variant': '#666666',
+            outline: '#e5e5e5',
+            surface: '#ffffff',
+          },
+          fontFamily: {
+            sans: ['system-ui', '-apple-system', 'sans-serif'],
+            mono: ['ui-monospace', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'monospace'],
+          },
+        },
+      },
+    }
+  </script>
+  @css
+</head>
+<body class="min-h-screen flex flex-col selection:bg-primary selection:text-white bg-grid-precision">
+  <main class="flex-grow w-full mx-auto px-6 md:px-12 py-16 md:py-24 max-w-[800px]">
+    @yield('content')
+  </main>
+
+  <footer class="border-t border-black bg-white py-12 px-6 md:px-12 mt-auto">
+    <div class="max-w-[1400px] mx-auto flex flex-col md:flex-row justify-between items-center gap-8">
+      <div class="text-[10px] font-mono tracking-[0.3em] uppercase text-on-surface-variant">
+        © 2026 Strav
+      </div>
+      <div class="flex gap-12">
+        <a class="text-sm font-bold uppercase tracking-tighter hover:text-primary transition-colors" href="https://strav.dev">Docs</a>
+        <a class="text-sm font-bold uppercase tracking-tighter hover:text-primary transition-colors" href="https://github.com/strav/strav">Repository</a>
+      </div>
+    </div>
+  </footer>
+</body>
+</html>

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

@@ -0,0 +1,47 @@
+@extends('layouts.app')
+
+@set('title', '{{projectName}}')
+
+@section('content')
+  {{-- Hero --}}
+  <div class="mb-24">
+    <div class="inline-block border border-primary px-3 py-1 mb-8 text-[11px] font-mono tracking-widest uppercase text-primary">
+      V1.0.0-AI • Local Environment Active
+    </div>
+    <h1 class="text-huge mb-8">
+      The Fast Path for<br>
+      <span class="text-primary">{{projectName}}</span>
+    </h1>
+    <p class="text-xl md:text-2xl text-on-surface-variant max-w-2xl leading-tight font-medium">
+      An industrial-grade architecture for modern web applications. Engineered for speed and the uncompromising developer.
+    </p>
+  </div>
+
+  {{-- Edit these to get started --}}
+  <div class="grid gap-0 border border-black bg-white">
+    <div class="p-8 md:p-12">
+      <h2 class="text-3xl font-bold tracking-tighter mb-8 italic">Edit these to get started</h2>
+
+      <div class="flex flex-col divide-y divide-black/10 border-t border-black/10">
+        <div class="py-4 flex flex-col md:flex-row md:justify-between md:items-center gap-2 group">
+          <code class="font-mono text-primary group-hover:underline">resources/views/pages/index.strav</code>
+          <span class="text-[10px] font-mono uppercase text-on-surface-variant">This Page</span>
+        </div>
+        <div class="py-4 flex flex-col md:flex-row md:justify-between md:items-center gap-2">
+          <code class="font-mono text-black">resources/views/layouts/app.strav</code>
+          <span class="text-[10px] font-mono uppercase text-on-surface-variant">Layout Shell</span>
+        </div>
+        <div class="py-4 flex flex-col md:flex-row md:justify-between md:items-center gap-2">
+          <code class="font-mono text-black">resources/css/app.css</code>
+          <span class="text-[10px] font-mono uppercase text-on-surface-variant">Styles</span>
+        </div>
+      </div>
+
+      <div class="mt-12 flex flex-wrap gap-4">
+        <span class="text-[10px] font-mono font-bold px-2 py-1 border border-black">BUN</span>
+        <span class="text-[10px] font-mono font-bold px-2 py-1 border border-black">TYPESCRIPT</span>
+        <span class="text-[10px] font-mono font-bold px-2 py-1 border border-primary text-primary">POSTGRESQL</span>
+      </div>
+    </div>
+  </div>
+@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.29'

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()