@askrjs/cli 0.0.3 → 0.0.4

package/skills/askr-routing-layouts/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Routing Layouts"
-  short_description: "Define Askr routes and shells"
-  default_prompt: "Use $askr-routing-layouts to add routes, layouts, and navigation."

package/skills/askr-runtime-reactivity/SKILL.md

@@ -1,92 +0,0 @@
----
-name: askr-runtime-reactivity
-description: Use when writing askr reactive runtime code with state, derive, selector, context, JSX control flow, stable call order, deterministic event handling, or render lifecycle rules.
----
-
-# Askr Runtime Reactivity
-
-Use this when local state, derived values, keyed identity, or runtime determinism matters. The goal is stable helper call order and correct primitive use.
-
-## Use This When
-
-- You are adding local UI state.
-- You need a computed value from reactive reads.
-- You are rendering keyed lists, selections, or filters.
-- You need to keep call order stable across renders.
-
-## Inspect First
-
-- The nearest existing component with similar state or list behavior.
-- Existing tests that already cover toggles, selection, or filtering.
-- The nearest feature owner if local state may need to become shared later.
-
-## Pick The Primitive
-
-- Local mutable value: `state()` returns a `[getter, setter]` pair.
-- Computed value from reactive reads: `derive()`.
-- One reactive source fans out to many keyed readers: `selector()`.
-- Cross-tree shared value: `defineScope()` and `readScope()`.
-- Keyed or identity-sensitive list: `For`.
-
-## Copy This Shape
-
-```tsx
-import { derive, selector, state } from "@askrjs/askr";
-import { For, Show } from "@askrjs/askr/control";
-
-const [count, setCount] = state(0);
-const [selectedId, setSelectedId] = state<number | null>(null);
-const doubled = derive(() => count() * 2);
-const isSelected = selector(selectedId);
-```
-
-`state()` returns a `[getter, setter]` pair. Read with `getter()` and update with `setter(...)`.
-
-## Determinism Rules
-
-- Do not call `state`, `derive`, `selector`, `resource`, query, or mutation helpers conditionally.
-- Do not mutate state during render.
-- Batch related updates in the event handler that owns the user action.
-- Preserve stable keys in `For` for rows and reorderable lists.
-
-## Reject This Shape
-
-```tsx
-function BadList({ rows }) {
-  if (rows.length > 0) {
-    const [selected, setSelected] = state(rows[0].id);
-    return rows.map((row, index) => (
-      <button key={index} onClick={() => setSelected(row.id)}>
-        {selected === row.id ? "Selected" : row.label}
-      </button>
-    ));
-  }
-
-  return null;
-}
-```
-
-Reject this shape. It creates state conditionally, treats getter/setter values like plain variables, and uses index keys where stable identity matters.
-
-- Reading a getter without calling it.
-- React hooks or `useState` in Askr app code.
-- Recreating selectors in row components.
-- Index keys for data with stable IDs.
-- Derived state that performs side effects.
-
-## Validate
-
-- Runtime helpers are top-level and unconditional.
-- Getter calls are explicit.
-- Lists have stable identity.
-- Existing or new tests cover the state change that matters.
-
-## Done When
-
-- No React-style state shape or conditional helper creation slipped in.
-
-## Handoff
-
-- Use `askr-query-mutation` when the next step is shared keyed state.
-- Use `askr-resources-data` when the next step is async lifecycle ownership.
-- Use `askr-testing-determinism` before closing runtime-sensitive changes.

package/skills/askr-runtime-reactivity/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Runtime Reactivity"
-  short_description: "Write deterministic Askr state code"
-  default_prompt: "Use $askr-runtime-reactivity to write deterministic Askr state and control flow."

package/skills/askr-ssr-ssg/SKILL.md

