@leanspec/ui 0.2.9-dev.20251205030455 → 0.2.10

package/.next/standalone/packages/ui/dist/standalone/specs/archived/039-template-variable-sync/README.md

@@ -0,0 +1,192 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - bug
+  - templates
+  - frontmatter
+  - enhancement
+priority: high
+completed: '2025-11-03'
+---
+
+# Template Variable Synchronization
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: bug, templates, frontmatter, enhancement
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+When creating a spec with `--field priority=high`, the frontmatter is correctly updated but the template body still shows hardcoded values. For example:
+
+```markdown
+---
+priority: high    # ✓ Correct (from --field)
+---
+
+> **Priority**: Medium  # ✗ Wrong (hardcoded in template)
+```
+
+**Why this matters:**
+- Inconsistent data between frontmatter and body content
+- Users expect `--field` values to populate throughout the spec
+- Manual editing required to fix mismatches
+- Affects `priority`, `status`, and potentially other fields
+
+**Root cause:** Templates have hardcoded values in body content instead of using variable placeholders like `{priority}`, `{status}`, etc.
+
+## Design
+
+### Solution 1: Add Frontmatter Variables to Variable Resolver
+
+Extend `variable-resolver.ts` to support frontmatter field variables:
+
+```typescript
+export interface VariableContext {
+  name?: string;
+  date?: string;
+  projectName?: string;
+  gitInfo?: GitInfo;
+  customVariables?: Record<string, string>;
+  frontmatter?: Record<string, unknown>;  // NEW
+}
+```
+
+**Variable resolution flow:**
+1. Parse template to extract frontmatter
+2. Merge frontmatter fields into variable context
+3. Resolve variables in body (including `{priority}`, `{status}`, etc.)
+4. Support nested fields like `{tags}` (array → comma-separated string)
+
+**Template update:**
+```markdown
+---
+status: planned
+priority: medium
+tags: []
+---
+
+# {name}
+
+> **Status**: {status} · **Priority**: {priority} · **Created**: {date}
+```
+
+### Solution 2: Post-Process After Frontmatter Update
+
+Alternative approach - update body content after frontmatter is modified:
+
+```typescript
+// In create.ts, after updating frontmatter:
+if (options.priority) {
+  parsed.data.priority = options.priority;
+  // Also update body content
+  content = content.replace(/Priority[:\s]+\w+/gi, `Priority: ${capitalize(options.priority)}`);
+}
+```
+
+**Pros**: Simple, no template changes needed  
+**Cons**: Fragile (regex-based), doesn't handle all cases
+
+### Recommended: Solution 1
+
+More robust, consistent with existing variable system, enables richer templates.
+
+## Plan
+
+- [ ] Extend `VariableContext` to include frontmatter fields
+- [ ] Update `buildVariableContext()` to parse frontmatter from template
+- [ ] Update `resolveVariables()` to handle frontmatter field variables
+- [ ] Add special handling for arrays (e.g., `{tags}` → comma-separated)
+- [ ] Add special handling for status/priority display formatting
+- [ ] Update all templates to use variables instead of hardcoded values
+  - [ ] `templates/standard/spec-template.md`
+  - [ ] `templates/minimal/spec-template.md`
+  - [ ] `templates/enterprise/spec-template.md`
+  - [ ] `.lean-spec/templates/spec-template.md` (if exists)
+- [ ] Update docs to document available frontmatter variables
+- [ ] Add tests for frontmatter variable resolution
+- [ ] Test with various field types (string, number, boolean, array)
+
+## Test
+
+### Variable Resolution
+- [ ] `{priority}` resolves to frontmatter priority value
+- [ ] `{status}` resolves to frontmatter status value
+- [ ] `{tags}` resolves to comma-separated tag list
+- [ ] Custom fields like `{epic}` resolve correctly
+- [ ] Missing fields don't break template (empty string or default)
+
+### Integration
+- [ ] `lean-spec create test --field priority=high` shows "Priority: high" in body
+- [ ] `lean-spec create test --field status=in-progress` shows correct status
+- [ ] Array fields like tags display correctly
+- [ ] Existing specs without variables still work
+
+### Edge Cases
+- [ ] Boolean fields (true/false) resolve as strings
+- [ ] Number fields resolve as strings
+- [ ] Nested objects are handled gracefully
+- [ ] Variables in frontmatter values don't cause recursion
+
+## Notes
+
+**Complexity**: Medium - requires careful handling of frontmatter parsing order
+
+**Workaround (current)**: Users can manually edit the body after creation, or update templates locally to match their needs
+
+**Alternative considered**: Use a more sophisticated template engine (Handlebars, Nunjucks), but that adds dependencies and complexity for a simple use case
+
+**Timeline**: Should be implemented before v1.0 release to avoid breaking template changes later
+
+---
+
+## Implementation Complete ✅
+
+**Implemented on**: 2025-11-03
+
+### What Was Built
+
+Implemented Solution 1 (frontmatter variables in variable resolver) as recommended in the design.
+
+**Key Changes:**
+
+1. **Extended `VariableContext`** to include `frontmatter` field
+2. **Added formatting helpers** for special field types:
+   - `formatStatus()` - Maps status values to emoji + label (e.g., "planned" → "📅 Planned")
+   - `formatPriority()` - Capitalizes priority values (e.g., "high" → "High")  
+   - `formatFrontmatterValue()` - Generic formatter handling arrays, objects, and primitives
+3. **Updated `resolveVariables()`** to process frontmatter field variables after built-in and custom variables
+4. **Refactored `create.ts`** to:
+   - Always parse frontmatter after initial template variable resolution
+   - Apply frontmatter variable resolution to body content
+   - Ensures `{status}`, `{priority}`, `{tags}`, etc. in templates are replaced with actual values
+5. **Updated all templates** (standard, minimal, enterprise) to use variables instead of hardcoded values
+
+### Test Coverage
+
+- ✅ Added 8 new unit tests for frontmatter variable resolution
+- ✅ All 165 tests passing
+- ✅ Manual testing confirms correct behavior with `--priority`, `--tags`, `--assignee` flags
+
+### Usage Examples
+
+```bash
+# Create spec with high priority - body shows "Priority: High"
+lean-spec create my-feature --priority high
+
+# Create spec with tags - frontmatter and body stay in sync
+lean-spec create api-feature --tags api,backend
+
+# Enterprise template with assignee
+lean-spec create project --assignee alice
+```
+
+### Benefits Delivered
+
+✅ Frontmatter and body content now stay synchronized  
+✅ No manual editing required after spec creation  
+✅ Works with all built-in templates  
+✅ Extensible to custom frontmatter fields  
+✅ Maintains backward compatibility

