kubernetes-fluent-client 3.11.11 → 3.12.0

package/README.md

@@ -13,6 +13,59 @@ To install the Kubernetes Fluent Client, run the following command:
 npm install kubernetes-fluent-client
 ```
 
+### Kubernetes integration testing
+
+Runner-neutral helpers for polling, preflight checks, diagnostics, ownership-aware apply, and
+label-scoped cleanup are available from the test-only entry point. The ownership helpers stamp and
+delete through the same exact labels, preventing one suite from cleaning up another suite's
+resources.
+
+```typescript
+import { kind, K8s } from "kubernetes-fluent-client";
+import {
+  applyWithOwnership,
+  deleteAllByOwnership,
+  preflight,
+  waitFor,
+} from "kubernetes-fluent-client/test";
+
+const ownership = { owner: "example-suite" };
+
+// Fail before the suite starts when the active Kubernetes context is unusable.
+await preflight();
+
+// Apply resources with labels that can be targeted safely during cleanup.
+await applyWithOwnership(
+  kind.ConfigMap,
+  { metadata: { name: "example", namespace: "testing" } },
+  ownership,
+);
+
+// Poll with a bounded deadline and Kubernetes-aware error handling.
+await waitFor("example ConfigMap", () => K8s(kind.ConfigMap).InNamespace("testing").Get("example"));
+
+// Delete only ConfigMaps carrying this suite's exact ownership labels.
+await deleteAllByOwnership(kind.ConfigMap, { ...ownership, namespace: "testing" });
+```
+
+Vitest projects can also share the integration-test configuration and register preflight as a
+suite hook. Vitest is an optional peer dependency and is only required when this entry point is
+used.
+
+```typescript
+// vitest.config.ts
+import { defineKubernetesTestConfig } from "kubernetes-fluent-client/test/vitest";
+
+export default defineKubernetesTestConfig();
+```
+
+```typescript
+// example.test.ts
+import { setupKubernetesPreflight } from "kubernetes-fluent-client/test/vitest/setup";
+
+setupKubernetesPreflight();
+```
+
 See below for some example uses of the library.
 
 ```typescript

package/dist/test/diagnostics.d.ts

@@ -0,0 +1,36 @@
+/** A named, independently executed diagnostics operation. */
+export interface DiagnosticCollector<TContext = void, TValue = unknown> {
+    /** Stable name identifying the diagnostic in the report. */
+    name: string;
+    /** Collect a diagnostic value without writing output. */
+    collect: (context: TContext) => TValue | Promise<TValue>;
+}
+/** Result from one diagnostics collector. */
+export type DiagnosticEntry = {
+    name: string;
+    value: unknown;
+    error?: never;
+} | {
+    name: string;
+    value?: never;
+    error: unknown;
+};
+/** Ordered, runner-neutral diagnostics report. */
+export interface DiagnosticReport {
+    /** ISO timestamp recorded immediately before collectors run. */
+    collectedAt: string;
+    /** One entry for every requested collector, in input order. */
+    entries: DiagnosticEntry[];
+}
+/**
+ * Run diagnostics collectors independently and return structured results.
+ *
+ * A failed collector is represented in its entry and does not prevent the
+ * remaining collectors from running. This function never prints or writes files.
+ *
+ * @param context - Value shared with every collector.
+ * @param collectors - Diagnostics operations to run.
+ * @returns A structured report suitable for any test runner or artifact format.
+ */
+export declare function collectDiagnostics<TContext>(context: TContext, collectors: readonly DiagnosticCollector<TContext>[]): Promise<DiagnosticReport>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/test/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/test/diagnostics.ts"],"names":[],"mappings":"AAGA,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB,CAAC,QAAQ,GAAG,IAAI,EAAE,MAAM,GAAG,OAAO;IACpE,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,OAAO,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1D;AAED,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GACzB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpG,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAC/C,OAAO,EAAE,QAAQ,EACjB,UAAU,EAAE,SAAS,mBAAmB,CAAC,QAAQ,CAAC,EAAE,GACnD,OAAO,CAAC,gBAAgB,CAAC,CAa3B"}

