@voltro/cli 0.20.2 → 0.22.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { et as e } from "./inspectMetrics-DvPNXmGA.js";
-import { t } from "./start-CXQ7WL1W.js";
+import { X as e } from "./inspectMetrics-4AVPn6IS.js";
+import { t } from "./start-BjGUIIvj.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.20.2",
+  "version": "0.22.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -59,42 +59,42 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@effect/platform-node": "^0.107.0",
-    "@effect/sql": "^0.51.1",
-    "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.20.2",
-    "@voltro/cache": "0.20.2",
-    "@voltro/data-transfer": "0.20.2",
-    "@voltro/database": "0.20.2",
-    "@voltro/env": "0.20.2",
-    "@voltro/kv": "0.20.2",
-    "@voltro/logger": "0.20.2",
-    "@voltro/plugin-auth": "0.20.2",
-    "@voltro/plugin-broadcast": "0.20.2",
-    "@voltro/plugin-mail": "0.20.2",
-    "@voltro/plugin-storage": "0.20.2",
-    "@voltro/plugin-webhooks": "0.20.2",
-    "@voltro/protocol": "0.20.2",
-    "@voltro/runtime": "0.20.2",
-    "@voltro/serverless": "0.20.2",
-    "@voltro/workflow": "0.20.2",
+    "@effect/platform-node": "^0.108.0",
+    "@effect/sql": "^0.52.0",
+    "@effect/workflow": "^0.19.0",
+    "@voltro/ai": "0.22.0",
+    "@voltro/cache": "0.22.0",
+    "@voltro/data-transfer": "0.22.0",
+    "@voltro/database": "0.22.0",
+    "@voltro/env": "0.22.0",
+    "@voltro/kv": "0.22.0",
+    "@voltro/logger": "0.22.0",
+    "@voltro/plugin-auth": "0.22.0",
+    "@voltro/plugin-broadcast": "0.22.0",
+    "@voltro/plugin-mail": "0.22.0",
+    "@voltro/plugin-storage": "0.22.0",
+    "@voltro/plugin-webhooks": "0.22.0",
+    "@voltro/protocol": "0.22.0",
+    "@voltro/runtime": "0.22.0",
+    "@voltro/serverless": "0.22.0",
+    "@voltro/workflow": "0.22.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",
     "ts-morph": "^28.0.0"
   },
   "optionalDependencies": {
-    "@tailwindcss/vite": "^4.3.2",
+    "@tailwindcss/vite": "^4.3.3",
     "@vercel/nft": "^1.10.2",
-    "@vitejs/plugin-react": "^6.0.3",
+    "@vitejs/plugin-react": "^6.0.4",
     "esbuild": "^0.28.0",
-    "tsx": "^4.23.0",
-    "vite": "^8.1.4"
+    "tsx": "^4.23.1",
+    "vite": "^8.1.5"
   },
   "peerDependencies": {
-    "@effect/platform": "^0.96.2",
-    "@effect/rpc": "^0.75.1",
-    "effect": "^3.21.4"
+    "@effect/platform": "^0.97.0",
+    "@effect/rpc": "^0.76.0",
+    "effect": "^3.22.0"
   },
   "publishConfig": {
     "access": "public"

package/templates/AGENTS.md

@@ -595,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.20.2** | `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.22.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.20.2** | `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.22.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/cli.md

@@ -495,10 +495,11 @@ Three checks run at boot and print one line each when they have something to say
 - **`apiKeys: true` with no `apikeys:issue:*` scope declared.** The capability is
   on and reachable by nobody; every issue request fails its guard.
 
-`voltro doctor` adds a fourth, over your source: an executor that writes
-`ctx.request.subject.id` while naming no guard, which is how an anonymous caller
-reaches a NOT NULL column and gets a raw statement failure instead of a typed
-refusal.
+`voltro doctor` adds a fourth, over your source: its **authz scan** asks of every
+executor — queries included — whether it references an access check at all, and
+lists the ones that reference none. It learns your own `require*` / `assert*`
+guard names, so it does not report the call sites of guards you already wrote.
+See [the authz scan](./build-and-start.md).
 
 ## `voltro dev <appDir>`
 
@@ -544,6 +545,45 @@ compile. Already-compiled (warm) pages are never throttled, so a hot app stays
 fully concurrent. Tune the cap with `VOLTRO_DEV_SSR_COMPILE_CONCURRENCY` (below) —
 drop it on a low-memory box, raise it on a big machine.
 
+### A failed server render fails the request
+
+If the server render throws, `voltro dev` answers **500** with the error and its
+stack, marks the response `x-voltro-rendered-by: ssr-dev-failed`, and logs it at
+`error`. It does **not** fall back to a client-rendered shell.
+
+That is deliberate, and it is the same outcome `voltro start` produces in
+production. A fallback would hand you a page that renders in the browser and a
+500 in production from the identical code — and because an empty `<div
+id="root">` is what a client-only app looks like, the usual conclusion is "the
+framework does not server-render", not "my page threw". The failure is loud so
+the cause is the thing you see.
+
+The practical consequence: anything that only misbehaves under
+`renderToPipeableStream` — a component that suspends with no `<Suspense>`
+boundary above it, a loader that throws, a hydration-unsafe value — surfaces in
+`voltro dev` at the moment you hit the route.
+
+**Suspending is fine here, and does not need a boundary you add.** A component
+that suspends during a streamed server render — a lazily-loaded translation
+catalog, a `React.lazy` component, `react-i18next` with `useSuspense: true` —
+renders normally: `renderToPipeableStream` treats the root as an implicit
+boundary, so a suspend delays the shell flush instead of failing. Measured, not
+assumed; a regression test pins it.
+
+Do **not** add a blanket `<Suspense>` at the root to "fix" a suspend. It makes
+things worse in a way that is hard to see: React downgrades an errored boundary
+to client rendering, so a page that THROWS starts answering 200 with
+`<template data-msg="Switched to client rendering">` instead of failing. You lose
+the hard failure above and gain nothing — the suspend already worked. Mount
+boundaries where you want a *fallback* (`loading.tsx` per route, `<Await>` for
+deferred loader values), not to make suspending legal.
+
+Two places where a suspend genuinely is not supported, both by React rather than
+by choice: `renderToString`, which backs the static prerender
+(`renderMode: 'static'`), emits the fallback instead of waiting — so a suspending
+component in a prerendered page needs its own boundary or a resolved value; and
+the client render after hydration, which follows React's own rules.
+
 
 Under `VOLTRO_LOG_LEVEL=debug` each cold compile logs its own duration, so a slow
 first paint can be attributed to a specific module:
@@ -737,6 +777,32 @@ The restart is a full re-exec — there is no in-process hot-reload of a
 handler body; editing a query's executor respawns the child (debounced
 80ms, so a burst of saves collapses into one restart).
 
+### How the old process is stopped
+
+SIGTERM first. The child runs its teardown — plugin `onDeactivate`, the
+CDC detach, the scheduler and workflow runtime, the connection pool, and
+every `ctx.onShutdown(cb)` a `*.startup.ts` registered — and then exits.
+That is normally tens of milliseconds and you never see it.
+
+It gets **1.5 seconds**, then SIGKILL, and the escalation says so:
+
+```text
+child ignored SIGTERM — escalated to SIGKILL   pid=41207
+```
+
+Read that as "something in this app's shutdown does not complete" — a
+pool draining against a database that is already gone, a plugin
+`onDeactivate` waiting on a dead socket. The restart still happens; it
+just costs the full grace window every time, and whatever teardown had
+not finished was cut off. Worth fixing at the source rather than living
+with, because the same hang is a slow — then failed — shutdown in
+production.
+
+Neither timeout is optional: a stop that can wait forever is a dev
+server that stops restarting entirely, with the old process still
+holding the port and your browser's websocket still attached to code you
+edited minutes ago.
+
 ## When the dev server stops
 
 A restart replaces the child; the supervisor keeps watching. When the dev
@@ -976,6 +1042,65 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The authz scan
+
+`voltro doctor` answers one mechanical question over every executor: **does it
+reference an access check at all?**
+
+```
+authz scan · 586 executor(s)
+  ✗ no access check                          21
+  ⚠ inline ownership check, no named guard   24   (informational)
+  ✓ guards: on the descriptor                 0
+  ✓ calls a guard from the vocabulary       320
+  – accepted as recorded debt               221   (voltro-authz-allowlist.txt)
+
+  ✗ teams.deleteSubTeam  — deletes teams with nothing constraining WHICH row
+      api/teams/deleteSubTeam.mutation.server.ts
+```
+
+It scans **queries and streams too**, not only writes: an executor that takes an
+id and returns the row is the same hole as one that writes it. The exploitable
+shape is "acts on a row the client named, without comparing anything on that row
+to the caller", and a read has it.
+
+**It learns your guard names.** An exported `require*` / `assert*` from your own
+source counts as a guard, so `requireTeamAccess()` is recognised without any
+configuration. Without that the scan would report every call site of your own
+guards, which is the failure mode that makes a check ignorable.
+
+**An inline ownership check is informational.** `row.userId !== subject.id → new
+AccessDeniedError({})` is correct code — it is listed so you can see where the
+rule lives in a handler rather than on a descriptor, and it never fails the run.
+
+Findings are ordered by blast radius: a `delete` outranks an `insert`, and a
+target table that is `tenant()`-scoped or referenced by other tables outranks one
+that is neither.
+
+#### The ratchet — how to adopt this on an existing app
+
+A first run on a large app reports hundreds of handlers, and nobody triages
+hundreds of findings. So record them once and fail only on what comes after:
+
+```bash
+voltro doctor --write-authz-allowlist    # writes voltro-authz-allowlist.txt
+voltro doctor                            # exits 1 on anything NEW
+```
+
+The file is **debt, not approval** — every line is a handler nobody has confirmed
+is safe. It is keyed by rpc tag rather than path, so moving a file can neither
+re-open a hole nor hide one, and it is consulted **last**: an executor that gains
+a real guard is reported as guarded whether or not its line is still there. The
+list can only shrink unless someone adds to it deliberately.
+
+#### Before you hand-roll another check
+
+If your checks are imperative because a scope cannot express "may this subject
+act on THIS row", that is what `guards: [{ action, resourceType, resource }]` is
+for — and an app whose relationships live in its own tables (a `teamMembers` row,
+say) registers its own tuple source instead of copying data into a framework
+table. See [Authorization](../authentication/authorization.md).
+
 ### The predicate-column check
 
 `eq` / `isNull` / `inSet` are free functions, so the column name arrives as a bare
