@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/api-saas/package.json

@@ -13,20 +13,20 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/plugin-analytics-postgres": "0.28.0",
-    "@voltro/plugin-billing": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/plugin-notifications": "0.28.0",
-    "@voltro/plugin-presence": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
-    "@voltro/sql-postgres": "0.28.0",
+    "@voltro/cli": "0.30.0",
+    "@voltro/database": "0.30.0",
+    "@voltro/plugin-analytics-postgres": "0.30.0",
+    "@voltro/plugin-billing": "0.30.0",
+    "@voltro/plugin-multitenancy": "0.30.0",
+    "@voltro/plugin-notifications": "0.30.0",
+    "@voltro/plugin-presence": "0.30.0",
+    "@voltro/protocol": "0.30.0",
+    "@voltro/runtime": "0.30.0",
+    "@voltro/sql-postgres": "0.30.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.30.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-saas-starter/README.md

@@ -0,0 +1,103 @@
+# {{capProjectName}} {{capAppName}} — the full SaaS backend
+
+The whole SaaS loop wired end to end in ONE api — **sign up → hit a paywall →
+upgrade → invite a teammate** — composing two shipped plugins that are normally
+wired separately, plus a small tenant-scoped domain. Boots **zero-infra**
+(`store: 'memory'`, `mock` billing provider, in-process users).
+
+Pair it with the **frontend-saas** web template for the dashboard UI:
+
+```bash
+voltro init my-saas --api=api-saas-starter --web=frontend-saas
+```
+
+## What it composes
+
+- **Auth** ([`@voltro/plugin-auth`](https://voltro.cloud/docs/plugins/auth)) —
+  password **sign-up / sign-in / sign-out** over an HttpOnly **session cookie**,
+  and `voltroPasswordStrategy` resolving that cookie into a typed `Subject` on
+  every rpc/ws call. `session.me` returns it (the frontend's SSR gate reads it).
+- **Billing** ([`@voltro/plugin-billing`](https://voltro.cloud/docs/plugins/overview)) —
+  subscriptions + **entitlements** over the in-memory `mock` provider. `plans`
+  is the single source of tier→quota truth: `free` caps `projects` at 3 and
+  `seats` at 1; `pro` lifts both.
+- **Domain** — tenant-scoped `projects` + `invites`. `projects.create` spends
+  the `projects` quota; `invites.create` spends the `seats` quota. Over quota →
+  typed **`EntitlementExceeded`** (the paywall signal), the row never written.
+
+## The loop
+
+| Step | Call | Result |
+|---|---|---|
+| Sign up | `POST /auth/sign-up` | session cookie; lands in tenant `acme` on the `free` plan |
+| Work | `projects.create` ×3 | ok |
+| **Paywall** | `projects.create` (4th) | typed `EntitlementExceeded { entitlement: 'projects', limit: 3 }` |
+| Upgrade | `billing.startCheckout` → `pro` | `projects` becomes `unlimited`, `seats` → 10 |
+| Invite | `invites.create` | spends a `seats` entitlement |
+| Buy seats | `billing.changeSeats` | raises the seat quantity |
+
+`billing.*` (`subscription`, `startCheckout`, `changePlan`, `changeSeats`,
+`invoices`) and `/auth/*` are contributed by the plugins — you don't author them.
+
+## Run it
+
+```bash
+voltro dev .
+# → http://localhost:4000   (rpc + /auth/* HTTP routes)
+```
+
+`voltro dev` mints a unique `VOLTRO_SESSION_SECRET` into a gitignored
+`.env.local` on first boot — no secret ships with the template.
+
+### Try the loop (curl)
+
+```bash
+# Sign up (CSRF-protected — grab a token first, keep the cookie jar)
+curl -s -c jar.txt http://localhost:4000/auth/csrf                     # → { "csrfToken": "<csrf>" }
+curl -s -b jar.txt -c jar.txt -X POST http://localhost:4000/auth/sign-up \
+  -H 'content-type: application/json' -H 'x-csrf-token: <csrf>' \
+  -d '{"email":"ada@example.com","password":"hunter2hunter2"}'
+
+# Create projects — the free plan allows 3, the 4th trips the paywall
+for i in 1 2 3 4; do
+  curl -s -b jar.txt -X POST http://localhost:4000/_voltro/inspect/invoke \
+    -H 'content-type: application/json' \
+    -d "{\"tag\":\"projects.create\",\"input\":{\"name\":\"Project $i\"}}"
+done
+# → the 4th: { "ok": false, "error": { "_tag": "EntitlementExceeded", "entitlement": "projects", "limit": 3, … } }
+```
+
+## Files
+
+```
+app.config.ts                 authRoutesPlugin + voltroPasswordStrategy + billingPlugin (free/pro plans)
+database/schema.ts            core actors/tenants + tenant-scoped projects + invites
+actions/me.action.ts(.server) session.me — the resolved Subject (SSR gate reads it)
+queries/
+  projects.list.query.*       live, tenant-scoped subscription
+  invites.list.query.*        live, tenant-scoped subscription
+mutations/
+  projects.create.*           entitlement-gated (projects quota → paywall)
+  invites.create.*            entitlement-gated (seats quota)
+tests/                        descriptor pins + tenant isolation + session.me
+```
+
+## Going to production
+
+| Want… | Do |
+|---|---|
+| Durable accounts | swap `memoryUserStore()` for `postgresUserStore({ sql })` + `store: 'postgres'` |
+| Real Stripe checkout | `billingPlugin({ provider: 'stripe', apiKey, webhookSecret, plans })` with real `priceId`s |
+| Email flows (magic-link, reset) | pass `sendEmail: mailSender(mailService)` from `@voltro/plugin-mail` |
+| Cookie hardening | `cookieSecure: true` (+ `cookieDomain`) — already ON in production here |
+
+## Anti-patterns
+
+- **Authoring your own `billing.*` / `/auth/*` procedures.** The plugins own
+  those namespaces — boot fails on a collision. Use the plugin routes + services.
+- **Skipping the entitlement gate on a paid action.** A scope says "may you call
+  this"; an entitlement says "do you have quota left". `requireEntitlement` is
+  one line and fails closed — that's what makes the paywall real.
+- **Reading `VOLTRO_SESSION_SECRET` at config time for a fallback.** The plugin
+  reads it per request, after the env gate mints it. A hardcoded fallback is a
+  published signing key.

package/templates/apps/api-saas-starter/actions/me.action.server.ts

@@ -0,0 +1,18 @@
+// Executor for `session.me`. Reads the Subject the AuthMiddleware resolved (via
+// voltroPasswordStrategy reading the session cookie) and returns it.
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (_input: Record<string, never>, ctx: AppContext) => {
+  const subject = ctx.request.subject as {
+    readonly type: string
+    readonly id: string | null
+    readonly tenantId: string | null
+  }
+  return {
+    type:     subject.type,
+    id:       subject.id ?? null,
+    tenantId: subject.tenantId ?? null,
+  }
+}
+
+export default execute

package/templates/apps/api-saas-starter/actions/me.action.ts

@@ -0,0 +1,20 @@
+// `session.me` — returns the caller's resolved identity. This is the proof the
+// auth loop works end-to-end, and the frontend's SSR auth gate reads it: call
+// it with no session cookie and you get an anonymous Subject; sign in via POST
+// /auth/sign-in (which sets the cookie), call it again, and
+// `voltroPasswordStrategy` has resolved that cookie into a `user` Subject.
+// Browser-safe descriptor — no server imports here.
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const me = defineAction({
+  name:  'session.me',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    // 'anonymous' | 'user' | 'apiKey' | 'serviceAccount'
+    type:     Schema.String,
+    // null while anonymous; the user id once signed in.
+    id:       Schema.NullOr(Schema.String),
+    tenantId: Schema.NullOr(Schema.String),
+  }),
+})

package/templates/apps/api-saas-starter/app.config.ts

@@ -0,0 +1,87 @@
+// The SaaS backend for the {{projectName}} project — the WHOLE loop in one api.
+// Read by `voltro dev`.
+//
+// It composes two shipped plugins that are normally wired separately, plus a
+// small tenant-scoped domain (projects + invites), so that signup → paywall →
+// app works out of the box:
+//
+//   • @voltro/plugin-auth   — password sign-up/in/out over an HttpOnly session
+//     cookie, and a strategy that resolves that cookie into a typed `Subject`
+//     on every rpc/ws call (so handlers read `ctx.request.subject`).
+//   • @voltro/plugin-billing — subscriptions + ENTITLEMENTS over a pluggable
+//     provider. `plans` is the single source of tier→quota truth. The handlers
+//     call `requireEntitlement(...)`, which consumes the tenant's metered
+//     quota and fails typed `EntitlementExceeded` when it's exhausted — that
+//     typed failure IS the paywall signal the frontend upgrades on.
+//
+// The domain then ties them together: `projects.create` spends a `projects`
+// quota (free = 3), and `invites.create` spends a `seats` quota (free = 1) — so
+// the free plan runs out and upgrading to `pro` (via `billing.startCheckout`)
+// lifts the caps. Boots ZERO-infra (`store: 'memory'`, `mock` billing provider,
+// `memoryUserStore`); the README shows the production swaps.
+import { defineEnv, envVar } from '@voltro/env'
+import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
+import { billingPlugin } from '@voltro/plugin-billing'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // HMAC key that signs + verifies the session cookie.
+  //
+  // `generate` means this project mints its OWN key: `voltro dev` writes a
+  // unique value into a gitignored `.env.local` on first boot. No value ships
+  // with the template — a shipped placeholder would be a signing key published
+  // to everyone who downloads it, and every session in every deployment built
+  // from it would be forgeable. Your DEPLOYMENT mints its own the same way (a
+  // missing secret is a hard boot failure in `serve`/`build`/`start`).
+  VOLTRO_SESSION_SECRET: envVar.secret({
+    generate: 'base64url',
+    description: 'HMAC key that signs and verifies session cookies.',
+  }),
+})
+
+// In-process user store — zero infra. `postgresUserStore({ sql })` for durable
+// accounts (it manages its own `_voltro_auth_*` tables, auto-migrated).
+const userStore = memoryUserStore()
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    // ── Auth ─────────────────────────────────────────────────────────────
+    authRoutesPlugin({
+      store: userStore,
+      // New sign-ups land in this tenant. Every table below carries `tenant()`,
+      // so the runtime AND-merges `tenantId = subject.tenantId` into reads —
+      // one tenant never sees another's projects or invites.
+      defaultTenantId: 'acme',
+      successRedirect: '/',
+      // `Secure` cookies are HTTPS-only, so OFF in dev (a localhost http page
+      // would silently drop the cookie) and ON in production — this is what
+      // makes the sign-in → session → authenticated-call loop work locally.
+      cookieSecure: process.env.NODE_ENV === 'production',
+    }),
+    // ── Billing ──────────────────────────────────────────────────────────
+    // `mock` is the in-memory provider (no Stripe key needed) — great for dev.
+    // `plans` is the single source of tier→quota truth: `free` caps projects at
+    // 3 and seats at 1; `pro` lifts both. Swap `provider: 'stripe'` (+
+    // STRIPE_SECRET_KEY) and real `priceId`s for production checkout.
+    billingPlugin({
+      provider: 'mock',
+      plans: {
+        free: { entitlements: { projects: 3, seats: 1 } },
+        pro:  {
+          priceId: 'price_demo_pro',
+          entitlements: { projects: 'unlimited', seats: 10 },
+        },
+      },
+    }),
+  ],
+  auth: {
+    // Resolves the session cookie the /auth routes mint into the request's
+    // Subject. Reads the SAME VOLTRO_SESSION_SECRET the routes sign with, so
+    // the signing and verifying sides cannot drift.
+    strategies: [voltroPasswordStrategy()],
+  },
+}

