@askrjs/cli 0.0.2 → 0.0.3

package/skills/askr-dashboard-charts/SKILL.md

@@ -1,79 +1,96 @@
 ---
 name: askr-dashboard-charts
-description: Use when building askr dashboards, stat cards, activity feeds, product metrics, tables, async feedback, and @askrjs/charts visualizations such as area, bar, line, donut, heatmap, timeline, gauges, and chart chrome.
+description: Build product dashboards and metric-heavy Askr routes with route-owned async state, shared formatting, and typed @askrjs/charts plots. Use for stat cards, mixed charts, live or follow-latest data, zoom, brush, selection, accessible summaries, and chart exports.
 ---
 
 # Askr Dashboard Charts
 
-Use this for product dashboards and metric-heavy screens. The goal is route-owned data, deterministic metric formatting, and charts that answer product questions without inventing parallel UI systems.
-
-## Use This When
-
-- You are building a dashboard, metrics screen, stat-card surface, or chart-heavy route.
-- The page needs resource-owned async loading plus chart composition.
-- Charts and tables must share the same formatter logic.
-- You need loading, empty, and error truth on a dense metrics screen.
+Build dashboards that answer product questions without inventing parallel data, UI, or formatting systems.
 
 ## Inspect First
 
-- `templates/startkit/src/pages/workspace/dashboard.tsx`
-- Existing stat card, table, empty state, and chart styles
-- Existing format helpers in `src/shared`
-- Existing route or feature owners for the metrics you need
+- Inspect the route or feature that owns the data.
+- Inspect existing cards, tables, empty states, chart tokens, and format helpers.
+- Inspect the nearest existing typed plot. In a generated SPA, start with `src/pages/app/admin-home.tsx`; in the CLI source, use `templates/spa/src/pages/app/admin-home.tsx`.
 
-## Choose The Owner
+## Keep Ownership Clear
 
-- The route or page owns high-level loading and composition.
+- Keep loading, empty, error, refresh, and composition state in the route or feature container.
 - `src/components/shared` owns reusable stat cards, page headers, tables, and empty states.
-- `src/features/<domain>` owns domain-specific dashboard panels and metric workflows.
+- `src/features/<domain>` owns metric workflows and transforms.
 - `src/shared` owns formatting helpers so cards, tables, and charts stay consistent.
+- Keep row types app-owned; do not import package-owned datum types.
 
-## Do This In Order
+## Work In Order
 
-1. Load dashboard data in the route or feature container with `resource()` unless the data must be shared across screens.
-2. Keep metric formatting in shared helpers.
-3. Use `@askrjs/charts` components for chart visuals and keep CSS imported at the app boundary.
-4. Pair charts with labels, summaries, or tables when precision matters.
-5. Keep loading, empty, error, and refresh states explicit.
+1. Load dashboard data with `resource()` unless a wider owner already exists.
+2. Model stable row keys and missing values before choosing marks.
+3. Create each typed plot namespace once at module scope.
+4. Compose the smallest plot that answers the product question.
+5. Import `@askrjs/charts/styles` once at the app boundary.
+6. Pair plots with summaries or on-demand data tables when precision matters.
 
-## Copy This Shape
+## Compose A Typed Plot
 
 ```tsx
-import { resource } from "@askrjs/askr/resources";
-import { AreaChart, ChartPanel, ChartShell } from "@askrjs/charts/components";
-
-const dashboard = resource(({ signal }) => loadDashboard({ signal }), []);
+import { createPlot } from "@askrjs/charts";
+
+type ThroughputRow = {
+  id: string;
+  timestamp: Date;
+  completed: number;
+  movingAverage: number;
+};
+
+const ThroughputPlot = createPlot<ThroughputRow>();
+
+<ThroughputPlot.Root
+  data={rows}
+  rowKey="id"
+  label="Completed runs over time"
+  title="Run throughput"
+  description="Completed runs with a moving average."
+>
+  <ThroughputPlot.Bar x="timestamp" y="completed" />
+  <ThroughputPlot.Line x="timestamp" y="movingAverage" />
+  <ThroughputPlot.Point x="timestamp" y="movingAverage" />
+  <ThroughputPlot.Zoom axes="x" />
+  <ThroughputPlot.Brush axis="x" modifier="shift" />
+</ThroughputPlot.Root>;
+```
 
-if (dashboard.pending && !dashboard.value) return <p>Loading dashboard...</p>;
-if (dashboard.error) return <p role="alert">Unable to load dashboard.</p>;
+## Handle Mixed, Live, And Interactive Data
 
-<ChartShell title="Revenue" description="Last 7 days">
-  <ChartPanel title="Trend">
-    <AreaChart label="Revenue trend" data={dashboard.value.revenue} />
-  </ChartPanel>
-</ChartShell>;
-```
+- Use named scales and dual axes only when a mixed plot compares different units.
+- Pass a reactive data getter for changing rows and update arrays with `appendPlotRows`, `upsertPlotRows`, `removePlotRows`, or `trimPlotRows`.
+- Configure follow-latest by row count or time; let user pan or zoom pause following and provide an explicit `resumeLive()` action.
+- Keep `view` and `selection` controlled when route or shared state owns them; otherwise use plot-local state.
+- Add zoom, brush, legend filtering, or `onActivate` only when the workflow needs that interaction.
+- Keep source and transformed exports distinguishable, and preserve access to visible or selected rows.
 
-## Never Do These
+## Avoid
 
 - Inline mock metrics inside page JSX.
 - Hardcoded chart colors in runtime code.
 - Decorative charts that do not answer a product question.
+- Calling `createPlot()` inside a component or using unstable row keys.
+- Treating missing or non-finite values as zero.
 - Dense dashboards without loading, empty, and error states.
 
 ## Validate
 
-- Cards and charts share formatter logic.
-- The page scans cleanly at mobile, tablet, and desktop widths.
-- Chart data has stable labels and keys.
-- Loading, empty, error, and refresh states are visible.
+- Verify cards, tables, tooltips, and exports share formatter logic; keep summaries and tooltip formatters valid for empty or missing rows.
+- Verify mobile and desktop layouts in light and dark themes.
+- Verify keyboard inspection, selection, zoom, brush, and the on-demand data table when used.
+- Verify live updates retain stable selections and pause follow-latest after user navigation.
+- Run the app's targeted tests and typecheck before its full acceptance command.
 
 ## Done When
 
-- Route-owned loading and chart composition are clear.
-- Metric formatting is shared and deterministic.
-- Charts support the page's product question instead of decorating it.
-- Async states remain explicit on the dashboard surface.
+- Route-owned async states remain explicit.
+- Typed rows and stable keys drive the plot.
+- The plot supports the product question without becoming a component gallery.
+- Accessible summaries and precise data remain available without relying on canvas pixels.
 
 ## Handoff
 

package/skills/askr-dashboard-charts/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Askr Dashboard Charts"
-  short_description: "Build dashboards and charts"
-  default_prompt: "Use $askr-dashboard-charts to build dashboard metrics and charts."
+  short_description: "Compose typed Askr dashboard plots"
+  default_prompt: "Use $askr-dashboard-charts to build an accessible typed dashboard plot."

package/templates/full-stack/AGENTS.md

@@ -9,4 +9,3 @@ This project is the progressive full-stack stage of an Askr application.
 - 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

@@ -15,4 +15,3 @@ 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/index.html

@@ -11,4 +11,3 @@
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
-

package/templates/full-stack/package.json

@@ -14,8 +14,8 @@
     "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/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",
@@ -33,5 +33,7 @@
     "vite-plus": "^0.2.4",
     "vitest": "^4.1.10"
   },
-  "engines": { "node": "^20.19.0 || >=22.12.0" }
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
 }

package/templates/full-stack/server.ts

@@ -1,13 +1,9 @@
-import { listen } from '@askrjs/node';
-import app from 'virtual:askr-server';
+import { serve } 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',
+await serve(app, {
+  host: process.env.HOST ?? "127.0.0.1",
   port,
+  assets: { root: new URL("./dist", import.meta.url).pathname },
 });
-
-const shutdown = () => server.close();
-process.once('SIGINT', shutdown);
-process.once('SIGTERM', shutdown);
-

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

@@ -1,5 +1,5 @@
-import type { ActionDescriptor } from '@askrjs/askr/actions';
-import { createMessageAction } from './actions/create-message';
+import type { ActionDescriptor } from "@askrjs/askr/actions";
+import { createMessageAction } from "./actions/create-message";
 
 const actionsByRoute: Readonly<Record<string, readonly ActionDescriptor[]>> = Object.freeze({
   "/": [createMessageAction],

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

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

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

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

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

@@ -1,12 +1,11 @@
-import { createSPA, hydrateSPA } from '@askrjs/askr/boot';
-import { pageRegistry } from './routes';
+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.');
+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,12 +1,12 @@
-import { ActionForm } from '@askrjs/askr/actions';
-import { createMessageAction } from '../actions/create-message';
-import { messages } from '../i18n';
+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>
+      <h1>{messages.text("title")}</h1>
+      <p>{messages.text("intro")}</p>
       <form method="post" action="/api/session">
         <button type="submit">Start demo session</button>
       </form>

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

@@ -1,7 +1,15 @@
-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';
+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 (
@@ -10,7 +18,9 @@ function ScopedLayout({ children }: { children?: unknown }) {
         <Header sticky>
           <Container paddingY="sm">
             <Navbar aria-label="Primary navigation" width="full">
-              <NavBrand><Link href="/">{messages.text('title')}</Link></NavBrand>
+              <NavBrand>
+                <Link href="/">{messages.text("title")}</Link>
+              </NavBrand>
               <NavGroup align="end">
                 <NavLink href="/">Home</NavLink>
                 <ThemeToggle aria-label="Toggle theme" />

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

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

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

@@ -1,20 +1,19 @@
-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';
+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('/'),
+    route("/", HomePage, {
+      actions: actionsFor("/"),
       meta: {
-        title: '{{appName}}',
-        description: 'A progressive full-stack Askr application.',
-        html: { lang: 'en', dir: 'ltr' },
+        title: "{{appName}}",
+        description: "A progressive full-stack Askr application.",
+        html: { lang: "en", dir: "ltr" },
       },
     });
-    route('/*', NotFoundPage);
+    route("/*", NotFoundPage);
   });
 });
-

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

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

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

@@ -1,12 +1,8 @@
-import { createActionRegistry } from '@askrjs/server/askr';
-import { createMessageAction } from '../actions/create-message';
-import { createMessage } from './actions/create-message';
-import type { AppDependencies } from './dependencies';
+import { handleAction } 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;
+export function createActionHandlers() {
+  return [handleAction(createMessageAction, createMessage)] as const;
 }

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

@@ -1,13 +1,13 @@
-import type { InferSchema } from '@askrjs/schema';
-import { createMessageAction } from '../../actions/create-message';
-import type { AppDependencies } from '../dependencies';
+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'>,
+  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

@@ -1,66 +1,76 @@
-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';
+import { createAuth } from "@askrjs/auth";
+import { createAskrApp } from "@askrjs/server/askr";
+import { csrf, rateLimit, requestId, securityHeaders } from "@askrjs/server/middleware";
+import { pageRegistry } from "../routes";
+import { Message, MessageInput } from "../schemas";
+import { telemetry } from "../telemetry";
+import { createActionHandlers } 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'],
+  return createAskrApp({
+    name: "{{appName}}",
+    version: "1.0.0",
+    dependencies: deps,
+    pages: pageRegistry,
+    api: {
+      define(api) {
+        api
+          .post("/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();
+        api
+          .post("/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: "/",
+            });
+          })
+          .operationId("createSession")
+          .summary("Create a demo session")
+          .seeOther();
       },
     },
-    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);
+    auth: {
+      resolver: createAuth({
+        sessions: deps.sessions,
+        principals: deps.principals,
+        sessionCookie: "askr-session",
+      }),
+    },
+    actions: {
+      handlers: createActionHandlers(),
+      csrf: { secret: process.env.CSRF_SECRET ?? "development-only-secret" },
     },
-  })
-    .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

@@ -13,7 +13,11 @@ export interface AppDependencies {
     record(entry: { action: string; value: string }): Promise<void>;
   };
   readonly rateLimits: {
-    consume(key: string, limit: number, windowMs: number): Promise<{
+    consume(
+      key: string,
+      limit: number,
+      windowMs: number,
+    ): Promise<{
       allowed: boolean;
       remaining: number;
       reset: number;
@@ -25,23 +29,19 @@ 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,
+      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,
+      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;
+        const window =
+          !current || current.reset <= now ? { count: 0, reset: now + windowMs } : current;
         window.count += 1;
         counters.set(key, window);
         return {

package/templates/full-stack/src/server/entry-server.ts

@@ -1,8 +1,8 @@
-import { createApp } from './app';
-import { createDependencies } from './dependencies';
+import { createApp } from "./app";
+import { createDependencies } from "./dependencies";
 
 const app = createApp(createDependencies());
 
 export { app };
-export { telemetry } from '../telemetry';
+export { telemetry } from "../telemetry";
 export default app;

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

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

package/templates/full-stack/src/vite-server.d.ts

@@ -1,6 +1,5 @@
-declare module 'virtual:askr-server' {
-  import type { ServerApp } from '@askrjs/server';
+declare module "virtual:askr-server" {
+  import type { ServerApp } from "@askrjs/server";
   const app: ServerApp;
   export default app;
 }
-