@voltro/cli 0.5.0 → 0.6.0

package/templates/agent-docs/testing.md

@@ -119,9 +119,9 @@ test('searchDocs returns matching rows', async () => {
 
 The returned `TestContext` carries `{ clock, email, llm, ai?, request, cache, store, withSubject, withTenant }` — read the acting subject at `ctx.request.subject` and the in-memory cache at `ctx.cache`.
 
-## `invoke` — run a handler through its input Schema
+## `invoke` — run a handler through its guards, its input Schema, and its transaction
 
-Calling an executor directly skips the input-Schema **decode** the real dispatcher runs first, so a test can feed the handler a value the wire would reject. `invoke(descriptor, executor, rawInput, ctx)` decodes `rawInput` through `descriptor.input` (throwing a `ParseError` on invalid input — the same validation that would 400 in production) and only then calls the executor with the decoded value.
+Calling an executor directly skips the hops the real dispatcher runs first: the descriptor's **guards**, the input-Schema **decode**, and — for a mutation — the **transaction**. So a test can feed the handler a value the wire would reject, can exercise a handler the caller was never authorized to reach, and can leave half-written state behind that production would have rolled back. `invoke(descriptor, executor, rawInput, ctx)` closes them — it decodes `rawInput` through `descriptor.input`, enforces `descriptor.guards` against `ctx.request.subject`, then calls the executor with the decoded value, wrapping a mutation in a real store transaction. It also runs the hops around those: the plugin interceptor chain, the post-commit (`afterCommit`) drain, and the deadlock replay.
 
 ```ts
 import { invoke, makeTestContext } from '@voltro/testing'
@@ -137,7 +137,161 @@ const note = await invoke(createNote, createNoteHandler, { title: 'hi' }, ctx)
 await expect(invoke(createNote, createNoteHandler, { title: 42 }, ctx)).rejects.toThrow()
 ```
 
-`invoke` reproduces the **input-Schema validation** hop only. RBAC / tenant / auth **guards** are rpc middleware wired at dispatch time — not carried on the descriptor — so to assert a guard, run the real handler under a scoped `ctx.request.subject` (via `makeTestContext({ subject })` / `ctx.withSubject`) and let the handler's own `requireScope(...)` execute.
+### Guards are enforced
+
+An unauthorized caller is refused with the typed `ScopeError` — the same error a client would receive — before the handler runs:
+
+```ts
+// the descriptor declares `guards: [scope('notes:write')]`
+const outsider = makeTestContext({
+  subject: { type: 'user', id: 'u2', tenantId: 't1', scopes: [] },
+})
+
+await expect(invoke(createNote, createNoteHandler, { title: 'hi' }, outsider))
+  .rejects.toMatchObject({ _tag: 'ScopeError' })
+```
+
+What this covers:
+
+- **Scope guards** — checked against `ctx.request.subject`.
+- **Resource-scoped guards** — resolved through whatever `setResourceScopeResolver` the test registered.
+- **Relationship / policy guards** — resolved through whatever tuple source the test registered. With none registered they **DENY**, exactly as in production: an authorization question nobody can answer is a refusal.
+
+The full order `invoke` runs, which is production's:
+
+```text
+decode → plugin interceptors( guards → [transaction → handler] → afterCommit )
+```
+
+The **decode is first** because in production it happens at the wire (`@effect/rpc`), before any runner is reached — so a malformed payload rejects with a parse error even for a caller no guard would have let through. Guards then run before the transaction opens, and **inside** the plugin chain, so an rbac-style plugin that publishes a subject's role scopes from its interceptor has already run when the guard is checked. A `resource` extractor therefore sees the **decoded** input, exactly as on the dispatch spine.
+
+### Mutations run in a real transaction
+
+A mutation invoked through `invoke` runs inside `store.transactional(...)` — the store's own method, the same one the serve pipeline calls. So "the mutation failed, therefore nothing was written" is something you can assert here rather than deferring to an e2e test:
+
+```ts
+// the handler inserts, then throws on the second step
+await expect(invoke(createNote, failingHandler, { title: 'hi' }, ctx)).rejects.toThrow()
+
+// nothing survived — the rollback is the store's, not a copy-aside restore
+expect(await ctx.store.select('notes').all()).toHaveLength(0)
+```
+
+The rollback is real: the in-memory data store's transactional view keeps a private overlay and discards it on a throw (buffered change events drain only on commit). Nothing in the harness copies rows aside and puts them back.
+
+Which procedures get wrapped comes off `descriptor.kind`, which every `defineQuery` / `defineMutation` / `defineAction` / `defineStream` stamps — you never declare it, and so can't declare it wrongly:
+
+- **`kind: 'mutation'`** → wrapped.
+- **Queries and actions** → **not** wrapped. That mirrors production rather than omitting something: an action deliberately runs *outside* a transaction because it performs external I/O that cannot be rolled back.
+- A hand-rolled descriptor object with no `kind` → not wrapped. There is nothing to key off, and wrapping everything would give an action the wrong semantics.
+
+The context the handler receives is re-derived over that transaction: `txCtx.store`, its `withSubject` / `withTenant` re-scopers, and its `load` / `loadMany` batcher all read and write through the **same** transaction, so a handler can't accidentally escape it mid-mutation.
+
+### `runInStoreTransaction`
+
+The same wrap is exported for tests that want it around something other than an `invoke` call:
+
+```ts
+import { runInStoreTransaction, makeTestContext } from '@voltro/testing'
+
+const ctx = makeTestContext({ store: mockStore({ notes: [] }) })
+
+await expect(
+  runInStoreTransaction(ctx, async (txCtx) => {
+    await txCtx.store.insert('notes', { title: 'a' })
+    throw new Error('boom')
+  }),
+).rejects.toThrow()
+
+expect(await ctx.store.select('notes').all()).toHaveLength(0)
+```
+
+Nested calls are **not** supported — the in-memory store rejects a nested transaction, exactly as it does at runtime.
+
+### `afterCommit` and `ctx.outbox`
+
+Post-commit work runs, after the commit and **never** after a rollback — which is the entire contract of `afterCommit`: the side effect happens if and only if the write did. `ctx.outbox.enqueue(...)` schedules its delivery nudge through exactly that hook, and the enqueue itself is atomic with your domain write, so a throw loses both. Read the nudges a call produced with `outboxNudgesOf(ctx)`:
+
+```ts
+await invoke(createNote, async (input, c) => {
+  await c.store.insert('notes', { title: input.title })
+  await c.outbox.enqueue('note.created', { title: input.title })
+  return 'ok'
+}, { title: 'hi' }, ctx)
+
+expect(outboxNudgesOf(ctx)).toHaveLength(1)
+```
+
+### Plugin interceptors
+
+Pass the plugins to the context and their rpc interceptors wrap every `invoke` on it — the same list you declare in `app.config.ts`, composed the same way (first listed is outermost):
+
+```ts
+const ctx = makeTestContext({ subject, plugins: [auditPlugin, rbacPlugin] })
+
+// the plugin's interceptMutation now wraps this call
+await invoke(createNote, createNoteHandler, { title: 'hi' }, ctx)
+```
+
+The harness takes the **plugin objects**, not a bare function, so it makes the same kind-selection production does: `interceptMutation` for a mutation, `interceptQuery` for a query, `interceptAction` for an action. A hook filed under the wrong name silently never fires here — exactly as it silently never fires in production, which is the bug worth catching.
+
+Your interceptor receives what it receives at runtime: `{ tag, kind, input, subject, traceId, spanId? }`, with `input` already decoded. It can short-circuit (return a different `Effect` and the handler never runs), transform the result, or tap the error channel. Typed errors round-trip unwrapped — a plugin in the chain does not turn your handler's `NoteNotFound` into an opaque defect.
+
+Two ordering properties you can assert directly, because they are the ones that bite:
+
+```ts
+// 1. The chain wraps the GUARDS — an interceptor sees the ScopeError.
+//    (This is what lets an rbac plugin publish scopes before the check.)
+// 2. The chain runs OUTSIDE the transaction — an interceptor that throws
+//    AFTER the commit does not roll the mutation back:
+const plugin = definePlugin({
+  name: '@acme/audit',
+  framework: '^1.0.0',
+  interceptMutation: (next) =>
+    next.pipe(Effect.flatMap(() => Effect.fail(new Error('audit sink down')))),
+})
+
+const ctx = makeTestContext({ subject, plugins: [plugin] })
+await expect(invoke(createNote, createNoteHandler, { title: 'hi' }, ctx)).rejects.toThrow()
+
+// the write is still there — post-only side effects must not undo the mutation
+expect(await ctx.store.select('notes').all()).toHaveLength(1)
+```
+
+Only the rpc interceptors are wired. Lifecycle hooks (`onActivate`), `schema`, routes and dashboard mounts are boot concerns with no meaning for a single handler call, and are ignored. `rpcInterceptorFor(ctx, 'mutation')` returns the composed chain if you want to assert on it without invoking.
+
+### The deadlock replay
+
+Production replays a mutation whose transaction lost a deadlock — under concurrency the contract is "the victim retries", not "the write fails". `invoke` does the same, using the runtime's own classifier (mysql/maria errnos, the pg/mssql serialization SQLSTATEs, walked down the `cause` chain), so what counts as deadlock-shaped has one definition:
+
+```ts
+let attempts = 0
+await invoke(createNote, async (input, c) => {
+  attempts++
+  await c.store.insert('notes', { title: input.title })
+  if (attempts === 1) throw Object.assign(new Error('Deadlock found'), { errno: 1213 })
+  return 'ok'
+}, { title: 'hi' }, ctx)
+
+expect(attempts).toBe(2)
+expect(await ctx.store.select('notes').all()).toHaveLength(1) // only the surviving attempt
+```
+
+An ordinary failure is **not** replayed — it throws on the first try, so a plain bug never runs your handler three times.
+
+The property that makes a replay safe is that each attempt starts **clean**: the rolled-back attempt's writes are gone (the transaction), and so is its queued post-commit work. Without that reset a replayed mutation would fire the outbox nudges of writes that never landed:
+
+```ts
+// attempt 1 enqueues then deadlocks; attempt 2 enqueues and commits
+expect(outboxNudgesOf(ctx)).toHaveLength(1) // one, not two
+```
+
+Retries are always on and carry no backoff here. Production's jitter exists to de-correlate concurrent lock victims; a unit harness has neither concurrency nor a lock manager, so a sleep would only cost wall-clock (and stall a suite on fake timers). The retry semantics — attempt budget, transient classification, per-attempt reset — are what's reproduced. There is no opt-out, and it cannot mask a real failure: a handler that fails deterministically fails identically after the last attempt.
+
+### What `invoke` still does NOT cover
+
+- **Transport concerns** — connection info, rate limiting, the tenant header. Those are properties of the HTTP hop, not of the procedure; faking them here would only assert against the fake.
+- **Undo capture and the metrics sample** — optional injections the serve entrypoint makes. Their absence changes nothing a handler can observe.
 
 ## Subject + tenant re-scoping
 

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

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/ai": "0.5.0",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/ai": "0.6.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -18,19 +18,21 @@ import { authRoutesPlugin, memoryUserStore, voltroPasswordStrategy } from '@volt
 
 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' }),
+  // The HMAC key that signs + verifies session cookies.
+  //
+  // `generate` means this project gets its OWN key: `voltro dev` mints one
+  // into a gitignored `.env.local` on first boot. That is why no value ships
+  // with this template — a shipped placeholder would be a signing key
+  // published to everyone who downloads the template, and every session in
+  // every deployment built from it would be forgeable.
+  //
+  // Your DEPLOYMENT still needs its own: `voltro secret generate session`.
+  VOLTRO_SESSION_SECRET: envVar.secret({
+    generate: 'base64url',
+    description: 'HMAC key that signs and verifies session cookies.',
+  }),
 })
 
