create-zerotal 1.0.0 → 1.0.2

package/templates/flow/app/flow/pages/reset-password.tsx

@@ -0,0 +1,103 @@
+import { Component, expose, url, Link } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { GuestMiddleware } from "zerotal/auth";
+import { passwordReset } from "@app/auth/passwords";
+import { AppLayout } from "../layouts/app";
+import { FIELD, LABEL, PRIMARY, CARD, ERROR, NOTICE } from "../ui";
+
+export const middleware = [GuestMiddleware];
+
+export class ResetPasswordPage extends Component {
+  static layout = AppLayout;
+  static title = "Choose a new password";
+
+  /** Seeded from the reset link's query string (`?token=…&email=…`). */
+  @url token = "";
+  @url email = "";
+
+  @expose password = "";
+  @expose passwordConfirmation = "";
+  @expose error = "";
+  @expose done = false;
+
+  @expose async reset(): Promise<void> {
+    this.error = "";
+
+    if (this.password.length < 8) {
+      this.error = "Choose a password of at least 8 characters.";
+      return;
+    }
+    if (this.password !== this.passwordConfirmation) {
+      this.error = "The two passwords do not match.";
+      return;
+    }
+
+    const ok = await passwordReset.reset({
+      email: this.email,
+      token: this.token,
+      password: this.password,
+    });
+
+    if (ok) this.done = true;
+    else this.error = "This reset link is invalid or has expired.";
+  }
+
+  async render(): Promise<HtmlNode> {
+    if (this.done) {
+      return (
+        <section class={CARD}>
+          <h1 class="text-2xl font-bold tracking-tight">Password updated</h1>
+          <p class={`${NOTICE} mt-4`}>You can now sign in with your new password.</p>
+          <p class="mt-6 text-sm text-gray-600">
+            <Link href="/login" class="text-indigo-600 hover:underline">
+              Go to sign in
+            </Link>
+          </p>
+        </section>
+      );
+    }
+
+    return (
+      <section class={CARD}>
+        <h1 class="text-2xl font-bold tracking-tight">Choose a new password</h1>
+        <p class="mt-1 text-sm text-gray-600">Resetting the password for {this.email}.</p>
+
+        <form onSubmit={this.reset} class="mt-6 space-y-4">
+          {this.error ? <p class={ERROR}>{this.error}</p> : null}
+
+          <div>
+            <label class={LABEL} for="password">
+              New password
+            </label>
+            <input
+              id="password"
+              type="password"
+              autocomplete="new-password"
+              required
+              class={FIELD}
+              value={this.password}
+            />
+          </div>
+
+          <div>
+            <label class={LABEL} for="password_confirmation">
+              Confirm password
+            </label>
+            <input
+              id="password_confirmation"
+              type="password"
+              autocomplete="new-password"
+              required
+              class={FIELD}
+              value={this.passwordConfirmation}
+            />
+          </div>
+
+          <button type="submit" class={PRIMARY}>
+            Update password
+          </button>
+        </form>
+      </section>
+    );
+  }
+}

package/templates/flow/app/flow/ui.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared form styling, so every auth screen looks like the same application.
+ *
+ * Plain string constants rather than components: Flow renders on the server and
+ * these are only class lists, so a constant is the whole abstraction needed.
+ */
+export const CARD = "mx-auto w-full max-w-sm rounded-2xl border border-gray-200/70 bg-white p-8 shadow-sm";
+
+export const LABEL = "block text-sm font-medium text-gray-900";
+
+export const FIELD =
+  "mt-1.5 block w-full rounded-lg border border-gray-300 bg-white px-3 py-2 text-sm text-gray-900 " +
+  "outline-none transition placeholder:text-gray-400 focus:border-indigo-500 focus:ring-2 focus:ring-indigo-500/30";
+
+export const PRIMARY =
+  "w-full rounded-lg bg-indigo-600 px-4 py-2 text-sm font-semibold text-white transition " +
+  "hover:bg-indigo-500 focus:outline-none focus:ring-2 focus:ring-indigo-500/40 disabled:opacity-60";
+
+export const SECONDARY =
+  "rounded-lg border border-gray-300 bg-white px-4 py-2 text-sm font-semibold text-gray-700 " +
+  "transition hover:bg-gray-50";
+
+export const ERROR =
+  "rounded-lg border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700";
+
+export const NOTICE =
+  "rounded-lg border border-emerald-200 bg-emerald-50 px-3 py-2 text-sm text-emerald-700";

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

@@ -0,0 +1,17 @@
+import { BaseModel, column, table } from "zerotal/orm";
+
+@table("users")
+export class User extends BaseModel {
+  // 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.
+  static override fillable = ["name", "email", "password"];
+
+  // Never serialised into a rendered page or a JSON response.
+  static override hidden = ["password"];
+
+  @column({ type: "string" }) name!: string;
+  @column({ type: "string" }) email!: string;
+  @column({ type: "string" }) password!: string;
+  @column({ type: "string", nullable: true, default: "user" }) role?: string;
+}

