@lbroth/rothunter 1.0.0-rc.1

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@lbroth/rothunter",
+  "version": "1.0.0-rc.1",
+  "description": "Self-hosted code-hygiene engine for TypeScript / JavaScript codebases. Deterministic detectors + local LLM verdicts + dashboard.",
+  "license": "MIT",
+  "author": "lBroth",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lBroth/rothunter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lBroth/rothunter/issues"
+  },
+  "homepage": "https://github.com/lBroth/rothunter#readme",
+  "keywords": [
+    "static-analysis",
+    "code-quality",
+    "typescript",
+    "race-condition",
+    "dead-code",
+    "duplicate-detection",
+    "monorepo",
+    "llm",
+    "self-hosted"
+  ],
+  "type": "module",
+  "main": "dist/rothunter.js",
+  "types": "dist/rothunter.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/rothunter.d.ts",
+      "default": "./dist/rothunter.js"
+    }
+  },
+  "files": [
+    "dist",
+    "scripts/start-llm.mjs",
+    "README.md",
+    "LICENSE",
+    "logo.png"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:ui": "cd src/ui && npm install && npm run build",
+    "prepublishOnly": "npm run build",
+    "setup": "npm install && cd src/ui && npm install",
+    "server": "tsx watch src/server/index.ts",
+    "server:lan": "ROTHUNTER_HOST=0.0.0.0 tsx watch src/server/index.ts",
+    "ui": "cd src/ui && npm run dev",
+    "llm": "node scripts/start-llm.mjs",
+    "dev": "concurrently -k -n SERVER,UI -c blue,magenta \"npm:server\" \"npm:ui\"",
+    "dev:full": "concurrently -k -n LLM,SERVER,UI -c green,blue,magenta \"npm:llm\" \"npm:server\" \"npm:ui\"",
+    "dev:lan": "concurrently -k -n SERVER,UI -c blue,magenta \"npm:server:lan\" \"npm:ui\"",
+    "dev:full:lan": "concurrently -k -n LLM,SERVER,UI -c green,blue,magenta \"npm:llm\" \"npm:server:lan\" \"npm:ui\"",
+    "docker": "docker compose -f src/docker/docker-compose.yml up --build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "depcheck": "depcheck",
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest"
+  },
+  "dependencies": {
+    "@fastify/static": "^9.1.3",
+    "fastify": "^5.8.5",
+    "ignore": "^7.0.5",
+    "pino": "^10.3.1",
+    "ts-morph": "^28.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@jest/globals": "^30.4.1",
+    "@resvg/resvg-js": "^2.6.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.0",
+    "concurrently": "^9.2.1",
+    "depcheck": "^1.4.7",
+    "eslint": "^10.4.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.6.0",
+    "jest": "^30.4.2",
+    "prettier": "^3.8.3",
+    "ts-jest": "^29.4.10",
+    "tsx": "^4.22.3",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.4"
+  }
+}

package/scripts/start-llm.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// Launch the LLM sidecar for the dev loop.
+//
+// Strategy — auto-detect the fastest backend available on this host:
+//
+//   1. `llama-server` on PATH → run native llama.cpp (uses Metal on
+//      macOS, CUDA / Vulkan on Linux when the binary was built with
+//      GPU support).
+//   2. Docker Desktop available → fall back to the docker-compose
+//      `rothunter-llm` service. Slower on macOS (no Metal in the
+//      Linux VM) but works on any platform with Docker.
+//
+// Set ROTHUNTER_LLM_BACKEND=llamacpp|docker to force a specific
+// backend; otherwise we pick the first available from the list above.
+//
+// The script blocks until its child exits — `npm run dev:full` runs it
+// alongside the server + UI via `concurrently -k` so killing one
+// tears the whole stack down.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = resolve(fileURLToPath(import.meta.url), '..', '..');
+
+/**
+ * Reject env values that would let a hostile environment inject extra
+ * llama-server flags via the `spawn(..., [args])` argv. `spawn` does
+ * not invoke a shell, so true shell injection is already blocked, but
+ * a value starting with `-` would still be interpreted as a flag
+ * (e.g. setting `ROTHUNTER_LLM_PORT='--alias --rpc 0.0.0.0:5000'`).
+ * Tight allow-lists per env: model repo / file paths, integer port,
+ * IPv4-ish host.
+ */
+function requireEnv(name, fallback, pattern) {
+  const v = process.env[name] ?? fallback;
+  if (!pattern.test(v)) {
+    console.error(`[llm] refusing to launch — env ${name}=${JSON.stringify(v)} does not match ${pattern}`);
+    process.exit(1);
+  }
+  return v;
+}
+const MODEL_LLAMACPP_REPO = requireEnv(
+  'ROTHUNTER_LLM_MODEL',
+  'bartowski/Qwen2.5-Coder-14B-Instruct-GGUF',
+  /^[A-Za-z0-9._\-/]+$/,
+);
+const MODEL_LLAMACPP_FILE = requireEnv(
+  'ROTHUNTER_LLM_MODEL_FILE',
+  'Qwen2.5-Coder-14B-Instruct-Q4_K_M.gguf',
+  /^[A-Za-z0-9._\-/]+$/,
+);
+const PORT = requireEnv('ROTHUNTER_LLM_PORT', '8080', /^\d{1,5}$/);
+// Loopback by default — the llama-server endpoint has no auth, so
+// `--host 0.0.0.0` would let anyone on the LAN use the GPU and read
+// the prompts we send. Override with `ROTHUNTER_LLM_HOST=0.0.0.0`
+// only when you intentionally want LAN access (and ideally only
+// behind a reverse proxy / VPN).
+const HOST = requireEnv('ROTHUNTER_LLM_HOST', '127.0.0.1', /^[0-9.:a-fA-F]+$/);
+
+function has(cmd) {
+  return spawnSync('which', [cmd], { stdio: 'ignore' }).status === 0;
+}
+
+function hasDocker() {
+  return spawnSync('docker', ['version'], { stdio: 'ignore' }).status === 0;
+}
+
+function pickBackend() {
+  const forced = process.env.ROTHUNTER_LLM_BACKEND;
+  if (forced) return forced;
+  if (has('llama-server')) return 'llamacpp';
+  if (hasDocker()) return 'docker';
+  return null;
+}
+
+/**
+ * Marker file the server reads to know which model + port this script
+ * launched. Lets the server pick the right model id without the
+ * operator having to mirror env vars between processes.
+ */
+const MARKER_DIR = join(homedir(), '.rothunter');
+const MARKER_PATH = join(MARKER_DIR, 'llm-active.json');
+
+function writeMarker(payload) {
+  try {
+    mkdirSync(MARKER_DIR, { recursive: true });
+    writeFileSync(MARKER_PATH, JSON.stringify(payload, null, 2));
+  } catch (err) {
+    console.warn(`[llm] failed to write marker file: ${err.message}`);
+  }
+}
+
+function clearMarker() {
+  try { unlinkSync(MARKER_PATH); } catch { /* already gone */ }
+}
+
+function run(cmd, args, marker) {
+  console.log(`[llm] launching: ${cmd} ${args.join(' ')}`);
+  if (marker) writeMarker(marker);
+  const child = spawn(cmd, args, { stdio: 'inherit' });
+  child.on('exit', (code) => {
+    clearMarker();
+    process.exit(code ?? 0);
+  });
+  const forward = (sig) => () => {
+    clearMarker();
+    child.kill(sig);
+  };
+  process.on('SIGINT', forward('SIGINT'));
+  process.on('SIGTERM', forward('SIGTERM'));
+}
+
+const backend = pickBackend();
+switch (backend) {
+  case 'llamacpp':
+    console.log(`[llm] native llama-server — ${MODEL_LLAMACPP_REPO}`);
+    run(
+      'llama-server',
+      [
+        '--hf-repo', MODEL_LLAMACPP_REPO,
+        '--hf-file', MODEL_LLAMACPP_FILE,
+        '--port', PORT,
+        '--host', HOST,
+        '--jinja',
+        '-c', '8192',
+        '-n', '256',
+      ],
+      { backend: 'llamacpp', model: MODEL_LLAMACPP_REPO, port: PORT },
+    );
+    break;
+  case 'docker': {
+    const compose = resolve(REPO_ROOT, 'src/docker/docker-compose.yml');
+    if (!existsSync(compose)) {
+      console.error(`[llm] docker-compose file not found at ${compose}`);
+      process.exit(1);
+    }
+    console.log('[llm] docker fallback — slower on macOS (no Metal in the VM)');
+    run(
+      'docker',
+      ['compose', '-f', compose, 'up', 'rothunter-llm'],
+      { backend: 'docker', model: MODEL_LLAMACPP_REPO, port: PORT },
+    );
+    break;
+  }
+  default:
+    console.error(
+      [
+        '[llm] no LLM backend available. Install ONE of:',
+        '  • brew install llama.cpp      (native llama-server, recommended)',
+        '  • Docker Desktop              (docker-compose sidecar fallback)',
+        '',
+        'Or set ROTHUNTER_LLM_BASE_URL to an existing OpenAI-compatible',
+        'endpoint (vLLM, OpenRouter, LM Studio, …) and start the server /',
+        'UI directly with `npm run server` and `npm run ui`.',
+      ].join('\n'),
+    );
+    process.exit(1);
+}