@openspecui/web 0.9.0

package/src/lib/use-subscription.ts

@@ -0,0 +1,375 @@
+import type { ArchiveMeta, Change, ChangeFile, ChangeMeta, Spec, SpecMeta } from '@openspecui/core'
+import { useEffect, useRef, useState } from 'react'
+import * as StaticProvider from './static-data-provider'
+import { isStaticMode } from './static-mode'
+import { trpcClient } from './trpc'
+
+/** 订阅状态 */
+export interface SubscriptionState<T> {
+  data: T | undefined
+  isLoading: boolean
+  error: Error | null
+}
+
+/** Dashboard 数据类型 */
+export interface DashboardData {
+  specs: Spec[]
+  changes: Change[]
+  archivedCount: number
+  summary: {
+    specCount: number
+    requirementCount: number
+    activeChangeCount: number
+    archivedChangeCount: number
+    totalTasks: number
+    completedTasks: number
+    progressPercent: number
+  }
+}
+
+/** 订阅回调 */
+interface SubscriptionCallbacks<T> {
+  onData: (data: T) => void
+  onError: (err: Error) => void
+}
+
+/** 可取消订阅的对象 */
+interface Unsubscribable {
+  unsubscribe: () => void
+}
+
+/**
+ * 通用订阅 Hook (支持静态模式)
+ *
+ * 替代 useQuery，直接从 WebSocket 获取数据。
+ * 当订阅的数据变更时，自动更新组件。
+ * 在静态模式下，从 data.json 加载数据。
+ *
+ * @param subscribe 订阅函数
+ * @param staticLoader 静态数据加载函数（静态模式下使用）
+ * @param deps 依赖数组
+ */
+export function useSubscription<T>(
+  subscribe: (callbacks: SubscriptionCallbacks<T>) => Unsubscribable,
+  staticLoader?: () => Promise<T>,
+  deps: unknown[] = []
+): SubscriptionState<T> {
+  const [state, setState] = useState<SubscriptionState<T>>({
+    data: undefined,
+    isLoading: true,
+    error: null,
+  })
+
+  const subscriptionRef = useRef<Unsubscribable | null>(null)
+  const inStaticMode = isStaticMode()
+
+  useEffect(() => {
+    // 清理之前的订阅
+    subscriptionRef.current?.unsubscribe()
+
+    // 重置状态
+    setState((prev) => ({ ...prev, isLoading: true, error: null }))
+
+    // 静态模式：从 data.json 加载数据
+    if (inStaticMode) {
+      if (staticLoader) {
+        staticLoader()
+          .then((data) => {
+            setState({ data, isLoading: false, error: null })
+          })
+          .catch((error) => {
+            console.error('Static data loading error:', error)
+            setState((prev) => ({ ...prev, isLoading: false, error }))
+          })
+      } else {
+        console.warn('No static loader provided for subscription in static mode')
+        setState((prev) => ({
+          ...prev,
+          isLoading: false,
+          error: new Error('Static loader not available'),
+        }))
+      }
+      return
+    }
+
+    // 动态模式：创建 WebSocket 订阅
+    const subscription = subscribe({
+      onData: (data) => {
+        setState({ data, isLoading: false, error: null })
+      },
+      onError: (error) => {
+        console.error('Subscription error:', error)
+        setState((prev) => ({ ...prev, isLoading: false, error }))
+      },
+    })
+
+    subscriptionRef.current = subscription
+
+    return () => {
+      subscription.unsubscribe()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [inStaticMode, ...deps])
+
+  return state
+}
+
+// =====================
+// Dashboard subscriptions
+// =====================
+
+export function useDashboardSubscription(): SubscriptionState<DashboardData> {
+  return useSubscription<DashboardData>(
+    (callbacks) =>
+      trpcClient.dashboard.subscribe.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    async () => {
+      const data = await StaticProvider.getDashboardData()
+      if (!data) throw new Error('Failed to load dashboard data')
+      return data
+    },
+    []
+  )
+}
+
+export function useInitializedSubscription(): SubscriptionState<boolean> {
+  return useSubscription<boolean>(
+    (callbacks) =>
+      trpcClient.dashboard.subscribeInitialized.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getInitialized,
+    []
+  )
+}
+
+// =====================
+// Spec subscriptions
+// =====================
+
+export function useSpecsSubscription(): SubscriptionState<SpecMeta[]> {
+  return useSubscription<SpecMeta[]>(
+    (callbacks) =>
+      trpcClient.spec.subscribe.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getSpecs,
+    []
+  )
+}
+
+export function useSpecSubscription(id: string): SubscriptionState<Spec | null> {
+  return useSubscription<Spec | null>(
+    (callbacks) =>
+      trpcClient.spec.subscribeOne.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getSpec(id),
+    [id]
+  )
+}
+
+export function useSpecRawSubscription(id: string): SubscriptionState<string | null> {
+  return useSubscription<string | null>(
+    (callbacks) =>
+      trpcClient.spec.subscribeRaw.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getSpecRaw(id),
+    [id]
+  )
+}
+
+// =====================
+// Change subscriptions
+// =====================
+
+export function useChangesSubscription(): SubscriptionState<ChangeMeta[]> {
+  return useSubscription<ChangeMeta[]>(
+    (callbacks) =>
+      trpcClient.change.subscribe.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getChanges,
+    []
+  )
+}
+
+export function useChangeSubscription(id: string): SubscriptionState<Change | null> {
+  return useSubscription<Change | null>(
+    (callbacks) =>
+      trpcClient.change.subscribeOne.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getChange(id),
+    [id]
+  )
+}
+
+export function useChangeFilesSubscription(id: string): SubscriptionState<ChangeFile[]> {
+  return useSubscription<ChangeFile[]>(
+    (callbacks) =>
+      trpcClient.change.subscribeFiles.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getChangeFiles(id),
+    [id]
+  )
+}
+
+/** Change 原始文件内容 */
+export interface ChangeRaw {
+  proposal: string
+  tasks?: string
+}
+
+export function useChangeRawSubscription(id: string): SubscriptionState<ChangeRaw | null> {
+  return useSubscription<ChangeRaw | null>(
+    (callbacks) =>
+      trpcClient.change.subscribeRaw.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getChangeRaw(id),
+    [id]
+  )
+}
+
+// =====================
+// Archive subscriptions
+// =====================
+
+export function useArchivesSubscription(): SubscriptionState<ArchiveMeta[]> {
+  return useSubscription<ArchiveMeta[]>(
+    (callbacks) =>
+      trpcClient.archive.subscribe.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getArchives,
+    []
+  )
+}
+
+/** Archived change 数据类型 (与 Change 相同结构) */
+export type ArchivedChange = Change
+
+export function useArchiveSubscription(id: string): SubscriptionState<ArchivedChange | null> {
+  return useSubscription<ArchivedChange | null>(
+    (callbacks) =>
+      trpcClient.archive.subscribeOne.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getArchive(id),
+    [id]
+  )
+}
+
+export function useArchiveFilesSubscription(id: string): SubscriptionState<ChangeFile[]> {
+  return useSubscription<ChangeFile[]>(
+    (callbacks) =>
+      trpcClient.archive.subscribeFiles.subscribe(
+        { id },
+        {
+          onData: callbacks.onData,
+          onError: callbacks.onError,
+        }
+      ),
+    () => StaticProvider.getArchiveFiles(id),
+    [id]
+  )
+}
+
+// =====================
+// Project subscriptions
+// =====================
+
+export function useProjectMdSubscription(): SubscriptionState<string | null> {
+  return useSubscription<string | null>(
+    (callbacks) =>
+      trpcClient.project.subscribeProjectMd.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getProjectMd,
+    []
+  )
+}
+
+export function useAgentsMdSubscription(): SubscriptionState<string | null> {
+  return useSubscription<string | null>(
+    (callbacks) =>
+      trpcClient.project.subscribeAgentsMd.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getAgentsMd,
+    []
+  )
+}
+
+// =====================
+// Config subscriptions
+// =====================
+
+/** OpenSpecUI 配置类型 */
+export interface OpenSpecUIConfig {
+  cli: { command?: string }
+  ui: { theme: 'light' | 'dark' | 'system' }
+}
+
+export function useConfigSubscription(): SubscriptionState<OpenSpecUIConfig> {
+  return useSubscription<OpenSpecUIConfig>(
+    (callbacks) =>
+      trpcClient.config.subscribe.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getConfig,
+    []
+  )
+}
+
+// =====================
+// CLI subscriptions
+// =====================
+
+export function useConfiguredToolsSubscription(): SubscriptionState<string[]> {
+  return useSubscription<string[]>(
+    (callbacks) =>
+      trpcClient.cli.subscribeConfiguredTools.subscribe(undefined, {
+        onData: callbacks.onData,
+        onError: callbacks.onError,
+      }),
+    StaticProvider.getConfiguredTools,
+    []
+  )
+}

package/src/lib/use-tabs-status-by-query.ts

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useMemo, useState } from 'react'
+
+interface UseTabsStatusByQueryParams {
+  tabsId: string
+  tabs: Array<{ id: string }>
+  initialTab?: string
+}
+
+export function useTabsStatusByQuery({ tabsId, tabs, initialTab }: UseTabsStatusByQueryParams) {
+  const validIds = useMemo(() => new Set(tabs.map((t) => t.id)), [tabs])
+
+  const readFromUrl = useCallback(() => {
+    if (typeof window === 'undefined') return null
+    const params = new URLSearchParams(window.location.search)
+    const value = params.get(tabsId)
+    return value && validIds.has(value) ? value : null
+  }, [tabsId, validIds])
+
+  const pickInitial = useCallback(() => {
+    return readFromUrl() ?? initialTab ?? tabs[0]?.id ?? ''
+  }, [readFromUrl, initialTab, tabs])
+
+  const [selectedTab, setSelectedTab] = useState<string>(pickInitial)
+
+  const writeToUrl = useCallback(
+    (id: string) => {
+      if (typeof window === 'undefined') return
+      const url = new URL(window.location.href)
+      url.searchParams.set(tabsId, id)
+      window.history.replaceState(null, '', url.toString())
+    },
+    [tabsId]
+  )
+
+  const setBoth = useCallback(
+    (id: string) => {
+      if (!validIds.has(id)) return
+      setSelectedTab(id)
+      writeToUrl(id)
+    },
+    [validIds, writeToUrl]
+  )
+
+  // keep in sync when tabs or URL change
+  useEffect(() => {
+    const fromUrl = readFromUrl()
+    const candidate = fromUrl ?? initialTab ?? tabs[0]?.id ?? ''
+    if (candidate && candidate !== selectedTab && validIds.has(candidate)) {
+      setSelectedTab(candidate)
+    } else if (!validIds.has(selectedTab) && candidate) {
+      setSelectedTab(candidate)
+    }
+  }, [readFromUrl, initialTab, tabs, selectedTab, validIds])
+
+  // respond to browser navigation
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const handler = () => {
+      const next = readFromUrl()
+      if (next && validIds.has(next)) {
+        setSelectedTab((prev) => (prev === next ? prev : next))
+      }
+    }
+    window.addEventListener('popstate', handler)
+    return () => window.removeEventListener('popstate', handler)
+  }, [readFromUrl, validIds])
+
+  // reflect current selection into URL
+  useEffect(() => {
+    if (!validIds.has(selectedTab) || typeof window === 'undefined') return
+    const current = readFromUrl()
+    if (current === selectedTab) return
+    writeToUrl(selectedTab)
+  }, [selectedTab, validIds, writeToUrl, readFromUrl])
+
+  return { selectedTab, setSelectedTab: setBoth }
+}
+