package/dist/test/diagnostics.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026-Present The Kubernetes Fluent Client Authors
+/**
+ * Run diagnostics collectors independently and return structured results.
+ *
+ * A failed collector is represented in its entry and does not prevent the
+ * remaining collectors from running. This function never prints or writes files.
+ *
+ * @param context - Value shared with every collector.
+ * @param collectors - Diagnostics operations to run.
+ * @returns A structured report suitable for any test runner or artifact format.
+ */
+export async function collectDiagnostics(context, collectors) {
+    const collectedAt = new Date().toISOString();
+    const entries = await Promise.all(collectors.map(async ({ name, collect }) => {
+        try {
+            return { name, value: await collect(context) };
+        }
+        catch (error) {
+            return { name, error };
+        }
+    }));
+    return { collectedAt, entries };
+}

package/dist/test/environment.d.ts

@@ -0,0 +1,28 @@
+/** Environment variable used to override the default waiter timeout. */
+export declare const TEST_TIMEOUT_ENV = "KFC_TEST_TIMEOUT_MS";
+/** Environment variable used to override the default polling interval. */
+export declare const TEST_INTERVAL_ENV = "KFC_TEST_POLL_INTERVAL_MS";
+/** Default waiter timeout used by KFC integration tests. */
+export declare const DEFAULT_TEST_TIMEOUT_MS = 60000;
+/** Default polling interval used by KFC integration tests. */
+export declare const DEFAULT_TEST_INTERVAL_MS = 2000;
+/** Timing configuration shared by integration test helpers. */
+export interface KubernetesTestEnvironment {
+    /** Maximum time to wait for an eventually consistent condition. */
+    timeoutMs: number;
+    /** Delay between attempts. */
+    intervalMs: number;
+}
+/** Optional timing overrides for {@link env}. */
+export type KubernetesTestEnvironmentOverrides = Partial<KubernetesTestEnvironment>;
+/**
+ * Resolve integration-test timing from explicit overrides, environment variables, and defaults.
+ *
+ * Explicit values take precedence over `KFC_TEST_TIMEOUT_MS` and
+ * `KFC_TEST_POLL_INTERVAL_MS`. Values must be positive whole milliseconds.
+ *
+ * @param overrides - Per-call timing values.
+ * @returns Resolved waiter timing.
+ */
+export declare function env(overrides?: KubernetesTestEnvironmentOverrides): KubernetesTestEnvironment;
+//# sourceMappingURL=environment.d.ts.map

package/dist/test/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/test/environment.ts"],"names":[],"mappings":"AAGA,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,0EAA0E;AAC1E,eAAO,MAAM,iBAAiB,8BAA8B,CAAC;AAE7D,4DAA4D;AAC5D,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,+DAA+D;AAC/D,MAAM,WAAW,yBAAyB;IACxC,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,iDAAiD;AACjD,MAAM,MAAM,kCAAkC,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;AA+BpF;;;;;;;;GAQG;AACH,wBAAgB,GAAG,CAAC,SAAS,GAAE,kCAAuC,GAAG,yBAAyB,CAWjG"}

package/dist/test/environment.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026-Present The Kubernetes Fluent Client Authors
+/** Environment variable used to override the default waiter timeout. */
+export const TEST_TIMEOUT_ENV = "KFC_TEST_TIMEOUT_MS";
+/** Environment variable used to override the default polling interval. */
+export const TEST_INTERVAL_ENV = "KFC_TEST_POLL_INTERVAL_MS";
+/** Default waiter timeout used by KFC integration tests. */
+export const DEFAULT_TEST_TIMEOUT_MS = 60_000;
+/** Default polling interval used by KFC integration tests. */
+export const DEFAULT_TEST_INTERVAL_MS = 2_000;
+/**
+ * Parse and validate a millisecond value.
+ *
+ * @param name - Setting name used in validation errors.
+ * @param value - Candidate millisecond value.
+ * @returns The validated positive integer.
+ */
+function positiveInteger(name, value) {
+    const parsed = typeof value === "number" ? value : Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new Error(`${name} must be a positive integer; received ${String(value)}`);
+    }
+    return parsed;
+}
+/**
+ * Read an optional timing setting from the process environment.
+ *
+ * @param name - Environment variable name.
+ * @param fallback - Value returned when the variable is unset or empty.
+ * @returns The configured or fallback millisecond value.
+ */
+function environmentValue(name, fallback) {
+    const value = process.env[name]?.trim();
+    return value ? positiveInteger(name, value) : fallback;
+}
+/**
+ * Resolve integration-test timing from explicit overrides, environment variables, and defaults.
+ *
+ * Explicit values take precedence over `KFC_TEST_TIMEOUT_MS` and
+ * `KFC_TEST_POLL_INTERVAL_MS`. Values must be positive whole milliseconds.
+ *
+ * @param overrides - Per-call timing values.
+ * @returns Resolved waiter timing.
+ */
+export function env(overrides = {}) {
+    return {
+        timeoutMs: positiveInteger("timeoutMs", overrides.timeoutMs ?? environmentValue(TEST_TIMEOUT_ENV, DEFAULT_TEST_TIMEOUT_MS)),
+        intervalMs: positiveInteger("intervalMs", overrides.intervalMs ?? environmentValue(TEST_INTERVAL_ENV, DEFAULT_TEST_INTERVAL_MS)),
+    };
+}

