create-zerotal 1.0.0

package/templates/admin/app/admin/SettingsResource.ts

@@ -0,0 +1,37 @@
+import { Resource, text, textInput, toggle, formSection } from "@zerotal/admin";
+import { Setting } from "@app/models/Setting";
+
+/**
+ * Site settings — one row, edited directly.
+ *
+ * `singular` collapses the usual list → view → edit chain into a single route:
+ * `/admin/settings` opens the form. There is nothing to list when there is only
+ * ever one record, and no id worth putting in a URL.
+ */
+export class SettingsResource extends Resource {
+  static override model = Setting;
+  static override singular = true;
+  static override slug = "settings";
+  static override label = "Settings";
+  static override pluralLabel = "Settings";
+  static override navigationIcon = "shield";
+  static override navigationGroup = "System";
+  static override navigationSort = 99;
+
+  static override columns() {
+    return [text("siteName").label("Site name")];
+  }
+
+  static override form() {
+    return [
+      formSection("Identity")
+        .description("How the site presents itself")
+        .columns(2)
+        .schema([
+          textInput("siteName").label("Site name").required().default("My Shop").maxLength(80),
+          textInput("supportEmail").label("Support email").email().default("support@example.com"),
+          toggle("ordersOpen").label("Accepting orders").default(true).columnSpan(2),
+        ]),
+    ];
+  }
+}

package/templates/admin/app/admin/UserResource.ts

@@ -0,0 +1,103 @@
+import {
+  Resource,
+  text,
+  imageColumn,
+  textInput,
+  select,
+  formSection,
+  section,
+  textEntry,
+  imageEntry,
+  createAction,
+  exportAction,
+} from "@zerotal/admin";
+import { Hash } from "zerotal/auth";
+import { User } from "@app/models/User";
+import { humanDate } from "@app/admin/shared";
+
+const ROLES = {
+  admin: "Administrator",
+  editor: "Editor",
+  support: "Support",
+  viewer: "Viewer",
+};
+
+/** Panel users. Sits outside every cluster — access is nobody's business area. */
+export class UserResource extends Resource {
+  static override model = User;
+  static override navigationIcon = "shield";
+  static override navigationGroup = "System";
+  static override navigationSort = 90;
+  static override recordTitleAttribute = "name";
+  static override defaultSort = { column: "created_at", direction: "desc" as const };
+
+  static override headerActions() {
+    return [createAction(), exportAction()];
+  }
+
+  static override columns() {
+    return [
+      imageColumn("avatarUrl").label("").circular().exportable(false),
+      text("name").searchable().sortable(),
+      text("email").searchable().copyable(),
+      text("roles")
+        .label("Roles")
+        .format((v) => (Array.isArray(v) && v.length > 0 ? v.join(", ") : "—")),
+      text("createdAt")
+        .label("Joined")
+        .sortable()
+        .format((v) => humanDate(v)),
+    ];
+  }
+
+  static override form() {
+    return [
+      formSection("Identity")
+        .columns(2)
+        .schema([
+          textInput("name").required().minLength(2).maxLength(120).autocomplete("name"),
+          textInput("email").email().required().maxLength(160).autocomplete("email"),
+          textInput("avatarUrl").label("Avatar URL").url().columnSpan(2),
+          select("roles").label("Roles").multiple().searchable().options(ROLES).columnSpan(2),
+        ]),
+      formSection("Security").schema([
+        // Only asked for on create, and hashed on the way to the database — the
+        // panel never holds a plaintext password.
+        textInput("password")
+          .password()
+          .required()
+          .minLength(8)
+          .helperText("At least 8 characters.")
+          .visibleOn("create")
+          .columnSpan(2)
+          .mutate((value) => Hash.make(String(value))),
+      ]),
+    ];
+  }
+
+  static override infolist() {
+    return [
+      section("Profile")
+        .icon("shield")
+        .columns(2)
+        .schema([
+          imageEntry("avatarUrl").label("Avatar").circular().height(64),
+          textEntry("name").weight("semibold").size("lg"),
+          textEntry("email").icon("mail").copyable(),
+          textEntry("roles")
+            .label("Roles")
+            .format((v) => (Array.isArray(v) && v.length > 0 ? v.join(", ") : "—")),
+          textEntry("createdAt").label("Joined").icon("calendar").since(),
+        ]),
+    ];
+  }
+
+  static override emptyState() {
+    return {
+      heading: "No users yet",
+      description: "Invite the people who will run this panel.",
+      icon: "shield",
+      actions: [createAction()],
+    };
+  }
+}

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

