@askrjs/cli 0.0.2

package/skills/askr-ui-composition/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: askr-ui-composition
+description: Use when composing Askr UI with @askrjs/ui headless primitives, accessibility behavior, asChild polymorphism, root-owned state, private component context, slots, keyboard behavior, overlays, and app-local components.
+---
+
+# Askr UI Composition
+
+Use this when the hard part is behavior and composition rather than theming. The goal is to reuse `@askrjs/ui` for focus, keyboard, dismissal, and ARIA behavior instead of rebuilding it locally.
+
+## Inspect First
+
+- Existing component imports and slot naming
+- The nearest shared component with similar behavior
+- Existing theme usage to decide whether headless or themed primitives fit better
+- Existing tests for keyboard or focus behavior
+
+## Use This When
+
+- You need dialog, popover, menu, select, toggle, checkbox, or other interactive behavior.
+- The app needs headless primitives or already owns its own CSS.
+- You are tempted to rebuild keyboard, focus, or dismissal logic locally.
+- Themed primitives are not enough because behavior composition is the real problem.
+
+## Choose UI Or Theme
+
+- Use `@askrjs/ui` directly when the app has its own CSS or needs a headless behavior primitive.
+- Use `@askrjs/themes` when the existing visual system should also style the primitive.
+- Do not create app-local wrappers for solved theme surfaces unless the wrapper adds product semantics.
+
+## Do This In Order
+
+1. Pick the primitive family that already owns the behavior.
+2. Keep coordination state in the root component that owns the interaction.
+3. Use `asChild` only when caller markup must be preserved.
+4. Use `data-slot` on app structure that needs stable styling hooks.
+5. Validate keyboard, pointer, and ARIA behavior.
+
+## Copy This Shape
+
+```tsx
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogOverlay,
+  AlertDialogPortal,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@askrjs/ui/alert-dialog";
+
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <button>Archive</button>
+  </AlertDialogTrigger>
+  <AlertDialogPortal>
+    <AlertDialogOverlay />
+    <AlertDialogContent>
+      <AlertDialogTitle>Archive account?</AlertDialogTitle>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Archive</AlertDialogAction>
+    </AlertDialogContent>
+  </AlertDialogPortal>
+</AlertDialog>;
+```
+
+## Never Do These
+
+- Reimplementing keyboard, focus, or dismissal behavior already owned by a primitive.
+- Styling or business logic inside behavior primitives.
+- Leaf components that fetch data or own routing.
+- Silent invalid composition when a part requires a root scope.
+- Prop bloat where composition would be clearer.
+
+## Validate
+
+- Keyboard and pointer behavior match the primitive contract.
+- ARIA labels, names, and roles are present where required.
+- `asChild` preserves expected markup and events.
+- User-facing interaction has jsdom or browser coverage.
+
+## Done When
+
+- The app reused the primitive that already owns the behavior.
+- Product composition stayed in the app, while behavior stayed in the primitive.
+- No local behavior clone was introduced.
+
+## Handoff
+
+- Use `askr-theming` when the next step is visual styling and shell coherence.
+- Use `askr-accessibility` when the next step is announcement, focus, or semantic review.
+- Use `askr-testing-determinism` before closing user-facing interaction changes.

package/skills/askr-ui-composition/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Askr UI Composition"
+  short_description: "Compose accessible headless UI"
+  default_prompt: "Use $askr-ui-composition to compose Askr UI primitives correctly."

package/templates/full-stack/AGENTS.md

@@ -0,0 +1,12 @@
+# {{appName}}
+
+This project is the progressive full-stack stage of an Askr application.
+
+- Prefer functions, closures, and structural interfaces over classes.
+- Keep action descriptors and schemas browser-safe under `src/actions` and `src/schemas.ts`.
+- Keep handlers, repositories, secrets, and composition dependencies under `src/server`.
+- Authorize every page action through the matched `route(..., { actions })` declaration.
+- Keep `index.html` as the only document source. Preserve exactly one `<!--askr-head-->` and one `<!--askr-app-->` marker.
+- Use native forms first; enhanced submission must preserve the same validation and authorization behavior.
+- Never log cookies, authorization values, tokens, form fields, request bodies, or personal data.
+

package/templates/full-stack/README.md