package/templates/flow/bootstrap/app.ts

@@ -1,5 +1,13 @@
 import { Application, basePath } from "zerotal";
 import providers from "./providers";
+import type { User } from "../app/models/User.ts";
+
+// Tell @zerotal/auth which model `Auth.user()` returns. The empty body is the
+// point: this augmentation exists to bind the type, not to add members.
+declare module "zerotal/auth" {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface UserModel extends User {}
+}
 
 const app = Application.create({ providers }).fileBasedRouting({
   web: basePath("app/flow/pages"),

package/templates/flow/bootstrap/providers.ts

@@ -1,6 +1,11 @@
 import { LogProvider } from "zerotal/logger";
+import { DatabaseProvider } from "zerotal/orm";
+import { SessionProvider } from "zerotal/session";
+import { AuthProvider } from "zerotal/auth";
 import { FlowProvider } from "@zerotal/flow";
 
-const providers = [LogProvider, FlowProvider];
+// 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];
 
 export default providers;

package/templates/flow/config/auth.ts

@@ -0,0 +1,7 @@
+import { AuthConfig } from "zerotal/auth";
+
+export default AuthConfig({
+  // argon2id is the default and what `Hash.make` uses unless told otherwise.
+  // Switch to 'bcrypt' only to stay compatible with an existing password table.
+  algorithm: "argon2id",
+});

package/templates/flow/config/database.ts

@@ -0,0 +1,18 @@
+import { env } from "zerotal";
+import { DatabaseConfig } from "zerotal/orm";
+
+export default DatabaseConfig({
+  // The driver has to agree with the URL's protocol — boot validation rejects a
+  // sqlite driver pointed at postgres:// or mysql://. Change both together.
+  driver: "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")),
+
+  // 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",
+});

package/templates/flow/config/session.ts

@@ -0,0 +1,14 @@
+import { env } from "zerotal";
+import { SessionConfig } from "zerotal/session";
+
+export default SessionConfig({
+  driver: "cookie",
+  // Cookie sessions are signed, so the driver needs the app key.
+  secret: env("APP_KEY", ""),
+  cookie: "{{name}}_session",
+  lifetime: 60 * 60 * 24 * 7, // 7 days
+  // Tied to the scheme rather than hardcoded: a `secure` cookie is never sent
+  // over plain HTTP, so setting it unconditionally would drop the session in
+  // local development. The framework refuses to boot production without it.
+  secure: env("APP_URL", "http://localhost:3000").startsWith("https://"),
+});

package/templates/flow/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", (table) => {
+      table.increments("id");
+      table.string("name");
+      table.string("email").unique();
+      table.string("password");
+      table.string("role").nullable().default("user");
+      table.timestamps();
+    });
+  }
+
+  async down(): Promise<void> {
+    await Schema.drop("users");
+  }
+}

package/templates/flow/database/migrations/0002_create_password_reset_tokens_table.ts

@@ -0,0 +1,23 @@
+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 sent: a leaked
+ * database should not hand out working reset links.
+ */
+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/flow/package.json

@@ -7,14 +7,20 @@
     "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/flow": "{{zerotal_version}}",
-    "zerotal": "{{zerotal_version}}"
+    "zerotal": "{{zerotal_version}}",
+    "tailwindcss": "^4.0.0",
+    "bun-plugin-tailwind": "latest"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
   },
   "devDependencies": {
-    "bun-plugin-tailwind": "latest",
-    "tailwindcss": "^4.0.0"
+    "typescript": "^5.8.0",
+    "@types/bun": "^1.3.14"
   }
 }

package/templates/flow/tests/smoke.test.ts

@@ -8,7 +8,7 @@
  * does rather than that it exists.
  */
 import { beforeAll, afterAll, describe, test, expect } from 'bun:test';
-import { createTestApp, type TestApp } from '@zerotal/testing';
+import { createTestApp, type TestApp } from 'zerotal/testing';
 import { FlowTest } from '@zerotal/flow/testing';
 import { ContactPage } from '../app/flow/pages/contact.tsx';
 
@@ -19,6 +19,8 @@ beforeAll(async () => {
   // deterministic one for tests; `??=` leaves a real key alone when the app's
   // .env is present.
   Bun.env.APP_KEY ??= 'test-app-key-aaaaaaaaaaaaaaaaaaaaaaaa';
+  // 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));
 });
 
@@ -54,3 +56,21 @@ describe('the contact page component', () => {
     page.assertSee('hello@example.com');
   });
 });
+
+/**
+ * The auth surface. The guard is the assertion that matters: /profile must be
+ * unreachable without a session, however the page itself is built.
+ */
+describe('auth', () => {
+  test('serves the guest screens', async () => {
+    (await app.get('/login')).assertOk();
+    (await app.get('/register')).assertOk();
+    (await app.get('/forgot-password')).assertOk();
+  });
+
+  test('keeps the profile behind a sign-in', async () => {
+    const res = await app.get('/profile');
+
+    expect(res.status).toBe(302);
+  });
+});

