@harnspec/cli 0.0.1

package/README.md

@@ -0,0 +1,225 @@
+# HarnSpec
+
+<p align="center">
+  <img src="https://github.com/harnspec/harnspec-docs/blob/main/static/img/logo-with-bg.svg" alt="HarnSpec Logo" width="120" height="120">
+</p>
+
+<p align="center">
+  <a href="https://github.com/harnspec/harnspec/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/harnspec/harnspec/ci.yml?branch=main" alt="CI Status"></a>
+  <a href="https://www.npmjs.com/package/@harnspec/cli"><img src="https://img.shields.io/npm/v/@harnspec/cli.svg?label=npm%20%40harnspec%2Fcli" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT%20with%20Commons%20Clause-red.svg" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://harnspec.github.io"><strong>Documentation</strong></a>
+  •
+  <a href="https://harnspec.github.io/zh-Hans/docs/guide/"><strong>中文文档</strong></a>
+  •
+  <a href="https://harnspec.github.io"><strong>Live Examples</strong></a>
+  •
+  <a href="https://harnspec.github.io/docs/tutorials/first-spec-with-ai"><strong>Tutorials</strong></a>
+</p>
+
+> [!IMPORTANT]
+> This project is a fork of [codervisor/lean-spec](https://github.com/codervisor/lean-spec). Following the fork, the [Commons Clause](LICENSE) license condition was added to the original MIT license to ensure the project's sustainability while remaining open for community use.
+
+---
+
+**Ship faster with higher quality. Lean specs that both humans and AI understand.**
+
+HarnSpec brings agile principles to SDD (Spec-Driven Development)—small, focused documents (<2,000 tokens) that keep you and your AI aligned.
+
+---
+
+## Quick Start
+
+```bash
+# Try with a tutorial project
+npx harnspec init --example dark-theme
+cd dark-theme && npm install && npm start
+
+# Or add to your existing project
+# Install with the @harnspec scope
+npm install -g @harnspec/cli && harnspec init
+```
+
+**Visualize your project:**
+
+```bash
+harnspec board    # Kanban view
+harnspec stats    # Project metrics
+harnspec ui       # Web UI at localhost:3000
+```
+
+**Next:** [Your First Spec with AI](https://harnspec.github.io/docs/tutorials/first-spec-with-ai) (10 min tutorial)
+
+---
+
+## Why HarnSpec?
+
+**High velocity + High quality.** Other SDD frameworks add process overhead (multi-step workflows, rigid templates). Vibe coding is fast but chaotic (no shared understanding). HarnSpec hits the sweet spot:
+
+- **Fast iteration** - Living documents that grow with your code
+- **AI performance** - Small specs = better AI output (context rot is real)
+- **Always current** - Lightweight enough that you actually update them
+
+📖 [Compare with Spec Kit, OpenSpec, Kiro →](https://harnspec.github.io/docs/guide/why-harnspec)
+
+---
+
+## AI Integration
+
+HarnSpec is designed to be used with any AI coding assistant (Claude Code, Cursor, Windsurf, GitHub Copilot, Aider, etc.) via the **CLI + Agent Skills** approach.
+
+Teach your AI assistant the methodology using:
+```bash
+harnspec skill install
+```
+
+AI agents can then use `harnspec` CLI tools directly to manage your project board and specs.
+
+📖 [Full AI integration guide →](https://harnspec.github.io/docs/guide/usage/ai-coding-workflow)
+
+---
+
+## Agent Skills
+
+Teach your AI assistant the Spec-Driven Development methodology:
+
+```bash
+# Recommended (uses skills.sh)
+harnspec skill install
+
+# Or directly via skills.sh
+npx skills add harnspec/skills@harnspec -y
+```
+
+This installs the **harnspec** skill which teaches AI agents:
+
+- When to create specs vs. implement directly
+- How to discover existing specs before creating new ones
+- Best practices for context economy and progressive disclosure
+- Complete SDD workflow (Discover → Design → Implement → Validate)
+
+**Compatible with:** Claude Code, Cursor, Windsurf, GitHub Copilot, and other [Agent Skills](https://skills.sh/) compatible tools.
+
+📖 [View skill documentation →](.agents/skills/harnspec/SKILL.md)
+
+---
+
+## Features
+
+| Feature             | Description                                                                                       |
+| ------------------- | ------------------------------------------------------------------------------------------------- |
+| **📊 Kanban Board**  | `harnspec board` - visual project tracking                                                       |
+| **🔍 Smart Search**  | `harnspec search` - find specs by content or metadata                                            |
+| **🔗 Dependencies**  | Track spec relationships with `depends_on` and `related`                                          |
+| **🎨 Web UI**        | `harnspec ui` - browser-based dashboard                                                          |
+| **📈 Project Stats** | `harnspec stats` - health metrics and bottleneck detection                                       |
+| **🤖 AI-Native**     | CLI-first with Agent Skills                                                                |
+| **🖥️ Desktop App**   | Desktop app repo: [harnspec/harnspec-desktop](https://github.com/harnspec/harnspec-desktop) |
+
+<p align="center">
+  <img src="https://github.com/harnspec/harnspec-docs/blob/main/static/img/ui/ui-board-view.png" alt="Kanban Board View" width="800">
+</p>
+
+---
+
+## 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/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 desktop application has moved to a dedicated repository:
+
+- <https://github.com/harnspec/harnspec-desktop>
+
+Use that repository for desktop development, CI, and release workflows.
+
+---
+
+## 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
+
+# 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://harnspec.github.io) · [CLI Reference](https://harnspec.github.io/docs/reference/cli) · [First Principles](https://harnspec.github.io/docs/advanced/first-principles) · [FAQ](https://harnspec.github.io/docs/faq) · [中文文档](https://harnspec.github.io/zh-Hans/)
+
+## Community
+
+💬 [Discussions](https://github.com/harnspec/harnspec/discussions) · 🐛 [Issues](https://github.com/harnspec/harnspec/issues) · 🤝 [Contributing](CONTRIBUTING.md) · 📋 [Changelog](CHANGELOG.md) · 📄 [LICENSE](LICENSE)
+
+---
+
+### Contact Me | 联系我
+
+If you find HarnSpec helpful, feel free to add me on WeChat (note "HarnSpec") to join the discussion group.
+
+如果您觉得 HarnSpec 对您有帮助，欢迎添加微信（备注 "HarnSpec"）加入交流群。
+
+<p align="center">
+  <img src="https://github.com/harnspec/harnspec-docs/blob/main/static/img/qr-code.png" alt="WeChat Contact | 微信联系" height="280">
+</p>

package/bin/harnspec-rust.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * HarnSpec 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. Rust target/debug binary (for local development)
+ * 2. Rust target/release binary (for local development)
+ * 3. Platform-specific npm package (harnspec-darwin-x64, etc.)
+ * 4. Local binaries directory (fallback)
+ */
+
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { accessSync, openSync, readSync, closeSync } from 'fs';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Debug mode - enable with HARNSPEC_DEBUG=1
+const DEBUG = process.env.HARNSPEC_DEBUG === '1';
+const debug = (...args) => DEBUG && console.error('[harnspec debug]', ...args);
+
+// Platform detection mapping
+const PLATFORM_MAP = {
+  darwin: { x64: 'darwin-x64', arm64: 'darwin-arm64' },
+  linux: { x64: 'linux-x64' },
+  win32: { x64: 'windows-x64' }
+};
+
+const MACHO_MAGICS = new Set([
+  0xfeedface,
+  0xfeedfacf,
+  0xcefaedfe,
+  0xcffaedfe,
+  0xcafebabe,
+  0xbebafeca,
+]);
+
+function readHeaderBytes(filePath) {
+  const fd = openSync(filePath, 'r');
+  try {
+    const buffer = Buffer.alloc(4);
+    const bytesRead = readSync(fd, buffer, 0, 4, 0);
+    return bytesRead === 4 ? buffer : null;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function isValidBinaryHeader(filePath, platform) {
+  try {
+    const header = readHeaderBytes(filePath);
+    if (!header) return false;
+
+    if (platform === 'linux') {
+      return header[0] === 0x7f && header[1] === 0x45 && header[2] === 0x4c && header[3] === 0x46;
+    }
+
+    if (platform === 'win32') {
+      return header[0] === 0x4d && header[1] === 0x5a;
+    }
+
+    if (platform === 'darwin') {
+      const magicBE = header.readUInt32BE(0);
+      const magicLE = header.readUInt32LE(0);
+      return MACHO_MAGICS.has(magicBE) || MACHO_MAGICS.has(magicLE);
+    }
+
+    return false;
+  } catch (error) {
+    debug('Failed to read binary header:', error.message);
+    return false;
+  }
+}
+
+function isExecutableBinary(filePath, platform) {
+  if (!isValidBinaryHeader(filePath, platform)) {
+    debug('Invalid binary header:', filePath);
+    return false;
+  }
+  return true;
+}
+
+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), Windows (x64)');
+    process.exit(1);
+  }
+
+  const isWindows = platform === 'win32';
+  const binaryName = isWindows ? 'harnspec.exe' : 'harnspec';
+  const packageName = `@harnspec/cli-${platformKey}`;
+
+  debug('Binary info:', { platformKey, binaryName, packageName });
+
+  // Try rust/target/debug directory first (for local development with `pnpm build:rust`)
+  try {
+    const rustDebugPath = join(__dirname, '..', '..', '..', 'rust', 'target', 'debug', binaryName);
+    debug('Trying rust debug binary:', rustDebugPath);
+    accessSync(rustDebugPath);
+    if (isExecutableBinary(rustDebugPath, platform)) {
+      debug('Found rust debug binary:', rustDebugPath);
+      return rustDebugPath;
+    }
+    debug('Rust debug binary is invalid:', rustDebugPath);
+  } catch (e) {
+    debug('Rust debug binary not found:', e.message);
+  }
+
+  // Try rust/target/release directory (for local development with `pnpm build:rust:release`)
+  try {
+    const rustTargetPath = join(__dirname, '..', '..', '..', 'rust', 'target', 'release', binaryName);
+    debug('Trying rust release binary:', rustTargetPath);
+    accessSync(rustTargetPath);
+    if (isExecutableBinary(rustTargetPath, platform)) {
+      debug('Found rust release binary:', rustTargetPath);
+      return rustTargetPath;
+    }
+    debug('Rust release binary is invalid:', rustTargetPath);
+  } catch (e) {
+    debug('Rust release binary not found:', e.message);
+  }
+
+  // Try to resolve platform package
+  try {
+    const resolvedPath = require.resolve(`${packageName}/${binaryName}`);
+    if (isExecutableBinary(resolvedPath, platform)) {
+      debug('Found platform package binary:', resolvedPath);
+      return resolvedPath;
+    }
+    debug('Platform package binary is invalid:', resolvedPath);
+  } catch (e) {
+    debug('Platform package not found:', packageName, '-', e.message);
+  }
+
+  // Try local binaries directory (fallback)
+  try {
+    const localPath = join(__dirname, '..', 'binaries', platformKey, binaryName);
+    debug('Trying local binary:', localPath);
+    accessSync(localPath);
+    if (isExecutableBinary(localPath, platform)) {
+      debug('Found local binary:', localPath);
+      return localPath;
+    }
+    debug('Local binary is invalid:', localPath);
+  } catch (e) {
+    debug('Local binary not found:', e.message);
+  }
+
+  console.error(`Binary not found for ${platform}-${arch}`);
+  console.error(`Expected package: ${packageName}`);
+  console.error('');
+  console.error('Detected missing or corrupted binary.');
+  console.error('If you installed globally, reinstall to restore the binary:');
+  console.error('  npm uninstall -g harnspec && npm install -g harnspec');
+  console.error('');
+  console.error('If your npm config omits optional dependencies, enable them and reinstall.');
+  console.error('');
+  console.error('To install:');
+  console.error('  npm install -g harnspec');
+  console.error('');
+  console.error('If you installed globally, try:');
+  console.error('  npm uninstall -g harnspec && npm install -g harnspec');
+  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 harnspec:', err.message);
+  debug('Spawn error:', err);
+  process.exit(1);
+});

package/bin/harnspec.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * HarnSpec 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 './harnspec-rust.js';

package/binaries/darwin-arm64/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@harnspec/cli-darwin-arm64",
+  "version": "0.0.1",
+  "description": "HarnSpec CLI binary for macOS ARM64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "harnspec",
+  "files": [
+    "harnspec",
+    "postinstall.js"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/harnspec.git"
+  },
+  "license": "MIT"
+}

package/binaries/darwin-arm64/postinstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script to set execute permissions on the binary.
+ * npm doesn't preserve file permissions, so we need to set them after install.
+ */
+const { chmodSync } = require('fs');
+const { join } = require('path');
+
+const binaryPath = join(__dirname, 'harnspec');
+
+try {
+  chmodSync(binaryPath, 0o755);
+  console.log('✓ Set execute permissions on harnspec binary');
+} catch (err) {
+  console.error('Warning: Could not set execute permissions:', err.message);
+  // Don't fail the install
+}

package/binaries/darwin-x64/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@harnspec/cli-darwin-x64",
+  "version": "0.0.1",
+  "description": "HarnSpec CLI binary for macOS x64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "harnspec",
+  "files": [
+    "harnspec",
+    "postinstall.js"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/harnspec.git"
+  },
+  "license": "MIT"
+}

package/binaries/darwin-x64/postinstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script to set execute permissions on the binary.
+ * npm doesn't preserve file permissions, so we need to set them after install.
+ */
+const { chmodSync } = require('fs');
+const { join } = require('path');
+
+const binaryPath = join(__dirname, 'harnspec');
+
+try {
+  chmodSync(binaryPath, 0o755);
+  console.log('✓ Set execute permissions on harnspec binary');
+} catch (err) {
+  console.error('Warning: Could not set execute permissions:', err.message);
+  // Don't fail the install
+}

package/binaries/linux-x64/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@harnspec/cli-linux-x64",
+  "version": "0.0.1",
+  "description": "HarnSpec CLI binary for Linux x64",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "harnspec",
+  "files": [
+    "harnspec",
+    "postinstall.js"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/harnspec.git"
+  },
+  "license": "MIT"
+}

package/binaries/linux-x64/postinstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script to set execute permissions on the binary.
+ * npm doesn't preserve file permissions, so we need to set them after install.
+ */
+const { chmodSync } = require('fs');
+const { join } = require('path');
+
+const binaryPath = join(__dirname, 'harnspec');
+
+try {
+  chmodSync(binaryPath, 0o755);
+  console.log('✓ Set execute permissions on harnspec binary');
+} catch (err) {
+  console.error('Warning: Could not set execute permissions:', err.message);
+  // Don't fail the install
+}

package/binaries/windows-x64/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@harnspec/cli-windows-x64",
+  "version": "0.0.1",
+  "description": "HarnSpec CLI binary for Windows x64",
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "harnspec.exe",
+  "files": [
+    "harnspec.exe",
+    "postinstall.js"
+  ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codervisor/harnspec.git"
+  },
+  "license": "MIT"
+}

package/binaries/windows-x64/postinstall.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script - no-op on Windows (permissions not needed).
+ * This file exists for consistency across all platform packages.
+ */
+console.log('✓ harnspec.exe ready');

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@harnspec/cli",
+  "version": "0.0.1",
+  "description": "Specification-driven development made simple",
+  "type": "module",
+  "bin": {
+    "harnspec": "./bin/harnspec.js"
+  },
+  "scripts": {
+    "typecheck": "echo 'No TypeScript source to check'"
+  },
+  "dependencies": {
+    "@harnspec/http-server": "0.0.1",
+    "@harnspec/ui": "0.0.1"
+  },
+  "keywords": [
+    "spec",
+    "specification",
+    "documentation",
+    "ai",
+    "agent",
+    "sdd"
+  ],
+  "author": "Marvin Zhang",
+  "license": "MIT AND Commons-Clause-1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/harnspec/harnspec.git"
+  },
+  "homepage": "https://harnspec.github.io",
+  "bugs": {
+    "url": "https://github.com/harnspec/harnspec/issues"
+  },
+  "files": [
+    "bin/",
+    "binaries/",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "optionalDependencies": {
+    "@harnspec/cli-darwin-x64": "0.0.1",
+    "@harnspec/cli-darwin-arm64": "0.0.1",
+    "@harnspec/cli-linux-x64": "0.0.1",
+    "@harnspec/cli-windows-x64": "0.0.1"
+  }
+}

package/templates/detailed/AGENTS-minimal.md

@@ -0,0 +1,9 @@
+# {project_name}
+
+## Project-Specific Rules
+
+Add your project-specific conventions here. For example:
+- Code style preferences
+- Naming conventions  
+- Team workflows
+- Custom tooling