@leanspec/ui 0.2.7-dev.20251126100750 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/024-pattern-aware-list-grouping/README.md

@@ -0,0 +1,117 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - ux
+  - polish
+  - v0.2.0
+priority: high
+related:
+  - 043-official-launch-02
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-05T05:43:43.501Z'
+completed_at: '2025-11-05T05:43:43.501Z'
+completed: '2025-11-05'
+transitions:
+  - status: complete
+    at: '2025-11-05T05:43:43.501Z'
+---
+
+# Pattern-Aware List Grouping
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: ux, polish, v0.2.0
+
+
+> Make `lean-spec list` adapt to flat vs date-grouped folder patterns
+
+## Overview
+
+Currently `list.ts` has hardcoded date grouping logic that assumes the `{YYYYMMDD}/{NNN}-{name}/` pattern. When users configure flat patterns like `{NNN}-{name}/` or custom patterns, the list command still tries to group by date, which doesn't make sense.
+
+**Issue:** List command doesn't adapt to configured folder pattern.
+
+**Solution:** Detect pattern type and adjust grouping accordingly.
+
+## Design
+
+Make `lean-spec list` respect the configured folder pattern:
+
+1. **For date-grouped patterns** (contains `{YYYYMMDD}/`):
+   - Group by date as it does now
+   - Show date headers
+
+2. **For flat patterns**:
+   - Show flat list, no date grouping
+   - Or group by prefix if present
+
+3. **For custom patterns**:
+   - Adapt based on pattern structure
+   - Default to flat list if unclear
+
+**Implementation:**
+- Read `folderPattern` from config
+- Detect if pattern includes date component
+- Adjust grouping logic in `list.ts` accordingly
+
+## Plan
+
+**Status (2025-11-05):** ✅ Complete - Implemented pattern detection utility and updated list command
+
+- [x] Extract grouping logic from `list.ts`
+- [x] Add pattern detection utility
+- [x] Implement adaptive grouping
+- [x] Add tests for flat/date/custom patterns
+- [x] Update documentation
+
+**Implementation Notes:**
+- Makes list command respect configured folder patterns
+- Fixes hardcoded date grouping assumption
+- Improves UX for users with flat or custom patterns
+- Part of spec 043 launch preparation
+- Estimated: 2-3 hours implementation
+- Works with spec 026 (pattern selection during init)
+
+**Technical Approach:**
+1. Read `folderPattern` from `.lean-spec/config.json`
+2. Detect if pattern contains `{YYYYMMDD}/` for date grouping
+3. Apply appropriate grouping strategy in list output
+4. Maintain backward compatibility
+
+## Implementation (2025-11-05)
+
+**Created new utility module:** `src/utils/pattern-detection.ts`
+- Exports `detectPatternType()` function that returns explicit pattern type
+- Pattern types: `flat`, `date-grouped`, or `custom-grouped`
+- Helper functions: `isDateGroupedPattern()`, `shouldGroupSpecs()`
+- Makes the logic testable and reusable
+
+**Updated list command:** `src/commands/list.ts`
+- Replaced inline pattern detection with utility function
+- Clearer intent: detect pattern type, then decide rendering strategy
+- Maintains full backward compatibility
+
+**Test coverage:**
+- 14 unit tests for pattern-detection utility
+- 4 integration tests for list command:
+  - Flat pattern → flat list
+  - Date-grouped pattern → grouped by date
+  - Custom-grouped pattern → grouped by custom field (e.g., milestone)
+  - Flat with date prefix → flat list (prefix in name, not folder)
+- All 261 tests pass
+
+**Files changed:**
+- `src/utils/pattern-detection.ts` (new)
+- `src/utils/pattern-detection.test.ts` (new)
+- `src/list-integration.test.ts` (new)
+- `src/commands/list.ts` (updated)
+
+## Test
+
+- [x] List command adapts to configured pattern
+- [x] Date grouping works for date-grouped patterns
+- [x] Flat list works for flat patterns
+- [x] No breaking changes to existing behavior
+
+## Notes
+
+Related to spec 20251103/002-folder-structure-improvements - this is a polish issue split out for focused tracking.

package/.next/standalone/packages/ui/dist/standalone/specs/025-template-config-updates/README.md