-// 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()
 
@@ -42,7 +44,12 @@ export default {
   plugins: [
     authRoutesPlugin({
       store: userStore,
-      secret: SECRET,
+      // No `secret:` — the plugin reads VOLTRO_SESSION_SECRET when it handles a
+      // request. Passing one here would mean reading process.env at config
+      // time, which runs BEFORE the env gate and before `voltro dev` mints the
+      // project's key, and that is exactly what tempts an app into a hardcoded
+      // fallback. The strategy below resolves the same value the same way, so
+      // the signing and verifying sides cannot drift.
       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
@@ -54,6 +61,6 @@ export default {
   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 })],
+    strategies: [voltroPasswordStrategy()],
   },
 }

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

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-auth": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
-    "@voltro/sql-postgres": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-auth": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
+    "@voltro/sql-postgres": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-deactivation": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-deactivation": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,18 +12,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-mail": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-mail": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-mariadb/.env.example

@@ -23,10 +23,16 @@ AI_PROVIDER=mock
 # AI_MODEL=claude-opus-4-7
 # ANTHROPIC_API_KEY=
 
-# ── Auth ───────────────────────────────────────────────────────────────
-# HMAC key for signed sessions — REQUIRED in production (refuses to boot
-# without it). Generate: openssl rand -hex 32
-VOLTRO_SESSION_SECRET=dev-only-change-me
+# Session signing secret — NO VALUE SHIPS HERE ON PURPOSE.
+#
+# `voltro dev` mints a unique one for this project into a gitignored
+# .env.local on first boot, so local development needs nothing from you.
+# A shipped placeholder would be a signing key published to everyone who
+# downloads this template, making every session in your deployment forgeable.
+#
+# Your DEPLOYMENT needs its own — `voltro serve` refuses to start without it:
+#     voltro secret generate session
+VOLTRO_SESSION_SECRET=
 
 # ── Cluster (K8s, >1 replica) ──────────────────────────────────────────
 # The workflow runner must advertise a routable host so a workflow can

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

