@karajan-family/code 4.21.0

package/src/utils/model-selector.js

@@ -0,0 +1,107 @@
+const DEFAULT_MODEL_TIERS = {
+  claude: { trivial: "haiku", simple: "haiku", medium: "sonnet", complex: "opus" },
+  codex: { trivial: "o4-mini", simple: "o4-mini", medium: "o4-mini", complex: "o3" },
+  gemini: { trivial: "gemini-2.0-flash", simple: "gemini-2.0-flash", medium: "gemini-2.5-pro", complex: "gemini-2.5-pro" },
+  aider: { trivial: null, simple: null, medium: null, complex: null }
+};
+
+const DEFAULT_ROLE_OVERRIDES = {
+  reviewer: { trivial: "medium", simple: "medium" },
+  triage: { medium: "simple", complex: "simple" }
+};
+
+const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
+
+export function getDefaultModelTiers() {
+  return structuredClone(DEFAULT_MODEL_TIERS);
+}
+
+export function getDefaultRoleOverrides() {
+  return structuredClone(DEFAULT_ROLE_OVERRIDES);
+}
+
+export function resolveModelForRole({ role, provider, level, tierMap, roleOverrides }) {
+  if (!provider || !level || !VALID_LEVELS.has(level)) return null;
+
+  const tiers = tierMap || DEFAULT_MODEL_TIERS;
+  const providerTiers = tiers[provider];
+  if (!providerTiers) return null;
+
+  const overrides = roleOverrides || DEFAULT_ROLE_OVERRIDES;
+  const roleOvr = overrides[role];
+
+  let effectiveLevel = level;
+  if (roleOvr?.[level]) {
+    const mappedLevel = roleOvr[level];
+    if (VALID_LEVELS.has(mappedLevel)) {
+      effectiveLevel = mappedLevel;
+    }
+  }
+
+  return providerTiers[effectiveLevel] || null;
+}
+
+export function selectModelsForRoles({ level, config, roles }) {
+  if (!level || !VALID_LEVELS.has(level)) {
+    return { modelOverrides: {}, reasoning: "No valid triage level provided" };
+  }
+
+  const modelSelection = config?.model_selection || {};
+  const userTiers = modelSelection.tiers || {};
+  const userRoleOverrides = modelSelection.role_overrides || {};
+
+  const mergedTiers = { ...getDefaultModelTiers() };
+  for (const [provider, levels] of Object.entries(userTiers)) {
+    mergedTiers[provider] = { ...mergedTiers[provider], ...levels };
+  }
+
+  const mergedRoleOverrides = { ...getDefaultRoleOverrides() };
+  for (const [role, levels] of Object.entries(userRoleOverrides)) {
+    mergedRoleOverrides[role] = { ...mergedRoleOverrides[role], ...levels };
+  }
+
+  const allRoles = roles || Object.keys(config?.roles || {});
+  const modelOverrides = {};
+  const details = [];
+
+  for (const role of allRoles) {
+    const roleConfig = config?.roles?.[role];
+    if (!roleConfig) continue;
+
+    if (roleConfig.model) {
+      details.push(`${role}: skipped (explicit model "${roleConfig.model}")`);
+      continue;
+    }
+
+    if (roleConfig.disabled) {
+      details.push(`${role}: skipped (disabled)`);
+      continue;
+    }
+
+    const provider = roleConfig.provider;
+    if (!provider) {
+      details.push(`${role}: skipped (no provider)`);
+      continue;
+    }
+
+    const model = resolveModelForRole({
+      role,
+      provider,
+      level,
+      tierMap: mergedTiers,
+      roleOverrides: mergedRoleOverrides
+    });
+
+    if (model) {
+      modelOverrides[role] = model;
+      details.push(`${role}: ${model} (level=${level}, provider=${provider})`);
+    } else {
+      details.push(`${role}: no model for provider "${provider}"`);
+    }
+  }
+
+  return {
+    modelOverrides,
+    reasoning: `Smart model selection (level=${level}): ${details.join("; ")}`
+  };
+}

package/src/utils/os-detect.js

