create-zerotal 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# 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
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `stable`**
+
+## [Unreleased]
+
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Notes
+- Conforms to the Zerotal package conventions (provider in `src/provider/`, PascalCase config factory, `ZerotalError`-based errors, test coverage).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# create-zerotal
+
+> Scaffold a new Zerotal application in seconds with `bun create zerotal`.
+
+`create-zerotal` is the interactive scaffolding CLI for the Zerotal framework. It prompts for a project name, a starter template, and (for the API template) a database, then generates the project and runs `bun install`.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+> **Bun is required.** The CLI entry (`src/index.ts`) uses a `#!/usr/bin/env bun` shebang and the Bun runtime APIs (`Bun.file`, `Bun.env`). It cannot run under Node — `npx create-zerotal` / `npm create zerotal` will fail; use `bun create zerotal`.
+
+## Usage
+
+```bash
+bun create zerotal my-app
+# or
+bunx create-zerotal my-app
+```
+
+The CLI is interactive: if you omit the project name it prompts for one (default `my-zerotal-app`), then asks you to choose a template and, for the `api` template, a database. It aborts rather than overwrite a directory that already contains a `package.json`.
+
+### Templates
+
+| Template  | Description                                                                   |
+| --------- | ----------------------------------------------------------------------------- |
+| `api`     | JSON REST API — core, ORM, auth, validation, testing. Prompts for a database. |
+| `admin`   | Admin panel — resources, auth, dashboard widgets, seeded demo data.           |
+| `flow`  | Server-driven UI — Flow pages, top nav, Tailwind.                           |
+| `react`   | Inertia + React SPA — file-based routes, Tailwind.                            |
+| `vue`     | Inertia + Vue SPA — file-based routes, Tailwind.                              |
+| `minimal` | Single page, JSX views, Tailwind — the bare framework.                        |
+
+### Databases (api template only)
+
+| Choice     | Notes                                               |
+| ---------- | --------------------------------------------------- |
+| `sqlite`   | Zero setup, file-based — great for getting started. |
+| `postgres` | Requires a `DATABASE_URL` env var.                  |
+| `mysql`    | Requires a `DATABASE_URL` env var.                  |
+
+### Next steps
+
+After scaffolding, the CLI prints the next commands:
+
+```bash
+cd my-app
+# (set DATABASE_URL in .env for a non-sqlite api project)
+bun zt migrate   # api template only
+bun zt db:seed   # admin template — demo data plus the first account
+bun zt serve --dev
+```
+
+The `admin` template's panel is behind a sign-in, so seeding is what makes a fresh
+app usable rather than a locked door: it creates `admin@example.com` with the
+password `password`, alongside a small demo catalogue. Open `/admin`.
+
+## Documentation
+
+- [Scaffolding](../../docs/scaffolding.md)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "create-zerotal",
+  "version": "1.0.0",
+  "description": "Create a new Zerotal application",
+  "license": "MIT",
+  "maturity": "stable",
+  "type": "module",
+  "bin": {
+    "create-zerotal": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "templates",
+    "!src/**/*.test.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "scaffold",
+    "cli",
+    "create"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/create-zerotal"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/create-zerotal#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/index.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+/**
+ * create-zerotal — Zerotal application scaffolder
+ *
+ * Usage:
+ *   bun create zerotal my-app
+ *   bunx create-zerotal my-app
+ */
+
+import { resolve } from 'node:path';
+import { printBanner, ask, choose, log, info, warn, step, dim, c } from './prompts.ts';
+import { scaffold, install, type Template, type Database } from './scaffold.ts';
+
+async function main(): Promise<void> {
+  printBanner();
+
+  // ── Project name ────────────────────────────────────────────────────────────
+  const nameArg = process.argv[2]?.trim() ?? '';
+  const name    = nameArg
+    || await ask('Project name', 'my-zerotal-app');
+
+  const target = resolve(process.cwd(), name);
+
+  // Guard: don't overwrite an existing non-empty directory
+  const existing = await Bun.file(target + '/package.json').exists();
+  if (existing) {
+    warn(`Directory already contains a package.json — aborting to avoid overwrite.`);
+    process.exit(1);
+  }
+
+  // ── Template ────────────────────────────────────────────────────────────────
+  log('');
+  const template = await choose<Template>('Template', [
+    {
+      value:       'api',
+      label:       'API',
+      description: 'JSON REST API — core, ORM, auth, validation, testing',
+    },
+    {
+      value:       'admin',
+      label:       'Admin',
+      description: 'Admin panel — resources, auth, dashboard widgets, seeded demo data',
+    },
+    {
+      value:       'flow',
+      label:       'Flow',
+      description: 'Server-driven UI — Flow pages, top nav, Tailwind',
+    },
+    {
+      value:       'react',
+      label:       'React',
+      description: 'Inertia + React SPA — file-based routes, Tailwind',
+    },
+    {
+      value:       'vue',
+      label:       'Vue',
+      description: 'Inertia + Vue SPA — file-based routes, Tailwind',
+    },
+    {
+      value:       'minimal',
+      label:       'Minimal',
+      description: 'Single page, JSX views, Tailwind — bare framework',
+    },
+  ]);
+
+  // ── Database ─────────────────────────────────────────────────────────────────
+  // Only the API template ships a database config; minimal/flow have no DB.
+  let db: Database = 'sqlite';
+  if (template === 'api') {
+    log('');
+    db = await choose<Database>('Database', [
+      {
+        value:       'sqlite',
+        label:       'SQLite',
+        description: 'Zero setup, file-based — great for getting started',
+      },
+      {
+        value:       'postgres',
+        label:       'PostgreSQL',
+        description: 'Requires DATABASE_URL env var',
+      },
+      {
+        value:       'mysql',
+        label:       'MySQL',
+        description: 'Requires DATABASE_URL env var',
+      },
+    ]);
+  }
+
+  // ── Scaffold ────────────────────────────────────────────────────────────────
+  log('');
+  step(`Scaffolding ${c.bold}${name}${c.reset} (${template})…`);
+
+  await scaffold({ name, template, db, target });
+  info(`Project files created`);
+
+  // ── Install ─────────────────────────────────────────────────────────────────
+  log('');
+  step('Installing dependencies…');
+  const ok = await install(target);
+  if (ok) {
+    info(`Dependencies installed`);
+  } else {
+    warn(`bun install failed — run it manually inside the project`);
+  }
+
+  // ── Done ─────────────────────────────────────────────────────────────────────
+  log('');
+  log(`${c.green}${c.bold}  ✓ Done!${c.reset}`);
+  log('');
+  log(`${c.bold}  Next steps:${c.reset}`);
+  dim(`cd ${name}`);
+  if (template === 'api') {
+    if (db !== 'sqlite') {
+      dim(`# Set DATABASE_URL in .env`);
+    }
+    dim(`bun zt migrate`);
+  }
+  if (template === 'admin') {
+    // The panel is behind a sign-in, so the demo data (which includes the first
+    // account) is what makes a fresh app usable rather than a locked door.
+    dim(`bun zt db:seed              # demo data + admin@example.com / password`);
+  }
+  dim(`bun zt serve --dev`);
+  if (template === 'admin') {
+    dim(`# then open http://localhost:3000/admin`);
+  }
+  log('');
+  log(`${c.gray}  Docs: https://zerotal.dev${c.reset}`);
+  log('');
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`\x1b[31mError: ${(err as Error).message}\x1b[0m\n`);
+  process.exit(1);
+});

