@voltro/cli 0.28.0 → 0.29.0

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

@@ -0,0 +1,51 @@
+# {{capProjectName}} {{capAppName}} — public status page
+
+A public status page, and a clean **live-`useSubscription`** showcase. Consumes
+the `api-status` backend. Bilingual (en/de), no auth.
+
+Scaffold both halves together:
+
+```bash
+voltro init my-status --api=api-status --web=frontend-status
+voltro dev
+```
+
+## What it does
+
+- **SSR first paint.** The index loader pulls the current incidents, components
+  and updates over the api's `/rpc` before the HTML is sent, so the page is
+  correct + crawlable on first load (no client round-trip).
+- **Live upgrade.** The component then subscribes with `useSubscription('app',
+  'incidents.live' | 'components.list' | 'updates.list')`, so when an operator
+  declares or resolves an incident on the api, the banner, uptime grid and
+  timeline update on every open page within seconds — no polling.
+- **Derived state.** The overall banner and the 90-day uptime grid are computed
+  from incident timestamps (`src/lib/status.ts`), not external monitoring — the
+  operator controls the narrative. That math is pure and unit-tested.
+
+## No auth by design
+
+The api leaves the read queries ungated, and this page carries no session gate —
+a status page must stay up when the product (and its login) is down. Operators
+post incidents against the api's operator-gated mutations from a separate
+authenticated surface.
+
+## Files
+
+```
+src/pages/
+  layout.tsx      header (brand + language) + stylesheet
+  page.tsx        the status page — SSR loader + 3 live subscriptions
+  page.test.tsx   loader + render + the pure status math
+src/lib/status.ts deriveOverall() + uptimeGrid() + uptimePercent() (pure, tested)
+src/locales/{en,de}.ts  bilingual catalogs
+```
+
+## Anti-patterns
+
+- **Polling for updates.** The whole point is the live subscription — don't add
+  a `setInterval`; `useSubscription` pushes deltas.
+- **Gating the reads.** These must work for anonymous visitors. Keep the api's
+  read queries ungated; the rbac guard belongs on the write mutations.
+- **A secret in this app's env.** The browser bundle is public — secrets live on
+  the api.

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

@@ -0,0 +1,39 @@
+// Web app for the {{projectName}} project — a PUBLIC status page fed by the
+// sibling `api-status` api.
+//
+// The index page is `renderMode: 'ssr'`: its loader runs server-side per request
+// and pulls the current incidents + components over the api's POST /rpc, so the
+// first paint + the document <title> reflect real state (crawlable, no client
+// round-trip). The component then upgrades to live with `useSubscription`, so a
+// new incident lands on every open page within seconds — the whole point of a
+// status page.
+//
+// No auth: the reads are public (the api leaves them ungated), and the page must
+// stay up even when the rest of the product — and its login — is down.
+import { defineEnv, envVar } from '@voltro/env'
+
+// Public, build-time env (baked into the bundle; read via `publicEnv`).
+// Never a secret here — declare secrets on the api.
+export const env = defineEnv({
+  VOLTRO_PUBLIC_APP_NAME: envVar.string({ access: 'public', default: '{{capProjectName}}' }),
+})
+
+export default {
+  type: 'web' as const,
+  name: '{{capProjectName}}{{capAppName}}',
+  port: {{port}},
+  theme: 'system' as const,
+  env,
+  // Bilingual by default (cookie-driven — no `/<locale>` prefix). The framework
+  // auto-wires <I18nProvider> from these codes + the `src/locales/<code>.ts`
+  // catalogs, so `<T>` / `useT()` / `useLocale()` work app-wide (SSR too). Add a
+  // code + a `src/locales/<code>.ts` to grow to more languages.
+  locales:       ['en', 'de'] as const,
+  defaultLocale: 'en'         as const,
+  // The api this page reads. The NAME ('app') is the lookup key the loader's
+  // `query` + the hooks use: `query('incidents.live', {})`,
+  // `useSubscription('app', 'incidents.live')`.
+  apis: {
+    app: { package: '@{{projectName}}/api' },
+  },
+}

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

