@appthrust/kest 0.2.0 → 0.3.1

package/ts/apis/index.ts

@@ -54,6 +54,39 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Creates a Kubernetes resource with `kubectl create`.
+   *
+   * The manifest is validated and then created. When the action succeeds, Kest
+   * registers a cleanup handler that deletes the resource using
+   * `kubectl delete <kind>/<metadata.name>` during scenario cleanup.
+   *
+   * Unlike {@link Scenario.apply}, this action uses `kubectl create` which
+   * fails if the resource already exists. Use this when you need to ensure the
+   * resource is freshly created (e.g. for resources that use `generateName` or
+   * when you want to guarantee no prior state).
+   *
+   * This action is retried when it throws.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param manifest - YAML string, resource object, or imported YAML module.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.create({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   metadata: { name: "my-config" },
+   *   data: { mode: "demo" },
+   * });
+   * ```
+   */
+  create<T extends K8sResource>(
+    manifest: ApplyingManifest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource using server-side apply.
    *
@@ -114,6 +147,38 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Adds, updates, or removes labels on a Kubernetes resource using
+   * `kubectl label`.
+   *
+   * Set a label value to a string to add/update it, or to `null` to remove it.
+   *
+   * This action is retried when it throws.
+   *
+   * Note: this is a one-way mutation and does not register a cleanup handler.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Resource reference and label changes.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.label({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "my-config",
+   *   labels: {
+   *     env: "production",  // add or update
+   *     deprecated: null,   // remove
+   *   },
+   * });
+   * ```
+   */
+  label<T extends K8sResource>(
+    input: LabelInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Fetches a Kubernetes resource and returns it as a typed object.
    *
@@ -176,6 +241,32 @@ export interface Scenario {
     options?: undefined | ActionOptions
   ): Promise<T>;
 
+  /**
+   * Asserts that a Kubernetes resource does not exist.
+   *
+   * Internally, this uses `kubectl get` and expects it to fail with a
+   * "not found" error. If the resource exists, the assertion fails.
+   *
+   * This action is retried until the resource is absent or a timeout expires.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind and name of the resource.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await s.assertAbsence({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "deleted-config",
+   * });
+   * ```
+   */
+  assertAbsence<T extends K8sResource>(
+    resource: K8sResourceReference<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Lists Kubernetes resources of a given type and runs a test function.
    *
@@ -212,7 +303,11 @@ export interface Scenario {
    * `kest-abc12`). The namespace creation is a mutating action that registers a
    * cleanup handler; the namespace is deleted during scenario cleanup.
    *
-   * @param name - Optional namespace name to create.
+   * You can also pass `{ generateName: "prefix-" }` to generate a name with a
+   * custom prefix (e.g. `"prefix-d7kpn"`).
+   *
+   * @param name - Optional namespace name, or `{ generateName }` for prefixed
+   *   generation.
    * @param options - Retry options such as timeout and polling interval.
    *
    * @example
@@ -225,9 +320,15 @@ export interface Scenario {
    *   data: { mode: "namespaced" },
    * });
    * ```
+   *
+   * @example
+   * ```ts
+   * // Generate a namespace with a custom prefix (e.g. "foo-d7kpn")
+   * const ns = await s.newNamespace({ generateName: "foo-" });
+   * ```
    */
   newNamespace(
-    name?: undefined | string,
+    name?: undefined | string | { readonly generateName: string },
     options?: undefined | ActionOptions
   ): Promise<Namespace>;
 
@@ -374,6 +475,30 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Creates a Kubernetes resource with `kubectl create` and registers cleanup.
+   *
+   * Unlike {@link Cluster.apply}, this uses `kubectl create` which fails if the
+   * resource already exists.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param manifest - YAML string, resource object, or imported YAML module.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await cluster.create({
+   *   apiVersion: "v1",
+   *   kind: "Namespace",
+   *   metadata: { name: "my-team" },
+   * });
+   * ```
+   */
+  create<T extends K8sResource>(
+    manifest: ApplyingManifest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource using server-side apply.
    *
@@ -412,6 +537,38 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Adds, updates, or removes labels on a Kubernetes resource in this cluster
+   * using `kubectl label`.
+   *
+   * Set a label value to a string to add/update it, or to `null` to remove it.
+   *
+   * This action is retried when it throws.
+   *
+   * Note: this is a one-way mutation and does not register a cleanup handler.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Resource reference and label changes.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await cluster.label({
+   *   apiVersion: "v1",
+   *   kind: "Namespace",
+   *   name: "my-team",
+   *   labels: {
+   *     team: "backend",
+   *     deprecated: null,
+   *   },
+   * });
+   * ```
+   */
+  label<T extends K8sResource>(
+    input: LabelInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Fetches a Kubernetes resource by GVK and name.
    *
@@ -457,6 +614,27 @@ export interface Cluster {
     options?: undefined | ActionOptions
   ): Promise<T>;
 
+  /**
+   * Asserts that a Kubernetes resource does not exist in this cluster.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind and name of the resource.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await cluster.assertAbsence({
+   *   apiVersion: "v1",
+   *   kind: "Namespace",
+   *   name: "deleted-ns",
+   * });
+   * ```
+   */
+  assertAbsence<T extends K8sResource>(
+    resource: K8sResourceReference<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Lists Kubernetes resources of a given type and runs a test function.
    *
@@ -483,7 +661,8 @@ export interface Cluster {
   /**
    * Creates a new namespace in this cluster and returns a namespaced API.
    *
-   * @param name - Optional namespace name to create.
+   * @param name - Optional namespace name, or `{ generateName }` for prefixed
+   *   generation.
    * @param options - Retry options such as timeout and polling interval.
    *
    * @example
@@ -496,9 +675,15 @@ export interface Cluster {
    *   data: { mode: "from-cluster" },
    * });
    * ```
+   *
+   * @example
+   * ```ts
+   * // Generate a namespace with a custom prefix
+   * const ns = await cluster.newNamespace({ generateName: "foo-" });
+   * ```
    */
   newNamespace(
-    name?: undefined | string,
+    name?: undefined | string | { readonly generateName: string },
     options?: undefined | ActionOptions
   ): Promise<Namespace>;
 }
@@ -522,6 +707,11 @@ export interface Cluster {
  *   causes `kubectl` to fail.
  */
 export interface Namespace {
+  /**
+   * The name of this namespace (e.g. `"kest-abc12"`).
+   */
+  readonly name: string;
+
   /**
    * Applies a Kubernetes manifest in this namespace and registers cleanup.
    *
@@ -550,6 +740,37 @@ export interface Namespace {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Creates a Kubernetes resource in this namespace with `kubectl create` and
+   * registers cleanup.
+   *
+   * The target namespace is controlled by this {@link Namespace} instance.
+   * Prefer omitting `manifest.metadata.namespace`; if it is set, it must match
+   * this namespace (otherwise `kubectl` fails).
+   *
+   * Unlike {@link Namespace.apply}, this uses `kubectl create` which fails if
+   * the resource already exists.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param manifest - YAML string, resource object, or imported YAML module.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * const ns = await s.newNamespace("my-ns");
+   * await ns.create({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   metadata: { name: "my-config" },
+   *   data: { mode: "demo" },
+   * });
+   * ```
+   */
+  create<T extends K8sResource>(
+    manifest: ApplyingManifest<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Applies the `status` subresource in this namespace using server-side apply.
    *
@@ -592,6 +813,40 @@ export interface Namespace {
     options?: undefined | ActionOptions
   ): Promise<void>;
 
+  /**
+   * Adds, updates, or removes labels on a namespaced Kubernetes resource using
+   * `kubectl label`.
+   *
+   * The target namespace is controlled by this {@link Namespace} instance.
+   *
+   * Set a label value to a string to add/update it, or to `null` to remove it.
+   *
+   * This action is retried when it throws.
+   *
+   * Note: this is a one-way mutation and does not register a cleanup handler.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param input - Resource reference and label changes.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await ns.label({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "my-config",
+   *   labels: {
+   *     env: "production",
+   *     deprecated: null,
+   *   },
+   * });
+   * ```
+   */
+  label<T extends K8sResource>(
+    input: LabelInput<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Fetches a namespaced Kubernetes resource by GVK and name.
    *
@@ -637,6 +892,27 @@ export interface Namespace {
     options?: undefined | ActionOptions
   ): Promise<T>;
 
+  /**
+   * Asserts that a namespaced Kubernetes resource does not exist.
+   *
+   * @template T - The expected Kubernetes resource shape.
+   * @param resource - Group/version/kind and name of the resource.
+   * @param options - Retry options such as timeout and polling interval.
+   *
+   * @example
+   * ```ts
+   * await ns.assertAbsence({
+   *   apiVersion: "v1",
+   *   kind: "ConfigMap",
+   *   name: "deleted-config",
+   * });
+   * ```
+   */
+  assertAbsence<T extends K8sResource>(
+    resource: K8sResourceReference<T>,
+    options?: undefined | ActionOptions
+  ): Promise<void>;
+
   /**
    * Lists namespaced Kubernetes resources of a given type and runs a test.
    *
@@ -737,6 +1013,57 @@ export interface K8sResourceReference<T extends K8sResource = K8sResource> {
   readonly name: string;
 }
 
+/**
+ * Input for {@link Scenario.label}, {@link Cluster.label}, and
+ * {@link Namespace.label}.
+ *
+ * Identifies a Kubernetes resource and the label changes to apply.
+ *
+ * - A label value of `string` adds or updates the label.
+ * - A label value of `null` removes the label.
+ */
+export interface LabelInput<T extends K8sResource = K8sResource> {
+  /**
+   * Kubernetes API version (e.g. `"v1"`, `"apps/v1"`).
+   */
+  readonly apiVersion: T["apiVersion"];
+
+  /**
+   * Kubernetes kind (e.g. `"ConfigMap"`, `"Deployment"`).
+   */
+  readonly kind: T["kind"];
+
+  /**
+   * `metadata.name` of the target resource.
+   */
+  readonly name: string;
+
+  /**
+   * Optional namespace override.
+   *
+   * When used on a {@link Namespace}-scoped API surface the namespace is
+   * already set; this field is mainly useful at the {@link Scenario} or
+   * {@link Cluster} level for namespaced resources.
+   */
+  readonly namespace?: undefined | string;
+
+  /**
+   * Label mutations to apply.
+   *
+   * - `"value"` -- add or update the label to the given value.
+   * - `null` -- remove the label.
+   */
+  readonly labels: Readonly<Record<string, string | null>>;
+
+  /**
+   * When `true`, passes `--overwrite` to allow updating labels that already
+   * exist on the resource.
+   *
+   * @default false
+   */
+  readonly overwrite?: undefined | boolean;
+}
+
 /**
  * A test definition for {@link Scenario.assert}.
  */

package/ts/k8s-resource/index.ts

@@ -118,3 +118,25 @@ export interface ESM {
 function isESM(value: unknown): value is ESM {
   return typeof value === "object" && value !== null && "default" in value;
 }
+
+export function getResourceMeta(
+  value: unknown
+): undefined | { kind: string; name: string } {
+  if (typeof value === "string") {
+    const result = parseK8sResourceYaml(value);
+    if (result.ok) {
+      return { kind: result.value.kind, name: result.value.metadata.name };
+    }
+  }
+  if (isESM(value)) {
+    const result = parseK8sResourceFromESM(value);
+    if (result.ok) {
+      return { kind: result.value.kind, name: result.value.metadata.name };
+    }
+  }
+  const result = parseK8sResource(value);
+  if (result.ok) {
+    return { kind: result.value.kind, name: result.value.metadata.name };
+  }
+  return undefined;
+}

package/ts/kubectl/index.ts

@@ -135,6 +135,26 @@ export interface Kubectl {
     name: string,
     options?: KubectlDeleteOptions
   ): Promise<string>;
+
+  /**
+   * Adds, updates, or removes labels on a Kubernetes resource using
+   * `kubectl label <resource>/<name> key=value ... [--overwrite]`.
+   *
+   * Labels with a `null` value are removed (emitted as `key-`).
+   *
+   * @param resource - The resource type (e.g., "configmap", "deployment.v1.apps")
+   * @param name - The name of the resource to label
+   * @param labels - Label mutations (string to set, null to remove)
+   * @param options - Optional label options (overwrite, context)
+   * @returns The trimmed stdout from kubectl
+   * @throws Error if kubectl exits with non-zero code
+   */
+  label(
+    resource: string,
+    name: string,
+    labels: Readonly<Record<string, string | null>>,
+    options?: KubectlLabelOptions
+  ): Promise<string>;
 }
 
 export interface KubectlDeleteOptions {
@@ -146,6 +166,15 @@ export interface KubectlDeleteOptions {
   readonly context?: undefined | KubectlContext;
 }
 
+export interface KubectlLabelOptions {
+  /**
+   * If true, adds `--overwrite` to allow updating labels that already
+   * exist on the resource.
+   */
+  readonly overwrite?: undefined | boolean;
+  readonly context?: undefined | KubectlContext;
+}
+
 export class RealKubectl implements Kubectl {
   private readonly recorder: Recorder;
   private readonly cwd: undefined | string;
@@ -283,6 +312,31 @@ export class RealKubectl implements Kubectl {
     });
   }
 
+  async label(
+    resource: string,
+    name: string,
+    labels: Readonly<Record<string, string | null>>,
+    options?: KubectlLabelOptions
+  ): Promise<string> {
+    const args: [string, ...Array<string>] = ["label", `${resource}/${name}`];
+    for (const [key, value] of Object.entries(labels)) {
+      if (value === null) {
+        args.push(`${key}-`);
+      } else {
+        args.push(`${key}=${value}`);
+      }
+    }
+    if (options?.overwrite) {
+      args.push("--overwrite");
+    }
+    return await this.runKubectl({
+      args,
+      stdoutLanguage: "text",
+      stderrLanguage: "text",
+      overrideContext: options?.context,
+    });
+  }
+
   private async runKubectl(params: ExecParams): Promise<string> {
     const cmd = "kubectl";
     const ctx = { ...this.defaultContext, ...params.overrideContext };