@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/export-resources.ts

@@ -20,33 +20,17 @@ import type { ExportedTemplate, ResourceSelector } from "@intentius/chant/lexico
 import { defaultK8sConnector, type K8sConnector } from "./api/connect";
 import { operationFor } from "./api/operation-surface";
 import { buildExportFromObjects } from "./import/live-export";
+import { DEFAULT_IMPORT_TYPES } from "./api/sweep-types";
 
 /**
  * Entity types a bare `chant import --from <cluster>` sweeps: the workload,
  * config, networking and RBAC kinds people actually author. Everything else is
- * reachable by naming it with `--selector type=...`.
+ * reachable by naming it with `--selector type=...`. Defined in
+ * `./api/sweep-types.ts` and re-exported here, its original home — chant
+ * #1075's ownership-scoped prune needs the same list without pulling the
+ * import parser into a Temporal worker.
  */
-export const DEFAULT_IMPORT_TYPES: readonly string[] = [
-  "K8s::Apps::Deployment",
-  "K8s::Apps::StatefulSet",
-  "K8s::Apps::DaemonSet",
-  "K8s::Apps::ReplicaSet",
-  "K8s::Core::Service",
-  "K8s::Core::ConfigMap",
-  "K8s::Core::Secret",
-  "K8s::Core::Namespace",
-  "K8s::Core::Pod",
-  "K8s::Core::PersistentVolumeClaim",
-  "K8s::Core::ServiceAccount",
-  "K8s::Batch::Job",
-  "K8s::Batch::CronJob",
-  "K8s::Networking::Ingress",
-  "K8s::Networking::NetworkPolicy",
-  "K8s::Rbac::Role",
-  "K8s::Rbac::RoleBinding",
-  "K8s::Rbac::ClusterRole",
-  "K8s::Rbac::ClusterRoleBinding",
-];
+export { DEFAULT_IMPORT_TYPES };
 
 export async function exportResources(
   options: {

package/src/kube/apply.test.ts

@@ -0,0 +1,105 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { runApply } from "./apply";
+import type { ApplyManifestResult } from "../op/activities/kubectl";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+const RESULT: ApplyManifestResult = {
+  fieldManager: "chant",
+  applied: [{ apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" }],
+  pruned: [],
+};
+
+describe("chant kube apply (#1079)", () => {
+  test("without --yes, applyManifest is called with dryRun and nothing is reported as persisted", async () => {
+    const apply = vi.fn().mockResolvedValue(RESULT);
+    const connect = vi.fn();
+    const { log } = spyConsole();
+
+    const code = await runApply(["-f", "manifest.yaml"], { apply, connect });
+
+    expect(code).toBe(0);
+    expect(apply).toHaveBeenCalledWith(expect.objectContaining({ manifest: "manifest.yaml", dryRun: true }), undefined, connect);
+    expect(log.mock.calls[0][0]).toContain("DRY RUN");
+    expect(log.mock.calls[0][0]).toContain("--yes");
+  });
+
+  test("--yes performs the real apply (dryRun: false) and reports what happened", async () => {
+    const apply = vi.fn().mockResolvedValue(RESULT);
+    const connect = vi.fn();
+    const { log } = spyConsole();
+
+    const code = await runApply(["-f", "manifest.yaml", "--yes"], { apply, connect });
+
+    expect(code).toBe(0);
+    expect(apply).toHaveBeenCalledWith(expect.objectContaining({ dryRun: false }), undefined, connect);
+    expect(log.mock.calls[0][0]).toContain("applied 1 object(s)");
+  });
+
+  test("an explicit manifest is mandatory — no bare sweeps", async () => {
+    const apply = vi.fn();
+    const { error } = spyConsole();
+
+    const code = await runApply([], { apply });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("--filename/-f is required");
+    expect(apply).not.toHaveBeenCalled();
+  });
+
+  test("binding mismatch refuses loudly, rendered as NOT-OBSERVED", async () => {
+    const apply = vi.fn().mockRejectedValue(new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks"));
+    const { error } = spyConsole();
+
+    const code = await runApply(["-f", "manifest.yaml", "--env", "prod", "--yes"], { apply });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before apply runs", async () => {
+    const apply = vi.fn();
+    const { error } = spyConsole();
+
+    const code = await runApply(["-f", "manifest.yaml", "--bogus"], { apply });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(apply).not.toHaveBeenCalled();
+  });
+
+  test("a field-manager conflict renders the same conflict surface the Op activity produces, not a raw 409", async () => {
+    class FieldManagerConflictError extends Error {
+      constructor(message: string) {
+        super(message);
+        this.name = "FieldManagerConflictError";
+      }
+    }
+    const apply = vi.fn().mockRejectedValue(new FieldManagerConflictError('k8s: server-side apply of apps/v1 Deployment prod/web was refused'));
+    const { error } = spyConsole();
+
+    const code = await runApply(["-f", "manifest.yaml", "--yes"], { apply });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("was refused");
+  });
+
+  test("tri-state: a transport failure renders NOT-OBSERVED, not a silent no-op", async () => {
+    const err = new Error("connect ECONNREFUSED");
+    (err as { name?: string }).name = "K8sTransportError";
+    const apply = vi.fn().mockRejectedValue(err);
+    const { error } = spyConsole();
+
+    const code = await runApply(["-f", "manifest.yaml", "--yes"], { apply });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+});

package/src/kube/apply.ts

@@ -0,0 +1,101 @@
+/**
+ * `chant kube apply` (chant #1079) — "writes are not cloned": this calls
+ * `applyManifest` (`../op/activities/kubectl.ts`) directly, the exact
+ * function the k8s Op activity registers under `kubectlApply` — server-side
+ * apply, chant's field-manager identity, the same `FieldManagerConflictError`
+ * surface (chant #1075/#1178) — never a second implementation of `kubectl
+ * apply`. An explicit manifest path is mandatory; there is no bare-sweep form.
+ *
+ * The one thing this verb adds on top of the activity is a confirmation
+ * gate, matching the issue's "route through plan, gate, and ownership": a
+ * bare `chant kube apply -f x.yaml` performs a server-side dry run — every
+ * document validated and previewed, nothing persisted — and says so; only
+ * `--yes` performs the real, persisting apply. That is a deliberate
+ * divergence from `kubectl apply`, which persists by default; a terminal
+ * command that can rewrite a live Deployment is worth one extra keystroke of
+ * intent.
+ */
+
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure, isMissingClientPackage, MISSING_CLIENT_DETAIL } from "../api/classify";
+import { applyManifest, type KubectlApplyArgs, type ApplyManifestResult } from "../op/activities/kubectl";
+import { parseKubeFlags } from "./flags";
+
+export type ApplyFn = (args: KubectlApplyArgs, signal?: AbortSignal, connect?: K8sConnector) => Promise<ApplyManifestResult>;
+
+export interface ApplyDeps {
+  connect?: K8sConnector;
+  apply?: ApplyFn;
+}
+
+export async function runApply(rawArgs: string[], deps: ApplyDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+  const apply = deps.apply ?? applyManifest;
+
+  let flags;
+  try {
+    flags = parseKubeFlags(rawArgs, {
+      value: { "-f": "filename", "--filename": "filename", "--field-manager": "fieldManager" },
+      boolean: { "--force-conflicts": "forceConflicts", "--yes": "yes", "-y": "yes" },
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const manifest = flags.values.filename;
+  if (!manifest) {
+    console.error(
+      "error: --filename/-f is required — chant kube apply never applies without an explicit manifest path (no bare sweeps)",
+    );
+    return 1;
+  }
+
+  const dryRun = !(flags.flags.yes ?? false);
+  const args: KubectlApplyArgs = {
+    manifest,
+    ...(flags.values.env !== undefined ? { environment: flags.values.env } : {}),
+    ...(flags.values.context !== undefined ? { context: flags.values.context } : {}),
+    ...(flags.values.fieldManager !== undefined ? { fieldManager: flags.values.fieldManager } : {}),
+    force: flags.flags.forceConflicts ?? false,
+    dryRun,
+  };
+
+  let result: ApplyManifestResult;
+  try {
+    result = await apply(args, undefined, connect);
+  } catch (err) {
+    if (err instanceof Error && err.name === "FieldManagerConflictError") {
+      console.error(err.message);
+      return 1;
+    }
+    if (err instanceof ClusterBindingMismatchError) {
+      console.error(formatUnobserved(manifest, { reason: "no-binding", detail: err.message }));
+      return 1;
+    }
+    if (isMissingClientPackage(err)) {
+      console.error(formatUnobserved(manifest, { reason: "read-failed", detail: MISSING_CLIENT_DETAIL }));
+      return 1;
+    }
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(manifest, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+
+  // applyManifest already logged one line per applied object (including,
+  // since chant #1079, whether it was a dry run) — this is the summary.
+  if (dryRun) {
+    console.log(`DRY RUN — ${result.applied.length} object(s) server-validated, nothing persisted. Pass --yes to apply for real.`);
+  } else {
+    console.log(`applied ${result.applied.length} object(s) as field manager "${result.fieldManager}"`);
+    if (result.pruned.length > 0) console.log(`pruned ${result.pruned.length} chant-owned object(s) no longer declared`);
+  }
+  return 0;
+}

package/src/kube/connect.ts

@@ -0,0 +1,54 @@
+/**
+ * Connecting to a cluster on `chant kube`'s behalf (chant #1079), honoring
+ * the exact same environment→cluster binding every other observing path
+ * does (chant #1100/#1155): `--env` resolves `k8s.profiles.<env>.context`
+ * and refuses loudly on a mismatch, `--context` is an explicit override that
+ * skips the binding entirely, and neither given falls back to the ambient
+ * kubeconfig context — the same three modes `describeResources` and the Op
+ * activities already use, via the same `defaultK8sConnector`. Nothing here
+ * reimplements that resolution; this only turns a connect failure into the
+ * observation tri-state so a verb can render NOT-OBSERVED-with-reason
+ * instead of a stack trace.
+ */
+
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import { defaultK8sConnector, type ConnectOptions, type ConnectedClient, type K8sConnector } from "../api/connect";
+import { classifyApiFailure, isMissingClientPackage, isWholeLexiconFailure, MISSING_CLIENT_DETAIL } from "../api/classify";
+
+export type KubeConnectResult =
+  | ({ kind: "connected" } & ConnectedClient)
+  | { kind: "unobserved"; reason: UnobservedReason; detail: string };
+
+/**
+ * Connect, or classify the failure into the tri-state. A bound-but-mismatched
+ * `--env` (`ClusterBindingMismatchError`), a missing `@intentius/chant-k8s-client`
+ * install, and a refused exec-credential plugin are the "nothing left the
+ * process" failures every verb must treat identically: NOT-OBSERVED, never
+ * an empty/absent result.
+ */
+export async function kubeConnect(
+  options: ConnectOptions,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<KubeConnectResult> {
+  try {
+    const connected = await connect(options);
+    return { kind: "connected", ...connected };
+  } catch (err) {
+    if (isMissingClientPackage(err)) {
+      return { kind: "unobserved", reason: "read-failed", detail: MISSING_CLIENT_DETAIL };
+    }
+    if (err instanceof ClusterBindingMismatchError) {
+      return { kind: "unobserved", reason: "no-binding", detail: err.message };
+    }
+    if (isWholeLexiconFailure(err)) {
+      const outcome = classifyApiFailure(err);
+      return {
+        kind: "unobserved",
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      };
+    }
+    throw err;
+  }
+}

package/src/kube/delete.test.ts

@@ -0,0 +1,123 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster, objectKey, ownedObject } from "../api/fake-cluster";
+import { runDelete } from "./delete";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+describe("chant kube delete (#1079)", () => {
+  test("without --yes, previews the delete and issues no DELETE request", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedObject("apps/v1", "Deployment", "web", "prod") },
+    });
+    const { log } = spyConsole();
+
+    const code = await runDelete(["deployment", "web", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("Would delete");
+    expect(log.mock.calls[0][0]).toContain("--yes");
+    expect(cluster.layer.requests.some((r) => r.method === "DELETE")).toBe(false);
+  });
+
+  test("--yes deletes through the typed client's own delete()", async () => {
+    const cluster = fakeCluster({
+      objects: { [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedObject("apps/v1", "Deployment", "web", "prod") },
+    });
+    const { log } = spyConsole();
+
+    const code = await runDelete(["deployment", "web", "-n", "prod", "--yes"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls.at(-1)?.[0]).toContain("deleted");
+    const deleted = cluster.layer.requests.find((r) => r.method === "DELETE");
+    expect(deleted?.path).toBe("/apis/apps/v1/namespaces/prod/deployments/web");
+  });
+
+  test("a non-chant-owned object gets a visible warning but is still deletable (explicit name = informed decision)", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1" },
+        },
+      },
+    });
+    const { log } = spyConsole();
+
+    const code = await runDelete(["deployment", "web", "-n", "prod", "--yes"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls.map((c) => c[0]).join("\n");
+    expect(out).toContain("no chant ownership marker");
+    expect(out).toContain("deleted");
+  });
+
+  test("explicit-target requirement: a bare kind with no name is refused — no sweeps", async () => {
+    const connect = vi.fn();
+    const { error } = spyConsole();
+
+    const code = await runDelete(["deployment"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no bare kind sweeps");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("a resource that is already gone reports NotFound rather than a silent success", async () => {
+    const cluster = fakeCluster({});
+    const { error } = spyConsole();
+
+    const code = await runDelete(["deployment", "ghost", "-n", "prod", "--yes"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("NotFound");
+  });
+
+  test("binding mismatch refuses loudly, before any read or delete", async () => {
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runDelete(["deployment", "web", "--env", "prod", "--yes"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before any connection", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runDelete(["deployment", "web", "--bogus"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: an RBAC-denied read-before-delete renders NOT-OBSERVED, never a silent delete", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/apis/apps/v1/namespaces/prod/deployments/web"
+          ? { status: 403, body: { kind: "Status", reason: "Forbidden", message: "forbidden" } }
+          : undefined,
+    });
+    const { error, log } = spyConsole();
+
+    const code = await runDelete(["deployment", "web", "-n", "prod", "--yes"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no credentials");
+    expect(log).not.toHaveBeenCalled();
+    expect(cluster.layer.requests.some((r) => r.method === "DELETE")).toBe(false);
+  });
+});

package/src/kube/delete.ts

@@ -0,0 +1,174 @@
+/**
+ * `chant kube delete` (chant #1079) — routes through the typed client's own
+ * `delete()` (`packages/k8s-client/src/client.ts`), the identical typed
+ * delete `applyManifest`'s prune step already uses (chant #1075) — never a
+ * second implementation. A kind and a name are both mandatory: there is no
+ * bare `chant kube delete deployments` form, so nothing here can become a
+ * sweep by omission (the issue's "nothing destructive happens without an
+ * explicit resource argument").
+ *
+ * Two guardrails on top of the typed delete itself:
+ *
+ * - **Gate.** A bare invocation reads the object, reports what it found (and
+ *   whether chant owns it), and stops — only `--yes` performs the delete.
+ * - **Ownership, surfaced not enforced.** kubectl itself deletes anything
+ *   RBAC allows, chant-applied or not, and this keeps that: an explicit name
+ *   is already an informed decision. What's added is visibility — a
+ *   warning when the object carries no chant ownership marker, so the
+ *   operator knows they are about to delete something chant did not apply.
+ */
+
+import type { K8sClient } from "@intentius/chant-k8s-client";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { formatUnobserved, type UnobservedReason } from "@intentius/chant/observation";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom } from "./flags";
+import { loadKubeProjectContext, type KubeProjectContext } from "./project";
+import { resolveKubeTarget, isTargetError, type KubeTarget } from "./target";
+
+export interface DeleteDeps {
+  connect?: K8sConnector;
+  loadProject?: (cwd?: string) => Promise<KubeProjectContext | undefined>;
+}
+
+function targetLabel(target: KubeTarget): string {
+  return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+
+const PROPAGATION_POLICIES = new Set(["Foreground", "Background", "Orphan"]);
+
+export async function runDelete(rawArgs: string[], deps: DeleteDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+  const loadProject = deps.loadProject ?? loadKubeProjectContext;
+
+  let flags;
+  try {
+    flags = parseKubeFlags(rawArgs, {
+      value: { "--propagation-policy": "propagationPolicy" },
+      boolean: { "--yes": "yes", "-y": "yes" },
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  if (flags.values.propagationPolicy !== undefined && !PROPAGATION_POLICIES.has(flags.values.propagationPolicy)) {
+    console.error(`error: --propagation-policy must be one of Foreground, Background, Orphan`);
+    return 1;
+  }
+
+  const project = await loadProject();
+  const target = resolveKubeTarget(flags.positional, flags.values.namespace, project);
+  if (isTargetError(target)) {
+    console.error(`error: ${target.error}`);
+    return 1;
+  }
+  if (!target.name) {
+    console.error(
+      "error: chant kube delete requires an explicit resource name — no bare kind sweeps " +
+        "(e.g. `chant kube delete deployment web`, not `chant kube delete deployment`)",
+    );
+    return 1;
+  }
+
+  const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+  if (connected.kind === "unobserved") {
+    console.error(formatUnobserved(targetLabel(target), { reason: connected.reason, detail: connected.detail }));
+    return 1;
+  }
+  const { client } = connected;
+
+  let info;
+  try {
+    info = await client.resolve(target.selector);
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    console.error(
+      formatUnobserved(targetLabel(target), {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+  if (!info) {
+    console.error(`error: the server doesn't have a resource type "${targetLabel(target)}"`);
+    return 1;
+  }
+
+  const namespace = target.namespace ?? client.defaultNamespace;
+  const ref = { apiVersion: info.apiVersion, kind: info.kind, name: target.name, namespace };
+
+  const object = await readForDelete(client, ref);
+  if (object.kind === "unobserved") {
+    console.error(formatUnobserved(`${info.kind}/${target.name}`, { reason: object.reason, detail: object.detail }));
+    return 1;
+  }
+  if (!object.found) {
+    console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+    return 1;
+  }
+
+  const owned = hasOwnershipMarker(object.labels, LABEL_OWNERSHIP_KEYS);
+  const label = `${info.kind}/${target.name}${namespace ? ` -n ${namespace}` : ""}`;
+
+  if (!(flags.flags.yes ?? false)) {
+    console.log(`Would delete ${label}${owned ? "" : " (warning: not chant-owned)"}. Pass --yes to delete for real.`);
+    return 0;
+  }
+
+  if (!owned) {
+    console.log(`warning: ${label} carries no chant ownership marker — deleting an object chant did not apply`);
+  }
+
+  try {
+    await client.delete(
+      { apiVersion: info.apiVersion, kind: info.kind, name: target.name, ...(namespace ? { namespace } : {}) },
+      { ...(flags.values.propagationPolicy ? { propagationPolicy: flags.values.propagationPolicy as "Foreground" | "Background" | "Orphan" } : {}) },
+    );
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    if (outcome.kind === "absent") {
+      console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+      return 1;
+    }
+    console.error(
+      formatUnobserved(label, {
+        reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+        detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+      }),
+    );
+    return 1;
+  }
+
+  console.log(`${label} deleted`);
+  return 0;
+}
+
+type ReadForDeleteResult =
+  | { kind: "found"; found: true; labels: Record<string, string> | undefined }
+  | { kind: "found"; found: false; labels: undefined }
+  | { kind: "unobserved"; reason: UnobservedReason; detail: string };
+
+async function readForDelete(
+  client: K8sClient,
+  ref: { apiVersion: string; kind: string; name: string; namespace?: string },
+): Promise<ReadForDeleteResult> {
+  try {
+    const obj = await client.readIfPresent(ref);
+    return obj ? { kind: "found", found: true, labels: obj.metadata?.labels } : { kind: "found", found: false, labels: undefined };
+  } catch (err) {
+    if (err instanceof ClusterBindingMismatchError) {
+      return { kind: "unobserved", reason: "no-binding", detail: err.message };
+    }
+    const outcome = classifyApiFailure(err);
+    return {
+      kind: "unobserved",
+      reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+      detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+    };
+  }
+}