spine-framework 0.4.4 → 0.5.0-rc.4

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

@@ -1,12 +1,28 @@
 // CIL[BEGIN stable_id="~/.framework/src/pages/admin/RoleDetailPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/admin/RoleDetailPage.tsx"]
-// CIL[DOC-MACRO purpose="Provides module-level imports and context for the admin role detail page."]
-// CIL[DOC-RESPONSIBILITY responsibility="Load React, routing, UI primitives, hooks, and utilities used by RoleDetailPage."]
-// CIL[DOC-CONTEXT module="admin" layer="page" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/alert.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/card.tsx,.framework/src/components/ui/checkbox.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/label.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
-// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports dependencies for the role detail page." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="admin-frontend"]
+/**
+ * @module   RoleDetailPage
+ * @audience internal
+ * @layer    app-specific
+ * @stability stable
+ *
+ * RoleDetailPage is a React component that manages the display and editing of role details within the admin interface. It interacts with the API to fetch and update role information based on the role ID obtained from the URL parameters. INVARIANT: The role ID must always be present in the URL for the component to function correctly.
+ *
+ * @seeAlso useApi (provides API interaction hooks).
+ * @seeAlso apiFetch (handles API requests).
+ * @seeAlso formatDateTime (formats date and time for display).
+ * @seeAlso PageInstructions (provides instructional content for the admin page).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 import { useState, useEffect } from 'react'
 import { useParams, useNavigate } from 'react-router-dom'
@@ -22,23 +38,31 @@ import { ArrowLeft, ShieldCheck, AlertCircle } from 'lucide-react'
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
 import { formatDateTime } from '../../lib/utils'
-import { PageInstructions } from '../../components/admin/PageInstructions'
-
-// CIL[DOC-VECTOR type="context" content="purpose='Provides module-level imports and context for the admin role detail page.'; No verified external callers; imports: .framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/textarea.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/pages/admin/RoleDetailPage.tsx:module_header:module_header"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/pages/admin/RoleDetailPage.tsx:Role:interface" type="interface" identity="Role" parent="~/.framework/src/pages/admin/RoleDetailPage.tsx"]
-// CIL[DOC-MACRO purpose="Defines the TypeScript shape of a Role record used in the admin UI."]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide a typed contract for role data, permissions, and metadata."]
-// CIL[DOC-CONTEXT module="admin" layer="domain" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/alert.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/card.tsx,.framework/src/components/ui/checkbox.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/label.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/RoleDetailPage.tsx"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Role type definition" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Declares the Role interface fields consumed by the detail page and API." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The Role interface defines the structure of a role object used in the admin panel, encapsulating essential attributes and permissions associated with a role. It exists to standardize role management within the application.
+ *
+ * @sideEffects none
+ * @stability   stable
+ * @cil-generated
+ */
 interface Role {
   id: string
   name: string
@@ -51,22 +75,37 @@ interface Role {
   created_at: string
   updated_at: string
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Defines the TypeScript shape of a Role record used in the admin UI.'; No verified external callers; imports: .framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/textarea.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/pages/admin/RoleDetailPage.tsx:Role:interface"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/pages/admin/RoleDetailPage.tsx:RoleDetailPage:component" type="component" identity="RoleDetailPage" parent="~/.framework/src/pages/admin/RoleDetailPage.tsx"]
-// CIL[DOC-MACRO purpose="Renders a create/edit form for admin roles and their permissions."]
-// CIL[DOC-RESPONSIBILITY responsibility="Fetch role data, manage form state, validate permissions JSON, submit to the API, and render the admin UI."]
-// CIL[DOC-CONTEXT module="admin" layer="page" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/ui/alert.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/ui/card.tsx,.framework/src/components/ui/checkbox.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/label.tsx,.framework/src/components/ui/skeleton.tsx,.framework/src/components/ui/textarea.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/RoleDetailPage.tsx"]
-// CIL[DOC-CONTRACT inputs="URL id parameter ('new' or existing role), role data from /api/roles, user input" outputs="Rendered role form, navigation after save" errors="fetchError, save error, invalid permissions JSON" side_effects="Calls /api/roles (POST or PATCH) and navigates on success"]
-// CIL[DOC-MICRO logic_summary="Initializes form from fetched role, parses permissions JSON, handles create/update submission, and renders instructions, alerts, and fields." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The RoleDetailPage component manages the creation and editing of role details in an admin interface. It fetches role data if editing an existing role and handles form submission for creating or updating roles.
+ *
+ * @macro       Component responsible for role management in an admin interface.
+ * @micro       Utilizes React hooks for state management and API calls to handle role data.
+ * @outputSpec  JSX.Element
+ * @throws      Error — Invalid JSON in permissions field, Error — Failed to fetch role, Error — Failed to save role
+ * @sideEffects API calls to fetch and save role data.
+ * @stability   stable
+ * @calls       useParams, useNavigate, useApi, apiFetch
+ * @errorHandling Catches and sets error messages for invalid JSON and API response failures.
+ * @cil-generated
+ */
 export function RoleDetailPage() {
   const { id } = useParams<{ id: string }>()
   const navigate = useNavigate()
@@ -186,43 +225,6 @@ export function RoleDetailPage() {
           {isCreateMode ? 'Create Role' : role?.name || 'Role Detail'}
         </h1>
       </div>
-
-      <PageInstructions
-        description="Define a role and set its permissions and metadata."
-        sections={[
-          { title: 'What this role controls', content: 'A role is a named permission set assigned to people. It controls which record types a person can create, read, update, delete, or admin, and whether the role can be assigned in the first place.' },
-          { title: 'Fields explained', content: <ul className="list-disc pl-4 space-y-1">
-            <li><strong>Name</strong> — string, required. The display label such as Sales Manager. Empty name blocks save.</li>
-            <li><strong>Slug</strong> — string, required. A unique URL-friendly identifier. Disabled after creation because permissions and references depend on it.</li>
-            <li><strong>Description</strong> — string. Optional context for other admins.</li>
-            <li><strong>System Role</strong> — checkbox, create-only. Marks a reserved role that cannot be deleted and is protected for core functions.</li>
-            <li><strong>Active</strong> — checkbox. Inactive roles cannot be assigned to people.</li>
-            <li><strong>Permissions (JSON)</strong> — JSON. Maps type slugs to arrays of allowed actions. Invalid JSON or wrong shape will cause save to fail.</li>
-          </ul> },
-          { title: 'Options and values', content: <ul className="list-disc pl-4 space-y-1">
-            <li><strong>Actions per type</strong>: typical values are create, read, update, delete, and admin. Use the array format with a type slug mapped to an array: type_slug: ["read", "write"].</li>
-            <li><strong>System Role</strong>: can only be set during creation and prevents deletion later.</li>
-          </ul> },
-          { title: 'Downstream impact', content: <ul className="list-disc pl-4 space-y-1">
-            <li>People assigned to this role receive the effective permissions immediately after the role is saved.</li>
-            <li>The admin-data API and runtime record UIs evaluate the role permissions for every create, read, update, and delete request.</li>
-            <li>Missing or malformed permissions can lock people out of records or grant unintended access.</li>
-          </ul> },
-          { title: 'How to create, save, and validate', content: <ol className="list-decimal pl-4 space-y-1">
-            <li>In create mode, enter Name and Slug, then set Active and optionally System. Existing roles cannot change the slug.</li>
-
-
-            <li>Enter valid Permissions JSON mapping type slugs to action arrays.</li>
-            <li>Click Create Role or Update Role. Save fails if the name/slug are empty, the slug is changed, or the permissions JSON cannot be parsed.</li>
-          </ol> },
-          { title: 'Common mistakes', content: <ul className="list-disc pl-4 space-y-1">
-            <li>Writing permissions as a flat list instead of an object of arrays.</li>
-            <li>Trying to change the slug after creation, which is disabled and will be ignored.</li>
-            <li>Forgetting to mark a role Active, which prevents assignment.</li>
-          </ul> },
-        ]}
-      />
-
       {error && (
         <Alert variant="destructive">
           <AlertCircle className="h-4 w-4" />
@@ -323,6 +325,14 @@ export function RoleDetailPage() {
               placeholder={`{\n  "item": ["read", "write"],\n  "account": ["read"]\n}`}
               rows={10}
             />
+            {(() => {
+              try {
+                JSON.parse(permissionsJson)
+                return null
+              } catch (err) {
+                return <p className="text-xs text-red-600 mt-2">Invalid JSON: {(err as Error).message}</p>
+              }
+            })()}
             <p className="text-xs text-muted-foreground mt-2">
               Example: <code className="bg-muted px-1 py-0.5 rounded">{`{"ticket": ["read", "write", "admin"]}`}</code>
             </p>
@@ -341,10 +351,11 @@ export function RoleDetailPage() {
     </div>
   )
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Renders a create/edit form for admin roles and their permissions.'; No verified external callers; imports: .framework/src/components/ui/button.tsx,.framework/src/components/ui/input.tsx,.framework/src/components/ui/textarea.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/pages/admin/RoleDetailPage.tsx:RoleDetailPage:component"]
+
+
+
+
+
+
+

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

@@ -1,18 +1,36 @@
 // CIL[BEGIN stable_id="~/.framework/src/pages/admin/RolesPage.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/pages/admin/RolesPage.tsx"]
-// CIL[DOC-MACRO purpose="Admin roles management page module: defines the Role interface and the RolesPage React component for listing, searching, filtering, and sorting roles."]
-// CIL[DOC-RESPONSIBILITY responsibility="Provide the top-level TypeScript module exports and role model shape consumed by the admin roles UI."]
-// CIL[DOC-CONTEXT module="admin" layer="pages" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/admin/SortableTableHeader.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts"]
-// CIL[DOC-CONTRACT inputs="module imports and role API response data" outputs="Role interface and RolesPage React component" errors="Network or API errors are surfaced by useApi hook" side_effects="none at module scope"]
-// CIL[DOC-MICRO logic_summary="Imports React, hooks, shared components, and utilities; exports Role type and RolesPage component for rendering the admin roles list." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="admin-frontend"]
+/**
+ * @module   RolesPage
+ * @audience both
+ * @layer    shared-core
+ * @stability stable
+ *
+ * The RolesPage module provides an interface for managing user roles within the admin panel of the application. It allows administrators to view, add, and modify roles, leveraging various UI components for a seamless experience.
+ * INVARIANT: The user must have admin privileges to access this page.
+ *
+ * @seeAlso AdminListPage (provides the list view for admin roles).
+ * @seeAlso LoadingSpinner (indicates loading states during API calls).
+ * @seeAlso useApi (custom hook for API interactions).
+ * @seeAlso SortableTableHeader (enables sorting functionality in tables).
+ *
+ * @cil-generated
+ */
+
+
+
+
+
+
+
+
+
 
 
 
 
 
 import React, { useState } from 'react'
+import { useNavigate } from 'react-router-dom'
 import { Plus, ShieldCheck, CheckCircle, XCircle, Settings, FileText, Cog } from 'lucide-react';
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
 import { Button } from '../../components/ui/button'
@@ -21,23 +39,32 @@ import { SortableTableHeader } from '../../components/admin/SortableTableHeader'
 import { formatDateTime } from '../../lib/utils'
 import { useApi } from '../../hooks/useApi'
 import { apiFetch } from '../../lib/api'
+// CIL[END stable_id="~/.framework/src/pages/admin/RolesPage.tsx:module_header:module_header"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
-// CIL[DOC-VECTOR type="context" content="purpose='Admin roles management page module: defines the Role interface and the RolesPage React component for listing, searching, filtering, and sorting roles.'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/admin/AdminListPage.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/RolesPage.tsx:module_header:module_header"]
 // CIL[BEGIN stable_id="~/.framework/src/pages/admin/RolesPage.tsx:Role:interface" type="interface" identity="Role" parent="~/.framework/src/pages/admin/RolesPage.tsx"]
-// CIL[DOC-MACRO purpose="Define the shape of a role record for use in the admin roles list and related operations."]
-// CIL[DOC-RESPONSIBILITY responsibility="Declare the TypeScript interface for role objects returned by the roles API."]
-// CIL[DOC-CONTEXT module="admin" layer="types" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/admin/SortableTableHeader.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/RolesPage.tsx"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Role interface type definition" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Typed interface with required and optional fields representing a role, its permissions, app association, and audit timestamps." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The Role interface defines the structure of a role object used in the admin panel for managing user roles and permissions. It encapsulates essential attributes such as identification, status, and metadata related to roles within the application.
+ *
+ * @sideEffects none
+ * @stability   internal
+ * @cil-generated
+ */
 interface Role {
   id: string
   name: string
@@ -51,23 +78,39 @@ interface Role {
   created_at: string
   updated_at: string
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Define the shape of a role record for use in the admin roles list and related operations.'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/admin/AdminListPage.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 // CIL[END stable_id="~/.framework/src/pages/admin/RolesPage.tsx:Role:interface"]
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 // CIL[BEGIN stable_id="~/.framework/src/pages/admin/RolesPage.tsx:RolesPage:component" type="component" identity="RolesPage" parent="~/.framework/src/pages/admin/RolesPage.tsx"]
-// CIL[DOC-MACRO purpose="Render the admin roles list page with search, filters, sorting, stats, and navigation to role detail."]
-// CIL[DOC-RESPONSIBILITY responsibility="Fetch and display roles; handle search, status/type filters, column sorting, row navigation, and summary statistics."]
-// CIL[DOC-CONTEXT module="admin" layer="pages" related_files=".framework/src/components/admin/AdminListPage.tsx,.framework/src/components/admin/SortableTableHeader.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/RolesPage.tsx"]
-// CIL[DOC-CONTRACT inputs="none (internal state and useApi fetch)" outputs="JSX admin list page for roles" errors="API fetch error passed to AdminListPage; boolean sort fallback for permissions" side_effects="Navigates to /spine-framework/admin/configs/roles/:id on row click; uses window.location.href"]
-// CIL[DOC-MICRO logic_summary="Uses useApi to load roles, applies search/status/type filters, sorts by selected column, computes stats cards, and renders an AdminListPage with a sortable table and clickable rows." notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
+/**
+ * The RolesPage component manages the display and filtering of user roles in the admin interface. It provides functionality for searching, sorting, and navigating to role details.
+ *
+ * @macro       Component responsible for rendering and managing roles in an admin dashboard.
+ * @micro       Utilizes state management and API calls to filter and sort roles based on user input.
+ * @outputSpec  JSX.Element — renders a UI for managing roles.
+ * @throws      Error — if the API call fails
+ * @sideEffects API call to '/api/roles?action=list' to fetch roles.
+ * @stability   internal
+ * @calls       useApi, apiFetch, useNavigate
+ * @errorHandling throws an error if the API call fails.
+ * @cil-generated
+ */
 export function RolesPage() {
+  const navigate = useNavigate()
   const [searchTerm, setSearchTerm] = useState('')
   const [selectedStatus, setSelectedStatus] = useState('all')
   const [selectedType, setSelectedType] = useState('all')
@@ -119,7 +162,7 @@ export function RolesPage() {
   }
 
   const handleRowClick = (role: Role) => {
-    window.location.href = `/spine-framework/admin/configs/roles/${role.id}`
+    navigate(`/spine-framework/admin/configs/roles/${role.id}`)
   }
 
   const sortedRoles = [...(filteredRoles || [])].sort((a, b) => {
@@ -319,10 +362,10 @@ export function RolesPage() {
     </AdminListPage>
   )
 }
-// CIL[DOC-VECTOR type="context" content="purpose='Render the admin roles list page with search, filters, sorting, stats, and navigation to role detail.'; No verified external callers; imports: .framework/src/components/ui/LoadingSpinner.tsx,.framework/src/components/ui/button.tsx,.framework/src/components/admin/AdminListPage.tsx"]
-// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
-// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
-// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/RolesPage.tsx:RolesPage:component"]
+// CIL[END stable_id="~/.framework/src/pages/admin/RolesPage.tsx:RolesPage:component"]
+
+
+
+
+
+

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

@@ -55,7 +55,7 @@ async function callSecurity(action: string, body?: any) {
   })
   const data = await res.json().catch(() => ({}))
   if (!res.ok) throw new Error(data?.error || data?.message || `${action} failed (${res.status})`)
-  return data
+  return data?.data ?? data
 }
 
 export function SecurityPage() {

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

@@ -28,7 +28,7 @@ import { AgentView } from '../../components/shared/AgentView'
 import { FlaskConical, CheckCircle, XCircle, Clock, RefreshCw } from 'lucide-react';
 import { LoadingSpinner } from '../../components/ui/LoadingSpinner'
 import { formatDateTime } from '../../lib/utils'
-import { PageInstructions } from '../../components/admin/PageInstructions'
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:module_header:module_header"]
 
 // CIL[DOC-VECTOR type="context" content="purpose='Admin test suite dashboard page module header'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -36,8 +36,6 @@ import { PageInstructions } from '../../components/admin/PageInstructions'
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:module_header:module_header"]
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteStat:interface" type="interface" identity="SuiteStat" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Type definition for suite statistics"]
 // CIL[DOC-RESPONSIBILITY responsibility="Describe the shape of aggregated test suite stats"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="types" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -45,6 +43,7 @@ import { PageInstructions } from '../../components/admin/PageInstructions'
 // CIL[DOC-MICRO logic_summary="Record of suite, total_runs, last status, counts, and timestamps" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteStat:interface" type="interface" identity="SuiteStat" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 interface SuiteStat {
   suite:        string
   total_runs:   number
@@ -54,16 +53,15 @@ interface SuiteStat {
   last_failed:  number | null
   last_total:   number | null
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteStat:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Type definition for suite statistics'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteStat:interface"]
 
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestRun:interface" type="interface" identity="TestRun" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Type definition for a test run record"]
 // CIL[DOC-RESPONSIBILITY responsibility="Describe the shape of an individual test run"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="types" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -71,6 +69,7 @@ interface SuiteStat {
 // CIL[DOC-MICRO logic_summary="Record of id, suite, status, timing, counts, and trigger" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestRun:interface" type="interface" identity="TestRun" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 interface TestRun {
   id:           string
   suite:        string
@@ -84,14 +83,13 @@ interface TestRun {
   skipped:      number | null
   triggered_by: string | null
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestRun:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Type definition for a test run record'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestRun:interface"]
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:suite_labels:constant" type="constant" identity="SUITE_LABELS" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Human readable labels for test suite names"]
 // CIL[DOC-RESPONSIBILITY responsibility="Map suite slugs to display labels"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="constants" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -99,26 +97,26 @@ interface TestRun {
 // CIL[DOC-MICRO logic_summary="Mapping of unit, integration, api, ui to display names" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SUITE_LABELS:constant" type="constant" identity="SUITE_LABELS" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 const SUITE_LABELS: Record<string, string> = {
   unit:        'Unit',
   integration: 'Integration',
   api:         'API',
   ui:          'UI',
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SUITE_LABELS:constant"]
 // CIL[DOC-VECTOR type="context" content="purpose='Human readable labels for test suite names'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:suite_labels:constant"]
 
 
 
 
 
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:StatusBadge:component" type="component" identity="StatusBadge" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Render a colored status badge"]
 // CIL[DOC-RESPONSIBILITY responsibility="Display a status string as a styled badge"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="presentation" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -126,6 +124,7 @@ const SUITE_LABELS: Record<string, string> = {
 // CIL[DOC-MICRO logic_summary="Selects Tailwind color classes based on status and renders text" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:StatusBadge:component" type="component" identity="StatusBadge" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 function StatusBadge({ status }: { status: string | null }) {
   if (!status) return <span className="text-gray-400 text-xs">—</span>
   const color =
@@ -139,16 +138,15 @@ function StatusBadge({ status }: { status: string | null }) {
     </span>
   )
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:StatusBadge:component"]
 // CIL[DOC-VECTOR type="context" content="purpose='Render a colored status badge'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:StatusBadge:component"]
 
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:durationLabel:function" type="function" identity="durationLabel" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Format a duration in milliseconds as a readable string"]
 // CIL[DOC-RESPONSIBILITY responsibility="Convert millisecond duration to ms or seconds display"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="presentation" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -156,20 +154,20 @@ function StatusBadge({ status }: { status: string | null }) {
 // CIL[DOC-MICRO logic_summary="Returns '—' for null, 'ms' for sub-second, or formatted seconds" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:durationLabel:function" type="function" identity="durationLabel" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 function durationLabel(ms: number | null): string {
   if (ms == null) return '—'
   if (ms < 1000) return `${ms}ms`
   return `${(ms / 1000).toFixed(1)}s`
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:durationLabel:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Format a duration in milliseconds as a readable string'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:durationLabel:function"]
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteCard:component" type="component" identity="SuiteCard" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Render a test suite summary card"]
 // CIL[DOC-RESPONSIBILITY responsibility="Show label, status, last run, pass/fail counts, and pass rate"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="presentation" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -177,6 +175,7 @@ function durationLabel(ms: number | null): string {
 // CIL[DOC-MICRO logic_summary="Computes pass rate and displays suite health in a card" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteCard:component" type="component" identity="SuiteCard" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 function SuiteCard({ stat }: { stat: SuiteStat }) {
   const label = SUITE_LABELS[stat.suite] ?? stat.suite
   const passRate = stat.last_total
@@ -209,15 +208,14 @@ function SuiteCard({ stat }: { stat: SuiteStat }) {
     </div>
   )
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteCard:component"]
 // CIL[DOC-VECTOR type="context" content="purpose='Render a test suite summary card'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:SuiteCard:component"]
 
-// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestingDashboard:component" type="component" identity="TestingDashboard" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 // CIL[DOC-MACRO purpose="Admin page for viewing test suite health and run history"]
 // CIL[DOC-RESPONSIBILITY responsibility="Fetch stats and recent runs, render suite cards and run table"]
 // CIL[DOC-CONTEXT module="TestingDashboard" layer="page" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/shared/AgentView.tsx,.framework/src/components/ui/LoadingSpinner.tsx,.framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/lib/utils.ts,.framework/src/pages/admin/TestingDashboard.tsx"]
@@ -225,6 +223,7 @@ function SuiteCard({ stat }: { stat: SuiteStat }) {
 // CIL[DOC-MICRO logic_summary="Loads suite stats and recent runs, renders cards, table, and agent view" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestingDashboard:component" type="component" identity="TestingDashboard" parent="~/.framework/src/pages/admin/TestingDashboard.tsx"]
 export default function TestingDashboard() {
   const navigate = useNavigate()
 
@@ -264,17 +263,6 @@ export default function TestingDashboard() {
           Refresh
         </button>
       </div>
-
-      <PageInstructions
-        description="Run and review Spine test suites."
-        sections={[
-          { title: 'What this page is for', content: 'This page displays the health and history of the unit, integration, API, and UI test suites.' },
-          { title: 'How to read the cards', content: 'The suite health cards show the most recent run status, pass rate, total runs, and last run time. Colors indicate passed, failed, running, or unknown states.' },
-          { title: 'How to use this page', content: 'Click the Refresh button to reload stats and runs. Click a row in the Recent Runs table to view individual test case results. Suites are triggered from the IDE or CI pipeline.' },
-          { title: 'Important notes', content: 'A pass rate below 100% is shown in red. Empty states mean no runs have been recorded yet for that suite.' },
-        ]}
-      />
-
       {/* Suite health cards */}
       {statsLoading ? (
         <div className="flex justify-center py-8"><LoadingSpinner /></div>
@@ -373,10 +361,10 @@ export default function TestingDashboard() {
     </div>
   )
 }
+// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestingDashboard:component"]
 // CIL[DOC-VECTOR type="context" content="purpose='Admin page for viewing test suite health and run history'; No verified external callers; imports: .framework/src/hooks/useApi.ts,.framework/src/lib/api.ts,.framework/src/components/shared/AgentView.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
 // CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
-// CIL[END stable_id="~/.framework/src/pages/admin/TestingDashboard.tsx:TestingDashboard:component"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]