@digimuza/saas-core 0.0.2

package/docs/cli.md

@@ -0,0 +1,238 @@
+# CLI
+
+```bash
+npx sc init
+npx sc start
+```
+
+> Orientation and design notes: [`src/cli/README.md`](../src/cli/README.md).
+
+A utility CLI, shipped as the `sc` binary, for bootstrapping and running a project
+built on this package. The original `saas-core` binary remains available for the
+advanced development stack.
+
+---
+
+## `sc init`
+
+Prompts for the project name and creates `docker-compose.yml` in the current
+directory. The generated stack contains PostgreSQL 17, binds it to
+`127.0.0.1:5432`, persists its data in a named volume, and includes a healthcheck.
+
+Pass `--project <name>` to skip the prompt, `--postgres-port <port>` to select a
+different host port, or `--force` to replace an existing Compose file.
+
+## `sc start`
+
+Starts the generated Compose stack in the background and waits until PostgreSQL
+is healthy:
+
+```bash
+sc start
+```
+
+Run `sc init` first. The command never searches parent directories, so it starts
+only the Compose file owned by the current project.
+
+---
+
+## `saas-core dev up`
+
+Generates `.saas-core/` if it is missing, starts the stack, and waits for every
+healthcheck to pass before returning.
+
+```
+> docker compose v2.29.0
+> created ./.saas-core/docker-compose.yml
+> created ./.saas-core/Caddyfile
+> created ./.saas-core/.gitignore
+> starting postgres, minio and caddy
+ok stack up (project my-app)
+
+Endpoints
+  app             https://app.localhost -> localhost:3000
+  postgres        localhost:5432
+  minio           http://localhost:9000
+  minio console   http://localhost:9001
+
+Configuration
+  Load these through Infisical rather than a .env file:
+
+  APP_URL                     https://app.localhost
+  DATABASE_URL                postgres://saas:saas@localhost:5432/saas_core
+  STORAGE_BUCKET              saas-core-dev
+  STORAGE_REGION              us-east-1
+  STORAGE_ENDPOINT            http://localhost:9000
+  STORAGE_ACCESS_KEY_ID       saascoredev
+  STORAGE_SECRET_ACCESS_KEY   saascoredev
+```
+
+### What it starts, and what it does not
+
+| Service | Why |
+| --- | --- |
+| PostgreSQL 17 | Durable state, and the realtime transport — `LISTEN`/`NOTIFY` |
+| MinIO | S3-compatible store for [storage](./storage.md) and [files](./files.md) |
+| Caddy | Local HTTPS in front of your dev server |
+
+No Redis: [realtime](./realtime.md) runs on PostgreSQL and [jobs](./jobs.md) on
+Trigger.dev, so there is nothing else to operate. No mail catcher: the
+[email](./email.md) module has a console provider for development.
+
+### Why Caddy is not optional
+
+Three things differ over plain HTTP, and all three stay invisible until deploy:
+
+- [`auth`](./auth.md) marks session cookies `Secure` outside development.
+- `SameSite` enforcement differs between schemes.
+- WorkOS redirect URIs are easier to keep consistent when both environments are
+  `https`.
+
+`tls internal` issues a certificate from Caddy's own CA, so local matches
+production. Trust the root once and the browser stops warning — `up` prints the
+command to extract it.
+
+---
+
+## Commands
+
+| Command | Effect |
+| --- | --- |
+| `dev up` | Generate, start, wait for health |
+| `dev down` | Stop; **data preserved** |
+| `dev down --volumes` | Stop and delete volumes — the one destructive command |
+| `dev status` (`dev ps`) | Container state |
+| `dev logs [service]` | Last 100 lines; `--follow` to stream |
+| `dev init` | Write the files without starting anything |
+
+## Options
+
+| Option | Default |
+| --- | --- |
+| `--project <name>` | the directory name, normalised |
+| `--domain <host>` | `app.localhost` |
+| `--app-port <n>` | `3000` |
+| `--postgres-port <n>` | `5432` |
+| `--minio-port <n>` | `9000`; the console takes the next port |
+| `--force` | off — overwrite generated files |
+| `--follow`, `-f` | off — follow logs |
+| `--volumes` | off — with `down`, delete volumes |
+| `--help`, `-h` / `--version` | |
+
+Ports are validated before Docker sees them, so a typo fails with a message rather
+than a bind error.
+
+The project name defaults to the directory name, so two checkouts on one machine
+get separate containers and volumes without anyone configuring it.
+
+---
+
+## The generated files
+
+`.saas-core/docker-compose.yml` and `.saas-core/Caddyfile` are **meant to be
+committed**. They are infrastructure, and a change to either should show up in a
+diff.
+
+They are generated rather than vendored because ports collide: a developer with an
+existing PostgreSQL on 5432 needs a different one, and editing a vendored file
+means losing the edit on every upgrade.
+
+**Existing files are left alone.** A second `up` will not discard a Caddyfile you
+added a second host to. `--force` overwrites.
+
+`.saas-core/.gitignore` ignores only local state — logs — never the two
+infrastructure files.
+
+### Choices baked into the compose file
+
+**Every published port binds to `127.0.0.1`,** not `0.0.0.0`. Otherwise a laptop
+on a cafe network is serving an unauthenticated database to the room. A test walks
+every port mapping in the generated file and asserts it.
+
+**`up --wait`.** Compose blocks on the healthchecks (`pg_isready`, `mc ready`), so
+the command returning means the stack is usable — not merely created. Without it
+the next command races the database.
+
+**PostgreSQL pinned to 17; 15 is the floor.** The schema uses `UNIQUE NULLS NOT
+DISTINCT` for [feature flag](./feature-flags.md) overrides, which does not exist
+before 15. Pinning the major keeps a local database from silently diverging from
+production, and a test asserts it.
+
+**A one-shot `minio-init`** creates the bucket. MinIO starts with none, so without
+it every upload fails on a fresh volume.
+
+**`host.docker.internal:host-gateway`** is mapped explicitly. Caddy proxies to the
+dev server on the *host* — so hot reload and the real `node_modules` keep working —
+and Docker Desktop provides that name while Linux needs the mapping.
+
+**Credentials are fixed and weak.** `saas:saas`, `saascoredev`. Throwaway data on
+loopback; a generated password is one more thing to look up before running `psql`.
+
+---
+
+## Configuration is printed, not written
+
+There is deliberately no `--write-env`. Configuration comes from Infisical (see
+[config](./config.md)), and a `.env` file sitting in the project is exactly the
+habit that leads to one in production.
+
+`up` prints the values and the matching `infisical secrets set` commands, so the
+next step is a paste rather than a lookup.
+
+The variable names are checked against `src/config/sections.ts` by a test — a
+drifted name would otherwise be silent: the stack comes up and the application
+cannot see it.
+
+---
+
+## Error handling
+
+Docker is checked before anything else, because "command not found", "daemon not
+running" and "no compose plugin" are three problems with three different fixes:
+
+```
+x The Docker CLI is installed but its daemon is not reachable.
+  Start Docker Desktop, or run `sudo systemctl start docker`.
+```
+
+**The daemon needs its own probe.** `docker compose version` reports the *client*
+plugin and succeeds with the daemon stopped — so checking only that lets a stopped
+daemon through to fail halfway through an image pull. That was a real bug during
+development; there is a test pinning the two-probe sequence.
+
+Compose failures are translated where the cause is knowable — a port collision
+names `--postgres-port`, exhausted disk suggests `docker system prune` — and passed
+through verbatim otherwise. Anything unrecognised is better shown raw than
+mislabelled.
+
+Errors print a message and a hint, never a stack trace: a stack tells someone
+running a CLI nothing actionable and buries the one line that matters.
+
+---
+
+## No CLI dependency
+
+Node's `parseArgs` handles arguments; four escape codes and a TTY check handle
+colour. Commander and chalk would each be a dependency for under twenty lines, in
+a package many applications install.
+
+Colour is dropped when stdout is not a TTY, when `NO_COLOR` is set, or when `TERM`
+is `dumb` — escape codes in a CI log are noise a human then reads around.
+
+---
+
+## Testing
+
+`CommandRunner` is a one-method interface, so every argument list is asserted
+without Docker installed:
+
+```ts
+const { runner, calls } = fakeRunner();
+await devUp({ cwd, runner, projectName: "demo" });
+
+expect(calls.find((c) => c.args.includes("up"))?.args).toContain("--wait");
+```
+
+That covers template generation, port validation, file-preservation behaviour,
+compose argument construction, and every error path. What it cannot cover is a real
+container coming up — see the note in the root README.

