cairn-ai 0.2.6 → 0.2.7

package/scripts/cairn-state.mjs

@@ -1,130 +1,13 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { evaluateStop, isGoalOwnedBySession, readGoalState, reconcileWorktreeState } from "./cairn-goal.mjs";
+import { contextResult, foreignSessionContextResult, prependContext } from "./cairn-state-context.mjs";
+import { continuationReason, stopAllowedMessage, stopHookOutput } from "./cairn-state-hook.mjs";
+import { initializeProject } from "./cairn-state-init.mjs";
+import { evaluateStop, isGoalOwnedBySession, reconcileWorktreeState } from "./cairn-goal.mjs";
 import { resolveRepoRoot } from "./cairn-paths.mjs";
-import { assertNoSymlinkComponents, safeMkdir, safeWriteFile } from "./cairn-safe-fs.mjs";
 
-const memoryTemplate = `# MEMORY
-
-This file is a short index of persistent repository knowledge.
-
-## Domain Knowledge
-
-- Link detailed notes under \`docs/memory/\`.
-
-## Policy
-
-- Prefer precise repository exploration before implementation.
-- Preserve proper nouns, file names, variable names, service names, alert names, MCP tool names, and agent names exactly as written.
-- Read only the detailed memory files needed for the current task.
-- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
-
-## Update Rules
-
-- Keep root files short.
-- Move detailed domain knowledge to \`docs/memory/<domain>.md\`.
-- Record facts with source paths, commands, and observed behavior.
-`;
-
-const memoryTemplateKo = `# MEMORY
-
-이 파일은 지속적으로 필요한 저장소 지식의 짧은 색인입니다.
-
-## Domain Knowledge
-
-- 자세한 기록은 \`docs/memory/\` 아래에 연결합니다.
-
-## Policy
-
-- 구현 전에는 저장소를 정확히 탐색합니다.
-- 고유명사, 파일 이름, 변수 이름, 서비스 이름, 알림 이름, MCP 도구 이름, 에이전트 이름은 쓰인 그대로 보존합니다.
-- 현재 작업에 필요한 상세 메모리 파일만 읽습니다.
-- 사용자가 다른 언어를 요청하지 않는 한, 사용자에게 보이는 응답과 생성 또는 갱신하는 문서, 계획, 메모리 산출물은 OS locale 언어로 작성합니다.
-
-## Update Rules
-
-- 루트 파일은 짧게 유지합니다.
-- 자세한 도메인 지식은 \`docs/memory/<domain>.md\`로 옮깁니다.
-- 사실은 출처 경로, 명령, 관찰된 동작과 함께 기록합니다.
-`;
-
-const planTemplate = `# PLAN
-
-This file is a short index of active and completed work plans.
-
-## Active Plans
-
-- Link detailed plans under \`docs/plan/\`.
-
-## Completed Plans
-
-- Move completed topics here with evidence links.
-
-## Planning Rules
-
-- Read project-root \`MEMORY.md\` first when it exists; if it is absent, continue without repository memory.
-- For non-trivial implementation or continuation of planned work, first write or restore a plan with \`triage-plan\` active and synchronize it before exploration. Known-target Git/GitHub operations stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design.
-- Plans must be decision-complete before implementation.
-- Run complexity triage before applying agent, plugin, or delegated workflow guidance.
-- Record the selected Light Path or Heavy Path and the checked Heavy Path signals in \`docs/plan/<topic>.md\`.
-- Record request, planning, and code checkpoints. When the route changes before editing, synchronize the plan artifact, repository goal task roadmap through \`goal replan\`, and native UI plan. After editing starts, a new Heavy Path signal promotes Light Path to Heavy Path; stop further edits, mark affected evidence stale, synchronize all three roadmaps, and repeat the code checkpoint.
-- Keep models inherited. Record requested/effective reasoning effort per task: Light planning/implementation/verification=\`medium\`; Heavy planning/review/implementation=\`high\`; final verification/review=\`xhigh\`. A route change also synchronizes the reasoning effort profile, preserving completed profiles and recalculating incomplete profiles. Unsupported host/value means effective=\`inherited\` with no model/global config change.
-- Split implementation into small module tasks.
-- Detect repository stack and required LSP/check tools before implementation.
-- Record missing required tools and suggested commands. Run only pinned, supported installation steps after explicit user approval.
-- Each task normally passes exactly two gates.
-  - Module acceptance verification.
-  - Surface integration verification.
-- Run dry-run or check mode before external-state mutation when available.
-- Write user-visible responses and generated or updated documentation, plans, and memory artifacts in the OS locale unless the user asks for another language.
-- Use at most two verification passes per task by default.
-- If a gate fails, diagnose once, shrink the task or split it into sub-tasks, and rerun both gates.
-- After two failed passes, record the blocker in \`docs/plan/<topic>.md\`.
-`;
-
-const planTemplateKo = `# PLAN
-
-이 파일은 진행 중이거나 완료된 작업 계획의 짧은 색인입니다.
-
-## Active Plans
-
-- 상세 계획은 \`docs/plan/\` 아래에 연결합니다.
-
-## Completed Plans
-
-- 완료된 주제는 증거 링크와 함께 이곳으로 옮깁니다.
-
-## Planning Rules
-
-- 프로젝트 루트 \`MEMORY.md\`가 있으면 먼저 읽고, 없으면 저장소 메모리 없이 계속 진행합니다.
-- 비단순 구현 또는 계획된 작업 재개는 먼저 \`triage-plan\`이 active인 계획을 쓰거나 복원하고 탐색 전에 동기화합니다. 대상이 확정된 Git/GitHub 운영은 코드 수정·충돌 해결·파괴적 복구·릴리스/배포·설계가 필요하지 않으면 plan/goal 없이 실행합니다.
-- 계획은 구현 전에 의사결정이 완료된 상태여야 합니다.
-- 에이전트, 플러그인, 위임 워크플로 지침을 적용하기 전에 복잡도 트리아지를 실행합니다.
-- 선택한 Light Path 또는 Heavy Path와 확인한 Heavy Path 신호를 \`docs/plan/<topic>.md\`에 기록합니다.
-- 요청, 계획, 코드 체크포인트를 기록합니다. 편집 전에 경로가 바뀌면 plan artifact, 저장소 goal task roadmap, native UI plan을 동기화합니다. 편집 뒤 새 Heavy Path 신호가 나오면 추가 편집을 중단하고 관련 증거를 stale로 표시한 뒤 세 roadmap과 코드 체크포인트를 다시 맞춥니다.
-- 모델은 상속하고 task별 requested/effective reasoning effort를 기록합니다. Light 계획/구현/검증은 \`medium\`, Heavy 계획/검토/구현은 \`high\`, 최종 검증/검토는 \`xhigh\`입니다. 경로 변경 시 reasoning effort profile도 동기화하고 완료 profile은 보존하며 미완료 profile은 재계산합니다. 미지원 host/value는 model/global config 변경 없이 effective=\`inherited\`입니다.
-- 구현은 작은 모듈 작업으로 나눕니다.
-- 구현 전에 저장소 스택과 필요한 LSP/check 도구를 감지합니다.
-- 필요한 도구가 없으면 누락 상태와 제안 명령을 기록합니다. 명시적 사용자 승인 뒤에만 고정된 지원 설치 단계를 실행합니다.
-- 각 작업은 보통 정확히 두 게이트를 통과합니다.
-  - 모듈 수용 검증.
-  - 표면 통합 검증.
-- 외부 상태 변경 전에는 가능한 경우 dry-run 또는 check mode를 실행합니다.
-- 사용자가 다른 언어를 요청하지 않는 한, 사용자에게 보이는 응답과 생성 또는 갱신하는 문서, 계획, 메모리 산출물은 OS locale 언어로 작성합니다.
-- 기본적으로 작업당 검증은 최대 두 번만 수행합니다.
-- 게이트가 실패하면 한 번 진단하고, 작업을 줄이거나 sub-task로 나눈 뒤 두 게이트를 다시 실행합니다.
-- 두 번 실패한 뒤에는 blocker를 \`docs/plan/<topic>.md\`에 기록합니다.
-`;
-
-const contextLimits = {
-  goalTitle: 64,
-  roadmapTaskId: 24,
-  taskTitle: 40,
-  roadmapWindow: 3,
-};
+const recoverableGoalStatuses = new Set(["active", "paused", "blocked"]);
 
 if (isCliEntry()) {
   const event = process.argv[2] ?? "manual";
@@ -163,7 +46,7 @@ export async function runStateResult(event = "manual", {
   if (event === "session-start" || event === "user-prompt-submit") {
     const reconciled = await reconcileWorktreeState({ root: resolvedRoot });
     const state = reconciled.state;
-    if (state?.goal?.status === "active" && !isGoalOwnedBySession(state, payload?.session_id)) {
+    if (recoverableGoalStatuses.has(state?.goal?.status) && !isGoalOwnedBySession(state, payload?.session_id)) {
       return foreignSessionContextResult({ ko, event });
     }
     const result = contextResult({ ko, state, event });
@@ -211,169 +94,6 @@ export async function runStateResult(event = "manual", {
   };
 }
 
-async function initializeProject(root, ko) {
-  await safeMkdir(root, "docs/memory");
-  await safeMkdir(root, "docs/plan");
-  await writeIfMissing(root, join(root, "MEMORY.md"), ko ? memoryTemplateKo : memoryTemplate);
-  await writeIfMissing(root, join(root, "PLAN.md"), ko ? planTemplateKo : planTemplate);
-}
-
-async function writeIfMissing(root, path, content) {
-  await assertNoSymlinkComponents(root, path);
-  try {
-    await readFile(path, "utf8");
-  } catch (error) {
-    if (error?.code !== "ENOENT") throw error;
-    try {
-      await safeWriteFile(root, path, content, { encoding: "utf8", flag: "wx" });
-    } catch (writeError) {
-      if (writeError?.code !== "EEXIST") throw writeError;
-      await assertNoSymlinkComponents(root, path, { allowMissing: false });
-    }
-  }
-}
-
-function prependContext(result, notice) {
-  const specific = result.hookOutput?.hookSpecificOutput;
-  if (!specific) return { ...result, message: `${notice}\n${result.message}` };
-  return {
-    ...result,
-    message: `${notice}\n${result.message}`,
-    hookOutput: {
-      ...result.hookOutput,
-      hookSpecificOutput: {
-        ...specific,
-        additionalContext: `${notice}\n${specific.additionalContext}`,
-      },
-    },
-  };
-}
-
-function contextResult({ ko, state, event }) {
-  const base = ko ? "Cairn kernel: 루트 MEMORY.md는 선택 사항이며, 있으면 읽으세요." : "Cairn kernel: root MEMORY.md is optional; read it when present.";
-  const idlePolicy = event === "user-prompt-submit"
-    ? (ko
-      ? " 비단순 구현이나 계획된 작업 재개는 cairn-plan과 plan/task를 복원·생성하세요. 대상이 확정된 Git/GitHub 상태·fetch·checkout·merge·push·PR 작업은 코드 수정·충돌 해결·파괴적 복구·릴리스/배포·설계가 필요하지 않으면 plan/goal 없이 실행하세요. 상담·설명·계획 전용도 goal 없이 처리하세요."
-      : " For non-trivial implementation or planned-work continuation, load cairn-plan and restore/create its plan and task. Known-target Git/GitHub operations stay plan/goal-free unless they require code edits, conflict resolution, destructive recovery, release/deploy, or design. Consultation, explanation, and plan-only requests are also goal-free.")
-    : (ko
-      ? " 중요 작업 전에 cairn-plan을 로드하고 active plan과 current task를 복원하세요."
-      : " Before non-trivial work, load cairn-plan and restore the active plan and current task.");
-  const failClosed = ko
-    ? " active state와 그 skill·plan·required task reference가 없거나 읽을 수 없거나 일치하지 않을 때만 중단하세요."
-    : " Stop only if active state and its skill, plan, or required task ref is missing, unreadable, or inconsistent.";
-  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}${failClosed}` });
-  const task = state.tasks.find((item) => item.status === "active")
-    ?? state.tasks.find((item) => item.status === "pending")
-    ?? state.tasks.find((item) => item.status === "blocked");
-  const planId = state.goal.planId;
-  const phase = task ? "cairn-work" : "cairn-review";
-  const activeHeader = ko
-    ? `${base} ${phase}를 로드하고 정확한 plan ${planId}${task ? "과 아래 current task" : "의 완료 기준"}를 복원하세요. 압축·재시작·handoff·위임 뒤 다시 읽으세요.${failClosed}`
-    : `${base} Load ${phase}; restore exact plan ${planId}${task ? " and the current task below" : " completion criteria"}. Re-read after compaction/restart/handoff/delegation.${failClosed}`;
-  if (!task) {
-    return contextHookResult({
-      event,
-      message: [activeHeader, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
-    });
-  }
-  const taskId = task.id;
-  const taskTitle = clipText(task.title, contextLimits.taskTitle);
-  const continuation = taskId.length > 48
-    ? (ko
-      ? `정확한 current task: ${taskId}. 바인딩된 증거 뒤에만 완료하세요.`
-      : `Exact task: ${taskId}. Complete after bound evidence.`)
-    : (ko
-      ? `현재: ${taskId} (${taskTitle}). 바인딩된 증거 뒤에만 완료하세요.`
-      : `Current: ${taskId} (${taskTitle}). Complete only after bound evidence.`);
-  const resume = event === "user-prompt-submit"
-    ? (taskId.length > 48
-      ? (ko
-        ? "곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 위의 정확한 task를 재개하세요."
-        : "Resume that exact task after side questions unless paused, stopped, or switched.")
-      : (ko
-        ? `곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 ${taskId}를 재개하세요.`
-        : `After a side question, resume ${taskId} unless asked to pause, stop, or switch.`))
-    : "";
-  return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
-}
-
-function foreignSessionContextResult({ ko, event }) {
-  const message = ko
-    ? "Cairn kernel: 루트 MEMORY.md는 선택 사항이며, 있으면 읽으세요. 저장소 goal을 다른 session이 소유합니다. cairn goal status로 상태를 확인하고 소유권이 해결될 때까지 Cairn 작업을 시작·수정·위임·완료하지 마세요. 이 capsule은 goal, plan, task 상세를 노출하지 않습니다."
-    : "Cairn kernel: root MEMORY.md is optional; read it when present. A repository goal is owned by another session. Inspect cairn goal status; until ownership is resolved, do not start, edit, delegate, or complete Cairn work. This capsule does not expose goal, plan, or task details.";
-  return contextHookResult({ event, message });
-}
-
-function taskRoadmap(ko, state) {
-  const formatTask = (task, index) => `${index + 1}. ${clipText(task.id, contextLimits.roadmapTaskId)} [${task.status}] ${clipText(task.title, contextLimits.taskTitle)}`;
-  if (state.tasks.length <= contextLimits.roadmapWindow) {
-    return `${ko ? "작업 단계" : "Work steps"}:\n${state.tasks.map(formatTask).join("\n")}`;
-  }
-
-  const currentIndex = Math.max(0, state.tasks.findIndex((task) => task.status === "active" || task.status === "pending"));
-  const counts = Object.fromEntries([...TASK_STATUS_NAMES].map((status) => [status, state.tasks.filter((task) => task.status === status).length]));
-  const countSummary = Object.entries(counts).filter(([, count]) => count > 0).map(([status, count]) => `${status} ${count}`).join(", ");
-  const omitted = state.tasks.length - 1;
-  const header = ko
-    ? `작업 단계 (${state.tasks.length}개; ${countSummary})`
-    : `Work steps (${state.tasks.length}; ${countSummary})`;
-  const omission = ko ? `… ${omitted}개 단계 생략` : `… ${omitted} steps omitted`;
-  const currentPosition = currentIndex + 1;
-  return `${header}. ${ko ? `현재 위치 ${currentPosition}` : `Current position ${currentPosition}`}; ${omission}`;
-}
-
-function contextHookResult({ event, message }) {
-  return {
-    status: 0,
-    message,
-    hookOutput: {
-      hookSpecificOutput: {
-        hookEventName: event === "session-start" ? "SessionStart" : "UserPromptSubmit",
-        additionalContext: message,
-      },
-    },
-  };
-}
-
-function continuationReason(reason, payload) {
-  const continuation = payload?.stop_hook_active ? " This turn was already continued; the active goal remains persisted for the next session." : "";
-  return `${reason}${continuation}`;
-}
-
-function stopHookOutput(gate, payload) {
-  if (!gate.block) return { continue: true };
-  const reason = continuationReason(gate.reason, payload);
-  if (payload?.stop_hook_active) {
-    return { continue: true, systemMessage: reason };
-  }
-  return { decision: "block", reason };
-}
-
-function stopAllowedMessage({ ko, state, event }) {
-  if (state?.goal?.status) {
-    return ko
-      ? `Cairn 종료 게이트: 목표 상태가 ${state.goal.status}이므로 종료를 허용합니다.`
-      : `Cairn stop gate: goal status is ${state.goal.status}; allowing stop.`;
-  }
-  return ko
-    ? `${event === "subagent-stop" ? "서브에이전트" : "작업"} 종료 게이트: 활성 Cairn 목표가 없어 종료를 허용합니다.`
-    : `${event === "subagent-stop" ? "Subagent" : "Turn"} stop gate: no active Cairn goal; allowing stop.`;
-}
-
-function activeGoalCompletionMessage(ko, state) {
-  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
-  return ko
-    ? `활성 목표 "${goalTitle}"의 모든 task가 완료되었습니다. 완료 기준을 확인하고 명시적으로 complete 상태로 전이하세요.`
-    : `All tasks for active goal "${goalTitle}" are complete. Verify criteria and explicitly transition the goal to completed.`;
-}
-
-const TASK_STATUS_NAMES = ["active", "pending", "blocked", "completed"];
-
-function clipText(value, maxLength) {
-  const text = String(value ?? "");
-  return text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
-}
-
 function resolveRoot(root, payload) {
   return resolveRepoRoot({
     explicitRoot: root ?? null,

package/scripts/cairn-toolcheck-detect.mjs

@@ -0,0 +1,229 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { commandOk } from "./cairn-toolcheck-runtime.mjs";
+
+export async function collectEntries(base) {
+  const output = [];
+  async function walk(dir) {
+    for (const entry of await readdir(dir)) {
+      if ([".git", ".cairn", "node_modules", "vendor", "target", ".venv", "__pycache__"].includes(entry)) continue;
+      const path = join(dir, entry);
+      const relativePath = normalizePath(relative(base, path));
+      if (relativePath === "test/fixtures" || relativePath.startsWith("test/fixtures/")) continue;
+      const info = await lstat(path);
+      if (info.isSymbolicLink()) continue;
+      if (info.isDirectory()) await walk(path);
+      else output.push(relativePath);
+    }
+  }
+  await walk(base);
+  return output;
+}
+
+export function detectStacks(paths) {
+  const stacks = new Set();
+  if (hasBasename(paths, "package.json")) stacks.add("javascript");
+  if (hasBasename(paths, "tsconfig.json") || paths.some((path) => path.endsWith(".ts") || path.endsWith(".tsx"))) stacks.add("typescript");
+  if (hasBasename(paths, "pyproject.toml") || paths.some((path) => path.endsWith(".py"))) stacks.add("python");
+  if (hasBasename(paths, "composer.json") || paths.some((path) => path.endsWith(".php"))) stacks.add("php");
+  if (hasBasename(paths, "pom.xml", "build.gradle", "build.gradle.kts") || paths.some((path) => path.endsWith(".java"))) stacks.add("java");
+  if (paths.some((path) => path.endsWith(".kt") || path.endsWith(".kts"))) stacks.add("kotlin");
+  if (hasBasename(paths, "Package.swift") || paths.some((path) => hasPathSegmentWithSuffix(path, ".xcodeproj", ".xcworkspace") || path.endsWith(".swift"))) stacks.add("swift");
+  if (hasBasename(paths, "go.mod") || paths.some((path) => path.endsWith(".go"))) stacks.add("go");
+  if (hasBasename(paths, "Cargo.toml") || paths.some((path) => path.endsWith(".rs"))) stacks.add("rust");
+  return [...stacks];
+}
+
+export function buildRequirements(stacks, entries = [], _commandAvailable = commandOk, platform = process.platform) {
+  const requirements = [];
+  if (stacks.includes("javascript")) {
+    requirements.push(unsafeReq("node", ["--version"], "JavaScript runtime for package scripts and CLI checks", "automatic runtime installation is unavailable"));
+    const manager = packageManager(entries);
+    requirements.push(unsafeReq(manager, ["--version"], `JavaScript package manager selected from ${packageManagerSource(entries)}`, "automatic package-manager installation is unavailable"));
+  }
+  if (stacks.includes("typescript")) {
+    requirements.push(unsafeReq("typescript-language-server", ["--version"], "TypeScript LSP server", "automatic package installation is disabled without pinned package versions"));
+    requirements.push(unsafeReq("tsc", ["--version"], "TypeScript compiler verification", "automatic package installation is disabled without pinned package versions"));
+  }
+  if (stacks.includes("python")) {
+    requirements.push(unsafeReq("basedpyright", ["--version"], "Python LSP/type checker", "automatic Python package installation is disabled without pinned package versions"));
+    requirements.push(unsafeReq("ruff", ["--version"], "Python lint and format checker", "automatic Python package installation is disabled without pinned package versions"));
+  }
+  if (stacks.includes("php")) {
+    const composerProject = hasBasename(entries, "composer.json");
+    requirements.push(req("php", ["--version"], "PHP runtime for Composer scripts and CLI checks"));
+    if (composerProject) requirements.push(req("composer", ["--version"], "PHP package manager for project-local tool installation"));
+    requirements.push(unsafeReq("phpactor", ["--version"], "PHP LSP server", "automatic Composer package installation is disabled without pinned package versions"));
+    requirements.push(unsafeReq("phpstan", ["--version"], "PHP static analysis verification", "automatic Composer package installation is disabled without pinned package versions"));
+    requirements.push(unsafeReq("php-cs-fixer", ["--version"], "PHP formatting verification", "automatic Composer package installation is disabled without pinned package versions"));
+  }
+  if (stacks.includes("java")) {
+    addJvmRequirements(requirements);
+    requirements.push(unsafeReq("jdtls", ["--version"], "Java LSP server", "checksum-free JDTLS latest downloads are disabled"));
+    addJvmBuildToolRequirements(requirements, entries);
+  }
+  if (stacks.includes("kotlin")) {
+    addJvmRequirements(requirements);
+    requirements.push(req("kotlin-lsp.sh", ["--help"], "Kotlin LSP server"));
+    requirements.push(req("kotlinc", ["-version"], "Kotlin compiler verification"));
+    addJvmBuildToolRequirements(requirements, entries);
+  }
+  if (stacks.includes("swift")) {
+    requirements.push(req("swift", ["--version"], "Swift toolchain for build and test commands"));
+    requirements.push(req("sourcekit-lsp", ["--version"], "Swift LSP server"));
+    if (entries.some((path) => hasPathSegmentWithSuffix(path, ".xcodeproj", ".xcworkspace"))) {
+      requirements.push(req("xcodebuild", ["-version"], "Xcode build verification"));
+    }
+  }
+  if (stacks.includes("go")) {
+    requirements.push(unsafeReq("gopls", ["version"], "Go LSP server", "unpinned go install targets are disabled"));
+    requirements.push(unsafeReq("golangci-lint", ["--version"], "Go lint verification", "unpinned go install targets are disabled"));
+  }
+  if (stacks.includes("rust")) {
+    requirements.push(unsafeReq("rust-analyzer", ["--version"], "Rust LSP server", "automatic rustup changes are disabled without a pinned toolchain manifest"));
+    requirements.push(unsafeReq("cargo", ["clippy", "--version"], "Rust clippy verification", "automatic rustup changes are disabled without a pinned toolchain manifest"));
+  }
+  return requirements;
+}
+
+export function addJvmRequirements(requirements) {
+  if (!requirements.some((requirement) => requirement.name === "java")) {
+    requirements.push(req("java", ["--version"], "JVM runtime for build and test commands"));
+  }
+  if (!requirements.some((requirement) => requirement.name === "javac")) {
+    requirements.push(req("javac", ["--version"], "JVM compiler verification"));
+  }
+}
+
+export function addJvmBuildToolRequirements(requirements, entries = []) {
+  const gradleWindows = findBasename(entries, "gradlew.bat");
+  const gradleUnix = findBasename(entries, "gradlew");
+  if (gradleWindows) pushUnique(requirements, req(repositoryCommand(gradleWindows), ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
+  else if (gradleUnix) pushUnique(requirements, req(repositoryCommand(gradleUnix), ["--version"], "Gradle wrapper availability", null, { localOnly: true }));
+  else if (hasBasename(entries, "build.gradle", "build.gradle.kts")) pushUnique(requirements, req("gradle", ["--version"], "Gradle availability"));
+  const mavenWindows = findBasename(entries, "mvnw.cmd", "mvnw.bat");
+  const mavenUnix = findBasename(entries, "mvnw");
+  if (mavenWindows) pushUnique(requirements, req(repositoryCommand(mavenWindows), ["--version"], "Maven wrapper availability", null, { localOnly: true }));
+  else if (mavenUnix) pushUnique(requirements, req(repositoryCommand(mavenUnix), ["--version"], "Maven wrapper availability", null, { localOnly: true }));
+  else if (hasBasename(entries, "pom.xml")) pushUnique(requirements, req("mvn", ["--version"], "Maven availability"));
+}
+
+export function pushUnique(requirements, requirement) {
+  if (!requirements.some((candidate) => candidate.name === requirement.name)) requirements.push(requirement);
+}
+
+// Kept for API compatibility. Callers may show these commands, but buildRequirements
+// no longer attaches an unpinned command to an automatically executable requirement.
+export function composerInstall(packages) {
+  return { command: "composer", args: ["require", "--dev", ...packages] };
+}
+
+export function pythonInstall(uv, project, tool, platform = process.platform) {
+  if (uv && project) return { command: "uv", args: ["add", "--dev", tool] };
+  if (uv) return { command: "uv", args: ["tool", "install", tool] };
+  if (platform === "win32") return { command: "py", args: ["-3", "-m", "pip", "install", "--user", tool] };
+  return { command: "python3", args: ["-m", "pip", "install", "--user", tool] };
+}
+
+export function jdtlsInstall(_platform = process.platform) {
+  return null;
+}
+
+export function req(command, args, reason, installCommand = null, options = {}) {
+  return {
+    name: command,
+    command,
+    args,
+    reason,
+    install: installCommand,
+    installUnavailableReason: options.installUnavailableReason ?? null,
+    localOnly: options.localOnly ?? false,
+  };
+}
+
+export function unsafeReq(command, args, reason, installUnavailableReason) {
+  return req(command, args, reason, null, { installUnavailableReason });
+}
+
+export function packageManager(entries = []) {
+  return selectPackageManager(entries).manager;
+}
+
+export function packageManagerSource(entries = []) {
+  const selected = selectPackageManager(entries);
+  return selected.path ?? "the npm default (no lockfile found)";
+}
+
+export function installDev(pm, packages) {
+  if (pm === "bun") return { command: "bun", args: ["add", "-d", ...packages] };
+  if (pm === "pnpm") return { command: "pnpm", args: ["add", "-D", ...packages] };
+  if (pm === "yarn") return { command: "yarn", args: ["add", "-D", ...packages] };
+  return { command: "npm", args: ["install", "--save-dev", ...packages] };
+}
+
+function normalizePath(path) {
+  return path.split(sep).join("/");
+}
+
+function pathBasename(path) {
+  const normalized = normalizePath(path);
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+
+function hasBasename(paths, ...names) {
+  const expected = new Set(names);
+  return paths.some((path) => expected.has(pathBasename(path)));
+}
+
+function findBasename(paths, ...names) {
+  const expected = new Set(names);
+  return [...paths]
+    .filter((path) => expected.has(pathBasename(path)))
+    .sort(compareRepositoryPaths)[0] ?? null;
+}
+
+function hasPathSegmentWithSuffix(path, ...suffixes) {
+  return normalizePath(path)
+    .split("/")
+    .some((segment) => suffixes.some((suffix) => segment.endsWith(suffix)));
+}
+
+function repositoryCommand(path) {
+  const normalized = normalizePath(path);
+  return normalized.startsWith("./") ? normalized : `./${normalized}`;
+}
+
+function selectPackageManager(entries) {
+  const lockfiles = [
+    { manager: "bun", names: new Set(["bun.lock", "bun.lockb"]), priority: 0 },
+    { manager: "pnpm", names: new Set(["pnpm-lock.yaml"]), priority: 1 },
+    { manager: "yarn", names: new Set(["yarn.lock"]), priority: 2 },
+    { manager: "npm", names: new Set(["package-lock.json", "npm-shrinkwrap.json"]), priority: 3 },
+  ];
+  const candidates = [];
+
+  for (const path of entries) {
+    const normalized = normalizePath(path);
+    const name = pathBasename(normalized);
+    const match = lockfiles.find(({ names }) => names.has(name));
+    if (!match) continue;
+    candidates.push({
+      manager: match.manager,
+      path: normalized,
+      depth: normalized.split("/").length - 1,
+      priority: match.priority,
+    });
+  }
+
+  candidates.sort((left, right) => left.depth - right.depth
+    || left.priority - right.priority
+    || left.path.localeCompare(right.path));
+  return candidates[0] ?? { manager: "npm", path: null };
+}
+
+function compareRepositoryPaths(left, right) {
+  const leftPath = normalizePath(left);
+  const rightPath = normalizePath(right);
+  const depth = leftPath.split("/").length - rightPath.split("/").length;
+  return depth || leftPath.localeCompare(rightPath);
+}