@nuvlore/extension-bds 0.1.1

package/tools/bds_environment_host_lookup.mjs

@@ -0,0 +1,741 @@
+export const description = "Find concrete private-cloud BDS hosts from the latest authoritative BDS config repo, returning config JSON paths and role-based host lists such as kube control planes, workers, etcd, NameNodes, and DataNodes.";
+
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { defineReadOnlyTool, fail, ok } from "@nuvlore/extension-read-only-toolkit/devops-diagnostics";
+import { configuredDataPath, devopsCachePath } from "@nuvlore/extension-read-only-toolkit/devops-data-paths";
+
+const execFileAsync = promisify(execFile);
+
+const BDS_REPOS = {
+  dev: "ssh://git@bitbucket.workday.com:7999/bds/bds-config-dev.git",
+  production: "ssh://git@bitbucket.workday.com:7999/bds/bds-config-cust.git",
+  "non-production": "ssh://git@bitbucket.workday.com:7999/bds/bds-config-nprd.git"
+};
+
+const ENV_ALIASES = new Map([
+  ["dev", "dev"],
+  ["development", "dev"],
+  ["prod", "production"],
+  ["production", "production"],
+  ["cust", "production"],
+  ["customer", "production"],
+  ["nprd", "non-production"],
+  ["nonprod", "non-production"],
+  ["non-prod", "non-production"],
+  ["non-production", "non-production"],
+  ["implementation", "non-production"],
+  ["impl", "non-production"]
+]);
+
+const DEFAULT_ROLES = ["kube_control_planes", "kube_workers", "etcd"];
+const ROLE_PATHS = {
+  kube_control_planes: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  control_planes: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  kube_workers: [
+    "bds.kubernetes.kube_workers",
+    "kubernetes.kube_workers"
+  ],
+  workers: [
+    "bds.kubernetes.kube_workers",
+    "kubernetes.kube_workers"
+  ],
+  etcd: [
+    "bds.kubernetes.etcd",
+    "bds.kubernetes.etcd_hosts",
+    "kubernetes.etcd",
+    "kubernetes.etcd_hosts"
+  ],
+  namenodes: [
+    "bds.active_name_node",
+    "bds.standby_name_node",
+    "bds.namenodes",
+    "bds.name_nodes",
+    "bds.hdfs.namenodes",
+    "bds.hdfs.name_nodes",
+    "hdfs.namenodes",
+    "hdfs.name_nodes",
+    "hdfs/name_nodes",
+    "hdfs/namenodes"
+  ],
+  namenode: [
+    "bds.active_name_node",
+    "bds.standby_name_node",
+    "bds.namenodes",
+    "bds.name_nodes",
+    "bds.hdfs.namenodes",
+    "bds.hdfs.name_nodes",
+    "hdfs.namenodes",
+    "hdfs.name_nodes",
+    "hdfs/name_nodes",
+    "hdfs/namenodes"
+  ],
+  datanodes: [
+    "bds.data_nodes",
+    "bds.datanodes",
+    "bds.data_nodes",
+    "bds.hdfs.datanodes",
+    "bds.hdfs.data_nodes"
+  ],
+  datanode: [
+    "bds.data_nodes",
+    "bds.datanodes",
+    "bds.hdfs.datanodes",
+    "bds.hdfs.data_nodes"
+  ],
+  journalnodes: [
+    "bds.journal_nodes",
+    "bds.journalnodes",
+    "bds.hdfs.journal_nodes",
+    "bds.hdfs.journalnodes"
+  ],
+  journalnode: [
+    "bds.journal_nodes",
+    "bds.journalnodes",
+    "bds.hdfs.journal_nodes",
+    "bds.hdfs.journalnodes"
+  ],
+  resourcemanagers: [
+    "bds.active_resource_manager_node",
+    "bds.standby_resource_manager_node",
+    "bds.resource_managers",
+    "bds.yarn.resource_managers",
+    "bds.yarn.resourcemanagers"
+  ],
+  resourcemanager: [
+    "bds.active_resource_manager_node",
+    "bds.standby_resource_manager_node",
+    "bds.resource_managers",
+    "bds.yarn.resource_managers",
+    "bds.yarn.resourcemanagers"
+  ],
+  nodemanagers: [
+    "bds.data_nodes",
+    "bds.node_managers",
+    "bds.yarn.node_managers",
+    "bds.yarn.nodemanagers"
+  ],
+  nodemanager: [
+    "bds.data_nodes",
+    "bds.node_managers",
+    "bds.yarn.node_managers",
+    "bds.yarn.nodemanagers"
+  ],
+  zookeeper: [
+    "bds.zookeeper_nodes"
+  ],
+  zk: [
+    "bds.zookeeper_nodes"
+  ],
+  kms: [
+    "bds.kms_nodes",
+    "bds.kms_nodes_cnames"
+  ],
+  history_server: [
+    "bds.history_server_node"
+  ],
+  mapreduce_history_server: [
+    "bds.history_server_node"
+  ],
+  spark_history_server: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  oozie: [
+    "bds.oozie.oozie_nodes",
+    "bds.oozie.mysql_node"
+  ],
+  bdm: [
+    "bds.active_bdm",
+    "bds.standby_bdm",
+    "active_bdm",
+    "standby_bdm"
+  ],
+  airflow: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  bas: [
+    "bds.bas.nodes",
+    "bds.bas.hosts",
+    "bds.admin_nodes",
+    "bds.oozie.oozie_nodes"
+  ],
+  tenant_data_operation: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  tenant_clone: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  tenant_dr: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  dr_pull: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  finalizer: [
+    "bds.kubernetes.kube_control_planes",
+    "kubernetes.kube_control_planes"
+  ],
+  service_proxy: [
+    "bds.bds_service_proxy.service_proxy_nodes"
+  ],
+  bds_service_proxy: [
+    "bds.bds_service_proxy.service_proxy_nodes"
+  ]
+};
+
+const SKIP_CLUSTER_BASENAMES = new Set(["bdm_bds_mapping", "bds_master_ldap"]);
+
+function bdsConfigCacheRoot() {
+  return configuredDataPath(
+    "DEVOPS_BDS_CONFIG_CACHE_ROOT",
+    "cache.bdsConfig",
+    devopsCachePath("bds-config")
+  );
+}
+
+function normalizeText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeEnvironment(env) {
+  const normalized = normalizeText(env).toLowerCase();
+  const resolved = ENV_ALIASES.get(normalized);
+  if (!resolved) {
+    throw new Error(`Unsupported BDS environment: ${env}. Use dev, production, or non-production.`);
+  }
+  return resolved;
+}
+
+function repoUrlForEnvironment(env) {
+  return BDS_REPOS[normalizeEnvironment(env)];
+}
+
+function repoDirForEnvironment(cacheRoot, env) {
+  return join(cacheRoot, basename(repoUrlForEnvironment(env), ".git"));
+}
+
+async function pathExists(path) {
+  try {
+    await fs.access(path);
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function assertStructuredHitlApproval(input, context) {
+  const approval = input.hitlApproval;
+  if (!approval || typeof approval !== "object") {
+    throw new Error(`${context} requires structured HITL approval with approved, approvedBy, action, target, reason, expectedImpact, and risk.`);
+  }
+
+  const missing = ["approvedBy", "action", "target", "reason", "expectedImpact", "risk"]
+    .filter((key) => !normalizeText(approval[key]));
+  if (approval.approved !== true || missing.length > 0) {
+    throw new Error(`${context} requires approved=true and complete HITL details: ${missing.join(", ") || "approved"}.`);
+  }
+}
+
+async function git(repoPath, args, input, execFileImpl = execFileAsync) {
+  return execFileImpl("git", ["-C", repoPath, ...args], {
+    timeout: input.timeoutMs,
+    maxBuffer: 1024 * 1024 * 10
+  });
+}
+
+async function pullLatest(repoPath, input, execFileImpl = execFileAsync) {
+  try {
+    await git(repoPath, ["pull", "--ff-only"], input, execFileImpl);
+    return { repoPath, repoFreshness: "pulled_latest_with_git_pull_ff_only" };
+  } catch (error) {
+    const message = String(error?.stderr || error?.stdout || error?.message || "");
+    if (!/no tracking information|no upstream branch|There is no tracking information/u.test(message)) {
+      throw error;
+    }
+    await git(repoPath, ["fetch", "origin", "master"], input, execFileImpl);
+    const treeRoot = await materializeGitTree(repoPath, "origin/master", input, execFileImpl);
+    return {
+      repoPath: treeRoot,
+      sourceRepoPath: repoPath,
+      repoFreshness: "fetched_origin_master_snapshot_no_tracking_branch"
+    };
+  }
+}
+
+async function materializeGitTree(repoPath, ref, input, execFileImpl = execFileAsync) {
+  const rev = (await git(repoPath, ["rev-parse", "--short=12", ref], input, execFileImpl)).stdout.trim();
+  const safeName = basename(repoPath).replace(/[^a-zA-Z0-9._-]+/gu, "_");
+  const treeRoot = join(tmpdir(), `eldwin-bds-config-${safeName}-${rev}`);
+  if (await pathExists(treeRoot)) return treeRoot;
+  await fs.mkdir(treeRoot, { recursive: true });
+  const archivePath = join(tmpdir(), `eldwin-bds-config-${safeName}-${rev}.tar`);
+  await git(repoPath, ["archive", "--format=tar", `--output=${archivePath}`, ref], input, execFileImpl);
+  await execFileImpl("tar", ["-xf", archivePath, "-C", treeRoot], {
+    timeout: input.timeoutMs,
+    maxBuffer: 1024 * 1024 * 100
+  });
+  await fs.rm(archivePath, { force: true });
+  return treeRoot;
+}
+
+async function ensureRepo(env, input, execFileImpl = execFileAsync) {
+  const explicitRepoPath = normalizeText(input.repoPath);
+  if (explicitRepoPath) {
+    if (!(await pathExists(join(explicitRepoPath, ".git")))) {
+      throw new Error(`repoPath must be a git checkout so bds_environment_host_lookup can pull latest code before lookup: ${explicitRepoPath}`);
+    }
+    return pullLatest(explicitRepoPath, input, execFileImpl);
+  }
+
+  const environment = normalizeEnvironment(env);
+  const cacheRoot = normalizeText(input.cacheRoot) || bdsConfigCacheRoot();
+  const repoPath = repoDirForEnvironment(cacheRoot, environment);
+  const repoUrl = repoUrlForEnvironment(environment);
+
+  if (await pathExists(join(repoPath, ".git"))) {
+    return pullLatest(repoPath, input, execFileImpl);
+  }
+
+  if (!input.allowCacheUpdate) {
+    throw new Error(`Local BDS config cache is missing at ${repoPath}. Provide repoPath for an existing checkout or set allowCacheUpdate=true to explicitly clone the read-only config repo.`);
+  }
+  assertStructuredHitlApproval(input, "BDS environment host lookup cache clone");
+  await fs.mkdir(cacheRoot, { recursive: true });
+  await execFileImpl("git", ["clone", "--depth", "1", repoUrl, repoPath], {
+    timeout: input.timeoutMs,
+    maxBuffer: 1024 * 1024 * 10
+  });
+  return { repoPath, repoFreshness: "cloned_latest_readonly_cache" };
+}
+
+async function listJsonFiles(root) {
+  const files = [];
+  if (!(await pathExists(root))) return files;
+  const entries = await fs.readdir(root, { withFileTypes: true });
+  for (const entry of entries) {
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await listJsonFiles(path));
+    } else if (entry.isFile() && entry.name.endsWith(".json")) {
+      files.push(path);
+    }
+  }
+  return files;
+}
+
+async function loadClusterDocuments(repoPath) {
+  const files = [
+    ...await listJsonFiles(join(repoPath, "data_bags", "bds")),
+    ...await listJsonFiles(join(repoPath, "config", "bds"))
+  ];
+  const docs = [];
+  for (const filePath of files.sort()) {
+    const cluster = basename(filePath, ".json");
+    if (SKIP_CLUSTER_BASENAMES.has(cluster) && !["bdm_bds_mapping", "bdm_config"].includes(cluster)) continue;
+    try {
+      const document = JSON.parse(await fs.readFile(filePath, "utf8"));
+      docs.push({ cluster, filePath, document });
+    } catch (error) {
+      docs.push({ cluster, filePath, parseError: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return docs;
+}
+
+function getPathValue(value, dotPath) {
+  return dotPath.split(/[./]+/u).filter(Boolean).reduce((current, part) => {
+    if (current === undefined || current === null) return undefined;
+    return current[part];
+  }, value);
+}
+
+function asStringList(value) {
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => typeof item === "string" ? [item.trim()] : []).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(/[,\s]+/u).map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function normalizeRole(role) {
+  return normalizeText(role).replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+}
+
+function pathsForRole(role) {
+  const normalized = normalizeRole(role);
+  return ROLE_PATHS[normalized] ?? [
+    role,
+    `bds.${role}`,
+    `bds.${normalized}`,
+    `bds.${normalized}_nodes`,
+    `bds.${normalized}_hosts`,
+    `bds.${normalized}_cnames`
+  ];
+}
+
+function clusterMatches(cluster, query) {
+  const raw = normalizeText(query);
+  return !raw || cluster.toLowerCase() === raw.toLowerCase() || cluster.toLowerCase().includes(raw.toLowerCase());
+}
+
+function bdmHostsFromMappingDocs(docs, cluster) {
+  const targetCluster = normalizeText(cluster).toLowerCase();
+  if (!targetCluster) return [];
+  return docs.flatMap((doc) => {
+    if (!["bdm_bds_mapping", "bdm_config"].includes(doc.cluster) || doc.parseError || !doc.document || typeof doc.document !== "object") return [];
+    return Object.entries(doc.document)
+      .filter(([, value]) => normalizeText(typeof value === "string" ? value : value?.cluster_name).toLowerCase() === targetCluster)
+      .map(([host]) => ({ host, path: `${doc.filePath}#${host}` }));
+  });
+}
+
+function hostEntries(hosts, path, extra = {}) {
+  return asStringList(hosts).map((host) => ({ host, path, ...extra }));
+}
+
+function extractHdfsNamespaces(document) {
+  const bds = document?.bds ?? {};
+  const namespaces = [];
+  if (Array.isArray(bds.hdfs)) {
+    for (const [index, hdfs] of bds.hdfs.entries()) {
+      const namespace = normalizeText(hdfs?.namespace) || `hdfs_${index}`;
+      namespaces.push({
+        namespace,
+        activeNameNode: normalizeText(hdfs?.active_name_node),
+        standbyNameNode: normalizeText(hdfs?.standby_name_node),
+        nameNodes: dedupeHostEntries([
+          ...hostEntries(hdfs?.name_nodes, `bds.hdfs.${index}.name_nodes`, { namespace }),
+          ...hostEntries(hdfs?.active_name_node, `bds.hdfs.${index}.active_name_node`, { namespace }),
+          ...hostEntries(hdfs?.standby_name_node, `bds.hdfs.${index}.standby_name_node`, { namespace })
+        ]),
+        dataNodes: dedupeHostEntries(hostEntries(hdfs?.data_nodes, `bds.hdfs.${index}.data_nodes`, { namespace }))
+      });
+    }
+  }
+  if (namespaces.length === 0 && bds.hdfs && typeof bds.hdfs === "object" && !Array.isArray(bds.hdfs)) {
+    const namespace = normalizeText(bds.hdfs.namespace) || "default";
+    const nameNodes = [
+      ...hostEntries(bds.hdfs.name_nodes ?? bds.hdfs.namenodes, "bds.hdfs.name_nodes", { namespace }),
+      ...hostEntries(bds.hdfs.active_name_node, "bds.hdfs.active_name_node", { namespace }),
+      ...hostEntries(bds.hdfs.standby_name_node, "bds.hdfs.standby_name_node", { namespace })
+    ];
+    const dataNodes = hostEntries(bds.hdfs.data_nodes ?? bds.hdfs.datanodes, "bds.hdfs.data_nodes", { namespace });
+    if (nameNodes.length || dataNodes.length) {
+      namespaces.push({
+        namespace,
+        activeNameNode: normalizeText(bds.hdfs.active_name_node),
+        standbyNameNode: normalizeText(bds.hdfs.standby_name_node),
+        nameNodes: dedupeHostEntries(nameNodes),
+        dataNodes: dedupeHostEntries(dataNodes)
+      });
+    }
+  }
+  if (namespaces.length === 0 && (bds.active_name_node || bds.standby_name_node || bds.data_nodes)) {
+    const namespace = normalizeText(bds.namespace) || "default";
+    namespaces.push({
+      namespace,
+      activeNameNode: normalizeText(bds.active_name_node),
+      standbyNameNode: normalizeText(bds.standby_name_node),
+      nameNodes: dedupeHostEntries([
+        ...hostEntries(bds.active_name_node, "bds.active_name_node", { namespace }),
+        ...hostEntries(bds.standby_name_node, "bds.standby_name_node", { namespace })
+      ]),
+      dataNodes: dedupeHostEntries(hostEntries(bds.data_nodes, "bds.data_nodes", { namespace }))
+    });
+  }
+  if (namespaces.length === 0) {
+    const hdfs = document?.hdfs ?? {};
+    const nameNodes = hostEntries(hdfs.name_nodes ?? hdfs.namenodes, "hdfs.name_nodes", { namespace: "default" });
+    const dataNodes = hostEntries(hdfs.data_nodes ?? hdfs.datanodes, "hdfs.data_nodes", { namespace: "default" });
+    if (nameNodes.length || dataNodes.length) {
+      namespaces.push({
+        namespace: "default",
+        activeNameNode: "",
+        standbyNameNode: "",
+        nameNodes: dedupeHostEntries(nameNodes),
+        dataNodes: dedupeHostEntries(dataNodes)
+      });
+    }
+  }
+  return namespaces;
+}
+
+function extractClusterPatterns(doc, docs) {
+  const bds = doc.document?.bds ?? {};
+  const hdfsNamespaces = extractHdfsNamespaces(doc.document);
+  return {
+    hdfsNamespaces,
+    kubernetes: {
+      controlPlanes: dedupeHostEntries(hostEntries(bds.kubernetes?.kube_control_planes ?? doc.document?.kubernetes?.kube_control_planes, "bds.kubernetes.kube_control_planes")),
+      workers: dedupeHostEntries(hostEntries(bds.kubernetes?.kube_workers ?? doc.document?.kubernetes?.kube_workers, "bds.kubernetes.kube_workers")),
+      etcd: dedupeHostEntries(hostEntries(bds.kubernetes?.etcd_hosts ?? bds.kubernetes?.etcd ?? doc.document?.kubernetes?.etcd_hosts, "bds.kubernetes.etcd_hosts"))
+    },
+    bdm: dedupeHostEntries([
+      ...bdmHostsFromMappingDocs(docs, doc.cluster),
+      ...hostEntries(bds.active_bdm, "bds.active_bdm"),
+      ...hostEntries(bds.standby_bdm, "bds.standby_bdm"),
+      ...hostEntries(doc.document?.active_bdm, "active_bdm"),
+      ...hostEntries(doc.document?.standby_bdm, "standby_bdm")
+    ]),
+    bas: dedupeHostEntries([
+      ...hostEntries(bds.bas?.nodes, "bds.bas.nodes"),
+      ...hostEntries(bds.bas?.hosts, "bds.bas.hosts"),
+      ...hostEntries(bds.admin_nodes, "bds.admin_nodes"),
+      ...hostEntries(bds.oozie?.oozie_nodes, "bds.oozie.oozie_nodes", { legacyConfigField: true, serviceRole: "bas_admin_host" })
+    ]),
+    oozie: dedupeHostEntries(hostEntries(bds.oozie?.oozie_nodes, "bds.oozie.oozie_nodes")),
+    kms: dedupeHostEntries([
+      ...hostEntries(bds.kms_nodes, "bds.kms_nodes"),
+      ...hostEntries(bds.kms_nodes_cnames, "bds.kms_nodes_cnames")
+    ]),
+    zookeeper: dedupeHostEntries(hostEntries(bds.zookeeper_nodes, "bds.zookeeper_nodes")),
+    journalNodes: dedupeHostEntries(hostEntries(bds.journal_nodes, "bds.journal_nodes")),
+    resourceManagers: dedupeHostEntries([
+      ...hostEntries(bds.active_resource_manager_node, "bds.active_resource_manager_node"),
+      ...hostEntries(bds.standby_resource_manager_node, "bds.standby_resource_manager_node")
+    ]),
+    historyServer: dedupeHostEntries(hostEntries(bds.history_server_node, "bds.history_server_node")),
+    sparkHistoryServer: dedupeHostEntries(hostEntries(bds.kubernetes?.kube_control_planes ?? doc.document?.kubernetes?.kube_control_planes, "bds.kubernetes.kube_control_planes", {
+      namespace: "bds-k8s-services",
+      serviceRole: "spark_history_server_k8s",
+      resourceNames: dedupeStrings([
+        ...asStringList(bds.spark_history_server_k8s_list),
+        ...asStringList(doc.document?.dcs?.map?.((dc) => dc?.spark_history_server_k8s).filter(Boolean))
+      ])
+    })),
+    serviceProxy: dedupeHostEntries(hostEntries(bds.bds_service_proxy?.service_proxy_nodes, "bds.bds_service_proxy.service_proxy_nodes"))
+  };
+}
+
+function patternHostsForRole(patterns, role) {
+  const normalized = normalizeRole(role);
+  if (["namenode", "namenodes", "name_node", "name_nodes"].includes(normalized)) {
+    return patterns.hdfsNamespaces.flatMap((namespace) => namespace.nameNodes);
+  }
+  if (["datanode", "datanodes", "data_node", "data_nodes"].includes(normalized)) {
+    return patterns.hdfsNamespaces.flatMap((namespace) => namespace.dataNodes);
+  }
+  if (["nodemanager", "nodemanagers", "node_manager", "node_managers"].includes(normalized)) {
+    return patterns.hdfsNamespaces.flatMap((namespace) => namespace.dataNodes);
+  }
+  if ([
+    "kube_control_planes",
+    "kube_control_plane",
+    "control_planes",
+    "airflow",
+    "tenant_data_operation",
+    "tenant_clone",
+    "tenant_dr",
+    "dr_pull",
+    "finalizer"
+  ].includes(normalized)) return patterns.kubernetes.controlPlanes;
+  if (["kube_workers", "workers"].includes(normalized)) return patterns.kubernetes.workers;
+  if (normalized === "etcd") return patterns.kubernetes.etcd;
+  if (normalized === "bdm") return patterns.bdm;
+  if (normalized === "bas") return patterns.bas;
+  if (normalized === "oozie") return patterns.oozie;
+  if (normalized === "kms") return patterns.kms;
+  if (["zookeeper", "zk"].includes(normalized)) return patterns.zookeeper;
+  if (["journalnode", "journalnodes", "journal_node", "journal_nodes"].includes(normalized)) return patterns.journalNodes;
+  if (["resourcemanager", "resourcemanagers", "resource_manager", "resource_managers"].includes(normalized)) return patterns.resourceManagers;
+  if (["history_server", "mapreduce_history_server"].includes(normalized)) return patterns.historyServer;
+  if (["spark_history_server", "shs"].includes(normalized)) return patterns.sparkHistoryServer;
+  if (["service_proxy", "bds_service_proxy"].includes(normalized)) return patterns.serviceProxy;
+  return [];
+}
+
+function lookupHosts(docs, input) {
+  const roles = input.roles.length ? input.roles : DEFAULT_ROLES;
+  const requestedPaths = input.hostFields.length ? input.hostFields : roles.flatMap(pathsForRole);
+  const matches = [];
+  const parseErrors = [];
+
+  for (const doc of docs) {
+    if (doc.parseError) {
+      parseErrors.push({ cluster: doc.cluster, filePath: doc.filePath, error: doc.parseError });
+      continue;
+    }
+    if (!clusterMatches(doc.cluster, input.cluster)) continue;
+
+    const hostsByRole = {};
+    const matchedPaths = [];
+    const patterns = extractClusterPatterns(doc, docs);
+    for (const role of roles) {
+      const roleHosts = patternHostsForRole(patterns, role);
+      if (roleHosts.length > 0) matchedPaths.push(...roleHosts.map((entry) => entry.path));
+      for (const path of input.hostFields.length ? requestedPaths : pathsForRole(role)) {
+        const hosts = asStringList(getPathValue(doc.document, path));
+        if (hosts.length === 0) continue;
+        matchedPaths.push(path);
+        roleHosts.push(...hosts.map((host) => ({ host, path })));
+      }
+      hostsByRole[normalizeRole(role)] = dedupeHostEntries(roleHosts);
+    }
+
+    if (input.hostFields.length) {
+      hostsByRole.explicit_fields = dedupeHostEntries(requestedPaths.flatMap((path) =>
+        asStringList(getPathValue(doc.document, path)).map((host) => ({ host, path }))
+      ));
+    }
+
+    const hostCount = Object.values(hostsByRole).reduce((sum, values) => sum + values.length, 0);
+    if (hostCount > 0 || input.includeEmptyMatches) {
+      matches.push({
+        cluster: doc.cluster,
+        filePath: doc.filePath,
+        matchedPaths: Array.from(new Set(matchedPaths)).sort(),
+        patterns,
+        hostsByRole
+      });
+    }
+  }
+
+  return { matches, parseErrors };
+}
+
+function dedupeHostEntries(entries) {
+  const seen = new Set();
+  const result = [];
+  for (const entry of entries) {
+    const key = entry.host;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(entry);
+  }
+  return result;
+}
+
+function dedupeStrings(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function normalizeInput(input = {}) {
+  return {
+    environment: normalizeEnvironment(input.environment ?? "production"),
+    cluster: normalizeText(input.cluster),
+    roles: Array.isArray(input.roles) ? input.roles.map(normalizeText).filter(Boolean) : [],
+    hostFields: Array.isArray(input.hostFields) ? input.hostFields.map(normalizeText).filter(Boolean) : [],
+    repoPath: normalizeText(input.repoPath),
+    cacheRoot: normalizeText(input.cacheRoot) || bdsConfigCacheRoot(),
+    allowCacheUpdate: input.allowCacheUpdate === true,
+    hitlApproval: input.hitlApproval,
+    includeEmptyMatches: input.includeEmptyMatches === true,
+    timeoutMs: Number.isInteger(input.timeoutMs) ? Math.max(1000, input.timeoutMs) : 120_000
+  };
+}
+
+export class BdsEnvironmentHostLookupService {
+  constructor(options = {}) {
+    this.execFileImpl = options.execFileImpl || execFileAsync;
+    this.loadClusterDocuments = options.loadClusterDocuments || loadClusterDocuments;
+  }
+
+  async invoke(input) {
+    const normalized = normalizeInput(input);
+    const repoInfo = await ensureRepo(normalized.environment, normalized, this.execFileImpl);
+    const repoPath = typeof repoInfo === "string" ? repoInfo : repoInfo.repoPath;
+    const docs = await this.loadClusterDocuments(repoPath);
+    const result = lookupHosts(docs, normalized);
+    return JSON.stringify({
+      environment: normalized.environment,
+      repoPath,
+      sourceRepoPath: repoInfo.sourceRepoPath,
+      cluster: normalized.cluster,
+      roles: normalized.roles.length ? normalized.roles : DEFAULT_ROLES,
+      hostFields: normalized.hostFields,
+      repoFreshness: repoInfo.repoFreshness ?? "pulled_latest_with_git_pull_ff_only",
+      ...result
+    }, null, 2);
+  }
+}
+
+async function bdsEnvironmentHostLookup(input, options = {}) {
+  return new BdsEnvironmentHostLookupService(options).invoke(input);
+}
+
+export const __test = {
+  BdsEnvironmentHostLookupService,
+  asStringList,
+  bdsEnvironmentHostLookup,
+  clusterMatches,
+  dedupeHostEntries,
+  ensureRepo,
+  getPathValue,
+  lookupHosts,
+  bdmHostsFromMappingDocs,
+  extractClusterPatterns,
+  extractHdfsNamespaces,
+  patternHostsForRole,
+  normalizeEnvironment,
+  normalizeInput,
+  normalizeRole,
+  pathsForRole,
+  pullLatest,
+  repoDirForEnvironment,
+  repoUrlForEnvironment
+};
+
+const defaultService = new BdsEnvironmentHostLookupService();
+
+const sharedTool = defineReadOnlyTool({
+  name: "bds_environment_host_lookup",
+  description: "Find concrete private-cloud BDS hosts from the latest authoritative BDS config repo, returning config JSON paths and role-based host lists such as kube control planes, workers, etcd, NameNodes, and DataNodes.",
+  meta: {
+    permissions: { rule: "ask" }
+  },
+  inputSchema: {
+    environment: z.string().trim().min(1).max(64).default("production"),
+    cluster: z.string().trim().min(1).max(256).describe("BDS cluster/environment filter, for example BDS_ASH_CUST_AZ1."),
+    roles: z.array(z.string().trim().min(1).max(128)).max(32).default(DEFAULT_ROLES).describe("Host roles to resolve, for example kube_control_planes, kube_workers, etcd, namenodes, datanodes."),
+    hostFields: z.array(z.string().trim().min(1).max(512)).max(64).default([]).describe("Optional exact JSON dot paths. When provided, these override role path expansion."),
+    repoPath: z.string().trim().max(4096).default(""),
+    cacheRoot: z.string().trim().max(4096).default(bdsConfigCacheRoot()),
+    allowCacheUpdate: z.boolean().default(false).describe("Set true only after HITL approval to create the local read-only BDS config cache when missing."),
+    hitlApproval: z.object({
+      approved: z.literal(true),
+      approvedBy: z.string().trim().min(1).max(256),
+      action: z.string().trim().min(1).max(256),
+      target: z.string().trim().min(1).max(4096),
+      reason: z.string().trim().min(1).max(2000),
+      expectedImpact: z.string().trim().min(1).max(2000),
+      risk: z.string().trim().min(1).max(2000)
+    }).optional().describe("Required when allowCacheUpdate=true because that creates a local cache."),
+    includeEmptyMatches: z.boolean().default(false),
+    timeoutMs: z.number().int().positive().max(600_000).default(120_000)
+  },
+  async handler(input) {
+    try {
+      return ok(await defaultService.invoke(input));
+    } catch (error) {
+      return fail(error);
+    }
+  }
+});
+
+export default {
+  name: sharedTool.name,
+  description,
+  inputSchema: sharedTool.inputSchema,
+  meta: sharedTool.meta,
+  annotations: sharedTool.annotations,
+  invoke: sharedTool.invoke,
+  handler: sharedTool.handler
+};