@karajan-family/code 4.21.0

package/packages/ai-trash/src/hook.js

@@ -0,0 +1,137 @@
+// Claude Code PreToolUse hook (KJC-TSK-0390 commit 2). Reads the JSON
+// payload from stdin, classifies the Bash command, snapshots target
+// paths, prints the decision JSON on stdout. Fail-closed: if snapshot
+// throws, deny the op so Claude never destroys without a recovery copy.
+
+import { promises as fs } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import process from "node:process";
+import { classifyCommand } from "./destructive-parser.js";
+import { loadManifest, saveManifest } from "./manifest.js";
+import { snapshotFile } from "./snapshot.js";
+import { snapshotGitBundle } from "./git-snapshot.js";
+import { ensureSecureDir, assertOwnedByCurrentUser } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+function reply(decision, reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: decision,
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+async function readJsonStdin(stdin) {
+  let raw = "";
+  for await (const chunk of stdin) raw += chunk;
+  if (!raw.trim()) return null;
+  return JSON.parse(raw);
+}
+
+async function snapshotExistingPaths(root, paths, cwd, command) {
+  const snapshots = [];
+  for (const p of paths) {
+    const abs = isAbsolute(p) ? p : resolve(cwd ?? process.cwd(), p);
+    try {
+      const stat = await fs.lstat(abs);
+      if (stat.isDirectory()) continue;
+      const entry = await snapshotFile(root, abs, { command, origin: "claude-code" });
+      snapshots.push(entry);
+    } catch (err) {
+      if (err.code === "ENOENT") continue;
+      throw err;
+    }
+  }
+  return snapshots;
+}
+
+async function snapshotGitRepo(root, cwd, command, kind) {
+  if (!cwd) return { snapshots: [], skipped: "no cwd" };
+  try {
+    const entry = await snapshotGitBundle(root, cwd, {
+      command,
+      origin: "claude-code",
+      label: kind,
+    });
+    return { snapshots: [entry], skipped: null };
+  } catch (err) {
+    if (/not a git repo/.test(err.message)) {
+      return { snapshots: [], skipped: "cwd is not a git repo" };
+    }
+    throw err;
+  }
+}
+
+export async function handleHookPayload(payload, { root, stdin }) {
+  const data = payload ?? (await readJsonStdin(stdin));
+  if (!data) return reply("allow", "ai-trash: empty payload, deferring");
+  if (data.hook_event_name !== "PreToolUse") {
+    return reply("allow", `ai-trash: not PreToolUse (${data.hook_event_name})`);
+  }
+  if (data.tool_name !== "Bash")
+    return reply("allow", `ai-trash: tool '${data.tool_name}' not handled`);
+
+  const command = data.tool_input?.command;
+  if (typeof command !== "string" || !command.trim()) {
+    return reply("allow", "ai-trash: empty Bash command");
+  }
+
+  const verdict = classifyCommand(command);
+  if (!verdict.destructive) return reply("allow", `ai-trash: ${verdict.kind} (${verdict.reason})`);
+
+  try {
+    await ensureSecureDir(root);
+    await assertOwnedByCurrentUser(root);
+    let snapshots = [];
+    let skipped = null;
+    if (verdict.kind.startsWith("git-")) {
+      ({ snapshots, skipped } = await snapshotGitRepo(root, data.cwd, command, verdict.kind));
+    } else {
+      snapshots = await snapshotExistingPaths(root, verdict.paths, data.cwd, command);
+    }
+    if (snapshots.length) {
+      const m = await loadManifest(root);
+      for (const s of snapshots) m.entries.push(s);
+      await saveManifest(root, m);
+    }
+    await appendLogEntry(root, "hook.allow", {
+      kind: verdict.kind,
+      command,
+      cwd: data.cwd ?? null,
+      snapshotCount: snapshots.length,
+      sessionId: data.session_id ?? null,
+    });
+    if (snapshots.length) {
+      return reply(
+        "allow",
+        `ai-trash: snapshotted ${snapshots.length} ${verdict.kind.startsWith("git-") ? "git bundle" : "path(s)"} before ${verdict.kind}`
+      );
+    }
+    return reply(
+      "allow",
+      skipped
+        ? `ai-trash: ${verdict.kind} (${skipped})`
+        : `ai-trash: ${verdict.kind} (no existing paths to snapshot)`
+    );
+  } catch (err) {
+    try {
+      await appendLogEntry(root, "hook.deny", {
+        kind: verdict.kind,
+        command,
+        error: err.message,
+        sessionId: data.session_id ?? null,
+      });
+    } catch {
+      /* root unwritable; deny is still the right answer */
+    }
+    return reply("deny", `ai-trash: snapshot failed (${err.message}); blocking ${verdict.kind}`);
+  }
+}
+
+export async function runHook({ root, stdin = process.stdin, stdout = process.stdout }) {
+  const response = await handleHookPayload(null, { root, stdin, stdout });
+  stdout.write(JSON.stringify(response) + "\n");
+  return 0;
+}

package/packages/ai-trash/src/index.js

@@ -0,0 +1,14 @@
+// @karajan/ai-trash — public entry (skeleton).
+// Real surface (snapshot, restore, list, manifest) lands in KJC-TSK-0388
+// commits 2-6 and KJC-TSK-0389 (git ops). For now we expose a single
+// `version` export so consumers / tests can confirm the package loads.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+
+export const version = pkg.version;
+export const name = pkg.name;

package/packages/ai-trash/src/install.js

@@ -0,0 +1,73 @@
+// Claude Code settings patcher (KJC-TSK-0390 commit 3). Idempotently
+// adds a PreToolUse hook entry that pipes Bash commands through
+// `kj-trash hook`. Preserves any unrelated keys and existing hooks so
+// the user's other settings are untouched.
+
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+// KJC-BUG-0095: the bare command fails SILENTLY when the bin drops off PATH
+// (nvm switch, global reinstall) — the anti-delete net goes down without
+// notice. The installed line fails CLOSED: a missing bin blocks the tool
+// call (exit 2) naming the net and the remedy, never a quiet pass-through.
+export const LEGACY_HOOK_COMMAND = "kj-trash hook";
+export const HOOK_COMMAND =
+  "if command -v kj-trash >/dev/null 2>&1; then exec kj-trash hook; fi; " +
+  "echo 'kj-trash: bin not on PATH — the anti-delete net is DOWN. Fix: npm i -g karajan-code (or remove this hook from ~/.claude/settings.json).' >&2; exit 2";
+const MATCHER = "Bash";
+
+async function readSettings(path) {
+  try {
+    return JSON.parse(await fs.readFile(path, "utf8"));
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+
+function hasHookCommand(matcherEntry, command) {
+  return (matcherEntry.hooks ?? []).some((h) => h.type === "command" && h.command === command);
+}
+
+export function patchSettings(settings, command = HOOK_COMMAND, matcher = MATCHER) {
+  const next = { ...settings };
+  next.hooks = { ...(next.hooks ?? {}) };
+  const preToolUse = Array.isArray(next.hooks.PreToolUse) ? next.hooks.PreToolUse.slice() : [];
+  let entry = preToolUse.find((e) => e.matcher === matcher);
+  let mutated = false;
+  if (!entry) {
+    entry = { matcher, hooks: [{ type: "command", command }] };
+    preToolUse.push(entry);
+    mutated = true;
+  } else if (hasHookCommand(entry, LEGACY_HOOK_COMMAND) && command !== LEGACY_HOOK_COMMAND) {
+    // KJC-BUG-0095 migration: upgrade the silent legacy line in place —
+    // deduped (reviewer catch): an entry already carrying the new line
+    // must end up with a single copy, not legacy-turned-duplicate.
+    let seen = false;
+    entry.hooks = entry.hooks
+      .map((h) => (h.type === "command" && h.command === LEGACY_HOOK_COMMAND ? { ...h, command } : h))
+      .filter((h) => {
+        if (!(h.type === "command" && h.command === command)) return true;
+        if (seen) return false;
+        seen = true;
+        return true;
+      });
+    mutated = true;
+  } else if (!hasHookCommand(entry, command)) {
+    entry.hooks = [...(entry.hooks ?? []), { type: "command", command }];
+    mutated = true;
+  }
+  next.hooks.PreToolUse = preToolUse;
+  return { settings: next, mutated };
+}
+
+export async function installClaudeCodeHook({ path = DEFAULT_SETTINGS_PATH, command = HOOK_COMMAND } = {}) {
+  const settings = await readSettings(path);
+  const { settings: next, mutated } = patchSettings(settings, command);
+  if (!mutated) return { path, mutated: false };
+  await fs.mkdir(dirname(path), { recursive: true });
+  await fs.writeFile(path, JSON.stringify(next, null, 2) + "\n", { encoding: "utf8" });
+  return { path, mutated: true };
+}

package/packages/ai-trash/src/logger.js

@@ -0,0 +1,60 @@
+// Append-only JSONL audit log for the trash store. Events are written one
+// JSON object per line so the file can be `tail -f`-d and parsed
+// line-by-line without holding the whole log in memory.
+
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { lockdownFile } from "./permissions.js";
+
+const HOME = homedir();
+
+function redactPath(p) {
+  if (typeof p !== "string" || !p) return p;
+  if (p === HOME) return "~";
+  if (p.startsWith(`${HOME}/`)) return `~/${p.slice(HOME.length + 1)}`;
+  return p;
+}
+
+function redactPayload(payload) {
+  if (!payload || typeof payload !== "object") return payload;
+  const out = {};
+  for (const [k, v] of Object.entries(payload)) {
+    if (typeof v === "string" && (k.includes("Path") || k === "cwd")) {
+      out[k] = redactPath(v);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+export async function appendLogEntry(rootDir, event, payload = {}) {
+  if (!event) throw new Error("ai-trash: log event required");
+  const file = join(rootDir, "log.jsonl");
+  const line =
+    JSON.stringify({
+      ts: new Date().toISOString(),
+      event,
+      ...redactPayload(payload),
+    }) + "\n";
+  await fs.mkdir(rootDir, { recursive: true });
+  await fs.appendFile(file, line, { encoding: "utf8", mode: 0o600 });
+  await lockdownFile(file);
+}
+
+export async function readLog(rootDir) {
+  const file = join(rootDir, "log.jsonl");
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    return raw
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l));
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+export { redactPath };

package/packages/ai-trash/src/manifest.js

@@ -0,0 +1,91 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { ulid } from "./ulid.js";
+
+export const SCHEMA_VERSION = 1;
+
+export async function loadManifest(rootDir) {
+  const file = join(rootDir, "manifest.json");
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion !== SCHEMA_VERSION) {
+      throw new Error(`ai-trash: unsupported manifest schemaVersion ${parsed?.schemaVersion}`);
+    }
+    if (!Array.isArray(parsed.entries)) parsed.entries = [];
+    return parsed;
+  } catch (err) {
+    if (err.code === "ENOENT") return { schemaVersion: SCHEMA_VERSION, entries: [] };
+    throw err;
+  }
+}
+
+export async function saveManifest(rootDir, manifest) {
+  const file = join(rootDir, "manifest.json");
+  await fs.mkdir(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(manifest, null, 2), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await fs.rename(tmp, file);
+}
+
+export function addEntry(manifest, partial) {
+  if (!partial?.sourcePath) throw new Error("ai-trash: sourcePath required");
+  if (typeof partial.sizeBytes !== "number" || partial.sizeBytes < 0) {
+    throw new Error("ai-trash: sizeBytes must be a non-negative number");
+  }
+  const now = Date.now();
+  const entry = {
+    id: ulid(now),
+    createdAt: now,
+    sourcePath: partial.sourcePath,
+    snapshotPath: partial.snapshotPath ?? null,
+    sizeBytes: partial.sizeBytes,
+    command: partial.command ?? null,
+    origin: partial.origin ?? "unknown",
+  };
+  manifest.entries.push(entry);
+  return entry;
+}
+
+export function listEntries(manifest) {
+  return [...manifest.entries].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function removeEntry(manifest, id) {
+  const idx = manifest.entries.findIndex((e) => e.id === id);
+  if (idx < 0) return null;
+  return manifest.entries.splice(idx, 1)[0];
+}
+
+export function expireBefore(manifest, cutoffMs) {
+  const expired = [];
+  manifest.entries = manifest.entries.filter((e) => {
+    if (e.createdAt < cutoffMs) {
+      expired.push(e);
+      return false;
+    }
+    return true;
+  });
+  return expired;
+}
+
+export function enforceLruQuota(manifest, maxBytes) {
+  if (typeof maxBytes !== "number" || maxBytes < 0) {
+    throw new Error("ai-trash: maxBytes must be a non-negative number");
+  }
+  const sorted = listEntries(manifest);
+  const total = sorted.reduce((sum, e) => sum + e.sizeBytes, 0);
+  const evicted = [];
+  let running = total;
+  for (const entry of sorted) {
+    if (running <= maxBytes) break;
+    evicted.push(entry);
+    running -= entry.sizeBytes;
+  }
+  const evictedIds = new Set(evicted.map((e) => e.id));
+  manifest.entries = manifest.entries.filter((e) => !evictedIds.has(e.id));
+  return evicted;
+}

package/packages/ai-trash/src/permissions.js

@@ -0,0 +1,26 @@
+import { promises as fs } from "node:fs";
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+export async function ensureSecureDir(path) {
+  await fs.mkdir(path, { recursive: true, mode: DIR_MODE });
+  await fs.chmod(path, DIR_MODE);
+}
+
+export async function lockdownFile(path) {
+  await fs.chmod(path, FILE_MODE);
+}
+
+export async function assertOwnedByCurrentUser(path) {
+  if (process.platform === "win32") return;
+  const stats = await fs.stat(path);
+  if (typeof process.getuid !== "function") return;
+  if (stats.uid !== process.getuid()) {
+    throw new Error(
+      `ai-trash: ${path} is owned by uid ${stats.uid}, expected ${process.getuid()}`
+    );
+  }
+}
+
+export { DIR_MODE, FILE_MODE };

package/packages/ai-trash/src/snapshot.js

@@ -0,0 +1,66 @@
+import { promises as fs } from "node:fs";
+import { basename, join } from "node:path";
+import { ulid } from "./ulid.js";
+import { ensureSecureDir, lockdownFile } from "./permissions.js";
+import { appendLogEntry } from "./logger.js";
+
+async function statOrNull(path) {
+  try {
+    return await fs.lstat(path);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function snapshotFile(rootDir, sourcePath, options = {}) {
+  const stat = await statOrNull(sourcePath);
+  if (!stat) throw new Error(`ai-trash: source not found: ${sourcePath}`);
+  if (stat.isDirectory()) {
+    throw new Error("ai-trash: directory snapshots not implemented in MVP");
+  }
+  const id = ulid();
+  const storeDir = join(rootDir, "store", id);
+  await ensureSecureDir(storeDir);
+  const snapshotPath = join(storeDir, basename(sourcePath));
+  await fs.copyFile(sourcePath, snapshotPath);
+  await lockdownFile(snapshotPath);
+  const entry = {
+    id,
+    createdAt: Date.now(),
+    sourcePath,
+    snapshotPath,
+    sizeBytes: stat.size,
+    command: options.command ?? null,
+    origin: options.origin ?? "unknown",
+  };
+  await appendLogEntry(rootDir, "snapshot.create", {
+    id,
+    sourcePath,
+    snapshotPath,
+    sizeBytes: stat.size,
+  });
+  return entry;
+}
+
+export async function restoreSnapshot(rootDir, entry, targetPath) {
+  const target = targetPath ?? entry.sourcePath;
+  const exists = await statOrNull(target);
+  if (exists) throw new Error(`ai-trash: refusing to overwrite ${target}`);
+  await fs.mkdir(join(target, ".."), { recursive: true });
+  await fs.copyFile(entry.snapshotPath, target);
+  await appendLogEntry(rootDir, "snapshot.restore", {
+    id: entry.id,
+    snapshotPath: entry.snapshotPath,
+    targetPath: target,
+  });
+  return target;
+}
+
+export async function purgeSnapshot(rootDir, entry) {
+  await fs.rm(join(rootDir, "store", entry.id), { recursive: true, force: true });
+  await appendLogEntry(rootDir, "snapshot.purge", {
+    id: entry.id,
+    sizeBytes: entry.sizeBytes,
+  });
+}

package/packages/ai-trash/src/ulid.js

@@ -0,0 +1,66 @@
+// Tiny ULID generator (Crockford base32, 26 chars, monotonic within ms).
+// We keep this self-contained to avoid pulling a runtime dep into the
+// safety-net package — fewer transitive deps = fewer supply-chain surfaces
+// that an attacker could pivot through to reach the trash store.
+
+import { randomBytes } from "node:crypto";
+
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+
+let lastMs = 0;
+let lastRandom = new Uint8Array(10);
+
+function encodeTime(ms) {
+  let out = "";
+  for (let i = 9; i >= 0; i--) {
+    out = ENCODING[ms % 32] + out;
+    ms = Math.floor(ms / 32);
+  }
+  return out;
+}
+
+function encodeRandom(bytes) {
+  let out = "";
+  for (let i = 0; i < 16; i++) {
+    const byteIndex = Math.floor((i * 5) / 8);
+    const bitOffset = (i * 5) % 8;
+    const hi = bytes[byteIndex] ?? 0;
+    const lo = bytes[byteIndex + 1] ?? 0;
+    const value = ((hi << 8) | lo) >> (11 - bitOffset);
+    out += ENCODING[value & 31];
+  }
+  return out;
+}
+
+function bumpRandom(buf) {
+  for (let i = buf.length - 1; i >= 0; i--) {
+    if (buf[i] === 0xff) {
+      buf[i] = 0;
+      continue;
+    }
+    buf[i] += 1;
+    return buf;
+  }
+  throw new Error("ulid: random overflow within the same millisecond");
+}
+
+export function ulid(nowMs = Date.now()) {
+  if (nowMs === lastMs) {
+    lastRandom = bumpRandom(lastRandom);
+  } else {
+    lastMs = nowMs;
+    lastRandom = new Uint8Array(randomBytes(10));
+  }
+  return encodeTime(nowMs) + encodeRandom(lastRandom);
+}
+
+export function decodeTimeFromUlid(id) {
+  const slice = id.slice(0, 10);
+  let ms = 0;
+  for (const ch of slice) {
+    const v = ENCODING.indexOf(ch);
+    if (v < 0) throw new Error(`ulid: invalid char ${ch}`);
+    ms = ms * 32 + v;
+  }
+  return ms;
+}

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,28 @@
+{
+  "name": "@karajan/hu-board",
+  "version": "1.1.0",
+  "description": "HU Story Board dashboard for Karajan Code",
+  "type": "module",
+  "private": true,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "node --watch src/server.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "karajan-core": "*",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
+    "express": "^5.1.0",
+    "express-rate-limit": "^8.5.0",
+    "helmet": "^8.1.0",
+    "js-yaml": "^4.2.0"
+  },
+  "devDependencies": {
+    "supertest": "^7.1.0",
+    "vitest": "^4.0.0"
+  }
+}