@@ -12,18 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/plugin-storage": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
-    "@voltro/sql-mysql": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/plugin-storage": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
+    "@voltro/sql-mysql": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -10,17 +10,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/plugin-storage": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/plugin-storage": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-data-advanced/app.config.ts

@@ -33,14 +33,27 @@ import { governancePlugin } from '@voltro/plugin-governance'
 // 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' }),
-  // The 32-byte hex key the field-encryption cipher uses. NO `default` here on
-  // purpose: governancePlugin resolves it through the Secrets-Resolver (which
-  // reads `process.env`), NOT this typed-env default — a default would satisfy
-  // the boot gate while the cipher still failed to resolve. The shipped `.env`
-  // supplies a DEV-ONLY value so `voltro dev` boots; for production generate a
-  // real key (`openssl rand -hex 32`) and set VOLTRO_FIELD_ENCRYPTION_KEY in
-  // the environment. Lose the key → lose the ciphertext (GCM fails closed).
-  VOLTRO_FIELD_ENCRYPTION_KEY: envVar.string({ access: 'secret' }),
+  // The 32-byte hex key the field-encryption cipher uses.
+  //
+  // `generate: 'hex'` gives this project its OWN key: `voltro dev` mints one
+  // into a gitignored `.env.local` on first boot, and no value ships with the
+  // template. A shipped key would be published to everyone who downloads the
+  // template — and unlike a session secret, that also means every
+  // `.encrypted()` column in a deployment built from it is readable.
+  //
+  // Note it is minted into the ENVIRONMENT, not declared as a typed-env
+  // `default`: governancePlugin resolves the key through the Secrets-Resolver
+  // (which reads `process.env`), so a default would satisfy the boot gate
+  // while the cipher still failed to resolve.
+  //
+  // Your DEPLOYMENT needs its own (`voltro secret generate field-encryption`).
+  // Lose the key → lose the ciphertext (GCM fails closed, never silent
+  // corruption). Rotating it makes existing `.encrypted()` values unreadable.
+  VOLTRO_FIELD_ENCRYPTION_KEY: envVar.secret({
+    generate: 'hex',
+    minLength: 64,
+    description: 'AES-256 key (64 hex chars) for `.encrypted()` columns.',
+  }),
 })
 
 export default {

package/templates/apps/api-data-advanced/package.json

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-governance": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-governance": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
-    "@voltro/workflow": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
+    "@voltro/workflow": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-feature-flags/package.json

@@ -12,18 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-flags": "0.5.0",
-    "@voltro/plugin-multitenancy": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
-    "@voltro/sql-postgres": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-flags": "0.6.0",
+    "@voltro/plugin-multitenancy": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
+    "@voltro/sql-postgres": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -14,16 +14,29 @@ import { governancePlugin } from '@voltro/plugin-governance'
 
 export const env = defineEnv({
   LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // Declared so the boot gate can see it — governancePlugin reads the key
+  // through the Secrets-Resolver (`process.env`), and an undeclared key would
+  // fail at the first `.encrypted()` write instead of at boot.
+  //
+  // `generate: 'hex'` mints a project-local key into a gitignored `.env.local`
+  // on first `voltro dev`, so nothing ships with the template. Your deployment
+  // needs its own: `voltro secret generate field-encryption`.
+  VOLTRO_FIELD_ENCRYPTION_KEY: envVar.secret({
+    generate: 'hex',
+    minLength: 64,
+    description: 'AES-256 key (64 hex chars) for `.encrypted()` columns.',
+  }),
 })
 
 export default {
   type:  'api' as const,
   name:  '{{capProjectName}}{{capAppName}}',
   store: 'memory' as const,
+  env,
   plugins: [
     governancePlugin({
-      // Reads the secret VOLTRO_FIELD_ENCRYPTION_KEY (see .env). LOSE THE KEY,
-      // LOSE THE DATA — GCM fails closed, it never silently corrupts.
+      // Key from the secret VOLTRO_FIELD_ENCRYPTION_KEY, declared above. LOSE
+      // THE KEY, LOSE THE DATA — GCM fails closed, it never silently corrupts.
       fieldEncryption: true,
       // GDPR export/erase walk these (table + the column holding the subject id).
       subjectScopes: [{ table: 'profiles', subjectField: 'id' }],

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

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.5.0",
-    "@voltro/database": "0.5.0",
-    "@voltro/env": "0.5.0",
-    "@voltro/plugin-audit": "0.5.0",
-    "@voltro/plugin-governance": "0.5.0",
-    "@voltro/protocol": "0.5.0",
-    "@voltro/runtime": "0.5.0",
+    "@voltro/cli": "0.6.0",
+    "@voltro/database": "0.6.0",
+    "@voltro/env": "0.6.0",
+    "@voltro/plugin-audit": "0.6.0",
+    "@voltro/plugin-governance": "0.6.0",
+    "@voltro/protocol": "0.6.0",
+    "@voltro/runtime": "0.6.0",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.5.0",
+    "@voltro/testing": "0.6.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }