lean-spec 0.2.9 → 0.2.15-dev.21022397862

package/README.md

@@ -84,14 +84,15 @@ Works with any AI coding assistant via MCP or CLI:
 
 ## Features
 
-| Feature | Description |
-|---------|-------------|
-| **📊 Kanban Board** | `lean-spec board` - visual project tracking |
-| **🔍 Smart Search** | `lean-spec search` - find specs by content or metadata |
-| **🔗 Dependencies** | Track spec relationships with `depends_on` and `related` |
-| **🎨 Web UI** | `lean-spec ui` - browser-based dashboard |
-| **📈 Project Stats** | `lean-spec stats` - health metrics and bottleneck detection |
-| **🤖 AI-Native** | MCP server + CLI for AI assistants |
+| Feature             | Description                                                   |
+| ------------------- | ------------------------------------------------------------- |
+| **📊 Kanban Board**  | `lean-spec board` - visual project tracking                   |
+| **🔍 Smart Search**  | `lean-spec search` - find specs by content or metadata        |
+| **🔗 Dependencies**  | Track spec relationships with `depends_on` and `related`      |
+| **🎨 Web UI**        | `lean-spec ui` - browser-based dashboard                      |
+| **📈 Project Stats** | `lean-spec stats` - health metrics and bottleneck detection   |
+| **🤖 AI-Native**     | MCP server + CLI for AI assistants                            |
+| **🖥️ Desktop App**   | Native Tauri shell with tray + shortcuts (`pnpm dev:desktop`) |
 
 <p align="center">
   <img src="https://github.com/codervisor/lean-spec-docs/blob/main/static/img/ui/ui-board-view.png" alt="Kanban Board View" width="800">
@@ -99,13 +100,104 @@ Works with any AI coding assistant via MCP or CLI:
 
 ---
 
+## Requirements
+
+### Runtime
+- **Node.js**: `>= 20.0.0`
+- **pnpm**: `>= 10.0.0` (preferred package manager)
+
+### Development
+- **Node.js**: `>= 20.0.0`
+- **Rust**: `>= 1.70` (for building CLI/MCP/HTTP binaries)
+- **pnpm**: `>= 10.0.0`
+
+**Quick Check:**
+```bash
+node --version   # Should be v20.0.0 or higher
+pnpm --version   # Should be 10.0.0 or higher
+rustc --version  # Should be 1.70 or higher (dev only)
+```
+
+---
+
+## Desktop App
+
+The `@leanspec/desktop` package wraps the Vite UI (`@leanspec/ui`) in a lightweight Tauri shell for local, multi-project workflows backed by Rust commands:
+
+```bash
+# Launch the desktop shell with hot reload
+pnpm install
+pnpm dev:desktop
+
+# Produce signed installers + embedded UI bundle
+pnpm build:desktop
+```
+
+Key capabilities:
+- Frameless window with custom title bar + native controls
+- Global shortcuts (`Cmd/Ctrl+Shift+L` to toggle, `Cmd/Ctrl+Shift+K` to open the project switcher, `Cmd/Ctrl+Shift+N` to add a spec)
+- Shared project registry + native folder picker backed by `~/.lean-spec/projects.json`
+- System tray with recent projects, background notifications, and update checks
+- Embedded Vite static build + Rust HTTP server for offline packaging (macOS `.dmg`, Windows `.msi/.exe`, Linux `.AppImage/.deb/.rpm`)
+
+See [packages/desktop/README.md](packages/desktop/README.md) for configuration details.
+
+---
+
+## Developer Workflow
+
+Common development tasks using `pnpm`:
+
+```bash
+# Development
+pnpm install             # Install dependencies
+pnpm build               # Build all packages
+pnpm dev                 # Start dev mode (UI + Core)
+pnpm dev:web             # UI only
+pnpm dev:cli             # CLI only
+pnpm dev:desktop         # Desktop app
+
+# Testing
+pnpm test                # Run all tests
+pnpm test:ui             # Tests with UI
+pnpm test:coverage       # Coverage report
+pnpm typecheck           # Type check all packages
+
+# Rust
+pnpm rust:build          # Build Rust packages (release)
+pnpm rust:build:dev      # Build Rust (dev, faster)
+pnpm rust:test           # Run Rust tests
+pnpm rust:check          # Quick Rust check
+pnpm rust:clippy         # Rust linting
+pnpm rust:fmt            # Format Rust code
+
+# CLI (run locally)
+pnpm cli board           # Show spec board
+pnpm cli list            # List specs
+pnpm cli create my-feat  # Create new spec
+pnpm cli validate        # Validate specs
+
+# Documentation
+pnpm docs:dev            # Start docs site
+pnpm docs:build          # Build docs
+
+# Release
+pnpm pre-release         # Run all pre-release checks
+pnpm prepare-publish     # Prepare for npm publish
+pnpm restore-packages    # Restore after publish
+```
+
+See [package.json](package.json) for all available scripts.
+
+---
+
 ## Documentation
 
 📖 [Full Documentation](https://www.lean-spec.dev) · [CLI Reference](https://www.lean-spec.dev/docs/reference/cli) · [First Principles](https://www.lean-spec.dev/docs/advanced/first-principles) · [FAQ](https://www.lean-spec.dev/docs/faq) · [中文文档](https://www.lean-spec.dev/zh-Hans/)
 
 ## Community
 
-💬 [Discussions](https://github.com/codervisor/lean-spec/discussions) · 🐛 [Issues](https://github.com/codervisor/lean-spec/issues) · 🤝 [Contributing](CONTRIBUTING.md) · 📋 [Changelog](CHANGELOG) · 📄 [LICENSE](LICENSE)
+💬 [Discussions](https://github.com/codervisor/lean-spec/discussions) · 🐛 [Issues](https://github.com/codervisor/lean-spec/issues) · 🤝 [Contributing](CONTRIBUTING.md) · 📋 [Changelog](CHANGELOG.md) · 📄 [LICENSE](LICENSE)
 
 ---
 

package/bin/lean-spec-rust.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * LeanSpec CLI Binary Wrapper
+ * 
+ * This script detects the current platform and architecture,
+ * then spawns the appropriate Rust binary with the provided arguments.
+ * 
+ * The wrapper looks for binaries in the following locations:
+ * 1. Platform-specific npm package (lean-spec-darwin-x64, etc.)
+ * 2. Local binaries directory (for development)
+ */
+
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { accessSync } from 'fs';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Debug mode - enable with LEANSPEC_DEBUG=1
+const DEBUG = process.env.LEANSPEC_DEBUG === '1';
+const debug = (...args) => DEBUG && console.error('[lean-spec debug]', ...args);
+
+// Platform detection mapping
+const PLATFORM_MAP = {
+  darwin: { x64: 'darwin-x64', arm64: 'darwin-arm64' },
+  linux: { x64: 'linux-x64', arm64: 'linux-arm64' },
+  win32: { x64: 'windows-x64', arm64: 'windows-arm64' }
+};
+
+function getBinaryPath() {
+  const platform = process.platform;
+  const arch = process.arch;
+  
+  debug('Platform detection:', { platform, arch });
+  
+  const platformKey = PLATFORM_MAP[platform]?.[arch];
+  if (!platformKey) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    console.error('Supported: macOS (x64/arm64), Linux (x64/arm64), Windows (x64)');
+    process.exit(1);
+  }
+
+  const isWindows = platform === 'win32';
+  const binaryName = isWindows ? 'lean-spec.exe' : 'lean-spec';
+  const packageName = `@leanspec/cli-${platformKey}`;
+  
+  debug('Binary info:', { platformKey, binaryName, packageName });
+
+  // Try to resolve platform package
+  try {
+    const resolvedPath = require.resolve(`${packageName}/${binaryName}`);
+    debug('Found platform package binary:', resolvedPath);
+    return resolvedPath;
+  } catch (e) {
+    debug('Platform package not found:', packageName, '-', e.message);
+  }
+
+  // Try local binaries directory (for development/testing)
+  try {
+    const localPath = join(__dirname, '..', 'binaries', platformKey, binaryName);
+    debug('Trying local binary:', localPath);
+    accessSync(localPath);
+    debug('Found local binary:', localPath);
+    return localPath;
+  } catch (e) {
+    debug('Local binary not found:', e.message);
+  }
+
+  // Try rust/target/release directory (for local development)
+  try {
+    const rustTargetPath = join(__dirname, '..', '..', '..', 'rust', 'target', 'release', binaryName);
+    debug('Trying rust target binary:', rustTargetPath);
+    accessSync(rustTargetPath);
+    debug('Found rust target binary:', rustTargetPath);
+    return rustTargetPath;
+  } catch (e) {
+    debug('Rust target binary not found:', e.message);
+  }
+
+  console.error(`Binary not found for ${platform}-${arch}`);
+  console.error(`Expected package: ${packageName}`);
+  console.error('');
+  console.error('To install:');
+  console.error('  npm install -g lean-spec');
+  console.error('');
+  console.error('If you installed globally, try:');
+  console.error('  npm uninstall -g lean-spec && npm install -g lean-spec');
+  process.exit(1);
+}
+
+// Execute binary
+const binaryPath = getBinaryPath();
+const args = process.argv.slice(2);
+
+debug('Spawning binary:', binaryPath);
+debug('Arguments:', args);
+
+const child = spawn(binaryPath, args, {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+child.on('exit', (code) => {
+  debug('Binary exited with code:', code);
+  process.exit(code ?? 1);
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start lean-spec:', err.message);
+  debug('Spawn error:', err);
+  process.exit(1);
+});

package/bin/lean-spec.js

@@ -1,2 +1,10 @@
 #!/usr/bin/env node
-import '../dist/cli.js';
+/**
+ * LeanSpec CLI Entry Point
+ * 
+ * Thin wrapper that delegates to the Rust binary.
+ * The TypeScript implementation has been deprecated in favor of Rust.
+ * 
+ * @see spec 181-typescript-deprecation-rust-migration
+ */
+import './lean-spec-rust.js';

package/binaries/darwin-arm64/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@leanspec/cli-darwin-arm64",
+  "version": "0.2.15-dev.21022397862",
+  "description": "LeanSpec CLI binary for macOS ARM64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "lean-spec",
+  "files": [
+    "lean-spec"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/lean-spec.git"
+  },
+  "license": "MIT"
+}

package/binaries/darwin-x64/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@leanspec/cli-darwin-x64",
+  "version": "0.2.15-dev.21022397862",
+  "description": "LeanSpec CLI binary for macOS x64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "lean-spec",
+  "files": [
+    "lean-spec"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/lean-spec.git"
+  },
+  "license": "MIT"
+}

package/binaries/linux-arm64/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@leanspec/cli-linux-arm64",
+  "version": "0.2.15-dev.21022397862",
+  "description": "LeanSpec CLI binary for Linux ARM64",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "lean-spec",
+  "files": [
+    "lean-spec"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/lean-spec.git"
+  },
+  "license": "MIT"
+}

package/binaries/linux-x64/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@leanspec/cli-linux-x64",
+  "version": "0.2.15-dev.21022397862",
+  "description": "LeanSpec CLI binary for Linux x64",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "lean-spec",
+  "files": [
+    "lean-spec"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/lean-spec.git"
+  },
+  "license": "MIT"
+}

