@voltro/cli 0.1.0

package/templates/apps/api-auth/README.md

@@ -0,0 +1,109 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-auth**).
+
+Real user authentication, wired turnkey with
+[`@voltro/plugin-auth`](https://voltro.cloud/docs/plugins/auth): password
+**sign-up / sign-in / sign-out** over HttpOnly **session cookies**, a strategy
+that resolves the session into a typed `Subject` on every rpc call, and a
+`session.me` action that proves the loop end-to-end. Boots with **zero infra**
+(`memoryUserStore()`).
+
+## Boot
+
+```bash
+pnpm install
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000   (rpc + /auth/* HTTP routes)
+```
+
+The shipped `.env` supplies a DEV-ONLY `VOLTRO_SESSION_SECRET` so it boots out
+of the box. **Replace it before production** (`openssl rand -hex 32`) — see
+Environment below.
+
+## The two pieces
+
+`app.config.ts` wires both halves with ONE shared secret:
+
+```ts
+plugins: [
+  authRoutesPlugin({ store: memoryUserStore(), secret: SECRET, defaultTenantId: 'acme' }),
+],
+auth: {
+  strategies: [voltroPasswordStrategy({ secret: SECRET })],
+},
+```
+
+- **`authRoutesPlugin`** mounts the HTTP auth surface under `/auth/*` and
+  **signs** the session cookie on success.
+- **`voltroPasswordStrategy`** runs in the AuthMiddleware chain on every
+  rpc/ws call, **verifies** that cookie, and resolves it to a `Subject` — so
+  handlers read the user via `ctx.request.subject`.
+
+They MUST share the same `secret` (one signs, the other verifies). The template
+reads `VOLTRO_SESSION_SECRET` once and passes it to both.
+
+## Try the loop (curl)
+
+State-changing routes are CSRF-protected, so grab a token first. (`session.me`
+is an rpc procedure — invoke it over HTTP via the dev inspect endpoint, which
+forwards your session cookie; from a browser you'd use `useAction('app',
+'session.me')`.)
+
+```bash
+# 1. Get a CSRF token (also sets the csrf cookie into the jar)
+curl -s -c jar.txt http://localhost:4000/auth/csrf
+#    → { "csrfToken": "<csrf>" }
+
+# 2. Sign up (sets the HttpOnly session cookie into the jar)
+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"}'
+#    → { "ok": true, "subject": { "type": "user", "id": "u_…", "tenantId": "acme" } }
+
+# 3. Call session.me, forwarding the session cookie → you're a `user`
+curl -s -b jar.txt -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"session.me","input":{}}'
+#    → { "ok": true, "result": { "type": "user", "id": "u_…", "tenantId": "acme" } }
+```
+
+Call `session.me` WITHOUT the cookie and `type` is `"anonymous"` with a null
+`id` — that's the strategy resolving (or not resolving) the session. (Note: the
+session cookie is `Secure` only in production — see `cookieSecure` in
+`app.config.ts` — so the loop works over plain-HTTP `localhost` in dev.)
+
+`/auth/*` also exposes `sign-in`, `sign-out`, `password-reset`,
+`magic-link`, session management (`/auth/sessions`), and tenant memberships —
+see the plugin docs.
+
+## Environment
+
+| Var | Access | Why |
+|---|---|---|
+| `VOLTRO_SESSION_SECRET` | secret | HMAC key signing + verifying the session cookie. The shipped `.env` is a DEV-ONLY placeholder; generate a real one (`openssl rand -hex 32`) and set it in your deployment's secrets. Rotating it invalidates all existing sessions. |
+| `LOG_LEVEL` | public | `debug \| info \| warn \| error` (default `info`). |
+
+## Files
+
+```
+app.config.ts                 authRoutesPlugin + voltroPasswordStrategy + memoryUserStore
+.env                          DEV-ONLY VOLTRO_SESSION_SECRET
+database/schema.ts            core actors + tenants (users live in the memory store)
+actions/
+  me.action.ts(.server)       session.me — returns the resolved Subject
+```
+
+## Going to production
+
+- **Durable accounts** — swap `memoryUserStore()` for `postgresUserStore({ sql })`
+  and `store: 'postgres'`. The postgres store manages its own auth tables
+  (auto-migrated).
+- **Email flows** — pass `sendEmail: mailSender(mailService)` (from
+  `@voltro/plugin-mail`) to `authRoutesPlugin` so magic-link + password-reset
+  can deliver. Without it those routes still mint tokens but return `202`.
+- **Cookie hardening** — set `cookieSecure: true` (and `cookieDomain`) for
+  HTTPS deployments.
+- **Pair with a frontend** — `frontend-app` shows the reactive client; add a
+  login form that POSTs to `/auth/sign-in`, and authenticated rpc calls carry
+  the session cookie automatically.

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

@@ -0,0 +1,20 @@
+// 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) => {
+  // The Subject union: { type: 'anonymous' | 'user' | 'apiKey' | 'serviceAccount',
+  // id: string | null, tenantId: string | null }.
+  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-auth/actions/me.action.ts

@@ -0,0 +1,19 @@
+// `session.me` — returns the caller's resolved identity. This is the proof the
+// auth loop works end-to-end: 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-auth/app.config.ts

@@ -0,0 +1,59 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// This template wires REAL user authentication with @voltro/plugin-auth:
+//   - `authRoutesPlugin(...)` mounts the password auth surface under /auth/*
+//     (POST /auth/sign-up, /auth/sign-in, /auth/sign-out, GET /auth/csrf,
+//     password-reset, magic-link, session management, …). It sets an HttpOnly
+//     session cookie on success.
+//   - `voltroPasswordStrategy(...)` runs in the AuthMiddleware chain: it reads
+//     that session cookie off every rpc/ws call and resolves it to a typed
+//     `Subject` — so handlers see the authenticated user via
+//     `ctx.request.subject` (see actions/me.action.server.ts).
+//
+// `memoryUserStore()` keeps users/sessions in-process, so it boots with ZERO
+// infra. Swap it for `postgresUserStore({ sql })` (and `store: 'postgres'`)
+// for durable accounts.
+import { defineEnv, envVar } from '@voltro/env'
+import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@voltro/plugin-auth'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // The HMAC key that signs + verifies session cookies. Declared here so it
+  // shows in `voltro env` and the boot gate fails loud if it's unset. The
+  // shipped `.env` supplies a DEV-ONLY value; generate a real one for prod
+  // (`openssl rand -hex 32`).
+  VOLTRO_SESSION_SECRET: envVar.string({ access: 'secret' }),
+})
+
+// Read once at config time and pass to BOTH the routes plugin (which signs
+// sessions) and the strategy (which verifies them) so they can never drift.
+// process.env is populated by the loaded `.env`; this is the documented shape
+// for a config-time secret (the typed `serverEnv` snapshot isn't ready yet).
+const SECRET = process.env.VOLTRO_SESSION_SECRET ?? 'dev-only-unsafe-session-secret-change-me'
+
+// In-process user store — zero infra. `postgresUserStore({ sql })` for durable.
+const userStore = memoryUserStore()
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  env,
+  plugins: [
+    authRoutesPlugin({
+      store: userStore,
+      secret: SECRET,
+      defaultTenantId: 'acme',     // tenant new sign-ups land in
+      successRedirect: '/',        // where the browser-form flow redirects after sign-in
+      // `Secure` cookies are HTTPS-only — so OFF in dev (http://localhost would
+      // silently drop the session cookie), ON in production. This is what makes
+      // the sign-in → session → authenticated-call loop actually work locally.
+      cookieSecure: process.env.NODE_ENV === 'production',
+    }),
+  ],
+  auth: {
+    // Runs after the built-in signed-cookie strategy; resolves the session
+    // cookie this app's /auth routes mint into the request's Subject.
+    strategies: [voltroPasswordStrategy({ secret: SECRET })],
+  },
+}

package/templates/apps/api-auth/database/schema.ts

@@ -0,0 +1,26 @@
+// Minimal schema. Auth users + sessions live in the `memoryUserStore()`
+// (in-process), NOT in these tables — so there's no users table here. These
+// are the framework core tables every app declares.
+//
+// When you switch to `postgresUserStore({ sql })`, that store manages its own
+// `_voltro_auth_*` tables (auto-migrated); you still keep these core tables for
+// your own domain data.
+import { databaseHandle, id, table, text, timestamp } from '@voltro/database'
+
+// The universal audit subject (user / serviceAccount / apiKey / system).
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+// The multi-tenancy boundary. New sign-ups land in `defaultTenantId` (see
+// app.config.ts → authRoutesPlugin).
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+export const database = databaseHandle({ actors, tenants })

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

@@ -0,0 +1,28 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-auth": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-auth/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-auth",
+  "kind": "api",
+  "summary": "Real user auth — @voltro/plugin-auth wired turnkey: password sign-up/in/out + HttpOnly session cookies over /auth/*, a voltroPasswordStrategy that resolves the session to a typed Subject, and a session.me action proving it end-to-end. Boots zero-infra (memoryUserStore).",
+  "tags": ["api", "auth", "authentication", "sessions", "login", "plugin-auth", "cookies"]
+}

package/templates/apps/api-auth/tests/me.test.ts

@@ -0,0 +1,37 @@
+// Unit test with `@voltro/testing`. `session.me` returns the caller's resolved
+// identity — the proof the auth loop threads the Subject through to handlers.
+// `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.
+//
+// (This template has no DB-write primitive — the identity read IS the runnable
+// unit here.) 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 () => {
+    // Default `makeTestContext()` subject is the anonymous Subject
+    // ({ type: 'anonymous', id: null, tenantId: null }).
+    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-auth/tsconfig.json

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

package/templates/apps/api-backend/README.md

@@ -0,0 +1,25 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-backend**).
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+## What's in here
+
+| File | Role |
+|---|---|
+| `app.config.ts`                          | App declaration; `voltro dev` reads this first. |
+| `database/schema.ts`                     | One example table (`notes`) with the `tenant()` mixin. |
+| `routes/notes.route.tsx`                 | Streaming subscription example. |
+| `mutations/notes.create.mutation.tsx`    | Tenant-guarded mutation example. |
+
+Drop more `*.route.tsx`, `*.mutation.tsx`, `*.action.tsx`, or
+`*.workflow.tsx` files anywhere in this tree — discovery is by file
+convention.

package/templates/apps/api-backend/app.config.ts

@@ -0,0 +1,39 @@
+// Backend app for the {{projectName}} project. Read by `voltro dev`.
+//
+// `store: 'memory'` is the dev-friendly default — fast startup, no
+// docker. Switch to `'postgres'` when you wire `docker compose up`
+// from the repo root.
+//
+// `plugins` composes cross-cutting behaviour. Drop entries here to
+// audit-log mutations, run authz checks, ship webhooks, etc. See
+// @voltro/plugin-audit for a reference plugin.
+//
+// OPTIONAL infra knobs — both are ON by default with a zero-infra backend,
+// so you only touch them to go distributed (see the commented lines below):
+//   • `cache:` — the query/result cache (`ctx.cache`). Default `memory`
+//     (in-process). Set `'redis'` for a cross-instance cache — or just run
+//     `voltro add redis`, which flips this and provisions the infra for you.
+//   • `kv:` — the durable key-value store (`ctx.kv`, for state you CAN'T
+//     recompute: cursors, onboarding progress, tokens). Default `database`
+//     (durable, shared across replicas). `'redis'` needs a PERSISTENT redis;
+//     `'memory'` is dev-only. Env `CACHE_BACKEND` / `KV_BACKEND` override.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed environment — declare your env once; it's validated at boot (fail-fast)
+// and read on the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+// `access` is required: 'public' (browser-safe) or 'secret' (server-only, never
+// bundled). Run `voltro env` to see the manifest. See the Environment docs.
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // Add your own, e.g.:
+  //   STRIPE_KEY: envVar.string({ access: 'secret' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  // cache: 'redis' as const,      // distributed query/result cache (or: voltro add redis)
+  // kv:    'redis' as const,      // durable ctx.kv on Redis (default 'database' — durable)
+  env,
+}

package/templates/apps/api-backend/database/schema.ts

@@ -0,0 +1,57 @@
+// Schema for the {{projectName}} backend.
+//
+// Tables are auto-discovered: every exported `table(...)` in this file
+// (or any `*.entity.ts` / `*.schema.ts` file) is registered by
+// `voltro dev` — no manual barrel. `actors` + `tenants` are the
+// framework's core tables: the built-in `audit()` / `tenant()` /
+// `softDelete()` mixins reference them, so they must be declared (the
+// CLI wires them into the mixin registry once it finds them).
+//
+// Add the `tenant()` mixin to a table to make it tenant-scoped — the
+// runtime AND-merges `eq('tenantId', subject.tenantId)` into every
+// subscription predicate, so cross-tenant reads can't leak.
+
+import {
+  boolean,
+  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 — rename / replace with your own ----------
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+  done:  boolean().default(false),
+})
+  // tenant() pulls audit() transitively → adds tenantId + createdAt /
+  // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+  // Opt into the matcher engine: subscriptions against `notes` get a
+  // fresh snapshot/delta whenever a mutation writes the table.
+  .reactive()
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

package/templates/apps/api-backend/mutations/notes.create.mutation.server.ts

@@ -0,0 +1,19 @@
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; title: string; body: string },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // Framework auto-injects a `note_…` id from the table's id() decl.
+  return ctx.store.insert('notes', {
+    title: input.title,
+    body: input.body,
+    done: false,
+    tenantId: input.tenantId,
+    createdAt: new Date(),
+  })
+}
+
+export default execute

package/templates/apps/api-backend/mutations/notes.create.mutation.ts

@@ -0,0 +1,37 @@
+// Creates a note. The handler's `assertOwnTenant` guard rejects
+// cross-tenant spoofing — input.tenantId MUST match the resolved
+// subject's tenantId, else the rpc layer surfaces a typed
+// `TenantMismatch` error.
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: {
+    table: 'notes',
+    op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string }) => ({
+      title: input.title,
+      body: input.body,
+      done: false,
+      tenantId: input.tenantId,
+      createdAt: new Date(),
+    }),
+  },
+  input: Schema.Struct({
+    tenantId: Schema.String,
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+  error: TenantMismatch,
+})

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

@@ -0,0 +1,28 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.96.1",
+    "@effect/rpc": "^0.75.1",
+    "@voltro/cli": "0.1.0",
+    "@voltro/database": "0.1.0",
+    "@voltro/env": "0.1.0",
+    "@voltro/plugin-multitenancy": "0.1.0",
+    "@voltro/protocol": "0.1.0",
+    "@voltro/runtime": "0.1.0",
+    "effect": "^3.21.2"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.1.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/templates/apps/api-backend/queries/notes.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'notes' 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-backend/queries/notes.query.ts

@@ -0,0 +1,20 @@
+// Streaming subscription: every change to `notes` for the caller's
+// tenant lands as a delta. The runtime AND-merges tenant scope into
+// the predicate via the `tenant()` mixin on the table — no manual
+// `eq('tenantId', ...)` needed in the handler.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-backend/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-backend",
+  "kind": "api",
+  "summary": "Minimal Voltro backend: app.config + schema + one streaming route + one mutation. Tenant-aware out of the box.",
+  "tags": ["api", "backend", "minimal", "starter"]
+}

package/templates/apps/api-backend/tests/notes.create.test.ts

@@ -0,0 +1,50 @@
+// Unit test with `@voltro/testing` — no database, no running server. Importing
+// `../database/schema` registers the `notes` / `actors` / `tenants` tables
+// globally, so `makeTestContext` auto-wires them into the in-memory store.
+// `ctx.store` is the SAME mixin-wrapped store the handler gets in production,
+// so tenant auto-scoping + audit auto-fill behave exactly as at runtime.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema' // registers notes / actors / tenants
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import createNote from '../mutations/notes.create.mutation.server'
+
+describe('notes.create', () => {
+  it('inserts a note stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    const row = await createNote({ tenantId: 'acme', title: 'Hello', body: 'World' }, ctx)
+
+    expect(row['title']).toBe('Hello')
+    expect(row['tenantId']).toBe('acme')  // assertOwnTenant let it through + stamped
+    expect(row['done']).toBe(false)
+    expect(String(row['id'])).toMatch(/^note_/) // TypeID auto-injected from id()
+  })
+
+  it('rejects a cross-tenant spoof — input.tenantId must match the subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    await expect(
+      createNote({ tenantId: 'other-tenant', title: 'spoof', body: '' }, ctx),
+    ).rejects.toBeInstanceOf(TenantMismatch)
+  })
+
+  it('isolates tenants — t2 never sees t1 rows (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ notes: [] }),
+    })
+    await createNote({ tenantId: 't1', title: 'secret', body: '' }, ctx)
+
+    // Re-scope the SAME store to a different tenant — the real WHERE filter
+    // (eq tenantId) hides t1's row from t2.
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

package/templates/apps/api-backend/tsconfig.json

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