spine-framework 0.3.125 → 0.3.126

package/.framework/src/pages/admin/MinimalShadcnTestPage.tsx

@@ -1,17 +1,41 @@
-/**
- * @module src/pages/admin/MinimalShadcnTestPage
- * @audience installer
- * @layer frontend-page
- * @stability testing
- *
- * Minimal test page with basic shadcn components to isolate import issues.
- */
 
+
+
+
+// CIL[BEGIN chunk_id="minimalshadcntestpage_module_header_1783666257" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React dependencies and UI components"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import all required modules for MinimalShadcnTestPage component"]
+// CIL[DOC-CONTEXT module="MinimalShadcnTestPage" layer="ui" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks, UI components" errors="Import errors" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React and basic shadcn UI components for testing" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import { useState } from 'react'
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../../components/ui/card'
 import { Button } from '../../components/ui/button'
 import { Badge } from '../../components/ui/badge'
-
+// CIL[END chunk_id="minimalshadcntestpage_module_header_1783666257"]
+// CIL[BEGIN chunk_id="minimalshadcntestpage_function_minimalshadcntestpage_1783666257" type="function" identity="MinimalShadcnTestPage" parent="none"]
+// CIL[DOC-MACRO purpose="Main MinimalShadcnTestPage component function"]
+// CIL[DOC-RESPONSIBILITY responsibility="Render test interface for shadcn UI components"]
+// CIL[DOC-CONTEXT module="MinimalShadcnTestPage" layer="ui" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX element" errors="Render errors" side_effects="State updates"]
+// CIL[DOC-MICRO logic_summary="Test component that demonstrates basic shadcn components functionality" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: ui. Direct callers: 0. Direct calls: 0. Related files: .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, custom/apps/cortex/functions/custom_cil-embeddings.ts, custom/apps/portal/pages/ContentPage.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function MinimalShadcnTestPage() {
   const [count, setCount] = useState(0)
 
@@ -83,3 +107,4 @@ export function MinimalShadcnTestPage() {
     </div>
   )
 }
+// CIL[END chunk_id="minimalshadcntestpage_function_minimalshadcntestpage_1783666257"]

package/.framework/src/pages/admin/ObservabilityDashboard.tsx

@@ -1,19 +1,23 @@
-/**
- * @module src/pages/admin/ObservabilityDashboard
- * @audience installer
- * @layer frontend-page
- * @stability stable
- *
- * System observability dashboard. Fetches aggregated metrics from
- * `/api/admin-data?action=metrics` and renders time-series line charts,
- * bar charts, and pie charts using `recharts`. Covers request rates,
- * error rates, pipeline execution counts, and resource utilisation.
- * Data is re-fetched on a configurable auto-refresh interval.
- *
- * @seeAlso src/pages/admin/LogsPage.tsx
- * @seeAlso src/pages/admin/AlertsConfigPage.tsx
- */
 
+
+
+
+
+// CIL[BEGIN chunk_id="observabilitydashboard_module_header_1783666257" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React dependencies and chart libraries"]
+// CIL[DOC-RESPONSIBILITY responsibility="Import all required modules for ObservabilityDashboard component"]
+// CIL[DOC-CONTEXT module="ObservabilityDashboard" layer="ui" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React hooks, chart components, utilities" errors="Import errors" side_effects="Module loading"]
+// CIL[DOC-MICRO logic_summary="Imports React, Recharts components, icons, and utility functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developer"]
+// CIL[DOC-VECTOR type="context" content="Layer: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React, { useState, useEffect, useMemo } from 'react'
 import {
   LineChart,
@@ -36,7 +40,22 @@ import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
 import { formatDateTime } from '../../lib/utils'
 import { Link } from 'react-router-dom'
-
+import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END chunk_id="observabilitydashboard_module_header_1783666257"]
+// CIL[BEGIN chunk_id="observabilitydashboard_interfaces_1783666257" type="interfaces" identity="MetricData" parent="none"]
+// CIL[DOC-MACRO purpose="Define observability data structures"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type definitions for dashboard metrics and events"]
+// CIL[DOC-CONTEXT module="ObservabilityDashboard" layer="types" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definitions" errors="Type errors" side_effects="Type system"]
+// CIL[DOC-MICRO logic_summary="Defines interfaces for metrics, errors, latency, pipelines, actors, and alerts" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: types. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/cortex/functions/custom_cil-embeddings.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface MetricData {
   bucket: string
   count: number
