@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/src/contexts/project-context.tsx

@@ -227,3 +227,27 @@ export function ProjectProvider({ children, initialProjectId }: ProjectProviderP
     </ProjectContext.Provider>
   );
 }
+
+/**
+ * Hook to generate project-scoped URLs
+ * Automatically uses project prefix in multi-project mode
+ */
+export function useProjectUrl() {
+  const { mode, currentProject } = useProject();
+  
+  const getUrl = useCallback((path: string) => {
+    if (mode === 'multi-project' && currentProject) {
+      // Ensure path starts with /
+      const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+      return `/projects/${currentProject.id}${normalizedPath}`;
+    }
+    return path.startsWith('/') ? path : `/${path}`;
+  }, [mode, currentProject]);
+
+  const getSpecUrl = useCallback((specId: string | number, subSpec?: string) => {
+    const base = getUrl(`/specs/${specId}`);
+    return subSpec ? `${base}?subspec=${subSpec}` : base;
+  }, [getUrl]);
+
+  return { getUrl, getSpecUrl, isMultiProject: mode === 'multi-project', projectId: currentProject?.id };
+}

package/.next/standalone/packages/ui/src/lib/db/service-queries.ts

@@ -5,9 +5,10 @@
 
 import { specsService } from '../specs/service';
 import type { Spec } from './schema';
+import type { ContextFile, ProjectContext, LeanSpecConfig } from '../specs/types';
 import { detectSubSpecs } from '../sub-specs';