@@ -0,0 +1,32 @@
+{
+  "name": "@{{projectName}}/{{appName}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "voltro dev .",
+    "lint": "voltro doctor .",
+    "build": "voltro build .",
+    "start": "voltro start .",
+    "typecheck": "tsc --noEmit",
+    "test": "voltro test"
+  },
+  "dependencies": {
+    "@{{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.29.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  }
+}

package/templates/apps/frontend-status/src/config.ts

@@ -0,0 +1,7 @@
+// The brand name shown in the status-page header.
+//
+// A plain constant — not `publicEnv` — so the template typechecks BEFORE
+// `voltro dev` generates the env types. `VOLTRO_PUBLIC_APP_NAME` is still
+// declared in app.config.ts; to read it typed instead, after one `voltro dev`
+// swap this for `publicEnv.VOLTRO_PUBLIC_APP_NAME` from '@voltro/env/public'.
+export const APP_NAME = '{{capProjectName}}'

package/templates/apps/frontend-status/src/globals.css

@@ -0,0 +1,70 @@
+/* Plain CSS — no Tailwind, so there's no @source scanner to configure. */
+:root {
+  --bg: #ffffff;
+  --fg: #0a0a0a;
+  --muted: #6b7280;
+  --border: #e5e7eb;
+  --panel: #f9fafb;
+  --up: #16a34a;
+  --down: #dc2626;
+  --warn: #d97706;
+}
+:root.dark {
+  --bg: #0a0a0a;
+  --fg: #fafafa;
+  --muted: #9ca3af;
+  --border: #1f2937;
+  --panel: #111827;
+  --up: #22c55e;
+  --down: #f87171;
+  --warn: #f59e0b;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, sans-serif;
+  line-height: 1.55;
+}
+.muted { color: var(--muted); }
+.spacer { flex: 1; }
+.shell { max-width: 46rem; margin: 0 auto; padding: 1.5rem 1.25rem 4rem; }
+.shell header { display: flex; align-items: center; gap: 1rem; margin-bottom: 1.5rem; }
+.brand { font-weight: 700; }
+h2 { font-size: 1rem; margin: 2rem 0 0.75rem; }
+
+/* Overall banner */
+.banner { display: flex; align-items: center; gap: 0.6rem; padding: 1rem 1.25rem; border-radius: 12px; border: 1px solid var(--border); }
+.banner .dot { width: 0.7rem; height: 0.7rem; border-radius: 999px; background: var(--muted); }
+.banner--operational  { background: color-mix(in oklab, var(--up) 12%, transparent); border-color: var(--up); }
+.banner--operational .dot { background: var(--up); }
+.banner--degraded     { background: color-mix(in oklab, var(--warn) 12%, transparent); border-color: var(--warn); }
+.banner--degraded .dot { background: var(--warn); }
+.banner--major_outage { background: color-mix(in oklab, var(--down) 12%, transparent); border-color: var(--down); }
+.banner--major_outage .dot { background: var(--down); }
+
+/* Uptime grid */
+.uptime { display: flex; gap: 2px; flex-wrap: wrap; }
+.uptime .day { width: 6px; height: 26px; border-radius: 2px; background: var(--up); }
+.uptime .day.down { background: var(--down); }
+
+/* Components */
+.components, .incidents, .timeline { list-style: none; padding: 0; margin: 0; }
+.components li { display: flex; justify-content: space-between; align-items: center; padding: 0.6rem 0; border-bottom: 1px solid var(--border); }
+.pill { font-size: 0.78rem; border: 1px solid var(--border); border-radius: 999px; padding: 0.05rem 0.55rem; color: var(--muted); }
+.pill--operational { color: var(--up); border-color: var(--up); }
+.pill--degraded, .pill--partial_outage { color: var(--warn); border-color: var(--warn); }
+.pill--major_outage { color: var(--down); border-color: var(--down); }
+
+/* Incidents */
+.incidents { display: flex; flex-direction: column; gap: 0.75rem; }
+.incident { border: 1px solid var(--border); border-left-width: 3px; border-radius: 10px; padding: 0.9rem 1.1rem; background: var(--panel); }
+.incident.impact--critical { border-left-color: var(--down); }
+.incident.impact--major { border-left-color: var(--warn); }
+.incident.impact--minor { border-left-color: var(--muted); }
+.incident-head { display: flex; align-items: center; gap: 0.5rem; flex-wrap: wrap; }
+.timeline { margin-top: 0.6rem; display: flex; flex-direction: column; gap: 0.35rem; border-top: 1px dashed var(--border); padding-top: 0.6rem; }
+.timeline li { display: flex; align-items: baseline; gap: 0.5rem; font-size: 0.9rem; }
+.timeline .ts { color: var(--muted); font-variant-numeric: tabular-nums; white-space: nowrap; }

