@askrjs/cli 0.0.2

package/dist/templates/full-stack/src/server/app.ts

@@ -0,0 +1,66 @@
+import { createAuth } from '@askrjs/auth';
+import { createServerApp } from '@askrjs/server';
+import { createAskrPageHandler } from '@askrjs/server/askr';
+import { csrf, rateLimit, requestId, securityHeaders } from '@askrjs/server/middleware';
+import { createApi } from '@askrjs/server/openapi';
+import { pageRegistry } from '../routes';
+import { Message, MessageInput } from '../schemas';
+import { telemetry } from '../telemetry';
+import { createActions } from './action-registry';
+import type { AppDependencies } from './dependencies';
+
+export function createApp(deps: AppDependencies) {
+  const api = createApi<AppDependencies>({
+    info: { title: '{{appName}} API', version: '1.0.0' },
+  });
+  api.post('/api/messages', {
+    input: {
+      body: {
+        schema: MessageInput,
+        mediaTypes: ['application/json'],
+      },
+    },
+    documentation: { body: { required: true } },
+    async handler(ctx, input, dependencies) {
+      const message = { id: crypto.randomUUID(), value: input.body.value };
+      await dependencies.actions.record({ action: 'api.create-message', value: message.value });
+      return ctx.created(message);
+    },
+  })
+    .operationId('createMessage')
+    .summary('Create a message')
+    .tags('Messages')
+    .use(
+      csrf({ secret: process.env.CSRF_SECRET ?? 'development-only-secret' }),
+      rateLimit({ store: deps.rateLimits, limit: 30, windowMs: 60_000 }),
+    )
+    .created(Message)
+    .badRequest()
+    .unprocessableEntity()
+    .tooManyRequests();
+
+  const router = api.createRouter(deps);
+  router.post('/api/session', (ctx) => {
+    const response = ctx.redirect('/', 303);
+    return ctx.setCookie(response, 'askr-session', 'demo-session', {
+      httpOnly: true,
+      sameSite: 'lax',
+      secure: ctx.url.protocol === 'https:',
+      path: '/',
+    });
+  });
+  return createServerApp({
+    router,
+    auth: createAuth({
+      sessions: deps.sessions,
+      principals: deps.principals,
+      sessionCookie: 'askr-session',
+    }),
+    middleware: [requestId(), securityHeaders()],
+    telemetry,
+    fallback: createAskrPageHandler({
+      registry: pageRegistry,
+      actions: createActions(deps),
+    }),
+  });
+}

package/dist/templates/full-stack/src/server/dependencies.ts

@@ -0,0 +1,55 @@
+export interface AppDependencies {
+  readonly sessions: {
+    get(id: string): Promise<{ id: string; subject: string } | null>;
+  };
+  readonly principals: {
+    get(subject: string): Promise<{
+      id: string;
+      subject: string;
+      permissions: readonly string[];
+    } | null>;
+  };
+  readonly actions: {
+    record(entry: { action: string; value: string }): Promise<void>;
+  };
+  readonly rateLimits: {
+    consume(key: string, limit: number, windowMs: number): Promise<{
+      allowed: boolean;
+      remaining: number;
+      reset: number;
+    }>;
+  };
+}
+
+export function createDependencies(): AppDependencies {
+  const counters = new Map<string, { count: number; reset: number }>();
+  return {
+    sessions: {
+      get: async (id) => id === 'demo-session'
+        ? { id, subject: 'demo-user' }
+        : null,
+    },
+    principals: {
+      get: async (subject) => subject === 'demo-user'
+        ? { id: subject, subject, permissions: ['messages:create'] }
+        : null,
+    },
+    actions: { record: async () => undefined },
+    rateLimits: {
+      async consume(key, limit, windowMs) {
+        const now = Date.now();
+        const current = counters.get(key);
+        const window = !current || current.reset <= now
+          ? { count: 0, reset: now + windowMs }
+          : current;
+        window.count += 1;
+        counters.set(key, window);
+        return {
+          allowed: window.count <= limit,
+          remaining: Math.max(0, limit - window.count),
+          reset: window.reset,
+        };
+      },
+    },
+  };
+}

package/dist/templates/full-stack/src/server/entry-server.ts

@@ -0,0 +1,8 @@
+import { createApp } from './app';
+import { createDependencies } from './dependencies';
+
+const app = createApp(createDependencies());
+
+export { app };
+export { telemetry } from '../telemetry';
+export default app;

package/dist/templates/full-stack/src/telemetry.ts