@@ -1470,6 +1595,30 @@ has never run is not "failing".
 Pair it with `voltro logs --level error`: a failing handler now logs at **error**
 level, so the two surfaces agree.
 
+## `voltro schedule run <name>` — fire one job, now
+
+```sh
+voltro schedule run nightly-reconcile
+voltro schedule run nightly-reconcile --process billing --format json
+voltro schedule run nightly-reconcile --url https://api.example.com   # a deployed app
+```
+
+For the normal case: a nightly job that corrects business data, and you want to
+run it once and watch. It reports the run id, and `voltro inspect schedules`
+shows the outcome.
+
+A run id of `null` is not a failure and is reported as its own outcome: the run
+was **coordinated away** — another replica holds the lock, or the previous run is
+still going and this schedule's `onOverlap` is `'skip'`. Printing "ok" there
+would claim work that never started.
+
+`--trigger external` records the run as externally triggered instead of manual,
+for schedules that are normally fired by an outside scheduler.
+
+This works against `voltro serve` as well as `voltro dev`. It did not before —
+production mounted no inspect surface at all, which also meant the post-deploy
+gate below could only ever be run against a dev server.
+
 ## Targeting a deployed app
 
 Every command in this family resolves its target from the local runtime registry — the apps running on *this* machine. Pass `--url` to point one at a **deployed** app instead:
@@ -1489,7 +1638,34 @@ voltro check             --url https://api.example.com
 
 ## The inspect HTTP surface
 
