create-zerotal 1.0.0

package/templates/api/app/controllers/AuthController.ts

@@ -0,0 +1,69 @@
+import type { HttpContext } from '@zerotal/core';
+import { Hash } from '@zerotal/auth';
+import { User } from '../models/User.ts';
+
+export class AuthController {
+  /** POST /register */
+  async register(http: HttpContext): Promise<void> {
+    const body = await http.request.json() as Record<string, string>;
+    const { name, email, password } = body;
+
+    if (!name || !email || !password) {
+      http.response = Response.json({ message: 'name, email, and password are required.' }, { status: 422 });
+      return;
+    }
+
+    const exists = await User.query().where('email', email).first();
+    if (exists) {
+      http.response = Response.json({ message: 'Email already in use.' }, { status: 422 });
+      return;
+    }
+
+    const user = await User.create({
+      name,
+      email,
+      password: await Hash.make(password),
+      role: 'user',
+    } as Partial<User>);
+
+    http.session?.set('user_id', user.id);
+    http.response = Response.json({ data: { id: user.id, name: user.name, email: user.email } }, { status: 201 });
+  }
+
+  /** POST /login */
+  async login(http: HttpContext): Promise<void> {
+    const body     = await http.request.json() as Record<string, string>;
+    const email    = body.email?.trim() ?? '';
+    const password = body.password ?? '';
+
+    if (!email || !password) {
+      http.response = Response.json({ message: 'email and password are required.' }, { status: 422 });
+      return;
+    }
+
+    const user = await User.query().where('email', email).first();
+    if (!user || !(await Hash.check(password, user.password))) {
+      http.response = Response.json({ message: 'Invalid credentials.' }, { status: 401 });
+      return;
+    }
+
+    http.session?.set('user_id', user.id);
+    http.response = Response.json({ data: { id: user.id, name: user.name, email: user.email } });
+  }
+
+  /** POST /logout */
+  async logout(http: HttpContext): Promise<void> {
+    http.session?.forget('user_id');
+    http.response = Response.json({ message: 'Logged out.' });
+  }
+
+  /** GET /me */
+  async me(http: HttpContext): Promise<void> {
+    if (!http.user) {
+      http.response = Response.json({ message: 'Unauthenticated.' }, { status: 401 });
+      return;
+    }
+    const user = await User.findOrFail(http.user.id as number);
+    http.response = Response.json({ data: { id: user.id, name: user.name, email: user.email } });
+  }
+}

package/templates/api/app/controllers/WelcomeController.ts

@@ -0,0 +1,10 @@
+import type { HttpContext } from '@zerotal/core';
+
+export class WelcomeController {
+  async index(http: HttpContext): Promise<void> {
+    http.json({
+      message: 'Welcome to {{name}}!',
+      docs:    'https://zerotal.dev/docs',
+    });
+  }
+}

package/templates/api/app/middleware/RequireAuth.ts

@@ -0,0 +1,10 @@
+import type { HttpContext, Pipe, NextFn } from '@zerotal/core';
+
+export class RequireAuth implements Pipe<HttpContext> {
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    if (!http.user) {
+      return Response.json({ message: 'Unauthenticated.' }, { status: 401 });
+    }
+    return next();
+  }
+}

package/templates/api/app/models/User.ts

@@ -0,0 +1,16 @@
+import { BaseModel, column, table } from '@zerotal/orm';
+
+@table('users')
+export class User extends BaseModel {
+  // Models guard every attribute by default. List the columns that may be
+  // mass-assigned from user input — note `role` is deliberately excluded so a
+  // request body cannot escalate privileges via `User.create(ctx.body())`.
+  static override fillable = ['name', 'email', 'password'];
+
+  static override hidden = ['password'];
+
+  @column({ type: 'string' }) name!:     string;
+  @column({ type: 'string' }) email!:    string;
+  @column({ type: 'string' }) password!: string;
+  @column({ type: 'string' }) role!:     string;
+}

package/templates/api/bootstrap/app.ts

@@ -0,0 +1,19 @@
+import { Application } from '@zerotal/core';
+import { DatabaseProvider } from '@zerotal/orm';
+import { SessionProvider } from '@zerotal/session';
+import { AuthProvider } from '@zerotal/auth';
+import { NotificationProvider } from '@zerotal/notifications';
+import { QueueProvider } from '@zerotal/queue';
+import { LogProvider } from '@zerotal/core/logger';
+
+export default Application.create({
+  providers: [
+    DatabaseProvider,
+    SessionProvider,
+    AuthProvider,
+    NotificationProvider,
+    QueueProvider,
+    LogProvider,
+  ],
+})
+  .routing({ web: `${import.meta.dir}/../routes/index.ts` });