@@ -76,7 +95,21 @@ interface AlertEvent {
 }
 
 const COLORS = ['#3b82f6', '#10b981', '#f59e0b', '#ef4444', '#8b5cf6']
-
+// CIL[END chunk_id="observabilitydashboard_interfaces_1783666257"]
+// CIL[BEGIN chunk_id="observabilitydashboard_function_observabilitydashboard_1783666257" type="function" identity="ObservabilityDashboard" parent="none"]
+// CIL[DOC-MACRO purpose="Render the complete observability dashboard interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Main render logic for observability dashboard page"]
+// CIL[DOC-CONTEXT module="ObservabilityDashboard" layer="ui" related_files="[\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/components/ui/table-primitives.tsx\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="JSX structure" errors="Render errors" side_effects="DOM updates"]
+// CIL[DOC-MICRO logic_summary="Renders header, stats cards, charts, and alerts sections" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: ui. Direct callers: 0. Direct calls: 0. Related files: custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.ts, .framework/src/components/ui/table-primitives.tsx."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function ObservabilityDashboard() {
   const [timeRange, setTimeRange] = useState<'1h' | '24h' | '7d'>('24h')
   const [refreshInterval, setRefreshInterval] = useState(30)
@@ -101,7 +134,21 @@ export function ObservabilityDashboard() {
     }
   }, [timeRange])
 
