lean-spec 0.2.10 → 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,6 +100,97 @@ 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/)

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.10",
+  "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.10",
-    "@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

@@ -28,6 +28,7 @@
 | 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
 
@@ -36,6 +37,7 @@
 | **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
@@ -46,13 +48,14 @@
 | Skip discovery | Run `board` and `search` first |
 | Leave status as "planned" | Update to `in-progress` before coding |
 | Edit frontmatter manually | Use `update` tool |
+| Complete spec without documentation | Document progress, prompts, learnings first |
 
 ## 📋 SDD Workflow
 
 ```
 BEFORE: board → search → check existing specs
 DURING: update status to in-progress → code → document decisions → link dependencies
-AFTER:  update status to complete → document learnings
+AFTER:  document completion → update status to complete
 ```
 
 **Status tracks implementation, NOT spec writing.**
@@ -84,6 +87,20 @@ lean-spec link <spec> --depends-on <other-spec>
 | 3,500-5,000 | ⚠️ Consider splitting |
 | >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)
 
 1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting

package/templates/standard/AGENTS.md

@@ -28,6 +28,7 @@
 | 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
 
@@ -36,6 +37,7 @@
 | **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
@@ -46,13 +48,14 @@
 | Skip discovery | Run `board` and `search` first |
 | Leave status as "planned" | Update to `in-progress` before coding |
 | Edit frontmatter manually | Use `update` tool |
+| Complete spec without documentation | Document progress, prompts, learnings first |
 
 ## 📋 SDD Workflow
 
 ```
 BEFORE: board → search → check existing specs
 DURING: update status to in-progress → code → document decisions → link dependencies
-AFTER:  update status to complete → document learnings
+AFTER:  document completion → update status to complete
 ```
 
 **Status tracks implementation, NOT spec writing.**
@@ -84,6 +87,20 @@ lean-spec link <spec> --depends-on <other-spec>
 | 3,500-5,000 | ⚠️ Consider splitting |
 | >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)
 
 1. **Context Economy** - <2,000 tokens optimal, >3,500 needs splitting

package/dist/backfill-446GBTBC.js

@@ -1,5 +0,0 @@
-export { backfillCommand, backfillTimestamps } from './chunk-H5MCUMBK.js';
-import './chunk-RF5PKL6L.js';
-import './chunk-VN5BUHTV.js';
-//# sourceMappingURL=backfill-446GBTBC.js.map
-//# sourceMappingURL=backfill-446GBTBC.js.map

package/dist/backfill-446GBTBC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"backfill-446GBTBC.js"}