@voltro/cli 0.28.0 → 0.29.0

package/templates/agent-docs/workflows.md

@@ -680,9 +680,20 @@ The three recovery tools, and when each applies:
 | `retry` | The input was wrong, or the job is short + idempotent | Fresh execution, empty journal — every step runs again |
 | `resume` | The run is `suspended` (you set `suspendOnFailure: true`, or it awaits a signal) | Continues from the failure/suspend point — completed steps replay |
 | `redrive` | The run is `failed` (dead-letter) and re-running earlier steps is expensive/unsafe | Continues from the failure point — completed steps replay, failed steps re-run |
+| `resume-from-step` | The run is `failed`, but the failure point is **not** the right recovery point — an earlier step ran on stale/wrong state | Rewinds to a chosen step — steps before it replay, that step + everything after re-run |
 
 `redrive` refuses a run that isn't a not-yet-discarded failure (use `resume` for a suspended run, `retry` for a fresh execution), and it needs a durable journal — on the memory store there is nothing to re-drive, so it declines cleanly (`redriven: false` with a reason) rather than pretending. It works under `voltro serve` as well as `voltro dev`, because dead-letter recovery happens in production. A re-drive records a `run-redriven` event on the run's timeline.
 
+### Rewind further back — `resume-from-step`
+
+`redrive` continues from the step that **failed**. Sometimes that isn't the right place to restart: step 5 failed, but the real problem is that step 3 completed against stale external state, and re-running from the failure point would carry that bad result forward. `resume-from-step` rewinds to a step **you** choose:
+
+```sh
+voltro workflows resume-from-step wf_01H... charge-card   # rewind to 'charge-card' and re-run from there
+```
+
+It resets the chosen step **and every step after it** — including steps that succeeded — so they re-execute, while the steps *before* your target replay from the journal unchanged. `redrive` is the special case where your chosen step is exactly the one that failed. Like `redrive`, it works under both `voltro serve` and `voltro dev`, refuses a run that isn't a not-yet-discarded failure, refuses an unknown step name, and declines cleanly on a run with no durable journal.
+
 ## Compensation
 
 For saga-style workflows, model compensation explicitly with `Effect.catchAll` around the step that can fail after an earlier side effect:

package/templates/apps/api-ai/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.28.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
+    "@voltro/ai": "0.29.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-auth/package.json

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-auth": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
-    "@voltro/sql-postgres": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-auth": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
+    "@voltro/sql-postgres": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend/package.json

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-deactivation/package.json

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-deactivation": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-deactivation": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-mail/package.json

@@ -13,18 +13,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-mail": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-mail": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-mariadb/package.json

@@ -13,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/plugin-storage": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
-    "@voltro/sql-mysql": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/plugin-storage": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
+    "@voltro/sql-mysql": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-sqlite/.env.example

@@ -0,0 +1,19 @@
+# {{capProjectName}} — SQLite backend env. Copy to `.env` and adjust.
+
+# ── Database (embedded SQLite) ─────────────────────────────────────────
+DB_DIALECT=sqlite
+# A file path keeps data across restarts (the `.data/` dir is gitignored):
+DB_URL=file:./.data/{{projectNameSnake}}.sqlite
+# Or an ephemeral, in-process DB that vanishes on exit (great for tests):
+#   DB_URL=:memory:
+
+# Session signing secret — NO VALUE SHIPS HERE ON PURPOSE.
+#
+# `voltro dev` mints a unique one for this project into a gitignored
+# .env.local on first boot, so local development needs nothing from you.
+# A shipped placeholder would be a signing key published to everyone who
+# downloads this template, making every session in your deployment forgeable.
+#
+# Your DEPLOYMENT needs its own — `voltro serve` refuses to start without it:
+#     voltro secret generate session
+VOLTRO_SESSION_SECRET=

package/templates/apps/api-backend-sqlite/README.md

@@ -0,0 +1,38 @@
+# {{projectName}} / {{appName}}
+
+Voltro backend scaffold (template: **api-backend-sqlite**) — an embedded,
+single-process **SQLite** store. No database server to run; one native
+dependency (`better-sqlite3`, via `@voltro/sql-sqlite`).
+
+## Boot
+
+```bash
+pnpm install                # at the repo root
+pnpm --filter @{{projectName}}/{{appName}} dev
+# → http://localhost:4000
+# → ws://localhost:4000/ws
+```
+
+The database file is created on first boot at the `DB_URL` path
+(`.env.example` defaults to `file:./.data/{{projectNameSnake}}.sqlite`, which is
+gitignored). Use `DB_URL=:memory:` for an ephemeral, in-process database.
+
+## What's in here
+
+| File | Role |
+|---|---|
+| `app.config.ts`                         | App declaration (`store: 'sqlite'`); `voltro dev` reads this first. |
+| `.env.example`                          | `DB_DIALECT` + `DB_URL` — copy to `.env`. |
+| `database/schema.ts`                    | One example table (`notes`) with the `tenant()` mixin. |
+| `queries/notes.query.ts`                | Streaming subscription example. |
+| `mutations/notes.create.mutation.ts`    | Tenant-guarded mutation example. |
+
+Drop more `*.query.ts`, `*.mutation.ts`, `*.action.ts`, or `*.workflow.tsx`
+files anywhere in this tree — discovery is by file convention.
+
+## When to reach for something else
+
+SQLite is single-writer and single-process, so real-time subscriptions do not
+fan out across replicas (there is no CDC bus — within the one process they work
+as normal). Scale to `store: 'postgres'` / `'mysql'` / `'mariadb'` when you run
+more than one replica.