@@ -0,0 +1,79 @@
+import os from "node:os";
+
+/**
+ * Detect platform and return OS-appropriate install commands.
+ */
+export function getPlatform() {
+  const platform = os.platform();
+  if (platform === "win32") return "windows";
+  if (platform === "darwin") return "macos";
+  return "linux";
+}
+
+const INSTALL_COMMANDS = {
+  rtk: {
+    macos: "brew install rtk && rtk init --global",
+    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",
+    windows: "npm install -g @anthropic-ai/claude-code"
+  },
+  codex: {
+    macos: "npm install -g @openai/codex",
+    linux: "npm install -g @openai/codex",
+    windows: "npm install -g @openai/codex"
+  },
+  gemini: {
+    macos: "npm install -g @google/gemini-cli",
+    linux: "npm install -g @google/gemini-cli",
+    windows: "npm install -g @google/gemini-cli"
+  },
+  aider: {
+    macos: "pipx install aider-chat",
+    linux: "pipx install aider-chat || pip3 install aider-chat",
+    windows: "pip install aider-chat"
+  },
+  opencode: {
+    macos: "curl -fsSL https://opencode.ai/install | bash",
+    linux: "curl -fsSL https://opencode.ai/install | bash",
+    windows: "See https://github.com/nicepkg/opencode for Windows install"
+  },
+  qwen: {
+    macos: "npm install -g @qwen-code/qwen-code",
+    linux: "npm install -g @qwen-code/qwen-code",
+    windows: "npm install -g @qwen-code/qwen-code"
+  },
+  agy: {
+    macos: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+    linux: "curl -fsSL https://antigravity.google/cli/install.sh | bash",
+    windows: "irm https://antigravity.google/cli/install.ps1 | iex"
+  },
+  copilot: {
+    macos: "npm install -g @github/copilot",
+    linux: "npm install -g @github/copilot",
+    windows: "npm install -g @github/copilot"
+  },
+  docker: {
+    macos: "brew install --cask docker",
+    linux: "sudo apt install docker.io docker-compose-v2 (or see https://docs.docker.com/engine/install/)",
+    windows: "Download Docker Desktop from https://www.docker.com/products/docker-desktop/"
+  }
+};
+
+export function getInstallCommand(tool) {
+  const platform = getPlatform();
+  return INSTALL_COMMANDS[tool]?.[platform] || INSTALL_COMMANDS[tool]?.linux || `Install ${tool} manually`;
+}

package/src/utils/paths.js

@@ -0,0 +1,13 @@
+// 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,
+  getPromptsDir,
+} from "karajan-core/paths";

package/src/utils/pending-user-action.js

