@voltro/cli 0.28.0 → 0.30.0

package/templates/apps/api-search/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-multitenancy": "0.28.0",
-    "@voltro/plugin-search": "0.28.0",
-    "@voltro/protocol": "0.28.0",
-    "@voltro/runtime": "0.28.0",
+    "@voltro/cli": "0.30.0",
+    "@voltro/database": "0.30.0",
+    "@voltro/env": "0.30.0",
+    "@voltro/plugin-multitenancy": "0.30.0",
+    "@voltro/plugin-search": "0.30.0",
+    "@voltro/protocol": "0.30.0",
+    "@voltro/runtime": "0.30.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.28.0",
+    "@voltro/testing": "0.30.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-status/README.md

@@ -0,0 +1,88 @@
+# {{capProjectName}} {{capAppName}} — status-page backend
+
+The backend for a public **status page**: live queries anyone can subscribe to,
+plus operator-only mutations to declare and resolve incidents. Boots
+**zero-infra** (`store: 'memory'`). Pair it with the **frontend-status** web
+template:
+
+```bash
+voltro init my-status --api=api-status --web=frontend-status
+voltro dev
+```
+
+## The asymmetry it encodes
+
+A status page is read by everyone and written by a few — so:
+
+- **Reads are PUBLIC.** `incidents.live`, `updates.list`, `components.list`
+  carry **no guard**, so an anonymous browser can `useSubscription('app',
+  'incidents.live')` and the timeline updates live.
+- **Writes are OPERATOR-ONLY.** Every mutation declares
+  `guards: [{ scope: 'status:write' }]`, enforced by `@voltro/plugin-rbac` in the
+  dispatch spine before the executor. The demo resolver (`authz.ts`) grants the
+  `operator` role to the `ops` tenant; everyone else — anonymous included — is
+  denied.
+
+## Surface
+
+| Tag | Kind | Guard |
+|---|---|---|
+| `incidents.live` | query (stream) | — public |
+| `updates.list` | query (stream) | — public |
+| `components.list` | query (stream) | — public |
+| `incidents.create` | mutation | `status:write` |
+| `incidents.update` | mutation | `status:write` |
+| `incidents.resolve` | mutation | `status:write` |
+| `components.create` | mutation | `status:write` |
+
+## Try it (curl)
+
+```bash
+voltro dev .
+
+# A public read — no auth (anyone can watch)
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"incidents.live","input":{}}'
+
+# An operator write — needs the `ops` tenant (demo resolver → operator role)
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' -H 'x-tenant: ops' \
+  -d '{"tag":"incidents.create","input":{"title":"API degraded","impact":"major"}}'
+
+# The SAME write without the operator tenant → typed ScopeError
+curl -s -X POST http://localhost:4000/_voltro/inspect/invoke \
+  -H 'content-type: application/json' \
+  -d '{"tag":"incidents.create","input":{"title":"nope","impact":"minor"}}'
+# → { "ok": false, "error": { "_tag": "ScopeError", "required": "status:write" } }
+```
+
+## Files
+
+```
+app.config.ts             rbacPlugin (roles + demo resolver)
+authz.ts                  the role→scope map (status:write) — one source of truth
+database/schema.ts        components / incidents / incident_updates (PUBLIC, not tenant-scoped)
+queries/                  incidents.live / updates.list / components.list — ungated streams
+mutations/                incidents.create|update|resolve, components.create — status:write
+tests/                    the public-read / operator-write asymmetry + descriptor pins
+```
+
+## Going to production
+
+- **Real operator auth.** Replace the demo `resolveRoles` with subject metadata
+  or a DB lookup, and pair this api with `api-auth` / `api-saas-starter` so
+  operators actually sign in. The rbac gate is already in place — you only swap
+  where the roles come from.
+- **Durable store.** `store: 'postgres'` (or `sqlite`) so incident history
+  survives a restart.
+- **Notify subscribers** on open/resolve with `@voltro/plugin-mail` (opt-in).
+
+## Anti-patterns
+
+- **Tenant-scoping the public tables.** Adding `tenant()` to `incidents` would
+  make an anonymous visitor (no tenant) see nothing. Public reads stay
+  unscoped; the rbac guard on the writes is the boundary.
+- **A write-only authz model.** These reads are intentionally ungated because
+  they're public — but if you ever gate a read, gate it with `guards:` on the
+  query (enforced on open AND every delivery), not a check inside the handler.

