@voltro/cli 0.17.0 → 0.18.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { Q as e } from "./inspectMetrics-DWh56Qas.js";
+import { Q as e } from "./inspectMetrics-D1DmLeJs.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-DO6qr5Ok.js";
+import { t as r } from "./serveCommand-CxcxHc9Y.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-ksY0wMZG.js → start-Clvz4IJb.js}

@@ -1,4 +1,4 @@
-import { A as e, B as t, C as n, E as r, G as i, I as a, K as o, N as s, O as c, U as l, W as ee, X as u, Y as d, _ as f, a as p, b as m, c as h, et as g, f as _, g as te, h as v, i as ne, it as y, j as b, k as x, m as S, nt as C, o as re, p as ie, q as w, r as ae, rt as T, s as E, st as D, t as O, tt as k, ut as A, v as j, w as oe, y as M } from "./inspectMetrics-DWh56Qas.js";
+import { A as e, B as t, C as n, E as r, G as i, I as a, K as o, N as s, O as c, U as l, W as ee, X as u, Y as d, _ as f, a as p, b as m, c as h, et as g, f as _, g as te, h as v, i as ne, it as y, j as b, k as x, m as S, nt as C, o as re, p as ie, q as w, r as ae, rt as T, s as E, st as D, t as O, tt as k, ut as A, v as j, w as oe, y as M } from "./inspectMetrics-D1DmLeJs.js";
 import { D as se, E as ce, T as le, a as N, p as ue, w as de } from "./inspect-Dwx0_tUj.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as pe, extname as P, join as F, resolve as I } from "node:path";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Q as e } from "./inspectMetrics-DWh56Qas.js";
-import { t } from "./start-ksY0wMZG.js";
+import { Q as e } from "./inspectMetrics-D1DmLeJs.js";
+import { t } from "./start-Clvz4IJb.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

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

package/templates/AGENTS.core.md