@@ -0,0 +1,95 @@
+/**
+ * Stop-on-sudo policy (KJC-TSK-0659). When a tool cannot be installed
+ * automatically (sudo needed, no package-manager route, or the attempt
+ * failed), kj must NOT continue degraded — a RAG with 0 chunks because
+ * Docker was missing helps nobody. Instead: emit ONE block with the exact
+ * commands for this machine's OS and exit with a distinctive code so a
+ * driving agent stops, shows the block, and waits for the user.
+ */
+
+export const PENDING_EXIT_CODE = 3;
+
+const PENDING = new Set(["manual", "failed", "needs-user"]);
+
+// Exact per-OS commands for the tools kj cannot install unattended.
+// Multiple lines when the route depends on the distro/package manager.
+const OS_COMMANDS = {
+  docker: {
+    linux: ["sudo apt-get install -y docker.io   # Debian/Ubuntu", "sudo dnf install -y docker          # Fedora/RHEL"],
+    darwin: ["brew install --cask docker   # Docker Desktop, then open it once"],
+    win32: ["winget install Docker.DockerDesktop", "wsl --install   # if WSL2 is not set up yet"],
+  },
+  git: {
+    linux: ["sudo apt-get install -y git   # Debian/Ubuntu", "sudo dnf install -y git        # Fedora/RHEL"],
+    darwin: ["brew install git   # or: xcode-select --install"],
+    win32: ["winget install Git.Git"],
+  },
+  semgrep: {
+    // PEP 668 (#1256): system Python is externally managed on modern
+    // distros — pipx comes from the distro package manager, never from pip.
+    linux: ["sudo apt update && sudo apt install -y pipx && pipx install semgrep   # Debian/Ubuntu", "sudo dnf install -y pipx && pipx install semgrep   # Fedora/RHEL"],
+    darwin: ["brew install semgrep"],
+    win32: ["python -m pip install --user semgrep"],
+  },
+  "osv-scanner": {
+    linux: ["go install github.com/google/osv-scanner/v2/cmd/osv-scanner@v2   # or download from GitHub releases"],
+    darwin: ["brew install osv-scanner"],
+    win32: ["winget install Google.OSVScanner   # or download from GitHub releases"],
+  },
+  lighthouse: {
+    linux: ["npm install -g lighthouse"],
+    darwin: ["npm install -g lighthouse"],
+    win32: ["npm install -g lighthouse"],
+  },
+  ollama: {
+    linux: ["curl -fsSL https://ollama.com/install.sh | sh   # official installer (uses sudo)", "ollama pull nomic-embed-text"],
+    darwin: ["brew install ollama && brew services start ollama", "ollama pull nomic-embed-text"],
+    win32: ["winget install Ollama.Ollama", "ollama pull nomic-embed-text"],
+  },
+};
+
+/** Exact commands to install `tool` on `platform` (empty when unknown). */
+export function osCommandsFor(tool, platform = process.platform) {
+  return OS_COMMANDS[tool]?.[platform] ?? [];
+}
+
+/**
+ * Results that require the USER's hands. `manual`/`failed`/`needs-user`
+ * always qualify; `declined` only when nobody actually declined — a non-TTY
+ * run without --yes auto-answers the default, which for sudo installs is
+ * "no". A real interactive decline stays the user's own decision.
+ */
+export function collectPending(results, { tty = Boolean(process.stdin.isTTY), yes = false } = {}) {
+  return results.filter((r) => PENDING.has(r.action) || (r.action === "declined" && !tty && !yes));
+}
+
+/** The PENDING USER ACTION block: exact commands for THIS OS, then wait. */
+export function renderPendingBlock(pending, { platform = process.platform, retry = "kj install-tools" } = {}) {
+  const lines = [
+    "════ PENDING USER ACTION ════════════════════════════════════════",
+    "kj could not finish this install by itself (sudo or a platform",
+    "installer is required). Karajan needs a COMPLETE environment —",
+    "do not continue degraded.",
+    "",
+    "Run in YOUR terminal:",
+    "",
+  ];
+  for (const r of pending) {
+    const why = r.error ? `install failed: ${r.error}` : r.reason || "no automatic route on this machine";
+    lines.push(`  ▸ ${r.tool}  (${why})`);
+    const os = osCommandsFor(r.tool, platform);
+    const own = r.commands ?? (r.command ? [r.command] : null) ?? (r.suggested ? [r.suggested] : null);
+    // A FAILED install must not be re-suggested verbatim (#1256: the pip
+    // route that just broke) — the curated per-OS route goes first there.
+    const commands = (r.action === "failed" ? (os.length > 0 ? os : own) : (own ?? (os.length > 0 ? os : null)))
+      ?? [`see ${r.manualUrl || "the tool's install docs"}`];
+    for (const c of commands) lines.push(`      ${c}`);
+    lines.push("");
+  }
+  lines.push(
+    `When done, re-run: ${retry}`,
+    "Agents: STOP here, show this block to your user, and WAIT for their",
+    `go-ahead. Exit code ${PENDING_EXIT_CODE} means "pending user action" — never proceed past it.`,
+  );
+  return lines.join("\n");
+}

package/src/utils/port-check.js

@@ -0,0 +1,6 @@
+// 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/port-occupant.js

@@ -0,0 +1,96 @@
+/**
+ * Detect which process is holding a TCP port. Cross-platform best-effort:
+ *   - Linux/macOS: try `lsof -iTCP:PORT -sTCP:LISTEN -n -P -Fpcn` (parsable),
+ *     fall back to `ss -tlnp` for Linux-only pid detection.
+ *   - Windows: `netstat -ano` + `tasklist` to resolve image name.
+ *
+ * Returns null if the port is free or we cannot determine the occupant.
+ * Never throws — designed to enrich diagnostic messages, not to gate logic.
+ */
+
+import { runCommand } from "./process.js";
+import { escapeRegExp } from "./escape-regexp.js";
+
+/**
+ * @typedef {Object} PortOccupant
+ * @property {number} port
+ * @property {number|null} pid
+ * @property {string|null} command      - process name ("karajan-sonarqube", "node", etc.)
+ * @property {string} raw               - raw tool output for debugging
+ */
+
+/**
+ * @param {number} port
+ * @returns {Promise<PortOccupant|null>}
+ */
+export async function getPortOccupant(port) {
+  if (process.platform === "win32") {
+    return detectWindows(port);
+  }
+  const byLsof = await detectLsof(port);
+  if (byLsof) return byLsof;
+  return detectSs(port);
+}
+
+async function detectLsof(port) {
+  try {
+    const res = await runCommand("lsof", [
+      `-iTCP:${port}`,
+      "-sTCP:LISTEN",
+      "-n",
+      "-P",
+      "-Fpcn",
+    ]);
+    if (res.exitCode !== 0 || !res.stdout.trim()) return null;
+    // Format: lines starting with p<pid>, c<command>, n<name>
+    const lines = res.stdout.split("\n").filter(Boolean);
+    let pid = null;
+    let command = null;
+    for (const line of lines) {
+      if (line.startsWith("p")) pid = Number(line.slice(1)) || null;
+      else if (line.startsWith("c")) command = line.slice(1) || null;
+    }
+    return { port, pid, command, raw: res.stdout };
+  } catch {
+    return null;
+  }
+}
+
+async function detectSs(port) {
+  try {
+    const res = await runCommand("ss", ["-tlnpH", `sport = :${port}`]);
+    if (res.exitCode !== 0 || !res.stdout.trim()) return null;
+    // Example line: LISTEN 0 511 0.0.0.0:4000 0.0.0.0:* users:(("node",pid=12345,fd=20))
+    const match = res.stdout.match(/users:\(\("([^"]+)",pid=(\d+)/);
+    if (!match) return null;
+    return { port, pid: Number(match[2]), command: match[1], raw: res.stdout };
+  } catch {
+    return null;
+  }
+}
+
+async function detectWindows(port) {
+  try {
+    const netstat = await runCommand("netstat", ["-ano"]);
+    if (netstat.exitCode !== 0) return null;
+    const line = netstat.stdout
+      .split(/\r?\n/)
+      .find((l) => l.match(new RegExp(`:${escapeRegExp(port)}\\s+.*LISTENING`)));
+    if (!line) return null;
+    const parts = line.trim().split(/\s+/);
+    const pid = Number(parts[parts.length - 1]) || null;
+    if (!pid) return { port, pid: null, command: null, raw: line };
+    const tasklist = await runCommand("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"]);
+    const command = parseTasklist(tasklist.stdout);
+    return { port, pid, command, raw: `${line}\n${tasklist.stdout}` };
+  } catch {
+    return null;
+  }
+}
+
+function parseTasklist(stdout) {
+  const line = stdout.split(/\r?\n/).find(Boolean);
+  if (!line) return null;
+  const match = line.match(/^"([^"]+)"/);
+  return match ? match[1] : null;
+}

package/src/utils/pricing.js

@@ -0,0 +1,29 @@
+import { buildDefaultPricingTable } from "../agents/model-registry.js";
+
+export const DEFAULT_MODEL_PRICING = buildDefaultPricingTable();
+
+export function calculateUsageCostUsd({ provider, model, tokens_in, tokens_out, pricing }) {
+  const table = pricing || DEFAULT_MODEL_PRICING;
+  
+  let entry = table[model];
+
+  if (!entry && provider && model) {
+    entry = table[`${provider}/${model}`];
+  }
+
+  if (!entry && model && model.includes("/")) {
+    const [, actualModel] = model.split("/");
+    entry = table[actualModel];
+  }
+
+  if (!entry) return 0;
+
+  const inputCost = (tokens_in * entry.input_per_million) / 1_000_000;
+  const outputCost = (tokens_out * entry.output_per_million) / 1_000_000;
+  return inputCost + outputCost;
+}
+
+export function mergePricing(defaults, overrides) {
+  if (!overrides || typeof overrides !== "object") return { ...defaults };
+  return { ...defaults, ...overrides };
+}

package/src/utils/process.js

@@ -0,0 +1,4 @@
+// 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/project-detect.js

