create-zerotal 1.0.4 → 1.1.0

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog — @zerotal/create-zerotal
+# Changelog — @zerotal/create-zerotal
 
 All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
@@ -8,6 +8,15 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-08-08
+
+### Fixed
+
+- **`StorageProvider` is registered in the scaffold.** `Storage.disk(...)` is used directly in the docs but the facade was unbound, so the first call failed with "Facade [storage] is not bound in the container". The error names the fix precisely; the cost is *when* it appears — a storage call sits behind auth, permission and upload checks, so simpler probes return 401/403 long before reaching it, and the first real upload is often in production. The provider falls back to `StorageConfig()` defaults and mounts no middleware when no disk is servable, so registering it unused costs nothing.
+- **A fresh scaffold can run `migrate`.** The flow, react and vue templates shipped `synchronize` on *and* baseline migrations, so boot-time sync created `users` from the model and the first `bun zt migrate` collided with it — on the very first command a new user types. Migrations are now the single source of truth in those templates, as they already were in `api`, and `bun zt migrate` is listed in the scaffold's next steps.
+- **The scaffolded test suite builds its schema.** With `synchronize` off, `createTestApp()` hands back a `:memory:` database with no tables; the smoke test now calls `migrateDatabase()`, which also means the schema under test is the schema that ships.
+- **Nullable model fields can be cleared.** The templates declared them `?: T` under `exactOptionalPropertyTypes: true`, which means "may be absent, but never `undefined`" — so assigning `undefined` to clear the field, which is the point of a nullable column, did not typecheck. They are now `?: T | undefined`.
+
 ## [1.0.4] — 2026-08-07
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zerotal",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Create a new Zerotal application",
   "license": "MIT",
   "maturity": "stable",

package/src/index.ts

