@askrjs/cli 0.0.2

package/templates/spa/README.md

@@ -0,0 +1,96 @@
+# {{appName}} - SPA Template
+
+A route-first Askr SPA built with `@askrjs/askr`, `@askrjs/ui`, `@askrjs/themes`, and `@askrjs/charts`.
+
+## Quick Start
+
+```bash
+npm install
+npm run dev      # Start dev server at http://localhost:5173
+npm run build    # Build for production
+npm run preview  # Preview production build
+npm test         # Run tests with Vitest
+```
+
+## Project Structure
+
+```
+src/
+|-- main.tsx                         # SPA boot and route manifest
+|-- pages/
+|   |-- _routes.tsx                  # Top-level route branches
+|   |-- _layout.tsx                  # Theme provider and app root
+|   |-- public/                      # Guest-facing landing pages and shell
+|   |-- auth/                        # Sign-in routes and shell
+|   `-- app/                         # Authenticated branch routes and shell
+|-- components/shared/               # App-local wrappers around theme primitives
+|-- features/operations/             # Product workflow queries and mutations
+|-- adapters/                        # API clients and transport adapters
+|-- shared/                          # Cross-cutting helpers and navigation data
+`-- styles/                          # reset.css, tokens.css, theme.css, layout.css, components.css
+```
+
+## Core Patterns
+
+Routes live in `src/pages`, shells live in `_layout.tsx`, reusable UI lives in
+`src/components/shared`, business workflows live in `src/features`, and adapter
+code lives in `src/adapters`.
+
+```tsx
+// src/pages/_routes.tsx
+import { fallback, group, registerRoutes } from '@askrjs/askr/router';
+import RootLayout from './_layout';
+import NotFoundPage from './not-found';
+import AuthLayout from './auth/_layout';
+import { registerAuthRoutes } from './auth/_routes';
+import AppLayout from './app/_layout';
+import { registerAppRoutes } from './app/_routes';
+import PublicLayout from './public/_layout';
+import { registerPublicRoutes } from './public/_routes';
+
+registerRoutes(() => {
+  group({ layout: RootLayout }, () => {
+    group({ layout: PublicLayout }, () => {
+      registerPublicRoutes();
+    });
+    group({ layout: AuthLayout }, () => {
+      registerAuthRoutes();
+    });
+    group({ layout: AppLayout }, () => {
+      registerAppRoutes();
+    });
+    fallback(NotFoundPage);
+  });
+});
+```
+
+The template uses the `@askrjs/themes/components` catalog for styled UI
+composition and keeps charts in `@askrjs/charts`. Add app-local components only
+when they compose those primitives into a product concept. Start with
+`src/styles/tokens.css` for theme knobs, then tune `theme.css`, `layout.css`,
+and `components.css`.
+
+Async reads are owned by route or container components with `resource()` and
+delegated through feature/adapters:
+
+```tsx
+const operations = resource(({ signal }) => loadOperations({ signal }), []);
+```
+
+Cancellation belongs in adapters, loading/error/value states stay visible in the
+route, and event-sourced consistency states should be modeled explicitly.
+
+## What This Template Includes
+
+- Public, auth, and authenticated app branches with separate layout shells
+- Theme provider, header/nav/sidebar, cards, badges, buttons, empty states, and layout primitives
+- A dashboard with async loading, charts, projection lag, and explicit refresh
+- Feature and adapter boundaries for data ownership
+- Tests that protect the route-first structure and cancellation behavior
+
+## Next Steps
+
+1. Replace the mock operations adapter with your generated API client.
+2. Tune `src/styles/tokens.css` and `src/styles/theme.css` to match your brand.
+3. Add route metadata for real auth and loader policies.
+4. Keep new screens route-first and compose solved UI through `@askrjs/themes`.

package/templates/spa/gitignore.template

@@ -0,0 +1,16 @@
+node_modules/
+dist/
+build/
+.env.local
+.env.*.local
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+*.swp
+*.swo
+*~

package/templates/spa/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{appName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/spa/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "clean": "npx rimraf node_modules dist",
+    "dev": "vp dev",
+    "build": "vp build",
+    "preview": "vp preview",
+    "test": "vp test run",
+    "typecheck": "tsc --noEmit",
+    "lint": "vp lint .",
+    "lint:fix": "npm run lint -- --fix",
+    "fmt": "vp fmt .",
+    "check": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@askrjs/askr": ">=0.0.53 <0.1.0",
+    "@askrjs/charts": ">=0.0.3 <0.1.0",
+    "@askrjs/logos": ">=0.0.3 <0.1.0",
+    "@askrjs/lucide": ">=0.0.3 <0.1.0",
+    "@askrjs/themes": ">=0.0.12 <0.1.0",
+    "@askrjs/ui": ">=0.0.13 <0.1.0"
+  },
+  "devDependencies": {
+    "@askrjs/vite": ">=0.0.6 <0.1.0",
+    "@types/node": "^26.0.0",
+    "jsdom": "^29.1.1",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.2.4"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}

package/templates/spa/src/adapters/operations-client.ts

@@ -0,0 +1,90 @@
+import type { RunStatus } from '../components/shared/status-badge';
+
+export type OperationRun = {
+  id: string;
+  title: string;
+  status: RunStatus;
+  owner: string;
+  updatedAt: string;
+};
+
+export type OperationsSnapshot = {
+  version: number;
+  consistency: 'fresh' | 'pending-write' | 'stale';
+  lastEventId: string;
+  metrics: Array<{ label: string; value: string; trend: string }>;
+  throughput: Array<{ label: string; value: number }>;
+  lag: Array<{ label: string; value: number }>;
+  runs: OperationRun[];
+};
+
+export async function getOperationsSnapshot({
+  signal,
+}: {
+  signal: AbortSignal;
+}): Promise<OperationsSnapshot> {
+  await delay(220, signal);
+
+  return {
+    version: 42,
+    consistency: 'fresh',
+    lastEventId: 'evt_18442',
+    metrics: [
+      { label: 'Active runs', value: '12', trend: '+3 today' },
+      { label: 'Pending approvals', value: '3', trend: '2 urgent' },
+      { label: 'Projection lag', value: '1.2s', trend: 'healthy' },
+    ],
+    throughput: [
+      { label: 'Research', value: 18 },
+      { label: 'Review', value: 11 },
+      { label: 'Deploy', value: 7 },
+      { label: 'Audit', value: 9 },
+    ],
+    lag: [
+      { label: '10:00', value: 4 },
+      { label: '10:10', value: 3 },
+      { label: '10:20', value: 2 },
+      { label: '10:30', value: 1 },
+      { label: '10:40', value: 2 },
+      { label: '10:50', value: 1 },
+    ],
+    runs: [
+      {
+        id: 'run_4812',
+        title: 'Summarize renewal risk',
+        status: 'running',
+        owner: 'Revenue ops',
+        updatedAt: '2026-05-22T09:52:00.000Z',
+      },
+      {
+        id: 'run_4811',
+        title: 'Approve workspace migration',
+        status: 'requires-action',
+        owner: 'Platform',
+        updatedAt: '2026-05-22T09:40:00.000Z',
+      },
+      {
+        id: 'run_4810',
+        title: 'Reconcile audit events',
+        status: 'succeeded',
+        owner: 'Security',
+        updatedAt: '2026-05-22T09:25:00.000Z',
+      },
+    ],
+  };
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timeout = globalThis.setTimeout(resolve, ms);
+
+    signal.addEventListener(
+      'abort',
+      () => {
+        globalThis.clearTimeout(timeout);
+        reject(new DOMException('Operation aborted', 'AbortError'));
+      },
+      { once: true }
+    );
+  });
+}

package/templates/spa/src/components/shared/metric-card.tsx

