karajan-code 3.0.0 → 3.2.0

package/src/utils/ai-trash.js

@@ -0,0 +1,48 @@
+// ai-trash detection + Claude Code hook install (KJC-TSK-0391).
+// `kj-trash` is the binary shipped by the @karajan/ai-trash workspace.
+// detectAiTrash() probes the binary; installAiTrashHook() invokes
+// `kj-trash install --claude-code`, which idempotently patches
+// ~/.claude/settings.json to register the PreToolUse hook.
+
+import { runCommand } from "./process.js";
+
+/**
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectAiTrash() {
+  try {
+    const res = await runCommand("kj-trash", ["--help"]);
+    if (res.exitCode === 0 || res.exitCode === 2) {
+      return { available: true, version: "0.0.0" };
+    }
+    return { available: false, version: null };
+  } catch {
+    return { available: false, version: null };
+  }
+}
+
+/**
+ * Register the kj-trash PreToolUse hook in ~/.claude/settings.json.
+ * Idempotent: second run reports "already installed" without rewriting.
+ *
+ * @param {object} logger - logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, mutated: boolean, error: string|null }>}
+ */
+export async function installAiTrashHook(logger) {
+  logger.info("Registering ai-trash Claude Code hook...");
+  try {
+    const res = await runCommand("kj-trash", ["install", "--claude-code"], { timeout: 30_000 });
+    if (res.exitCode !== 0) {
+      const error = (res.stderr || "").trim() || `exit code ${res.exitCode}`;
+      logger.warn(`ai-trash hook install failed: ${error}`);
+      return { ok: false, mutated: false, error };
+    }
+    const mutated = !(res.stdout || "").includes("already installed");
+    logger.info(mutated ? "ai-trash hook installed." : "ai-trash hook already installed.");
+    return { ok: true, mutated, error: null };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`ai-trash hook install failed: ${error}`);
+    return { ok: false, mutated: false, error };
+  }
+}

package/src/utils/atomic-write.js

@@ -1,43 +1,6 @@
-// Atomic JSON writes for persistent state (resilience audit, Phase 2).
-//
-// A plain `writeFile(path, JSON.stringify(...))` truncates the live file
-// before the new content lands. If the process is killed mid-write
-// (SIGKILL, crash, power loss) the file is left truncated and the only
-// good copy is already gone — the plan / session / standby JSON
-// silently corrupts.
-//
-// write-temp + rename fixes it: `rename` is atomic on the same
-// filesystem, so a reader sees either the old file or the complete new
-// one, never a half-written one. The temp file sits next to the target
-// (same dir → same FS) and is uniquely named so concurrent writers do
-// not clobber each other's temp. A crash before the rename leaves an
-// orphan `.tmp` but never a corrupt target.
-
-import { writeFileSync, renameSync } from "node:fs";
-import { writeFile, rename } from "node:fs/promises";
-
-function tempPath(target) {
-  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
-}
-
-/**
- * Atomically write `obj` as pretty JSON to `target` (synchronous).
- * @param {string} target - destination path; its directory must exist
- * @param {unknown} obj
- */
-export function writeJsonAtomicSync(target, obj) {
-  const tmp = tempPath(target);
-  writeFileSync(tmp, JSON.stringify(obj, null, 2), "utf-8");
-  renameSync(tmp, target);
-}
-
-/**
- * Atomically write `obj` as pretty JSON to `target` (async).
- * @param {string} target - destination path; its directory must exist
- * @param {unknown} obj
- */
-export async function writeJsonAtomic(target, obj) {
-  const tmp = tempPath(target);
-  await writeFile(tmp, JSON.stringify(obj, null, 2), "utf-8");
-  await rename(tmp, target);
-}
+// Shim — the real implementation now lives in @karajan/core/atomic-write.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "#utils/atomic-write.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the @karajan/core import.
+export { writeJsonAtomic, writeJsonAtomicSync } from "@karajan/core/atomic-write";

package/src/utils/cli-ask-question.js