package/templates/api/config/app.ts

@@ -0,0 +1,8 @@
+import { env } from '@zerotal/core';
+
+export default {
+  name: '{{name}}',
+  env:  env('APP_ENV', 'console'),
+  key:  env('APP_KEY', ''),
+  url:  env('APP_URL', 'http://localhost:3000'),
+};

package/templates/api/config/database.ts

@@ -0,0 +1,6 @@
+import { env } from '@zerotal/core';
+import { DatabaseConfig } from '@zerotal/orm';
+
+export default DatabaseConfig({
+  url: env('DATABASE_URL', '{{db_url}}'),
+});

package/templates/api/config/notifications.ts

@@ -0,0 +1,13 @@
+import { env } from '@zerotal/core';
+import { NotificationConfig } from '@zerotal/notifications';
+
+export default NotificationConfig({
+  // The mail channel — delivery is via the configured driver (log/smtp/resend).
+  mail: {
+    driver: env('MAIL_DRIVER', 'log') as 'log' | 'smtp' | 'resend',
+    from: {
+      address: env('MAIL_FROM_ADDRESS', 'noreply@{{name}}.local'),
+      name:    env('MAIL_FROM_NAME',    '{{name}}'),
+    },
+  },
+});

package/templates/api/config/queue.ts

@@ -0,0 +1,6 @@
+import { env } from '@zerotal/core';
+
+export default {
+  driver:     env('QUEUE_DRIVER', 'sync'),
+  connection: env('DATABASE_URL', '{{db_url}}'),
+};

package/templates/api/config/session.ts

@@ -0,0 +1,10 @@
+import { env } from '@zerotal/core';
+import { SessionConfig } from '@zerotal/session';
+
+export default SessionConfig({
+  driver:   env('SESSION_DRIVER', 'cookie') as 'cookie' | 'redis',
+  cookie:   env('SESSION_NAME',   'session'),
+  secret:   env('SESSION_SECRET') ?? env('APP_KEY', ''),
+  lifetime: env('SESSION_TTL',    7200),
+  secure:   env('APP_ENV') === 'production',
+});

package/templates/api/database/migrations/0001_create_users_table.ts

@@ -0,0 +1,18 @@
+import { Migration, Schema } from '@zerotal/orm';
+
+export default class CreateUsersTable extends Migration {
+  async up(): Promise<void> {
+    await Schema.create('users', (t) => {
+      t.increments('id');
+      t.string('name');
+      t.string('email').unique();
+      t.string('password');
+      t.string('role').default('user');
+      t.timestamps();
+    });
+  }
+
+  async down(): Promise<void> {
+    await Schema.drop('users');
+  }
+}

package/templates/api/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "zt": "bun zt.ts",
+    "dev": "bun zt.ts serve --dev",
+    "start": "bun zt.ts serve",
+    "test": "bun zt.ts test"
+  },
+  "dependencies": {
+    "@zerotal/notifications": "{{zerotal_version}}",
+    "zerotal": "{{zerotal_version}}"
+  }
+}

package/templates/api/routes/index.ts

@@ -0,0 +1,13 @@
+import { Router } from '@zerotal/core';
+import { WelcomeController } from '../app/controllers/WelcomeController.ts';
+import { AuthController }    from '../app/controllers/AuthController.ts';
+import { RequireAuth }       from '../app/middleware/RequireAuth.ts';
+
+// Public
+Router.get('/',          WelcomeController, 'index');
+Router.post('/register', AuthController,    'register');
+Router.post('/login',    AuthController,    'login');
+Router.post('/logout',   AuthController,    'logout');
+
+// Protected
+Router.get('/me', AuthController, 'me', [RequireAuth]);

package/templates/api/tests/README.md