package/templates/apps/api-saas-starter/database/schema.ts

@@ -0,0 +1,57 @@
+// Schema for the {{projectName}} SaaS backend.
+//
+// Two tenant-scoped domain tables — `projects` and `invites`. The plugins
+// contribute their OWN tables automatically (auth uses the in-process
+// `memoryUserStore`; billing adds `_voltro_billing_*`), so you don't declare
+// those here. `actors` + `tenants` are the framework's core tables the audit /
+// tenant mixins reference.
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application tables ----------
+
+// Creating a project spends the billing `projects` entitlement (free = 3) —
+// see mutations/projects.create.
+export const projects = table('projects', {
+  id:   id({ prefix: 'proj' }),
+  name: text(),
+})
+  // tenant() pulls audit() transitively → tenantId + createdAt / updatedAt /
+  // createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+
+// Inviting a teammate spends the billing `seats` entitlement (free = 1) — see
+// mutations/invites.create.
+export const invites = table('invites', {
+  id:     id({ prefix: 'inv' }),
+  email:  text(),
+  status: text().oneOf(['pending', 'accepted', 'revoked']),
+})
+  .with(tenant())
+
+export type Project = InferRow<typeof projects>
+export type Invite = InferRow<typeof invites>
+
+export const database = databaseHandle({ actors, tenants, projects, invites })