-Every `voltro dev` / `voltro start` instance exposes a read-only introspection surface under `/_voltro/inspect/*`. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
+Every `voltro dev` / `voltro start` instance exposes an introspection surface
+under `/_voltro/inspect/*`.
+
+**It is not read-only.** The core endpoints are reads, but installed plugins
+mount their own — and some are POSTs that DO things: `plugin-governance` mounts
+`/erase` (an irreversible GDPR right-to-be-forgotten deletion) and `/export` (a
+full personal-data dump); `plugin-storage` mounts `/share` and `/revoke`.
+
+**So a mutating method needs a second credential.** `VOLTRO_INSPECT_WRITE_TOKEN`,
+sent as the `x-voltro-inspect-write` header ON TOP of the bearer — an additional
+factor, not an alternative: the read token still has to be correct. GET / HEAD /
+OPTIONS are unaffected. Unset, those endpoints are refused.
+
+```sh
+curl -H "authorization: Bearer $VOLTRO_INSPECT_TOKEN" \
+     -H "x-voltro-inspect-write: $VOLTRO_INSPECT_WRITE_TOKEN" \
+     -X POST http://localhost:4000/_voltro/inspect/plugins/governance/erase
+```
+
+`voltro dev` mints it per project like the read token, and the dashboard proxy
+injects it for loopback targets, so the dev loop is unchanged. **Nothing mints it
+for `serve` / `start`** — in production a destructive endpoint should take a
+deliberate act to enable. Use a DIFFERENT value from the read token; reusing it
+gives the split no meaning.
+
+A plugin mounting a non-GET inspect endpoint must also declare the
+`inspect:write` permission, and the boot audit refuses it otherwise. That governs
+what a PLUGIN may mount; the write credential governs who may call it. The [Voltro Dashboard](/docs/observability/dashboard) consumes it to render the route sitemap, RPC list, subscription panel, workflow runs, and metrics. You can also hit the endpoints directly with `curl` (the `voltro inspect` subcommands above are the thin wrapper over exactly these).
 
 ```bash
 PORT=4000   # from the app's app.config.ts

package/templates/agent-docs/data.md

@@ -328,6 +328,32 @@ defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' },
 
 With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
 
+### A guard that reads a second table belongs in `source`
+
+`source` is the reactive trigger set: the query re-runs when a listed table
+changes, and only then. So a guard that loads a row from ANOTHER table to decide
+access has made that table part of what the result depends on:
+
+```ts
+export const teamBoard = defineQuery({
+  name: 'boards.forTeam',
+  input: Schema.Struct({ teamId: Schema.String }),
+  output: BoardRows,
+  // `boards` alone is wrong here — `requireTeamAccess` reads `teamMembers`.
+  source: ['boards', 'teamMembers'],
+})
+```
+
+Leave `teamMembers` out and the subscription does not re-run when membership
+changes. **That is an authorization staleness, not a cosmetic one:** revoke
+someone's membership and their open subscription keeps serving rows they may no
+longer see, until something else happens to invalidate it.
+
+Nothing warns about this at runtime — a query that silently stops reacting looks
+exactly like one with nothing to report. Reported by a team whose own invariant
+caught it after five computed queries under-declared their `source`; the fix was
+array sources.
+
 ## `output` is the serializer — `timestampMs`
 
 A descriptor's `output` is not documentation of the shape. It **is** the
@@ -951,6 +977,38 @@ const message = matchError(err, {
 }, () => 'Something went wrong')
 ```
 
+## `internal: true` — off the wire entirely
+
+Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts` is
+callable over the WebSocket by any authenticated browser session. `publicApi` and
+`exposeAsTool` opt IN to wider surfaces; `internal: true` opts OUT of the default
+one:
+
+```ts
+export const createFromAction = defineMutation({
+  name: 'auditLog.createFromAction',
+  input: Schema.Struct({ actorId: Schema.String, eventType: Schema.String }),
+  output: Schema.Void,
+  internal: true,
+})
+```
+
+It is not emitted into `rpcGroup.generated.ts`, and neither `voltro dev` nor
+`voltro serve` registers a route — the tag is unroutable over `/rpc` and the
+WebSocket. Server code calls it by importing its executor directly.
+
+**A naming convention is not a boundary.** One app had grown 18 procedures named
+`*Internal`, meaning "only other server code calls this"; all 18 were in the
+client group, and one of them accepted `actorId` / `actorEmail` / `actorType`
+from the caller and wrote an audit row. No guard, zero callers, reachable by
+anyone logged in. If the only thing keeping a procedure off the wire is that
+nobody wrote a client call for it, it is on the wire — the same reasoning as
+`.serverOnly()` on a column, one level up.
+
+**It is not a substitute for a guard.** An internal procedure still runs with
+whatever authority its caller has. This removes the wire surface, not the need to
+check who is asking; `voltro doctor`'s authz scan still covers it.
+
 ## When Not To Use A Mutation
 
 - **External I/O.** Use an action or workflow.