karajan-code 3.1.0 → 3.3.0

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

package/src/utils/telemetry.js

@@ -26,6 +26,49 @@ export function buildTelemetryPayload(eventName, data = {}) {
   };
 }
 
+/**
+ * Φ0-H (KJC-TSK-0526): aggregate cache-hit ratio per role from the budget
+ * summary the orchestrator already builds. Returns `{ cached_pct_coder,
+ * cached_pct_reviewer, cached_pct_total }` with values rounded to one
+ * decimal, or `null` per slot when there is no measurable input (rather
+ * than `0`, so the backend can distinguish "no cache" from "no signal").
+ *
+ * Provider-agnostic by design: the BudgetTracker entries already
+ * normalise `cached_tokens` for Anthropic (`cache_read_input_tokens`),
+ * OpenAI / Codex (`prompt_tokens_details.cached_tokens`), Gemini
+ * (`cachedContentTokenCount`) and the LiteLLM-routed providers
+ * (aider, opencode), so this helper does not need to know which
+ * provider produced the run.
+ *
+ * @param {{ breakdown_by_role?: object, total_cached_tokens?: number } | null | undefined} summary
+ * @returns {{ cached_pct_coder: number|null, cached_pct_reviewer: number|null, cached_pct_total: number|null }}
+ */
+export function computeCachedPct(summary) {
+  const empty = { cached_pct_coder: null, cached_pct_reviewer: null, cached_pct_total: null };
+  if (!summary || typeof summary !== "object") return empty;
+  const ratio = (cached, tokensIn) => {
+    const c = Number(cached);
+    const t = Number(tokensIn);
+    if (!Number.isFinite(c) || !Number.isFinite(t) || t <= 0 || c < 0) return null;
+    return Math.round((c / t) * 1000) / 10;
+  };
+  const byRole = summary.breakdown_by_role || {};
+  const coder = byRole.coder || null;
+  const reviewer = byRole.reviewer || null;
+  let totalCached = 0;
+  let totalIn = 0;
+  for (const role of Object.keys(byRole)) {
+    const r = byRole[role];
+    totalCached += Number(r?.cached_tokens || 0);
+    totalIn += Number(r?.tokens_in || 0);
+  }
+  return {
+    cached_pct_coder: coder ? ratio(coder.cached_tokens, coder.tokens_in) : null,
+    cached_pct_reviewer: reviewer ? ratio(reviewer.cached_tokens, reviewer.tokens_in) : null,
+    cached_pct_total: ratio(totalCached, totalIn)
+  };
+}
+
 /**
  * Send an anonymous telemetry event. Non-blocking, fire-and-forget.
  * Never throws, never blocks the pipeline.