package/templates/apps/api-saas-starter/mutations/invites.create.mutation.server.ts

@@ -0,0 +1,26 @@
+// Effect-mode: gate on the `seats` entitlement (free = 1), then write the
+// pending invite. Because the free plan grants a single seat, the FIRST invite
+// after sign-up already trips `EntitlementExceeded` unless the tenant has
+// upgraded / bought seats — which is exactly the seat-management moment the
+// frontend's team page surfaces.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+import { requireEntitlement } from '@voltro/plugin-billing'
+
+const execute = (input: { email: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    yield* requireEntitlement(ctx, 'seats', 1)
+
+    const store = yield* EffectStore
+    const row = yield* store.insert('invites', { email: input.email, status: 'pending' })
+
+    return {
+      id:       row['id'] as string,
+      email:    row['email'] as string,
+      status:   row['status'] as string,
+      tenantId: row['tenantId'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-saas-starter/mutations/invites.create.mutation.ts

@@ -0,0 +1,18 @@
+// Invite a teammate — spends a `seats` entitlement. Same shape as
+// projects.create: the billing plugin merges `EntitlementExceeded` into the
+// wire-error union, so running out of seats surfaces typed and the frontend
+// shows "buy more seats" (billing.changeSeats) instead of a generic error.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createInvite = defineMutation({
+  name:   'invites.create',
+  target: { table: 'invites', op: 'insert' },
+  input:  Schema.Struct({ email: Schema.NonEmptyString }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    email:    Schema.String,
+    status:   Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-saas-starter/mutations/projects.create.mutation.server.ts

@@ -0,0 +1,29 @@
+// Effect-mode so it can `yield*` the billing service the framework provides in
+// the per-request stack. `requireEntitlement` consumes the tenant's metered
+// `projects` quota (free = 3) and fails typed `EntitlementExceeded` when it's
+// exhausted — BEFORE the row is written, so an over-quota create never leaves a
+// partial write. Upgrading to `pro` (via `billing.startCheckout`) lifts the cap
+// to `unlimited` and the same handler starts succeeding again.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+import { requireEntitlement } from '@voltro/plugin-billing'
+
+const execute = (input: { name: string }, ctx: AppContext) =>
+  Effect.gen(function* () {
+    // 1. Billing gate — fails closed (typed EntitlementExceeded) when the
+    //    tenant has no `projects` quota left. Runs BEFORE the write.
+    yield* requireEntitlement(ctx, 'projects', 1)
+
+    // 2. Write the row. `tenant()` auto-stamps tenantId + audit columns.
+    const store = yield* EffectStore
+    const row = yield* store.insert('projects', { name: input.name })
+
+    return {
+      id:       row['id'] as string,
+      name:     row['name'] as string,
+      tenantId: row['tenantId'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-saas-starter/mutations/projects.create.mutation.ts

@@ -0,0 +1,18 @@
+// Create a project — the paywall in ONE handler. The billing plugin auto-merges
+// its typed `EntitlementExceeded` (+ `BillingError`) into this procedure's
+// wire-error union, so the client decodes the over-quota failure typed WITHOUT
+// a manual `error:` declaration here. That typed failure is the paywall signal:
+// the frontend catches `_tag === 'EntitlementExceeded'` and shows the upgrade CTA.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createProject = defineMutation({
+  name:   'projects.create',
+  target: { table: 'projects', op: 'insert' },
+  input:  Schema.Struct({ name: Schema.NonEmptyString }),
+  output: Schema.Struct({
+    id:       Schema.String,
+    name:     Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-saas-starter/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.97.0",
+    "@effect/rpc": "^0.76.0",
+    "@voltro/cli": "0.30.0",
+    "@voltro/database": "0.30.0",
+    "@voltro/env": "0.30.0",
+    "@voltro/plugin-auth": "0.30.0",
+    "@voltro/plugin-billing": "0.30.0",
+    "@voltro/plugin-multitenancy": "0.30.0",
+    "@voltro/protocol": "0.30.0",
+    "@voltro/runtime": "0.30.0",
+    "@voltro/sql-postgres": "0.30.0",
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.30.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/api-saas-starter/queries/invites.list.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'invites' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

package/templates/apps/api-saas-starter/queries/invites.list.query.ts

@@ -0,0 +1,17 @@
+// Streaming subscription of the tenant's teammate invites. Tenant-scoped like
+// projects.list — read live from the frontend's team page with
+// `useSubscription('app', 'invites.list')`.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listInvites = defineQuery({
+  name: 'invites.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:        Schema.String,
+    email:     Schema.String,
+    status:    Schema.String,
+    tenantId:  Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-saas-starter/queries/projects.list.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'projects' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

package/templates/apps/api-saas-starter/queries/projects.list.query.ts

@@ -0,0 +1,18 @@
+// Streaming subscription of the tenant's projects. Every change to `projects`
+// for the caller's tenant lands as a delta — the frontend upgrades its first
+// paint to live with `useSubscription('app', 'projects.list')`. The runtime
+// AND-merges the tenant predicate (the table carries `tenant()`), so this never
+// leaks across tenants — no manual `eq('tenantId', ...)` needed.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listProjects = defineQuery({
+  name: 'projects.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:        Schema.String,
+    name:      Schema.String,
+    tenantId:  Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-saas-starter/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-saas-starter",
+  "kind": "api",
+  "summary": "The whole SaaS loop wired end to end: @voltro/plugin-auth (sign-up/in → session cookie → typed Subject) + @voltro/plugin-billing (free/pro plans, entitlement paywall, seats, checkout) + a tenant-scoped projects + invites backend. projects.create is gated by the billing `projects` quota (4th trips EntitlementExceeded); invites.create consumes a `seats` entitlement. Pair with the frontend-saas web template for signup → paywall → app. Boots zero-infra.",
+  "tags": ["api", "saas", "auth", "billing", "entitlements", "paywall", "seats", "invites", "starter"]
+}

package/templates/apps/api-saas-starter/tests/projects.create.test.ts

@@ -0,0 +1,62 @@
+// Unit tests with `@voltro/testing` — no database, no running server, no
+// billing backend. The create executors run in Effect mode and `yield*` the
+// billing service (`requireEntitlement`), which lives in the per-request plugin
+// layer the unit harness does NOT wire — so we do not fake it. Instead we PIN
+// each descriptor's wire contract (the shape the client codegen + the paywall
+// branch depend on) and prove the `tenant()` scoping that keeps one SaaS
+// tenant's rows invisible to another — the headline isolation guarantee.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema'   // registers projects / invites / actors / tenants
+import { createProject } from '../mutations/projects.create.mutation'
+import { createInvite } from '../mutations/invites.create.mutation'
+
+describe('projects.create descriptor', () => {
+  it('decodes a valid input and rejects a blank name', () => {
+    const decode = Schema.decodeUnknownSync(createProject.input)
+    expect(decode({ name: 'Acme App' })).toEqual({ name: 'Acme App' })
+    // `name: Schema.NonEmptyString` — an empty string fails the wire decode.
+    expect(() => decode({ name: '' })).toThrow()
+  })
+
+  it('encodes the output shape the client expects', () => {
+    const encode = Schema.encodeUnknownSync(createProject.output)
+    const wire = encode({ id: 'proj_1', name: 'Acme App', tenantId: 'acme' })
+    expect(wire).toEqual({ id: 'proj_1', name: 'Acme App', tenantId: 'acme' })
+  })
+})
+
+describe('invites.create descriptor', () => {
+  it('decodes an email and rejects a blank one', () => {
+    const decode = Schema.decodeUnknownSync(createInvite.input)
+    expect(decode({ email: 'ada@example.com' })).toEqual({ email: 'ada@example.com' })
+    expect(() => decode({ email: '' })).toThrow()
+  })
+
+  it('encodes the invite output shape', () => {
+    const encode = Schema.encodeUnknownSync(createInvite.output)
+    const wire = encode({ id: 'inv_1', email: 'ada@example.com', status: 'pending', tenantId: 'acme' })
+    expect(wire).toEqual({ id: 'inv_1', email: 'ada@example.com', status: 'pending', tenantId: 'acme' })
+  })
+})
+
+describe('tenant isolation (REAL tenant scoping)', () => {
+  it('t2 never sees t1 projects', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ projects: [], invites: [] }),
+    })
+    // Raw insert through the mixin store — tenant() auto-stamps tenantId=t1.
+    const row = await ctx.store.insert('projects', { name: 'secret' })
+    expect(row['tenantId']).toBe('t1')
+
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.projects.descriptor))
+    expect(seenByT2).toHaveLength(0)
+    // …and t1 still sees its own row.
+    const seenByT1 = await ctx.store.query(database.projects.descriptor)
+    expect(seenByT1).toHaveLength(1)
+  })
+})

package/templates/apps/api-saas-starter/tests/session.test.ts

@@ -0,0 +1,33 @@
+// `session.me` returns the caller's resolved identity — the proof the auth loop
+// threads the Subject through to handlers, and the value the frontend's SSR gate
+// reads to decide redirect-to-login vs render. `makeTestContext({ subject })`
+// sets `ctx.request.subject` to exactly what the AuthMiddleware would resolve at
+// runtime, so the executor is fully runnable with no cookie, no session store,
+// no running server. Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext } from '@voltro/testing'
+import '../database/schema'   // registers actors / tenants
+import me from '../actions/me.action.server'
+
+describe('session.me', () => {
+  it('reflects a signed-in user Subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+    })
+    const identity = await me({}, ctx)
+
+    expect(identity.type).toBe('user')
+    expect(identity.id).toBe('user_1')
+    expect(identity.tenantId).toBe('acme')
+  })
+
+  it('returns an anonymous identity with null id/tenant when no session is present', async () => {
+    const ctx = makeTestContext()
+    const identity = await me({}, ctx)
+
+    expect(identity.type).toBe('anonymous')
+    expect(identity.id).toBeNull()
+    expect(identity.tenantId).toBeNull()
+  })
+})

package/templates/apps/api-saas-starter/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}