helloloop 0.2.1 → 0.6.1

package/src/discovery_inference.mjs

@@ -4,10 +4,12 @@ import path from "node:path";
 import { readJson } from "./common.mjs";
 import { expandDocumentEntries } from "./doc_loader.mjs";
 import {
+  findPreferredRepoRootFromPath,
   findRepoRootFromPath,
   isDocFile,
   isDocsDirectory,
-  looksLikeProjectRoot,
+  listDocFilesInDirectory,
+  listProjectCandidatesInDirectory,
   normalizeForRepo,
   pathExists,
   resolveAbsolute,
@@ -48,7 +50,7 @@ function readDocPreview(docEntries, cwd) {
 }
 
 function normalizePathHint(rawValue) {
-  const trimmed = String(rawValue || "").trim().replace(/^["'`(<\[]+|[>"'`)\].,;:]+$/g, "");
+  const trimmed = String(rawValue || "").trim().replace(/^[:"'`(<\[：]+|[>"'`)\].,;:：]+$/g, "");
   if (/^\/[A-Za-z]:[\\/]/.test(trimmed)) {
     return trimmed.slice(1);
   }
@@ -59,7 +61,7 @@ function extractPathHintsFromText(text) {
   const hints = new Set();
   const normalizedText = String(text || "");
   const windowsMatches = normalizedText.match(/\/?[A-Za-z]:[\\/][^\s"'`<>()\]]+/g) || [];
-  const posixMatches = normalizedText.match(/(?:^|[\s("'`])\/[^\s"'`<>()\]]+/g) || [];
+  const posixMatches = normalizedText.match(/(?:^|[\s("'`:：])\/(?!\/)[^\s"'`<>()\]]+/g) || [];
 
   for (const rawMatch of [...windowsMatches, ...posixMatches]) {
     const normalized = normalizePathHint(rawMatch);
@@ -86,15 +88,52 @@ function extractRepoNameHintsFromText(text) {
   return [...hints];
 }
 
-function listNearbyProjectCandidates(searchRoot) {
-  if (!pathExists(searchRoot) || !fs.statSync(searchRoot).isDirectory()) {
+function formatCandidates(title, candidates) {
+  if (!Array.isArray(candidates) || !candidates.length) {
     return [];
   }
 
-  return fs.readdirSync(searchRoot, { withFileTypes: true })
+  return [
+    title,
+    ...candidates.map((item, index) => `${index + 1}. ${path.basename(item)} — ${item.replaceAll("\\", "/")}`),
+  ];
+}
+
+export function inspectWorkspaceDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return {
+      docCandidates: [],
+      docsEntries: [],
+      repoCandidates: [],
+      topLevelDirectories: [],
+      topLevelDocFiles: [],
+    };
+  }
+
+  const topLevelEntries = fs.readdirSync(directoryPath, { withFileTypes: true });
+  const namedDocsDirectories = topLevelEntries
+    .filter((entry) => (
+      entry.isDirectory()
+      && ["doc", "docs", "documentation"].includes(entry.name.toLowerCase())
+    ))
+    .map((entry) => path.join(directoryPath, entry.name))
+    .filter((candidate) => isDocsDirectory(candidate));
+
+  const topLevelDocFiles = listDocFilesInDirectory(directoryPath)
+    .filter((candidate) => path.basename(candidate).toLowerCase() !== "agents.md");
+  const docCandidates = uniquePaths([...topLevelDocFiles, ...namedDocsDirectories]);
+  const topLevelDirectories = topLevelEntries
     .filter((entry) => entry.isDirectory())
-    .map((entry) => path.join(searchRoot, entry.name))
-    .filter((directoryPath) => looksLikeProjectRoot(directoryPath));
+    .map((entry) => path.join(directoryPath, entry.name));
+
+  const repoCandidates = uniquePaths(listProjectCandidatesInDirectory(directoryPath));
+  return {
+    docCandidates,
+    docsEntries: docCandidates.length === 1 ? [docCandidates[0]] : [],
+    repoCandidates,
+    topLevelDirectories,
+    topLevelDocFiles,
+  };
 }
 
 export function inferRepoFromDocs(docEntries, cwd) {
@@ -117,7 +156,7 @@ export function inferRepoFromDocs(docEntries, cwd) {
     .map((item) => resolveAbsolute(item, cwd))
     .filter((candidate) => pathExists(candidate))
     .map((candidate) => (fs.statSync(candidate).isDirectory() ? candidate : path.dirname(candidate)))
-    .map((candidate) => findRepoRootFromPath(candidate) || (looksLikeProjectRoot(candidate) ? candidate : ""))
+    .map((candidate) => findPreferredRepoRootFromPath(candidate))
     .filter(Boolean);
 
   const uniquePathCandidates = uniquePaths(pathHintCandidates);
@@ -136,11 +175,15 @@ export function inferRepoFromDocs(docEntries, cwd) {
         ? absolutePath
         : path.dirname(absolutePath);
       const parent = path.dirname(directory);
-      return [directory, parent, path.dirname(parent)];
+      const roots = [directory, parent];
+      if (["doc", "docs", "documentation"].includes(path.basename(directory).toLowerCase())) {
+        roots.push(path.dirname(parent));
+      }
+      return roots;
     }),
   );
   const nearbyCandidates = uniquePaths(
-    searchRoots.flatMap((searchRoot) => listNearbyProjectCandidates(searchRoot)),
+    searchRoots.flatMap((searchRoot) => listProjectCandidatesInDirectory(searchRoot)),
   );
   const namedCandidates = nearbyCandidates.filter((directoryPath) => (
     repoNameHints.includes(path.basename(directoryPath).toLowerCase())
@@ -156,7 +199,7 @@ export function inferRepoFromDocs(docEntries, cwd) {
 
   return {
     repoRoot: "",
-    candidates: uniquePaths([...uniquePathCandidates, ...namedCandidates]),
+    candidates: uniquePaths([...uniquePathCandidates, ...namedCandidates, ...nearbyCandidates]),
     source: "",
   };
 }
@@ -203,18 +246,19 @@ export function inferDocsForRepo(repoRoot, cwd, configDirName) {
 export function renderMissingRepoMessage(docEntries, candidates) {
   return [
     "无法自动确定要开发的项目仓库路径。",
-    docEntries.length ? `已找到开发文档：${docEntries.join(", ")}` : "",
-    candidates.length > 1 ? `本地发现多个候选项目：${candidates.map((item) => path.basename(item)).join(", ")}` : "",
-    "请补充项目仓库路径后重试，例如：",
+    docEntries.length ? `已找到开发文档：${docEntries.map((item) => item.replaceAll("\\", "/")).join("，")}` : "",
+    ...formatCandidates("候选项目：", candidates),
+    "可重新运行 `npx helloloop` 后按提示选择，或显式补充项目路径，例如：",
     "npx helloloop --repo <PROJECT_ROOT>",
   ].filter(Boolean).join("\n");
 }
 
-export function renderMissingDocsMessage(repoRoot) {
+export function renderMissingDocsMessage(repoRoot, candidates = []) {
   return [
     "无法自动确定开发文档位置。",
-    `已找到项目仓库：${repoRoot}`,
-    "请补充开发文档路径后重试，例如：",
+    `已找到项目仓库：${repoRoot.replaceAll("\\", "/")}`,
+    ...formatCandidates("候选开发文档：", candidates),
+    "可重新运行 `npx helloloop` 后按提示选择，或显式补充开发文档路径，例如：",
     "npx helloloop --docs <DOCS_PATH>",
   ].join("\n");
 }

package/src/discovery_paths.mjs

@@ -36,15 +36,80 @@ const PROJECT_DIR_MARKERS = [
   "tests",
 ];
 
-function directoryContainsDocs(directoryPath) {
+const IGNORED_PROJECT_SEGMENTS = new Set([
+  ".cache",
+  ".git",
+  ".next",
+  ".nuxt",
+  ".pnpm",
+  ".turbo",
+  ".venv",
+  ".yarn",
+  "__pycache__",
+  "build",
+  "cache",
+  "coverage",
+  "dist",
+  "node_modules",
+  "out",
+  "target",
+  "temp",
+  "tmp",
+  "vendor",
+  "venv",
+]);
+
+function listImmediateDirectories(directoryPath) {
   if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
-    return false;
+    return [];
   }
 
-  const entries = fs.readdirSync(directoryPath, { withFileTypes: true });
-  return entries.some((entry) => (
-    entry.isFile() && DOC_FILE_SUFFIX.has(path.extname(entry.name).toLowerCase())
-  ));
+  return fs.readdirSync(directoryPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(directoryPath, entry.name));
+}
+
+function hasProjectMarker(directoryPath) {
+  return PROJECT_MARKERS.some((name) => pathExists(path.join(directoryPath, name)));
+}
+
+function looksLikeStrongProjectRoot(directoryPath) {
+  return pathExists(directoryPath)
+    && fs.statSync(directoryPath).isDirectory()
+    && hasProjectMarker(directoryPath);
+}
+
+export function listDocFilesInDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return [];
+  }
+
+  return fs.readdirSync(directoryPath, { withFileTypes: true })
+    .filter((entry) => (
+      entry.isFile() && DOC_FILE_SUFFIX.has(path.extname(entry.name).toLowerCase())
+    ))
+    .map((entry) => path.join(directoryPath, entry.name));
+}
+
+function directoryContainsDocs(directoryPath) {
+  return listDocFilesInDirectory(directoryPath).length > 0;
+}
+
+function hasIgnoredProjectBasename(targetPath) {
+  return IGNORED_PROJECT_SEGMENTS.has(path.basename(targetPath).toLowerCase());
+}
+
+function choosePreferredCandidate(candidates, directory) {
+  return candidates.find((candidate) => {
+    const relativeToLeaf = path.relative(candidate, directory);
+    return relativeToLeaf
+      .split(/[\\/]+/)
+      .filter(Boolean)
+      .some((segment) => IGNORED_PROJECT_SEGMENTS.has(segment.toLowerCase()));
+  })
+    || candidates.find((candidate) => !hasIgnoredProjectBasename(candidate))
+    || candidates[0]
+    || "";
 }
 
 function walkUpDirectories(startPath) {
@@ -86,13 +151,37 @@ export function looksLikeProjectRoot(directoryPath) {
     return false;
   }
 
-  if (PROJECT_MARKERS.some((name) => pathExists(path.join(directoryPath, name)))) {
+  if (hasProjectMarker(directoryPath)) {
     return true;
   }
 
   return PROJECT_DIR_MARKERS.some((name) => pathExists(path.join(directoryPath, name)));
 }
 
+export function listProjectCandidatesInDirectory(searchRoot) {
+  return listImmediateDirectories(searchRoot)
+    .filter((directoryPath) => (
+      looksLikeProjectRoot(directoryPath) && !hasIgnoredProjectBasename(directoryPath)
+    ));
+}
+
+export function looksLikeWorkspaceDirectory(directoryPath) {
+  if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
+    return false;
+  }
+
+  const repoCandidates = listProjectCandidatesInDirectory(directoryPath);
+  if (!repoCandidates.length) {
+    return false;
+  }
+
+  const hasLooseDocs = directoryContainsDocs(directoryPath)
+    || listImmediateDirectories(directoryPath)
+      .some((childPath) => DOC_DIR_NAMES.has(path.basename(childPath).toLowerCase()));
+
+  return repoCandidates.length > 1 || hasLooseDocs;
+}
+
 export function isDocsDirectory(directoryPath) {
   if (!pathExists(directoryPath) || !fs.statSync(directoryPath).isDirectory()) {
     return false;
@@ -103,6 +192,10 @@ export function isDocsDirectory(directoryPath) {
     return true;
   }
 
+  if (looksLikeWorkspaceDirectory(directoryPath)) {
+    return false;
+  }
+
   return directoryContainsDocs(directoryPath) && !looksLikeProjectRoot(directoryPath);
 }
 
@@ -124,6 +217,39 @@ export function findRepoRootFromPath(startPath) {
   return "";
 }
 
+export function findPreferredRepoRootFromPath(startPath) {
+  if (!pathExists(startPath)) {
+    return "";
+  }
+
+  const directory = fs.statSync(startPath).isDirectory()
+    ? startPath
+    : path.dirname(startPath);
+  const strongCandidates = [];
+  const weakCandidates = [];
+
+  for (const current of walkUpDirectories(directory)) {
+    if (pathExists(path.join(current, ".git"))) {
+      return current;
+    }
+
+    if (looksLikeStrongProjectRoot(current)) {
+      strongCandidates.push(current);
+      continue;
+    }
+
+    if (looksLikeProjectRoot(current)) {
+      weakCandidates.push(current);
+    }
+  }
+
+  if (strongCandidates.length) {
+    return choosePreferredCandidate(strongCandidates, directory);
+  }
+
+  return choosePreferredCandidate(weakCandidates, directory);
+}
+
 export function normalizeForRepo(repoRoot, targetPath) {
   const relative = path.relative(repoRoot, targetPath);
   if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
@@ -159,7 +285,16 @@ export function classifyExplicitPath(inputPath) {
   }
 
   if (fs.statSync(inputPath).isDirectory()) {
-    return { kind: "repo", absolutePath: inputPath };
+    const repoRoot = findRepoRootFromPath(inputPath);
+    if (repoRoot) {
+      return { kind: "repo", absolutePath: repoRoot };
+    }
+
+    if (looksLikeWorkspaceDirectory(inputPath)) {
+      return { kind: "workspace", absolutePath: inputPath };
+    }
+
+    return { kind: "directory", absolutePath: inputPath };
   }
 
   return { kind: "unsupported", absolutePath: inputPath };

package/src/discovery_prompt.mjs

@@ -0,0 +1,273 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  listDocFilesInDirectory,
+  listProjectCandidatesInDirectory,
+  pathExists,
+  resolveAbsolute,
+} from "./discovery_paths.mjs";
+import { createPromptSession } from "./prompt_session.mjs";
+
+function toDisplayPath(targetPath) {
+  return String(targetPath || "").replaceAll("\\", "/");
+}
+
+export function createDiscoveryPromptSession() {
+  return createPromptSession();
+}
+
+function summarizeList(items, options = {}) {
+  const limit = Number(options.limit || 12);
+  if (!items.length) {
+    return ["- 无"];
+  }
+
+  const visible = items.slice(0, limit);
+  const lines = visible.map((item) => `- ${item}`);
+  if (items.length > limit) {
+    lines.push(`- 其余 ${items.length - limit} 项未展开`);
+  }
+  return lines;
+}
+
+function collectDirectoryOverview(rootPath) {
+  if (!pathExists(rootPath) || !fs.statSync(rootPath).isDirectory()) {
+    return {
+      rootPath,
+      directories: [],
+      docFiles: [],
+      repoCandidates: [],
+    };
+  }
+
+  const entries = fs.readdirSync(rootPath, { withFileTypes: true });
+  return {
+    rootPath,
+    directories: entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort((left, right) => left.localeCompare(right, "zh-CN")),
+    docFiles: listDocFilesInDirectory(rootPath)
+      .map((filePath) => path.basename(filePath))
+      .sort((left, right) => left.localeCompare(right, "zh-CN")),
+    repoCandidates: listProjectCandidatesInDirectory(rootPath)
+      .map((directoryPath) => path.basename(directoryPath))
+      .sort((left, right) => left.localeCompare(right, "zh-CN")),
+  };
+}
+
+function renderDirectoryOverview(title, overview) {
+  return [
+    title,
+    `扫描目录：${toDisplayPath(overview.rootPath)}`,
+    "",
+    "顶层文档文件：",
+    ...summarizeList(overview.docFiles),
+    "",
+    "顶层目录：",
+    ...summarizeList(overview.directories),
+    "",
+    "疑似项目目录：",
+    ...summarizeList(overview.repoCandidates),
+  ].join("\n");
+}
+
+function renderExistingChoices(title, candidates) {
+  return [
+    title,
+    ...candidates.map((item, index) => `${index + 1}. ${toDisplayPath(item)}`),
+    "",
+    "请输入编号；也可以直接输入本地路径；直接回车取消。",
+  ].join("\n");
+}
+
+async function promptForExistingPathSelection(readline, title, candidates, cwd, preface = "") {
+  if (preface) {
+    console.log(preface);
+    console.log("");
+  }
+  console.log(renderExistingChoices(title, candidates));
+  while (true) {
+    const answer = String(await readline.question("> ") || "").trim();
+    if (!answer) {
+      return "";
+    }
+
+    const choiceIndex = Number(answer);
+    if (Number.isInteger(choiceIndex) && choiceIndex >= 1 && choiceIndex <= candidates.length) {
+      return candidates[choiceIndex - 1];
+    }
+
+    const maybePath = resolveAbsolute(answer, cwd);
+    if (pathExists(maybePath)) {
+      return maybePath;
+    }
+
+    console.log("输入无效，请输入候选编号或一个存在的本地路径。");
+  }
+}
+
+async function promptForDocsPath(readline, discovery, cwd) {
+  const docChoices = Array.isArray(discovery.docCandidates) ? discovery.docCandidates : [];
+  const scanRoot = discovery.workspaceRoot || discovery.repoRoot || cwd;
+  const overview = collectDirectoryOverview(scanRoot);
+  const title = docChoices.length
+    ? "请选择开发文档来源："
+    : "未自动识别到明确的开发文档。请输入开发文档目录或文件路径：";
+  const preface = renderDirectoryOverview("当前目录顶层概览", overview);
+
+  if (docChoices.length) {
+    return promptForExistingPathSelection(readline, title, docChoices, cwd, preface);
+  }
+
+  console.log(preface);
+  console.log("");
+  console.log(title);
+  console.log("可直接输入当前目录下的相对路径或绝对路径；直接回车取消。");
+  while (true) {
+    const answer = String(await readline.question("> ") || "").trim();
+    if (!answer) {
+      return "";
+    }
+
+    const maybePath = resolveAbsolute(answer, cwd);
+    if (pathExists(maybePath)) {
+      return maybePath;
+    }
+
+    console.log("路径不存在，请输入一个已存在的开发文档目录或文件路径。");
+  }
+}
+
+async function promptForRepoPath(readline, discovery, cwd) {
+  const repoChoices = Array.isArray(discovery.repoCandidates) ? discovery.repoCandidates : [];
+  const scanRoot = discovery.workspaceRoot
+    || (Array.isArray(discovery.docsEntries) && discovery.docsEntries.length
+      ? path.dirname(discovery.docsEntries[0])
+      : "")
+    || cwd;
+  const overview = collectDirectoryOverview(scanRoot);
+  const preface = renderDirectoryOverview("当前目录顶层概览", overview);
+  const title = repoChoices.length
+    ? "请选择目标项目仓库："
+    : "请输入要开发的项目路径：";
+  console.log(preface);
+  console.log("");
+  if (repoChoices.length) {
+    console.log(renderExistingChoices(title, repoChoices));
+    console.log("也可以直接输入项目路径；如果这是新项目，可输入准备创建的新目录路径。");
+  } else {
+    console.log(title);
+    console.log("如果这是新项目，可直接输入准备创建的新目录路径；直接回车取消。");
+  }
+
+  while (true) {
+    const answer = String(await readline.question("> ") || "").trim();
+    if (!answer) {
+      return { repoRoot: "", allowNewRepoRoot: false };
+    }
+
+    const choiceIndex = Number(answer);
+    if (repoChoices.length && Number.isInteger(choiceIndex) && choiceIndex >= 1 && choiceIndex <= repoChoices.length) {
+      return {
+        repoRoot: repoChoices[choiceIndex - 1],
+        allowNewRepoRoot: false,
+      };
+    }
+
+    const maybePath = resolveAbsolute(answer, cwd);
+    if (pathExists(maybePath) && !fs.statSync(maybePath).isDirectory()) {
+      console.log("项目路径必须是目录，不能是文件。");
+      continue;
+    }
+
+    return {
+      repoRoot: maybePath,
+      allowNewRepoRoot: !pathExists(maybePath),
+    };
+  }
+}
+
+export async function resolveDiscoveryFailureInteractively(
+  failure,
+  options = {},
+  cwd = process.cwd(),
+  allowPrompt = true,
+  sharedPromptSession = null,
+) {
+  const discovery = failure?.discovery || {};
+  const nextOptions = {
+    ...options,
+    selectionSources: {
+      ...(options.selectionSources || {}),
+    },
+  };
+  let changed = false;
+  const promptSession = sharedPromptSession || (allowPrompt ? createDiscoveryPromptSession() : null);
+  const ownsPromptSession = Boolean(promptSession) && !sharedPromptSession;
+
+  try {
+    if (!nextOptions.docsPath) {
+      const docChoices = Array.isArray(discovery.docCandidates) ? discovery.docCandidates : [];
+      if (Array.isArray(discovery.docsEntries) && discovery.docsEntries.length === 1) {
+        nextOptions.docsPath = discovery.docsEntries[0];
+        nextOptions.selectionSources.docs = "workspace_single_doc";
+        changed = true;
+      } else if (docChoices.length === 1) {
+        nextOptions.docsPath = docChoices[0];
+        nextOptions.selectionSources.docs = "workspace_single_doc";
+        changed = true;
+      } else if (failure?.code === "missing_docs" || docChoices.length > 1 || discovery.workspaceRoot) {
+        if (!allowPrompt) {
+          return null;
+        }
+        const selectedDocs = await promptForDocsPath(promptSession, discovery, cwd);
+        if (!selectedDocs) {
+          return null;
+        }
+        nextOptions.docsPath = selectedDocs;
+        nextOptions.selectionSources.docs = "interactive";
+        changed = true;
+        console.log(`已选择开发文档：${toDisplayPath(selectedDocs)}`);
+        console.log("");
+      }
+    }
+
+    const repoChoices = Array.isArray(discovery.repoCandidates) ? discovery.repoCandidates : [];
+    if (!nextOptions.repoRoot && repoChoices.length) {
+      if (repoChoices.length === 1) {
+        nextOptions.repoRoot = repoChoices[0];
+        nextOptions.selectionSources.repo = "workspace_single_repo";
+        changed = true;
+      }
+    }
+
+    if (!nextOptions.repoRoot && failure?.code === "missing_repo") {
+      if (!allowPrompt) {
+        return null;
+      }
+      const selectedRepo = await promptForRepoPath(promptSession, discovery, cwd);
+      if (!selectedRepo.repoRoot) {
+        return null;
+      }
+      nextOptions.repoRoot = selectedRepo.repoRoot;
+      nextOptions.allowNewRepoRoot = selectedRepo.allowNewRepoRoot;
+      nextOptions.selectionSources.repo = selectedRepo.allowNewRepoRoot
+        ? "interactive_new_repo"
+        : "interactive";
+      changed = true;
+      if (selectedRepo.allowNewRepoRoot) {
+        console.log(`已指定项目路径（当前不存在，将按新项目创建）：${toDisplayPath(selectedRepo.repoRoot)}`);
+      } else {
+        console.log(`已选择项目仓库：${toDisplayPath(selectedRepo.repoRoot)}`);
+      }
+      console.log("");
+    }
+    return changed ? nextOptions : null;
+  } finally {
+    if (ownsPromptSession) {
+      promptSession?.close();
+    }
+  }
+}

package/src/engine_metadata.mjs

@@ -0,0 +1,79 @@
+const ENGINE_METADATA = {
+  codex: {
+    name: "codex",
+    displayName: "Codex",
+    commandName: "codex",
+    hostDisplayName: "Codex CLI",
+  },
+  claude: {
+    name: "claude",
+    displayName: "Claude",
+    commandName: "claude",
+    hostDisplayName: "Claude Code",
+  },
+  gemini: {
+    name: "gemini",
+    displayName: "Gemini",
+    commandName: "gemini",
+    hostDisplayName: "Gemini CLI",
+  },
+};
+
+const HOST_METADATA = {
+  terminal: {
+    name: "terminal",
+    displayName: "终端",
+  },
+  codex: {
+    name: "codex",
+    displayName: "Codex",
+  },
+  claude: {
+    name: "claude",
+    displayName: "Claude",
+  },
+  gemini: {
+    name: "gemini",
+    displayName: "Gemini",
+  },
+};
+
+export function listKnownEngines() {
+  return Object.keys(ENGINE_METADATA);
+}
+
+export function normalizeEngineName(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return ENGINE_METADATA[normalized] ? normalized : "";
+}
+
+export function isKnownEngine(value) {
+  return Boolean(normalizeEngineName(value));
+}
+
+export function getEngineMetadata(engine) {
+  return ENGINE_METADATA[normalizeEngineName(engine)] || null;
+}
+
+export function getEngineDisplayName(engine) {
+  return getEngineMetadata(engine)?.displayName || String(engine || "").trim();
+}
+
+export function normalizeHostContext(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) {
+    return "terminal";
+  }
+  if (normalized === "shell") {
+    return "terminal";
+  }
+  return HOST_METADATA[normalized] ? normalized : "terminal";
+}
+
+export function getHostMetadata(hostContext) {
+  return HOST_METADATA[normalizeHostContext(hostContext)] || HOST_METADATA.terminal;
+}
+
+export function getHostDisplayName(hostContext) {
+  return getHostMetadata(hostContext).displayName;
+}