@sansavision/aurora 0.1.0-alpha.20260212.4

package/templates/dashboard/src/queries/getDashboardMetrics.server.ts

@@ -0,0 +1,30 @@
+export interface MetricPoint {
+  label: string;
+  value: number;
+}
+
+export interface GridRow {
+  id: string;
+  service: string;
+  status: "healthy" | "degraded" | "incident";
+}
+
+export interface DashboardMetrics {
+  series: MetricPoint[];
+  rows: GridRow[];
+  pendingAlerts: number;
+}
+
+export async function getDashboardMetrics(): Promise<DashboardMetrics> {
+  return {
+    series: [
+      { label: "Requests", value: 1240 },
+      { label: "Errors", value: 12 },
+    ],
+    rows: [
+      { id: "svc-api", service: "api", status: "healthy" },
+      { id: "svc-search", service: "search", status: "degraded" },
+    ],
+    pendingAlerts: 1,
+  };
+}

package/templates/dashboard/src/realtime/useDashboardRealtime.client.ts

@@ -0,0 +1,13 @@
+export interface DashboardRealtimeEvent {
+  type: "metrics-updated" | "alert-created" | "alert-acknowledged";
+  timestamp: number;
+}
+
+export function useDashboardRealtime(
+  onEvent: (event: DashboardRealtimeEvent) => void,
+): () => void {
+  const dispose = () => {
+    void onEvent;
+  };
+  return dispose;
+}

package/templates/dashboard/src/routes/index.tsx

@@ -0,0 +1,19 @@
+import { acknowledgeAlert } from "../actions/acknowledgeAlert.action.server";
+import { getDashboardMetrics } from "../queries/getDashboardMetrics.server";
+import { renderDataGrid } from "../widgets/DataGrid.client";
+import { renderMetricChart } from "../widgets/MetricChart.client";
+import { useDashboardRealtime } from "../realtime/useDashboardRealtime.client";
+
+export async function HomePage(): Promise<string> {
+  const metrics = await getDashboardMetrics();
+  const chart = renderMetricChart(metrics.series);
+  const grid = renderDataGrid(metrics.rows);
+  const unsubscribe = useDashboardRealtime(() => undefined);
+
+  if (metrics.pendingAlerts > 0) {
+    await acknowledgeAlert("alert-1");
+  }
+
+  unsubscribe();
+  return `<main><h1>Aurora Dashboard Starter</h1>${chart}${grid}</main>`;
+}

package/templates/dashboard/src/widgets/DataGrid.client.ts

@@ -0,0 +1,8 @@
+import { type GridRow } from "../queries/getDashboardMetrics.server";
+
+export function renderDataGrid(rows: ReadonlyArray<GridRow>): string {
+  const body = rows
+    .map((row) => `<tr><td>${row.service}</td><td>${row.status}</td></tr>`)
+    .join("");
+  return `<section data-widget="data-grid"><h2>Data Grid</h2><table><thead><tr><th>Service</th><th>Status</th></tr></thead><tbody>${body}</tbody></table></section>`;
+}

package/templates/dashboard/src/widgets/MetricChart.client.ts

@@ -0,0 +1,8 @@
+import { type MetricPoint } from "../queries/getDashboardMetrics.server";
+
+export function renderMetricChart(series: ReadonlyArray<MetricPoint>): string {
+  const points = series
+    .map((point) => `<li>${point.label}: ${point.value}</li>`)
+    .join("");
+  return `<section data-widget="metric-chart"><h2>Metric Chart</h2><ul>${points}</ul></section>`;
+}

package/templates/desktop/README.md

@@ -0,0 +1,18 @@
+# __AURORA_APP_NAME__
+
+Template: desktop
+
+Aurora desktop starter template.
+
+Includes:
+
+- Tauri bridge wiring seam for desktop shell calls
+- secure local storage abstraction seam
+- offline-safe sync boundary with queued operation planning
+- query + action example for desktop settings state
+
+## Commands
+
+- `aurora dev`
+- `aurora build --target node`
+- `aurora start`

package/templates/desktop/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "__AURORA_APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "aurora dev",
+    "build": "aurora build --target node",
+    "start": "aurora start",
+    "test": "aurora test"
+  }
+}

