@openspecui/web 0.9.0

package/src/lib/static-data-provider.ts

@@ -0,0 +1,386 @@
+/**
+ * Static Data Provider
+ *
+ * Provides data from the static snapshot (data.json) instead of WebSocket subscriptions
+ *
+ * The snapshot includes fully parsed markdown content generated during export,
+ * so specs, changes, and archives can be displayed with proper rendering.
+ */
+
+import type { ArchiveMeta, Change, ChangeFile, ChangeMeta, Spec, SpecMeta } from '@openspecui/core'
+import type { ExportSnapshot } from '../ssg/types'
+import type { ChangeRaw, DashboardData, OpenSpecUIConfig } from './use-subscription'
+import { getBasePath, getInitialData } from './static-mode'
+
+/**
+ * In-memory cache of the loaded snapshot
+ */
+let snapshotCache: ExportSnapshot | null = null
+let snapshotPromise: Promise<ExportSnapshot | null> | null = null
+
+/**
+ * Load the static snapshot once
+ */
+export async function loadSnapshot(): Promise<ExportSnapshot | null> {
+  // Return cached data if available
+  if (snapshotCache) {
+    return snapshotCache
+  }
+
+  // Check for injected initial data first (SSR/SSG)
+  const initialData = getInitialData()
+  if (initialData) {
+    snapshotCache = initialData
+    return initialData
+  }
+
+  // Reuse in-flight request if exists
+  if (snapshotPromise) {
+    return snapshotPromise
+  }
+
+  snapshotPromise = (async () => {
+    try {
+      const basePath = getBasePath()
+      const dataUrl = `${basePath}data.json`.replace('//', '/')
+      const response = await fetch(dataUrl)
+
+      if (!response.ok) {
+        console.error('Failed to load data snapshot:', response.statusText)
+        return null
+      }
+
+      const snapshot = (await response.json()) as ExportSnapshot
+      snapshotCache = snapshot
+      return snapshot
+    } catch (error) {
+      console.error('Error loading static snapshot:', error)
+      return null
+    }
+  })()
+
+  return snapshotPromise
+}
+
+/**
+ * Convert snapshot spec to Spec type (with parsed content from export)
+ */
+function snapshotSpecToSpec(snapSpec: ExportSnapshot['specs'][0]): Spec {
+  return {
+    id: snapSpec.id,
+    name: snapSpec.name,
+    overview: snapSpec.overview,
+    requirements: snapSpec.requirements,
+    metadata: {
+      version: '1.0',
+      format: 'openspec' as const,
+    },
+  }
+}
+
+/**
+ * Convert snapshot change to Change type (with parsed content from export)
+ */
+function snapshotChangeToChange(snapChange: ExportSnapshot['changes'][0]): Change {
+  return {
+    id: snapChange.id,
+    name: snapChange.name,
+    why: snapChange.why,
+    whatChanges: snapChange.whatChanges,
+    design: snapChange.design,
+    deltas: [], // Simplified - not used in UI directly
+    tasks: snapChange.parsedTasks,
+    progress: snapChange.progress,
+  } as Change
+}
+
+/**
+ * Get dashboard data from snapshot
+ */
+export async function getDashboardData(): Promise<DashboardData | null> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return null
+
+  const specs = snapshot.specs.map(snapshotSpecToSpec)
+  const changes = snapshot.changes.map(snapshotChangeToChange)
+  const archives = snapshot.archives
+
+  // Calculate summary
+  const specCount = specs.length
+  const requirementCount = 0 // Simplified for static mode
+  const activeChangeCount = changes.length
+  const archivedChangeCount = archives.length
+
+  // Calculate task progress from snapshot data
+  let totalTasks = 0
+  let completedTasks = 0
+
+  for (const change of snapshot.changes) {
+    totalTasks += change.progress.total
+    completedTasks += change.progress.completed
+  }
+
+  const progressPercent = totalTasks > 0 ? Math.round((completedTasks / totalTasks) * 100) : 0
+
+  return {
+    specs,
+    changes,
+    archivedCount: archivedChangeCount,
+    summary: {
+      specCount,
+      requirementCount,
+      activeChangeCount,
+      archivedChangeCount,
+      totalTasks,
+      completedTasks,
+      progressPercent,
+    },
+  }
+}
+
+/**
+ * Check if OpenSpec is initialized (always true in static mode)
+ */
+export async function getInitialized(): Promise<boolean> {
+  const snapshot = await loadSnapshot()
+  return snapshot !== null
+}
+
+/**
+ * Get all specs metadata
+ */
+export async function getSpecs(): Promise<SpecMeta[]> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return []
+
+  return snapshot.specs.map((spec) => ({
+    id: spec.id,
+    name: spec.name,
+    createdAt: spec.createdAt,
+    updatedAt: spec.updatedAt,
+  }))
+}
+
+/**
+ * Get a single spec by ID
+ */
+export async function getSpec(id: string): Promise<Spec | null> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return null
+
+  const snapSpec = snapshot.specs.find((s) => s.id === id)
+  if (!snapSpec) return null
+
+  return snapshotSpecToSpec(snapSpec)
+}
+
+/**
+ * Get raw spec content (markdown)
+ */
+export async function getSpecRaw(id: string): Promise<string | null> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return null
+
+  const spec = snapshot.specs.find((s) => s.id === id)
+  return spec?.content || null
+}
+
+/**
+ * Get all changes metadata
+ */
+export async function getChanges(): Promise<ChangeMeta[]> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return []
+
+  return snapshot.changes.map((change) => ({
+    id: change.id,
+    name: change.name,
+    progress: change.progress,
+    createdAt: change.createdAt,
+    updatedAt: change.updatedAt,
+  }))
+}
+
+/**
+ * Get a single change by ID
+ */
+export async function getChange(id: string): Promise<Change | null> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return null
+
+  const snapChange = snapshot.changes.find((c) => c.id === id)
+  if (!snapChange) return null
+
+  return snapshotChangeToChange(snapChange)
+}
+
+/**
+ * Get change files
+ */
+export async function getChangeFiles(id: string): Promise<ChangeFile[]> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return []
+
+  const change = snapshot.changes.find((c) => c.id === id)
+  if (!change) return []
+
+  const files: ChangeFile[] = []
+
+  files.push({
+    path: 'proposal.md',
+    type: 'file' as const,
+    content: change.proposal,
+  })
+
+  if (change.tasks) {
+    files.push({
+      path: 'tasks.md',
+      type: 'file' as const,
+      content: change.tasks,
+    })
+  }
+
+  if (change.design) {
+    files.push({
+      path: 'design.md',
+      type: 'file' as const,
+      content: change.design,
+    })
+  }
+
+  // Add delta spec files
+  change.deltas.forEach((delta) => {
+    files.push({
+      path: `specs/${delta.capability}/spec.md`,
+      type: 'file' as const,
+      content: delta.content,
+    })
+  })
+
+  return files
+}
+
+/**
+ * Get raw change content
+ */
+export async function getChangeRaw(id: string): Promise<ChangeRaw | null> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return null
+
+  const change = snapshot.changes.find((c) => c.id === id)
+  if (!change) return null
+
+  return {
+    proposal: change.proposal,
+    tasks: change.tasks,
+  }
+}
+
+/**
+ * Get all archives metadata
+ */
+export async function getArchives(): Promise<ArchiveMeta[]> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return []
+
+  return snapshot.archives.map((archive) => ({
+    id: archive.id,
+    name: archive.name,
+    createdAt: archive.createdAt,
+    updatedAt: archive.updatedAt,
+  }))
+}
+
+/**
+ * Get a single archive by ID
+ */
+export async function getArchive(id: string): Promise<Change | null> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return null
+
+  const snapArchive = snapshot.archives.find((a) => a.id === id)
+  if (!snapArchive) return null
+
+  // Convert archive to Change with parsed content
+  return {
+    id: snapArchive.id,
+    name: snapArchive.name,
+    why: snapArchive.why,
+    whatChanges: snapArchive.whatChanges,
+    design: snapArchive.design,
+    deltas: [],
+    tasks: snapArchive.parsedTasks,
+    progress: { total: 0, completed: 0 },
+  } as Change
+}
+
+/**
+ * Get archive files
+ */
+export async function getArchiveFiles(id: string): Promise<ChangeFile[]> {
+  const snapshot = await loadSnapshot()
+  if (!snapshot) return []
+
+  const archive = snapshot.archives.find((a) => a.id === id)
+  if (!archive) return []
+
+  const files: ChangeFile[] = []
+
+  files.push({
+    path: 'proposal.md',
+    type: 'file' as const,
+    content: archive.proposal,
+  })
+
+  if (archive.tasks) {
+    files.push({
+      path: 'tasks.md',
+      type: 'file' as const,
+      content: archive.tasks,
+    })
+  }
+
+  if (archive.design) {
+    files.push({
+      path: 'design.md',
+      type: 'file' as const,
+      content: archive.design,
+    })
+  }
+
+  return files
+}
+
+/**
+ * Get project.md content (not in snapshot currently)
+ */
+export async function getProjectMd(): Promise<string | null> {
+  const snapshot = await loadSnapshot()
+  return snapshot?.projectMd || null
+}
+
+/**
+ * Get AGENTS.md content (not in snapshot currently)
+ */
+export async function getAgentsMd(): Promise<string | null> {
+  const snapshot = await loadSnapshot()
+  return snapshot?.agentsMd || null
+}
+
+/**
+ * Get UI config (default in static mode)
+ */
+export async function getConfig(): Promise<OpenSpecUIConfig> {
+  // In static mode, return default config
+  return {
+    cli: { command: 'openspecui' },
+    ui: { theme: 'system' },
+  }
+}
+
+/**
+ * Get configured tools (empty in static mode)
+ */
+export async function getConfiguredTools(): Promise<string[]> {
+  return []
+}

