openk8s 0.0.1 → 1.0.0

package/src/lib/kubectl/kubectl-service.ts

@@ -0,0 +1,1116 @@
+import { type ChildProcess } from "node:child_process";
+
+import { formatAge } from "../k8s/k8s-format";
+import { buildResourceDetail, type KubernetesResource } from "../k8s/resource-detail-builder";
+import type {
+  ClusterContext,
+  EventItem,
+  LogOptions,
+  NamespaceItem,
+  ResourceDetail,
+  ResourceKind,
+  ResourceListItem,
+  ResourceRef,
+} from "../k8s/types";
+import { runCommand, runJson, runText, startPersistentProcess } from "./spawn-utils";
+
+const KUBECTL_TIMEOUT_MS = 15_000;
+
+export class KubectlService {
+  async isAvailable(): Promise<boolean> {
+    try {
+      await runCommand({ command: "kubectl", args: ["version", "--client"], timeoutMs: KUBECTL_TIMEOUT_MS });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async isHelmAvailable(): Promise<boolean> {
+    try {
+      await runCommand({ command: "helm", args: ["version", "--short"], timeoutMs: KUBECTL_TIMEOUT_MS });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async listContexts(): Promise<ClusterContext[]> {
+    const parsed = await runJson<KubeConfigContextResponse>({
+      command: "kubectl",
+      args: ["config", "view", "-o", "json"],
+      timeoutMs: KUBECTL_TIMEOUT_MS,
+    });
+    const current = parsed["current-context"];
+
+    return (parsed.contexts ?? [])
+      .map((context) => context.name)
+      .filter((name): name is string => Boolean(name))
+      .map((name) => ({ name, isCurrent: name === current }));
+  }
+
+  async listNamespaces(options: ListNamespacesOptions): Promise<NamespaceItem[]> {
+    const parsed = await runJson<NamespaceListResponse>({
+      command: "kubectl",
+      args: ["--context", options.context, "get", "namespaces", "-o", "json"],
+      timeoutMs: KUBECTL_TIMEOUT_MS,
+    });
+
+    return (parsed.items ?? [])
+      .map((item) => item.metadata?.name)
+      .filter((name): name is string => Boolean(name))
+      .map((name) => ({ name }));
+  }
+
+  async listResourceKinds(options: ListResourceKindsOptions): Promise<ResourceKind[]> {
+    const [result, helmAvailable] = await Promise.all([
+      runCommand({ command: "kubectl", args: ["--context", options.context, "api-resources", "--cached=false", "-o", "wide"], timeoutMs: KUBECTL_TIMEOUT_MS }),
+      this.isHelmAvailable(),
+    ]);
+
+    const lines = result.stdout
+      .split("\n")
+      .map((line) => line.trimEnd())
+      .filter(Boolean);
+
+    const dataLines = lines.slice(1);
+    const parsed = dataLines
+      .map((line): ApiResourcesLine | undefined => {
+        const columns = line.split(/\s{2,}/).map((part) => part.trim());
+        const [name, shortNamesText = "", groupText = "", namespacedText = "", kindText = ""] = columns;
+
+        if (columns.length < 5 || !name || !namespacedText || !kindText) {
+          return undefined;
+        }
+
+        return {
+          name,
+          shortNames: shortNamesText === "<none>" ? [] : shortNamesText.split(","),
+          group: groupText === "<none>" ? "" : groupText,
+          namespaced: namespacedText === "true",
+          kind: kindText,
+        };
+      })
+      .filter((value): value is ApiResourcesLine => value !== undefined)
+      .map((value) => ({
+        name: value.name,
+        namespaced: value.namespaced,
+        group: value.group || undefined,
+        shortNames: value.shortNames,
+      }));
+
+    const curated = curatedKinds(parsed);
+
+    if (helmAvailable) {
+      curated.push({ name: "helmreleases", namespaced: true, shortNames: ["hr"] });
+    }
+
+    return curated;
+  }
+
+  async listResources(options: ListResourcesOptions): Promise<ResourceListItem[]> {
+    if (options.resourceKind.name === "helmreleases") {
+      return this.listHelmReleases(options);
+    }
+
+    const isEvents = options.resourceKind.name === "events";
+
+    const args = ["--context", options.context, "get", options.resourceKind.name];
+
+    if (isEvents) {
+      // Always fetch all namespaces for events, sorted by time
+      args.push("-A");
+    } else if (options.resourceKind.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    args.push("-o", "json");
+
+    const parsed = await runJson<GenericListResponse>({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+
+    let items = parsed.items ?? [];
+
+    if (isEvents) {
+      items = items
+        .sort((a, b) => {
+          const aTime = a.lastTimestamp ?? a.firstTimestamp ?? a.metadata?.creationTimestamp ?? "";
+          const bTime = b.lastTimestamp ?? b.firstTimestamp ?? b.metadata?.creationTimestamp ?? "";
+          return bTime.localeCompare(aTime);
+        })
+        .slice(0, 200);
+    }
+
+    return items.map((item) => ({
+      ref: {
+        kind: item.kind ?? options.resourceKind.name,
+        name: item.metadata?.name ?? "unknown",
+        namespace: item.metadata?.namespace,
+      },
+      status: resourceStatus(item),
+      age: formatAge(item.lastTimestamp ?? item.firstTimestamp ?? item.metadata?.creationTimestamp),
+      summary: resourceSummary(item),
+    }));
+  }
+
+  async getResourceDetail(options: GetResourceDetailOptions): Promise<ResourceDetail> {
+    if (options.resourceKind.name === "helmreleases") {
+      return this.getHelmReleaseDetail(options);
+    }
+
+    const jsonArgs = ["--context", options.context, "get", options.resourceKind.name, options.name];
+    const yamlArgs = ["--context", options.context, "get", options.resourceKind.name, options.name];
+    const describeArgs = ["--context", options.context, "describe", options.resourceKind.name, options.name];
+
+    if (options.resourceKind.namespaced) {
+      jsonArgs.push("-n", options.namespace);
+      yamlArgs.push("-n", options.namespace);
+      describeArgs.push("-n", options.namespace);
+    }
+
+    jsonArgs.push("-o", "json");
+    yamlArgs.push("-o", "yaml");
+
+    const [resource, yaml, describe] = await Promise.all([
+      runJson<KubernetesResource>({ command: "kubectl", args: jsonArgs, timeoutMs: KUBECTL_TIMEOUT_MS }),
+      runText({ command: "kubectl", args: yamlArgs, timeoutMs: KUBECTL_TIMEOUT_MS }),
+      runText({ command: "kubectl", args: describeArgs, timeoutMs: KUBECTL_TIMEOUT_MS }).catch(() => ""),
+    ]);
+
+    return buildResourceDetail({ resourceKind: options.resourceKind, resource, yaml, describe });
+  }
+
+  async listResourceEvents(options: ListResourceEventsOptions): Promise<EventItem[]> {
+    const args = ["--context", options.context, "get", "events"];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    } else {
+      args.push("-A");
+    }
+
+    args.push("-o", "json");
+
+    const parsed = await runJson<EventListResponse>({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+    const targetKind = normalizeKind(options.resourceRef.kind);
+
+    return (parsed.items ?? [])
+      .filter((item) => {
+        const involved = item.involvedObject;
+
+        if (!involved?.name || !involved.kind) {
+          return false;
+        }
+
+        if (normalizeKind(involved.kind) !== targetKind) {
+          return false;
+        }
+
+        if (involved.name !== options.resourceRef.name) {
+          return false;
+        }
+
+        if (
+          options.resourceRef.namespace &&
+          involved.namespace &&
+          involved.namespace !== options.resourceRef.namespace
+        ) {
+          return false;
+        }
+
+        return true;
+      })
+      .sort((left, right) => {
+        const leftTime = left.lastTimestamp ?? left.firstTimestamp ?? left.metadata?.creationTimestamp ?? "";
+        const rightTime = right.lastTimestamp ?? right.firstTimestamp ?? right.metadata?.creationTimestamp ?? "";
+        return rightTime.localeCompare(leftTime);
+      })
+      .slice(0, 50)
+      .map((item) => ({
+        type: item.type ?? "Normal",
+        reason: item.reason ?? "Unknown",
+        message: item.message ?? "",
+        age: formatAge(item.lastTimestamp ?? item.firstTimestamp ?? item.metadata?.creationTimestamp),
+        source: item.reportingComponent ?? item.source?.component ?? item.source?.host ?? "cluster",
+      }));
+  }
+
+  streamLogs(options: StreamLogsOptions): StreamLogsResult {
+    const logTarget = normalizeLogTarget(options.resourceRef);
+
+    if (!logTarget) {
+      throw new Error(`Logs are not supported yet for ${options.resourceRef.kind}`);
+    }
+
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    const tail = options.logOptions?.tail ?? 120;
+    const since = options.logOptions?.since;
+    const previous = options.logOptions?.previous ?? false;
+
+    args.push("logs", logTarget.target, `--tail=${tail}`);
+
+    if (since) {
+      args.push(`--since=${since}`);
+    }
+
+    if (previous) {
+      args.push("--previous=true");
+    } else {
+      args.push("--follow=true");
+    }
+
+    if (logTarget.includeAllPods) {
+      args.push("--all-pods=true");
+    }
+
+    if (options.container) {
+      args.push(`--container=${options.container}`);
+    }
+
+    return {
+      target: logTarget.target,
+      child: startPersistentProcess({ command: "kubectl", args, stdio: ["ignore", "pipe", "pipe"] }),
+    };
+  }
+
+  async scaleResource(options: ScaleResourceOptions): Promise<void> {
+    if (!supportsScale(options.resourceRef)) {
+      throw new Error(`Scale is not supported yet for ${options.resourceRef.kind}`);
+    }
+
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    args.push("scale", normalizeResourceTarget(options.resourceRef), `--replicas=${options.replicas}`);
+
+    await runText({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+  }
+
+  async rolloutRestart(options: RolloutRestartOptions): Promise<void> {
+    if (!supportsRolloutRestart(options.resourceRef)) {
+      throw new Error(`Rollout restart is not supported yet for ${options.resourceRef.kind}`);
+    }
+
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    args.push("rollout", "restart", normalizeResourceTarget(options.resourceRef));
+
+    await runText({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+  }
+
+  async deleteResource(options: DeleteResourceOptions): Promise<void> {
+    if (normalizeKind(options.resourceRef.kind) === "helmreleases") {
+      return this.uninstallHelmRelease(options);
+    }
+
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    args.push("delete", normalizeResourceTarget(options.resourceRef));
+
+    await runText({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+  }
+
+  startShell(options: StartShellOptions): ChildProcess {
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    // pod/name is the canonical exec target; other workload kinds are also accepted by kubectl exec
+    const kind = normalizeKind(options.resourceRef.kind);
+    const target = kind === "pod" || kind === "pods" ? `pod/${options.resourceRef.name}` : normalizeResourceTarget(options.resourceRef);
+
+    // sh -lc lets $SHELL expand inside the child shell, not this process
+    args.push("exec", "-it", target, "--", "sh", "-lc", "exec ${SHELL:-/bin/sh}");
+
+    return startPersistentProcess({ command: "kubectl", args, stdio: "inherit" });
+  }
+
+  editResource(options: EditResourceOptions): ChildProcess {
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    args.push("edit", normalizeResourceTarget(options.resourceRef));
+
+    return startPersistentProcess({ command: "kubectl", args, stdio: "inherit" });
+  }
+
+  async helmUpgradeValues(options: HelmUpgradeValuesOptions): Promise<void> {
+    await runCommand({
+      command: "helm",
+      args: [
+        "upgrade",
+        options.name,
+        options.chart,
+        "--reuse-values",
+        "--values",
+        options.valuesFile,
+        "--kube-context",
+        options.context,
+        "-n",
+        options.namespace,
+      ],
+      timeoutMs: KUBECTL_TIMEOUT_MS,
+    });
+  }
+
+  async getPodMetrics(options: { context: string; namespace: string }): Promise<PodMetricsMap> {
+    try {
+      const raw = await runText({
+        command: "kubectl",
+        args: [
+          "--context", options.context,
+          "get", "--raw",
+          `/apis/metrics.k8s.io/v1beta1/namespaces/${options.namespace}/pods`,
+        ],
+        timeoutMs: KUBECTL_TIMEOUT_MS,
+      });
+      const parsed = JSON.parse(raw) as { items?: PodMetricsItem[] };
+      const result: PodMetricsMap = {};
+      for (const item of parsed.items ?? []) {
+        const name = item.metadata?.name;
+        if (!name) continue;
+        const cpuNano = item.containers?.reduce((acc, c) => acc + parseCpuNano(c.usage?.cpu ?? "0"), 0) ?? 0;
+        const memBytes = item.containers?.reduce((acc, c) => acc + parseMemBytes(c.usage?.memory ?? "0"), 0) ?? 0;
+        result[name] = { cpu: formatCpu(cpuNano), memory: formatMem(memBytes) };
+      }
+      return result;
+    } catch {
+      return {};
+    }
+  }
+
+  async getNodeMetrics(options: { context: string }): Promise<NodeMetricsMap> {
+    try {
+      const [metricsRaw, nodesRaw] = await Promise.all([
+        runText({ command: "kubectl", args: ["--context", options.context, "get", "--raw", "/apis/metrics.k8s.io/v1beta1/nodes"], timeoutMs: KUBECTL_TIMEOUT_MS }),
+        runText({ command: "kubectl", args: ["--context", options.context, "get", "nodes", "-o", "json"], timeoutMs: KUBECTL_TIMEOUT_MS }),
+      ]);
+      const metricsData = JSON.parse(metricsRaw) as { items?: NodeMetricsItem[] };
+      const nodesData = JSON.parse(nodesRaw) as { items?: Array<{ metadata?: { name?: string }; status?: { allocatable?: { cpu?: string; memory?: string } } }> };
+
+      const allocatable = new Map<string, { cpu: number; memory: number }>();
+      for (const node of nodesData.items ?? []) {
+        const name = node.metadata?.name;
+        if (!name) continue;
+        const cpu = parseCpuNano(node.status?.allocatable?.cpu ?? "0");
+        const mem = parseMemBytes(node.status?.allocatable?.memory ?? "0");
+        allocatable.set(name, { cpu, memory: mem });
+      }
+
+      const result: NodeMetricsMap = {};
+      for (const item of metricsData.items ?? []) {
+        const name = item.metadata?.name;
+        if (!name) continue;
+        const cpuNano = parseCpuNano(item.usage?.cpu ?? "0");
+        const memBytes = parseMemBytes(item.usage?.memory ?? "0");
+        const alloc = allocatable.get(name);
+        const cpuPct = alloc && alloc.cpu > 0 ? Math.round((cpuNano / alloc.cpu) * 100) : 0;
+        const memPct = alloc && alloc.memory > 0 ? Math.round((memBytes / alloc.memory) * 100) : 0;
+        result[name] = { cpu: formatCpu(cpuNano), memory: formatMem(memBytes), cpuPct, memPct };
+      }
+      return result;
+    } catch {
+      return {};
+    }
+  }
+
+  async helmRollback(options: HelmRollbackOptions): Promise<void> {
+    const args = [
+      "rollback",
+      options.name,
+      ...(options.revision !== undefined ? [String(options.revision)] : []),
+      "--kube-context", options.context,
+      "-n", options.namespace,
+    ];
+    await runCommand({ command: "helm", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+  }
+
+  helmUpgrade(options: HelmUpgradeOptions): ChildProcess {
+    const args = [
+      "upgrade",
+      options.name,
+      options.chart,
+      "--reuse-values",
+      "--kube-context", options.context,
+      "-n", options.namespace,
+    ];
+    return startPersistentProcess({ command: "helm", args, stdio: "inherit" });
+  }
+
+  startPortForward(options: StartPortForwardOptions): ChildProcess {
+    const target = normalizePortForwardTarget(options.resourceRef);
+
+    if (!target) {
+      throw new Error(`Port forward is not supported yet for ${options.resourceRef.kind}`);
+    }
+
+    const args = ["--context", options.context];
+
+    if (options.namespaced) {
+      args.push("-n", options.namespace);
+    }
+
+    args.push("port-forward", target, `${options.localPort}:${options.remotePort}`);
+
+    return startPersistentProcess({ command: "kubectl", args, stdio: ["ignore", "pipe", "pipe"] });
+  }
+
+  /** Returns true if kubectl scale is supported for the given resource kind. */
+  canScale(ref: ResourceRef): boolean {
+    return supportsScale(ref);
+  }
+
+  /** Returns true if kubectl rollout restart is supported for the given resource kind. */
+  canRolloutRestart(ref: ResourceRef): boolean {
+    return supportsRolloutRestart(ref);
+  }
+
+  /** Fetches and base64-decodes a single key from a Kubernetes Secret. */
+  async getSecretValue(options: GetSecretValueOptions): Promise<string> {
+    const args = ["--context", options.context, "-n", options.namespace, "get", "secret", options.name, "-o", "json"];
+    const parsed = await runJson<SecretResponse>({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+    const encoded = parsed.data?.[options.key];
+
+    if (!encoded) {
+      throw new Error(`Key "${options.key}" not found in secret "${options.name}"`);
+    }
+
+    return Buffer.from(encoded, "base64").toString("utf8");
+  }
+
+  /** Fetches and base64-decodes all keys from a Kubernetes Secret. */
+  async getAllSecretValues(options: GetAllSecretValuesOptions): Promise<Record<string, string>> {
+    const args = ["--context", options.context, "-n", options.namespace, "get", "secret", options.name, "-o", "json"];
+    const parsed = await runJson<SecretResponse>({ command: "kubectl", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+    const data = parsed.data ?? {};
+
+    return Object.fromEntries(
+      Object.entries(data).map(([key, encoded]) => [key, Buffer.from(encoded, "base64").toString("utf8")]),
+    );
+  }
+
+  private async listHelmReleases(options: ListResourcesOptions): Promise<ResourceListItem[]> {
+    const args = ["list", "--kube-context", options.context, "-n", options.namespace, "-o", "json"];
+    const result = await runCommand({ command: "helm", args, timeoutMs: KUBECTL_TIMEOUT_MS });
+    const items = JSON.parse(result.stdout) as HelmListItem[];
+
+    return items.map((item) => ({
+      ref: {
+        kind: "helmreleases",
+        name: item.name,
+        namespace: item.namespace,
+      },
+      status: item.status,
+      age: formatAge(item.updated),
+      summary: item.chart,
+    }));
+  }
+
+  private async getHelmReleaseDetail(options: GetResourceDetailOptions): Promise<ResourceDetail> {
+    const baseArgs = ["--kube-context", options.context, "-n", options.namespace];
+
+    const [statusResult, valuesResult] = await Promise.all([
+      runCommand({ command: "helm", args: ["status", options.name, ...baseArgs, "-o", "json"], timeoutMs: KUBECTL_TIMEOUT_MS }),
+      runCommand({ command: "helm", args: ["get", "values", options.name, ...baseArgs], timeoutMs: KUBECTL_TIMEOUT_MS }),
+    ]);
+
+    const status = JSON.parse(statusResult.stdout) as HelmStatusResponse;
+    const yaml = valuesResult.stdout;
+
+    const overviewLines: string[] = [
+      `name: ${status.name}`,
+      `namespace: ${status.namespace}`,
+      `chart: ${status.chart.metadata.name}`,
+      `chartVersion: ${status.chart.metadata.version}`,
+      ...(status.chart.metadata.appVersion ? [`appVersion: ${status.chart.metadata.appVersion}`] : []),
+      `revision: ${status.version}`,
+      `status: ${status.info.status}`,
+      `firstDeployed: ${status.info.first_deployed}`,
+      `lastDeployed: ${status.info.last_deployed}`,
+      ...(status.info.description ? [`description: ${status.info.description}`] : []),
+    ];
+
+    const notesLines =
+      status.info.notes
+        ?.split("\n")
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0) ?? [];
+
+    const summarySections = [
+      { title: "Overview", lines: overviewLines },
+      ...(notesLines.length > 0 ? [{ title: "Notes", lines: notesLines }] : []),
+    ];
+
+    const summaryLines = summarySections.flatMap((section) => [
+      section.title,
+      ...section.lines.map((line) => `  ${line}`),
+    ]);
+
+    return {
+      ref: {
+        kind: "helmreleases",
+        name: status.name,
+        namespace: status.namespace,
+      },
+      summaryLines,
+      summarySections,
+      yaml,
+      replicas: undefined,
+      portForwards: undefined,
+      helmChart: status.chart.metadata.name,
+    };
+  }
+
+  private async uninstallHelmRelease(options: DeleteResourceOptions): Promise<void> {
+    await runCommand({
+      command: "helm",
+      args: ["uninstall", options.resourceRef.name, "--kube-context", options.context, "-n", options.namespace],
+      timeoutMs: KUBECTL_TIMEOUT_MS,
+    });
+  }
+
+
+}
+
+export interface ListNamespacesOptions {
+  context: string;
+}
+
+export interface ListResourceKindsOptions {
+  context: string;
+}
+
+export interface ListResourcesOptions {
+  context: string;
+  namespace: string;
+  resourceKind: ResourceKind;
+}
+
+export interface GetResourceDetailOptions {
+  context: string;
+  namespace: string;
+  resourceKind: ResourceKind;
+  name: string;
+}
+
+export interface ListResourceEventsOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+}
+
+export interface EditResourceOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+}
+
+export interface HelmUpgradeValuesOptions {
+  context: string;
+  namespace: string;
+  name: string;
+  chart: string;
+  valuesFile: string;
+}
+
+export interface HelmRollbackOptions {
+  context: string;
+  namespace: string;
+  name: string;
+  revision?: number | undefined;
+}
+
+export interface HelmUpgradeOptions {
+  context: string;
+  namespace: string;
+  name: string;
+  chart: string;
+}
+
+export type PodMetricsMap = Record<string, { cpu: string; memory: string }>;
+export type NodeMetricsMap = Record<string, { cpu: string; memory: string; cpuPct: number; memPct: number }>;
+
+export interface StreamLogsOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+  container?: string | undefined;
+  logOptions?: LogOptions | undefined;
+}
+
+export interface StreamLogsResult {
+  target: string;
+  child: ChildProcess;
+}
+
+export interface ScaleResourceOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+  replicas: number;
+}
+
+export interface RolloutRestartOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+}
+
+export interface DeleteResourceOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+}
+
+export interface StartShellOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+}
+
+export interface StartPortForwardOptions {
+  context: string;
+  namespace: string;
+  resourceRef: ResourceRef;
+  namespaced: boolean;
+  localPort: number;
+  remotePort: number;
+}
+
+export interface GetSecretValueOptions {
+  context: string;
+  namespace: string;
+  name: string;
+  key: string;
+}
+
+export interface GetAllSecretValuesOptions {
+  context: string;
+  namespace: string;
+  name: string;
+}
+
+interface KubeConfigContextResponse {
+  contexts?: Array<{ name?: string | undefined }> | undefined;
+  "current-context"?: string | undefined;
+}
+
+interface NamespaceListResponse {
+  items?: Array<{ metadata?: { name?: string | undefined } | undefined }> | undefined;
+}
+
+interface ApiResourcesLine {
+  name: string;
+  shortNames: string[];
+  group: string;
+  namespaced: boolean;
+  kind: string;
+}
+
+interface GenericListResponse {
+  apiVersion?: string | undefined;
+  kind?: string | undefined;
+  items?: GenericListItem[] | undefined;
+}
+
+interface GenericListItem {
+  kind?: string | undefined;
+  metadata?: {
+    name?: string | undefined;
+    namespace?: string | undefined;
+    creationTimestamp?: string | undefined;
+  } | undefined;
+  spec?: Record<string, unknown> | undefined;
+  status?: Record<string, unknown> | undefined;
+  // Event-specific top-level fields
+  type?: string | undefined;
+  reason?: string | undefined;
+  message?: string | undefined;
+  lastTimestamp?: string | undefined;
+  firstTimestamp?: string | undefined;
+}
+
+interface EventListResponse {
+  items?: EventResponseItem[] | undefined;
+}
+
+interface SecretResponse {
+  data?: Record<string, string> | undefined;
+}
+
+interface EventResponseItem {
+  metadata?: {
+    creationTimestamp?: string | undefined;
+  } | undefined;
+  involvedObject?: {
+    kind?: string | undefined;
+    name?: string | undefined;
+    namespace?: string | undefined;
+  } | undefined;
+  reason?: string | undefined;
+  message?: string | undefined;
+  type?: string | undefined;
+  source?: {
+    component?: string | undefined;
+    host?: string | undefined;
+  } | undefined;
+  reportingComponent?: string | undefined;
+  firstTimestamp?: string | undefined;
+  lastTimestamp?: string | undefined;
+}
+
+interface HelmListItem {
+  name: string;
+  namespace: string;
+  revision: string;
+  updated: string;
+  status: string;
+  chart: string;
+  app_version: string;
+}
+
+interface HelmStatusResponse {
+  name: string;
+  namespace: string;
+  version: number;
+  info: {
+    first_deployed: string;
+    last_deployed: string;
+    status: string;
+    notes?: string | undefined;
+    description?: string | undefined;
+  };
+  chart: {
+    metadata: {
+      name: string;
+      version: string;
+      appVersion?: string | undefined;
+    };
+  };
+}
+
+interface PodMetricsItem {
+  metadata?: { name?: string };
+  containers?: Array<{ usage?: { cpu?: string; memory?: string } }>;
+}
+
+interface NodeMetricsItem {
+  metadata?: { name?: string };
+  usage?: { cpu?: string; memory?: string };
+}
+
+function parseCpuNano(value: string): number {
+  if (!value) return 0;
+  if (value.endsWith("n")) return Number.parseInt(value, 10);
+  if (value.endsWith("m")) return Number.parseInt(value, 10) * 1_000_000;
+  // plain integer = cores
+  const n = Number.parseFloat(value);
+  return Number.isFinite(n) ? n * 1_000_000_000 : 0;
+}
+
+function parseMemBytes(value: string): number {
+  if (!value) return 0;
+  const units: Record<string, number> = {
+    Ki: 1024, Mi: 1024 ** 2, Gi: 1024 ** 3, Ti: 1024 ** 4,
+    K: 1000, M: 1000 ** 2, G: 1000 ** 3, T: 1000 ** 4,
+  };
+  for (const [suffix, mult] of Object.entries(units)) {
+    if (value.endsWith(suffix)) {
+      return Number.parseFloat(value) * mult;
+    }
+  }
+  return Number.parseFloat(value) || 0;
+}
+
+function formatCpu(nano: number): string {
+  if (nano >= 1_000_000_000) return `${(nano / 1_000_000_000).toFixed(2)}`;
+  return `${Math.round(nano / 1_000_000)}m`;
+}
+
+function formatMem(bytes: number): string {
+  if (bytes >= 1024 ** 3) return `${(bytes / 1024 ** 3).toFixed(1)}Gi`;
+  if (bytes >= 1024 ** 2) return `${Math.round(bytes / 1024 ** 2)}Mi`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)}Ki`;
+  return `${bytes}B`;
+}
+
+function parseKubectlError(stderr: string, args: string[]): Error {
+  const message = stderr.trim() || `kubectl ${args.join(" ")} failed`;
+  return new Error(message);
+}
+
+function resourceStatus(resource: GenericListItem): string {
+  const kind = (resource.kind ?? "").toLowerCase();
+  const status = resource.status ?? {};
+  const spec = resource.spec ?? {};
+
+  // Events
+  if (kind === "event" || kind === "events") {
+    return resource.type ?? "Normal";
+  }
+
+  // HorizontalPodAutoscalers
+  if (kind === "horizontalpodautoscaler") {
+    const current = typeof status.currentReplicas === "number" ? status.currentReplicas : "-";
+    const max = typeof spec.maxReplicas === "number" ? spec.maxReplicas : "-";
+    return `${current}/${max} replicas`;
+  }
+
+  // CronJobs
+  if (kind === "cronjob") {
+    const active = Array.isArray(status.active) ? status.active : [];
+    return active.length > 0 ? "active" : "idle";
+  }
+
+  // Nodes: summarize conditions
+  if (kind === "node") {
+    const conditions = Array.isArray(status.conditions) ? (status.conditions as Record<string, unknown>[]) : [];
+    const ready = conditions.find((c) => c.type === "Ready");
+    const memPressure = conditions.find((c) => c.type === "MemoryPressure" && c.status === "True");
+    const diskPressure = conditions.find((c) => c.type === "DiskPressure" && c.status === "True");
+
+    if (memPressure) return "MemoryPressure";
+    if (diskPressure) return "DiskPressure";
+    return ready?.status === "True" ? "Ready" : "NotReady";
+  }
+
+  // RBAC subjects count
+  if (kind === "rolebinding" || kind === "clusterrolebinding") {
+    const subjects = Array.isArray((resource as unknown as Record<string, unknown>).subjects)
+      ? ((resource as unknown as Record<string, unknown>).subjects as unknown[])
+      : [];
+    return `${subjects.length} subjects`;
+  }
+
+  if (typeof status.phase === "string") {
+    return status.phase;
+  }
+
+  if (typeof status.readyReplicas === "number" && typeof spec.replicas === "number") {
+    return `${status.readyReplicas}/${spec.replicas} ready`;
+  }
+
+  if (typeof status.availableReplicas === "number" && typeof spec.replicas === "number") {
+    return `${status.availableReplicas}/${spec.replicas} available`;
+  }
+
+  if (typeof status.capacity === "object") {
+    return "capacity";
+  }
+
+  return "-";
+}
+
+function resourceSummary(resource: GenericListItem): string {
+  const kind = (resource.kind ?? "").toLowerCase();
+  const spec = resource.spec ?? {};
+  const status = resource.status ?? {};
+
+  // Events
+  if (kind === "event" || kind === "events") {
+    const reason = resource.reason ?? "";
+    const message = (resource.message ?? "").slice(0, 60);
+    return reason ? `${reason}: ${message}` : message;
+  }
+
+  // HorizontalPodAutoscalers
+  if (kind === "horizontalpodautoscaler") {
+    const min = spec.minReplicas ?? "-";
+    const max = spec.maxReplicas ?? "-";
+    const ref = (spec.scaleTargetRef as Record<string, unknown> | undefined)?.name ?? "-";
+    return `min:${min} max:${max} ref:${ref}`;
+  }
+
+  // CronJobs
+  if (kind === "cronjob") {
+    const schedule = typeof spec.schedule === "string" ? spec.schedule : "-";
+    const lastRun = typeof status.lastScheduleTime === "string" ? formatAge(status.lastScheduleTime) : "-";
+    return `${schedule}  last: ${lastRun}`;
+  }
+
+  // Nodes
+  if (kind === "node") {
+    const nodeInfo = (status.nodeInfo ?? {}) as Record<string, unknown>;
+    const kubeletVersion = typeof nodeInfo.kubeletVersion === "string" ? nodeInfo.kubeletVersion : "";
+    const labels = (resource as unknown as { metadata?: { labels?: Record<string, string> } }).metadata?.labels ?? {};
+    const roles = Object.keys(labels)
+      .filter((k) => k.startsWith("node-role.kubernetes.io/"))
+      .map((k) => k.replace("node-role.kubernetes.io/", ""))
+      .join(",") || "worker";
+    return kubeletVersion ? `${kubeletVersion}  roles: ${roles}` : `roles: ${roles}`;
+  }
+
+  // Roles/ClusterRoles: show rule count
+  if (kind === "role" || kind === "clusterrole") {
+    const rules = (resource as unknown as { rules?: unknown[] }).rules ?? [];
+    return `${rules.length} rules`;
+  }
+
+  // RoleBindings/ClusterRoleBindings: show roleRef
+  if (kind === "rolebinding" || kind === "clusterrolebinding") {
+    const roleRef = (resource as unknown as { roleRef?: Record<string, unknown> }).roleRef;
+    if (roleRef) {
+      return `\u2192 ${roleRef.kind ?? ""}/${roleRef.name ?? ""}`;
+    }
+    return "";
+  }
+
+  if (typeof spec.clusterIP === "string") {
+    return `clusterIP ${spec.clusterIP}`;
+  }
+
+  if (typeof spec.nodeName === "string") {
+    return `node ${spec.nodeName}`;
+  }
+
+  if (typeof status.hostIP === "string") {
+    return `host ${status.hostIP}`;
+  }
+
+  if (typeof status.podIP === "string") {
+    return `podIP ${status.podIP}`;
+  }
+
+  return "";
+}
+
+function curatedKinds(kinds: ResourceKind[]): ResourceKind[] {
+  const preferredOrder = [
+    "pods",
+    "deployments",
+    "statefulsets",
+    "daemonsets",
+    "services",
+    "ingresses",
+    "jobs",
+    "cronjobs",
+    "horizontalpodautoscalers",
+    "configmaps",
+    "secrets",
+    "nodes",
+    "namespaces",
+    "events",
+    "persistentvolumeclaims",
+    "persistentvolumes",
+    "serviceaccounts",
+    "roles",
+    "clusterroles",
+    "rolebindings",
+    "clusterrolebindings",
+    "networkpolicies",
+    "poddisruptionbudgets",
+  ];
+
+  const kindMap = new Map(kinds.map((kind) => [kind.name, kind]));
+  const curated = preferredOrder
+    .map((name) => kindMap.get(name))
+    .filter((kind): kind is ResourceKind => kind !== undefined);
+
+  if (curated.length > 0) {
+    return curated;
+  }
+
+  return kinds.slice(0, 20);
+}
+
+function normalizeKind(kind: string): string {
+  return kind.trim().toLowerCase();
+}
+
+function normalizeLogTarget(ref: ResourceRef): { target: string; includeAllPods: boolean } | undefined {
+  const kind = normalizeKind(ref.kind);
+
+  if (kind === "pod" || kind === "pods") {
+    return { target: `pod/${ref.name}`, includeAllPods: false };
+  }
+
+  if (kind === "deployment" || kind === "deployments") {
+    return { target: `deployment/${ref.name}`, includeAllPods: true };
+  }
+
+  if (kind === "job" || kind === "jobs") {
+    return { target: `job/${ref.name}`, includeAllPods: true };
+  }
+
+  if (kind === "replicaset" || kind === "replicasets") {
+    return { target: `replicaset/${ref.name}`, includeAllPods: true };
+  }
+
+  if (kind === "statefulset" || kind === "statefulsets") {
+    return { target: `statefulset/${ref.name}`, includeAllPods: true };
+  }
+
+  if (kind === "daemonset" || kind === "daemonsets") {
+    return { target: `daemonset/${ref.name}`, includeAllPods: true };
+  }
+
+  return undefined;
+}
+
+function normalizeResourceTarget(ref: ResourceRef): string {
+  const kind = normalizeKind(ref.kind);
+  return `${kind}/${ref.name}`;
+}
+
+function normalizePortForwardTarget(ref: ResourceRef): string | undefined {
+  const kind = normalizeKind(ref.kind);
+
+  if (kind === "pod" || kind === "pods") {
+    return `pod/${ref.name}`;
+  }
+
+  if (kind === "service" || kind === "services") {
+    return `service/${ref.name}`;
+  }
+
+  if (kind === "deployment" || kind === "deployments") {
+    return `deployment/${ref.name}`;
+  }
+
+  if (kind === "replicaset" || kind === "replicasets") {
+    return `replicaset/${ref.name}`;
+  }
+
+  if (kind === "statefulset" || kind === "statefulsets") {
+    return `statefulset/${ref.name}`;
+  }
+
+  return undefined;
+}
+
+function supportsRolloutRestart(ref: ResourceRef): boolean {
+  const kind = normalizeKind(ref.kind);
+  return ["deployment", "deployments", "statefulset", "statefulsets", "daemonset", "daemonsets"].includes(kind);
+}
+
+function supportsScale(ref: ResourceRef): boolean {
+  const kind = normalizeKind(ref.kind);
+  return ["deployment", "deployments", "statefulset", "statefulsets", "replicaset", "replicasets"].includes(kind);
+}