@leanspec/ui 0.2.8 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/082-web-realtime-sync-architecture/DATABASE.md

@@ -1,111 +0,0 @@
-### Mode 2: Database-Backed (External GitHub Repos)
-
-**Use Case:** Multi-project showcase (spec 035), external public repos
-
-**Data Flow:**
-```
-GitHub API → Sync Service → PostgreSQL → Web App
-     ↓              ↓             ↓
-Rate limits    Orchestration   Cache layer
-(5000/hr)      (scheduled)     (fast queries)
-```
-
-**Architecture:**
-```typescript
-// packages/web/src/lib/specs/sources/database-source.ts
-export class DatabaseSource implements SpecSource {
-  async getAllSpecs(projectId?: string): Promise<Spec[]> {
-    const query = projectId 
-      ? db.select().from(specs).where(eq(specs.projectId, projectId))
-      : db.select().from(specs);
-    
-    return await query.orderBy(specs.specNumber);
-  }
-  
-  async getSpec(specPath: string, projectId: string): Promise<Spec | null> {
-    // Parse spec number from path (e.g., "035" or "035-my-spec")
-    const specNum = parseInt(specPath.split('-')[0], 10);
-    
-    const results = await db.select()
-      .from(specs)
-      .where(and(
-        eq(specs.projectId, projectId),
-        eq(specs.specNumber, specNum)
-      ))
-      .limit(1);
-    
-    return results[0] || null;
-  }
-}
-
-// packages/web/src/lib/github/sync-service.ts
-export class GitHubSyncService {
-  private octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
-  
-  async syncProject(owner: string, repo: string, projectId: string) {
-    // 1. Fetch specs from GitHub
-    const repoSpecs = await this.discoverSpecs(owner, repo);
-    
-    // 2. Compare with database
-    const dbSpecs = await db.select()
-      .from(specs)
-      .where(eq(specs.projectId, projectId));
-    
-    // 3. Compute diff (added, updated, deleted)
-    const diff = this.computeDiff(repoSpecs, dbSpecs);
-    
-    // 4. Apply changes
-    await this.applyDiff(projectId, diff);
-    
-    // 5. Log sync result
-    await db.insert(syncLogs).values({
-      projectId,
-      status: 'success',
-      specsAdded: diff.added.length,
-      specsUpdated: diff.updated.length,
-      specsDeleted: diff.deleted.length,
-      completedAt: new Date(),
-    });
-  }
-  
-  private async discoverSpecs(owner: string, repo: string) {
-    // Fetch specs directory listing
-    const { data } = await this.octokit.repos.getContent({
-      owner,
-      repo,
-      path: 'specs',
-    });
-    
-    // Filter directories (ignore archived)
-    const specDirs = Array.isArray(data)
-      ? data.filter(item => item.type === 'dir' && item.name !== 'archived')
-      : [];
-    
-    // Fetch each spec's README.md
-    const specs = await Promise.all(
-      specDirs.map(dir => this.fetchSpec(owner, repo, dir.name))
-    );
-    
-    return specs.filter(Boolean);
-  }
-}
-```
-
-**Pros:**
-- ✅ **Handles rate limits**: Database caches GitHub data
-- ✅ **Fast queries**: Database optimized for filtering/sorting/search
-- ✅ **Multi-project support**: Can showcase many repos
-- ✅ **Scheduled sync**: Background jobs handle updates
-- ✅ **Relationships**: Can query cross-spec dependencies
-- ✅ **Audit trail**: Sync logs track changes
-
-**Cons:**
-- ⚠️ **Not realtime**: Sync delay (5-60 min typical)
-- ⚠️ **Database dependency**: PostgreSQL required (Vercel Postgres)
-- ⚠️ **Sync orchestration**: Need cron jobs or webhooks
-- ⚠️ **Complexity**: More moving parts
-
-**Mitigation:**
-- Webhooks for near-realtime (optional, Phase 2+)
-- Database is cache layer, not source of truth
-- Fallback to GitHub API if sync fails

package/.next/standalone/packages/ui/dist/standalone/specs/082-web-realtime-sync-architecture/DEPLOYMENT.md