@@ -0,0 +1,18 @@
+# {{appName}}
+
+An Askr full-stack application with shared routes, executable schemas, declared actions, API routes, SSR hydration, i18n, telemetry seams, and Node/Vite production entrypoints.
+
+## Commands
+
+```bash
+npm install
+npm run dev
+npm run check
+npm run build
+npm run preview
+```
+
+Use `askr add action <name> --route <path>` to generate a browser-safe descriptor, server handler, composition-root registration, route authorization, and focused test.
+
+`index.html` owns the static document. `@askrjs/vite/server` injects only Askr-owned head nodes and composes the streamed app response at `<!--askr-app-->`.
+

package/templates/full-stack/gitignore.template

@@ -0,0 +1,4 @@
+node_modules
+dist
+coverage
+.env

package/templates/full-stack/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#111827" />
+    <!--askr-head-->
+  </head>
+  <body>
+    <div id="app"><!--askr-app--></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+

package/templates/full-stack/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build && vp build --ssr server.ts --outDir dist/server",
+    "preview": "node dist/server/server.js",
+    "test": "vp test run",
+    "typecheck": "tsc --noEmit",
+    "lint": "vp lint src server.ts tests vite.config.ts",
+    "fmt": "vp fmt .",
+    "check": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@askrjs/auth": ">=0.0.1 <0.1.0",
+    "@askrjs/askr": ">=0.0.53 <0.1.0",
+    "@askrjs/i18n": ">=0.0.1 <0.1.0",
+    "@askrjs/node": ">=0.0.1 <0.1.0",
+    "@askrjs/otel": ">=0.0.1 <0.1.0",
+    "@askrjs/schema": ">=0.0.1 <0.1.0",
+    "@askrjs/server": ">=0.0.1 <0.1.0",
+    "@askrjs/themes": ">=0.0.12 <0.1.0",
+    "@askrjs/ui": ">=0.0.13 <0.1.0",
+    "@opentelemetry/api": "^1.9.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",
+    "vitest": "^4.1.10"
+  },
+  "engines": { "node": "^20.19.0 || >=22.12.0" }
+}

package/templates/full-stack/server.ts

@@ -0,0 +1,13 @@
+import { listen } from '@askrjs/node';
+import app from 'virtual:askr-server';
+
+const port = Number(process.env.PORT ?? 3000);
+const server = await listen(app, {
+  host: process.env.HOST ?? '127.0.0.1',
+  port,
+});
+
+const shutdown = () => server.close();
+process.once('SIGINT', shutdown);
+process.once('SIGTERM', shutdown);
+

package/templates/full-stack/src/action-authorizations.ts

@@ -0,0 +1,10 @@
+import type { ActionDescriptor } from '@askrjs/askr/actions';
+import { createMessageAction } from './actions/create-message';
+
+const actionsByRoute: Readonly<Record<string, readonly ActionDescriptor[]>> = Object.freeze({
+  "/": [createMessageAction],
+});
+
+export function actionsFor(path: string): readonly ActionDescriptor[] {
+  return actionsByRoute[path] ?? [];
+}

package/templates/full-stack/src/actions/create-message.ts

@@ -0,0 +1,10 @@
+import { defineAction } from '@askrjs/askr/actions';
+import { MessageInput } from '../schemas';
+
+export const createMessageActionRoute = '/';
+
+export const createMessageAction = defineAction({
+  id: 'create-message',
+  input: MessageInput,
+  invalidates: ['messages'],
+});

package/templates/full-stack/src/i18n.ts

@@ -0,0 +1,8 @@
+import { createI18n } from '@askrjs/i18n';
+
+export const messages = createI18n('en', {
+  en: {
+    title: () => '{{appName}}',
+    intro: () => 'A progressive full-stack Askr application.',
+  },
+});

package/templates/full-stack/src/main.tsx

@@ -0,0 +1,12 @@
+import { createSPA, hydrateSPA } from '@askrjs/askr/boot';
+import { pageRegistry } from './routes';
+
+const root = document.getElementById('app');
+if (!root) throw new Error('Missing #app root element.');
+
+if (root.hasChildNodes()) {
+  await hydrateSPA({ root, registry: pageRegistry });
+} else {
+  await createSPA({ root, registry: pageRegistry });
+}
+

package/templates/full-stack/src/pages/home.tsx

