@openspecui/web 0.9.0

package/src/routes/spec-list.tsx

@@ -0,0 +1,49 @@
+import { formatRelativeTime } from '@/lib/format-time'
+import { useSpecsSubscription } from '@/lib/use-subscription'
+import { Link } from '@tanstack/react-router'
+import { ChevronRight, FileText } from 'lucide-react'
+
+export function SpecList() {
+  const { data: specs, isLoading } = useSpecsSubscription()
+
+  if (isLoading && !specs) {
+    return <div className="route-loading animate-pulse">Loading specs...</div>
+  }
+
+  return (
+    <div className="space-y-6">
+      <h1 className="font-nav flex items-center gap-2 text-2xl font-bold">
+        <FileText className="h-6 w-6 shrink-0" />
+        Specifications
+      </h1>
+
+      <div className="border-border divide-border divide-y rounded-lg border">
+        {specs?.map((spec) => (
+          <Link
+            key={spec.id}
+            to="/specs/$specId"
+            params={{ specId: spec.id }}
+            className="hover:bg-muted/50 flex items-center justify-between p-4"
+          >
+            <div className="flex items-center gap-3">
+              <FileText className="text-muted-foreground h-5 w-5" />
+              <div>
+                <div className="font-medium">{spec.name}</div>
+                <div className="text-muted-foreground text-sm">
+                  {spec.id}
+                  {spec.updatedAt > 0 && <> · {formatRelativeTime(spec.updatedAt)}</>}
+                </div>
+              </div>
+            </div>
+            <ChevronRight className="text-muted-foreground h-4 w-4" />
+          </Link>
+        ))}
+        {specs?.length === 0 && (
+          <div className="text-muted-foreground p-4 text-center">
+            No specs found. Create a spec in <code>openspec/specs/</code>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/routes/spec-view.tsx

@@ -0,0 +1,164 @@
+import { MarkdownViewer } from '@/components/markdown-viewer'
+import { useSpecSubscription } from '@/lib/use-subscription'
+import type { Spec } from '@openspecui/core'
+import { Link, useParams } from '@tanstack/react-router'
+import { AlertCircle, AlertTriangle, ArrowLeft, CheckCircle, FileText, Info } from 'lucide-react'
+
+export function SpecView() {
+  const { specId } = useParams({ from: '/specs/$specId' })
+
+  const { data: spec, isLoading } = useSpecSubscription(specId)
+  // TODO: validation 暂时不支持订阅，后续可以添加
+  const validation = null as {
+    valid: boolean
+    issues: Array<{ severity: string; message: string; path?: string }>
+  } | null
+
+  if (isLoading && !spec) {
+    return <div className="route-loading animate-pulse">Loading spec...</div>
+  }
+
+  if (!spec) {
+    return <div className="text-red-600">Spec not found</div>
+  }
+
+  return <SpecContent spec={spec} validation={validation} />
+}
+
+function SpecContent({
+  spec,
+  validation,
+}: {
+  spec: Spec
+  validation: {
+    valid: boolean
+    issues: Array<{ severity: string; message: string; path?: string }>
+  } | null
+}) {
+  return (
+    <div className="flex min-h-0 flex-1 flex-col gap-6">
+      <div className="flex items-center gap-4">
+        <Link to="/specs" className="hover:bg-muted rounded-md p-2">
+          <ArrowLeft className="h-5 w-5" />
+        </Link>
+        <div>
+          <h1 className="font-nav flex items-center gap-2 text-2xl font-bold">
+            <FileText className="h-6 w-6 shrink-0" />
+            {spec.name}
+          </h1>
+          <p className="text-muted-foreground">ID: {spec.id}</p>
+        </div>
+      </div>
+
+      {validation && <ValidationStatus validation={validation} />}
+
+      <MarkdownViewer
+        className="min-h-0 flex-1"
+        markdown={({ H1, H2, Section }) => (
+          <div className="space-y-6">
+            {/* Overview */}
+            <Section>
+              <H1 id="overview">Overview</H1>
+              <div className="bg-muted/30 mt-2 rounded-lg p-4">
+                {spec.overview ? (
+                  <MarkdownViewer markdown={spec.overview} />
+                ) : (
+                  <span className="text-muted-foreground">No overview</span>
+                )}
+              </div>
+            </Section>
+
+            {/* Requirements */}
+            <Section>
+              <H1 id="requirements">Requirements ({spec.requirements.length})</H1>
+              <div className="mt-3 space-y-4">
+                {spec.requirements.map((req) => (
+                  <Section key={req.id} className="border-border rounded-lg border p-4">
+                    <H2 className="text-base" id={`req-${req.id}`}>
+                      {req.text}
+                    </H2>
+                    {req.scenarios.length > 0 && (
+                      <div className="mt-3">
+                        <div className="text-muted-foreground mb-2 text-sm font-medium">
+                          Scenarios ({req.scenarios.length})
+                        </div>
+                        {req.scenarios.map((scenario, i) => {
+                          // Remove leading/trailing --- separators
+                          const content = scenario.rawText
+                            .replace(/^---\n?/, '')
+                            .replace(/\n?---$/, '')
+                            .trim()
+                          return (
+                            <div key={i} className="bg-muted/50 rounded-md p-3">
+                              <MarkdownViewer markdown={content} />
+                            </div>
+                          )
+                        })}
+                      </div>
+                    )}
+                  </Section>
+                ))}
+                {spec.requirements.length === 0 && (
+                  <div className="text-muted-foreground">No requirements defined</div>
+                )}
+              </div>
+            </Section>
+          </div>
+        )}
+      />
+    </div>
+  )
+}
+
+function ValidationStatus({
+  validation,
+}: {
+  validation: {
+    valid: boolean
+    issues: Array<{ severity: string; message: string; path?: string }>
+  }
+}) {
+  const errors = validation.issues.filter((i) => i.severity === 'ERROR')
+  const warnings = validation.issues.filter((i) => i.severity === 'WARNING')
+  const infos = validation.issues.filter((i) => i.severity === 'INFO')
+
+  return (
+    <div
+      className={`flex rounded-lg border p-4 ${validation.valid ? 'border-green-500 bg-green-500/10' : 'border-red-500 bg-red-500/10'}`}
+    >
+      <div className="align-content flex gap-2">
+        {validation.valid ? (
+          <CheckCircle className="h-5 w-5 text-green-500" />
+        ) : (
+          <AlertCircle className="h-5 w-5 text-red-500" />
+        )}
+        <span className={`font-medium ${validation.valid ? 'text-green-600' : 'text-red-600'}`}>
+          {validation.valid ? 'Validation Passed' : 'Validation Failed'}
+        </span>
+      </div>
+
+      {validation.issues.length > 0 && (
+        <div className="space-y-1 text-sm">
+          {errors.map((issue, i) => (
+            <div key={i} className="flex items-start gap-2 text-red-600">
+              <AlertCircle className="mt-0.5 h-4 w-4 shrink-0" />
+              <span>{issue.message}</span>
+            </div>
+          ))}
+          {warnings.map((issue, i) => (
+            <div key={i} className="flex items-start gap-2 text-yellow-600">
+              <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+              <span>{issue.message}</span>
+            </div>
+          ))}
+          {infos.map((issue, i) => (
+            <div key={i} className="text-muted-foreground flex items-start gap-2">
+              <Info className="mt-0.5 h-4 w-4 shrink-0" />
+              <span>{issue.message}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/ssg/entry-server.tsx

@@ -0,0 +1,111 @@
+/**
+ * SSR entry point for pre-rendering
+ */
+import { renderToString } from 'react-dom/server'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  RouterProvider,
+} from '@tanstack/react-router'
+import { RootLayout } from '../components/layout'
+import { ArchiveModalProvider } from '../lib/archive-modal-context'
+import { setSSRBasePath } from '../lib/static-mode'
+import { StaticDataProvider } from './static-data-context'
+import { Dashboard } from '../routes/dashboard'
+import { SpecList } from '../routes/spec-list'
+import { SpecView } from '../routes/spec-view'
+import { ChangeList } from '../routes/change-list'
+import { ChangeView } from '../routes/change-view'
+import { ArchiveList } from '../routes/archive-list'
+import { ArchiveView } from '../routes/archive-view'
+import { Project } from '../routes/project'
+import { Settings } from '../routes/settings'
+import type { ExportSnapshot } from '@openspecui/core'
+
+function createRouteTree() {
+  const rootRoute = createRootRoute({ component: RootLayout })
+
+  return rootRoute.addChildren([
+    createRoute({ getParentRoute: () => rootRoute, path: '/', component: Dashboard }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/specs', component: SpecList }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/specs/$specId', component: SpecView }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/changes', component: ChangeList }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/changes/$changeId', component: ChangeView }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/archive', component: ArchiveList }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/archive/$changeId', component: ArchiveView }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/project', component: Project }),
+    createRoute({ getParentRoute: () => rootRoute, path: '/settings', component: Settings }),
+  ])
+}
+
+/**
+ * Render a route to HTML string
+ */
+export async function render(url: string, snapshot: ExportSnapshot, basePath = '/'): Promise<string> {
+  setSSRBasePath(basePath)
+
+  const router = createRouter({
+    routeTree: createRouteTree(),
+    history: createMemoryHistory({ initialEntries: [url] }),
+    basepath: basePath,
+  })
+
+  await router.load()
+
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, staleTime: Infinity } },
+  })
+
+  return renderToString(
+    <StaticDataProvider snapshot={snapshot} basePath={basePath}>
+      <QueryClientProvider client={queryClient}>
+        <ArchiveModalProvider>
+          <RouterProvider router={router} />
+        </ArchiveModalProvider>
+      </QueryClientProvider>
+    </StaticDataProvider>
+  )
+}
+
+/**
+ * Get all routes to pre-render
+ */
+export function getRoutes(snapshot: ExportSnapshot): string[] {
+  return [
+    '/',
+    '/specs',
+    '/changes',
+    '/archive',
+    '/project',
+    '/settings',
+    ...snapshot.specs.map(s => `/specs/${s.id}`),
+    ...snapshot.changes.map(c => `/changes/${c.id}`),
+    ...snapshot.archives.map(a => `/archive/${a.id}`),
+  ]
+}
+
+/**
+ * Get page title for a route
+ */
+export function getTitle(path: string, snapshot: ExportSnapshot): string {
+  if (path === '/') return 'Dashboard'
+  if (path === '/specs') return 'Specifications'
+  if (path === '/changes') return 'Active Changes'
+  if (path === '/archive') return 'Archived Changes'
+  if (path === '/project') return 'Project'
+  if (path === '/settings') return 'Settings'
+
+  const specMatch = path.match(/^\/specs\/(.+)$/)
+  if (specMatch) return snapshot.specs.find(s => s.id === specMatch[1])?.name || 'Spec'
+
+  const changeMatch = path.match(/^\/changes\/(.+)$/)
+  if (changeMatch) return snapshot.changes.find(c => c.id === changeMatch[1])?.name || 'Change'
+
+  const archiveMatch = path.match(/^\/archive\/(.+)$/)
+  if (archiveMatch) return snapshot.archives.find(a => a.id === archiveMatch[1])?.name || 'Archive'
+
+  return 'OpenSpec UI'
+}

package/src/ssg/index.ts

@@ -0,0 +1,6 @@
+/**
+ * SSG module exports
+ */
+export { render, getRoutes, getTitle } from './entry-server'
+export { StaticDataProvider, useStaticData, useStaticSnapshot, useIsStaticMode, useBasePath } from './static-data-context'
+export type { ExportSnapshot } from '@openspecui/core'

package/src/ssg/prerender.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Pre-render script for SSG
+ *
+ * Usage:
+ *   # First build client and server:
+ *   pnpm build:client
+ *   pnpm build:server
+ *
+ *   # Then pre-render:
+ *   node dist/server/prerender.js --data ./data.json --output ./dist/client
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+interface Options {
+  data: string
+  output: string
+  basePath: string
+}
+
+function parseArgs(): Options {
+  const args = process.argv.slice(2)
+  const options: Options = { data: '', output: '', basePath: '/' }
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--data' || args[i] === '-d') options.data = args[++i]
+    else if (args[i] === '--output' || args[i] === '-o') options.output = args[++i]
+    else if (args[i] === '--base-path' || args[i] === '-b') options.basePath = args[++i]
+  }
+
+  if (!options.data || !options.output) {
+    console.error('Usage: node prerender.js --data <data.json> --output <dir>')
+    process.exit(1)
+  }
+
+  return options
+}
+
+async function prerender() {
+  const { data, output, basePath } = parseArgs()
+  const outputDir = resolve(output)
+  const dataPath = resolve(data)
+
+  console.log('\n=== OpenSpec UI Pre-render ===\n')
+
+  // 1. Read data.json
+  const snapshot = JSON.parse(readFileSync(dataPath, 'utf-8'))
+  console.log(`Data: ${snapshot.specs.length} specs, ${snapshot.changes.length} changes`)
+
+  // 2. Read HTML template (generated by vite build)
+  const templatePath = join(outputDir, 'index.html')
+  if (!existsSync(templatePath)) {
+    throw new Error(`Template not found: ${templatePath}\nRun 'pnpm build:client' first.`)
+  }
+  const template = readFileSync(templatePath, 'utf-8')
+
+  // 3. Import SSR module
+  const { render, getRoutes, getTitle } = await import('./entry-server.js')
+
+  // 4. Pre-render each route
+  const routes = getRoutes(snapshot)
+  console.log(`Routes: ${routes.length}\n`)
+
+  // Generate head tags for injecting data
+  const headTags = `
+    <script>
+      window.__OPENSPEC_BASE_PATH__ = '${basePath}';
+      window.__OPENSPEC_STATIC_MODE__ = true;
+      window.__INITIAL_DATA__ = ${JSON.stringify(snapshot)};
+    </script>`
+
+  for (const route of routes) {
+    const appHtml = await render(route, snapshot, basePath)
+    const title = getTitle(route, snapshot)
+
+    const html = template
+      .replace('<!--app-html-->', appHtml)
+      .replace('<!--head-tags-->', headTags)
+      .replace('<title>OpenSpec UI</title>', `<title>${title} - OpenSpec UI</title>`)
+
+    // Write HTML file
+    if (route === '/') {
+      writeFileSync(join(outputDir, 'index.html'), html)
+    } else {
+      const routeDir = join(outputDir, route.slice(1))
+      mkdirSync(routeDir, { recursive: true })
+      writeFileSync(join(routeDir, 'index.html'), html)
+    }
+    console.log(`  ${route}`)
+  }
+
+  // 5. Copy index.html to 404.html
+  copyFileSync(join(outputDir, 'index.html'), join(outputDir, '404.html'))
+
+  // 6. Copy data.json to output
+  copyFileSync(dataPath, join(outputDir, 'data.json'))
+
+  // 7. Cleanup .vite directory
+  const viteDir = join(outputDir, '.vite')
+  if (existsSync(viteDir)) {
+    rmSync(viteDir, { recursive: true })
+  }
+
+  console.log(`\nDone! ${routes.length} pages generated.\n`)
+}
+
+prerender().catch(err => {
+  console.error('Pre-render failed:', err.message)
+  process.exit(1)
+})

package/src/ssg/static-data-context.tsx

@@ -0,0 +1,49 @@
+/**
+ * Static data context for SSG
+ */
+import { createContext, useContext, type ReactNode } from 'react'
+import type { ExportSnapshot } from '@openspecui/core'
+
+interface StaticDataContextValue {
+  snapshot: ExportSnapshot | null
+  basePath: string
+  isStatic: boolean
+}
+
+const StaticDataContext = createContext<StaticDataContextValue>({
+  snapshot: null,
+  basePath: '/',
+  isStatic: false,
+})
+
+export function StaticDataProvider({
+  children,
+  snapshot,
+  basePath = '/',
+}: {
+  children: ReactNode
+  snapshot: ExportSnapshot | null
+  basePath?: string
+}) {
+  return (
+    <StaticDataContext.Provider value={{ snapshot, basePath, isStatic: true }}>
+      {children}
+    </StaticDataContext.Provider>
+  )
+}
+
+export function useStaticData() {
+  return useContext(StaticDataContext)
+}
+
+export function useStaticSnapshot() {
+  return useContext(StaticDataContext).snapshot
+}
+
+export function useIsStaticMode() {
+  return useContext(StaticDataContext).isStatic
+}
+
+export function useBasePath() {
+  return useContext(StaticDataContext).basePath
+}

package/src/ssg/types.ts

@@ -0,0 +1,5 @@
+/**
+ * Types for SSG export
+ * Re-exported from @openspecui/core for convenience
+ */
+export type { ExportSnapshot } from '@openspecui/core'

package/src/test/setup.ts

@@ -0,0 +1 @@
+import '@testing-library/jest-dom/vitest'

package/src/vite-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module '*.css' {
+  const content: string
+  export default content
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "allowImportingTsExtensions": true,
+    "moduleDetection": "force",
+    "noUncheckedSideEffectImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"],
+      "@openspecui/server": ["../server/src/index.ts"],
+      "@openspecui/core": ["../core/src/index.ts"],
+      "@openspecui/ai-provider": ["../ai-provider/src/index.ts"]
+    }
+  },
+  "include": ["src"]
+}