-  // Event volume data
+  
+  // CIL[BEGIN chunk_id="observabilitydashboard_hooks_1783666257" type="hooks" identity="useApi" parent="observabilitydashboard_function_observabilitydashboard_1783666257"]
+// CIL[DOC-MACRO purpose="Fetch observability data from multiple API endpoints"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle useApi"]
+// CIL[DOC-CONTEXT module="ObservabilityDashboard" layer="data" related_files="[\".framework/src/pages/admin/IntegrationsPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="metrics data arrays" errors="API errors" side_effects="HTTP requests, auto-refresh"]
+// CIL[DOC-MICRO logic_summary="Uses multiple useApi hooks to fetch various metrics with auto-refresh" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: data. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/IntegrationsPage.tsx, .framework/functions/_shared/schema-utils.ts, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
   const { data: eventVolume, loading: loadingVolume, refetch: refetchVolume } = useApi<MetricData[]>(
     async () => {
       const bucket = timeRange === '1h' ? 'minute' : timeRange === '24h' ? 'hour' : 'day'
@@ -123,7 +170,7 @@ export function ObservabilityDashboard() {
     { immediate: true, deps: [timeRange] }
   )
 
-  // Error rate data
+  
   const { data: errorRate, loading: loadingError, refetch: refetchError } = useApi<ErrorRateData>(
     async () => {
       const response = await apiFetch(
@@ -136,7 +183,7 @@ export function ObservabilityDashboard() {
     { immediate: true, deps: [timeRange] }
   )
 
-  // Latency percentiles
+  
   const { data: latency, loading: loadingLatency, refetch: refetchLatency } = useApi<LatencyData>(
     async () => {
       const response = await apiFetch(
@@ -149,7 +196,7 @@ export function ObservabilityDashboard() {
     { immediate: true, deps: [timeRange] }
   )
 
-  // Pipeline stats
+  
   const { data: pipelineStats, loading: loadingPipelines, refetch: refetchPipelines } = useApi<PipelineStats[]>(
     async () => {
       const response = await apiFetch(
@@ -162,7 +209,7 @@ export function ObservabilityDashboard() {
     { immediate: true, deps: [timeRange] }
   )
 
-  // Top actors
+  
   const { data: topActors, loading: loadingActors, refetch: refetchActors } = useApi<TopActor[]>(
     async () => {
       const response = await apiFetch(
@@ -175,7 +222,7 @@ export function ObservabilityDashboard() {
     { immediate: true, deps: [timeRange] }
   )
 
-  // Recent alerts
+  
   const { data: recentAlerts } = useApi<AlertEvent[]>(
     async () => {
       const response = await apiFetch('/api/logs?action=account&event=threshold.breached&limit=5')
@@ -186,7 +233,7 @@ export function ObservabilityDashboard() {
     { immediate: true }
   )
 
-  // Auto refresh
+  
   useEffect(() => {
     const interval = setInterval(() => {
       refetchVolume()
@@ -197,7 +244,22 @@ export function ObservabilityDashboard() {
     }, refreshInterval * 1000)
     return () => clearInterval(interval)
   }, [refreshInterval])
+// CIL[END chunk_id="observabilitydashboard_hooks_1783666257"]
 
+  // CIL[BEGIN chunk_id="observabilitydashboard_computed_1783666257" type="computed_values" identity="pipelineChartData" parent="observabilitydashboard_function_observabilitydashboard_1783666257"]
+// CIL[DOC-MACRO purpose="Compute derived values and stats cards"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle pipelineChartData"]
+// CIL[DOC-CONTEXT module="ObservabilityDashboard" layer="logic" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="computed values, stats cards" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Transforms raw data into chart format and creates stats cards" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: logic. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/components/ui/dialog.tsx, \."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
   const pipelineChartData = useMemo(() => {
     return (pipelineStats || []).map((stat) => ({
       name: stat.pipeline_id.slice(0, 8),
@@ -247,7 +309,22 @@ export function ObservabilityDashboard() {
     refetchPipelines()
     refetchActors()
   }
+// CIL[END chunk_id="observabilitydashboard_computed_1783666257"]
 
+  // CIL[BEGIN chunk_id="observabilitydashboard_render_1783666257" type="render_logic" identity="return" parent="observabilitydashboard_function_observabilitydashboard_1783666257"]
+// CIL[DOC-MACRO purpose="Render the complete observability dashboard interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle return"]
+// CIL[DOC-CONTEXT module="return" layer="unknown" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Implements return" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: unknown. Direct callers: 0. Direct calls: 0. Related files: none."]
+// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
+// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
+// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
   return (
     <div className="space-y-6">
       {/* Header */}
@@ -281,6 +358,16 @@ export function ObservabilityDashboard() {
         </div>
       </div>
 
+      <PageInstructions
+        description="Review observability metrics and trace summaries."
+        sections={[
+          { title: 'What this page is for', content: 'This page shows real-time metrics for event volume, error rates, latency percentiles, and pipeline execution.' },
+          { title: 'How to read the cards', content: 'The stats cards show Total Events, Error Rate, P95 Latency, and Active Pipelines. Values change color when thresholds are exceeded (e.g., error rate above 5% or p95 above 2000ms).' },
+          { title: 'How to filter and interpret', content: 'Use the time range selector (1h, 24h, 7d) and refresh interval to control the window. Charts below the cards show trends for events, errors, latency, and pipeline success or failure.' },
+          { title: 'Important notes', content: 'Alert events are listed when metrics cross their configured thresholds. Top actors show the principals driving the most events.' },
+        ]}
+      />
+
       {/* Stats Cards */}
       <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4">
         {statsCards.map((card) => (
@@ -468,3 +555,5 @@ export function ObservabilityDashboard() {
     </div>
   )
 }
+// CIL[END chunk_id="observabilitydashboard_render_1783666257"]
+// CIL[END chunk_id="observabilitydashboard_function_observabilitydashboard_1783666257"]