@voltro/cli 0.12.0 → 0.13.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { X as e } from "./inspectMetrics-uEfIS1vp.js";
-import { K as t } from "./seedRunner-DZmhoqNt.js";
+import { X as e } from "./inspectMetrics-DOiiII34.js";
+import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-B2-YV9TU.js";
+import { t as r } from "./serveCommand-CqYxzBZR.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-DKcQd52a.js → start-CjG_0xhR.js}

@@ -1,4 +1,4 @@
-import { $ as e, A as t, C as n, E as r, G as i, H as a, I as o, J as s, N as c, O as l, Q as u, R as ee, U as d, V as f, W as p, _ as m, a as h, at as g, b as _, c as v, ct as y, et as b, f as te, g as x, h as S, i as C, j as w, k as ne, m as T, nt as re, o as ie, p as E, q as D, r as O, s as k, t as A, tt as j, v as M, w as ae, y as N } from "./inspectMetrics-uEfIS1vp.js";
+import { $ as e, A as t, C as n, E as r, G as i, H as a, I as o, J as s, N as c, O as l, Q as u, R as ee, U as d, V as f, W as p, _ as m, a as h, at as g, b as _, c as v, ct as y, et as b, f as te, g as x, h as S, i as C, j as w, k as ne, m as T, nt as re, o as ie, p as E, q as D, r as O, s as k, t as A, tt as j, v as M, w as ae, y as N } from "./inspectMetrics-DOiiII34.js";
 import { D as oe, E as se, T as ce, a as P, p as le, w as ue } from "./inspect-Dwx0_tUj.js";
 import { t as de } from "./bootTiming-BdyP9nYw.js";
 import { dirname as fe, extname as F, join as I, resolve as L } from "node:path";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { X as e } from "./inspectMetrics-uEfIS1vp.js";
-import { t } from "./start-DKcQd52a.js";
+import { X as e } from "./inspectMetrics-DOiiII34.js";
+import { t } from "./start-CjG_0xhR.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.12.0",
-    "@voltro/cache": "0.12.0",
-    "@voltro/data-transfer": "0.12.0",
-    "@voltro/database": "0.12.0",
-    "@voltro/env": "0.12.0",
-    "@voltro/kv": "0.12.0",
-    "@voltro/logger": "0.12.0",
-    "@voltro/plugin-auth": "0.12.0",
-    "@voltro/plugin-broadcast": "0.12.0",
-    "@voltro/plugin-mail": "0.12.0",
-    "@voltro/plugin-storage": "0.12.0",
-    "@voltro/plugin-webhooks": "0.12.0",
-    "@voltro/protocol": "0.12.0",
-    "@voltro/runtime": "0.12.0",
-    "@voltro/serverless": "0.12.0",
-    "@voltro/workflow": "0.12.0",
+    "@voltro/ai": "0.13.0",
+    "@voltro/cache": "0.13.0",
+    "@voltro/data-transfer": "0.13.0",
+    "@voltro/database": "0.13.0",
+    "@voltro/env": "0.13.0",
+    "@voltro/kv": "0.13.0",
+    "@voltro/logger": "0.13.0",
+    "@voltro/plugin-auth": "0.13.0",
+    "@voltro/plugin-broadcast": "0.13.0",
+    "@voltro/plugin-mail": "0.13.0",
+    "@voltro/plugin-storage": "0.13.0",
+    "@voltro/plugin-webhooks": "0.13.0",
+    "@voltro/protocol": "0.13.0",
+    "@voltro/runtime": "0.13.0",
+    "@voltro/serverless": "0.13.0",
+    "@voltro/workflow": "0.13.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -452,7 +452,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.11.4** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.13.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.11.4** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.13.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |

package/templates/agent-docs/authentication.md