package/src/prompts.ts

@@ -0,0 +1,81 @@
+import { createInterface } from 'node:readline';
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+
+export const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  green:  '\x1b[32m',
+  cyan:   '\x1b[36m',
+  yellow: '\x1b[33m',
+  blue:   '\x1b[34m',
+  gray:   '\x1b[90m',
+  white:  '\x1b[97m',
+};
+
+export function log(msg: string)  { process.stdout.write(msg + '\n'); }
+export function info(msg: string) { log(`${c.green}  ✓${c.reset}  ${msg}`); }
+export function warn(msg: string) { log(`${c.yellow}  ⚠${c.reset}  ${msg}`); }
+export function step(msg: string) { log(`${c.cyan}  ◆${c.reset}  ${c.bold}${msg}${c.reset}`); }
+export function dim(msg: string)  { log(`${c.gray}     ${msg}${c.reset}`); }
+
+// ── Banner ────────────────────────────────────────────────────────────────────
+
+export function printBanner(): void {
+  log('');
+  log(`${c.bold}${c.white}  ██╗  ██╗██╗   ██╗██╗      █████╗ ███╗   ██╗██╗${c.reset}`);
+  log(`${c.bold}${c.white}  ██║ ██╔╝██║   ██║██║     ██╔══██╗████╗  ██║██║${c.reset}`);
+  log(`${c.bold}${c.cyan}  █████╔╝ ██║   ██║██║     ███████║██╔██╗ ██║██║${c.reset}`);
+  log(`${c.bold}${c.cyan}  ██╔═██╗ ██║   ██║██║     ██╔══██║██║╚██╗██║██║${c.reset}`);
+  log(`${c.bold}${c.blue}  ██║  ██╗╚██████╔╝███████╗██║  ██║██║ ╚████║██║${c.reset}`);
+  log(`${c.bold}${c.blue}  ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝${c.reset}`);
+  log('');
+  log(`${c.gray}  Bun-native TypeScript framework${c.reset}`);
+  log('');
+}
+
+// ── Prompt primitives ─────────────────────────────────────────────────────────
+
+function rl(): ReturnType<typeof createInterface> {
+  return createInterface({
+    input:    process.stdin,
+    output:   process.stdout,
+    terminal: false,
+  });
+}
+
+export function ask(question: string, defaultValue = ''): Promise<string> {
+  return new Promise((resolve) => {
+    const hint = defaultValue ? ` ${c.gray}(${defaultValue})${c.reset}` : '';
+    process.stdout.write(`  ${c.cyan}?${c.reset}  ${question}${hint} `);
+    const iface = rl();
+    iface.once('line', (line) => {
+      iface.close();
+      resolve(line.trim() || defaultValue);
+    });
+  });
+}
+
+export function choose<T extends string>(
+  question: string,
+  options: Array<{ value: T; label: string; description?: string }>,
+): Promise<T> {
+  return new Promise((resolve) => {
+    log(`  ${c.cyan}?${c.reset}  ${question}`);
+    options.forEach(({ label, description }, i) => {
+      const idx = `${c.gray}[${i + 1}]${c.reset}`;
+      const desc = description ? ` ${c.gray}— ${description}${c.reset}` : '';
+      log(`     ${idx} ${label}${desc}`);
+    });
+    process.stdout.write(`  ${c.gray}Enter number (default 1):${c.reset} `);
+
+    const iface = rl();
+    iface.once('line', (line) => {
+      iface.close();
+      const n = parseInt(line.trim(), 10);
+      const idx = isNaN(n) || n < 1 || n > options.length ? 0 : n - 1;
+      resolve(options[idx]!.value);
+    });
+  });
+}