package/src/lib/static-mode.ts

@@ -0,0 +1,158 @@
+/**
+ * Static Mode Detection and Data Loading
+ *
+ * This module detects whether the app is running in static export mode
+ * and provides data snapshot loading functionality.
+ */
+
+import type { ExportSnapshot } from '../ssg/types'
+
+let staticModeDetected: boolean | null = null
+
+// Check for static mode flag set by SSG at build time
+// This is the preferred detection method - no network requests needed
+if (typeof window !== 'undefined' && (window as any).__OPENSPEC_STATIC_MODE__ === true) {
+  staticModeDetected = true
+  console.log('[static-mode] Detected static export mode (via flag)')
+}
+
+/**
+ * Check if running in static export mode
+ * Static mode is detected by:
+ * 1. window.__OPENSPEC_STATIC_MODE__ flag (set by SSG)
+ * 2. Fallback: attempting to load data.json
+ */
+export async function detectStaticMode(): Promise<boolean> {
+  if (staticModeDetected !== null) {
+    return staticModeDetected
+  }
+
+  // Fallback: check for data.json
+  try {
+    const basePath = getBasePath()
+    const dataUrl = `${basePath}data.json`.replace('//', '/')
+    const response = await fetch(dataUrl, { method: 'HEAD' })
+    staticModeDetected = response.ok
+  } catch {
+    staticModeDetected = false
+  }
+
+  return staticModeDetected
+}
+
+/**
+ * Check if running in static export mode (synchronous)
+ */
+export function isStaticMode(): boolean {
+  return staticModeDetected === true
+}
+
+/**
+ * Set static mode (used during app initialization)
+ */
+export function setStaticMode(value: boolean): void {
+  staticModeDetected = value
+}
+
+// SSR basePath - set during server-side rendering
+let ssrBasePath: string | null = null
+
+/**
+ * Set base path for SSR (called before rendering)
+ */
+export function setSSRBasePath(basePath: string): void {
+  ssrBasePath = basePath
+}
+
+/**
+ * Get the base path for the application
+ */
+export function getBasePath(): string {
+  // SSR mode: use the set basePath
+  if (ssrBasePath !== null) {
+    return ssrBasePath
+  }
+  // Browser mode: use window variable
+  if (typeof window !== 'undefined') {
+    return (window as any).__OPENSPEC_BASE_PATH__ || './'
+  }
+  return './'
+}
+
+/**
+ * Get initial data injected by SSG (if available)
+ */
+export function getInitialData(): ExportSnapshot | null {
+  if (typeof window !== 'undefined' && (window as any).__INITIAL_DATA__) {
+    return (window as any).__INITIAL_DATA__ as ExportSnapshot
+  }
+  return null
+}
+
+/**
+ * Load the data snapshot in static mode
+ */
+export async function loadStaticSnapshot(): Promise<ExportSnapshot | null> {
+  // First check for injected data (faster, no network request)
+  const initialData = getInitialData()
+  if (initialData) {
+    return initialData
+  }
+
+  // Fallback: fetch from data.json
+  const isStatic = await detectStaticMode()
+  if (!isStatic) {
+    return null
+  }
+
+  try {
+    const basePath = getBasePath()
+    const dataUrl = `${basePath}data.json`.replace('//', '/')
+    const response = await fetch(dataUrl)
+
+    if (!response.ok) {
+      console.error('Failed to load data snapshot:', response.statusText)
+      return null
+    }
+
+    const snapshot = (await response.json()) as ExportSnapshot
+    return snapshot
+  } catch (error) {
+    console.error('Error loading static snapshot:', error)
+    return null
+  }
+}
+
+/**
+ * Static snapshot cache - loaded once and reused
+ */
+let snapshotCache: ExportSnapshot | null | undefined = undefined
+
+/**
+ * Get the cached snapshot or load it if not yet loaded
+ */
+export async function getStaticSnapshot(): Promise<ExportSnapshot | null> {
+  if (snapshotCache !== undefined) {
+    return snapshotCache
+  }
+
+  snapshotCache = await loadStaticSnapshot()
+  return snapshotCache
+}
+
+/**
+ * Check if snapshot is loaded
+ */
+export function isSnapshotLoaded(): boolean {
+  return snapshotCache !== undefined && snapshotCache !== null
+}
+
+/**
+ * Get snapshot metadata (timestamp, version, etc.)
+ */
+export function getSnapshotMeta() {
+  if (!isSnapshotLoaded() || !snapshotCache) {
+    return null
+  }
+  return snapshotCache.meta
+}

