@voltro/cli 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -39,6 +39,55 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.4.0] — 2026-07-18
+
+### ⚠ BREAKING
+
+- **@voltro/protocol, @voltro/plugin-rbac, @voltro/runtime** — **Resource-aware declarative guards + one denial tag.** `guards: [{ scope, resource }]` now actually scopes to a resource. Register a resolver — either `setResourceScopeResolver((req) => Effect<boolean>)` from `@voltro/protocol`, or `rbacPlugin({ resolveResourceRoles: (subject, resourceId) => roleSlugs })` — and the framework asks it, per request, whether the caller holds the scope **on the extracted resource** (a team, workspace, document), before the executor runs (mutations: before the transaction opens). A globally-held scope or `admin:full` still short-circuits without a resolver call; a resolver error fails **closed**. With no resolver registered, `resource` stays advisory (global check) exactly as before, so single-tenant apps are unaffected. **BREAKING — `@voltro/plugin-rbac` no longer exports `Forbidden`.** rbac's `permission()` / `assertPermission()` / `anyPermission()` now fail with protocol's `ScopeError` — the SAME typed error the declarative `guards:` enforcement already raised. One denial tag across the framework: a client that matches `_tag === 'ScopeError'` (or `errorTag(err)`) recognizes both a descriptor-guard denial and a `permission()` denial with one branch. The `@voltro/plugin-rbac/errors` subpath is removed. Migration (the `voltro update` codemod rewrites the mechanical part): - `import { Forbidden } from '@voltro/plugin-rbac/errors'` →   `import { ScopeError } from '@voltro/protocol'`; `import { Forbidden } from '@voltro/plugin-rbac'` →   `import { ScopeError } from '@voltro/plugin-rbac'` (re-exported from the root). - Every `Forbidden` identifier → `ScopeError` (incl. `error: Forbidden` on a descriptor). - By hand: a constructed `new Forbidden({ required, reason })` becomes   `new ScopeError({ required, message })` (the field is `message` and is   REQUIRED); and any `Effect.catchTag('Forbidden', …)` / `err._tag === 'Forbidden'`   string becomes `'ScopeError'`. Guards are normally caught, not constructed, so   most apps only need the import rewrite the codemod does. Also note: `requireScope` / declarative `guards:` enforcement is now async-capable (it awaits the resource resolver when one is registered) — no change to handler code, which never called the internal enforcement directly.
+- **@voltro/client, @voltro/plugin-rbac** — **`@voltro/plugin-rbac/web` is removed — the UI permission gate lives in `@voltro/client`.** The framework shipped `useCan` TWICE, with the same name and the same semantics, over two different React contexts. An app that mounted `<PermissionProvider>` and imported the plugin's `useCan` got an empty scope set and silently hid every gated affordance — no error, just a UI where nothing is permitted. One of the two had to go. `@voltro/client` survives because scopes are a FRAMEWORK concept: `@voltro/protocol` owns `ScopeError`, `guards: [{ scope }]` and `ctx.access`, and rbac is only one way to PRODUCE scopes — an app can register its own `setResourceScopeResolver` over its own tables and never install the plugin. The hook consumes scopes, which is generic; producing them is rbac-specific. Keeping the hook behind the plugin would force an rbac dependency on apps that deliberately don't use rbac, purely to gate a button. `@voltro/plugin-rbac` keeps everything that IS rbac: the roles map, role→scope compilation, the `permission()` / `assertPermission()` / `anyPermission()` server guards, the role tables, and `resolveResourceRoles`. The codemod rewrites every mechanical site: `RbacScopeProvider` → `PermissionProvider`, `canFromScopes` → `canCall`, `canAnyFromScopes` → `canCallAny`, and repoints `useCan` / `useCanAny` / `ADMIN_SCOPE` to `@voltro/client`. A raw `useContext(RbacScopeContext)` is ANNOTATED rather than rewritten — the client equivalent is `usePermissions()`, which returns `{ scopes }` instead of the bare array, so a silent rewrite would compile and then hand back the wrong shape.
+
+### Added
+
+- **@voltro/runtime, @voltro/cli** — **`read({ where })` on aggregates.** Aggregate reads were all-or-nothing, so every consumer that wanted one slice pulled the whole materialised set over the wire and filtered in the component — the cost scaling with the aggregate, not the slice. `where` entries are ANDed; a scalar means strict equality, an array means IN; filtering runs before `orderBy`/`limit`. Deliberately a data filter over already materialised rows, not a predicate language — aggregates stay aggregates.
+- **@voltro/client** — **Two ergonomics that remove the two most-repeated shapes in a Voltro frontend.** - **`mutate(input, options)` — `onSuccess` / `onError` / `notify`.** Every write   site used to re-type `try { await mutate() } catch { toast.error(…) } finally   { setSubmitting(false) }`. `pending` already replaced the `finally`; these   replace the rest. Load-bearing semantic: supplying an error handler (`onError`   or `notify.error`) marks the failure HANDLED — `mutate` resolves with   `undefined` instead of rejecting, which is what actually deletes the try/catch.   With no handler it rejects exactly as before, so unhandled failures stay loud.   `notify` routes to an app-registered sink (`setMutationNotifier`) — the   framework stays unbound to any toast library. - **`useSubscription` now returns `loading` and `isEmpty`, and accepts   `fallback`.** Call sites branched on `data === undefined`, conflating "no   snapshot yet" with "zero rows" — the cause of a flash of empty-state before the   first snapshot. They are now distinct, derived once. `fallback` fills `data`   while loading without lying about `loading`. Also documented: `error` carries a   COLD-START stream failure (check it to avoid an infinite skeleton); a failure   after data arrived deliberately does not blank good data — those reach the   error bus (`useOnRpcError`).
+- **@voltro/cli** — **Make the client hook surface discoverable — and keep it that way.** A downstream app built its whole frontend on three transport hooks (`useSubscription` / `useMutation` / `useAction`) and hand-rolled forms, tables, upload, permission gates, debounce and pagination, because the agent guide documented ~none of the ~40 client hooks that already ship. Three changes: - **The always-loaded core now carries a "Pick the CLIENT primitive" rubric** —   the same decision-rubric treatment the backend primitives get, plus a   "you're about to write X → reach for Y" table (per-field `useState` →   `useFormBinding`, hand-rolled table → `useDataTable`, `FileReader` → `useUpload`,   `useMemo` fan-in → `useDerived`, …). - **The hook reference is complete.** `reference/hooks-overview.md` presented   itself as "the client-side hook surface" while documenting 13 of 44 hooks; it   now enumerates the schema-driven-UI, files/permissions/utilities, and AI   families (en + de). - **A coverage GATE** (`agentsMdTemplate.test.ts`): every exported `use*` hook of   `@voltro/client` must appear in the composed agent-docs corpus, or the test   fails with the list. Docs can no longer silently fall behind the export surface. Plus **`voltro doctor` now flags hand-rolls**: it scans an app's source for the patterns a shipped primitive covers (hand-rolled form/table, `FileReader` upload, `setTimeout` debounce, `useMemo` fan-in, local Next.js compat shims, hand-rolled presence) and names the primitive to use. Advisory, never fatal — a false-positive lecture must not fail a build.
+- **@voltro/cli** — **Generated `matchError` / `AppError` / `AppErrorTag`.** Codegen now emits a per-app exhaustive error matcher into `rpcGroup.generated.ts`, derived BY REFERENCE from every descriptor's `error:` schema plus the cross-cutting plugin errors. `matchError(err, { [tag]: handler }, fallback?)` dispatches on `_tag` with the handler keys constrained to the app's ACTUAL error tags — so a hand-maintained tag list that silently drifts (dead/renamed tags) is gone; a stale tag is a compile error. Browser-safe (reads `_tag` structurally, no runtime dep). Workflows keep their existing `WorkflowErrors`.
+- **@voltro/cli** — **`voltro doctor` + `voltro update --codemods-only`/`--from`** — two upgrade-path ergonomics from AWB adoption feedback: - **`voltro doctor [app]`** (and **`voltro serve --preflight`**) preflights an API   app for production serve: it verifies the precompiled serve bundle exists and,   if not, prints the exact fix and exits 1 — so a Dockerfile / CI step catches   "prod `voltro serve` with no `voltro build`" at BUILD time instead of at   cold-start (0.3.0 made an unbuilt production serve fatal). - **`voltro update --codemods-only` (alias `--run-codemods`) + `--from <version>`**   — re-apply the codemods + manual notes for an explicit `[from, to]` delta   WITHOUT bumping `package.json` or installing. The recovery path for a hand-edited   version bump (`bump package.json` + install first), which otherwise makes   `voltro update` report "already on X — nothing to do" and silently skip the   codemods. `--from` also overrides the auto-detected source version on a normal   update.
+- **@voltro/runtime** — **`encryptField` / `decryptField` — standalone field cipher for raw-SQL paths.** `.encrypted()` columns encrypt/decrypt transparently inside the `ctx.store` middleware, so a code path that reaches the DB by RAW SQL (an auth strategy with no store handle reading/writing a session token, a one-off backfill) bypasses it. `@voltro/runtime` now exposes the SAME registered cipher standalone: `encryptField` encrypts a value; `decryptField` decrypts an `enc:v1:…` value and passes a non-ciphertext value through unchanged (so a raw-SQL path can adopt encryption while pre-existing plaintext rows keep working). Both throw a clear error when no cipher is registered. Encryption stops being all-or-nothing tied to going through `ctx.store`.
+- **@voltro/testing** — **`makeVoltroTestClient` — the missing half of the test story.** The framework shipped a strong BACKEND test story (`makeTestContext`, `mockStore`, `mockAi`, the workflow runner) and nothing for the client. A Voltro frontend is a reactive-data app: with no way to render a component against mocked `useSubscription` / `useMutation` — and to inject a loading state, a stream error, or a failing write — it is structurally untestable, which is why real apps end up with zero frontend tests. `import { makeVoltroTestClient } from '@voltro/testing/client'` returns a `Provider` plus `setSubscription` / `failSubscription` / `resetSubscription` and a `calls` log of every write with its input. A tag ABSENT from the fixture stays in the loading state — the distinction from an empty result is exactly what you want to assert. Deliberately NOT a renderer: it hands you a Provider, so it works with `react-dom/client` + `act`, testing-library, or your own harness, and locks you into none of them.
+- **@voltro/i18n** — **Plurals, Intl formatters, and catalogs a bundler can actually split.** - **`plural(locale, count, forms)` + `usePlural`** — real CLDR categories via   `Intl.PluralRules`. Replaces the hardcoded `"{count} epic(s)"` pattern, whose   literal `(s)` is simply wrong outside English, and which cannot express   languages that distinguish few from many (Polish 2–4 vs 5+). An explicit `zero`   form is honoured for exactly 0; ordinals via `{ type: 'ordinal' }`. - **`useFormatDate` / `useRelativeTime` / `useFormatNumber` / `useFormatCurrency`   / `useFormatters`** — locale-bound `Intl` wrappers, so an app stops carrying   several divergent hand-rolled "X minutes ago" helpers that each round   differently. - **`defineCatalogs` + `LazyI18nProvider`** — code-split catalogs.   `pickCatalog({ en, de })` is a STATIC import map: every locale is a value-level   import, so the bundler must emit them in one chunk and a German-only visitor   downloads English too, growing linearly per locale. A map of `() => import()`   loaders is the only shape a bundler treats as a chunk boundary. `preload(locale)`   before hydration keeps first paint synchronous via `peek()`; the provider's   `fallback` is for a locale SWITCH, not first paint. Unknown locales degrade to   the base catalog, and a failed chunk load stays retryable.
+- **@voltro/protocol, @voltro/client** — **Nested optimistic: `shapeItem` + bulk (multi-item) targets.** Two additive improvements to path-targeted auto-optimistic: - **`shapeItem`** — the nested counterpart of `shape`, typed to the ITEM of the   nested array (not the mutation's output), so a path-target patch reads/returns   the item without casting `current`. (Previously the nested shaper was the flat   `shape`, pinned to the output row — every adopter had to cast. `shape` stays   bound to the output for flat targets; a single field can't be both, so the   nested shaper is its own.) - **Bulk `identify`** — a target's `identify` may now return `string[]` to   patch/delete MANY items (or top-level rows) in one mutation — the group-drag /   batch-edit case where per-item parallel writes used to race. Each patched item   keeps its own key. Runtime-compatible: a nested target that still uses `shape` falls back transparently. No codemod — additive.
+- **@voltro/web, @voltro/client** — **Two hooks apps kept hand-rolling, because nothing shipped them.** - **`useTheme` (`@voltro/web`)** — returns `{ theme, resolvedTheme, setTheme }`   over the framework's own `voltro:theme` cookie and the `html.dark` class. The   bug it removes is specific: an app that hand-rolls a second theme store ends up   with two writers on one class, so the toggle's state and the rendered theme can   disagree, and the pre-paint script flashes the wrong one. `'system'` resolves   through `matchMedia` and tracks live OS changes. - **`useConnectionStatus` (`@voltro/client`)** — `'connected' | 'degraded' |   'offline'`, derived from the only two signals the client honestly has:   `navigator.onLine` (browser says the network is gone) and the rpc error bus (a   call actually failed). `degraded` means "we saw a failure and no success since";   coming back online clears it, because the failures counted during an offline   window ARE that window. Deliberately no polling ping just to colour an   indicator.
+- **@voltro/database** — **`.uniqueActive([cols])` now works on mysql / mariadb** (it previously failed loud at migrate — those engines have no partial index). It lowers automatically to a STORED generated column per key column — `CASE WHEN <predicate> THEN CAST(<col> AS CHAR(255)) ELSE NULL END` — plus a UNIQUE over them. NULL-distinct uniqueness means a soft-deleted row's generated columns are all NULL and never collide, so re-creating the key just works — the same resurrection-safe semantics the partial index gives on postgres/sqlite/mssql. The lowering is applied identically on the emit side and the declared-snapshot side, so it round-trips through the declarative differ (verified live on MariaDB: declare→migrate→introspect→re-plan is a no-diff, and a duplicate among active rows is rejected while soft-deleting one frees the key). You write the same `.uniqueActive([...])` on every dialect.
+
+### Fixed
+
+- **@voltro/cli** — **Standalone `voltro codegen` now emits the SAME `rpcGroup.generated.ts` as `voltro dev` / `voltro build`.** Previously the standalone command skipped the app's plugins, so it dropped every plugin's cross-cutting error union AND its client RPC routes — an inconsistent generated file (typed plugin errors gone, plugin route tags unresolved) vs the dev/serve boot path. The command now loads `app.config` and gathers the plugins' codegen inputs through the SAME `gatherCodegenPluginImports` the boot path uses (single-sourced, so the three paths can't drift).
+- **@voltro/cli** — **The hook-coverage gate was too weak, and it let dead documentation through.** It asked only whether a hook's NAME appeared in the agent-docs corpus — which a one-line row in a link table satisfies. Ten client hooks had exactly that, and six of those rows linked to a page that never mentions the hook, so a reader following the link learned nothing. Two sharper checks replace it: - **Substance** (`agentsMdTemplate.test.ts`): a hook must appear at least once   OUTSIDE a table row, so a bare row no longer counts as documentation. - **Dead references** (`gen-agent-docs.mjs`): a row promising `[`useX`](/docs/…)`   must point at a page that actually mentions `useX`. This lives in the generator   because that is the only thing which reads the docs tree — and it walks BOTH   language trees, since an en-only check leaves every German dead link invisible.
+- **@voltro/cli** — - **Serve bundle: inline the pure-JS SQL drivers (`pg`/`mysql2`/`tedious`) instead of runtime-shimming them.** A production `voltro serve` with a postgres/mysql/mssql store crashed at boot with `Pg.Pool is not a constructor` (and the mysql/mssql equivalents): the driver's `@effect/sql-*` consumer links its leaf as a namespace (`import * as Pg from 'pg'; new Pg.Pool()`), but the native-leaf CJS shim (`module.exports = <leaf>`) did not surface the named members through esbuild's `import * as` interop, so `Pg.Pool` was `undefined`. These drivers are pure JS (no `.node`), so they are now inlined into the serve bundle like the rest of the framework — esbuild links the real module and the namespace resolves correctly. Only genuinely-native leaves (`better-sqlite3`, the turso/libsql addons, `pg-native`) and the dynamically-imported `ioredis`/`nodemailer` still resolve via the runtime shim. Verified end-to-end from a relocated prod tree (a real `POST /rpc` through the inlined `pg`).
+
+---
+
+## [0.3.0] — 2026-07-18
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — `voltro build` precompiles the whole serve path (framework + effect + `@voltro` inlined, app modules as lazy chunks) into a single **serve bundle**, and `voltro serve` boots from it in-process — cutting `serve: ready` from ~1000 ms to ~180 ms (5–6×; the win is larger on a cold scale-to-zero container). The app's declared SQL driver is inlined (only the native leaf like `pg` stays external, resolved at runtime so it survives the deploy relocation). **Production now serves ONLY from the bundle and NEVER transpiles on demand:** the bundle build externalises unresolvable optional peers (e.g. `@react-email/render` behind `@voltro/plugin-mail`) so it always builds; a bundle-build failure is **fatal** (`voltro build` exits non-zero); and an unbuilt production `voltro serve` fails loud instead of falling back to tsx. The build toolchain (`tsx`, `esbuild`, `vite`, `@vitejs/plugin-react`, `@tailwindcss/vite` + their native tree: rolldown/lightningcss/postcss/jiti) moves to **`optionalDependencies`** of `@voltro/cli`, so `pnpm --prod --no-optional deploy` yields a serve image with none of it — a prod API image's `node_modules` drops ~305 MB → ~131 MB, structurally, with no fragile prune list. `voltro dev` and a non-production local `voltro serve` are unchanged (still tsx). **Migration:** in production (`NODE_ENV=production`) run `voltro build` before `voltro serve`. The generated Dockerfiles already do; a custom Dockerfile / start script adds a `voltro build .` step before `voltro serve .` (`voltro update` prints this — see the 0.3.0 codemod note).
+
+### Added
+
+- **@voltro/protocol, @voltro/runtime, @voltro/plugin-rbac** — Declarative authorization `guards:` on `defineMutation` / `defineQuery` / `defineAction`. The framework enforces the declared scope(s) in the dispatch spine BEFORE the executor (for a mutation, before the transaction opens), fails with a typed `ScopeError`, and auto-merges `ScopeError` into the wire error union so the client decodes the denial typed. Guards are browser-safe DATA (scope strings + a pure `resource: (input) => id` extractor). Checks run against the caller's EFFECTIVE scope set — raw subject scopes ∪ `@voltro/plugin-rbac` role-derived scopes — via a new canonical effective-scope seam in `@voltro/protocol` (`effectiveScopes` / `setEffectiveScopes` / `checkGuards`), which rbac now publishes to (so a role-granted scope satisfies a `guards:` entry and the in-handler `permission()` identically). Adds `ctx.access` (`has` / `hasAny` / `require` / `scopes`) — the cast-free typed authorization slice on every handler context. Enforcement is single-sourced in the shared serve pipeline, so `voltro dev` and `voltro serve` can't drift.
+- **@voltro/protocol, @voltro/client** — Nested / path-targeted auto-optimistic. A mutation `target` can now patch a nested array INSIDE a query's value — a JSON array column (`snapshot.projects`) or a computed/shaped result — at item granularity, via `path` (dot-path to the array), `by` (item key, default `id`), and `match` (a pure predicate that scopes the patch to the entries whose current value satisfies it, preventing a patch bleeding across sibling subscriptions that share a source table). Previously auto-optimistic only patched the flat top-level row array keyed by `id`; nested values needed a hand-written `.withOptimistic` reducer. `path`/`by`/`match` are browser-safe descriptor data (a dot-path string + pure predicate), same discipline as `identify`/`shape`. A path insert is applied even on a computed entry (it targets a known document, not a blind top-level add).
+- **@voltro/runtime** — `ctx.store.applyDefined(input, keys)` (and a standalone `applyDefined` export from `@voltro/runtime`) — builds a partial-update patch keeping only the listed keys whose value the caller actually provided (`!== undefined`; a defined falsy value like `0`/`''`/`false` is kept). Collapses the per-field `if (input.x !== undefined) patch.x = input.x` idiom every partial-update mutation hand-writes.
+- **@voltro/database** — `.uniqueActive([cols], opts?)` on the table builder — a portable partial-UNIQUE constraint that holds only among the rows matching a predicate (default `"deletedAt" IS NULL`, pairing with `.softDelete()`). Emits `CREATE UNIQUE INDEX … WHERE` on postgres / sqlite / mssql, so a soft-deleted row leaves the active set and a NEW row with the same key inserts cleanly — no hand-written `generatedAs("CASE WHEN …")` column and no resurrection footgun. On mysql / mariadb (no partial-index support) it FAILS LOUDLY at migrate time rather than silently emitting a full unique index that would forbid re-creating a soft-deleted key — the generated-STORED-column lowering for those dialects is a follow-up. Kept out of the declarative index snapshot (the incremental planner is predicate-blind and would misclassify a unique+partial index as a full constraint), so the fresh-schema DDL path is its sole emitter and there is no re-diff churn. Live-verified against postgres.
+- **@voltro/cli** — `voltro update` upgrades an app to the latest framework: it bumps every `@voltro/*` dependency, installs with the detected package manager, and runs the codemods shipped with the target version. Codemods are authored with `defineCodemod` + an import-scoped ts-morph helper toolkit (`renameImport`, `renameModuleSpecifier`, `renameJsxProp`, `renameObjectKey`, `add`/`removeImport`, structural `changeCallArgs`/`wrapCall`, `annotate`) and run against the app source; a `manual` kind surfaces written steps for changes that can't be automated. Breaking public-API changes now ship a codemod (or an explicit `codemod: none`), enforced by the changelog gate. Framework-owned `_voltro_*` table changes continue to ride the declarative differ on `voltro db apply` / `voltro dev` boot — `update` does not touch the database.
+
+### Fixed
+
+- **@voltro/database** — The core-table registry (`registerCoreTables` / `requireActors` / `requireTenants`) now stores its state on a process-global `Symbol.for` singleton, the same mechanism the main table registry already uses — instead of module-local `let` bindings. Module-local state splits when the `@voltro/database` module is duplicated in a process (e.g. resolved through both the `.` and `./sql` entry points, or a bundled framework copy alongside an externally-resolved one): one instance's `registerCoreTables` becomes invisible to the instance that reads it, surfacing as a spurious `core 'actors' table not registered` at store construction. Pinning it to `globalThis` makes every copy share one store, matching the table registry's already-global behaviour.
+
+---
+
 ## [0.2.2] — 2026-07-17
 
 ### Added

