@askrjs/cli 0.0.2

package/dist/templates/startkit/README.md

@@ -0,0 +1,192 @@
+# {{appName}} starter kit
+
+A production-ready Askr starter built to feel like a real product from day one.
+
+It ships with opinionated defaults for routing boundaries, layout composition,
+state handling, and interface polish so you can focus on product behavior instead
+of project plumbing.
+
+Stack:
+
+- `@askrjs/askr`
+- `@askrjs/auth`
+- `@askrjs/ui`
+- `@askrjs/themes` (default)
+- Lucide icons via `@askrjs/lucide`
+- plain CSS with layers and design tokens
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+Then run quality checks before your first commit:
+
+```bash
+npm run check
+npm run fmt:check
+```
+
+## Command reference
+
+```bash
+npm run dev         # Local dev server with HMR
+npm run build       # Production build
+npm run preview     # Preview production build
+npm run typecheck   # TypeScript checks
+npm run lint        # ESLint across project files
+npm test            # Vitest suite
+npm run fmt         # Format full project with Prettier
+npm run fmt:check   # Verify formatting
+npm run check       # lint + typecheck + tests + production build
+```
+
+## Routes and layout model
+
+Routes are registered in src/router.tsx and split into explicit groups:
+
+- Public routes: / (landing)
+- Auth routes: /login (centered auth layout)
+- Protected routes: /dashboard, /accounts, /settings (app shell layout)
+- Fallback route: /\* (not found)
+
+The root app wrapper in `src/pages/_layout.tsx` owns cross-cutting UI such as toast.
+
+## Project structure
+
+```text
+src/
+  main.tsx
+  router.tsx
+
+  routes/
+    index.ts
+    auth.ts
+    auth-config.ts
+    public.ts
+    workspace/
+      index.ts
+      accounts.ts
+
+  pages/
+    _layout.tsx
+    home.tsx
+    not-found.tsx
+    auth/
+      _layout.tsx
+      login.tsx
+    workspace/
+      _layout.tsx
+      dashboard.tsx
+      settings.tsx
+      accounts/
+        index.tsx
+
+  components/
+    app-sidebar.tsx
+    app-header.tsx
+    stat-card.tsx
+    data-table.tsx
+    empty-state.tsx
+    page-header.tsx
+
+  features/
+    accounts/
+      account-table.tsx
+      account-filters.tsx
+
+  lib/
+    mock-data.ts
+    format.ts
+    routes.ts
+
+  styles.css
+  styles/
+    reset.css
+    tokens.css
+    theme.css
+    layout.css
+    components.css
+```
+
+## How routing works
+
+`src/router.tsx` creates one registry with `createRouteRegistry()`. The files in
+`src/routes` compose its `group()` and `route()` declarations:
+
+- A shared root wrapper for providers
+- Auth layout only for /login
+- App layout only for protected routes
+- Function-based auth requirements redirect unauthenticated users from protected routes to /login
+
+This keeps route ownership clear and avoids one mega-layout for every page type.
+
+## How layouts work
+
+- App layout (`src/pages/workspace/_layout.tsx`): sidebar + sticky header + content area.
+- Auth layout (`src/pages/auth/_layout.tsx`): minimal centered shell for forms.
+
+Use app layout for authenticated product surfaces and auth layout for onboarding/login flows.
+
+## How to add a page
+
+1. Create a new page file in the matching branch under `src/pages`.
+2. Register it in the matching file under `src/routes`.
+3. Place the route in the correct layout group (public, auth, protected).
+4. If protected, use the existing function requirements such as `requireUser()`,
+   `requireRole()`, or `requirePermission()` at the narrowest owning route or group.
+
+## First-hour customization checklist
+
+1. Update brand name, colors, and typography tokens in src/styles/tokens.css.
+2. Replace mock user/session data in src/lib/mock-data.ts.
+3. Swap dashboard/account samples for domain-specific features.
+4. Wire login and route auth logic to your real auth provider.
+5. Replace placeholders in landing and settings copy with product language.
+6. Add one end-to-end happy-path test for your primary workflow.
+
+## How to add a component
+
+1. Put shared UI in `src/components`.
+2. Put domain-specific pieces in `src/features/<feature-name>`.
+3. Keep component APIs prop-driven and small.
+4. Prefer composing `@askrjs/ui` and `@askrjs/themes/components` before inventing new abstractions.
+
+## Styling organization
+
+The CSS architecture is intentionally layered:
+
+- reset.css: baseline resets
+- tokens.css: design tokens (colors, spacing, type scale, radius)
+- theme.css: global typography and high-level theme values
+- layout.css: page/shell structure and responsive behavior
+- components.css: component and slot-level styling
+
+Guidelines:
+
+- Use token variables for spacing and colors.
+- Keep a calm neutral palette and one accent color.
+- Prefer subtle borders over heavy shadows.
+- Keep radius and motion restrained.
+
+## UX patterns included
+
+- Loading states (skeletons)
+- Empty states
+- Error states
+- Disabled actions
+- Form validation examples
+- Toast example
+- Modal example
+
+## Notes
+
+Data is intentionally mock-only and deterministic.
+
+When integrating backend services:
+
+1. Keep API calls and data transforms in src/lib.
+2. Preserve AbortController signal forwarding in async operations.
+3. Keep route guards and layout boundaries explicit in src/router.tsx.

