@elinpf/dsh-ops-tool-environment 0.1.0

package/lib/tool.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The `environment` model tool — the preset-plane face of the inventory.
+ *
+ * Three working actions plus help:
+ *
+ * - `overview` — compact all-cluster summary (middleware counts by type,
+ *   unknown count, stale flag, scan time).
+ * - `show` — one cluster in detail: middleware instances, the unknown
+ *   bucket, relation edges.
+ * - `refresh` — re-scan every k8s profile in the ops-access registry.
+ *
+ * Freshness: overview/show call ensureFresh first — when the inventory is
+ * missing or its oldest section is older than the configured TTL, a refresh
+ * runs before answering. Nothing scans at session start; apply() only
+ * registers the tool.
+ *
+ * Refresh resolves each k8s profile WITHOUT an agent identity: the access
+ * gate's broker falls back to the ro tier for agent-less resolves, which is
+ * exactly the read-only discipline the scanner wants. kubeconfig paths are
+ * used to spawn kubectl and never surface in results — every error string
+ * crossing into tool output is scrubbed.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { readInventory, refreshInventory } from './inventory.js';
+import type { InventorySection } from './inventory.js';
+import type { CephHints, MonitoringStatus, RelationEdge, ResourceRef } from './types.js';
+export interface EnvironmentToolConfig {
+    /** Inventory file path (default ~/.dsh-ops/environment.yaml). */
+    inventoryFile: string;
+    /** User classification rules file (default ~/.dsh-ops/environment-rules.yaml). */
+    rulesFile: string;
+    /** Sections older than this are re-scanned on the next read (default 60). */
+    ttlMinutes: number;
+    /** Per-kubectl-call scan timeout (ms, default 30000). Slow clusters may need more. */
+    scanTimeoutMs: number;
+    /** Prometheus scrape timeout (ms, default 15000). */
+    prometheusTimeoutMs: number;
+}
+export interface ClusterSummary {
+    name: string;
+    scannedAt: string;
+    stale: boolean;
+    /** Middleware instance count. */
+    middleware: number;
+    /** Unknown-bucket workload count. */
+    unknown: number;
+    /** Prometheus-down target count across workloads (0 when unmonitored/healthy). */
+    down: number;
+    /** Detected anomaly count. */
+    anomalies: number;
+    /** Middleware type → instance count. */
+    byType: Array<{
+        type: string;
+        count: number;
+    }>;
+    /** CephBlockPool count when the scan found rook-ceph hints (ticket 15). */
+    cephPools?: number;
+    lastError?: string;
+}
+export interface UnknownWorkload {
+    name: string;
+    namespace: string;
+    kind: string;
+    images: string[];
+    monitoring?: MonitoringStatus;
+}
+/**
+ * Edge as shown to the model: same shape as RelationEdge but with a plain
+ * string kind — the output schema cannot express the literal union, and
+ * RelationEdge is assignable to it.
+ */
+export interface DisplayEdge {
+    kind: string;
+    from: RelationEdge['from'];
+    to: RelationEdge['to'];
+    via: string;
+    targetType?: string;
+}
+export interface ClusterDetail {
+    name: string;
+    scannedAt: string;
+    stale: boolean;
+    lastError?: string;
+    /** The Prometheus service monitoring data came from, when discovered. */
+    prometheusService?: string;
+    /** rook-ceph footprint hints (pools / cluster / tools pod), when found. */
+    ceph?: CephHints;
+    middleware: InventorySection['middleware'];
+    unknown: UnknownWorkload[];
+    edges: DisplayEdge[];
+    anomalies: DisplayAnomaly[];
+    counts: {
+        services: number;
+        ingresses: number;
+        workloads: number;
+    };
+}
+/** Anomaly as shown to the model: Anomaly with plain-string kind/severity. */
+export interface DisplayAnomaly {
+    kind: string;
+    severity: string;
+    message: string;
+    ref: ResourceRef;
+    related?: ResourceRef;
+}
+/** One anomaly line in overview output. */
+export interface OverviewAnomaly {
+    cluster: string;
+    kind: string;
+    severity: string;
+    message: string;
+}
+export interface RefreshResultEntry {
+    cluster: string;
+    status: 'ok' | 'stale' | 'skipped';
+    middleware?: number;
+    unknown?: number;
+    /** Sanitized — never carries a credential path. */
+    error?: string;
+}
+export interface EnvironmentToolResult {
+    action: string;
+    help?: string;
+    /** overview */
+    totalClusters?: number;
+    clusters?: ClusterSummary[];
+    /** overview: every detected anomaly across clusters, one line each. */
+    anomalies?: OverviewAnomaly[];
+    /** show */
+    cluster?: ClusterDetail;
+    /** refresh */
+    results?: RefreshResultEntry[];
+    refreshedAt?: string;
+    /** Non-fatal note, e.g. auto-refresh skipped because ops-access is absent. */
+    note?: string;
+    error?: string;
+}
+export interface EnvironmentToolDeps {
+    readInventory?: typeof readInventory;
+    refreshInventory?: typeof refreshInventory;
+    now?: () => number;
+}
+export interface ShowFilter {
+    namespace?: string;
+    name?: string;
+}
+/**
+ * Apply show's optional filters to a cluster detail. Both filters narrow the
+ * middleware list and the unknown bucket; when a filter is given, edges are
+ * kept only when their WORKLOAD endpoint survives the filter — that endpoint
+ * is `from` for uses-service/uses-middleware/references-secret edges and `to`
+ * for fronts edges (whose from is a Service). An investigation starts from a
+ * workload and follows its outgoing edges, so edges whose workload fell out
+ * of the filtered set are noise.
+ */
+export declare function filterDetail(detail: ClusterDetail, filter: ShowFilter): ClusterDetail;
+export declare function createEnvironmentTool(ctx: Context, config: EnvironmentToolConfig, deps?: EnvironmentToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;