@voltro/cli 0.27.0 → 0.29.0

package/templates/apps/api-status/database/schema.ts

@@ -0,0 +1,70 @@
+// Schema for the {{projectName}} status page.
+//
+// These tables are PUBLIC and NOT tenant-scoped on purpose: a status page is
+// read by anyone, so the live queries must return rows for an anonymous caller.
+// (Adding `tenant()` here would AND-merge `tenantId = subject.tenantId` and an
+// anonymous visitor — tenantId null — would see nothing.) Write access is
+// controlled by the rbac `status:write` guard on the mutations instead.
+//
+// `actors` + `tenants` are the framework core tables.
+import {
+  databaseHandle,
+  id,
+  table,
+  text,
+  timestamp,
+  type InferRow,
+} from '@voltro/database'
+
+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'),
+})
+
+// A monitored service component (API, Dashboard, Webhooks, …).
+export const components = table('components', {
+  id:     id({ prefix: 'cmp' }),
+  name:   text(),
+  status: text().oneOf(['operational', 'degraded', 'partial_outage', 'major_outage']),
+})
+
+// An incident. `impact` drives the public banner colour; `status` walks the
+// lifecycle investigating → identified → monitoring → resolved.
+export const incidents = table('incidents', {
+  id:         id({ prefix: 'inc' }),
+  title:      text(),
+  impact:     text().oneOf(['minor', 'major', 'critical']),
+  status:     text().oneOf(['investigating', 'identified', 'monitoring', 'resolved']),
+  startedAt:  timestamp().default('now'),
+  resolvedAt: timestamp().nullable(),
+})
+
+// A timeline entry posted against an incident. The public page renders these in
+// order under each incident.
+export const incidentUpdates = table('incident_updates', {
+  id:         id({ prefix: 'iu' }),
+  incidentId: text(),
+  body:       text(),
+  status:     text().oneOf(['investigating', 'identified', 'monitoring', 'resolved']),
+  createdAt:  timestamp().default('now'),
+})
+
+export type Component = InferRow<typeof components>
+export type Incident = InferRow<typeof incidents>
+export type IncidentUpdate = InferRow<typeof incidentUpdates>
+
+export const database = databaseHandle({
+  actors,
+  tenants,
+  components,
+  incidents,
+  incidentUpdates,
+})

package/templates/apps/api-status/mutations/components.create.mutation.server.ts