@@ -0,0 +1,77 @@
+# Tests
+
+## Running tests
+
+```bash
+bun zt test          # run all tests (sets APP_ENV=test, auto-wires the DB)
+bun zt test --watch  # watch mode
+bun zt test --bail   # stop at the first failure
+```
+
+## How a test is put together
+
+`helpers.ts` exports `createApp()`, which boots this application configured for
+tests — in-memory database, synchronous queue, a known session secret. Every test
+file uses it, so adding a provider to the app means editing one place rather than
+every suite.
+
+`auth.test.ts` is a complete worked example. The shape it uses:
+
+```ts
+import { describe, it, beforeAll, afterAll } from 'bun:test';
+import { migrateDatabase, refreshDatabase, assertDatabaseHas } from '@zerotal/testing';
+import type { TestApp } from '@zerotal/testing';
+import '../routes/index.ts';
+import { createApp } from './helpers.ts';
+
+let app: TestApp;
+
+beforeAll(async () => {
+  app = await createApp();
+  await migrateDatabase(); // build the schema from database/migrations
+});
+
+afterAll(() => app.close());
+
+describe('GET /posts', () => {
+  refreshDatabase(); // each test runs in a transaction that rolls back
+
+  it('lists posts', async () => {
+    const res = await app.get('/posts');
+
+    res.assertOk();
+    res.assertJsonCount(0, 'data');
+  });
+});
+```
+
+Build the schema with `migrateDatabase()` rather than hand-written `CREATE TABLE`
+statements. A second definition of your tables drifts from the real one, and you
+find out when something fails for a reason unrelated to the change you made.
+
+## Useful assertions
+
+```ts
+res.assertOk();                          // and assertCreated, assertNotFound, …
+res.assertJsonPath('data.0.title', 'Hi');
+res.assertInvalid('email');              // 422 errors, or errors flashed to the session
+res.assertAuthenticatedAs(user);
+res.assertSessionHas('cart_id');
+await assertDatabaseHas('posts', { slug: 'hello' });
+```
+
+When a test fails on an unexpected `500`, ask for the exception instead of
+guessing from the rendered page:
+
+```ts
+const res = await app.withoutExceptionHandling().get('/checkout');
+console.log(res.exception());
+```
+
+## Generators
+
+```bash
+bun zt make:test PostTest         # tests/feature/PostTest.ts
+bun zt make:test SlugTest --unit  # tests/unit/SlugTest.ts
+bun zt make:factory User          # database/factories/UserFactory.ts
+```

package/templates/api/tests/auth.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, beforeAll, afterAll } from 'bun:test';
+import {
+  migrateDatabase,
+  refreshDatabase,
+  assertDatabaseHas,
+  assertDatabaseMissing,
+  type TestApp,
+} from '@zerotal/testing';
+import '../routes/index.ts';
+import { createApp } from './helpers.ts';
+
+let app: TestApp;
+
+beforeAll(async () => {
+  app = await createApp();
+  // Build the schema from the same migrations that ship, rather than from a
+  // second copy of the tables written by hand — the two always drift.
+  await migrateDatabase();
+});
+
+afterAll(() => app.close());
+
+describe('registration', () => {
+  // Every test below runs in a transaction that rolls back, so they each start
+  // from the same empty database and can be read in any order.
+  refreshDatabase();
+
+  it('creates a user and signs them in', async () => {
+    const res = await app.asJson().post('/register', {
+      name: 'Ada Lovelace',
+      email: 'ada@example.com',
+      password: 'correct-horse',
+    });
+
+    res.assertCreated();
+    res.assertJsonPath('data.email', 'ada@example.com');
+    await assertDatabaseHas('users', { email: 'ada@example.com' });
+  });
+
+  it('never stores the password as given', async () => {
+    await app.asJson().post('/register', {
+      name: 'Ada',
+      email: 'ada@example.com',
+      password: 'correct-horse',
+    });
+
+    await assertDatabaseMissing('users', { password: 'correct-horse' });
+  });
+
+  it('rejects an incomplete payload', async () => {
+    const res = await app.asJson().post('/register', { email: 'ada@example.com' });
+
+    res.assertUnprocessable();
+    await assertDatabaseMissing('users', { email: 'ada@example.com' });
+  });
+
+  it('rejects a duplicate email', async () => {
+    const payload = { name: 'Ada', email: 'ada@example.com', password: 'secret' };
+    await app.asJson().post('/register', payload);
+
+    const res = await app.asJson().post('/register', payload);
+
+    res.assertUnprocessable();
+  });
+});
+
+describe('login', () => {
+  refreshDatabase();
+
+  it('signs a registered user in', async () => {
+    await app.asJson().post('/register', {
+      name: 'Ada',
+      email: 'ada@example.com',
+      password: 'correct-horse',
+    });
+
+    const res = await app.asJson().post('/login', {
+      email: 'ada@example.com',
+      password: 'correct-horse',
+    });
+
+    res.assertOk();
+    res.assertAuthenticated();
+  });
+
+  it('refuses a wrong password without saying which field was wrong', async () => {
+    await app.asJson().post('/register', {
+      name: 'Ada',
+      email: 'ada@example.com',
+      password: 'correct-horse',
+    });
+
+    const res = await app.asJson().post('/login', {
+      email: 'ada@example.com',
+      password: 'wrong',
+    });
+
+    res.assertUnauthorized();
+    res.assertGuest();
+  });
+
+  it('refuses an unknown email', async () => {
+    const res = await app.asJson().post('/login', {
+      email: 'nobody@example.com',
+      password: 'secret',
+    });
+
+    res.assertUnauthorized();
+  });
+});
+
+describe('GET /me', () => {
+  refreshDatabase();
+
+  it('turns a guest away', async () => {
+    const res = await app.actingAsGuest().asJson().get('/me');
+
+    res.assertUnauthorized();
+  });
+
+  it('returns the signed-in user', async () => {
+    const created = await app.asJson().post('/register', {
+      name: 'Ada Lovelace',
+      email: 'ada@example.com',
+      password: 'correct-horse',
+    });
+    const id = created.json<{ data: { id: number } }>().data.id;
+
+    const res = await app.actingAs({ id }).asJson().get('/me');
+
+    res.assertOk();
+    res.assertJsonPath('data.name', 'Ada Lovelace');
+  });
+});

