@nuvlore/extension-bds 0.1.1

package/tools/bds_machine_inventory.mjs

@@ -0,0 +1,434 @@
+export const description = "List BDS machine types or hostnames from the authoritative BDS config repositories for dev, production, and non-production environments.";
+
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+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 SKIP_CLUSTER_BASENAMES = new Set(["bdm_bds_mapping", "bds_master_ldap"]);
+const DEFAULT_MAX_HOSTS = 500;
+const HOSTISH_PATTERN = /(^|[._-])(nodes?|hosts?|cnames?|servers?|masters?|workers?|managers?)($|[._-])/i;
+
+function bdsConfigCacheRoot() {
+  return configuredDataPath(
+    "DEVOPS_BDS_CONFIG_CACHE_ROOT",
+    "cache.bdsConfig",
+    devopsCachePath("bds-config"),
+  );
+}
+
+function normalizeText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+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"}.`);
+  }
+}
+
+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;
+  }
+}
+
+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_machine_inventory can pull latest code before lookup: ${explicitRepoPath}`);
+    }
+    await pullLatest(explicitRepoPath, input, execFileImpl);
+    return explicitRepoPath;
+  }
+
+  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"))) {
+    await pullLatest(repoPath, input, execFileImpl);
+    return repoPath;
+  }
+
+  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 config 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;
+}
+
+async function pullLatest(repoPath, input, execFileImpl = execFileAsync) {
+  await execFileImpl("git", ["-C", repoPath, "pull", "--ff-only"], {
+    timeout: input.timeoutMs,
+    maxBuffer: 1024 * 1024 * 10
+  });
+}
+
+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)) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+      docs.push({ cluster, filePath, document: parsed });
+    } catch (error) {
+      docs.push({ cluster, filePath, parseError: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return docs;
+}
+
+function walk(value, onLeaf, path = []) {
+  if (Array.isArray(value)) {
+    onLeaf(path, value);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const [key, child] of Object.entries(value)) {
+      walk(child, onLeaf, [...path, key]);
+    }
+    return;
+  }
+  onLeaf(path, value);
+}
+
+function getPathValue(value, dotPath) {
+  return dotPath.split(".").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]+/).map((item) => item.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function pathLooksHostLike(dotPath, value) {
+  if (!dotPath.startsWith("bds.")) {
+    return false;
+  }
+  if (dotPath.includes(".cluster_spec.")) {
+    return false;
+  }
+  if (!HOSTISH_PATTERN.test(dotPath)) {
+    return false;
+  }
+  return asStringList(value).length > 0;
+}
+
+function typeFromPath(dotPath) {
+  const last = dotPath.split(".").at(-1) || dotPath;
+  return last
+    .replace(/_(nodes?|hosts?|servers?)_cnames?$/i, "")
+    .replace(/-(nodes?|hosts?|servers?)-cnames?$/i, "")
+    .replace(/_(nodes?|hosts?|cnames?|servers?)$/i, "")
+    .replace(/-(nodes?|hosts?|cnames?|servers?)$/i, "")
+    .replace(/(Nodes?|Hosts?|Cnames?|Servers?)$/g, "")
+    .replace(/[^a-zA-Z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase() || last.toLowerCase();
+}
+
+function candidatePathsForMachineType(machineType) {
+  const raw = normalizeText(machineType);
+  if (!raw) return [];
+  const normalized = raw.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toLowerCase();
+  return Array.from(new Set([
+    raw,
+    `bds.${raw}`,
+    `bds.${normalized}`,
+    `bds.${normalized}_nodes`,
+    `bds.${normalized}_hosts`,
+    `bds.${normalized}_cnames`,
+    `bds.${normalized}_servers`
+  ]));
+}
+
+function matchesCluster(cluster, filter) {
+  const raw = normalizeText(filter);
+  return !raw || cluster.toLowerCase().includes(raw.toLowerCase());
+}
+
+function collectMachineTypes(docs, clusterFilter = "") {
+  const types = new Map();
+  const parseErrors = [];
+  for (const doc of docs) {
+    if (doc.parseError) {
+      parseErrors.push({ cluster: doc.cluster, filePath: doc.filePath, error: doc.parseError });
+      continue;
+    }
+    if (!matchesCluster(doc.cluster, clusterFilter)) {
+      continue;
+    }
+    walk(doc.document, (path, value) => {
+      const dotPath = path.join(".");
+      if (!pathLooksHostLike(dotPath, value)) {
+        return;
+      }
+      const type = typeFromPath(dotPath);
+      const entry = types.get(type) ?? { type, paths: new Set(), clusters: new Set(), hostCount: 0 };
+      entry.paths.add(dotPath);
+      entry.clusters.add(doc.cluster);
+      entry.hostCount += asStringList(value).length;
+      types.set(type, entry);
+    });
+  }
+  return {
+    machineTypes: [...types.values()].map((entry) => ({
+      type: entry.type,
+      paths: [...entry.paths].sort(),
+      clusterCount: entry.clusters.size,
+      hostCount: entry.hostCount
+    })).sort((left, right) => left.type.localeCompare(right.type)),
+    parseErrors
+  };
+}
+
+function collectHosts(docs, input) {
+  const hostField = normalizeText(input.hostField);
+  const machineType = normalizeText(input.machineType);
+  const candidatePaths = hostField ? [hostField, `bds.${hostField}`] : candidatePathsForMachineType(machineType);
+  const maxHosts = input.maxHosts;
+  const hosts = [];
+  const matchedPaths = new Set();
+  const parseErrors = [];
+  let truncated = false;
+
+  for (const doc of docs) {
+    if (doc.parseError) {
+      parseErrors.push({ cluster: doc.cluster, filePath: doc.filePath, error: doc.parseError });
+      continue;
+    }
+    if (!matchesCluster(doc.cluster, input.cluster)) {
+      continue;
+    }
+
+    const addHosts = (dotPath, values) => {
+      if (values.length === 0) return;
+      matchedPaths.add(dotPath);
+      for (const host of values) {
+        if (hosts.length >= maxHosts) {
+          truncated = true;
+          return;
+        }
+        hosts.push({ cluster: doc.cluster, type: typeFromPath(dotPath), path: dotPath, host });
+      }
+    };
+
+    if (candidatePaths.length > 0) {
+      for (const dotPath of candidatePaths) {
+        addHosts(dotPath, asStringList(getPathValue(doc.document, dotPath)));
+      }
+      continue;
+    }
+
+    walk(doc.document, (path, value) => {
+      if (truncated) return;
+      const dotPath = path.join(".");
+      if (pathLooksHostLike(dotPath, value)) {
+        addHosts(dotPath, asStringList(value));
+      }
+    });
+  }
+
+  return {
+    hosts,
+    matchedPaths: [...matchedPaths].sort(),
+    truncated,
+    parseErrors
+  };
+}
+
+export class BdsMachineInventoryService {
+  constructor(options = {}) {
+    this.execFileImpl = options.execFileImpl || execFileAsync;
+    this.loadClusterDocuments = options.loadClusterDocuments || loadClusterDocuments;
+  }
+
+  async invoke(input) {
+    const environment = normalizeEnvironment(input.environment);
+    const repoPath = await ensureRepo(environment, input, this.execFileImpl);
+    const docs = await this.loadClusterDocuments(repoPath);
+    const base = {
+      action: input.action,
+      environment,
+      repoPath,
+      clustersScanned: docs.filter((doc) => !doc.parseError && matchesCluster(doc.cluster, input.cluster)).length
+    };
+
+    if (input.action === "list_types") {
+      return JSON.stringify({
+        ...base,
+        ...collectMachineTypes(docs, input.cluster)
+      }, null, 2);
+    }
+
+    return JSON.stringify({
+      ...base,
+      machineType: normalizeText(input.machineType),
+      hostField: normalizeText(input.hostField),
+      ...collectHosts(docs, input)
+    }, null, 2);
+  }
+}
+
+async function bdsMachineInventory(input, options = {}) {
+  return new BdsMachineInventoryService(options).invoke(input);
+}
+
+export const __test = {
+  normalizeEnvironment,
+  repoUrlForEnvironment,
+  repoDirForEnvironment,
+  asStringList,
+  typeFromPath,
+  candidatePathsForMachineType,
+  collectMachineTypes,
+  collectHosts,
+  pullLatest,
+  loadClusterDocuments,
+  bdsMachineInventory,
+  BdsMachineInventoryService
+};
+
+const defaultService = new BdsMachineInventoryService();
+
+const sharedTool = defineReadOnlyTool({
+  name: "bds_machine_inventory",
+  description: "List BDS machine types or hostnames from the authoritative BDS config repositories for dev, production, and non-production environments.",
+  meta: {
+    permissions: { rule: "ask" }
+  },
+  inputSchema: {
+    action: z.enum(["list_types", "list_hosts"]).default("list_types"),
+    environment: z.string().trim().min(1).max(64).default("non-production"),
+    cluster: z.string().trim().max(256).default(""),
+    machineType: z.string().trim().max(256).default(""),
+    hostField: z.string().trim().max(512).default(""),
+    repoPath: z.string().trim().max(4096).default(""),
+    cacheRoot: z.string().trim().max(4096).default(bdsConfigCacheRoot()),
+    refresh: z.boolean().default(true).describe("Deprecated: bds_machine_inventory always pulls latest code before lookup."),
+    allowCacheUpdate: z.boolean().default(false).describe("Set true only after human-in-the-loop approval to create the local read-only BDS config cache when it is 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."),
+    maxHosts: z.number().int().positive().max(5000).default(DEFAULT_MAX_HOSTS),
+    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
+};

package/tools/bds_mapreduce_historyserver_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read MapReduce history server logs from a private-cloud history server host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_mapreduce_historyserver_log_read",
+  description: "Read MapReduce history server logs from a private-cloud history server host through the approved Boundary sudo read tool.",
+  glob: "/var/log/hadoop-mapreduce/mapred-mapred-historyserver-*.log /var/log/hadoop-mapreduce/mapred-mapred-historyserver-*.out"
+});
+
+export const __test = spec;
+
+const sharedTool = createPrivateCloudLogReadTool(spec);
+
+export default {
+  name: sharedTool.name,
+  description,
+  inputSchema: sharedTool.inputSchema,
+  meta: sharedTool.meta,
+  annotations: sharedTool.annotations,
+  invoke: sharedTool.invoke,
+  handler: sharedTool.handler
+};

package/tools/bds_migration_service_operation_command_pack.mjs

@@ -0,0 +1,233 @@
+export const description = "Generate a atomic-helper, read-only BDS migration-service command/API pack from Slack event facts, Jira links, HDFS tenant records, cutover state, and optional S3 VPCE probes; does not call Jira, SSH, or inspect HDFS.";
+
+import { z } from "zod";
+import { defineReadOnlyTool, fail, ok } from "@nuvlore/extension-read-only-toolkit/devops-diagnostics";
+
+const identifierSchema = z.string().trim().min(1).max(255).regex(/^[A-Za-z0-9_.:@+=,~%/-]+$/).optional();
+const tenantSchema = z.string().trim().min(1).max(255).regex(/^[A-Za-z0-9_.:-]+$/).optional();
+const hostSchema = z.string().trim().min(1).max(255).regex(/^(?!-)[a-zA-Z0-9._:@%-]+$/);
+const hdfsPathSchema = z.string().trim().min(1).max(2048).regex(/^hdfs:\/\/[A-Za-z0-9_.:-]+\/.+$/).optional();
+const urlSchema = z.string().trim().url().max(2048).optional();
+const migrationRunTypeSchema = z.enum(["FIRST_MIGRATION", "DIFF_MIGRATION", "CUTOVER_MIGRATION", "BUCKET_SYNC"]).optional();
+
+const SAFETY_RULES = [
+  "read-only only: use Slack facts, Jira reads, Confluence reads, Airflow callback evidence, HDFS tenant record reads, Kubernetes metadata, DNS/route lookup, and bounded curl connect probes",
+  "do not cancel, retry, trigger, or mutate migration-service runs from this command pack",
+  "do not run Airflow clear/backfill/trigger/mark_success or any DAG/task state mutation",
+  "do not write HDFS, S3, Kubernetes, or local files; in particular do not use aws s3 cp as a connectivity test",
+  "derive HDFS authority from evidence instead of guessing or shortening cluster names",
+  "treat Slack thread as event source and Jira as tracking/follow-up evidence"
+];
+
+const INTERPRETATION_RULES = [
+  "FIRST_MIGRATION, DIFF_MIGRATION, CUTOVER_MIGRATION, bucket sync, PRISM_READY, and event COMPLETED are migration-service state-chain evidence.",
+  "Only cutover run allowed ... Discarding message for DIFF_MIGRATION during cutover is state-machine evidence, not an Airflow trigger failure.",
+  "A recovery is not complete from copy success alone; verify source/target file counts, bucket sync, PRISM_READY, and event COMPLETED when applicable.",
+  "If a main Jira exists, read issuelinks and use a linked monitoring/product follow-up Jira for on-call report follow-up when present.",
+  "For S3 endpoint failures, http=000 plus connect timeout means the request did not reach HTTP/S3 authorization; HTTP 307 or another HTTP status from an alternate endpoint proves that endpoint path is reachable."
+];
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+function summaryLines(input) {
+  return [
+    input.slackThreadUrl ? `slackThreadUrl=${input.slackThreadUrl}` : "",
+    input.migrationEventId ? `migrationEventId=${input.migrationEventId}` : "",
+    input.sourceCluster ? `sourceCluster=${input.sourceCluster}` : "",
+    input.sourceEnvironment ? `sourceEnvironment=${input.sourceEnvironment}` : "",
+    input.targetEnvironment ? `targetEnvironment=${input.targetEnvironment}` : "",
+    input.sourceTenant ? `sourceTenant=${input.sourceTenant}` : "",
+    input.targetTenant ? `targetTenant=${input.targetTenant}` : "",
+    input.migrationRunType ? `migrationRunType=${input.migrationRunType}` : "",
+    input.snapshotId ? `snapshotId=${input.snapshotId}` : "",
+    input.fromSnapshotId ? `fromSnapshotId=${input.fromSnapshotId}` : "",
+    input.dagRunId ? `dagRunId=${input.dagRunId}` : "",
+    input.cutoverDateUtc ? `cutoverDateUtc=${input.cutoverDateUtc}` : "",
+    input.tenantHdfsPath ? `tenantHdfsPath=${input.tenantHdfsPath}` : "",
+    input.mainJira ? `mainJira=${input.mainJira}` : "",
+    input.followUpJira ? `followUpJira=${input.followUpJira}` : ""
+  ].filter(Boolean);
+}
+
+function tenantRecordScript(input) {
+  const path = input.tenantHdfsPath || "hdfs://<cluster-authority>/data/tenants/<ENV>.<tenant>";
+  return [
+    "set -eu",
+    `tenant_path=${shellQuote(path)}`,
+    "echo TENANT_PATH \"$tenant_path\"",
+    "hdfs dfs -ls \"$tenant_path\"",
+    "hdfs dfs -du -h \"$tenant_path\"",
+    "for f in operationsLog.csv s3MigrationCopyRecords.txt s3MigrationDagRunRecords.txt s3MigrationVerificationRecords.txt; do",
+    "  echo FILE \"$f\"",
+    "  hdfs dfs -test -e \"$tenant_path/$f\" && hdfs dfs -tail \"$tenant_path/$f\" || true",
+    "done"
+  ].join("\n");
+}
+
+function endpointScript(input) {
+  const endpoints = [...new Set([...(input.s3VpceEndpointUrls || []), ...(input.alternateS3VpceEndpointUrls || [])])];
+  if (!endpoints.length) return "";
+  return [
+    "set -eu",
+    ...endpoints.flatMap((endpoint) => {
+      const host = new URL(endpoint).hostname;
+      return [
+        `echo ENDPOINT ${shellQuote(endpoint)}`,
+        `getent hosts ${shellQuote(host)}`,
+        `getent hosts ${shellQuote(host)} | awk '{print $1}' | while read -r ip; do ip route get "$ip"; done`,
+        `curl -k -sS -o /dev/null --connect-timeout 10 --max-time 15 -w 'host=%{local_ip} remote=%{remote_ip} connect=%{time_connect} http=%{http_code} err=%{errormsg}\\n' ${shellQuote(endpoint)}`
+      ];
+    })
+  ].join("\n");
+}
+
+function jiraReadPath(jira) {
+  const key = String(jira || "").match(/[A-Z][A-Z0-9]+-\d+/u)?.[0] || "<main-jira-key>";
+  return `/rest/api/2/issue/${key}?fields=summary,status,issuelinks,subtasks,labels,components`;
+}
+
+function buildCommandPack(input = {}) {
+  const commands = [
+    {
+      id: "01-slack-event-facts",
+      purpose: "Extract the migration-service incident source of truth from the Slack thread.",
+      command: "Read the Slack thread and capture migrationEventId, source cluster, source/target environments, tenant, run type, snapshot id, dagRunId, failure timestamp, cutover window, main Jira, and follow-up Jira candidates.",
+      expectedEvidence: "Slack thread URL and concrete migration identifiers"
+    },
+    {
+      id: "02-main-jira-links",
+      purpose: "Read main Jira relationship fields before choosing the follow-up Jira.",
+      command: jiraReadPath(input.mainJira),
+      expectedEvidence: "summary, status, issuelinks, subtasks, labels, components; linked monitoring/product follow-up ticket when present"
+    },
+    {
+      id: "03-tenant-migration-records",
+      purpose: "Read tenant record files to establish migration state, copy history, dag run history, and verification counts.",
+      command: tenantRecordScript(input),
+      expectedEvidence: "last successful/failed copy records, dag run records, verification source/target file counts, cutover success, bucket sync, PRISM_READY, event COMPLETED"
+    },
+    {
+      id: "04-cutover-state-machine",
+      purpose: "Classify cutover-window retry behavior without mutating migration-service state.",
+      command: "Look for messages such as 'Only cutover run allowed ... Discarding message', CUTOVER_MIGRATION success, bucket sync completion, PRISM_READY, and event COMPLETED.",
+      expectedEvidence: "whether retry behavior matches migration-service state machine and whether recovery completed"
+    }
+  ];
+  const endpoint = endpointScript(input);
+  if (endpoint) {
+    commands.push({
+      id: "05-s3-vpce-readonly-comparison",
+      purpose: "Compare failing and alternate S3 VPCE endpoint paths from the same worker/source IP.",
+      command: endpoint,
+      expectedEvidence: "DNS answers, route gateway/device, source IP, remote IP, time_connect, http_code, errormsg"
+    });
+  }
+  return {
+    mode: "atomic-helper",
+    remoteWrite: "never",
+    summary: summaryLines(input),
+    workerHosts: input.workerHosts || [],
+    safetyRules: SAFETY_RULES,
+    commands
+  };
+}
+
+function renderMarkdown(result) {
+  return [
+    "# BDS Migration-Service Operation Read-Only Command Pack",
+    "",
+    "## Summary",
+    "",
+    ...(result.summary.length ? result.summary.map((line) => `- ${line}`) : ["- <fill from Slack thread>"]),
+    "",
+    "## Safety Boundary",
+    "",
+    ...result.safetyRules.map((rule) => `- ${rule}`),
+    "",
+    "## Read-Only Commands",
+    "",
+    ...result.commands.flatMap((command) => [
+      `### ${command.id}`,
+      `Purpose: ${command.purpose}`,
+      "",
+      "```bash",
+      command.command,
+      "```",
+      "",
+      `Evidence to capture: ${command.expectedEvidence}`,
+      ""
+    ]),
+    "Procedure and interpretation live in the `bds-airflow-job-status-investigation` skill runbook."
+  ].join("\n");
+}
+
+const inputSchema = {
+  slackThreadUrl: urlSchema,
+  migrationEventId: identifierSchema,
+  sourceCluster: identifierSchema,
+  sourceEnvironment: identifierSchema,
+  targetEnvironment: identifierSchema,
+  sourceTenant: tenantSchema,
+  targetTenant: tenantSchema,
+  migrationRunType: migrationRunTypeSchema,
+  snapshotId: identifierSchema,
+  fromSnapshotId: identifierSchema,
+  dagRunId: identifierSchema,
+  cutoverDateUtc: z.string().trim().datetime().optional(),
+  tenantHdfsPath: hdfsPathSchema,
+  mainJira: identifierSchema,
+  followUpJira: identifierSchema,
+  workerHosts: z.array(hostSchema).max(100).default([]),
+  s3VpceEndpointUrls: z.array(z.string().trim().url().regex(/^https:\/\/[^/]+\.s3\.[A-Za-z0-9-]+\.vpce\.amazonaws\.com\/?$/)).max(8).default([]),
+  alternateS3VpceEndpointUrls: z.array(z.string().trim().url().regex(/^https:\/\/[^/]+\.s3\.[A-Za-z0-9-]+\.vpce\.amazonaws\.com\/?$/)).max(8).default([]),
+  outputFormat: z.enum(["markdown", "json"]).default("markdown")
+};
+
+const schema = z.object(inputSchema);
+
+export function bdsMigrationServiceOperationPlan(rawInput = {}) {
+  const input = schema.parse(rawInput);
+  const result = buildCommandPack(input);
+  return input.outputFormat === "json" ? JSON.stringify(result, null, 2) : renderMarkdown(result);
+}
+
+export class BdsMigrationServiceOperationCommandPackService {
+  invoke(rawInput = {}) {
+    return bdsMigrationServiceOperationPlan(rawInput);
+  }
+}
+
+const defaultService = new BdsMigrationServiceOperationCommandPackService();
+
+export const __test = {
+  BdsMigrationServiceOperationCommandPackService,
+  bdsMigrationServiceOperationPlan,
+  endpointScript,
+  jiraReadPath,
+  tenantRecordScript
+};
+
+const sharedTool = defineReadOnlyTool({
+  name: "bds_migration_service_operation_command_pack",
+  description: "Generate a atomic-helper, read-only BDS migration-service command/API pack from Slack event facts, Jira links, HDFS tenant records, cutover state, and optional S3 VPCE probes; does not call Jira, SSH, or inspect HDFS.",
+  inputSchema,
+  async handler(input) {
+    try {
+      return ok(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
+};