karajan-code 3.1.0 → 3.2.0

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 };
+  }
+}

package/src/utils/qmd-install.js

@@ -0,0 +1,37 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectQmd } from "./qmd-detect.js";
+
+/**
+ * Install QMD using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installQmd(logger) {
+  const command = getInstallCommand("qmd");
+
+  logger.info("Installing QMD...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`QMD install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    const check = await detectQmd();
+    if (check.available) {
+      logger.info(`QMD ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("QMD install command succeeded but qmd binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`QMD install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}

package/src/utils/run-registry.js

@@ -1,116 +1,9 @@
-/**
- * Run registry — registro persistente de `kj run` activos.
- *
- * KJC-TSK-0396 (extensión): el HU Board necesita ver runs lanzados desde
- * la terminal externa (no solo los lanzados desde el propio board). Para
- * eso, cada `kj run` escribe su PID + planId + huIds + projectDir a un
- * archivo en `~/.karajan/runs/<runId>.json` al arrancar, y lo borra al
- * terminar (success o crash con cleanup vía finally).
- *
- * El board lee ese directorio en startup + cada vez que sirve el endpoint
- * `/api/runs/:planId/active`, descartando los registros con PID muerto
- * (filtrado con `process.kill(pid, 0)`). Resultado: bidireccionalidad
- * total terminal ↔ board.
- *
- * Compartido entre el CLI (src/commands/run.js) y el board
- * (packages/hu-board/src/run-tracker.js). Vive en src/utils/ porque
- * el board ya importa cosas de src/ sin problema.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-import { writeJsonAtomicSync } from "./atomic-write.js";
-import { getRunsDir } from "./paths.js";
-
-/**
- * Directorio raíz donde viven los registros de run.
- * Delega en `getRunsDir()` (KJC-TSK-0420) — respeta KARAJAN_HOME,
- * KJ_HOME (con warning de deprecación), VITEST tmp y default.
- */
-export function runsDir() {
-  return getRunsDir();
-}
-
-/**
- * Registra un nuevo run en disco. El runId es derivado del PID + timestamp
- * para ser único por proceso.
- *
- * @param {{ pid: number, planId?: string|null, huIds?: string[]|null, projectDir?: string|null, source?: string }} info
- * @returns {string|null} runId o null si la escritura falló (no bloquea al caller).
- */
-export function registerRun(info = {}) {
-  if (!info?.pid) return null;
-  try {
-    fs.mkdirSync(runsDir(), { recursive: true });
-    // Sufijo random para evitar colisiones cuando 2 runs del mismo PID
-    // se registran en el mismo ms (raro en CLI, posible en tests).
-    const runId = `run-${Date.now()}-${info.pid}-${Math.random().toString(36).slice(2, 8)}`;
-    const filePath = path.join(runsDir(), `${runId}.json`);
-    const entry = {
-      runId,
-      pid: info.pid,
-      planId: info.planId || null,
-      huIds: Array.isArray(info.huIds) ? info.huIds : null,
-      projectDir: info.projectDir || null,
-      source: info.source || "cli",
-      startedAt: new Date().toISOString(),
-    };
-    writeJsonAtomicSync(filePath, entry);
-    return runId;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Borra el registro de un run. Idempotente — silencia ENOENT.
- *
- * @param {string} runId
- */
-export function unregisterRun(runId) {
-  if (!runId) return;
-  try {
-    fs.unlinkSync(path.join(runsDir(), `${runId}.json`));
-  } catch {
-    // Idempotente
-  }
-}
-
-/**
- * Lista todos los runs activos en disco, filtrando los con PID muerto.
- * Los muertos se borran del FS (auto-cleanup defensivo).
- *
- * @param {{ planId?: string }} [filter] - si se pasa planId, devuelve solo los runs de ese plan.
- * @returns {Array<{runId, pid, planId, huIds, projectDir, source, startedAt}>}
- */
-export function listActiveRuns(filter = {}) {
-  const dir = runsDir();
-  if (!fs.existsSync(dir)) return [];
-  const out = [];
-  let files;
-  try { files = fs.readdirSync(dir); } catch { return []; }
-  for (const f of files) {
-    if (!f.endsWith(".json")) continue;
-    const filePath = path.join(dir, f);
-    let entry;
-    try { entry = JSON.parse(fs.readFileSync(filePath, "utf8")); }
-    catch { try { fs.unlinkSync(filePath); } catch { /* swallow */ } continue; }
-    if (!isAlive(entry.pid)) {
-      try { fs.unlinkSync(filePath); } catch { /* swallow */ }
-      continue;
-    }
-    if (filter.planId && entry.planId !== filter.planId) continue;
-    out.push(entry);
-  }
-  return out;
-}
-
-/**
- * Verifica si un PID sigue vivo. `process.kill(pid, 0)` NO envía
- * señal — solo lanza ESRCH si el proceso no existe.
- */
-function isAlive(pid) {
-  if (!pid) return false;
-  try { process.kill(pid, 0); return true; }
-  catch (err) { return err.code === "EPERM"; }
-}
+// Shim: run-registry now lives in @karajan/core/run-registry so the
+// hu-board workspace can consume it without a relative dep on the CLI
+// src tree. KJC-TSK-0511 PR3.
+export {
+  runsDir,
+  registerRun,
+  unregisterRun,
+  listActiveRuns,
+} from "@karajan/core/run-registry";

package/src/utils/shared-paths.js

@@ -1,41 +1,12 @@
-/**
- * Team-shared HU Board paths — KJC-PRP-0002 / v2.31.0 PR1.
- *
- * The shared root lives INSIDE the project, not in `~/.karajan/`, so a team
- * can commit it to git (or sync via Drive/SyncThing) and share plans + HU
- * stories without each member regenerating them locally.
- *
- *   <projectDir>/.karajan-shared/
- *     plans/<planId>.json     ← `kj plan share <planId>` copies here
- *     hu-stories/<huId>.md    ← reserved for PR2+ (board reads it)
- *
- * Keep the dir name in lockstep with the HU Board sync layer
- * (`packages/hu-board/src/sync.js`) — diverging the constant breaks the
- * watcher silently. One source of truth lives here.
- */
-
-import path from "node:path";
-
-export const SHARED_DIR_NAME = ".karajan-shared";
-
-export function getSharedRoot(projectDir) {
-  return path.join(projectDir, SHARED_DIR_NAME);
-}
-
-export function getSharedPlansDir(projectDir) {
-  return path.join(getSharedRoot(projectDir), "plans");
-}
-
-export function getSharedHuStoriesDir(projectDir) {
-  return path.join(getSharedRoot(projectDir), "hu-stories");
-}
-
-/**
- * Quick check used by callers that decide whether a plan came from local
- * (`~/.karajan/plans/`) or from the shared dir. The HU Board uses this to
- * stamp a `source` column on each record so the UI can render a 🌐 badge.
- */
-export function isSharedPath(p) {
-  if (!p) return false;
-  return p.split(path.sep).includes(SHARED_DIR_NAME);
-}
+// Shim — the real implementation now lives in @karajan/core/shared-paths.
+// Kept here so CLI callers (src/**/*.js) keep importing
+// "../utils/shared-paths.js" without churn during KJC-TSK-0511 (decouple
+// @karajan/hu-board). Will be retired once every consumer migrates to
+// the @karajan/core import.
+export {
+  SHARED_DIR_NAME,
+  getSharedRoot,
+  getSharedPlansDir,
+  getSharedHuStoriesDir,
+  isSharedPath,
+} from "@karajan/core/shared-paths";

package/src/utils/squeezr-detect.js

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

package/src/utils/squeezr-install.js

@@ -0,0 +1,37 @@
+import { runCommand } from "./process.js";
+import { getInstallCommand } from "./os-detect.js";
+import { detectSqueezr } from "./squeezr-detect.js";
+
+/**
+ * Install Squeezr using the OS-appropriate command.
+ * @param {object} logger - Logger with info/warn methods
+ * @returns {Promise<{ ok: boolean, version: string|null, error: string|null }>}
+ */
+export async function installSqueezr(logger) {
+  const command = getInstallCommand("squeezr");
+
+  logger.info("Installing Squeezr...");
+
+  try {
+    const result = await runCommand("sh", ["-c", command], { timeout: 120_000 });
+
+    if (result.exitCode !== 0) {
+      const error = (result.stderr || "").trim() || `exit code ${result.exitCode}`;
+      logger.warn(`Squeezr install failed: ${error}`);
+      return { ok: false, version: null, error };
+    }
+
+    const check = await detectSqueezr();
+    if (check.available) {
+      logger.info(`Squeezr ${check.version || ""} installed successfully.`);
+      return { ok: true, version: check.version, error: null };
+    }
+
+    logger.warn("Squeezr install command succeeded but squeezr binary not found in PATH.");
+    return { ok: false, version: null, error: "Binary not found after install" };
+  } catch (err) {
+    const error = err.message || String(err);
+    logger.warn(`Squeezr install failed: ${error}`);
+    return { ok: false, version: null, error };
+  }
+}