package/templates/flow/tsconfig.json

@@ -11,8 +11,15 @@
     "jsxImportSource": "@zerotal/flow",
     "skipLibCheck": true,
     "paths": {
-      "@app/*": ["./app/*"]
-    }
+      "@app/*": [
+        "./app/*"
+      ]
+    },
+    "noEmit": true,
+    "allowImportingTsExtensions": true
   },
-  "exclude": ["node_modules", ".zerotal"]
+  "exclude": [
+    "node_modules",
+    ".zerotal"
+  ]
 }

package/templates/minimal/README.md

@@ -0,0 +1,39 @@
+# {{name}}
+
+A single-page starter on the bare framework — JSX views and Tailwind, nothing else.
+
+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/minimal/_env.example

@@ -1,2 +1,11 @@
+# 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

package/templates/minimal/bootstrap/app.ts

@@ -1,5 +1,5 @@
-import { Application, basePath } from '@zerotal/core';
-import { LogProvider } from '@zerotal/core/logger';
+import { Application, basePath } from 'zerotal';
+import { LogProvider } from 'zerotal/logger';
 
 const app = Application.create({ providers: [LogProvider] })
   .routing({

package/templates/minimal/package.json

@@ -7,14 +7,19 @@
     "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/flow": "{{zerotal_version}}",
-    "zerotal": "{{zerotal_version}}"
+    "zerotal": "{{zerotal_version}}",
+    "tailwindcss": "^4.0.0",
+    "bun-plugin-tailwind": "latest"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
   },
   "devDependencies": {
-    "bun-plugin-tailwind": "latest",
-    "tailwindcss": "^4.0.0"
+    "typescript": "^5.8.0",
+    "@types/bun": "^1.3.14"
   }
 }

package/templates/minimal/tests/smoke.test.ts

@@ -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, type TestApp } from 'zerotal/testing';
 
 let app: TestApp;
 

package/templates/minimal/tsconfig.json

@@ -11,9 +11,18 @@
     "jsxImportSource": "zerotal",
     "skipLibCheck": true,
     "paths": {
-      "@app/*": ["./app/*"],
-      "@pages/*": ["./resources/js/pages/*"]
-    }
+      "@app/*": [
+        "./app/*"
+      ],
+      "@pages/*": [
+        "./resources/js/pages/*"
+      ]
+    },
+    "noEmit": true,
+    "allowImportingTsExtensions": true
   },
-  "exclude": ["node_modules", ".zerotal"]
+  "exclude": [
+    "node_modules",
+    ".zerotal"
+  ]
 }

package/templates/react/README.md

@@ -0,0 +1,40 @@
+# {{name}}
+
+An Inertia + React single-page app with file-based routes and Tailwind.
+
+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 build` | Build the frontend bundle for production |
+
+## 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/react/_env.example

@@ -1,4 +1,22 @@
+# 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
+
+# Bump to bust cached frontend assets after a deploy.
 ASSET_VERSION=1
+
+# Where the user table lives. 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=./database/db.sqlite

package/templates/react/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 forgot/reset pages.
+ *
+ * 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"}/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/react/app/models/User.ts

@@ -0,0 +1,17 @@
+import { BaseModel, column, table } from "zerotal/orm";
+
+@table("users")
+export class User extends BaseModel {
+  // 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.
+  static override fillable = ["name", "email", "password"];
+
+  // Never serialised into a rendered page or a JSON response.
+  static override hidden = ["password"];
+
+  @column({ type: "string" }) name!: string;
+  @column({ type: "string" }) email!: string;
+  @column({ type: "string" }) password!: string;
+  @column({ type: "string", nullable: true, default: "user" }) role?: string;
+}

package/templates/react/app/routes/forgot-password.ts

@@ -0,0 +1,24 @@
+import type { HttpContext } from "zerotal";
+import { Inertia } from "@zerotal/inertia";
+import { GuestMiddleware } from "zerotal/auth";
+import { validate } from "zerotal/validator";
+import { passwordReset } from "@app/auth/passwords";
+
+export const middleware = [GuestMiddleware];
+
+export const GET = async () => {
+  return Inertia.render("forgot-password", { title: "Reset your password" });
+};
+
+export async function POST(http: HttpContext): Promise<void> {
+  const { email } = await validate(http, (r) => ({
+    email: r.string().trim().email(),
+  }));
+
+  await passwordReset.sendResetLink(email);
+
+  // The same answer whether or not that address has an account — reporting "no
+  // such user" would make this form a way to enumerate registered addresses.
+  http.flash("success", "If that address has an account, a reset link is on its way.");
+  http.redirect("/forgot-password", 303);
+}