@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

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

@@ -0,0 +1,111 @@
+### 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

@@ -0,0 +1,69 @@
+### 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

@@ -0,0 +1,77 @@
+### 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

@@ -0,0 +1,184 @@
+### 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