package/binaries/windows-x64/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@leanspec/cli-windows-x64",
+  "version": "0.2.15-dev.21022397862",
+  "description": "LeanSpec CLI binary for Windows x64",
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "lean-spec.exe",
+  "files": [
+    "lean-spec.exe"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/lean-spec.git"
+  },
+  "license": "MIT"
+}

package/package.json

@@ -1,17 +1,13 @@
 {
   "name": "lean-spec",
-  "version": "0.2.9",
+  "version": "0.2.15-dev.21022397862",
   "description": "Specification-driven development made simple",
   "type": "module",
   "bin": {
     "lean-spec": "./bin/lean-spec.js"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
+    "typecheck": "echo 'No TypeScript source to check'"
   },
   "keywords": [
     "spec",
@@ -33,48 +29,18 @@
   },
   "files": [
     "bin/",
-    "dist/",
+    "binaries/",
     "templates/",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
-  "dependencies": {
-    "@inquirer/prompts": "^7.9.0",
-    "@modelcontextprotocol/sdk": "^1.21.0",
-    "chalk": "^5.3.0",
-    "cli-spinners": "^3.3.0",
-    "cli-table3": "^0.6.5",
-    "commander": "^14.0.2",
-    "dayjs": "^1.11.19",
-    "gray-matter": "^4.0.3",
-    "ink": "^6.4.0",
-    "ink-gradient": "^3.0.0",
-    "ink-progress-bar": "^3.0.0",
-    "ink-select-input": "^6.2.0",
-    "ink-spinner": "^5.0.0",
-    "ink-table": "^3.1.0",
-    "ink-text-input": "^6.0.0",
-    "js-yaml": "^4.1.0",
-    "marked": "^15.0.12",
-    "marked-terminal": "^7.3.0",
-    "open": "^11.0.0",
-    "ora": "^9.0.0",
-    "react": "^19.2.0",
-    "strip-ansi": "^7.1.2",
-    "tiktoken": "^1.0.22",
-    "tokenx": "^1.2.1",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@leanspec/core": "^0.2.9",
-    "@types/js-yaml": "^4.0.9",
-    "@types/marked-terminal": "^6.1.1",
-    "@types/node": "^20.10.0",
-    "@types/react": "^19.2.2",
-    "tsup": "^8.0.1",
-    "typescript": "^5.3.3",
-    "vitest": "^4.0.6"
+  "optionalDependencies": {
+    "@leanspec/cli-darwin-arm64": "workspace:*",
+    "@leanspec/cli-darwin-x64": "workspace:*",
+    "@leanspec/cli-linux-arm64": "workspace:*",
+    "@leanspec/cli-linux-x64": "workspace:*",
+    "@leanspec/cli-windows-x64": "workspace:*"
   },
   "engines": {
     "node": ">=20"

package/templates/detailed/AGENTS.md

@@ -12,132 +12,103 @@
 
 > **Why?** Skipping discovery creates duplicate work. Manual file creation breaks LeanSpec tooling.
 
-## 🔧 How to Manage Specs
-
-### Primary Method: MCP Tools (Recommended)
-
-If you have LeanSpec MCP tools available, **ALWAYS use them**:
-
-| Action | MCP Tool | Description |
-|--------|----------|-------------|
-| See project status | `board` | Kanban view + project health metrics |
-| List all specs | `list` | Filterable list with metadata |
-| Search specs | `search` | Semantic search across all content |
-| View a spec | `view` | Full content with formatting |
-| Create new spec | `create` | Auto-sequences, proper structure |
-| Update spec | `update` | Validates transitions, timestamps |
-| Link specs | `link` | Add dependencies (depends_on) |
-| Unlink specs | `unlink` | Remove dependencies |
-| Check dependencies | `deps` | Visual dependency graph |
-
-**Why MCP over CLI?**
-- ✅ Direct tool integration (no shell execution needed)
-- ✅ Structured responses (better for AI reasoning)
-- ✅ Real-time validation (immediate feedback)
-- ✅ Context-aware (understands project state)
-
-### Fallback: CLI Commands
-
-If MCP tools are not available, use CLI commands:
-
-```bash
-lean-spec board              # Project overview
-lean-spec list               # See all specs
-lean-spec search "query"     # Find relevant specs
-lean-spec create <name>      # Create new spec
-lean-spec update <spec> --status <status>  # Update status
-lean-spec link <spec> --depends-on <other>   # Add dependencies
-lean-spec unlink <spec> --depends-on <other> # Remove dependencies
-lean-spec deps <spec>        # Show dependencies
-```
-
-**Tip:** Check if you have LeanSpec MCP tools available before using CLI.
-
-## ⚠️ SDD Workflow Checkpoints
-
-### Before Starting ANY Task
-
-1. 📋 **Run `board`** - What's the current project state?
-2. 🔍 **Run `search`** - Are there related specs already?
-3. 📝 **Check existing specs** - Is there one for this work?
-
-### During Implementation
-
-4. 📊 **Update status to `in-progress`** BEFORE coding
-5. 📝 **Document decisions** in the spec as you work
-6. 🔗 **Link dependencies** if you discover blocking relationships
-
-### After Completing Work
-
-7. ✅ **Update status to `complete`** when done
-8. 📄 **Document what you learned** in the spec
-9. 🤔 **Create follow-up specs** if needed
-
-### 🚫 Common Mistakes to Avoid
+## 🔧 Managing Specs
+
+### MCP Tools (Preferred) with CLI Fallback
+
+| Action | MCP Tool | CLI Fallback |
+|--------|----------|--------------|
+| Project status | `board` | `lean-spec board` |
+| List specs | `list` | `lean-spec list` |
+| Search specs | `search` | `lean-spec search "query"` |
+| View spec | `view` | `lean-spec view <spec>` |
+| Create spec | `create` | `lean-spec create <name>` |
+| Update spec | `update` | `lean-spec update <spec> --status <status>` |
+| Link specs | `link` | `lean-spec link <spec> --depends-on <other>` |
+| Unlink specs | `unlink` | `lean-spec unlink <spec> --depends-on <other>` |
+| Dependencies | `deps` | `lean-spec deps <spec>` |
+| Token count | `tokens` | `lean-spec tokens <spec>` |
+| Validate specs | `validate` | `lean-spec validate` |
+
+## ⚠️ Core Rules
+
+| Rule | Details |
+|------|---------|
+| **NEVER edit frontmatter manually** | Use `update`, `link`, `unlink` for: `status`, `priority`, `tags`, `assignee`, `transitions`, timestamps, `depends_on` |
+| **ALWAYS link spec references** | Content mentions another spec → `lean-spec link <spec> --depends-on <other>` |
+| **Track status transitions** | `planned` → `in-progress` (before coding) → `complete` (after done) |
+| **Keep specs current** | Document progress, decisions, and learnings as work happens. Obsolete specs mislead both humans and AI |
+| **No nested code blocks** | Use indentation instead |
+
+### 🚫 Common Mistakes
 
 | ❌ Don't | ✅ Do Instead |
 |----------|---------------|
 | Create spec files manually | Use `create` tool |
-| Skip discovery before new work | Run `board` and `search` first |
-| Leave status as "planned" after starting | Update to `in-progress` immediately |
-| Finish work without updating spec | Document decisions, update status |
+| Skip discovery | Run `board` and `search` first |
+| Leave status as "planned" | Update to `in-progress` before coding |
 | Edit frontmatter manually | Use `update` tool |
-| Forget about specs mid-conversation | Check spec status periodically |
-
-## Core Rules
-
-1. **Read README.md first** - Understand project context
-2. **Check specs/** - Review existing specs before starting
-3. **Use MCP tools** - Prefer MCP over CLI when available
-4. **Follow LeanSpec principles** - Clarity over documentation
-5. **Keep it minimal** - If it doesn't add clarity, cut it
-6. **NEVER manually edit frontmatter** - Use `update`, `link`, `unlink` tools
-7. **Track progress in specs** - Update status and document decisions
+| Complete spec without documentation | Document progress, prompts, learnings first |
 
-## When to Use Specs
+## 📋 SDD Workflow
 
-**Write a spec for:**
-- Features affecting multiple parts of the system
-- Breaking changes or significant refactors
-- Design decisions needing team alignment
+```
+BEFORE: board → search → check existing specs
+DURING: update status to in-progress → code → document decisions → link dependencies
+AFTER:  document completion → update status to complete
+```
 
-**Skip specs for:**
-- Bug fixes
-- Trivial changes
-- Self-explanatory refactors
+**Status tracks implementation, NOT spec writing.**
 
 ## Spec Dependencies
 
-### `depends_on` - Blocking Dependency
-Directional dependency - this spec cannot start until dependencies are complete.
-**Use when:** True blocking dependency, work order matters, one spec builds on another.
+Use `depends_on` to express blocking relationships between specs:
+- **`depends_on`** = True blocker, work order matters, directional (A depends on B)
 
+Link dependencies when one spec builds on another:
 ```bash
 lean-spec link <spec> --depends-on <other-spec>
 ```
 
-**Note:** Only use `depends_on` for actual blocking dependencies. Don't link specs just because they're "related" - link them when one truly blocks the other.
-
-## Quality Standards
+## When to Use Specs
 
-- **Status tracking is mandatory:**
-  - `planned` → after creation
-  - `in-progress` → BEFORE starting implementation
-  - `complete` → AFTER finishing implementation
-- Specs stay in sync with implementation
-- Never leave specs with stale status
+| ✅ Write spec | ❌ Skip spec |
+|---------------|--------------|
+| Multi-part features | Bug fixes |
+| Breaking changes | Trivial changes |
+| Design decisions | Self-explanatory refactors |
 
-## Spec Complexity Guidelines
+## Token Thresholds
 
 | Tokens | Status |
 |--------|--------|
 | <2,000 | ✅ Optimal |
 | 2,000-3,500 | ✅ Good |
 | 3,500-5,000 | ⚠️ Consider splitting |
-| >5,000 | 🔴 Should split |
+| >5,000 | 🔴 Must split |
+
+## Quality Validation
+
+Before completing work, validate spec quality:
+```bash
+lean-spec validate              # Check structure and quality
+lean-spec validate --check-deps # Verify dependency alignment
+```
+
+Validation checks:
+- Missing required sections
+- Excessive length (>400 lines)
+- Content/frontmatter dependency misalignment
+- Invalid frontmatter fields
+
+## First Principles (Priority Order)
 
-Use `tokens` tool to check spec size.
+1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting
+2. **Signal-to-Noise** - Every word must inform a decision
+3. **Intent Over Implementation** - Capture why, let how emerge
+4. **Bridge the Gap** - Both human and AI must understand
+5. **Progressive Disclosure** - Add complexity only when pain is felt
 
 ---
 
-**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!
+**Remember:** LeanSpec tracks what you're building. Keep specs in sync with your work!