package/vite.config.ts

@@ -0,0 +1,58 @@
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import { resolve } from 'path'
+import { defineConfig } from 'vite'
+
+function resolveBackendTarget(): string {
+  const explicit =
+    process.env.VITE_API_URL || process.env.OPENSPEC_SERVER_URL || process.env.API_URL
+  if (explicit) return explicit.replace(/\/$/, '')
+
+  const port = process.env.OPENSPEC_SERVER_PORT || process.env.SERVER_PORT || process.env.PORT
+  const targetPort = port ? Number(port) : 3100
+  return `http://localhost:${targetPort}`
+}
+
+export default defineConfig(({ isSsrBuild }) => {
+  const backendTarget = resolveBackendTarget()
+  console.log(`[dev-proxy] backend target => ${backendTarget}`)
+
+  // Always use base: '/' - base path is now configured at runtime via window.__OPENSPEC_BASE_PATH__
+  return {
+    base: '/',
+    plugins: [react(), tailwindcss()],
+    resolve: {
+      alias: {
+        '@': resolve(__dirname, './src'),
+        '@openspecui/core': resolve(__dirname, '../core/src'),
+        '@openspecui/server': resolve(__dirname, '../server/src'),
+      },
+    },
+    server: {
+      port: 5173,
+      proxy: {
+        '/trpc': {
+          target: backendTarget,
+          changeOrigin: true,
+          ws: true,
+        },
+        '/api': {
+          target: backendTarget,
+          changeOrigin: true,
+        },
+      },
+    },
+    test: {
+      environment: 'jsdom',
+      setupFiles: './src/test/setup.ts',
+    },
+    ssr: {
+      // SSR build: don't externalize these packages - bundle them
+      noExternal: isSsrBuild ? [
+        '@tanstack/react-router',
+        '@tanstack/react-query',
+        'lucide-react',
+      ] : [],
+    },
+  }
+})