@@ -0,0 +1,160 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+// --- JS/TS ---
+const JS_FRAMEWORKS = ["vitest", "jest", "@jest/core", "mocha", "ava", "tap", "playwright", "@playwright/test"];
+const JS_CONFIG_FILES = [
+  "vitest.config.js", "vitest.config.ts",
+  "jest.config.js", "jest.config.ts", "jest.config.mjs",
+  ".mocharc.yml", ".mocharc.json",
+  "playwright.config.js", "playwright.config.ts"
+];
+
+// --- Multi-language project markers ---
+const LANGUAGE_MARKERS = [
+  // Java / Kotlin (Maven)
+  { file: "pom.xml", framework: "junit", language: "java" },
+  // Java / Kotlin (Gradle)
+  { file: "build.gradle", framework: "junit", language: "java" },
+  { file: "build.gradle.kts", framework: "junit", language: "kotlin" },
+  // Python
+  { file: "pytest.ini", framework: "pytest", language: "python" },
+  { file: "pyproject.toml", framework: "pytest", language: "python" },
+  { file: "setup.py", framework: "pytest", language: "python" },
+  { file: "setup.cfg", framework: "pytest", language: "python" },
+  { file: "tox.ini", framework: "pytest", language: "python" },
+  // Go
+  { file: "go.mod", framework: "go-test", language: "go" },
+  // Rust
+  { file: "Cargo.toml", framework: "cargo-test", language: "rust" },
+  // C# / .NET
+  { file: "*.csproj", glob: true, framework: "dotnet-test", language: "csharp" },
+  { file: "*.sln", glob: true, framework: "dotnet-test", language: "csharp" },
+  // Ruby
+  { file: "Gemfile", framework: "rspec", language: "ruby" },
+  { file: ".rspec", framework: "rspec", language: "ruby" },
+  // PHP
+  { file: "phpunit.xml", framework: "phpunit", language: "php" },
+  { file: "phpunit.xml.dist", framework: "phpunit", language: "php" },
+  // Swift
+  { file: "Package.swift", framework: "xctest", language: "swift" },
+  // Dart / Flutter
+  { file: "pubspec.yaml", framework: "dart-test", language: "dart" },
+];
+
+// --- Infra (INF-B, KJC-TSK-0759) ---
+// Checked AFTER app-language markers: a mixed repo keeps its app framework.
+// Only unequivocal markers — a stray .yaml never classifies as infra.
+const INFRA_MARKERS = [
+  { file: "*.tf", glob: true, framework: "terraform-validate", language: "infra" },
+  { file: "terraform", framework: "terraform-validate", language: "infra" },
+  { file: "Chart.yaml", framework: "helm-lint", language: "infra" },
+  { file: "kustomization.yaml", framework: "kustomize-build", language: "infra" },
+  { file: "kustomization.yml", framework: "kustomize-build", language: "infra" },
+  { file: "ansible.cfg", framework: "ansible-lint", language: "infra" },
+];
+
+/** Test file patterns per language (used by TDD policy). */
+export const TEST_PATTERNS_BY_LANGUAGE = {
+  javascript: ["/tests/", "/__tests__/", ".test.", ".spec."],
+  java:       ["/src/test/", "/test/", "Test.java", "Tests.java", "IT.java"],
+  kotlin:     ["/src/test/", "/test/", "Test.kt", "Tests.kt", "/src/androidTest/"],
+  python:     ["/tests/", "/test/", "test_", "_test.py", "tests.py"],
+  go:         ["_test.go"],
+  rust:       ["/tests/", "#[test]", "#[cfg(test)]"],
+  csharp:     ["/Tests/", "/Test/", "Tests.cs", "Test.cs", ".Tests/"],
+  ruby:       ["/spec/", "/test/", "_spec.rb", "_test.rb"],
+  php:        ["/tests/", "/test/", "Test.php"],
+  swift:      ["/Tests/", "Tests.swift"],
+  dart:       ["/test/", "_test.dart"],
+  infra:      ["/tests/", "/test/", "_test."],
+};
+
+function frameworkFromConfig(filename) {
+  if (filename.startsWith("vitest")) return "vitest";
+  if (filename.startsWith("jest")) return "jest";
+  if (filename.startsWith(".mocha")) return "mocha";
+  return "playwright";
+}
+
+/**
+ * Detect if the project has a test framework configured.
+ * Checks JS (package.json), then multi-language project markers.
+ * @param {string} cwd - Project root
+ * @returns {Promise<{hasTests: boolean, framework: string|null, language: string|null}>}
+ */
+export async function detectTestFramework(cwd = process.cwd()) {
+  // 1. JS/TS: check package.json
+  try {
+    const pkgRaw = await fs.readFile(path.join(cwd, "package.json"), "utf8");
+    const pkg = JSON.parse(pkgRaw);
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+    for (const fw of JS_FRAMEWORKS) {
+      if (allDeps[fw]) {
+        return { hasTests: true, framework: fw, language: "javascript" };
+      }
+    }
+  } catch { /* no package.json or parse error */ }
+
+  // 2. JS/TS: check config files
+  for (const cf of JS_CONFIG_FILES) {
+    try {
+      await fs.access(path.join(cwd, cf));
+      return { hasTests: true, framework: frameworkFromConfig(cf), language: "javascript" };
+    } catch { /* not found */ }
+  }
+
+  // 3. Multi-language: check project markers
+  const lang = await matchMarkers(cwd, LANGUAGE_MARKERS);
+  if (lang) return lang;
+
+  // 4. Infra (INF-B): terraform/helm/kustomize/ansible have their own suite.
+  const infra = await matchMarkers(cwd, INFRA_MARKERS);
+  if (infra) return infra;
+
+  return { hasTests: false, framework: null, language: null };
+}
+
+/**
+ * True when the project carries unequivocal infra markers (terraform, helm,
+ * kustomize, ansible) — regardless of the app framework the repo may also
+ * have. Used by INF-C's audit collector to gate the checkov scan.
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+export async function detectInfraMarkers(cwd = process.cwd()) {
+  return Boolean(await matchMarkers(cwd, INFRA_MARKERS));
+}
+
+async function matchMarkers(cwd, markers) {
+  for (const marker of markers) {
+    try {
+      if (marker.glob) {
+        const entries = await fs.readdir(cwd);
+        const ext = marker.file.replaceAll("*", "");
+        if (entries.some((e) => e.endsWith(ext))) {
+          return { hasTests: true, framework: marker.framework, language: marker.language };
+        }
+      } else {
+        await fs.access(path.join(cwd, marker.file));
+        return { hasTests: true, framework: marker.framework, language: marker.language };
+      }
+    } catch { /* not found */ }
+  }
+  return null;
+}
+
+/**
+ * Detect if SonarQube is configured for this project.
+ * @param {string} cwd - Project root
+ * @returns {Promise<{configured: boolean}>}
+ */
+export async function detectSonarConfig(cwd = process.cwd()) {
+  try {
+    await fs.access(path.join(cwd, "sonar-project.properties"));
+    return { configured: true };
+  } catch { /* sonar-project.properties does not exist */
+    return { configured: false };
+  }
+}

