spine-framework 0.1.0

package/.framework/src/components/admin/AdminListPage.tsx

@@ -0,0 +1,151 @@
+import React, { ReactNode } from 'react'
+import { Button } from '../ui/button'
+import { Card, CardContent } from '../ui/card'
+import { Input } from '../ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../ui/select'
+import { Skeleton } from '../ui/skeleton'
+import { Search } from 'lucide-react'
+import { LucideIcon } from 'lucide-react'
+import { AdminStatsCard } from './AdminStatsCard'
+import { cn } from '../../lib/utils'
+
+interface AdminListPageProps {
+  title: string
+  description: string
+  newButtonText?: string
+  newButtonHref?: string
+  onNewClick?: () => void
+  statsCards: Array<{
+    title: string
+    value: string | number
+    icon: LucideIcon
+    iconColor?: string
+  }>
+  searchPlaceholder?: string
+  searchValue?: string
+  onSearchChange?: (value: string) => void
+  filters?: Array<{
+    label: string
+    value: string
+    options: Array<{ value: string; label: string }>
+    onChange: (value: string) => void
+  }>
+  children: ReactNode
+  loading?: boolean
+  error?: string | null
+  onRetry?: () => void
+  emptyMessage?: string
+  emptyIcon?: LucideIcon
+}
+
+export function AdminListPage({
+  title,
+  description,
+  newButtonText,
+  newButtonHref = '#',
+  onNewClick,
+  statsCards,
+  searchPlaceholder = "Search...",
+  searchValue = "",
+  onSearchChange,
+  filters = [],
+  children,
+  loading = false,
+  error = null,
+  onRetry,
+}: AdminListPageProps) {
+  return (
+    <div className="space-y-6">
+      {/* Header */}
+      <div className="flex justify-between items-center">
+        <div>
+          <h1 className="text-xl font-semibold">{title}</h1>
+          <p className="mt-1 text-sm text-muted-foreground">{description}</p>
+        </div>
+        
+        {newButtonText && (
+          <Button onClick={() => onNewClick ? onNewClick() : (window.location.href = newButtonHref!)}>
+            {newButtonText}
+          </Button>
+        )}
+      </div>
+
+      {/* Stats Cards */}
+      <div className="grid grid-cols-1 gap-5 sm:grid-cols-2 lg:grid-cols-4">
+        {statsCards.map((stat, index) => (
+          <AdminStatsCard
+            key={index}
+            title={stat.title}
+            value={stat.value}
+            icon={stat.icon}
+            iconColor={stat.iconColor}
+          />
+        ))}
+      </div>
+
+      {/* Search and Filters */}
+      <Card>
+        <CardContent className="p-4">
+          <div className="flex flex-col sm:flex-row gap-4">
+            {/* Search */}
+            {onSearchChange && (
+              <div className="flex-1">
+                <div className="relative">
+                  <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+                  <Input
+                    placeholder={searchPlaceholder}
+                    value={searchValue}
+                    onChange={(e) => onSearchChange(e.target.value)}
+                    className="pl-9"
+                  />
+                </div>
+              </div>
+            )}
+
+            {/* Filters */}
+            {filters.map((filter, index) => (
+              <div key={index} className="sm:w-48">
+                <Select value={filter.value} onValueChange={filter.onChange}>
+                  <SelectTrigger>
+                    <SelectValue placeholder={filter.label} />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {filter.options.map(option => (
+                      <SelectItem key={option.value} value={option.value}>
+                        {option.label}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            ))}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Content */}
+      <Card>
+        {loading ? (
+          <div className="p-8 space-y-4">
+            <Skeleton className="h-8 w-full" />
+            <Skeleton className="h-8 w-full" />
+            <Skeleton className="h-8 w-3/4" />
+          </div>
+        ) : error ? (
+          <div className="p-8 text-center">
+            <p className="text-destructive">Error: {error}</p>
+            {onRetry && (
+              <Button onClick={onRetry} className="mt-4">
+                Retry
+              </Button>
+            )}
+          </div>
+        ) : (
+          <CardContent className="p-0">
+            {children}
+          </CardContent>
+        )}
+      </Card>
+    </div>
+  )
+}

package/.framework/src/components/admin/AdminSidebar.tsx

@@ -0,0 +1,166 @@
+/**
+ * @module src/components/admin/AdminSidebar
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Admin sidebar with proper sections, React Router navigation, and active link highlighting.
+ */
+
+import * as React from "react"
+import { Link, useLocation } from "react-router-dom"
+import { 
+  PlusIcon, 
+  Database, 
+  Settings, 
+  Type, 
+  Users, 
+  Layout, 
+  FileText,
+  BarChart3,
+  AlertTriangle,
+  Activity,
+  FileSearch,
+  FlaskConical,
+  Brain,
+  Cpu,
+  Timer,
+  Puzzle,
+  Shield,
+  MessageSquare,
+  Key,
+  TestTube
+} from "lucide-react"
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarRail,
+} from "../ui/sidebar"
+import { Button } from "../ui/button"
+
+// Navigation sections with correct admin URLs
+const navigationSections = [
+  {
+    title: "Configs",
+    items: [
+      { title: "Types", url: "/spine-framework/admin/configs/types", icon: Type },
+      { title: "Apps", url: "/spine-framework/admin/configs/apps", icon: Layout },
+      { title: "Pipelines", url: "/spine-framework/admin/configs/pipelines", icon: Activity },
+      { title: "Triggers", url: "/spine-framework/admin/configs/triggers", icon: AlertTriangle },
+      { title: "AI Agents", url: "/spine-framework/admin/configs/ai-agents", icon: Brain },
+      { title: "Embeddings", url: "/spine-framework/admin/configs/embeddings", icon: Cpu },
+      { title: "Timers", url: "/spine-framework/admin/configs/timers", icon: Timer },
+      { title: "Integrations", url: "/spine-framework/admin/configs/integrations", icon: Puzzle },
+      { title: "Roles", url: "/spine-framework/admin/configs/roles", icon: Shield },
+      { title: "Prompts", url: "/spine-framework/admin/configs/prompts", icon: MessageSquare },
+      { title: "API Keys", url: "/spine-framework/admin/configs/api-keys", icon: Key },
+    ]
+  },
+  {
+    title: "Runtime",
+    items: [
+      { title: "Items", url: "/spine-framework/admin/runtime/items", icon: Database },
+      { title: "Accounts", url: "/spine-framework/admin/runtime/accounts", icon: Users },
+      { title: "People", url: "/spine-framework/admin/runtime/people", icon: Users },
+      { title: "Threads", url: "/spine-framework/admin/runtime/threads", icon: MessageSquare },
+      { title: "Messages", url: "/spine-framework/admin/runtime/messages", icon: FileText },
+      { title: "Attachments", url: "/spine-framework/admin/runtime/attachments", icon: FileSearch },
+      { title: "Watchers", url: "/spine-framework/admin/runtime/watchers", icon: Activity },
+      { title: "Links", url: "/spine-framework/admin/runtime/links", icon: Puzzle },
+      { title: "Progress", url: "/spine-framework/admin/runtime/item_progress", icon: BarChart3 },
+    ]
+  },
+  {
+    title: "Observability",
+    items: [
+      { title: "Dashboard", url: "/spine-framework/admin/observability", icon: BarChart3 },
+      { title: "Alerts", url: "/spine-framework/admin/observability/alerts", icon: AlertTriangle },
+      { title: "Executions", url: "/spine-framework/admin/observability/executions", icon: Activity },
+      { title: "Logs", url: "/spine-framework/admin/observability/logs", icon: FileSearch },
+    ]
+  },
+  {
+    title: "Testing",
+    items: [
+      { title: "Test Runs", url: "/spine-framework/admin/testing", icon: TestTube },
+    ]
+  }
+]
+
+export function AdminSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
+  const location = useLocation()
+
+  // Check if a URL is active (exact match or starts with path)
+  const isActive = (url: string) => {
+    return location.pathname === url || location.pathname.startsWith(url + '/')
+  }
+
+  return (
+    <Sidebar {...props}>
+      <SidebarHeader>
+        {/* Brand Header */}
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton size="lg" asChild>
+              <Link to="/spine-framework/admin/configs/types">
+                <div className="flex aspect-square size-8 items-center justify-center rounded-lg bg-primary text-primary-foreground">
+                  <span className="text-sm font-bold">S</span>
+                </div>
+                <div className="flex flex-col gap-0.5 leading-none">
+                  <span className="font-semibold">Spine</span>
+                  <span className="text-xs text-muted-foreground">Framework</span>
+                </div>
+              </Link>
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+
+        {/* Quick Create Button */}
+        <SidebarGroup className="py-2">
+          <Button className="w-full" size="sm">
+            <PlusIcon className="mr-2 h-4 w-4" />
+            Quick Create
+          </Button>
+        </SidebarGroup>
+      </SidebarHeader>
+
+      <SidebarContent>
+        {navigationSections.map((section) => (
+          <SidebarGroup key={section.title}>
+            <SidebarGroupLabel>{section.title}</SidebarGroupLabel>
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {section.items.map((item) => (
+                  <SidebarMenuItem key={item.title}>
+                    <SidebarMenuButton asChild isActive={isActive(item.url)}>
+                      <Link to={item.url}>
+                        <item.icon className="h-4 w-4" />
+                        <span>{item.title}</span>
+                      </Link>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                ))}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        ))}
+      </SidebarContent>
+
+      <SidebarFooter className="p-4">
+        <div className="text-xs text-muted-foreground">
+          Spine v2.0
+        </div>
+      </SidebarFooter>
+
+      <SidebarRail />
+    </Sidebar>
+  )
+}

package/.framework/src/components/admin/AdminStatsCard.tsx

@@ -0,0 +1,62 @@
+/**
+ * @module src/components/admin/AdminStatsCard
+ * @audience installer
+ * @layer frontend-component
+ * @stability stable
+ *
+ * Single stat card used in admin list page headers. Renders an icon,
+ * a title, and a numeric or string value inside a white rounded panel.
+ * Icon colour defaults to `'text-blue-500'` but can be overridden per card.
+ *
+ * @seeAlso src/components/admin/AdminListPage.tsx (mounts this component)
+ */
+
+import React from 'react'
+import { LucideIcon } from 'lucide-react'
+import { Card, CardContent } from '../ui/card'
+
+/**
+ * Props for `AdminStatsCard`.
+ *
+ * @prop title - Stat label
+ * @prop value - Numeric or formatted string value to display
+ * @prop icon - Lucide icon component
+ * @prop iconColor - Tailwind text-colour class (default: `'text-blue-500'`)
+ */
+interface AdminStatsCardProps {
+  title: string
+  value: string | number
+  icon: LucideIcon
+  iconColor?: string
+}
+
+/**
+ * Single stat card.
+ *
+ * @param props - `AdminStatsCardProps`
+ * @returns White rounded card with icon and stat value
+ * @sideEffects none (pure rendering)
+ */
+export function AdminStatsCard({ title, value, icon: Icon, iconColor = "text-primary" }: AdminStatsCardProps) {
+  return (
+    <Card>
+      <CardContent className="p-5">
+        <div className="flex items-center">
+          <div className="flex-shrink-0">
+            <Icon className={`h-6 w-6 ${iconColor}`} />
+          </div>
+          <div className="ml-5 w-0 flex-1">
+            <dl>
+              <dt className="text-sm font-medium text-muted-foreground truncate">
+                {title}
+              </dt>
+              <dd className="text-lg font-semibold text-foreground">
+                {value}
+              </dd>
+            </dl>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}

package/.framework/src/components/admin/SortableTableHeader.tsx

@@ -0,0 +1,42 @@
+import React from 'react'
+import { ChevronUp, ChevronDown } from 'lucide-react'
+import { TableHead } from '../ui/table'
+
+interface SortableTableHeaderProps {
+  title: string
+  sortKey: string
+  currentSortKey?: string
+  currentSortDirection?: 'asc' | 'desc'
+  onSort: (key: string) => void
+}
+
+export function SortableTableHeader({
+  title,
+  sortKey,
+  currentSortKey,
+  currentSortDirection,
+  onSort,
+}: SortableTableHeaderProps) {
+  const isSorted = currentSortKey === sortKey
+  const isAscending = currentSortDirection === 'asc'
+  
+  return (
+    <TableHead
+      className="cursor-pointer"
+      onClick={() => onSort(sortKey)}
+    >
+      <div className="flex items-center gap-1">
+        <span>{title}</span>
+        {isSorted && (
+          <span className="inline-flex">
+            {isAscending ? (
+              <ChevronUp className="h-4 w-4 text-foreground" />
+            ) : (
+              <ChevronDown className="h-4 w-4 text-foreground" />
+            )}
+          </span>
+        )}
+      </div>
+    </TableHead>
+  )
+}

package/.framework/src/components/app-shell/GenericAppShell.tsx

@@ -0,0 +1,181 @@
+import { useState } from 'react'
+import { Routes, Route, Navigate, useNavigate, useLocation } from 'react-router-dom'
+import { AppRecord } from '../../hooks/useApps'
+import { GenericListPage } from './GenericListPage'
+import { GenericDetailPage } from './GenericDetailPage'
+
+interface NavItem {
+  id: string
+  label: string
+  icon?: string
+  path: string
+  type_slug?: string
+  view?: string
+  min_role?: string
+}
+
+interface GenericAppShellProps {
+  app: AppRecord
+}
+
+/**
+ * Data-driven app shell. Reads nav_items from the app record to build
+ * a sidebar and child routes. Each nav entry with a type_slug renders
+ * a GenericListPage (at path) and GenericDetailPage (at path/:id).
+ */
+export function GenericAppShell({ app }: GenericAppShellProps) {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const [sidebarOpen, setSidebarOpen] = useState(false)
+
+  const navItems: NavItem[] = (app.nav_items || []) as NavItem[]
+
+  // Derive relative paths from app's route_prefix
+  const prefix = app.route_prefix || `/${app.slug}`
+
+  // Check if a nav item is active
+  const isActive = (item: NavItem) => {
+    const fullPath = item.path.startsWith('/') ? item.path : `${prefix}/${item.path}`
+    return location.pathname.startsWith(fullPath)
+  }
+
+  return (
+    <div className="min-h-screen bg-slate-50 flex">
+      {/* Sidebar */}
+      <aside className={`
+        fixed inset-y-0 left-0 z-40 w-64 bg-white border-r border-slate-200
+        transform transition-transform duration-200 ease-in-out
+        lg:translate-x-0 lg:static lg:inset-auto
+        ${sidebarOpen ? 'translate-x-0' : '-translate-x-full'}
+      `}>
+        <div className="flex items-center gap-3 h-16 px-6 border-b border-slate-200">
+          {app.icon && (
+            <div className={`w-8 h-8 rounded-lg flex items-center justify-center text-white text-sm font-bold`}
+              style={{ backgroundColor: app.color || '#475569' }}>
+              {app.name.charAt(0).toUpperCase()}
+            </div>
+          )}
+          <div>
+            <h2 className="font-semibold text-slate-900 text-sm">{app.name}</h2>
+            {app.description && (
+              <p className="text-xs text-slate-500 truncate max-w-[160px]">{app.description}</p>
+            )}
+          </div>
+        </div>
+
+        <nav className="px-3 py-4 space-y-1">
+          {navItems.map(item => (
+            <button
+              key={item.id || item.path}
+              onClick={() => {
+                const target = item.path.startsWith('/') ? item.path : `${prefix}/${item.path}`
+                navigate(target)
+                setSidebarOpen(false)
+              }}
+              className={`
+                w-full flex items-center gap-3 px-3 py-2 rounded-lg text-sm transition-colors
+                ${isActive(item)
+                  ? 'bg-slate-100 text-slate-900 font-medium'
+                  : 'text-slate-600 hover:bg-slate-50 hover:text-slate-900'
+                }
+              `}
+            >
+              <span>{item.label}</span>
+            </button>
+          ))}
+        </nav>
+      </aside>
+
+      {/* Overlay for mobile sidebar */}
+      {sidebarOpen && (
+        <div
+          className="fixed inset-0 z-30 bg-black/20 lg:hidden"
+          onClick={() => setSidebarOpen(false)}
+        />
+      )}
+
+      {/* Main content */}
+      <div className="flex-1 min-w-0">
+        {/* Mobile header */}
+        <div className="lg:hidden flex items-center h-16 px-4 border-b border-slate-200 bg-white">
+          <button
+            onClick={() => setSidebarOpen(true)}
+            className="p-2 -ml-2 text-slate-600 hover:text-slate-900"
+          >
+            <svg className="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M4 6h16M4 12h16M4 18h16" />
+            </svg>
+          </button>
+          <span className="ml-3 font-semibold text-slate-900">{app.name}</span>
+        </div>
+
+        <main className="p-6">
+          <Routes>
+            {/* Default: redirect to first nav item */}
+            {navItems.length > 0 && (
+              <Route index element={
+                <Navigate to={navItems[0].path.startsWith('/') ? navItems[0].path : navItems[0].path} replace />
+              } />
+            )}
+
+            {/* Generate list + detail routes for each nav item with type_slug */}
+            {navItems.filter(item => item.type_slug).map(item => {
+              // Strip leading prefix to get relative route path
+              const relativePath = item.path.startsWith(prefix)
+                ? item.path.slice(prefix.length).replace(/^\//, '')
+                : item.path.replace(/^\//, '')
+
+              return [
+                <Route
+                  key={`${item.id}-list`}
+                  path={relativePath}
+                  element={
+                    <GenericListPage
+                      typeSlug={item.type_slug!}
+                      viewSlug={item.view}
+                      appPrefix={prefix}
+                      detailPath={`${relativePath}`}
+                    />
+                  }
+                />,
+                <Route
+                  key={`${item.id}-new`}
+                  path={`${relativePath}/new`}
+                  element={
+                    <GenericDetailPage
+                      typeSlug={item.type_slug!}
+                      viewSlug={item.view}
+                      isCreating={true}
+                    />
+                  }
+                />,
+                <Route
+                  key={`${item.id}-detail`}
+                  path={`${relativePath}/:id`}
+                  element={
+                    <GenericDetailPage
+                      typeSlug={item.type_slug!}
+                      viewSlug={item.view}
+                    />
+                  }
+                />
+              ]
+            })}
+
+            {/* Empty state */}
+            {navItems.length === 0 && (
+              <Route path="*" element={
+                <div className="text-center py-16">
+                  <h2 className="text-lg font-medium text-slate-900">No pages configured</h2>
+                  <p className="mt-2 text-sm text-slate-500">
+                    Add nav_items to this app's record to create pages.
+                  </p>
+                </div>
+              } />
+            )}
+          </Routes>
+        </main>
+      </div>
+    </div>
+  )
+}