@elinpf/dsh-ops-tool-environment 0.1.0

package/lib/index.js

@@ -0,0 +1,44 @@
+/**
+ * Environment inventory tool plugin (preset plane).
+ *
+ * Registers the model-facing `environment` tool (overview / show / refresh /
+ * help) on top of the ticket-01 scanner core. The tool resolves the
+ * ops-access seam per call via ctx.get — never a static inject, never
+ * cached — so it must be mounted in the same isolate realm as opsAccess
+ * (the `ops-access-registry` group in ops-preset.yml). The one-line
+ * methodology section lives in the `./prompt` subpath plugin, mounted with
+ * the prompt-channel consumers.
+ *
+ * apply() only registers the tool: nothing scans at session start. Scans
+ * happen on explicit refresh, or on a read whose oldest section is past
+ * the TTL.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import z from '@deepseek-ai/schemastery';
+import { DEFAULT_USER_RULES_FILE } from './classify.js';
+import { DEFAULT_INVENTORY_FILE } from './inventory.js';
+import { createEnvironmentTool } from './tool.js';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-tool-environment';
+export const inject = ['tools'];
+// ── Config ───────────────────────────────────────────────────────────────────
+export const Config = z.object({
+    inventoryFile: z.string().default(DEFAULT_INVENTORY_FILE),
+    rulesFile: z.string().default(DEFAULT_USER_RULES_FILE),
+    ttlMinutes: z.number().default(60),
+    scanTimeoutMs: z.number().default(30000),
+    prometheusTimeoutMs: z.number().default(15000),
+});
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx, config) {
+    ctx.effect(() => ctx.tools.register(createEnvironmentTool(ctx, config)));
+}
+export { builtinRules, classifySignals, classifyWorkload, DEFAULT_USER_RULES_FILE, expandHome, isMiddlewareType, loadUserRules, } from './classify.js';
+export { defaultExec, ScanError, SCAN_TIMEOUT_MS, scanCluster, scrubKubeconfigPath, } from './scanner.js';
+export { buildRelations, findServiceAddresses } from './relations.js';
+export { detectAnomalies } from './anomalies.js';
+export { findPrometheusService, matchTargetsToWorkloads, parseActiveTargets, scrapePrometheusTargets, } from './prometheus.js';
+export { buildClusterInventory, DEFAULT_INVENTORY_FILE, readInventory, refreshInventory, } from './inventory.js';
+export { createEnvironmentTool, filterDetail } from './tool.js';
+export { HELP_POINTER, HELP_TEXT, STATIC_PROMPT, TOOL_DESCRIPTION } from './doctrine.js';

package/lib/inventory.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Inventory persistence — `~/.dsh-ops/environment.yaml`.
+ *
+ * The file is auto-generated (header says so), segmented per cluster, and
+ * each section carries the scan timestamp. Freshness discipline lives here:
+ * refreshInventory re-scans every target cluster; a cluster that fails
+ * (unreachable, timeout, kubectl error) keeps its previous section with
+ * `stale: true` and a sanitized `lastError` — the section never disappears
+ * and the failure never aborts the other clusters.
+ *
+ * Security discipline: the kubeconfig path is used to run kubectl and then
+ * scrubbed out of every error before it is stored; Secret values never
+ * enter the pipeline (see scanner.ts). What lands in this file is safe to
+ * show the model verbatim.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { SpawnFn } from './prometheus.js';
+import type { ExecFn } from './scanner.js';
+import type { ClusterInventory, ClusterScan } from './types.js';
+export declare const DEFAULT_INVENTORY_FILE = "~/.dsh-ops/environment.yaml";
+/** One cluster section: the inventory plus freshness markers. */
+export interface InventorySection extends ClusterInventory {
+    /** Set when the last refresh failed and this section holds older data. */
+    stale?: boolean;
+    /** Sanitized message of the last refresh failure (no credential paths). */
+    lastError?: string;
+}
+/** The whole environment.yaml document. */
+export interface EnvironmentInventory {
+    version: 1;
+    clusters: Record<string, InventorySection>;
+}
+/** A cluster to refresh: profile id plus its resolved kubeconfig path. */
+export interface RefreshTarget {
+    cluster: string;
+    kubeconfigPath: string;
+}
+export interface RefreshOptions {
+    /** Inventory file path; defaults to ~/.dsh-ops/environment.yaml. */
+    file?: string;
+    /** Injectable kubectl runner (tests); defaults to spawning kubectl. */
+    exec?: ExecFn;
+    /** Injectable port-forward spawn for the Prometheus scrape (tests). */
+    spawn?: SpawnFn;
+    /** Injectable fetch for the Prometheus scrape (tests). */
+    fetchFn?: typeof fetch;
+    /** User classification rules file; defaults to ~/.dsh-ops/environment-rules.yaml. */
+    userRulesFile?: string;
+    /** Timestamp source (tests). */
+    now?: Date;
+    /** Per-kubectl-call scan timeout (ms); defaults to the scanner's own 30s. */
+    scanTimeoutMs?: number;
+    /** Prometheus scrape timeout (ms); defaults to the scrape's own 15s. */
+    prometheusTimeoutMs?: number;
+}
+/**
+ * Assemble the per-cluster inventory from a raw scan: classify every
+ * workload, collect middleware instances with their Service entries, and
+ * derive relation edges. Deterministic — output lists are sorted so the
+ * same cluster scanned twice yields the same section.
+ */
+export declare function buildClusterInventory(scan: ClusterScan, opts?: {
+    userRulesFile?: string;
+}): ClusterInventory;
+/** Read the inventory file. Returns null when it does not exist or is malformed. */
+export declare function readInventory(file?: string): Promise<EnvironmentInventory | null>;
+/**
+ * Refresh the inventory for the given clusters.
+ *
+ * Per cluster: scan + assemble + replace the section. On failure the
+ * previous section survives with `stale: true` and a sanitized lastError;
+ * a cluster with no previous data gets an empty stale section so the gap
+ * is visible. Sections of clusters not in `targets` are left untouched.
+ * Never throws — per-cluster failures are folded into their sections.
+ */
+export declare function refreshInventory(targets: RefreshTarget[], opts?: RefreshOptions): Promise<EnvironmentInventory>;