package/templates/apps/api-backend-sqlite/app.config.ts

@@ -0,0 +1,35 @@
+// Backend app for the {{projectName}} project, backed by SQLite. Read by
+// `voltro dev` (local) and `voltro serve` (production).
+//
+// `store: 'sqlite'` is the simplest DURABLE store: an embedded, single-file
+// (or `:memory:`) database with no server to run and one native dependency
+// (`better-sqlite3`, pulled by `@voltro/sql-sqlite`). Great for a single
+// process — a CLI tool, an edge box, a small self-hosted app, or a durable
+// local dev store that survives restarts (unlike `store: 'memory'`).
+//
+// The database file + dialect come from env — see `.env.example`:
+//   DB_DIALECT=sqlite
+//   DB_URL=file:./.data/{{projectNameSnake}}.sqlite   (or ':memory:')
+//
+// SQLite is single-writer and single-process by design, so it does NOT
+// fan real-time subscriptions across replicas (there is no CDC bus). Within
+// the one process, reactive queries work exactly as elsewhere. Reach for
+// postgres/mysql/mariadb when you scale to more than one replica.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Typed environment — declare your env once; it's validated at boot (fail-fast)
+// and read on the server via `serverEnv` / `getSecret` from '@voltro/env/server'.
+// `access` is required: 'public' (browser-safe) or 'secret' (server-only, never
+// bundled). Run `voltro env` to see the manifest. See the Environment docs.
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+  // Add your own, e.g.:
+  //   STRIPE_KEY: envVar.string({ access: 'secret' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'sqlite' as const,
+  env,
+}

package/templates/apps/api-backend-sqlite/database/schema.ts

@@ -0,0 +1,54 @@
+// Schema for the {{projectName}} backend.
+//
+// Tables are auto-discovered: every exported `table(...)` in this file
+// (or any `*.entity.ts` / `*.schema.ts` file) is registered by
+// `voltro dev` — no manual barrel. `actors` + `tenants` are the
+// framework's core tables: the built-in `audit()` / `tenant()` /
+// `softDelete()` mixins reference them, so they must be declared (the
+// CLI wires them into the mixin registry once it finds them).
+//
+// Add the `tenant()` mixin to a table to make it tenant-scoped — the
+// runtime AND-merges `eq('tenantId', subject.tenantId)` into every
+// subscription predicate, so cross-tenant reads can't leak.
+
+import {
+  boolean,
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+import { tenant } from '@voltro/plugin-multitenancy'
+
+// ---------- Core tables (required by the audit / tenant mixins) ----------
+
+export const actors = table('actors', {
+  id:          id(),
+  kind:        text().oneOf(['user', 'serviceAccount', 'apiKey', 'system']),
+  displayName: text().nullable(),
+  createdAt:   timestamp().default('now'),
+})
+
+export const tenants = table('tenants', {
+  id:        id(),
+  name:      text(),
+  createdAt: timestamp().default('now'),
+})
+
+// ---------- Application tables — rename / replace with your own ----------
+
+export const notes = table('notes', {
+  id:    id({ prefix: 'note' }),
+  title: text(),
+  body:  text(),
+  done:  boolean().default(false),
+})
+  // tenant() pulls audit() transitively → adds tenantId + createdAt /
+  // updatedAt / createdBy / updatedBy (auto-stamped by the runtime).
+  .with(tenant())
+
+export type Note = InferRow<typeof notes>
+
+export const database = databaseHandle({ actors, tenants, notes })

package/templates/apps/api-backend-sqlite/mutations/notes.create.mutation.server.ts

@@ -0,0 +1,19 @@
+import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import type { AppContext } from '@voltro/runtime'
+
+const execute = async (
+  input: { tenantId: string; title: string; body: string },
+  ctx: AppContext,
+) => {
+  assertOwnTenant(input.tenantId, ctx.request.subject)
+  // Framework auto-injects a `note_…` id from the table's id() decl.
+  return ctx.store.insert('notes', {
+    title: input.title,
+    body: input.body,
+    done: false,
+    tenantId: input.tenantId,
+    createdAt: new Date(),
+  })
+}
+
+export default execute

package/templates/apps/api-backend-sqlite/mutations/notes.create.mutation.ts

@@ -0,0 +1,37 @@
+// Creates a note. The handler's `assertOwnTenant` guard rejects
+// cross-tenant spoofing — input.tenantId MUST match the resolved
+// subject's tenantId, else the rpc layer surfaces a typed
+// `TenantMismatch` error.
+
+import { defineMutation } from '@voltro/protocol'
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: {
+    table: 'notes',
+    op: 'insert',
+    shape: (input: { tenantId: string; title: string; body: string }) => ({
+      title: input.title,
+      body: input.body,
+      done: false,
+      tenantId: input.tenantId,
+      createdAt: new Date(),
+    }),
+  },
+  input: Schema.Struct({
+    tenantId: Schema.String,
+    title: Schema.NonEmptyString,
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+  error: TenantMismatch,
+})

package/templates/apps/api-backend-sqlite/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "migrate": "voltro migrate",
+    "test": "voltro test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform": "^0.97.0",
+    "@effect/rpc": "^0.76.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
+    "@voltro/sql-sqlite": "0.29.0",
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.29.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/api-backend-sqlite/queries/notes.query.server.ts

@@ -0,0 +1,14 @@
+import type { AppContext } from '@voltro/runtime'
+
+const execute = (_input: Record<string, never>, _ctx: AppContext) => ({
+  descriptor: {
+    table: 'notes' as const,
+    predicate: undefined,
+    order: [{ column: 'createdAt' as const, direction: 'desc' as const }],
+    take: 100,
+    skip: undefined,
+    projection: undefined,
+  },
+})
+
+export default execute

package/templates/apps/api-backend-sqlite/queries/notes.query.ts

@@ -0,0 +1,20 @@
+// Streaming subscription: every change to `notes` for the caller's
+// tenant lands as a delta. The runtime AND-merges tenant scope into
+// the predicate via the `tenant()` mixin on the table — no manual
+// `eq('tenantId', ...)` needed in the handler.
+
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id: Schema.String,
+    title: Schema.String,
+    body: Schema.String,
+    done: Schema.Boolean,
+    tenantId: Schema.String,
+    createdAt: Schema.Date,
+  }),
+})