package/src/scaffold.ts

@@ -0,0 +1,104 @@
+import { join, dirname } from 'node:path';
+import { mkdir } from 'node:fs/promises';
+
+export type Database = 'sqlite' | 'postgres' | 'mysql';
+export type Template = 'minimal' | 'api' | 'admin' | 'flow' | 'react' | 'vue';
+
+// Version range stamped into scaffolded apps' `zerotal` / `@zerotal/*` dependencies.
+// Tracks the published framework release — bump this when the packages are
+// versioned for a release (see AUDIT_2 "Set real versions").
+export const ZT_VERSION = '^1.1.0';
+
+export interface ScaffoldOptions {
+  name:     string;
+  template: Template;
+  db:       Database;
+  target:   string; // absolute path of the new project directory
+}
+
+// ── Token map ─────────────────────────────────────────────────────────────────
+
+function randomBase64(bytes: number): string {
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(bytes))).toString('base64');
+}
+
+function tokens(opts: ScaffoldOptions): Record<string, string> {
+  const dbUrl: Record<Database, string> = {
+    sqlite:   './database/db.sqlite',
+    postgres: 'postgres://localhost/{{name}}',
+    mysql:    'mysql://root@localhost/{{name}}',
+  };
+
+  return {
+    '{{name}}':            opts.name,
+    '{{db_url}}':          dbUrl[opts.db].replace('{{name}}', opts.name),
+    '{{app_key}}':         randomBase64(32),
+    '{{session_secret}}':  randomBase64(32),
+    '{{db_driver}}':       opts.db,
+    '{{zerotal_version}}':  ZT_VERSION,
+  };
+}
+
+function applyTokens(content: string, map: Record<string, string>): string {
+  let out = content;
+  for (const [token, value] of Object.entries(map)) {
+    out = out.replaceAll(token, value);
+  }
+  return out;
+}
+
+// ── File walker ───────────────────────────────────────────────────────────────
+
+async function* walk(dir: string): AsyncGenerator<string> {
+  const glob = new Bun.Glob('**/*');
+  for await (const rel of glob.scan({ cwd: dir, onlyFiles: true })) {
+    yield rel;
+  }
+}
+
+// ── Scaffold ──────────────────────────────────────────────────────────────────
+
+export async function scaffold(opts: ScaffoldOptions): Promise<void> {
+  const templatesRoot = join(import.meta.dir, '..', 'templates');
+  const templateDir   = join(templatesRoot, opts.template);
+  const map           = tokens(opts);
+
+  for await (const rel of walk(templateDir)) {
+    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.
+    const dest = join(opts.target, rel
+      .replace('_gitignore',   '.gitignore')
+      .replace('_env.example', '.env.example')
+      .replace('_test.ts',     '.test.ts'),
+    );
+
+    await mkdir(dirname(dest), { recursive: true });
+
+    const raw     = await Bun.file(src).text();
+    const content = applyTokens(raw, map);
+    await Bun.write(dest, content);
+
+    // Also write a ready-to-run `.env` next to `.env.example`. The example
+    // already carries a freshly-generated APP_KEY/SESSION_SECRET, so a fresh
+    // app boots immediately without a manual `cp .env.example .env` +
+    // `key:generate` step (the old flow left APP_KEY empty on first boot).
+    if (dest.endsWith('.env.example')) {
+      await Bun.write(dest.replace(/\.env\.example$/, '.env'), content);
+    }
+  }
+}
+
+// ── Install ───────────────────────────────────────────────────────────────────
+
+export async function install(cwd: string): Promise<boolean> {
+  const proc = Bun.spawn(['bun', 'install'], {
+    cwd,
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const code = await proc.exited;
+  return code === 0;
+}

package/templates/admin/_env.example

@@ -0,0 +1,2 @@
+APP_ENV=development
+APP_KEY={{app_key}}

package/templates/admin/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.zerotal/
+*.sqlite
+.env

package/templates/admin/app/admin/ProductResource.ts

@@ -0,0 +1,192 @@
+import {
+  Resource,
+  text,
+  toggleColumn,
+  selectColumn,
+  textInput,
+  textarea,
+  toggle,
+  select,
+  formSection,
+  section,
+  textEntry,
+  iconEntry,
+  tab,
+  queryBuilder,
+  textConstraint,
+  numberConstraint,
+  selectConstraint,
+  booleanConstraint,
+  action,
+  actionGroup,
+  viewAction,
+  editAction,
+  deleteAction,
+  replicateAction,
+  createAction,
+  exportAction,
+  importAction,
+  bulkExportAction,
+  bulkDeleteAction,
+} from "@zerotal/admin";
+import type { AdminRecord } from "@zerotal/admin";
+import { Product } from "@app/models/Product";
+import { money } from "@app/admin/shared";
+
+const STATUS = { draft: "Draft", active: "Active", discontinued: "Discontinued" };
+
+/**
+ * The catalogue — the resource to copy when you add your own.
+ *
+ * It shows the parts of a table that most resources end up wanting: filter tabs
+ * with live counts, a build-your-own filter, footer summaries, an overflow menu
+ * for the occasional actions, CSV import/export, and soft deletes.
+ */
+export class ProductResource extends Resource {
+  static override model = Product;
+  static override navigationIcon = "collection";
+  static override navigationSort = 1;
+  static override recordTitleAttribute = "name";
+  static override defaultSort = { column: "created_at", direction: "desc" as const };
+
+  /** A count beside the sidebar entry. Cached, and refreshed on every write. */
+  static override navigationBadge() {
+    return this.count((q) => q.where("status", "active"));
+  }
+
+  static override tabs() {
+    return [
+      tab("all").label("All").badge(),
+      tab("active")
+        .label("Active")
+        .badge()
+        .badgeColor("success")
+        .modifyQuery((q) => q.where("status", "active")),
+      tab("draft")
+        .label("Drafts")
+        .badge()
+        .badgeColor("muted")
+        .modifyQuery((q) => q.where("status", "draft")),
+    ];
+  }
+
+  static override filters() {
+    return [
+      queryBuilder("q")
+        .label("Advanced filter")
+        .constraints([
+          textConstraint("name"),
+          textConstraint("sku").label("SKU"),
+          numberConstraint("price").label("Price (cents)"),
+          numberConstraint("stock"),
+          selectConstraint("status").options(STATUS),
+          booleanConstraint("featured"),
+        ]),
+    ];
+  }
+
+  static override headerActions() {
+    return [createAction(), exportAction(), importAction()];
+  }
+
+  static override bulkActions() {
+    return [bulkExportAction(), bulkDeleteAction()];
+  }
+
+  static override recordActions() {
+    return [
+      viewAction(),
+      editAction(),
+      // Occasional and destructive actions go behind one menu, so the row keeps
+      // two buttons rather than five.
+      actionGroup([
+        replicateAction()
+          .excludeAttributes(["sku"])
+          .beforeReplicaSaved((data) => ({
+            ...data,
+            name: `${String(data["name"])} (copy)`,
+            status: "draft",
+          })),
+        action("feature")
+          .label("Feature")
+          .icon("plus")
+          .visible((rec) => !(rec as unknown as Product)?.featured)
+          .run(async ({ record, resource }) => {
+            await resource.update(record!.id, { featured: true });
+          })
+          .successMessage("Product featured."),
+        deleteAction(),
+      ]).label("More"),
+    ];
+  }
+
+  static override columns() {
+    return [
+      text("name").searchable().sortable(),
+      text("sku").label("SKU").searchable().copyable(),
+      text("price")
+        .sortable()
+        .align("end")
+        .format((v) => money(v))
+        .sum("Total value", (n) => money(n)),
+      text("stock").sortable().align("end").sum("Units"),
+      selectColumn("status", STATUS).label("Status"),
+      toggleColumn("featured").label("Featured"),
+    ];
+  }
+
+  static override form() {
+    return [
+      formSection("Product")
+        .columns(2)
+        .schema([
+          textInput("name").required().minLength(2).maxLength(120).columnSpan(2),
+          textInput("sku").label("SKU").required().maxLength(40),
+          select("status").options(STATUS).default("draft").required(),
+          textInput("price")
+            .label("Price (cents)")
+            .numeric()
+            .required()
+            .min(0)
+            .helperText("Stored in minor units so money never rides on a float."),
+          textInput("stock").numeric().min(0).default(0),
+          textarea("description").rows(4).columnSpan(2),
+          toggle("featured").label("Featured").columnSpan(2),
+        ]),
+    ];
+  }
+
+  static override infolist() {
+    return [
+      section("Product")
+        .icon("collection")
+        .columns(2)
+        .schema([
+          textEntry("name").weight("semibold").size("lg"),
+          textEntry("sku").label("SKU").copyable(),
+          textEntry("price").format((v) => money(v)),
+          textEntry("stock"),
+          textEntry("status")
+            .badge()
+            .color((v) => (v === "active" ? "success" : "muted")),
+          iconEntry("featured").label("Featured"),
+          textEntry("description").columnSpan(2).placeholder("(no description)"),
+        ]),
+    ];
+  }
+
+  /** Runs on every save, after validation and before the write. */
+  static override mutateBeforeSave(data: AdminRecord): AdminRecord {
+    if (typeof data["sku"] === "string") data["sku"] = data["sku"].toUpperCase();
+    return data;
+  }
+
+  static override emptyState() {
+    return {
+      heading: "No products yet",
+      description: "Add your first product, or import a catalogue from a CSV file.",
+      icon: "collection",
+      actions: [createAction(), importAction()],
+    };
+  }
+}