package/templates/desktop/src/actions/saveDesktopPreference.action.server.ts

@@ -0,0 +1,28 @@
+import { getDesktopSyncStatus } from "../queries/getDesktopSyncStatus.server";
+import { planOfflineSync } from "../sync/offlineSyncBoundary.server";
+
+export interface SaveDesktopPreferenceInput {
+  key: string;
+  value: string;
+}
+
+export interface SaveDesktopPreferenceResult {
+  ok: true;
+  key: string;
+  value: string;
+  syncMode: "immediate" | "queued";
+}
+
+export async function saveDesktopPreference(
+  input: SaveDesktopPreferenceInput,
+): Promise<SaveDesktopPreferenceResult> {
+  const syncStatus = await getDesktopSyncStatus();
+  const syncPlan = planOfflineSync(syncStatus);
+
+  return {
+    ok: true,
+    key: input.key,
+    value: input.value,
+    syncMode: syncPlan.mode,
+  };
+}

package/templates/desktop/src/desktop/secureStorage.client.ts

@@ -0,0 +1,20 @@
+import type { TauriBridge } from "./tauriBridge.client";
+
+export interface SecureStorage {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+}
+
+export function createSecureStorage(bridge: TauriBridge): SecureStorage {
+  return {
+    async get(key: string): Promise<string | null> {
+      const result = await bridge.invoke<{ value?: string | null }>("secure_storage_get", {
+        key,
+      });
+      return result.value ?? null;
+    },
+    async set(key: string, value: string): Promise<void> {
+      await bridge.invoke("secure_storage_set", { key, value });
+    },
+  };
+}

package/templates/desktop/src/desktop/tauriBridge.client.ts

@@ -0,0 +1,14 @@
+export interface TauriBridge {
+  invoke<T>(command: string, payload?: Record<string, unknown>): Promise<T>;
+}
+
+export function createTauriBridge(): TauriBridge {
+  return {
+    async invoke<T>(command: string, payload: Record<string, unknown> = {}): Promise<T> {
+      return {
+        command,
+        payload,
+      } as T;
+    },
+  };
+}

package/templates/desktop/src/queries/getDesktopSyncStatus.server.ts

@@ -0,0 +1,9 @@
+import type { OfflineSyncStatus } from "../sync/offlineSyncBoundary.server";
+
+export async function getDesktopSyncStatus(): Promise<OfflineSyncStatus> {
+  return {
+    lastSyncedAt: 1707609600000,
+    pendingOperations: 2,
+    offlineMode: true,
+  };
+}

package/templates/desktop/src/routes/index.tsx

@@ -0,0 +1,27 @@
+import { saveDesktopPreference } from "../actions/saveDesktopPreference.action.server";
+import { createSecureStorage } from "../desktop/secureStorage.client";
+import { createTauriBridge } from "../desktop/tauriBridge.client";
+import { getDesktopSyncStatus } from "../queries/getDesktopSyncStatus.server";
+import { planOfflineSync } from "../sync/offlineSyncBoundary.server";
+
+export async function HomePage(): Promise<string> {
+  const syncStatus = await getDesktopSyncStatus();
+  const syncPlan = planOfflineSync(syncStatus);
+
+  const bridge = createTauriBridge();
+  const secureStorage = createSecureStorage(bridge);
+  await secureStorage.set("desktop-theme", "system");
+
+  await saveDesktopPreference({
+    key: "window.startupView",
+    value: "dashboard",
+  });
+
+  return [
+    "<main>",
+    "<h1>Aurora Desktop Starter</h1>",
+    `<p>sync_mode: ${syncPlan.mode}</p>`,
+    `<p>pending_operations: ${syncStatus.pendingOperations}</p>`,
+    "</main>",
+  ].join("");
+}

package/templates/desktop/src/sync/offlineSyncBoundary.server.ts

@@ -0,0 +1,27 @@
+export interface OfflineSyncStatus {
+  lastSyncedAt: number;
+  pendingOperations: number;
+  offlineMode: boolean;
+}
+
+export interface OfflineSyncPlan {
+  mode: "immediate" | "queued";
+  queuedOperationLimit: number;
+  reason: string;
+}
+
+export function planOfflineSync(status: OfflineSyncStatus): OfflineSyncPlan {
+  if (!status.offlineMode && status.pendingOperations === 0) {
+    return {
+      mode: "immediate",
+      queuedOperationLimit: 0,
+      reason: "network-online",
+    };
+  }
+
+  return {
+    mode: "queued",
+    queuedOperationLimit: 100,
+    reason: status.offlineMode ? "offline-mode" : "pending-operations",
+  };
+}

package/templates/feature-skeleton/README.md

@@ -0,0 +1,13 @@
+# Aurora Feature Skeleton
+
+This skeleton is used by `AUR-TPL-004` to define the canonical feature module layout for:
+
+- UI (`ui/*.client.tsx`)
+- Query layer (`queries/*.server.ts`)
+- Action layer (`actions/*.action.server.ts`)
+- Realtime hooks (`realtime/*.client.ts`)
+
+Placeholders:
+
+- `__AURORA_FEATURE_NAME__` for display-oriented naming
+- `__AURORA_FEATURE_SLUG__` for route/cache key style naming

package/templates/feature-skeleton/actions/createFeature.action.server.ts

@@ -0,0 +1,19 @@
+export interface Create__AURORA_FEATURE_NAME__Input {
+  label: string;
+}
+
+export interface __AURORA_FEATURE_NAME__Record {
+  id: string;
+  label: string;
+  createdAt: number;
+}
+
+export async function create__AURORA_FEATURE_NAME__(
+  input: Create__AURORA_FEATURE_NAME__Input,
+): Promise<__AURORA_FEATURE_NAME__Record> {
+  return {
+    id: `__AURORA_FEATURE_SLUG__-${Date.now()}`,
+    label: input.label,
+    createdAt: Date.now(),
+  };
+}

package/templates/feature-skeleton/index.ts

@@ -0,0 +1,8 @@
+const FEATURE_SLUG = "__AURORA_FEATURE_SLUG__";
+
+export { FeatureView } from "./ui/FeatureView.client";
+export { list__AURORA_FEATURE_NAME__ } from "./queries/listFeature.server";
+export { create__AURORA_FEATURE_NAME__ } from "./actions/createFeature.action.server";
+export { use__AURORA_FEATURE_NAME__Realtime } from "./realtime/useFeatureRealtime.client";
+
+void FEATURE_SLUG;

package/templates/feature-skeleton/queries/listFeature.server.ts

@@ -0,0 +1,15 @@
+export interface __AURORA_FEATURE_NAME__Record {
+  id: string;
+  label: string;
+  createdAt: number;
+}
+
+export async function list__AURORA_FEATURE_NAME__(): Promise<__AURORA_FEATURE_NAME__Record[]> {
+  return [
+    {
+      id: "__AURORA_FEATURE_SLUG__-seed-1",
+      label: "seed item",
+      createdAt: 1707609600000,
+    },
+  ];
+}

package/templates/feature-skeleton/realtime/useFeatureRealtime.client.ts

@@ -0,0 +1,16 @@
+export interface FeatureRealtimeEvent {
+  type: "created" | "updated" | "deleted";
+  entityId: string;
+}
+
+const FEATURE_CHANNEL = "__AURORA_FEATURE_SLUG__";
+
+export function use__AURORA_FEATURE_NAME__Realtime(
+  onEvent: (event: FeatureRealtimeEvent) => void,
+): () => void {
+  const dispose = () => {
+    void onEvent;
+    void FEATURE_CHANNEL;
+  };
+  return dispose;
+}

package/templates/feature-skeleton/template.manifest.json

@@ -0,0 +1,15 @@
+{
+  "template": "feature-skeleton",
+  "version": 1,
+  "placeholders": [
+    "__AURORA_FEATURE_NAME__",
+    "__AURORA_FEATURE_SLUG__"
+  ],
+  "modules": [
+    "ui/FeatureView.client.tsx",
+    "queries/listFeature.server.ts",
+    "actions/createFeature.action.server.ts",
+    "realtime/useFeatureRealtime.client.ts",
+    "index.ts"
+  ]
+}

package/templates/feature-skeleton/ui/FeatureView.client.tsx

@@ -0,0 +1,14 @@
+export interface __AURORA_FEATURE_NAME__Item {
+  id: string;
+  label: string;
+  createdAt: number;
+}
+
+export interface FeatureViewProps {
+  items: ReadonlyArray<__AURORA_FEATURE_NAME__Item>;
+  onCreate: (label: string) => Promise<void>;
+}
+
+export function FeatureView(props: FeatureViewProps): string {
+  return `<section data-feature="__AURORA_FEATURE_SLUG__"><h2>__AURORA_FEATURE_NAME__</h2><p>items: ${props.items.length}</p></section>`;
+}

package/templates/mobile/README.md

@@ -0,0 +1,17 @@
+# __AURORA_APP_NAME__
+
+Template: mobile
+
+Aurora mobile companion starter template.
+
+Includes:
+
+- generated typed API client usage seam (`src/mobile/generated/mobile-api-sdk.ts`)
+- auth token/session handoff strategy for mobile client state (`src/mobile/auth/session-handoff.client.ts`)
+- retry-aware transport for network-limited conditions (`src/mobile/transport/mobile-api-transport.client.ts`)
+
+## Commands
+
+- `aurora dev`
+- `aurora build --target node`
+- `aurora start`

package/templates/mobile/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "__AURORA_APP_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "aurora dev",
+    "build": "aurora build --target node",
+    "start": "aurora start",
+    "test": "aurora test"
+  }
+}

package/templates/mobile/src/mobile/auth/session-handoff.client.ts

@@ -0,0 +1,69 @@
+const TOKEN_STORAGE_KEY = "aurora.mobile.session.token";
+
+export interface MobileSessionToken {
+  token: string;
+  expiresAt: number | null;
+}
+
+export function readSessionToken(): MobileSessionToken | null {
+  const storage = resolveStorage();
+  if (!storage) {
+    return null;
+  }
+
+  const raw = storage.getItem(TOKEN_STORAGE_KEY);
+  if (!raw) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(raw) as MobileSessionToken;
+    if (typeof parsed.token !== "string" || parsed.token.trim().length === 0) {
+      return null;
+    }
+
+    if (parsed.expiresAt !== null && typeof parsed.expiresAt !== "number") {
+      return null;
+    }
+
+    return {
+      token: parsed.token,
+      expiresAt: parsed.expiresAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeSessionToken(token: string, expiresAt: number | null): void {
+  const storage = resolveStorage();
+  if (!storage) {
+    return;
+  }
+
+  const normalizedToken = token.trim();
+  if (normalizedToken.length === 0) {
+    storage.removeItem(TOKEN_STORAGE_KEY);
+    return;
+  }
+
+  storage.setItem(
+    TOKEN_STORAGE_KEY,
+    JSON.stringify({
+      token: normalizedToken,
+      expiresAt,
+    }),
+  );
+}
+
+function resolveStorage(): Storage | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}

package/templates/mobile/src/mobile/generated/mobile-api-sdk.ts

@@ -0,0 +1,62 @@
+export interface MobileMessageRecord {
+  id: string;
+  text: string;
+  createdAt: number;
+}
+
+export interface MobileActionTypes {
+  "messages.create": {
+    input: {
+      text: string;
+    };
+    result: MobileMessageRecord;
+  };
+}
+
+export interface MobileQueryTypes {
+  "messages.list": {
+    params: {
+      cursor: string | null;
+      limit: number;
+    };
+    result: {
+      items: MobileMessageRecord[];
+      nextCursor: string | null;
+    };
+  };
+}
+
+export interface MobileApiTransport {
+  callAction<TName extends keyof MobileActionTypes>(
+    name: TName,
+    input: MobileActionTypes[TName]["input"],
+  ): Promise<MobileActionTypes[TName]["result"]>;
+  callQuery<TName extends keyof MobileQueryTypes>(
+    name: TName,
+    params: MobileQueryTypes[TName]["params"],
+  ): Promise<MobileQueryTypes[TName]["result"]>;
+}
+
+export interface MobileApiClient {
+  actions: {
+    [TName in keyof MobileActionTypes]: (
+      input: MobileActionTypes[TName]["input"],
+    ) => Promise<MobileActionTypes[TName]["result"]>;
+  };
+  queries: {
+    [TName in keyof MobileQueryTypes]: (
+      params: MobileQueryTypes[TName]["params"],
+    ) => Promise<MobileQueryTypes[TName]["result"]>;
+  };
+}
+
+export function createMobileApiClient(transport: MobileApiTransport): MobileApiClient {
+  return {
+    actions: {
+      "messages.create": (input) => transport.callAction("messages.create", input),
+    },
+    queries: {
+      "messages.list": (params) => transport.callQuery("messages.list", params),
+    },
+  };
+}

package/templates/mobile/src/mobile/transport/mobile-api-transport.client.ts

@@ -0,0 +1,122 @@
+import type {
+  MobileActionTypes,
+  MobileApiTransport,
+  MobileQueryTypes,
+} from "../generated/mobile-api-sdk";
+import { readSessionToken } from "../auth/session-handoff.client";
+
+export interface MobileTransportOptions {
+  baseUrl: string;
+  retries?: number;
+  retryDelayMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+interface MobileResponseEnvelope<TData> {
+  data: TData;
+  tags?: string[];
+}
+
+export function createHttpMobileTransport(
+  options: MobileTransportOptions,
+): MobileApiTransport {
+  const fetchImpl = options.fetchImpl ?? fetch;
+
+  return {
+    callAction: async <TName extends keyof MobileActionTypes>(
+      name: TName,
+      input: MobileActionTypes[TName]["input"],
+    ): Promise<MobileActionTypes[TName]["result"]> => {
+      const envelope = await postJsonWithRetry<MobileActionTypes[TName]["result"]>(
+        fetchImpl,
+        `${normalizeBaseUrl(options.baseUrl)}/mobile/action`,
+        {
+          operation: "action",
+          name,
+          input,
+          session: readSessionToken(),
+        },
+        {
+          retries: options.retries ?? 2,
+          retryDelayMs: options.retryDelayMs ?? 75,
+        },
+      );
+
+      return envelope.data;
+    },
+    callQuery: async <TName extends keyof MobileQueryTypes>(
+      name: TName,
+      params: MobileQueryTypes[TName]["params"],
+    ): Promise<MobileQueryTypes[TName]["result"]> => {
+      const envelope = await postJsonWithRetry<MobileQueryTypes[TName]["result"]>(
+        fetchImpl,
+        `${normalizeBaseUrl(options.baseUrl)}/mobile/query`,
+        {
+          operation: "query",
+          name,
+          params,
+          session: readSessionToken(),
+        },
+        {
+          retries: options.retries ?? 2,
+          retryDelayMs: options.retryDelayMs ?? 75,
+        },
+      );
+
+      return envelope.data;
+    },
+  };
+}
+
+async function postJsonWithRetry<TData>(
+  fetchImpl: typeof fetch,
+  url: string,
+  payload: unknown,
+  retryPolicy: {
+    retries: number;
+    retryDelayMs: number;
+  },
+): Promise<MobileResponseEnvelope<TData>> {
+  const maxAttempts = Math.max(1, retryPolicy.retries + 1);
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok) {
+        if (response.status >= 500 && attempt < maxAttempts) {
+          await sleep(retryPolicy.retryDelayMs * attempt);
+          continue;
+        }
+
+        throw new Error(`mobile transport request failed: ${response.status}`);
+      }
+
+      const parsed = (await response.json()) as MobileResponseEnvelope<TData>;
+      return parsed;
+    } catch (error) {
+      if (attempt >= maxAttempts) {
+        throw error;
+      }
+
+      await sleep(retryPolicy.retryDelayMs * attempt);
+    }
+  }
+
+  throw new Error("mobile transport retries exhausted");
+}
+
+function normalizeBaseUrl(value: string): string {
+  const normalized = value.trim().replace(/\/+$/, "");
+  return normalized.length > 0 ? normalized : "https://example.invalid";
+}
+
+function sleep(durationMs: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, durationMs));
+}