package/lib/inventory.js

@@ -0,0 +1,168 @@
+/**
+ * Inventory persistence — `~/.dsh-ops/environment.yaml`.
+ *
+ * The file is auto-generated (header says so), segmented per cluster, and
+ * each section carries the scan timestamp. Freshness discipline lives here:
+ * refreshInventory re-scans every target cluster; a cluster that fails
+ * (unreachable, timeout, kubectl error) keeps its previous section with
+ * `stale: true` and a sanitized `lastError` — the section never disappears
+ * and the failure never aborts the other clusters.
+ *
+ * Security discipline: the kubeconfig path is used to run kubectl and then
+ * scrubbed out of every error before it is stored; Secret values never
+ * enter the pipeline (see scanner.ts). What lands in this file is safe to
+ * show the model verbatim.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { classifyWorkload, expandHome, isMiddlewareType } from './classify.js';
+import { detectAnomalies } from './anomalies.js';
+import { matchTargetsToWorkloads } from './prometheus.js';
+import { buildRelations } from './relations.js';
+import { scanCluster, scrubKubeconfigPath } from './scanner.js';
+export const DEFAULT_INVENTORY_FILE = '~/.dsh-ops/environment.yaml';
+const HEADER = [
+    '# AUTO-GENERATED by @elinpf/dsh-ops-tool-environment — DO NOT EDIT BY HAND.',
+    '# Regenerated from live k8s scans; manual changes are overwritten on the next refresh.',
+].join('\n');
+const byNsName = (a, b) => a.namespace.localeCompare(b.namespace) || a.name.localeCompare(b.name);
+/**
+ * Assemble the per-cluster inventory from a raw scan: classify every
+ * workload, collect middleware instances with their Service entries, and
+ * derive relation edges. Deterministic — output lists are sorted so the
+ * same cluster scanned twice yields the same section.
+ */
+export function buildClusterInventory(scan, opts = {}) {
+    const classified = scan.workloads
+        .map(w => ({ ...w, type: classifyWorkload(w, { userRulesFile: opts.userRulesFile }) }))
+        .sort(byNsName);
+    // Prometheus corroboration: attach up/down counts per workload (best-effort;
+    // absent when the cluster had no scrapable Prometheus).
+    if (scan.prometheus !== undefined) {
+        const statuses = matchTargetsToWorkloads(classified, scan.prometheus.targets);
+        for (const w of classified) {
+            const status = statuses.get(`${w.namespace}/${w.name}`);
+            if (status !== undefined)
+                w.monitoring = status;
+        }
+    }
+    const edges = buildRelations({ scan, classified });
+    const services = [...scan.services].sort(byNsName);
+    const middleware = [];
+    for (const w of classified) {
+        if (!isMiddlewareType(w.type))
+            continue;
+        const serviceEntries = edges
+            .filter(e => e.kind === 'fronts' && e.to.kind === w.kind && e.to.namespace === w.namespace && e.to.name === w.name)
+            .map(e => e.from.name)
+            .sort();
+        const instance = {
+            type: w.type,
+            namespace: w.namespace,
+            workload: w.name,
+            workloadKind: w.kind,
+            images: [...w.images].sort(),
+            serviceEntries,
+        };
+        if (w.monitoring !== undefined)
+            instance.monitoring = w.monitoring;
+        middleware.push(instance);
+    }
+    middleware.sort((a, b) => a.namespace.localeCompare(b.namespace) || a.workload.localeCompare(b.workload));
+    edges.sort((a, b) => a.kind.localeCompare(b.kind)
+        || a.from.namespace.localeCompare(b.from.namespace)
+        || a.from.name.localeCompare(b.from.name)
+        || a.to.name.localeCompare(b.to.name)
+        || a.via.localeCompare(b.via));
+    const inventory = {
+        scannedAt: scan.scannedAt,
+        middleware,
+        anomalies: detectAnomalies({ edges, services, endpoints: scan.endpoints }),
+        workloads: classified,
+        services,
+        ingresses: [...scan.ingresses].sort(byNsName),
+        edges,
+    };
+    if (scan.prometheus !== undefined)
+        inventory.prometheusService = scan.prometheus.service;
+    if (scan.ceph !== undefined)
+        inventory.ceph = scan.ceph;
+    return inventory;
+}
+/** Read the inventory file. Returns null when it does not exist or is malformed. */
+export async function readInventory(file = DEFAULT_INVENTORY_FILE) {
+    let text;
+    try {
+        text = await readFile(expandHome(file), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const doc = parseYaml(text);
+        if (!doc || typeof doc !== 'object' || typeof doc.clusters !== 'object' || doc.clusters === null) {
+            return null;
+        }
+        return doc;
+    }
+    catch {
+        return null;
+    }
+}
+/** Serialize and write the inventory, prepending the do-not-edit header. */
+async function writeInventory(file, inventory) {
+    const path = expandHome(file);
+    await mkdir(dirname(path), { recursive: true });
+    const body = stringifyYaml(inventory);
+    await writeFile(path, `${HEADER}\n${body}`, 'utf8');
+}
+function emptySection(scannedAt) {
+    return { scannedAt, middleware: [], anomalies: [], workloads: [], services: [], ingresses: [], edges: [] };
+}
+/**
+ * Refresh the inventory for the given clusters.
+ *
+ * Per cluster: scan + assemble + replace the section. On failure the
+ * previous section survives with `stale: true` and a sanitized lastError;
+ * a cluster with no previous data gets an empty stale section so the gap
+ * is visible. Sections of clusters not in `targets` are left untouched.
+ * Never throws — per-cluster failures are folded into their sections.
+ */
+export async function refreshInventory(targets, opts = {}) {
+    const file = opts.file ?? DEFAULT_INVENTORY_FILE;
+    const now = opts.now ?? new Date();
+    const existing = await readInventory(file);
+    const clusters = { ...(existing?.clusters ?? {}) };
+    await Promise.all(targets.map(async (target) => {
+        try {
+            const scan = await scanCluster({
+                cluster: target.cluster,
+                kubeconfigPath: target.kubeconfigPath,
+                exec: opts.exec,
+                spawn: opts.spawn,
+                fetchFn: opts.fetchFn,
+                timeoutMs: opts.scanTimeoutMs,
+                prometheusTimeoutMs: opts.prometheusTimeoutMs,
+                now,
+            });
+            clusters[target.cluster] = buildClusterInventory(scan, { userRulesFile: opts.userRulesFile });
+        }
+        catch (err) {
+            const raw = err instanceof Error ? err.message : String(err);
+            // Defense in depth: scanner errors are pre-scrubbed; scrub again here so
+            // no code path can persist the real kubeconfig path.
+            const lastError = scrubKubeconfigPath(raw, target.kubeconfigPath);
+            const previous = clusters[target.cluster] ?? emptySection(now.toISOString());
+            clusters[target.cluster] = { ...previous, stale: true, lastError };
+        }
+    }));
+    const inventory = {
+        version: 1,
+        clusters: Object.fromEntries(Object.entries(clusters).sort(([a], [b]) => a.localeCompare(b))),
+    };
+    await writeInventory(file, inventory);
+    return inventory;
+}

package/lib/prometheus.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Prometheus read-only corroboration (spec 0003, ticket 03).
+ *
+ * When a cluster has a discoverable Prometheus service, the scanner opens a
+ * `kubectl port-forward` to it, reads `/api/v1/targets?state=active`, and
+ * matches targets onto workloads by namespace + pod-name prefix. The result
+ * is a compact `monitoring: { up, down }` per workload — k8s data and
+ * Prometheus state corroborate each other, and a down instance surfaces in
+ * the inventory.
+ *
+ * Everything here is an ENHANCEMENT, never a hard dependency: no Prometheus
+ * service, port-forward failure, timeout, or malformed response all degrade
+ * to "no monitoring data" — the cluster section is still written and is NOT
+ * marked stale (stale is reserved for k8s scan failures).
+ *
+ * Lifecycle discipline: the port-forward child is always killed (SIGKILL
+ * after a SIGTERM grace) and reaped before this module returns, on every
+ * path — success, error, or timeout. The kubeconfig path appears only in
+ * the child's argv, never in returned data.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { ScannedService } from './types.js';
+/** 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;
+}
+/** Minimal child-process surface the scraper drives (injectable for tests). */
+export interface PortForwardProcess {
+    stdout: NodeJS.ReadableStream | null;
+    stderr: NodeJS.ReadableStream | null;
+    /** Set once the process has exited (node's ChildProcess has this natively). */
+    exitCode?: number | null;
+    kill(signal?: NodeJS.Signals): boolean;
+    once(event: 'exit', listener: (code: number | null) => void): unknown;
+}
+export type SpawnFn = (args: string[]) => PortForwardProcess;
+/**
+ * Find the cluster's Prometheus service. Heuristic: a Service whose name
+ * contains 'prometheus' and which exposes port 9090; the `monitoring`
+ * namespace wins ties (kube-prometheus-stack names its service
+ * `*-kube-prometheus-stack-prometheus` there). Returns undefined when no
+ * candidate exists — the caller then skips the enhancement.
+ */
+export declare function findPrometheusService(services: ScannedService[]): ScannedService | undefined;
+/** Parse a /api/v1/targets response. Malformed input yields [], never throws. */
+export declare function parseActiveTargets(body: unknown): PromTarget[];
+interface WorkloadIdentity {
+    namespace: string;
+    name: string;
+}
+/**
+ * Match targets onto workloads by namespace + pod-name prefix
+ * (`<workload>-<suffix>` covers Deployment ReplicaSet hashes, StatefulSet
+ * ordinals, and DaemonSet suffixes). A pod matching several names goes to
+ * the LONGEST one (`foo-bar-xyz` belongs to `foo-bar`, not `foo`).
+ * Targets without a pod label, or matching no workload, are dropped.
+ */
+export declare function matchTargetsToWorkloads(workloads: WorkloadIdentity[], targets: PromTarget[]): Map<string, MonitoringStatus>;
+export interface ScrapeOptions {
+    kubeconfigPath: string;
+    /** The scanned services of the cluster (discovery source). */
+    services: ScannedService[];
+    /** Injectable process spawn (tests); defaults to node:child_process. */
+    spawn?: SpawnFn;
+    /** Injectable fetch (tests); defaults to global fetch. */
+    fetchFn?: typeof fetch;
+    /** Readiness + overall watchdog budget. Default 15s. */
+    timeoutMs?: number;
+}
+/**
+ * Discover the cluster's Prometheus and scrape its active targets through a
+ * kubectl port-forward. Returns undefined on ANY failure — no candidate,
+ * spawn error, readiness timeout, fetch error, malformed JSON — and always
+ * reaps the child process. The caller treats undefined as "no monitoring
+ * data", never as a scan failure.
+ */
+export declare function scrapePrometheusTargets(opts: ScrapeOptions): Promise<{
+    service: string;
+    targets: PromTarget[];
+} | undefined>;
+export {};

package/lib/prometheus.js

@@ -0,0 +1,190 @@
+/**
+ * Prometheus read-only corroboration (spec 0003, ticket 03).
+ *
+ * When a cluster has a discoverable Prometheus service, the scanner opens a
+ * `kubectl port-forward` to it, reads `/api/v1/targets?state=active`, and
+ * matches targets onto workloads by namespace + pod-name prefix. The result
+ * is a compact `monitoring: { up, down }` per workload — k8s data and
+ * Prometheus state corroborate each other, and a down instance surfaces in
+ * the inventory.
+ *
+ * Everything here is an ENHANCEMENT, never a hard dependency: no Prometheus
+ * service, port-forward failure, timeout, or malformed response all degrade
+ * to "no monitoring data" — the cluster section is still written and is NOT
+ * marked stale (stale is reserved for k8s scan failures).
+ *
+ * Lifecycle discipline: the port-forward child is always killed (SIGKILL
+ * after a SIGTERM grace) and reaped before this module returns, on every
+ * path — success, error, or timeout. The kubeconfig path appears only in
+ * the child's argv, never in returned data.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:net';
+const defaultSpawn = (args) => spawn(args[0], args.slice(1), { stdio: ['ignore', 'pipe', 'pipe'] });
+// ── Discovery ────────────────────────────────────────────────────────────────
+/**
+ * Find the cluster's Prometheus service. Heuristic: a Service whose name
+ * contains 'prometheus' and which exposes port 9090; the `monitoring`
+ * namespace wins ties (kube-prometheus-stack names its service
+ * `*-kube-prometheus-stack-prometheus` there). Returns undefined when no
+ * candidate exists — the caller then skips the enhancement.
+ */
+export function findPrometheusService(services) {
+    const candidates = services.filter(s => s.name.includes('prometheus') && s.ports.some(p => p.port === 9090));
+    return candidates.find(s => s.namespace === 'monitoring') ?? candidates[0];
+}
+// ── Targets parsing ──────────────────────────────────────────────────────────
+/** Parse a /api/v1/targets response. Malformed input yields [], never throws. */
+export function parseActiveTargets(body) {
+    try {
+        const data = body?.data;
+        if (!data || !Array.isArray(data.activeTargets))
+            return [];
+        const targets = [];
+        for (const entry of data.activeTargets) {
+            const labels = entry?.labels ?? {};
+            const health = entry?.health;
+            if (typeof health !== 'string')
+                continue;
+            const target = { health };
+            for (const key of ['namespace', 'pod', 'service', 'job']) {
+                const value = labels[key];
+                if (typeof value === 'string' && value !== '')
+                    target[key] = value;
+            }
+            targets.push(target);
+        }
+        return targets;
+    }
+    catch {
+        return [];
+    }
+}
+function workloadKey(w) {
+    return `${w.namespace}/${w.name}`;
+}
+/**
+ * Match targets onto workloads by namespace + pod-name prefix
+ * (`<workload>-<suffix>` covers Deployment ReplicaSet hashes, StatefulSet
+ * ordinals, and DaemonSet suffixes). A pod matching several names goes to
+ * the LONGEST one (`foo-bar-xyz` belongs to `foo-bar`, not `foo`).
+ * Targets without a pod label, or matching no workload, are dropped.
+ */
+export function matchTargetsToWorkloads(workloads, targets) {
+    const statuses = new Map();
+    for (const target of targets) {
+        if (!target.namespace || !target.pod)
+            continue;
+        let best;
+        for (const w of workloads) {
+            if (w.namespace !== target.namespace)
+                continue;
+            if (target.pod !== w.name && !target.pod.startsWith(`${w.name}-`))
+                continue;
+            if (!best || w.name.length > best.name.length)
+                best = w;
+        }
+        if (!best)
+            continue;
+        const key = workloadKey(best);
+        const status = statuses.get(key) ?? { up: 0, down: 0 };
+        if (target.health === 'up')
+            status.up++;
+        else if (target.health === 'down')
+            status.down++;
+        statuses.set(key, status);
+    }
+    return statuses;
+}
+const DEFAULT_SCRAPE_TIMEOUT_MS = 15_000;
+const KILL_GRACE_MS = 2_000;
+/** Pick an ephemeral local port by binding and releasing :0. */
+function pickLocalPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address !== null ? address.port : 0;
+            server.close(() => port > 0 ? resolve(port) : reject(new Error('no ephemeral port')));
+        });
+    });
+}
+/** Kill the child (SIGTERM, then SIGKILL after a grace) and wait for exit. */
+async function reap(child) {
+    if (child.exitCode !== undefined && child.exitCode !== null)
+        return; // already dead
+    const exited = new Promise(resolve => child.once('exit', () => resolve()));
+    child.kill('SIGTERM');
+    const deadline = new Promise(resolve => setTimeout(resolve, KILL_GRACE_MS));
+    await Promise.race([exited, deadline]);
+    child.kill('SIGKILL'); // no-op if already dead
+    await Promise.race([exited, deadline]);
+}
+/** Wait until kubectl port-forward announces readiness (or dies trying). */
+function waitForForwarding(child, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buffer = '';
+        const onExit = (code) => {
+            cleanup();
+            reject(new Error(`port-forward exited before ready (code ${code ?? 'null'})`));
+        };
+        const onData = (chunk) => {
+            buffer += chunk.toString('utf8');
+            if (buffer.includes('Forwarding from')) {
+                cleanup();
+                resolve();
+            }
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`port-forward not ready within ${timeoutMs}ms`));
+        }, timeoutMs);
+        function cleanup() {
+            clearTimeout(timer);
+            child.stdout?.removeListener('data', onData);
+        }
+        child.stdout?.on('data', onData);
+        child.once('exit', onExit);
+    });
+}
+/**
+ * Discover the cluster's Prometheus and scrape its active targets through a
+ * kubectl port-forward. Returns undefined on ANY failure — no candidate,
+ * spawn error, readiness timeout, fetch error, malformed JSON — and always
+ * reaps the child process. The caller treats undefined as "no monitoring
+ * data", never as a scan failure.
+ */
+export async function scrapePrometheusTargets(opts) {
+    const service = findPrometheusService(opts.services);
+    if (!service)
+        return undefined;
+    const servicePort = service.ports.find(p => p.port === 9090).port;
+    const spawnFn = opts.spawn ?? defaultSpawn;
+    const fetchFn = opts.fetchFn ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_SCRAPE_TIMEOUT_MS;
+    let child;
+    try {
+        const localPort = await pickLocalPort();
+        child = spawnFn([
+            'kubectl', `--kubeconfig=${opts.kubeconfigPath}`,
+            '-n', service.namespace,
+            'port-forward', `svc/${service.name}`, `${localPort}:${servicePort}`,
+        ]);
+        await waitForForwarding(child, timeoutMs);
+        const response = await fetchFn(`http://127.0.0.1:${localPort}/api/v1/targets?state=active`, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok)
+            return undefined;
+        const targets = parseActiveTargets(await response.json());
+        return { service: `${service.namespace}/${service.name}`, targets };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (child)
+            await reap(child);
+    }
+}

