create-zerotal 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -8,6 +8,24 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.0.2] — 2026-08-06
+
+### Fixed
+
+- **Templates could not be type-checked and, for two database choices, could not
+  boot.** `api` scaffolded with PostgreSQL or MySQL wrote a matching
+  `DATABASE_URL` but left the driver at its `sqlite` default — the exact pairing
+  boot validation rejects. No template declared `@types/bun`, so `tsc` failed in
+  all six; none had a `typecheck` script to reveal it.
+- `flow` and `minimal` listed Tailwind as a dev dependency although `zt serve`
+  builds their assets at boot, so `bun install --production` broke them.
+- Templates imported packages they did not declare, resolving only via hoisting.
+
+### Added
+
+- A README, an `engines` floor, a `typecheck` script and a documented
+  `.env.example` in every template.
+
 ## [1.0.1] — 2026-08-06
 
 ### Fixed

package/package.json

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

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.1';
+export const ZT_VERSION = '^1.0.2';
 
 export interface ScaffoldOptions {
   name:     string;

package/templates/admin/README.md

@@ -0,0 +1,41 @@
+# {{name}}
+
+An admin panel: resources, authentication, dashboard widgets and seeded demo data.
+
+
+Built with [Zerotal](https://zerotal.dev) — a full-stack TypeScript framework for Bun.
+
+## Requirements
+
+- [Bun](https://bun.sh) 1.3.14 or newer. Node.js is not supported: Zerotal uses
+  Bun-native APIs throughout.
+
+## Getting started
+
+```bash
+bun install
+bun run dev
+```
+
+The dev server prints a local URL and a network one, so you can open the app on
+another device on the same Wi-Fi.
+
+## Scripts
+
+| Command | What it does |
+| --- | --- |
+| `bun run dev` | Start the dev server with hot reload |
+| `bun run start` | Start the server without dev tooling |
+| `bun run test` | Run the test suite |
+| `bun run typecheck` | Type-check without emitting |
+| `bun run seed` | Re-seed the demo data |
+
+## Configuration
+
+Environment variables live in `.env`, documented in `.env.example`. `APP_KEY`
+was generated for this project when it was scaffolded — keep it out of version
+control, and use a different one per environment.
+
+## Documentation
+
+Full documentation is at [zerotal.dev/docs](https://zerotal.dev/docs).

package/templates/admin/_env.example

@@ -1,2 +1,19 @@
+# The runtime environment. "production" turns on the framework's stricter
+# config checks and turns off verbose error output.
 APP_ENV=development
+
+# Signs sessions, cookies and encrypted values. Generated per project — never
+# reuse one between environments, and never commit a real key.
 APP_KEY={{app_key}}
+
+# Canonical base URL. Used for absolute links, and to recognise your own origin
+# when the app runs behind a reverse proxy.
+APP_URL=http://localhost:3000
+
+# Connection string for the database. Must match the driver in config/database.ts.
+#
+# Left commented on purpose. config/database.ts already points at this file, and
+# `bun zt test` treats a set DATABASE_URL as the test database too — so setting
+# it here would have the suite mutate your development data instead of running
+# against a throwaway :memory: schema. Uncomment only to point somewhere else.
+# DATABASE_URL={{db_url}}

package/templates/admin/app/admin/index.ts

@@ -10,6 +10,7 @@
 // independent registry that shares this one's models and sign-in.
 import { Panel } from "@zerotal/admin";
 import { AuthMiddleware, GuestMiddleware } from "zerotal/auth";
+import { passwordReset } from "@app/auth/passwords";
 
 import { ProductResource } from "@app/admin/ProductResource";
 import { UserResource } from "@app/admin/UserResource";
@@ -35,10 +36,15 @@ Panel.configure({
 });
 
 // The panel's own login and profile screens.
+// Login and profile come with the panel. Supplying `passwordReset` is what
+// mounts /admin/forgot-password and /admin/reset-password and puts the "Forgot
+// your password?" link on the login screen — without it those routes do not
+// exist, so the link is deliberately absent rather than dead.
 Panel.auth({
   enabled: true,
   heading: "{{name}}",
   guestMiddleware: [GuestMiddleware],
+  passwordReset,
 });
 
 Panel.widgets(...dashboardWidgets());

package/templates/admin/app/auth/passwords.ts

@@ -0,0 +1,79 @@
+import { PasswordBroker, Hash } from "zerotal/auth";
+import { DB } from "zerotal/orm";
+import { Log } from "zerotal/logger";
+import { User } from "@app/models/User";
+
+/**
+ * Password-reset broker for the panel's forgot/reset screens.
+ *
+ * The broker owns the security-sensitive half — generating the token, hashing
+ * it before storage, expiring it, and comparing candidates in constant time.
+ * Everything below is the part only this app can answer: where tokens live, how
+ * a message reaches the user, and what "set the password" means for our model.
+ */
+const broker = new PasswordBroker({
+  expireMinutes: 60,
+
+  async findToken(email) {
+    const row = await DB.table("password_reset_tokens").where("email", email).first();
+    if (!row) return null;
+    return {
+      token: String((row as Record<string, unknown>)["token"]),
+      createdAt: new Date(String((row as Record<string, unknown>)["created_at"])),
+    };
+  },
+
+  async storeToken(email, hash) {
+    // One live token per address: a second request invalidates the first rather
+    // than leaving two working links in someone's inbox.
+    await DB.table("password_reset_tokens").where("email", email).delete();
+    await DB.table("password_reset_tokens").insert({
+      email,
+      token: hash,
+      created_at: new Date().toISOString(),
+    });
+  },
+
+  async deleteToken(email) {
+    await DB.table("password_reset_tokens").where("email", email).delete();
+  },
+
+  async pruneTokens(cutoff) {
+    await DB.table("password_reset_tokens").where("created_at", "<", cutoff.toISOString()).delete();
+  },
+
+  async sendResetLink(email, token) {
+    const url = `${process.env["APP_URL"] ?? "http://localhost:3000"}/admin/reset-password?token=${token}&email=${encodeURIComponent(email)}`;
+
+    // Logged rather than emailed, so a freshly scaffolded app has a working
+    // reset flow before any mail server exists. To send it for real, add
+    // `@zerotal/notifications` and swap this line for a Mail send — the token
+    // is the only thing this callback needs to deliver.
+    Log.info(`[password reset] ${email} → ${url}`);
+  },
+
+  async resetPassword(email, newPassword) {
+    const user = await User.query().where("email", email).first();
+    if (!user) return;
+    user.password = await Hash.make(newPassword);
+    await user.save();
+  },
+});
+
+/**
+ * Adapter matching the panel's `passwordReset` contract, which wants booleans
+ * rather than the broker's result strings.
+ */
+export const passwordReset = {
+  async sendResetLink(email: string): Promise<boolean> {
+    // Always reports success. Answering "no such account" here would turn the
+    // forgot-password form into a way to test which addresses are registered.
+    await broker.sendResetLink(email);
+    return true;
+  },
+
+  async reset(input: { email: string; token: string; password: string }): Promise<boolean> {
+    const result = await broker.reset(input.token, input.email, input.password);
+    return result === "passwords.reset";
+  },
+};

package/templates/admin/config/database.ts

@@ -3,9 +3,10 @@ import { DatabaseConfig } from "zerotal/orm";
 
 export default DatabaseConfig({
   driver: "sqlite",
-  // `bun zt test` sets ZT_DB_URL (defaults to :memory:) so the suite runs
-  // against an isolated database instead of your local dev file.
-  url: env("DATABASE_URL", env("ZT_DB_URL", "./database/db.sqlite")),
+  // ZT_DB_URL first: `bun zt test` sets it (defaults to :memory:) and that
+  // override has to beat the DATABASE_URL in .env, or the suite would run
+  // against your development database and leave its rows behind.
+  url: env("ZT_DB_URL", env("DATABASE_URL", "./database/db.sqlite")),
 
   // Additive schema sync for local development — creates every demo table from
   // the models at boot, so `bun run dev` works with no migration step. Hard-off

package/templates/admin/database/migrations/0001_create_password_reset_tokens_table.ts

@@ -0,0 +1,26 @@
+import { Migration, Schema } from "zerotal/orm";
+
+/**
+ * One live reset token per address, keyed by email rather than user id so a
+ * request for an unknown address does the same work as a known one — the
+ * response must not reveal which addresses have accounts.
+ *
+ * `token` holds a SHA-256 hash, never the value that was emailed: a leaked
+ * database should not hand out working reset links.
+ *
+ * This is a plain table rather than a model, so `synchronize` does not create
+ * it. Run `bun zt migrate` once before using password reset.
+ */
+export default class CreatePasswordResetTokensTable extends Migration {
+  async up(): Promise<void> {
+    await Schema.create("password_reset_tokens", (table) => {
+      table.string("email").primary();
+      table.string("token");
+      table.timestamp("created_at");
+    });
+  }
+
+  async down(): Promise<void> {
+    await Schema.drop("password_reset_tokens");
+  }
+}

package/templates/admin/package.json

@@ -8,11 +8,19 @@
     "dev": "bun zt.ts serve --dev",
     "start": "bun zt.ts serve",
     "seed": "bun zt.ts db:seed",
-    "test": "bun zt.ts test"
+    "test": "bun zt.ts test",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@zerotal/admin": "{{zerotal_version}}",
     "@zerotal/flow": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@types/bun": "^1.3.14"
   }
 }

package/templates/admin/tsconfig.json

@@ -13,8 +13,13 @@
     "noEmit": true,
     "allowImportingTsExtensions": true,
     "paths": {
-      "@app/*": ["./app/*"]
+      "@app/*": [
+        "./app/*"
+      ]
     }
   },
-  "exclude": ["node_modules", ".zerotal"]
+  "exclude": [
+    "node_modules",
+    ".zerotal"
+  ]
 }

package/templates/api/README.md

@@ -0,0 +1,39 @@
+# {{name}}
+
+A JSON REST API — routing, ORM, authentication, validation and tests, with no frontend.
+
+Built with [Zerotal](https://zerotal.dev) — a full-stack TypeScript framework for Bun.
+
+## Requirements
+
+- [Bun](https://bun.sh) 1.3.14 or newer. Node.js is not supported: Zerotal uses
+  Bun-native APIs throughout.
+
+## Getting started
+
+```bash
+bun install
+bun run dev
+```
+
+The dev server prints a local URL and a network one, so you can open the app on
+another device on the same Wi-Fi.
+
+## Scripts
+
+| Command | What it does |
+| --- | --- |
+| `bun run dev` | Start the dev server with hot reload |
+| `bun run start` | Start the server without dev tooling |
+| `bun run test` | Run the test suite |
+| `bun run typecheck` | Type-check without emitting |
+
+## Configuration
+
+Environment variables live in `.env`, documented in `.env.example`. `APP_KEY`
+was generated for this project when it was scaffolded — keep it out of version
+control, and use a different one per environment.
+
+## Documentation
+
+Full documentation is at [zerotal.dev/docs](https://zerotal.dev/docs).

package/templates/api/_env.example

@@ -1,4 +1,17 @@
+# The runtime environment. "production" turns on the framework's stricter
+# config checks and turns off verbose error output.
 APP_ENV=development
+
+# Signs sessions, cookies and encrypted values. Generated per project — never
+# reuse one between environments, and never commit a real key.
 APP_KEY={{app_key}}
+
+# Canonical base URL. Used for absolute links, and to recognise your own origin
+# when the app runs behind a reverse proxy.
+APP_URL=http://localhost:3000
+
+# Connection string for the database. Must match the driver in config/database.ts.
 DATABASE_URL={{db_url}}
+
+# Separate secret for session payloads, independent of APP_KEY.
 SESSION_SECRET={{session_secret}}

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

@@ -1,5 +1,5 @@
-import type { HttpContext } from '@zerotal/core';
-import { Hash } from '@zerotal/auth';
+import type { HttpContext } from 'zerotal';
+import { Hash } from 'zerotal/auth';
 import { User } from '../models/User.ts';
 
 export class AuthController {
@@ -19,12 +19,15 @@ export class AuthController {
       return;
     }
 
-    const user = await User.create({
-      name,
-      email,
-      password: await Hash.make(password),
-      role: 'user',
-    } as Partial<User>);
+    // `role` is not in `fillable`, so it cannot be mass-assigned — passing it to
+    // create() is refused outright, which is the guard doing its job. Setting it
+    // here, in code, is the point: a value the request can never influence.
+    const user = new User();
+    user.name = name;
+    user.email = email;
+    user.password = await Hash.make(password);
+    user.role = 'user';
+    await user.save();
 
     http.session?.set('user_id', user.id);
     http.response = Response.json({ data: { id: user.id, name: user.name, email: user.email } }, { status: 201 });

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

@@ -1,4 +1,4 @@
-import type { HttpContext } from '@zerotal/core';
+import type { HttpContext } from 'zerotal';
 
 export class WelcomeController {
   async index(http: HttpContext): Promise<void> {

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

@@ -1,4 +1,4 @@
-import type { HttpContext, Pipe, NextFn } from '@zerotal/core';
+import type { HttpContext, Pipe, NextFn } from 'zerotal';
 
 export class RequireAuth implements Pipe<HttpContext> {
   async handle(http: HttpContext, next: NextFn): Promise<Response | void> {

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

@@ -1,4 +1,4 @@
-import { BaseModel, column, table } from '@zerotal/orm';
+import { BaseModel, column, table } from 'zerotal/orm';
 
 @table('users')
 export class User extends BaseModel {
@@ -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' }) role!:     string;
+  @column({ type: 'string', nullable: true, default: 'user' }) role?: string;
 }

package/templates/api/bootstrap/app.ts

@@ -1,10 +1,10 @@
-import { Application } from '@zerotal/core';
-import { DatabaseProvider } from '@zerotal/orm';
-import { SessionProvider } from '@zerotal/session';
-import { AuthProvider } from '@zerotal/auth';
+import { Application } from 'zerotal';
+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';
+import { QueueProvider } from 'zerotal/queue';
+import { LogProvider } from 'zerotal/logger';
 
 export default Application.create({
   providers: [

package/templates/api/config/app.ts

@@ -1,4 +1,4 @@
-import { env } from '@zerotal/core';
+import { env } from 'zerotal';
 
 export default {
   name: '{{name}}',

package/templates/api/config/database.ts

@@ -1,6 +1,15 @@
-import { env } from '@zerotal/core';
-import { DatabaseConfig } from '@zerotal/orm';
+import { env } from 'zerotal';
+import { DatabaseConfig } from 'zerotal/orm';
 
 export default DatabaseConfig({
-  url: env('DATABASE_URL', '{{db_url}}'),
+  // The driver has to agree with the URL's protocol. Boot validation rejects a
+  // sqlite driver pointed at postgres:// or mysql://, which is exactly what you
+  // get if this is left to its default while DATABASE_URL names a network
+  // database — so it is stamped from the database you chose when scaffolding.
+  driver: '{{db_driver}}',
+
+  // ZT_DB_URL first: `bun zt test` sets it (defaults to :memory:) and that
+  // override has to beat the DATABASE_URL in .env, or the suite would run
+  // against your development database and leave its rows behind.
+  url: env('ZT_DB_URL', env('DATABASE_URL', '{{db_url}}')),
 });

package/templates/api/config/notifications.ts

@@ -1,4 +1,4 @@
-import { env } from '@zerotal/core';
+import { env } from 'zerotal';
 import { NotificationConfig } from '@zerotal/notifications';
 
 export default NotificationConfig({

package/templates/api/config/queue.ts

@@ -1,4 +1,4 @@
-import { env } from '@zerotal/core';
+import { env } from 'zerotal';
 
 export default {
   driver:     env('QUEUE_DRIVER', 'sync'),

package/templates/api/config/session.ts

@@ -1,5 +1,5 @@
-import { env } from '@zerotal/core';
-import { SessionConfig } from '@zerotal/session';
+import { env } from 'zerotal';
+import { SessionConfig } from 'zerotal/session';
 
 export default SessionConfig({
   driver:   env('SESSION_DRIVER', 'cookie') as 'cookie' | 'redis',

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

@@ -1,14 +1,14 @@
-import { Migration, Schema } from '@zerotal/orm';
+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();
+    await Schema.create('users', (table) => {
+      table.increments('id');
+      table.string('name');
+      table.string('email').unique();
+      table.string('password');
+      table.string('role').nullable().default('user');
+      table.timestamps();
     });
   }
 

package/templates/api/package.json

@@ -7,10 +7,18 @@
     "zt": "bun zt.ts",
     "dev": "bun zt.ts serve --dev",
     "start": "bun zt.ts serve",
-    "test": "bun zt.ts test"
+    "test": "bun zt.ts test",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@zerotal/notifications": "{{zerotal_version}}",
     "zerotal": "{{zerotal_version}}"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@types/bun": "^1.3.14"
   }
 }

package/templates/api/routes/index.ts

@@ -1,13 +1,28 @@
-import { Router } from '@zerotal/core';
+import { Router } from 'zerotal';
 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');
+/**
+ * Every route this API serves.
+ *
+ * Exported as a function *and* called below, because the two callers need
+ * different things. `bootstrap/app.ts` points `.routing()` at this file and
+ * relies on importing it to register the routes — that is the call at the
+ * bottom. Tests build their own application, and `createTestApp` resets the
+ * router before handing control to its `setup` callback; re-importing this file
+ * would not help, since a module's top-level code runs once per process. So the
+ * suite calls `registerRoutes()` from that callback instead.
+ */
+export function registerRoutes(): void {
+  // 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]);
+  // Protected
+  Router.get('/me', AuthController, 'me', [RequireAuth]);
+}
+
+registerRoutes();

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

@@ -5,14 +5,17 @@ import {
   assertDatabaseHas,
   assertDatabaseMissing,
   type TestApp,
-} from '@zerotal/testing';
-import '../routes/index.ts';
+} from 'zerotal/testing';
+import { registerRoutes } from '../routes/index.ts';
 import { createApp } from './helpers.ts';
 
 let app: TestApp;
 
 beforeAll(async () => {
-  app = await createApp();
+  // Routes are registered through the setup callback, not by importing this
+  // file for its side effects: `createTestApp` resets the router before it
+  // runs setup, and a module's top-level code only executes once per process.
+  app = await createApp(registerRoutes);
   // 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();

package/templates/api/tests/helpers.ts

@@ -1,10 +1,10 @@
-import { Application } from '@zerotal/core';
-import { DatabaseProvider } from '@zerotal/orm';
-import { SessionProvider, AuthSessionMiddleware, CookieDriver } from '@zerotal/session';
-import { AuthProvider } from '@zerotal/auth';
+import { Application } from 'zerotal';
+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 { 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';

package/templates/api/tsconfig.json

@@ -7,8 +7,12 @@
     "exactOptionalPropertyTypes": true,
     "noUncheckedIndexedAccess": true,
     "emitDecoratorMetadata": false,
-    "skipLibCheck": true
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true
   },
-  "include": ["**/*.ts"],
-  "exclude": ["node_modules", ".zerotal"]
+  "exclude": [
+    "node_modules",
+    ".zerotal"
+  ]
 }