@harnspec/http-server 0.0.1

package/README.md

@@ -0,0 +1,127 @@
+# @harnspec/http-server
+
+High-performance Rust HTTP server for HarnSpec UI.
+
+## Features
+
+- **Fast**: Built with Rust and Axum web framework
+- **Lightweight**: <30MB bundle size
+- **Multi-project**: Support for multiple project workspaces
+- **RESTful API**: JSON API for all spec operations
+- **Unified UI + API**: Serves the Vite UI and `/api/*` from one server
+- **CORS-enabled**: Configurable cross-origin resource sharing
+- **Detailed Logging**: Request tracing with error context for development
+
+## Installation
+
+```bash
+npm install @harnspec/http-server
+```
+
+## Usage
+
+### As a standalone server
+
+```bash
+npx harnspec-http
+```
+
+Options:
+
+- `--host <host>` - Server host (default: 127.0.0.1)
+- `--port <port>` - Server port (default: 3000)
+- `-v, --verbose` - Enable verbose (debug) logging
+- `--log-level <level>` - Log level: trace, debug, info, warn, error (default: info)
+- `--help` - Show help message
+
+### Development Mode
+
+For improved developer experience, set environment variables to enable detailed logging:
+
+```bash
+# Enable debug mode with verbose logging
+HARNSPEC_DEBUG=1 HARNSPEC_DEV_MODE=1 npx harnspec-http -v
+
+# Or use RUST_LOG for fine-grained control
+RUST_LOG=harnspec_http=debug,tower_http=debug npx harnspec-http
+```
+
+In dev mode, the server provides:
+
+- **Request tracing**: Each request gets a unique ID for correlation
+- **Error context**: Full error details with status codes and stack context
+- **Latency tracking**: Response timing in milliseconds
+- **File/line info**: Source location for debugging
+
+### Log Levels
+
+| Level   | When to use | What you see                        |
+| ------- | ----------- | ----------------------------------- |
+| `error` | Production  | Only errors/failures                |
+| `warn`  | Production  | Warnings + errors                   |
+| `info`  | Default     | Requests + responses + errors       |
+| `debug` | Development | Detailed request/response info      |
+| `trace` | Debugging   | Everything including internal calls |
+
+### As a library
+
+```javascript
+import { spawn } from 'child_process';
+
+const server = spawn('harnspec-http', ['--port', '3000']);
+```
+
+## Configuration
+
+The server reads configuration from `~/.harnspec/config.json`:
+
+```json
+{
+  "server": {
+    "host": "127.0.0.1",
+    "port": 3000,
+    "cors": {
+      "enabled": false,
+      "origins": [
+        "http://localhost:5173",
+        "http://localhost:3000"
+      ]
+    }
+  }
+}
+```
+
+## API Endpoints
+
+### Projects
+
+- `GET /api/projects` - List all projects
+- `POST /api/projects` - Add new project
+- `GET /api/projects/:id` - Get project details
+- `PATCH /api/projects/:id` - Update project
+- `DELETE /api/projects/:id` - Remove project
+- `POST /api/projects/:id/switch` - Switch to project
+
+### Specs
+
+- `GET /api/specs` - List specs (with filters)
+- `GET /api/specs/:spec` - Get spec detail
+- `PATCH /api/specs/:spec/metadata` - Update spec metadata
+- `POST /api/search` - Search specs
+- `GET /api/stats` - Project statistics
+- `GET /api/deps/:spec` - Dependency graph
+- `GET /api/validate` - Validate all specs
+
+### Health
+
+- `GET /health` - Health check
+
+## Platform Support
+
+- macOS (x64, arm64)
+- Linux (x64, arm64)
+- Windows (x64)
+
+## License
+
+MIT