package/lib/prompt.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Prompt half of the environment inventory (preset plane).
+ *
+ * Registers the one-line methodology section ("run environment overview
+ * before investigating") through the ops-prompts channel. Split from the
+ * tool entry because of realm topology: the tool needs the opsAccess
+ * isolate realm (ops-access-registry group), the prompt needs the
+ * opsPrompts realm (ops-orchestration group), and entry-local realms are
+ * invisible across groups. Mount this row inside the ops-orchestration
+ * group; see ops-preset.yml.
+ *
+ * @module @elinpf/dsh-ops-tool-environment/prompt
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { OpsPromptsHandle } from '@elinpf/dsh-ops-prompts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        opsPrompts?: OpsPromptsHandle;
+    }
+}
+export declare const name = "ops-tool-environment-prompt";
+export declare function apply(ctx: Context): void;

package/lib/prompt.js

@@ -0,0 +1,43 @@
+/**
+ * Prompt half of the environment inventory (preset plane).
+ *
+ * Registers the one-line methodology section ("run environment overview
+ * before investigating") through the ops-prompts channel. Split from the
+ * tool entry because of realm topology: the tool needs the opsAccess
+ * isolate realm (ops-access-registry group), the prompt needs the
+ * opsPrompts realm (ops-orchestration group), and entry-local realms are
+ * invisible across groups. Mount this row inside the ops-orchestration
+ * group; see ops-preset.yml.
+ *
+ * @module @elinpf/dsh-ops-tool-environment/prompt
+ */
+import { STATIC_PROMPT } from './doctrine.js';
+// ── Plugin identity ───────────────────────────────────────────────────────────
+export const name = 'ops-tool-environment-prompt';
+// ── Plugin apply ─────────────────────────────────────────────────────────────
+export function apply(ctx) {
+    // registerMethodology returns a disposer — route it through ctx.effect so
+    // the section leaves the ops-prompts registry when this plugin's fiber is
+    // disposed (HMR reload / preset unmount), not just on process exit.
+    const registerThroughHandle = (rctx, opsPrompts) => {
+        rctx.effect(() => opsPrompts.registerMethodology({
+            name: 'environment:usage',
+            order: 250,
+            text: STATIC_PROMPT,
+        }));
+    };
+    // The preset mounts the group's plugins concurrently, so a one-shot
+    // ctx.get can lose the race against ops-prompts' provide — fall back to
+    // ctx.inject, which defers until the service arrives. When ops-prompts is
+    // genuinely absent, the tool description and action=help still carry the
+    // usage documentation.
+    const immediate = ctx.get('opsPrompts');
+    if (immediate !== undefined) {
+        registerThroughHandle(ctx, immediate);
+    }
+    else {
+        ctx.inject(['opsPrompts'], (pctx) => {
+            registerThroughHandle(pctx, pctx.opsPrompts);
+        });
+    }
+}

