create-zerotal 1.0.0

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

@@ -0,0 +1,48 @@
+import { Component, Link } from "@zerotal/flow";
+import type { HtmlNode } from "@zerotal/flow";
+import { AppLayout } from "../layouts/app";
+
+export class WelcomePage extends Component {
+  static layout = AppLayout;
+  static title = "Home";
+
+  async render(): Promise<HtmlNode> {
+    return (
+      <section class="py-10 text-center">
+        <span class="inline-flex items-center gap-2 rounded-full bg-green-50 px-3 py-1 text-sm font-medium text-green-700 ring-1 ring-green-600/20">
+          <span class="h-2 w-2 rounded-full bg-green-500"></span>
+          The install worked successfully!
+        </span>
+
+        <h1 class="mx-auto mt-6 max-w-2xl text-4xl font-bold tracking-tight text-gray-900 sm:text-5xl">
+          Build server-driven apps with <span class="text-indigo-600">Zerotal</span>
+        </h1>
+
+        <p class="mx-auto mt-4 max-w-xl text-lg leading-relaxed text-gray-600">
+          Flow pages, file-based routing, and Tailwind — out of the box. Edit{" "}
+          <code class="rounded bg-gray-100 px-1.5 py-0.5 font-mono text-sm text-indigo-600">
+            app/flow/pages/index.tsx
+          </code>{" "}
+          to get started.
+        </p>
+
+        <div class="mt-8 flex items-center justify-center gap-3">
+          <Link
+            href="/about"
+            hover
+            class="rounded-lg bg-indigo-600 px-4 py-2.5 text-sm font-semibold text-white shadow-sm transition hover:bg-indigo-700"
+          >
+            Learn more
+          </Link>
+          <Link
+            href="/contact"
+            hover
+            class="rounded-lg border border-gray-300 bg-white px-4 py-2.5 text-sm font-semibold text-gray-700 transition hover:bg-gray-50"
+          >
+            Get in touch
+          </Link>
+        </div>
+      </section>
+    );
+  }
+}

package/templates/flow/bootstrap/app.ts

@@ -0,0 +1,8 @@
+import { Application, basePath } from "zerotal";
+import providers from "./providers";
+
+const app = Application.create({ providers }).fileBasedRouting({
+  web: basePath("app/flow/pages"),
+});
+
+export default app;

package/templates/flow/bootstrap/providers.ts

@@ -0,0 +1,6 @@
+import { LogProvider } from "zerotal/logger";
+import { FlowProvider } from "@zerotal/flow";
+
+const providers = [LogProvider, FlowProvider];
+
+export default providers;

package/templates/flow/config/app.ts

@@ -0,0 +1,28 @@
+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 should be set to 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,
+  },
+
+  assets: {
+    entrypoint: "resources/js/app.ts",
+    outDir: "public",
+    prefix: env("ASSETS_PREFIX", "/"),
+  },
+});

package/templates/flow/package.json

@@ -0,0 +1,20 @@
+{
+  "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",
+    "test": "bun zt.ts test"
+  },
+  "dependencies": {
+    "@zerotal/flow": "{{zerotal_version}}",
+    "zerotal": "{{zerotal_version}}"
+  },
+  "devDependencies": {
+    "bun-plugin-tailwind": "latest",
+    "tailwindcss": "^4.0.0"
+  }
+}

package/templates/flow/public/zt.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Zerotal">
+  <defs>
+    <linearGradient id="zt-grad" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#818cf8" />
+      <stop offset="0.5" stop-color="#6366f1" />
+      <stop offset="1" stop-color="#7c3aed" />
+    </linearGradient>
+    <linearGradient id="zt-shine" x1="0" y1="0" x2="0" y2="64" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#ffffff" stop-opacity="0.35" />
+      <stop offset="0.55" stop-color="#ffffff" stop-opacity="0" />
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="18" fill="url(#zt-grad)" />
+  <rect width="64" height="64" rx="18" fill="url(#zt-shine)" />
+  <rect x="0.75" y="0.75" width="62.5" height="62.5" rx="17.25" stroke="#ffffff" stroke-opacity="0.18" stroke-width="1.5" />
+  <text x="32" y="41" text-anchor="middle" font-family="system-ui, -apple-system, Segoe UI, sans-serif" font-size="20" font-weight="800" letter-spacing="0.5" fill="#ffffff">ZT</text>
+</svg>

package/templates/flow/resources/css/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/flow/resources/js/app.ts

@@ -0,0 +1,10 @@
+import "../css/app.css";
+console.log("Zerotal app, welcome from Browser!");
+
+// Global client store — app-wide, client-only reactive UI state (theme, sidebar, …)
+// shared across components with no server round-trip. Declare its initial shape here,
+// then read/write it in JSX client expressions as `$flow.store.ui.dark`. Type it by
+// augmenting `FlowStore` (see resources/js/env.d.ts).
+//
+// import { defineStore } from "@zerotal/flow/store";
+// defineStore({ ui: { dark: false, sidebar: true } });

package/templates/flow/resources/js/env.d.ts

@@ -0,0 +1,23 @@
+// Ambient declarations for non-code assets imported from TypeScript and bundled
+// by `bun zt serve` (see the `assets` block in config/app.ts). These let
+// side-effect imports like `import "../css/app.css"` type-check.
+declare module "*.css";
+declare module "*.scss";
+declare module "*.svg";
+declare module "*.png";
+declare module "*.jpg";
+declare module "*.jpeg";
+declare module "*.gif";
+declare module "*.webp";
+declare module "*.woff";
+declare module "*.woff2";
+
+// Type the global client store by declaring your namespaces here. Every `$flow.store.*`
+// access in your components is then fully typed. Keep in sync with the `defineStore(…)`
+// call in resources/js/app.ts.
+//
+// declare module "@zerotal/flow/store" {
+//   interface FlowStore {
+//     ui: { dark: boolean; sidebar: boolean };
+//   }
+// }

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

@@ -0,0 +1,56 @@
+/**
+ * The scaffold boots and serves its pages.
+ *
+ * Two levels are shown here, and they answer different questions. The HTTP tests
+ * confirm the app wires up: providers register, file-based routes resolve, a
+ * request completes. The FlowTest block drives a page's own lifecycle in
+ * process — no server and no browser — which is where you test what a component
+ * does rather than that it exists.
+ */
+import { beforeAll, afterAll, describe, test, expect } from 'bun:test';
+import { createTestApp, type TestApp } from '@zerotal/testing';
+import { FlowTest } from '@zerotal/flow/testing';
+import { ContactPage } from '../app/flow/pages/contact.tsx';
+
+let app: TestApp;
+
+beforeAll(async () => {
+  // Flow snapshot signing and session encryption both need a key. Seed a
+  // deterministic one for tests; `??=` leaves a real key alone when the app's
+  // .env is present.
+  Bun.env.APP_KEY ??= 'test-app-key-aaaaaaaaaaaaaaaaaaaaaaaa';
+  app = await createTestApp(() => import('../bootstrap/app.ts').then((m) => m.default));
+});
+
+afterAll(() => app.close());
+
+describe('scaffold', () => {
+  test('boots and serves the home page', async () => {
+    const res = await app.get('/');
+
+    res.assertOk();
+  });
+
+  test('serves every file-based page', async () => {
+    (await app.get('/about')).assertOk();
+    (await app.get('/contact')).assertOk();
+  });
+
+  test('answers HEAD on the home route, as probes and load balancers do', async () => {
+    const res = await app.head('/');
+    expect(res.status).toBeLessThan(400);
+  });
+
+  test('returns 404 for an unregistered path', async () => {
+    (await app.get('/definitely-not-a-route')).assertNotFound();
+  });
+});
+
+describe('the contact page component', () => {
+  test('renders its content without a server or a browser', async () => {
+    const page = await FlowTest.mount(ContactPage);
+
+    page.assertSee('Contact');
+    page.assertSee('hello@example.com');
+  });
+});