@@ -0,0 +1,19 @@
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+
+const execute = (input: { name: string }, _ctx: AppContext) =>
+  Effect.gen(function* () {
+    const store = yield* EffectStore
+    const row = yield* store.insert('components', {
+      name:   input.name,
+      status: 'operational',
+    })
+    return {
+      id:     row['id'] as string,
+      name:   row['name'] as string,
+      status: row['status'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-status/mutations/components.create.mutation.ts

@@ -0,0 +1,16 @@
+// Add a monitored component — OPERATOR ONLY. Seed your components once
+// (API, Dashboard, Webhooks, …); the public page lists them with their status.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createComponent = defineMutation({
+  name:   'components.create',
+  target: { table: 'components', op: 'insert' },
+  guards: [{ scope: 'status:write' }],
+  input:  Schema.Struct({ name: Schema.NonEmptyString }),
+  output: Schema.Struct({
+    id:     Schema.String,
+    name:   Schema.String,
+    status: Schema.String,
+  }),
+})

package/templates/apps/api-status/mutations/incidents.create.mutation.server.ts

@@ -0,0 +1,25 @@
+// Authz-free here: by the time this runs the framework has already enforced the
+// `status:write` guard from the descriptor. A new incident opens in the
+// `investigating` state; `startedAt` is stamped by the column default.
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+
+const execute = (input: { title: string; impact: string }, _ctx: AppContext) =>
+  Effect.gen(function* () {
+    const store = yield* EffectStore
+    const row = yield* store.insert('incidents', {
+      title:      input.title,
+      impact:     input.impact,
+      status:     'investigating',
+      resolvedAt: null,
+    })
+    return {
+      id:     row['id'] as string,
+      title:  row['title'] as string,
+      impact: row['impact'] as string,
+      status: row['status'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-status/mutations/incidents.create.mutation.ts

@@ -0,0 +1,22 @@
+// Declare an incident — OPERATOR ONLY. The `guards: [{ scope: 'status:write' }]`
+// is enforced by the framework before the executor runs; `voltro check` sees it
+// statically. Declaring `guards:` merges `ScopeError` into the wire-error union
+// automatically (no `error:` needed).
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createIncident = defineMutation({
+  name:   'incidents.create',
+  target: { table: 'incidents', op: 'insert' },
+  guards: [{ scope: 'status:write' }],
+  input:  Schema.Struct({
+    title:  Schema.NonEmptyString,
+    impact: Schema.Literal('minor', 'major', 'critical'),
+  }),
+  output: Schema.Struct({
+    id:     Schema.String,
+    title:  Schema.String,
+    impact: Schema.String,
+    status: Schema.String,
+  }),
+})

package/templates/apps/api-status/mutations/incidents.resolve.mutation.server.ts

@@ -0,0 +1,24 @@
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+
+const execute = (input: { incidentId: string; body: string }, _ctx: AppContext) =>
+  Effect.gen(function* () {
+    const store = yield* EffectStore
+    const row = yield* store.update('incidents', input.incidentId, {
+      status:     'resolved',
+      resolvedAt: new Date(),
+    })
+    // A closing timeline entry (default body when the operator left it blank).
+    yield* store.insert('incident_updates', {
+      incidentId: input.incidentId,
+      body:       input.body === '' ? 'Resolved.' : input.body,
+      status:     'resolved',
+    })
+    return {
+      id:     input.incidentId,
+      status: (row?.['status'] as string | undefined) ?? 'resolved',
+    }
+  })
+
+export default execute

package/templates/apps/api-status/mutations/incidents.resolve.mutation.ts

@@ -0,0 +1,19 @@
+// Resolve an incident — OPERATOR ONLY. Sets `status: 'resolved'` + stamps
+// `resolvedAt`, and appends a final `resolved` timeline entry. The public page's
+// banner goes green and the incident archives into the history.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const resolveIncident = defineMutation({
+  name:   'incidents.resolve',
+  target: { table: 'incidents', op: 'update' },
+  guards: [{ scope: 'status:write' }],
+  input:  Schema.Struct({
+    incidentId: Schema.NonEmptyString,
+    body:       Schema.String,
+  }),
+  output: Schema.Struct({
+    id:     Schema.String,
+    status: Schema.String,
+  }),
+})

package/templates/apps/api-status/mutations/incidents.update.mutation.server.ts

@@ -0,0 +1,26 @@
+import { Effect } from 'effect'
+import type { AppContext } from '@voltro/runtime'
+import { EffectStore } from '@voltro/runtime'
+
+const execute = (
+  input: { incidentId: string; body: string; status: string },
+  _ctx: AppContext,
+) =>
+  Effect.gen(function* () {
+    const store = yield* EffectStore
+    // Advance the incident's own status so the banner reflects the latest note.
+    yield* store.update('incidents', input.incidentId, { status: input.status })
+    // Append the timeline entry.
+    const row = yield* store.insert('incident_updates', {
+      incidentId: input.incidentId,
+      body:       input.body,
+      status:     input.status,
+    })
+    return {
+      id:         row['id'] as string,
+      incidentId: row['incidentId'] as string,
+      status:     row['status'] as string,
+    }
+  })
+
+export default execute

package/templates/apps/api-status/mutations/incidents.update.mutation.ts

@@ -0,0 +1,21 @@
+// Post a timeline update to an open incident — OPERATOR ONLY. Writes an
+// `incident_updates` row AND advances the incident's own `status` so the public
+// banner + timeline move together.
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const updateIncident = defineMutation({
+  name:   'incidents.update',
+  target: { table: 'incident_updates', op: 'insert' },
+  guards: [{ scope: 'status:write' }],
+  input:  Schema.Struct({
+    incidentId: Schema.NonEmptyString,
+    body:       Schema.NonEmptyString,
+    status:     Schema.Literal('investigating', 'identified', 'monitoring'),
+  }),
+  output: Schema.Struct({
+    id:         Schema.String,
+    incidentId: Schema.String,
+    status:     Schema.String,
+  }),
+})

package/templates/apps/api-status/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-rbac": "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.29.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/api-status/queries/components.list.query.server.ts

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

package/templates/apps/api-status/queries/components.list.query.ts

@@ -0,0 +1,13 @@
+// Live list of service components + their current status. Public (no guard).
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const componentsList = defineQuery({
+  name: 'components.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:     Schema.String,
+    name:   Schema.String,
+    status: Schema.String,
+  }),
+})

package/templates/apps/api-status/queries/incidents.live.query.server.ts

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

package/templates/apps/api-status/queries/incidents.live.query.ts

@@ -0,0 +1,20 @@
+// The live incident feed — the heart of the status page. NO `guards:`, so an
+// anonymous visitor's browser can subscribe: `useSubscription('app',
+// 'incidents.live')`. Every insert/update to `incidents` lands as a delta, so a
+// newly-declared incident (or a resolve) shows up on every open status page
+// within seconds — no polling.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const incidentsLive = defineQuery({
+  name: 'incidents.live',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:         Schema.String,
+    title:      Schema.String,
+    impact:     Schema.String,
+    status:     Schema.String,
+    startedAt:  Schema.Date,
+    resolvedAt: Schema.NullOr(Schema.Date),
+  }),
+})

