@voltro/cli 0.20.1 → 0.21.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-DMjWBQif.js";
+import { t } from "./start-B1x6Z60h.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.20.1",
+  "version": "0.21.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.1",
-    "@voltro/cache": "0.20.1",
-    "@voltro/data-transfer": "0.20.1",
-    "@voltro/database": "0.20.1",
-    "@voltro/env": "0.20.1",
-    "@voltro/kv": "0.20.1",
-    "@voltro/logger": "0.20.1",
-    "@voltro/plugin-auth": "0.20.1",
-    "@voltro/plugin-broadcast": "0.20.1",
-    "@voltro/plugin-mail": "0.20.1",
-    "@voltro/plugin-storage": "0.20.1",
-    "@voltro/plugin-webhooks": "0.20.1",
-    "@voltro/protocol": "0.20.1",
-    "@voltro/runtime": "0.20.1",
-    "@voltro/serverless": "0.20.1",
-    "@voltro/workflow": "0.20.1",
+    "@effect/platform-node": "^0.108.0",
+    "@effect/sql": "^0.52.0",
+    "@effect/workflow": "^0.19.0",
+    "@voltro/ai": "0.21.0",
+    "@voltro/cache": "0.21.0",
+    "@voltro/data-transfer": "0.21.0",
+    "@voltro/database": "0.21.0",
+    "@voltro/env": "0.21.0",
+    "@voltro/kv": "0.21.0",
+    "@voltro/logger": "0.21.0",
+    "@voltro/plugin-auth": "0.21.0",
+    "@voltro/plugin-broadcast": "0.21.0",
+    "@voltro/plugin-mail": "0.21.0",
+    "@voltro/plugin-storage": "0.21.0",
+    "@voltro/plugin-webhooks": "0.21.0",
+    "@voltro/protocol": "0.21.0",
+    "@voltro/runtime": "0.21.0",
+    "@voltro/serverless": "0.21.0",
+    "@voltro/workflow": "0.21.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.1** | `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.21.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.1** | `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.21.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

@@ -544,6 +544,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:
@@ -1470,6 +1509,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:

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

@@ -89,7 +89,7 @@ voltro db plan --against <url>    # diff vs a remote env's inspect endpoint (see
 voltro db apply                   # execute (dev only — refuses on NODE_ENV=production)
 voltro db apply --note '...'      # apply with a freeform note recorded in history
 voltro db plans [--limit 20]      # history from _voltro_migration_plans, newest first
-voltro db drift                   # live-vs-applied fingerprint check — exit 4 on drift
+voltro db drift                   # live-vs-baseline check — exit 0 match, 3 no baseline, 4 drift
 voltro db squash --before <date>  # consolidate history into one snapshot
 voltro db restore-snapshot <id>   # restore VOLTRO_SOFT_DROP=1 columns from a plan
 
@@ -2009,7 +2009,7 @@ Drift = the live database's schema doesn't match the fingerprint of the last app
 
 Three trigger paths:
 
-1. **Manual** — `voltro db drift` runs the check on demand, exits 4 on drift
+1. **Manual** — `voltro db drift` runs the check on demand: exit 0 match, 3 no baseline, 4 drift
 2. **On boot (dev)** — every `voltro dev` boot runs the planner, which detects drift implicitly (the plan will be non-empty)
 3. **Periodic (cloud)** — the cloud dashboard polls each app's `/_voltro/inspect/migrations` endpoint; drift state is in the response
 
@@ -2018,16 +2018,39 @@ All three paths produce the same `DriftSnapshot` shape:
 ```ts
 {
   isDrifted: boolean,
-  liveFingerprint: string,             // current introspected user-schema fingerprint
-  lastAppliedFingerprint?: string,     // newest _voltro_migration_plans row's fp
+  liveFingerprint: string,             // current introspected schema fingerprint
+  lastAppliedFingerprint?: string,     // the BASELINE the newest row recorded
   lastAppliedAt?: string,              // when it was applied
   lastAppliedId?: string,              // plan id
 }
 ```
 