package/src/utils/prompt-project-name.js

@@ -0,0 +1,35 @@
+/**
+ * PR-H: ask the user "Nombre del proyecto?" before saving a plan.
+ *
+ * The user's words: "El nombre del board debería de deducirse del
+ * cwd o del nombre del plan, pero no darlo por hecho, preguntar al
+ * usuario siempre, por si quiere cambiarlo."
+ *
+ * Pre-fills the prompt with the suggested name (derived from the
+ * task / cwd) so accepting the default is one ENTER away. Returns
+ * the trimmed answer; falls back to the default when the user just
+ * hits ENTER (empty input).
+ *
+ * Caller is responsible for skipping this when stdin/stdout are not
+ * a TTY, when --yes is set, or when --json is set.
+ */
+
+import readline from "node:readline";
+
+/**
+ * @param {string} defaultName — pre-filled suggestion shown in [brackets]
+ * @returns {Promise<string>} the user's answer (defaults to defaultName)
+ */
+export async function promptProjectName(defaultName) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const fallback = String(defaultName || "").trim();
+  const hint = fallback ? ` [${fallback}]` : "";
+  return new Promise((resolve) => {
+    rl.question(`Nombre del proyecto${hint}: `, (answer) => {
+      rl.close();
+      const trimmed = String(answer || "").trim();
+      resolve(trimmed || fallback);
+    });
+    rl.on("SIGINT", () => { rl.close(); resolve(fallback); });
+  });
+}