@harnspec/ui 0.0.1

package/README.md

@@ -0,0 +1,144 @@
+# @harnspec/ui
+
+Primary Vite-based Single Page Application for HarnSpec spec management (web + desktop).
+
+## Overview
+
+This is a lightweight, fast SPA built with Vite. It provides a modern UI for viewing and managing HarnSpec specifications.
+
+**Unified Server Architecture**: The UI is served by the Rust HTTP server on port 3000. When you run `npx @harnspec/ui`, it starts a single process that serves both the static UI files and the API endpoints. This provides:
+- Single port (default: 3000)
+- Same-origin API requests (no CORS needed)
+- Better performance (no Node.js HTTP server overhead)
+- Simpler deployment
+
+## Usage
+
+```bash
+# Start the unified HTTP server
+npx @harnspec/ui
+
+# Custom port and host
+npx @harnspec/ui --port 3001 --host 0.0.0.0
+
+# Auto-add project
+npx @harnspec/ui --project /path/to/specs
+
+# Read-only mode
+npx @harnspec/ui --readonly
+
+# All CLI arguments are passed to the Rust HTTP server
+npx @harnspec/ui --help
+```
+
+Visit `http://localhost:3000` to access the UI.
+
+## Architecture
+
+- **Build Tool**: Vite 7 (fast HMR, optimized builds)
+- **Framework**: React 19 + TypeScript 5
+- **Routing**: React Router 7 (client-side)
+- **Components**: Shared UI library exported from `@harnspec/ui`
+- **Styling**: Tailwind CSS 3
+- **Backend**: Same-origin API served by the Rust HTTP server at `http://localhost:3000`
+
+## Features
+
+- **Specs Page**: Browse all specifications with filtering
+- **Spec Detail**: View individual spec content and metadata
+- **Stats Page**: Project statistics and metrics
+- **Dependencies Page**: Dependency graph visualization
+- **Responsive**: Works on desktop and mobile
+- **Dark Mode**: Automatic dark mode support
+
+## Development
+
+### Development with HMR (Recommended)
+
+For fast UI development with Hot Module Replacement:
+
+```bash
+# Terminal 1: Start Rust HTTP server (API on port 3000)
+cd rust/harnspec-http
+cargo run
+
+# Terminal 2: Start Vite dev server (UI on port 5173)
+cd packages/ui
+pnpm dev
+```
+
+Access the UI at `http://localhost:5173`. Vite's proxy automatically forwards API requests to port 3000.
+
+### Production-like Development
+
+To test the unified server locally:
+
+```bash
+# Build UI
+pnpm build
+
+# Start unified server (serves UI + API on port 3000)
+cd ../../rust/harnspec-http
+cargo run
+```
+
+Access at `http://localhost:3000`.
+
+### Other Commands
+
+```bash
+# Type check
+pnpm typecheck
+
+# Lint
+pnpm lint
+
+# Preview production build (Vite preview server)
+pnpm preview
+```
+
+## Configuration
+
+By default the UI uses same-origin API calls (relative `/api/...`).
+
+### Dev (recommended, “single origin” in the browser)
+
+Run the Rust HTTP server (API) on a port (default `3000`), run Vite on `5173`, and let Vite proxy `/api`.
+
+If you need to change where the dev proxy points, use a server-only env var:
+
+```bash
+# .env.local (used by Vite dev server only)
+HARNSPEC_API_URL=http://localhost:3000
+```
+
+With this setup the browser still talks to a single origin (the Vite origin) because all API calls are made to `/api`.
+
+### Deploy UI separately (cross-origin)
+
+If you are serving the UI from a different origin than the Rust server, you can set an explicit API base URL:
+
+```bash
+# .env.local
+VITE_API_URL=http://localhost:3000
+```
+
+If you want the Rust HTTP server to serve both UI + API on a single port, leave `VITE_API_URL` unset.
+
+## Build Output
+
+Production builds are output to `dist/`:
+- Small bundle size (~300KB gzipped)
+- Optimized assets with code splitting
+- Static files ready for deployment
+
+## Deployment
+
+The built static files can be:
+1. Served by the Rust HTTP server
+2. Deployed to any static hosting (Vercel, Netlify, etc.)
+3. Bundled in the Tauri desktop app
+
+## License
+
+MIT

package/bin/harnspec-ui.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+/**
+ * HarnSpec UI Launcher
+ *
+ * This script starts the Rust HTTP server and serves the embedded UI
+ * from the same process and port.
+ */
+
+import { spawn, spawnSync } from 'child_process';
+import { existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const DIST_DIR = join(__dirname, '..', 'dist');
+
+// Check if dist exists
+if (!existsSync(DIST_DIR)) {
+  console.error('Error: UI build not found!');
+  console.error('Expected directory:', DIST_DIR);
+  console.error('');
+  console.error('The @harnspec/ui package must be built before running.');
+  console.error('This is typically done during the npm publish process.');
+  process.exit(1);
+}
+
+/**
+ * Try to resolve @harnspec/http-server from multiple locations
+ */
+function resolveHttpServer() {
+  // Try local resolution first
+  try {
+    return require.resolve('@harnspec/http-server/bin/harnspec-http.js');
+  } catch {
+    // Continue to try other locations
+  }
+  
+  // Try resolving from global npm modules
+  try {
+    const npmRoot = spawnSync('npm', ['root', '-g'], { 
+      encoding: 'utf8', 
+      shell: true 
+    });
+    if (npmRoot.status === 0 && npmRoot.stdout) {
+      const globalPath = join(
+        npmRoot.stdout.trim(), 
+        '@harnspec', 
+        'http-server', 
+        'bin', 
+        'harnspec-http.js'
+      );
+      if (existsSync(globalPath)) {
+        return globalPath;
+      }
+    }
+  } catch {
+    // Continue
+  }
+  
+  return null;
+}
+
+/**
+ * Auto-install @harnspec/http-server globally using npm
+ */
+function installHttpServer() {
+  console.log('📦 @harnspec/http-server not found, installing globally...');
+  console.log('');
+  
+  // Get the version of @harnspec/ui to match
+  const uiPkg = JSON.parse(
+    require('fs').readFileSync(join(__dirname, '..', 'package.json'), 'utf8')
+  );
+  const version = uiPkg.version;
+  const packageSpec = version.includes('dev') 
+    ? '@harnspec/http-server@dev' 
+    : `@harnspec/http-server@^${version}`;
+  
+  // Install globally so it persists across npx runs
+  const result = spawnSync('npm', ['install', '-g', packageSpec], {
+    stdio: 'inherit',
+    shell: true
+  });
+  
+  if (result.status !== 0) {
+    console.error('');
+    console.error('Failed to auto-install @harnspec/http-server');
+    console.error('');
+    console.error('Please install manually:');
+    console.error('  npm install -g @harnspec/http-server');
+    process.exit(1);
+  }
+  
+  console.log('');
+  console.log('✅ @harnspec/http-server installed globally');
+  console.log('');
+}
+
+// Try to resolve http-server, install if needed
+let httpServerPath = resolveHttpServer();
+if (!httpServerPath) {
+  installHttpServer();
+  httpServerPath = resolveHttpServer();
+  
+  if (!httpServerPath) {
+    console.error('Error: Failed to resolve @harnspec/http-server after installation');
+    console.error('Please try installing manually: npm install -g @harnspec/http-server');
+    process.exit(1);
+  }
+}
+
+// Start the Rust HTTP server (serves API + UI)
+let httpServerProcess;
+
+console.log('🚀 Starting HarnSpec HTTP server...');
+const args = process.argv.slice(2);
+
+// Validate httpServerPath before spawning
+if (!httpServerPath || !existsSync(httpServerPath)) {
+  console.error('Error: HTTP server script not found at:', httpServerPath);
+  console.error('');
+  console.error('This usually means @harnspec/http-server was not installed correctly.');
+  console.error('');
+  console.error('Try reinstalling:');
+  console.error('  npm install -g @harnspec/http-server@latest');
+  process.exit(1);
+}
+
+// Use process.execPath to ensure Node.js is found correctly on all platforms
+httpServerProcess = spawn(process.execPath, [httpServerPath, ...args], {
+  stdio: 'inherit',
+  env: { ...process.env, HARNSPEC_UI_DIST: DIST_DIR }
+});
+
+httpServerProcess.on('error', (err) => {
+  console.error('Failed to start HTTP server:', err.message);
+  console.error('');
+  console.error('This usually means the HTTP server binary could not be found.');
+  console.error('Error code:', err.code);
+  console.error('');
+  console.error('Try reinstalling:');
+  console.error('  npm install -g @harnspec/http-server@latest');
+  process.exit(1);
+});
+
+// Wait a moment for the HTTP server to start
+await new Promise(resolve => setTimeout(resolve, 1000));
+
+// Cleanup on exit
+process.on('SIGINT', () => {
+  console.log('\n\nShutting down...');
+  if (httpServerProcess) {
+    httpServerProcess.kill();
+  }
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  if (httpServerProcess) {
+    httpServerProcess.kill();
+  }
+  process.exit(0);
+});