package/dist/test/index.d.ts

@@ -0,0 +1,6 @@
+export { collectDiagnostics, type DiagnosticCollector, type DiagnosticEntry, type DiagnosticReport, } from "./diagnostics.js";
+export { DEFAULT_TEST_INTERVAL_MS, DEFAULT_TEST_TIMEOUT_MS, TEST_INTERVAL_ENV, TEST_TIMEOUT_ENV, env, type KubernetesTestEnvironment, type KubernetesTestEnvironmentOverrides, } from "./environment.js";
+export { preflight, type PreflightOptions, type PreflightResult } from "./preflight.js";
+export { TEST_OWNERSHIP_LABEL, TEST_RUN_ID_LABEL, applyWithOwnership, deleteAllByOwnership, ownershipLabels, waitForResource, type ApplyWithOwnershipOptions, type DeleteAllByOwnershipOptions, type OwnershipLabels, type OwnershipOptions, type ResourceReference, type WaitForResourceOptions, } from "./resources.js";
+export { WaitForTimeoutError, waitFor, type ErrorClassifier, type ErrorDisposition, type WaitForOptions, type WaitForTimeoutDetails, } from "./wait.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/test/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,kBAAkB,EAClB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,gBAAgB,EAChB,GAAG,EACH,KAAK,yBAAyB,EAC9B,KAAK,kCAAkC,GACxC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxF,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,eAAe,EACf,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,mBAAmB,EACnB,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,qBAAqB,GAC3B,MAAM,WAAW,CAAC"}

package/dist/test/index.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026-Present The Kubernetes Fluent Client Authors
+export { collectDiagnostics, } from "./diagnostics.js";
+export { DEFAULT_TEST_INTERVAL_MS, DEFAULT_TEST_TIMEOUT_MS, TEST_INTERVAL_ENV, TEST_TIMEOUT_ENV, env, } from "./environment.js";
+export { preflight } from "./preflight.js";
+export { TEST_OWNERSHIP_LABEL, TEST_RUN_ID_LABEL, applyWithOwnership, deleteAllByOwnership, ownershipLabels, waitForResource, } from "./resources.js";
+export { WaitForTimeoutError, waitFor, } from "./wait.js";

package/dist/test/preflight.d.ts

@@ -0,0 +1,29 @@
+import { KubeConfig } from "@kubernetes/client-node";
+import { type WaitForOptions } from "./wait.js";
+/** Options accepted by {@link preflight}. */
+export interface PreflightOptions extends Pick<WaitForOptions, "timeoutMs" | "intervalMs" | "signal"> {
+    /** An already configured client, primarily for callers with non-default kubeconfig loading. */
+    kubeConfig?: KubeConfig;
+}
+/** Successfully verified Kubernetes connection details. */
+export interface PreflightResult {
+    /** Name of the active kubeconfig context. */
+    contextName: string;
+    /** Name of the cluster selected by that context. */
+    clusterName: string;
+    /** Kubernetes API server URL. */
+    server: string;
+    /** Version reported by the authenticated API server. */
+    gitVersion: string;
+}
+/**
+ * Verify kubeconfig selection and authenticated Kubernetes API connectivity.
+ *
+ * This intentionally calls the non-privileged `/version` endpoint rather than
+ * probing a namespaced resource, so it does not impose additional RBAC needs.
+ *
+ * @param options - Kubeconfig, timing, and cancellation overrides.
+ * @returns The selected context, cluster, server, and Kubernetes version.
+ */
+export declare function preflight(options?: PreflightOptions): Promise<PreflightResult>;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/test/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/test/preflight.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAc,MAAM,yBAAyB,CAAC;AAEjE,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD,6CAA6C;AAC7C,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAC5C,cAAc,EACd,WAAW,GAAG,YAAY,GAAG,QAAQ,CACtC;IACC,+FAA+F;IAC/F,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB;AAeD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAqBxF"}