package/templates/apps/frontend-status/src/globals.d.ts

@@ -0,0 +1,6 @@
+// Ambient declarations.
+//
+// `declare module '*.css'`: TypeScript with `moduleResolution: Bundler`
+// rejects a bare `import './globals.css'` unless the asset module is
+// declared. Vite resolves it at build time; the declaration is type-only.
+declare module '*.css'

package/templates/apps/frontend-status/src/lib/status.ts

@@ -0,0 +1,81 @@
+// Pure status math — no React, no api. Kept here so it's unit-testable on its
+// own (see page.test.tsx) and reused by the page's banner + uptime grid.
+
+export interface Incident {
+  readonly id: string
+  readonly title: string
+  readonly impact: string   // 'minor' | 'major' | 'critical'
+  readonly status: string   // 'investigating' | 'identified' | 'monitoring' | 'resolved'
+  readonly startedAt: string | Date
+  readonly resolvedAt: string | Date | null
+}
+
+export interface Component {
+  readonly id: string
+  readonly name: string
+  readonly status: string   // 'operational' | 'degraded' | 'partial_outage' | 'major_outage'
+}
+
+export interface Update {
+  readonly id: string
+  readonly incidentId: string
+  readonly body: string
+  readonly status: string
+  readonly createdAt: string | Date
+}
+
+export type Overall = 'operational' | 'degraded' | 'major_outage'
+
+const isOpen = (i: Incident): boolean => i.status !== 'resolved'
+
+// The banner state, from current incidents + component statuses. A live critical
+// incident (or a component in major_outage) is the worst; any other open
+// incident or non-operational component is a partial degradation.
+export const deriveOverall = (
+  incidents: ReadonlyArray<Incident>,
+  components: ReadonlyArray<Component>,
+): Overall => {
+  const open = incidents.filter(isOpen)
+  const worstOpen = open.some((i) => i.impact === 'critical')
+  const worstComponent = components.some((c) => c.status === 'major_outage')
+  if (worstOpen || worstComponent) return 'major_outage'
+  if (open.length > 0 || components.some((c) => c.status !== 'operational')) return 'degraded'
+  return 'operational'
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const ms = (v: string | Date): number => (v instanceof Date ? v.getTime() : Date.parse(v))
+
+/**
+ * A 90-day uptime grid (oldest → newest). A day counts as "down" when a
+ * major-or-critical incident overlapped it — derived from incident timestamps,
+ * NOT external monitoring, so operators control the narrative. `now` is a seam
+ * for deterministic tests.
+ */
+export const uptimeGrid = (
+  incidents: ReadonlyArray<Incident>,
+  now: number = Date.now(),
+  days = 90,
+): ReadonlyArray<boolean> => {
+  const impactful = incidents.filter((i) => i.impact === 'major' || i.impact === 'critical')
+  const todayStart = Math.floor(now / DAY_MS) * DAY_MS
+  const grid: boolean[] = []
+  for (let d = days - 1; d >= 0; d--) {
+    const dayStart = todayStart - d * DAY_MS
+    const dayEnd = dayStart + DAY_MS
+    const down = impactful.some((i) => {
+      const start = ms(i.startedAt)
+      const end = i.resolvedAt == null ? now : ms(i.resolvedAt)
+      return start < dayEnd && end >= dayStart
+    })
+    grid.push(!down)
+  }
+  return grid
+}
+
+// Uptime percentage over the grid window, to one decimal.
+export const uptimePercent = (grid: ReadonlyArray<boolean>): number => {
+  if (grid.length === 0) return 100
+  const up = grid.filter(Boolean).length
+  return Math.round((up / grid.length) * 1000) / 10
+}

package/templates/apps/frontend-status/src/locales/de.ts

@@ -0,0 +1,41 @@
+// German catalog. Mirrors every key in `en.ts` — `defineLocale<typeof en>()`
+// fails the build on a missing/misspelled key. Translate prose only; keep ICU
+// placeholders (`{days}`, `{percent}`, `{when}`) identical to en.ts.
+import { defineLocale } from '@voltro/i18n'
+import en from './en'
+
+export default defineLocale<typeof en>()({
+  'meta.title':       'Status',
+  'meta.description': 'Live-Servicestatus, Verfügbarkeit und Störungsverlauf.',
+
+  'lang.label':   'Sprache',
+  'header.status': 'Status',
+
+  'overall.operational':  'Alle Systeme betriebsbereit',
+  'overall.degraded':     'Einige Systeme beeinträchtigt',
+  'overall.major_outage': 'Schwerwiegende Störung',
+
+  'uptime.heading': 'Verfügbarkeit über {days} Tage',
+  'uptime.percent': '{percent}% Verfügbarkeit',
+
+  'components.heading':          'Komponenten',
+  'components.empty':            'Noch keine Komponenten konfiguriert.',
+  'comp.status.operational':     'Betriebsbereit',
+  'comp.status.degraded':        'Beeinträchtigt',
+  'comp.status.partial_outage':  'Teilausfall',
+  'comp.status.major_outage':    'Schwerer Ausfall',
+
+  'incidents.heading':  'Störungen',
+  'incidents.none':     'Keine Störungen gemeldet.',
+  'incident.started':   'Begonnen {when}',
+  'incident.ongoing':   'Andauernd',
+  'incident.resolved':  'Behoben {when}',
+
+  'impact.minor':          'Gering',
+  'impact.major':          'Erheblich',
+  'impact.critical':       'Kritisch',
+  'status.investigating':  'Wird untersucht',
+  'status.identified':     'Identifiziert',
+  'status.monitoring':     'Wird beobachtet',
+  'status.resolved':       'Behoben',
+})

package/templates/apps/frontend-status/src/locales/en.ts

@@ -0,0 +1,45 @@
+// Base catalog — source of truth. Every key MUST be mirrored in `de.ts`
+// (`defineLocale<typeof en>()` enforces parity at build time). ICU `{token}`
+// placeholders are substituted via `<T values={{ … }} />`.
+import { defineCatalog } from '@voltro/i18n'
+
+export default defineCatalog({
+  'meta.title':       'Status',
+  'meta.description': 'Live service status, uptime and incident history.',
+
+  'lang.label':   'Language',
+  'header.status': 'Status',
+
+  // Overall banner
+  'overall.operational':  'All systems operational',
+  'overall.degraded':     'Some systems degraded',
+  'overall.major_outage': 'Major outage',
+
+  // Uptime
+  'uptime.heading': '{days}-day uptime',
+  'uptime.percent': '{percent}% uptime',
+
+  // Components
+  'components.heading':          'Components',
+  'components.empty':            'No components configured yet.',
+  'comp.status.operational':     'Operational',
+  'comp.status.degraded':        'Degraded',
+  'comp.status.partial_outage':  'Partial outage',
+  'comp.status.major_outage':    'Major outage',
+
+  // Incidents
+  'incidents.heading':  'Incidents',
+  'incidents.none':     'No incidents reported.',
+  'incident.started':   'Started {when}',
+  'incident.ongoing':   'Ongoing',
+  'incident.resolved':  'Resolved {when}',
+
+  // Impact + lifecycle labels
+  'impact.minor':          'Minor',
+  'impact.major':          'Major',
+  'impact.critical':       'Critical',
+  'status.investigating':  'Investigating',
+  'status.identified':     'Identified',
+  'status.monitoring':     'Monitoring',
+  'status.resolved':       'Resolved',
+} as const)

package/templates/apps/frontend-status/src/locales/index.ts

@@ -0,0 +1,13 @@
+// Catalog lookup OUTSIDE React — for the page's `meta({ locale })` locale-aware
+// <title>. Cookie-i18n (no URL prefix), so @voltro/web hands `meta` the active
+// locale from the `voltro:lang` cookie. Inside React use `<T>` / `useT()`.
+import en from './en'
+import de from './de'
+
+// Both catalogs share `en`'s keys (defineLocale enforces the mirror), so a
+// known-key lookup returns `string` — what `PageMeta.title` requires under
+// exactOptionalPropertyTypes.
+export type Messages = Record<keyof typeof en, string>
+
+export const getCatalog = (locale?: string): Messages =>
+  (locale === 'de' ? de : en) as Messages

package/templates/apps/frontend-status/src/pages/layout.tsx

@@ -0,0 +1,27 @@
+// Root layout — the status-page header (brand + language) and the stylesheet.
+// Don't render <html>/<head>/<body> here — the framework shell owns them.
+import type { ReactNode } from 'react'
+import { T, useLocale, useT } from '@voltro/i18n'
+import { LocaleSwitcher } from '@voltro/ui-shadcn'
+import { APP_NAME } from '../config'
+import '../globals.css'
+
+const LOCALES = [
+  { code: 'en', label: 'English' },
+  { code: 'de', label: 'Deutsch' },
+]
+
+export default function Layout({ children }: { readonly children: ReactNode }): ReactNode {
+  const locale = useLocale()
+  const langLabel = useT('lang.label')
+  return (
+    <div className="shell">
+      <header>
+        <span className="brand">{APP_NAME} <span className="muted"><T id="header.status" /></span></span>
+        <span className="spacer" />
+        <LocaleSwitcher locales={LOCALES} current={locale} ariaLabel={langLabel} />
+      </header>
+      {children}
+    </div>
+  )
+}

package/templates/apps/frontend-status/src/pages/page.test.tsx

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+//
+// The status page. We mock `@voltro/web` (the loader hook) + `@voltro/client`
+// (the three subscriptions, keyed by tag) and assert: the loader drains the api,
+// the SSR snapshot renders the banner/components/incidents, live subscription
+// data overrides the snapshot, and the pure status math (banner + uptime) is
+// correct on its own.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import { act, createElement, type ReactNode } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { I18nProvider } from '@voltro/i18n'
+import enCatalog from '../locales/en'
+import { deriveOverall, uptimeGrid, uptimePercent, type Incident } from '../lib/status'
+
+const loaderData = vi.fn<() => unknown>()
+const subs = new Map<string, unknown>()
+vi.mock('@voltro/web', () => ({ useLoaderData: () => loaderData() }))
+vi.mock('@voltro/client', () => ({ useSubscription: (_api: string, tag: string) => ({ data: subs.get(tag) }) }))
+
+const { default: StatusPage, meta, loader, renderMode } = await import('./page')
+
+;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+const render = (node: ReactNode): void => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  act(() => {
+    root = createRoot(container)
+    root.render(
+      createElement(I18nProvider, { locale: 'en', messages: enCatalog, defaultLocale: 'en', children: node }),
+    )
+  })
+}
+
+const emptyData = { incidents: [], components: [], updates: [] }
+
+beforeEach(() => {
+  loaderData.mockReset()
+  loaderData.mockReturnValue(emptyData)
+  subs.clear()
+})
+
+afterEach(() => {
+  if (root) act(() => root.unmount())
+  container?.remove()
+  document.body.innerHTML = ''
+})
+
+describe('status page — config + loader', () => {
+  test('is an SSR page titled Status', () => {
+    expect(renderMode).toBe('ssr')
+    expect(meta({ locale: 'en' }).title).toBe('Status')
+  })
+
+  test('the loader drains all three feeds from the api', async () => {
+    const query = vi.fn(async (tag: string) =>
+      tag === 'incidents.live'  ? [{ id: 'inc_1' }]
+      : tag === 'components.list' ? [{ id: 'cmp_1' }]
+      : [{ id: 'iu_1' }])
+    const data = await loader({ query } as never)
+    expect(query).toHaveBeenCalledWith('incidents.live', {})
+    expect(data.incidents).toHaveLength(1)
+    expect(data.components).toHaveLength(1)
+    expect(data.updates).toHaveLength(1)
+  })
+
+  test('returns empty feeds on a client navigation (no server query fn)', async () => {
+    const data = await loader({ query: undefined } as never)
+    expect(data).toEqual(emptyData)
+  })
+})
+
+describe('status page — render', () => {
+  test('shows the all-operational banner with no incidents', () => {
+    render(createElement(StatusPage))
+    expect(container.querySelector('.banner--operational')).not.toBeNull()
+    expect(container.textContent).toContain('All systems operational')
+  })
+
+  test('renders a live incident over the (empty) SSR snapshot', () => {
+    subs.set('incidents.live', [
+      { id: 'inc_9', title: 'API degraded', impact: 'major', status: 'investigating', startedAt: '2026-08-01T00:00:00Z', resolvedAt: null },
+    ])
+    subs.set('updates.list', [
+      { id: 'iu_1', incidentId: 'inc_9', body: 'Looking into it', status: 'investigating', createdAt: '2026-08-01T00:05:00Z' },
+    ])
+    render(createElement(StatusPage))
+    expect(container.querySelector('.banner--degraded')).not.toBeNull()
+    expect(container.textContent).toContain('API degraded')
+    expect(container.querySelector('.timeline')).not.toBeNull()
+    expect(container.textContent).toContain('Looking into it')
+  })
+})
+
+describe('status math (pure)', () => {
+  const inc = (over: Partial<Incident>): Incident => ({
+    id: 'i', title: 't', impact: 'minor', status: 'investigating',
+    startedAt: '2026-08-01T00:00:00Z', resolvedAt: null, ...over,
+  })
+
+  test('deriveOverall escalates with impact and clears when resolved', () => {
+    expect(deriveOverall([], [])).toBe('operational')
+    expect(deriveOverall([inc({ impact: 'major' })], [])).toBe('degraded')
+    expect(deriveOverall([inc({ impact: 'critical' })], [])).toBe('major_outage')
+    expect(deriveOverall([inc({ impact: 'critical', status: 'resolved', resolvedAt: '2026-08-02T00:00:00Z' })], [])).toBe('operational')
+    expect(deriveOverall([], [{ id: 'c', name: 'API', status: 'major_outage' }])).toBe('major_outage')
+  })
+
+  test('uptimeGrid marks a day down only for a major/critical incident overlapping it', () => {
+    const now = Date.parse('2026-08-10T12:00:00Z')
+    const minorOnly = uptimeGrid([inc({ impact: 'minor', startedAt: '2026-08-09T00:00:00Z', resolvedAt: '2026-08-09T06:00:00Z' })], now, 90)
+    expect(minorOnly.every(Boolean)).toBe(true)          // minor never dings uptime
+    expect(uptimePercent(minorOnly)).toBe(100)
+
+    const majorDay = uptimeGrid([inc({ impact: 'critical', startedAt: '2026-08-09T00:00:00Z', resolvedAt: '2026-08-09T06:00:00Z' })], now, 90)
+    expect(majorDay.filter((up) => !up)).toHaveLength(1)  // exactly one down day
+    expect(uptimePercent(majorDay)).toBeLessThan(100)
+  })
+})