alchemy 2.0.0-beta.74 → 2.0.0-beta.76

package/src/Hetzner/hosted.ts

@@ -2,17 +2,33 @@ import { Services } from "@distilled.cloud/hetzner";
 import * as Data from "effect/Data";
 import * as Duration from "effect/Duration";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import * as Schedule from "effect/Schedule";
 import type * as rolldown from "rolldown";
 import * as Bundle from "../Bundle/Bundle.ts";
+import {
+  matchesPackageRoot,
+  normalizeInstallTargets,
+  resolvePackageInstallIdentity,
+  type PackageInstall,
+} from "../Bundle/InstalledPackages.ts";
 import { findCwdForBundle, resolveMainPath } from "../Bundle/TempRoot.ts";
 import type { ResourceBinding } from "../Resource.ts";
-import { Self } from "../Self.ts";
 import {
   createHostRuntimeContext,
   type HostRuntimeContext,
 } from "../Server/Process.ts";
-import { zipCode } from "../Util/zip.ts";
+import {
+  contextRootOf,
+  extraFileDestination,
+  hashExtraFiles,
+  isContextRootDest,
+  posixRelUnder,
+  resolveExtraSource,
+} from "../Util/extraFiles.ts";
+import { sha256, sha256Object } from "../Util/sha256.ts";
+import { zipCode, zipFiles, type ZipFile } from "../Util/zip.ts";
 import { waitForAction } from "./actions.ts";
 import type { ServiceBinding } from "./MountVolume.ts";
 import { openSshClient, type SshClient } from "./Ssh.ts";
