@zerotal/arch 1.7.0

package/docs/getting-started.md

@@ -0,0 +1,286 @@
+---
+title: Getting Started
+description: Scaffold, configure, and run your first Zerotal application on Bun in a few minutes.
+---
+
+# Getting Started
+
+Zerotal is a full-stack framework for [Bun](https://bun.sh). This guide walks you
+from a blank machine to a running app with a route, a model, and a service
+provider.
+
+## Requirements
+
+- **Bun** ≥ 1.1 — [install](https://bun.sh/docs/installation)
+- A PostgreSQL, MySQL, or SQLite database (SQLite requires nothing extra)
+
+## Create a new project
+
+```bash
+# in your project root's parent directory
+bun create zerotal my-app    # or: bunx create-zerotal my-app
+cd my-app
+```
+
+The scaffolder prompts for a project name and a template, then generates a
+ready-to-run project and installs dependencies. The **database** prompt only
+appears for the API template:
+
+| Prompt       | Options                                                                     |
+| ------------ | --------------------------------------------------------------------------- |
+| Project name | Defaults to `my-zerotal-app`                                                |
+| Template     | **API**, **Flow**, **React**, **Vue**, or **Minimal** (see the guide below) |
+| Database     | **SQLite** (zero setup), **PostgreSQL**, or **MySQL** — API template only   |
+
+It writes a fresh `APP_KEY` into the generated `.env.example` for you (no manual
+generation needed). For Postgres/MySQL it reminds you to set `DATABASE_URL`
+before migrating.
+
+### Which template should I use?
+
+- **API** — JSON REST API with core, [ORM](/docs/orm), [auth](/docs/authentication),
+  [validation](/docs/validator), and [testing](/docs/testing/index). The default for a backend service.
+- **Flow** — server-driven reactive UI ([Flow](/docs/flow) pages, top nav, Tailwind).
+- **React** — [Inertia](/docs/inertia) + React SPA with file-based routes and Tailwind.
+- **Vue** — Inertia + Vue SPA with file-based routes and Tailwind.
+- **Minimal** — a single page with JSX views and Tailwind on the bare framework.
+
+> **Note** — Only the **API** template ships a database config and migrations.
+> The Flow, React, Vue, and Minimal templates start without a database.
+
+## Project structure
+
+The **API** template generates the following. Other templates vary (SPA
+templates add a `resources/` frontend, for example):
+
+```
+# my-app/ (API template)
+my-app/
+├── app/
+│   ├── controllers/        # HTTP controllers
+│   ├── middleware/          # Custom middleware
+│   └── models/              # ORM models (auto-discovered)
+├── bootstrap/
+│   └── app.ts               # Builds the Application (providers + routing)
+├── config/                  # Config files (database, session, queue…) — auto-loaded
+├── database/
+│   └── migrations/          # Database migrations
+├── routes/
+│   └── index.ts             # Route definitions
+├── tests/                   # Test suites
+├── zt.ts                   # Managed CLI entry point — do not edit
+└── .env                     # Environment variables (git-ignored)
+```
+
+`zt.ts` is the entry point for **everything** — `bun zt serve`, `migrate`,
+`test`, and every `make:*` generator run through it. It boots `bootstrap/app.ts`,
+which defines your [Application](/docs/application). Anything under `app/models/`,
+`app/providers/`, and `config/` is [auto-discovered](/docs/conventions) at boot —
+no manual registration.
+
+> **Tip** — `app/providers/` is auto-discovered when present. The API template
+> doesn't generate one; run `bun zt make:provider …` and the framework picks it
+> up at boot.
+
+## Environment setup
+
+The scaffolder generates `.env.example` with a ready-made `APP_KEY`. Copy it to
+`.env`:
+
+```bash
+# in your project root
+cp .env.example .env
+```
+
+```ini
+# .env
+APP_ENV=development
+APP_KEY=base64:…              # pre-generated; rotate with `bun zt key:generate`
+DATABASE_URL=./database/db.sqlite
+SESSION_SECRET=change-me-in-production
+```
+
+The database is configured with a single **`DATABASE_URL`** — SQLite uses a file
+path, Postgres/MySQL use a connection string:
+
+```ini
+# .env — alternative DATABASE_URL forms
+# DATABASE_URL=postgres://user:pass@localhost:5432/my_app
+# DATABASE_URL=mysql://root@localhost:3306/my_app
+```
+
+> **Danger** — Change `SESSION_SECRET` before deploying. The placeholder value is
+> not safe for production.
+
+See [Configuration](/docs/config-system) for the full config system.
+
+## Run migrations
+
+```bash
+# in your project root
+bun zt migrate
+```
+
+## Start the dev server
+
+```bash
+# in your project root
+bun dev          # → bun zt serve --dev
+```
+
+Your app is now running at **http://localhost:3000** with hot reload enabled —
+`--dev` watches your files and hot-swaps routes without dropping connections. The
+generated `package.json` also gives you `bun start` (production serve) and
+`bun test`.
+
+## Your first route
+
+Open `routes/index.ts` and add:
+
+```typescript
+// routes/index.ts
+import { Router } from "zerotal";
+import { PostController } from "../app/controllers/PostController.ts";
+
+Router.get("/posts", PostController, "index");
+Router.post("/posts", PostController, "store");
+```
+
+Create the controller:
+
+```typescript
+// app/controllers/PostController.ts
+import type { HttpContext } from "zerotal";
+
+export class PostController {
+  async index(ctx: HttpContext) {
+    return ctx.json({ posts: [] });
+  }
+
+  async store(ctx: HttpContext) {
+    const body = await ctx.request.json();
+    return ctx.json({ created: body }, 201);
+  }
+}
+```
+
+> **Note** — Every controller action receives the request
+> [HttpContext](/docs/context) directly. Read route params and resolved model
+> bindings from `ctx.params`; type them with the generic, e.g.
+> `ctx: HttpContext<{ post: Post }>`.
+
+## Your first model
+
+```bash
+# in your project root
+bun zt make:model Post --migration
+```
+
+This generates `app/models/Post.ts` and a matching migration. Models in
+`app/models/` are auto-discovered at boot — no manual registration, and the table
+name is derived by convention (`Post` → `posts`), so `@table` is optional. The
+same applies to observers, policies, and event listeners; see
+[Conventions](/docs/conventions).
+
+Open the migration and define your columns:
+
+```typescript
+// database/migrations/xxxx_create_posts_table.ts
+import { Migration, Schema } from "@zerotal/orm";
+
+export default class CreatePostsTable extends Migration {
+  async up(): Promise<void> {
+    await Schema.create("posts", (table) => {
+      table.increments("id");
+      table.string("title");
+      table.text("body");
+      table.string("slug").unique();
+      table.timestamps();
+    });
+  }
+
+  async down(): Promise<void> {
+    await Schema.drop("posts");
+  }
+}
+```
+
+Run it:
+
+```bash
+# in your project root
+bun zt migrate
+```
+
+Your model is ready to use:
+
+```typescript
+// in a controller or service
+import { Post } from "../models/Post.ts";
+
+const posts = await Post.query().latest().limit(10).get();
+const post = await Post.find(1);
+const fresh = await Post.create({ title: "Hello", body: "...", slug: "hello" });
+```
+
+## Adding a service provider
+
+Providers are where you wire up your own bindings. Scaffold one:
+
+```bash
+# in your project root
+bun zt make:provider AppServiceProvider
+```
+
+```typescript
+// app/providers/AppServiceProvider.ts
+import { ServiceProvider } from "zerotal";
+import { PaymentGateway } from "../services/PaymentGateway.ts";
+import { StripeGateway } from "../services/StripeGateway.ts";
+
+export class AppServiceProvider extends ServiceProvider {
+  onRegister(): void {
+    this.app.container.singleton(
+      PaymentGateway,
+      () => new StripeGateway({ key: Bun.env.STRIPE_KEY! }),
+    );
+  }
+}
+```
+
+Anything under `app/providers/` is **auto-discovered and registered at boot** — no
+manual wiring needed. You only touch `bootstrap/app.ts` when you need to control
+_ordering_ (e.g. one provider must register before another). See
+[Service Providers](/docs/providers) and [Conventions](/docs/conventions).
+
+## Available commands
+
+Everything runs through `zt.ts`. The most common:
+
+```bash
+# in your project root
+bun zt make:model Name --migration   # model + migration
+bun zt make:controller Name          # controller class
+bun zt make:middleware Name          # middleware class
+bun zt make:provider Name            # service provider
+bun zt make:job Name                 # queue job
+bun zt migrate                       # run pending migrations
+bun zt migrate:rollback              # roll back last batch
+bun zt migrate:status                # show migration status
+bun zt migrate:fresh                 # roll back all + re-migrate
+bun zt key:generate                  # generate a fresh APP_KEY
+bun zt queue:work                    # start the queue worker
+```
+
+There are many more (`make:policy`, `make:factory`, `make:seeder`, `make:page`,
+`db:seed`, `schedule:list`, …). Run `bun zt list` to see them all, or see
+[Commands](/docs/commands) for the full list and
+[Scaffolding](/docs/scaffolding) for what each generator produces.
+
+## Next steps
+
+- [Routing](/docs/routing) — route definitions, groups, parameters, and file-based routes.
+- [Controllers](/docs/controllers) — move route logic into classes.
+- [ORM](/docs/orm) — models, queries, and relationships.
+- [Configuration](/docs/config-system) — how config and auto-discovery work.
+- [Flow](/docs/flow) — server-driven reactive UI (or [Inertia](/docs/inertia) for a React/Vue SPA).

package/docs/health.md

@@ -0,0 +1,269 @@
+---
+title: Health Checks
+description: Serve a probe-friendly /health endpoint that reports liveness and the readiness of your app's dependencies.
+---
+
+# Health Checks
+
+Zerotal serves a `/health` endpoint for liveness/readiness probes (Kubernetes,
+load balancers, uptime monitors). It is **on by default outside production** and
+**off in production until you enable it and protect it**.
+
+Health checks are a core built-in — there is no package to install and no
+provider to register. You configure the endpoint under the `health` key of
+`config/app.ts`, then register dependency checks via the `Health` registry.
+
+## Getting Started
+
+Health checks are built into `@zerotal/core` — nothing to install and no
+provider to register. The endpoint is registered when the application starts:
+
+```typescript
+import { Health } from "zerotal";
+```
+
+## Defaults
+
+| Environment                  | Default  | Access                                                       |
+| ---------------------------- | -------- | ------------------------------------------------------------ |
+| development / test / staging | enabled  | open                                                         |
+| production                   | disabled | requires a `secret` (`?key=` or `X-Health-Key`) once enabled |
+
+## Configuration
+
+The health config lives under the `health` key of `config/app.ts`. Use the
+`AppConfig()` helper so every field stays type-checked:
+
+```typescript
+// config/app.ts
+import { env } from "zerotal";
+import { AppConfig } from "zerotal/config";
+
+export default AppConfig({
+  name: "My App",
+  health: {
+    enabled: true, // default: on outside production, off in production
+    path: "/health", // default: '/health'
+    secret: env("HEALTH_KEY"), // required in production
+    showDetails: true, // false → bare { "status": "ok" }
+  },
+});
+```
+
+| Field         | Required | Default         | Description                                                            |
+| ------------- | -------- | --------------- | ---------------------------------------------------------------------- |
+| `enabled`     | no       | on outside prod | Serve the endpoint. Off in production unless explicitly set.           |
+| `path`        | no       | `"/health"`     | Route path the endpoint is registered at.                              |
+| `secret`      | in prod  | unset           | Shared secret, supplied via `?key=` or the `X-Health-Key` header.      |
+| `showDetails` | no       | `true`          | Include per-check details; `false` collapses the body to `{ status }`. |
+
+> **Note** — The endpoint is only registered when the app runs in the `web` or
+> `worker` environment. Console commands and tests never expose it.
+
+> **Note** — A legacy `config/health.ts` namespace and a bare `health: true`
+> boolean on `config/app.ts` are still honoured for back-compat. New projects
+> should author the `health` object directly under `config/app.ts`.
+
+### Protecting the endpoint
+
+In production the endpoint refuses to serve unless a `secret` is configured —
+so it can never be exposed unprotected by accident. Call it with the key:
+
+```bash
+# from a probe or terminal
+curl "https://your-app.com/health?key=YOUR_HEALTH_KEY"
+# or via header
+curl -H "X-Health-Key: YOUR_HEALTH_KEY" https://your-app.com/health
+```
+
+Access control resolves as follows:
+
+- **A `secret` is set** — the request must supply a matching `?key=` or
+  `X-Health-Key`. A wrong or missing key returns **HTTP 401**.
+- **Production with no `secret`** — the endpoint is refused with **HTTP 503**;
+  it must be protected before it can be exposed.
+- **Otherwise** (development, no secret) — access is open.
+
+You can also leave `secret` unset and instead wrap the path in your own
+auth/IP-allowlist middleware.
+
+> **Danger** — In production, set a `secret` (or wrap the path in your own auth)
+> before enabling the endpoint. The detailed report exposes dependency status,
+> versions, and memory; an unprotected `/health` leaks that to anyone.
+
+## Registering checks
+
+Out of the box the endpoint is a **liveness** probe (the process answered) plus
+a built-in `runtime` probe (memory, Bun version, in-flight requests). It becomes
+a **readiness** probe as you register dependency checks against the `Health`
+registry exported from `zerotal`:
+
+```typescript
+// in a bootstrap file (e.g. bootstrap/health.ts)
+import { Health } from "zerotal/health";
+
+// Critical checks drive the overall status and the HTTP 503 response.
+Health.register(
+  "database",
+  async () => {
+    await DB.raw("select 1");
+  },
+  { critical: true },
+);
+
+// Non-critical failures degrade the report without failing readiness.
+Health.register("cache", async () => {
+  await Cache.put("__health", "1", 5);
+  return { meta: { driver: "redis" } };
+});
+
+Health.register("disk", () => {
+  const free = getFreeBytes();
+  return free < 100_000_000
+    ? { status: "degraded", message: "low disk" }
+    : { status: "ok", meta: { freeBytes: free } };
+});
+```
+
+A check is healthy when it returns (or returns `{ status: 'ok' }`), `degraded`
+when it returns `{ status: 'degraded' }`, and `down` when it returns
+`{ status: 'down' }` **or throws** (the thrown message becomes the check's
+`message`).
+
+### Overall status
+
+The aggregate status is derived from every check:
+
+- **`down`** (HTTP 503) — any `critical` check is down.
+- **`degraded`** (HTTP 200) — a non-critical check is down or degraded.
+- **`ok`** (HTTP 200) — everything passed.
+
+> **Tip** — Mark only the dependencies your app genuinely cannot serve requests
+> without (your primary database, say) as `critical`. A flaky cache should
+> `degrade` the report, not knock the whole app out of the load balancer.
+
+## What the endpoint returns
+
+```json
+{
+  "status": "ok",
+  "app": { "name": "my-app", "version": "1.4.0", "environment": "production" },
+  "uptime": 3672,
+  "timestamp": "2026-06-15T10:32:00.000Z",
+  "checks": {
+    "runtime": {
+      "status": "ok",
+      "durationMs": 0,
+      "critical": false,
+      "meta": { "memory": { "rss": 84934656 }, "bun": "1.3.14", "pendingRequests": 3 }
+    },
+    "database": { "status": "ok", "durationMs": 4, "critical": true },
+    "cache": { "status": "ok", "durationMs": 2, "critical": false, "meta": { "driver": "redis" } }
+  }
+}
+```
+
+`uptime` is whole seconds since the process started. With `showDetails: false`
+the body collapses to `{ "status": "ok" }` — handy for public uptime monitors
+that should not see internal details.
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing). A health check
+is a function you registered, so test it directly — and test what happens when it
+fails, since that is the case the endpoint exists for.
+
+```typescript
+// tests/health/checks.test.ts
+import { test, expect, afterEach } from "bun:test";
+import { Health } from "zerotal";
+
+afterEach(() => Health.clear());
+
+test("a failing critical check brings the report down", async () => {
+  Health.register(
+    "database",
+    async () => {
+      throw new Error("connection refused");
+    },
+    { critical: true },
+  );
+
+  const report = await Health.run({ name: "app", version: "1.0.0", environment: "test" });
+
+  expect(report.status).toBe("down");
+  expect(report.checks.database?.status).toBe("down");
+});
+```
+
+**`Health.clear()` in `afterEach` matters.** The registry is process-wide, so a
+check registered by one test runs in every later one — and a deliberately failing
+check left behind turns the rest of your suite red for reasons that have nothing
+to do with it.
+
+**Critical and non-critical fail differently**, and that distinction is the whole
+design. A non-critical check that fails must leave the overall status up,
+otherwise a flaky cache probe takes your deployment out of the load balancer:
+
+```typescript
+// tests/health/checks.test.ts
+test("a non-critical failure degrades without going down", async () => {
+  Health.register("cache", async () => {
+    throw new Error("timeout");
+  }); // critical defaults to false
+
+  const report = await Health.run(meta);
+
+  expect(report.status).not.toBe("down");
+  expect(report.checks.cache?.status).toBe("down");
+});
+```
+
+**The endpoint's access rules deserve their own test**, because a health endpoint
+that leaks internals is a reconnaissance gift:
+
+```typescript
+// tests/http/health.test.ts
+const res = await app.get("/health");
+
+res.assertOk();
+res.assertDontSee("connection refused"); // no error detail to an anonymous caller
+```
+
+> **Note** — Check functions run on every request to the endpoint. A check that
+> queries the database on each call turns your load balancer's probe into
+> steady traffic — worth a test asserting yours is cheap, or a cache in front.
+
+## References
+
+### `Health` registry
+
+```typescript
+import { Health } from "zerotal/health";
+```
+
+| Method     | Signature                                                                           | Description                                                            |
+| ---------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `register` | `register(name: string, fn: HealthCheckFn, options?: { critical?: boolean }): this` | Register (or replace) a named check; `critical` checks fail readiness. |
+| `remove`   | `remove(name: string): this`                                                        | Remove a previously registered check by name.                          |
+| `clear`    | `clear(): this`                                                                     | Remove every registered check.                                         |
+| `has`      | `has(name: string): boolean`                                                        | Whether a check is registered under the given name.                    |
+| `names`    | `names: string[]`                                                                   | The names of all registered checks.                                    |
+| `run`      | `run(meta: HealthRunMeta): Promise<HealthReport>`                                   | Run every check and assemble the aggregate report.                     |
+
+### `HealthResult`
+
+What a check returns to describe its own state. A check may also return nothing
+(or `undefined`) to mean `ok`.
+
+| Field     | Type                           | Description                                             |
+| --------- | ------------------------------ | ------------------------------------------------------- |
+| `status`  | `"ok" \| "degraded" \| "down"` | Defaults to `ok` when a check returns without throwing. |
+| `message` | `string`                       | Optional human-readable detail.                         |
+| `meta`    | `Record<string, unknown>`      | Optional structured metadata surfaced in the report.    |
+
+## Next steps
+
+- [Telemetry](/docs/telemetry) — collect the metrics behind your readiness checks.
+- [Deployment](/docs/deployment) — wire `/health` into liveness and readiness probes.
+- [Logger](/docs/logger) — record failing checks for later inspection.