@@ -0,0 +1,46 @@
+// Admin panel wiring. AdminProvider loads this file on boot, so every
+// Panel.configure / register call below runs once at startup.
+//
+// This is the whole application: there is no file-based routing and no
+// hand-written pages. Add a resource, register it here, and its list, view,
+// create and edit pages exist.
+//
+// One panel is enough for most apps. If you ever need a second audience on a
+// second path, `Panel.make("console", { path: "/app" })` gives you an
+// independent registry that shares this one's models and sign-in.
+import { Panel } from "@zerotal/admin";
+import { AuthMiddleware, GuestMiddleware } from "zerotal/auth";
+
+import { ProductResource } from "@app/admin/ProductResource";
+import { UserResource } from "@app/admin/UserResource";
+import { SettingsResource } from "@app/admin/SettingsResource";
+import { dashboardWidgets } from "@app/admin/widgets";
+
+Panel.configure({
+  brand: "{{name}}",
+  tagline: "Admin",
+  path: "/admin",
+  // Every panel route is behind a signed-in session, and the guard sends people
+  // to the panel's own login rather than the framework default. Without a
+  // `middleware` here the panel refuses to serve outside local development —
+  // it exposes full CRUD, so the safe default is closed.
+  middleware: [AuthMiddleware.with({ redirectTo: "/admin/login" })],
+  userMenu: {
+    label: "Account",
+    items: [
+      { label: "Profile", href: "/admin/profile", icon: "users" },
+      { label: "Settings", href: "/admin/settings", icon: "shield" },
+    ],
+  },
+});
+
+// The panel's own login and profile screens.
+Panel.auth({
+  enabled: true,
+  heading: "{{name}}",
+  guestMiddleware: [GuestMiddleware],
+});
+
+Panel.widgets(...dashboardWidgets());
+
+Panel.register(ProductResource, UserResource, SettingsResource);

package/templates/admin/app/admin/shared.ts

@@ -0,0 +1,36 @@
+/** Formatting helpers shared by the resources. */
+
+/** Render minor units as money — prices are stored as integers, never floats. */
+export function money(value: unknown, currency = "USD"): string {
+  const cents = Number(value);
+  if (!Number.isFinite(cents)) return "—";
+  return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(cents / 100);
+}
+
+/** Trim a value to `n` characters with an ellipsis, for table cells. */
+export function excerpt(value: unknown, n = 60): string {
+  const s = String(value ?? "").trim();
+  if (!s) return "—";
+  return s.length > n ? `${s.slice(0, n).trimEnd()}…` : s;
+}
+
+/** Make a URL slug from arbitrary text. */
+export function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80);
+}
+
+/** Coerce an empty form value to null, for nullable columns. */
+export function nullIfEmpty(value: unknown): unknown {
+  return value === "" || value == null ? null : value;
+}
+
+/** Format a timestamp column as a relative time. */
+export function humanDate(value: unknown): string {
+  const c = value as { diffForHumans?: () => string } | null | undefined;
+  return c?.diffForHumans ? c.diffForHumans() : "—";
+}

package/templates/admin/app/admin/widgets.ts

@@ -0,0 +1,51 @@
+import { statsWidget, stat, chartWidget } from "@zerotal/admin";
+import type { DashboardWidget } from "@zerotal/admin";
+import { Product } from "@app/models/Product";
+import { User } from "@app/models/User";
+import { money } from "@app/admin/shared";
+
+/**
+ * The dashboard. A widget is a data provider — the panel owns the markup — so
+ * these stay easy to read and easy to test.
+ *
+ * `.poll()` re-renders on an interval, which is worth it for numbers someone
+ * actually watches and wasteful for the rest.
+ */
+export function dashboardWidgets(): DashboardWidget[] {
+  return [
+    statsWidget(async () => {
+      const [products, active, users, value] = await Promise.all([
+        Product.count(),
+        Product.query().where("status", "active").count(),
+        User.count(),
+        Product.query()
+          .get()
+          .then((rows) =>
+            (rows as unknown as { price?: number; stock?: number }[]).reduce(
+              (sum, r) => sum + Number(r.price ?? 0) * Number(r.stock ?? 0),
+              0,
+            ),
+          ),
+      ]);
+
+      return [
+        stat("Products", products).icon("collection").tone("primary"),
+        stat("Active", active).icon("check-circle").tone("success"),
+        stat("Stock value", money(value)).icon("database"),
+        stat("Users", users).icon("users").tone("muted"),
+      ];
+    }).poll("30s"),
+
+    chartWidget("Catalogue by status", async () => {
+      const statuses = ["draft", "active", "discontinued"];
+      const counts = await Promise.all(
+        statuses.map((s) => Product.query().where("status", s).count()),
+      );
+      return {
+        type: "doughnut",
+        labels: ["Draft", "Active", "Discontinued"],
+        datasets: [{ data: counts }],
+      };
+    }),
+  ];
+}

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

@@ -0,0 +1,21 @@
+import { BaseModel, column, table } from "zerotal/orm";
+
+/**
+ * Something the shop sells. Soft-deleted, so a discontinued product can be
+ * restored rather than lost.
+ */
+@table("products")
+export class Product extends BaseModel {
+  static override softDeletes = true;
+  static override fillable = ["name", "sku", "description", "price", "stock", "status", "featured"];
+
+  @column() name!: string;
+  @column() sku!: string;
+  @column({ nullable: true }) description?: string;
+  /** Price in minor units, so money never rides on a float. */
+  @column("integer") price!: number;
+  @column({ cast: "integer", nullable: true }) stock?: number;
+  /** draft | active | discontinued — drives the filter tabs and a select column. */
+  @column({ nullable: true }) status?: string;
+  @column({ cast: "boolean", nullable: true }) featured?: boolean;
+}

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

@@ -0,0 +1,14 @@
+import { BaseModel, column, table } from "zerotal/orm";
+
+/**
+ * Site-wide configuration — exactly one row, edited through a singular resource
+ * rather than a list. See `app/admin/SettingsResource.ts`.
+ */
+@table("settings")
+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;
+}

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

@@ -0,0 +1,20 @@
+import { BaseModelWith, column, table } from "zerotal/orm";
+import { Authenticatable } from "zerotal/auth";
+
+/**
+ * A person who signs into the panel. Also the author side of the blog: posts
+ * belong to a user.
+ */
+@table("users")
+export class User extends BaseModelWith(Authenticatable) {
+  static override hidden = ["password"];
+  static override fillable = ["name", "email", "password", "roles", "avatarUrl"];
+
+  @column() name!: string;
+  @column() email!: string;
+  @column() password!: string;
+  /** Assigned roles — drives a multi-select field and a badge column. */
+  @column({ cast: "json", nullable: true }) roles?: string[];
+  /** Profile picture, shown as a circular image entry on the view page. */
+  @column({ nullable: true }) avatarUrl?: string;
+}

package/templates/admin/bootstrap/app.ts

@@ -0,0 +1,16 @@
+import { Application } 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 {}
+}
+
+// No file-based routing: this app is the admin panel. AdminProvider loads
+// `app/admin/index.ts` on boot and mounts every route from what it registers.
+const app = Application.create({ providers });
+
+export default app;

package/templates/admin/bootstrap/providers.ts

@@ -0,0 +1,23 @@
+import { LogProvider } from "zerotal/logger";
+import { DatabaseProvider } from "zerotal/orm";
+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";
+
+// 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.
+const providers = [
+  LogProvider,
+  DatabaseProvider,
+  CacheProvider,
+  SessionProvider,
+  AuthProvider,
+  FlowProvider,
+  AdminProvider,
+];
+
+export default providers;

package/templates/admin/config/app.ts

@@ -0,0 +1,22 @@
+import { env, requireEnv } from "zerotal";
+import { AppConfig } from "zerotal/config";
+
+export default AppConfig({
+  name: "{{name}}",
+  url: env("APP_URL", "http://localhost:3000"),
+  /**
+   * The APP_KEY is used for encryption (and signs the session cookie) and should be
+   * a random 32 character string. Use `bun zt key:generate` to generate a secure key.
+   */
+  key: requireEnv("APP_KEY"),
+
+  cors: {
+    origin: env("CORS_ORIGIN", "*"),
+    credentials: false,
+  },
+
+  throttle: {
+    maxAttempts: 120,
+    windowSeconds: 60,
+  },
+});

package/templates/admin/config/auth.ts

@@ -0,0 +1,5 @@
+import { AuthConfig } from "zerotal/auth";
+
+export default AuthConfig({
+  algorithm: "argon2id", // 'argon2id' (default) | 'bcrypt'
+});

package/templates/admin/config/cache.ts

@@ -0,0 +1,7 @@
+import { CacheConfig } from "zerotal/cache";
+
+// The panel caches its navigation-badge counts here, invalidating them on every
+// write. In-memory suits a demo; swap the driver for redis in production.
+export default CacheConfig({
+  driver: "memory",
+});

package/templates/admin/config/database.ts

@@ -0,0 +1,14 @@
+import { env } from "zerotal";
+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")),
+
+  // 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
+  // in production, where you run generated migrations instead.
+  synchronize: env("APP_ENV", "local") !== "production",
+});

package/templates/admin/config/session.ts

@@ -0,0 +1,10 @@
+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: env("SESSION_COOKIE", "zerotal_session"),
+  lifetime: 60 * 24 * 7,
+});

