@karajan-family/code 4.21.0

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/stack-detect.js

@@ -0,0 +1,135 @@
+/**
+ * Detects the project technology stack by scanning project files.
+ * Used by `kj init` to auto-configure roles, skills, and settings.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * Frameworks detectable from package.json dependencies.
+ * Maps dependency name -> { name, type } where type is "frontend" | "backend" | "fullstack".
+ */
+const PKG_FRAMEWORKS = {
+  react: { name: "react", type: "frontend" },
+  "react-dom": { name: "react", type: "frontend" },
+  vue: { name: "vue", type: "frontend" },
+  svelte: { name: "svelte", type: "frontend" },
+  "@angular/core": { name: "angular", type: "frontend" },
+  astro: { name: "astro", type: "frontend" },
+  next: { name: "next", type: "fullstack" },
+  nuxt: { name: "nuxt", type: "fullstack" },
+  "solid-js": { name: "solid", type: "frontend" },
+  lit: { name: "lit", type: "frontend" },
+  express: { name: "express", type: "backend" },
+  fastify: { name: "fastify", type: "backend" },
+  "@nestjs/core": { name: "nestjs", type: "backend" },
+  hono: { name: "hono", type: "backend" },
+  koa: { name: "koa", type: "backend" },
+};
+
+/**
+ * Language markers: file presence -> { language, type }.
+ */
+const LANGUAGE_FILE_MARKERS = [
+  { file: "go.mod", language: "go", type: "backend" },
+  { file: "Cargo.toml", language: "rust", type: "backend" },
+  { file: "pom.xml", language: "java", type: "backend" },
+  { file: "build.gradle", language: "java", type: "backend" },
+  { file: "build.gradle.kts", language: "kotlin", type: "backend" },
+  { file: "pyproject.toml", language: "python", type: "backend" },
+  { file: "setup.py", language: "python", type: "backend" },
+  { file: "requirements.txt", language: "python", type: "backend" },
+  { file: "Gemfile", language: "ruby", type: "backend" },
+  { file: "composer.json", language: "php", type: "backend" },
+  { file: "pubspec.yaml", language: "dart", type: "frontend" },
+  { file: "Package.swift", language: "swift", type: "backend" },
+];
+
+/**
+ * Maps framework names to skill names for auto-install suggestions.
+ */
+const FRAMEWORK_TO_SKILL = {
+  react: "react",
+  vue: "vue",
+  svelte: "svelte",
+  angular: "angular",
+  astro: "astro",
+  next: "nextjs",
+  nuxt: "vue",
+  solid: "solid",
+  lit: "lit",
+  express: "express",
+  fastify: "fastify",
+  nestjs: "nestjs",
+};
+
+/**
+ * Detect the project technology stack.
+ * @param {string} projectDir - Absolute path to project root.
+ * @returns {Promise<{frameworks: string[], language: string|null, isFrontend: boolean, isBackend: boolean, isFullstack: boolean, suggestions: {impeccable: boolean, skills: string[]}}>}
+ */
+export async function detectProjectStack(projectDir) {
+  const frameworks = new Set();
+  let language = null;
+  let hasFrontend = false;
+  let hasBackend = false;
+
+  // 1. Scan package.json for known frameworks
+  try {
+    const pkgRaw = await fs.readFile(path.join(projectDir, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    if (!language) language = "javascript";
+
+    // Check for TypeScript
+    if (allDeps.typescript || allDeps["ts-node"]) {
+      language = "typescript";
+    }
+
+    for (const [dep, info] of Object.entries(PKG_FRAMEWORKS)) {
+      if (allDeps[dep]) {
+        frameworks.add(info.name);
+        if (info.type === "frontend" || info.type === "fullstack") hasFrontend = true;
+        if (info.type === "backend" || info.type === "fullstack") hasBackend = true;
+      }
+    }
+  } catch { /* no package.json or parse error */ }
+
+  // 2. Check language file markers
+  for (const marker of LANGUAGE_FILE_MARKERS) {
+    try {
+      await fs.access(path.join(projectDir, marker.file));
+      if (!language || language === "javascript") {
+        language = marker.language;
+      }
+      if (marker.type === "frontend") hasFrontend = true;
+      if (marker.type === "backend") hasBackend = true;
+    } catch { /* file not found */ }
+  }
+
+  const frameworkList = Array.from(frameworks);
+  const isFullstack = hasFrontend && hasBackend;
+
+  // Build suggestions
+  const skills = [];
+  for (const fw of frameworkList) {
+    const skill = FRAMEWORK_TO_SKILL[fw];
+    if (skill && !skills.includes(skill)) {
+      skills.push(skill);
+    }
+  }
+
+  return {
+    frameworks: frameworkList,
+    language,
+    isFrontend: hasFrontend,
+    isBackend: hasBackend,
+    isFullstack,
+    suggestions: {
+      impeccable: hasFrontend,
+      skills,
+    },
+  };
+}

package/src/utils/stall-detector.js

@@ -0,0 +1,159 @@
+/**
+ * Stall detector for agent execution.
+ *
+ * Wraps an onOutput callback to track activity and emit heartbeat / stall
+ * warnings when an agent stops producing output for too long.
+ *
+ * Usage:
+ *   const detector = createStallDetector({ onOutput, emitter, eventBase, stage, provider, stallTimeoutMs });
+ *   // pass detector.onOutput to the agent
+ *   // when done: detector.stop();
+ */
+
+import { emitProgress, makeEvent } from "./events.js";
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;   // heartbeat every 30s
+const DEFAULT_STALL_TIMEOUT_MS      = 120_000;  // warn after 2min silence
+const DEFAULT_CRITICAL_TIMEOUT_MS   = 300_000;  // critical after 5min silence
+const DEFAULT_STALL_REPEAT_MS       = 60_000;   // repeat stall notices every 60s
+
+export function createStallDetector({
+  onOutput,
+  emitter,
+  eventBase,
+  stage,
+  provider,
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+  stallTimeoutMs      = DEFAULT_STALL_TIMEOUT_MS,
+  criticalTimeoutMs   = DEFAULT_CRITICAL_TIMEOUT_MS,
+  stallRepeatMs       = DEFAULT_STALL_REPEAT_MS,
+  maxSilenceMs        = null,
+  onMaxSilence        = null
+}) {
+  let lastActivityAt = Date.now();
+  let lineCount = 0;
+  let bytesReceived = 0;
+  let heartbeatTimer = null;
+  const startedAt = Date.now();
+  let lastStallWarnAt = 0;
+  let lastCriticalWarnAt = 0;
+  let maxSilenceTriggered = false;
+
+  function emitHeartbeat() {
+    const now = Date.now();
+    const silenceMs = now - lastActivityAt;
+    const elapsedMs = now - startedAt;
+    const shouldWarn = silenceMs >= stallTimeoutMs;
+    const shouldCritical = silenceMs >= criticalTimeoutMs;
+    const repeatWindow = Math.max(1000, Number(stallRepeatMs) || DEFAULT_STALL_REPEAT_MS);
+
+    if (shouldCritical && (now - lastCriticalWarnAt >= repeatWindow)) {
+      lastCriticalWarnAt = now;
+      emitProgress(emitter, makeEvent("agent:stall", { ...eventBase, stage }, {
+        status: "critical",
+        message: `[${stage}] Agent ${provider} unresponsive for ${Math.round(silenceMs / 1000)}s — may be hung`,
+        detail: {
+          provider,
+          silenceMs,
+          elapsedMs,
+          lineCount,
+          bytesReceived,
+          severity: "critical"
+        }
+      }));
+    } else if (shouldWarn && (now - lastStallWarnAt >= repeatWindow)) {
+      lastStallWarnAt = now;
+      emitProgress(emitter, makeEvent("agent:stall", { ...eventBase, stage }, {
+        status: "warning",
+        message: `[${stage}] Agent ${provider} silent for ${Math.round(silenceMs / 1000)}s — still waiting`,
+        detail: {
+          provider,
+          silenceMs,
+          elapsedMs,
+          lineCount,
+          bytesReceived,
+          severity: "warning"
+        }
+      }));
+    }
+
+    emitProgress(emitter, makeEvent("agent:heartbeat", { ...eventBase, stage }, {
+      message: silenceMs < stallTimeoutMs
+        ? `[${stage}] Agent ${provider} active — ${lineCount} lines, ${Math.round(elapsedMs / 1000)}s elapsed`
+        : `[${stage}] Agent ${provider} waiting — silent ${Math.round(silenceMs / 1000)}s, ${Math.round(elapsedMs / 1000)}s elapsed`,
+      detail: {
+        provider,
+        elapsedMs,
+        silenceMs,
+        lineCount,
+        bytesReceived,
+        status: silenceMs < stallTimeoutMs ? "active" : "waiting"
+      }
+    }));
+
+    const hardLimit = Number(maxSilenceMs);
+    if (!maxSilenceTriggered && Number.isFinite(hardLimit) && hardLimit > 0 && silenceMs >= hardLimit) {
+      maxSilenceTriggered = true;
+      emitProgress(emitter, makeEvent("agent:stall", { ...eventBase, stage }, {
+        status: "fail",
+        message: `[${stage}] Agent ${provider} exceeded max silence (${Math.round(hardLimit / 1000)}s)`,
+        detail: {
+          provider,
+          silenceMs,
+          elapsedMs,
+          lineCount,
+          bytesReceived,
+          severity: "fatal",
+          maxSilenceMs: hardLimit
+        }
+      }));
+      if (typeof onMaxSilence === "function") {
+        onMaxSilence({
+          provider,
+          stage,
+          silenceMs,
+          elapsedMs,
+          lineCount,
+          bytesReceived,
+          maxSilenceMs: hardLimit
+        });
+      }
+    }
+  }
+
+  // Start periodic heartbeat
+  heartbeatTimer = setInterval(emitHeartbeat, heartbeatIntervalMs);
+
+  function wrappedOnOutput(data) {
+    lastActivityAt = Date.now();
+    lineCount++;
+    bytesReceived += data.line?.length || 0;
+
+    // Forward to the original callback
+    if (onOutput) {
+      onOutput(data);
+    }
+  }
+
+  function stop() {
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+  }
+
+  function stats() {
+    return {
+      lineCount,
+      bytesReceived,
+      elapsedMs: Date.now() - startedAt,
+      lastActivityMs: Date.now() - lastActivityAt
+    };
+  }
+
+  return {
+    onOutput: wrappedOnOutput,
+    stop,
+    stats
+  };
+}

package/src/utils/status-dashboard.js

@@ -0,0 +1,254 @@
+/**
+ * Status dashboard formatter.
+ * Builds a structured terminal dashboard from session data and run-log lines.
+ */
+
+import { HU_STATUS } from "../hu/store.js";
+
+/**
+ * Status label mapping with visual indicators for terminal output.
+ * @type {Record<string, string>}
+ */
+const STATUS_LABELS = {
+  [HU_STATUS.PENDING]:       "pending",
+  [HU_STATUS.CODING]:        "coding",
+  [HU_STATUS.REVIEWING]:     "reviewing",
+  [HU_STATUS.DONE]:          "done",
+  [HU_STATUS.FAILED]:        "failed",
+  [HU_STATUS.BLOCKED]:       "blocked",
+  [HU_STATUS.CERTIFIED]:     "certified",
+  [HU_STATUS.NEEDS_CONTEXT]: "needs_ctx",
+};
+
+/**
+ * Format a millisecond duration into a human-readable string (e.g. "3m 42s").
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (!ms || ms < 0) return "0s";
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  const parts = [];
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  if (seconds > 0 || parts.length === 0) parts.push(`${seconds}s`);
+  return parts.join(" ");
+}
+
+/**
+ * Parse the current pipeline stage from log lines.
+ * @param {string[]} lines - Raw log lines.
+ * @returns {{ currentStage: string|null, lastEvent: string|null }}
+ */
+export function parseStageFromLog(lines) {
+  let currentStage = null;
+  let lastEvent = null;
+
+  for (const line of lines) {
+    const stageStart = /\[(\w+):start\]/.exec(line);
+    if (stageStart) currentStage = stageStart[1];
+
+    const stageDone = /\[(\w+):done\]|\[(\w+)\] finished/.exec(line);
+    if (stageDone) {
+      const doneName = stageDone[1] || stageDone[2];
+      if (doneName === currentStage) currentStage = "idle";
+    }
+
+    if (line.includes("[standby]") || line.includes("standby")) {
+      currentStage = "standby";
+    }
+
+    if (line.trim()) lastEvent = line.trim();
+  }
+
+  return { currentStage, lastEvent };
+}
+
+/**
+ * Format a single HU line for the dashboard.
+ * @param {object} story - HU story object.
+ * @param {boolean} isCurrent - Whether this is the currently active HU.
+ * @returns {string}
+ */
+function formatHuLine(story, isCurrent) {
+  const id = (story.id || "???").padEnd(12);
+  const rawStatus = story.status || "pending";
+  const label = STATUS_LABELS[rawStatus] || rawStatus;
+  const statusStr = `[${label}]`.padEnd(13);
+  const title = story.title || story.original?.text || "(untitled)";
+  const truncTitle = title.length > 40 ? title.slice(0, 37) + "..." : title;
+
+  let timing = "";
+  if (story.duration_ms) {
+    timing = formatDuration(story.duration_ms);
+  }
+
+  const blockedInfo = story.blocked_by?.length
+    ? ` (needs ${story.blocked_by.join(", ")})`
+    : "";
+
+  const marker = isCurrent ? "  <-- current" : "";
+  const timingStr = timing ? `  ${timing}` : "";
+
+  return `  ${id} ${statusStr} ${truncTitle}${blockedInfo}${timingStr}${marker}`;
+}
+
+/**
+ * Build a terminal dashboard string from session data and log lines.
+ *
+ * @param {object|null} sessionData - Session JSON (from session-store) or null.
+ * @param {string[]} logLines - Raw run-log lines.
+ * @param {object} [options] - Optional overrides.
+ * @param {object[]|null} [options.stories] - HU stories array (from hu batch).
+ * @returns {string}
+ */
+export function buildDashboard(sessionData, logLines, options = {}) {
+  if (!sessionData) {
+    return "No active pipeline";
+  }
+
+  const lines = [];
+  const config = sessionData.config_snapshot || {};
+  const maxIter = config.max_iterations ?? "?";
+  const status = sessionData.status || "unknown";
+
+  // Parse log for current stage info
+  const logInfo = parseStageFromLog(logLines || []);
+
+  // Determine iteration from session or log
+  const iteration = sessionData.reviewer_retry_count != null
+    ? sessionData.reviewer_retry_count + 1
+    : null;
+  const iterFromLog = parseIterationFromLog(logLines || []);
+  const displayIter = iterFromLog || iteration || "?";
+
+  // Pipeline header
+  const statusUpper = status.toUpperCase();
+  lines.push(`Pipeline: ${statusUpper} (iteration ${displayIter}/${maxIter})`);
+
+  // Duration
+  const duration = computeDuration(sessionData);
+  lines.push(`Duration: ${formatDuration(duration)}`);
+
+  // Agent info
+  const coderProvider = config.coder?.provider || config.roles?.coder?.provider || "?";
+  const reviewerProvider = config.reviewer?.provider || config.roles?.reviewer?.provider || "?";
+  lines.push(`Agent: ${coderProvider} (coder) / ${reviewerProvider} (reviewer)`);
+
+  // HU stories section
+  const stories = options.stories || [];
+  if (stories.length > 0) {
+    lines.push("");
+    lines.push("HUs:");
+
+    // Determine which story is currently being worked on
+    const currentStory = stories.find(s =>
+      s.status === HU_STATUS.CODING || s.status === HU_STATUS.REVIEWING
+    );
+
+    for (const story of stories) {
+      const isCurrent = currentStory && story.id === currentStory.id;
+      lines.push(formatHuLine(story, isCurrent));
+    }
+  }
+
+  // Current stage and last event
+  lines.push("");
+  const stage = logInfo.currentStage || "idle";
+  const iterSuffix = displayIter !== "?" ? ` (iteration ${displayIter})` : "";
+  lines.push(`Current stage: ${stage}${iterSuffix}`);
+
+  if (logInfo.lastEvent) {
+    // Truncate last event for display
+    const maxLen = 120;
+    const event = logInfo.lastEvent.length > maxLen
+      ? logInfo.lastEvent.slice(0, maxLen - 3) + "..."
+      : logInfo.lastEvent;
+    lines.push(`Last event: ${event}`);
+  }
+
+  // Errors
+  if (sessionData.deferred_issues?.length) {
+    lines.push("");
+    lines.push(`Deferred issues: ${sessionData.deferred_issues.length}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build a structured JSON response for MCP consumers.
+ *
+ * @param {object|null} sessionData - Session JSON or null.
+ * @param {string[]} logLines - Raw run-log lines.
+ * @param {object} [options] - Optional overrides.
+ * @param {object[]|null} [options.stories] - HU stories array.
+ * @returns {object}
+ */
+export function buildDashboardJson(sessionData, logLines, options = {}) {
+  if (!sessionData) {
+    return { ok: false, message: "No active pipeline" };
+  }
+
+  const config = sessionData.config_snapshot || {};
+  const logInfo = parseStageFromLog(logLines || []);
+  const iterFromLog = parseIterationFromLog(logLines || []);
+  const iteration = iterFromLog
+    || (sessionData.reviewer_retry_count != null ? sessionData.reviewer_retry_count + 1 : null);
+
+  const stories = (options.stories || []).map(s => ({
+    id: s.id,
+    status: s.status || "pending",
+    title: s.title || s.original?.text || null,
+    blocked_by: s.blocked_by || [],
+    duration_ms: s.duration_ms || null,
+  }));
+
+  return {
+    ok: true,
+    pipeline: {
+      status: sessionData.status || "unknown",
+      iteration: iteration || null,
+      maxIterations: config.max_iterations ?? null,
+      duration_ms: computeDuration(sessionData),
+      coder: config.coder?.provider || config.roles?.coder?.provider || null,
+      reviewer: config.reviewer?.provider || config.roles?.reviewer?.provider || null,
+    },
+    hus: stories,
+    currentStage: logInfo.currentStage || "idle",
+    lastEvent: logInfo.lastEvent || null,
+  };
+}
+
+/**
+ * Parse iteration number from log lines.
+ * @param {string[]} lines
+ * @returns {number|null}
+ */
+function parseIterationFromLog(lines) {
+  let iteration = null;
+  for (const line of lines) {
+    const m = /[Ii]teration\s+(\d+)/.exec(line);
+    if (m) iteration = Number.parseInt(m[1], 10);
+  }
+  return iteration;
+}
+
+/**
+ * Compute pipeline duration in milliseconds from session timestamps.
+ * @param {object} sessionData
+ * @returns {number}
+ */
+function computeDuration(sessionData) {
+  const created = sessionData.created_at;
+  if (!created) return 0;
+  const start = new Date(created).getTime();
+  const now = sessionData.updated_at
+    ? new Date(sessionData.updated_at).getTime()
+    : Date.now();
+  return Math.max(0, now - start);
+}

package/src/utils/task-file.js

@@ -0,0 +1,109 @@
+/**
+ * Load a task description from a file (.md / .txt / .markdown / any plain text).
+ *
+ * Motivation: for anything beyond a one-line task, writing a `kj run "long
+ * multi-paragraph prompt ..."` becomes painful — escaping quotes, losing
+ * markdown formatting, no history. `kj run --task-file my-task.md` reads the
+ * file's contents and uses them as the task description. Same for `kj plan`,
+ * `kj audit`, `kj code`, and their MCP counterparts (via the `taskFile`
+ * argument).
+ *
+ * Behaviour:
+ *   - `taskFile` may be relative (resolved against `process.cwd()` by default,
+ *     or against `projectDir` if supplied) or absolute.
+ *   - Accepts any text file; markdown is the expected common case but we do
+ *     not require a specific extension.
+ *   - Trimmed of leading/trailing whitespace so agents don't get empty lines
+ *     around the task.
+ *   - `maxBytes` (default 256 KiB) guards against accidentally passing a huge
+ *     file (log dumps, PDFs). Agents choke on very long prompts anyway.
+ *   - Precedence with the positional `task` arg is decided by the caller:
+ *     this helper only loads, never merges. Convention used across commands:
+ *     when BOTH are provided, the positional task wins and the file is a
+ *     fallback — with a log warning so the user notices.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_TASK_FILE_MAX_BYTES = 256 * 1024;
+
+/**
+ * @param {string} filePath                - relative or absolute
+ * @param {Object} [opts]
+ * @param {string} [opts.projectDir]       - base dir for relative paths; defaults to process.cwd()
+ * @param {number} [opts.maxBytes]         - size cap; default 256 KiB
+ * @returns {Promise<string>}              - the trimmed file contents (task text)
+ * @throws                                 - Error with a user-readable message when the file is
+ *                                           missing, unreadable, empty, or over the size cap.
+ */
+export async function readTaskFile(filePath, opts = {}) {
+  if (!filePath || typeof filePath !== "string") {
+    throw new Error("readTaskFile: path must be a non-empty string");
+  }
+  const { projectDir, maxBytes = DEFAULT_TASK_FILE_MAX_BYTES } = opts;
+  const base = projectDir || process.cwd();
+  const resolved = path.isAbsolute(filePath) ? filePath : path.resolve(base, filePath);
+
+  let stat;
+  try {
+    stat = await fs.stat(resolved);
+  } catch (err) {
+    throw new Error(`Task file not found: ${resolved} (${err.code || err.message})`, { cause: err });
+  }
+  if (!stat.isFile()) {
+    throw new Error(`Task file is not a regular file: ${resolved}`);
+  }
+  if (stat.size > maxBytes) {
+    const kb = Math.round(stat.size / 1024);
+    const capKb = Math.round(maxBytes / 1024);
+    throw new Error(
+      `Task file is too large: ${resolved} (${kb} KiB > ${capKb} KiB cap). ` +
+      `Summarise the task or raise the limit with the caller's maxBytes option.`
+    );
+  }
+
+  const raw = await fs.readFile(resolved, "utf8");
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error(`Task file is empty (or whitespace-only): ${resolved}`);
+  }
+  return trimmed;
+}
+
+/**
+ * Resolve the task text a command should use, given both positional `task`
+ * and an optional `taskFile`. Single source of truth for precedence across
+ * CLI and MCP entry points.
+ *
+ * Rules:
+ *   - Neither provided → throw (caller decides the UX; typically propagates).
+ *   - Only `task` → returns it, untouched.
+ *   - Only `taskFile` → reads and returns it.
+ *   - Both → `task` wins; emits a warning through `logger.warn` (if given).
+ *
+ * @param {Object} args
+ * @param {string|undefined} args.task
+ * @param {string|undefined} args.taskFile
+ * @param {string} [args.projectDir]
+ * @param {Object} [args.logger]             - optional; uses `logger.warn(msg)` only
+ * @returns {Promise<string>}
+ */
+export async function resolveTaskInput({ task, taskFile, projectDir, logger } = {}) {
+  const hasTask = typeof task === "string" && task.trim().length > 0;
+  const hasFile = typeof taskFile === "string" && taskFile.trim().length > 0;
+
+  if (!hasTask && !hasFile) {
+    throw new Error("No task provided. Pass a task argument or --task-file <path>.");
+  }
+  if (hasTask && hasFile) {
+    logger?.warn?.(
+      `Both task and --task-file given; using the positional task and ignoring file: ${taskFile}`
+    );
+    return task.trim();
+  }
+  if (hasFile) {
+    return readTaskFile(taskFile, { projectDir });
+  }
+  return task.trim();
+}