package/bin/harnspec-http.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * HarnSpec HTTP Server Binary Wrapper
+ * 
+ * This script detects the current platform and architecture,
+ * then spawns the appropriate Rust HTTP server binary.
+ * 
+ * The wrapper looks for binaries in the following locations:
+ * 1. Platform-specific npm package (@harnspec/http-darwin-x64, etc.)
+ * 2. Local binaries directory (for development)
+ * 3. Rust target directory (for local 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 HARNSPEC_DEBUG=1
+const DEBUG = process.env.HARNSPEC_DEBUG === '1';
+const DEV_MODE = process.env.HARNSPEC_DEV_MODE === '1';
+const debug = (...args) => DEBUG && console.error('[harnspec-http debug]', ...args);
+
+// Platform detection mapping
+const PLATFORM_MAP = {
+  darwin: { x64: 'darwin-x64', arm64: 'darwin-arm64' },
+  linux: { x64: 'linux-x64' },
+  win32: { x64: 'windows-x64' }
+};
+
+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-http.exe' : 'harnspec-http';
+  const packageName = `@harnspec/http-${platformKey}`;
+
+  debug('Binary info:', { platformKey, binaryName, packageName });
+
+  // In dev mode, prefer rust target directory first for faster iteration
+  if (DEV_MODE) {
+    // Try rust/target/debug directory first (faster builds)
+    try {
+      const rustDebugPath = join(__dirname, '..', '..', '..', 'rust', 'target', 'debug', binaryName);
+      debug('Trying rust debug binary:', rustDebugPath);
+      accessSync(rustDebugPath);
+      debug('Found rust debug binary:', rustDebugPath);
+      return rustDebugPath;
+    } catch (e) {
+      debug('Rust debug binary not found:', e.message);
+    }
+
+    // Try rust/target/release directory
+    try {
+      const rustReleasePath = join(__dirname, '..', '..', '..', 'rust', 'target', 'release', binaryName);
+      debug('Trying rust release binary:', rustReleasePath);
+      accessSync(rustReleasePath);
+      debug('Found rust release binary:', rustReleasePath);
+      return rustReleasePath;
+    } catch (e) {
+      debug('Rust release binary not found:', e.message);
+    }
+  }
+
+  // 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 (fallback 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 @harnspec/http-server');
+  console.error('');
+  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-http:', err.message);
+  debug('Spawn error:', err);
+  process.exit(1);
+});

package/binaries/darwin-arm64/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@harnspec/http-darwin-arm64",
+  "version": "0.0.1",
+  "description": "HarnSpec HTTP Server binary for macOS ARM64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "arm64"
+  ],
+  "main": "harnspec-http",
+  "files": [
+    "harnspec-http",
+    "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-http');
+
+try {
+  chmodSync(binaryPath, 0o755);
+  console.log('✓ Set execute permissions on harnspec-http 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/http-darwin-x64",
+  "version": "0.0.1",
+  "description": "HarnSpec HTTP Server binary for macOS x64",
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "harnspec-http",
+  "files": [
+    "harnspec-http",
+    "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-http');
+
+try {
+  chmodSync(binaryPath, 0o755);
+  console.log('✓ Set execute permissions on harnspec-http 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/http-linux-x64",
+  "version": "0.0.1",
+  "description": "HarnSpec HTTP Server binary for Linux x64",
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "harnspec-http",
+  "files": [
+    "harnspec-http",
+    "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-http');
+
+try {
+  chmodSync(binaryPath, 0o755);
+  console.log('✓ Set execute permissions on harnspec-http 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/http-windows-x64",
+  "version": "0.0.1",
+  "description": "HarnSpec HTTP Server binary for Windows x64",
+  "os": [
+    "win32"
+  ],
+  "cpu": [
+    "x64"
+  ],
+  "main": "harnspec-http.exe",
+  "files": [
+    "harnspec-http.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-http.exe ready');

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@harnspec/http-server",
+  "version": "0.0.1",
+  "description": "Rust HTTP server for HarnSpec UI",
+  "type": "module",
+  "bin": {
+    "harnspec-http": "./bin/harnspec-http.js"
+  },
+  "scripts": {
+    "dev": "RUST_BACKTRACE=1 HARNSPEC_DEBUG=1 HARNSPEC_DEV_MODE=1 nodemon --watch ./binaries --ignore '*.js' --ignore '*.json' --delay 1 --exec 'node ./bin/harnspec-http.js -v --no-open'",
+    "typecheck": "echo 'No TypeScript source to check'"
+  },
+  "keywords": [
+    "harnspec",
+    "http",
+    "server",
+    "api",
+    "rust"
+  ],
+  "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/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "nodemon": "^3.1.11"
+  },
+  "optionalDependencies": {
+    "@harnspec/http-darwin-x64": "0.0.1",
+    "@harnspec/http-darwin-arm64": "0.0.1",
+    "@harnspec/http-linux-x64": "0.0.1",
+    "@harnspec/http-windows-x64": "0.0.1"
+  }
+}