@voltro/cli 0.40.0 → 0.41.0

package/dist/{webhooksCommand-DubZWNOx.js → webhooksCommand-D7ZpH7w0.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-D8JSKlBM.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-DuqBJC7g.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -622,6 +622,12 @@
         "title": "a rejected credential answers `Unauthenticated`, widening three guard results",
         "kind": "manual"
       },
+      {
+        "version": "0.41.0",
+        "id": "0.41.0/01_middleware-defines-where-it-runs",
+        "title": "`middleware.ts` exports `defineMiddleware(...)` and can say where it runs",
+        "kind": "transform"
+      },
       {
         "version": "0.5.0",
         "id": "0.5.0/01_one-terminal-exactly-one",
@@ -709,22 +715,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.40.0",
-    "@voltro/cache": "0.40.0",
-    "@voltro/data-transfer": "0.40.0",
-    "@voltro/database": "0.40.0",
-    "@voltro/env": "0.40.0",
-    "@voltro/kv": "0.40.0",
-    "@voltro/logger": "0.40.0",
-    "@voltro/plugin-auth": "0.40.0",
-    "@voltro/plugin-broadcast": "0.40.0",
-    "@voltro/plugin-mail": "0.40.0",
-    "@voltro/plugin-storage": "0.40.0",
-    "@voltro/plugin-webhooks": "0.40.0",
-    "@voltro/protocol": "0.40.0",
-    "@voltro/runtime": "0.40.0",
-    "@voltro/serverless": "0.40.0",
-    "@voltro/workflow": "0.40.0",
+    "@voltro/ai": "0.41.0",
+    "@voltro/cache": "0.41.0",
+    "@voltro/data-transfer": "0.41.0",
+    "@voltro/database": "0.41.0",
+    "@voltro/env": "0.41.0",
+    "@voltro/kv": "0.41.0",
+    "@voltro/logger": "0.41.0",
+    "@voltro/plugin-auth": "0.41.0",
+    "@voltro/plugin-broadcast": "0.41.0",
+    "@voltro/plugin-mail": "0.41.0",
+    "@voltro/plugin-storage": "0.41.0",
+    "@voltro/plugin-webhooks": "0.41.0",
+    "@voltro/protocol": "0.41.0",
+    "@voltro/runtime": "0.41.0",
+    "@voltro/serverless": "0.41.0",
+    "@voltro/workflow": "0.41.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -707,7 +707,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.40.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. |
+| **What's new in 0.41.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.40.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. |
+| **What's new in 0.41.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/_manifest.json

@@ -242,7 +242,7 @@
       "group": null,
       "description": "Voltro's file-based router — pages, layouts, render modes, loaders, navigation, islands. The web side of the framework.",
       "path": "agent-docs/routing.md",
-      "files": 8
+      "files": 9
     },
     {
       "id": "scheduling",

package/templates/agent-docs/cli.md

@@ -2525,6 +2525,7 @@ Both stream — a table or a blob is never fully held in memory — and both sur
 voltro data export ./backup-2026-07-01
 voltro data export ./out --tenant org_abc            # one tenant + its FK closure
 voltro data export ./out --tables users,posts         # an explicit set
+voltro data export ./out --exclude cluster_locks       # everything else
 voltro data export ./out --assets                      # include stored blobs
 voltro data export ./out --compression gzip            # zstd (default) | gzip | none
 voltro data export ./out --consistency snapshot        # point-in-time (see below)
@@ -2596,6 +2597,11 @@ Rows are written as newline-delimited JSON — streamable, resumable by line, an
 | *(none)* | Every table (the default). |
 | `--tenant <id>` | Every `tenant()`-scoped table filtered to that tenant, **plus** the FK closure in BOTH directions: (1) the transitive **FK-parent** closure of those rows — closure-pulled shared tables (a global `users` / reference table) are **row-subset to the ids the tenant's rows actually reference**, never exported in full; and (2) the **child** closure — rows that *reference* the tenant's rows (the comments on the tenant's projects) come along too, each scoped to the ids that actually point into the tenant set. The child walk is anchored on the `tenant()` tables, so a row that references **only a shared parent** (a global `users` another tenant also references) is **not** pulled — that would be a cross-tenant leak. A `--tenant` bundle therefore carries the tenant's parents AND children and **no other tenant's rows** — that's what makes it safe as a GDPR / per-tenant takeout. |
 | `--tables a,b` | An explicit set (you own referential integrity; the importer's deferred-FK resolution covers load-order dangles, see below). |
+| `--exclude a,b` | Everything EXCEPT these, expanded against the live table list. Direct target only. Cannot be combined with `--tables` or `--tenant`; a name that does not exist is refused, because an exclusion that excludes nothing leaves the run looking like it worked. |
+
+**Every table needs a single-column primary key.** The export is keyset-paginated, so it orders by one column and resumes from the last value on the next page. That column comes from the real primary key — a declared `id()` where there is one, otherwise the table's actual PK, whatever it is called.
+
+A table with a **composite** primary key, or none at all, is **refused by name** rather than exported. Ordering by one column of a composite key splits equal values across page boundaries, which drops or duplicates rows into a bundle that reports success — and a short backup is discovered at the restore. Leave such a table out with `--exclude`.
 
 Tenant-scope details:
 

package/templates/agent-docs/plugins/governance.md

@@ -232,6 +232,14 @@ const token = decryptField(row.token)   // a non-ciphertext value returns unchan
 
 `decryptField` returns a non-`enc:v1:…` value **unchanged**, so you can switch a raw-SQL path to encryption while pre-existing plaintext rows keep working until they're re-written. Both throw a clear error if no cipher is registered (enable `fieldEncryption`). Encryption stops being all-or-nothing tied to going through `ctx.store`.
 
+**One encoding, both directions.** These helpers and the store middleware write the same thing, so a value written by `encryptField` reads through `ctx.store` and vice versa. That was not always true: the store encoded JSON and the helpers did not, both under the same `enc:v1:` envelope, and a value written by one and read by the other either threw blaming the KEY — while the key was fine — or came back with the JSON quotes still on it and raised nothing.
+
+**Rows written under the OLD encoding still read — nothing has to be rewritten.** Both forms are resolved on read, deterministically: after decrypting, a value that does not parse as JSON is the raw form, one that parses to a string is the JSON form, and one that parses to a non-string is decided by the column's declared type (a text column cannot hold a number, so `12345` is a raw string that parsed by accident). This matters because the old form is already on staging and production disks, and a fix that needs the data rewritten before the app works is an outage with a migration attached.
+
+Normalising is optional hygiene, and `voltro db encrypt-column` does it: it re-encodes rows in the old form as it goes and reports them separately from the ones it encrypts. It skips anything ambiguous and anything it cannot decrypt.
+
+**Backups are unaffected either way.** `voltro data export` reads through the raw store, so an encrypted column travels as ciphertext in whichever encoding it holds, and comes back unchanged.
+
 ## Dashboard panel
 
 Both dashboards ship a **Governance** panel (api apps): retention-policy status + field-encryption state + last-sweep results (with a **Run sweep now** button), a **GDPR runner** (enter a subject id → Export / Erase delete / Erase anonymize), a consent-ledger lookup, and the erasure log. Write-actions gate on the `canRunGovernance` capability. Backed by `/_voltro/inspect/plugins/governance/{status,erasures,consent,export,erase,sweep}`.

package/templates/agent-docs/routing.md

@@ -1160,35 +1160,12 @@ and `preload` on the page fails.
 You cannot fix that in a loader. `ctx.query` and every `preload` entry are bound
 from ONE cookie string **before any loader runs**, so a layout loader that
 renews the session cannot reach them. `middleware.ts` at the web app root runs
-earlier than both:
+earlier than both, says which routes it covers, and writes the rotated cookie
+back so this render and the browser agree.
 
-```ts
-// middleware.ts — server-only. NOT app.config.ts, which is imported into the
-// client bundle whenever an api declares `authHeaders`.
-export default async (req) => {
-  const fresh = await refreshSession(req.cookies['sb-session'])
-  if (!fresh) return
-  return {
-    headers:    { authorization: `Bearer ${fresh.accessToken}` },
-    setCookies: [{ name: 'sb-session', value: fresh.cookie, maxAge: 3600 }],
-  }
-}
-```
-
-**Write the cookie back.** An IdP that rotates refresh tokens (Supabase does, and
-detects reuse) will invalidate the session if you renew server-side and leave the
-browser holding the consumed one. `setCookies` is not an optimisation.
-
-**It cannot redirect or refuse a request**, deliberately: authorization belongs
-on the api, which is the only thing that sees the data, and a web-side hook that
-could refuse would be a second authorization layer beside the real one. For a
-login redirect, throw `RedirectError` from the loader.
-
-Headers you return are merged over the request's, and only auth-shaped ones
-(`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api. Cookies
-default to `HttpOnly`, `Path=/`, `SameSite=lax`. The file is loaded once per
-boot; if it throws, the request fails rather than rendering with the credential
-you asked to replace.
+See [Middleware](/docs/routing/middleware) for the full contract: `match`
+(`under` / `routes` / `except` / `assets`), the one-middleware-per-route rule,
+and what it deliberately cannot do.
 
 ## Errors from loaders
 
@@ -2002,3 +1979,139 @@ matches (workspace link and npm install alike).
 How to verify: `curl -sS http://localhost:<port>/@fs/<abs>/src/globals.css | grep
 animate-` should list every kit animation utility you use. If a class is missing,
 the `@source` is misconfigured.
+
+
+
+---
+
+<!-- source: en/routing/middleware.md -->
+## Middleware
+
+_'`middleware.ts` — the web app''s one server-only hook: renew a credential before the SSR render uses it, and say which routes it runs on.'_
+
+`middleware.ts` at the web app root runs **before** a server render binds its data. It exists for one job — renewing a credential — and it is deliberately narrow about everything else.
+
+```ts
+// middleware.ts — server-only. NOT app.config.ts, which is imported into the
+// client bundle whenever an api declares `authHeaders`.
+import { defineMiddleware } from '@voltro/web/middleware'
+
+export const session = defineMiddleware({
+  match: { under: '/app' },
+  run: async (req) => {
+    const fresh = await refreshSession(req.cookies['sb-session'])
+    if (!fresh) return
+    return {
+      headers:    { authorization: `Bearer ${fresh.accessToken}` },
+      setCookies: [{ name: 'sb-session', value: fresh.cookie, maxAge: 3600 }],
+    }
+  },
+})
+```
+
+## The problem it solves
+
+A cookie older than the IdP's token lifetime — practically every first page view of the day for a 1-hour token — makes the api resolve the caller to anonymous, and every loader and `preload` on the page fails.
+
+**You cannot fix that in a loader.** `ctx.query` and every `preload` entry are bound from ONE cookie string *before any loader runs*, so a layout loader that renews the session cannot reach them. The middleware runs earlier than both.
+
+## What it receives, and what it can return
+
+`run` gets a read-only request and returns `{ headers?, setCookies? }` — or nothing, to change nothing.
+
+| Field | |
+|---|---|
+| `req.pathname` | matched path, no query string |
+| `req.search` | raw query string including `?`, or `''` |
+| `req.headers` | incoming headers, lowercased keys |
+| `req.cookies` | the parsed `Cookie` header |
+| `req.route` | the matched **route pattern** (`/notes/[id]`), or `undefined` for a non-page request |
+
+Returned headers are merged over the request's, and only auth-shaped names (`authorization`, `x-tenant`, `x-voltro-*`) are forwarded to the api — a returned `host` would otherwise produce failures that look like anything but a header copy. Cookies default to `HttpOnly`, `Path=/`, `SameSite=lax`, and several are written as separate header lines, never comma-joined (a cookie's `Expires` contains a comma).
+
+**Write the cookie back.** An IdP that rotates refresh tokens (Supabase does, and detects reuse) will invalidate the session if you renew server-side and leave the browser holding the consumed one. `setCookies` is not an optimisation.
+
+**A cookie your IdP SDK reads in the browser needs `httpOnly: false`.** The default is `HttpOnly` — right for a cookie only the server touches, and wrong for this one. Supabase's `createBrowserClient` reads the session from `document.cookie`, so a forgotten `false` hands the browser a session it cannot see: the SSR render is perfect, every server-side check passes, and the user is signed out at the first client-side call. `voltro dev` warns once per cookie when a session-shaped name is written with no `httpOnly` decision; setting it explicitly either way silences that.
+
+## What you return applies to THIS render
+
+The middleware produces one view of the request that everything downstream reads:
+
+| Reader | sees |
+|---|---|
+| `ctx.query` and every `preload` | your headers, and the renewed cookie |
+| `ctx.headers` in a loader | your headers |
+| `useServerRequest().cookies` / `.headers` | the jar after `setCookies` was applied |
+| locale resolution (`cookie`, `accept-language`) | the same jar |
+
+So a hook that renews **only** via `setCookies` — no `headers` at all, which is the normal shape for a cookie-session IdP — still authenticates this render's rpc calls: the `Cookie` header is rebuilt from the updated jar. A `maxAge` of `0` deletes, so a hook that signs someone out renders them signed out. If you return an explicit `cookie` header yourself, yours wins.
+
+## `match` — where it runs
+
+Without a `match`, a middleware runs on every server-rendered route, including your marketing pages. That is an IdP round trip on the page least able to afford one.
+
+```ts
+import { defineMiddleware } from '@voltro/web/middleware'
+
+export const session = defineMiddleware({
+  match: { under: '/app', except: ['/app/public'] },
+  run: async (req) => { /* … */ },
+})
+
+export const adminTenant = defineMiddleware({
+  match: { under: '/admin' },
+  run: async () => ({ headers: { 'x-tenant': 'ops' } }),
+})
+```
+
+| Field | Means |
+|---|---|
+| `under` | a route subtree — `/app` covers `/app` and everything below it, on segment boundaries (never `/application`). A string or an array. |
+| `routes` | exact route patterns, as the router spells them: `/notes/[id]`. |
+| `except` | subtrees or patterns to subtract from the two above. |
+| `assets` | also run on requests that matched no page. Off by default. |
+
+**Every path here is a ROUTE path, checked against your routes at boot.** A `under: '/ap'` that covers nothing refuses the boot; it does not become a middleware that quietly never fires. An `except` that excludes nothing is reported the same way — it reads as an active rule and is not.
+
+That is the deliberate difference from the URL-pattern shape you may have met elsewhere:
+
+```ts
+matcher: '/((?!api|_next/static|_next/image|favicon.ico).*)'
+```
+
+You have to know your own asset layout to write that, it breaks when a build tool renames a directory, and it breaks silently. Voltro's hook runs **after** route matching — framework URLs, anything with a file extension, and anything matching no page are already gone — so an app has never had to know an asset path.
+
+## One middleware per route
+
+**At most one middleware may match a given route.** Two hooks writing one `authorization` header have no defensible winner, so an overlap refuses the boot and names both plus the route:
+
+```
+✗ middleware.ts: 1 problem(s)
+
+  • `session` and `admin` both match /app/admin. A route may have at most one
+    middleware — two hooks writing one `authorization` header have no defined
+    winner. Narrow one with `except`, or fold them into one middleware that
+    branches on `req.route`.
+```
+
+Declaration order is not a semantic, "most specific wins" would silently drop the broader hook — for a session renewal, that means a subtree stops renewing with nothing red anywhere — and merging needs a per-field rule nobody remembers.
+
+`voltro doctor` reports overlaps and dead matchers before you deploy, and says so out loud when a matcher is built from a variable and it could not read it statically.
+
+## Reaching non-page requests
+
+`assets: true` extends a middleware to requests that matched no page — your files, and paths the router does not serve. It is opt-in and narrow on purpose: there is no render and no rpc call on such a request, so `headers` has nothing to act on and **only `setCookies` takes effect**. The framework's own surface (`/@vite/*`, `/_voltro/*`) is never reachable.
+
+## What it deliberately cannot do
+
+**It cannot redirect or refuse a request.** Authorization belongs on the api, which is the only thing that sees the data; a web-side hook that could refuse would be a second authorization layer beside the real one, and a hook that cannot refuse also cannot be mistaken for a guard. For a login redirect, throw `RedirectError` from the loader.
+
+It also cannot live in `app.config.ts`: that file is imported into the client bundle whenever an api declares `authHeaders`, and a hook that renews a session reaches for an IdP SDK by definition.
+
+## Lifecycle
+
+The file is loaded **once per boot** — it is app code with a stable identity, and re-importing per request would rebuild whatever an IdP client constructs at module level. A failure to import is fatal rather than degrading to "the app has none", and a middleware that throws fails the request: the render must not proceed on the credential the hook was told to replace.
+
+**`voltro dev` therefore RESTARTS when you edit it**, the same way a hard-restart field in `app.config.ts` does, and says so in the log. Once-per-boot is documented, and it is still the rule most easily forgotten — everything else in a dev server hot-reloads, so a sabotaged middleware that changes nothing reads as a hook that was never wired.
+
+It runs on both SSR boot paths, `voltro dev` and `voltro start`, with the cookies written on every response arm.

package/templates/agent-docs/security.md

@@ -51,6 +51,30 @@ job with no diff to review. Full detail — including how plugin routes are
 covered per-request in the dispatch spine rather than by the boot gate — in
 [Authorization](/docs/authentication/authorization).
 
+### A decode failure on a guarded procedure is NOT a guard verdict
+
+The payload is decoded before the handler runs, so a guard on a procedure with a
+malformed payload never gets the chance to refuse. Calling one with an incomplete
+payload therefore answers with a decode error, not a `ScopeError` — and reading
+that as "the guard is not applied" is the wrong conclusion in the dangerous
+direction.
+
+A consumer reached exactly that conclusion while auditing a guard, and flipped
+back the moment they sent a complete payload. So a guarded procedure says it in
+the failure:
+
+```
+workAreas.create input (guarded — the guard did NOT run: the payload failed to
+decode first, so this says nothing about access)
+└─ ["type"] └─ is missing
+```
+
+**Measure a guard with a VALID payload.** The ordering itself is not fixable at
+that seam — the request never reaches the handler or the auth middleware, so
+"evaluate guards first" means replacing the protocol layer rather than annotating
+a schema. An `openAccess:` declaration is not an enforced guard and gets no such
+sentence.
+
 ## Outbound HTTP is SSRF-guarded by default
 
 The `HttpClient` your handlers `yield*` refuses internal targets: