@askrjs/cli 0.0.2

package/dist/templates/spa/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite-plus';
+import { askr } from '@askrjs/vite';
+
+export default defineConfig({
+  plugins: [askr()],
+  esbuild: {
+    jsx: 'automatic',
+    jsxImportSource: '@askrjs/askr',
+  },
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+    },
+  },
+});

package/dist/templates/ssg/AGENTS.md

@@ -0,0 +1,55 @@
+# {{appName}}
+
+Static site built with Askr, askr-ui, askr-themes, and the Askr CLI.
+
+## Commands
+
+```bash
+npm run dev        # Vite dev server (runs as SPA for development)
+npm run build      # Build client assets and atomically publish dist/
+npm run generate   # Run full SSG through `askr ssg`
+npm run preview    # Serve production build locally
+npm test           # Vitest (jsdom)
+npm run typecheck  # tsc --noEmit
+npm run lint       # vite-plus lint
+npm run fmt        # vite-plus format
+```
+
+## Architecture
+
+- **Framework:** Askr - actor-backed, fine-grained reactive UI. No virtual DOM.
+- **Boot flow:** `src/main.tsx` starts the browser app with the shared `pageRegistry`.
+- **SSG flow:** `ssg.config.ts` passes that same registry to the complete executable SSG config. `askr ssg` owns full and incremental generation.
+- **Pages:** `src/pages/home.tsx`, `src/pages/about.tsx`, `src/pages/content.tsx`, and `src/pages/example.tsx` form the sample site.
+- **Shell:** `src/app.tsx` owns the nav and page frame.
+- **Theme primitives:** the starter composes `Header`, `Nav`, `NavLink`, `Container`, `Section`, `Stack`, `Box`, and `Block` from `@askrjs/themes` instead of hand-rolling shell/layout wrappers.
+- **Components:** askr-ui headless components. Props use `onPress` (not `onClick`) and `asChild` for polymorphism.
+- **Styling:** askr-themes CSS via public classes and `data-slot` selectors. Theme import lives in `src/styles.css`.
+- **Routing:** keep `pageRegistry` in `src/routes.tsx` as the single route source of truth for both dev and SSG.
+- **State:** `const [value, setValue] = state(initial)` and `derive()`. Keep starter routes synchronously prerenderable; if you add async data back, provide an SSR-safe strategy before expecting SSG to render it.
+- **Vite plugin:** `askr()` from `@askrjs/vite` handles JSX transform.
+
+## File Structure
+
+```
+ssg.config.ts          # Routes, document renderer, and static asset sources
+src/
+  main.tsx             # Client entry: registers routes and boots createSPA
+  app.tsx              # Root layout with nav
+  routes.tsx           # Shared route registration source of truth
+  styles.css           # Theme import + layout CSS
+  components/          # Reusable components
+  pages/               # Route page components
+tests/                 # Vitest tests
+```
+
+## Conventions
+
+- TypeScript strict mode, ESM-only
+- JSX import source: `@askrjs/askr`
+- Add new pages in `src/pages/`, then update `pageRegistry` in `src/routes.tsx`
+- Pass the shared registry through `ssg.config.ts` instead of maintaining a second hand-written route list
+- Keep SSG execution behind `askr ssg`; do not add a parallel project-local generator
+- Use askr-ui components for interactive elements and askr-themes layout/shell primitives for structure
+- Style with `--ak-*` tokens
+- Keep SSG routes synchronous at render time unless you intentionally wire SSR data into generation

package/dist/templates/ssg/README.md

