@askrjs/cli 0.0.3 → 0.0.4

package/skills/askr-accessibility/SKILL.md

@@ -1,68 +0,0 @@
----
-name: askr-accessibility
-description: Use when making Askr UI accessible, including keyboard flows, focus management, ARIA names, dialogs, menus, forms, tables, live regions, screen-reader behavior, and @askrjs/ui primitive selection.
----
-
-# Askr Accessibility
-
-Use this for accessibility-sensitive UI or when composing interactive primitives. The goal is predictable keyboard flow, visible and announced state changes, and reuse of primitives that already own behavior.
-
-## Use This When
-
-- The surface includes dialogs, menus, forms, tables, or other interactive controls.
-- Focus management, keyboard flow, or screen-reader behavior matters to the task.
-- Async status, stale state, or destructive confirmation must be announced clearly.
-- You need to review whether a UI change stayed accessible after composition or theming work.
-
-## Inspect First
-
-- Existing `@askrjs/ui` primitive usage
-- Labels, accessible names, focus order, and keyboard behavior
-- Form errors, async status messages, and destructive confirmations
-- Browser tests for overlays, menus, forms, and tables
-
-## Do This In Order
-
-1. Prefer `@askrjs/ui` for behavior-heavy controls before raw HTML.
-2. Make sure every interactive control has an accessible name.
-3. Keep dialog, menu, and overlay focus behavior predictable.
-4. Make form errors, async failures, and important status changes visible and announceable.
-5. Check that stale, selected, pending, and error states are not color-only.
-
-## Copy This Shape
-
-```tsx
-<Show when={mutation.error}>
-	<p role="alert">Unable to save changes.</p>
-</Show>
-
-<button aria-label="Archive account">Archive</button>
-```
-
-## Never Do These
-
-- Reimplementing primitive keyboard behavior.
-- Icon-only buttons without labels.
-- Focus loss after route changes, dialogs, or list updates.
-- Color-only error, stale, selected, or pending states.
-- Toast-only critical errors.
-
-## Validate
-
-- Keyboard-only users can complete the workflow.
-- Focus lands in the expected place after navigation, dialog open or close, and submit.
-- Axe or equivalent accessibility checks pass for changed surfaces when available.
-- Browser tests cover complex focus and keyboard behavior.
-
-## Done When
-
-- Keyboard, focus, and naming behavior are predictable.
-- Important async and failure states are announced or visible semantically.
-- The surface does not depend on color alone to communicate state.
-- Accessibility behavior is verified at the right test level.
-
-## Handoff
-
-- Use `askr-ui-composition` when the hard part is primitive behavior composition.
-- Use `askr-error-loading-empty` when async state truth is the blocker.
-- Use `askr-testing-determinism` before closing browser-level accessibility changes.

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Accessibility"
-  short_description: "Make Askr UI accessible and usable"
-  default_prompt: "Use $askr-accessibility to review or build accessible UI."

package/skills/askr-agent-execution/SKILL.md

@@ -1,85 +0,0 @@
----
-name: askr-agent-execution
-description: Use when an AI coding agent needs the canonical execution playbook for reading an Askr repo, choosing the right skill, validating work, and avoiding invented primitives or foreign framework defaults.
----
-
-# Askr Agent Execution
-
-Use this before any edit in an Askr repo. This is the execution loop that every other Askr skill assumes.
-
-## Use This When
-
-- Starting a new task.
-- The right Askr skill is not obvious yet.
-- You need a fixed read order before editing.
-- You need objective done criteria.
-
-## Read In This Order
-
-1. `package.json`
-2. `AGENTS.md` when it exists
-3. `src/main.tsx`
-4. `src/router.tsx` or `src/pages/_routes.tsx`
-5. The nearest branch `_routes.tsx` and `_layout.tsx`
-6. The nearest `src/features/<feature>/` or `src/components/<feature>/` owner
-7. Existing tests for the touched surface
-8. `src/styles.css` and `src/styles/*` only when visual behavior changes
-
-## Choose The Next Skill
-
-- File ownership unclear: use `askr-project-structure`.
-- Route tree, shell, metadata, or navigation change: use `askr-routing-layouts`.
-- Local state, derived values, keyed rendering, or call-order safety: use `askr-runtime-reactivity`.
-- One route or container owns an async read: use `askr-resources-data`.
-- Shared keyed reads or writes must coordinate across screens: use `askr-query-mutation`.
-- Loading, empty, stale, retry, or pending-write truth is the hard part: use `askr-error-loading-empty`.
-- You are closing the task and need the right checks: use `askr-testing-determinism`.
-- The task spans many app surfaces and no narrower owner is enough: use `askr-app-builder` last, not first.
-
-## Execution Loop
-
-1. Inspect the existing owner files before proposing a new abstraction.
-2. Pick one owning skill for the current slice.
-3. Make the smallest edit that matches the repo's current structure.
-4. Run the narrowest executable validation for that slice.
-5. Only widen scope after that validation passes or clearly changes your understanding.
-6. Stop when the change is structurally correct, validated, and easy for the next agent to follow.
-
-## Non-Negotiables
-
-- Keep pages route-focused, features workflow-focused, and adapters transport-focused.
-- Add files only where another agent could predict they belong.
-- Reuse existing layouts, route groups, features, and shared helpers before creating new ones.
-- Use `@askrjs/ui` and `@askrjs/themes` before inventing app-local primitives.
-
-## Never Do These By Default
-
-- React hooks or React Router patterns.
-- TanStack Query or a generic query-client abstraction.
-- Custom routing systems or page-local route state copies.
-- App-local `Button`, `Card`, `Panel`, `Sidebar`, `Navbar`, `EmptyState`, `Page`, `Toolbar`, `HStack`, or `VStack` clones.
-- Generic store or service-locator layers when `state()`, `resource()`, `createQuery()`, or `createMutation()` already fit.
-- Diff-only validation when a narrower executable check exists.
-
-## Validate In This Order
-
-1. Run the narrowest relevant test for the touched behavior.
-2. Run the nearest type check or project check.
-3. Run build or template-specific checks if the change affects app boot, routing, SSR/SSG, or packaging.
-4. Confirm loading, error, empty, stale, pending, focus, and overflow states when user-visible.
-
-Use existing scripts such as `npm test`, `npm run type-check`, `npm run build`, `npm run lint`, or `npm run check` when they exist. Do not invent new validation commands when the repo already defines the contract.
-
-## Done When
-
-- You can name the owner file for every new change.
-- The chosen skill matches the slice you edited.
-- No foreign framework defaults or parallel architecture were introduced.
-- At least one executable validation ran, or the blocker is explicit.
-- The next likely skill for follow-up work is obvious.
-
-## Handoff
-
-- Use `askr-project-structure` when the next step is mostly about file placement.
-- Use `askr-routing-layouts` when the next step is mostly about URL ownership or shell boundaries.
-- Use `askr-testing-determinism` before closing any user-visible or stateful change.

package/skills/askr-agent-execution/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Agent Execution"
-  short_description: "Follow the canonical Askr editing playbook"
-  default_prompt: "Use $askr-agent-execution to decide how to read, edit, and validate an Askr repository."

package/skills/askr-agent-workflows/SKILL.md

@@ -1,57 +0,0 @@
----
-name: askr-agent-workflows
-description: Use when building Askr UI for AI or agent workflows, including prompts, runs, streaming output, tool timelines, approvals, cancellation, retries, audit logs, persistence, and event-sourced run state.
----
-
-# Askr Agent Workflows
-
-Use this for user-facing agentic product flows.
-
-## Inspect First
-
-- Existing agent API adapters and run/event schemas.
-- Feature folders for prompts, runs, tools, approvals, or artifacts.
-- Realtime/event-streaming utilities.
-- Product requirements for human approval, audit, and cancellation.
-
-## Run State Model
-
-Model agent work as a run, not a one-off response:
-
-- `draft`: user is composing input.
-- `queued`: backend accepted the run but no work is visible.
-- `running`: events or tokens are arriving.
-- `requires-action`: user approval, credential, or clarification is needed.
-- `cancelling`: cancel requested, waiting for acknowledgement.
-- `succeeded`, `failed`, `cancelled`: terminal states.
-
-## Event-Sourced UX
-
-- Treat the server event log as the source of truth.
-- Apply events idempotently by event ID or sequence.
-- Show optimistic local intent separately from confirmed server state.
-- Preserve `lastEventId` or cursor for resume/reconnect.
-- On reconnect, request events after the last seen cursor and refetch the affected projection if a gap is detected.
-- When projections lag, display "saving", "syncing", or "finalizing" rather than pretending completion.
-
-## UI Composition
-
-- Prompt composer owns draft state and submit intent.
-- Run timeline renders messages, tool calls, approvals, errors, and artifacts.
-- Approval cards make the requested action, risk, and resulting command explicit.
-- Cancel and retry controls reflect backend acknowledgement, not just button clicks.
-
-## Avoid
-
-- A single `loading` boolean for the whole run.
-- Replacing the timeline wholesale when streaming events arrive.
-- Hiding tool calls or approvals in unstructured text.
-- Retrying runs without idempotency or parent-run linkage.
-- Losing partial output on refresh or reconnect.
-
-## Checks
-
-- Run states map to visible UI.
-- Event application is idempotent and ordered.
-- Cancellation, retry, approval, and failure paths are covered.
-- The user can understand what the agent did and what still needs attention.

package/skills/askr-agent-workflows/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Agent Workflows"
-  short_description: "Build agent run product flows"
-  default_prompt: "Use $askr-agent-workflows to build an agent run workflow."

package/skills/askr-api-integration/SKILL.md

@@ -1,79 +0,0 @@
----
-name: askr-api-integration
-description: Use when integrating Askr apps with generated API clients, transport adapters, auth headers, cancellation, DTO mapping, error normalization, retries, and event-sourced consistency metadata.
----
-
-# Askr API Integration
-
-Use this for the boundary between Askr feature code and backend APIs. The goal is one adapter boundary, deterministic DTO mapping, and preserved cancellation and consistency metadata.
-
-## Use This When
-
-- Frontend code crosses an HTTP, SSE, WebSocket, or generated-client boundary.
-- DTOs need mapping before they enter features or UI.
-- Auth headers, retries, request IDs, or error normalization belong in one place.
-- Event-sourced writes need version, cursor, or event metadata for reconciliation.
-
-## Inspect First
-
-- Existing `src/adapters` generated clients and transport wrappers
-- Existing `src/features` query or mutation workflows
-- Existing `src/shared` config, error formatting, and auth helpers
-- API DTO naming, version fields, event IDs, cursor fields, and request IDs
-
-## Choose The Boundary
-
-- `src/adapters`: generated clients, raw transport, auth header injection, and low-level retry behavior.
-- `src/features/<feature>`: app-level queries, mutations, DTO-to-model mapping, and workflow state.
-- `src/shared`: cross-cutting config, error normalization, formatters, and request tracing.
-- Components should consume app models and feature state, never raw transport DTOs.
-
-## Do This In Order
-
-1. Keep raw client calls in the adapter boundary.
-2. Forward `AbortSignal` through every cancellable layer.
-3. Map DTOs into app models before they leave the feature or adapter boundary.
-4. Normalize errors into user-safe messages plus machine-readable diagnostics.
-5. Preserve request IDs, versions, cursors, or event IDs when the UI needs freshness or reconciliation truth.
-6. Retry only idempotent reads or commands with explicit idempotency keys.
-
-## Copy This Shape
-
-```ts
-export async function listAccounts({ signal }: { signal: AbortSignal }) {
-  const response = await accountsClient.list({ signal });
-
-  return {
-    items: response.items.map(toAccount),
-    version: response.version,
-    lastEventId: response.last_event_id,
-  };
-}
-```
-
-## Never Do These
-
-- Returning raw API DTOs directly to page props.
-- Hiding `signal`, request IDs, or version metadata because the first screen does not need them yet.
-- Retrying a non-idempotent command from the UI without a server-recognized idempotency key.
-- Putting raw clients in `src/pages` or generic UI components.
-
-## Validate
-
-- Every async adapter accepts and forwards `signal`.
-- Errors normalize into user-safe messages and machine-readable codes.
-- DTO mapping is deterministic and tested where the boundary matters.
-- Event or version metadata reaches query or mutation state when consistency matters.
-
-## Done When
-
-- Components no longer see raw transport DTOs.
-- `signal`, request IDs, and consistency metadata survive the adapter boundary.
-- Retry behavior is explicit and safe.
-- Error normalization is ready for both user copy and machine-readable handling.
-
-## Handoff
-
-- Use `askr-query-mutation` when feature state must invalidate or reconcile shared reads.
-- Use `askr-auth-access` when auth headers or session policy shape the adapter behavior.
-- Use `askr-observability-debugging` when request IDs, traces, and safe diagnostics must survive end to end.

package/skills/askr-api-integration/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr API Integration"
-  short_description: "Connect APIs with Askr boundaries"
-  default_prompt: "Use $askr-api-integration to connect an API to an Askr feature."

package/skills/askr-app-builder/SKILL.md

@@ -1,99 +0,0 @@
----
-name: askr-app-builder
-description: Use when building or substantially extending an Askr application, choosing scaffolds, planning app architecture, combining routing, state, data, UI primitives, theming, charts, SSR/SSG, or deciding which more specific Askr skill should guide the work.
----
-
-# Askr App Builder
-
-Use this only when a task spans multiple owned workflows and no single narrower skill is enough. This is a planning and dispatch skill, not the default starting point for everyday feature work.
-
-## Use This When
-
-- A new feature spans routing, data ownership, UI composition, and validation together.
-- You need to choose a scaffold or template path before implementation.
-- You need to break a broad feature into smaller owned slices.
-- The task touches multiple branches, features, and render surfaces at once.
-
-## Do Not Use This First When
-
-- The task is only about one route, one component, one async owner, or one UI surface.
-- File ownership is unclear but still local; use `askr-project-structure` instead.
-- The hard problem is already clearly routing, state, theming, auth, or validation.
-
-## Inspect First
-
-- `AGENTS.md` when it exists
-- `package.json`
-- `src/main.tsx`
-- The top-level route registry and nearest branch layout
-- Existing `src/features`, `src/adapters`, `src/shared`, and `src/styles` ownership
-- Existing tests for the surfaces involved
-
-## Plan The Slice
-
-1. Pick the template or existing app baseline.
-2. Identify the route owner, layout owner, feature owner, adapter owner, and validation owner.
-3. Split the work into smaller slices that can each be guided by one narrower skill.
-4. Apply those narrower skills in sequence instead of keeping the whole task under this one.
-5. End with `askr-testing-determinism` once the slices are implemented.
-
-## Choose The Baseline
-
-- New product app: `askr create startkit <name>`.
-- Minimal interactive app: `spa`.
-- Server-rendered app: `ssr`.
-- Static or docs site: `ssg`.
-- Existing app: follow its current route, layout, style, and test conventions before introducing new ones.
-
-## Route The Work To Narrower Skills
-
-- File placement or ownership: `askr-project-structure`.
-- Route tree, metadata, shell boundaries, navigation: `askr-routing-layouts`.
-- Local state or keyed rendering: `askr-runtime-reactivity`.
-- Route-owned async reads: `askr-resources-data`.
-- Shared keyed reads and writes: `askr-query-mutation`.
-- Async truth states: `askr-error-loading-empty`.
-- CRUD workflow: `askr-forms-tables-crud`.
-- Auth and access: `askr-auth-access`.
-- Theming and UI composition: `askr-theming` and `askr-ui-composition`.
-- Realtime or event streams: `askr-realtime-streaming`.
-- SSR or SSG: `askr-ssr-ssg`.
-- Final validation: `askr-testing-determinism`.
-
-## Copy This Shape
-
-```text
-route owner      -> src/pages/app/_routes.tsx
-layout owner     -> src/pages/app/_layout.tsx
-feature owner    -> src/features/agents/
-adapter owner    -> src/adapters/agents-client.ts
-validation owner -> tests/ or nearest package test script
-```
-
-## Never Do These
-
-- React-shaped defaults such as `useEffect` data loading or implicit mutable state.
-- Mixing route registration, data transport, layout shell, and visual theme logic in one component.
-- Treating this skill as a substitute for narrower workflow skills.
-- Raw interactive HTML when an `@askrjs/ui` primitive owns the behavior.
-- App-local layout, shell, card, nav, feedback, or form primitives when `@askrjs/themes` already owns the surface.
-- Hardcoded `--ak-*` token literals in runtime TypeScript or JavaScript.
-
-## Validate
-
-- The app has one clear route tree.
-- Route branches, layouts, feature workflows, adapters, shared helpers, UI behavior, and theme concerns sit in separate layers.
-- Loading, empty, error, disabled, and narrow-screen states are explicit.
-- `npm run check` or the closest available project check passes.
-
-## Done When
-
-- The chosen template path still matches the app surface.
-- Each slice is routed to one narrower skill.
-- Route, layout, feature, adapter, shared, and theme concerns are separated.
-- No foreign framework defaults or invented primitives slipped in.
-
-## Handoff
-
-- Use the narrower skill that owns the next slice.
-- Use `askr-testing-determinism` before finalizing the assembled result.

package/skills/askr-app-builder/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr App Builder"
-  short_description: "Build idiomatic Askr applications"
-  default_prompt: "Use $askr-app-builder to plan and build an idiomatic Askr app."

package/skills/askr-auth-access/SKILL.md

@@ -1,74 +0,0 @@
----
-name: askr-auth-access
-description: Use when building Askr authentication, session loading, public/app route branches, protected layouts, role and permission requirements, redirects, login/logout, and access-denied UX.
----
-
-# Askr Auth Access
-
-Use this for authentication and authorization in route-first Askr apps. The goal is explicit route policy, explicit session resolution, and no token or permission logic leaking into pages.
-
-## Inspect First
-
-- `src/pages/_routes.tsx`, `src/pages/public/_routes.tsx`, and `src/pages/app/_routes.tsx`
-- `src/pages/public/_layout.tsx` and `src/pages/app/_layout.tsx`
-- Existing session, token, and user helpers in `src/shared` or `src/features/auth`
-- Router auth resolver configuration
-
-## Use This When
-
-- You need guest-only and authenticated route branches.
-- You need route-level auth or permission requirements.
-- You need login, logout, redirect, or forbidden behavior.
-- You need to keep access checks out of page-local component logic.
-
-## Do This In Order
-
-1. Keep public and authenticated branches explicit in the route tree.
-2. Put an `AuthRequirement` on the narrowest route group or route that owns the policy.
-3. Resolve session state before rendering protected data or destructive controls.
-4. Redirect unauthenticated users to login with a return target when useful.
-5. Show a signed-in forbidden state when the user is authenticated but lacks permission.
-6. Keep token storage, refresh, and header policy in auth helpers or adapters, not components.
-
-## Copy This Shape
-
-```tsx
-import { requireAnonymous, requireUser } from "@askrjs/auth";
-
-group({ layout: AuthLayout, auth: requireAnonymous() }, () => {
-  registerAuthRoutes();
-});
-
-group({ layout: AppLayout, auth: requireUser() }, () => {
-  registerAppRoutes();
-});
-```
-
-## Never Do These
-
-- Per-page auth checks duplicated across protected routes.
-- Rendering protected app data before session resolution.
-- Putting token storage or API auth header logic in components.
-- Treating roles and permissions as visual-only state.
-- Client-only authorization decisions for sensitive server actions.
-- Silent redirects when the user is signed in but lacks access.
-
-## Validate
-
-- Public and app branches are explicit.
-- Protected routes have a function-based auth requirement in the route tree.
-- Access-denied, loading, and redirect behavior are tested.
-- Auth state is available to adapters without leaking transport details into UI.
-
-## Done When
-
-- Session resolution is explicit before protected data renders.
-- Auth and authorization live in route requirements or auth workflows, not scattered through pages.
-- Unauthorized, redirect, and signed-out states are all covered.
-- Sensitive transport or token logic did not leak into UI components.
-
-## Handoff
-
-- Use `askr-routing-layouts` when auth changes also reshape the route tree.
-- Use `askr-api-integration` when auth headers, session refresh, or adapter policy is changing.
-- Use `askr-observability-debugging` when denial reasons or audit trails must stay visible.

package/skills/askr-auth-access/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr Auth Access"
-  short_description: "Model auth branches and access"
-  default_prompt: "Use $askr-auth-access to add authentication and route access."

package/skills/askr-cli-vite/SKILL.md

@@ -1,76 +0,0 @@
----
-name: askr-cli-vite
-description: Use when scaffolding Askr projects with @askrjs/cli, choosing spa/ssr/ssg/startkit templates, configuring @askrjs/vite, JSX import source, Vite build setup, generated app customization, or fixing transform wiring.
----
-
-# Askr CLI Vite
-
-Use this only when the task is scaffold choice, initial project setup, or repair of Vite and transform wiring. It is not a normal feature-work skill after the app is already on the canonical path.
-
-## Use This When
-
-- Choosing between `spa`, `ssr`, `ssg`, and `startkit`.
-- Fixing `@askrjs/vite` plugin wiring or JSX import-source setup.
-- Repairing generated `package.json`, `vite.config.ts`, or `tsconfig` settings.
-- Adjusting scaffolded build integration without changing runtime architecture.
-
-## Inspect First
-
-- `docs/create.md`
-- `docs/workflows.md`
-- Existing `package.json`, `vite.config.ts`, and `tsconfig.json`
-- The nearest matching template under `templates/`
-
-## Start From The Closest Template
-
-- `startkit`: default for new product apps with dashboard, accounts, settings, login, themes, icons, and common checks.
-- `spa`: minimal client-rendered interactive app.
-- `ssr`: server-rendered app boundary.
-- `ssg`: static generation scaffold with `ssg.config.ts`.
-
-## Do This In Order
-
-1. Choose the closest template instead of starting from raw Vite.
-2. Preserve generated Vite wiring unless the app has a concrete build requirement.
-3. Keep `askr()` as the owning plugin for Askr JSX and transforms.
-4. Keep runtime route, data, and component decisions out of build config.
-5. Treat generated files as app-owned after scaffold, not immutable.
-6. Validate scripts and transforms before moving on to feature work.
-
-## Copy This Shape
-
-```ts
-import { defineConfig } from "vite";
-import { askr } from "@askrjs/vite";
-
-export default defineConfig({
-  plugins: [askr()],
-});
-```
-
-## Never Do These
-
-- Duplicating JSX transform setup in Vite, `tsconfig`, and custom esbuild config.
-- Choosing `startkit` for a tiny isolated demo when `spa` fits better.
-- Treating CLI-generated files as immutable.
-- Adding runtime route or data decisions to build config.
-
-## Validate
-
-- `vite.config.ts` uses `askr()`.
-- `package.json` scripts match the selected template.
-- `tsconfig` JSX settings match template conventions.
-- `npm run dev`, `npm run build`, and available checks pass after setup.
-
-## Done When
-
-- The template matches the runtime boundary the app actually needs.
-- Vite wiring stays package-owned and minimal.
-- Generated files are ready for normal workflow skills.
-- No runtime architecture leaked into build config.
-
-## Handoff
-
-- Use `askr-app-builder` only when the task is still a broad app brief.
-- Use `askr-ssr-ssg` when the render boundary is the hard part.
-- Use the normal route, data, or UI workflow skills once the scaffold exists.

package/skills/askr-cli-vite/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Askr CLI Vite"
-  short_description: "Scaffold and configure Askr apps"
-  default_prompt: "Use $askr-cli-vite to scaffold or configure an askr Vite app."