@@ -0,0 +1,27 @@
+import {
+  Card,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@askrjs/themes/components';
+import { Inline } from '@askrjs/themes/components';
+
+export type MetricCardProps = {
+  label: string;
+  value: string;
+  trend: string;
+};
+
+export default function MetricCard({ label, value, trend }: MetricCardProps) {
+  return (
+    <Card class="metric-card">
+      <CardHeader>
+        <Inline justify="between" align="center" gap="3">
+          <CardDescription>{label}</CardDescription>
+          <span class="metric-trend">{trend}</span>
+        </Inline>
+        <CardTitle>{value}</CardTitle>
+      </CardHeader>
+    </Card>
+  );
+}

package/templates/spa/src/components/shared/status-badge.tsx

@@ -0,0 +1,24 @@
+import { Badge } from '@askrjs/themes/components';
+
+export type RunStatus =
+  | 'queued'
+  | 'running'
+  | 'requires-action'
+  | 'succeeded'
+  | 'failed';
+
+export type StatusBadgeProps = {
+  status: RunStatus;
+};
+
+const labels: Record<RunStatus, string> = {
+  queued: 'queued',
+  running: 'running',
+  'requires-action': 'needs review',
+  succeeded: 'succeeded',
+  failed: 'failed',
+};
+
+export default function StatusBadge({ status }: StatusBadgeProps) {
+  return <Badge data-status={status}>{labels[status]}</Badge>;
+}

package/templates/spa/src/features/operations/operations.query.ts

@@ -0,0 +1,9 @@
+import { getOperationsSnapshot } from '../../adapters/operations-client';
+
+export function loadOperations({
+  signal = new AbortController().signal,
+}: {
+  signal?: AbortSignal;
+}) {
+  return getOperationsSnapshot({ signal });
+}

package/templates/spa/src/main.tsx

@@ -0,0 +1,10 @@
+import { createSPA } from '@askrjs/askr/boot';
+import { getManifest } from '@askrjs/askr/router';
+
+import './styles.css';
+import './pages/_routes';
+
+await createSPA({
+  root: document.getElementById('app')!,
+  manifest: getManifest(),
+});

package/templates/spa/src/pages/_layout.tsx

@@ -0,0 +1,9 @@
+import { ThemeScope } from '@askrjs/themes/theme';
+
+export default function RootLayout({ children }: { children?: unknown }) {
+  return (
+    <ThemeScope defaultTheme="tabby">
+      <div class="app-root">{children}</div>
+    </ThemeScope>
+  );
+}

package/templates/spa/src/pages/_routes.tsx

@@ -0,0 +1,27 @@
+import { fallback, group, registerRoutes } from '@askrjs/askr/router';
+import RootLayout from './_layout';
+import AuthLayout from './auth/_layout';
+import { registerAuthRoutes } from './auth/_routes';
+import { registerAppRoutes } from './app/_routes';
+import AppLayout from './app/_layout';
+import NotFoundPage from './not-found';
+import { registerPublicRoutes } from './public/_routes';
+import PublicLayout from './public/_layout';
+
+registerRoutes(() => {
+  group({ layout: RootLayout }, () => {
+    group({ layout: PublicLayout }, () => {
+      registerPublicRoutes();
+    });
+
+    group({ layout: AuthLayout }, () => {
+      registerAuthRoutes();
+    });
+
+    group({ layout: AppLayout }, () => {
+      registerAppRoutes();
+    });
+
+    fallback(NotFoundPage);
+  });
+});

package/templates/spa/src/pages/app/_layout.tsx

@@ -0,0 +1,94 @@
+import {
+  BotIcon,
+  HomeIcon,
+  LogOutIcon,
+  MoonIcon,
+  SettingsIcon,
+  SunIcon,
+} from '@askrjs/lucide';
+import { Link, navigate } from '@askrjs/askr/router';
+import { Button } from '@askrjs/themes/components';
+import { Container, Inline, Stack } from '@askrjs/themes/components';
+import { Header, Shell, ShellMain, ShellNav } from '@askrjs/themes/components';
+import {
+  NavBrand,
+  NavGroup,
+  NavLink,
+  Sidebar,
+} from '@askrjs/themes/components';
+import { Badge } from '@askrjs/themes/components';
+import { ThemeToggle } from '@askrjs/themes/theme';
+import { appNavItems } from '../../shared/navigation';
+
+const icons = {
+  home: <HomeIcon size={16} aria-hidden="true" />,
+  agents: <BotIcon size={16} aria-hidden="true" />,
+  settings: <SettingsIcon size={16} aria-hidden="true" />,
+};
+
+export default function AppLayout({ children }: { children?: unknown }) {
+  return (
+    <Shell variant="sidebar" class="app-shell">
+      <ShellNav>
+        <Sidebar
+          aria-label="Workspace navigation"
+          breakpoint="md"
+          collapsible="icon"
+        >
+          <NavBrand>
+            <Link href="/app" class="brand-link">
+              <span class="brand-mark">A</span>
+              <strong>{'{{appName}}'}</strong>
+            </Link>
+          </NavBrand>
+          <NavGroup label="Workspace">
+            {appNavItems.map((item) => (
+              <NavLink href={item.href} match={item.match}>
+                <Inline as="span" gap="2" align="center">
+                  {icons[item.icon]}
+                  <span>{item.label}</span>
+                </Inline>
+              </NavLink>
+            ))}
+          </NavGroup>
+          <NavGroup label="Session" align="end">
+            <NavLink href="/" match="exact">
+              <Inline as="span" gap="2" align="center">
+                <LogOutIcon size={16} aria-hidden="true" />
+                <span>Sign out</span>
+              </Inline>
+            </NavLink>
+          </NavGroup>
+        </Sidebar>
+      </ShellNav>
+      <ShellMain>
+        <Header position="sticky" class="app-header">
+          <Container size="full">
+            <Inline justify="between" align="center" gap="3" wrap="wrap">
+              <Stack gap="none">
+                <span class="eyebrow">Operations console</span>
+                <strong>Agent workflow control plane</strong>
+              </Stack>
+              <Inline gap="2" align="center" wrap="wrap">
+                <Badge>event stream healthy</Badge>
+                <ThemeToggle
+                  variant="ghost"
+                  size="icon"
+                  aria-label="Toggle color theme"
+                  lightIcon={<SunIcon size={18} aria-hidden="true" />}
+                  darkIcon={<MoonIcon size={18} aria-hidden="true" />}
+                />
+                <Button variant="secondary" onPress={() => navigate('/')}>
+                  Public site
+                </Button>
+              </Inline>
+            </Inline>
+          </Container>
+        </Header>
+        <Container size="full" class="app-main">
+          {children}
+        </Container>
+      </ShellMain>
+    </Shell>
+  );
+}

package/templates/spa/src/pages/app/_routes.tsx

@@ -0,0 +1,10 @@
+import { route } from '@askrjs/askr/router';
+import AgentRunsPage from './agent-runs';
+import AdminHomePage from './admin-home';
+import SettingsPage from './settings';
+
+export function registerAppRoutes(): void {
+  route('/app', AdminHomePage);
+  route('/app/agents', AgentRunsPage);
+  route('/app/settings', SettingsPage);
+}

package/templates/spa/src/pages/app/admin-home.tsx

@@ -0,0 +1,152 @@
+import { resource } from '@askrjs/askr/resources';
+import { BarChart, Sparkline } from '@askrjs/charts/components';
+import { AlertCircleIcon, RefreshCwIcon } from '@askrjs/lucide';
+import { Button } from '@askrjs/themes/components';
+import {
+  Alert,
+  Badge,
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  Skeleton,
+} from '@askrjs/themes/components';
+import { Block, Inline, Section, Stack } from '@askrjs/themes/components';
+import { EmptyState } from '@askrjs/themes/components';
+import MetricCard from '../../components/shared/metric-card';
+import StatusBadge from '../../components/shared/status-badge';
+import { loadOperations } from '../../features/operations/operations.query';
+import { formatRelativeTime } from '../../shared/format';
+
+export default function AdminHomePage() {
+  const operations = resource(({ signal }) => loadOperations({ signal }), []);
+  const snapshot = operations.value;
+
+  if (operations.error && !snapshot) {
+    return (
+      <Section>
+        <EmptyState
+          icon={<AlertCircleIcon size={24} aria-hidden="true" />}
+          title="Operations could not load"
+          description="The dashboard keeps failures recoverable. Retry the owning resource instead of hiding the error in a toast."
+          actions={<Button onPress={() => operations.refresh()}>Retry</Button>}
+        />
+      </Section>
+    );
+  }
+
+  return (
+    <Stack gap="5">
+      <section class="page-heading">
+        <Stack gap="2">
+          <Badge>projection v{snapshot?.version ?? '...'}</Badge>
+          <h1>Workspace home</h1>
+          <p class="lead">
+            A consistency-aware dashboard for agent runs, queue health, and
+            event-sourced read models.
+          </p>
+        </Stack>
+        <Inline gap="2" align="center">
+          {operations.pending && snapshot ? <Badge>refreshing</Badge> : null}
+          <Button variant="secondary" onPress={() => operations.refresh()}>
+            <RefreshCwIcon size={14} aria-hidden="true" /> Refresh
+          </Button>
+        </Inline>
+      </section>
+
+      {operations.pending && !snapshot ? (
+        <Block gap="md">
+          <Skeleton style="height: 8rem" />
+          <Skeleton style="height: 8rem" />
+          <Skeleton style="height: 8rem" />
+        </Block>
+      ) : null}
+
+      {snapshot ? (
+        <>
+          <Block gap="md" class="metric-grid">
+            {snapshot.metrics.map((metric) => (
+              <MetricCard
+                label={metric.label}
+                value={metric.value}
+                trend={metric.trend}
+              />
+            ))}
+          </Block>
+
+          <Block gap="md" align="stretch" class="chart-grid">
+            <Card>
+              <CardHeader>
+                <CardTitle>Run throughput</CardTitle>
+                <CardDescription>
+                  Accepted commands by work type.
+                </CardDescription>
+              </CardHeader>
+              <CardContent>
+                <BarChart label="Run throughput" data={snapshot.throughput} />
+              </CardContent>
+            </Card>
+            <Card>
+              <CardHeader>
+                <CardTitle>Projection lag</CardTitle>
+                <CardDescription>
+                  Lower is better; stale states stay visible.
+                </CardDescription>
+              </CardHeader>
+              <CardContent>
+                <Sparkline label="Projection lag" data={snapshot.lag} />
+              </CardContent>
+            </Card>
+          </Block>
+
+          {snapshot.consistency !== 'fresh' ? (
+            <Alert variant="warning">
+              Read models are {snapshot.consistency}. Last processed event is{' '}
+              {snapshot.lastEventId}.
+            </Alert>
+          ) : null}
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Recent agent runs</CardTitle>
+              <CardDescription>
+                Run state is modeled as product state, not a single loading
+                boolean.
+              </CardDescription>
+            </CardHeader>
+            <CardContent>
+              <div class="run-table-wrap">
+                <table class="run-table">
+                  <thead>
+                    <tr>
+                      <th>Run</th>
+                      <th>Status</th>
+                      <th>Owner</th>
+                      <th>Updated</th>
+                    </tr>
+                  </thead>
+                  <tbody>
+                    {snapshot.runs.map((run) => (
+                      <tr>
+                        <td>
+                          <strong>{run.title}</strong>
+                          <span>{run.id}</span>
+                        </td>
+                        <td>
+                          <StatusBadge status={run.status} />
+                        </td>
+                        <td>{run.owner}</td>
+                        <td>{formatRelativeTime(run.updatedAt)}</td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </CardContent>
+          </Card>
+        </>
+      ) : null}
+    </Stack>
+  );
+}