package/src/lib/trpc.ts

@@ -0,0 +1,107 @@
+import type { AppRouter } from '@openspecui/server'
+import { QueryClient } from '@tanstack/react-query'
+import {
+  createTRPCClient,
+  createWSClient,
+  httpBatchLink,
+  splitLink,
+  wsLink,
+  type TRPCLink,
+} from '@trpc/client'
+import { createTRPCOptionsProxy } from '@trpc/tanstack-react-query'
+import { getTrpcUrl, getWsUrl } from './api-config'
+import { isStaticMode } from './static-mode'
+
+// Check if running in browser
+const isBrowser = typeof window !== 'undefined'
+
+// Query client singleton for SPA
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000,
+    },
+  },
+})
+
+/** WebSocket 重连延迟（毫秒） */
+export const WS_RETRY_DELAY_MS = 3000
+
+// Lazy WebSocket client creation
+let wsClient: ReturnType<typeof createWSClient> | null = null
+function getWsClient() {
+  if (!isBrowser || isStaticMode()) {
+    return null
+  }
+  if (!wsClient) {
+    try {
+      wsClient = createWSClient({
+        url: getWsUrl(),
+        retryDelayMs: () => WS_RETRY_DELAY_MS,
+        // Suppress connection errors in console
+        onOpen: () => {
+          // Connection opened successfully
+        },
+        onClose: (cause) => {
+          // Only log if not in static mode (shouldn't happen, but just in case)
+          if (!isStaticMode()) {
+            console.log('WebSocket closed:', cause)
+          }
+        },
+      })
+    } catch (error) {
+      // Suppress WebSocket creation errors in static mode
+      if (!isStaticMode()) {
+        console.error('Failed to create WebSocket client:', error)
+      }
+      return null
+    }
+  }
+  return wsClient
+}
+
+// Export for cleanup if needed
+export function getWsClientInstance() {
+  return wsClient
+}
+
+// Create tRPC client only in browser environment
+function createTrpcClientSafe() {
+  if (!isBrowser) {
+    // Return a dummy client for SSR that throws on use
+    return null as unknown as ReturnType<typeof createTRPCClient<AppRouter>>
+  }
+
+  return createTRPCClient<AppRouter>({
+    links: [
+      splitLink({
+        // Use WebSocket for subscriptions (only if not in static mode)
+        condition: (op) => op.type === 'subscription' && !isStaticMode(),
+        true: ((runtime) => {
+          const ws = getWsClient()
+          if (ws) {
+            return wsLink({ client: ws })(runtime)
+          }
+          return httpBatchLink({ url: getTrpcUrl() })(runtime)
+        }) as TRPCLink<AppRouter>,
+        // Use HTTP for queries and mutations
+        false: httpBatchLink({
+          url: getTrpcUrl(),
+        }),
+      }),
+    ],
+  })
+}
+
+// tRPC client singleton with WebSocket support for subscriptions
+export const trpcClient = createTrpcClientSafe()
+
+// tRPC options proxy for use with React Query hooks
+// Use: trpc.router.procedure.queryOptions() with useQuery()
+// Use: trpcClient.router.procedure.mutate() with useMutation()
+export const trpc = isBrowser
+  ? createTRPCOptionsProxy<AppRouter>({
+      client: trpcClient,
+      queryClient,
+    })
+  : (null as unknown as ReturnType<typeof createTRPCOptionsProxy<AppRouter>>)