@@ -110,7 +110,9 @@ async function main(): Promise<void> {
   log('');
   log(`${c.bold}  Next steps:${c.reset}`);
   dim(`cd ${name}`);
-  if (template === 'api') {
+  // Every template that ships baseline migrations builds its schema from them
+  // (synchronize is off), so the first migrate is a required step, not a tip.
+  if (template === 'api' || template === 'flow' || template === 'react' || template === 'vue') {
     if (db !== 'sqlite') {
       dim(`# Set DATABASE_URL in .env`);
     }

package/src/scaffold.ts

@@ -13,7 +13,7 @@ export type Template = 'minimal' | 'api' | 'admin' | 'flow' | 'react' | 'vue';
 // "^1.1.0" found for specifier "zerotal"` — the first thing anyone trying the
 // framework saw. `scaffold.test.ts` now asserts the two agree, so CI fails rather
 // than the user's install.
-export const ZT_VERSION = '^1.0.4';
+export const ZT_VERSION = '^1.1.0';
 
 export interface ScaffoldOptions {
   name:     string;
@@ -73,12 +73,18 @@ export async function scaffold(opts: ScaffoldOptions): Promise<void> {
     const src  = join(templateDir, rel);
     // Rename underscore-prefixed dotfiles — npm and Bun glob both skip real dotfiles
     // inside published/scanned directories. _gitignore → .gitignore, etc.
-    // Also strip the .tmpl infix from test files so Bun doesn't discover them
-    // as tests while the package is being developed in the monorepo.
+    //
+    // Test files carry a trailing `.tmpl` that is stripped here, so Bun does not
+    // discover them while this package is developed inside the monorepo — where their
+    // `zerotal/testing` imports cannot resolve, because they are written for the app
+    // being scaffolded rather than for this workspace. The previous spelling was
+    // `_test.ts`, which does not work: Bun's matcher globs `_test.ts` as readily as
+    // `.test.ts` (and `.spec.ts` / `_spec.ts`), so those files were collected and failed
+    // on every root `bun test`. A trailing suffix is matched by none of them.
     const dest = join(opts.target, rel
       .replace('_gitignore',   '.gitignore')
       .replace('_env.example', '.env.example')
-      .replace('_test.ts',     '.test.ts'),
+      .replace(/\.tmpl$/,      ''),
     );
 
     await mkdir(dirname(dest), { recursive: true });

package/templates/admin/app/models/Product.ts

@@ -11,11 +11,11 @@ export class Product extends BaseModel {
 
   @column() name!: string;
   @column() sku!: string;
-  @column({ nullable: true }) description?: string;
+  @column({ nullable: true }) description?: string | undefined;
   /** Price in minor units, so money never rides on a float. */
   @column("integer") price!: number;
-  @column({ cast: "integer", nullable: true }) stock?: number;
+  @column({ cast: "integer", nullable: true }) stock?: number | undefined;
   /** draft | active | discontinued — drives the filter tabs and a select column. */
-  @column({ nullable: true }) status?: string;
-  @column({ cast: "boolean", nullable: true }) featured?: boolean;
+  @column({ nullable: true }) status?: string | undefined;
+  @column({ cast: "boolean", nullable: true }) featured?: boolean | undefined;
 }

package/templates/admin/app/models/Setting.ts

@@ -9,6 +9,6 @@ export class Setting extends BaseModel {
   static override fillable = ["siteName", "supportEmail", "ordersOpen"];
 
   @column() siteName!: string;
-  @column({ nullable: true }) supportEmail?: string;
-  @column({ cast: "boolean", nullable: true }) ordersOpen?: boolean;
+  @column({ nullable: true }) supportEmail?: string | undefined;
+  @column({ cast: "boolean", nullable: true }) ordersOpen?: boolean | undefined;
 }

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

@@ -14,7 +14,7 @@ export class User extends BaseModelWith(Authenticatable) {
   @column() email!: string;
   @column() password!: string;
   /** Assigned roles — drives a multi-select field and a badge column. */
-  @column({ cast: "json", nullable: true }) roles?: string[];
+  @column({ cast: "json", nullable: true }) roles?: string[] | undefined;
   /** Profile picture, shown as a circular image entry on the view page. */
-  @column({ nullable: true }) avatarUrl?: string;
+  @column({ nullable: true }) avatarUrl?: string | undefined;
 }

package/templates/admin/bootstrap/providers.ts

@@ -1,23 +1,37 @@
 import { LogProvider } from "zerotal/logger";
 import { DatabaseProvider } from "zerotal/orm";
+import { StorageProvider } from "zerotal/storage";
 import { CacheProvider } from "zerotal/cache";
 import { SessionProvider } from "zerotal/session";
 import { AuthProvider } from "zerotal/auth";
 import { FlowProvider } from "@zerotal/flow";
 import { AdminProvider } from "@zerotal/admin";
+import { DevtoolsProvider } from "@zerotal/devtools";
 
 // Order matters: the database backs every resource, the cache holds the panel's
 // navigation-badge counts, and the session underpins auth. FlowProvider is
 // listed explicitly (before AdminProvider, which also `dependsOn` it) so its CLI
 // tooling boots in `bun zt`, where the admin panel itself does not run.
+//
+// `DevtoolsProvider` is last and needs no configuration. It activates only when
+// APP_ENV is one of development/dev/local/test/testing — it fails *closed*, so
+// an unset or `staging` APP_ENV leaves it inert rather than exposing the trace
+// inspector. It also injects its own in-page panel, so nothing has to be added
+// to the panel's assets. Press Alt+D (Cmd+D on Mac) to open it.
+//
+// It is a real dependency rather than a devDependency on purpose: this import
+// runs in every environment, so a `--production` install that dropped the
+// package would fail at boot instead of simply skipping the panel.
 const providers = [
   LogProvider,
   DatabaseProvider,
+  StorageProvider,
   CacheProvider,
   SessionProvider,
   AuthProvider,
   FlowProvider,
   AdminProvider,
+  DevtoolsProvider,
 ];
 
 export default providers;

package/templates/admin/package.json

@@ -12,6 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@zerotal/devtools": "{{zerotal_version}}",
     "@zerotal/admin": "{{zerotal_version}}",
     "@zerotal/flow": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}"

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

@@ -12,5 +12,5 @@ export class User extends BaseModel {
   @column({ type: 'string' }) name!:     string;
   @column({ type: 'string' }) email!:    string;
   @column({ type: 'string' }) password!: string;
-  @column({ type: 'string', nullable: true, default: 'user' }) role?: string;
+  @column({ type: 'string', nullable: true, default: 'user' }) role?: string | undefined;
 }

package/templates/api/bootstrap/app.ts

@@ -5,7 +5,20 @@ import { AuthProvider } from 'zerotal/auth';
 import { NotificationProvider } from '@zerotal/notifications';
 import { QueueProvider } from 'zerotal/queue';
 import { LogProvider } from 'zerotal/logger';
+import { DevtoolsProvider } from '@zerotal/devtools';
 
+// `DevtoolsProvider` needs no configuration. It activates only when APP_ENV is
+// one of development/dev/local/test/testing — it fails *closed*, so an unset or
+// `staging` APP_ENV leaves it inert rather than exposing the trace inspector.
+//
+// This API answers with JSON, so there is no HTML for the floating panel to
+// attach itself to. Open `http://localhost:3000/__zerotal/devtools` instead —
+// the dashboard is served as its own page, and every request this API handles
+// still records its SQL, N+1 warnings, jobs, mail and logs there.
+//
+// It is a real dependency rather than a devDependency on purpose: this import
+// runs in every environment, so a `--production` install that dropped the
+// package would fail at boot instead of simply skipping the panel.
 export default Application.create({
   providers: [
     DatabaseProvider,
@@ -14,6 +27,7 @@ export default Application.create({
     NotificationProvider,
     QueueProvider,
     LogProvider,
+    DevtoolsProvider,
   ],
 })
   .routing({ web: `${import.meta.dir}/../routes/index.ts` });

package/templates/api/package.json

@@ -11,6 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@zerotal/devtools": "{{zerotal_version}}",
     "@zerotal/notifications": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}"
   },

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

@@ -48,7 +48,15 @@ export class RegisterPage extends Component {
     user.role = "user";
     await user.save();
 
-    await Auth.attempt({ email: this.email, password: this.password });
+    // Check the result. Redirecting to a guarded page on a failed attempt sends
+    // the visitor to /profile, where AuthMiddleware turns them straight back to
+    // /login — so the account is created and they are bounced to a sign-in form
+    // with no error shown anywhere. Report it instead of redirecting into it.
+    if (!(await Auth.attempt({ email: this.email, password: this.password }))) {
+      this.error = "Your account was created, but signing you in failed. Please sign in.";
+      return;
+    }
+
     this.redirect("/profile").withSuccess("Welcome aboard.");
   }
 

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

@@ -1,7 +1,20 @@
-import { BaseModel, column, table } from "zerotal/orm";
+import { BaseModelWith, column, table } from "zerotal/orm";
+import { Authenticatable } from "zerotal/auth";
 
+/**
+ * `BaseModelWith(Authenticatable)`, not a plain `BaseModel`.
+ *
+ * The mixin is what brands the class so `authUserModel()` can find it. Without
+ * the brand nothing errors and nothing warns — the model saves, queries and
+ * hashes exactly as before — but `Auth.attempt()` resolves *no* user model at
+ * all and therefore returns `false` for every correct password. Registration
+ * appears to work while login silently never succeeds.
+ *
+ * It also supplies `getAuthId()` / `getAuthPassword()`, which the auth flow
+ * reads, and registers the `rememberToken` column that "remember me" needs.
+ */
 @table("users")
-export class User extends BaseModel {
+export class User extends BaseModelWith(Authenticatable) {
   // Models guard every attribute by default. Only these may be mass-assigned
   // from a request body — `role` is deliberately absent, so no amount of extra
   // fields in a form post can promote the account that submitted it.
@@ -13,5 +26,5 @@ export class User extends BaseModel {
   @column({ type: "string" }) name!: string;
   @column({ type: "string" }) email!: string;
   @column({ type: "string" }) password!: string;
-  @column({ type: "string", nullable: true, default: "user" }) role?: string;
+  @column({ type: "string", nullable: true, default: "user" }) role?: string | undefined;
 }

package/templates/flow/bootstrap/providers.ts

@@ -1,11 +1,31 @@
 import { LogProvider } from "zerotal/logger";
 import { DatabaseProvider } from "zerotal/orm";
+import { StorageProvider } from "zerotal/storage";
 import { SessionProvider } from "zerotal/session";
 import { AuthProvider } from "zerotal/auth";
 import { FlowProvider } from "@zerotal/flow";
+import { DevtoolsProvider } from "@zerotal/devtools";
 
 // Order matters: the database backs the user model, and the session underpins
 // auth — AuthProvider needs both already registered when it boots.
-const providers = [LogProvider, DatabaseProvider, SessionProvider, AuthProvider, FlowProvider];
+//
+// `DevtoolsProvider` is last and needs no configuration. It activates only when
+// APP_ENV is one of development/dev/local/test/testing — it fails *closed*, so
+// an unset or `staging` APP_ENV leaves it inert rather than exposing the trace
+// inspector. It also injects its own in-page panel, so nothing has to be added
+// to the frontend bundle. Press Alt+D (Cmd+D on Mac) to open it.
+//
+// It is a real dependency rather than a devDependency on purpose: this import
+// runs in every environment, so a `--production` install that dropped the
+// package would fail at boot instead of simply skipping the panel.
+const providers = [
+  LogProvider,
+  DatabaseProvider,
+  StorageProvider,
+  SessionProvider,
+  AuthProvider,
+  FlowProvider,
+  DevtoolsProvider,
+];
 
 export default providers;

package/templates/flow/config/database.ts

@@ -11,8 +11,10 @@ export default DatabaseConfig({
   // against your development database and leave its rows behind.
   url: env("ZT_DB_URL", env("DATABASE_URL", "./database/db.sqlite")),
 
-  // Builds the schema from the models at boot, so `bun run dev` works with no
-  // migration step. Hard-off in production, where you run the migrations in
-  // database/migrations instead.
-  synchronize: env("APP_ENV", "development") !== "production",
+  // Off deliberately. This template ships baseline migrations in
+  // database/migrations, and boot-time schema sync would create the same tables
+  // from the models first — so the very first `bun zt migrate` would fail with
+  // "table users already exists". Migrations are the single source of truth, in
+  // development exactly as in production; run `bun zt migrate` after scaffolding.
+  synchronize: false,
 });

package/templates/flow/package.json

@@ -11,6 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@zerotal/devtools": "{{zerotal_version}}",
     "@zerotal/flow": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}",
     "tailwindcss": "^4.0.0",

package/templates/flow/tests/{smoke.test.ts → smoke.test.ts.tmpl}

@@ -8,9 +8,11 @@
  * does rather than that it exists.
  */
 import { beforeAll, afterAll, describe, test, expect } from 'bun:test';
-import { createTestApp, type TestApp } from 'zerotal/testing';
+import { createTestApp, migrateDatabase, type TestApp } from 'zerotal/testing';
 import { FlowTest } from '@zerotal/flow/testing';
+import { Auth, Hash, isAuthenticatable } from 'zerotal/auth';
 import { ContactPage } from '../app/flow/pages/contact.tsx';
+import { User } from '../app/models/User.ts';
 
 let app: TestApp;
 
@@ -22,6 +24,12 @@ beforeAll(async () => {
   // Each run gets its own throwaway schema rather than the dev database.
   Bun.env.ZT_DB_URL ??= ':memory:';
   app = await createTestApp(() => import('../bootstrap/app.ts').then((m) => m.default));
+  // Build the schema from the project's own migrations. config/database.ts keeps
+  // synchronize off — migrations are the single source of truth — so without this
+  // the :memory: database above has no tables and every test fails on 'no such
+  // table'. Running the real migrations also means the schema under test is the
+  // schema that ships, rather than a second definition that drifts from it.
+  await migrateDatabase();
 });
 
 afterAll(() => app.close());
@@ -73,6 +81,46 @@ describe('auth', () => {
 
     expect(res.status).toBe(302);
   });
+
+  /*
+   * Credentials must actually verify. Asserting that /login and /register
+   * *render* proves nothing about whether anyone can get in, and that gap let a
+   * User model ship that the auth layer could not resolve at all: every correct
+   * password was rejected, and the only symptom was being returned to the
+   * sign-in form. Nothing threw, and every other test still passed.
+   */
+  /*
+   * `validate` rather than `attempt`: it runs the same user lookup and password
+   * check, but stops short of `Auth.login`, which needs a live request context
+   * that a plain unit test has no reason to build. The bug this guards against
+   * lives entirely in the lookup half.
+   */
+  test('a registered user can actually sign in', async () => {
+    const user = new User();
+    user.name = 'Test Person';
+    user.email = 'signin-check@example.com';
+    user.password = await Hash.make('correct-horse-battery');
+    user.role = 'user';
+    await user.save();
+
+    expect(await Auth.validate({
+      email: 'signin-check@example.com',
+      password: 'correct-horse-battery',
+    })).toBe(true);
+  });
+
+  test('the User model is resolvable by the auth layer', () => {
+    // The root cause, asserted directly: `Auth.attempt` finds the user model
+    // through this brand, so a plain `BaseModel` makes every login fail.
+    expect(isAuthenticatable(User)).toBe(true);
+  });
+
+  test('a wrong password is still refused', async () => {
+    expect(await Auth.validate({
+      email: 'signin-check@example.com',
+      password: 'not-the-password',
+    })).toBe(false);
+  });
 });
 
 /**

package/templates/minimal/bootstrap/app.ts

@@ -1,7 +1,17 @@
 import { Application, basePath } from 'zerotal';
 import { LogProvider } from 'zerotal/logger';
+import { DevtoolsProvider } from '@zerotal/devtools';
 
-const app = Application.create({ providers: [LogProvider] })
+// `DevtoolsProvider` needs no configuration. It activates only when APP_ENV is
+// one of development/dev/local/test/testing — it fails *closed*, so an unset or
+// `staging` APP_ENV leaves it inert rather than exposing the trace inspector. It
+// injects its own in-page panel, so nothing has to be added to the frontend
+// bundle. Press Alt+D (Cmd+D on Mac) to open it.
+//
+// It is a real dependency rather than a devDependency on purpose: this import
+// runs in every environment, so a `--production` install that dropped the
+// package would fail at boot instead of simply skipping the panel.
+const app = Application.create({ providers: [LogProvider, DevtoolsProvider] })
   .routing({
     web: basePath("routes/index.ts"),
   });

package/templates/minimal/package.json

@@ -11,6 +11,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@zerotal/devtools": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}",
     "tailwindcss": "^4.0.0",
     "bun-plugin-tailwind": "latest"

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

@@ -1,7 +1,20 @@
-import { BaseModel, column, table } from "zerotal/orm";
+import { BaseModelWith, column, table } from "zerotal/orm";
+import { Authenticatable } from "zerotal/auth";
 
+/**
+ * `BaseModelWith(Authenticatable)`, not a plain `BaseModel`.
+ *
+ * The mixin is what brands the class so `authUserModel()` can find it. Without
+ * the brand nothing errors and nothing warns — the model saves, queries and
+ * hashes exactly as before — but `Auth.attempt()` resolves *no* user model at
+ * all and therefore returns `false` for every correct password, so no one can
+ * ever sign in.
+ *
+ * It also supplies `getAuthId()` / `getAuthPassword()`, which the auth flow
+ * reads, and registers the `rememberToken` column that "remember me" needs.
+ */
 @table("users")
-export class User extends BaseModel {
+export class User extends BaseModelWith(Authenticatable) {
   // Models guard every attribute by default. Only these may be mass-assigned
   // from a request body — `role` is deliberately absent, so no amount of extra
   // fields in a form post can promote the account that submitted it.
@@ -13,5 +26,5 @@ export class User extends BaseModel {
   @column({ type: "string" }) name!: string;
   @column({ type: "string" }) email!: string;
   @column({ type: "string" }) password!: string;
-  @column({ type: "string", nullable: true, default: "user" }) role?: string;
+  @column({ type: "string", nullable: true, default: "user" }) role?: string | undefined;
 }

package/templates/react/app/routes/register.ts

@@ -33,7 +33,16 @@ export async function POST(http: HttpContext): Promise<void> {
   user.role = "user";
   await user.save();
 
-  await Auth.attempt({ email, password });
+  // Check the result. Redirecting to a guarded page on a failed attempt sends
+  // the visitor to /profile, where the auth guard turns them straight back to
+  // /login — so the account is created and they land on a sign-in form with no
+  // error shown anywhere. Say what happened instead of redirecting into it.
+  if (!(await Auth.attempt({ email, password }))) {
+    http.flash("error", "Your account was created, but signing you in failed. Please sign in.");
+    http.redirect("/login", 303);
+    return;
+  }
+
   http.flash("success", "Welcome aboard.");
   http.redirect("/profile", 303);
 }

package/templates/react/bootstrap/providers.ts

@@ -1,13 +1,33 @@
 import { LogProvider } from "zerotal/logger";
 import { DatabaseProvider } from "zerotal/orm";
+import { StorageProvider } from "zerotal/storage";
 import { SessionProvider } from "zerotal/session";
 import { AuthProvider } from "zerotal/auth";
 import { InertiaProvider } from "@zerotal/inertia";
+import { DevtoolsProvider } from "@zerotal/devtools";
 
 // Order matters: the database backs the user model and the session underpins
 // auth, so both are registered before AuthProvider boots. AuthProvider installs
 // the middleware that puts the signed-in user on the request — which is what
 // makes `auth.user` appear in every Inertia page's props.
-const providers = [LogProvider, DatabaseProvider, SessionProvider, AuthProvider, InertiaProvider];
+//
+// `DevtoolsProvider` is last and needs no configuration. It activates only when
+// APP_ENV is one of development/dev/local/test/testing — it fails *closed*, so
+// an unset or `staging` APP_ENV leaves it inert rather than exposing the trace
+// inspector. It also injects its own in-page panel, so nothing has to be added
+// to the React bundle. Press Alt+D (Cmd+D on Mac) to open it.
+//
+// It is a real dependency rather than a devDependency on purpose: this import
+// runs in every environment, so a `--production` install that dropped the
+// package would fail at boot instead of simply skipping the panel.
+const providers = [
+  LogProvider,
+  DatabaseProvider,
+  StorageProvider,
+  SessionProvider,
+  AuthProvider,
+  InertiaProvider,
+  DevtoolsProvider,
+];
 
 export default providers;

package/templates/react/config/database.ts

@@ -11,8 +11,10 @@ export default DatabaseConfig({
   // against your development database and leave its rows behind.
   url: env("ZT_DB_URL", env("DATABASE_URL", "./database/db.sqlite")),
 
-  // Builds the schema from the models at boot, so `bun run dev` works with no
-  // migration step. Hard-off in production, where you run the migrations in
-  // database/migrations instead.
-  synchronize: env("APP_ENV", "development") !== "production",
+  // Off deliberately. This template ships baseline migrations in
+  // database/migrations, and boot-time schema sync would create the same tables
+  // from the models first — so the very first `bun zt migrate` would fail with
+  // "table users already exists". Migrations are the single source of truth, in
+  // development exactly as in production; run `bun zt migrate` after scaffolding.
+  synchronize: false,
 });

package/templates/react/package.json

@@ -12,6 +12,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@zerotal/devtools": "{{zerotal_version}}",
     "@inertiajs/react": "^2.0.0",
     "@zerotal/inertia": "{{zerotal_version}}",
     "react": "^19.0.0",

package/templates/react/tests/{smoke.test.ts → smoke.test.ts.tmpl}

@@ -7,7 +7,7 @@
  * you have real tests, or keep it as the shape to copy.
  */
 import { beforeAll, afterAll, describe, test, expect } from 'bun:test';
-import { createTestApp, type TestApp } from 'zerotal/testing';
+import { createTestApp, migrateDatabase, type TestApp } from 'zerotal/testing';
 
 let app: TestApp;
 
@@ -18,6 +18,12 @@ beforeAll(async () => {
   // Each run gets its own throwaway schema rather than the dev database.
   Bun.env.ZT_DB_URL ??= ':memory:';
   app = await createTestApp(() => import('../bootstrap/app.ts').then((m) => m.default));
+  // Build the schema from the project's own migrations. config/database.ts keeps
+  // synchronize off — migrations are the single source of truth — so without this
+  // the :memory: database above has no tables and every test fails on 'no such
+  // table'. Running the real migrations also means the schema under test is the
+  // schema that ships, rather than a second definition that drifts from it.
+  await migrateDatabase();
 });
 
 afterAll(() => app.close());

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

@@ -13,5 +13,5 @@ export class User extends BaseModel {
   @column({ type: "string" }) name!: string;
   @column({ type: "string" }) email!: string;
   @column({ type: "string" }) password!: string;
-  @column({ type: "string", nullable: true, default: "user" }) role?: string;
+  @column({ type: "string", nullable: true, default: "user" }) role?: string | undefined;
 }

package/templates/vue/bootstrap/providers.ts

@@ -1,5 +1,6 @@
 import { LogProvider } from "zerotal/logger";
 import { DatabaseProvider } from "zerotal/orm";
+import { StorageProvider } from "zerotal/storage";
 import { SessionProvider } from "zerotal/session";
 import { AuthProvider } from "zerotal/auth";
 import { InertiaProvider } from "@zerotal/inertia";

package/templates/vue/config/database.ts

@@ -11,8 +11,10 @@ export default DatabaseConfig({
   // against your development database and leave its rows behind.
   url: env("ZT_DB_URL", env("DATABASE_URL", "./database/db.sqlite")),
 
-  // Builds the schema from the models at boot, so `bun run dev` works with no
-  // migration step. Hard-off in production, where you run the migrations in
-  // database/migrations instead.
-  synchronize: env("APP_ENV", "development") !== "production",
+  // Off deliberately. This template ships baseline migrations in
+  // database/migrations, and boot-time schema sync would create the same tables
+  // from the models first — so the very first `bun zt migrate` would fail with
+  // "table users already exists". Migrations are the single source of truth, in
+  // development exactly as in production; run `bun zt migrate` after scaffolding.
+  synchronize: false,
 });

package/templates/vue/tests/{smoke.test.ts → smoke.test.ts.tmpl}

@@ -7,7 +7,7 @@
  * you have real tests, or keep it as the shape to copy.
  */
 import { beforeAll, afterAll, describe, test, expect } from 'bun:test';
-import { createTestApp, type TestApp } from 'zerotal/testing';
+import { createTestApp, migrateDatabase, type TestApp } from 'zerotal/testing';
 
 let app: TestApp;
 
@@ -18,6 +18,12 @@ beforeAll(async () => {
   // Each run gets its own throwaway schema rather than the dev database.
   Bun.env.ZT_DB_URL ??= ':memory:';
   app = await createTestApp(() => import('../bootstrap/app.ts').then((m) => m.default));
+  // Build the schema from the project's own migrations. config/database.ts keeps
+  // synchronize off — migrations are the single source of truth — so without this
+  // the :memory: database above has no tables and every test fails on 'no such
+  // table'. Running the real migrations also means the schema under test is the
+  // schema that ships, rather than a second definition that drifts from it.
+  await migrateDatabase();
 });
 
 afterAll(() => app.close());