package/lib/relations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Best-effort relation edges between scanned resources.
+ *
+ * Sources of truth, in order of strength:
+ *
+ * - `fronts` — a Service whose pod selector is a subset of a workload's pod
+ *   template labels fronts that workload. Deterministic, from k8s itself.
+ * - `uses-service` — a literal `env` value or a data value of a referenced
+ *   ConfigMap contains a `<name>.<namespace>.svc[.cluster.local]` address
+ *   that resolves to a scanned Service.
+ * - `uses-middleware` — composition of the two above: a workload that uses
+ *   a Service which fronts a recognized middleware instance.
+ * - `references-secret` — envFrom/valueFrom secret references, NAME only.
+ *   Secret values are never read anywhere in this package.
+ *
+ * Everything here is best-effort: a value that parses to nothing produces
+ * no edge and no error. A missing ConfigMap, a dangling Service name, a
+ * selector-less Service — all simply yield no edge.
+ *
+ * @module @elinpf/dsh-ops-tool-environment
+ */
+import type { ClassifiedWorkload, ClusterScan, RelationEdge } from './types.js';
+/** Extract distinct (name, namespace) Service addresses mentioned in a text value. */
+export declare function findServiceAddresses(value: string): Array<{
+    name: string;
+    namespace: string;
+}>;
+export interface BuildRelationsInput {
+    scan: ClusterScan;
+    /** Workloads after classification — used to compose uses-middleware edges. */
+    classified: ClassifiedWorkload[];
+}
+/** Derive all relation edges for one scanned cluster. Never throws. */
+export declare function buildRelations(input: BuildRelationsInput): RelationEdge[];