@@ -1,76 +0,0 @@
----
-name: askr-ssr-ssg
-description: Use when building askr server-rendered or static-generated apps, working with SSR/SSG entrypoints, route manifests, static generation configs, hydration-safe rendering, resource constraints, and render output verification.
----
-
-# Askr SSR SSG
-
-Use this when the app renders outside the browser or produces static output. The goal is one shared route tree, environment-safe render paths, and hydration-safe output.
-
-## Inspect First
-
-- `src/main.tsx`
-- The shared route registry
-- SSR entry files such as `server.ts` or `entry-server.tsx`
-- SSG files such as `ssg.config.ts` or `ssg-build.ts`
-- Existing build and preview scripts in `package.json`
-
-## Use This When
-
-- You are adding SSR or SSG routes.
-- You need parameterized static entries.
-- You need to keep browser-only code out of server render paths.
-- You need to verify hydration safety after changing render behavior.
-
-## Do This In Order
-
-1. Keep the route tree shared across browser, server, and static output where possible.
-2. Register routes at module load before boot or render.
-3. Keep render paths deterministic and environment-safe.
-4. Use route `entries` or the template's static config for parameterized SSG paths.
-5. Build and preview after changes that cross the render boundary.
-
-## Copy This Shape
-
-```ts
-registerRoutes(() => {
-  page("/docs/{slug}", DocsPage, {
-    entries: async () => [{ slug: "getting-started" }, { slug: "routing" }],
-  });
-});
-```
-
-## Never Do These
-
-- Async components in render paths.
-- Route registration that depends on request-time mutation.
-- Browser-only globals in server or static render paths without guards.
-- Divergent route trees for client, server, and static output.
-- Random values or time reads that change initial markup across server and client.
-
-## Static Generation Pattern
-
-```bash
-npx @askrjs/cli create ssg my-site
-npm run build
-npx @askrjs/cli ssg --config ./ssg.config.ts --output ./dist/static
-```
-
-## Validate
-
-- SSR or SSG build output is deterministic for the same inputs.
-- Hydration has no structural mismatch warnings.
-- Generated static routes cover expected params.
-- Browser preview still navigates correctly after hydration.
-
-## Done When
-
-- The same route tree still owns navigation across environments.
-- Server and static render paths are environment-safe.
-- Parameterized routes have explicit static coverage where needed.
-- Build and preview prove the render boundary still works.
-
-## Handoff
-
-- Use `askr-routing-layouts` when the hard part is route ownership.
-- Use `askr-testing-determinism` when hydration, preview, or build verification is the real blocker.

package/skills/askr-ssr-ssg/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr SSR SSG"
-  short_description: "Render askr on server or static"
-  default_prompt: "Use $askr-ssr-ssg to build SSR or static Askr output."

package/skills/askr-testing-determinism/SKILL.md

@@ -1,75 +0,0 @@
----
-name: askr-testing-determinism
-description: Use when testing Askr apps, validating deterministic runtime behavior, writing jsdom or browser tests, checking accessibility, cleanup, route behavior, resources, queries, mutations, keyed lists, and performance-sensitive UI.
----
-
-# Askr Testing Determinism
-
-Use this when choosing or running validation for Askr work. The goal is the narrowest executable check that proves the changed contract.
-
-## Use This When
-
-- You changed route behavior, state behavior, async ownership, or user-visible UI.
-- You need to decide which test level is correct.
-- You need objective done criteria before closing a task.
-- You need to avoid ending on diff review alone.
-
-## Inspect First
-
-- Existing tests nearest to the changed files.
-- The repo's test scripts in `package.json`.
-- Existing browser or jsdom coverage for similar behavior.
-- Any known failing test that already describes the bug.
-
-## Pick The Smallest Useful Check
-
-- Unit tests: pure helpers, formatters, validators, route metadata, data transforms.
-- jsdom tests: runtime state, resource behavior, route rendering, component logic.
-- Browser tests: focus, keyboard behavior, overlays, layout, hydration, visual regressions, performance-sensitive flows.
-- Type tests: public API and component prop contracts.
-- Benchmarks: hot paths, keyed lists, large tables, router matching, hydration.
-
-## Validate In This Order
-
-1. The narrowest failing or behavior-scoped test for the slice you changed.
-2. The nearest type check or package check.
-3. Build or template-specific checks when boot, routing, SSR, SSG, or packaging changed.
-4. Manual runtime verification for user-visible async, focus, overflow, or stale-state behavior when tests do not already cover it.
-
-## Determinism Targets
-
-- Event ordering and batched updates.
-- Stable call order for runtime helpers.
-- Keyed DOM identity during list updates.
-- No partial DOM commit after render failure.
-- Async cancellation on navigation or unmount.
-- Route identity and layout retention across navigation.
-
-## Patterns
-
-- Clean up mounted apps with `cleanupApp(root)` when tests mount an app.
-- Prefer user-visible assertions over implementation detail checks.
-- For `resource()`, cover pending, success, error, refresh, and cancellation when relevant.
-- For `@askrjs/ui`, cover keyboard and ARIA behavior.
-- For themes, include computed style and overflow checks where visual contracts matter.
-
-- Tests that depend on uncontrolled timers or random data.
-- Snapshot-only coverage for interactive behavior.
-- Browser behavior tested only in jsdom.
-- Performance changes without a focused benchmark or regression test.
-
-## Validate The Test Itself
-
-- The smallest meaningful test covers the changed contract.
-- The chosen test level matches the behavior under change.
-- Async checks wait for visible state instead of sleeping blindly.
-- The repo's existing scripts are used before inventing new ones.
-
-## Done When
-
-- Diff review was not used as the only proof when an executable check existed.
-
-## Handoff
-
-- Use `askr-accessibility` when browser coverage reveals focus or announcement issues.
-- Use `askr-observability-debugging` when tests expose stale-state or correlation failures.

