@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/016-github-action/README.md

@@ -0,0 +1,317 @@
+---
+status: planned
+created: '2025-11-02'
+tags: ["feature","ci","automation"]
+priority: low
+depends_on:
+  - 067-monorepo-core-extraction
+---
+
+# github-action
+
+> **Status**: 📅 Planned · **Priority**: Medium · **Created**: 2025-11-02
+
+## Overview
+
+Create a GitHub Action to automate LeanSpec workflows in CI/CD pipelines. Enable teams to validate specs, check status, and enforce spec requirements as part of their development process.
+
+**Use Cases:**
+1. **Spec Validation** - Ensure all specs have required frontmatter
+2. **Status Checks** - Block PRs if planned specs aren't complete
+3. **Documentation Generation** - Auto-generate spec summaries in PR comments
+4. **Metrics Collection** - Track spec completion over time
+5. **Template Compliance** - Validate specs follow template structure
+
+**Why Now:**
+- Core CLI is stable and tested
+- Common use case for teams adopting LeanSpec
+- Differentiator for AI-powered development workflows
+
+## Design
+
+### 1. Action Types
+
+**Option A: Single Flexible Action**
+```yaml
+- uses: codervisor/lspec-action@v1
+  with:
+    command: validate  # or: stats, board, search, check-status
+    filters: '--status=in-progress'
+    fail-on-error: true
+```
+
+**Option B: Multiple Specific Actions**
+```yaml
+- uses: codervisor/lspec-validate@v1
+- uses: codervisor/lspec-stats@v1
+- uses: codervisor/lspec-check-status@v1
+```
+
+**Recommendation**: Option A (single flexible action) for v1, easier to maintain.
+
+### 2. Core Features
+
+**1. Spec Validation**
+```yaml
+- uses: codervisor/lspec-action@v1
+  with:
+    command: validate
+    rules: |
+      - required: [status, created]
+      - no-empty-sections: true
+      - max-age-days: 90
+```
+
+**2. Status Checks**
+```yaml
+- uses: codervisor/lspec-action@v1
+  with:
+    command: check-status
+    fail-if: 'in-progress'
+    message: 'Cannot merge with in-progress specs'
+```
+
+**3. PR Comments**
+```yaml
+- uses: codervisor/lspec-action@v1
+  with:
+    command: stats
+    output: pr-comment
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+**4. Metrics Export**
+```yaml
+- uses: codervisor/lspec-action@v1
+  with:
+    command: export-metrics
+    format: json
+    output-file: specs-metrics.json
+```
+
+### 3. Action Structure
+
+```
+lspec-action/
+├── action.yml          # Action metadata
+├── dist/
+│   └── index.js       # Bundled action code (ncc)
+├── src/
+│   ├── main.ts        # Entry point
+│   ├── commands/      # Command implementations
+│   │   ├── validate.ts
+│   │   ├── check-status.ts
+│   │   ├── stats.ts
+│   │   └── export.ts
+│   └── utils/
+│       ├── github.ts  # GitHub API helpers
+│       └── formatting.ts
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### 4. Example Workflows
+
+**Validate on PR:**
+```yaml
+name: Validate Specs
+on: pull_request
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: codervisor/lspec-action@v1
+        with:
+          command: validate
+          fail-on-error: true
+```
+
+**Block Merge with In-Progress Specs:**
+```yaml
+name: Check Spec Status
+on: pull_request
+
+jobs:
+  check-status:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: codervisor/lspec-action@v1
+        with:
+          command: check-status
+          allow-status: 'planned,complete'
+          fail-if: 'in-progress'
+```
+
+**Post Stats to PR:**
+```yaml
+name: Spec Stats
+on: pull_request
+
+jobs:
+  stats:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: codervisor/lspec-action@v1
+        with:
+          command: stats
+          output: pr-comment
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 5. Action Inputs
+
+```yaml
+inputs:
+  command:
+    description: 'Command to run (validate, check-status, stats, export-metrics)'
+    required: true
+  
+  fail-on-error:
+    description: 'Fail action if validation fails'
+    default: 'true'
+  
+  filters:
+    description: 'CLI filter flags (--status, --tag, --priority)'
+    required: false
+  
+  output:
+    description: 'Output type (console, pr-comment, file, json)'
+    default: 'console'
+  
+  output-file:
+    description: 'Output file path (for file/json output)'
+    required: false
+  
+  github-token:
+    description: 'GitHub token for PR comments'
+    required: false
+  
+  working-directory:
+    description: 'Directory containing .lean-spec/ (defaults to repo root)'
+    default: '.'
+```
+
+### 6. Action Outputs
+
+```yaml
+outputs:
+  result:
+    description: 'Command result (success/failure)'
+  
+  stats:
+    description: 'Spec statistics (JSON)'
+  
+  validation-errors:
+    description: 'List of validation errors (JSON array)'
+  
+  comment-url:
+    description: 'URL of posted PR comment'
+```
+
+## Plan
+
+### Phase 1: Setup & Core Infrastructure
+- [ ] Create `lspec-action` repository
+- [ ] Set up TypeScript build with @vercel/ncc for bundling
+- [ ] Create action.yml with inputs/outputs
+- [ ] Set up GitHub Actions workflow for testing action itself
+- [ ] Install lean-spec as dependency
+
+### Phase 2: Core Commands
+- [ ] Implement `validate` command (check frontmatter, structure)
+- [ ] Implement `check-status` command (fail on specific statuses)
+- [ ] Implement `stats` command (gather metrics)
+- [ ] Implement `export-metrics` command (JSON output)
+- [ ] Add formatting utilities for console/PR output
+
+### Phase 3: GitHub Integration
+- [ ] Add PR comment posting (using @actions/github)
+- [ ] Add commit status updates
+- [ ] Add annotations for validation errors
+- [ ] Test with sample repository
+
+### Phase 4: Documentation & Examples
+- [ ] Write comprehensive README
+- [ ] Add example workflows for common use cases
+- [ ] Create action marketplace listing
+- [ ] Document all inputs/outputs
+
+### Phase 5: Publishing
+- [ ] Tag v1.0.0 release
+- [ ] Publish to GitHub Marketplace
+- [ ] Link from lean-spec README
+- [ ] Create demo repository showing usage
+
+## Test
+
+### Action Tests
+- [ ] Action builds and bundles correctly
+- [ ] All commands execute without errors
+- [ ] Exit codes are correct (0 for success, 1 for failure)
+- [ ] Inputs are parsed correctly
+- [ ] Outputs are set correctly
+
+### Command Tests
+- [ ] `validate` detects missing frontmatter
+- [ ] `validate` passes for valid specs
+- [ ] `check-status` fails on disallowed statuses
+- [ ] `stats` generates correct metrics
+- [ ] `export-metrics` produces valid JSON
+
+### GitHub Integration Tests
+- [ ] PR comments are posted correctly
+- [ ] Comments include formatted tables
+- [ ] Annotations appear on correct files/lines
+- [ ] Works with GITHUB_TOKEN
+
+### End-to-End Tests
+- [ ] Run action in test repository
+- [ ] Validate specs workflow works
+- [ ] PR comment workflow works
+- [ ] Metrics export workflow works
+
+## Notes
+
+**Dependencies:**
+- lean-spec CLI (core dependency)
+- @actions/core (GitHub Actions SDK)
+- @actions/github (GitHub API)
+- @vercel/ncc (bundle for distribution)
+
+**Marketplace Listing:**
+- Name: "LeanSpec Action"
+- Description: "Validate and manage LeanSpec documents in CI/CD"
+- Categories: Code Quality, Continuous Integration
+- Icon: 📋 or 📝
+- Color: Blue
+
+**Future Enhancements:**
+- Spec coverage reports (% of code with specs)
+- Spec drift detection (specs out of sync with code)
+- Auto-create specs from PR descriptions
+- Integration with Linear, Jira for issue linking
+- Spec dependency graph visualization in PR
+
+**Alternative: Reusable Workflow**
+Instead of GitHub Action, could provide reusable workflow:
+```yaml
+# .github/workflows/lspec-validate.yml
+on:
+  workflow_call:
+    inputs:
+      command:
+        required: true
+        type: string
+```
+
+But GitHub Action is more flexible and easier for users to adopt.
+
+**References:**
+- GitHub Actions docs: https://docs.github.com/en/actions
+- Action toolkit: https://github.com/actions/toolkit
+- Marketplace: https://github.com/marketplace?type=actions

package/.next/standalone/packages/ui/dist/standalone/specs/017-vscode-extension/README.md

@@ -0,0 +1,261 @@
+---
+status: planned
+created: '2025-11-02'
+tags: ["feature","ide","vscode"]
+priority: low
+depends_on:
+  - 067-monorepo-core-extraction
+---
+
+# vscode-extension
+
+> **Status**: 📅 Planned · **Priority**: Medium · **Created**: 2025-11-02
+
+## Overview
+
+Create a VS Code extension that integrates LeanSpec directly into the editor, providing inline spec management, navigation, and AI agent integration.
+
+**Developer Pain Points:**
+- Switching between editor and terminal for spec management
+- Finding specs across folder structure
+- No syntax highlighting for spec frontmatter
+- AI agents can't easily reference specs during coding
+- Manual updating of spec status
+
+**What Success Looks Like:**
+- Create/edit specs without leaving VS Code
+- Tree view showing all specs with status indicators
+- Quick actions to update spec metadata
+- Frontmatter validation and autocomplete
+- Integration with GitHub Copilot context
+
+## Design
+
+### 1. Extension Features
+
+**Spec Explorer (Tree View)**
+```
+LEANSPEC SPECS
+├── 📅 20251102/
+│   ├── ✅ 001-custom-spec-templates/
+│   ├── 📅 002-complete-custom-frontmatter/
+│   └── 🔨 003-npm-publishing/
+├── ✅ 20251101/
+│   └── ✅ 001-existing-project-integration/
+└── 📅 Planned (3)
+    🔨 In Progress (1)
+    ✅ Complete (9)
+```
+
+**Quick Actions:**
+- Right-click spec → Update Status
+- Right-click spec → Archive
+- Right-click spec → Open in Editor
+- Right-click spec → Copy Path
+
+**Commands (Ctrl+Shift+P):**
+- `LeanSpec: Create New Spec`
+- `LeanSpec: Update Spec Status`
+- `LeanSpec: Show Stats`
+- `LeanSpec: Show Board`
+- `LeanSpec: Search Specs`
+- `LeanSpec: Validate All Specs`
+
+**Status Bar:**
+```
+📋 LeanSpec: 3 planned, 1 in progress, 9 complete
+```
+
+### 2. Editor Features
+
+**Frontmatter Validation:**
+- Syntax highlighting for YAML frontmatter
+- Red squiggles for invalid fields
+- Autocomplete for status, priority, tags
+- Hover tooltips showing field descriptions
+
+**Snippets:**
+- `lspec-spec` → Full spec template
+- `lspec-front` → Frontmatter block
+- `lspec-plan` → Plan section with checkboxes
+
+**CodeLens:**
+```markdown
+---
+status: planned
+---
+👆 Update Status | 🔄 Sync Metadata
+
+# My Feature Spec
+```
+
+### 3. AI Agent Integration
+
+**Copilot Context Provider:**
+```typescript
+// Enable Copilot to reference specs
+vscode.lm.registerContextProvider('leanspec', {
+  provideContext(query) {
+    // Search specs matching query
+    // Return relevant spec content
+  }
+});
+```
+
+**Usage:**
+```
+@leanspec How should I implement the API endpoints?
+// Copilot gets context from relevant specs
+```
+
+### 4. Extension Architecture
+
+```typescript
+// Extension structure
+src/
+├── extension.ts              # Activation
+├── commands/
+│   ├── createSpec.ts
+│   ├── updateSpec.ts
+│   └── searchSpecs.ts
+├── providers/
+│   ├── SpecTreeProvider.ts   # Tree view
+│   ├── FrontmatterValidator.ts
+│   ├── CompletionProvider.ts # Autocomplete
+│   └── CopilotProvider.ts    # AI context
+├── views/
+│   └── statsWebview.ts       # Stats dashboard
+└── utils/
+    └── lspecClient.ts        # Wrap CLI commands
+```
+
+### 5. Configuration
+
+```json
+{
+  "leanspec.specsDirectory": "specs",
+  "leanspec.autoRefresh": true,
+  "leanspec.showStatusBar": true,
+  "leanspec.validateOnSave": true,
+  "leanspec.copilotIntegration": true
+}
+```
+
+## Plan
+
+### Phase 1: Core Extension Setup
+- [ ] Initialize VS Code extension project
+- [ ] Set up TypeScript, webpack bundling
+- [ ] Create extension manifest (package.json)
+- [ ] Set up activation events
+- [ ] Install lean-spec as dependency
+
+### Phase 2: Spec Explorer Tree View
+- [ ] Implement SpecTreeProvider
+- [ ] Load specs from workspace
+- [ ] Display folder structure with icons
+- [ ] Show status indicators (icons)
+- [ ] Add click to open spec
+- [ ] Add refresh button
+
+### Phase 3: Commands & Quick Actions
+- [ ] Implement `Create New Spec` command
+- [ ] Implement `Update Status` command
+- [ ] Implement `Show Stats` command
+- [ ] Implement `Search Specs` command
+- [ ] Add context menu items to tree view
+- [ ] Add status bar item with spec counts
+
+### Phase 4: Editor Features
+- [ ] Add frontmatter syntax highlighting
+- [ ] Implement validation diagnostics
+- [ ] Add autocomplete for frontmatter fields
+- [ ] Create spec snippets
+- [ ] Add CodeLens for quick actions
+- [ ] Add hover tooltips
+
+### Phase 5: AI Integration
+- [ ] Research Copilot Context Provider API
+- [ ] Implement context provider
+- [ ] Test with GitHub Copilot
+- [ ] Add configuration toggle
+
+### Phase 6: Polish & Publishing
+- [ ] Create extension icon
+- [ ] Write comprehensive README
+- [ ] Add screenshots/GIFs
+- [ ] Test on Windows, macOS, Linux
+- [ ] Publish to VS Code Marketplace
+- [ ] Link from lean-spec README
+
+## Test
+
+### Tree View Tests
+- [ ] Tree view loads specs correctly
+- [ ] Icons match spec status
+- [ ] Click opens spec file
+- [ ] Refresh updates tree
+- [ ] Works with empty specs directory
+
+### Command Tests
+- [ ] Create spec command works
+- [ ] Update status command works
+- [ ] Commands show in palette
+- [ ] Status bar updates on changes
+
+### Editor Tests
+- [ ] Frontmatter validation detects errors
+- [ ] Autocomplete suggests valid values
+- [ ] Snippets expand correctly
+- [ ] CodeLens actions work
+
+### Integration Tests
+- [ ] Extension activates in workspace with .lean-spec/
+- [ ] Works with all templates
+- [ ] Handles spec creation/deletion
+- [ ] File watcher updates on external changes
+
+### Copilot Tests
+- [ ] Context provider registers
+- [ ] Copilot can query specs
+- [ ] Returns relevant spec content
+
+## Notes
+
+**VS Code Extension API:**
+- TreeDataProvider for tree view
+- DiagnosticCollection for validation
+- CompletionItemProvider for autocomplete
+- CodeLensProvider for inline actions
+- StatusBarItem for status display
+- FileSystemWatcher for auto-refresh
+
+**Marketplace Listing:**
+- Name: "LeanSpec"
+- Description: "Lightweight spec management for AI-powered development"
+- Categories: Programming Languages, Other
+- Icon: 📋 or spec document icon
+- Keywords: spec, sdd, documentation, ai, agent
+
+**Bundle Size:**
+- Keep extension lightweight (< 5MB)
+- Use webpack to bundle dependencies
+- Consider using CLI as subprocess vs. importing
+
+**Future Enhancements:**
+- Spec dependency graph visualization
+- Inline spec preview in hover
+- Spec templates gallery
+- Integration with other AI tools (Cursor, etc.)
+- Spec metrics dashboard (webview)
+- Git blame integration (show who wrote spec)
+
+**Alternative Approach:**
+- Could build as Language Server Protocol (LSP)
+- Would enable support for other editors (Neovim, etc.)
+- More complex but more portable
+
+**References:**
+- VS Code Extension API: https://code.visualstudio.com/api
+- Tree View Guide: https://code.visualstudio.com/api/extension-guides/tree-view
+- Copilot Context: https://code.visualstudio.com/api/extension-guides/language-model