@nuvlore/extension-bds 0.1.1

package/tools/bds_tenant_data_operation_log_command_pack.mjs

@@ -0,0 +1,321 @@
+export const description = "Generate a atomic-helper, read-only BDS tenant data operation-log HDFS/source command pack that separates TSS tenant state from PRISM/BDS data evidence; does not SSH or inspect HDFS.";
+
+import { z } from "zod";
+import { defineReadOnlyTool, fail, ok } from "@nuvlore/extension-read-only-toolkit/devops-diagnostics";
+import { ReadOnlyStep, remoteCommandInput, shellQuote } from "@nuvlore/extension-read-only-toolkit/read-only-command-pack";
+
+const DEFAULT_CLUSTER = "BDS_DUB_NPRD1_AZ1";
+const DEFAULT_DATANODE_HOST = "s-cz22240ms4.sys.az1.cust.dub.wd";
+const DEFAULT_HDFS_AUTHORITY = "bdsdubnprd1az1";
+const DEFAULT_TSS_BASE_URL = "http://balance-impl.env.az1.cust.dub.wd:17020";
+const DEFAULT_SIRIUS_REPO_URL = "https://bitbucket.workday.com/projects/BDS/repos/sirius/browse";
+
+const SAFETY_RULES = [
+  "read-only only: tenant status GET, hdfs crypto -listZones, and hdfs dfs list/read/test/du operations",
+  "do not equate TSS state RELEASED/OK with BDS or PRISM data readiness; verify the tenant data path directly",
+  "operation log path is data/tenants/<ENV_NAME>.<tenantName>/operationsLog.csv",
+  "expected BDS tenant data shape is operationsLog.csv, ted, and tmp; missing operationsLog.csv or tmp is strong evidence that PRISM/BDS data was not enable/clone-created",
+  "compare against related tenants such as preview, gold, or numbered tenants only as evidence, not as an automatic remediation",
+  "never print LDAP passwords, Keychain JSON, tokens, or sudo stdin",
+  "Keychain item may be JSON; extract only the top-level token field locally and pass it through stdin",
+  "never run hdfs dfs -rm, -put, -get, -cp, -mv, -mkdir, -touchz, -chmod, -chown, or any tenant state mutation"
+];
+
+const BDS_OPERATION_LOG_SOURCE_NOTES = [
+  "Sirius BDM exposes operationLog routes such as /v2/bds/log/:envTenant and /api/v3/bds/log/:envTenant.",
+  "TenantDataManager builds the operation log path from the tenant base path plus operationsLog.csv.",
+  "If BDM HTTP routes return 403 from a jump host, inspect the same HDFS path from an authorized datanode or BDM pod."
+];
+
+const clusterSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_.:-]+$/);
+
+const hostSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^(?!-)[a-zA-Z0-9._:@%-]+$/);
+
+const pathNameSchema = z
+  .string()
+  .min(1)
+  .max(160)
+  .regex(/^[A-Za-z0-9_.-]+$/);
+
+const hdfsAuthoritySchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_.-]+$/);
+
+const urlSchema = z
+  .string()
+  .trim()
+  .url()
+  .max(2048);
+
+const relatedTenantSchema = z.array(pathNameSchema).max(12).default([]);
+
+class BdsTenantDataOperationLogCommandPack {
+  constructor(input) {
+    this.cluster = input.cluster ?? DEFAULT_CLUSTER;
+    this.datanodeHost = input.datanodeHost ?? DEFAULT_DATANODE_HOST;
+    this.hdfsAuthority = input.hdfsAuthority ?? DEFAULT_HDFS_AUTHORITY;
+    this.environmentName = input.environmentName;
+    this.tenantName = input.tenantName;
+    this.relatedTenants = input.relatedTenants ?? [];
+    this.tssBaseUrl = input.tssBaseUrl ?? DEFAULT_TSS_BASE_URL;
+    this.siriusRepoUrl = input.siriusRepoUrl ?? DEFAULT_SIRIUS_REPO_URL;
+  }
+
+  envTenant() {
+    return `${this.environmentName}.${this.tenantName}`;
+  }
+
+  tenantHdfsPath(envTenant = this.envTenant()) {
+    return `hdfs://${this.hdfsAuthority}/data/tenants/${envTenant}`;
+  }
+
+  operationLogPath(envTenant = this.envTenant()) {
+    return `${this.tenantHdfsPath(envTenant)}/operationsLog.csv`;
+  }
+
+  allEnvTenants() {
+    return Array.from(new Set([this.envTenant(), ...this.relatedTenants]));
+  }
+
+  keychainSudoSnippet(command) {
+    return `mcp__devops-tool__workday_private_cloud_sudo_readonly_command ${JSON.stringify({
+      action: "run",
+      host: this.datanodeHost,
+      command,
+      humanApprovedSudoRead: true
+    })}`;
+  }
+
+  statusUrl() {
+    return `${this.tssBaseUrl}/tenant/${this.tenantName}?detail=true`;
+  }
+
+  sourceSearchCommand() {
+    return [
+      "Use bitbucket_api_read on /rest/api/latest/projects/BDS/repos/sirius, or perform an optional HITL local cache clone:",
+      "git clone --filter=blob:none https://bitbucket.workday.com/scm/BDS/sirius.git <local-cache>/bds-sirius",
+      "Then search read-only for: operationLog, operationLogPath, getOperationLogRaw, /api/v3/bds/log, /v2/bds/log, TenantDataManager"
+    ].join("\n");
+  }
+
+  operationLogCheckScript() {
+    const body = [
+      "set +e",
+      "echo HDFS_AUTHORITY " + shellQuote(this.hdfsAuthority),
+      "echo TARGET " + shellQuote(this.envTenant()),
+      "echo KLIST",
+      "klist 2>/dev/null | sed -n '1,3p'",
+      "echo CRYPTO_ZONES_MATCHING_TENANT",
+      `hdfs crypto -listZones 2>&1 | grep -E ${shellQuote(`/data/tenants/${this.environmentName}\\.${this.tenantName}($|/|[0-9]|_|-)`)} || true`,
+      "echo TENANT_PATH_SHAPE",
+      `hdfs dfs -ls ${shellQuote(this.tenantHdfsPath())} 2>&1 | sed -n '1,40p'`,
+      "echo TENANT_DU",
+      `hdfs dfs -du -h ${shellQuote(this.tenantHdfsPath())} 2>&1 | sed -n '1,40p'`,
+      "echo OPERATION_LOG",
+      `if hdfs dfs -test -e ${shellQuote(this.operationLogPath())}; then`,
+      `  hdfs dfs -du -h ${shellQuote(this.operationLogPath())};`,
+      `  hdfs dfs -tail ${shellQuote(this.operationLogPath())} | tail -80;`,
+      "else",
+      "  echo operationsLog.csv MISSING;",
+      "fi"
+    ];
+    return body.join("\n");
+  }
+
+  comparisonCommands() {
+    return this.allEnvTenants().map((envTenant) => [
+      `echo ### ${envTenant}`,
+      `hdfs dfs -ls ${shellQuote(this.tenantHdfsPath(envTenant))} 2>&1 | sed -n '1,30p'`,
+      `if hdfs dfs -test -e ${shellQuote(this.operationLogPath(envTenant))}; then hdfs dfs -tail ${shellQuote(this.operationLogPath(envTenant))} | tail -20; else echo operationsLog.csv MISSING; fi`
+    ].join("\n")).join("\n\n");
+  }
+
+  mcpSafeRemoteCommands() {
+    return [
+      { label: "datanode-hostname", input: remoteCommandInput({ host: this.datanodeHost, command: "hostname -f" }) },
+      { label: "datanode-user", input: remoteCommandInput({ host: this.datanodeHost, command: "id" }) },
+      { label: "check-hdfs", input: remoteCommandInput({ host: this.datanodeHost, command: "command -v hdfs" }) },
+      { label: "kerberos-cache", input: remoteCommandInput({ host: this.datanodeHost, command: "klist" }) },
+      { label: "crypto-zones", input: remoteCommandInput({ host: this.datanodeHost, command: "hdfs crypto -listZones", timeoutMs: 120_000 }) },
+      { label: "tenant-list", input: remoteCommandInput({ host: this.datanodeHost, command: `hdfs dfs -ls ${shellQuote(this.tenantHdfsPath())}` }) },
+      { label: "tenant-du", input: remoteCommandInput({ host: this.datanodeHost, command: `hdfs dfs -du -h ${shellQuote(this.tenantHdfsPath())}` }) },
+      { label: "operation-log-exists", input: remoteCommandInput({ host: this.datanodeHost, command: `hdfs dfs -test -e ${shellQuote(this.operationLogPath())}` }) },
+      { label: "operation-log-tail", input: remoteCommandInput({ host: this.datanodeHost, command: `hdfs dfs -tail ${shellQuote(this.operationLogPath())}` }) }
+    ];
+  }
+
+  commands() {
+    return [
+      new ReadOnlyStep({
+        id: "00-source-route-map",
+        purpose: "Confirm where BDM expects tenant operation logs before interpreting HDFS path shape.",
+        command: this.sourceSearchCommand(),
+        expectedEvidence: "Sirius route and TenantDataManager code proving operationsLog.csv is under data/tenants/<ENV>.<tenant>/"
+      }),
+      new ReadOnlyStep({
+        id: "01-tss-status-is-not-bds-proof",
+        purpose: "Read tenant state from TSS/OMS while explicitly separating it from BDS/PRISM data readiness.",
+        command: `curl -s ${shellQuote(this.statusUrl())} | python3 -m json.tool`,
+        expectedEvidence: "state, health, releaseTime, and message; use only as TSS evidence, not BDS data evidence"
+      }),
+      new ReadOnlyStep({
+        id: "02-credential-handling",
+        purpose: "Use the approved Keychain LDAP item without printing secrets when sudo/root HDFS access is needed.",
+        command: this.keychainSudoSnippet("klist 2>/dev/null | sed -n '1,3p'"),
+        expectedEvidence: "root Kerberos principal only; no password, token, raw JSON, or sudo stdin"
+      }),
+      new ReadOnlyStep({
+        id: "03-target-operation-log",
+        purpose: "Check the exact target tenant data path, crypto zones, and operation log from a datanode.",
+        command: this.keychainSudoSnippet(this.operationLogCheckScript()),
+        expectedEvidence: "crypto-zone presence or absence, children under tenant path, du output, and operationsLog.csv tail or missing marker"
+      }),
+      new ReadOnlyStep({
+        id: "04-related-tenant-comparison",
+        purpose: "Compare the target path shape with preview/gold/numbered tenants to distinguish missing data creation from a general HDFS read issue.",
+        command: this.keychainSudoSnippet(this.comparisonCommands()),
+        expectedEvidence: "related tenant path shape and operation log entries such as prism Enable or Clone"
+      })
+    ];
+  }
+
+  antiPatterns() {
+    return [
+      {
+        command: "Assume RELEASED/OK means PRISM/BDS data is present.",
+        reason: "TSS/OMS release state and BDS HDFS tenant data are separate evidence domains."
+      },
+      {
+        command: `hdfs dfs -get ${this.tenantHdfsPath()}`,
+        reason: "Downloads tenant data to local disk; not needed for operation log inspection."
+      },
+      {
+        command: `hdfs dfs -rm ${this.tenantHdfsPath()}`,
+        reason: "Mutates tenant data and is outside read-only investigation scope."
+      },
+      {
+        command: "direct Keychain LDAP PROD password read",
+        reason: "Only the dedicated Workday login/sudo tools may read PROD password; do not call Keychain from command packs or agents."
+      }
+    ];
+  }
+
+  toMarkdown() {
+    return [
+      "# BDS Tenant Data Operation Log Read-Only Command Pack",
+      "",
+      `Cluster: ${this.cluster}`,
+      `Datanode host: ${this.datanodeHost}`,
+      `HDFS authority: ${this.hdfsAuthority}`,
+      `Environment: ${this.environmentName}`,
+      `Tenant: ${this.tenantName}`,
+      `Env tenant: ${this.envTenant()}`,
+      `Tenant data path: \`${this.tenantHdfsPath()}\``,
+      `Operation log: \`${this.operationLogPath()}\``,
+      `TSS URL: ${this.statusUrl()}`,
+      `Sirius repo: ${this.siriusRepoUrl}`,
+      "",
+      "## Source Notes",
+      "",
+      ...BDS_OPERATION_LOG_SOURCE_NOTES.map((note) => `- ${note}`),
+      "",
+      "## Safety Boundary",
+      "",
+      ...SAFETY_RULES.map((rule) => `- ${rule}`),
+      "",
+      "## Read-Only Commands",
+      "",
+      ...this.commands().map((command) => command.toMarkdown()),
+      "",
+      "## MCP-Safe Remote Reads",
+      "",
+      "These are single-command read-only probes for `remote_readonly_command`. Run credential setup separately when needed.",
+      "",
+      ...this.mcpSafeRemoteCommands().map((item) => `- ${item.label}: \`${item.input.command}\``),
+      "",
+      "## Do Not Use",
+      "",
+      ...this.antiPatterns().map((entry) => `- \`${entry.command}\`: ${entry.reason}`),
+      "",
+      "Procedure, interpretation, and output shape live in the `bds-tenant-data-operation-log-investigation` skill."
+    ].join("\n");
+  }
+
+  toJson() {
+    return {
+      cluster: this.cluster,
+      datanodeHost: this.datanodeHost,
+      hdfsAuthority: this.hdfsAuthority,
+      environmentName: this.environmentName,
+      tenantName: this.tenantName,
+      envTenant: this.envTenant(),
+      tenantDataPath: this.tenantHdfsPath(),
+      operationLogPath: this.operationLogPath(),
+      relatedTenants: this.relatedTenants,
+      tssUrl: this.statusUrl(),
+      siriusRepoUrl: this.siriusRepoUrl,
+      expectedTenantChildren: ["operationsLog.csv", "ted", "tmp"],
+      sourceNotes: BDS_OPERATION_LOG_SOURCE_NOTES,
+      safetyBoundary: SAFETY_RULES,
+      commands: this.commands().map((command) => command.toJson()),
+      mcpSafeRemoteCommands: this.mcpSafeRemoteCommands(),
+      antiPatterns: this.antiPatterns()
+    };
+  }
+}
+
+function buildResponse(input) {
+  const commandPack = new BdsTenantDataOperationLogCommandPack(input);
+  if (input.format === "json") {
+    return JSON.stringify(commandPack.toJson(), null, 2);
+  }
+  return commandPack.toMarkdown();
+}
+
+const sharedTool = defineReadOnlyTool({
+  name: "bds_tenant_data_operation_log_command_pack",
+  description: "Generate a atomic-helper, read-only BDS tenant data operation-log HDFS/source command pack that separates TSS tenant state from PRISM/BDS data evidence; does not SSH or inspect HDFS.",
+  meta: {
+    permissions: { rule: "ask" },
+    secret_provider: "keychain"
+  },
+  inputSchema: {
+    cluster: clusterSchema.default(DEFAULT_CLUSTER),
+    datanodeHost: hostSchema.default(DEFAULT_DATANODE_HOST),
+    hdfsAuthority: hdfsAuthoritySchema.default(DEFAULT_HDFS_AUTHORITY),
+    environmentName: pathNameSchema.describe("Tenant environment name, for example WD3-IMPL."),
+    tenantName: pathNameSchema.describe("Tenant name without environment prefix, for example chloe."),
+    relatedTenants: relatedTenantSchema.describe("Optional envTenant names for comparison, for example WD3-IMPL.chloe_preview."),
+    tssBaseUrl: urlSchema.default(DEFAULT_TSS_BASE_URL),
+    siriusRepoUrl: urlSchema.default(DEFAULT_SIRIUS_REPO_URL),
+    format: z.enum(["markdown", "json"]).default("markdown")
+  },
+  annotations: { openWorldHint: true },
+  async handler(input) {
+    try {
+      return ok(buildResponse(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
+};