@@ -0,0 +1,25 @@
+import { ActionForm } from '@askrjs/askr/actions';
+import { createMessageAction } from '../actions/create-message';
+import { messages } from '../i18n';
+
+export function HomePage() {
+  return (
+    <main>
+      <h1>{messages.text('title')}</h1>
+      <p>{messages.text('intro')}</p>
+      <form method="post" action="/api/session">
+        <button type="submit">Start demo session</button>
+      </form>
+      {ActionForm({
+        action: createMessageAction,
+        children: (
+          <>
+            <label htmlFor="message">Message</label>
+            <input id="message" name="value" required />
+            <button type="submit">Create message</button>
+          </>
+        ),
+      })}
+    </main>
+  );
+}

package/templates/full-stack/src/pages/layout.tsx

@@ -0,0 +1,33 @@
+import { Link } from '@askrjs/askr/router';
+import { Block, Container, Header, Navbar, NavBrand, NavGroup, NavLink } from '@askrjs/themes/components';
+import { ThemeScope, ThemeToggle } from '@askrjs/themes/theme';
+import { messages } from '../i18n';
+
+function ScopedLayout({ children }: { children?: unknown }) {
+  return (
+    <ThemeScope defaultTheme="light" storageKey="{{appName}}-theme">
+      <Block minHeight="screen">
+        <Header sticky>
+          <Container paddingY="sm">
+            <Navbar aria-label="Primary navigation" width="full">
+              <NavBrand><Link href="/">{messages.text('title')}</Link></NavBrand>
+              <NavGroup align="end">
+                <NavLink href="/">Home</NavLink>
+                <ThemeToggle aria-label="Toggle theme" />
+              </NavGroup>
+            </Navbar>
+          </Container>
+        </Header>
+        <Container paddingY="2xl">{children}</Container>
+      </Block>
+    </ThemeScope>
+  );
+}
+
+export function AppLayout({ children }: { children?: unknown }) {
+  return (
+    <messages.Scope locale="en" dir="ltr">
+      <ScopedLayout>{children}</ScopedLayout>
+    </messages.Scope>
+  );
+}

package/templates/full-stack/src/pages/not-found.tsx

@@ -0,0 +1,4 @@
+export function NotFoundPage() {
+  return <main><h1>Not found</h1></main>;
+}
+

package/templates/full-stack/src/routes.tsx

@@ -0,0 +1,20 @@
+import { createRouteRegistry, group, route } from '@askrjs/askr/router';
+import { actionsFor } from './action-authorizations';
+import { AppLayout } from './pages/layout';
+import { HomePage } from './pages/home';
+import { NotFoundPage } from './pages/not-found';
+
+export const pageRegistry = createRouteRegistry(() => {
+  group({ layout: AppLayout }, () => {
+    route('/', HomePage, {
+      actions: actionsFor('/'),
+      meta: {
+        title: '{{appName}}',
+        description: 'A progressive full-stack Askr application.',
+        html: { lang: 'en', dir: 'ltr' },
+      },
+    });
+    route('/*', NotFoundPage);
+  });
+});
+

package/templates/full-stack/src/schemas.ts

@@ -0,0 +1,11 @@
+import { schema } from '@askrjs/schema';
+
+export const MessageInput = schema.object({
+  value: schema.string({ minLength: 1, maxLength: 200 }),
+});
+
+export const Message = schema.object({
+  id: schema.string(),
+  value: schema.string(),
+});
+

package/templates/full-stack/src/server/action-registry.ts

@@ -0,0 +1,12 @@
+import { createActionRegistry } from '@askrjs/server/askr';
+import { createMessageAction } from '../actions/create-message';
+import { createMessage } from './actions/create-message';
+import type { AppDependencies } from './dependencies';
+
+export function createActions(deps: AppDependencies) {
+  const registry = createActionRegistry(deps, {
+    csrf: { secret: process.env.CSRF_SECRET ?? 'development-only-secret' },
+  });
+  registry.register(createMessageAction, createMessage);
+  return registry;
+}

package/templates/full-stack/src/server/actions/create-message.ts

@@ -0,0 +1,14 @@
+import type { InferSchema } from '@askrjs/schema';
+import { createMessageAction } from '../../actions/create-message';
+import type { AppDependencies } from '../dependencies';
+
+type Input = InferSchema<typeof createMessageAction.input>;
+
+export async function createMessage(
+  _context: unknown,
+  input: Input,
+  deps: Pick<AppDependencies, 'actions'>,
+) {
+  await deps.actions.record({ action: createMessageAction.id, value: input.value });
+  return { result: { accepted: true } };
+}

package/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/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/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/templates/full-stack/src/telemetry.ts

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

package/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/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/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/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/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.