@@ -1,69 +0,0 @@
-### Production Deployment Configuration
-
-#### v0.3.0 (Filesystem Mode)
-
-**Vercel Configuration:**
-```json
-// vercel.json (web app deployment)
-{
-  "buildCommand": "pnpm -F @leanspec/web build",
-  "outputDirectory": "packages/web/.next",
-  "framework": "nextjs",
-  "installCommand": "pnpm install"
-}
-```
-
-**Environment Variables (Vercel Dashboard):**
-```bash
-SPECS_MODE=filesystem
-SPECS_DIR=../../specs
-CACHE_TTL=60000
-REVALIDATION_SECRET=<random-secret>
-```
-
-**Key Points:**
-- Specs directory (`specs/`) must be in git repo
-- No database required for v0.3.0
-- Specs read at runtime from filesystem
-- In-memory cache keeps performance <100ms
-- Vercel serverless functions have filesystem access
-
-#### v0.3.1+ (Dual Mode)
-
-**Vercel Configuration:**
-```json
-// vercel.json (unchanged)
-{
-  "buildCommand": "pnpm -F @leanspec/web build",
-  "outputDirectory": "packages/web/.next",
-  "framework": "nextjs",
-  "installCommand": "pnpm install",
-  "crons": [{
-    "path": "/api/cron/sync",
-    "schedule": "0 * * * *"
-  }]
-}
-```
-
-**Environment Variables (Vercel Dashboard):**
-```bash
-SPECS_MODE=both
-SPECS_DIR=../../specs
-CACHE_TTL=60000
-DATABASE_URL=postgres://...
-GITHUB_TOKEN=ghp_...
-CRON_SECRET=<random-secret>
-REVALIDATION_SECRET=<random-secret>
-```
-
-**Database Setup (Vercel Postgres):**
-1. Create Vercel Postgres database
-2. Run migrations: `pnpm -F @leanspec/web db:migrate`
-3. Seed LeanSpec project: `pnpm -F @leanspec/web db:seed`
-4. Cron job handles external repos
-
-**Key Points:**
-- Both filesystem and database sources active
-- LeanSpec's specs use filesystem (fast, realtime)
-- External repos use database (cached, scheduled sync)
-- Cron job syncs external repos every hour

package/.next/standalone/packages/ui/dist/standalone/specs/082-web-realtime-sync-architecture/FILESYSTEM.md

@@ -1,77 +0,0 @@
-### Mode 1: Filesystem-Based (Local Specs)
-
-**Use Case:** LeanSpec's own specs in monorepo
-
-**Data Flow:**
-```
-specs/ directory → @leanspec/core → In-Memory Cache → Web App
-         ↓
-   Single source of truth
-   Git is the version control
-```
-
-**Architecture:**
-```typescript
-// packages/web/src/lib/specs/sources/filesystem-source.ts
-export class FilesystemSource implements SpecSource {
-  private cache = new Map<string, CachedSpec>();
-  private reader = new SpecReader({ specsDir: '../../specs' });
-  
-  async getAllSpecs(): Promise<Spec[]> {
-    const cacheKey = '__all_specs__';
-    const cached = this.cache.get(cacheKey);
-    
-    if (cached && Date.now() < cached.expiresAt) {
-      return cached.data;
-    }
-    
-    const specs = await this.reader.getAllSpecs();
-    this.cache.set(cacheKey, {
-      data: specs,
-      expiresAt: Date.now() + CACHE_TTL,
-    });
-    
-    return specs;
-  }
-  
-  async getSpec(specPath: string): Promise<Spec | null> {
-    const cached = this.cache.get(specPath);
-    if (cached && Date.now() < cached.expiresAt) {
-      return cached.data;
-    }
-    
-    const spec = await this.reader.readSpec(specPath);
-    this.cache.set(specPath, {
-      data: spec,
-      expiresAt: Date.now() + CACHE_TTL,
-    });
-    
-    return spec;
-  }
-  
-  invalidateCache(specPath?: string) {
-    if (specPath) {
-      this.cache.delete(specPath);
-    } else {
-      this.cache.clear();
-    }
-  }
-}
-```
-
-**Pros:**
-- ✅ **Realtime sync**: Changes appear within cache TTL (60s)
-- ✅ **No database dependency**: Simpler deployment
-- ✅ **Fast**: In-memory cache keeps performance <100ms
-- ✅ **Source of truth**: Filesystem is authoritative
-- ✅ **Works everywhere**: Dev, staging, production (Vercel)
-
-**Cons:**
-- ⚠️ Cache invalidation: TTL-based (not event-driven)
-- ⚠️ Cold starts: Cache empty after deployment
-- ⚠️ No cross-instance cache: Each Vercel function has own cache
-
-**Mitigation:**
-- Use Next.js `revalidate` for additional CDN caching
-- File watcher in dev mode for instant invalidation (optional)
-- Acceptable trade-off for simplicity

package/.next/standalone/packages/ui/dist/standalone/specs/082-web-realtime-sync-architecture/IMPLEMENTATION.md