package/templates/flow/tsconfig.json

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

package/templates/flow/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 worker                        Start the background worker
+//   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/minimal/_env.example

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

package/templates/minimal/_gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.zerotal/
+*.sqlite
+.env
+public/app.js
+public/app.css

package/templates/minimal/bootstrap/app.ts

@@ -0,0 +1,9 @@
+import { Application, basePath } from '@zerotal/core';
+import { LogProvider } from '@zerotal/core/logger';
+
+const app = Application.create({ providers: [LogProvider] })
+  .routing({
+    web: basePath("routes/index.ts"),
+  });
+
+export default app;

package/templates/minimal/config/app.ts

@@ -0,0 +1,28 @@
+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 should be set to 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,
+  },
+
+  assets: {
+    entrypoint: "resources/js/app.ts",
+    outDir: "public",
+    prefix: env("ASSETS_PREFIX", "/"),
+  },
+});

package/templates/minimal/package.json

@@ -0,0 +1,20 @@
+{
+  "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",
+    "test": "bun zt.ts test"
+  },
+  "dependencies": {
+    "@zerotal/flow": "{{zerotal_version}}",
+    "zerotal": "{{zerotal_version}}"
+  },
+  "devDependencies": {
+    "bun-plugin-tailwind": "latest",
+    "tailwindcss": "^4.0.0"
+  }
+}

package/templates/minimal/resources/css/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/templates/minimal/resources/js/app.ts

@@ -0,0 +1,2 @@
+import "../css/app.css";
+console.log("Zerotal app, welcome from Browser!");

package/templates/minimal/resources/js/components/Logo.tsx

@@ -0,0 +1,48 @@
+export function Logo({ class: className }: { class?: string }) {
+  return (
+    <svg
+      class={className}
+      viewBox="0 0 64 64"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      role="img"
+      aria-label="Zerotal"
+    >
+      <defs>
+        <linearGradient id="zt-grad" x1="0" y1="0" x2="64" y2="64" gradientUnits="userSpaceOnUse">
+          <stop stop-color="#818cf8" />
+          <stop offset="0.5" stop-color="#6366f1" />
+          <stop offset="1" stop-color="#7c3aed" />
+        </linearGradient>
+        <linearGradient id="zt-shine" x1="0" y1="0" x2="0" y2="64" gradientUnits="userSpaceOnUse">
+          <stop stop-color="#ffffff" stop-opacity="0.35" />
+          <stop offset="0.55" stop-color="#ffffff" stop-opacity="0" />
+        </linearGradient>
+      </defs>
+      <rect width="64" height="64" rx="18" fill="url(#zt-grad)" />
+      <rect width="64" height="64" rx="18" fill="url(#zt-shine)" />
+      <rect
+        x="0.75"
+        y="0.75"
+        width="62.5"
+        height="62.5"
+        rx="17.25"
+        stroke="#ffffff"
+        stroke-opacity="0.18"
+        stroke-width="1.5"
+      />
+      <text
+        x="32"
+        y="41"
+        text-anchor="middle"
+        font-family="system-ui, -apple-system, Segoe UI, sans-serif"
+        font-size="20"
+        font-weight="800"
+        letter-spacing="0.5"
+        fill="#ffffff"
+      >
+        ZT
+      </text>
+    </svg>
+  );
+}

package/templates/minimal/resources/js/env.d.ts

@@ -0,0 +1,13 @@
+// Ambient declarations for non-code assets imported from TypeScript and bundled
+// by `bun zt serve` (see the `assets` block in config/app.ts). These let
+// side-effect imports like `import "../css/app.css"` type-check.
+declare module "*.css";
+declare module "*.scss";
+declare module "*.svg";
+declare module "*.png";
+declare module "*.jpg";
+declare module "*.jpeg";
+declare module "*.gif";
+declare module "*.webp";
+declare module "*.woff";
+declare module "*.woff2";