package/templates/apps/api-backend-sqlite/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-backend-sqlite",
+  "kind": "api",
+  "summary": "SQLite-backed Voltro backend: a single-process, embedded, zero-server database (file or :memory:). The simplest durable-store shape — no docker, one dependency.",
+  "tags": ["api", "backend", "sqlite", "embedded", "single-process", "durable"]
+}

package/templates/apps/api-backend-sqlite/tests/notes.create.test.ts

@@ -0,0 +1,50 @@
+// Unit test with `@voltro/testing` — no database, no running server. Importing
+// `../database/schema` registers the `notes` / `actors` / `tenants` tables
+// globally, so `makeTestContext` auto-wires them into the in-memory store.
+// `ctx.store` is the SAME mixin-wrapped store the handler gets in production,
+// so tenant auto-scoping + audit auto-fill behave exactly as at runtime.
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { makeTestContext, mockStore } from '@voltro/testing'
+import { database } from '../database/schema' // registers notes / actors / tenants
+import { TenantMismatch } from '@voltro/plugin-multitenancy/guard'
+import createNote from '../mutations/notes.create.mutation.server'
+
+describe('notes.create', () => {
+  it('inserts a note stamped to the caller tenant', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    const row = await createNote({ tenantId: 'acme', title: 'Hello', body: 'World' }, ctx)
+
+    expect(row['title']).toBe('Hello')
+    expect(row['tenantId']).toBe('acme')  // assertOwnTenant let it through + stamped
+    expect(row['done']).toBe(false)
+    expect(String(row['id'])).toMatch(/^note_/) // TypeID auto-injected from id()
+  })
+
+  it('rejects a cross-tenant spoof — input.tenantId must match the subject', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'user_1', tenantId: 'acme' },
+      store:   mockStore({ notes: [] }),
+    })
+    await expect(
+      createNote({ tenantId: 'other-tenant', title: 'spoof', body: '' }, ctx),
+    ).rejects.toBeInstanceOf(TenantMismatch)
+  })
+
+  it('isolates tenants — t2 never sees t1 rows (REAL tenant scoping)', async () => {
+    const ctx = makeTestContext({
+      subject: { type: 'user', id: 'u1', tenantId: 't1' },
+      store:   mockStore({ notes: [] }),
+    })
+    await createNote({ tenantId: 't1', title: 'secret', body: '' }, ctx)
+
+    // Re-scope the SAME store to a different tenant — the real WHERE filter
+    // (eq tenantId) hides t1's row from t2.
+    const seenByT2 = await ctx.withTenant('t2', (c) => c.store.query(database.notes.descriptor))
+    expect(seenByT2).toHaveLength(0)
+  })
+})

package/templates/apps/api-backend-sqlite/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/apps/api-backend-storage/package.json

@@ -11,17 +11,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.28.0",
-    "@voltro/database": "0.28.0",
-    "@voltro/env": "0.28.0",
-    "@voltro/plugin-multitenancy": "0.28.0",
-    "@voltro/plugin-storage": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/plugin-storage": "0.29.0",
+    "@voltro/protocol": "0.29.0",
+    "@voltro/runtime": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }