@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/shared/contracts/types/telemetry-envelope.types.ts

@@ -0,0 +1,139 @@
+/**
+ * Telemetry Envelope Types
+ *
+ * TypeScript interfaces for Platform SDK telemetry messages and error reports.
+ * These types mirror the JSON schemas in contracts/schemas/ and provide
+ * compile-time type safety.
+ *
+ * @see contracts/schemas/envelope.v1.schema.json
+ * @see contracts/schemas/error_report.v1.schema.json
+ */
+
+// =============================================================================
+// Telemetry Message Types
+// =============================================================================
+
+/**
+ * Feature metrics payload — maps to FeatureMetrics from consumer SDK.
+ * Each field corresponds to a Cloudflare service metric.
+ */
+export interface TelemetryMetrics {
+  // D1 Database
+  d1Writes?: number;
+  d1Reads?: number;
+  d1RowsRead?: number;
+  d1RowsWritten?: number;
+
+  // KV Namespace
+  kvReads?: number;
+  kvWrites?: number;
+  kvDeletes?: number;
+  kvLists?: number;
+
+  // Workers AI
+  aiRequests?: number;
+  aiNeurons?: number;
+
+  // Vectorize
+  vectorizeQueries?: number;
+  vectorizeInserts?: number;
+
+  // Durable Objects
+  doRequests?: number;
+  doGbSeconds?: number;
+
+  // R2 Storage
+  r2ClassA?: number;
+  r2ClassB?: number;
+
+  // Queues
+  queueMessages?: number;
+
+  // General
+  requests?: number;
+  cpuMs?: number;
+}
+
+/**
+ * Telemetry message envelope — the standard format for SDK telemetry
+ * sent through the platform-telemetry queue.
+ */
+export interface TelemetryEnvelope {
+  /** Fully qualified feature key (project:category:feature) */
+  feature_key: string;
+  /** Project identifier */
+  project: string;
+  /** Feature category within the project */
+  category: string;
+  /** Feature name within the category */
+  feature: string;
+  /** Feature metrics payload */
+  metrics: TelemetryMetrics;
+  /** Unix timestamp in milliseconds when the event occurred */
+  timestamp: number;
+  /** If true, this is a heartbeat message (no metrics, just liveness) */
+  is_heartbeat?: boolean;
+}
+
+// =============================================================================
+// Error Report Types
+// =============================================================================
+
+/** Worker outcome types captured by the error collector */
+export type ErrorOutcome =
+  | 'exception'
+  | 'exceededCpu'
+  | 'exceededMemory'
+  | 'canceled'
+  | 'responseStreamDisconnected'
+  | 'scriptNotFound'
+  | 'soft_error'
+  | 'warning';
+
+/** Priority levels for error reports */
+export type ErrorPriority = 'P0' | 'P1' | 'P2' | 'P3' | 'P4';
+
+/**
+ * Error report structure — captured by the error-collector tail worker
+ * and optionally escalated to GitHub issues.
+ */
+export interface ErrorReport {
+  /** Name of the worker that produced the error */
+  script_name: string;
+  /** Unique error identifier for deduplication */
+  fingerprint: string;
+  /** Error message text */
+  message: string;
+  /** Full stack trace if available */
+  stack_trace?: string;
+  /** Worker outcome type */
+  outcome?: ErrorOutcome;
+  /** Assigned priority level */
+  priority?: ErrorPriority;
+  /** Error category (e.g., unhandled-exception, quota-exhausted) */
+  category?: string;
+  /** Project the error belongs to */
+  project?: string;
+  /** When the error occurred (ISO 8601 UTC) */
+  timestamp?: string;
+  /** Unix timestamp in milliseconds from the tail event */
+  event_timestamp?: number;
+}
+
+// =============================================================================
+// Circuit Breaker Types
+// =============================================================================
+
+/** Circuit breaker states stored in KV */
+export type CircuitBreakerState = 'active' | 'warning' | 'paused';
+
+/**
+ * Circuit breaker KV entry — stored at cb:{project}:{feature} key.
+ */
+export interface CircuitBreakerEntry {
+  state: CircuitBreakerState;
+  tripped_at?: string;
+  reason?: string;
+  d1_writes_24h?: number;
+  d1_limit?: number;
+}

package/templates/shared/dashboard/astro.config.mjs

@@ -0,0 +1,21 @@
+import { defineConfig } from 'astro/config';
+import cloudflare from '@astrojs/cloudflare';
+import tailwind from '@astrojs/tailwind';
+import react from '@astrojs/react';
+
+export default defineConfig({
+  output: 'server',
+  adapter: cloudflare({
+    mode: 'directory',
+    imageService: 'passthrough',
+  }),
+  integrations: [tailwind(), react()],
+  vite: {
+    optimizeDeps: {
+      include: ['react', 'react-dom', 'react-dom/client'],
+    },
+    resolve: {
+      conditions: ['workerd', 'browser', 'import', 'module', 'default'],
+    },
+  },
+});

package/templates/shared/dashboard/package.json.hbs

@@ -0,0 +1,29 @@
+{
+  "name": "{{projectSlug}}-dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "check": "astro check"
+  },
+  "dependencies": {
+    "astro": "^5.0.0",
+    "@astrojs/cloudflare": "^12.0.0",
+    "@astrojs/react": "^4.0.0",
+    "@astrojs/tailwind": "^6.0.0",
+    "clsx": "^2.1.0",
+    "jose": "^5.2.0",
+    "lucide-react": "^0.300.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^3.4.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/shared/dashboard/src/components/Header.astro

@@ -0,0 +1,29 @@
+---
+---
+
+<header class="sticky top-0 z-10 bg-white dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700 px-4 lg:px-6 py-3">
+  <div class="flex items-center justify-between">
+    <div class="lg:hidden">
+      <h1 class="text-lg font-bold text-gray-900 dark:text-white">Platform</h1>
+    </div>
+
+    <div class="flex items-center gap-3 ml-auto">
+      <!-- Dark mode toggle -->
+      <button
+        id="theme-toggle"
+        class="p-2 rounded-md text-gray-500 dark:text-gray-400 hover:bg-gray-100 dark:hover:bg-gray-700"
+        aria-label="Toggle dark mode"
+      >
+        <span id="theme-light" class="hidden dark:inline">Sun</span>
+        <span id="theme-dark" class="dark:hidden">Moon</span>
+      </button>
+    </div>
+  </div>
+</header>
+
+<script is:inline>
+  document.getElementById('theme-toggle')?.addEventListener('click', () => {
+    const isDark = document.documentElement.classList.toggle('dark');
+    localStorage.setItem('theme', isDark ? 'dark' : 'light');
+  });
+</script>

package/templates/shared/dashboard/src/components/Nav.astro.hbs

@@ -0,0 +1,59 @@
+---
+const pathname = Astro.url.pathname;
+
+interface NavItem {
+  href: string;
+  label: string;
+  icon: string;
+}
+
+const navItems: NavItem[] = [
+  { href: '/dashboard', label: 'Overview', icon: 'home' },
+  { href: '/resources', label: 'Resources', icon: 'server' },
+{{#if isStandard}}
+  { href: '/health', label: 'Health', icon: 'activity' },
+  { href: '/errors', label: 'Errors', icon: 'alert-triangle' },
+  { href: '/circuit-breakers', label: 'Breakers', icon: 'zap' },
+{{/if}}
+{{#if isFull}}
+  { href: '/notifications', label: 'Notifications', icon: 'bell' },
+{{/if}}
+  { href: '/settings', label: 'Settings', icon: 'settings' },
+];
+
+function isActive(href: string): boolean {
+  return pathname === href || pathname.startsWith(href + '/');
+}
+---
+
+<aside class="hidden lg:flex lg:flex-col lg:w-56 bg-white dark:bg-gray-800 border-r border-gray-200 dark:border-gray-700">
+  <div class="p-4 border-b border-gray-200 dark:border-gray-700">
+    <h1 class="text-lg font-bold text-gray-900 dark:text-white">Platform</h1>
+    <p class="text-xs text-gray-500 dark:text-gray-400">Dashboard</p>
+  </div>
+
+  <nav class="flex-1 p-3 space-y-1">
+    {navItems.map((item) => (
+      <a
+        href={item.href}
+        class:list={[
+          'flex items-center gap-3 px-3 py-2 rounded-md text-sm transition-colors',
+          isActive(item.href)
+            ? 'bg-blue-50 text-blue-700 dark:bg-blue-900/30 dark:text-blue-300 font-medium'
+            : 'text-gray-600 dark:text-gray-400 hover:bg-gray-50 dark:hover:bg-gray-700/50',
+        ]}
+      >
+        <span class="w-5 h-5 flex items-center justify-center text-current opacity-60">
+          {item.icon === 'home' && '\u2302'}
+          {item.icon === 'server' && '\u229E'}
+          {item.icon === 'activity' && '\u2661'}
+          {item.icon === 'alert-triangle' && '\u25B3'}
+          {item.icon === 'zap' && '\u26A1'}
+          {item.icon === 'bell' && '\uD83D\uDD14'}
+          {item.icon === 'settings' && '\u2699'}
+        </span>
+        {item.label}
+      </a>
+    ))}
+  </nav>
+</aside>

package/templates/shared/dashboard/src/components/infrastructure/AlertHistory.tsx

@@ -0,0 +1,57 @@
+import { useState, useEffect } from 'react';
+import { LoadingSkeleton } from '../ui/LoadingSkeleton';
+import { EmptyState } from '../ui/EmptyState';
+
+interface Alert {
+  id: number;
+  title: string;
+  severity: string;
+  source: string;
+  created_at: string;
+  resolved_at?: string;
+}
+
+export function AlertHistory() {
+  const [alerts, setAlerts] = useState<Alert[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/usage/anomalies?limit=20')
+      .then((r) => r.json())
+      .then((data: { anomalies: Alert[] }) => {
+        setAlerts(data.anomalies ?? []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, []);
+
+  if (loading) return <LoadingSkeleton lines={3} />;
+  if (alerts.length === 0) return <EmptyState title="No alerts" description="No recent alerts or anomalies detected." />;
+
+  const severityColour: Record<string, string> = {
+    critical: 'text-red-600 dark:text-red-400',
+    warning: 'text-yellow-600 dark:text-yellow-400',
+    info: 'text-blue-600 dark:text-blue-400',
+  };
+
+  return (
+    <div className="space-y-2">
+      {alerts.map((a) => (
+        <div
+          key={a.id}
+          className="flex items-start justify-between gap-3 py-2 px-3 bg-white dark:bg-gray-800 rounded border border-gray-200 dark:border-gray-700"
+        >
+          <div className="min-w-0">
+            <p className={`text-sm font-medium ${severityColour[a.severity] ?? 'text-gray-900 dark:text-white'}`}>
+              {a.title}
+            </p>
+            <p className="text-xs text-gray-500 dark:text-gray-400 mt-0.5">{a.source}</p>
+          </div>
+          <span className="text-xs text-gray-400 dark:text-gray-500 shrink-0">
+            {new Date(a.created_at).toLocaleDateString()}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}

package/templates/shared/dashboard/src/components/infrastructure/InfrastructureStats.tsx

@@ -0,0 +1,73 @@
+import { useState, useEffect } from 'react';
+import { LoadingSkeleton } from '../ui/LoadingSkeleton';
+
+interface Stats {
+  services: {
+    total: number;
+    byStatus: Record<string, number>;
+    byType: Record<string, number>;
+    byProject: Record<string, number>;
+  };
+  alerts: {
+    total: number;
+    unacknowledged: number;
+    critical: number;
+  };
+}
+
+export function InfrastructureStats() {
+  const [data, setData] = useState<Stats | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/infrastructure/stats')
+      .then(res => res.json())
+      .then((stats: Stats) => { setData(stats); setLoading(false); })
+      .catch(() => setLoading(false));
+  }, []);
+
+  if (loading) return <LoadingSkeleton lines={4} />;
+
+  if (!data) {
+    return <p className="text-sm text-gray-500 dark:text-gray-400">No infrastructure data available.</p>;
+  }
+
+  const cards = [
+    { label: 'Total Services', value: data.services.total, icon: '\u229E' },
+    { label: 'Deployed', value: data.services.byStatus.deployed ?? 0, icon: '\u2713' },
+    { label: 'Alerts', value: data.alerts.total, icon: '\u25B3' },
+    { label: 'Critical', value: data.alerts.critical, icon: '\u26A0' },
+  ];
+
+  return (
+    <div className="space-y-4">
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-3">
+        {cards.map(card => (
+          <div key={card.label} className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+            <div className="flex items-center gap-2 mb-1">
+              <span className="opacity-50">{card.icon}</span>
+              <span className="text-xs text-gray-500 dark:text-gray-400 uppercase tracking-wide">{card.label}</span>
+            </div>
+            <p className="text-2xl font-bold text-gray-900 dark:text-white">{card.value}</p>
+          </div>
+        ))}
+      </div>
+
+      {Object.keys(data.services.byType).length > 0 && (
+        <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-4">
+          <h3 className="text-sm font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide mb-3">
+            By Resource Type
+          </h3>
+          <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
+            {Object.entries(data.services.byType).map(([type, count]) => (
+              <div key={type} className="flex items-center justify-between py-1">
+                <span className="text-sm text-gray-600 dark:text-gray-300">{type}</span>
+                <span className="text-sm font-medium text-gray-900 dark:text-white">{count}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/templates/shared/dashboard/src/components/infrastructure/ServiceRegistry.tsx

@@ -0,0 +1,55 @@
+import { useState, useEffect } from 'react';
+import { EmptyState } from '../ui/EmptyState';
+import { LoadingSkeleton } from '../ui/LoadingSkeleton';
+
+interface Service {
+  script_name: string;
+  project: string;
+  resource_type: string;
+  last_seen_at?: string;
+}
+
+export function ServiceRegistry() {
+  const [services, setServices] = useState<Service[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/infrastructure/services')
+      .then((r) => r.json())
+      .then((data: { services: Service[] }) => {
+        setServices(data.services ?? []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, []);
+
+  if (loading) return <LoadingSkeleton lines={5} />;
+  if (services.length === 0) return <EmptyState title="No services" description="Register services via services.yaml." />;
+
+  const grouped = services.reduce<Record<string, Service[]>>((acc, s) => {
+    const key = s.project || 'unassigned';
+    (acc[key] ??= []).push(s);
+    return acc;
+  }, {});
+
+  return (
+    <div className="space-y-4">
+      {Object.entries(grouped).map(([project, svcList]) => (
+        <div key={project}>
+          <h4 className="text-xs font-semibold uppercase text-gray-500 dark:text-gray-400 mb-1">{project}</h4>
+          <div className="space-y-1">
+            {svcList.map((s) => (
+              <div
+                key={s.script_name}
+                className="flex items-center justify-between py-1 px-2 text-sm bg-white dark:bg-gray-800 rounded border border-gray-200 dark:border-gray-700"
+              >
+                <span className="font-mono text-gray-900 dark:text-white">{s.script_name}</span>
+                <span className="text-xs text-gray-400 dark:text-gray-500">{s.resource_type}</span>
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/templates/shared/dashboard/src/components/infrastructure/UptimeStatus.tsx

@@ -0,0 +1,56 @@
+import { useState, useEffect } from 'react';
+import { LoadingSkeleton } from '../ui/LoadingSkeleton';
+
+interface ServiceStatus {
+  name: string;
+  status: 'healthy' | 'degraded' | 'down' | 'unknown';
+  lastCheck: string;
+  uptimePct?: number;
+}
+
+export function UptimeStatus() {
+  const [services, setServices] = useState<ServiceStatus[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    fetch('/api/infrastructure/services')
+      .then((r) => r.json())
+      .then((data: { services: ServiceStatus[] }) => {
+        setServices(data.services ?? []);
+        setLoading(false);
+      })
+      .catch(() => setLoading(false));
+  }, []);
+
+  if (loading) return <LoadingSkeleton lines={3} />;
+
+  const statusColour: Record<string, string> = {
+    healthy: 'bg-green-500',
+    degraded: 'bg-yellow-500',
+    down: 'bg-red-500',
+    unknown: 'bg-gray-400',
+  };
+
+  return (
+    <div className="space-y-2">
+      {services.length === 0 ? (
+        <p className="text-sm text-gray-500 dark:text-gray-400">No service data available.</p>
+      ) : (
+        services.map((s) => (
+          <div
+            key={s.name}
+            className="flex items-center justify-between py-1.5 px-3 bg-white dark:bg-gray-800 rounded border border-gray-200 dark:border-gray-700"
+          >
+            <div className="flex items-center gap-2">
+              <span className={`w-2 h-2 rounded-full ${statusColour[s.status] ?? statusColour.unknown}`} />
+              <span className="text-sm text-gray-900 dark:text-white">{s.name}</span>
+            </div>
+            {s.uptimePct !== undefined && (
+              <span className="text-xs text-gray-500 dark:text-gray-400">{s.uptimePct.toFixed(1)}%</span>
+            )}
+          </div>
+        ))
+      )}
+    </div>
+  );
+}

package/templates/shared/dashboard/src/components/infrastructure/index.ts

@@ -0,0 +1,4 @@
+export { InfrastructureStats } from './InfrastructureStats';
+export { UptimeStatus } from './UptimeStatus';
+export { ServiceRegistry } from './ServiceRegistry';
+export { AlertHistory } from './AlertHistory';

package/templates/shared/dashboard/src/components/overview/ActivityFeed.tsx

@@ -0,0 +1,134 @@
+/**
+ * Activity Feed Quadrant - Mission Control
+ * Shows last 5 notifications, pending patterns count, recent alerts
+ */
+
+interface ActivityData {
+  notifications: Array<{
+    id: string;
+    title: string;
+    category: string;
+    priority: string;
+    source: string;
+    created_at: number;
+    action_url: string | null;
+  }>;
+  pendingPatterns: number;
+}
+
+interface Props {
+  data: ActivityData;
+  loading: boolean;
+}
+
+const categoryLabels: Record<string, string> = {
+  error: '[ERR]',
+  warning: '[WARN]',
+  info: '[INFO]',
+  success: '[OK]',
+};
+
+const sourceLabels: Record<string, string> = {
+  'error-collector': 'Error',
+  'pattern-discovery': 'Pattern',
+  'circuit-breaker': 'CB',
+  usage: 'Usage',
+  gatus: 'Monitor',
+  system: 'System',
+};
+
+function formatTimestamp(ts: number): string {
+  if (!ts) return '';
+  const now = Date.now();
+  const diffMs = now - ts * 1000;
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return 'Just now';
+  if (diffMins < 60) return `${diffMins}m`;
+  if (diffHours < 24) return `${diffHours}h`;
+  if (diffDays < 7) return `${diffDays}d`;
+  return new Date(ts * 1000).toLocaleDateString('en-AU', { day: 'numeric', month: 'short' });
+}
+
+export function ActivityFeed({ data, loading }: Props) {
+  if (loading) {
+    return <QuadrantSkeleton />;
+  }
+
+  return (
+    <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-5">
+      <div className="flex items-center justify-between mb-4">
+        <h3 className="text-sm font-medium text-gray-500 dark:text-gray-400 uppercase tracking-wide">
+          Activity
+        </h3>
+        {data.pendingPatterns > 0 && (
+          <span className="text-xs px-2 py-1 rounded-full bg-purple-100 text-purple-700 dark:bg-purple-900/40 dark:text-purple-300">
+            {data.pendingPatterns} pattern{data.pendingPatterns !== 1 ? 's' : ''} pending
+          </span>
+        )}
+      </div>
+
+      {data.notifications.length > 0 ? (
+        <div className="space-y-3">
+          {data.notifications.map((n) => (
+            <div key={n.id} className="flex items-start gap-2">
+              <span className="text-xs font-mono flex-shrink-0 mt-0.5 text-gray-500 dark:text-gray-400">
+                {categoryLabels[n.category] ?? '[INFO]'}
+              </span>
+              <div className="flex-1 min-w-0">
+                <div className="text-sm text-gray-900 dark:text-white truncate">
+                  {n.action_url ? (
+                    <a
+                      href={n.action_url}
+                      className="hover:text-blue-600 dark:hover:text-blue-400"
+                      onClick={(e) => e.stopPropagation()}
+                    >
+                      {n.title}
+                    </a>
+                  ) : (
+                    n.title
+                  )}
+                </div>
+                <div className="flex items-center gap-2 text-xs text-gray-500 dark:text-gray-400 mt-0.5">
+                  <span>{sourceLabels[n.source] ?? n.source}</span>
+                  <span>&middot;</span>
+                  <span>{formatTimestamp(n.created_at)}</span>
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : (
+        <div className="text-center py-4 text-sm text-gray-500 dark:text-gray-400">
+          No recent activity
+        </div>
+      )}
+
+      <div className="mt-4 pt-3 border-t border-gray-100 dark:border-gray-700">
+        <a
+          href="/notifications"
+          className="text-xs text-blue-600 dark:text-blue-400 hover:underline"
+        >
+          View all notifications &rarr;
+        </a>
+      </div>
+    </div>
+  );
+}
+
+function QuadrantSkeleton() {
+  return (
+    <div className="bg-white dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700 p-5">
+      <div className="animate-pulse space-y-3">
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-16" />
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-full" />
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-3/4" />
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-full" />
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-2/3" />
+        <div className="h-4 bg-gray-200 dark:bg-gray-700 rounded w-5/6" />
+      </div>
+    </div>
+  );
+}