@@ -28,15 +44,53 @@ class VolumeAttachTimeout extends Data.TaggedError(
 
 export const createHetznerHostRuntimeContext = createHostRuntimeContext;
 
+export interface HetznerBuildOptions extends Bundle.BundleConfig {
+  /**
+   * Native or Node-only packages to `npm install` into the unit instead
+   * of bundling them. Same shape as Fly/Lambda `build.install`.
+   */
+  readonly install?: PackageInstall;
+}
+
 export interface HostedProgramProps {
   main: string;
   handler?: string;
   port?: number;
   env?: Record<string, any>;
   isExternal?: boolean;
-  build?: Bundle.BundleConfig;
+  build?: HetznerBuildOptions;
+  /**
+   * Extra host directories packed into the unit archive (framework
+   * client assets, Next.js `.next`, …). Hashed into `code.hash` so
+   * asset changes update the unit. Destination is relative to the
+   * unit root.
+   */
+  extraFiles?: ReadonlyArray<ExtraFile>;
+}
+
+export interface ExtraFile {
+  readonly source: string;
+  readonly destination: string;
 }
 
+const matchesConfiguredExternal = (
+  external: rolldown.InputOptions["external"],
+  moduleId: string,
+  parentId: string | undefined,
+  isResolved: boolean,
+): boolean => {
+  if (external === undefined) return false;
+  if (typeof external === "function") {
+    return external(moduleId, parentId, isResolved) === true;
+  }
+  const matchers = Array.isArray(external) ? external : [external];
+  return matchers.some((matcher) =>
+    typeof matcher === "string" ? matcher === moduleId : matcher.test(moduleId),
+  );
+};
+
+export { extraFileDestination };
+
 const quoteEnvValue = (value: unknown) => {
   const text =
     typeof value === "string" ? value : JSON.stringify(value ?? null);
@@ -72,72 +126,85 @@ export const collectBindingState = (
   return { env, volumes };
 };
 
+const skipExtraPath = (relative: string) =>
+  relative
+    .replaceAll("\\", "/")
+    .split("/")
+    .some(
+      (segment) =>
+        segment === "node_modules" ||
+        segment === ".git" ||
+        segment.startsWith(".alchemy-hetzner"),
+    );
+
+const toSharedExtraFiles = (extraFiles: ReadonlyArray<ExtraFile> | undefined) =>
+  extraFiles?.map((file) => ({
+    source: file.source,
+    dest: file.destination,
+  }));
+
+const collectExtraFiles = Effect.fn(function* (
+  extraFiles: ReadonlyArray<ExtraFile> | undefined,
+) {
+  if (extraFiles === undefined || extraFiles.length === 0) {
+    return [] as ZipFile[];
+  }
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const files: ZipFile[] = [];
+  for (const extra of extraFiles) {
+    const dest = extraFileDestination(extra.destination);
+    const source = resolveExtraSource(extra.source, path);
+    if (!(yield* fs.exists(source))) continue;
+    const rootStat = yield* fs.stat(source);
+    const skip = isContextRootDest(dest)
+      ? (relative: string) =>
+          relative
+            .replaceAll("\\", "/")
+            .split("/")
+            .some(
+              (segment) =>
+                segment === ".git" || segment.startsWith(".alchemy-hetzner"),
+            )
+      : skipExtraPath;
+    if (rootStat.type === "File") {
+      files.push({
+        path: isContextRootDest(dest) ? path.basename(source) : dest,
+        content: yield* fs.readFile(source),
+      });
+      continue;
+    }
+    const names = yield* fs.readDirectory(source, { recursive: true });
+    for (const name of names) {
+      if (skip(name)) continue;
+      const full = path.join(source, name);
+      const stat = yield* fs.stat(full);
+      if (stat.type !== "File") continue;
+      const posixName = name.replaceAll("\\", "/");
+      files.push({
+        path: isContextRootDest(dest)
+          ? posixName
+          : `${dest}/${posixName}`.replaceAll(/\/+/g, "/"),
+        content: yield* fs.readFile(full),
+      });
+    }
+  }
+  return files;
+});
+
+/**
+ * The generated entry for `Hetzner.Service` units: a shim importing only
+ * `alchemy/Runtime/Bootstrap/Hetzner` plus the user's `main` — see that
+ * module for why the entry never imports alchemy's own dependencies.
+ */
 const makeBunBootstrap =
   (handler: string) =>
   (importPath: string): string =>
     `
-import { BunServices } from "@effect/platform-bun";
-import { BunHttpServer } from "alchemy/Http";
-import { Stack } from "alchemy/Stack";
-import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
-import * as Config from "effect/Config";
-import * as ConfigProvider from "effect/ConfigProvider";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
-import * as Layer from "effect/Layer";
-import * as Logger from "effect/Logger";
-
+import { bootstrap } from "alchemy/Runtime/Bootstrap/Hetzner";
 import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};
 
-const tag = Context.Service(${JSON.stringify(Self.key)});
-const layer = makeEntrypointLayer(tag, entrypoint);
-
-const platform = Layer.mergeAll(
-  BunServices.layer,
-  FetchHttpClient.layer,
-  Logger.layer([Logger.consolePretty()]),
-);
-
-const stack = Layer.effect(
-  Stack,
-  Effect.all([
-    Config.string("ALCHEMY_STACK_NAME"),
-    Config.string("ALCHEMY_STAGE")
-  ]).pipe(
-    Effect.map(([name, stage]) => ({
-      name,
-      stage,
-      bindings: {},
-      resources: {}
-    }))
-  )
-);
-
-const program = tag.pipe(
-  Effect.flatMap((service) => service.RuntimeContext.exports),
-  Effect.flatMap((exports) => exports.program),
-  Effect.provide(
-    layer.pipe(
-      Layer.provideMerge(stack),
-      Layer.provideMerge(BunHttpServer()),
-      Layer.provideMerge(platform),
-      Layer.provideMerge(
-        Layer.succeed(
-          ConfigProvider.ConfigProvider,
-          reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env)
-        )
-      ),
-    )
-  ),
-  Effect.scoped
-);
-
-console.log("Hetzner service bootstrap starting...");
-await Effect.runPromise(program).catch((err) => {
-  console.error("Hetzner service bootstrap failed:", err);
-  process.exit(1);
-});
+await bootstrap(entrypoint);
 `;
 
 export const createHetznerHostedSupport = ({
@@ -155,6 +222,7 @@ export const createHetznerHostedSupport = ({
     ALCHEMY_STACK_NAME: stackName,
     ALCHEMY_STAGE: stage,
     ALCHEMY_PHASE: "runtime",
+    HOST: "0.0.0.0",
   };
 
   const bundleProgram = Effect.fn(function* (
@@ -165,6 +233,10 @@ export const createHetznerHostedSupport = ({
     const realMain = yield* resolveMainPath(props.main);
     const cwd = yield* findCwdForBundle(realMain);
 
+    const requested = yield* normalizeInstallTargets(props.build?.install);
+    const installRoots = new Set(Object.keys(requested));
+    const configuredExternal = props.build?.input?.external;
+
     const buildBundle = Effect.fn(function* (
       entry: string,
       plugins?: rolldown.RolldownPluginOption,
@@ -175,13 +247,20 @@ export const createHetznerHostedSupport = ({
           input: entry,
           cwd,
           platform: "node",
-          external: [
-            "bun",
-            "bun:*",
-            ...((props.build?.input?.external as string[] | undefined) ?? []),
-          ],
+          external: (moduleId, parentId, isResolved) => {
+            if (moduleId === "bun" || moduleId.startsWith("bun:")) return true;
+            for (const root of installRoots) {
+              if (matchesPackageRoot(moduleId, root)) return true;
+            }
+            return matchesConfiguredExternal(
+              configuredExternal,
+              moduleId,
+              parentId,
+              isResolved,
+            );
+          },
           resolve: {
-            conditionNames: ["bun", "import", "module", "default"],
+            conditionNames: [...Bundle.NODE_CONDITION_NAMES],
             ...props.build?.input?.resolve,
           },
           plugins: [props.build?.input?.plugins, plugins],
@@ -192,32 +271,109 @@ export const createHetznerHostedSupport = ({
           sourcemap: props.build?.output?.sourcemap ?? false,
           minify: props.build?.output?.minify ?? false,
           entryFileNames: "index.mjs",
+          // Preserve init order for framework SSR bundles.
+          strictExecutionOrder: true,
+          keepNames: true,
         },
         props.build,
       );
     });
 
-    const bundleOutput = props.isExternal
-      ? yield* buildBundle(realMain)
-      : yield* buildBundle(
-          realMain,
-          virtualEntryPlugin(makeBunBootstrap(handler)),
-        );
-
     const toBytes = (content: string | Uint8Array<ArrayBufferLike>) =>
       typeof content === "string" ? new TextEncoder().encode(content) : content;
+    const extraFiles = yield* collectExtraFiles(props.extraFiles);
+    const identity =
+      Object.keys(requested).length > 0
+        ? yield* resolvePackageInstallIdentity({ cwd, requested })
+        : undefined;
+    const install =
+      identity !== undefined && Object.keys(identity.resolved).length > 0
+        ? identity.resolved
+        : undefined;
+    const packageJson =
+      install === undefined
+        ? undefined
+        : `${JSON.stringify(
+            { private: true, type: "module", dependencies: install },
+            null,
+            2,
+          )}\n`;
+    const installFiles =
+      packageJson !== undefined
+        ? [
+            {
+              path: "package.json",
+              content: new TextEncoder().encode(packageJson),
+            },
+          ]
+        : [];
+
+    // `isExternal` mains are already complete Node programs. Pack the
+    // dist tree as-built so relative imports (`../client`, nitro chunks)
+    // survive. Do not rolldown-flatten.
+    if (props.isExternal) {
+      const fs = yield* FileSystem.FileSystem;
+      const pathMod = yield* Path.Path;
+      const extras = toSharedExtraFiles(props.extraFiles) ?? [];
+      const root = contextRootOf(realMain, extras, pathMod, (source) =>
+        resolveExtraSource(source, pathMod),
+      );
+      const entryRel =
+        posixRelUnder(root, realMain, pathMod) ?? pathMod.basename(realMain);
+      const entryBytes = yield* fs.readFile(realMain);
+      const zipEntries: ZipFile[] = [
+        ...extraFiles.filter(
+          (file) =>
+            !(file.path === "package.json" && packageJson !== undefined),
+        ),
+        ...installFiles,
+      ];
+      if (!zipEntries.some((file) => file.path === entryRel)) {
+        zipEntries.push({ path: entryRel, content: entryBytes });
+      }
+      const archive = yield* zipFiles(zipEntries);
+      const extraHash = yield* hashExtraFiles(
+        toSharedExtraFiles(props.extraFiles),
+      );
+      const hash = yield* sha256Object({
+        bundle: yield* sha256(entryBytes),
+        extra: extraHash,
+        packageJson: packageJson ?? "",
+        entryRel,
+      });
+      return { archive, hash, entryRel };
+    }
+
+    const bundleOutput = yield* buildBundle(
+      realMain,
+      virtualEntryPlugin(makeBunBootstrap(handler)),
+    );
     const [entryFile, ...chunkFiles] = bundleOutput.files;
-    const archive = yield* zipCode(
-      toBytes(entryFile.content),
-      chunkFiles.map((file) => ({
+    const zipExtras = [
+      ...chunkFiles.map((file) => ({
         path: file.path,
         content: toBytes(file.content),
       })),
+      ...extraFiles,
+      ...installFiles,
+    ];
+    const archive = yield* zipCode(toBytes(entryFile.content), zipExtras);
+    const extraHash = yield* hashExtraFiles(
+      toSharedExtraFiles(props.extraFiles),
     );
-    return { archive, hash: bundleOutput.hash };
+    const hash = yield* sha256Object({
+      bundle: bundleOutput.hash,
+      extra: extraHash,
+      packageJson: packageJson ?? "",
+    });
+    return { archive, hash, entryRel: "index.mjs" };
   });
 
-  const renderUnit = (unitName: string, appDir: string) => `[Unit]
+  const renderUnit = (
+    unitName: string,
+    appDir: string,
+    entryRel: string,
+  ) => `[Unit]
 Description=Alchemy Hetzner Service ${unitName}
 After=network-online.target
 Wants=network-online.target
@@ -226,7 +382,8 @@ Wants=network-online.target
 Type=simple
 WorkingDirectory=${appDir}
 EnvironmentFile=-${appDir}/env
-ExecStart=/root/.bun/bin/bun --no-install ${appDir}/index.mjs
+Environment=HOST=0.0.0.0
+ExecStart=/usr/bin/env node ${appDir}/${entryRel}
 Restart=always
 RestartSec=5
 
@@ -246,6 +403,14 @@ WantedBy=multi-user.target
       }),
     );
 
+  const hetznerTransient = (e: { readonly _tag: string }): boolean =>
+    e._tag === "TooManyRequests" ||
+    e._tag === "ServiceUnavailable" ||
+    e._tag === "InternalServerError" ||
+    e._tag === "BadGateway" ||
+    e._tag === "GatewayTimeout" ||
+    e._tag === "Locked";
+
   const attachAndMount = Effect.fn(function* (input: {
     ssh: SshClient;
     serverId: number;
@@ -254,6 +419,14 @@ WantedBy=multi-user.target
     for (const { volumeId, path } of input.volumes) {
       let volume = yield* Services.volumes.getVolume({ id: volumeId }).pipe(
         Effect.map(({ volume }) => volume),
+        Effect.retry({
+          while: hetznerTransient,
+          times: 8,
+          schedule: Schedule.min([
+            Schedule.exponential(Duration.millis(500), 1.5),
+            Schedule.spaced(Duration.seconds(5)),
+          ]),
+        }),
         Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
       );
       if (volume === undefined) continue;
@@ -276,9 +449,21 @@ WantedBy=multi-user.target
           .attachVolume({
             id: volumeId,
             server: input.serverId,
-            automount: true,
+            // No automount: Hetzner would mount the device at
+            // `/mnt/HC_Volume_{id}`, and a device mounted elsewhere makes
+            // our own `mount` at the service path fail with
+            // "already mounted". We own the mount + fstab below.
+            automount: false,
           })
           .pipe(
+            Effect.retry({
+              while: hetznerTransient,
+              times: 8,
+              schedule: Schedule.min([
+                Schedule.exponential(Duration.millis(500), 1.5),
+                Schedule.spaced(Duration.seconds(5)),
+              ]),
+            }),
             Effect.tap(({ action }) =>
               waitForAction(action).pipe(
                 Effect.catchTag("ActionTimeout", () => Effect.void),
@@ -329,12 +514,41 @@ WantedBy=multi-user.target
       const pathLit = JSON.stringify(path);
       const deviceLit = JSON.stringify(device);
       const fsLit = JSON.stringify(fsType);
+      // Attach returns before udev creates `/dev/disk/by-id/scsi-0HC_Volume_*`.
       yield* input.ssh.exec(
         [
           `set -euo pipefail`,
           `mkdir -p ${pathLit}`,
           `if ! findmnt -n ${pathLit} >/dev/null 2>&1; then`,
-          `  mount -t ${fsLit} ${deviceLit} ${pathLit} || findmnt -n ${pathLit} >/dev/null`,
+          `  udevadm settle --timeout=10 2>/dev/null || true`,
+          `  mounted=0`,
+          `  for i in 1 2 3 4 5 6 7 8 9 10; do`,
+          // A sibling Service sharing the same (volume, path) may have
+          // mounted it between iterations — that IS the desired state.
+          `    if findmnt -n ${pathLit} >/dev/null 2>&1; then`,
+          `      mounted=1`,
+          `      break`,
+          `    fi`,
+          `    if [ -e ${deviceLit} ]; then`,
+          // A previous attach with automount (or a leaked mount from an
+          // interrupted run) may hold the device at /mnt/HC_Volume_* —
+          // "already mounted" would fail our mount at the service path.
+          `      current="$(findmnt -n -o TARGET ${deviceLit} 2>/dev/null || true)"`,
+          `      if [ -n "$current" ] && [ "$current" != ${pathLit} ]; then`,
+          `        umount ${deviceLit} 2>/dev/null || true`,
+          `      fi`,
+          `      if mount -t ${fsLit} ${deviceLit} ${pathLit}; then`,
+          `        mounted=1`,
+          `        break`,
+          `      fi`,
+          `    fi`,
+          `    sleep 2`,
+          `  done`,
+          `  if [ "$mounted" != 1 ]; then`,
+          `    echo "volume ${deviceLit} could not be mounted at ${pathLit}" >&2`,
+          `    ls -l /dev/disk/by-id 2>/dev/null || true`,
+          `    exit 1`,
+          `  fi`,
           `fi`,
           `if ! grep -qF ${pathLit} /etc/fstab; then`,
           `  echo ${JSON.stringify(`${device} ${path} ${fsType} defaults,nofail 0 2`)} >> /etc/fstab`,
@@ -349,6 +563,7 @@ WantedBy=multi-user.target
     unitName: string;
     archive: Uint8Array<ArrayBufferLike>;
     env: Record<string, unknown>;
+    entryRel?: string;
   }) {
     const appDir = `/opt/${input.unitName}`;
     yield* waitForSsh(input.ssh);
@@ -356,21 +571,19 @@ WantedBy=multi-user.target
       [
         `set -uo pipefail`,
         `export HOME=/root`,
-        `export BUN_INSTALL=/root/.bun`,
-        `export PATH="/root/.bun/bin:$PATH"`,
         `mkdir -p ${JSON.stringify(appDir)}`,
-        `if ! command -v curl >/dev/null 2>&1 || ! command -v unzip >/dev/null 2>&1; then`,
+        `if ! command -v curl >/dev/null 2>&1 || ! command -v unzip >/dev/null 2>&1 || ! command -v ca-certificates >/dev/null 2>&1; then`,
         `  apt-get update`,
         `  DEBIAN_FRONTEND=noninteractive apt-get install -y curl unzip ca-certificates`,
         `fi`,
-        `if [ ! -x /root/.bun/bin/bun ]; then`,
+        `if ! command -v node >/dev/null 2>&1 || ! node -e 'process.exit(Number(process.versions.node.split(".")[0])<26)'; then`,
         `  for attempt in 1 2 3 4 5; do`,
-        `    curl -fsSL https://bun.sh/install | bash && break`,
+        `    curl -fsSL https://deb.nodesource.com/setup_26.x | bash - && DEBIAN_FRONTEND=noninteractive apt-get install -y nodejs && break`,
         `    sleep 5`,
         `  done`,
         `fi`,
-        `if [ ! -x /root/.bun/bin/bun ]; then`,
-        `  echo "bun install failed" >&2`,
+        `if ! command -v node >/dev/null 2>&1; then`,
+        `  echo "node install failed" >&2`,
         `  exit 1`,
         `fi`,
       ].join("\n"),
@@ -381,14 +594,20 @@ WantedBy=multi-user.target
       `${appDir}/env`,
     );
     yield* input.ssh.scp(
-      new TextEncoder().encode(renderUnit(input.unitName, appDir)),
+      new TextEncoder().encode(
+        renderUnit(input.unitName, appDir, input.entryRel ?? "index.mjs"),
+      ),
       `/etc/systemd/system/${input.unitName}.service`,
     );
     yield* input.ssh.exec(
       [
-        `set -uo pipefail`,
-        `if [ ! -x /root/.bun/bin/bun ]; then echo "bun missing at start" >&2; exit 1; fi`,
+        `set -euo pipefail`,
+        `export HOME=/root`,
+        `if ! command -v node >/dev/null 2>&1; then echo "node missing at start" >&2; exit 1; fi`,
         `unzip -o ${JSON.stringify(`${appDir}/bundle.zip`)} -d ${JSON.stringify(appDir)}`,
+        `if [ -f ${JSON.stringify(`${appDir}/package.json`)} ]; then`,
+        `  (cd ${JSON.stringify(appDir)} && npm install --omit=dev --no-fund --no-audit)`,
+        `fi`,
         `systemctl daemon-reload`,
         `systemctl enable --now ${input.unitName}.service`,
         `systemctl restart ${input.unitName}.service`,
@@ -403,7 +622,7 @@ WantedBy=multi-user.target
     yield* input.ssh.exec(
       [
         `set -uo pipefail`,
-        `for attempt in 1 2 3 4 5 6 7 8 9 10; do`,
+        `for attempt in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30; do`,
         `  if systemctl is-active --quiet ${input.unitName}.service && ${health}; then`,
         `    exit 0`,
         `  fi`,

package/src/Hetzner/index.ts

@@ -26,6 +26,7 @@ export * from "./Ssh.ts";
 export * from "./SshKey.ts";
 export * from "./Volume.ts";
 export * from "./VolumeAttachment.ts";
+export * as Website from "./Website/index.ts";
 export * from "./WriteDns.ts";
 export * from "./WriteDnsHttp.ts";
 export * from "./Zone.ts";

package/src/Http.ts

@@ -162,7 +162,16 @@ export const BunHttpServer = (serverOptions?: BunHttpServerOptions) =>
     }),
   );
 
-export const NodeHttpServer = () =>
+export interface NodeHttpServerOptions {
+  /**
+   * Address the Node HTTP server binds. Fly / Hetzner / Railway machines
+   * need `0.0.0.0`; omit to use that default.
+   * @default "0.0.0.0"
+   */
+  hostname?: string;
+}
+
+export const NodeHttpServer = (serverOptions?: NodeHttpServerOptions) =>
   Layer.effect(
     HttpServer,
     Effect.gen(function* () {
@@ -176,7 +185,10 @@ export const NodeHttpServer = () =>
             const port = yield* resolvePort(options);
             const server = yield* NodeHttpServerPlatform.make(
               NodeHttp.createServer,
-              { port },
+              {
+                port,
+                host: serverOptions?.hostname ?? "0.0.0.0",
+              },
             );
             yield* server.serve(safeHttpEffect(handler));
           }).pipe(Effect.orDie),

package/src/Kubernetes/HelmChart.ts

@@ -125,9 +125,11 @@ export interface HelmChart extends Resource<
  * target `cluster` can be a managed cluster resource (e.g.
  * `AWS.EKS.Cluster`) or any cluster your kubeconfig can reach.
  *
- * Helm install/upgrade hooks are not executed (objects are applied, not
- * `helm install`ed); charts that depend on hooks for correctness should be
- * installed with Helm directly.
+ * Helm lifecycle hooks (`helm.sh/hook`-annotated objects: install/upgrade/
+ * delete hooks, tests) are neither executed nor applied — the chart is
+ * rendered with `--no-hooks`, so they never enter the managed-object graph.
+ * Charts that depend on hooks for correctness should be installed with Helm
+ * directly.
  * ### Installing a Chart
  * **Example:** Chart from a repository
  * ```typescript

package/src/Kubernetes/internal/helm.ts

@@ -55,10 +55,12 @@ export interface RenderHelmChartOptions {
 }
 
 /**
- * Render a chart with `helm template` and parse the multi-document YAML
- * output into object definitions. Every rendered object must carry
- * `apiVersion`, `kind`, and `metadata.name` (server-side apply needs a
- * name; `generateName`-only objects are rejected with a clear error).
+ * Render a chart with `helm template --no-hooks` and parse the
+ * multi-document YAML output into object definitions. Every rendered object
+ * must carry `apiVersion`, `kind`, and `metadata.name` (server-side apply
+ * needs a name; `generateName`-only objects are rejected with a clear
+ * error). Helm lifecycle hooks are excluded from the result (see
+ * {@link isHelmHook}).
  */
 export const renderHelmChart = Effect.fn(function* (
   options: RenderHelmChartOptions,
@@ -74,6 +76,11 @@ export const renderHelmChart = Effect.fn(function* (
     options.chart,
     "--namespace",
     options.namespace,
+    // Helm lifecycle hooks (`helm.sh/hook`) only make sense under Helm's own
+    // release events; HelmChart server-side applies the render and does not
+    // implement hook timing/weights/delete policies, so a hook (e.g. a
+    // pre-delete uninstall Job) must never enter the managed-object graph.
+    "--no-hooks",
   ];
   if (options.repo !== undefined) {
     args.push("--repo", options.repo);
@@ -135,7 +142,21 @@ export const renderHelmChart = Effect.fn(function* (
   return yield* parseRenderedManifests(options.chart, result.stdout);
 });
 
-/** Parse `helm template` output (multi-document YAML) into definitions. */
+/**
+ * Whether a rendered object is a Helm lifecycle hook (`helm.sh/hook`
+ * annotation). Hooks are executed by Helm at release events (pre-install,
+ * pre-delete, test, …); HelmChart has no release and no hook lifecycle, so
+ * they are filtered out rather than applied as ordinary objects.
+ */
+export const isHelmHook = (object: KubernetesObjectDefinition): boolean =>
+  typeof object.metadata.annotations?.["helm.sh/hook"] === "string";
+
+/**
+ * Parse `helm template` output (multi-document YAML) into definitions.
+ * Hook-annotated objects are dropped — `renderHelmChart` already passes
+ * `--no-hooks`, but the parser enforces the invariant independently of the
+ * helm CLI's behavior.
+ */
 export const parseRenderedManifests = (
   chart: string,
   rendered: string,
@@ -190,7 +211,9 @@ export const parseRenderedManifests = (
           }),
         );
       }
-      objects.push(object as KubernetesObjectDefinition);
+      const definition = object as KubernetesObjectDefinition;
+      if (isHelmHook(definition)) continue;
+      objects.push(definition);
     }
     return objects;
   });