@@ -0,0 +1,4 @@
+import { createTelemetry } from '@askrjs/otel';
+
+export const telemetry = createTelemetry();
+

package/dist/templates/full-stack/src/vite-server.d.ts

@@ -0,0 +1,6 @@
+declare module 'virtual:askr-server' {
+  import type { ServerApp } from '@askrjs/server';
+  const app: ServerApp;
+  export default app;
+}
+

package/dist/templates/full-stack/tests/actions/create-message.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { createMessageAction } from '../../src/actions/create-message';
+
+describe('create message action', () => {
+  it('should reject an empty message given declared input validation', () => {
+    expect(createMessageAction.input.safeParse({ value: '' }).success).toBe(false);
+  });
+
+  it('should accept a message given valid input', () => {
+    expect(createMessageAction.input.safeParse({ value: 'hello' }).success).toBe(true);
+  });
+});
+

package/dist/templates/full-stack/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "jsx": "preserve",
+    "jsxImportSource": "@askrjs/askr",
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "tests", "server.ts", "vite.config.ts"]
+}
+

package/dist/templates/full-stack/vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'vite-plus';
+import { askr } from '@askrjs/vite';
+import { askrServer } from '@askrjs/vite/server';
+
+export default defineConfig({
+  plugins: [askr(), askrServer({ entry: './src/server/entry-server.ts' })],
+  lint: { ignorePatterns: ['dist/**', 'node_modules/**', 'coverage/**'] },
+  server: { port: 5173, open: true },
+  build: { manifest: true, sourcemap: true },
+});
+

package/dist/templates/spa/AGENTS.md

@@ -0,0 +1,60 @@
+# {{appName}}
+
+Client-side SPA built with Askr, askr-ui, askr-themes, and askr-charts.
+
+## Commands
+
+```bash
+npm run dev        # Vite dev server with HMR (port 5173)
+npm run build      # Production build to dist/
+npm run preview    # Serve production build locally
+npm test           # Vitest (jsdom)
+npm run typecheck  # tsc --noEmit
+npm run lint       # ESLint
+npm run fmt        # Prettier
+```
+
+## Architecture
+
+- **Routing:** `src/main.tsx` imports `src/pages/_routes.tsx`, then boots `createSPA()` with the route manifest. Route branches live under `src/pages/public`, `src/pages/auth`, and `src/pages/app`.
+- **Layouts:** `_layout.tsx` files own shells. The root layout owns `ThemeScope`; public layouts own landing chrome, auth layouts own sign-in chrome, and app layouts own authenticated sidebar chrome.
+- **UI:** Prefer the `@askrjs/themes/components` catalog before writing local components. Use app-local components only for product concepts such as `MetricCard` and `StatusBadge`; keep charts in `@askrjs/charts`.
+- **State:** `const [value, setValue] = state(initial)`. Read with `value()`, update with `setValue(...)`. Use `derive()` for computed values and `resource()` for async data.
+- **Data:** Route/container components own resources; `src/features` owns product workflows; `src/adapters` owns API clients, transports, abort handling, and generated clients.
+- **Consistency:** Event-sourced screens should expose pending writes, projection lag, stale data, retries, and manual refresh instead of hiding everything behind one loading state.
+- **Styling:** Keep `src/styles.css` thin. Customize theme values in `src/styles/tokens.css`, global defaults in `src/styles/theme.css`, shell structure in `src/styles/layout.css`, and component classes in `src/styles/components.css`.
+- **Charts:** Import chart components from `@askrjs/charts/components`; chart CSS is loaded from `@askrjs/charts/default`.
+- **Vite plugin:** `askr()` from `@askrjs/vite` handles JSX transform. Do not add manual esbuild JSX config.
+
+## File Structure
+
+```
+src/
+  main.tsx
+  pages/
+    _routes.tsx
+    _layout.tsx
+    public/
+    auth/
+    app/
+  components/shared/
+  features/
+  adapters/
+  shared/
+  styles/
+    reset.css
+    tokens.css
+    theme.css
+    layout.css
+    components.css
+tests/
+```
+
+## Conventions
+
+- Keep routes thin and route-first.
+- Keep shell chrome in layouts, not leaf pages.
+- Keep business logic out of `src/pages`.
+- Use `Link` and `navigate` from `@askrjs/askr/router`.
+- Use headless `@askrjs/ui/*` for behavior primitives and `@askrjs/themes/*` for composed visual surfaces.
+- Avoid hardcoded color systems, custom component catalogs, and React habits like effect-driven data loading.

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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);
+  });
+});