@elinpf/dsh-ops-tool-environment 0.1.0

package/lib/types.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Shared shapes for the environment inventory scanner core.
+ *
+ * Data flow: scanCluster (raw k8s reads) -> ClusterScan; buildClusterInventory
+ * (classification + relations) -> ClusterInventory; inventory.ts persists
+ * ClusterInventory per cluster section. Everything here is plain data —
+ * no credential paths, no Secret values ever appear in these shapes.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+/** Reference to a namespaced k8s object. */
+export interface ResourceRef {
+    kind: string;
+    namespace: string;
+    name: string;
+}
+/** A workload (Deployment / StatefulSet / DaemonSet) reduced to scan-relevant fields. */
+export interface ScannedWorkload {
+    kind: 'Deployment' | 'StatefulSet' | 'DaemonSet';
+    namespace: string;
+    name: string;
+    /** All container images (init containers included), as written in the spec. */
+    images: string[];
+    /** Workload metadata labels. */
+    labels: Record<string, string>;
+    /** Pod template labels — the set a Service selector matches against. */
+    podLabels: Record<string, string>;
+    /** Plaintext env values only: { VAR: value }. valueFrom entries never appear here. */
+    env: Record<string, string>;
+    /** ConfigMap names referenced via envFrom.configMapRef or env.valueFrom.configMapKeyRef. */
+    configMapRefs: string[];
+    /** Secret names referenced via envFrom.secretRef or env.valueFrom.secretKeyRef — names only, never values. */
+    secretRefs: string[];
+}
+export interface ScannedService {
+    namespace: string;
+    name: string;
+    /** ClusterIP / NodePort / LoadBalancer / ExternalName. */
+    type: string;
+    clusterIP?: string;
+    externalName?: string;
+    ports: Array<{
+        port: number;
+        targetPort?: number | string;
+        name?: string;
+    }>;
+    /** Pod selector; null for selector-less Services (external endpoints). */
+    selector: Record<string, string> | null;
+    labels: Record<string, string>;
+}
+export interface ScannedIngress {
+    namespace: string;
+    name: string;
+    hosts: string[];
+    /** Service backends referenced by the rules. */
+    serviceBackends: Array<{
+        serviceName: string;
+        servicePort?: number | string;
+    }>;
+}
+export interface ScannedConfigMap {
+    namespace: string;
+    name: string;
+    /** Plain configuration — ConfigMap data is non-secret by design. */
+    data: Record<string, string>;
+}
+/** Secret metadata only. The scanner never requests `data`/`stringData`. */
+export interface ScannedSecret {
+    namespace: string;
+    name: string;
+}
+/** An Endpoints object reduced to what anomaly detection needs. */
+export interface ScannedEndpoints {
+    namespace: string;
+    name: string;
+    /** Ready backend address count (sum of subsets[].addresses). */
+    addresses: number;
+}
+/**
+ * A rule-detected anomaly in a cluster section. Rules only use generic k8s
+ * semantics (namespace comparison, selector/endpoints agreement) — never
+ * environment-specific names.
+ */
+export interface Anomaly {
+    kind: 'cross-namespace-ref' | 'service-no-backend';
+    severity: 'info' | 'warning';
+    /** The object the anomaly is about (the referencing workload, or the backend-less Service). */
+    ref: ResourceRef;
+    /** The other side, for cross-namespace references. */
+    related?: ResourceRef;
+    /** One-line human-readable statement. */
+    message: string;
+}
+/** One active Prometheus target, reduced to what matching needs. */
+export interface PromTarget {
+    namespace?: string;
+    pod?: string;
+    service?: string;
+    job?: string;
+    /** Prometheus health string: 'up' | 'down' | 'unknown'. */
+    health: string;
+}
+/** Compact per-workload monitoring status attached to inventory entries. */
+export interface MonitoringStatus {
+    up: number;
+    down: number;
+}
+/** rook-ceph footprint hints discovered in a cluster (ticket 15). */
+export interface CephHints {
+    /** CephBlockPool CRs — the pool names to use with the ceph tool (`rbd ls -p <name>`). */
+    pools: {
+        namespace: string;
+        name: string;
+    }[];
+    /** CephCluster CRs. */
+    clusters: {
+        namespace: string;
+        name: string;
+    }[];
+    /**
+     * rook-ceph-tools pod location when one is deployed (in-cluster ceph
+     * CLI); absent = none deployed, which is itself useful to know.
+     */
+    toolsPod?: {
+        namespace: string;
+        name: string;
+    };
+}
+/** Raw read of one cluster — the scanner's output before classification. */
+export interface ClusterScan {
+    /** Cluster profile id (the ops-access registry key), never a path. */
+    cluster: string;
+    /** ISO timestamp of the scan. */
+    scannedAt: string;
+    workloads: ScannedWorkload[];
+    services: ScannedService[];
+    ingresses: ScannedIngress[];
+    configMaps: ScannedConfigMap[];
+    secrets: ScannedSecret[];
+    /**
+     * Endpoints read (ready-address counts per Service). Undefined when the
+     * read failed — detectors that need it then skip, rather than guessing.
+     */
+    endpoints?: ScannedEndpoints[];
+    /**
+     * Prometheus corroboration, when a Prometheus service was discovered and
+     * scraped (undefined otherwise — enhancement, never a hard dependency).
+     */
+    prometheus?: {
+        service: string;
+        targets: PromTarget[];
+    };
+    /**
+     * rook-ceph hints, when any were found (pools/clusters/tools pod).
+     * Absent both when the cluster has no rook footprint AND when the reads
+     * failed — absence of evidence is not annotated.
+     */
+    ceph?: CephHints;
+}
+/** A workload after classification. `type` is a middleware name, 'infra', or 'unknown'. */
+export interface ClassifiedWorkload extends ScannedWorkload {
+    type: string;
+    /** Prometheus up/down counts, when the cluster has a scrapable Prometheus. */
+    monitoring?: MonitoringStatus;
+}
+/** A recognized middleware instance: workload + the Services fronting it. */
+export interface MiddlewareInstance {
+    /** Middleware type from the classification table (e.g. 'redis', 'mysql'). */
+    type: string;
+    namespace: string;
+    /** Workload name. */
+    workload: string;
+    workloadKind: string;
+    images: string[];
+    /** Names of Services whose selector matches this instance's pod labels. */
+    serviceEntries: string[];
+    /** Prometheus up/down counts, when available. */
+    monitoring?: MonitoringStatus;
+}
+/**
+ * A best-effort relation edge.
+ *
+ * - `uses-service`      workload -> Service (found a svc FQDN in env/ConfigMap values)
+ * - `fronts`            Service -> workload (Service selector matches pod labels)
+ * - `uses-middleware`   workload -> middleware instance (uses-service + fronts composed)
+ * - `references-secret` workload -> Secret (envFrom/env secretRef; the name only)
+ */
+export interface RelationEdge {
+    kind: 'uses-service' | 'fronts' | 'uses-middleware' | 'references-secret';
+    from: ResourceRef;
+    to: ResourceRef;
+    /** Where the link was seen, e.g. 'env:PG_HOST' or 'configmap:app-config:PG_HOST'. */
+    via: string;
+    /** Middleware type, set on uses-middleware edges. */
+    targetType?: string;
+}
+/** The per-cluster section that lands in environment.yaml. */
+export interface ClusterInventory {
+    /** ISO timestamp of the scan that produced this section. */
+    scannedAt: string;
+    /** Middleware instances recognized by the classification table. */
+    middleware: MiddlewareInstance[];
+    /** Rule-detected anomalies (cross-namespace references, backend-less Services). */
+    anomalies: Anomaly[];
+    /**
+     * Every scanned workload with its classification. Workloads with
+     * type 'unknown' are the unknown bucket — listed, never dropped.
+     */
+    workloads: ClassifiedWorkload[];
+    services: ScannedService[];
+    ingresses: ScannedIngress[];
+    edges: RelationEdge[];
+    /** The Prometheus service this cluster's monitoring data came from. */
+    prometheusService?: string;
+    /** rook-ceph footprint hints carried through from the scan. */
+    ceph?: CephHints;
+}

package/lib/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared shapes for the environment inventory scanner core.
+ *
+ * Data flow: scanCluster (raw k8s reads) -> ClusterScan; buildClusterInventory
+ * (classification + relations) -> ClusterInventory; inventory.ts persists
+ * ClusterInventory per cluster section. Everything here is plain data —
+ * no credential paths, no Secret values ever appear in these shapes.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@elinpf/dsh-ops-tool-environment",
+  "version": "0.1.0",
+  "description": "Environment inventory for ops mode — read-only scanner that maps registered k8s clusters (workloads, services, middleware instances, best-effort relation edges) into ~/.dsh-ops/environment.yaml, plus the model-facing environment tool (overview/show/refresh). Deterministic code only, zero LLM.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./prompt": {
+      "types": "./lib/prompt.d.ts",
+      "default": "./lib/prompt.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "yaml": "^2.7.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@elinpf/dsh-ops-access": "^0.1.0",
+    "@elinpf/dsh-ops-prompts": "^0.1.0",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-tools": "0.0.1-rc.1",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.11",
+    "@elinpf/dsh-ops-access": "0.1.0",
+    "@elinpf/dsh-ops-prompts": "0.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}