package/.next/standalone/packages/ui/dist/standalone/specs/archived/040-spec-viewer-commands/README.md

@@ -0,0 +1,171 @@
+---
+status: complete
+created: '2025-11-03'
+tags:
+  - cli
+  - enhancement
+  - ux
+  - viewer
+priority: high
+completed: '2025-11-03'
+---
+
+# Spec Viewer Commands
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: cli, enhancement, ux, viewer
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+Add new `lean-spec` commands for viewing and reading spec details with rich rendering capabilities. Users currently need to manually open spec files in their editor or navigate to the specs directory. This spec introduces commands to view spec content directly in the terminal with proper markdown rendering, making it easier to quickly read and reference specs without leaving the command line.
+
+**Why now?** As LeanSpec grows, users need quick ways to view spec content. This is foundational for:
+- MCP server integration (spec 033) - needs to expose spec content to AI agents
+- Better CLI UX - completes the workflow of discover → view → edit
+- AI agent workflows - agents need to read specs before taking action
+
+## Design
+
+**New Commands:**
+
+### `lean-spec show <spec-name>`
+Display full spec content with rendered markdown in the terminal.
+
+```bash
+lean-spec show api-redesign
+lean-spec show 015-npm-publishing  # Also support spec number
+```
+
+**Features:**
+- Render markdown with syntax highlighting (headers, lists, code blocks)
+- Preserve frontmatter display in readable format
+- Support terminal hyperlinks for cross-references
+- Gracefully degrade for non-interactive terminals
+- Show spec metadata (status, priority, tags) at top
+
+**Implementation:**
+- Use `marked-terminal` or `ink-markdown` for rendering
+- Parse frontmatter and display separately from content
+- Auto-detect terminal capabilities (colors, hyperlinks)
+- Handle long content with pagination (optional `--no-pager` flag)
+
+### `lean-spec view <spec-name>` (alias)
+Shorter alias for `lean-spec show` for convenience.
+
+### `lean-spec read <spec-name>` (raw mode)
+Output raw markdown content without rendering (useful for piping, AI consumption, scripting).
+
+```bash
+lean-spec read api-redesign
+lean-spec read 015-npm-publishing | grep "TODO"
+```
+
+**Output Options:**
+- `--format=markdown` (default) - raw markdown
+- `--format=json` - structured JSON with frontmatter and content separated
+- `--frontmatter-only` - only output frontmatter as JSON
+
+### `lean-spec open <spec-name>`
+Open spec in default editor or specified editor.
+
+```bash
+lean-spec open api-redesign
+lean-spec open api-redesign --editor=code  # Open in VS Code
+```
+
+**Technical Approach:**
+
+1. **Markdown Rendering:**
+   - Add `marked-terminal` for terminal markdown rendering
+   - Configure syntax highlighting for code blocks
+   - Handle edge cases (wide terminals, small terminals, no-color mode)
+
+2. **Content Resolution:**
+   - Reuse existing spec loader logic
+   - Support spec name, full path, or spec number as input
+   - Handle README.md vs spec.md file naming
+
+3. **Output Formatting:**
+   - Separate frontmatter rendering from content
+   - Add color-coded status badges
+   - Support `--no-color` flag for CI/scripting
+
+4. **Pagination:**
+   - Auto-detect if content exceeds terminal height
+   - Use system pager (`less`, `more`) if available
+   - Support `--no-pager` to disable
+
+5. **Integration Points:**
+   - Export `readSpec()` utility for MCP server reuse
+   - Ensure JSON format matches MCP resource schema
+   - Add to help/docs as recommended workflow
+
+## Plan
+
+- [ ] Add `marked-terminal` dependency
+- [ ] Implement `lean-spec show` command with markdown rendering
+- [ ] Add frontmatter display formatting
+- [ ] Implement `lean-spec read` command for raw/JSON output
+- [ ] Add `lean-spec view` alias
+- [ ] Implement `lean-spec open` command with editor detection
+- [ ] Add pagination support for long content
+- [ ] Add terminal capability detection (colors, hyperlinks)
+- [ ] Write unit tests for rendering logic
+- [ ] Write integration tests for all commands
+- [ ] Update CLI help and documentation
+- [ ] Add examples to README
+
+## Test
+
+- [ ] `lean-spec show` renders markdown correctly in terminal
+- [ ] Frontmatter displays with proper formatting
+- [ ] Code blocks have syntax highlighting
+- [ ] Long specs trigger pagination (unless --no-pager)
+- [ ] `lean-spec read` outputs raw markdown
+- [ ] `lean-spec read --format=json` outputs valid JSON
+- [ ] `lean-spec read --frontmatter-only` outputs frontmatter only
+- [ ] `lean-spec open` opens spec in default editor
+- [ ] `lean-spec open --editor=<cmd>` uses specified editor
+- [ ] Commands work with spec name, number, or path
+- [ ] Graceful error for non-existent specs
+- [ ] Works in non-interactive terminals (CI)
+- [ ] Respects `--no-color` flag
+- [ ] Terminal hyperlinks work for supported terminals
+
+## Notes
+
+**Dependencies:**
+- Related to spec 033 (MCP Server) - `read` command output should match MCP resource format
+- Complements spec 006 (PM Visualization) - different view modes for different contexts
+
+**Markdown Rendering Libraries Considered:**
+- `marked-terminal` - Battle-tested, good terminal rendering
+- `ink-markdown` - React-based, heavier but more features
+- `terminal-markdown` - Lighter but less maintained
+
+**Decision:** Start with `marked-terminal` for simplicity and reliability.
+
+**Editor Detection:**
+- Check `$EDITOR`, `$VISUAL` environment variables
+- Fall back to `open` (macOS), `xdg-open` (Linux), `start` (Windows)
+- Allow override with `--editor` flag or config setting
+
+**Future Enhancements:**
+- Interactive mode with search/filter
+- Spec-to-spec navigation (jump to dependencies)
+- Diff mode (`lean-spec show <spec> --diff`) to see changes
+- Export to PDF/HTML for sharing
+
+**MCP Integration Notes:**
+The `lean-spec read --format=json` output should align with the MCP resource schema:
+```json
+{
+  "name": "spec-name",
+  "path": "/path/to/spec",
+  "frontmatter": {...},
+  "content": "...",
+  "sections": [...]
+}
+```