package/templates/minimal/resources/js/layouts/AppLayout.tsx

@@ -0,0 +1,56 @@
+import type { Children } from "zerotal/view";
+import { Logo } from "../components/Logo";
+
+interface AppLayoutProps {
+  title: string;
+  /** Current request path — used to highlight the active nav item. */
+  path?: string;
+  children?: Children;
+}
+
+const NAV = [
+  { href: "/", label: "Home" },
+  { href: "/about", label: "About" },
+  { href: "/contact", label: "Contact" },
+];
+
+export default function AppLayout({ title, path = "/", children }: AppLayoutProps) {
+  const navLink =
+    "rounded-lg px-3 py-2 text-sm font-medium text-gray-600 transition hover:bg-gray-100 hover:text-gray-900";
+  const activeLink = "bg-indigo-50 text-indigo-700";
+
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{title}</title>
+        <link rel="stylesheet" href="/app.css" />
+        <script type="module" src="/app.js"></script>
+      </head>
+      <body class="min-h-screen bg-linear-to-b from-white via-white to-indigo-50 text-gray-900 antialiased">
+        <header class="sticky top-0 z-10 border-b border-gray-200/70 bg-white/80 backdrop-blur">
+          <nav class="mx-auto flex max-w-5xl items-center justify-between px-6 py-3">
+            <a href="/" class="flex items-center gap-2 font-bold tracking-tight">
+              <Logo class="h-7 w-7" />
+              <span>Zerotal</span>
+            </a>
+
+            <div class="flex items-center gap-1">
+              {NAV.map((item) => {
+                const isActive = item.href === "/" ? path === "/" : path.startsWith(item.href);
+                return (
+                  <a href={item.href} class={`${navLink} ${isActive ? activeLink : ""}`}>
+                    {item.label}
+                  </a>
+                );
+              })}
+            </div>
+          </nav>
+        </header>
+
+        <main class="mx-auto max-w-3xl px-6 py-14">{children}</main>
+      </body>
+    </html>
+  );
+}

package/templates/minimal/resources/js/pages/about.tsx

@@ -0,0 +1,30 @@
+import type { HttpContext } from "zerotal";
+import AppLayout from "../layouts/AppLayout";
+
+export default function About(ctx: HttpContext, { title }: { title: string }) {
+  return (
+    <AppLayout title={title} path={ctx.url.pathname}>
+      <section class="py-4">
+        <h1 class="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">About</h1>
+        <div class="mt-6 space-y-4 text-lg leading-relaxed text-gray-600">
+          <p>
+            This is an example app built with{" "}
+            <span class="font-medium text-gray-900">Zerotal</span> and its server-rendered JSX view
+            layer.
+          </p>
+          <p>
+            Routes are declared in{" "}
+            <code class="rounded bg-gray-100 px-1.5 py-0.5 font-mono text-sm text-indigo-600">
+              routes/index.ts
+            </code>{" "}
+            and render pages from{" "}
+            <code class="rounded bg-gray-100 px-1.5 py-0.5 font-mono text-sm text-indigo-600">
+              resources/js/pages
+            </code>
+            . This page is served at <span class="font-medium text-gray-900">/about</span>.
+          </p>
+        </div>
+      </section>
+    </AppLayout>
+  );
+}

package/templates/minimal/resources/js/pages/contact.tsx