-import { join, resolve } from 'path';
-import { readFileSync } from 'node:fs';
+import { join, resolve, dirname } from 'path';
+import { readFileSync, existsSync, statSync, readdirSync } from 'node:fs';
 import matter from 'gray-matter';
 
 /**
@@ -17,6 +18,20 @@ export type ParsedSpec = Omit<Spec, 'tags'> & {
   tags: string[] | null;
 };
 
+/**
+ * Lightweight spec for list views (excludes contentMd to reduce payload size)
+ * The full contentMd can be 1MB+ for all specs combined
+ */
+export type LightweightSpec = Omit<ParsedSpec, 'contentMd' | 'contentHtml'>;
+
+/**
+ * Strip contentMd from a spec to create a lightweight version
+ */
+function toLightweightSpec<T extends ParsedSpec>(spec: T): Omit<T, 'contentMd' | 'contentHtml'> {
+  const { contentMd, contentHtml, ...rest } = spec;
+  return rest;
+}
+
 const DEFAULT_SPECS_DIR = resolve(process.cwd(), '../../specs');
 
 function getSpecsRootDir(): string {
@@ -36,7 +51,7 @@ function buildSpecDirPath(filePath: string): string {
 
 interface SpecRelationships {
   dependsOn: string[];
-  related: string[];
+  requiredBy: string[];
 }
 function normalizeRelationshipList(value: unknown): string[] {
   if (!value) return [];
@@ -55,14 +70,14 @@ function getFilesystemRelationships(specDirPath: string): SpecRelationships {
     const raw = readFileSync(readmePath, 'utf-8');
     const { data } = matter(raw);
     const dependsOn = normalizeRelationshipList(data?.depends_on ?? data?.dependsOn);
-    const related = normalizeRelationshipList(data?.related);
+    // Note: requiredBy is computed from the dependency graph, not stored in frontmatter
     return {
       dependsOn,
-      related,
+      requiredBy: [],
     };
   } catch (error) {
     console.warn('Unable to parse spec relationships', error);
-    return { dependsOn: [], related: [] };
+    return { dependsOn: [], requiredBy: [] };
   }
 }
 
@@ -81,7 +96,6 @@ function parseSpecTags(spec: Spec): ParsedSpec {
  */
 function countSubSpecs(specDirPath: string): number {
   try {
-    const { readdirSync, existsSync, statSync } = require('fs');
     if (!existsSync(specDirPath)) return 0;
     
     const entries = readdirSync(specDirPath);
@@ -112,55 +126,79 @@ function countSubSpecs(specDirPath: string): number {
 
 /**
  * Get all specs (uses filesystem by default, database if projectId provided)
+ * Returns lightweight specs without contentMd for list views
  */
-export async function getSpecs(projectId?: string): Promise<ParsedSpec[]> {
+export async function getSpecs(projectId?: string): Promise<LightweightSpec[]> {
   const specs = await specsService.getAllSpecs(projectId);
-  return specs.map(parseSpecTags);
+  return specs.map(spec => toLightweightSpec(parseSpecTags(spec)));
 }
 
 /**
  * Get all specs with sub-spec count (for sidebar)
+ * Returns lightweight specs without contentMd
  */
-export async function getSpecsWithSubSpecCount(projectId?: string): Promise<(ParsedSpec & { subSpecsCount: number })[]> {
+export async function getSpecsWithSubSpecCount(projectId?: string): Promise<(LightweightSpec & { subSpecsCount: number })[]> {
   const specs = await specsService.getAllSpecs(projectId);
   
   // Only count sub-specs for filesystem mode
   if (projectId) {
-    return specs.map(spec => ({ ...parseSpecTags(spec), subSpecsCount: 0 }));
+    return specs.map(spec => ({ ...toLightweightSpec(parseSpecTags(spec)), subSpecsCount: 0 }));
   }
   
   return specs.map(spec => {
     const specDirPath = buildSpecDirPath(spec.filePath);
     const subSpecsCount = countSubSpecs(specDirPath);
-    return { ...parseSpecTags(spec), subSpecsCount };
+    return { ...toLightweightSpec(parseSpecTags(spec)), subSpecsCount };
   });
 }
 
 /**
  * Get all specs with sub-spec count and relationships (for comprehensive list view)
+ * Builds the full dependency graph to compute requiredBy (reverse dependencies)
+ * Returns lightweight specs without contentMd
  */
-export async function getSpecsWithMetadata(projectId?: string): Promise<(ParsedSpec & { subSpecsCount: number; relationships: SpecRelationships })[]> {
+export async function getSpecsWithMetadata(projectId?: string): Promise<(LightweightSpec & { subSpecsCount: number; relationships: SpecRelationships })[]> {
   const specs = await specsService.getAllSpecs(projectId);
   
   // Only count sub-specs and relationships for filesystem mode
   if (projectId) {
     return specs.map(spec => ({ 
-      ...parseSpecTags(spec), 
+      ...toLightweightSpec(parseSpecTags(spec)), 
       subSpecsCount: 0,
-      relationships: { dependsOn: [], related: [] }
+      relationships: { dependsOn: [], requiredBy: [] }
     }));
   }
   
+  // First pass: collect all dependsOn relationships
+  const specRelationshipsMap = new Map<string, { dependsOn: string[]; requiredBy: string[] }>();
+  
+  for (const spec of specs) {
+    const specDirPath = buildSpecDirPath(spec.filePath);
+    const { dependsOn } = getFilesystemRelationships(specDirPath);
+    specRelationshipsMap.set(spec.specName, { dependsOn, requiredBy: [] });
+  }
+  
+  // Second pass: compute requiredBy (reverse lookup)
+  for (const [specName, rels] of specRelationshipsMap.entries()) {
+    for (const dep of rels.dependsOn) {
+      const depRels = specRelationshipsMap.get(dep);
+      if (depRels) {
+        depRels.requiredBy.push(specName);
+      }
+    }
+  }
+  
   return specs.map(spec => {
     const specDirPath = buildSpecDirPath(spec.filePath);
     const subSpecsCount = countSubSpecs(specDirPath);
-    const relationships = getFilesystemRelationships(specDirPath);
-    return { ...parseSpecTags(spec), subSpecsCount, relationships };
+    const relationships = specRelationshipsMap.get(spec.specName) || { dependsOn: [], requiredBy: [] };
+    return { ...toLightweightSpec(parseSpecTags(spec)), subSpecsCount, relationships };
   });
 }
 
 /**
  * Get a spec by ID (number or UUID)
+ * Computes requiredBy by scanning all specs for reverse dependencies
  */
 export async function getSpecById(id: string, projectId?: string): Promise<(ParsedSpec & { subSpecs?: import('../sub-specs').SubSpec[]; relationships?: SpecRelationships }) | null> {
   const spec = await specsService.getSpec(id, projectId);
@@ -173,8 +211,22 @@ export async function getSpecById(id: string, projectId?: string): Promise<(Pars
   if (!projectId) {
     const specDirPath = buildSpecDirPath(spec.filePath);
     const subSpecs = detectSubSpecs(specDirPath);
-    const relationships = getFilesystemRelationships(specDirPath);
-    return { ...parsedSpec, subSpecs, relationships };
+    const { dependsOn } = getFilesystemRelationships(specDirPath);
+    
+    // Compute requiredBy by scanning all specs
+    const allSpecs = await specsService.getAllSpecs();
+    const requiredBy: string[] = [];
+    
+    for (const otherSpec of allSpecs) {
+      if (otherSpec.specName === spec.specName) continue;
+      const otherSpecDirPath = buildSpecDirPath(otherSpec.filePath);
+      const otherRels = getFilesystemRelationships(otherSpecDirPath);
+      if (otherRels.dependsOn.includes(spec.specName)) {
+        requiredBy.push(otherSpec.specName);
+      }
+    }
+    
+    return { ...parsedSpec, subSpecs, relationships: { dependsOn, requiredBy } };
   }
 
   return parsedSpec;
@@ -182,21 +234,23 @@ export async function getSpecById(id: string, projectId?: string): Promise<(Pars
 
 /**
  * Get specs by status
+ * Returns lightweight specs without contentMd
  */
 export async function getSpecsByStatus(
   status: 'planned' | 'in-progress' | 'complete' | 'archived',
   projectId?: string
-): Promise<ParsedSpec[]> {
+): Promise<LightweightSpec[]> {
   const specs = await specsService.getSpecsByStatus(status, projectId);
-  return specs.map(parseSpecTags);
+  return specs.map(spec => toLightweightSpec(parseSpecTags(spec)));
 }
 
 /**
  * Search specs
+ * Returns lightweight specs without contentMd (search happens server-side)
  */
-export async function searchSpecs(query: string, projectId?: string): Promise<ParsedSpec[]> {
+export async function searchSpecs(query: string, projectId?: string): Promise<LightweightSpec[]> {
   const specs = await specsService.searchSpecs(query, projectId);
-  return specs.map(parseSpecTags);
+  return specs.map(spec => toLightweightSpec(parseSpecTags(spec)));
 }
 
 /**
@@ -237,3 +291,172 @@ export async function getStats(projectId?: string): Promise<StatsResult> {
     completionRate: Math.round(completionRate * 10) / 10,
   };
 }
+
+// ============================================================================
+// Project Context Functions (Spec 131)
+// ============================================================================
+
+/**
+ * Get the project root directory (parent of specs directory)
+ */
+function getProjectRootDir(): string {
+  const specsDir = getSpecsRootDir();
+  return dirname(specsDir);
+}
+
+/**
+ * Simple token estimation (approximation without tiktoken for browser compatibility)
+ * Uses the common heuristic of ~4 characters per token for English text
+ */
+function estimateTokens(text: string): number {
+  // More accurate estimation:
+  // - Count words (roughly 1.3 tokens per word for English)
+  // - Account for punctuation and special characters
+  const words = text.split(/\s+/).filter(w => w.length > 0).length;
+  const specialChars = (text.match(/[^a-zA-Z0-9\s]/g) || []).length;
+  return Math.ceil(words * 1.3 + specialChars * 0.5);
+}
+
+/**
+ * Read a context file and return its metadata
+ */
+function readContextFile(filePath: string, projectRoot: string): ContextFile | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    
+    const stats = statSync(filePath);
+    const content = readFileSync(filePath, 'utf-8');
+    const relativePath = filePath.replace(projectRoot + '/', '');
+    
+    return {
+      name: relativePath.split('/').pop() || relativePath,
+      path: relativePath,
+      content,
+      tokenCount: estimateTokens(content),
+      lastModified: stats.mtime,
+    };
+  } catch (error) {
+    console.warn(`Unable to read context file: ${filePath}`, error);
+    return null;
+  }
+}
+
+/**
+ * Get agent instruction files (AGENTS.md, GEMINI.md, etc.)
+ */
+export async function getAgentInstructions(projectRootOverride?: string): Promise<ContextFile[]> {
+  const projectRoot = projectRootOverride || getProjectRootDir();
+  const files: ContextFile[] = [];
+  
+  // Primary agent instruction files in root
+  const rootAgentFiles = [
+    'AGENTS.md',
+    'GEMINI.md',
+    'CLAUDE.md',
+    'COPILOT.md',
+  ];
+  
+  for (const fileName of rootAgentFiles) {
+    const file = readContextFile(join(projectRoot, fileName), projectRoot);
+    if (file) files.push(file);
+  }
+  
+  // Check .github/copilot-instructions.md
+  const copilotInstructions = readContextFile(
+    join(projectRoot, '.github', 'copilot-instructions.md'),
+    projectRoot
+  );
+  if (copilotInstructions) files.push(copilotInstructions);
+  
+  // Check docs/agents/*.md
+  const agentsDocsDir = join(projectRoot, 'docs', 'agents');
+  if (existsSync(agentsDocsDir)) {
+    try {
+      const entries = readdirSync(agentsDocsDir);
+      for (const entry of entries) {
+        if (entry.endsWith('.md')) {
+          const file = readContextFile(join(agentsDocsDir, entry), projectRoot);
+          if (file) files.push(file);
+        }
+      }
+    } catch {
+      // Directory might not be accessible
+    }
+  }
+  
+  return files;
+}
+
+/**
+ * Get LeanSpec configuration
+ */
+export async function getProjectConfig(projectRootOverride?: string): Promise<{ file: ContextFile | null; parsed: LeanSpecConfig | null }> {
+  const projectRoot = projectRootOverride || getProjectRootDir();
+  const configPath = join(projectRoot, '.lean-spec', 'config.json');
+  
+  const file = readContextFile(configPath, projectRoot);
+  
+  if (!file) {
+    return { file: null, parsed: null };
+  }
+  
+  try {
+    const parsed = JSON.parse(file.content) as LeanSpecConfig;
+    return { file, parsed };
+  } catch {
+    return { file, parsed: null };
+  }
+}
+
+/**
+ * Get project documentation files (README, CONTRIBUTING, etc.)
+ */
+export async function getProjectDocs(projectRootOverride?: string): Promise<ContextFile[]> {
+  const projectRoot = projectRootOverride || getProjectRootDir();
+  const files: ContextFile[] = [];
+  
+  const docFiles = [
+    'README.md',
+    'CONTRIBUTING.md',
+    'CHANGELOG.md',
+  ];
+  
+  for (const fileName of docFiles) {
+    const file = readContextFile(join(projectRoot, fileName), projectRoot);
+    if (file) files.push(file);
+  }
+  
+  return files;
+}
+
+/**
+ * Get complete project context
+ */
+export async function getProjectContext(projectRootOverride?: string): Promise<ProjectContext> {
+  const projectRoot = projectRootOverride || getProjectRootDir();
+  const [agentInstructions, config, projectDocs] = await Promise.all([
+    getAgentInstructions(projectRoot),
+    getProjectConfig(projectRoot),
+    getProjectDocs(projectRoot),
+  ]);
+  
+  // Calculate total tokens
+  let totalTokens = 0;
+  for (const file of agentInstructions) {
+    totalTokens += file.tokenCount;
+  }
+  if (config.file) {
+    totalTokens += config.file.tokenCount;
+  }
+  for (const file of projectDocs) {
+    totalTokens += file.tokenCount;
+  }
+  
+  return {
+    agentInstructions,
+    config,
+    projectDocs,
+    totalTokens,
+    projectRoot,
+  };
+}

package/.next/standalone/packages/ui/src/lib/dependency-graph.ts

@@ -7,7 +7,6 @@ export interface SpecFrontmatter {
   status: string;
   created: string;
   depends_on?: string[];
-  related?: string[];
   priority?: string;
   tags?: string[];
   assignee?: string;
@@ -24,14 +23,12 @@ export interface SpecInfo {
 interface DependencyNode {
   dependsOn: Set<string>;
   requiredBy: Set<string>;
-  related: Set<string>;
 }
 
 export interface CompleteDependencyGraph {
   current: SpecInfo;
   dependsOn: SpecInfo[];
   requiredBy: SpecInfo[];
-  related: SpecInfo[];
 }
 
 /**
@@ -54,7 +51,6 @@ export class SpecDependencyGraph {
       this.graph.set(spec.path, {
         dependsOn: new Set(spec.frontmatter.depends_on || []),
         requiredBy: new Set(),
-        related: new Set(spec.frontmatter.related || []),
       });
     }
 
@@ -67,14 +63,6 @@ export class SpecDependencyGraph {
           depNode.requiredBy.add(specPath);
         }
       }
-      
-      // For each related, add bidirectional link
-      for (const rel of node.related) {
-        const relNode = this.graph.get(rel);
-        if (relNode) {
-          relNode.related.add(specPath);
-        }
-      }
     }
   }
 
@@ -93,7 +81,6 @@ export class SpecDependencyGraph {
       current: spec,
       dependsOn: this.getSpecsByPaths(Array.from(node.dependsOn)),
       requiredBy: this.getSpecsByPaths(Array.from(node.requiredBy)),
-      related: this.getSpecsByPaths(Array.from(node.related)),
     };
   }
 

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

@@ -53,3 +53,47 @@ export interface CachedSpec<T = Spec | Spec[]> {
   data: T;
   expiresAt: number;
 }
+
+/**
+ * Context file representation for project context visibility
+ */
+export interface ContextFile {
+  name: string;
+  path: string;
+  content: string;
+  tokenCount: number;
+  lastModified: Date;
+}
+
+/**
+ * LeanSpec configuration (from .lean-spec/config.json)
+ */
+export interface LeanSpecConfig {
+  template?: string;
+  specsDir?: string;
+  structure?: {
+    pattern?: string;
+    prefix?: string;
+    dateFormat?: string;
+    sequenceDigits?: number;
+    defaultFile?: string;
+  };
+  features?: {
+    aiAgents?: boolean;
+  };
+  templates?: Record<string, string>;
+}
+
+/**
+ * Project context containing all contextual files
+ */
+export interface ProjectContext {
+  agentInstructions: ContextFile[];  // AGENTS.md, GEMINI.md, etc.
+  config: {
+    file: ContextFile | null;        // .lean-spec/config.json
+    parsed: LeanSpecConfig | null;   // Parsed config object
+  };
+  projectDocs: ContextFile[];        // README.md, CONTRIBUTING.md, etc.
+  totalTokens: number;
+  projectRoot: string;               // Absolute path to project root (for editor links)
+}

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

@@ -1,10 +1,9 @@
-import type { ParsedSpec } from '@/lib/db/service-queries';
+import type { ParsedSpec, LightweightSpec } 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)
+  requiredBy: string[]; // Downstream dependents (specs that depend on this one)
 }
 
 export type SpecWithMetadata = ParsedSpec & {
@@ -12,7 +11,10 @@ export type SpecWithMetadata = ParsedSpec & {
   relationships?: SpecRelationships;
 };
 
-export type SidebarSpec = Pick<SpecWithMetadata, 'id' | 'specNumber' | 'title' | 'specName' | 'status' | 'priority' | 'contentMd' | 'updatedAt'> & {
+/**
+ * Lightweight spec type for sidebar (no contentMd for performance)
+ */
+export type SidebarSpec = Pick<LightweightSpec, 'id' | 'specNumber' | 'title' | 'specName' | 'status' | 'priority' | 'updatedAt'> & {
   tags: string[] | null;
   subSpecsCount?: number;
 };