package/dist/test/preflight.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026-Present The Kubernetes Fluent Client Authors
+import { KubeConfig, VersionApi } from "@kubernetes/client-node";
+import { waitFor } from "./wait.js";
+/**
+ * Use a supplied kubeconfig or load the process default.
+ *
+ * @param kubeConfig - Optional caller-configured Kubernetes client.
+ * @returns The client used by preflight checks.
+ */
+function loadKubeConfig(kubeConfig) {
+    if (kubeConfig)
+        return kubeConfig;
+    const loaded = new KubeConfig();
+    loaded.loadFromDefault();
+    return loaded;
+}
+/**
+ * Verify kubeconfig selection and authenticated Kubernetes API connectivity.
+ *
+ * This intentionally calls the non-privileged `/version` endpoint rather than
+ * probing a namespaced resource, so it does not impose additional RBAC needs.
+ *
+ * @param options - Kubeconfig, timing, and cancellation overrides.
+ * @returns The selected context, cluster, server, and Kubernetes version.
+ */
+export async function preflight(options = {}) {
+    const kubeConfig = loadKubeConfig(options.kubeConfig);
+    const contextName = kubeConfig.getCurrentContext();
+    const cluster = kubeConfig.getCurrentCluster();
+    if (!contextName)
+        throw new Error("Kubernetes preflight failed: no current context is selected");
+    if (!cluster)
+        throw new Error("Kubernetes preflight failed: the current context has no cluster");
+    const versionApi = kubeConfig.makeApiClient(VersionApi);
+    const version = await waitFor(`Kubernetes API server ${cluster.server}`, () => versionApi.getCode(), options);
+    return {
+        contextName,
+        clusterName: cluster.name,
+        server: cluster.server,
+        gitVersion: version.gitVersion,
+    };
+}

package/dist/test/resources.d.ts

