@voltro/cli 0.14.0 → 0.15.0

package/dist/{fileConventions-COg0ZytD.js → fileConventions-Cu0tM-Bl.js}

@@ -1,9 +1,29 @@
 //#region src/fileConventions.ts
-var e = /\.(query|mutation|action|stream)\.ts$/, t = /\.(query|mutation|action|stream)\.server\.ts$/, n = /\.workflow\.tsx$/, r = /\.workflow\.server\.tsx$/, i = /\.workflow\.tsx?$/, a = /\.trigger\.tsx?$/, o = /\.cron\.tsx?$/, s = /\.webhook\.tsx?$/, c = /\.outbox\.tsx?$/, l = /\.subscribe\.tsx?$/, u = /\.reaction\.tsx?$/, d = /\.aggregate\.tsx?$/, f = /\.startup\.tsx?$/, p = /\.seed\.ts$/, m = /\.relations\.ts$/, h = /\.entity\.ts$|\.schema\.ts$|^schema\.ts$/, g = (e) => i.test(e) && !n.test(e) && !r.test(e), _ = /\.page\.tsx$/, v = /\.island\.tsx?$/, y = /\.component\.tsx$/, b = /\.component\.ui\.tsx$/, x = /\.hook\.tsx?$/, S = /\.internal\.tsx?$/, C = /\.types\.tsx?$/, w = /\.fixture\.tsx?$/, T = /\.tracking\.tsx?$/, E = /\.store\.tsx?$/, D = /\.(test|spec)\.tsx?$/, O = /* @__PURE__ */ new Set([
+var e = /\.(query|mutation|action|stream)\.ts$/, t = /\.(query|mutation|action|stream)\.server\.ts$/, n = /\.workflow\.tsx$/, r = /\.workflow\.server\.tsx$/, i = /\.workflow\.tsx?$/, a = /\.trigger\.tsx?$/, o = /\.cron\.tsx?$/, s = /\.webhook\.tsx?$/, c = /\.outbox\.tsx?$/, l = /\.subscribe\.tsx?$/, u = /\.reaction\.tsx?$/, d = /\.aggregate\.tsx?$/, f = /\.startup\.tsx?$/, p = /\.seed\.ts$/, m = /\.relations\.ts$/, h = /\.entity\.ts$|\.schema\.ts$|^schema\.ts$/, g = (e) => i.test(e) && !n.test(e) && !r.test(e), _ = /\.page\.tsx$/, v = /\.island\.tsx?$/, y = /\.component\.tsx$/, b = /\.component\.ui\.tsx$/, x = /\.hook\.tsx?$/, S = /\.internal\.tsx?$/, C = /\.types\.tsx?$/, w = /\.fixture\.tsx?$/, T = /\.tracking\.tsx?$/, E = /\.store\.tsx?$/, D = /\.client\.tsx?$/, O = /\.(test|spec)\.tsx?$/, k = [
+	e,
+	t,
+	i,
+	r,
+	a,
+	o,
+	s,
+	c,
+	l,
+	u,
+	d,
+	f,
+	p,
+	m,
+	h,
+	/\.route\.tsx?$/,
+	E,
+	D,
+	/\.(agent|tool|email|connection|serverless|server|config|generated)\.tsx?$/
+], A = (e) => k.some((t) => t.test(e)), j = /* @__PURE__ */ new Set([
 	"layout.tsx",
 	"error.tsx",
 	"loading.tsx",
 	"not-found.tsx"
 ]);
 //#endregion
-export { a as C, i as D, n as E, r as O, T as S, s as T, p as _, w as a, l as b, v as c, O as d, e as f, h as g, m as h, o as i, g as k, c as l, u as m, y as n, x as o, t as p, b as r, S as s, d as t, _ as u, f as v, C as w, D as x, E as y };
+export { g as A, a as C, i as D, n as E, r as O, T as S, s as T, p as _, w as a, l as b, v as c, j as d, e as f, h as g, m as h, o as i, A as k, c as l, u as m, y as n, x as o, t as p, b as r, S as s, d as t, _ as u, f as v, C as w, O as x, E as y };

package/dist/{frameworkTableAssembly-DCLhpHsF.js → frameworkTableAssembly-BA2bAmYN.js}

@@ -1,5 +1,5 @@
 import { n as e } from "./appModuleLoader-C9r9mxZt.js";
-import { C as t, D as n, T as r, i, l as a } from "./fileConventions-COg0ZytD.js";
+import { C as t, D as n, T as r, i, l as a } from "./fileConventions-Cu0tM-Bl.js";
 import { basename as o, join as s } from "node:path";
 import { pathToFileURL as c } from "node:url";
 import { Effect as l } from "effect";

package/dist/frameworkTableAssembly-D1zJSgOU.js

@@ -0,0 +1,2 @@
+import { t as e } from "./frameworkTableAssembly-BA2bAmYN.js";
+export { e as assembleFrameworkTables };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as e, i as t, n, o as r, r as i, t as a } from "./commands-D-teL_TM.js";
+import { a as e, i as t, n, o as r, r as i, t as a } from "./commands-CPQuQRXh.js";
 //#region src/index.ts
 var o = "framework";
 //#endregion

package/dist/{inspectMetrics-CyVMeofr.js → inspectMetrics-CYDSO3za.js}

@@ -1,4 +1,4 @@
-import { d as e, u as t, x as n } from "./fileConventions-COg0ZytD.js";
+import { d as e, u as t, x as n } from "./fileConventions-Cu0tM-Bl.js";
 import { D as r, E as i, T as a, a as o, p as s, w as c } from "./inspect-Dwx0_tUj.js";
 import { basename as l, dirname as u, isAbsolute as d, join as f, relative as p, resolve as m } from "node:path";
 import { fileURLToPath as h, pathToFileURL as g } from "node:url";

package/dist/{serveCommand-CU3Sw4ZM.js → serveCommand-DBzQcCuv.js}

@@ -1,10 +1,10 @@
-import { ct as e, t } from "./inspectMetrics-CyVMeofr.js";
+import { ct as e, t } from "./inspectMetrics-CYDSO3za.js";
 import { s as n } from "./seedRunner-D6eu-u5U.js";
 import { r, t as i } from "./appModuleLoader-C9r9mxZt.js";
-import { f as a, m as o, n as s, p as c, u as l } from "./frameworkTableAssembly-DCLhpHsF.js";
-import { l as u } from "./fileConventions-COg0ZytD.js";
-import { $ as d, A as ee, B as f, C as te, D as ne, E as re, F as p, H as ie, I as m, J as h, K as ae, L as oe, M as g, N as _, O as se, P as v, Q as y, S as ce, T as le, V as ue, X as de, Y as b, Z as x, _ as fe, a as S, b as C, c as pe, et as me, f as w, g as he, h as ge, j as _e, k as ve, n as ye, p as T, q as be, r as xe, s as Se, v as Ce, w as we, x as Te, y as E, z as Ee } from "./dev-CKyW_LAv.js";
-import { c as D, r as De } from "./apiBuild-370ITNRk.js";
+import { f as a, m as o, n as s, p as c, u as l } from "./frameworkTableAssembly-BA2bAmYN.js";
+import { l as u } from "./fileConventions-Cu0tM-Bl.js";
+import { $ as d, A as ee, B as f, C as te, D as ne, E as re, F as p, H as ie, I as m, J as h, K as ae, L as oe, M as g, N as _, O as se, P as v, Q as y, S as ce, T as le, V as ue, X as de, Y as b, Z as x, _ as fe, a as S, b as C, c as pe, et as me, f as w, g as he, h as ge, j as _e, k as ve, n as ye, p as T, q as be, r as xe, s as Se, v as Ce, w as we, x as Te, y as E, z as Ee } from "./dev-C2lCUhYI.js";
+import { c as D, r as De } from "./apiBuild-CHItlwPO.js";
 import { t as Oe } from "./bootTiming-BdyP9nYw.js";
 import { n as ke } from "./cliArgs-qdZSElM3.js";
 import { join as Ae } from "node:path";

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { $ as e } from "./inspectMetrics-CyVMeofr.js";
+import { $ as e } from "./inspectMetrics-CYDSO3za.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-CU3Sw4ZM.js";
+import { t as r } from "./serveCommand-DBzQcCuv.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-D8ATvTzo.js → start-BtgatJN3.js}

@@ -1,4 +1,4 @@
-import { A as e, C as t, E as n, G as r, I as i, J as a, K as o, N as s, O as c, V as l, W as u, X as d, Z as f, _ as ee, a as p, at as m, b as h, c as g, ct as _, dt as v, f as te, g as y, h as b, i as x, it as ne, j as S, k as C, m as w, nt as T, o as re, p as ie, q as E, r as D, rt as O, s as k, t as A, tt as j, v as M, w as ae, y as N } from "./inspectMetrics-CyVMeofr.js";
+import { A as e, C as t, E as n, G as r, I as i, J as a, K as o, N as s, O as c, V as l, W as u, X as d, Z as f, _ as ee, a as p, at as m, b as h, c as g, ct as _, dt as v, f as te, g as y, h as b, i as x, it as ne, j as S, k as C, m as w, nt as T, o as re, p as ie, q as E, r as D, rt as O, s as k, t as A, tt as j, v as M, w as ae, y as N } from "./inspectMetrics-CYDSO3za.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 { $ as e } from "./inspectMetrics-CyVMeofr.js";
-import { t } from "./start-D8ATvTzo.js";
+import { $ as e } from "./inspectMetrics-CYDSO3za.js";
+import { t } from "./start-BtgatJN3.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.14.0",
+  "version": "0.15.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.14.0",
-    "@voltro/cache": "0.14.0",
-    "@voltro/data-transfer": "0.14.0",
-    "@voltro/database": "0.14.0",
-    "@voltro/env": "0.14.0",
-    "@voltro/kv": "0.14.0",
-    "@voltro/logger": "0.14.0",
-    "@voltro/plugin-auth": "0.14.0",
-    "@voltro/plugin-broadcast": "0.14.0",
-    "@voltro/plugin-mail": "0.14.0",
-    "@voltro/plugin-storage": "0.14.0",
-    "@voltro/plugin-webhooks": "0.14.0",
-    "@voltro/protocol": "0.14.0",
-    "@voltro/runtime": "0.14.0",
-    "@voltro/serverless": "0.14.0",
-    "@voltro/workflow": "0.14.0",
+    "@voltro/ai": "0.15.0",
+    "@voltro/cache": "0.15.0",
+    "@voltro/data-transfer": "0.15.0",
+    "@voltro/database": "0.15.0",
+    "@voltro/env": "0.15.0",
+    "@voltro/kv": "0.15.0",
+    "@voltro/logger": "0.15.0",
+    "@voltro/plugin-auth": "0.15.0",
+    "@voltro/plugin-broadcast": "0.15.0",
+    "@voltro/plugin-mail": "0.15.0",
+    "@voltro/plugin-storage": "0.15.0",
+    "@voltro/plugin-webhooks": "0.15.0",
+    "@voltro/protocol": "0.15.0",
+    "@voltro/runtime": "0.15.0",
+    "@voltro/serverless": "0.15.0",
+    "@voltro/workflow": "0.15.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -526,7 +526,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **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. |
+| **What's new in 0.14.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.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. |
+| **What's new in 0.14.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

@@ -525,6 +525,7 @@ interface AuthStrategy {
 interface AuthStrategyInput {
   readonly headers: Readonly<Record<string, string | undefined>>
   readonly clientId: number                    // per-connection id (for soft re-auth)
+  readonly store?: DataStore                   // the app's store, for a DB-backed strategy
 }
 ```
 
@@ -540,6 +541,34 @@ The `failed`-stops-the-chain rule is a **security** decision, not an ergonomic o
 
 > Strategies must be **fast on the no-match path** — a cookie-name substring check, no IO — because every strategy runs on every request until one matches. Do JWKS fetches / DB lookups only *after* you've confirmed the request is yours, and cache them.
 
+### Reading your database — `input.store`
+
+A strategy that identifies the caller from a row — a session, an API key, a PAT
+— gets the app's `DataStore` on its input:
+
+```ts
+const dbSession: AuthStrategy = {
+  id: 'db-session',
+  resolve: async ({ headers, store }) => {
+    const token = headers.authorization?.slice('Bearer '.length)
+    if (token === undefined) return { kind: 'skip' }
+    if (store === undefined) return { kind: 'skip' }
+    const [row] = await store.query(sessions.byToken(token))
+    return row ? { kind: 'matched', subject: toSubject(row) } : { kind: 'failed', reason: 'unknown token' }
+  },
+}
+```
+
+It is the **boot** store, not a request-scoped one — strategies resolve before a
+request store exists — and the same value `auth.resolveScopes` receives.
+`undefined` only while the store is still being built (`voltro dev` builds it
+after the auth chain) and on an app with no store, so a strategy should `skip`
+rather than throw.
+
+Read users, sessions, keys. A strategy that runs domain writes while deciding
+who the caller is has the two jobs the wrong way round; nothing in the type
+stops you, and it is still wrong.
+
 ## Composing the chain
 
 `composeAuthStrategies` turns an ordered list of strategies into a single resolver. First `matched` wins; first `failed` short-circuits to anonymous.

package/templates/agent-docs/cli.md

@@ -718,6 +718,45 @@ 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).
 
+## When the dev server stops
+
+A restart replaces the child; the supervisor keeps watching. When the dev
+server exits **on its own** — an aborted boot, or you stopping it — what
+happens next depends on whether anyone is there to react.
+
+**In a terminal**, a crashed boot is something you are about to fix, so
+the supervisor keeps watching and tells you:
+
+```text
+dev server crashed — waiting for a file change   exitCode=1
+```
+
+Fix the cause and save. The watcher restarts the server exactly as it
+would for any other edit; you don't retype the command.
+
+**Piped, backgrounded or in CI** — anywhere stdout is not a TTY — nobody
+is going to fix anything, so `voltro dev` exits with the child's code:
+
+```text
+dev server exited — supervisor stopping   exitCode=1
+```
+
+That half matters because the supervisor used to keep watching in *both*
+cases: a shell that had long since closed still had a `voltro dev` behind
+it holding a watcher, and a CI job that had "finished" kept its runner
+busy. A failed boot is now a failed command wherever no one is looking.
+
+A **clean** exit always stops the supervisor, watched or not — a dev
+server ending on purpose is not something to wait out.
+
+| Env | Effect |
+|---|---|
+| `VOLTRO_DEV_KEEP_ALIVE=1` | Wait for a fix even without a TTY — a CI runner with a TTY allocated, or a wrapper that pipes output while you watch it. |
+| `VOLTRO_DEV_KEEP_ALIVE=0` | Exit on a crash even in a terminal. |
+
+Neither can keep a clean exit alive; that would turn a deliberate
+shutdown into a hang.
+
 The `.env` trigger applies to **both api and web** apps — `process.env` is
 parsed once at boot, so editing a `.env` (or re-pulling secrets, e.g.
 `doppler secrets download > .env`) needs a full re-exec. `voltro dev` watches
@@ -2255,6 +2294,7 @@ voltro update                 # bump to the latest published version, install, r
 voltro update --to 0.4.0      # pin an explicit target version
 voltro update --dry-run       # preview the bump + which codemods would run — writes nothing
 voltro update --force         # allow a dirty working tree (not recommended)
+voltro update --only 0.14.0/03_pages-suffix   # run just these codemod(s), comma-separated
 voltro update --exact         # pin exact versions (drop the ^ / ~ range prefix)
 voltro update --help          # every flag — always answered, even on a dirty tree
 
@@ -2263,6 +2303,26 @@ voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0
 voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
 ```
 
+### Taking only part of the jump — `--only`
+
+Ids are what `--dry-run` prints:
+
+```bash
+voltro update --dry-run
+voltro update --codemods-only --from 0.13.0 --only 0.14.0/03_pages-suffix,0.14.0/02_reactive-by-default
+```
+
+Useful when part of a jump is load-bearing (without it the app does not build or
+its routes 404) and part is elective: take the necessary ones, get back to a
+committable tree, then run the rest. An id that matches nothing in the jump is an
+error listing the ids that do — "it did nothing" and "you typed it wrong" would
+otherwise look identical.
+
+There is no `--required` flag, deliberately. "Required" would have to mean *this
+app does not run without it*, and that is a property of your app rather than of
+the codemod: the pages rename is unavoidable for a project with pages and
+irrelevant to an api-only one. You know which ones you need; we would be guessing.
+
 ## In a workspace, the whole workspace moves
 
 Run `voltro update` anywhere inside a workspace — a `pnpm-workspace.yaml`, or a
@@ -2333,6 +2393,26 @@ voltro update --codemods-only --from 0.5.0 --to 0.6.0
 
 Every `@voltro/*` entry in `dependencies` and `devDependencies` — in every workspace member, see above — with the range style preserved (`^0.3.0` stays caret, `~0.3.0` stays tilde) unless you pass `--exact`. Non-registry specs (`workspace:*`, `catalog:`, `link:`, …) are left untouched — they're already resolved by your monorepo or catalog.
 
+## When the install cannot run on this host
+
+Some projects install in a container with their own store, from an offline
+mirror, or in a locked-down CI image. `voltro update` runs your package manager
+on the machine you invoke it from, so on those hosts the install step fails —
+and it fails *after* the version bump is written, which leaves the tree
+half-upgraded.
+
+`--no-install` splits the command where those projects need it split:
+
+```bash
+voltro update --no-install --to 0.14.0   # writes the bump, stops, says what is left
+# ...install however this project installs...
+voltro update --codemods-only --from 0.13.0 --to 0.14.0
+```
+
+Step two is not optional and the command says so: the codemods for a jump ship
+**inside** the target version, so nothing can run them until the install has put
+that version on disk.
+
 ## Which package manager
 
 `voltro update` never assumes npm. It resolves your project's package manager in this order, starting in the app directory and walking **up to the repo root**:

package/templates/agent-docs/data.md

@@ -911,10 +911,10 @@ Throw a matching error from the server file; the client can narrow on `_tag`.
 
 Tagged errors **round-trip structurally** over the wire — the caught value carries `_tag` plus every declared field as real properties (and `instanceof` works, same Schema class both ends). You do **not** need to parse the error message string.
 
-Inside Effect, use `Effect.catchTag('NoteQuotaExceeded', …)`. In a React `try/catch` (outside Effect, where `catchTag` isn't available and the decoded value may be a plain object, not a class instance), match with **`errorTag(err)`** — the dependency-free tag reader `@voltro/client` ships:
+Inside Effect, use `Effect.catchTag('NoteQuotaExceeded', …)`. In a React `try/catch` (outside Effect, where `catchTag` isn't available and the decoded value may be a plain object, not a class instance), match with **`errorTag(err)`** — the dependency-free tag reader `@voltro/protocol` ships (it reads what `toRpc` writes):
 
 ```ts
-import { errorTag } from '@voltro/client'
+import { errorTag } from '@voltro/protocol'
 
 try {
   await createNote(input)

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

@@ -435,6 +435,27 @@ VOLTRO_DESTRUCTIVE_OK=1 voltro db apply --note 'retiring users table after migra
 
 For complex multi-table retirements (move data out, then drop), use a [file-based migration](./file-based.md) — explicit ordering + a transaction wrapped around the data move.
 
+### Name the tables, not the whole run
+
+`VOLTRO_DESTRUCTIVE_OK=1` acknowledges **every** lossy op in the plan. That is
+rarely what you mean — a plan with one intended drop and three other lossy ops
+would have all four approved by a single `1`. Give it a comma-separated list
+instead:
+
+```sh
+# Only these tables — every other lossy op in the plan stays refused.
+VOLTRO_DESTRUCTIVE_OK=users,legacy_notes voltro db apply --note 'retiring the pre-migration tables'
+```
+
+An op the list does not name stays blocked, and a plan with anything still
+blocked is refused as a whole. Half a plan applied is how a schema ends up in a
+state neither the declaration nor the database describes.
+
+There is deliberately **no `.dropped()` marker for a table**, unlike for a
+column. A dropped column leaves a slot worth documenting in the declaration; a
+dropped table leaves nothing, so the marker would be a dead entry you have to
+remember to delete.
+
 ## `.narrowedFrom()` for type changes
 
 A bare column type change is **refuse-to-plan** — the planner blocks it

package/templates/agent-docs/schema-driven-ui.md

@@ -1017,7 +1017,8 @@ be on. Rather than repeat that check in every `useMutation` call site, each api'
 runtime carries an error bus; this hook subscribes to it with React lifecycle.
 
 ```tsx
-import { useOnRpcError, errorTag } from '@voltro/client'
+import { useOnRpcError } from '@voltro/client'
+import { errorTag } from '@voltro/protocol'
 
 useOnRpcError('app', useCallback((e) => {
   if (errorTag(e.error) === 'Unauthenticated') redirectToSignIn()