@leanspec/ui 0.2.8 → 0.2.9

package/.next/standalone/packages/ui/dist/standalone/packages/web/src/lib/specs/sources/filesystem-source.ts

@@ -0,0 +1,249 @@
+/**
+ * Filesystem-based spec source
+ * Reads specs directly from the filesystem with in-memory caching
+ */
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import matter from 'gray-matter';
+import type { SpecSource, CachedSpec } from '../types';
+import type { Spec } from '../../db/schema';
+
+// Cache TTL from environment
+// Default: 0ms in development, 60s in production
+const isDev = process.env.NODE_ENV === 'development';
+const CACHE_TTL = parseInt(process.env.CACHE_TTL || (isDev ? '0' : '60000'), 10);
+
+/**
+ * Filesystem source implementation
+ * Reads specs from local filesystem with in-memory caching
+ */
+export class FilesystemSource implements SpecSource {
+  private cache = new Map<string, CachedSpec<Spec | Spec[]>>();
+  private specsDir: string;
+
+  constructor(specsDir?: string) {
+    // Default to ../../specs relative to the web package
+    this.specsDir = specsDir || path.join(process.cwd(), '../../specs');
+  }
+
+  /**
+   * Get all specs from filesystem
+   */
+  async getAllSpecs(): Promise<Spec[]> {
+    const cacheKey = '__all_specs__';
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.data as Spec[];
+    }
+
+    const specs = await this.loadSpecsFromFilesystem();
+
+    this.cache.set(cacheKey, {
+      data: specs,
+      expiresAt: Date.now() + CACHE_TTL,
+    });
+
+    return specs;
+  }
+
+  /**
+   * Get a single spec by path
+   */
+  async getSpec(specPath: string): Promise<Spec | null> {
+    const cacheKey = `spec:${specPath}`;
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.data as Spec;
+    }
+
+    // Parse spec number from path (e.g., "035" or "035-my-spec")
+    const specNum = parseInt(specPath.split('-')[0], 10);
+    if (isNaN(specNum)) {
+      return null;
+    }
+
+    const spec = await this.loadSpecByNumber(specNum);
+
+    if (spec) {
+      this.cache.set(cacheKey, {
+        data: spec,
+        expiresAt: Date.now() + CACHE_TTL,
+      });
+    }
+
+    return spec;
+  }
+
+  /**
+   * Get specs by status
+   */
+  async getSpecsByStatus(status: 'planned' | 'in-progress' | 'complete' | 'archived'): Promise<Spec[]> {
+    const allSpecs = await this.getAllSpecs();
+    return allSpecs.filter((spec) => spec.status === status);
+  }
+
+  /**
+   * Search specs by query (basic implementation)
+   */
+  async searchSpecs(query: string): Promise<Spec[]> {
+    const allSpecs = await this.getAllSpecs();
+    const lowerQuery = query.toLowerCase();
+
+    return allSpecs.filter((spec) => {
+      // Search in spec name, title, and content
+      return (
+        spec.specName.toLowerCase().includes(lowerQuery) ||
+        spec.title?.toLowerCase().includes(lowerQuery) ||
+        spec.contentMd.toLowerCase().includes(lowerQuery)
+      );
+    });
+  }
+
+  /**
+   * Invalidate cache
+   */
+  invalidateCache(specPath?: string): void {
+    if (specPath) {
+      this.cache.delete(`spec:${specPath}`);
+      // Also invalidate the all specs cache since it contains this spec
+      this.cache.delete('__all_specs__');
+    } else {
+      this.cache.clear();
+    }
+  }
+
+  /**
+   * Load all specs from filesystem
+   */
+  private async loadSpecsFromFilesystem(): Promise<Spec[]> {
+    const specs: Spec[] = [];
+
+    try {
+      await fs.access(this.specsDir);
+    } catch {
+      // Specs directory doesn't exist
+      return [];
+    }
+
+    // Pattern to match spec directories (2 or more digits followed by dash)
+    const specPattern = /^(\d{2,})-/;
+
+    const entries = await fs.readdir(this.specsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'archived') continue; // Skip archived directory
+
+      if (specPattern.test(entry.name)) {
+        const specDir = path.join(this.specsDir, entry.name);
+        const spec = await this.loadSpecFromDirectory(specDir, entry.name);
+        if (spec) {
+          specs.push(spec);
+        }
+      }
+    }
+
+    // Sort by spec number
+    return specs.sort((a, b) => (a.specNumber || 0) - (b.specNumber || 0));
+  }
+
+  /**
+   * Load a single spec by number
+   */
+  private async loadSpecByNumber(specNum: number): Promise<Spec | null> {
+    try {
+      await fs.access(this.specsDir);
+    } catch {
+      return null;
+    }
+
+    const entries = await fs.readdir(this.specsDir, { withFileTypes: true });
+    const specPattern = new RegExp(`^0*${specNum}-`);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (specPattern.test(entry.name)) {
+        const specDir = path.join(this.specsDir, entry.name);
+        return await this.loadSpecFromDirectory(specDir, entry.name);
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Load a spec from a directory
+   */
+  private async loadSpecFromDirectory(specDir: string, specName: string): Promise<Spec | null> {
+    const readmePath = path.join(specDir, 'README.md');
+
+    try {
+      const rawContent = await fs.readFile(readmePath, 'utf-8');
+      const { data: frontmatter, content: markdownContent } = matter(rawContent);
+
+      if (!frontmatter || !frontmatter.status) {
+        return null;
+      }
+
+      // Extract spec number from directory name
+      const specNumMatch = specName.match(/^(\d+)/);
+      const specNumber = specNumMatch ? parseInt(specNumMatch[1], 10) : null;
+
+      // Generate a pseudo-ID for filesystem specs (not stored in DB)
+      const id = `fs-${specName}`;
+
+      const createdValue = frontmatter.created_at ?? frontmatter.created;
+      const updatedValue = frontmatter.updated_at ?? frontmatter.updated;
+      const completedValue = frontmatter.completed_at ?? frontmatter.completed;
+
+      const toDate = (value: unknown): Date | null => {
+        if (!value) return null;
+        const parsed = new Date(value as string | number | Date);
+        return isNaN(parsed.getTime()) ? null : parsed;
+      };
+
+      // Create a Spec object compatible with the schema
+      const spec: Spec = {
+        id,
+        projectId: 'leanspec', // Default project for LeanSpec's own specs
+        specNumber,
+        specName,
+        title: this.extractTitle(markdownContent),
+        status: frontmatter.status || 'planned',
+        priority: frontmatter.priority || null,
+        tags: frontmatter.tags ? JSON.stringify(frontmatter.tags) : null,
+        assignee: frontmatter.assignee || null,
+        contentMd: markdownContent, // Use parsed content without frontmatter
+        contentHtml: null, // Not pre-rendered for filesystem mode
+        createdAt: toDate(createdValue),
+        updatedAt: toDate(updatedValue),
+        completedAt: toDate(completedValue),
+        filePath: `specs/${specName}/README.md`,
+        githubUrl: `https://github.com/codervisor/lean-spec/tree/main/specs/${specName}/README.md`,
+        syncedAt: new Date(), // Current time for filesystem reads
+      };
+
+      return spec;
+    } catch {
+      // File doesn't exist or can't be read
+      return null;
+    }
+  }
+
+  /**
+   * Extract title from markdown content (first H1)
+   */
+  private extractTitle(content: string): string | null {
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const match = line.match(/^#\s+(.+)$/);
+      if (match) {
+        return match[1].trim();
+      }
+    }
+    return null;
+  }
+}

package/.next/standalone/packages/ui/dist/standalone/packages/web/src/lib/specs/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Types for the specs service layer
+ */
+
+import type { Spec } from '../db/schema';
+
+/**
+ * Unified interface for accessing specs from different sources
+ * (filesystem or database)
+ */
+export interface SpecSource {
+  /**
+   * Get all specs, optionally filtered by projectId
+   * @param projectId - Optional project ID for database mode
+   */
+  getAllSpecs(projectId?: string): Promise<Spec[]>;
+
+  /**
+   * Get a single spec by its identifier
+   * @param specPath - Spec identifier (e.g., "035" or "035-my-spec")
+   * @param projectId - Optional project ID for database mode
+   */
+  getSpec(specPath: string, projectId?: string): Promise<Spec | null>;
+
+  /**
+   * Get specs filtered by status
+   * @param status - Status to filter by
+   * @param projectId - Optional project ID for database mode
+   */
+  getSpecsByStatus(
+    status: 'planned' | 'in-progress' | 'complete' | 'archived',
+    projectId?: string
+  ): Promise<Spec[]>;
+
+  /**
+   * Search specs by query
+   * @param query - Search query string
+   * @param projectId - Optional project ID for database mode
+   */
+  searchSpecs(query: string, projectId?: string): Promise<Spec[]>;
+
+  /**
+   * Invalidate cache for a specific spec or all specs
+   * @param specPath - Optional spec path to invalidate, or undefined for all
+   */
+  invalidateCache(specPath?: string): void;
+}
+
+/**
+ * Cached spec entry with expiration
+ */
+export interface CachedSpec<T = Spec | Spec[]> {
+  data: T;
+  expiresAt: number;
+}

package/.next/standalone/packages/ui/dist/standalone/packages/web/src/lib/stores/specs-sidebar-store.ts

@@ -0,0 +1,152 @@
+'use client';
+
+import * as React from 'react';
+import { useSyncExternalStore } from 'react';
+import type { SidebarSpec } from '@/types/specs';
+
+interface SidebarState {
+  specs: SidebarSpec[];
+  signature: string | null;
+  scrollTop: number;
+  activeSpecId: string | null;
+}
+
+let state: SidebarState = {
+  specs: [],
+  signature: null,
+  scrollTop: 0,
+  activeSpecId: null,
+};
+
+const EMPTY_SIDEBAR_SPECS: SidebarSpec[] = [];
+
+const listeners = new Set<() => void>();
+
+// Separate listeners for different state slices to avoid unnecessary re-renders
+const specsListeners = new Set<() => void>();
+const activeSpecListeners = new Set<() => void>();
+
+function emitChange() {
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+function emitSpecsChange() {
+  for (const listener of specsListeners) {
+    listener();
+  }
+}
+
+function emitActiveSpecChange() {
+  for (const listener of activeSpecListeners) {
+    listener();
+  }
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getState() {
+  return state;
+}
+
+function computeSignature(specs: SidebarSpec[]): string {
+  return specs
+    .map((spec) => [
+      spec.id,
+      spec.specNumber ?? '',
+      spec.title ?? '',
+      spec.status ?? '',
+      spec.priority ?? '',
+      spec.updatedAt ? new Date(spec.updatedAt).getTime() : 0,
+    ].join(':'))
+    .join('|');
+}
+
+export function useSpecsSidebarState() {
+  return useSyncExternalStore(subscribe, getState, () => state);
+}
+
+// Optimized selector hooks that only subscribe to specific state slices
+export function useSpecsSidebarSpecs() {
+  const subscribeToSpecs = React.useCallback((listener: () => void) => {
+    specsListeners.add(listener);
+    return () => {
+      specsListeners.delete(listener);
+    };
+  }, []);
+
+  return useSyncExternalStore(
+    subscribeToSpecs,
+    () => getState().specs,
+    () => EMPTY_SIDEBAR_SPECS
+  );
+}
+
+export function useSpecsSidebarActiveSpec() {
+  const subscribeToActiveSpec = React.useCallback((listener: () => void) => {
+    activeSpecListeners.add(listener);
+    return () => {
+      activeSpecListeners.delete(listener);
+    };
+  }, []);
+
+  return useSyncExternalStore(
+    subscribeToActiveSpec,
+    () => getState().activeSpecId,
+    () => null
+  );
+}
+
+export function primeSpecsSidebar(specs: SidebarSpec[]) {
+  if (specs.length === 0) {
+    return;
+  }
+
+  const signature = computeSignature(specs);
+  if (signature === state.signature) {
+    return;
+  }
+
+  state = {
+    ...state,
+    specs,
+    signature,
+  };
+  emitChange();
+  emitSpecsChange(); // Notify specs-specific listeners
+}
+
+export function setActiveSidebarSpec(specId: string) {
+  if (state.activeSpecId === specId) {
+    return;
+  }
+
+  state = {
+    ...state,
+    activeSpecId: specId,
+  };
+  emitChange();
+  emitActiveSpecChange(); // Notify activeSpec-specific listeners
+}
+
+export function updateSidebarScrollTop(nextScrollTop: number) {
+  if (Math.abs(nextScrollTop - state.scrollTop) < 1) {
+    return;
+  }
+
+  state = {
+    ...state,
+    scrollTop: nextScrollTop,
+  };
+  // Scroll position persistence should not trigger subscriber re-renders.
+}
+
+export function getSidebarScrollTop() {
+  return state.scrollTop;
+}

package/.next/standalone/packages/ui/dist/standalone/packages/web/src/lib/sub-specs.ts

@@ -0,0 +1,171 @@
+/**
+ * Sub-spec detection and management
+ */
+
+import { readdirSync, readFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import matter from 'gray-matter';
+
+export interface SubSpec {
+  name: string;
+  file: string;
+  iconName: string;
+  color: string;
+  content: string;
+}
+
+// Icon and color mapping with regex patterns for flexible matching
+const ICON_PATTERNS: Array<{ pattern: RegExp; iconName: string; color: string }> = [
+  // Design & UI
+  { pattern: /design|ui|ux|mockup|wireframe|prototype/i, iconName: 'Palette', color: 'text-purple-600' },
+  
+  // Architecture & Structure
+  { pattern: /architecture|structure|system|diagram/i, iconName: 'Map', color: 'text-indigo-600' },
+  
+  // Implementation & Code
+  { pattern: /implementation|code|develop|build/i, iconName: 'Code', color: 'text-green-600' },
+  
+  // API & Integration
+  { pattern: /api|endpoint|integration|interface/i, iconName: 'Code', color: 'text-blue-600' },
+  
+  // Testing & QA
+  { pattern: /test|qa|quality|validation/i, iconName: 'TestTube', color: 'text-orange-600' },
+  
+  // Tasks & Project Management
+  { pattern: /task|todo|checklist|milestone/i, iconName: 'CheckSquare', color: 'text-gray-600' },
+  
+  // Configuration & Setup
+  { pattern: /config|setup|settings|environment/i, iconName: 'Wrench', color: 'text-yellow-600' },
+  
+  // Deployment & DevOps
+  { pattern: /deploy|devops|ci|cd|pipeline|release/i, iconName: 'Wrench', color: 'text-orange-600' },
+  
+  // Migration & Updates
+  { pattern: /migration|upgrade|refactor|transition/i, iconName: 'GitBranch', color: 'text-cyan-600' },
+  
+  // Security & Authentication
+  { pattern: /security|auth|permission|access|encryption/i, iconName: 'CheckSquare', color: 'text-red-600' },
+  
+  // Performance & Optimization
+  { pattern: /performance|optimization|speed|cache|benchmark/i, iconName: 'TrendingUp', color: 'text-green-600' },
+  
+  // Database & Data
+  { pattern: /database|data|schema|model|query/i, iconName: 'FileText', color: 'text-blue-600' },
+  
+  // Documentation
+  { pattern: /doc|guide|manual|reference/i, iconName: 'FileText', color: 'text-gray-500' },
+  
+  // GitHub & Git
+  { pattern: /github|git|vcs|version/i, iconName: 'GitBranch', color: 'text-pink-600' },
+];
+
+// Default icon for unknown sub-spec types
+const DEFAULT_ICON = { iconName: 'FileText', color: 'text-gray-600' };
+
+/**
+ * Get icon and color for a sub-spec based on its name using regex patterns
+ */
+function getIconForSubSpec(fileName: string): { iconName: string; color: string } {
+  // Remove .md extension
+  const baseName = fileName.replace(/\.md$/i, '');
+  
+  // Try to match against patterns
+  for (const { pattern, iconName, color } of ICON_PATTERNS) {
+    if (pattern.test(baseName)) {
+      return { iconName, color };
+    }
+  }
+  
+  return DEFAULT_ICON;
+}
+
+/**
+ * Convert filename to display name (e.g., "DESIGN.md" -> "Design")
+ */
+function formatSubSpecName(fileName: string): string {
+  const baseName = fileName.replace(/\.md$/i, '');
+  // Convert to title case: "API-DESIGN" -> "Api Design", "TESTING" -> "Testing"
+  return baseName
+    .split(/[-_]/)
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join(' ');
+}
+
+/**
+ * Detect sub-spec files in a spec directory (dynamically finds all .md files except README.md)
+ */
+export function detectSubSpecs(specDirPath: string): SubSpec[] {
+  const subSpecs: SubSpec[] = [];
+
+  if (!existsSync(specDirPath)) {
+    return subSpecs;
+  }
+
+  try {
+    const entries = readdirSync(specDirPath);
+    
+    for (const entry of entries) {
+      // Skip README.md (main spec file), non-.md files, and directories
+      if (entry === 'README.md' || !entry.endsWith('.md')) {
+        continue;
+      }
+
+      const filePath = join(specDirPath, entry);
+      const stat = statSync(filePath);
+      
+      // Skip directories
+      if (!stat.isFile()) {
+        continue;
+      }
+
+      try {
+        const content = readFileSync(filePath, 'utf-8');
+        // Remove frontmatter if present
+        const { content: markdownContent } = matter(content);
+        const iconConfig = getIconForSubSpec(entry);
+        
+        subSpecs.push({
+          name: formatSubSpecName(entry),
+          file: entry,
+          iconName: iconConfig.iconName,
+          color: iconConfig.color,
+          content: markdownContent,
+        });
+      } catch (error) {
+        console.error(`Error reading sub-spec ${entry}:`, error);
+      }
+    }
+
+    // Sort alphabetically by filename for consistent ordering
+    subSpecs.sort((a, b) => a.file.localeCompare(b.file));
+  } catch (error) {
+    console.error(`Error reading spec directory ${specDirPath}:`, error);
+  }
+
+  return subSpecs;
+}
+
+/**
+ * Get sub-spec by name from a spec directory
+ */
+export function getSubSpec(specDirPath: string, fileName: string): SubSpec | null {
+  const filePath = join(specDirPath, fileName);
+  if (!existsSync(filePath)) return null;
+
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const { content: markdownContent } = matter(content);
+    const iconConfig = getIconForSubSpec(fileName);
+    
+    return {
+      name: formatSubSpecName(fileName),
+      file: fileName,
+      iconName: iconConfig.iconName,
+      color: iconConfig.color,
+      content: markdownContent,
+    };
+  } catch (error) {
+    console.error(`Error reading sub-spec ${fileName}:`, error);
+    return null;
+  }
+}

package/.next/standalone/packages/ui/dist/standalone/packages/web/src/lib/utils.ts

@@ -0,0 +1,17 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+/**
+ * Extract the first H1 heading from markdown content
+ */
+export function extractH1Title(markdown: string): string | null {
+  if (!markdown) return null;
+  
+  // Match first H1 heading (# Title)
+  const match = markdown.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : null;
+}

package/.next/standalone/packages/ui/dist/standalone/packages/web/src/types/specs.ts

@@ -0,0 +1,18 @@
+import type { ParsedSpec } from '@/lib/db/service-queries';
+import type { SubSpec } from '@/lib/sub-specs';
+
+export interface SpecRelationships {
+  dependsOn: string[];
+  related: string[];
+  requiredBy?: string[]; // Downstream dependents (specs that depend on this one)
+}
+
+export type SpecWithMetadata = ParsedSpec & {
+  subSpecs?: SubSpec[];
+  relationships?: SpecRelationships;
+};
+
+export type SidebarSpec = Pick<SpecWithMetadata, 'id' | 'specNumber' | 'title' | 'specName' | 'status' | 'priority' | 'contentMd' | 'updatedAt'> & {
+  tags: string[] | null;
+  subSpecsCount?: number;
+};