@@ -563,6 +563,42 @@ const resolve = composeAuthStrategies(
 
 Order matters: put the cheapest / most-common strategy first. When no strategy matches, the resolver returns an [anonymous Subject](/docs/authentication/subject) scoped to the `x-tenant` header (or a custom `fallback` you supply).
 
+## Roles from your database — `auth.resolveScopes`
+
+If your authorization is a database ROLE rather than a scope on the token, the framework cannot see it. `voltro check`'s `rbac/unguarded-mutation` reports every such write as unguarded — correctly, because nothing about the decision is declared — and the declarative alternative is unusable for you: subjects that come from an external IdP carry no scopes, so `requireScope('employee:admin')` would lock out every real user. One app measured 1566 findings it had no way to act on.
+
+`resolveScopes` closes that. It runs after a strategy matches and adds scopes to the resolved Subject from whatever source you like:
+
+```ts
+// app.config.ts
+export default defineApiConfig({
+  auth: {
+    resolveScopes: async (subject) => {
+      const role = await roleCache.get(subject.id)   // cache it — see below
+      return role === 'admin' ? ['employee:admin', 'employee:read'] : ['employee:read']
+    },
+  },
+})
+```
+
+The same authorization is now declarable on the descriptor:
+
+```ts
+export const payrollList = defineQuery({
+  name: 'payroll.list',
+  guards: [requireScope('employee:admin')],   // visible in the manifest, checkable in CI
+  …
+})
+```
+
+**Scopes only — never a Subject.** The hook cannot change `id` or `tenantId`: identity belongs to the auth strategy, and a hook that could rewrite it would be a forgery surface. The returned scopes are UNIONED with whatever the strategy already set, so a resolver can grant authority but never revoke it.
+
+**It does not run for anonymous callers** — there is no identity to look a role up for.
+
+**Cache it yourself.** It is on the request path. A `Map` keyed by subject id with a short TTL is usually enough. The framework deliberately does not cache for you, because only you know how quickly a role change has to take effect.
+
+Wired identically under `voltro dev` and `voltro serve`.
+
 ## Wiring it into the app
 
 The composed resolver becomes the runtime's `AuthMiddleware` — the per-request middleware that populates `SubjectService` so every handler can `yield* SubjectService` (or read `ctx.subject`). On a single-strategy password app you never touch this; the plugin wires `voltroPasswordStrategy` for you. You only assemble the chain explicitly when you add a second strategy:

package/templates/agent-docs/cli.md

@@ -163,7 +163,7 @@ nothing type-checks — the mutation succeeds, the write lands, and the wrong li
 fails to update.
 
 `voltro dev` records what each procedure ACTUALLY touched, into
-`app.graph.observed.json` (gitignored automatically). When that file is present,
+`app.graph.observed.generated.json` (gitignored automatically). When that file is present,
 `check` diffs it against the declarations:
 
 ```
@@ -447,6 +447,25 @@ _voltro dev, codegen, agents-md — what runs during local development and the e
 
 `voltro dev` is the day-to-day command. It runs different machinery for api vs web apps but the contract is the same: edit a file, the right thing happens.
 
+### Running `voltro dev` in a container
+
+If your dev pod runs as root with the host workspace bind-mounted, everything
+the framework generates would otherwise land `root:root` inside your own tree —
+and on the host `voltro build` then fails on its own output:
+
+```
+EACCES: permission denied, open '…/apps/display/.framework/index.html'
+```
+
+`voltro dev` and `voltro build` hand their generated output (`.framework`,
+`.env.local`, every `*.generated.*`) to whoever owns the app root, and warn
+loudly when they cannot. Only generated state — the framework never takes
+ownership of a file you wrote.
+
+The cleaner fix is on your side and worth doing anyway: start the container as
+the workspace owner, `docker run --user $(id -u):$(id -g)`. Then nothing needs
+handing over at all.
+
 ## `voltro dev <appDir>`
 
 ```bash
@@ -885,9 +904,31 @@ exactly the apps that already adopted it, and misses the ones that never did.
 Those are usually the same apps that secured least elsewhere, which is why the
 absence is worth naming out loud rather than assuming the default did its job.
 
-Server files only (`*.server.ts`, `*.cron.ts`, `*.subscribe.ts`, …): `fetch` is
-unremarkable in a browser component, and flagging it there would make the rule
-noise that gets scrolled past — taking the real findings with it.
+The rule follows the IMPORT GRAPH, not the filename. Server-convention files
+(`*.server.ts`, `*.cron.ts`, `*.subscribe.ts`, …) are the starting points, and
+any file reachable from them and from **nothing else** counts as server code
+too. That matters: keyed on filenames alone the rule caught 9 of 39 outbound
+calls on the app that reported it — the other 30 sat in `lib/*.ts` helpers
+(payments, an AI provider, TTS) imported only from server executors. A
+`lib/payments-mollie.ts` is not client code, and no file extension can say so.
+
+A helper a page ALSO imports stays unflagged, and that is the property keeping
+this rule useful: `fetch` is unremarkable in a browser component, and flagging it
+there would make the rule noise that gets scrolled past — taking the real
+findings with it. Relative imports and your tsconfig `paths` aliases are both
+followed.
+
+The detector also flags an **executor that never names its own descriptor**.
+Pairing is by FILENAME, which is right — and it means a `*.server.ts` can be a
+complete, correct executor with no reference at all to the contract it
+implements. Those are exactly the files where a hand-written input drifts from
+the wire: in one reported codebase, six executors declared `boardPurpose: string`
+where their own descriptor said `Schema.Literal(...)`, discarding the contract at
+the executor boundary. Fix by importing the descriptor and typing the input as
+`ExecutorInput<typeof descriptor>`. Only a SIBLING import clears the finding —
+an executor importing nothing but `@voltro/*` and `node:*` has still not named
+its contract.
+
 
 ### The `workflows.start` audit
 
@@ -1014,6 +1055,39 @@ matching rule lives inside the CLI, so you cannot re-derive the list with your
 own grep. `--json` prints the complete scan, nothing elided, with no preflight
 output mixed in:
 
+### Duplicate package instances
+
+`voltro doctor` also reports any identity-sensitive package resolved at more than
+one version — `effect`, `@effect/*`, `@voltro/*`, react/react-dom:
+
+```
+•  1 package(s) resolved at more than one version:
+     effect — 3.18.4, 3.21.0
+       node_modules/effect
+       ../../node_modules/effect
+```
+
+This is worth its own check because of how it PRESENTS. Effect's types are
+nominal, so a `Schema` built by one copy is not the type the other expects, and
+the errors land in the GENERATED `rpcGroup.generated.ts` — a file you cannot edit
+and did not write:
+
+```
+Property '[TypeId]' is missing in type … Schema<any, any, unknown>
+Type 'typeof Never' is not assignable to type 'All'
+Argument of type 'Rpc<…, Stream<…>, …>' is not assignable to 'Any'
+```
+
+Read cold, that says "the framework emits bad types". It says nothing about the
+dependency tree, which is where the problem is. And the RUNTIME usually stays
+green — two instances only diverge where identity matters — so the app boots,
+serves and passes its tests while `tsc` is red.
+
+Fix it in the install, not the code: align the version across the workspace (a
+root `pnpm.overrides` / `resolutions` entry for `effect` is the blunt
+instrument), then reinstall. Do NOT add `@ts-nocheck` to the generated file — it
+is exactly where a genuine mistake in your own descriptors surfaces.
+
 ```bash
 voltro doctor . --json          # the complete scan: every file path, machine-readable
 ```

package/templates/agent-docs/configuration.md

@@ -326,6 +326,54 @@ const issued = await svc.issue({ tenantId, name: 'mobile app', scopes: ['read']
 // show issued.token ONCE; later: svc.rotate(id), svc.revoke(id), svc.list(tenantId)
 ```
 
+## The second ownership axis — `metadata`
+
+`tenantId` and `onBehalfOf` are the two relationships the framework models. If
+your keys also belong to something else — a team, a project, an environment —
+and that binding is what authorizes them, store it in `metadata`:
+
+```ts
+const key = await keys.issue({
+  tenantId: ctx.request.subject.tenantId,
+  name: 'CI deploy',
+  createdBy: ctx.request.subject.id,   // who minted it
+  onBehalfOf: null,                    // an ORG key: acts as no person
+  metadata: { teamId: 'team_7' },      // your axis
+})
+```
+
+It comes straight back on resolve, so a guard needs no second query:
+
+```ts
+const resolved = await keys.verify(token)
+resolved?.metadata   // { teamId: 'team_7' }
+```
+
+It survives `rotate` — a rotated key is the same credential with a new secret,
+so dropping it would silently de-authorize every rotated key. And it reaches the
+Subject as `metadata`, alongside the framework's own claims.
+
+**It is app data, never identity.** The strategy merges your bag UNDER its own
+claims: `provider`, and the acting `userId`, are written afterwards from
+`onBehalfOf` and always win — including when the answer is "none". A bag that
+could set `userId` would let whoever minted a key choose who the request is.
+
+Before this slot existed, an app with a team axis could authenticate through the
+built-in strategy and still not authorize, so `apiKeys: true` was unusable for
+it. The alternatives people reached for were a second table joined on every auth
+check, or `team:<id>` smuggled into `scopes` — where `hasScope` then sees a scope
+that is not a scope.
+
+## Two strategies, one prefix
+
+If your app already runs its own key strategy on a prefix and you then enable
+`apiKeys: true`, both claim the same shape. The chain is first-match-wins, so the
+first one decides the Subject — and if they resolve to different authority,
+*which strategy answered* decides whether authorization works.
+
+`voltro dev` / `voltro serve` warn at boot when this happens. Give them distinct
+prefixes (`apiKeys: { prefix: 'vk_' }`) or drop one.
+
 ## Security model
 
 - **Hash-only storage.** A DB dump never exposes a usable key — only `sha256(token)`. Lose a token → rotate it (`rotate` revokes the old + issues a fresh one with the same scopes).

package/templates/agent-docs/database/migrations.md

@@ -2600,6 +2600,38 @@ export const users = table('users', {
 
 The planner folds the diff into one `ALTER TABLE users RENAME COLUMN firstName TO givenName`, classified `safe`. After the rename is applied in every env, the marker can be removed (covered in [rename-and-drop.md](./rename-and-drop.md)).
 
+## "the migration did not converge" (apply refuses to record a fingerprint)
+
+```
+applyPlan: the migration did not converge. 31 operation(s) were executed without
+error, but re-planning against the live schema still finds 31:
+  - alter-column-default todos.attachments
+  …
+No fingerprint was recorded — recording one would make the next boot report
+"schema up to date" for a schema that was never applied.
+```
+
+Every statement ran and the database accepted every one of them, and none of them
+changed anything. That is possible because DDL that changes nothing succeeds
+exactly as quietly as DDL that works — `ALTER COLUMN x TYPE text` on a column
+that is already `text` is a valid, successful no-op.
+
+This message exists because the alternative is worse. Before the convergence
+check, such a plan reported `applied 31 op(s)`, recorded a fingerprint, and every
+later boot short-circuited on "schema up to date" — for a schema that had never
+been applied. One app ran that way for two releases. The apply now proves it
+worked before it records anything: the same planner, run against the database as
+it now is, must have nothing left to do.
+
+**It is a framework bug, not a mistake in your schema.** The named operations
+emit DDL that does not take effect. Report the operation kinds plus the column
+types involved. In the meantime the schema is unchanged and safe — nothing was
+half-applied, and no fingerprint was written, so `voltro db plan` still shows you
+the truth.
+
+If you need to move forward before a fix lands, apply the equivalent DDL by hand
+and re-run `voltro db plan` to confirm it converges.
+
 ## "Schema fingerprint mismatch" (prod refuse)
 
 Full error:

package/templates/agent-docs/database/transactions.md

@@ -235,6 +235,37 @@ The `where` predicate is a regular [Predicate](/docs/database/query-builder#pred
 AST — same shape `.where()` uses. Sub-queries via `inSubquery` /
 `exists` are supported.
 
+### Typed: `updateManyRow`
+
+`updateMany` takes a string table name and an untyped patch, so a misspelled
+column or a wrongly-typed value is only found by the database — or not at all,
+if the column happens to exist. `updateManyRow` takes the TABLE OBJECT instead
+and checks the patch against the row type:
+
+```ts
+import { updateManyRow, eq } from '@voltro/database'
+
+await updateManyRow(ctx.store, posts, { hidden: true }, {
+  where: eq('userId', bannedId),
+})
+
+await updateManyRow(ctx.store, posts, { hiddne: true }, { where: … })
+//                                      ^^^^^^^ compile error: not a column
+```
+
+It is worth using rather than the string form, and the evidence is concrete: one
+app migrating 29 `store.upsert` call sites to the typed `upsertRow` got 15 `tsc`
+errors across 8 distinct defects that no test had caught — including seven
+per-user mutations with no authentication check at all, which wrote
+`ctx.request.subject.id` (typed `string | null`) into a NOT NULL column, so an
+anonymous caller reached the database and got a raw statement failure instead of
+a typed refusal.
+
+The subtlest one is the most persuasive: a value spread from a plain object
+literal widens to `string`, and a column's `.oneOf()` union rejects it even
+though the value IS one of the members. Neither a reviewer nor a test would
+plausibly find that; only the row type asks the question. (`as const` fixes it.)
+
 ### Reactivity
 
 `updateMany` emits ONE ChangeEvent per affected row, so reactive

package/templates/agent-docs/testing.md

@@ -66,6 +66,30 @@ voltro e2e     # boot api + web siblings, run tests, tear down
 
 _makeTestContext — the in-memory request ctx for handler and tool tests. The real mixin-wrapped store, mockStore seeding, subject/tenant re-scoping, and the deterministic clock / email / LLM mocks._
 
+## tsconfig `paths` aliases
+
+`voltro test` derives Vite's `resolve.alias` from your app's tsconfig
+`compilerOptions.paths`, so an app that maps `@/* → ./src/*` can test modules
+that import through it without any extra config:
+
+```jsonc
+// tsconfig.json
+{ "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["./src/*"] } } }
+```
+
+```ts
+import { greeting } from '@/locales/en'   // resolves under `voltro test`
+```
+
+Before this, the first person to write a test for each aliased file discovered
+`Cannot find package '@/locales/en' imported from src/lib/i18n.ts` — one file at
+a time — and worked around it with a local `vitest.config.ts` restating what
+tsconfig already said. The dev and build pipelines resolve these already (your
+app runs), so the test runner disagreeing with them was a gap, not a policy.
+
+A project-local `vitest.config.ts` still merges on top, so an app that already
+wrote the workaround keeps working.
+
 ## `makeTestContext`
 
 `makeTestContext(options?)` returns an **`AppContext`** — the exact `ctx` a mutation / query / action / tool executor receives at runtime — with the deterministic test doubles added on top. Because it *is* an `AppContext`, you pass it straight into a handler: `await myHandler(input, makeTestContext({ … }))`. The acting subject is at `ctx.request.subject`; `ctx.store` is the **real** mixin-wrapped store backed by an in-memory data store (so tenant auto-scoping, soft-delete filtering, audit auto-fill, and the fluent `select` / `update` / `delete` builders behave exactly as in production); `ctx.cache` is a real in-memory cache whose TTLs honour `ctx.clock`.