package/docs/config.md

@@ -0,0 +1,163 @@
+# Configuration
+
+```ts
+import { config, assertConfig, ConfigError } from "@digimuza/saas-core/config";
+import { clientConfig } from "@digimuza/saas-core/config/client";
+```
+
+> Orientation and recipes: [`src/config/README.md`](../src/config/README.md).
+
+
+Typed, Zod-validated configuration. Values come from the process environment,
+which **Infisical** populates at runtime — there is no `.env` strategy:
+
+```bash
+infisical run -- npm run dev
+```
+
+Only two files in the whole package read `process.env`
+(`src/config/env.ts` and `src/config/client.ts`), and a test enforces that.
+Application code must never read it directly.
+
+---
+
+## `config`
+
+An object of lazily-validated sections.
+
+```ts
+config.app;      // { name, url, environment, logLevel, isProduction }
+config.database; // { url, maxConnections, ssl, statementTimeoutMs, preparedStatements }
+config.auth;     // { workosApiKey, workosClientId, cookiePassword, redirectUri }
+config.billing;  // { apiKey, webhookSecret, apiUrl }
+config.email;    // { apiKey, fromAddress, fromName }
+config.storage;  // { bucket, region, accessKeyId, secretAccessKey, endpoint, publicUrl }
+config.realtime; // { url, apiKey }
+config.jobs;     // { secretKey, apiUrl }
+```
+
+### Why sections validate on first access, not at import
+
+A core package is consumed by many runtimes — a migration script, a Trigger.dev
+task, a Next.js route handler — and few need every integration configured.
+Validating everything at import would force every deployment to supply Revolut
+and storage credentials just to run a migration.
+
+Each section is validated once, on first read, then memoised.
+
+---
+
+## `assertConfig(names?)`
+
+```ts
+function assertConfig(names?: readonly SectionName[]): void
+```
+
+Eagerly validate sections so misconfiguration surfaces at boot rather than
+mid-request. Call it once at startup with what the process actually needs:
+
+```ts
+assertConfig(["app", "database", "auth"]);
+```
+
+- Throws `ConfigError` when one section is invalid.
+- Throws `AggregateError` of `ConfigError` when several are, so one boot reports
+  every problem instead of making you fix them one at a time.
+- Called with no argument, validates all eight sections.
+
+---
+
+## `ConfigError`
+
+```ts
+class ConfigError extends Error {
+  readonly section: string;         // "database"
+  readonly variables: readonly string[];  // ["DATABASE_URL"]
+}
+```
+
+The message names the offending **variables** and Zod's structural complaint, and
+**never interpolates values** — so a malformed secret cannot leak into logs,
+stack traces, or an error tracker. There is a test that puts a recognisable
+secret into a failing config and asserts it does not appear in the message.
+
+---
+
+## Environment variables
+
+| Section | Variables |
+| --- | --- |
+| `app` | `APP_NAME`, `APP_URL`, `APP_ENV`¹, `LOG_LEVEL`¹ |
+| `database` | `DATABASE_URL`, `DATABASE_MAX_CONNECTIONS`¹, `DATABASE_SSL`¹, `DATABASE_STATEMENT_TIMEOUT_MS`¹, `DATABASE_PREPARED_STATEMENTS`¹ |
+| `auth` | `WORKOS_API_KEY`, `WORKOS_CLIENT_ID`, `WORKOS_COOKIE_PASSWORD`², `WORKOS_REDIRECT_URI` |
+| `billing` | `REVOLUT_API_KEY`, `REVOLUT_WEBHOOK_SECRET`, `REVOLUT_API_URL`¹ |
+| `email` | `EMAIL_API_KEY`, `EMAIL_FROM_ADDRESS`, `EMAIL_FROM_NAME`³ |
+| `storage` | `STORAGE_BUCKET`, `STORAGE_REGION`, `STORAGE_ACCESS_KEY_ID`, `STORAGE_SECRET_ACCESS_KEY`, `STORAGE_ENDPOINT`³, `STORAGE_PUBLIC_URL`³ |
+| `realtime` | `REALTIME_URL`, `REALTIME_API_KEY` |
+| `jobs` | `TRIGGER_SECRET_KEY`, `TRIGGER_API_URL`¹ |
+
+¹ has a default · ² minimum 32 characters · ³ optional
+
+**Empty strings count as unset.** Secret managers and CI runners routinely inject
+`FOO=` for absent values; without this, `.default()` and `.optional()` would never
+apply and every deployment would need a placeholder for everything.
+
+`DATABASE_PREPARED_STATEMENTS=false` is required behind a transaction-pooling
+proxy (pgBouncer, Supabase or Neon pooler): prepared statements are per-session
+and break when the proxy multiplexes sessions across connections.
+
+Variables are named after the credential's **provider** (`REVOLUT_API_KEY`, not
+`BILLING_API_KEY`) so an operator can see what belongs where, and so two
+providers can run side by side during a migration.
+
+---
+
+## Client configuration
+
+```ts
+import { clientConfig, assertClientConfig } from "@digimuza/saas-core/config/client";
+
+clientConfig.app;      // { name, url, environment, isProduction }
+clientConfig.auth;     // { workosClientId }
+clientConfig.realtime; // { url }
+```
+
+Required: `NEXT_PUBLIC_APP_NAME`, `NEXT_PUBLIC_APP_URL`,
+`NEXT_PUBLIC_WORKOS_CLIENT_ID`. Optional: `NEXT_PUBLIC_APP_ENV` (defaults),
+`NEXT_PUBLIC_REALTIME_URL`.
+
+Three things make this safe:
+
+1. `config/client` imports **no** server configuration code, so a bundler cannot
+   reach a secret through it. Tested.
+2. Every variable is read as a **literal** `process.env.NEXT_PUBLIC_*` access.
+   Next.js substitutes those textually at build time; a dynamic
+   `process.env[key]` lookup is *not* substituted and would be `undefined` in the
+   browser. Do not refactor them into a loop — there is a test that fails if you
+   do.
+3. `@digimuza/saas-core/config` and `/db` throw if evaluated in a browser.
+
+### Why not the `server-only` package
+
+`server-only` resolves to a module that *throws* unless the bundler sets the
+`react-server` export condition. That condition is absent in plain Node, so
+importing it would break every migration script, Trigger.dev task and Vitest run.
+The core uses a runtime browser guard instead. This is weaker than build-time
+enforcement — the structural guarantee is that clients import `/config/client`,
+which never imports server code.
+
+---
+
+## Testing
+
+```ts
+import { setEnvSource, resetConfigCache } from "@digimuza/saas-core/config";
+
+resetConfigCache();
+setEnvSource({ DATABASE_URL: "postgres://localhost/test" });
+// ...
+setEnvSource(undefined); // back to process.env
+```
+
+Vitest merges into the ambient environment rather than replacing it, so tests must
+inject a fixture rather than depend on `process.env`.