@@ -449,6 +449,44 @@ aggregations, FTS, vectors/RAG, migrations, dialect parity → the **`database/*
 docs (see index). Async-vs-Effect handlers, `EffectStore`, typed store errors →
 **`data.md`**.
 
+## What may cross the wire (three ORTHOGONAL markers — do not substitute one for another)
+
+A column is not "protected" or "unprotected". Three separate questions get three
+separate markers, and using one to answer another's question is the mistake:
+
+| Marker | Answers | Enforced by |
+|---|---|---|
+| `.serverOnly()` | may this value leave the server AT ALL? | **the boot audit — it FAILS the boot**, it does not warn |
+| `.sensitive('class')` / `.safe()` | may it appear in a `voltro data export`? | the export's masking profile, **fail-closed** |
+| `.encrypted()` | is it encrypted AT REST? | the store's codec |
+
+```ts
+export const users = table('users', {
+  id:       id(),
+  email:    text().sensitive('pii'),      // exportable only through a profile
+  pinHash:  text().serverOnly(),          // never reaches a client, ever
+  ssn:      text().encrypted().serverOnly(),  // both — they are not the same claim
+})
+```
+
+- **`.serverOnly()` is the one that decides "leak / no leak".** A wire-reachable
+  query that declares such a column in its OUTPUT does not start: the boot audit
+  refuses. That is a feature — the failure happens at boot, not in a bundle.
+- **`.encrypted()` is NOT an exposure marker.** It says the bytes at rest are
+  encrypted; the runtime decrypts them for a handler, so an encrypted column
+  flows to the client exactly like any other unless it is ALSO `.serverOnly()`.
+  Reading `.encrypted()` as "safe to expose" is a category error, and a plausible
+  one — say both when you mean both.
+- **Masking is fail-closed**: an unclassified column blocks the export rather
+  than passing through, so `.sensitive()` / `.safe()` is a decision you make once
+  per column, not a filter you remember to apply.
+- `crud.list` / `getById` / `create` / `update` are **redacted by construction** —
+  they strip `serverOnly` columns for you. Hand-rolling the same CRUD is where
+  that stripping gets forgotten.
+
+Depth (classes, profiles, the export flow) → **`database/sensitivity`**; the
+redacted CRUD surface → **`data/crud`**.
+
 ## Naming / RPC tags
 
 - **camelCase** for vars, files, schemas, and rpc tags. The tag IS the wire

package/templates/AGENTS.md

@@ -449,6 +449,44 @@ aggregations, FTS, vectors/RAG, migrations, dialect parity → the **`database/*
 docs (see index). Async-vs-Effect handlers, `EffectStore`, typed store errors →
 **`data.md`**.
 
+## What may cross the wire (three ORTHOGONAL markers — do not substitute one for another)
+
+A column is not "protected" or "unprotected". Three separate questions get three
+separate markers, and using one to answer another's question is the mistake:
+
+| Marker | Answers | Enforced by |
+|---|---|---|
+| `.serverOnly()` | may this value leave the server AT ALL? | **the boot audit — it FAILS the boot**, it does not warn |
+| `.sensitive('class')` / `.safe()` | may it appear in a `voltro data export`? | the export's masking profile, **fail-closed** |
+| `.encrypted()` | is it encrypted AT REST? | the store's codec |
+
+```ts
+export const users = table('users', {
+  id:       id(),
+  email:    text().sensitive('pii'),      // exportable only through a profile
+  pinHash:  text().serverOnly(),          // never reaches a client, ever
+  ssn:      text().encrypted().serverOnly(),  // both — they are not the same claim
+})
+```
+
+- **`.serverOnly()` is the one that decides "leak / no leak".** A wire-reachable
+  query that declares such a column in its OUTPUT does not start: the boot audit
+  refuses. That is a feature — the failure happens at boot, not in a bundle.
+- **`.encrypted()` is NOT an exposure marker.** It says the bytes at rest are
+  encrypted; the runtime decrypts them for a handler, so an encrypted column
+  flows to the client exactly like any other unless it is ALSO `.serverOnly()`.
+  Reading `.encrypted()` as "safe to expose" is a category error, and a plausible
+  one — say both when you mean both.
+- **Masking is fail-closed**: an unclassified column blocks the export rather
+  than passing through, so `.sensitive()` / `.safe()` is a decision you make once
+  per column, not a filter you remember to apply.
+- `crud.list` / `getById` / `create` / `update` are **redacted by construction** —
+  they strip `serverOnly` columns for you. Hand-rolling the same CRUD is where
+  that stripping gets forgotten.
+
+Depth (classes, profiles, the export flow) → **`database/sensitivity`**; the
+redacted CRUD surface → **`data/crud`**.
+
 ## Naming / RPC tags
 
 - **camelCase** for vars, files, schemas, and rpc tags. The tag IS the wire
@@ -541,7 +579,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.16.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.18.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.16.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.18.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

@@ -569,6 +569,54 @@ 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.
 
+#### What the boot store carries, and what it does not
+
+The line is **everything that does not need a Subject** — not "less than
+`ctx.store`":
+
+| | Boot store (`input.store`, `req.store`) | Request store (`ctx.store`) |
+|---|---|---|
+| `.encrypted()` columns decrypt / encrypt | ✓ | ✓ |
+| Array columns round-trip on non-native dialects | ✓ | ✓ |
+| Tenant scope | — | ✓ |
+| Soft-delete filter | — | ✓ |
+| Audit-column stamping | — | ✓ |
+| Row-level security | — | ✓ |
+
+The right-hand four need a resolved Subject, and a strategy runs *before* one
+exists — so a read of tenant-owned rows here must derive and apply that scope
+itself. The first two do not, and getting them wrong is silent: a `.encrypted()`
+column read raw hands back the string `enc:v1:…`, which compares, concatenates,
+renders and logs perfectly well, and simply never matches the token you compare
+it to.
+
+This is also what changes when you move a read **off** hand-written SQL and onto
+the store. Raw SQL sees ciphertext and you decrypt it yourself — `decryptField`
+from `@voltro/runtime` is the escape hatch for exactly that. Through either
+store you get plaintext, so a hand-rolled `decryptField` on the way out will now
+be handed a plaintext value; `decryptField` passes a non-ciphertext value
+through unchanged, so the double call is harmless, but the manual step is no
+longer doing anything.
+
+#### Reading a plugin's own tables
+
+A plugin's tables are declared through `extendSchema` like any others, so they
+are in the same registry and the same store reads them. A public route that
+needs a row a plugin wrote — a storage reference for an avatar proxy, say —
+reads it directly:
+
+```ts
+const [ref] = await req.store.query(
+  queryFor(storageObjects).where(eq('id', objectId)).descriptor,
+)
+```
+
+Two things to keep in mind. The table is the plugin's contract with itself, not
+with you, so it can change shape in any release — pin the version if you depend
+on it. And this store applies no tenant scope, so a route reading a
+tenant-owned plugin table must filter by tenant itself, from something the
+request proves rather than something it claims.
+
 ## 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

@@ -600,19 +600,23 @@ export default {
 }
 ```
 
-#### Inspect token (token-gated deploys)
+#### Inspect token
 
-The overlay's webhooks / traces / indexes panels poll each api's `/_voltro/inspect/*` endpoints. Under `voltro dev` that surface is open, so no auth is needed. A token-gated deploy (`voltro start` with `VOLTRO_INSPECT_TOKEN` set) requires the same `Authorization: Bearer <token>` the CLI sends — otherwise the panels 401 to their empty state.
+The overlay's webhooks / traces / indexes panels poll each api's `/_voltro/inspect/*` endpoints, and that surface is **fail-closed everywhere**: with no `VOLTRO_INSPECT_TOKEN` configured, nobody is authorised — `voltro dev` included.
 
-The overlay reads that token from `VITE_VOLTRO_INSPECT_TOKEN` (only `VITE_`-prefixed vars reach the browser bundle). A foreign-host mount can also pass it explicitly:
+**Under `voltro dev` you configure nothing.** The dev server mints a token per project and its proxy attaches the `Authorization: Bearer` header server-side, on the `/_voltro/api/<name>` route the panels fetch through. The token stays in the dev server's process; the browser never holds it.
+
+That is deliberate rather than convenient. A token compiled into the client bundle is a live credential published to everyone who loads the page, so there is no env-var channel for it — `voltro dev` and `voltro build` set vite's `envPrefix` to a sentinel precisely so nothing leaks through `import.meta.env`.
+
+For an api the dev proxy does not front — a `voltro start` deploy with `VOLTRO_INSPECT_TOKEN` set, say — pass the token explicitly, and note that whatever you pass ships in the bundle:
 
 ```tsx
 import { VoltroDevtools } from '@voltro/devtools'
 
-<VoltroDevtools inspectToken={import.meta.env.VITE_VOLTRO_INSPECT_TOKEN} />
+<VoltroDevtools inspectToken={myToken} />
 ```
 
-When neither the prop nor the env var is set, no `Authorization` header is sent — local dev is unaffected. (The indexes panel's live SSE stream can't carry a header; a token-gated deploy falls back to token-carrying HTTP polling for that panel.)
+Without the prop the overlay sends no `Authorization` header of its own, which is correct: under `voltro dev` the proxy has already added one. (The indexes panel's live SSE stream can't carry a header at all; against an api reached without the proxy it falls back to token-carrying HTTP polling.)
 
 #### Overriding the overlay's labels
 

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

@@ -105,11 +105,15 @@ ctx.store.select('notes')
 .where('col', '>',  value)
 .where('col', '>=', value)
 .where('col', 'in',  [a, b, c])
-.where('col', 'like',  'abc%')
-.where('col', 'contains', 'needle')        // case-insensitive substring (ILIKE '%…%')
+.where('col', 'contains',   'needle')      // case-INsensitive substring (ILIKE '%…%')
+.where('col', 'startsWith', 'awb_')        // case-SENSITIVE prefix (LIKE 'awb\_%')
 .where('col', 'fts', 'query string')       // full-text fallback (LIKE-based here)
 ```
 
+`contains` folds case because it is a search primitive — a human typing into a box means `hello` to find `Hello`. `startsWith` does not, because a prefix is a namespace: `awb_` and `AWB_` are two different key spaces, and quietly merging them is a bug. `startsWith` is also the only one of the two a database can answer from an index — `LIKE 'literal%'` is a btree range scan, `%…%` is not. `%` and `_` inside either value are escaped, so they match literally.
+
+There is no `'like'`. It used to be here, and it was a lie: it mapped to `contains`, so `.where('path', 'like', '/api/%')` matched only rows literally containing the characters `/api/%` and the wildcard you wrote did nothing. An operator named after SQL's must honour your wildcards or not exist.
+
 These are the only operators the ergonomic `.where(col, op, value)` form accepts. For `IS NULL` / `NOT IN` / `IS NOT NULL`, pass a predicate built with the `@voltro/database` helpers:
 
 ```ts

package/templates/agent-docs/introduction.md

@@ -473,7 +473,7 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 
 | Suffix | Promise | Enforced by |
 |---|---|---|
-| `*.component.tsx` | exactly one component (+ types) | `component/one-per-file`, `component/no-hook-export` |
+| `*.component.tsx` | exactly one component | `component/one-per-file`, `component/no-hook-export` |
 | `*.component.ui.tsx` | one component, **reads only** | `ui/no-write`, `ui/orphaned`, `ui/unlinked` |
 | `*.hook.ts` | exactly one `use*` hook (+ types) | `hook/one-per-file`, `hook/no-component-export` |
 | `*.types.ts` | zero runtime exports | `types/runtime-export` |
@@ -483,6 +483,10 @@ If yes, the promise belongs in the name — you cannot see a contract before you
 | `*.client.ts` | it and its imports are browser-safe | boot-time import walk, `client/not-browser-safe` |
 | `*.store.ts` | exactly one `defineStore`, no server state | `store/one-per-file`, `store/mirrors-server-state` |
 
+A `*.component.tsx` promises exactly ONE component. It does not promise to export nothing else: types, and plain module-local values a `const COLUMNS = […]` beside the table that renders them, are fine and always were. What the rule counts is components — a declaration that renders — so an object, an array, a string or a `new` beside your component is not a second one, and neither is `export default Card` next to `export const Card`.
+
+The BOUNDARY rules (`internal/foreign-import`, `fixture/production-import`, `ui/unlinked`) are assertions about your import graph, so it is worth knowing which edges they follow: relative specifiers, your tsconfig `paths` aliases (read from the nearest `tsconfig.json`, so a per-app `@/*` works when you run `voltro doctor` at the repo root), `export … from` re-exports, and dynamic `import()`. A package import is a leaf — the walk stops at the edge of your app.
+
 ## `*.component.ui.tsx` — reads, never writes
 
 ```tsx
@@ -536,6 +540,16 @@ A component then wires it up with `useTracking(checkoutTracking, props, sink)`
 
 The payoff is not tidiness. "What do we send to third parties" becomes a file listing instead of an archaeology project — which is the only form in which that question can be answered on demand when someone asks about personal data.
 
+## `convention/missing-test` — why a shallow test is still worth writing
+
+Every suffix that declares a runtime contract also expects a test beside it, named mechanically: `Card.component.tsx` → `Card.component.test.tsx`. It is an advisory, not an error.
+
+The usual objection is that a per-component test at any real size is low value, and for *assertions* that is often true. That is not what the rule buys. What it buys is that something **mounts** the component — and a render loop, a crashing effect, a missing provider or a broken context is invisible until something does.
+
+That is not hypothetical. One app adopting the taxonomy wrote 251 of these, deliberately shallow (it mounts, it performs no domain write, it renders no raw catalogue key). The first run found a page whose breadcrumb effect rebuilt a fresh array literal on every render — effect → context state → re-render → new literal, without end. That one test took 423 seconds and exhausted the heap. Ten sibling pages memoised; exactly one did not, and in a browser the screen had looked usable. After the fix the whole web suite went from 645 s to 57 s.
+
+So write them shallow if you like. The mount is the point.
+
 ## What deliberately has NO suffix
 
 A generic "one component per file" rule would be worth enforcing everywhere, so tying it to a rename would make it opt-in — less coverage for more cost. The shape rules above fire only on files that *declared* the contract, because declaring it is what makes the promise mean something.

package/templates/agent-docs/routing.md

@@ -262,6 +262,8 @@ No naming trick is needed to keep something out of the router: the absence of th
 
 The canonical form is **no trailing slash** — always link with `<Link to="/about">`, not `<Link to="/about/">`.
 
+`Link` forwards every prop it does not consume itself to the underlying `<a>`, `ref` included — so it drops straight into a polymorphic slot (`<Button component={Link} to={url}>`) without a wrapper.
+
 The framework does NOT emit a trailing-slash redirect on its own. If you need `/about/` → `/about` normalisation (for SEO), configure a 301 redirect at your reverse proxy.
 
 ## What pages CAN'T do

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

@@ -903,9 +903,12 @@ that affordance read-only rather than binding to a tag that does not resolve. Th
 [`useCan`](/docs/ui/client-utilities/use-can); map them to your app's real RBAC
 scopes.
 
-The inspect surface is open in dev. When a deploy sets an inspect token the
-manifest GET is bearer-gated, so an admin UI pointed at a locked-down api has to
-supply that token — a deployment concern, not something this hook handles.
+The manifest GET is bearer-gated wherever it runs — `/_voltro/inspect/*` is
+fail-closed, so no configured `VOLTRO_INSPECT_TOKEN` means `401`, not "everyone".
+Under `voltro dev` that is handled for you (the dev server mints a token and its
+proxy attaches it server-side). An admin UI pointed at a deployed api has to
+supply the token itself — a deployment concern, not something this hook
+handles.