package/templates/apps/api-status/queries/updates.list.query.server.ts

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

package/templates/apps/api-status/queries/updates.list.query.ts

@@ -0,0 +1,17 @@
+// Live feed of incident timeline entries. Public (no guard). The page joins
+// these to incidents by `incidentId` client-side to render each incident's
+// update history.
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const updatesList = defineQuery({
+  name: 'updates.list',
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    id:         Schema.String,
+    incidentId: Schema.String,
+    body:       Schema.String,
+    status:     Schema.String,
+    createdAt:  Schema.Date,
+  }),
+})

package/templates/apps/api-status/template.json

@@ -0,0 +1,6 @@
+{
+  "id": "api-status",
+  "kind": "api",
+  "summary": "The backend for a public status page: ungated live queries (incidents.live, updates.list, components.list) any visitor can subscribe to, plus operator-only mutations (create/update/resolve incidents, manage components) gated by a @voltro/plugin-rbac `status:write` scope. Reads are public so an anonymous status page works; writes need an operator. Pairs with the frontend-status web template. Boots zero-infra.",
+  "tags": ["api", "status-page", "incidents", "rbac", "live", "useSubscription", "operator"]
+}

package/templates/apps/api-status/tests/status.test.ts

@@ -0,0 +1,70 @@
+// Authorization + descriptor tests, driven through the REAL rbac plugin.
+//
+// `makeTestContext({ plugins: [...] })` + `invoke` composes this app's actual
+// interceptor chain and enforces each descriptor's `guards:` with the same
+// `checkGuardsEffect` the serve pipeline calls — so we exercise the whole path
+// (tenant → role → compiled scope → guard), not a hand-stamped `subject.scopes`.
+// The asymmetry that defines a status page is the thing under test: reads are
+// public, writes are operator-only.
+//
+// Run with `voltro test` (vitest).
+
+import { describe, it, expect } from 'vitest'
+import { Schema } from 'effect'
+import { makeTestContext, mockStore, invoke } from '@voltro/testing'
+import { rbacPlugin } from '@voltro/plugin-rbac'
+import type { Subject } from '@voltro/protocol'
+
+import { roles, demoRolesForTenant } from '../authz'
+import { database } from '../database/schema' // registers incidents / components / updates / core
+import { createIncident } from '../mutations/incidents.create.mutation'
+import createIncidentHandler from '../mutations/incidents.create.mutation.server'
+import { incidentsLive } from '../queries/incidents.live.query'
+import incidentsLiveHandler from '../queries/incidents.live.query.server'
+
+/** The app's real plugin, built from the app's real role map. */
+const plugin = () => rbacPlugin({ roles, resolveRoles: (subject) => demoRolesForTenant(subject.tenantId) })
+
+const subjectFor = (tenantId: string | null, id: string | null = 'u_1', type = 'user'): Subject =>
+  ({ type, id, tenantId, scopes: [] }) as Subject
+
+const ctxFor = (subject: Subject) =>
+  makeTestContext({ subject, store: mockStore({ incidents: [], components: [], incident_updates: [] }), plugins: [plugin()] })
+
+describe('incidents.create — operator-gated', () => {
+  it('an operator (tenant `ops`) may declare an incident', async () => {
+    const ctx = ctxFor(subjectFor('ops'))
+    const inc = await invoke(createIncident, createIncidentHandler, { title: 'API degraded', impact: 'major' }, ctx)
+    expect(inc.title).toBe('API degraded')
+    expect(inc.status).toBe('investigating')
+  })
+
+  it('an anonymous visitor is refused with a typed ScopeError, and nothing is written', async () => {
+    const ctx = ctxFor(subjectFor(null, null, 'anonymous'))
+    await expect(invoke(createIncident, createIncidentHandler, { title: 'nope', impact: 'minor' }, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError', required: 'status:write' })
+    expect(await ctx.store.query(database.incidents.descriptor)).toHaveLength(0)
+  })
+
+  it('a signed-in NON-operator is also refused', async () => {
+    const ctx = ctxFor(subjectFor('marketing'))
+    await expect(invoke(createIncident, createIncidentHandler, { title: 'nope', impact: 'minor' }, ctx))
+      .rejects.toMatchObject({ _tag: 'ScopeError', required: 'status:write' })
+  })
+})
+
+describe('incidents.live — reads are PUBLIC', () => {
+  it('an anonymous visitor may subscribe (no guard on the query)', async () => {
+    const ctx = ctxFor(subjectFor(null, null, 'anonymous'))
+    await expect(invoke(incidentsLive, incidentsLiveHandler, {}, ctx)).resolves.toBeDefined()
+  })
+})
+
+describe('incidents.create — descriptor', () => {
+  it('accepts a valid impact and rejects an unknown one', () => {
+    const decode = Schema.decodeUnknownSync(createIncident.input)
+    expect(decode({ title: 'x', impact: 'critical' })).toEqual({ title: 'x', impact: 'critical' })
+    expect(() => decode({ title: 'x', impact: 'catastrophic' })).toThrow()
+    expect(() => decode({ title: '', impact: 'minor' })).toThrow()
+  })
+})

package/templates/apps/api-status/tsconfig.json

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

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

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

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

@@ -13,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.27.0",
-    "@voltro/database": "0.27.0",
-    "@voltro/env": "0.27.0",
-    "@voltro/plugin-multitenancy": "0.27.0",
-    "@voltro/plugin-webhooks": "0.27.0",
-    "@voltro/protocol": "0.27.0",
-    "@voltro/runtime": "0.27.0",
-    "@voltro/sql-postgres": "0.27.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/database": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/plugin-multitenancy": "0.29.0",
+    "@voltro/plugin-webhooks": "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.27.0",
+    "@voltro/testing": "0.29.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/changelog/package.json

@@ -12,12 +12,12 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/changelog": "0.27.0",
-    "@voltro/cli": "0.27.0",
-    "@voltro/client": "0.27.0",
-    "@voltro/env": "0.27.0",
-    "@voltro/i18n": "0.27.0",
-    "@voltro/web": "0.27.0",
+    "@voltro/changelog": "0.29.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/templates/apps/edge-functions/package.json

@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.27.0",
-    "@voltro/serverless": "0.27.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/serverless": "0.29.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {

package/templates/apps/frontend-admin/package.json

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.27.0",
-    "@voltro/cli": "0.27.0",
-    "@voltro/client": "0.27.0",
-    "@voltro/env": "0.27.0",
-    "@voltro/i18n": "0.27.0",
-    "@voltro/ui-shadcn": "0.27.0",
-    "@voltro/web": "0.27.0",
+    "@{{projectName}}/api": "0.29.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.27.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",

package/templates/apps/frontend-app/package.json

@@ -12,18 +12,18 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.27.0",
-    "@voltro/cli": "0.27.0",
-    "@voltro/client": "0.27.0",
-    "@voltro/env": "0.27.0",
-    "@voltro/i18n": "0.27.0",
-    "@voltro/ui-shadcn": "0.27.0",
-    "@voltro/web": "0.27.0",
+    "@{{projectName}}/api": "0.29.0",
+    "@voltro/cli": "0.29.0",
+    "@voltro/client": "0.29.0",
+    "@voltro/env": "0.29.0",
+    "@voltro/i18n": "0.29.0",
+    "@voltro/ui-shadcn": "0.29.0",
+    "@voltro/web": "0.29.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.27.0",
+    "@voltro/devtools": "0.29.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "typescript": "^6.0.3",