package/THIRD-PARTY-NOTICES.md

@@ -5,7 +5,7 @@ property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/cli itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (191 packages).
+Generated from the resolved runtime dependency closure (198 packages).
 
 ---
 
@@ -10139,6 +10139,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## @ts-morph/common@0.29.0
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2017 David Sherret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## @typespec/ts-http-runtime@0.3.5
 
 License: MIT
@@ -10490,6 +10518,36 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ```
 
+## balanced-match@4.0.4
+
+License: MIT
+
+```
+(MIT)
+
+Original code Copyright Julian Gruber <julian@juliangruber.com>
+
+Port to TypeScript Copyright Isaac Z. Schlueter <i@izs.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## base64-js@1.5.1
 
 License: MIT
@@ -10564,6 +10622,36 @@ programs and associated documentation files created by the
 Original Author, when distributed with the Software.
 ```
 
+## brace-expansion@5.0.6
+
+License: MIT
+
+```
+MIT License
+
+Copyright Julian Gruber <julian@juliangruber.com>
+
+TypeScript port Copyright Isaac Z. Schlueter <i@izs.me>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## buffer@5.6.0
 
 License: MIT
@@ -10640,6 +10728,34 @@ See the License for the specific language governing permissions and
 limitations under the License.
 ```
 
+## code-block-writer@13.0.3
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015-2024 David Sherret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## debug@4.4.3
 
 License: MIT
@@ -12590,6 +12706,68 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
+## minimatch@10.2.3
+
+License: BlueOak-1.0.0
+
+```
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules. The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice. If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+**_As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim._**
+```
+
 ## ms@2.1.3
 
 License: MIT
@@ -12823,6 +13001,33 @@ OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
 USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+## path-browserify@1.0.1
+
+License: MIT
+
+```
+MIT License
+
+Copyright (c) 2013 James Halliday
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+
 ## path-expression-matcher@1.5.0
 
 License: MIT
