@leanspec/ui 0.2.7 → 0.2.9-dev.20251205030455

package/.next/standalone/packages/ui/dist/standalone/specs/100-release-process-typecheck-failure/README.md

@@ -1,266 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags:
-  - process
-  - quality
-  - ci-cd
-  - post-mortem
-priority: high
-created_at: '2025-11-17T21:12:06.305Z'
-completed_at: '2025-11-17T21:12:00.000Z'
-updated_at: '2025-11-17T13:13:28.300Z'
-completed: '2025-11-17'
----
-
-# Post-Mortem: v0.2.3 TypeScript Check Failure
-
-## Overview
-
-On November 17, 2025, we attempted to release v0.2.3 only to discover **30+ TypeScript compilation errors** that should have been caught before the release process began. This spec documents what went wrong, why it happened, and how to prevent it in the future.
-
-**Impact**: Blocked release, required emergency fix session, wasted development time, damaged trust in release process.
-
-## What Went Wrong
-
-### The Problem
-Version 0.2.3 was tagged and released without running `pnpm typecheck`, leading to a published package that:
-- Failed TypeScript compilation (`tsc --noEmit` showed 30+ errors)
-- Had broken MCP SDK integration (signature mismatches)
-- Had type mismatches across packages (core vs CLI)
-- Would break for users with strict TypeScript checking
-
-### Root Causes
-
-1. **No Pre-Release Type Check**
-   - Release process did NOT include `pnpm typecheck` as a required step
-   - Only ran `pnpm build` which uses `tsup` with less strict checking
-   - `tsup` successfully bundles code even with type errors when `noCheck: true` or similar flags
-
-2. **No CI/CD Type Checking**
-   - GitHub Actions publish workflow (`.github/workflows/publish.yml`) does NOT run `pnpm typecheck`
-   - Only runs `pnpm build` before publishing
-   - No gate preventing broken releases
-
-3. **Monorepo Complexity**
-   - Errors were spread across CLI and Core packages
-   - Cross-package type dependencies not validated
-   - Core package exported types used in CLI weren't properly exposed
-
-4. **MCP SDK Version Upgrade**
-   - SDK v1.21.0 changed handler signatures (added `extra` parameter)
-   - No automated check for SDK compatibility
-   - Breaking changes went unnoticed until compilation
-
-### Timeline of Errors
-
-The errors fell into several categories:
-
-**Type Export Issues (1 error)**
-- `isolate.ts` couldn't import `Frontmatter` type from core (not exported)
-
-**Interface Mismatches (2 errors)**  
-- `SpecInfo.date` was required in CLI but optional in core
-- `deps.ts` failed due to this mismatch
-
-**Type Casting Issues (2 errors)**
-- `search.ts` had `unknown` types for `title`/`description` from frontmatter
-- Needed explicit type guards
-
-**MCP SDK Signature Changes (25+ errors)**
-- All tool handlers missing required `extra` parameter
-- Resource callbacks missing `variables` and `extra` parameters  
-- Console capturing code broken by incorrect multi_replace edits
-- Type literal issues (`type: 'text'` vs `type: string`)
-
-## Why Didn't We Catch This?
-
-### Human Factors
-- **Assumption**: "If build passes, types are good"
-- **Habit**: Not running `pnpm typecheck` before releases
-- **Time pressure**: Rush to publish without full validation
-- **Trust**: Assumed CI would catch issues (but it didn't)
-
-### Process Gaps
-- No checklist for releases
-- No automated pre-release validation
-- No CI gate for type checking
-- No cross-package type validation
-
-### Tool Configuration
-- `tsup.config.ts` may have been too lenient
-- Build tool doesn't enforce strict type checking
-- Missing `turbo run typecheck` in release workflow
-
-## What Should Have Happened
-
-### Ideal Pre-Release Checklist
-```bash
-# 1. Type check all packages
-pnpm typecheck
-
-# 2. Run all tests
-pnpm test:run
-
-# 3. Build all packages
-pnpm build
-
-# 4. Validate docs build
-cd docs-site && npm run build
-
-# 5. Run local spec validation
-node bin/lean-spec.js validate
-
-# 6. Update CHANGELOG.md
-
-# 7. Commit and tag
-git add -A
-git commit -m "chore: bump version to X.Y.Z"
-git tag vX.Y.Z
-git push origin main --tags
-
-# 8. Create GitHub release (triggers CI)
-gh release create vX.Y.Z
-```
-
-### Ideal CI/CD Workflow
-```yaml
-# .github/workflows/publish.yml
-jobs:
-  publish:
-    steps:
-      - name: Install dependencies
-        run: pnpm install
-      
-      - name: Type check ⚠️ MISSING
-        run: pnpm typecheck
-      
-      - name: Run tests ⚠️ MISSING  
-        run: pnpm test:run
-      
-      - name: Build
-        run: pnpm build
-      
-      - name: Publish to npm
-        if: all tests pass
-        run: pnpm publish
-```
-
-## Lessons Learned
-
-### What Worked
-- ✅ Fast identification and triage of errors
-- ✅ Systematic fix approach (categorize, prioritize, fix)
-- ✅ Good git practices (committed fix, tagged properly)
-- ✅ Clear documentation of what was fixed
-
-### What Didn't Work
-- ❌ No automated type checking in CI
-- ❌ No pre-release validation checklist
-- ❌ Build tools don't enforce type safety
-- ❌ Assumed "build passes" = "types are correct"
-- ❌ No cross-package type validation
-
-## Action Items
-
-### Immediate (Before Next Release)
-
-**1. Add Type Checking to CI Workflow**
-```yaml
-# .github/workflows/publish.yml
-- name: Type check all packages
-  run: pnpm typecheck
-
-- name: Run tests
-  run: pnpm test:run
-```
-
-**2. Create Release Checklist**
-Add to `CONTRIBUTING.md` or create `RELEASING.md`:
-- [ ] Run `pnpm typecheck`
-- [ ] Run `pnpm test:run`  
-- [ ] Run `pnpm build`
-- [ ] Validate with `node bin/lean-spec.js validate`
-- [ ] Update CHANGELOG.md
-- [ ] Commit, tag, push
-- [ ] Create GitHub release
-
-**3. Add Pre-Push Hook** (Optional)
-```bash
-# .husky/pre-push
-pnpm typecheck || (echo "Type check failed!" && exit 1)
-```
-
-### Short-term (Next Sprint)
-
-**4. Improve Package Scripts**
-Add a `pre-release` script:
-```json
-{
-  "scripts": {
-    "pre-release": "pnpm typecheck && pnpm test:run && pnpm build && pnpm validate"
-  }
-}
-```
-
-**5. Enhanced CI Pipeline**
-- Add separate typecheck job that runs on all PRs
-- Require passing typecheck before merge
-- Add matrix testing across Node versions
-
-**6. Documentation**
-- Document the release process in `AGENTS.md`
-- Add "Why typecheck matters" section
-- Include common type error patterns
-
-### Long-term (Future)
-
-**7. Automated Release Process**
-Consider tools like:
-- `semantic-release` for automated versioning
-- `changesets` for monorepo releases
-- `release-please` for GitHub-native releases
-
-**8. Type Safety Improvements**
-- Enable stricter TypeScript compiler options
-- Add `strict: true` to all `tsconfig.json`
-- Use `exactOptionalPropertyTypes`
-- Enable `noUncheckedIndexedAccess`
-
-**9. Monorepo Type Validation**
-- Add Turbo task for cross-package type checking
-- Validate type exports/imports between packages
-- Add package boundary lint rules
-
-## Metrics to Track
-
-Going forward, track:
-- **Time to catch type errors**: Pre-push vs CI vs post-release
-- **Type error frequency**: Trend over time
-- **Release confidence**: Did we catch issues before release?
-- **Developer friction**: Does strict checking slow development?
-
-## Success Criteria
-
-This post-mortem is successful when:
-- ✅ CI blocks releases with type errors
-- ✅ `pnpm typecheck` is part of standard workflow
-- ✅ Developers run typecheck before PRs
-- ✅ Zero type-related release failures for 3 months
-- ✅ Release checklist is documented and followed
-
-## References
-
-- [TypeScript Handbook - Type Checking](https://www.typescriptlang.org/docs/handbook/2/basic-types.html)
-- [Turbo: Type Checking in Monorepos](https://turbo.build/repo/docs/handbook/linting)
-- [GitHub Actions: Required Status Checks](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging)
-
-## Conclusion
-
-This was a **preventable failure** caused by process gaps, not technical limitations. The fix is straightforward:
-
-1. **Always run `pnpm typecheck` before releasing**
-2. **Add typecheck to CI/CD pipeline**
-3. **Document and follow release checklist**
-
-The tools exist, we just need to use them consistently. This post-mortem serves as both documentation and action plan to ensure this never happens again.

package/.next/standalone/packages/ui/dist/standalone/specs/101-sidebar-scroll-position-drift/README.md

@@ -1,100 +0,0 @@
----
-status: complete
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T14:22:14.161Z'
-updated_at: '2025-11-17T14:54:01.282Z'
-completed_at: '2025-11-17T14:54:01.282Z'
-completed: '2025-11-17'
-transitions:
-  - status: complete
-    at: '2025-11-17T14:54:01.282Z'
----
-
-# Fix Sidebar Scroll Position Drift
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-The specs navigation sidebar in the web package experiences scroll position drift when navigating between specs. The list jumps or loses its scroll position during navigation, causing poor UX especially with large spec lists.
-
-**Root Cause**: Multiple performance optimization attempts revealed the issue stems from:
-1. Store design causing unnecessary re-renders - `updateSidebarScrollTop` spreads state, triggering all subscribers even when only `scrollTop` changes
-2. Component subscribing to entire store state rather than specific slices
-3. `cachedSpecs` creating new references on every render before memoization
-4. Complex interaction between react-window's internal scroll management and external state updates
-
-**Why Now**: This affects daily workflow navigation and has resisted multiple quick fixes. Needs proper investigation and testing.
-
-## Design
-
-### Investigation Completed
-- Verified React 19 `useSyncExternalStore` requirements: unstable server snapshot references were causing infinite loops
-- Determined global store broadcasts on every scroll write were the primary source of drift
-- Confirmed `react-window` retains internal scroll state reliably when left to manage DOM scroll positions
-- Observed that auto-anchoring logic was running too late, producing flicker during hydration
-
-### Final Approach
-1. **Selector-driven store reads** – keep existing selector hooks but ensure server snapshots are stable constants
-2. **Isolate scroll persistence** – keep global persistence value, but stop emitting change events when the value updates
-3. **Component-local scroll management** – mirror scrollTop in refs, throttle writes with `requestAnimationFrame`, and restore via `useIsomorphicLayoutEffect`
-4. **Controlled auto-anchoring** – only scroll the virtual list on the first render (when no stored offset exists) and guard future attempts with refs
-
-### Current Optimizations Applied
-- Wrapped List in React.memo
-- Memoized RowComponent with useCallback
-- Memoized cachedSpecs
-- Added selector-based store hooks (useSpecsSidebarSpecs, useSpecsSidebarActiveSpec)
-- Separate listener sets per state slice
-
-## Plan
-
-- [ ] Add detailed logging to track re-render causes (component, store, props changes)
-- [x] Profile with React DevTools to identify actual render triggers
-- [x] Test removing all scroll management code to establish baseline behavior (browser-managed scroll proved stable)
-- [x] Implement proper selector pattern with verified render prevention
-- [x] Test with large spec lists (100+ items) to verify performance
-- [x] Document final solution and architecture decision
-
-### Implementation Summary
-
-- Updated `useSyncExternalStore` server snapshot for specs to return a memoized empty array, eliminating React 19 infinite-loop warnings.
-- Prevented `updateSidebarScrollTop` from emitting global store changes so unrelated subscribers no longer re-render on scroll.
-- Added scroll persistence effect in `SpecsNavSidebar` that restores the cached offset via `useIsomorphicLayoutEffect` and throttled listeners.
-- Introduced guarded auto-anchoring that only runs on the initial render when no stored offset exists, ensuring refreshed pages center the active spec without affecting later interactions.
-- Added retry logic for auto-anchoring to wait until the virtualized list ref is ready, removing flicker.
-
-### Validation
-
-- Navigating between specs preserves scroll position without jumps.
-- Filtering, collapsing, and mobile toggles retain the current offset.
-- Rapid spec changes and scrolling back to the top no longer trigger downward drift.
-- Browser refresh loads with the active spec centered when no previous scroll position was saved.
-- Large spec lists (>100 entries) scroll smoothly with no lag or unexpected reflows.
-
-## Test
-
-- [x] Navigate between specs - scroll position should remain stable
-- [x] Filter specs while scrolled - list should not jump
-- [x] Open/close mobile sidebar - no scroll position loss
-- [x] Rapid navigation (click multiple specs quickly) - no drift or jumping
-- [x] Large spec lists (100+) - smooth scrolling without lag
-- [x] Browser refresh - reasonable scroll restoration behavior
-
-## Notes
-
-**Attempted Fixes (Session 1)**:
-- Removed scroll restoration on navigation
-- Removed scroll tracking callbacks
-- Wrapped List in memo
-- Memoized cachedSpecs to prevent reference changes
-- Implemented selector-based store subscriptions
-
-**Key Learning**: The issue persisted despite multiple optimizations, suggesting the problem is architectural rather than a simple memoization issue. The store design fundamentally causes re-renders when any state changes, even with selector hooks.
-
-**Next Steps**: Monitor for regressions when introducing future sidebar features (e.g., grouping, pinning). Add logging only if new drift reports appear.

package/.next/standalone/packages/ui/dist/standalone/specs/102-mcp-wrapper-package/README.md

@@ -1,172 +0,0 @@
----
-status: in-progress
-created: '2025-11-18'
-tags:
-  - mcp
-  - integration
-  - npm-package
-  - developer-experience
-priority: high
-created_at: '2025-11-18T03:06:33.496Z'
-updated_at: '2025-11-18T03:24:10.457Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-18T03:24:10.457Z'
----
-
-# @leanspec/mcp - MCP Server Integration Wrapper
-
-> **Status**: ⏳ In progress · **Priority**: High · **Created**: 2025-11-18 · **Tags**: mcp, integration, npm-package, developer-experience
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-Create a lightweight CLI wrapper that makes `lean-spec mcp` more discoverable and easier to use. The existing `lean-spec` CLI has many features, making MCP setup less obvious. This dedicated package provides a simple entry point for users to quickly onboard MCP with their preferred IDE/tools.
-
-**Problem**: `lean-spec` is a full-featured CLI tool. When users configure MCP servers in their IDE, they need to know to use `lean-spec mcp`, which isn't obvious. Also, the package name `lean-spec` doesn't clearly indicate MCP functionality.
-
-**Solution**: Ship `@leanspec/mcp` as a thin wrapper. IDEs can call `npx @leanspec/mcp` directly, which just delegates to `lean-spec mcp`. This makes the MCP server more discoverable and the package name more intuitive.
-
-## Design
-
-### Package Structure
-```
-@leanspec/mcp/
-├── bin/
-│   └── leanspec-mcp.js   # Thin wrapper CLI
-├── package.json          # Depends on lean-spec
-└── README.md             # Quick start guide
-```
-
-### How It Works
-
-The package is a **simple passthrough**:
-1. User adds MCP server to their IDE config: `npx @leanspec/mcp`
-2. When IDE needs the server, npx auto-installs `@leanspec/mcp` and its `lean-spec` dependency
-3. Script delegates to: `lean-spec mcp`
-4. MCP server starts and IDE can communicate with it
-
-No interaction needed - the IDE handles everything.
-
-### Usage in IDE Configs
-
-**Claude Desktop** (`claude_desktop_config.json`):
-```json
-{
-  "mcpServers": {
-    "leanspec": {
-      "command": "npx",
-      "args": ["-y", "@leanspec/mcp"]
-    }
-  }
-}
-```
-
-**Cline** (VS Code `settings.json`):
-```json
-{
-  "cline.mcpServers": {
-    "leanspec": {
-      "command": "npx",
-      "args": ["-y", "@leanspec/mcp"]
-    }
-  }
-}
-```
-
-**Zed** (`settings.json`):
-```json
-{
-  "context_servers": {
-    "leanspec": {
-      "command": "npx",
-      "args": ["-y", "@leanspec/mcp"]
-    }
-  }
-}
-```
-
-### Key Design Decisions
-
-**Pure passthrough**: Just delegates to `lean-spec mcp`, no logic needed.
-
-**Better naming**: `@leanspec/mcp` is more intuitive than `lean-spec mcp` for MCP use cases.
-
-**Auto-install**: npx automatically installs both `@leanspec/mcp` and its `lean-spec` dependency when needed.
-
-**No interaction**: MCP servers are called by IDEs, not by users directly. No wizard needed.
-
-**Simpler docs**: Users just copy-paste the config snippet, IDE handles the rest.
-
-## Plan
-
-- [ ] Create minimal package structure in `packages/mcp/`
-- [ ] Write simple passthrough script (delegates to `lean-spec mcp`)
-- [ ] Add `lean-spec` as dependency in package.json
-- [ ] Create README with config examples for different IDEs
-- [ ] Test with Claude Desktop, Cline, Zed
-- [ ] Publish to npm as `@leanspec/mcp`
-- [ ] Update main docs with `@leanspec/mcp` examples
-
-## Test
-
-- [ ] Config with `npx @leanspec/mcp` works in Claude Desktop
-- [ ] Config with `npx @leanspec/mcp` works in Cline
-- [ ] Config with `npx @leanspec/mcp` works in Zed
-- [ ] Server starts correctly when IDE calls it
-- [ ] npx auto-installs dependencies on first run
-- [ ] Works on macOS, Windows, Linux
-- [ ] Package size is minimal (<5KB)
-
-## Notes
-
-### Why This Approach
-
-**Maximum simplicity**: Just a ~10 line passthrough script.
-
-**No complexity**: No IDE detection, no config merging, no interaction. Users just copy config.
-
-**Better naming**: Package name clearly indicates MCP functionality.
-
-**Zero maintenance**: All logic lives in `lean-spec mcp`, wrapper just delegates.
-
-**Discoverability**: Searching for "leanspec mcp" finds the right package immediately.
-
-### Implementation
-
-```javascript
-#!/usr/bin/env node
-const { spawn } = require('child_process');
-
-// Simply delegate to lean-spec mcp
-const child = spawn('lean-spec', ['mcp'], { stdio: 'inherit' });
-child.on('exit', (code) => process.exit(code));
-```
-
-### Documentation Example
-
-Users see this in the docs:
-
-> **Quick Setup**
-> 
-> Add to your Claude Desktop config:
-> ```json
-> {
->   "mcpServers": {
->     "leanspec": {
->       "command": "npx",
->       "args": ["-y", "@leanspec/mcp"]
->     }
->   }
-> }
-> ```
-> 
-> Restart Claude Desktop. Done!
-
-### Dependencies
-- `lean-spec` - The actual MCP server (peer dependency)
-
-### Related
-- Existing `lean-spec mcp` command (what this delegates to)

package/.next/standalone/packages/ui/dist/standalone/specs/archived/001-typescript-cli-migration/README.md

@@ -1,37 +0,0 @@
----
-status: complete
-created: 2025-10-31
-tags: [typescript, cli, migration]
-priority: high
-completed: 2025-10-31
----
-
-# typescript-cli-migration
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-10-31 · **Tags**: typescript, cli, migration
-
-## Goal
-
-Migrate lean-spec CLI from bash script to TypeScript/pnpm while keeping the methodology language-agnostic. Better tooling for maintainability without sacrificing lean principles.
-
-## Key Points
-
-- CLI commands: `create`, `archive`, `list` with same UX
-- Date-based structure: `specs/YYYYMMDD/NNN-name.md`
-- Modern TS tooling: tsup, Prettier
-- Minimal dependencies: only `chalk` for colors
-- Fast build with pnpm
-
-## Non-Goals
-
-What we're explicitly NOT doing:
-- Adding complex CLI features or frameworks
-- Over-engineering with unnecessary dependencies
-- Making methodology TS-specific (stays language-agnostic)
-- Breaking changes to command interface
-
-## Notes
-
-The bash version worked but lacked type safety and was harder to extend. TS provides better DX while keeping the tool lean (~200 lines of code).
-
-LeanSpec methodology remains framework/language-agnostic - this is just the CLI implementation.

package/.next/standalone/packages/ui/dist/standalone/specs/archived/002-template-system-redesign/README.md

@@ -1,60 +0,0 @@
----
-status: complete
-created: 2025-10-31
-tags: [templates, templates-system]
-priority: high
-completed: 2025-10-31
----
-
-# template-system-redesign
-
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-10-31 · **Tags**: templates, templates-system
-
-
-**Created**: 2025-10-31  
-**Status**: Complete
-
-## Goal
-
-Expand LeanSpec template system to support multiple working styles, team sizes, and domains. Current single template is too limiting - teams need options without sacrificing lean principles.
-
-## Key Points
-
-- Template bundles: Each template is a directory containing spec.md + supporting files (AGENTS.md, checklists, etc.)
-- Core templates: default (new structured), minimal (current simple), team, enterprise, api
-- CLI support: `--template` flag for selection, `lean-spec templates` to list available
-- New default template: Hybrid structure with Overview, Objectives, Design, Implementation Plan, Success Criteria, Non-Goals, Notes, References
-
-## Non-Goals
-
-What we're explicitly NOT doing:
-- Creating dozens of domain-specific templates (start with 5 core ones)
-- Making templates mandatory or rigid (still adaptable)
-- Losing the lean philosophy (every template stays focused)
-- Complex template inheritance system (keep it simple)
-
-## Notes
-
-Current template (to become "minimal"):
-- Simple: Goal, Key Points, Non-Goals, Notes
-- Works but feels like a form
-
-New default template structure:
-- Status with emoji, spec location link
-- Overview, Objectives, Non-Goals
-- Design, Implementation Plan (numbered)
-- Success Criteria (checkboxes)
-- References, Notes
-- More actionable and structured while staying lean
-
-Template directory structure:
-```
-templates/
-├── default/
-├── minimal/
-├── team/
-├── enterprise/
-└── api/
-```
-
-Each can contain multiple files - not just spec.md.