package/skills/askr-testing-determinism/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Testing Determinism"
-  short_description: "Test deterministic Askr behavior"
-  default_prompt: "Use $askr-testing-determinism to test Askr runtime and UI behavior."

package/skills/askr-theming/SKILL.md

@@ -1,86 +0,0 @@
----
-name: askr-theming
-description: Use when styling Askr apps with @askrjs/themes, tokens, data-theme, ThemeScope, shell/nav/layout primitives, data-slot selectors, visual quality audits, dark mode, and theme/app boundary decisions.
----
-
-# Askr Theming
-
-Use this when styling an Askr app with the theme layer. The goal is one obvious shell, one obvious token strategy, and no app-local clones of solved surfaces.
-
-## Inspect First
-
-- `src/styles.css` and `src/styles/*`
-- The root layout or app shell that imports the theme
-- Existing shared components and `@askrjs/themes` imports
-- The nearest screen with the same layout or surface pattern
-
-## Use This When
-
-- You are styling a new product surface.
-- You need dark mode, shell chrome, or token overrides.
-- You want the default Askr admin or SaaS visual language.
-- You are tempted to create local `Card`, `Panel`, `Sidebar`, `Toolbar`, or `EmptyState` components.
-
-## Choose The Layer
-
-- Use `@askrjs/themes` when the existing app already uses the default visual layer.
-- Use `@askrjs/ui` directly only when the app already owns its own visual system and just needs headless behavior.
-- Create an app-local wrapper only when it adds clear product semantics beyond one screen.
-
-## Do This In Order
-
-1. Import the theme once at the app boundary or stylesheet entry.
-2. Reuse existing theme primitives for shells, navigation, layout, surfaces, feedback, and forms.
-3. Override semantic `--ak-*` tokens in CSS, not runtime TypeScript.
-4. Use `data-slot` or documented selectors for local CSS hooks.
-5. Check the result in mobile, desktop, light, dark, empty, error, and disabled states.
-
-## Copy This Shape
-
-```ts
-import "@askrjs/themes/default";
-import {
-  Button,
-  Card,
-  CardContent,
-  CardHeader,
-  CardTitle,
-  Container,
-  EmptyState,
-  Section,
-  Shell,
-  ShellMain,
-  ShellNav,
-  Stack,
-  ThemeScope,
-} from "@askrjs/themes/components";
-```
-
-## Never Do These
-
-- Moving runtime behavior into theme files.
-- Treating theme components as app state containers.
-- Hardcoded non-token colors when tokens exist.
-- Deep internal selectors or `!important`.
-- Marketing-page assumptions in operational SaaS surfaces.
-- Inventing app-local `Panel`, `HStack`, `VStack`, `Page`, `Toolbar`, `Badge`, `Card`, or `EmptyState` components before checking the theme surface.
-- Recreating shell, nav, feedback, form field, or responsive layout primitives already exported by `@askrjs/themes`.
-
-## Validate
-
-- No clipped text, horizontal overflow, or broken shell composition.
-- Focus, hover, disabled, empty, and error states are styled deliberately.
-- Dark mode is intentional, not inverted by accident.
-- App CSS remains override-friendly and token-based.
-
-## Done When
-
-- The surface reuses the existing theme layer instead of inventing a second one.
-- Tokens live in CSS and behavior stays in components.
-- The interface remains coherent across responsive and state changes.
-
-## Handoff
-
-- Use `askr-ui-composition` when the hard part is behavior and composition, not visual styling.
-- Use `askr-accessibility` when announcements, focus, or semantic behavior need review.
-- Use `askr-testing-determinism` before closing visible UI changes.

package/skills/askr-theming/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Theming"
-  short_description: "Style apps with Askr themes"
-  default_prompt: "Use $askr-theming to apply tokens, shells, navs, and theme rules."

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

@@ -1,92 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,11 +0,0 @@
-# {{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

@@ -1,17 +0,0 @@
-# {{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

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

package/templates/full-stack/index.html

@@ -1,13 +0,0 @@
-<!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

@@ -1,39 +0,0 @@
-{
-  "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/askr": ">=0.0.53 <0.1.0",
-    "@askrjs/auth": ">=0.0.1 <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

@@ -1,9 +0,0 @@
-import { serve } from "@askrjs/node";
-import app from "virtual:askr-server";
-
-const port = Number(process.env.PORT ?? 3000);
-await serve(app, {
-  host: process.env.HOST ?? "127.0.0.1",
-  port,
-  assets: { root: new URL("./dist", import.meta.url).pathname },
-});

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

@@ -1,10 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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>
-  );
-}