package/templates/admin/database/seeders/DatabaseSeeder.ts

@@ -0,0 +1,50 @@
+import { Seeder } from "zerotal/orm";
+import { Hash } from "zerotal/auth";
+import { User } from "@app/models/User";
+import { Setting } from "@app/models/Setting";
+import { Product } from "@app/models/Product";
+
+/**
+ * Demo data, so the panel has something to show on the first run.
+ *
+ * Deterministic on purpose — a reseed produces the same catalogue rather than
+ * noise. Run it with `bun run seed`.
+ */
+export class DatabaseSeeder extends Seeder {
+  async run(): Promise<void> {
+    await User.create({
+      name: "Admin",
+      email: "admin@example.com",
+      password: await Hash.make("password"),
+      roles: ["admin"],
+    });
+
+    await Setting.create({
+      siteName: "{{name}}",
+      supportEmail: "support@example.com",
+      ordersOpen: true,
+    });
+
+    const names = [
+      "Desk Lamp",
+      "Mechanical Keyboard",
+      "USB-C Hub",
+      "Standing Desk",
+      "Monitor Arm",
+      "Laptop Stand",
+    ];
+    const statuses = ["active", "active", "draft", "discontinued"];
+
+    for (const [i, name] of names.entries()) {
+      await Product.create({
+        name,
+        sku: `SKU-${String(1000 + i)}`,
+        description: `A dependable ${name.toLowerCase()} for everyday work.`,
+        price: 1999 + i * 1500,
+        stock: i % 5 === 0 ? 4 : 12 + i * 3,
+        status: statuses[i % statuses.length]!,
+        featured: i % 3 === 0,
+      });
+    }
+  }
+}

package/templates/admin/package.json

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

package/templates/admin/tests/admin_test.ts

@@ -0,0 +1,58 @@
+import { beforeAll, describe, test, expect } from "bun:test";
+import { createTestApp, type TestApp } from "zerotal/testing";
+import { Panel } from "@zerotal/admin";
+import { User } from "@app/models/User.ts";
+import { Product } from "@app/models/Product.ts";
+
+// Boots the real app: AdminProvider auto-loads app/admin/index.ts and mounts
+// the panel, so these tests exercise the wiring the browser gets.
+let app: TestApp;
+let staff: User;
+
+beforeAll(async () => {
+  Bun.env.APP_KEY ??= "test-app-key-aaaaaaaaaaaaaaaaaaaaaaaa";
+  app = await createTestApp(() => import("../bootstrap/app.ts").then((m) => m.default));
+
+  staff = await User.create({
+    name: "Ada Admin",
+    email: `staff-${Date.now()}@example.com`,
+    password: "password",
+    roles: ["admin"],
+  });
+});
+
+describe("the panel", () => {
+  test("registers the resources", () => {
+    expect(Panel.default().resources().map((r) => r.getSlug()).sort()).toEqual([
+      "products",
+      "settings",
+      "users",
+    ]);
+  });
+
+  test("sends guests to the login page", async () => {
+    const res = await app.actingAsGuest().get("/admin", { Accept: "text/html" });
+    res.assertRedirect("/admin/login");
+  });
+
+  test("shows the dashboard to a signed-in user", async () => {
+    const res = await app.actingAs(staff).get("/admin", { Accept: "text/html" });
+    res.assertOk();
+    res.assertSee("Products");
+  });
+
+  test("lists products with their filter tabs", async () => {
+    await Product.create({ name: "Test Widget", sku: "SKU-T1", price: 4999, status: "active" });
+
+    const res = await app.actingAs(staff).get("/admin/products", { Accept: "text/html" });
+    res.assertOk();
+    res.assertSee("Test Widget");
+    res.assertSee("Drafts"); // a filter tab
+  });
+
+  test("opens settings straight onto its form, with no record id", async () => {
+    const res = await app.actingAs(staff).get("/admin/settings", { Accept: "text/html" });
+    res.assertOk();
+    res.assertSee("Site name");
+  });
+});

package/templates/admin/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "emitDecoratorMetadata": false,
+    "jsx": "react-jsx",
+    "jsxImportSource": "@zerotal/flow",
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "paths": {
+      "@app/*": ["./app/*"]
+    }
+  },
+  "exclude": ["node_modules", ".zerotal"]
+}

package/templates/admin/zt.ts

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

package/templates/api/_env.example

@@ -0,0 +1,4 @@
+APP_ENV=development
+APP_KEY={{app_key}}
+DATABASE_URL={{db_url}}
+SESSION_SECRET={{session_secret}}

package/templates/api/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.zerotal/
+*.sqlite
+.env
+public/assets/