@@ -0,0 +1,73 @@
+---
+status: planned
+created: 2025-11-03
+tags: [templates, polish]
+priority: low
+---
+
+# Template Config Updates
+
+> Update all template configs to use new format consistently
+
+## Overview
+
+The built-in templates (minimal, standard, enterprise) in `templates/` still use the legacy config format. They work fine but are inconsistent with the new flexible folder structure config format introduced in spec 20251103/001.
+
+**Issue:** Templates use old config format.
+
+**Solution:** Update all template `config.json` files to new format with `folderPattern`.
+
+## Design
+
+Update templates to use new config format:
+
+**Current format (legacy):**
+```json
+{
+  "specDir": "specs"
+}
+```
+
+**New format:**
+```json
+{
+  "specDir": "specs",
+  "folderPattern": "{YYYYMMDD}/{NNN}-{name}/",
+  "prefix": "",
+  "frontmatter": {
+    "required": ["status", "created"],
+    "custom": {}
+  }
+}
+```
+
+**Templates to update:**
+- `templates/minimal/config.json`
+- `templates/standard/config.json`
+- `templates/enterprise/config.json`
+
+Each template should have a sensible default `folderPattern`:
+- **Minimal**: Flat pattern `{NNN}-{name}/` (simplest)
+- **Standard**: Date-grouped `{YYYYMMDD}/{NNN}-{name}/` (prevents conflicts)
+- **Enterprise**: Date-grouped `{YYYYMMDD}/{NNN}-{name}/` (team workflows)
+
+## Plan
+
+- [ ] Update `templates/minimal/config.json`
+- [ ] Update `templates/standard/config.json`
+- [ ] Update `templates/enterprise/config.json`
+- [ ] Test template creation with new configs
+- [ ] Update template README files if needed
+
+## Test
+
+- [ ] All templates use new config format
+- [ ] `lean-spec init` works with each template
+- [ ] Config merging works correctly
+- [ ] Backward compatibility maintained
+
+## Notes
+
+Related to spec 20251103/002-folder-structure-improvements - this is a polish issue split out for focused tracking.
+
+Low priority since legacy format still works, but good for consistency.

package/.next/standalone/packages/ui/dist/standalone/specs/026-init-pattern-selection/README.md

@@ -0,0 +1,109 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - ux
+  - init
+  - v0.2.0
+priority: high
+related:
+  - 043-official-launch-02
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-05T05:44:40.533Z'
+completed_at: '2025-11-05T05:44:40.533Z'
+completed: '2025-11-05'
+transitions:
+  - status: complete
+    at: '2025-11-05T05:44:40.533Z'
+---
+
+# Init Pattern Selection
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: ux, init, v0.2.0
+
+
+> Let users choose folder pattern during `lean-spec init`
+
+## Overview
+
+Currently when running `lean-spec init`, users can only choose a template (minimal/standard/enterprise). The folder pattern is set by the template and users must manually edit `.lean-spec/config.json` to change it.
+
+**Issue:** No way to choose folder pattern during initialization.
+
+**Solution:** Add pattern selection step to init wizard.
+
+## Design
+
+Enhance the `lean-spec init` wizard to offer pattern choices:
+
+**Current flow:**
+1. Choose template (minimal/standard/enterprise)
+2. Confirm → Done
+
+**New flow:**
+1. Choose template (minimal/standard/enterprise)
+2. Choose folder pattern:
+   - `{YYYYMMDD}/{NNN}-{name}/` (Date-grouped - recommended for teams)
+   - `{YYYYMMDD}-{NNN}-{name}/` (Flat with date prefix)
+   - `{NNN}-{name}/` (Simple sequential)
+   - Custom (enter your own)
+3. Confirm → Done
+
+**UI mockup:**
+```bash
+$ lean-spec init
+
+? Select a template:
+  ❯ standard
+    minimal
+    enterprise
+
+? Select folder pattern:
+  ❯ Date-grouped: 20251103/001-my-spec/ (recommended for teams)
+    Flat with date: 20251103-001-my-spec/
+    Simple: 001-my-spec/
+    Custom pattern
+```
+
+**Implementation:**
+- Add pattern selection prompt to `init.ts`
+- Override template's `folderPattern` in generated config
+- Provide sensible descriptions for each pattern
+- Default to date-grouped (current best practice)
+
+## Plan
+
+**Status (2025-11-04):** Ready to implement - part of Phase 2 UX improvements for v0.2.0
+
+- [ ] Add pattern selection to init wizard
+- [ ] Update init command to handle pattern choice
+- [ ] Add pattern override logic
+- [ ] Update documentation
+- [ ] Add tests for pattern selection
+
+**Implementation Notes:**
+- Straightforward UX enhancement to init flow
+- Improves onboarding by eliminating manual config edits
+- Part of spec 043 launch preparation
+- Estimated: 3-4 hours implementation
+- No blocking dependencies
+
+**Testing Priority:**
+- Pattern selection UI is intuitive
+- Selected pattern correctly overrides template default
+- Custom pattern validation works
+- Backward compatibility maintained
+
+## Test
+
+- [ ] Init wizard offers pattern choices
+- [ ] Selected pattern overrides template default
+- [ ] Custom pattern option works
+- [ ] Default pattern is date-grouped
+- [ ] Backward compatibility (skip pattern selection if not needed)
+
+## Notes
+
+Related to spec 20251103/002-folder-structure-improvements - this is a polish issue split out for focused tracking.
+
+This improves onboarding by letting users choose the right pattern upfront instead of requiring manual config edits.

