karajan-code 2.19.0 → 2.19.1

package/README.md

@@ -345,6 +345,8 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.19.1 released** — Patch. **APPLICATION BLOCKER fix** for the HU Board: every fresh `npm install -g karajan-code` since the HU Board feature shipped was producing tarballs without the `packages/hu-board/` directory (the `files` array in `package.json` did not include it), and even when the user copied that directory manually, the board crashed at startup with `Cannot find package 'helmet' imported from .../packages/hu-board/src/server.js` because its five dependencies (`helmet`, `chokidar`, `better-sqlite3`, `express`, `express-rate-limit`) were declared in `packages/hu-board/package.json` but missing from the root `dependencies`. PR #791 adds `packages/hu-board/{src,public,package.json}` to `files`, adds the five deps at root at the exact same versions so `npm dedupe` collapses to one copy resolvable by upward traversal, and regenerates `package-lock.json`. Verified end-to-end: `npm pack --dry-run` now ships 12 board files; `node packages/hu-board/src/server.js` boots cleanly. Also internal: 38 direct `os.homedir()` callers routed through the unified resolver (PR #790, `KARAJAN_HOME` now redirects every component) and 5 inline constructions of `~/.karajan/hu-board-runs/` unified under one helper (PR #789). Reported by [@aitormf](https://github.com/aitormf). **If you tried v2.19.0 and `kj board start` failed, upgrade to v2.19.1.**
+>
 > **v2.19.0 released** — Minor. Consolidates the HOME-level state of Karajan into a single root: **`~/.karajan/`**. Previously `~/.kj/` held plans, hibernated standby state, run-registry entries and worktrees, while `~/.karajan/` held sessions, hu-stories, config and the rest — no ADR justified the split and four divergent `getKjHome()` implementations had drifted. Three internal PRs land the change without breaking anyone: PR #781 unifies the resolver and introduces **`KARAJAN_HOME`** as the canonical env var (with `KJ_HOME` honoured + one-shot deprecation warning); PR #782 ships an idempotent **auto-migrator** that runs once on the next `kj` invocation — tarball backup at `~/.karajan/backup/kj-pre-migration-<ISO>.tar.gz` BEFORE moving, marker file `~/.karajan/.kj-migrated.json` prevents re-runs, cross-device safe (`rename` → `cp + rm` on `EXDEV`); PR #783 flips every default to `~/.karajan/` and adds a `legacy-kj-home` check to `kj doctor`. The HU Board reads BOTH locations until the migrator fires, so users who start the board first never see "missing plans". Restore is one `tar -xzf ~/.karajan/backup/kj-pre-migration-<ts>.tar.gz -C ~` away. Safe upgrade from 2.18.x.
 >
 > **v2.18.1 released** — Patch. Six user-feedback follow-ups to v2.18.0: **`kj-tail` after `kj resume`** (#772, was silent because `resume.js` skipped `withCliRunLog`); **standby waits in-process instead of exiting on a short cooldown** (#773, kj stays alive for waits ≤ 12 h and retries on its own; Ctrl+C during the wait prints `kj standby resume <id>`); **closed KJC-BUG-0040 — SEA linux binaries** (#774, was a race between `gh release create` and softprops, not `better-sqlite3` as the memory said — 60 s poll fix + `make_latest:false`); **stack bias — Python repos no longer get vitest** (#775 + #776 + #777, `detectProjectStack` finally cabled into the coder prompt, the HU auto-generator templates by language, and the synthesizer + `auto-hu-batch` take the stack from the filesystem). 4 971/4 971 tests passing across 416 files. Safe upgrade from 2.18.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.19.0",
+  "version": "2.19.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -37,6 +37,9 @@
     "bin/",
     "templates/",
     "scripts/",
+    "packages/hu-board/src/",
+    "packages/hu-board/public/",
+    "packages/hu-board/package.json",
     "docs/karajan-code-logo-small.png",
     "docs/README.es.md",
     "LICENSE",
@@ -67,8 +70,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^11.0.0",
+    "chokidar": "^4.0.0",
     "commander": "^14.0.0",
     "execa": "^9.6.0",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.5.0",
+    "helmet": "^8.1.0",
     "js-yaml": "^4.1.0",
     "knip": "^6.14.1",
     "madge": "^8.0.0",

package/packages/hu-board/README.md

@@ -0,0 +1,69 @@
+# Karajan HU Board
+
+A web dashboard that visualizes all HU (User Story) stories managed by Karajan Code. Reads from `~/.karajan/hu-stories/` and `~/.karajan/sessions/`, groups by project, and provides a read-only kanban board with quality metrics and session timelines.
+
+## Quick Start
+
+### Without Docker
+
+```bash
+cd packages/hu-board
+npm install
+npm start
+# Open http://localhost:4000
+```
+
+### With Docker
+
+```bash
+cd packages/hu-board
+docker compose up -d
+# Open http://localhost:4000
+```
+
+### Development (auto-reload)
+
+```bash
+npm run dev
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `4000` | Server port (auto-detects next available if busy) |
+| `KJ_HOME` | `~/.karajan` | Path to Karajan data directory |
+
+You can also use `--port` flag:
+
+```bash
+node src/server.js --port 5000
+```
+
+## Architecture
+
+- **Backend**: Node.js + Express serving REST API + static files
+- **Frontend**: Vanilla JS single-page app with hash-based routing
+- **Database**: SQLite (via `better-sqlite3`) at `$KJ_HOME/hu-board.db`
+- **Sync**: Chokidar watches JSON files and syncs to SQLite in real-time
+
+The SQLite database is a read index over the JSON source files. If deleted, it rebuilds automatically on next startup.
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/dashboard` | Global statistics |
+| GET | `/api/projects` | List all projects with counts |
+| GET | `/api/projects/:id` | Project detail |
+| GET | `/api/projects/:id/stories` | Stories for a project |
+| GET | `/api/stories/:id` | Story detail with quality, AC, context requests |
+| GET | `/api/projects/:id/sessions` | Sessions for a project |
+| GET | `/api/sessions` | All sessions |
+| GET | `/api/sessions/:id` | Session detail with timeline |
+
+## Views
+
+1. **Dashboard** - Global stats cards + project overview grid
+2. **Board** - Kanban columns (Pending / Needs Context / Certified / Done)
+3. **Sessions** - Timeline of Karajan pipeline sessions with stages and duration

package/packages/hu-board/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@karajan/hu-board",
+  "version": "1.0.0",
+  "description": "HU Story Board dashboard for Karajan Code",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "better-sqlite3": "^11.0.0",
+    "chokidar": "^4.0.0",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.5.0",
+    "helmet": "^8.1.0"
+  },
+  "devDependencies": {
+    "supertest": "^7.1.0",
+    "vitest": "^4.0.0"
+  }
+}