-`isDrifted: false` ↔ `liveFingerprint === lastAppliedFingerprint`.
+`isDrifted: false` ↔ `liveFingerprint === lastAppliedFingerprint`, **or** no baseline was recorded — nothing compared is not the same as nothing changed, and it is never reported as drift.
 
-User-schema only: the fingerprint excludes `_voltro_*` framework tables. Bookkeeping tables grow rows + change row counts as the app runs; including them in the fingerprint would make every boot look drifted.
+### What it compares, and what it does not
+
+The baseline is `_voltro_migration_plans.liveFingerprint`: the fingerprint of the **live** schema as it was immediately after the last `voltro db apply`. Not `fingerprint`, which is the **declared** snapshot's hash — introspection cannot recover everything a declaration carries (generated expressions, `maxLength`, sensitivity markers), so a live hash and a declared hash never agree and comparing them reports drift on every clean database.
+
+Both sides hash the **whole** live schema, framework tables included. A framework upgrade that adds a `_voltro_*` column therefore shows as drift until the next `db apply` records a new baseline — honest, since the live schema did change, and it self-heals on the apply the upgrade needs anyway.
+
+### No baseline yet
+
+A ledger row written before `liveFingerprint` existed has no baseline, and so does a database whose schema was already current when it upgraded. `voltro db drift` says so and **exits 3**:
+
+```sh
+$ voltro db drift
+db drift: no drift baseline recorded yet — cannot compare
+```
+
+Run `voltro db apply` once — a no-op apply backfills the baseline too. Until then use `voltro db plan`, which compares declared against live directly.
+
+**Exit 3 is deliberately not 0.** "Did not compare" is not "clean", and a CI gate on the exit code has to be able to tell them apart — otherwise it passes vacuously on a stable schema, which is the failure drift detection exists to prevent.
+
+| exit | meaning |
+|---|---|
+| 0 | compared, live matches the baseline |
+| 3 | no baseline — did NOT compare |
+| 4 | compared, live diverged |
 
 ## Common causes
 
@@ -2038,12 +2061,11 @@ Someone ran `ALTER TABLE ...` or `CREATE INDEX ...` via psql / DataGrip / Admine
 ```sh
 $ voltro db drift
 db drift: live schema DIVERGED from last applied state
-  last applied: 8f507ba1e1aadad5  at 2026-06-15 14:32:00  (plan_mig_5k78)
-  live now:     a8f2c9d10b3f4e62
+  baseline:      8f507ba1e1aadad5  at 2026-06-15 14:32:00  (plan_mig_5k78)
+  live now:      a8f2c9d10b3f4e62
 
-Probable causes:
-  - manual DDL ran out-of-band (psql session, another tool)
-  - someone applied a plan but the row never made it into _voltro_migration_plans
+Something changed the live schema after the last apply. This command can see
+THAT it changed, not what or who — the fingerprints are hashes, not a diff.
 
 To reconcile, run `voltro db plan` to see what your code expects vs the live DB.
 ```

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

@@ -73,6 +73,13 @@ Plain `text()` is **unbounded** — `TEXT` on Postgres/SQLite, `LONGTEXT` on MyS
 
 Reach for **`.maxLength(n)`** when the column is a short identifier (a kind, slug, external id, resource discriminator) that participates in a `.unique([...])` or composite `.index([...])`: an unbounded column can only back a HASH long-unique constraint (MariaDB) or a prefix index, whereas a bounded `VARCHAR(n)` takes a plain BTREE key. It's cross-dialect (`VARCHAR(n)` on Postgres/MySQL/MariaDB, `NVARCHAR(n)` on MSSQL, `TEXT` on SQLite) — unlike `raw('varchar(20)')`, which hardcodes one dialect's DDL.
 
