@voltro/cli 0.58.0 → 0.60.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
 import { t as e } from "./loadEnv-D9nEOClM.js";
-import { t } from "./start-DNtIlBcn.js";
+import { t } from "./start-CcdPRG8L.js";
 export { e as loadDotEnv, t as runStartCommand };

package/dist/{updateCommand-CtuD5r1t.js → updateCommand-D9avpQFT.js}

@@ -1,4 +1,4 @@
-import { n as e, r as t, t as n } from "./codemodRunner-BKjCwGiN.js";
+import { n as e, r as t, t as n } from "./codemodRunner-ClUqkhvR.js";
 import { basename as r, dirname as i, join as a, relative as o, resolve as s } from "node:path";
 import { existsSync as c, readFileSync as l, readdirSync as u, statSync as d, writeFileSync as f } from "node:fs";
 import { totalmem as p } from "node:os";

package/dist/updateCommand-QMOirvXC.js

@@ -0,0 +1,2 @@
+import { m as e, p as t } from "./updateCommand-D9avpQFT.js";
+export { t as runApplyCodemods, e as runUpdateCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -844,6 +844,18 @@
         "title": "rerank reaches the gateway through a ProviderConfig",
         "kind": "manual"
       },
+      {
+        "version": "0.59.0",
+        "id": "0.59.0/01_sourcemaps_moved_to_the_top_level",
+        "title": "`web.sourcemaps` moved to the top level of app.config.ts",
+        "kind": "transform"
+      },
+      {
+        "version": "0.59.0",
+        "id": "0.59.0/02_costsource_gained_unpriced",
+        "title": "`costSource` gained `unpriced`, and AI usage is counted in a unit",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -880,6 +892,12 @@
         "title": "UiStrings gained a required `connectAccount` section",
         "kind": "manual"
       },
