create-zerotal 1.0.0 → 1.0.2

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"
+  ]
 }

package/templates/flow/README.md

@@ -0,0 +1,39 @@
+# {{name}}
+
+A server-driven UI built with Flow: pages render on the server and stream patches over a WebSocket, so there is no API to maintain.
+
+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/flow/_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
+
+# 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/flow/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/flow/app/flow/layouts/app.tsx

@@ -1,6 +1,7 @@
 import { Layout, Link } from "@zerotal/flow";
 import type { HtmlNode } from "@zerotal/flow";
 import { asset } from "zerotal/assets";
+import { Auth } from "zerotal/auth";
 
 const NAV = [
   { href: "/", label: "Home" },
@@ -8,6 +9,14 @@ const NAV = [
   { href: "/contact", label: "Contact" },
 ];
 
+// Shown to signed-in visitors and guests respectively, so the header always
+// offers the next useful step rather than a link that would bounce them.
+const AUTHED_NAV = [{ href: "/profile", label: "Profile" }];
+const GUEST_NAV = [
+  { href: "/login", label: "Sign in" },
+  { href: "/register", label: "Register" },
+];
+
 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
@@ -36,7 +45,7 @@ export class AppLayout extends Layout {
             </Link>
 
             <div class="flex items-center gap-1">
-              {NAV.map((item) => (
+              {[...NAV, ...(Auth.check() ? AUTHED_NAV : GUEST_NAV)].map((item) => (
                 <Link href={item.href} hover class={navLink}>
                   {item.label}
                 </Link>

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

@@ -0,0 +1,69 @@
+import { Component, expose, 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, NOTICE } from "../ui";
+
+export const middleware = [GuestMiddleware];
+
+export class ForgotPasswordPage extends Component {
+  static layout = AppLayout;
+  static title = "Reset your password";
+
+  @expose email = "";
+  @expose sent = false;
+
+  @expose async send(): Promise<void> {
+    await passwordReset.sendResetLink(this.email);
+
+    // Always the same outcome, whether or not the address has an account.
+    // Reporting "no such user" here would make this form a way to enumerate
+    // which addresses are registered.
+    this.sent = true;
+  }
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <section class={CARD}>
+        <h1 class="text-2xl font-bold tracking-tight">Reset your password</h1>
+        <p class="mt-1 text-sm text-gray-600">
+          Give us the address you signed up with and we will send a link.
+        </p>
+
+        {this.sent ? (
+          <p class={`${NOTICE} mt-6`}>
+            If that address has an account, a reset link is on its way. In development the link is
+            written to the server log rather than emailed.
+          </p>
+        ) : (
+          <form onSubmit={this.send} class="mt-6 space-y-4">
+            <div>
+              <label class={LABEL} for="email">
+                Email
+              </label>
+              <input
+                id="email"
+                type="email"
+                autocomplete="email"
+                required
+                class={FIELD}
+                value={this.email}
+              />
+            </div>
+
+            <button type="submit" class={PRIMARY}>
+              Send reset link
+            </button>
+          </form>
+        )}
+
+        <p class="mt-6 text-sm text-gray-600">
+          <Link href="/login" class="text-indigo-600 hover:underline">
+            Back to sign in
+          </Link>
+        </p>
+      </section>
+    );
+  }
+}

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

@@ -0,0 +1,88 @@
+import { Component, expose, Link } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { Auth, GuestMiddleware } from "zerotal/auth";
+import { AppLayout } from "../layouts/app";
+import { FIELD, LABEL, PRIMARY, CARD, ERROR } from "../ui";
+
+// Signed-in visitors are sent away from the sign-in form rather than shown it.
+export const middleware = [GuestMiddleware];
+
+export class LoginPage extends Component {
+  static layout = AppLayout;
+  static title = "Sign in";
+
+  @expose email = "";
+  @expose password = "";
+  @expose remember = false;
+  @expose error = "";
+
+  @expose async login(): Promise<void> {
+    this.error = "";
+
+    const ok = await Auth.attempt(
+      { email: this.email, password: this.password },
+      Boolean(this.remember),
+    );
+
+    if (!ok) {
+      // One message for a wrong address and a wrong password alike — saying
+      // which was wrong turns this form into a way to discover valid accounts.
+      this.error = "Those credentials do not match our records.";
+      return;
+    }
+
+    this.redirect("/profile").withSuccess("Welcome back.");
+  }
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <section class={CARD}>
+        <h1 class="text-2xl font-bold tracking-tight">Sign in</h1>
+        <p class="mt-1 text-sm text-gray-600">Enter your details to continue.</p>
+
+        <form onSubmit={this.login} class="mt-6 space-y-4">
+          {this.error ? <p class={ERROR}>{this.error}</p> : null}
+
+          <div>
+            <label class={LABEL} for="email">
+              Email
+            </label>
+            <input id="email" type="email" autocomplete="email" required class={FIELD} value={this.email} />
+          </div>
+
+          <div>
+            <label class={LABEL} for="password">
+              Password
+            </label>
+            <input
+              id="password"
+              type="password"
+              autocomplete="current-password"
+              required
+              class={FIELD}
+              value={this.password}
+            />
+          </div>
+
+          <label class="flex items-center gap-2 text-sm text-gray-600">
+            <input type="checkbox" checked={this.remember} class="rounded border-gray-300" />
+            Remember me
+          </label>
+
+          <button type="submit" class={PRIMARY}>
+            Sign in
+          </button>
+        </form>
+
+        <div class="mt-6 flex items-center justify-between text-sm">
+          <Link href="/forgot-password" class="text-indigo-600 hover:underline">
+            Forgot your password?
+          </Link>
+          <Link href="/register" class="text-indigo-600 hover:underline">
+            Create an account
+          </Link>
+        </div>
+      </section>
+    );
+  }
+}

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

@@ -0,0 +1,194 @@
+import { Component, expose } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { Auth, AuthMiddleware, Hash } from "zerotal/auth";
+import { User } from "@app/models/User";
+import { AppLayout } from "../layouts/app";
+import { FIELD, LABEL, PRIMARY, SECONDARY, CARD, ERROR, NOTICE } from "../ui";
+
+// Only for signed-in visitors; everyone else is sent to the sign-in form.
+export const middleware = [AuthMiddleware];
+
+export class ProfilePage extends Component {
+  static layout = AppLayout;
+  static title = "Your profile";
+
+  @expose name = "";
+  @expose email = "";
+  @expose detailsError = "";
+  @expose detailsSaved = false;
+
+  @expose currentPassword = "";
+  @expose password = "";
+  @expose passwordConfirmation = "";
+  @expose passwordError = "";
+  @expose passwordSaved = false;
+
+  /** Seed the form from the signed-in user on first render. */
+  async onMount(): Promise<void> {
+    const user = Auth.user() as User;
+    this.name = user.name;
+    this.email = user.email;
+  }
+
+  @expose async saveDetails(): Promise<void> {
+    this.detailsError = "";
+    this.detailsSaved = false;
+
+    const user = Auth.user() as User;
+
+    if (this.name.trim() === "" || this.email.trim() === "") {
+      this.detailsError = "Name and email are required.";
+      return;
+    }
+
+    // Someone else holding this address is the one case that must be rejected;
+    // keeping your own is not a conflict.
+    const taken = await User.query().where("email", this.email).first();
+    if (taken && taken.id !== user.id) {
+      this.detailsError = "That email is already in use.";
+      return;
+    }
+
+    user.name = this.name;
+    user.email = this.email;
+    await user.save();
+
+    this.detailsSaved = true;
+  }
+
+  @expose async changePassword(): Promise<void> {
+    this.passwordError = "";
+    this.passwordSaved = false;
+
+    const user = Auth.user() as User;
+
+    // Proving the current password is what stops a borrowed session from
+    // locking the real owner out of their account.
+    if (!(await Hash.check(this.currentPassword, user.password))) {
+      this.passwordError = "Your current password is not correct.";
+      return;
+    }
+    if (this.password.length < 8) {
+      this.passwordError = "Choose a password of at least 8 characters.";
+      return;
+    }
+    if (this.password !== this.passwordConfirmation) {
+      this.passwordError = "The two passwords do not match.";
+      return;
+    }
+
+    user.password = await Hash.make(this.password);
+    await user.save();
+
+    this.currentPassword = "";
+    this.password = "";
+    this.passwordConfirmation = "";
+    this.passwordSaved = true;
+  }
+
+  @expose async signOut(): Promise<void> {
+    await Auth.logout();
+    this.redirect("/login").withSuccess("Signed out.");
+  }
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <div class="mx-auto w-full max-w-lg space-y-6">
+        <div>
+          <h1 class="text-3xl font-bold tracking-tight">Your profile</h1>
+          <p class="mt-1 text-gray-600">Update your details or change your password.</p>
+        </div>
+
+        <section class={CARD}>
+          <h2 class="text-lg font-semibold">Details</h2>
+
+          <form onSubmit={this.saveDetails} class="mt-4 space-y-4">
+            {this.detailsError ? <p class={ERROR}>{this.detailsError}</p> : null}
+            {this.detailsSaved ? <p class={NOTICE}>Details saved.</p> : null}
+
+            <div>
+              <label class={LABEL} for="name">
+                Name
+              </label>
+              <input id="name" type="text" required class={FIELD} value={this.name} />
+            </div>
+
+            <div>
+              <label class={LABEL} for="email">
+                Email
+              </label>
+              <input id="email" type="email" required class={FIELD} value={this.email} />
+            </div>
+
+            <button type="submit" class={PRIMARY}>
+              Save details
+            </button>
+          </form>
+        </section>
+
+        <section class={CARD}>
+          <h2 class="text-lg font-semibold">Password</h2>
+
+          <form onSubmit={this.changePassword} class="mt-4 space-y-4">
+            {this.passwordError ? <p class={ERROR}>{this.passwordError}</p> : null}
+            {this.passwordSaved ? <p class={NOTICE}>Password updated.</p> : null}
+
+            <div>
+              <label class={LABEL} for="current_password">
+                Current password
+              </label>
+              <input
+                id="current_password"
+                type="password"
+                autocomplete="current-password"
+                required
+                class={FIELD}
+                value={this.currentPassword}
+              />
+            </div>
+
+            <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 new password
+              </label>
+              <input
+                id="password_confirmation"
+                type="password"
+                autocomplete="new-password"
+                required
+                class={FIELD}
+                value={this.passwordConfirmation}
+              />
+            </div>
+
+            <button type="submit" class={PRIMARY}>
+              Change password
+            </button>
+          </form>
+        </section>
+
+        <section class={CARD}>
+          <h2 class="text-lg font-semibold">Session</h2>
+          <p class="mt-1 text-sm text-gray-600">Sign out of this browser.</p>
+          <button type="button" onClick={this.signOut} class={`${SECONDARY} mt-4`}>
+            Sign out
+          </button>
+        </section>
+      </div>
+    );
+  }
+}

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

@@ -0,0 +1,120 @@
+import { Component, expose, Link } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { Auth, GuestMiddleware, Hash } from "zerotal/auth";
+import { User } from "@app/models/User";
+import { AppLayout } from "../layouts/app";
+import { FIELD, LABEL, PRIMARY, CARD, ERROR } from "../ui";
+
+export const middleware = [GuestMiddleware];
+
+export class RegisterPage extends Component {
+  static layout = AppLayout;
+  static title = "Create an account";
+
+  @expose name = "";
+  @expose email = "";
+  @expose password = "";
+  @expose passwordConfirmation = "";
+  @expose error = "";
+
+  @expose async register(): Promise<void> {
+    this.error = "";
+
+    if (this.name.trim() === "" || this.email.trim() === "") {
+      this.error = "Name and email are required.";
+      return;
+    }
+    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 taken = await User.query().where("email", this.email).first();
+    if (taken) {
+      this.error = "That email is already registered.";
+      return;
+    }
+
+    // `role` is not fillable, so it cannot arrive from the form at all — it is
+    // set here, in code, which is the whole point of leaving it off `fillable`.
+    const user = new User();
+    user.name = this.name;
+    user.email = this.email;
+    user.password = await Hash.make(this.password);
+    user.role = "user";
+    await user.save();
+
+    await Auth.attempt({ email: this.email, password: this.password });
+    this.redirect("/profile").withSuccess("Welcome aboard.");
+  }
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <section class={CARD}>
+        <h1 class="text-2xl font-bold tracking-tight">Create an account</h1>
+        <p class="mt-1 text-sm text-gray-600">It takes about ten seconds.</p>
+
+        <form onSubmit={this.register} class="mt-6 space-y-4">
+          {this.error ? <p class={ERROR}>{this.error}</p> : null}
+
+          <div>
+            <label class={LABEL} for="name">
+              Name
+            </label>
+            <input id="name" type="text" autocomplete="name" required class={FIELD} value={this.name} />
+          </div>
+
+          <div>
+            <label class={LABEL} for="email">
+              Email
+            </label>
+            <input id="email" type="email" autocomplete="email" required class={FIELD} value={this.email} />
+          </div>
+
+          <div>
+            <label class={LABEL} for="password">
+              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}>
+            Create account
+          </button>
+        </form>
+
+        <p class="mt-6 text-sm text-gray-600">
+          Already registered?{" "}
+          <Link href="/login" class="text-indigo-600 hover:underline">
+            Sign in
+          </Link>
+        </p>
+      </section>
+    );
+  }
+}