package/dist/templates/startkit/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/startkit/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/startkit/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{appName}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build",
+    "preview": "vp preview",
+    "test": "vp test run",
+    "test:watch": "vp test --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "vp lint .",
+    "lint:fix": "npm run lint -- --fix",
+    "fmt": "vp fmt .",
+    "fmt:check": "vp fmt --check .",
+    "check": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "@askrjs/askr": ">=0.0.53 <0.1.0",
+    "@askrjs/auth": ">=0.0.1 <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/startkit/src/components/app-header.tsx

@@ -0,0 +1,93 @@
+import { currentRoute, Link } from '@askrjs/askr/router';
+import { Input } from '@askrjs/ui/input';
+import {
+  Avatar,
+  AvatarFallback,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+  Inline,
+} from '@askrjs/themes/components';
+import { SearchIcon } from '@askrjs/lucide';
+import { buildLoginHref, getRouteLabel, settingsRoute } from '../lib/routes';
+import { showToast } from '../toast';
+import { signOut } from '../lib/mock-data';
+
+export default function AppHeader() {
+  const breadcrumb = () => getRouteLabel(currentRoute().path);
+
+  return (
+    <header class="app-header">
+      <Inline
+        align="center"
+        justify="between"
+        gap="var(--ak-space-lg)"
+        wrap="wrap"
+      >
+        <div class="breadcrumbs">
+          <span>App</span>
+          <span aria-hidden="true">/</span>
+          <strong>{breadcrumb()}</strong>
+        </div>
+
+        <label class="header-search" aria-label="Search">
+          <SearchIcon size={15} aria-hidden="true" />
+          <Input placeholder="Search docs, accounts, settings..." disabled />
+        </label>
+
+        <DropdownMenu>
+          <DropdownMenuTrigger class="header-account-trigger">
+            <Avatar>
+              <AvatarFallback>AM</AvatarFallback>
+            </Avatar>
+            <span class="header-account-name">Alex Morgan</span>
+          </DropdownMenuTrigger>
+          <DropdownMenuPortal>
+            <DropdownMenuContent side="bottom" align="end" sideOffset={8}>
+              <DropdownMenuLabel>Workspace</DropdownMenuLabel>
+              <DropdownMenuGroup>
+                <DropdownMenuItem asChild>
+                  <Link href={settingsRoute.href}>Profile settings</Link>
+                </DropdownMenuItem>
+                <DropdownMenuItem
+                  onSelect={() =>
+                    showToast({
+                      title: 'Notifications enabled',
+                      description:
+                        'Connect this action to your notification center.',
+                    })
+                  }
+                >
+                  Notifications
+                </DropdownMenuItem>
+              </DropdownMenuGroup>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem
+                onSelect={() => {
+                  const nextTarget =
+                    typeof window === 'undefined'
+                      ? undefined
+                      : `${window.location.pathname}${window.location.search}${window.location.hash}`;
+                  signOut();
+                  showToast({
+                    title: 'Signed out',
+                    description:
+                      'Session state is now cleared from local storage.',
+                  });
+                  window.location.assign(buildLoginHref(nextTarget));
+                }}
+              >
+                Sign out
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenuPortal>
+        </DropdownMenu>
+      </Inline>
+    </header>
+  );
+}

package/dist/templates/startkit/src/components/app-sidebar.tsx

