@nuvlore/extension-bds 0.1.1

package/tools/bds_disk_io_alert_command_pack.mjs

@@ -0,0 +1,287 @@
+export const description = "Generate a atomic-helper, read-only BDS storage command pack for disk IO, HDFS DataNode failed volumes, kernel medium errors, PERC virtual disks, physical disk predictive failure, and concise RCA handoff; does not SSH, inspect hosts, or call Pharos.";
+
+import { z } from "zod";
+import { defineReadOnlyTool, fail, ok } from "@nuvlore/extension-read-only-toolkit/devops-diagnostics";
+
+const DEFAULT_ALERT_NAME = "bds_disk_kernel_daily_io_error_total";
+const SAFETY_RULES = [
+  "read-only only: lsblk, df, findmnt, iostat, journalctl reads, omreport reads, smartctl health reads",
+  "never unmount, format, repair, fsck, xfs_repair, hdparm write, dd, wipefs, or modify RAID state",
+  "never restart services, stop workloads, mark disks offline, clear logs, delete data, or write files",
+  "never print LDAP passwords, Keychain payloads, tokens, or sudo stdin",
+  "if sudo is required, use mcp__devops-tool__workday_private_cloud_sudo_readonly_command; do not read Keychain directly"
+];
+
+const hostSchema = z
+  .string()
+  .min(1)
+  .max(255)
+  .regex(/^(?!-)[a-zA-Z0-9._:@%-]+$/);
+
+const identifierSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_.:/@%-]+$/)
+  .optional();
+
+const mountSchema = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^\/[A-Za-z0-9._/-]+$/)
+  .optional();
+
+const timestampSchema = z
+  .string()
+  .min(1)
+  .max(64)
+  .regex(/^[0-9TZ:+ ._-]+$/)
+  .optional();
+
+class ReadOnlyCommand {
+  constructor({ id, purpose, command, expectedEvidence }) {
+    this.id = id;
+    this.purpose = purpose;
+    this.command = command;
+    this.expectedEvidence = expectedEvidence;
+  }
+
+  toMarkdown() {
+    return [
+      `### ${this.id}`,
+      `Purpose: ${this.purpose}`,
+      "",
+      "```bash",
+      this.command,
+      "```",
+      "",
+      `Evidence to capture: ${this.expectedEvidence}`
+    ].join("\n");
+  }
+
+  toJson() {
+    return {
+      id: this.id,
+      purpose: this.purpose,
+      command: this.command,
+      expectedEvidence: this.expectedEvidence
+    };
+  }
+}
+
+class CredentialHandlingGuide {
+  constructor({ sourceHost }) {
+    this.sourceHost = sourceHost;
+  }
+
+  toMarkdown() {
+    return [
+      "## Credential Handling",
+      "",
+      "- Prefer read-only commands that do not need sudo, such as `lsblk`, `df`, `findmnt`, `iostat`, and many `omreport` reads.",
+      "- If sudo is needed for kernel journal or hardware health reads, use `workday_private_cloud_sudo_readonly_command`.",
+      "- Do not call Keychain directly from this command pack or from an agent.",
+      "",
+      "```json",
+      JSON.stringify({
+        tool: "mcp__devops-tool__workday_private_cloud_sudo_readonly_command",
+        input: {
+          action: "run",
+          host: this.sourceHost,
+          command: "journalctl -k --since '24 hours ago' | head -80",
+          humanApprovedSudoRead: true
+        }
+      }, null, 2),
+      "```"
+    ].join("\n");
+  }
+}
+
+class BdsDiskIoAlertCommandPack {
+  constructor(input) {
+    this.alertName = input.alertName ?? DEFAULT_ALERT_NAME;
+    this.cluster = input.cluster;
+    this.sourceHost = input.sourceHost;
+    this.device = input.device;
+    this.mountPoint = input.mountPoint;
+    this.physicalDisk = input.physicalDisk;
+    this.virtualDisk = input.virtualDisk;
+    this.sinceUtc = input.sinceUtc;
+    this.untilUtc = input.untilUtc;
+  }
+
+  ssh(command) {
+    return `ssh -o BatchMode=yes -o ConnectTimeout=10 -- ${this.sourceHost} ${JSON.stringify(command)}`;
+  }
+
+  journalWindowArgs() {
+    const args = [];
+    if (this.sinceUtc) args.push(`--since=${JSON.stringify(this.sinceUtc)}`);
+    if (this.untilUtc) args.push(`--until=${JSON.stringify(this.untilUtc)}`);
+    if (args.length === 0) args.push("--since='24 hours ago'");
+    return args.join(" ");
+  }
+
+  deviceFilter() {
+    return this.device ? this.device.replace(/^\/dev\//, "") : "sd[a-z]|nvme";
+  }
+
+  commands() {
+    const deviceName = this.deviceFilter();
+    const physicalDisk = this.physicalDisk ?? "0:1:8";
+    const virtualDisk = this.virtualDisk ?? "9";
+    const mountPoint = this.mountPoint ?? "/hadoop/disk9";
+    return [
+      new ReadOnlyCommand({
+        id: "01-host-identity",
+        purpose: "Confirm host identity, UTC clock, boot time, kernel, and whether sudo currently has a cached timestamp.",
+        command: this.ssh("hostname -f; date -u; uptime -s; uname -a; sudo -n true >/dev/null 2>&1; echo SUDO_N_STATUS_$?"),
+        expectedEvidence: "host, UTC time anchor, boot time, kernel version, sudo timestamp availability"
+      }),
+      new ReadOnlyCommand({
+        id: "02-disk-topology",
+        purpose: "Map OS block devices to model, serial, filesystem, and mount point.",
+        command: this.ssh("lsblk -d -o NAME,MAJ:MIN,MODEL,SERIAL,SIZE,ROTA,STATE,TRAN,HCTL; lsblk -o NAME,KNAME,SIZE,TYPE,FSTYPE,MOUNTPOINT,UUID,MODEL,SERIAL"),
+        expectedEvidence: "device to mount mapping, especially impacted data disk and backing controller logical disk"
+      }),
+      new ReadOnlyCommand({
+        id: "03-filesystem-state",
+        purpose: "Confirm whether the impacted filesystem is mounted, capacity, and current usage.",
+        command: this.ssh(`df -hT; findmnt -D | egrep '${mountPoint}|SOURCE|TARGET'`),
+        expectedEvidence: "mount state, filesystem type, capacity, used/free percentage"
+      }),
+      new ReadOnlyCommand({
+        id: "04-realtime-io",
+        purpose: "Check whether the alert is accompanied by current high iowait, queue depth, latency, or device utilization.",
+        command: this.ssh("iostat -xz 1 3"),
+        expectedEvidence: "current await, aqu-sz, util, iowait, and whether the issue is active under current workload"
+      }),
+      new ReadOnlyCommand({
+        id: "05-kernel-io-errors",
+        purpose: "Read bounded kernel evidence for disk medium errors, timeouts, resets, and unrecovered reads.",
+        command: this.ssh(`sudo -n journalctl -k ${this.journalWindowArgs()} --no-pager | egrep -i 'I/O error|blk_update_request|critical medium|medium error|uncorrect|failed command|reset|timeout|sense key|Buffer I/O|end_request|megaraid|${deviceName}' | tail -300`),
+        expectedEvidence: "kernel timestamps, OS device, sector/LBA, SCSI sense key, PERC physical disk and virtual disk references"
+      }),
+      new ReadOnlyCommand({
+        id: "06-dell-controller",
+        purpose: "Read Dell controller state without changing RAID configuration.",
+        command: this.ssh("/opt/dell/srvadmin/bin/omreport storage controller"),
+        expectedEvidence: "controller status, firmware, driver, patrol read state, cache and policy details"
+      }),
+      new ReadOnlyCommand({
+        id: "07-dell-virtual-disk",
+        purpose: "Confirm impacted virtual disk status, layout, bad block state, OS device, and redundancy level.",
+        command: this.ssh(`/opt/dell/srvadmin/bin/omreport storage vdisk controller=0 vdisk=${virtualDisk}`),
+        expectedEvidence: "virtual disk status, RAID layout, bad block flag, device name"
+      }),
+      new ReadOnlyCommand({
+        id: "08-dell-physical-disk",
+        purpose: "Confirm physical disk predictive failure and hardware identity for replacement.",
+        command: this.ssh(`/opt/dell/srvadmin/bin/omreport storage pdisk controller=0 pdisk=${physicalDisk}`),
+        expectedEvidence: "physical disk status, `Failure Predicted`, serial, part number, SAS address, capacity"
+      }),
+      new ReadOnlyCommand({
+        id: "09-dell-alert-log",
+        purpose: "Correlate Dell storage alert log with kernel errors and alert firing time.",
+        command: this.ssh(`/opt/dell/srvadmin/bin/omreport system alertlog | egrep -A4 -B1 'PDR64|VDR58|${physicalDisk}|Virtual Disk ${virtualDisk}' | head -260`),
+        expectedEvidence: "PDR64, VDR58, STOR0210, timestamps, and repeated error cadence"
+      }),
+      new ReadOnlyCommand({
+        id: "10-health-summary",
+        purpose: "Summarize risk without performing remediation.",
+        command: this.ssh(`printf 'device=${this.device ?? "unknown"}\\nmount=${mountPoint}\\nphysicalDisk=${physicalDisk}\\nvirtualDisk=${virtualDisk}\\n'`),
+        expectedEvidence: "stable identifiers to include in RCA and handoff"
+      })
+    ];
+  }
+
+  toMarkdown() {
+    return [
+      "# BDS Disk IO Alert Read-Only Command Pack",
+      "",
+      `Alert: ${this.alertName}`,
+      this.cluster ? `Cluster: ${this.cluster}` : "",
+      `Source host: ${this.sourceHost}`,
+      this.device ? `Device: ${this.device}` : "",
+      this.mountPoint ? `Mount point: ${this.mountPoint}` : "",
+      this.physicalDisk ? `Physical disk: ${this.physicalDisk}` : "",
+      this.virtualDisk ? `Virtual disk: ${this.virtualDisk}` : "",
+      "",
+      "## Safety Boundary",
+      "",
+      ...SAFETY_RULES.map((rule) => `- ${rule}`),
+      "",
+      new CredentialHandlingGuide({
+        sourceHost: this.sourceHost
+      }).toMarkdown(),
+      "",
+      "## Read-Only Commands",
+      "",
+      ...this.commands().map((command) => command.toMarkdown()),
+      "",
+      "Procedure, interpretation, and RCA shape live in the `bds-disk-io-alert-investigation` skill."
+    ].filter(Boolean).join("\n");
+  }
+
+  toJson() {
+    return {
+      alertName: this.alertName,
+      cluster: this.cluster,
+      sourceHost: this.sourceHost,
+      device: this.device,
+      mountPoint: this.mountPoint,
+      physicalDisk: this.physicalDisk,
+      virtualDisk: this.virtualDisk,
+      safetyBoundary: SAFETY_RULES,
+      commands: this.commands().map((command) => command.toJson())
+    };
+  }
+}
+
+function buildResponse(input) {
+  const commandPack = new BdsDiskIoAlertCommandPack(input);
+  if (input.format === "json") {
+    return JSON.stringify(commandPack.toJson(), null, 2);
+  }
+  return commandPack.toMarkdown();
+}
+
+const sharedTool = defineReadOnlyTool({
+  name: "bds_disk_io_alert_command_pack",
+  description: "Generate a atomic-helper, read-only BDS storage command pack for disk IO, HDFS DataNode failed volumes, kernel medium errors, PERC virtual disks, physical disk predictive failure, and concise RCA handoff; does not SSH, inspect hosts, or call Pharos.",
+  meta: {
+    permissions: { rule: "ask" },
+    secret_provider: "keychain"
+  },
+  inputSchema: {
+    alertName: z.string().min(1).max(128).default(DEFAULT_ALERT_NAME),
+    cluster: z.string().min(1).max(128).regex(/^[A-Za-z0-9_.:-]+$/).optional(),
+    sourceHost: hostSchema.describe("Alert source host to inspect with read-only SSH commands."),
+    device: identifierSchema.describe("Optional impacted OS device, for example /dev/sdk or sdk."),
+    mountPoint: mountSchema.describe("Optional impacted mount point, for example /hadoop/disk9."),
+    physicalDisk: identifierSchema.describe("Optional Dell physical disk ID, for example 0:1:8."),
+    virtualDisk: identifierSchema.describe("Optional Dell virtual disk ID, for example 9."),
+    sinceUtc: timestampSchema.describe("Optional UTC lower bound for journal reads."),
+    untilUtc: timestampSchema.describe("Optional UTC upper bound for journal reads."),
+    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
+};