@@ -1,184 +0,0 @@
-### v0.3 Implementation Plan
-
-#### Phase 1: Filesystem Mode (v0.3.0 - Days 1-4)
-
-**Goal**: Ship filesystem-based architecture for LeanSpec's own specs
-
-**Changes Required:**
-
-1. **Create Unified Service Layer**
-   ```typescript
-   // packages/web/src/lib/specs/service.ts
-   export interface SpecSource { ... }
-   export class SpecsService { ... }
-   ```
-
-2. **Implement Filesystem Source**
-   ```typescript
-   // packages/web/src/lib/specs/sources/filesystem-source.ts
-   export class FilesystemSource implements SpecSource {
-     private cache: Map<string, CachedSpec>;
-     private reader: SpecReader;
-     // ... implementation
-   }
-   ```
-
-3. **Update All Data Fetching**
-   - Replace `db.select()` calls with `specsService.getAllSpecs()`
-   - Update API routes to use service layer
-   - Update page components to use service layer
-
-4. **Add Cache Invalidation API** (optional, nice-to-have)
-   ```typescript
-   // packages/web/src/app/api/revalidate/route.ts
-   export async function POST(request: Request) {
-     const { secret, specPath } = await request.json();
-     if (secret !== process.env.REVALIDATION_SECRET) {
-       return Response.json({ error: 'Unauthorized' }, { status: 401 });
-     }
-     specsService.invalidateCache(specPath);
-     revalidatePath('/specs');
-     return Response.json({ revalidated: true });
-   }
-   ```
-
-5. **Environment Configuration**
-   ```bash
-   # .env.local (development)
-   SPECS_MODE=filesystem
-   SPECS_DIR=../../specs
-   CACHE_TTL=60000
-   
-   # Vercel (production)
-   SPECS_MODE=filesystem
-   SPECS_DIR=../../specs
-   CACHE_TTL=60000
-   ```
-
-6. **Keep Database Schema (for Phase 2)**
-   - Don't delete database code yet
-   - Add feature flag to switch between modes
-   - Document migration path for Phase 2
-
-**Testing:**
-- [ ] All specs load from filesystem
-- [ ] Cache works (verify hit rate)
-- [ ] Performance <100ms
-- [ ] Deployment to Vercel succeeds
-- [ ] Specs update within 60s of file change
-
-#### Phase 2: Database Mode (v0.3.1 - Days 5-8)
-
-**Goal**: Add multi-project support with GitHub integration
-
-**Changes Required:**
-
-1. **Implement Database Source**
-   ```typescript
-   // packages/web/src/lib/specs/sources/database-source.ts
-   export class DatabaseSource implements SpecSource {
-     async getAllSpecs(projectId?: string): Promise<Spec[]> { ... }
-     async getSpec(specPath: string, projectId: string): Promise<Spec | null> { ... }
-   }
-   ```
-
-2. **Implement GitHub Sync Service**
-   ```typescript
-   // packages/web/src/lib/github/sync-service.ts
-   export class GitHubSyncService {
-     async syncProject(owner: string, repo: string, projectId: string) { ... }
-     private async discoverSpecs(owner: string, repo: string) { ... }
-     private computeDiff(repoSpecs: Spec[], dbSpecs: Spec[]) { ... }
-   }
-   ```
-
-3. **Add Project Management UI**
-   - Add project page (admin only)
-   - Add project form (owner, repo, sync frequency)
-   - Add sync status dashboard
-
-4. **Add Scheduled Sync (Vercel Cron)**
-   ```typescript
-   // packages/web/src/app/api/cron/sync/route.ts
-   export async function GET(request: Request) {
-     // Verify cron secret
-     if (request.headers.get('Authorization') !== `Bearer ${process.env.CRON_SECRET}`) {
-       return Response.json({ error: 'Unauthorized' }, { status: 401 });
-     }
-     
-     // Sync all projects
-     const projects = await db.select().from(schema.projects);
-     for (const project of projects) {
-       await syncService.syncProject(project.githubOwner, project.githubRepo, project.id);
-     }
-     
-     return Response.json({ synced: projects.length });
-   }
-   ```
-
-5. **Update Configuration**
-   ```bash
-   # Vercel (production)
-   SPECS_MODE=both  # Enable both modes
-   DATABASE_URL=postgres://...
-   GITHUB_TOKEN=ghp_...
-   CRON_SECRET=...
-   ```
-
-6. **Update Service Layer Routing**
-   - If `projectId` provided → use database source
-   - Otherwise → use filesystem source
-   - Graceful fallback if one fails
-
-**Testing:**
-- [ ] Can add external GitHub repo
-- [ ] Sync discovers all specs
-- [ ] Database stores specs correctly
-- [ ] UI shows both local and external specs
-- [ ] Cron job runs successfully
-
-#### Phase 3: Webhooks & Optimization (v0.4 - Future)
-
-**Goal**: Near-realtime sync with webhooks
-
-**Changes Required:**
-
-1. **GitHub Webhook Endpoint**
-   ```typescript
-   // packages/web/src/app/api/webhooks/github/route.ts
-   export async function POST(request: Request) {
-     const payload = await request.json();
-     const event = request.headers.get('X-GitHub-Event');
-     
-     if (event === 'push') {
-       const { repository, commits } = payload;
-       const changedFiles = commits.flatMap(c => c.modified);
-       
-       if (changedFiles.some(f => f.startsWith('specs/'))) {
-         // Trigger sync for this project
-         await syncService.syncProject(
-           repository.owner.login,
-           repository.name,
-           projectId
-         );
-       }
-     }
-     
-     return Response.json({ ok: true });
-   }
-   ```
-
-2. **Webhook Management UI**
-   - Auto-configure webhook on project add
-   - Show webhook status and delivery logs
-   - Retry failed deliveries
-
-3. **Incremental Sync**
-   - Only sync changed specs (not full resync)
-   - Use webhook payload to identify changed files
-   - Much faster than full sync
-
-**Testing:**
-- [ ] Webhook receives push events
-- [ ] Only changed specs are synced
-- [ ] Latency <10 seconds from push to UI update