@@ -0,0 +1,39 @@
+# {{appName}}
+
+Static site built with [Askr](https://github.com/askrjs/askr).
+
+## Development workflow
+
+The starter keeps the authoring loop small and explicit:
+
+1. Run `npm run dev` for the SPA-style editing experience.
+2. Edit the page components in `src/pages/`.
+3. Register routes in `src/routes.tsx`.
+4. Run `npm run build` to build client assets and atomically generate `dist/`.
+5. Run `npm run preview` to check the production build locally.
+
+## Sample pages
+
+- `/` introduces the starter and the basic developer loop.
+- `/workflow` explains the edit, generate, and preview loop.
+- `/content` shows the small explicit route map.
+- `/preview` keeps one interactive page so you can verify hydration.
+
+## Commands
+
+```bash
+npm run dev        # Start dev server (runs as SPA)
+npm run build      # Build assets and generate the complete static site
+npm run generate   # Regenerate static HTML with the Askr CLI
+npm run preview    # Preview production build
+npm test           # Run tests
+npm run lint       # Lint code
+npm run fmt        # Format code
+npm run typecheck  # Type check
+```
+
+## Static generation
+
+Run `npm run build` to compile browser assets and pre-render every route into `dist/`. The `askr ssg` command owns both full and incremental generation, and publishes routes, metadata, the incremental manifest, and browser assets together.
+
+`ssg.config.ts` passes the same immutable route registry used in dev mode, so the shell and leaf pages stay in sync.

package/dist/templates/ssg/gitignore.template

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+.askr/client/
+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/ssg/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/ssg/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vp dev",
+    "build": "npm run build:client && npm run generate",
+    "build:client": "vp build --outDir .askr/client",
+    "generate": "askr ssg --config ./ssg.config.ts --output ./dist",
+    "generate:incremental": "npm run generate -- --incremental",
+    "preview": "vp preview",
+    "test": "vp test run -c ./vitest.config.ts",
+    "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/themes": ">=0.0.12 <0.1.0",
+    "@askrjs/ui": ">=0.0.13 <0.1.0"
+  },
+  "devDependencies": {
+    "@askrjs/cli": ">=0.0.2 <0.1.0",
+    "@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/ssg/src/app.tsx

@@ -0,0 +1,14 @@
+import { PageFrame, SiteHeader } from './components/site-shell';
+
+export { navItems } from './components/site-shell';
+
+export default function App({ children }: { children?: unknown }) {
+  return (
+    <div class="site-shell">
+      <SiteHeader />
+      <main class="site-main">
+        <PageFrame>{children}</PageFrame>
+      </main>
+    </div>
+  );
+}

package/dist/templates/ssg/src/components/badge.tsx

@@ -0,0 +1,3 @@
+export default function Badge({ children }: { children?: unknown }) {
+  return <span class="badge">{children}</span>;
+}

package/dist/templates/ssg/src/components/counter.tsx

@@ -0,0 +1,30 @@
+import { state, derive } from '@askrjs/askr';
+import { Button } from '@askrjs/ui';
+import { Box, Stack } from '@askrjs/themes/components';
+import Badge from './badge';
+
+export default function Counter() {
+  const [count, setCount] = state(0);
+  const parity = derive(() => (count() % 2 === 0 ? 'even' : 'odd'));
+
+  return (
+    <Box class="card counter">
+      <Stack gap="3">
+        <h2>Hydration check</h2>
+        <p class="text-muted">
+          This counter should still feel live after static generation.
+        </p>
+        <div class="counter-value">{count()}</div>
+        <div>
+          <Badge>{parity()}</Badge>
+        </div>
+        <div class="counter-controls">
+          <Button onPress={() => setCount((c) => Math.max(0, c - 1))}>
+            - Decrement
+          </Button>
+          <Button onPress={() => setCount((c) => c + 1)}>+ Increment</Button>
+        </div>
+      </Stack>
+    </Box>
+  );
+}

package/dist/templates/ssg/src/components/site-shell.tsx

@@ -0,0 +1,111 @@
+import { Link } from '@askrjs/askr/router';
+import { Header } from '@askrjs/themes/components';
+import {
+  Block,
+  Box,
+  Container,
+  Section,
+  Stack,
+} from '@askrjs/themes/components';
+import { Nav, NavLink } from '@askrjs/themes/components';
+import Badge from './badge';
+
+export const navItems = [
+  { href: '/', label: 'Home' },
+  { href: '/workflow', label: 'Workflow' },
+  { href: '/content', label: 'Content' },
+  { href: '/preview', label: 'Preview' },
+] as const;
+
+export function SiteHeader() {
+  return (
+    <Header position="sticky">
+      <Container size="xl" paddingY="md">
+        <Box class="navbar-shell">
+          <Box class="navbar-brand">
+            <Link class="brand" href="/">
+              <strong>{'{{appName}}'}</strong>
+              <span>Static site generation sample</span>
+            </Link>
+          </Box>
+
+          <Nav
+            as="div"
+            aria-label="Primary navigation"
+            class="navbar-group"
+            data-align="end"
+          >
+            {navItems.map((item) => (
+              <NavLink href={item.href}>{item.label}</NavLink>
+            ))}
+          </Nav>
+        </Box>
+      </Container>
+    </Header>
+  );
+}
+
+export function PageFrame({ children }: { children?: unknown }) {
+  return (
+    <Container size="xl" paddingY="2xl">
+      <Stack gap="8">{children}</Stack>
+    </Container>
+  );
+}
+
+export function SectionHeader({
+  eyebrow,
+  title,
+  description,
+  actions,
+}: {
+  eyebrow: string;
+  title: string;
+  description: string;
+  actions?: unknown;
+}) {
+  return (
+    <Section class="section-header" paddingY="xl">
+      <Block gap="md">
+        <Stack gap="3" class="section-header-copy">
+          <Badge>{eyebrow}</Badge>
+          <h1>{title}</h1>
+          <p class="section-header-description">{description}</p>
+        </Stack>
+
+        {actions ?? null}
+      </Block>
+    </Section>
+  );
+}
+
+export function CardGrid({ children }: { children?: unknown }) {
+  return <Box class="card-grid">{children}</Box>;
+}
+
+export function Card({
+  eyebrow,
+  title,
+  description,
+  children,
+}: {
+  eyebrow?: string;
+  title: string;
+  description?: string;
+  children?: unknown;
+}) {
+  return (
+    <Box class="card">
+      <Stack gap="3">
+        {eyebrow ? <Badge>{eyebrow}</Badge> : null}
+        <h2>{title}</h2>
+        {description ? <p>{description}</p> : null}
+        {children}
+      </Stack>
+    </Box>
+  );
+}
+
+export function ActionRow({ children }: { children?: unknown }) {
+  return <Box class="action-row">{children}</Box>;
+}

package/dist/templates/ssg/src/jsx.d.ts

@@ -0,0 +1,23 @@
+import type { JSXElement } from '@askrjs/askr/foundations';
+
+declare global {
+  namespace JSX {
+    interface Element extends JSXElement {
+      readonly __askrSsgJsxElementBrand?: never;
+    }
+
+    interface IntrinsicElements {
+      [elem: string]: Record<string, unknown>;
+    }
+
+    interface ElementAttributesProperty {
+      props: Record<string, unknown>;
+    }
+
+    interface ElementChildrenAttribute {
+      children: unknown;
+    }
+  }
+}
+
+export {};

package/dist/templates/ssg/src/main.tsx

@@ -0,0 +1,8 @@
+import './styles.css';
+import { createSPA } from '@askrjs/askr/boot';
+import { pageRegistry } from './routes';
+
+await createSPA({
+  root: document.getElementById('app')!,
+  registry: pageRegistry,
+});

package/dist/templates/ssg/src/pages/about.tsx

@@ -0,0 +1,82 @@
+import { Link } from '@askrjs/askr/router';
+import { Button } from '@askrjs/ui';
+import {
+  ActionRow,
+  Card,
+  CardGrid,
+  SectionHeader,
+} from '../components/site-shell';
+
+const steps = [
+  {
+    number: '01',
+    title: 'Start the dev server',
+    command: 'npm run dev',
+    body: 'Vite runs the sample as a SPA while you edit, so page changes feel immediate.',
+  },
+  {
+    number: '02',
+    title: 'Edit a page',
+    command: 'src/pages/*.tsx',
+    body: 'Each page is a plain component. Keep view code, layout, and copy close together.',
+  },
+  {
+    number: '03',
+    title: 'Keep the route map explicit',
+    command: 'ssg.config.ts',
+    body: 'The static route list mirrors the pages the sample site actually ships.',
+  },
+  {
+    number: '04',
+    title: 'Generate and preview',
+    command: 'npm run generate && npm run preview',
+    body: 'Render the site to dist/static and verify the production output before you ship it.',
+  },
+];
+
+export default function Workflow() {
+  return (
+    <>
+      <SectionHeader
+        eyebrow="Workflow"
+        title="The authoring loop stays short."
+        description="This sample keeps the daily work obvious: edit a page, update the route map, generate static HTML, and preview the result."
+        actions={
+          <ActionRow>
+            <Button asChild>
+              <Link href="/content">See the route map</Link>
+            </Button>
+            <Button asChild>
+              <Link href="/preview">Open the preview</Link>
+            </Button>
+          </ActionRow>
+        }
+      />
+
+      <CardGrid>
+        {steps.map((step) => (
+          <Card
+            eyebrow={step.number}
+            title={step.title}
+            description={step.body}
+          >
+            <p>
+              <code>{step.command}</code>
+            </p>
+          </Card>
+        ))}
+      </CardGrid>
+
+      <Card
+        title="Why this feels good"
+        description="There is no hidden router magic. The generated site and the dev server read the same route definitions, so the UI you edit is the UI you ship."
+      >
+        <p>
+          <code>npm run dev</code>, <code>npm run generate</code>, and{' '}
+          <code>npm run preview</code> are the only commands you need to
+          remember.
+        </p>
+      </Card>
+    </>
+  );
+}

package/dist/templates/ssg/src/pages/content.tsx

@@ -0,0 +1,63 @@
+import { Link } from '@askrjs/askr/router';
+import { Button } from '@askrjs/ui';
+import {
+  ActionRow,
+  Card,
+  CardGrid,
+  SectionHeader,
+} from '../components/site-shell';
+
+const routeMap = [
+  {
+    path: '/',
+    title: 'Home',
+    note: 'Start here and link out to the rest of the sample.',
+  },
+  {
+    path: '/workflow',
+    title: 'Workflow',
+    note: 'Show the edit, generate, and preview loop.',
+  },
+  {
+    path: '/content',
+    title: 'Content',
+    note: 'Keep the route list visible and easy to extend.',
+  },
+  {
+    path: '/preview',
+    title: 'Preview',
+    note: 'Keep one interactive page to confirm hydration.',
+  },
+] as const;
+
+export default function Content() {
+  return (
+    <>
+      <SectionHeader
+        eyebrow="Content"
+        title="Four routes, one clear source of truth."
+        description="Keep the starter small and predictable. Add more routes when the app actually needs them."
+        actions={
+          <ActionRow>
+            <Button asChild>
+              <Link href="/workflow">Read the workflow</Link>
+            </Button>
+            <Button asChild>
+              <Link href="/preview">Open the preview</Link>
+            </Button>
+          </ActionRow>
+        }
+      />
+
+      <CardGrid>
+        {routeMap.map((route) => (
+          <Card
+            eyebrow={route.path}
+            title={route.title}
+            description={route.note}
+          />
+        ))}
+      </CardGrid>
+    </>
+  );
+}

package/dist/templates/ssg/src/pages/example.tsx

@@ -0,0 +1,97 @@
+import { state } from '@askrjs/askr';
+import { Link } from '@askrjs/askr/router';
+import { Button, Input } from '@askrjs/ui';
+import Counter from '../components/counter';
+import {
+  ActionRow,
+  Card,
+  CardGrid,
+  SectionHeader,
+} from '../components/site-shell';
+
+const sampleUsers: Record<
+  number,
+  { name: string; email: string; note: string }
+> = {
+  1: {
+    name: 'User 1',
+    email: 'user1@example.com',
+    note: 'Replace this with your own content or connect it to real data later.',
+  },
+  2: {
+    name: 'User 2',
+    email: 'user2@example.com',
+    note: 'This stays simple on purpose so the starter remains easy to delete or extend.',
+  },
+  3: {
+    name: 'User 3',
+    email: 'user3@example.com',
+    note: 'Interactive state still hydrates after static generation without adding async complexity.',
+  },
+};
+
+export default function Preview() {
+  const [userId, setUserId] = state(1);
+  const user = sampleUsers[userId()] ?? {
+    name: `User ${userId()}`,
+    email: `user${userId()}@example.com`,
+    note: 'Use this route as a safe place to try small interactive changes.',
+  };
+
+  return (
+    <>
+      <SectionHeader
+        eyebrow="Preview"
+        title="Interactive parts still work after static generation."
+        description="Keep one page interactive so you can verify hydration, state, and resource loading without turning the template into an app."
+        actions={
+          <ActionRow>
+            <Button asChild>
+              <Link href="/workflow">Read the workflow</Link>
+            </Button>
+            <Button asChild>
+              <Link href="/content">Review the routes</Link>
+            </Button>
+          </ActionRow>
+        }
+      />
+
+      <CardGrid>
+        <Counter />
+
+        <Card
+          eyebrow="Interactive state"
+          title="State still hydrates after generation"
+          description="Change the user id to prove the generated page still responds in the browser."
+        >
+          <div class="preview-controls">
+            <Input
+              type="number"
+              min="1"
+              step="1"
+              value={String(userId())}
+              onInput={(event: Event) => {
+                const nextValue = Number.parseInt(
+                  (event.target as HTMLInputElement).value,
+                  10
+                );
+
+                setUserId(Number.isNaN(nextValue) ? 1 : Math.max(1, nextValue));
+              }}
+            />
+          </div>
+
+          <div class="resource-panel">
+            <div class="resource-status">
+              <span class="badge">Ready</span>
+              <span>Hydrated preview</span>
+            </div>
+            <h3>{user.name}</h3>
+            <p>{user.email}</p>
+            <p class="text-muted">{user.note}</p>
+          </div>
+        </Card>
+      </CardGrid>
+    </>
+  );
+}

package/dist/templates/ssg/src/pages/home.tsx

@@ -0,0 +1,51 @@
+import { Link } from '@askrjs/askr/router';
+import { Button } from '@askrjs/ui';
+import {
+  ActionRow,
+  Card,
+  CardGrid,
+  SectionHeader,
+} from '../components/site-shell';
+
+const highlights = [
+  {
+    title: 'Fast feedback',
+    body: 'Run npm run dev and edit a page to stay in a SPA-style authoring loop.',
+  },
+  {
+    title: 'Deterministic output',
+    body: 'Keep one explicit route registry in src/routes.tsx so dev and generated output cannot drift.',
+  },
+  {
+    title: 'Hydrated preview',
+    body: 'Keep one interactive route so you can verify static output and browser behavior together.',
+  },
+];
+
+export default function Home() {
+  return (
+    <>
+      <SectionHeader
+        eyebrow="Static site generation"
+        title="Build a multi-page site, then ship it as plain HTML."
+        description="This sample keeps the loop small: author routes, preview in the SPA dev server, generate static files, and inspect the output."
+        actions={
+          <ActionRow>
+            <Button asChild>
+              <Link href="/workflow">See the workflow</Link>
+            </Button>
+            <Button asChild>
+              <Link href="/preview">Open the preview</Link>
+            </Button>
+          </ActionRow>
+        }
+      />
+
+      <CardGrid>
+        {highlights.map((highlight) => (
+          <Card title={highlight.title} description={highlight.body} />
+        ))}
+      </CardGrid>
+    </>
+  );
+}