@@ -0,0 +1,90 @@
+import type { KubernetesObject } from "@kubernetes/client-node";
+import type { PartialDeep } from "../fluent/types.js";
+import type { GenericClass } from "../types.js";
+import { type WaitForOptions } from "./wait.js";
+/** Default label used to identify resources created by integration tests. */
+export declare const TEST_OWNERSHIP_LABEL = "test.defenseunicorns.dev/source";
+/** Default label used to isolate one execution of an integration test suite. */
+export declare const TEST_RUN_ID_LABEL = "test.defenseunicorns.dev/run-id";
+/** Label identity shared by apply and cleanup operations. */
+export interface OwnershipOptions {
+    /** Stable value identifying the test suite that owns the resource. */
+    owner: string;
+    /** Optional value isolating one execution of the test suite. */
+    runId?: string;
+    /** Label key override for repositories with an existing convention. */
+    labelKey?: string;
+    /** Run-ID label key override for repositories with an existing convention. */
+    runIdLabelKey?: string;
+}
+/** Resolved Kubernetes ownership labels. */
+export interface OwnershipLabels {
+    /** Kubernetes metadata label key-value pairs. */
+    [key: string]: string;
+}
+/** Options accepted by {@link applyWithOwnership}. */
+export interface ApplyWithOwnershipOptions extends OwnershipOptions {
+    /** Forwarded to KFC server-side apply. */
+    force?: boolean;
+}
+/** Options accepted by {@link deleteAllByOwnership}. */
+export interface DeleteAllByOwnershipOptions extends OwnershipOptions, Pick<WaitForOptions, "timeoutMs" | "intervalMs" | "signal"> {
+    /** Restrict discovery and deletion to one namespace. */
+    namespace?: string;
+    /** Wait until no resources carry the exact ownership labels. */
+    waitForDeletion?: boolean;
+}
+/** Name and optional namespace identifying one Kubernetes resource. */
+export interface ResourceReference {
+    /** Resource name. */
+    name: string;
+    /** Namespace for namespaced resources; omit for cluster-scoped resources. */
+    namespace?: string;
+}
+/** Options accepted by {@link waitForResource}. */
+export interface WaitForResourceOptions<TDiagnostics = unknown> extends ResourceReference, WaitForOptions<TDiagnostics> {
+    /** Override the human-readable timeout description. */
+    description?: string;
+}
+/**
+ * Resolve and validate the exact labels used by ownership-aware helpers.
+ *
+ * Run IDs use a separate label so owner and execution identities cannot
+ * produce ambiguous composite values.
+ *
+ * @param options - Stable owner, optional run ID, and optional label key.
+ * @returns Validated Kubernetes label key-value pairs.
+ */
+export declare function ownershipLabels(options: OwnershipOptions): OwnershipLabels;
+/**
+ * Apply a resource after stamping a stable ownership label.
+ *
+ * The input object is not mutated. Any existing labels are preserved unless
+ * they use a selected ownership key.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param resource - Resource body to server-side apply.
+ * @param options - Ownership labels and apply configuration.
+ * @returns The resource returned by Kubernetes.
+ */
+export declare function applyWithOwnership<T extends GenericClass, K extends KubernetesObject = InstanceType<T>>(model: T, resource: PartialDeep<K>, options: ApplyWithOwnershipOptions): Promise<K>;
+/**
+ * Delete every resource carrying the exact ownership labels.
+ *
+ * Kubernetes evaluates the exact label selectors when collection deletion is
+ * supported. Other APIs use UID and resource-version preconditions so a
+ * re-labeled or re-created resource cannot be deleted after discovery.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param options - Ownership identity and optional namespace restriction.
+ */
+export declare function deleteAllByOwnership<T extends GenericClass, K extends KubernetesObject = InstanceType<T>>(model: T, options: DeleteAllByOwnershipOptions): Promise<void>;
+/**
+ * Wait for one named Kubernetes resource to exist.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param options - Resource identity plus standard waiter options.
+ * @returns The resource read from Kubernetes.
+ */
+export declare function waitForResource<T extends GenericClass, K extends KubernetesObject = InstanceType<T>, TDiagnostics = unknown>(model: T, options: WaitForResourceOptions<TDiagnostics>): Promise<K>;
+//# sourceMappingURL=resources.d.ts.map

package/dist/test/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/test/resources.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAW,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAEzD,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,oCAAoC,CAAC;AAEtE,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,oCAAoC,CAAC;AAEnE,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,sDAAsD;AACtD,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,0CAA0C;IAC1C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wDAAwD;AACxD,MAAM,WAAW,2BACf,SAAQ,gBAAgB,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,GAAG,YAAY,GAAG,QAAQ,CAAC;IACrF,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB,CAAC,YAAY,GAAG,OAAO,CAC5D,SAAQ,iBAAiB,EAAE,cAAc,CAAC,YAAY,CAAC;IACvD,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAoB1E;AAuJD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,gBAAgB,GAAG,YAAY,CAAC,CAAC,CAAC,EAC5C,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,CAAC,CAAC,CAcpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,gBAAgB,GAAG,YAAY,CAAC,CAAC,CAAC,EAC5C,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC,CAoB/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,YAAY,EACtB,CAAC,SAAS,gBAAgB,GAAG,YAAY,CAAC,CAAC,CAAC,EAC5C,YAAY,GAAG,OAAO,EACtB,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,sBAAsB,CAAC,YAAY,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CASrE"}

