@voltro/cli 0.4.0 → 0.6.0

package/templates/agent-docs/authentication.md

@@ -1732,6 +1732,81 @@ export const todoPolicy = defineResourcePolicy({
 })
 ```
 
+## Enforce it declaratively — `guards:`
+
+`can` / `assertCan` above are the imperative form: you load the tuples and make
+the decision inside the handler. That works, and it is what you reach for when
+the check needs data you have already loaded.
+
+For the ordinary case — "may this caller perform ACTION on the row this input
+names?" — declare it on the descriptor instead:
+
+```ts
+export const todoUpdate = defineMutation({
+  name: 'todos.update',
+  input: Schema.Struct({ id: Schema.String, title: Schema.String }),
+  output: Schema.Void,
+  guards: [{ action: 'edit', resourceType: 'todo', resource: (input) => input.id }],
+})
+```
+
+The framework resolves it BEFORE the executor runs — for a mutation, before the
+transaction opens — and fails with a typed `ScopeError` naming
+`<resourceType>:<action>`.
+
+Why the declarative form is not just shorter: an in-handler check is one an
+author can forget, and a forgotten check is a silent hole rather than an error.
+The same is true of the older pattern of hand-maintaining a map from rpc tag to
+policy rule and installing it as an interceptor — that map is **fail-open by
+omission**: add an endpoint, forget the entry, and nothing anywhere tells you.
+A guard on the descriptor cannot be forgotten for an rpc that exists, because
+it is part of the rpc.
+
+Scope guards and relationship guards live in the same array and ALL must pass:
+
+```ts
+guards: [
+  { scope: 'todos:write' },                                        // may you edit todos at all
+  { action: 'edit', resourceType: 'todo', resource: (i) => i.id }, // may you edit THIS one
+]
+```
+
+A guard answers **may you call this**. It cannot answer **which rows may you
+see** — a list has no single resource to name. For visibility that follows from a
+relationship ("tickets on teams I hold a role on"), declare a
+[row filter](/docs/authentication/row-level-security) instead; it AND-merges a
+subject-derived predicate into every read, so it narrows and never grants.
+
+### Activate it: register a tuple source
+
+A relationship guard needs to read the caller's relations. That comes from the
+registered **tuple source**:
+
+```ts
+// app.config.ts or a *.startup.ts
+import { setTupleSource, loadResourceTuples } from '@voltro/runtime'
+
+setTupleSource((req) =>
+  loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId))
+```
+
+`voltro dev` / `voltro serve` register exactly this default for you, reading
+`_voltro_rebac_tuples`. Register your own when your relationships already live
+in your own tables — a `teamMembers` row is a relation; you should not have to
+copy it into a framework table to authorize against it.
+
+**Every unanswerable case denies.** No tuple source registered, no policy for
+that `resourceType`, an input that doesn't identify a resource, a tuple source
+that throws — each is a denial, not a pass. An authorization question nobody can
+answer is a refusal; treating it as a pass is how a policy layer ends up
+enforcing nothing while looking like it does.
+
+### Guards are re-checked on every subscription delivery
+
+A subscription is a long-lived grant. Its guards — scope and relationship alike
+— are re-evaluated before each delivery, so revoking a relation mid-session ends
+the stream with the typed error instead of continuing to push rows.
+
 ## Decide — `can` / `assertCan`
 
 `can(subject, action, resource, { policy, tuples })` is the decision; `assertCan`
@@ -1789,3 +1864,166 @@ Full API — including the batch `useResourceCans` for per-row gating — in
 `rebacPolicyGraph()` returns every resource type, its actions, the relations each
 grants, and the implication edges — the policy graph a dashboard or an AI agent
 reads to reason about authority without grepping the code.
+
+
+
+---
+
+<!-- source: en/authentication/row-level-security.md -->
+## Row-level security
+
+_setRowFilter — a subject-derived predicate AND-merged into every read, so relational visibility ("rows on teams I hold a role on") is declared once instead of hand-written into every list handler and every subscription._
+
+Reads already scope themselves by tenant and by soft-delete, and a descriptor's
+[`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards)
+decide whether you may call a procedure **at all**. Neither of those says which
+**rows** you may see.
+
+That gap matters as soon as visibility is *relational* — "tickets on teams I hold
+a role on". Without a row filter, that predicate has to be hand-written into
+every list handler and every subscription, and a filter you have to remember is a
+filter you only have to forget once.
+
+`setRowFilter` declares it once. The framework AND-merges the resulting predicate
+into every read.
+
+## The two phases
+
+```ts no-check
+setRowFilter({
+  load:      (subject) => Effect<Ctx>,                    // ASYNC, once per request
+  predicate: (ctx, table) => Predicate | undefined,       // PURE + SYNC, per read
+})
+```
+
+- **`load`** resolves everything the predicates need — the memberships, the role
+  rows, the project ids — **once per request**. It may read the store. This is
+  the expensive half.
+- **`predicate`** derives the filter for one table from what `load` already
+  fetched. It runs on **every read**, so it must be pure and synchronous. Return
+  `undefined` for a table this filter does not constrain — which is most tables.
+
+### Why two halves rather than one function
+
+A single async `(subject, table) => Promise<Predicate>` would be simpler to
+declare and much worse to run. Every read on the hot path would await, and the
+obvious implementation would re-query the membership tables **once per query** —
+so a handler that reads five tables pays five membership lookups.
+
+Splitting the phases makes the per-read cost a map lookup and makes the
+per-request cost explicit and visible: one load, reused.
+
+## A worked example
+
+The motivating shape — rows on teams the caller holds a role on:
+
+```ts no-check
+// apps/api/rls.startup.ts
+import { Effect } from 'effect'
+import { eq, inSet } from '@voltro/database'
+import { setRowFilter } from '@voltro/runtime'
+import { database } from './database/index'
+
+setRowFilter({
+  // ASYNC — once per request. Read your own tables here.
+  load: (subject) =>
+    Effect.promise(async () => {
+      const rows = await database.teamMembers
+        .where(eq('userId', subject.id ?? ''))
+        .all()
+      return rows.map((row) => row.teamId)
+    }),
+
+  // PURE + SYNC — runs on every read.
+  predicate: (teamIds: ReadonlyArray<string>, table: string) =>
+    table === 'tickets' ? inSet('teamId', teamIds) : undefined,
+})
+```
+
+Register it at boot — `app.config.ts` or a `*.startup.ts`. It is process-global
+and last-write-wins. `Ctx` is whatever your `load` returns; the framework never
+inspects it.
+
+With that registered, an ordinary list query needs no filter of its own:
+
+```ts no-check
+// apps/api/queries/tickets.list.query.server.ts
+export default () => database.tickets.orderBy('createdAt', 'desc')
+```
+
+A caller with no memberships gets zero rows. Nothing in the handler says so.
+
+## It can only narrow, never grant
+
+The predicate is **AND-merged** onto whatever the handler already asked for — it
+never replaces it. A row filter cannot widen a query, so it can never become an
+accidental grant:
+
+```ts no-check
+// the handler asks for one ticket; the filter still applies
+database.tickets.where(eq('id', 'ticket-42'))
+// → id = 'ticket-42' AND teamId IN (…the caller's teams)
+```
+
+## Both read paths are filtered
+
+The filter applies to descriptor reads **and** to the fluent builder. A filter
+present on only one read path is not a filter, it is a detour:
+
+```ts no-check
+await ctx.store.query(tickets.descriptor)   // filtered
+await ctx.store.select('tickets').all()     // filtered
+```
+
+## A failing `load` denies
+
+If `load` fails, every constrained read is **refused** rather than silently
+running unfiltered. A row filter that degrades to "no filter" under load failure
+is worse than no filter at all, because the system keeps serving and nothing
+looks wrong.
+
+The refusal is expressed as a predicate that matches nothing, not as an error —
+so a failure surfaces as an **empty result** rather than a 500 on every page. The
+underlying cause is reported separately, so it cannot pass unnoticed.
+
+## What does *not* bypass it
+
+| | Bypasses the row filter? |
+|---|---|
+| `.unscoped()` / `crossTenant` | **No** |
+| a `system` subject | Yes |
+
+`.unscoped()` and `crossTenant` exist for legitimate cross-tenant admin reads.
+They opt out of **tenant isolation**, not out of **authorization** — letting them
+also drop row visibility would turn an isolation opt-out into an authorization
+one, which is exactly the silent widening this feature exists to prevent.
+
+Only a `system` subject bypasses, because a system subject is the framework
+acting as itself — janitor sweeps, migrations, the scheduler — rather than on
+behalf of a user. That bypass is deliberately the narrow, explicit one.
+
+Apps that register no filter pay nothing.
+
+## Subscriptions re-resolve it
+
+A subscription is the one read path that stays open for hours, so it is the one
+where a stale filter would matter most. Before every delivery the runtime
+re-derives the read from the **unfiltered base descriptor** and re-applies the
+freshly resolved filter.
+
+A membership that ends mid-subscription therefore stops serving rows — the
+caller's open ticket list drops the rows they can no longer see, without a
+refresh and without the subscription having to be torn down.
+
+## Row filters vs. guards
+
+They answer different questions, and a complete policy usually wants both:
+
+| | Question | Failure |
+|---|---|---|
+| [`guards:`](/docs/authentication/authorization#enforce-it-declaratively-guards) | May you call this procedure? | typed `ScopeError`, before the executor runs |
+| `setRowFilter` | Which rows may you see? | the rows are simply absent |
+
+A guard is the right tool for "may this caller edit *this* ticket". A row filter
+is the right tool for "which tickets appear in the list at all" — a question a
+guard cannot answer, because there is no single resource to name.

package/templates/agent-docs/cli.md

@@ -30,6 +30,7 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
 | AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
+| [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled |
 | Harness | `test`, `e2e` |
 | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`) |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
@@ -739,6 +740,147 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The hand-roll detector
+
+`voltro doctor` also scans your source for shapes the framework already has a
+primitive for, and names the primitive at the spot the hand-roll lives. This is
+**advisory and never blocking** — it prints, it does not fail your build.
+
+```bash
+voltro doctor .
+```
+
+```text
+•  Shipped primitives you may be hand-rolling:
+   [server]
+   hand-written not-found branch on rows[0] — 12 file(s): queries/team.get.ts, …
+     → .one() — fails with the typed NoRowFound on zero rows AND on more than one
+   [client]
+   per-field useState + a submit flag (hand-rolled form) — 4 file(s): src/create-dialog.tsx, …
+     → useFormBinding — fields + validation from the mutation input Schema
+```
+
+It covers both halves of the stack:
+
+| Scope | It notices | Reach for |
+|---|---|---|
+| server | `if (!rows[0]) throw …` | `.one()` / `.first()` |
+| server | 3+ sequential `store.query` in one handler | `relations()` + `.with()` — or `Effect.all` |
+| server | `Effect.promise(() => ctx.store.…)` | `yield* EffectStore` |
+| server | `requireScope(...)` at the top of an executor | `guards:` on the descriptor |
+| server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
+| server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
+| server | `hasMore` + `limit + 1` | `paginateById` |
+| server | `.getTime()` / `.toISOString()` mapping a row on the way out | `rowSchema(table)` as the descriptor's `output` |
+| client | per-field `useState` + a submit flag | `useFormBinding` |
+| client | a table with local sort/filter state | `useDataTable` |
+| client | `FileReader` / `readAsDataURL` | `useUpload` |
+| client | `setTimeout` debounce in a `useEffect` | `useDebounced` |
+| client | `useMemo` fanning in several subscriptions | `useDerived` |
+| client | a local Next.js compat shim | the native `@voltro/web` exports |
+| client | a hand-rolled presence heartbeat | `@voltro/plugin-presence` |
+
+The rules are deliberately conservative — a detector that cries wolf trains you
+to ignore it. A column that already carries `.encrypted()`, or a handler that
+already uses `.one()`, stays silent.
+
+Two of them are worth spelling out, because their advice is not one-line:
+
+**The credential-column rule skips names that aren't credentials.** A name ending
+in `Id` / `_id`, a name ending in `Hash` / `_hash`, and a name beginning with
+`vault` are all left alone:
+
+| Column | Why it's skipped |
+|---|---|
+| `jiraSecretId`, `token_id` | an IDENTIFIER of a secret held elsewhere, not the secret |
+| `apiKeyHash`, `password_hash` | the hash IS the protection — encrypting it is nonsense, and it breaks the column as a unique lookup key |
+| `vaultToken` | a HANDLE into a secret store, naming a secret held elsewhere |
+
+The suffix tests use a camelCase / underscore boundary on purpose: a blind
+`/id$/i` would also swallow `apiKeyValid`, while `tokenIdentifier` — which ends
+in neither — must still fire.
+
+**The sequential-reads rule names TWO levers, and the criterion for choosing.**
+Both shapes chain later reads off earlier results, so no text-level heuristic can
+split them — you make the call:
+
+- The reads are a **parent → child walk on ONE key** → declare `relations()` in a
+  `*.relations.ts` and collapse them into `.with({ … })`: one JSON-aggregate
+  query, on every dialect.
+- The reads **collect ids from SEVERAL sources** (JSON-array references, a
+  junction carrying extra columns, JS-side sorting) → keep the assembly and run
+  the independent LEADING reads under `Effect.all`. Same queries, same results,
+  only concurrent — zero parity risk.
+
+The second case is the common one. Measured on a real 74-hit codebase, about two
+handlers were clean full-parity `relations()` conversions and the other ~72 were
+multi-source assemblies where `.with()` covers only part of the work or subtly
+changes behaviour. Prescribing `relations()` for all of them would be wrong ~97%
+of the time — and advice that is usually wrong trains you to ignore the finding.
+
+The human view shows the first three file paths per finding and says how many it
+withheld. Those paths are the actionable part — a count you cannot turn back
+into a work list tells you the size of the problem, not how to fix it — and the
+matching rule lives inside the CLI, so you cannot re-derive the list with your
+own grep. `--json` prints the complete scan, nothing elided, with no preflight
+output mixed in:
+
+```bash
+voltro doctor . --json          # the complete scan: every file path, machine-readable
+```
+
+```json
+{
+  "root": "/app/api",
+  "scannedFiles": 214,
+  "scannedDirs": ["queries", "mutations", "database"],
+  "findings": [
+    {
+      "id": "row-not-found",
+      "scope": "server",
+      "smell": "hand-written not-found branch on rows[0]",
+      "use": ".one() — fails with the typed NoRowFound on zero rows AND on more than one",
+      "files": ["queries/team.get.ts", "queries/user.get.ts", "…"]
+    }
+  ]
+}
+```
+
+That is the form to hand an agent, or to pipe into a script that works the list
+file by file.
+
+## `voltro capabilities` — what the framework actually exports
+
+Asked "what does this framework export", a language model will produce a
+confident answer whether or not it knows. This command replaces that guess with
+a reading of the `.d.ts` files in your own `node_modules`:
+
+```bash
+voltro capabilities              # human summary, grouped by package
+voltro capabilities --json       # the full machine-readable surface
+```
+
+```text
+voltro capabilities — 2517 exported symbols across 36 packages
+  @voltro/runtime@0.4.0 — 9 primitives, 41 values, 118 types
+    defineAggregate, defineReaction, defineSubscriber, defineResourcePolicy, …
+  @voltro/client@0.4.0 — 47 hooks, 12 components, 60 types
+    useSubscription, useMutation, useFormBinding, useDataTable, useUpload, …
+
+  * 8 primitive(s)/hook(s) appear nowhere in this project's agent guide:
+      @voltro/plugin-mail: defineEmail
+      …
+```
+
+Every symbol reported was read out of an installed package a moment ago, so an
+agent can **verify** the surface instead of recalling it. The `--json` form is
+stable and locale-independent — the same tree produces byte-identical output on
+every machine, so you can diff it across upgrades.
+
+Symbols marked `*` ship but appear nowhere in this project's seeded `AGENTS.md`
+/ `CLAUDE.md`. Refresh the guide with `voltro agents-md --force`, or read that
+package's README.
+
 ## Anti-patterns
 
 - **Running `voltro start` against a directory without `dist/`.** It exits 1 with a clear `no built dist found — run voltro build first` (checked against `.framework/dist/index.html` before any heavy work). Run `voltro build` first.

package/templates/agent-docs/configuration.md

@@ -91,6 +91,44 @@ build-time constant, still works.)
 | `envVar.boolean(opts)` | `boolean` | `true/1/yes/on` ↔ `false/0/no/off/""` |
 | `envVar.url(opts)` | `string` | validated with `URL` |
 | `envVar.enum([…] as const, opts)` | literal union | must be one of the values |
+| `envVar.secret(opts)` | `string` | server-only, required, length floor |
+
+### `envVar.secret` — for values that must not be guessable
+
+```ts
+env: defineEnv({
+  // Ours to invent → `voltro dev` mints one per project.
+  VOLTRO_SESSION_SECRET: envVar.secret({ generate: 'base64url' }),
+  // Someone else's to issue → must be fetched, never invented.
+  STRIPE_SECRET_KEY:     envVar.secret({ minLength: 20 }),
+})
+```
+
+It differs from `envVar.string({ access: 'secret' })` in three ways, each
+closing a specific failure:
+
+- **`access` is forced to `'secret'`** — a value with a length floor is never
+  something you meant to bundle into a browser.
+- **There is no `default`.** A default secret is not a secret: every
+  deployment that forgot to set the variable would share it.
+- **A length floor** (default 32). Presence alone does not catch the real
+  failure mode — a variable that is *set* but reads `change-me` signs forgeable
+  cookies while looking completely healthy.
+
+**`generate` opts a variable into per-project minting.** On first `voltro dev`,
+any declared-but-unset mintable secret is written to a gitignored `.env.local`
+and the boot continues. That is why no Voltro template ships a secret value: a
+placeholder in a template is a signing key published to everyone who downloads
+it, and it passes every check you could write.
+
+Leave `generate` off for anything a third party issues. A WorkOS API key is
+just as secret and just as required, but inventing one produces a value that
+merely *looks* right and authenticates nobody — better that the boot gate fails
+and a human fetches the real one.
+
+Minting is **development only**. `voltro serve`, `build` and `start` never mint:
+in production a missing secret is a boot failure, which is the whole point.
+Generate deployment values with `voltro secret generate <purpose>`.
 
 Every builder takes `{ access, optional?, default?, description?, example? }`.
 Use `default` for a fallback (the value type stays present, `A`); use