@@ -13982,6 +14187,34 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
+## ts-morph@28.0.0
+
+License: MIT
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2017 David Sherret
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## tslib@2.8.1
 
 License: 0BSD

package/bin/voltro.mjs

@@ -1,4 +1,16 @@
 #!/usr/bin/env node
+// `framework` executable. `pnpm install` symlinks this into every
+// dependent package's `node_modules/.bin/framework`, so user apps invoke
+// it from their npm scripts as just `voltro dev` / `voltro serve`
+// — same UX as `next dev` or `vite`, without the user knowing the bin
+// lives in our monorepo's framework/ tree.
+//
+// Prefer the bundled, minified `dist/bin.js` (the published artifact);
+// fall back to the TypeScript `src/bin.ts` when running from the
+// monorepo before a build (dev). The tsx ESM loader stays registered in
+// BOTH modes because the CLI imports the USER's `app.config.ts` (and
+// other `.ts` app files) at runtime — Node cannot import those without
+// it. The public bin interface (`voltro <cmd>`) is unchanged.
 
 import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
@@ -6,6 +18,16 @@ import { createRequire } from 'node:module'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { dirname, join, resolve } from 'node:path'
 
+// FAST PATH — `voltro serve <app>` with a precompiled SERVE BUNDLE boots from that
+// ONE artefact IN THIS PROCESS: no child `node --import tsx`, no CLI command
+// graph. `voltro build` esbuilds the whole serve path (framework + effect +
+// @voltro inlined) into `.framework/dist-api/serveBundle/serveEntry.js` with the
+// app modules as lazy .js chunks — so tsx is UNNECESSARY (nothing loads `.ts` at
+// runtime) and the second node startup + the tsx loader hook are pure overhead on
+// a cold scale-to-zero boot. The bundle's exported `runServe` loads `.env` itself
+// (idempotent) so the boot is fully self-contained here. In PRODUCTION the bundle
+// is MANDATORY — a missing/unusable bundle fails loud (below), never on-demand
+// tsx. Only non-production falls through to the tsx spawn path (a dev convenience).
 const argv = process.argv.slice(2)
 if (argv[0] === 'serve') {
   const appArg = argv.slice(1).find((a) => !a.startsWith('-'))
@@ -13,6 +35,11 @@ if (argv[0] === 'serve') {
   const serveBundle = join(serveRoot, '.framework', 'dist-api', 'serveBundle', 'serveEntry.js')
   if (existsSync(serveBundle)) {
     try {
+      // chdir to the app root BEFORE importing the bundle: the bundle's generated
+      // entry registers its app-module keys from `process.cwd()` at import time, so
+      // cwd must already be the app root (the serve runtime resolves the same keys
+      // by walking the app tree). This is what makes the bundle relocation-safe —
+      // the Docker deploy moves the app from `apps/x/api` to the image root.
       if (serveRoot !== process.cwd()) process.chdir(serveRoot)
       const mod = await import(pathToFileURL(serveBundle).href)
       if (typeof mod.runServe === 'function') {
@@ -20,17 +47,42 @@ if (argv[0] === 'serve') {
         process.exit(typeof code === 'number' ? code : 0)
       }
     } catch (error) {
-      console.warn('[voltro] serve bundle failed to load — using the standard serve path:', error?.message ?? error)
+      // Unusable bundle — degrade to the standard tsx path, never crash the boot.
+      console.warn('[voltro] serve bundle failed to load:', error?.message ?? error)
     }
   }
+  // PRODUCTION MUST serve from the precompiled bundle — never transpile on demand.
+  // If we reach here in production the bundle is missing or unusable: FAIL LOUD
+  // instead of silently spawning the slow tsx path (which re-transpiles the app on
+  // every cold start, defeating the whole precompiled-boot optimisation). `voltro
+  // build` produces the bundle and treats a build failure as fatal, so a healthy
+  // deploy never hits this. Non-production (dev / an unbuilt local serve) falls
+  // through to the tsx path below — on-demand transpile is a DEV-only convenience.
+  if (process.env.NODE_ENV === 'production') {
+    console.error(
+      `[voltro] FATAL: production \`voltro serve\` requires a precompiled serve bundle at\n  ${serveBundle}\n` +
+        'but it is missing or failed to load. Run `voltro build` before serving — a bundle-build ' +
+        'failure is fatal by design; production never transpiles on demand.',
+    )
+    process.exit(1)
+  }
 }
 
 const here = dirname(fileURLToPath(import.meta.url))
 const built = resolve(here, '..', 'dist', 'bin.js')
 const entry = existsSync(built) ? built : resolve(here, '..', 'src', 'bin.ts')
 
+// Resolve the tsx ESM loader RELATIVE TO @voltro/cli (which depends on it) —
+// NOT the user app's CWD. As a bare `--import tsx`, Node resolves the specifier
+// from the current working directory; strict pnpm nests tsx inside @voltro/cli,
+// so from a consuming app's dir it isn't reachable and a standalone (non-
+// monorepo) install fails at `voltro dev` / `voltro build` with "Cannot find
+// package 'tsx'". Resolving to an absolute URL here sidesteps CWD resolution
+// entirely (the monorepo happened to hoist tsx, which hid this).
 let tsxImport = 'tsx'
 try {
+  // import.meta.resolve applies tsx's export map (the ESM auto-register entry);
+  // synchronous since Node 20.6.
   tsxImport = import.meta.resolve('tsx')
 } catch {
   try {
@@ -46,6 +98,11 @@ const child = spawn(
   { stdio: 'inherit' },
 )
 
+// Forward signals the parent receives to the child. Without this the
+// shim catches SIGTERM (e.g. from `kill $PID` in test-all.sh) and exits,
+// leaving the spawned Node child as an orphan still bound to its port.
+// Subsequent harness stages then fail to start their own server because
+// the port is held by the orphan.
 const forward = (signal) => () => {
   if (!child.killed) child.kill(signal)
 }
@@ -61,12 +118,25 @@ child.on('exit', (code, signal) => {
   process.exit(code ?? 0)
 })
 
+// Parent-death guard. When invoked from a smoke (or any wrapper) that
+// dies ungracefully — `process.exit(1)` skipping `finally`, kill -9,
+// IDE termination — we'd otherwise be reparented to init and keep our
+// tsx child alive holding the port. We watch our parent pid; when it
+// flips to 1 we forward SIGTERM to the child and exit. The 2s interval
+// gives the harness fast-enough orphan cleanup without burning a watch
+// loop per shim. The TSX child has its own ppid watch on US (the shim),
+// so this layer covers the case where the shim itself outlives its
+// parent; the inner layer covers the unusual case of the shim dying
+// while the tsx child somehow survives.
 const initialPpid = process.ppid
 if (initialPpid > 1) {
   const ppidWatch = setInterval(() => {
     if (process.ppid !== initialPpid || process.ppid === 1) {
       clearInterval(ppidWatch)
       if (!child.killed) child.kill('SIGTERM')
+      // Give the child a brief window to clean up + exit; if it doesn't,
+      // we exit anyway. The child's `on('exit')` above will route us out
+      // cleanly if it does.
       setTimeout(() => process.exit(0), 1500).unref()
     }
   }, 2000)