package/dist/test/resources.js

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026-Present The Kubernetes Fluent Client Authors
+import { K8s } from "../fluent/index.js";
+import { FetchMethods } from "../fluent/shared-types.js";
+import { k8sExec } from "../fluent/utils.js";
+import { waitFor } from "./wait.js";
+/** Default label used to identify resources created by integration tests. */
+export const TEST_OWNERSHIP_LABEL = "test.defenseunicorns.dev/source";
+/** Default label used to isolate one execution of an integration test suite. */
+export const TEST_RUN_ID_LABEL = "test.defenseunicorns.dev/run-id";
+const LABEL_NAME_PATTERN = /^[A-Za-z0-9](?:[-_.A-Za-z0-9]{0,61}[A-Za-z0-9])?$/;
+const DNS_LABEL_PATTERN = /^[a-z0-9](?:[-a-z0-9]{0,61}[a-z0-9])?$/;
+/**
+ * Determine whether a string is a valid Kubernetes label name.
+ *
+ * @param value - Label name or label value to inspect.
+ * @returns True when the value follows Kubernetes label-name syntax.
+ */
+function isLabelName(value) {
+    return value.length <= 63 && LABEL_NAME_PATTERN.test(value);
+}
+/**
+ * Determine whether a string is a valid optional DNS label-key prefix.
+ *
+ * @param value - DNS prefix to inspect.
+ * @returns True when every segment follows Kubernetes DNS syntax.
+ */
+function isDnsPrefix(value) {
+    return value.length <= 253 && value.split(".").every(segment => DNS_LABEL_PATTERN.test(segment));
+}
+/**
+ * Determine whether a string is a valid Kubernetes label key.
+ *
+ * @param value - Label key to inspect.
+ * @returns True when the key has a valid optional prefix and name.
+ */
+function isLabelKey(value) {
+    const parts = value.split("/");
+    if (parts.length === 1)
+        return isLabelName(parts[0]);
+    if (parts.length !== 2)
+        return false;
+    return isDnsPrefix(parts[0]) && isLabelName(parts[1]);
+}
+/**
+ * Resolve and validate the exact labels used by ownership-aware helpers.
+ *
+ * Run IDs use a separate label so owner and execution identities cannot
+ * produce ambiguous composite values.
+ *
+ * @param options - Stable owner, optional run ID, and optional label key.
+ * @returns Validated Kubernetes label key-value pairs.
+ */
+export function ownershipLabels(options) {
+    const key = options.labelKey ?? TEST_OWNERSHIP_LABEL;
+    if (!isLabelKey(key))
+        throw new Error(`Invalid Kubernetes ownership label key: ${key}`);
+    if (!isLabelName(options.owner)) {
+        throw new Error(`Invalid Kubernetes ownership label value: ${options.owner}`);
+    }
+    const labels = { [key]: options.owner };
+    if (options.runId !== undefined) {
+        const runIdKey = options.runIdLabelKey ?? TEST_RUN_ID_LABEL;
+        if (!isLabelKey(runIdKey)) {
+            throw new Error(`Invalid Kubernetes run-ID label key: ${runIdKey}`);
+        }
+        if (runIdKey === key)
+            throw new Error("Ownership and run-ID label keys must be different");
+        if (!isLabelName(options.runId)) {
+            throw new Error(`Invalid Kubernetes run-ID label value: ${options.runId}`);
+        }
+        labels[runIdKey] = options.runId;
+    }
+    return labels;
+}
+/**
+ * Create a fluent client with an optional namespace filter.
+ *
+ * @param model - KFC model for the resource kind.
+ * @param namespace - Optional namespace for namespaced resources.
+ * @returns A fluent resource client.
+ */
+function resourceClient(model, namespace) {
+    const client = K8s(model);
+    return namespace ? client.InNamespace(namespace) : client;
+}
+/**
+ * Create a fluent client filtered by every ownership label.
+ *
+ * @param model - KFC model for the resource kind.
+ * @param options - Ownership identity and optional namespace.
+ * @returns A fluent resource client with exact label selectors.
+ */
+function ownedResourceClient(model, options) {
+    let client = resourceClient(model, options.namespace);
+    for (const [key, value] of Object.entries(ownershipLabels(options))) {
+        client = client.WithLabel(key, value);
+    }
+    return client;
+}
+/**
+ * Validate a resource reference before it can affect a Kubernetes request path.
+ *
+ * @param reference - Resource name and optional namespace.
+ */
+function validateResourceReference(reference) {
+    if (!reference.name.trim())
+        throw new Error("Resource name must not be blank");
+    if (reference.namespace !== undefined && !reference.namespace.trim()) {
+        throw new Error("Resource namespace must not be blank when provided");
+    }
+}
+/**
+ * Determine whether an error carries one HTTP status.
+ *
+ * @param error - Error raised by a Kubernetes request.
+ * @param status - HTTP status to match.
+ * @returns True when the error has the requested status.
+ */
+function hasStatus(error, status) {
+    return (typeof error === "object" && error !== null && "status" in error && error.status === status);
+}
+/**
+ * Read the metadata required for a preconditioned deletion.
+ *
+ * @param model - KFC model for the resource kind.
+ * @param resource - Resource returned by an exact-label list operation.
+ * @returns The resource identity and version used by the delete request.
+ */
+function deletionIdentity(model, resource) {
+    const { name, namespace, resourceVersion, uid } = resource.metadata ?? {};
+    if (!name || !uid || !resourceVersion) {
+        throw new Error(`Cannot safely delete owned ${model.name}: metadata.name, uid, and resourceVersion are required`);
+    }
+    return { name, namespace, resourceVersion, uid };
+}
+/**
+ * Delete one listed resource only if its identity and version have not changed.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param resource - Resource returned by an exact-label list operation.
+ * @param namespace - Optional namespace restriction supplied by the caller.
+ */
+async function deleteWithPreconditions(model, resource, namespace) {
+    const identity = deletionIdentity(model, resource);
+    try {
+        await k8sExec(model, { name: identity.name, namespace: namespace ?? identity.namespace }, {
+            method: FetchMethods.DELETE,
+            payload: {
+                apiVersion: "v1",
+                kind: "DeleteOptions",
+                preconditions: {
+                    resourceVersion: identity.resourceVersion,
+                    uid: identity.uid,
+                },
+            },
+        });
+    }
+    catch (error) {
+        if (!hasStatus(error, 404))
+            throw error;
+    }
+}
+/**
+ * Safely delete labeled resources for APIs without collection deletion.
+ *
+ * UID and resource-version preconditions prevent deletion if a listed object
+ * is re-created, re-labeled, or otherwise modified before the delete request.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param options - Ownership identity and optional namespace restriction.
+ */
+async function deleteWithoutCollectionSupport(model, options) {
+    await waitFor(`safe deletion of ${model.name} resources with the requested ownership labels`, async () => {
+        const list = await ownedResourceClient(model, options).Get();
+        if (list.items.length === 0)
+            return true;
+        await Promise.all(list.items.map(resource => deleteWithPreconditions(model, resource, options.namespace)));
+        return true;
+    }, options);
+}
+/**
+ * Apply a resource after stamping a stable ownership label.
+ *
+ * The input object is not mutated. Any existing labels are preserved unless
+ * they use a selected ownership key.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param resource - Resource body to server-side apply.
+ * @param options - Ownership labels and apply configuration.
+ * @returns The resource returned by Kubernetes.
+ */
+export function applyWithOwnership(model, resource, options) {
+    const labels = ownershipLabels(options);
+    const owned = {
+        ...resource,
+        metadata: {
+            ...resource.metadata,
+            labels: {
+                ...resource.metadata?.labels,
+                ...labels,
+            },
+        },
+    };
+    return K8s(model).Apply(owned, { force: options.force });
+}
+/**
+ * Delete every resource carrying the exact ownership labels.
+ *
+ * Kubernetes evaluates the exact label selectors when collection deletion is
+ * supported. Other APIs use UID and resource-version preconditions so a
+ * re-labeled or re-created resource cannot be deleted after discovery.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param options - Ownership identity and optional namespace restriction.
+ */
+export async function deleteAllByOwnership(model, options) {
+    if (options.namespace !== undefined && !options.namespace.trim()) {
+        throw new Error("Resource namespace must not be blank when provided");
+    }
+    try {
+        await ownedResourceClient(model, options).Delete();
+    }
+    catch (error) {
+        if (!hasStatus(error, 405))
+            throw error;
+        await deleteWithoutCollectionSupport(model, options);
+    }
+    if (options.waitForDeletion) {
+        await waitFor(`${model.name} resources with the requested ownership labels to be deleted`, async () => {
+            const remaining = await ownedResourceClient(model, options).Get();
+            return remaining.items.length === 0;
+        }, options);
+    }
+}
+/**
+ * Wait for one named Kubernetes resource to exist.
+ *
+ * @param model - KFC model for the Kubernetes resource kind.
+ * @param options - Resource identity plus standard waiter options.
+ * @returns The resource read from Kubernetes.
+ */
+export function waitForResource(model, options) {
+    const { name, namespace, description, ...waitOptions } = options;
+    validateResourceReference({ name, namespace });
+    const identity = namespace ? `${model.name}/${namespace}/${name}` : `${model.name}/${name}`;
+    return waitFor(description ?? identity, () => resourceClient(model, namespace).Get(name), waitOptions);
+}