feat: implement sub-spec detection and enhance error handling in SpecDetailPage; update API to support sub-specs in responses

Author: tikazyq

packages/ui-vite/src/components/spec-detail/SubSpecTabs.tsx

@@ -98,7 +98,7 @@ export function SubSpecTabs({ mainContent, subSpecs = [] }: SubSpecTabsProps) {
       key={value}
       onClick={() => setActiveTab(value)}
       className={cn(
-        'flex items-center gap-2 px-4 py-2 text-sm border-b-2 -mb-px transition-colors',
+        'flex items-center gap-2 px-4 py-2 text-sm border-b-2 -mb-px transition-colors rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2',
         activeTab === value
           ? 'border-primary text-foreground'
           : 'border-transparent text-muted-foreground hover:text-foreground'
@@ -128,7 +128,7 @@ export function SubSpecTabs({ mainContent, subSpecs = [] }: SubSpecTabsProps) {
                       key={subSpec.file}
                       variant="ghost"
                       onClick={() => setActiveTab(subSpec.name.toLowerCase())}
-                      className="justify-start gap-2 h-auto px-2 py-2"
+                      className="justify-start gap-2 h-auto px-2 py-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2"
                     >
                       {Icon && <Icon className={cn('h-4 w-4', subSpec.color)} />}
                       <span className="text-sm font-medium">{subSpec.name}</span>

packages/ui-vite/src/lib/api.ts

@@ -19,6 +19,7 @@ import type {
   RustSpec,
   RustSpecDetail,
   RustStats,
+  SubSpecItem,
 } from '../types/api';
 
 const API_BASE = import.meta.env.VITE_API_URL || 'http://localhost:3333';
@@ -28,7 +29,7 @@ export type SpecDetail = NextJsSpecDetail;
 export type Stats = NextJsStats;
 export type Project = ProjectType;
 
-class APIError extends Error {
+export class APIError extends Error {
   status: number;
 
   constructor(status: number, message: string) {
@@ -48,8 +49,23 @@ async function fetchAPI<T>(endpoint: string, options?: RequestInit): Promise<T>
   });
 
   if (!response.ok) {
-    const error = await response.text();
-    throw new APIError(response.status, error || response.statusText);
+    const raw = await response.text();
+    let message = raw || response.statusText;
+
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed.message === 'string') {
+        message = parsed.message;
+      } else if (typeof parsed.error === 'string') {
+        message = parsed.error;
+      } else if (typeof parsed.detail === 'string') {
+        message = parsed.detail;
+      }
+    } catch {
+      // Fall back to raw message
+    }
+
+    throw new APIError(response.status, message || response.statusText);
   }
 
   if (response.status === 204) {
@@ -68,8 +84,9 @@ async function fetchAPI<T>(endpoint: string, options?: RequestInit): Promise<T>
   }
 }
 
-function toDateOrNull(value?: string): Date | null {
+function toDateOrNull(value?: string | Date | null): Date | null {
   if (!value) return null;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? null : value;
   const date = new Date(value);
   return Number.isNaN(date.getTime()) ? null : date;
 }
@@ -91,6 +108,10 @@ export function calculateCompletionRate(byStatus: Record<string, number>): numbe
 }
 
 export function adaptSpec(rustSpec: RustSpec): NextJsSpec {
+  const created = rustSpec.created_at ?? rustSpec.createdAt ?? rustSpec.created;
+  const updated = rustSpec.updated_at ?? rustSpec.updatedAt ?? rustSpec.updated;
+  const completed = rustSpec.completed_at ?? rustSpec.completedAt;
+
   return {
     id: rustSpec.name,
     name: rustSpec.name,
@@ -100,18 +121,49 @@ export function adaptSpec(rustSpec: RustSpec): NextJsSpec {
     status: rustSpec.status ?? null,
     priority: rustSpec.priority ?? null,
     tags: rustSpec.tags ?? null,
-    createdAt: toDateOrNull(rustSpec.created),
-    updatedAt: toDateOrNull(rustSpec.updated),
+    assignee: rustSpec.assignee ?? null,
+    createdAt: toDateOrNull(created),
+    updatedAt: toDateOrNull(updated),
+    completedAt: toDateOrNull(completed),
+    filePath: rustSpec.file_path ?? rustSpec.filePath,
+    relationships: rustSpec.relationships,
   };
 }
 
 export function adaptSpecDetail(rustSpec: RustSpecDetail): NextJsSpecDetail {
+  const content = rustSpec.contentMd ?? rustSpec.content_md ?? rustSpec.content ?? '';
+  const dependsOn = rustSpec.depends_on ?? rustSpec.dependsOn ?? [];
+  const requiredBy = rustSpec.required_by ?? rustSpec.requiredBy ?? [];
+  const metadata = rustSpec.metadata ?? {};
+
+  const rawSubSpecs = rustSpec.sub_specs ?? rustSpec.subSpecs ?? (metadata.sub_specs as unknown);
+  const subSpecs: SubSpecItem[] = Array.isArray(rawSubSpecs)
+    ? rawSubSpecs.flatMap((entry) => {
+      if (!entry || typeof entry !== 'object') return [];
+      const candidate = entry as Partial<SubSpecItem> & Record<string, unknown>;
+      const name = typeof candidate.name === 'string' ? candidate.name : undefined;
+      const subContent = typeof candidate.content === 'string' ? candidate.content : undefined;
+      if (!name || !subContent) return [];
+
+      const file = typeof candidate.file === 'string' ? candidate.file : name;
+      const iconName = typeof candidate.iconName === 'string'
+        ? candidate.iconName
+        : typeof candidate.icon_name === 'string'
+          ? (candidate.icon_name as string)
+          : undefined;
+      const color = typeof candidate.color === 'string' ? candidate.color : undefined;
+
+      return [{ name, file, iconName, color, content: subContent } satisfies SubSpecItem];
+    })
+    : [];
+
   return {
     ...adaptSpec(rustSpec),
-    content: rustSpec.content ?? '',
-    metadata: rustSpec.metadata ?? {},
-    dependsOn: rustSpec.depends_on ?? [],
-    requiredBy: rustSpec.required_by ?? [],
+    content,
+    metadata,
+    dependsOn,
+    requiredBy,
+    subSpecs: subSpecs.length > 0 ? subSpecs : undefined,
   };
 }
 

packages/ui-vite/src/pages/SpecDetailPage.tsx

@@ -2,7 +2,7 @@ import { useCallback, useEffect, useMemo, useState } from 'react';
 import { Link, useParams } from 'react-router-dom';
 import { AlertTriangle, ArrowLeft, RefreshCcw } from 'lucide-react';
 import { Button, Card, CardContent } from '@leanspec/ui-components';
-import { api, type SpecDetail } from '../lib/api';
+import { APIError, api, type SpecDetail } from '../lib/api';
 import { StatusBadge } from '../components/StatusBadge';
 import { PriorityBadge } from '../components/PriorityBadge';
 import { SubSpecTabs, type SubSpec } from '../components/spec-detail/SubSpecTabs';
@@ -17,6 +17,27 @@ export function SpecDetailPage() {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
 
+  const describeError = useCallback((err: unknown) => {
+    if (err instanceof APIError) {
+      switch (err.status) {
+        case 404:
+          return 'Spec not found (404). Check the spec ID or sync the project.';
+        case 400:
+          return 'Bad request when loading spec. Verify the spec path and try again.';
+        case 500:
+          return 'Server error while loading spec. Restart the Rust server or check logs.';
+        default:
+          return `Failed to load spec (${err.status}). ${err.message || 'Please retry.'}`;
+      }
+    }
+
+    if (err instanceof Error && err.message.includes('Failed to fetch')) {
+      return 'Network error: unable to reach the backend. Ensure VITE_API_URL is reachable and the server is running.';
+    }
+
+    return err instanceof Error ? err.message : 'Unexpected error while loading spec.';
+  }, []);
+
   const loadSpec = useCallback(async () => {
     if (!specName) return;
     setLoading(true);
@@ -25,19 +46,18 @@ export function SpecDetailPage() {
       setSpec(data);
       setError(null);
     } catch (err) {
-      const message = err instanceof Error ? err.message : 'Failed to load spec';
-      setError(message);
+      setError(describeError(err));
     } finally {
       setLoading(false);
     }
-  }, [specName]);
+  }, [describeError, specName]);
 
   useEffect(() => {
     void loadSpec();
   }, [loadSpec]);
 
   const subSpecs: SubSpec[] = useMemo(() => {
-    const raw = spec?.metadata?.sub_specs as unknown;
+    const raw = (spec?.subSpecs as unknown) ?? (spec?.metadata?.sub_specs as unknown);
     if (!Array.isArray(raw)) return [];
     return raw
       .map((entry) => {
@@ -49,7 +69,11 @@ export function SpecDetailPage() {
           name,
           content,
           file: typeof (entry as Record<string, unknown>).file === 'string' ? (entry as Record<string, unknown>).file as string : name,
-          iconName: typeof (entry as Record<string, unknown>).iconName === 'string' ? (entry as Record<string, unknown>).iconName as string : undefined,
+          iconName: typeof (entry as Record<string, unknown>).iconName === 'string'
+            ? (entry as Record<string, unknown>).iconName as string
+            : typeof (entry as Record<string, unknown>).icon_name === 'string'
+              ? (entry as Record<string, unknown>).icon_name as string
+              : undefined,
           color: typeof (entry as Record<string, unknown>).color === 'string' ? (entry as Record<string, unknown>).color as string : undefined,
         } satisfies SubSpec;
       })
@@ -82,6 +106,16 @@ export function SpecDetailPage() {
               <RefreshCcw className="h-4 w-4" />
               Retry
             </Button>
+            <a
+              href="https://github.com/codervisor/lean-spec/issues"
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex"
+            >
+              <Button variant="ghost" size="sm" className="gap-2">
+                Report issue
+              </Button>
+            </a>
           </>
         )}
       />

packages/ui-vite/src/types/api.ts

@@ -1,27 +1,55 @@
 export type SpecStatus = 'planned' | 'in-progress' | 'complete' | 'archived';
 export type SpecPriority = 'low' | 'medium' | 'high' | 'critical';
 
+export interface SubSpecItem {
+  name: string;
+  file: string;
+  iconName?: string;
+  color?: string;
+  content: string;
+}
+
 export interface RustSpec {
   name: string;
   title: string;
   status: SpecStatus;
   priority?: SpecPriority;
   tags?: string[];
+  assignee?: string | null;
   created?: string;
+  created_at?: string;
+  createdAt?: string;
   updated?: string;
+  updated_at?: string;
+  updatedAt?: string;
+  completed_at?: string;
+  completedAt?: string;
   depends_on?: string[];
+  dependsOn?: string[];
   required_by?: string[];
+  requiredBy?: string[];
+  file_path?: string;
+  filePath?: string;
+  relationships?: {
+    depends_on: string[];
+    required_by?: string[];
+  };
 }
 
 export interface RustSpecDetail extends RustSpec {
-  content: string;
+  content?: string;
+  content_md?: string;
+  contentMd?: string;
   metadata?: {
     created_at?: string;
     updated_at?: string;
     assignee?: string;
     github_url?: string;
+    sub_specs?: SubSpecItem[];
     [key: string]: unknown;
   };
+  sub_specs?: SubSpecItem[];
+  subSpecs?: SubSpecItem[];
 }
 
 export interface RustStats {
@@ -40,8 +68,15 @@ export interface NextJsSpec {
   status: SpecStatus | null;
   priority: SpecPriority | null;
   tags: string[] | null;
+  assignee?: string | null;
   createdAt: Date | null;
   updatedAt: Date | null;
+  completedAt?: Date | null;
+  filePath?: string;
+  relationships?: {
+    depends_on: string[];
+    required_by?: string[];
+  };
 }
 
 export interface NextJsSpecDetail extends NextJsSpec {
@@ -55,6 +90,7 @@ export interface NextJsSpecDetail extends NextJsSpec {
   };
   dependsOn?: string[];
   requiredBy?: string[];
+  subSpecs?: SubSpecItem[];
 }
 
 export interface NextJsStats {