+      {
+        "version": "0.60.0",
+        "id": "0.60.0/01_declared_failures_are_not_incidents",
+        "title": "Sentry no longer reports declared failures by default",
+        "kind": "manual"
+      },
       {
         "version": "0.7.0",
         "id": "0.7.0/01_row-filter-load-failure",
@@ -926,24 +944,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.58.0",
-    "@voltro/cache": "0.58.0",
-    "@voltro/client": "0.58.0",
-    "@voltro/content": "0.58.0",
-    "@voltro/data-transfer": "0.58.0",
-    "@voltro/database": "0.58.0",
-    "@voltro/env": "0.58.0",
-    "@voltro/kv": "0.58.0",
-    "@voltro/logger": "0.58.0",
-    "@voltro/plugin-auth": "0.58.0",
-    "@voltro/plugin-broadcast": "0.58.0",
-    "@voltro/plugin-mail": "0.58.0",
-    "@voltro/plugin-storage": "0.58.0",
-    "@voltro/plugin-webhooks": "0.58.0",
-    "@voltro/protocol": "0.58.0",
-    "@voltro/runtime": "0.58.0",
-    "@voltro/serverless": "0.58.0",
-    "@voltro/workflow": "0.58.0",
+    "@voltro/ai": "0.60.0",
+    "@voltro/cache": "0.60.0",
+    "@voltro/client": "0.60.0",
+    "@voltro/content": "0.60.0",
+    "@voltro/data-transfer": "0.60.0",
+    "@voltro/database": "0.60.0",
+    "@voltro/env": "0.60.0",
+    "@voltro/kv": "0.60.0",
+    "@voltro/logger": "0.60.0",
+    "@voltro/plugin-auth": "0.60.0",
+    "@voltro/plugin-broadcast": "0.60.0",
+    "@voltro/plugin-mail": "0.60.0",
+    "@voltro/plugin-storage": "0.60.0",
+    "@voltro/plugin-webhooks": "0.60.0",
+    "@voltro/protocol": "0.60.0",
+    "@voltro/runtime": "0.60.0",
+    "@voltro/serverless": "0.60.0",
+    "@voltro/workflow": "0.60.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -749,7 +749,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.58.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.60.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.58.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.60.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/ai.md

@@ -185,6 +185,20 @@ const usable = models.filter(canExecute).filter((m) => m.capabilities?.vision)
 
 Each entry adds `capabilities`, `modalities`, `contextWindow`, `maxOutputTokens`, `releasedAt`, `knowledgeCutoff` and `dataPolicy`.
 
+Plus **`raw`** — the entry exactly as it came over the wire.
+
+The normalised fields are the shared answer to the questions every app on the gateway asks. `raw` is for the ones only one app asks: a chips row built from the vendor's own `tags`, a pricing display that shows a structure we have not normalised, `zdr` and `no_training` kept apart instead of folded into `dataPolicy`.
+
+```ts
+const models = await readGatewayCatalog({ modality: 'language' })
+const chips = models[0]?.raw?.tags            // vendor's own vocabulary
+const audioRate = (models[0]?.raw?.pricing as { audio_per_second?: string })?.audio_per_second
+```
+
+Without it, an app with its own display fetches `/v1/models` a second time and keeps a second parser of the same response — and then has to decide again, at every field the gateway adds, whether to wait for a framework release. That is the decision `raw` removes, which is why it is one field rather than three more normalised ones.
+
+It is absent on the injected-provider path (the seam a test uses), for the same reason `capabilities` is: that path never saw a response, and an empty object would turn "no wire data" into the claim "the wire carried nothing".
+
 `capabilities` is **unioned from three fields that each half-say it** — `tags`, `supported_parameters` and `modalities` — because they overlap and regularly disagree: a model tagged `reasoning` does not always carry the parameter, and the other way round. Taking either alone produces a false negative, and a false "cannot" removes a model from a picker with no way for anyone to find out why. That union is framework knowledge; without it every app writes the same forty lines, differently.
 
 `dataPolicy` carries `zeroRetention` and `noTraining` (`'all' | 'some' | 'none'`). They decide whether a model may see customer text, and an unreadable value reads as `'none'` — the question is "may this", and an unparseable answer is not a yes.
@@ -2589,7 +2603,42 @@ yield* generateSpeech({ text, provider: { name: 'elevenlabs', model: 'eleven_tur
 
 This ships **no** adapters, on purpose: bundling an ElevenLabs client would put the framework in the business of tracking somebody else's REST API, and the app already has the adapter. What the app deletes is its dispatch, not its adapters.
 
-A registered provider receives every option the primitive already had — `voice`, `outputFormat`, `speed`, `language`, `instructions`, `providerOptions` — or the seam would be a narrower primitive wearing the same name. Built-in names (`mock`, `openai`, `gateway`, `anthropic`) cannot be shadowed: silently overriding one would make the same config mean different things depending on which module loaded first.
+A registered provider receives every option the primitive already had — `voice`, `outputFormat`, `speed`, `language`, `instructions`, `providerOptions` — or the seam would be a narrower primitive wearing the same name.
+
+#### Taking over a built-in name
+
+`mock`, `openai`, `gateway` and `anthropic` resolve without a registration, and shadowing one by accident would make the same config mean different things depending on which module loaded first. So it takes a flag:
+
+```ts
+registerSpeechProvider('openai', myOpenAiTts, { replaceBuiltin: true })
+```
+
+The flag exists because a provider name is not always an alias you choose. `openai` is the value the gateway puts in its model ids, so it is what a stored catalog's rows carry and what a picker submits — an app told to pick another name cannot, without rewriting persisted rows and live sessions. Refusing outright did not protect that app; it made it keep its own dispatch for every provider, not just the colliding one.
+
+What the refusal was protecting is kept: the intent is now in the call, so an override is a decision someone wrote down rather than an accident of load order. Registered providers are resolved **before** built-ins — otherwise the flag would let you register a name and never reach it.
+
+### Cost — speech is not billed in tokens
+
+`generateSpeech` never records a ledger row itself; it returns `usage` and you pass it to `recordAiUsage`, the same as `generateText`. The difference is the unit. Every speech vendor meters characters of input or seconds of audio, so a `usage` shape that only knew tokens could not hold the call at all — speech spend was not un-priced, it was **absent**.
+
+A registered provider returns a `MeteredUsage`:
+
+```ts
+synthesize: (request) => Effect.succeed({
+  audio,
+  usage: { unit: 'characters', input: request.text.length },
+})
+```
+
+```ts
+yield* recordAiUsage(store, {
+  provider: 'elevenlabs', model: 'eleven_turbo_v3', operation: 'generateSpeech',
+  usage: { unit: 'characters', input: 4200 },
+  price: { inputPer1M: 30, outputPer1M: 0 },   // your rate, in your unit
+})
+```
+
+The ledger row carries `unit` beside the two counts. **A non-token unit is never priced by the token table**: without a `price` or an `actualCostUsd` the row is written `costSource: 'unpriced'` with the real count and a zero cost, because a per-1M-token rate applied to a character count produces a number indistinguishable from a real one. Sum the count columns grouped by `unit`, never across it.
 
 ## As a durable step — `transcribeStep`
 

package/templates/agent-docs/cli.md

@@ -1455,13 +1455,14 @@ web: {
   // `dist/assets/` to the prefix on deploy. Filenames are content-hashed, so a
   // previous deploy's assets stay valid for a visitor mid-navigation.
   assetPrefix: 'https://cdn.example.com/_assets',
-
-  // Emit `.map` files WITHOUT a `//# sourceMappingURL` comment, so nothing in
-  // the shipped JS points at them. For `plugin-sentry`: upload them in your
-  // deploy step and DELETE them before the image is built. `voltro start`
-  // refuses to serve a `.map` regardless, so a forgotten delete is not a leak.
-  sourcemaps: 'hidden',
 },
+
+// Top level, NOT under `web:` — it covers every bundle the build minifies
+// (browser, SSR, start, and an api app's serve bundle). Emits `.map` files with
+// no `//# sourceMappingURL` comment, so nothing shipped points at them.
+// `plugin-sentry` can upload and sweep them for you; `voltro start` refuses to
+// serve a `.map` regardless, so a forgotten delete is not a leak.
+sourcemaps: 'hidden',
 http: {
   // Node hangs up an idle keep-alive connection after 5s; every proxy in front
   // holds one longer, and the request that lands in that window comes back as

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

@@ -161,17 +161,15 @@ The two halves are independent: the api plugin alone gives you server traces + e
 
 **Traces default to on, at `tracesSampleRate: 1.0`.** That is the coherent default rather than a generous one: the browser half already sampled every page load, navigation and rpc call at 1.0, so with the api half off each of those spans was emitted, paid for, and belonged to a trace with no server side — a browser hop hanging off nothing. The rate is named on the boot line (`sentry active traces=true tracesSampleRate=1`) so a first boot shows what it is about to send; lower it with `tracesSampleRate`, or set `traces: false` to keep errors and breadcrumbs only.
 
-## Source maps (browser stack traces)
+## Source maps (every bundle, browser and server)
 
-The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless the maps are uploaded. `voltro build` does it:
+Every bundle `voltro build` emits is minified, so an error arrives in Sentry with a **minified** stack trace unless the maps are uploaded. `voltro build` does it:
 
 ```ts
-// app.config.ts
-web: {
-  sourcemaps: {
-    mode: 'hidden',
-    upload: { org: 'acme', project: 'web' },
-  },
+// app.config.ts — top level, for a web app AND an api app
+sourcemaps: {
+  mode: 'hidden',
+  upload: { org: 'acme', project: 'web' },
 }
 ```
 
@@ -191,11 +189,9 @@ That emits the maps, uploads them through `@sentry/cli`, and then **removes them
 `app.config.ts` is TypeScript, so the ordinary branch is the answer:
 
 ```ts
-web: {
-  sourcemaps: process.env.CI
-    ? { mode: 'hidden', upload: { org: 'acme', project: 'web' } }
-    : 'hidden',
-}
+sourcemaps: process.env.CI
+  ? { mode: 'hidden', upload: { org: 'acme', project: 'web' } }
+  : 'hidden',
 ```
 
 `'hidden'` alone emits the maps and **keeps** them — right for reading a stack trace locally, and a leak in an image. Omit the field entirely and nothing is emitted, which is the default.
@@ -206,9 +202,138 @@ web: {
 
 It is read from `SENTRY_AUTH_TOKEN` and there is deliberately no `authToken` option: `app.config.ts` is a committed file, and a token with `project:releases` scope can write to every project in the org. Give it to the **build** (a CI secret, a Docker build secret) — not to the deployment, since the upload happens while the bundle is being built.
 
-**Install `@sentry/cli` yourself: `pnpm add -D @sentry/cli` in the web app.** The framework depends on it nowhere, and that is a licence decision rather than a packaging one — it is FSL-1.1-MIT, which restricts competing commercial use, so it must not sit in the dependency graph of a package we publish. A build with an upload configured and the package missing **refuses and names the command**, rather than skipping the upload and leaving you to find out months later that no frame resolves.
+**Install `@sentry/cli` yourself: `pnpm add -D @sentry/cli` in the app being built.** The framework depends on it nowhere, and that is a licence decision rather than a packaging one — it is FSL-1.1-MIT, which restricts competing commercial use, so it must not sit in the dependency graph of a package we publish. A build with an upload configured and the package missing **refuses and names the command**, rather than skipping the upload and leaving you to find out months later that no frame resolves.
+
+### It covers the server too — and that is what it was missing
+
+An earlier version of this page said server traces were un-minified already and
+that source maps were a browser-only concern. That was wrong about the built
+artefact, and the correction is the reason the option moved to the top level.
+
+`voltro build` minifies **four** bundles, not one: the browser bundle, the SSR
+bundle, the `voltro start` bundle, and — for an api app — the precompiled entry
+plus the serve bundle that `voltro serve` actually runs. `keepNames` rescues the
+handful of identifiers that are read as strings (Effect tags, error `name`s) and
+nothing else, so a frame out of the serve bundle reads:
+
+```
+at l  (file:///…/serveBundle/serveEntry.js:79:51)
+at Qo (file:///…/serveBundle/serveEntry.js:236:76405)
+```
+
+The server half is also where it hurts most. A schedule, a workflow step, a
+subscriber or a REST route has no browser caller whose frame could stand in for
+it — a workflow that dies at 03:30 in a cron is only what its stack trace says.
+
+So `sourcemaps` is one field at the top level of `app.config.ts` and it covers
+everything the build minifies. **It replaces `web.sourcemaps`**, which reached
+only the browser bundle; the build refuses the old spelling rather than ignoring
+it, and `voltro update` moves it for you.
+
+Two details worth knowing before the first upload:
+
+- **Each output directory is uploaded under the prefix that matches how its
+  files are named.** `dist/assets` is fetched by a browser under `~/assets`; the
+  SSR, start and serve bundles are files a node process loaded and go up under
+  `~/`. Set `upload.urlPrefix` only if you know your project needs one value for
+  both.
+- **`node:*-slim` images have no CA certificates.** `/etc/ssl/certs` is empty and
+  the `ca-certificates` package is not installed. Node carries its own roots, so
+  nothing in JS notices — but `sentry-cli` is a Rust binary that uses the system
+  store, and it fails with `SSL peer certificate … unable to get local issuer
+  certificate`. Add `ca-certificates` to the build stage.
+
+**Debug ids are what make a server frame resolve, and they need their own
+step.** `sentry-cli sourcemaps upload` does **not** write them — `inject` is a
+separate subcommand, and `upload` only uses ids that are already there, falling
+back to matching on the artifact NAME when they are not.
+
+That fallback cannot work for a server bundle: the artifact is named from
+`--url-prefix` (`~/chunk-ABC.js`) while the frame carries the absolute path the
+node process loaded (`/workspace/…/serveBundle/chunk-ABC.js`), and nothing
+rewrites either side. Measured downstream before this was fixed: 4300 artifacts
+uploaded, the release finalised, every frame still minified — nothing red, which
+is the failure this page's own warning describes.
+
+`voltro build` runs `inject` first now, so the ids are in both the shipped JS and
+the map before anything is uploaded. The URL prefix stays as the fallback for the
+browser bundle, whose frames really are URLs under `~/assets`.
+
+## The web server is a SECOND process — and it needs the DSN too
+
+A framework app runs two server processes. `voltro serve` is the api, where
+`sentryPlugin()` initialises the SDK through the plugin lifecycle. `voltro start`
+is the **web server** — SSR, loaders, ISR, the revalidation legs — and it has no
+plugin lifecycle at all.
+
+It now initialises Sentry itself when `SENTRY_DSN` is set:
+
+```sh
+SENTRY_DSN=… SENTRY_ENVIRONMENT=production SENTRY_RELEASE=1.4.2 voltro start
+```
+
+```
+{"level":"info","msg":"sentry active","environment":"production","release":"1.4.2","traces":false,"profiling":false,"process":"web"}
+```
+
+Same line and same field names as the api half, from the same function — one
+vocabulary across both pods, plus `process` so a collector can tell them apart.
+
+**Why this was a hole rather than a missing log line.** An SSR shell throw is
+caught, logged, and answered with a 500. No browser ever renders it, so the
+client-side ErrorBoundary bridge below cannot see it either: the error existed
+only in the pod's stdout. Both ends of the integration worked and the middle was
+dark.
+
+Three things to know:
+
+- **`@voltro/plugin-sentry` must be installed in the WEB app**, not only the api
+  — the web server resolves the shared init from it. With a DSN set and the
+  package missing, the boot says so and names the command; it does not fail.
+- **`traces` is `false` here, deliberately.** The api half contributes a span
+  processor to the framework's tracer. The web server has no tracer, so
+  initialising with tracing on would put `traces: true` in a boot line while
+  nothing produces a span.
+- **No DSN is silent.** On the api side `sentryPlugin()` in your config is a
+  declaration, so an inert one is worth a warning. Here there is no declaration
+  to contradict, and a line about an integration you did not ask for is noise.
+
+**Re-run `voltro build` after upgrading.** Production `voltro start` loads the
+app's precompiled start bundle, so the web half picks this up when that bundle
+is rebuilt — not from the framework version alone.
+
+## What reaches Sentry — a declared failure does not
+
+A procedure's `error:` union is a **contract**. Somebody wrote the outcome down,
+the client gets it typed and branches on it, and it describes a state of the
+world: `AccessDeniedError` on a team you are not a member of is the system
+working. A **defect** is the opposite — nobody foresaw it. Sentry is built for
+the second.
+
+So a cause that carries only declared failures is **not** reported:
+
+```ts
+sentryPlugin()                              // captureFailures: false — the default
+sentryPlugin({ captureFailures: true })     // report them again
+sentryPlugin({ captureFailures: (e) => (e as { _tag?: string })._tag === 'PaymentDeclined' })
+```
 
-Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
+- **Defects are always reported**, including a defect that arrived beside a
+  failure — the rule is failures-*only*, so one cannot hide the other.
+- **Both halves take the option.** A rejected call is an rpc error on the client
+  too, so `initSentryBrowser({ captureFailures })` applies the same rule to
+  `rpc.*` events that carry a `_tag`. Set them together, or the api goes quiet
+  while the browser keeps filing the same rejection.
+- **Route render failures and `reportClientError` are never filtered.** Nobody
+  declared those, which is the whole distinction.
+- **The boot line names it** — `sentry active … captureFailures=false` — because
+  a default the framework picks for you is one nobody finds again.
+
+Why the default is off: an issue list that fills with the expected is one nobody
+reads. Every invalid form value, every click on a resource without access and
+every call on a deleted row was a `level: error` issue. If Sentry is where you
+see errors at all, `captureFailures: true` is the one-line answer and it is a
+reasonable choice.
 
 ## Catching errors — what's automatic, what's manual
 
@@ -218,7 +343,8 @@ Once the two halves are wired, most errors are captured **with no per-call code*
 |---|---|---|
 | rpc handler throw (mutation/query/action) | ✅ auto | server interceptor → Sentry, trace-correlated + breadcrumbs |
 | Unhandled browser error / promise rejection | ✅ auto | `@sentry/react` global handlers (after `initSentryBrowser`) |
-| **React render error** (any page, incl. catch-all `[...slug]`, `error.tsx` boundary) | ✅ auto | the framework's route ErrorBoundary publishes to a client-error bus → the Sentry web bridge captures it. React swallows boundary-caught errors before `window.onerror`, so this bridge is what makes them reach Sentry — tagged with the route + component stack. |
+| **React render error, in the BROWSER** (any page, incl. catch-all `[...slug]`, `error.tsx` boundary) | ✅ auto | the framework's route ErrorBoundary publishes to a client-error bus → the Sentry web bridge captures it. React swallows boundary-caught errors before `window.onerror`, so this bridge is what makes them reach Sentry — tagged with the route + component stack. |
+| **React render error, during SSR** (shell throw, loader throw, PPR/SWR refresh) | ✅ auto, from the WEB server | a different process and a different path: the render never reaches a browser, so the row above cannot cover it. Captured by the web server's own Sentry (see the section above), tagged `voltro.process=web` and `voltro.stage`. Needs `SENTRY_DSN` on the **web** deployment. |
 | **Loader failure** (page/layout `loader` reject) | ✅ auto | same route bus path |
 | Manual try/catch (event handler, async effect, anywhere) | ✋ one call | `reportClientError(error, context?)` |
 | **Every other server primitive** — REST route (`defineRestRoute`), aggregate, subscriber, schedule, workflow, webhook, startup | ✅ auto | each primitive's error path publishes to the framework's server-error bus → the plugin captures it, tagged `voltro.errorSource` + `voltro.name` (+ traceId for workflows) |