@voltro/cli 0.5.0 → 0.7.0

package/templates/agent-docs/cli.md

@@ -765,12 +765,13 @@ 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()` |
+| 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` |
@@ -783,6 +784,71 @@ The rules are deliberately conservative — a detector that cries wolf trains yo
 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
@@ -1756,7 +1822,7 @@ _voltro update — bump the framework to the latest version and run the codemods
 `voltro update` upgrades an app to the latest framework release. It does three things in order:
 
 1. **Bump** every `@voltro/*` dependency in `package.json` to the target version.
-2. **Install** with your package manager (detected from the lockfile — pnpm / npm / yarn / bun).
+2. **Install** with your project's package manager — see [Which package manager](#which-package-manager) below.
 3. **Run the codemods** shipped with the target version — automatic source rewrites for any breaking API change, plus printed manual steps for anything that can't be automated.
 
 ```bash
@@ -1765,12 +1831,47 @@ voltro update --to 0.4.0      # pin an explicit target version
 voltro update --dry-run       # preview the bump + which codemods would run — writes nothing
 voltro update --force         # allow a dirty working tree (not recommended)
 voltro update --exact         # pin exact versions (drop the ^ / ~ range prefix)
+voltro update --help          # every flag — always answered, even on a dirty tree
 
 # Recover the codemods after a MANUAL version bump (no bump, no install):
 voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0 → installed
 voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
 ```
 
+## In a workspace, the whole workspace moves
+
+Run `voltro update` anywhere inside a workspace — a `pnpm-workspace.yaml`, or a
+`workspaces` field in an ancestor `package.json` — and **every member
+`package.json` that declares `@voltro/*` is bumped to the same version**, with
+the install running **once at the workspace root**.
+
+This is not a convenience. Your api and your web app share generated types (the
+rpcGroup) and a session cookie shape; if the api moves to 0.6.0 while
+`apps/web` and `packages/ui-*` stay on 0.5.0, the mismatch shows up as a runtime
+decode error in the browser, not as a build failure. Half-upgraded is the worst
+state to be in, so `voltro update` never leaves you there.
+
+The plan output — and `--dry-run` — lists every file it will touch:
+
+```text
+voltro update: 0.5.0 → 0.6.0
+  workspace: /repo (4 package.json with @voltro/* deps)
+  package.json
+    @voltro/cli: ^0.5.0 → ^0.6.0
+  apps/api/package.json
+    @voltro/cli: ^0.5.0 → ^0.6.0
+    @voltro/database: ^0.5.0 → ^0.6.0
+  apps/web/package.json
+    @voltro/client: ^0.5.0 → ^0.6.0
+  packages/ui-admin/package.json
+    @voltro/web: ~0.5.0 → ~0.6.0
+  package manager: pnpm
+  install runs in: /repo
+```
+
+A standalone (non-workspace) project is unaffected: its own `package.json`, its
+own install, in place.
+
 ## Already bumped by hand? Recover the codemods
 
 If you bump `@voltro/*` versions in `package.json` yourself and install first, a
@@ -1793,9 +1894,31 @@ source version.
 
 Codemods **rewrite your source**, so you need a clean diff to review afterwards. `voltro update` refuses to run on a dirty git working tree — commit or stash first. Use `--dry-run` to preview without touching anything, or `--force` to override the guard (you accept a mixed diff).
 
+`--help` / `-h` is answered *before* the guard, so `voltro update --help` prints the flag list even on a dirty tree. The same holds for `voltro doctor --help`.
+
+## If the install fails
+
+The bump is written before the install runs, so a failed install leaves your `package.json` on the target version — and **no codemods applied**. `voltro update` says so explicitly, because the codemods for a jump ship *inside* the target version: a failed install never put them on disk, so there is nothing that could have run them. Fix the install, run it, then apply the codemods you are missing with the command the failure message prints for you:
+
+```bash
+voltro update --codemods-only --from 0.5.0 --to 0.6.0
+```
+
 ## What gets bumped
 
-Every `@voltro/*` entry in `dependencies` and `devDependencies`, with the range style preserved (`^0.3.0` stays caret, `~0.3.0` stays tilde) unless you pass `--exact`. Non-registry specs (`workspace:*`, `catalog:`, `link:`, …) are left untouched — they're already resolved by your monorepo or catalog.
+Every `@voltro/*` entry in `dependencies` and `devDependencies` — in every workspace member, see above — with the range style preserved (`^0.3.0` stays caret, `~0.3.0` stays tilde) unless you pass `--exact`. Non-registry specs (`workspace:*`, `catalog:`, `link:`, …) are left untouched — they're already resolved by your monorepo or catalog.
+
+## Which package manager
+
+`voltro update` never assumes npm. It resolves your project's package manager in this order, starting in the app directory and walking **up to the repo root**:
+
+1. The **`packageManager` field** in a `package.json` (the corepack standard) — authoritative, wins over any lockfile.
+2. A **lockfile** at that level — `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` / `bun.lockb`, `package-lock.json`.
+3. **npm**, only when nothing declares one.
+
+Walking up matters in a workspace: a scaffolded Voltro project keeps its lockfile at the monorepo root, so running `voltro update` from `apps/api` still finds `pnpm` rather than falling back to npm and running `npm install` against a pnpm workspace.
+
+The same resolved manager is used for the **registry lookup** of the latest version (`pnpm view`, `yarn npm info`, `bun pm view`), so a private or scoped registry configured in your `.npmrc` / `.yarnrc.yml` is honored. `npm view` is only a last-resort fallback.
 
 ## Codemods
 

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