@@ -0,0 +1,95 @@
+import { Link } from '@askrjs/askr/router';
+import {
+  LayoutDashboardIcon,
+  UsersIcon,
+  SettingsIcon,
+  LayersIcon,
+  ShieldCheckIcon,
+} from '@askrjs/lucide';
+import type { IconProps } from '@askrjs/lucide';
+import type { JSXElement } from '@askrjs/askr/foundations';
+import { NavBrand, NavGroup, NavLink, Navbar } from '@askrjs/themes/components';
+import {
+  accountsRoute,
+  dashboardRoute,
+  landingRoute,
+  loginRoute,
+  settingsRoute,
+} from '../lib/routes';
+
+type NavItem = {
+  href: string;
+  label: string;
+  icon: (props: IconProps) => JSXElement;
+};
+
+const primaryNav: NavItem[] = [
+  {
+    href: dashboardRoute.href,
+    label: dashboardRoute.navLabel,
+    icon: LayoutDashboardIcon,
+  },
+  {
+    href: accountsRoute.href,
+    label: accountsRoute.navLabel,
+    icon: UsersIcon,
+  },
+  {
+    href: settingsRoute.href,
+    label: settingsRoute.navLabel,
+    icon: SettingsIcon,
+  },
+];
+
+const secondaryNav: NavItem[] = [
+  { href: landingRoute.href, label: 'Marketing site', icon: LayersIcon },
+  { href: loginRoute.href, label: 'Auth entry', icon: ShieldCheckIcon },
+];
+
+export default function AppSidebar() {
+  return (
+    <aside class="app-sidebar" aria-label="Sidebar navigation">
+      <Navbar
+        orientation="vertical"
+        class="app-sidebar-nav"
+        aria-label="Sidebar navigation"
+      >
+        <NavBrand>
+          <Link href={dashboardRoute.href} class="sidebar-brand">
+            <span class="brand-pill" aria-hidden="true">
+              A
+            </span>
+            <div>
+              <p class="sidebar-title">{'{{appName}}'}</p>
+              <p class="sidebar-subtitle">Starter Kit</p>
+            </div>
+          </Link>
+        </NavBrand>
+
+        <NavGroup id="workspace-nav-group" label="Workspace">
+          {primaryNav.map((item) => {
+            const Icon = item.icon;
+            return (
+              <NavLink href={item.href}>
+                <Icon size={16} aria-hidden={true} />
+                <span>{item.label}</span>
+              </NavLink>
+            );
+          })}
+        </NavGroup>
+
+        <NavGroup id="other-nav-group" label="Other" placement="bottom">
+          {secondaryNav.map((item) => {
+            const Icon = item.icon;
+            return (
+              <NavLink href={item.href}>
+                <Icon size={16} aria-hidden={true} />
+                <span>{item.label}</span>
+              </NavLink>
+            );
+          })}
+        </NavGroup>
+      </Navbar>
+    </aside>
+  );
+}

package/dist/templates/startkit/src/components/data-table.tsx