@@ -0,0 +1,49 @@
+import type { HttpContext } from "zerotal";
+import AppLayout from "../layouts/AppLayout";
+
+export default function Contact(ctx: HttpContext, { title }: { title: string }) {
+  return (
+    <AppLayout title={title} path={ctx.url.pathname}>
+      <section class="py-4">
+        <h1 class="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">Contact</h1>
+        <p class="mt-4 text-lg leading-relaxed text-gray-600">
+          Have a question or feedback? We'd love to hear from you.
+        </p>
+
+        <div class="mt-6 rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+          <dl class="space-y-4 text-sm">
+            <div class="flex items-center justify-between gap-4">
+              <dt class="font-medium text-gray-500">Email</dt>
+              <dd>
+                <a
+                  href="mailto:hello@example.com"
+                  class="font-medium text-indigo-600 hover:text-indigo-700"
+                >
+                  hello@example.com
+                </a>
+              </dd>
+            </div>
+            <div class="flex items-center justify-between gap-4">
+              <dt class="font-medium text-gray-500">GitHub</dt>
+              <dd>
+                <a
+                  href="https://github.com"
+                  class="font-medium text-indigo-600 hover:text-indigo-700"
+                >
+                  github.com/your-org
+                </a>
+              </dd>
+            </div>
+          </dl>
+
+          <a
+            href="mailto:hello@example.com"
+            class="mt-6 inline-block w-full rounded-lg bg-indigo-600 px-4 py-2.5 text-center text-sm font-semibold text-white shadow-sm transition hover:bg-indigo-700"
+          >
+            Email us
+          </a>
+        </div>
+      </section>
+    </AppLayout>
+  );
+}

package/templates/minimal/resources/js/pages/welcome.tsx

@@ -0,0 +1,42 @@
+import type { HttpContext } from "zerotal";
+import AppLayout from "../layouts/AppLayout";
+
+export default function Welcome(ctx: HttpContext, { title }: { title: string }) {
+  return (
+    <AppLayout title={title} path={ctx.url.pathname}>
+      <section class="py-10 text-center">
+        <span class="inline-flex items-center gap-2 rounded-full bg-green-50 px-3 py-1 text-sm font-medium text-green-700 ring-1 ring-green-600/20">
+          <span class="h-2 w-2 rounded-full bg-green-500"></span>
+          The install worked successfully!
+        </span>
+
+        <h1 class="mx-auto mt-6 max-w-2xl text-4xl font-bold tracking-tight text-gray-900 sm:text-5xl">
+          Build server-driven apps with <span class="text-indigo-600">Zerotal</span>
+        </h1>
+
+        <p class="mx-auto mt-4 max-w-xl text-lg leading-relaxed text-gray-600">
+          Server-rendered JSX views, routing, and Tailwind — out of the box. Edit{" "}
+          <code class="rounded bg-gray-100 px-1.5 py-0.5 font-mono text-sm text-indigo-600">
+            resources/js/pages/welcome.tsx
+          </code>{" "}
+          to get started.
+        </p>
+
+        <div class="mt-8 flex items-center justify-center gap-3">
+          <a
+            href="/about"
+            class="rounded-lg bg-indigo-600 px-4 py-2.5 text-sm font-semibold text-white shadow-sm transition hover:bg-indigo-700"
+          >
+            Learn more
+          </a>
+          <a
+            href="/contact"
+            class="rounded-lg border border-gray-300 bg-white px-4 py-2.5 text-sm font-semibold text-gray-700 transition hover:bg-gray-50"
+          >
+            Get in touch
+          </a>
+        </div>
+      </section>
+    </AppLayout>
+  );
+}

package/templates/minimal/routes/index.ts

@@ -0,0 +1,16 @@
+import { Router, view, type HttpContext } from "zerotal";
+import Welcome from "../resources/js/pages/welcome";
+import About from "../resources/js/pages/about";
+import Contact from "../resources/js/pages/contact";
+
+Router.get("/", () => view(Welcome, { title: "Welcome to Zerotal" }));
+Router.get("/about", () => view(About, { title: "About" }));
+Router.get("/contact", () => view(Contact, { title: "Contact" }));
+
+Router.get("/api", (http: HttpContext) => {
+  return http.json({ message: "Hello, API!" });
+});
+
+Router.get("/api/:id", (http: HttpContext) => {
+  return http.json({ id: http.params.id, message: "Hello, API!" });
+});