@alchemy.run/kubernetes 2.0.0-beta.84 → 2.0.0-beta.85

package/src/Client.ts

@@ -36,6 +36,13 @@ import {
   type KubernetesObjectRef,
 } from "./Objects.ts";
 
+export class KubernetesClientOperationFailed extends Data.TaggedError(
+  "KubernetesClientOperationFailed",
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
 export class KubernetesApiError extends Data.TaggedError("KubernetesApiError")<{
   method: string;
   path: string;
@@ -49,6 +56,12 @@ export class KubernetesApiError extends Data.TaggedError("KubernetesApiError")<{
   }
 }
 
+/** An object ref that cannot be mapped to a REST path (e.g. a namespaced kind without a namespace). */
+export class KubernetesObjectPathError extends Data.TaggedError("KubernetesObjectPathError")<{
+  message: string;
+  cause?: unknown;
+}> {}
+
 const fieldManager = "alchemy";
 
 /** Deadline for auth-header minting and for each HTTP attempt. */
@@ -81,7 +94,7 @@ export class KubernetesNotFound extends Data.TaggedError("KubernetesNotFound")<{
  * becomes `undefined`; auth and HTTP failures stay failures.
  */
 export const ifClusterExists = <A, E, R>(effect: Effect.Effect<A, ClusterNotFoundError | E, R>) =>
-  effect.pipe(Effect.catchTag("Kubernetes.ClusterNotFoundError", () => Effect.succeed(undefined)));
+  effect.pipe(Effect.catchTag("Kubernetes.ClusterNotFoundError", () => Effect.undefined));
 
 const requestJson = Effect.fn(function* ({
   transport,
@@ -156,13 +169,21 @@ const requestJson = Effect.fn(function* ({
           resume(Effect.fail(error));
         });
         incoming.on("aborted", () => {
-          resume(Effect.fail(new Error(`Kubernetes ${method} ${path} response aborted`)));
+          resume(
+            Effect.fail(
+              new KubernetesClientOperationFailed({
+                message: `Kubernetes ${method} ${path} response aborted`,
+              }),
+            ),
+          );
         });
         incoming.on("end", () => {
           if (incoming.complete === false) {
             resume(
               Effect.fail(
-                new Error(`Kubernetes ${method} ${path} response ended before completion`),
+                new KubernetesClientOperationFailed({
+                  message: `Kubernetes ${method} ${path} response ended before completion`,
+                }),
               ),
             );
             return;
@@ -178,7 +199,13 @@ const requestJson = Effect.fn(function* ({
       },
     );
     request.on("error", (error) => {
-      resume(Effect.fail(error instanceof Error ? error : new Error(String(error))));
+      resume(
+        Effect.fail(
+          error instanceof Error
+            ? error
+            : new KubernetesClientOperationFailed({ message: String(error) }),
+        ),
+      );
     });
     if (prepared.payload !== undefined) request.write(prepared.payload);
     request.end();
@@ -193,9 +220,9 @@ const requestJson = Effect.fn(function* ({
     Effect.timeout(requestTimeout),
     Effect.mapError(
       (error) =>
-        new Error(
-          `Failed Kubernetes ${method} ${path}: ${error instanceof Error ? error.message : String(error)}`,
-        ),
+        new KubernetesClientOperationFailed({
+          message: `Failed Kubernetes ${method} ${path}: ${error instanceof Error ? error.message : String(error)}`,
+        }),
     ),
     // Transport-level failures (ECONNREFUSED/ECONNRESET/ETIMEDOUT/DNS,
     // the per-attempt deadline) are transient — a fresh managed endpoint's
@@ -310,7 +337,11 @@ const buildPath = Effect.fn(function* ({
   const spec = yield* resolveKindSpec({ transport, input: object });
   return yield* Effect.try({
     try: () => buildKubernetesObjectPathWithSpec(object, spec),
-    catch: (error) => (error instanceof Error ? error : new Error(String(error))),
+    catch: (error) =>
+      new KubernetesObjectPathError({
+        message: error instanceof Error ? error.message : String(error),
+        cause: error,
+      }),
   });
 });
 

package/src/ClusterAdapter.ts

@@ -1,4 +1,5 @@
 import type { InlineDockerfile } from "@alchemy.run/docker/Dockerfile";
+import type { DockerfileBuild } from "@alchemy.run/docker/ImageSource";
 import type * as Bundle from "alchemy/Bundle/Bundle";
 import type { ResourceBinding } from "alchemy/Resource";
 import type { ResourceContext } from "alchemy/ResourceContext";
@@ -170,12 +171,13 @@ export interface WorkloadImageSource {
   main?: string;
   handler?: string;
   /**
-   * Bundler configuration for `main`. Unused code is tree-shaken.
+   * Bundler configuration for `main`, or Docker build args and secrets for
+   * a `context`/`dockerfile` build. Unused bundled code is tree-shaken.
    * `effect`, alchemy, and `@distilled.cloud` are marked pure so unused
    * parts prune more aggressively. List extra packages with
    * `pure.packages`, or disable with `pure: false`.
    */
-  build?: Bundle.BundleConfig;
+  build?: Bundle.BundleConfig & DockerfileBuild;
   context?: string;
   dockerfile?: string | InlineDockerfile;
   image?: string;
@@ -210,6 +212,7 @@ export interface WorkloadIdentityResult {
   /** Annotations to stamp on the workload's ServiceAccount object. */
   serviceAccountAnnotations?: Record<string, string>;
   /** Serializable state persisted on the workload's attributes. */
+  // oxlint-disable-next-line typescript/no-redundant-type-constituents -- registry type is `never` until cloud packages augment it
   state: IdentityState | undefined;
 }
 

package/src/Deployment.ts

@@ -1,3 +1,5 @@
+import type { DockerfileBuildOptions } from "@alchemy.run/docker/ImageSource";
+import type * as Bundle from "alchemy/Bundle/Bundle";
 import { isResolved } from "alchemy/Diff";
 import type { Input } from "alchemy/Input";
 import { createPhysicalName } from "alchemy/PhysicalName";
@@ -174,7 +176,7 @@ export interface BundledDeploymentProps extends DeploymentPropsBase {
   /** Named export to load from `main`. @default "default" */
   handler?: string;
   /** Bundler configuration for the entrypoint. */
-  build?: WorkloadImageSource["build"];
+  build?: Bundle.BundleConfig;
   /** Environment Dockerfile (path or inline content). */
   dockerfile?: WorkloadImageSource["dockerfile"];
   /** Build context for a path {@link dockerfile} environment. */
@@ -182,7 +184,7 @@ export interface BundledDeploymentProps extends DeploymentPropsBase {
 }
 
 /** Build the user's own Dockerfile (`context` + optional `dockerfile` path). */
-export interface DockerfileDeploymentProps extends DeploymentPropsBase {
+export interface DockerfileDeploymentProps extends DeploymentPropsBase, DockerfileBuildOptions {
   /** Docker build context directory. */
   context?: string;
   /**
@@ -229,6 +231,7 @@ export interface Deployment extends Resource<
      * adapter (on EKS: the pod-identity role + association; on GKE: the
      * Workload Identity principal and the IAM grants applied to it).
      */
+    // oxlint-disable-next-line typescript/no-redundant-type-constituents -- registry type is `never` until cloud packages augment it
     identity: IdentityState | undefined;
     /**
      * Image-registry state provisioned by the cluster platform's adapter
@@ -252,6 +255,7 @@ export interface Deployment extends Resource<
   Providers
 > {}
 
+// oxlint-disable-next-line typescript/no-redundant-type-constituents -- registry type is `never` until cloud packages augment it
 export type DeploymentServices = ServerHostService | WorkloadServices;
 
 export type DeploymentShape = Main<DeploymentServices>;
@@ -320,6 +324,23 @@ export interface DeploymentRuntimeContext extends HostRuntimeContext {
  * });
  * ```
  *
+ * **Example:** Build args and secrets
+ * ```typescript
+ * // Dockerfile:
+ * //   ARG NODE_ENV
+ * //   RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
+ * const api = yield* Kubernetes.Deployment("Api", {
+ *   cluster,
+ *   context: "./api",
+ *   build: {
+ *     args: { NODE_ENV: "production" },
+ *     // Mounted only into the RUN step that asks for it; never in the image.
+ *     secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
+ *   },
+ *   port: 8080,
+ * });
+ * ```
+ *
  * ### Effect Servers
  * **Example:** Inline Effect server
  * ```typescript
@@ -538,7 +559,7 @@ export const DeploymentProvider = () =>
             hostname ? Effect.succeed(hostname) : Effect.fail(new ServiceNotReady()),
           ),
           retryUntilServiceReady,
-          Effect.catchTag("Kubernetes.ServiceNotReady", () => Effect.succeed(undefined)),
+          Effect.catchTag("Kubernetes.ServiceNotReady", () => Effect.undefined),
         );
 
       return {
@@ -613,7 +634,7 @@ export const DeploymentProvider = () =>
           const anchor = (output.kubernetesObjects ?? [])[0];
           if (!anchor) return output;
           const observed = yield* readObject({ transport, object: anchor }).pipe(
-            Effect.catchTag("KubernetesNotFound", () => Effect.succeed(undefined)),
+            Effect.catchTag("KubernetesNotFound", () => Effect.undefined),
           );
           if (observed === undefined) return undefined;
           return output;

package/src/HelmChart.ts

@@ -355,7 +355,7 @@ export const HelmChartProvider = () =>
               Effect.gen(function* () {
                 const key = kubernetesObjectKey(object);
                 const observed = yield* readObject({ transport, object }).pipe(
-                  Effect.catchTag("KubernetesNotFound", () => Effect.succeed(undefined)),
+                  Effect.catchTag("KubernetesNotFound", () => Effect.undefined),
                 );
                 if (!observed) return `missing:${key}`;
                 // Older rows stored no selection. Re-rendering the chart is

package/src/Job.ts

@@ -1,3 +1,5 @@
+import type { DockerfileBuildOptions } from "@alchemy.run/docker/ImageSource";
+import type * as Bundle from "alchemy/Bundle/Bundle";
 import { isResolved } from "alchemy/Diff";
 import * as Output from "alchemy/Output";
 import { createPhysicalName } from "alchemy/PhysicalName";
@@ -155,7 +157,7 @@ export interface BundledJobProps extends JobPropsBase {
   /** Named export to load from `main`. @default "default" */
   handler?: string;
   /** Bundler configuration for the entrypoint. */
-  build?: WorkloadImageSource["build"];
+  build?: Bundle.BundleConfig;
   /** Environment Dockerfile (path or inline content). */
   dockerfile?: WorkloadImageSource["dockerfile"];
   /** Build context for a path {@link dockerfile} environment. */
@@ -163,7 +165,7 @@ export interface BundledJobProps extends JobPropsBase {
 }
 
 /** Build the user's own Dockerfile (`context` + optional `dockerfile` path). */
-export interface DockerfileJobProps extends JobPropsBase {
+export interface DockerfileJobProps extends JobPropsBase, DockerfileBuildOptions {
   /** Docker build context directory. */
   context?: string;
   /**
@@ -207,6 +209,7 @@ export interface Job extends Resource<
      * adapter (on EKS: the pod-identity role + association; on GKE: the
      * Workload Identity principal and the IAM grants applied to it).
      */
+    // oxlint-disable-next-line typescript/no-redundant-type-constituents -- registry type is `never` until cloud packages augment it
     identity: IdentityState | undefined;
     /**
      * Image-registry state provisioned by the cluster platform's adapter
@@ -267,6 +270,23 @@ export interface JobRuntimeContext extends HostRuntimeContext {
  * });
  * ```
  *
+ * **Example:** Your own Dockerfile with build args and secrets
+ * ```typescript
+ * // Dockerfile:
+ * //   ARG NODE_ENV
+ * //   RUN --mount=type=secret,id=NPM_TOKEN,env=NPM_TOKEN npm ci
+ * const migrate = yield* Kubernetes.Job("DbMigrate", {
+ *   cluster,
+ *   context: "./migrator",
+ *   build: {
+ *     args: { NODE_ENV: "production" },
+ *     // Mounted only into the RUN step that asks for it; never in the image.
+ *     secrets: { NPM_TOKEN: Config.Redacted("NPM_TOKEN") },
+ *   },
+ *   backoffLimit: 2,
+ * });
+ * ```
+ *
  * **Example:** Inline Effect program
  * ```typescript
  * const cluster = yield* Kubernetes.LocalCluster("Cluster", {
@@ -477,7 +497,7 @@ export const JobProvider = () =>
           const observed = yield* readObject({
             transport,
             object: anchor,
-          }).pipe(Effect.catchTag("KubernetesNotFound", () => Effect.succeed(undefined)));
+          }).pipe(Effect.catchTag("KubernetesNotFound", () => Effect.undefined));
           if (observed === undefined) return undefined;
           return output;
         }),

package/src/LocalCluster.ts

@@ -1,4 +1,4 @@
-import { Unowned } from "alchemy/AdoptPolicy";
+import { unownedUnlessPrevious } from "alchemy/AdoptPolicy";
 import { deepEqual, isResolved } from "alchemy/Diff";
 import { createPhysicalName } from "alchemy/PhysicalName";
 import * as Provider from "alchemy/Provider";
@@ -308,7 +308,7 @@ export const LocalClusterProvider = () =>
           detached: false,
           extendEnv: true,
         }).pipe(
-          spawner.spawn,
+          (command) => spawner.spawn(command),
           Effect.flatMap((child) =>
             Effect.all(
               {
@@ -559,7 +559,7 @@ export const LocalClusterProvider = () =>
             return { action: "replace", deleteFirst: true } as const;
           }
         }),
-        read: Effect.fn(function* ({ id, olds, output }) {
+        read: Effect.fn(function* ({ id, olds, output, previous }) {
           const name = yield* clusterName(id, olds, output);
           if (!(yield* clusterExists(name))) return undefined;
           const registryInfo = yield* inspectRegistry(`${name}-registry`);
@@ -574,7 +574,7 @@ export const LocalClusterProvider = () =>
           // kind clusters carry no ownership marker; the registry container
           // we start next to them does. Anything else is foreign.
           const owned = yield* hasAlchemyTags(id, registryInfo?.Config?.Labels ?? undefined);
-          return owned ? attrs : Unowned(attrs);
+          return owned ? attrs : unownedUnlessPrevious(attrs, previous, "name");
         }),
         reconcile: Effect.fn(function* ({ id, news, output, session }) {
           const name = yield* clusterName(id, news, output);

package/src/Manifest.ts

@@ -2,6 +2,7 @@ import { isResolved } from "alchemy/Diff";
 import * as Provider from "alchemy/Provider";
 import { Resource } from "alchemy/Resource";
 import { isPlainObject } from "alchemy/Util/data";
+import * as Data from "effect/Data";
 import * as Effect from "effect/Effect";
 import {
   applyObject,
@@ -16,6 +17,11 @@ import { connectionIdentity, connectionOfOutput, tryConnectionOf } from "./inter
 import type { KubernetesObjectDefinition, KubernetesObjectRef } from "./Objects.ts";
 import type { Providers } from "./Providers.ts";
 
+export class ManifestInvalidProps extends Data.TaggedError("ManifestInvalidProps")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
 /**
  * A literal Kubernetes object: `apiVersion` + `kind` + `metadata`, with the
  * rest of the object's fields (`spec`, `data`, …) carried as-is. Any kind is
@@ -174,9 +180,9 @@ const toObjectDefinition = (
   const name = manifest.metadata?.name;
   if (!name) {
     return Effect.fail(
-      new Error(
-        `Kubernetes.Manifest requires manifest.metadata.name (got ${manifest.apiVersion}/${manifest.kind})`,
-      ),
+      new ManifestInvalidProps({
+        message: `Kubernetes.Manifest requires manifest.metadata.name (got ${manifest.apiVersion}/${manifest.kind})`,
+      }),
     );
   }
   return Effect.succeed(manifest as KubernetesObjectDefinition);
@@ -219,7 +225,7 @@ export const ManifestProvider = () =>
           const observed = yield* readObject({
             transport,
             object: output.ref,
-          }).pipe(Effect.catchTag("KubernetesNotFound", () => Effect.succeed(undefined)));
+          }).pipe(Effect.catchTag("KubernetesNotFound", () => Effect.undefined));
           if (!observed) return undefined;
           const uid = (observed as { metadata?: { uid?: string } }).metadata?.uid;
           const attrs = { ...output, uid };

package/src/internal/helm.ts

@@ -116,7 +116,7 @@ export const renderHelmChart = Effect.fn(function* (options: RenderHelmChartOpti
         detached: false,
         extendEnv: true,
       }).pipe(
-        spawner.spawn,
+        (command) => spawner.spawn(command),
         Effect.flatMap((child) =>
           Effect.all(
             {

package/src/internal/kubeconfig.ts

@@ -215,7 +215,7 @@ export const runExecCredential = Effect.fn(function* (options: {
     extendEnv: true,
     env: options.env,
   }).pipe(
-    spawner.spawn,
+    (command) => spawner.spawn(command),
     Effect.flatMap((child) =>
       Effect.all(
         {

package/src/internal/workload.ts

@@ -57,7 +57,7 @@ export const deepMerge = <T>(base: T, override: unknown): T => {
  */
 export const imagePlatformOf = (
   architecture: "amd64" | "arm64" | undefined,
-  connection?: Connection | undefined,
+  connection?: Connection,
 ): string =>
   (architecture ?? connection?.architecture) === "arm64" ? "linux/arm64" : "linux/amd64";
 
@@ -320,6 +320,7 @@ export const workloadImageHash = Effect.fn(function* (options: {
 });
 
 /** The identity-adapter state persisted on workload attributes. */
+// oxlint-disable-next-line typescript/no-redundant-type-constituents -- registry type is `never` until cloud packages augment it
 export type PersistedIdentityState = IdentityState | undefined;
 
 /**