@nuvlore/extension-bds 0.1.1

package/tools/bds_hdfs_datanode_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read HDFS DataNode logs from a private-cloud DataNode host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_hdfs_datanode_log_read",
+  description: "Read HDFS DataNode logs from a private-cloud DataNode host through the approved Boundary sudo read tool.",
+  glob: "/var/log/hadoop-hdfs/hadoop-hdfs-datanode-*.log"
+});
+
+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_hdfs_journalnode_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read HDFS JournalNode logs from a private-cloud JournalNode host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_hdfs_journalnode_log_read",
+  description: "Read HDFS JournalNode logs from a private-cloud JournalNode host through the approved Boundary sudo read tool.",
+  glob: "/var/log/hadoop-hdfs/hadoop-hdfs-journalnode-*.log /var/log/hadoop-hdfs/hadoop-hdfs-journalnode-*.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_hdfs_namenode_log_read.mjs

@@ -0,0 +1,23 @@
+export const description = "Read HDFS NameNode logs from a private-cloud NameNode host through the approved Boundary sudo read tool.";
+
+import { createPrivateCloudLogReadTool, globPrivateLogSpec } from "../src/bds-atomic-log-tools.mjs";
+
+const spec = globPrivateLogSpec({
+  toolName: "bds_hdfs_namenode_log_read",
+  description: "Read HDFS NameNode logs from a private-cloud NameNode host through the approved Boundary sudo read tool.",
+  glob: "/var/log/hadoop-hdfs/hadoop-hdfs-namenode-*.log"
+});
+
+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_hdfs_path_knowledge.mjs

