@voltro/cli 0.57.0 → 0.58.0

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

@@ -111,21 +111,104 @@ What it does:
 > ```
 > It's a no-op on the server (SSR) and without a DSN.
 
-The two halves are independent: the api plugin alone gives you server traces + errors; add the web half for the browser hop. For the FULL frontend→backend waterfall in Sentry, run **both** (`sentryPlugin({ traces:true })` on the api + `sentry: { dsn }` on the web app), with matching `release`.
+### Values the bundle cannot know
+
+Everything in that `sentry:` block is a literal frozen into the bundle. That is
+right for a DSN and a release, and wrong for `environment` as soon as one image
+serves more than one environment — one build job and several environment-bound
+deploy jobs is an ordinary pipeline, and a baked `environment` is then true for
+at most one of them. Leaving it out does not help: Sentry defaults a missing
+environment to `production`, so a wrong tag is what you get either way, and a
+wrong tag is worse than none because somebody acts on it.
+
+There is no runtime channel to read instead — public values are baked at build
+time by construction — so the value has to be computed where it is known. The
+entry is generated anyway, so it can call something:
+
+```ts
+// app.config.ts
+sentry: { dsn: '…', optionsFrom: 'src/sentryOptions.ts' }
+```
+
+```ts
+// src/sentryOptions.ts
+export default () => ({
+  environment: location.hostname.startsWith('stage-') ? 'staging' : 'production',
+})
+```
+
+The module's default export is called by the generated entry before
+`initSentryBrowser`, may be async, and its result is spread LAST — so it
+overrides the literals above it, which is the whole reason to reach for it.
+
+### Or from the public env
+
+Without an explicit option, the browser half reads
+`VOLTRO_PUBLIC_SENTRY_DSN`, `VOLTRO_PUBLIC_SENTRY_ENVIRONMENT` and
+`VOLTRO_PUBLIC_SENTRY_RELEASE` — the same shape the api half already has, where
+`sentryPlugin()` takes no arguments and resolves `SENTRY_*` from the environment.
+Declare them in your `defineEnv` contract and an app is finished without touching
+`app.config.ts`.
+
+**A public value must exist when the bundle is BUILT.** `voltro build` freezes the
+declared public subset into the bundle — that is what makes it readable in a
+browser — so these belong in the build (a Docker build-arg, a CI build step), not
+in deployment env. Setting one as a deployment variable deploys cleanly and does
+nothing; `voltro start` warns when it finds one, naming whether the bundle
+carries that key at all.
+
+The two halves are independent: the api plugin alone gives you server traces + errors; add the web half for the browser hop. For the full frontend→backend waterfall, run **both** — and both are on by default, so an app with the plugin on the api and `@voltro/plugin-sentry` as a dependency of the web app gets the whole trace from one `SENTRY_DSN` plus one `VOLTRO_PUBLIC_SENTRY_DSN`. Give both halves the same `release`.
+
+**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)
 
-The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless you upload source maps. The plugin does **not** upload them for you — it captures + correlates errors, but wiring the build to publish maps is a per-app build step (it needs your build output plus a Sentry auth token, neither of which the runtime plugin owns). Wire it once with Sentry's official tooling, keyed to the **same `release`** the plugin uses so the maps match the uploaded events:
+The web bundle is minified, so browser errors arrive in Sentry with **minified** stack traces unless the maps are uploaded. `voltro build` does it:
+
+```ts
+// app.config.ts
+web: {
+  sourcemaps: {
+    mode: 'hidden',
+    upload: { org: 'acme', project: 'web' },
+  },
+}
+```
 
 ```sh