package/.next/standalone/packages/ui/dist/standalone/specs/archived/042-mcp-error-handling/README.md

@@ -0,0 +1,200 @@
+---
+status: archived
+created: '2025-11-04'
+tags:
+  - bug
+  - mcp
+  - stability
+  - error-handling
+priority: critical
+related:
+  - 043-official-launch-02
+completed: '2025-11-04'
+created_at: '2025-11-11T04:26:08.161Z'
+updated_at: '2025-11-11T04:26:08.161Z'
+transitions:
+  - status: archived
+    at: '2025-11-11T04:26:08.161Z'
+---
+
+# MCP Server Should Not Exit on Tool Errors
+
+> **Status**: 📦 Archived · **Priority**: Critical · **Created**: 2025-11-04 · **Tags**: bug, mcp, stability, error-handling
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Critical bug:** When MCP server tool calls encounter errors (e.g., spec not found), the commands call `process.exit(1)`, crashing the entire MCP server and terminating the agent chat session.
+
+**Example from logs:**
+```
+2025-11-04 15:31:05.575 [warning] [server stderr] Error: Spec not found: 041-simplify-viewer-commands
+2025-11-04 15:31:05.578 [info] Connection state: Error Process exited with code 1
+```
+
+**Impact:**
+- 🔴 **Crashes entire agent session** - User loses context and has to restart
+- 🔴 **No graceful error handling** - Agent can't recover or try alternatives
+- 🔴 **Poor UX** - Single typo in spec name kills the session
+- 🔴 **Violates MCP protocol** - Tools should return error objects, not exit
+
+**Root cause:** Commands like `showCommand`, `viewCommand`, `readCommand`, `openCommand`, etc. call `process.exit(1)` on errors. This is fine for CLI usage but catastrophic when called from MCP server.
+
+## Design
+
+### Solution: Never Exit, Return Errors
+
+MCP tools should **never** call `process.exit()`. Instead, they should:
+1. Throw errors that the MCP server catches
+2. Return error responses via MCP protocol
+3. Let the agent handle the error gracefully
+
+### Code Changes Needed
+
+**1. Update all viewer commands to throw instead of exit:**
+
+```typescript
+// BEFORE (crashes MCP server)
+if (!spec) {
+  console.error(chalk.red(`Error: Spec not found: ${specPath}`));
+  process.exit(1);
+}
+
+// AFTER (returns error to agent)
+if (!spec) {
+  throw new Error(`Spec not found: ${specPath}. Try: lean-spec list`);
+}
+```
+
+**2. Wrap MCP tool handlers with error catching:**
+
+```typescript
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  
+  try {
+    // ... tool logic ...
+  } catch (error) {
+    return {
+      content: [{
+        type: "text",
+        text: `Error: ${error instanceof Error ? error.message : String(error)}`
+      }],
+      isError: true
+    };
+  }
+});
+```
+
+**3. Remove console.error() from commands when used via MCP:**
+
+Commands should accept a `silent` option or check if they're running in MCP mode:
+
+```typescript
+export async function showCommand(
+  specPath: string,
+  options: {
+    noColor?: boolean;
+    throwErrors?: boolean;  // NEW: for MCP usage
+  } = {}
+): Promise<void> {
+  const spec = await readSpecContent(specPath, process.cwd());
+  
+  if (!spec) {
+    const message = `Spec not found: ${specPath}. Try: lean-spec list`;
+    if (options.throwErrors) {
+      throw new Error(message);  // MCP mode
+    } else {
+      console.error(chalk.red(`Error: ${message}`));  // CLI mode
+      process.exit(1);
+    }
+  }
+  // ...
+}
+```
+
+### Files to Update
+
+**Commands with process.exit():**
+- `src/commands/viewer.ts` (5 instances: showCommand, readCommand, openCommand)
+- `src/commands/update.ts` (likely has exit calls)
+- `src/commands/archive.ts` (likely has exit calls)
+- Any other command that calls `process.exit()`
+
+**MCP Server:**
+- `src/mcp-server.ts` - Add try/catch to all tool handlers
+- Ensure tool responses include `isError: true` for errors
+
+## Plan
+
+- [ ] Audit all command files for `process.exit()` calls
+- [ ] Add `throwErrors` option to all command functions
+- [ ] Update viewer commands to throw instead of exit when `throwErrors: true`
+- [ ] Update MCP tool handlers to pass `throwErrors: true`
+- [ ] Wrap all MCP tool handlers in try/catch
+- [ ] Return proper error responses via MCP protocol
+- [ ] Test error scenarios (spec not found, invalid input, etc.)
+- [ ] Verify MCP server stays alive after errors
+- [ ] Update tests to verify both CLI and MCP modes
+
+## Test
+
+### MCP Error Handling Tests
+
+- [ ] Call `lean-spec_update` with non-existent spec → returns error, server stays alive
+- [ ] Call `lean-spec_read` with non-existent spec → returns error, server stays alive
+- [ ] Try to create spec with invalid name → returns error, server stays alive
+- [ ] Multiple consecutive errors → server handles all gracefully
+- [ ] Agent session remains active after tool errors
+- [ ] Error messages are clear and actionable
+
+### CLI Behavior Tests
+
+- [ ] CLI commands still exit with code 1 on errors (backward compat)
+- [ ] Error messages still display properly in terminal
+- [ ] No regression in CLI UX
+
+### Manual Verification
+
+```bash
+# Test MCP via VS Code Copilot
+1. Try to update non-existent spec: @lean-spec update 999-fake
+2. Verify: Error message appears, chat continues
+3. Try valid command after error: @lean-spec list
+4. Verify: Works normally, server didn't crash
+```
+
+## Notes
+
+**Why this is critical:**
+- MCP servers are long-running processes shared across multiple agent interactions
+- A single tool error shouldn't kill the entire server
+- This violates the MCP protocol design (tools return errors, not crash)
+
+**MCP Protocol Spec:**
+From the MCP documentation, tools should return:
+```json
+{
+  "content": [{"type": "text", "text": "error message"}],
+  "isError": true
+}
+```
+
+NOT: `process.exit(1)`
+
+**Related Issues:**
+- This affects ALL commands, not just viewer commands
+- Need consistent error handling strategy across codebase
+- Consider creating a `CommandContext` class to handle CLI vs MCP modes
+
+**Alternative Approaches Considered:**
+1. ~~Catch process.exit() globally~~ - Too hacky, hard to debug
+2. ~~Spawn commands in child processes~~ - Too complex, performance overhead
+3. **Add throwErrors flag** - ✅ Clean, explicit, testable
+
+**Follow-up Work:**
+- Create consistent error handling pattern for all commands
+- Add logging/telemetry for MCP errors
+- Document command authoring guidelines (never use process.exit in shared code)