package/.next/standalone/packages/ui/dist/standalone/specs/034-copilot-slash-commands/README.md

@@ -0,0 +1,107 @@
+---
+status: planned
+created: '2025-11-03'
+tags:
+  - vscode
+  - copilot
+  - ai
+  - ux
+  - v0.2.0-optional
+priority: medium
+created_at: '2025-11-03T00:00:00Z'
+updated_at: '2025-11-05T05:03:54.950Z'
+depends_on:
+  - 067-monorepo-core-extraction
+  - 017-vscode-extension
+---
+
+# GitHub Copilot Chat Slash Commands & Prompts
+
+> **Status**: 🗓️ Planned · **Priority**: Medium · **Created**: 2025-11-03 · **Tags**: vscode, copilot, ai, ux, v0.2.0-optional
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Add LeanSpec integration directly into VS Code via GitHub Copilot Chat using slash commands and chat participants. This enables developers to interact with specs naturally through Copilot chat without leaving their coding context.
+
+**Why now?** Copilot Chat is where developers already ask questions and get guidance. Integrating LeanSpec here makes specs discoverable and actionable at the exact moment they're needed—when writing code.
+
+## Design
+
+**Implementation Options:**
+
+**Option A: Chat Participant** (Recommended)
+- Register `@lean-spec` chat participant via VS Code extension
+- Natural language interactions: `@lean-spec what's the status of auth system?`
+- Context-aware: can reference open files, workspace, current work
+
+**Option B: Slash Commands**
+- Register commands like `/lspec-search`, `/lspec-create`, `/lspec-status`
+- More structured but less conversational
+- Fallback if participant API has limitations
+
+**Key Features:**
+- `/lean-spec search <query>` or `@lean-spec search for authentication specs`
+- `/lean-spec status` or `@lean-spec show me what's in progress`
+- `/lean-spec create` or `@lean-spec help me create a spec for this feature`
+- `/lean-spec read <spec>` or `@lean-spec show me the API redesign spec`
+- `/lean-spec update <spec> --status <status>` or `@lean-spec mark auth-system as complete`
+
+**Context Integration:**
+- Automatically detect related specs based on open files
+- Suggest creating specs when Copilot detects new feature work
+- Link spec references in code comments to full specs
+
+**Architecture:**
+- Extend existing VS Code extension (spec 006)
+- Use VS Code Chat Participant API or Slash Command API
+- Reuse LeanSpec CLI logic via TypeScript imports
+- Return formatted markdown with links to specs
+
+## Plan
+
+- [ ] Research VS Code Chat Participant API vs Slash Command API
+- [ ] Choose implementation approach (likely Chat Participant)
+- [ ] Extend VS Code extension package
+- [ ] Implement spec search with Copilot Chat
+- [ ] Add spec status queries and visualization
+- [ ] Enable spec creation through conversational flow
+- [ ] Add spec reading/preview in chat
+- [ ] Implement status updates
+- [ ] Add context-aware spec suggestions
+- [ ] Test with real development workflows
+- [ ] Document in extension README and docs
+
+## Test
+
+- [ ] Chat participant/commands register successfully
+- [ ] Search returns relevant results with correct formatting
+- [ ] Status queries show accurate current state
+- [ ] Create flow guides user through spec creation
+- [ ] Read command displays spec content clearly
+- [ ] Update commands modify specs correctly
+- [ ] Context awareness suggests relevant specs
+- [ ] Works alongside other Copilot features
+- [ ] Handles workspaces without LeanSpec gracefully
+
+## Notes
+
+**GitHub Copilot Chat APIs:**
+- Chat Participants: https://code.visualstudio.com/api/extension-guides/chat
+- Language Model API for context
+
+**Design Principles:**
+- Conversational over command-line syntax
+- Smart defaults based on workspace context
+- Clear feedback and error messages
+- Don't interrupt flow—augment it
+
+**Related:**
+- VS Code extension (spec 006) - base extension to extend
+- MCP server (spec 019) - similar capabilities, different context (Claude Desktop vs VS Code)
+
+**Open Questions:**
+- Should this replace or complement the VS Code extension sidebar?
+- Can we auto-generate spec suggestions from PR descriptions?