package/templates/api/tests/helpers.ts

@@ -0,0 +1,36 @@
+import { Application } from '@zerotal/core';
+import { DatabaseProvider } from '@zerotal/orm';
+import { SessionProvider, AuthSessionMiddleware, CookieDriver } from '@zerotal/session';
+import { AuthProvider } from '@zerotal/auth';
+import { NotificationProvider } from '@zerotal/notifications';
+import { QueueProvider } from '@zerotal/queue';
+import { createTestApp, type TestApp } from '@zerotal/testing';
+import { User } from '../app/models/User.ts';
+
+export const TEST_SESSION_SECRET = 'test-secret';
+
+export function createApp(setup?: () => void): Promise<TestApp> {
+  const driver = new CookieDriver(TEST_SESSION_SECRET, 'session');
+
+  return createTestApp(
+    () =>
+      Application.create({ env: 'test' })
+        .register([DatabaseProvider, SessionProvider, AuthProvider, NotificationProvider, QueueProvider])
+        .use([
+          class extends AuthSessionMiddleware {
+            constructor() {
+              super(driver, (id) => User.find(id) as Promise<{ id: number } | null>);
+            }
+          },
+        ])
+        .useConfig({
+          database: { url: ':memory:' },
+          session:  { driver: 'cookie', secret: TEST_SESSION_SECRET, cookie: 'session', ttl: 7200 },
+          mail:     { driver: 'log', from: { address: 'no-reply@test', name: 'Test' },
+                      smtp: { host: 'localhost', port: 1025, secure: false, username: '', password: '' },
+                      resend: { apiKey: '' }, log: { channel: 'console' } },
+          queue:    { driver: 'sync', connection: ':memory:' },
+        }),
+    setup,
+  );
+}

package/templates/api/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "emitDecoratorMetadata": false,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", ".zerotal"]
+}

package/templates/api/zt.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env bun
+// zt.ts — Zerotal CLI entry point.
+// ─────────────────────────────────────────────────────────────────
+// Managed by the framework. All orchestration lives in @zerotal/core's
+// startZerotal(); this file just hands it the app's bootstrap module.
+//
+// Run commands with:  bun zt <command>
+//   bun zt serve [--port=3000] [--dev]   Start the HTTP server
+//   bun zt worker                        Start the background worker
+//   bun zt migrate                       Run database migrations
+//   bun zt test                          Run tests with the app booted
+//   bun zt list                          Show all available commands
+// ─────────────────────────────────────────────────────────────────
+import { startZerotal } from "zerotal";
+
+await startZerotal(() => import("./bootstrap/app"));

package/templates/flow/_env.example

@@ -0,0 +1,2 @@
+APP_ENV=development
+APP_KEY={{app_key}}

package/templates/flow/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.zerotal/
+*.sqlite
+.env
+public/app.js
+public/app.css

package/templates/flow/app/flow/layouts/app.tsx