package/src/main.tsx

@@ -0,0 +1,9 @@
+/**
+ * Main entry point - re-exports from entry-client
+ *
+ * This file exists for backwards compatibility with Vite's default entry.
+ */
+export * from './entry-client'
+
+// Import to trigger side effects (the actual app initialization)
+import './entry-client'

package/src/routes/archive-list.tsx

@@ -0,0 +1,65 @@
+import { formatRelativeTime } from '@/lib/format-time'
+import { useArchivesSubscription } from '@/lib/use-subscription'
+import { Link } from '@tanstack/react-router'
+import { Archive, ChevronRight } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+export function ArchiveList() {
+  const { data: archived, isLoading } = useArchivesSubscription()
+
+  const [firstFrameLoading, setFirstFrameLoading] = useState(true)
+  useEffect(() => {
+    const id = requestAnimationFrame(() => setFirstFrameLoading(false))
+    return () => cancelAnimationFrame(id)
+  }, [])
+
+  if (firstFrameLoading || (isLoading && !archived)) {
+    return <div className="route-loading animate-pulse">Loading archived changes...</div>
+  }
+
+  return (
+    <div className="space-y-6">
+      <h1 className="font-nav flex items-center gap-2 text-2xl font-bold">
+        <Archive className="h-6 w-6 shrink-0" />
+        Archive
+      </h1>
+
+      <p className="text-muted-foreground">
+        Completed changes that have been archived after implementation.
+      </p>
+
+      <div className="border-border divide-border divide-y rounded-lg border">
+        {archived?.map((change) => (
+          <Link
+            key={change.id}
+            to="/archive/$changeId"
+            params={{ changeId: change.id }}
+            className="hover:bg-muted/50 flex items-center justify-between p-4"
+          >
+            <div className="flex items-center gap-3">
+              <Archive className="text-muted-foreground h-5 w-5" />
+              <div>
+                <div className="font-medium">{change.name}</div>
+                <div className="text-muted-foreground text-sm">
+                  {change.id}
+                  {change.updatedAt > 0 && <> · {formatRelativeTime(change.updatedAt)}</>}
+                </div>
+              </div>
+            </div>
+            <ChevronRight className="text-muted-foreground h-4 w-4" />
+          </Link>
+        ))}
+        {archived?.length === 0 && (
+          <div className="text-muted-foreground p-8 text-center">
+            <Archive className="mx-auto mb-4 h-12 w-12 opacity-50" />
+            <p>No archived changes yet.</p>
+            <p className="mt-2 text-sm">
+              Changes are archived after implementation using{' '}
+              <code className="bg-muted rounded px-1">openspec archive</code>
+            </p>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/routes/archive-view.tsx

@@ -0,0 +1,116 @@
+import { ChangeOverview } from '@/components/change-overview'
+import { FolderEditorViewer } from '@/components/folder-editor-viewer'
+import { Tabs, type Tab } from '@/components/tabs'
+import { useTabsStatusByQuery } from '@/lib/use-tabs-status-by-query'
+import { TasksView } from '@/components/tasks-view'
+import { useArchiveSubscription } from '@/lib/use-subscription'
+import { getRouteApi, Link } from '@tanstack/react-router'
+import { Archive, ArrowLeft, CheckCircle, FileText, FolderTree, ListChecks } from 'lucide-react'
+import { useEffect, useMemo, useState } from 'react'
+
+const route = getRouteApi('/archive/$changeId')
+
+export function ArchiveView() {
+  const { changeId } = route.useParams()
+
+  const { data: change } = useArchiveSubscription(changeId)
+  const [loading, setLoading] = useState(true)
+  useEffect(() => {
+    const id = requestAnimationFrame(() => setLoading(false))
+    return () => cancelAnimationFrame(id)
+  }, [])
+
+  const tabs = useMemo<Tab[]>(() => {
+    if (!change) return []
+
+    const result: Tab[] = [
+      {
+        id: 'overview',
+        label: 'Overview',
+        icon: <FileText className="h-4 w-4" />,
+        content: <ChangeOverview change={change} />,
+      },
+    ]
+
+    if (change.tasks.length > 0) {
+      result.push({
+        id: 'tasks',
+        label: `Tasks (${change.progress.completed}/${change.progress.total})`,
+        icon: <ListChecks className="h-4 w-4" />,
+        content: (
+          <div className="border-border h-full overflow-auto rounded-lg border p-4">
+            <TasksView tasks={change.tasks} progress={change.progress} readonly />
+          </div>
+        ),
+      })
+    }
+
+    result.push({
+      id: 'folder',
+      label: 'Folder',
+      icon: <FolderTree className="h-4 w-4" />,
+      content: <FolderEditorViewer changeId={changeId} archived />,
+    })
+
+    return result
+  }, [change, changeId])
+
+  const { selectedTab, setSelectedTab } = useTabsStatusByQuery({
+    tabsId: 'archiveTab',
+    tabs,
+    initialTab: tabs[0]?.id,
+  })
+
+  if (loading) {
+    return <div className="route-loading animate-pulse">Loading archived change...</div>
+  }
+
+  if (!change) {
+    return (
+      <div className="py-12 text-center">
+        <p className="text-muted-foreground">Archived change not found: {changeId}</p>
+        <Link to="/archive" className="text-primary mt-4 inline-block hover:underline">
+          Back to Archive
+        </Link>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col gap-6">
+      {/* Header */}
+      <div className="flex items-center gap-4">
+        <Link
+          to="/archive"
+          className="hover:bg-muted rounded-md p-2 transition-colors"
+          title="Back to Archive"
+        >
+          <ArrowLeft className="h-5 w-5" />
+        </Link>
+        <div>
+          <h1 className="font-nav flex items-center gap-2 text-2xl font-bold">
+            <Archive className="h-6 w-6 shrink-0" />
+            {change.name}
+          </h1>
+          <p className="text-muted-foreground text-sm">{changeId}</p>
+        </div>
+      </div>
+
+      {/* Progress */}
+      <div className="flex items-center gap-2 text-sm">
+        <CheckCircle className="h-4 w-4 text-green-500" />
+        <span className="text-green-600">
+          Completed: {change.progress.completed}/{change.progress.total} tasks
+        </span>
+      </div>
+
+      {/* Tabs with Activity for state preservation */}
+      <Tabs
+        tabs={tabs}
+        selectedTab={selectedTab}
+        onTabChange={setSelectedTab}
+        className="min-h-0 flex-1 gap-6"
+      />
+    </div>
+  )
+}

package/src/routes/change-list.tsx

@@ -0,0 +1,63 @@
+import { formatRelativeTime } from '@/lib/format-time'
+import { useChangesSubscription } from '@/lib/use-subscription'
+import { Link } from '@tanstack/react-router'
+import { ChevronRight, GitBranch } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+export function ChangeList() {
+  const { data: changes, isLoading } = useChangesSubscription()
+  const [firstFrameLoading, setFirstFrameLoading] = useState(true)
+  useEffect(() => {
+    const id = requestAnimationFrame(() => setFirstFrameLoading(false))
+    return () => cancelAnimationFrame(id)
+  }, [])
+
+  if (firstFrameLoading || (isLoading && !changes)) {
+    return <div className="route-loading animate-pulse">Loading changes...</div>
+  }
+
+  return (
+    <div className="space-y-6">
+      <h1 className="font-nav flex items-center gap-2 text-2xl font-bold">
+        <GitBranch className="h-6 w-6 shrink-0" />
+        Changes
+      </h1>
+
+      <p className="text-muted-foreground">
+        Active change proposals. Completed changes are moved to{' '}
+        <Link to="/archive" className="text-primary hover:underline">
+          Archive
+        </Link>
+        .
+      </p>
+
+      <div className="border-border divide-border divide-y rounded-lg border">
+        {changes?.map((change) => (
+          <Link
+            key={change.id}
+            to="/changes/$changeId"
+            params={{ changeId: change.id }}
+            className="hover:bg-muted/50 flex items-center justify-between p-4"
+          >
+            <div className="flex items-center gap-3">
+              <GitBranch className="text-muted-foreground h-5 w-5" />
+              <div>
+                <div className="font-medium">{change.name}</div>
+                <div className="text-muted-foreground text-sm">
+                  {change.progress.completed}/{change.progress.total} tasks
+                  {change.updatedAt > 0 && <> · {formatRelativeTime(change.updatedAt)}</>}
+                </div>
+              </div>
+            </div>
+            <ChevronRight className="text-muted-foreground h-4 w-4" />
+          </Link>
+        ))}
+        {changes?.length === 0 && (
+          <div className="text-muted-foreground p-4 text-center">
+            No active changes. Create one in <code>openspec/changes/</code>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}