@@ -0,0 +1,76 @@
+import readline from "node:readline";
+
+/**
+ * Shared askQuestion factory used by `kj run` and `kj resume`.
+ *
+ * Pre-fix (KJC-BUG-0081 round 1), `src/commands/run.js` got the guard
+ * but `src/commands/resume.js` kept its own copy without the guard, so
+ * `kj resume --yes` in non-TTY mode still hung on the HU Board bridge.
+ * Centralising the three paths here means both commands honour the
+ * same contract and a future fix only needs to land in one place.
+ *
+ * Three paths:
+ *   1. Interactive TTY: prompt via readline (developer terminal).
+ *   2. No TTY + `flags.yes`: caller asked NOT to be prompted → write
+ *      question + context to stderr, return null so the run aborts
+ *      fast and loud (CI / scripted / `kj audit --yes` desatendido).
+ *   3. No TTY without `flags.yes` (HU Board ▶ Run plan with
+ *      `stdio=ignore`): publish through the file-based bridge so the
+ *      board can surface a modal; block until the user answers.
+ *
+ * @param {object} [opts]
+ * @param {string|null} [opts.sessionId]
+ * @param {object} [opts.flags]
+ * @returns {(question: string, context?: object) => Promise<string|null>}
+ */
+export function createCliAskQuestion(opts = {}) {
+  const { sessionId = null, flags = {} } = opts;
+  return async (question, context) => {
+    const stdinReadable = process.stdin && process.stdin.readable !== false;
+    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
+    if (!isInteractive) {
+      if (flags?.yes) {
+        process.stderr.write(
+          `\n[non-interactive --yes] Pipeline asked a question that cannot be auto-answered:\n`
+          + `  ❓ ${question}\n`
+          + (context?.detail ? `  Context: ${JSON.stringify(context.detail)}\n` : "")
+          + `  Stopping the session. Re-run without --yes (TTY or HU Board) to answer it,\n`
+          + `  or pass --skip-spec-review / a more complete spec so the question never appears.\n`
+        );
+        return null;
+      }
+      const { askThroughBoard } = await import("./board-prompt-bridge.js");
+      console.log(`\n❓ ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      console.log(
+        "\n[non-interactive] Routing the prompt to the HU Board.\n"
+        + "  Open http://localhost:4000 — a modal will appear asking for your answer.\n"
+        + "  This process is now waiting; closing the board does NOT cancel the run."
+      );
+      try {
+        return await askThroughBoard({ sessionId, question, context });
+      } catch (err) {
+        console.log(`\n[prompt-bridge] ${err.message} — stopping the session.`);
+        return null;
+      }
+    }
+
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n❓ ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}

package/src/utils/doc-links.js

@@ -15,6 +15,8 @@ const ERROR_DOCS = {
   config_missing: `${BASE_URL}/getting-started/quick-start/`,
   branch_error: `${BASE_URL}/guides/pipeline/#git-workflow`,
   rtk_install: `${BASE_URL}/guides/configuration/#rtk`,
+  squeezr_install: `${BASE_URL}/guides/configuration/#squeezr`,
+  qmd_install: `${BASE_URL}/guides/configuration/#qmd`,
 };
 
 export function docLink(errorType) {

package/src/utils/os-detect.js

@@ -16,6 +16,16 @@ const INSTALL_COMMANDS = {
     linux: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh && rtk init --global",
     windows: "Download from https://github.com/rtk-ai/rtk/releases and add to PATH"
   },
+  squeezr: {
+    macos: "npm install -g squeezr-ai",
+    linux: "npm install -g squeezr-ai",
+    windows: "npm install -g squeezr-ai"
+  },
+  qmd: {
+    macos: "npm install -g @tobilu/qmd",
+    linux: "npm install -g @tobilu/qmd",
+    windows: "npm install -g @tobilu/qmd"
+  },
   claude: {
     macos: "npm install -g @anthropic-ai/claude-code",
     linux: "npm install -g @anthropic-ai/claude-code",

package/src/utils/paths.js

@@ -1,111 +1,14 @@
-import os from "node:os";
-import path from "node:path";
-
-// Per-process vitest root. We memoise the *root* (not the suffixed
-// `.karajan` / `.kj` path) so callers with different legacy defaults
-// — plan-store wants `.kj`, db.js wants `.karajan` — can share one
-// random tmp prefix per test run without colliding.
-let _vitestRoot = null;
-function vitestRoot() {
-  if (_vitestRoot) return _vitestRoot;
-  _vitestRoot = path.join(
-    os.tmpdir(),
-    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
-  );
-  return _vitestRoot;
-}
-
-function vitestTmpHome(defaultSegment) {
-  return path.join(vitestRoot(), defaultSegment);
-}
-
-// One-shot warning so users with KJ_HOME set in their shell rcfile do
-// not get spammed once per `kj` invocation. Reset across processes,
-// which is the granularity that matters for a humans-reading-stderr
-// audience.
-let _kjHomeWarned = false;
-function emitKjHomeDeprecationWarning() {
-  if (_kjHomeWarned) return;
-  _kjHomeWarned = true;
-  // eslint-disable-next-line no-console
-  console.warn(
-    "\x1b[33m[warn]\x1b[0m KJ_HOME is deprecated, rename to KARAJAN_HOME (KJ_HOME will be removed in a future release)"
-  );
-}
-
-/**
- * Unified resolver for Karajan's HOME-level storage root. Used by every
- * helper that previously rolled its own `getKjHome()` with subtly
- * different defaults and VITEST handling.
- *
- * Precedence (highest first):
- *   1. KARAJAN_HOME env var — explicit, no warning
- *   2. KJ_HOME env var      — explicit, prints deprecation warning once
- *   3. VITEST tmp dir       — auto-isolation under `os.tmpdir()/karajan-vitest-<pid>-<rand>/<defaultSegment>`
- *   4. `~/<defaultSegment>` — production default
- *
- * Callers pass `defaultSegment` so we can preserve `.kj` for legacy
- * paths (plan-store, standby-store) and `.karajan` for the canonical
- * root, until PR 3 unifies the defaults too.
- *
- * @param {object} [options]
- * @param {string} [options.defaultSegment=".karajan"]  HOME subdir name
- * @returns {string} absolute path
- */
-export function resolveHome({ defaultSegment = ".karajan" } = {}) {
-  if (process.env.KARAJAN_HOME) {
-    return path.resolve(process.env.KARAJAN_HOME);
-  }
-  if (process.env.KJ_HOME) {
-    emitKjHomeDeprecationWarning();
-    return path.resolve(process.env.KJ_HOME);
-  }
-  if (process.env.VITEST) {
-    return vitestTmpHome(defaultSegment);
-  }
-  return path.join(os.homedir(), defaultSegment);
-}
-
-/**
- * Canonical Karajan home (`~/.karajan` by default). Every helper that
- * used to roll its own `getKjHome()` now goes through this one — see
- * KJC-PCS-0047 PR 3 for the consolidation.
- */
-export function getKarajanHome() {
-  return resolveHome({ defaultSegment: ".karajan" });
-}
-
-// Test-only export. Tests that depend on observing the deprecation
-// warning being emitted exactly once need to reset the latch between
-// cases.
-export function __resetKjHomeWarningForTests() {
-  _kjHomeWarned = false;
-}
-
-export function getSessionRoot() {
-  return path.join(getKarajanHome(), "sessions");
-}
-
-export function getSonarComposePath() {
-  return path.join(getKarajanHome(), "docker-compose.sonar.yml");
-}
-
-/** Ollama RAG embedder compose: `<karajan-home>/docker-compose.ollama.yml` — KJC-TSK-0435. */
-export function getOllamaComposePath() {
-  return path.join(getKarajanHome(), "docker-compose.ollama.yml");
-}
-
-/** Webperf cache: `<karajan-home>/webperf/` — KJC-TSK-0420. */
-export function getWebperfDir() {
-  return path.join(getKarajanHome(), "webperf");
-}
-
-/** Run-registry: `<karajan-home>/runs/` — KJC-TSK-0420. */
-export function getRunsDir() {
-  return path.join(getKarajanHome(), "runs");
-}
-
-/** Board prompt bridge: `<karajan-home>/prompts/` — KJC-TSK-0420. */
-export function getPromptsDir() {
-  return path.join(getKarajanHome(), "prompts");
-}
+// Shim: paths primitives now live in @karajan/core/paths so the
+// hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR3.
+export {
+  resolveHome,
+  getKarajanHome,
+  __resetKjHomeWarningForTests,
+  getSessionRoot,
+  getSonarComposePath,
+  getOllamaComposePath,
+  getWebperfDir,
+  getRunsDir,
+  getPromptsDir,
+} from "@karajan/core/paths";

package/src/utils/port-check.js

@@ -1,45 +1,6 @@
-/**
- * TCP port availability helpers.
- *
- * Originally lived in packages/hu-board/src/server.js. Moved here so the
- * doctor/preflight subsystem (src/checks/) and hu-board share a single
- * implementation.
- */
-
-import { createServer } from "node:net";
-
-/**
- * Check whether a TCP port is available to bind on localhost.
- *
- * @param {number} port
- * @returns {Promise<boolean>}
- */
-export function isPortAvailable(port) {
-  return new Promise((resolve) => {
-    const server = createServer();
-    server.once("error", () => resolve(false));
-    server.once("listening", () => {
-      server.close();
-      resolve(true);
-    });
-    server.listen(port);
-  });
-}
-
-/**
- * Find the first available port starting from `startPort`.
- *
- * @param {number} startPort       - first port to try
- * @param {number} [maxAttempts=11] - how many consecutive ports to probe
- * @param {(port: number) => void} [onBusy] - called for each busy port seen
- * @returns {Promise<number>}      - resolves with the first free port found
- * @throws {Error} if no port is free within the range
- */
-export async function findAvailablePort(startPort, maxAttempts = 11, onBusy) {
-  for (let i = 0; i < maxAttempts; i++) {
-    const port = startPort + i;
-    if (await isPortAvailable(port)) return port;
-    if (onBusy) onBusy(port);
-  }
-  throw new Error(`No available port found between ${startPort} and ${startPort + maxAttempts - 1}`);
-}
+// Shim — the real implementation now lives in @karajan/core/port-check.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "../utils/port-check.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the @karajan/core import.
+export { isPortAvailable, findAvailablePort } from "@karajan/core/port-check";

package/src/utils/process.js

@@ -1,188 +1,4 @@
-import { execa } from "execa";
-
-const isWin = process.platform === "win32";
-const KILL_SIGNAL = isWin ? "SIGTERM" : "SIGKILL";
-
-function buildSilenceKilledResult(silenceTimeoutMs, stdout, signal) {
-  return {
-    exitCode: 143,
-    stdout,
-    stderr: `Command killed after ${Number(silenceTimeoutMs)}ms without output`,
-    timedOut: true,
-    signal: signal || KILL_SIGNAL
-  };
-}
-
-function setupOutputStreaming(subprocess, onOutput, partialOutputFlushMs) {
-  const flushMs = Number(partialOutputFlushMs) > 0 ? Number(partialOutputFlushMs) : 2000;
-  const streams = {};
-  const makeHandler = (stream) => {
-    const state = { partial: "", dirty: false };
-    streams[stream] = state;
-    return (chunk) => {
-      state.partial += chunk.toString();
-      const lines = state.partial.split(/\r\n|\n|\r/);
-      state.partial = lines.pop() ?? "";
-      state.dirty = state.partial.length > 0;
-      for (const line of lines) {
-        if (line) onOutput({ stream, line });
-      }
-    };
-  };
-
-  const flushPartials = () => {
-    for (const [stream, state] of Object.entries(streams)) {
-      if (!state.dirty || !state.partial) continue;
-      onOutput({ stream, line: state.partial });
-      state.partial = "";
-      state.dirty = false;
-    }
-  };
-
-  if (subprocess.stdout) subprocess.stdout.on("data", makeHandler("stdout"));
-  if (subprocess.stderr) subprocess.stderr.on("data", makeHandler("stderr"));
-  const flushInterval = setInterval(flushPartials, flushMs);
-  flushInterval.unref?.();
-
-  subprocess.finally(() => {
-    flushPartials();
-    clearInterval(flushInterval);
-  });
-}
-
-async function awaitWithTimeout(subprocess, timeout, getStdout) {
-  let timer = null;
-  const timeoutResult = new Promise((resolve) => {
-    timer = setTimeout(() => {
-      try {
-        subprocess.kill(KILL_SIGNAL, { forceKillAfterDelay: 1000 });
-      } catch {
-        // no-op
-      }
-      resolve({
-        exitCode: 143,
-        stdout: getStdout(),
-        stderr: `Command timed out after ${timeout}ms`,
-        timedOut: true,
-        signal: KILL_SIGNAL
-      });
-    }, timeout);
-  });
-
-  const result = await Promise.race([subprocess, timeoutResult]);
-  if (timer) clearTimeout(timer);
-  return result;
-}
-
-export async function runCommand(command, args = [], options = {}) {
-  const { timeout, onOutput, silenceTimeoutMs, partialOutputFlushMs, ...rest } = options;
-  // Detach stdin unless the caller provides input (e.g. Codex uses input: prompt).
-  // Without this, a subprocess prompting for input hangs forever since there is no TTY.
-  if (!rest.stdin && !rest.input) rest.stdin = "ignore";
-  const subprocess = execa(command, args, { reject: false, ...rest });
-
-  let stdoutAccum = "";
-  let stderrAccum = "";
-  let outputSilenceTimer = null;
-  let silenceTimedOut = false;
-
-  function clearSilenceTimer() {
-    if (outputSilenceTimer) {
-      clearTimeout(outputSilenceTimer);
-      outputSilenceTimer = null;
-    }
-  }
-
-  function armSilenceTimer() {
-    const ms = Number(silenceTimeoutMs);
-    if (!Number.isFinite(ms) || ms <= 0 || silenceTimedOut) return;
-    clearSilenceTimer();
-    outputSilenceTimer = setTimeout(() => {
-      silenceTimedOut = true;
-      try {
-        subprocess.kill(KILL_SIGNAL, { forceKillAfterDelay: 1000 });
-      } catch {
-        // no-op
-      }
-    }, ms);
-  }
-
-  if (subprocess.stdout) {
-    subprocess.stdout.on("data", (chunk) => {
-      stdoutAccum += chunk.toString();
-      armSilenceTimer();
-    });
-  }
-  if (subprocess.stderr) {
-    subprocess.stderr.on("data", (chunk) => {
-      stderrAccum += chunk.toString();
-      armSilenceTimer();
-    });
-  }
-
-  if (onOutput) {
-    setupOutputStreaming(subprocess, onOutput, partialOutputFlushMs);
-  }
-  armSilenceTimer();
-
-  try {
-    const result = timeout
-      ? await awaitWithTimeout(subprocess, timeout, () => stdoutAccum)
-      : await subprocess;
-    clearSilenceTimer();
-    if (silenceTimedOut) return buildSilenceKilledResult(silenceTimeoutMs, stdoutAccum);
-    return enrichResult(result, stdoutAccum, stderrAccum);
-  } catch (error) {
-    clearSilenceTimer();
-    if (silenceTimedOut) return buildSilenceKilledResult(silenceTimeoutMs, error?.stdout || stdoutAccum, error?.signal);
-
-    const details = [error?.shortMessage, error?.originalMessage, error?.stderr, error?.stdout, error?.message]
-      .filter(Boolean)
-      .join("\n");
-
-    return {
-      exitCode: 1,
-      stdout: error?.stdout || stdoutAccum,
-      stderr: details || String(error),
-      signal: error?.signal || null
-    };
-  }
-}
-
-function enrichResult(result, stdoutAccum, _stderrAccum) {
-  if (result.timedOut) return result;
-
-  // execa with reject:false RESOLVES (does not throw) on a spawn
-  // failure — ENOENT (binary not in PATH), EACCES, etc. The result
-  // then carries exitCode null/undefined, an empty stderr, and the
-  // real cause only in `code` / `shortMessage`. Surface it: a missing
-  // agent CLI used to fail with a completely empty error message,
-  // leaving the user with "coder failed" and no idea what to install.
-  if (result.failed && result.exitCode == null && !result.signal) {
-    const reason = result.shortMessage || result.message
-      || `spawn failed${result.code ? ` (${result.code})` : ""}`;
-    return {
-      ...result,
-      exitCode: 1,
-      stdout: result.stdout || stdoutAccum,
-      stderr: result.stderr || reason,
-      spawnError: result.code || true,
-    };
-  }
-
-  const killed = result.killed || !!result.signal;
-  const signal = result.signal || null;
-
-  if (killed && !result.stderr) {
-    return {
-      ...result,
-      stdout: result.stdout || stdoutAccum,
-      stderr: signal
-        ? `Process killed by signal ${signal}`
-        : "Process was killed externally",
-      signal
-    };
-  }
-
-  return result;
-}
+// Shim: process runner now lives in @karajan/core/process so the
+// hu-board workspace can consume it without a relative dep on the CLI
+// src tree. KJC-TSK-0511 PR6.
+export { runCommand } from "@karajan/core/process";

package/src/utils/qmd-collection.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { runCommand } from "./process.js";
+
+export const QMD_DEFAULT_PATHS = ["docs", ".reviews", ".karajan/plans"];
+
+export function projectSlug(projectDir) {
+  const base = path.basename(path.resolve(projectDir));
+  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "project";
+}
+
+export function planQmdCollections(projectDir) {
+  const slug = projectSlug(projectDir);
+  const result = [];
+  for (const rel of QMD_DEFAULT_PATHS) {
+    const abs = path.join(projectDir, rel);
+    if (!existsSync(abs)) continue;
+    try { if (!statSync(abs).isDirectory()) continue; } catch { continue; }
+    const suffix = rel.replace(/^\./, "").replace(/[/\\]+/g, "-");
+    result.push({ name: `${slug}-${suffix}`, path: abs });
+  }
+  return result;
+}
+
+async function listExistingCollections() {
+  try {
+    const res = await runCommand("qmd", ["collection", "list"]);
+    if (res.exitCode !== 0) return new Set();
+    const names = new Set();
+    for (const line of (res.stdout || "").split("\n")) {
+      const m = line.match(/^([\w.-]+)\s+\(qmd:\/\//);
+      if (m) names.add(m[1]);
+    }
+    return names;
+  } catch { return new Set(); }
+}
+
+/**
+ * Register all default QMD collections for the project. Idempotent: skips
+ * collections already present in `qmd collection list`. qmd's CLI only
+ * accepts one path per `collection add`, so we register up to 3 sibling
+ * collections (`<slug>-docs`, `<slug>-reviews`, `<slug>-karajan-plans`).
+ */
+export async function registerQmdCollections(projectDir, logger) {
+  const planned = planQmdCollections(projectDir);
+  const result = { ok: true, added: [], skipped: [], errors: [] };
+  if (planned.length === 0) {
+    logger.info("QMD: no indexable folders yet (docs/, .reviews/, .karajan/plans/ all missing).");
+    return result;
+  }
+  const existing = await listExistingCollections();
+  for (const { name, path: abs } of planned) {
+    if (existing.has(name)) { result.skipped.push(name); continue; }
+    try {
+      const res = await runCommand("qmd", ["collection", "add", abs, "--name", name], { timeout: 60_000 });
+      if (res.exitCode === 0) {
+        result.added.push(name);
+      } else {
+        const err = (res.stderr || res.stdout || "").trim() || `exit code ${res.exitCode}`;
+        result.errors.push(`${name}: ${err}`);
+        result.ok = false;
+      }
+    } catch (err) {
+      result.errors.push(`${name}: ${err.message || String(err)}`);
+      result.ok = false;
+    }
+  }
+  if (result.added.length) logger.info(`QMD: registered ${result.added.length} collection(s): ${result.added.join(", ")}.`);
+  if (result.skipped.length) logger.info(`QMD: ${result.skipped.length} collection(s) already present, skipped.`);
+  for (const err of result.errors) logger.warn(`QMD: collection registration failed — ${err}`);
+  return result;
+}

package/src/utils/qmd-detect.js

@@ -0,0 +1,18 @@
+import { runCommand } from "./process.js";
+
+/**
+ * Detect whether QMD is installed and available.
+ * @returns {Promise<{ available: boolean, version: string|null }>}
+ */
+export async function detectQmd() {
+  try {
+    const result = await runCommand("qmd", ["--version"]);
+    if (result.exitCode === 0) {
+      const version = (result.stdout || "").trim() || null;
+      return { available: true, version };
+    }
+    return { available: false, version: null };
+  } catch { /* qmd binary not found */
+    return { available: false, version: null };
+  }
+}