@@ -0,0 +1,324 @@
+export const description = "Return BDS HDFS and S3A path templates plus rendered read-only path candidates for tenant data, operations logs, YARN app logs, Spark event logs, snapshots, encryption zones, and audit evidence.";
+
+import { z } from "zod";
+import { defineReadOnlyTool, fail, ok } from "@nuvlore/extension-read-only-toolkit/devops-diagnostics";
+
+export const BDS_HDFS_PATH_CATEGORIES = {
+  tenant_data: {
+    purpose: "Primary BDS tenant data root in a private-cloud HDFS namespace.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>",
+      "/data/tenants/<ENV_NAME>.<tenantName>"
+    ],
+    expectedChildren: ["operationsLog.csv", "ted", "tmp"],
+    readOnlyChecks: [
+      "hdfs dfs -ls <tenantDataPath>",
+      "hdfs dfs -du -h <tenantDataPath>",
+      "hdfs dfs -count <tenantDataPath>",
+      "hdfs dfs -stat <tenantDataPath>"
+    ]
+  },
+  tenant_operation_log: {
+    purpose: "BDS tenant operations log stored under the tenant data path.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>/operationsLog.csv",
+      "/data/tenants/<ENV_NAME>.<tenantName>/operationsLog.csv"
+    ],
+    readOnlyChecks: [
+      "hdfs dfs -test -e <operationLogPath>",
+      "hdfs dfs -tail <operationLogPath>",
+      "hdfs dfs -cat <operationLogPath>"
+    ]
+  },
+  tenant_ted: {
+    purpose: "Tenant encrypted data subtree used by BDS/PRISM data checks.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>/ted",
+      "/data/tenants/<ENV_NAME>.<tenantName>/ted"
+    ],
+    readOnlyChecks: ["hdfs dfs -ls <tenantTedPath>", "hdfs dfs -du -h <tenantTedPath>"]
+  },
+  tenant_tmp: {
+    purpose: "Tenant temporary subtree; missing tmp can be useful readiness evidence for some BDS/PRISM investigations.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>/tmp",
+      "/data/tenants/<ENV_NAME>.<tenantName>/tmp"
+    ],
+    readOnlyChecks: ["hdfs dfs -ls <tenantTmpPath>", "hdfs dfs -du -h <tenantTmpPath>"]
+  },
+  scylla_tenant_bucket: {
+    purpose: "Public-cloud/Scylla BDS tenant bucket path; inspect from BDM pod with hadoop fs, not hdfs.",
+    templates: [
+      "s3a://<bucketName>/data/tenants/<ENV_NAME>.<tenantName>/",
+      "s3a://<bucketName>/data/tenants/<ENV_NAME>.<tenantName>/operationsLog.csv",
+      "s3a://<bucketName>/data/tenants/<ENV_NAME>.<tenantName>/ted",
+      "s3a://<bucketName>/data/tenants/<ENV_NAME>.<tenantName>/tmp"
+    ],
+    expectedChildren: ["operationsLog.csv", "ted", "tmp"],
+    readOnlyChecks: [
+      "hadoop fs -ls <s3aTenantPath>",
+      "hadoop fs -du -h <s3aTenantPath>",
+      "hadoop fs -cat <s3aOperationLogPath>"
+    ]
+  },
+  yarn_app_logs: {
+    purpose: "Aggregated YARN application logs in HDFS; owner and bucket suffix may vary by cluster/log aggregation format.",
+    templates: [
+      "hdfs://<hdfsAuthority>/var/log/hadoop-yarn/apps/<owner>/logs/<applicationId>",
+      "hdfs://<hdfsAuthority>/var/log/hadoop-yarn/apps/<owner>/logs-tfile/<applicationId>",
+      "hdfs://<hdfsAuthority>/var/log/hadoop-yarn/apps/<owner>/bucket-logs-tfile/<last4>/<applicationId>",
+      "/app-logs/<owner>/logs/<applicationId>",
+      "/app-logs/<owner>/logs-tfile/<applicationId>",
+      "/app-logs/<owner>/bucket-logs-tfile/<last4>/<applicationId>"
+    ],
+    readOnlyChecks: [
+      "hdfs dfs -find <yarnLogRoot> -name '*<applicationId>*'",
+      "hdfs dfs -ls <yarnAppLogPath>",
+      "hdfs dfs -du -h <yarnAppLogPath>"
+    ]
+  },
+  spark_event_logs: {
+    purpose: "Spark History Server event logs in HDFS, including BDS SHS compacted eventlog_v2 paths.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/applications/spark/hs_1/eventlog_v2_<applicationId>_1",
+      "hdfs://<hdfsAuthority>/data/applications/spark/hs_1/<applicationId>*",
+      "hdfs://<hdfsAuthority>/spark-history/<applicationId>*",
+      "hdfs://<hdfsAuthority>/user/spark/applicationHistory/<applicationId>*"
+    ],
+    readOnlyChecks: [
+      "hdfs dfs -ls <sparkEventLogDir>",
+      "hdfs dfs -du -h <sparkEventLogDir>",
+      "hdfs dfs -find <sparkRoot> -name '*<applicationId>*'"
+    ]
+  },
+  mapreduce_history: {
+    purpose: "MapReduce JobHistory files in HDFS; usually use JobHistoryServer first, then HDFS path checks when needed.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/mapred/staging/history/done_intermediate/<owner>/<jobId>*",
+      "hdfs://<hdfsAuthority>/data/mapred/staging/history/done/<yyyy>/<MM>/<dd>/<jobId>*",
+      "/data/mapred/staging/history/done_intermediate/<owner>/<jobId>*",
+      "/data/mapred/staging/history/done/<yyyy>/<MM>/<dd>/<jobId>*"
+    ],
+    readOnlyChecks: [
+      "hdfs dfs -ls <mapreduceHistoryPath>",
+      "hdfs dfs -find /data/mapred/staging/history -name '*<jobId>*'"
+    ]
+  },
+  snapshots: {
+    purpose: "HDFS snapshot paths used by tenant clone, DR, migration copy, and cleanup investigations.",
+    templates: [
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>/.snapshot/<snapshotId>",
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>/.snapshot/<snapshotId>/ted",
+      "/data/tenants/<ENV_NAME>.<tenantName>/.snapshot/<snapshotId>"
+    ],
+    readOnlyChecks: [
+      "hdfs dfs -ls <snapshotPath>",
+      "hdfs dfs -du -h <snapshotPath>",
+      "hdfs dfs -count <snapshotPath>"
+    ]
+  },
+  encryption_zones: {
+    purpose: "HDFS encryption-zone evidence for BDS tenant paths.",
+    templates: [
+      "/data/tenants/<ENV_NAME>.<tenantName>",
+      "hdfs://<hdfsAuthority>/data/tenants/<ENV_NAME>.<tenantName>"
+    ],
+    readOnlyChecks: [
+      "hdfs crypto -listZones",
+      "hdfs crypto -listZones | grep '<ENV_NAME>.<tenantName>'"
+    ]
+  },
+  hdfs_audit_paths: {
+    purpose: "NameNode audit log path patterns on the host; useful for correlating HDFS path operations with timestamps.",
+    templates: [
+      "/var/log/hadoop-hdfs/hdfs-audit.log",
+      "/var/log/hadoop-hdfs/hdfs-audit.log.<yyyy-mm-dd>-<hour>.*.gz"
+    ],
+    readOnlyChecks: [
+      "zgrep -n '<tenantName>\\|<applicationId>\\|<snapshotId>' <auditShard>",
+      "grep -n '<tenantName>\\|<applicationId>\\|<snapshotId>' /var/log/hadoop-hdfs/hdfs-audit.log"
+    ]
+  }
+};
+
+export const BDS_HDFS_PATH_ALIASES = {
+  tenant: "tenant_data",
+  tenant_path: "tenant_data",
+  tenant_data_path: "tenant_data",
+  operations_log: "tenant_operation_log",
+  operation_log: "tenant_operation_log",
+  operationslog: "tenant_operation_log",
+  ted: "tenant_ted",
+  tmp: "tenant_tmp",
+  bucket: "scylla_tenant_bucket",
+  s3a: "scylla_tenant_bucket",
+  yarn: "yarn_app_logs",
+  yarn_logs: "yarn_app_logs",
+  app_logs: "yarn_app_logs",
+  application_logs: "yarn_app_logs",
+  spark: "spark_event_logs",
+  spark_history: "spark_event_logs",
+  spark_eventlog: "spark_event_logs",
+  mr_history: "mapreduce_history",
+  mapred_history: "mapreduce_history",
+  job_history: "mapreduce_history",
+  snapshot: "snapshots",
+  snapshot_path: "snapshots",
+  ez: "encryption_zones",
+  encryption: "encryption_zones",
+  encryption_zone: "encryption_zones",
+  audit: "hdfs_audit_paths",
+  audit_log: "hdfs_audit_paths",
+  hdfs_audit: "hdfs_audit_paths"
+};
+
+function normalizeText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function normalizeType(value) {
+  return normalizeText(value).toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+
+function envTenant(input) {
+  const env = normalizeText(input.environmentName) || "<ENV_NAME>";
+  const tenant = normalizeText(input.tenantName) || "<tenantName>";
+  return `${env}.${tenant}`;
+}
+
+function last4(input) {
+  const appId = normalizeText(input.applicationId);
+  return appId.length >= 4 ? appId.slice(-4) : "<last4>";
+}
+
+function substitutions(input) {
+  return {
+    "<hdfsAuthority>": normalizeText(input.hdfsAuthority) || "<hdfsAuthority>",
+    "<ENV_NAME>.<tenantName>": envTenant(input),
+    "<ENV_NAME>": normalizeText(input.environmentName) || "<ENV_NAME>",
+    "<tenantName>": normalizeText(input.tenantName) || "<tenantName>",
+    "<bucketName>": normalizeText(input.bucketName) || "<bucketName>",
+    "<owner>": normalizeText(input.owner) || "<owner>",
+    "<applicationId>": normalizeText(input.applicationId) || "<applicationId>",
+    "<last4>": last4(input),
+    "<jobId>": normalizeText(input.jobId) || "<jobId>",
+    "<snapshotId>": normalizeText(input.snapshotId) || "<snapshotId>",
+    "<yyyy>": normalizeText(input.year) || "<yyyy>",
+    "<MM>": normalizeText(input.month) || "<MM>",
+    "<dd>": normalizeText(input.day) || "<dd>",
+    "<yyyy-mm-dd>": normalizeText(input.date) || "<yyyy-mm-dd>",
+    "<hour>": normalizeText(input.hour) || "<hour>"
+  };
+}
+
+function renderTemplate(template, input) {
+  let rendered = template;
+  for (const [token, value] of Object.entries(substitutions(input))) {
+    rendered = rendered.split(token).join(value);
+  }
+  return rendered;
+}
+
+function renderCategory(category, input) {
+  return {
+    ...category,
+    templates: category.templates,
+    renderedPaths: category.templates.map((template) => renderTemplate(template, input)),
+    renderedReadOnlyChecks: (category.readOnlyChecks ?? []).map((command) => renderTemplate(command, input))
+  };
+}
+
+export class BdsHdfsPathKnowledgeService {
+  constructor({ categories = BDS_HDFS_PATH_CATEGORIES } = {}) {
+    this.categories = categories;
+  }
+
+  resolveType(value) {
+    const normalized = normalizeType(value);
+    return BDS_HDFS_PATH_ALIASES[normalized] ?? normalized;
+  }
+
+  invoke(input = {}) {
+    const requestedType = normalizeType(input.pathType);
+    const resolvedType = this.resolveType(input.pathType);
+    const selected = resolvedType ? { [resolvedType]: this.categories[resolvedType] ?? undefined } : this.categories;
+    const categories = Object.fromEntries(Object.entries(selected)
+      .filter(([, value]) => value)
+      .map(([key, value]) => [key, renderCategory(value, input)]));
+    return JSON.stringify({
+      pathType: requestedType,
+      resolvedType,
+      inputs: {
+        hdfsAuthority: normalizeText(input.hdfsAuthority),
+        environmentName: normalizeText(input.environmentName),
+        tenantName: normalizeText(input.tenantName),
+        envTenant: normalizeText(input.environmentName) || normalizeText(input.tenantName) ? envTenant(input) : "",
+        owner: normalizeText(input.owner),
+        applicationId: normalizeText(input.applicationId),
+        jobId: normalizeText(input.jobId),
+        snapshotId: normalizeText(input.snapshotId),
+        bucketName: normalizeText(input.bucketName)
+      },
+      categories,
+      safety: [
+        "Read-only only: use hdfs dfs -ls/-du/-count/-stat/-test/-cat/-tail/-find and hdfs crypto -listZones.",
+        "Do not use hdfs dfs -rm/-put/-get/-cp/-mv/-mkdir/-touchz/-chmod/-chown.",
+        "For Scylla/S3A tenant buckets, use hadoop fs from a BDM pod; do not assume hdfs exists in the pod."
+      ]
+    }, null, 2);
+  }
+}
+
+const defaultService = new BdsHdfsPathKnowledgeService();
+
+export function bdsHdfsPathKnowledge(input) {
+  return defaultService.invoke(input);
+}
+
+export const __test = {
+  BDS_HDFS_PATH_ALIASES,
+  BDS_HDFS_PATH_CATEGORIES,
+  BdsHdfsPathKnowledgeService,
+  bdsHdfsPathKnowledge,
+  envTenant,
+  renderTemplate,
+  substitutions
+};
+
+const sharedTool = defineReadOnlyTool({
+  name: "bds_hdfs_path_knowledge",
+  description: "Return BDS HDFS and S3A path templates plus rendered read-only path candidates for tenant data, operations logs, YARN app logs, Spark event logs, snapshots, encryption zones, and audit evidence.",
+  inputSchema: {
+    pathType: z.string().trim().max(128).default(""),
+    hdfsAuthority: z.string().trim().max(256).default(""),
+    environmentName: z.string().trim().max(160).default(""),
+    tenantName: z.string().trim().max(160).default(""),
+    owner: z.string().trim().max(256).default(""),
+    applicationId: z.string().trim().max(128).default(""),
+    jobId: z.string().trim().max(128).default(""),
+    snapshotId: z.string().trim().max(256).default(""),
+    bucketName: z.string().trim().max(512).default(""),
+    year: z.string().trim().max(4).default(""),
+    month: z.string().trim().max(2).default(""),
+    day: z.string().trim().max(2).default(""),
+    date: z.string().trim().max(10).default(""),
+    hour: z.string().trim().max(2).default("")
+  },
+  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
+};