package/docs/db.md

@@ -0,0 +1,219 @@
+# Database & schema
+
+```ts
+import { getDatabase, createDatabase, runMigrations } from "@digimuza/saas-core/db";
+import { workspaces, users } from "@digimuza/saas-core/db/schema";
+```
+
+> Orientation and recipes: [`src/db/README.md`](../src/db/README.md).
+
+
+PostgreSQL + Drizzle ORM. Two separate entry points, deliberately:
+
+- **`/db/schema`** — table definitions only. No configuration, no driver. Safe for
+  drizzle-kit and for your own schema files. A test enforces that it imports
+  nothing but `drizzle-orm`.
+- **`/db`** — the client. Server-only, needs configuration.
+
+---
+
+## `getDatabase()`
+
+```ts
+function getDatabase(): Database
+```
+
+The shared, configuration-driven handle. Reads the `database` config section on
+first call, so it throws `ConfigError` if the database is not configured.
+
+```ts
+const db = getDatabase();
+await db.select().from(users);
+```
+
+The handle is cached on `globalThis`. That is not premature optimisation: Next.js
+dev-mode hot reloading re-evaluates modules on every edit, and without the cache
+each edit would leak a connection pool until PostgreSQL refuses new connections.
+
+## `getDatabaseHandle()`
+
+```ts
+function getDatabaseHandle(): DatabaseHandle  // { db, client, close() }
+```
+
+As above, but exposes the raw postgres.js client — for `LISTEN`/`NOTIFY` and raw
+SQL — and the lifecycle.
+
+## `createDatabase(options)`
+
+```ts
+function createDatabase(options: {
+  url: string;
+  maxConnections?: number;        // 10
+  ssl?: boolean;                  // false
+  statementTimeoutMs?: number;    // 30_000
+  preparedStatements?: boolean;   // true
+}): DatabaseHandle
+```
+
+An explicitly configured handle, for when the caller must own the connection
+lifecycle: migrations, tests, one-off scripts.
+
+`statement_timeout` is applied per connection so a runaway query cannot hold a
+pool slot indefinitely.
+
+## `closeDatabase()`
+
+```ts
+function closeDatabase(): Promise<void>
+```
+
+Close and forget the shared handle. For shutdown hooks and tests.
+
+## `CoreDatabase`
+
+```ts
+import type { CoreDatabase } from "@digimuza/saas-core/db";
+```
+
+A driver-independent handle typed against the core schema. Every service accepts
+this rather than a concrete `PostgresJsDatabase`, so the same code runs against
+postgres.js in production and PGlite in tests. A `PgTransaction` is assignable to
+it, so any service also composes inside a transaction. There is a compile-time
+assertion proving both drivers unify.
+
+---
+
+## Referencing core tables
+
+```ts
+import { pgTable, text, uuid } from "drizzle-orm/pg-core";
+import { workspaces } from "@digimuza/saas-core/db/schema";
+
+export const projects = pgTable("projects", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  workspaceId: uuid("workspace_id")
+    .notNull()
+    .references(() => workspaces.id, { onDelete: "cascade" }),
+  name: text("name").notNull(),
+});
+```
+
+`drizzle-orm` is a **peer** dependency for exactly this reason: two copies in one
+dependency tree produce table objects Drizzle cannot relate to each other, and the
+failure is a confusing type error far from the cause.
+
+---
+
+## Migrations
+
+Versioned migrations ship inside the package (`files: ["drizzle"]`), so an
+application applies core schema changes without vendoring SQL.
+
+```ts
+import { runMigrations, coreMigrationsFolder } from "@digimuza/saas-core/db";
+
+await runMigrations();                          // core migrations
+await runMigrations({ migrationsFolder: "./drizzle" }); // your own
+```
+
+```bash
+npm run db:generate                    # after editing src/db/schema
+infisical run -- npm run db:migrate
+```
+
+Migrations run on a dedicated single connection: they take advisory locks and must
+not compete with application traffic.
+
+---
+
+## Schema conventions
+
+Follow these in your own tables so both halves of the schema stay coherent.
+
+- **Explicit `snake_case` names everywhere.** Nothing relies on Drizzle's casing
+  inference, so a rename is always a visible diff.
+- **UUID primary keys** from `gen_random_uuid()`. Identifiers appear in URLs;
+  sequential ids leak volume and allow enumeration across tenants.
+- **`timestamptz` for all timestamps.** Never naive local time.
+- **`updated_at` is maintained by Drizzle, not a trigger.** Writes that bypass the
+  application (manual SQL, data repairs) then show a stale timestamp rather than
+  being silently rewritten.
+
+Helpers:
+
+```ts
+import { primaryId, timestamps } from "@digimuza/saas-core/db/schema";
+
+export const documents = pgTable("documents", {
+  id: primaryId(),
+  ...timestamps,   // createdAt, updatedAt
+});
+```
+
+---
+
+## Constraint error introspection
+
+```ts
+import { isUniqueViolation, isForeignKeyViolation, getPostgresError } from "@digimuza/saas-core/db";
+```
+
+Tenant isolation in this schema *is* a set of database constraints, so services
+need to tell "duplicate slug" from "cross-workspace role" from an unrelated
+failure.
+
+```ts
+try {
+  await db.insert(workspaces).values({ name, slug });
+} catch (error) {
+  if (isUniqueViolation(error, "workspaces_slug_unique")) {
+    throw new ConflictError("Slug taken.");
+  }
+  throw error;
+}
+```
+
+Always pass the constraint name. Matching on the code alone will absorb unrelated
+violations — a bug the core itself had: `ensureCustomer` treated *any* unique
+violation as "a concurrent request won the race", which silently swallowed a
+provider returning an id already bound to another workspace.
+
+The helper walks the error's `cause` chain and accepts both spellings, because
+postgres.js puts `code`/`constraint_name` on the thrown error while Drizzle's
+PGlite driver nests `code`/`constraint` under `cause`.
+
+---
+
+## Table ownership
+
+Core-owned: `users`, `user_profiles`, `workspaces`, `workspace_members`,
+`workspace_invitations`, `roles`, `permissions`, `role_permissions`,
+`workspace_member_roles`, `plans`, `entitlements`, `billing_customers`,
+`subscriptions`, `billing_events`, `usage_records`, `events`.
+
+Your application owns everything else. Do not add product-specific models to the
+core unless they clearly apply to several products.
+
+---
+
+## Testing against real PostgreSQL
+
+The core's own tests use `@electric-sql/pglite` — PostgreSQL compiled to WASM — and
+run the real migrations:
+
+```ts
+import { PGlite } from "@electric-sql/pglite";
+import { drizzle } from "drizzle-orm/pglite";
+import { migrate } from "drizzle-orm/pglite/migrator";
+import { coreMigrationsFolder } from "@digimuza/saas-core/db";
+import * as schema from "@digimuza/saas-core/db/schema";
+
+const client = new PGlite();
+const db = drizzle(client, { schema });
+await migrate(db, { migrationsFolder: coreMigrationsFolder });
+```
+
+Real PostgreSQL rather than a mock, because the guarantees under test *are*
+database constraints — composite foreign keys, partial unique indexes, cascades. A
+fake would happily accept the cross-tenant writes the schema exists to reject.