package/templates/apps/api-status/app.config.ts

@@ -0,0 +1,36 @@
+// Backend for the {{projectName}} public status page. Read by `voltro dev`.
+//
+// The shape of a status page is asymmetric, and this config encodes it:
+//   • READS are PUBLIC — `incidents.live` / `updates.list` / `components.list`
+//     carry NO guard, so an anonymous visitor's browser can subscribe and see
+//     the live timeline. (A status page that requires a login is useless during
+//     an outage.)
+//   • WRITES are OPERATOR-ONLY — every mutation declares a `status:write` guard.
+//     `rbacPlugin` resolves each caller's ROLES to SCOPES and the framework
+//     enforces the guard in the dispatch spine, before the executor. `voltro
+//     check` can see the guard statically.
+//
+// The role map lives in `authz.ts`. Config-only — no external infra.
+import { defineEnv, envVar } from '@voltro/env'
+import { rbacPlugin } from '@voltro/plugin-rbac'
+import { demoRolesForTenant, roles } from './authz'
+
+export const env = defineEnv({
+  LOG_LEVEL: envVar.enum(['debug', 'info', 'warn', 'error'], { access: 'public', default: 'info' }),
+})
+
+export default {
+  type:  'api' as const,
+  name:  '{{capProjectName}}{{capAppName}}',
+  store: 'memory' as const,
+  plugins: [
+    rbacPlugin({
+      roles,
+      // Demo: `ops` tenant → operator. Swap for a real resolver (subject
+      // metadata / a DB lookup) when you wire operator auth — pair this api
+      // with the api-auth / api-saas-starter auth backend.
+      resolveRoles: (subject) => demoRolesForTenant(subject.tenantId),
+    }),
+  ],
+  env,
+}

package/templates/apps/api-status/authz.ts

@@ -0,0 +1,33 @@
+// The status page's authorization vocabulary, in ONE place — split out of
+// app.config.ts so the tests build the real plugin from the real role map (a
+// test that redeclares the roles only proves its own copy is self-consistent).
+//
+// A status page has exactly two kinds of caller: the PUBLIC (anonymous
+// visitors, who only READ — the live queries carry no guard) and OPERATORS
+// (who post incidents). So there is one write scope, `status:write`, held by
+// the `operator` role; `admin` gets the wildcard bypass.
+//
+// This map is ALSO the app's declared scope vocabulary: `rbacPlugin` publishes
+// its union, and `voltro check` errors on any descriptor guard requiring a
+// scope that appears nowhere here — so a guard and its grant can't silently
+// drift out of sync.
+export const roles = {
+  operator: ['status:write'],
+  admin:    ['*'],
+}
+
+/**
+ * DEMO role resolver — grants `operator` to callers in the `ops` tenant so
+ * every operator flow is reachable with an `x-tenant: ops` header and zero auth
+ * setup. Everyone else (including anonymous visitors) gets NO role, so the
+ * ungated read queries still work but every `status:write` mutation is denied.
+ *
+ * PRODUCTION reads the caller's REAL roles: the default resolver reads
+ * `subject.metadata.roles` (set by your auth strategy — pair this with the
+ * api-auth / api-saas-starter auth wiring), or do a DB lookup here. If this
+ * throws, rbac degrades to the subject's own scopes — it never grants on
+ * failure.
+ */
+export const demoRolesForTenant = (
+  tenantId: string | null | undefined,
+): ReadonlyArray<string> => (tenantId === 'ops' ? ['operator'] : [])

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.30.0",
+    "@voltro/database": "0.30.0",
+    "@voltro/env": "0.30.0",
+    "@voltro/plugin-rbac": "0.30.0",
+    "@voltro/protocol": "0.30.0",
+    "@voltro/runtime": "0.30.0",
+    "@voltro/sql-postgres": "0.30.0",
+    "effect": "^3.22.0"
+  },
+  "devDependencies": {
+    "@voltro/testing": "0.30.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"]
+}