@@ -0,0 +1,80 @@
+import { For } from '@askrjs/askr/control';
+import { Skeleton } from '@askrjs/themes/components';
+import EmptyState from './empty-state';
+import { joinClasses } from '../utils/join-classes';
+
+export type DataTableColumn<Row> = {
+  key: string;
+  header: unknown;
+  class?: string;
+  render: (row: Row) => unknown;
+};
+
+export default function DataTable<Row>(props: {
+  rows: () => Row[];
+  rowKey: (row: Row) => string;
+  columns: DataTableColumn<Row>[];
+  class?: string;
+  tableClass?: string;
+  rowClass?: (row: Row) => string | undefined;
+  isLoading?: boolean;
+  errorText?: string | null;
+  emptyTitle?: string;
+  emptyDescription?: string;
+}) {
+  if (props.errorText) {
+    return (
+      <EmptyState title="Could not load table" description={props.errorText} />
+    );
+  }
+
+  if (props.isLoading) {
+    return (
+      <div
+        class={joinClasses('panel stack-sm', props.class)}
+        aria-hidden="true"
+      >
+        <Skeleton class="skeleton-line" />
+        <Skeleton class="skeleton-line" />
+        <Skeleton class="skeleton-line" />
+      </div>
+    );
+  }
+
+  if (props.rows().length === 0) {
+    return (
+      <EmptyState
+        title={props.emptyTitle ?? 'No rows found'}
+        description={
+          props.emptyDescription ??
+          'Try changing filters or adding new records.'
+        }
+      />
+    );
+  }
+
+  return (
+    <div class={joinClasses('table-wrap', props.class)}>
+      <table class={props.tableClass}>
+        <thead>
+          <tr>
+            {props.columns.map((column) => (
+              <th class={column.class}>{column.header}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          <For each={props.rows} by={props.rowKey}>
+            {(row: Row) => (
+              <tr class={props.rowClass?.(row)}>
+                {props.columns.map((column) => (
+                  <td class={column.class}>{column.render(row)}</td>
+                ))}
+              </tr>
+            )}
+          </For>
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/dist/templates/startkit/src/components/empty-state.tsx

@@ -0,0 +1,13 @@
+export default function EmptyState(props: {
+  title: string;
+  description: string;
+  action?: unknown;
+}) {
+  return (
+    <section class="empty-state panel" role="status">
+      <h2>{props.title}</h2>
+      <p>{props.description}</p>
+      {props.action && <div>{props.action}</div>}
+    </section>
+  );
+}

package/dist/templates/startkit/src/components/page-header.tsx

@@ -0,0 +1,23 @@
+import { Inline } from '@askrjs/themes/components';
+
+export default function PageHeader(props: {
+  title: string;
+  description: string;
+  actions?: unknown;
+}) {
+  return (
+    <Inline
+      class="page-header"
+      align="center"
+      justify="between"
+      gap="var(--ak-space-lg)"
+      wrap="wrap"
+    >
+      <div class="page-header-copy">
+        <h1>{props.title}</h1>
+        <p>{props.description}</p>
+      </div>
+      {props.actions && <div>{props.actions}</div>}
+    </Inline>
+  );
+}

package/dist/templates/startkit/src/components/stat-card.tsx

@@ -0,0 +1,24 @@
+import type { JSXElement } from '@askrjs/askr/foundations';
+import type { IconProps } from '@askrjs/lucide';
+
+type IconComponent = (props: IconProps) => JSXElement;
+
+export default function StatCard(props: {
+  label: string;
+  value: string;
+  trend: string;
+  icon: IconComponent;
+}) {
+  const Icon = props.icon;
+
+  return (
+    <article class="panel stat-card">
+      <div class="stat-card-head">
+        <p>{props.label}</p>
+        <Icon size={16} aria-hidden="true" />
+      </div>
+      <strong>{props.value}</strong>
+      <p class="trend">{props.trend}</p>
+    </article>
+  );
+}

package/dist/templates/startkit/src/features/accounts/account-filters.tsx

@@ -0,0 +1,61 @@
+import { Input } from '@askrjs/ui/input';
+import { SearchIcon } from '@askrjs/lucide';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectPortal,
+  SelectTrigger,
+  SelectValue,
+} from '@askrjs/ui/select';
+import { Button } from '@askrjs/ui/button';
+import type { AccountStatus } from '../../lib/mock-data';
+
+export default function AccountFilters(props: {
+  query: string;
+  status: AccountStatus | 'all';
+  onQueryChange: (next: string) => void;
+  onStatusChange: (next: AccountStatus | 'all') => void;
+  onReset: () => void;
+}) {
+  const hasFilters = () =>
+    props.query.trim().length > 0 || props.status !== 'all';
+
+  return (
+    <div class="account-filters">
+      <label class="input-row account-search" aria-label="Search accounts">
+        <SearchIcon size={15} aria-hidden="true" />
+        <Input
+          placeholder="Search by name, email, or id"
+          value={props.query}
+          onInput={(event: Event) =>
+            props.onQueryChange((event.target as HTMLInputElement).value)
+          }
+        />
+      </label>
+
+      <Select
+        value={props.status}
+        onValueChange={(value) =>
+          props.onStatusChange(value as AccountStatus | 'all')
+        }
+      >
+        <SelectTrigger aria-label="Status filter">
+          <SelectValue placeholder="Filter by status" />
+        </SelectTrigger>
+        <SelectPortal>
+          <SelectContent>
+            <SelectItem value="all">All statuses</SelectItem>
+            <SelectItem value="active">Active</SelectItem>
+            <SelectItem value="pending">Pending</SelectItem>
+            <SelectItem value="archived">Archived</SelectItem>
+          </SelectContent>
+        </SelectPortal>
+      </Select>
+
+      <Button onPress={props.onReset} disabled={!hasFilters()}>
+        Clear filters
+      </Button>
+    </div>
+  );
+}