@@ -0,0 +1,52 @@
+import { Layout, Link } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { asset } from "zerotal/assets";
+
+const NAV = [
+  { href: "/", label: "Home" },
+  { href: "/about", label: "About" },
+  { href: "/contact", label: "Contact" },
+];
+
+export class AppLayout extends Layout {
+  // Built by `bun zt serve` from resources/css/app.css (Tailwind) → public/app.css.
+  // A getter (not a static field) so asset() re-runs per request and picks up
+  // the latest ?v= cache-busting token after a dev rebuild.
+  static override get head(): string {
+    return `
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="${asset("/app.css")}">
+  `;
+  }
+
+  override render(slot: HtmlNode) {
+    // Flow adds `data-current` to the <Link> matching the current URL — style the active item with it.
+    const navLink =
+      "rounded-lg px-3 py-2 text-sm font-medium text-gray-600 transition hover:bg-gray-100 hover:text-gray-900 " +
+      "data-[current]:bg-indigo-50 data-[current]:text-indigo-700";
+
+    return (
+      <div class="min-h-screen bg-linear-to-b from-white via-white to-indigo-50 text-gray-900 antialiased">
+        <header class="sticky top-0 z-10 border-b border-gray-200/70 bg-white/80 backdrop-blur">
+          <nav class="mx-auto flex max-w-5xl items-center justify-between px-6 py-3">
+            {/* Brand opts out of the active style (current={false}) so it isn't highlighted on Home. */}
+            <Link href="/" current={false} class="flex items-center gap-2 font-bold tracking-tight">
+              <img src={asset("/zt.svg")} alt="" class="h-7 w-7" />
+              <span>Zerotal</span>
+            </Link>
+
+            <div class="flex items-center gap-1">
+              {NAV.map((item) => (
+                <Link href={item.href} hover class={navLink}>
+                  {item.label}
+                </Link>
+              ))}
+            </div>
+          </nav>
+        </header>
+
+        <main class="mx-auto max-w-3xl px-6 py-14">{slot}</main>
+      </div>
+    );
+  }
+}

package/templates/flow/app/flow/pages/about.tsx

@@ -0,0 +1,35 @@
+import { Component } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { AppLayout } from "../layouts/app";
+
+export class AboutPage extends Component {
+  static layout = AppLayout;
+  static title = "About";
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <section class="py-4">
+        <h1 class="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">About</h1>
+        <div class="mt-6 space-y-4 text-lg leading-relaxed text-gray-600">
+          <p>
+            This is an example app built with{" "}
+            <span class="font-medium text-gray-900">Zerotal</span> and its server-driven view
+            layer, <span class="font-medium text-gray-900">Flow</span>.
+          </p>
+          <p>
+            Each file under{" "}
+            <code class="rounded bg-gray-100 px-1.5 py-0.5 font-mono text-sm text-indigo-600">
+              app/flow/pages
+            </code>{" "}
+            becomes a route — this page lives in{" "}
+            <code class="rounded bg-gray-100 px-1.5 py-0.5 font-mono text-sm text-indigo-600">
+              about.tsx
+            </code>{" "}
+            and is served at <span class="font-medium text-gray-900">/about</span>. Navigation
+            between pages happens over a WebSocket, so it feels instant — no full reloads.
+          </p>
+        </div>
+      </section>
+    );
+  }
+}

package/templates/flow/app/flow/pages/contact.tsx

@@ -0,0 +1,47 @@
+import { Component } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { AppLayout } from "../layouts/app";
+
+export class ContactPage extends Component {
+  static layout = AppLayout;
+  static title = "Contact";
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <section class="py-4">
+        <h1 class="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">Contact</h1>
+        <p class="mt-4 text-lg leading-relaxed text-gray-600">
+          Have a question or feedback? We'd love to hear from you.
+        </p>
+
+        <div class="mt-6 rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+          <dl class="space-y-4 text-sm">
+            <div class="flex items-center justify-between gap-4">
+              <dt class="font-medium text-gray-500">Email</dt>
+              <dd>
+                <a href="mailto:hello@example.com" class="font-medium text-indigo-600 hover:text-indigo-700">
+                  hello@example.com
+                </a>
+              </dd>
+            </div>
+            <div class="flex items-center justify-between gap-4">
+              <dt class="font-medium text-gray-500">GitHub</dt>
+              <dd>
+                <a href="https://github.com" class="font-medium text-indigo-600 hover:text-indigo-700">
+                  github.com/your-org
+                </a>
+              </dd>
+            </div>
+          </dl>
+
+          <a
+            href="mailto:hello@example.com"
+            class="mt-6 inline-block w-full rounded-lg bg-indigo-600 px-4 py-2.5 text-center text-sm font-semibold text-white shadow-sm transition hover:bg-indigo-700"
+          >
+            Email us
+          </a>
+        </div>
+      </section>
+    );
+  }
+}