+**Changing the bound on an EXISTING column is a real migration.** The differ compares `maxLength` on both sides, so `text()` → `text().maxLength(64)`, or 64 → 128, produces an operation:
+
+- **widening** (a larger bound, or dropping the bound) is `safe` — no value can be lost;
+- **narrowing** is `needs-backfill`: the `ALTER` fails at the database for any existing value longer than the new bound. The plan says so and gives you the query to run first.
+
+Not compared on SQLite, which has no length-enforced type — a declared bound there is real, the live column is always `TEXT`, and comparing them would re-plan the same ALTER on every boot.
+
 For **value** constraints (length ranges, regex, email, numeric min/max, cross-field invariants), use table-level `table().validate(Schema)` (see below) — that's the single validation surface, not a pile of per-column modifiers. There are no `.minLength()` / `.pattern()` column modifiers by design.
 
 ### `integer()`

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

@@ -996,7 +996,7 @@ If you write hand-rolled queries that read JSON columns through `unsafe()`, you'
 > then applies it. Idempotent, and a no-op on every other dialect. Without it,
 > workflow message/runner storage misbehaves on SQL Server.
 
-`@effect/cluster`'s mssql branch uses `sp_getapplock` for shard claims and `MERGE … WHEN NOT MATCHED THEN INSERT … OUTPUT INSERTED` for runner upserts. Four bugs in `@effect/cluster@0.59.0` mssql code paths fail under the framework's workflow stack; the framework carries a `pnpm patch` (shipped in the CLI at `packages/cli/templates/patches/@effect__cluster@0.59.0.patch`, written into your project by `voltro add mssql`):
+`@effect/cluster`'s mssql branch uses `sp_getapplock` for shard claims and `MERGE … WHEN NOT MATCHED THEN INSERT … OUTPUT INSERTED` for runner upserts. Four bugs in `@effect/cluster@0.60.0` mssql code paths fail under the framework's workflow stack; the framework carries a `pnpm patch` (shipped in the CLI at `packages/cli/templates/patches/@effect__cluster@0.60.0.patch`, written into your project by `voltro add mssql`):
 
 ### Patch 1 — SqlRunnerStorage shard-lock MERGE alias
 
@@ -1024,7 +1024,7 @@ MSSQL forbids subqueries inside OUTPUT clauses (Msg 10705). The original `insert
 
 The cluster's `deliver_at` column is BIGINT (storing millisecond epoch). Tedious binds JS `number` parameters as INT — which overflows for any post-2001 timestamp. The patch casts `deliver_at` to `BigInt` once at the top of `envelopeToRow` so all three message-kind switch arms emit `bigint | null`; other dialects accept bigint fine.
 
-All four patches are dialect-keyed (touch only the `mssql:` branch of `sql.onDialectOrElse`) so postgres / mysql / sqlite paths are bit-identical to upstream. The framework carries them and ships them to your project via `voltro add mssql` (see the note at the top of this section) — there is no newer `@effect/cluster` to bump to (0.59.0 is the latest), so the patch is how the fix reaches you.
+All four patches are dialect-keyed (touch only the `mssql:` branch of `sql.onDialectOrElse`) so postgres / mysql / sqlite paths are bit-identical to upstream. The framework carries them and ships them to your project via `voltro add mssql` (see the note at the top of this section) — the patch is how the fix reaches you. Upstream still carries these bugs on the current release — the framework re-verifies that on every bump (`git apply --check` against the new tarball) and re-keys the patch, because a `patchedDependencies` key is version-exact and a stale one fails the install.
 
 ## Read replicas — Always-On Availability Groups
 
@@ -1088,7 +1088,7 @@ For a full before-image or per-op fidelity, use **mariadb** (binlog CDC). For ze
 - `voltro/packages/sql-mssql/src/replicationAdapter.ts` — `end_of_log_lsn` / `last_hardened_lsn` compare for RYW
 - `voltro/packages/database/src/sqlCompiler.ts` — TOP / FETCH NEXT dispatch
 - `voltro/packages/database/src/migrate.ts` — mssql DDL branch (line 72)
-- `packages/cli/templates/patches/@effect__cluster@0.59.0.patch` — the four upstream patches (shipped in the CLI; `voltro add mssql` writes it into your project)
+- `packages/cli/templates/patches/@effect__cluster@0.60.0.patch` — the four upstream patches (shipped in the CLI; `voltro add mssql` writes it into your project)