-# after the web build, from the web app dir — uploads maps for one release
-pnpm add -D @sentry/cli
-SENTRY_AUTH_TOKEN=… npx sentry-cli sourcemaps upload \
-  --org <org> --project <project> \
-  --release "$SENTRY_RELEASE" ./dist
+# the build needs both; the deployment needs neither
+SENTRY_AUTH_TOKEN=sntrys_… SENTRY_RELEASE=1.4.2 voltro build
 ```
 
-Or add `@sentry/vite-plugin` to the web app's Vite config so the upload runs automatically on every production build. Either way, set `release` to the same value (e.g. the git SHA) on BOTH the api `sentryPlugin({ release })` and the web `sentry` field — the upload's `--release` must match or Sentry won't resolve the frames. Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
+That emits the maps, uploads them through `@sentry/cli`, and then **removes them from the output**. Three things in that sentence are the reason it lives in the build rather than in your deploy script:
+
+- **The moment.** There is no seam in a Dockerfile between "the bundle exists" and "the image is built". There is one here.
+- **The release.** Sentry matches an artifact to an event by release, and the event's comes from `SENTRY_RELEASE` via `sentryPlugin`. Upload under a different value and no frame resolves — silently, because an upload that matched nothing looks exactly like one that worked. A build with an upload configured and no release **refuses** rather than uploading under nothing.
+- **The deletion.** A `.map` left in `dist` is your source, downloadable by anyone. "We delete it in the deploy step" is a promise a failing build breaks, so the removal is a `finally`: the maps go even when the upload fails, and a configured upload that did not happen fails the build.
+
+### Turning it on selectively
+
+`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',
+}
+```
+
+`'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.
+
+`keep` defaults to "keep them only if nothing consumed them": `false` when `upload` is set, `true` when it is not. Set `keep: true` beside an upload when you want both.
+
+### The auth token is not a config field
+
+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.
+
+Server stack traces are un-minified already (the api ships readable JS), so this is a browser-only concern.
 
 ## Catching errors — what's automatic, what's manual
 

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

@@ -843,6 +843,23 @@ chat.regenerate()                            // re-run the last user prompt
 | `regenerate()` | Re-sends the last user prompt as a fresh turn; `undefined` if there is none. |
 | `sending` | `true` while a `send` is in flight. |
 
+**You do not need `@ai-sdk/react`.** `useAgentChat` covers the three things it is
+usually kept for:
+
+- **Tool calls** — each message carries `parts`, and a `tool` part has
+  `toolName`, `state`, `input` and `output`. Render from `parts` rather than
+  `content` and a tool call looks the same live and after a reload.
+- **Persistence** — the thread is a DB-backed reactive query, not client state.
+  Nothing is lost when the tab closes.
+- **Resumption** — for the same reason. Reopen the tab mid-turn and the
+  in-flight assistant message re-renders from the row that is still being
+  written; there is no transport to reconnect and no replay to arrange.
+
+So an app can drop `@ai-sdk/react` and `DefaultChatTransport` entirely. What
+`useAgentChat` deliberately does not do is manage a transport of its own — it
+composes the agent's synthesized `messages` subscription and `send` action, which
+is what makes the reload behaviour free rather than implemented.
+
 `threadId` is required — mint one per chat (a `useRef`'d uuid) and keep it stable
 across renders, since it is the subscription key for the whole thread. Render
 from `message.parts` (text / reasoning / tool / source / file) rather than
@@ -1577,6 +1594,18 @@ changes, so define it with `useCallback` or at module scope unless you want that
 And the bus is per api runtime — an app talking to several apis subscribes once
 per api name.
 
+**You do not need this hook to REPORT rpc failures.** Every event this bus emits
+is also published on the client error bus, so a reporter — the Sentry browser
+integration, or anything wired with `subscribeClientErrors` — already sees it,
+under `source: 'rpc.mutation' | 'rpc.action' | 'rpc.subscription'` with the rpc
+tag and `traceId` in `context`. This hook is for cross-cutting *policy* (redirect
+on `Unauthenticated`, toast on a network failure), not for telemetry; bridging
+the two by hand now reports twice.
+
+Everything is published, including a reconnect storm. If that is too loud for
+your reporter, gate it in the subscriber — which failures are worth an event is
+your policy, and the bus cannot hold one for every subscriber.
+
 This is the read side of failures that already happened on the wire. To push a
 client-side error the server never saw, call `reportClientError(error, context)`
 instead. Note also that a subscription failure *after* data arrived reaches only