package/.next/standalone/packages/ui/dist/standalone/specs/035-live-specs-showcase/ARCHITECTURE.md

@@ -0,0 +1,244 @@
+# Architecture & Technical Design
+
+Technical architecture, technology stack, database schema, and GitHub integration strategy for LeanSpec Web.
+
+## System Architecture
+
+**Three-Tier Architecture:**
+```
+Frontend (Next.js + React)
+    ↓
+API Layer (Next.js API Routes)
+    ↓
+Database (PostgreSQL/SQLite) + GitHub API
+```
+
+**Data Flow:**
+1. Frontend requests data from API
+2. API checks database cache
+3. If cache miss/stale, fetch from GitHub
+4. Parse and store in database
+5. Return to frontend
+
+**Storage Strategy:**
+- **GitHub**: Source of truth (authoritative, versioned)
+- **Database**: Performance layer (fast queries, caching)
+- Best of both: Reliability + Speed + Decoupled from API limits
+
+## Technology Stack
+
+### Frontend
+- **Framework**: Next.js 16+ (App Router, Server Components)
+- **Styling**: Tailwind CSS v3 + shadcn/ui
+- **Markdown**: react-markdown + rehype-highlight + remark-gfm
+- **State**: React Query (TanStack Query)
+- **Theme**: next-themes (dark/light/system)
+
+### Backend
+- **API**: Next.js API Routes (serverless)
+- **Database**: PostgreSQL (prod) / SQLite (dev)
+- **ORM**: Drizzle ORM with type-safe queries
+- **GitHub**: Octokit.js (official client)
+- **Cache**: Redis (optional, for rate limiting)
+
+### Infrastructure
+- **Hosting**: Vercel (recommended) or Railway/Fly.io
+- **Database**: Neon (PostgreSQL) or Turso (SQLite on edge)
+- **Deployment**: Zero-config CI/CD via Vercel
+
+## Database Schema
+
+### Projects
+```sql
+CREATE TABLE projects (
+  id UUID PRIMARY KEY,
+  github_owner TEXT NOT NULL,
+  github_repo TEXT NOT NULL,
+  display_name TEXT,
+  description TEXT,
+  stars INTEGER DEFAULT 0,
+  is_public BOOLEAN DEFAULT true,
+  is_featured BOOLEAN DEFAULT false,
+  last_synced_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(github_owner, github_repo)
+);
+```
+
+### Specs
+```sql
+CREATE TABLE specs (
+  id UUID PRIMARY KEY,
+  project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
+  spec_number INTEGER,
+  spec_name TEXT NOT NULL,
+  title TEXT,
+  status TEXT CHECK(status IN ('planned', 'in-progress', 'complete', 'archived')),
+  priority TEXT CHECK(priority IN ('low', 'medium', 'high', 'critical')),
+  tags TEXT[],
+  assignee TEXT,
+  content_md TEXT NOT NULL,
+  created_at TIMESTAMP,
+  updated_at TIMESTAMP,
+  completed_at TIMESTAMP,
+  file_path TEXT NOT NULL,
+  github_url TEXT,
+  synced_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(project_id, spec_number)
+);
+
+CREATE INDEX idx_specs_project ON specs(project_id);
+CREATE INDEX idx_specs_status ON specs(status);
+```
+
+### Spec Relationships
+```sql
+CREATE TABLE spec_relationships (
+  id UUID PRIMARY KEY,
+  spec_id UUID REFERENCES specs(id) ON DELETE CASCADE,
+  related_spec_id UUID REFERENCES specs(id) ON DELETE CASCADE,
+  relationship_type TEXT CHECK(relationship_type IN ('depends_on', 'related')),
+  UNIQUE(spec_id, related_spec_id, relationship_type)
+);
+```
+
+### Sync Logs
+```sql
+CREATE TABLE sync_logs (
+  id UUID PRIMARY KEY,
+  project_id UUID REFERENCES projects(id) ON DELETE CASCADE,
+  status TEXT CHECK(status IN ('pending', 'running', 'success', 'failed')),
+  specs_added INTEGER DEFAULT 0,
+  specs_updated INTEGER DEFAULT 0,
+  specs_deleted INTEGER DEFAULT 0,
+  error_message TEXT,
+  started_at TIMESTAMP DEFAULT NOW(),
+  completed_at TIMESTAMP
+);
+```
+
+## API Design
+
+### Endpoints
+```
+GET  /api/projects              - List all projects
+GET  /api/projects/:id          - Get project details
+POST /api/projects              - Add new project
+GET  /api/projects/:id/specs    - List project specs
+GET  /api/specs/:id             - Get spec details
+GET  /api/stats                 - Global statistics
+GET  /api/search?q=query        - Full-text search
+POST /api/projects/:id/sync     - Trigger sync
+```
+
+### Response Format
+```json
+{
+  "data": { /* resource */ },
+  "meta": { "total": 42, "page": 1 }
+}
+```
+
+## GitHub Integration
+
+### Sync Mechanisms
+
+**1. Manual Trigger (MVP)**
+User adds GitHub URL → immediate sync
+
+**2. Scheduled Sync (Phase 2)**
+- Featured projects: Every 6 hours
+- Active projects: Daily
+- Inactive projects: Weekly
+
+**3. Webhooks (Phase 4)**
+Real-time updates when repo changes
+
+### Sync Process
+
+**Discovery:**
+1. Fetch repository tree via API (recursive)
+2. Filter files matching `specs/*/README.md` pattern
+3. Exclude `specs/archived/**`
+
+**Parsing:**
+1. Download file content from GitHub
+2. Parse frontmatter (reuse `spec-loader.ts` from CLI)
+3. Extract markdown content
+4. Generate GitHub URL
+
+**Storage:**
+1. Upsert project record
+2. Upsert specs (match by spec_number or file_path)
+3. Handle deletions (soft delete)
+4. Upsert relationships
+5. Log results in sync_logs
+
+### Rate Limiting
+
+GitHub API limits:
+- Authenticated: 5000 req/hour
+- Unauthenticated: 60 req/hour
+
+**Strategies:**
+- Conditional requests (ETags)
+- Response caching (Redis/database)
+- Request batching (tree API)
+- Rate limit monitoring
+- Exponential backoff on errors
+- Prioritization (manual > featured > active)
+
+### Error Handling
+
+- **404 Repo Not Found**: Mark unavailable, keep for history
+- **429 Rate Limit**: Pause until reset, queue job
+- **Parse Errors**: Log error, continue with other specs
+- **Network Timeouts**: Retry with backoff, alert if persistent
+
+## Caching Strategy
+
+**Layer 1: Database (Primary)**
+- Parsed spec content
+- Fast indexed queries
+- TTL: Until next sync (~24h)
+
+**Layer 2: React Query (Client)**
+- In-memory cache
+- Background refetch
+- TTL: 5min stale / 30min cache
+
+**Layer 3: Redis (Optional)**
+- GitHub API responses
+- Rate limit tracking
+- TTL: 1 hour
+
+**Invalidation:**
+- Manual/scheduled sync → invalidate project
+- Stale-while-revalidate pattern
+- Optimistic updates for mutations
+
+## Security
+
+- Sanitize user inputs (prevent SSRF, XSS)
+- Validate GitHub URLs (whitelist domains)
+- Rate limit API endpoints
+- Parameterized queries (prevent SQL injection)
+- Environment variables for secrets
+- CORS configuration
+
+## Performance
+
+- Database indexes on frequent queries
+- Connection pooling
+- Code splitting per route
+- Image optimization (Next.js Image)
+- Lazy loading heavy components
+- Response compression (gzip/brotli)
+
+## Future Enhancements
+
+- Private repo support (OAuth)
+- Real-time webhooks
+- Multi-branch support
+- Cross-repo relationships
+- Version history/diffs