@intentius/chant-k8s-client 0.31.0 → 0.32.0

package/src/client.test.ts

@@ -12,7 +12,8 @@
 
 import { describe, test, expect } from "vitest";
 import { createK8sClient } from "./client";
-import { K8sApiError, K8sTransportError, ExecCredentialNotAllowedError, KubeConfigError, UnknownResourceError } from "./errors";
+import { K8sApiError, K8sTransportError, ExecCredentialNotAllowedError, FieldManagerError, KubeConfigError, UnknownResourceError } from "./errors";
+import { FieldManagerConflictError } from "./conflict";
 import { apiResourceList, fakeKubeconfig, fakeRequestLayer, statusBody } from "./testing";
 import type { RecordedRequest } from "./testing";
 
@@ -358,6 +359,110 @@ describe("list", () => {
     await c.list({ apiVersion: "apps/v1", kind: "Deployment" }, { namespace: "prod" });
     expect(layer.paths()).toContain("/apis/apps/v1/namespaces/prod/deployments");
   });
+
+  test("a label selector is sent to the server, not filtered afterwards (chant #1075)", async () => {
+    const layer = cluster({ "/apis/apps/v1/namespaces/prod/deployments": { items: [deployment("a")] } });
+    const c = await client(layer);
+    await c.list(
+      { apiVersion: "apps/v1", kind: "Deployment" },
+      { namespace: "prod", labelSelector: "app.kubernetes.io/managed-by=chant" },
+    );
+    const listed = layer.requests.find((r) => r.path === "/apis/apps/v1/namespaces/prod/deployments")!;
+    expect(listed.query.labelSelector).toBe("app.kubernetes.io/managed-by=chant");
+  });
+});
+
+describe("readLog (chant #1079)", () => {
+  test("GETs the pod's /log subresource and returns the raw text, not JSON", async () => {
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in ROOT_DISCOVERY) return { body: ROOT_DISCOVERY[req.path] };
+      if (req.path === "/api/v1/namespaces/prod/pods/web/log") {
+        return { body: "line one\nline two\n" };
+      }
+      return { status: 404, body: statusBody(404, "NotFound", "no") };
+    });
+    const c = await client(layer as unknown as ReturnType<typeof cluster>);
+    const text = await c.readLog({ apiVersion: "v1", kind: "Pod", name: "web", namespace: "prod" });
+    expect(text).toBe("line one\nline two\n");
+  });
+
+  test("container, tailLines, sinceSeconds, previous and timestamps are query parameters", async () => {
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in ROOT_DISCOVERY) return { body: ROOT_DISCOVERY[req.path] };
+      if (req.path === "/api/v1/namespaces/prod/pods/web/log") return { body: "" };
+      return { status: 404, body: statusBody(404, "NotFound", "no") };
+    });
+    const c = await client(layer as unknown as ReturnType<typeof cluster>);
+    await c.readLog(
+      { apiVersion: "v1", kind: "Pod", name: "web", namespace: "prod" },
+      { container: "app", tailLines: 50, sinceSeconds: 3600, previous: true, timestamps: true },
+    );
+    const req = layer.requests.find((r) => r.path === "/api/v1/namespaces/prod/pods/web/log")!;
+    expect(req.query).toEqual({
+      container: "app",
+      tailLines: "50",
+      sinceSeconds: "3600",
+      previous: "true",
+      timestamps: "true",
+    });
+  });
+
+  test("a failure is a typed K8sApiError, not a swallowed empty string", async () => {
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in ROOT_DISCOVERY) return { body: ROOT_DISCOVERY[req.path] };
+      return { status: 404, body: statusBody(404, "NotFound", 'pods "web" not found') };
+    });
+    const c = await client(layer as unknown as ReturnType<typeof cluster>);
+    const err = (await c
+      .readLog({ apiVersion: "v1", kind: "Pod", name: "web", namespace: "prod" })
+      .catch((e: unknown) => e)) as K8sApiError;
+    expect(err).toBeInstanceOf(K8sApiError);
+    expect(err.notFound).toBe(true);
+  });
+
+  test("an unresolvable kind throws UnknownResourceError before any log request", async () => {
+    const layer = fakeRequestLayer((req) => {
+      if (req.path in ROOT_DISCOVERY) return { body: ROOT_DISCOVERY[req.path] };
+      return { status: 404, body: statusBody(404, "NotFound", "no") };
+    });
+    const c = await client(layer as unknown as ReturnType<typeof cluster>);
+    await expect(
+      c.readLog({ apiVersion: "v1", kind: "Widget", name: "web", namespace: "prod" }),
+    ).rejects.toThrow(UnknownResourceError);
+    expect(layer.requests.some((r) => r.path.endsWith("/log"))).toBe(false);
+  });
+});
+
+describe("delete (chant #1075 — the prune path)", () => {
+  test("DELETEs the addressed object", async () => {
+    const layer = cluster({}, (req) => (req.method === "DELETE" ? { body: statusBody(200, "", "ok") } : undefined));
+    const c = await client(layer);
+    await c.delete({ apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" });
+    const deleted = layer.requests.find((r) => r.method === "DELETE")!;
+    expect(deleted.path).toBe("/apis/apps/v1/namespaces/prod/deployments/web");
+    expect(deleted.query.propagationPolicy).toBeUndefined();
+  });
+
+  test("a propagation policy and a dry run are query parameters", async () => {
+    const layer = cluster({}, (req) => (req.method === "DELETE" ? { body: {} } : undefined));
+    const c = await client(layer);
+    await c.delete(
+      { apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" },
+      { propagationPolicy: "Foreground", dryRun: true },
+    );
+    const deleted = layer.requests.find((r) => r.method === "DELETE")!;
+    expect(deleted.query).toMatchObject({ propagationPolicy: "Foreground", dryRun: "All" });
+  });
+
+  test("a 404 surfaces as a typed notFound rather than being swallowed", async () => {
+    const layer = cluster();
+    const c = await client(layer);
+    const err = (await c
+      .delete({ apiVersion: "apps/v1", kind: "Deployment", name: "gone", namespace: "prod" })
+      .catch((e: unknown) => e)) as K8sApiError;
+    expect(err).toBeInstanceOf(K8sApiError);
+    expect(err.notFound).toBe(true);
+  });
 });
 
 describe("apply", () => {
@@ -397,6 +502,37 @@ describe("apply", () => {
     expect(err.apiMessage).toContain("conflict with");
   });
 
+  test("that 409 is presented, naming the owner and the contested paths (chant #1075)", async () => {
+    const conflict = {
+      ...statusBody(409, "Conflict", 'Apply failed with 1 conflict: conflict with "helm" using apps/v1'),
+      details: {
+        causes: [
+          { type: "FieldManagerConflict", message: 'conflict with "helm" using apps/v1', field: ".spec.replicas" },
+        ],
+      },
+    };
+    const layer = cluster({}, (req) => (req.method === "PATCH" ? { status: 409, body: conflict } : undefined));
+    const c = await client(layer);
+    const err = (await c
+      .apply(deployment("web") as never, { fieldManager: "chant:web" })
+      .catch((e: unknown) => e)) as FieldManagerConflictError;
+
+    expect(err).toBeInstanceOf(FieldManagerConflictError);
+    expect(err.byManager).toEqual({ helm: [".spec.replicas"] });
+    expect(err.fieldManager).toBe("chant:web");
+    expect(err.message).toContain("apps/v1 Deployment prod/web");
+    expect(err.message).toContain("chant does not force this for you");
+  });
+
+  test("a field manager the API server would reject is refused before any request", async () => {
+    const layer = cluster();
+    const c = await client(layer);
+    await expect(c.apply(deployment("web") as never, { fieldManager: "chant web" })).rejects.toThrow(
+      FieldManagerError,
+    );
+    expect(layer.requests).toHaveLength(0);
+  });
+
   test("an object missing apiVersion/kind/name is refused before any request", async () => {
     const layer = cluster();
     const c = await client(layer);

package/src/client.ts

@@ -44,6 +44,8 @@ import {
   UnknownResourceError,
 } from "./errors";
 import { assertExecCredentialAllowed, credentialPathOf, DEFAULT_EXEC_ALLOWLIST } from "./credentials";
+import { asFieldManagerConflict } from "./conflict";
+import { assertValidFieldManager, CHANT_FIELD_MANAGER } from "./field-manager";
 import { DEFAULT_CONCURRENCY, mapConcurrent } from "./concurrency";
 import type {
   ApiResourceInfo,
@@ -120,12 +122,17 @@ export interface ReadOptions {
 
 /** Options for {@link K8sClient.apply}. */
 export interface ApplyOptions {
-  /** Field manager recorded on the objects this apply owns. Default `chant`. */
+  /**
+   * Field manager recorded on the fields this apply owns. Defaults to the bare
+   * `chant`; the k8s lexicon passes the stack-qualified `chant:<stack>` derived
+   * by {@link import("./field-manager").fieldManagerFor} (chant #1075).
+   */
   fieldManager?: string;
   /**
    * Take ownership of fields another manager owns instead of failing with a
-   * 409. Default false — chant #1075 is where the conflict surface proper
-   * lives; here a conflict simply arrives as a typed {@link K8sApiError}.
+   * {@link import("./conflict").FieldManagerConflictError}. **Default false,
+   * and nothing in chant sets it for you** — transferring ownership of a live
+   * field is a decision, not a retry (chant #1075).
    */
   force?: boolean;
   /** Server-side dry run — validates and returns the result, persists nothing. */
@@ -133,6 +140,39 @@ export interface ApplyOptions {
   signal?: AbortSignal;
 }
 
+/** Options for {@link K8sClient.delete}. */
+export interface DeleteOptions {
+  /** `Foreground`, `Background` or `Orphan`. Omitted leaves the server's default. */
+  propagationPolicy?: "Foreground" | "Background" | "Orphan";
+  /** Server-side dry run — validates, deletes nothing. */
+  dryRun?: boolean;
+  signal?: AbortSignal;
+}
+
+/** Options for {@link K8sClient.list}. */
+export interface ListOptions {
+  /** Restrict to one namespace. Omitted lists across all of them. */
+  namespace?: string;
+  /** A label selector, e.g. `app.kubernetes.io/managed-by=chant`. */
+  labelSelector?: string;
+  signal?: AbortSignal;
+}
+
+/** Options for {@link K8sClient.readLog} (chant #1079). */
+export interface ReadLogOptions {
+  /** Container name. Required by the API server when a Pod has more than one. */
+  container?: string;
+  /** Read the previous (crashed/restarted) container instance's log. */
+  previous?: boolean;
+  /** Only the last N lines. */
+  tailLines?: number;
+  /** Only entries from the last N seconds. */
+  sinceSeconds?: number;
+  /** Prefix each line with its RFC3339 timestamp. */
+  timestamps?: boolean;
+  signal?: AbortSignal;
+}
+
 /** The client surface the k8s lexicon consumes. */
 export interface K8sClient {
   /** Where this client is pointed and what authorized it. */
@@ -149,10 +189,22 @@ export interface K8sClient {
   read(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject>;
   /** GET one object, returning undefined instead of throwing on a 404. */
   readIfPresent(ref: ObjectRef, options?: ReadOptions): Promise<K8sObject | undefined>;
-  /** LIST a kind, optionally namespaced. Follows `continue` tokens. */
-  list(selector: ResourceSelector, options?: { namespace?: string; signal?: AbortSignal }): Promise<K8sObject[]>;
+  /** LIST a kind, optionally namespaced and label-filtered. Follows `continue` tokens. */
+  list(selector: ResourceSelector, options?: ListOptions): Promise<K8sObject[]>;
+  /**
+   * GET a Pod's `/log` subresource — plain text, not JSON, which is why this
+   * is its own method rather than a `read` variant. A snapshot only: the
+   * server's log endpoint supports `follow` as a chunked stream, but this
+   * client's transport seam (`ResponseContextLike.body.text()`) reads a
+   * response to completion rather than exposing it as a stream, so `--follow`
+   * is out of reach without widening that seam — chant #1079 leaves it there
+   * deliberately rather than half-implementing it.
+   */
+  readLog(ref: ObjectRef, options?: ReadLogOptions): Promise<string>;
   /** Server-side apply one object. Creates it when absent. */
   apply(object: K8sObject, options?: ApplyOptions): Promise<K8sObject>;
+  /** DELETE one object. Throws {@link K8sApiError} with `notFound` when absent. */
+  delete(ref: ObjectRef, options?: DeleteOptions): Promise<void>;
   /** Run `fn` over `items` with this client's concurrency ceiling. */
   concurrently<T, R>(items: readonly T[], fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
   /** The API resource lists discovery has been asked for so far, for tests and diagnostics. */
@@ -475,14 +527,14 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     }
   }
 
-  async function list(
-    selector: ResourceSelector,
-    opts: { namespace?: string; signal?: AbortSignal } = {},
-  ): Promise<K8sObject[]> {
+  async function list(selector: ResourceSelector, opts: ListOptions = {}): Promise<K8sObject[]> {
     const info = await resolveOrThrow(selector, opts.signal);
     const items: K8sObject[] = [];
     let cont: string | undefined;
     do {
+      const query: Record<string, string> = {};
+      if (cont) query.continue = cont;
+      if (opts.labelSelector) query.labelSelector = opts.labelSelector;
       const page = await sendJson<{ items?: K8sObject[]; metadata?: { continue?: string } }>(
         // Omitting the namespace segment lists across all namespaces, which is
         // what `kubectl get <kind> -A` does and what the import path wants.
@@ -492,7 +544,7 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
         "GET",
         {
           signal: opts.signal,
-          query: cont ? { continue: cont } : undefined,
+          query: Object.keys(query).length > 0 ? query : undefined,
           target: `list ${selectorText(selector)}`,
         },
       );
@@ -514,20 +566,64 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     if (!name) {
       throw new KubeConfigError(`cannot apply a ${apiVersion} ${kind} without metadata.name`);
     }
+    const fieldManager = opts.fieldManager ?? CHANT_FIELD_MANAGER;
+    // Checked before the request so an unusable identity is reported against
+    // the config that produced it, not as a 400 from the cluster.
+    assertValidFieldManager(fieldManager);
     const info = await resolveOrThrow({ apiVersion, kind }, opts.signal);
     const query: Record<string, string> = {
-      fieldManager: opts.fieldManager ?? "chant",
+      fieldManager,
       force: String(opts.force ?? false),
     };
     if (opts.dryRun) query.dryRun = "All";
-    return sendJson<K8sObject>(objectPath(info, name, object.metadata?.namespace), "PATCH", {
-      // Server-side apply. JSON is valid YAML, so the JSON body is accepted
-      // under the apply-patch content type without a YAML round trip.
-      contentType: "application/apply-patch+yaml",
-      body: JSON.stringify(object),
-      query,
+    try {
+      return await sendJson<K8sObject>(objectPath(info, name, object.metadata?.namespace), "PATCH", {
+        // Server-side apply. JSON is valid YAML, so the JSON body is accepted
+        // under the apply-patch content type without a YAML round trip.
+        contentType: "application/apply-patch+yaml",
+        body: JSON.stringify(object),
+        query,
+        signal: opts.signal,
+        target: refText({ apiVersion, kind, name, namespace: object.metadata?.namespace }),
+      });
+    } catch (err) {
+      // A 409 here is the one Kubernetes failure that already carries a
+      // machine-readable account of itself; chant #1075 presents it rather
+      // than letting a one-line 409 stand in for it.
+      throw asFieldManagerConflict(err, fieldManager);
+    }
+  }
+
+  async function readLog(ref: ObjectRef, opts: ReadLogOptions = {}): Promise<string> {
+    const info = await resolveOrThrow({ apiVersion: ref.apiVersion, kind: ref.kind }, opts.signal);
+    const query: Record<string, string> = {};
+    if (opts.container) query.container = opts.container;
+    if (opts.previous) query.previous = "true";
+    if (opts.tailLines !== undefined) query.tailLines = String(opts.tailLines);
+    if (opts.sinceSeconds !== undefined) query.sinceSeconds = String(opts.sinceSeconds);
+    if (opts.timestamps) query.timestamps = "true";
+
+    const target = `${refText(ref)} logs`;
+    const { status, body } = await send(`${objectPath(info, ref.name, ref.namespace)}/log`, "GET", {
+      query: Object.keys(query).length > 0 ? query : undefined,
+      signal: opts.signal,
+      target,
+    });
+    if (status < 200 || status > 299) {
+      throw K8sApiError.fromResponse(status, body, target);
+    }
+    return body;
+  }
+
+  async function remove(ref: ObjectRef, opts: DeleteOptions = {}): Promise<void> {
+    const info = await resolveOrThrow({ apiVersion: ref.apiVersion, kind: ref.kind }, opts.signal);
+    const query: Record<string, string> = {};
+    if (opts.propagationPolicy) query.propagationPolicy = opts.propagationPolicy;
+    if (opts.dryRun) query.dryRun = "All";
+    await sendJson<unknown>(objectPath(info, ref.name, ref.namespace), "DELETE", {
       signal: opts.signal,
-      target: refText({ apiVersion, kind, name, namespace: object.metadata?.namespace }),
+      query: Object.keys(query).length > 0 ? query : undefined,
+      target: refText(ref),
     });
   }
 
@@ -538,7 +634,9 @@ export async function createK8sClient(options: K8sClientOptions = {}): Promise<K
     read,
     readIfPresent,
     list,
+    readLog,
     apply,
+    delete: remove,
     concurrently: (items, fn) => mapConcurrent(items, fn, concurrency),
     discoveryCacheKeys: () => [...discoveryCache.keys()].sort(),
   };

package/src/conflict.test.ts

@@ -0,0 +1,209 @@
+/**
+ * The conflict surface (chant #1075).
+ *
+ * The `Status` bodies below are shaped like real API-server output for a
+ * refused server-side apply: `details.causes` on a current server, and the
+ * prose-only form some aggregated/older servers send instead.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  FieldManagerConflictError,
+  asFieldManagerConflict,
+  parseConflictMessage,
+  parseFieldConflicts,
+  renderConflictReport,
+} from "./conflict";
+import { K8sApiError, type K8sStatus } from "./errors";
+
+const CAUSES_STATUS: K8sStatus = {
+  kind: "Status",
+  apiVersion: "v1",
+  status: "Failure",
+  reason: "Conflict",
+  code: 409,
+  message:
+    'Apply failed with 2 conflicts: conflicts with "kubectl-client-side-apply" using apps/v1:\n' +
+    "- .spec.replicas\n" +
+    '- .spec.template.spec.containers[name="web"].image',
+  details: {
+    causes: [
+      {
+        type: "FieldManagerConflict",
+        message: 'conflict with "kubectl-client-side-apply" using apps/v1',
+        field: ".spec.replicas",
+      },
+      {
+        type: "FieldManagerConflict",
+        message: 'conflict with "kubectl-client-side-apply" using apps/v1',
+        field: '.spec.template.spec.containers[name="web"].image',
+      },
+    ],
+  },
+};
+
+function apiError(status: K8sStatus, target = "apps/v1 Deployment prod/web"): K8sApiError {
+  return new K8sApiError(409, status.reason, status.message ?? "", target, status);
+}
+
+describe("parsing the conflict out of the Status", () => {
+  test("details.causes is the machine-readable form and is used when present", () => {
+    expect(parseFieldConflicts(CAUSES_STATUS)).toEqual([
+      { manager: "kubectl-client-side-apply", field: ".spec.replicas", apiVersion: "apps/v1" },
+      {
+        manager: "kubectl-client-side-apply",
+        field: '.spec.template.spec.containers[name="web"].image',
+        apiVersion: "apps/v1",
+      },
+    ]);
+  });
+
+  test("two managers in one refusal are kept apart", () => {
+    const conflicts = parseFieldConflicts({
+      reason: "Conflict",
+      details: {
+        causes: [
+          { type: "FieldManagerConflict", message: 'conflict with "helm"', field: ".spec.replicas" },
+          { type: "FieldManagerConflict", message: 'conflict with "argo"', field: ".metadata.labels.env" },
+        ],
+      },
+    });
+    expect(conflicts.map((c) => c.manager)).toEqual(["helm", "argo"]);
+  });
+
+  test("a cause of some other type is not read as a field conflict", () => {
+    expect(
+      parseFieldConflicts({
+        reason: "Conflict",
+        details: { causes: [{ type: "FieldValueInvalid", message: "bad", field: ".spec.replicas" }] },
+      }),
+    ).toEqual([]);
+  });
+
+  test("the prose form is parsed when the server sent no causes", () => {
+    expect(
+      parseConflictMessage(
+        'Apply failed with 2 conflicts: conflicts with "kubectl" using apps/v1:\n' +
+          "- .spec.replicas\n" +
+          "- .spec.paused",
+      ),
+    ).toEqual([
+      { manager: "kubectl", field: ".spec.replicas", apiVersion: "apps/v1" },
+      { manager: "kubectl", field: ".spec.paused", apiVersion: "apps/v1" },
+    ]);
+  });
+
+  test("the prose form with several managers attributes each block to its own", () => {
+    const conflicts = parseConflictMessage(
+      'Apply failed with 2 conflicts: conflicts with "helm":\n' +
+        "- .spec.replicas\n" +
+        'conflicts with "argocd":\n' +
+        "- .metadata.labels.env",
+    );
+    expect(conflicts).toEqual([
+      { manager: "helm", field: ".spec.replicas" },
+      { manager: "argocd", field: ".metadata.labels.env" },
+    ]);
+  });
+
+  test("a single inline conflict is read out of the header line", () => {
+    expect(parseConflictMessage('Apply failed with 1 conflict: conflict with "kubectl": .spec.replicas')).toEqual([
+      { manager: "kubectl", field: ".spec.replicas" },
+    ]);
+  });
+
+  test("a message that names nothing parseable yields nothing rather than a guess", () => {
+    expect(parseConflictMessage("the object has been modified")).toEqual([]);
+    expect(parseFieldConflicts(undefined, "")).toEqual([]);
+  });
+});
+
+describe("FieldManagerConflictError", () => {
+  const error = asFieldManagerConflict(apiError(CAUSES_STATUS), "chant:web") as FieldManagerConflictError;
+
+  test("it is still a K8sApiError, so nothing that caught 409s stops working", () => {
+    expect(error).toBeInstanceOf(FieldManagerConflictError);
+    expect(error).toBeInstanceOf(K8sApiError);
+    expect(error.statusCode).toBe(409);
+    expect(error.conflict).toBe(true);
+    expect(error.name).toBe("FieldManagerConflictError");
+  });
+
+  test("it names the competing manager and the contested paths", () => {
+    expect(error.managers).toEqual(["kubectl-client-side-apply"]);
+    expect(error.fields).toEqual([
+      ".spec.replicas",
+      '.spec.template.spec.containers[name="web"].image',
+    ]);
+    expect(error.byManager).toEqual({
+      "kubectl-client-side-apply": [
+        ".spec.replicas",
+        '.spec.template.spec.containers[name="web"].image',
+      ],
+    });
+  });
+
+  test("it records which manager chant applied as", () => {
+    expect(error.fieldManager).toBe("chant:web");
+  });
+
+  test("the message names the object, the owner, every field, and the way out", () => {
+    const text = error.message;
+    expect(text).toContain("apps/v1 Deployment prod/web");
+    expect(text).toContain('"kubectl-client-side-apply" owns:');
+    expect(text).toContain(".spec.replicas");
+    expect(text).toContain('.spec.template.spec.containers[name="web"].image');
+    expect(text).toContain('chant applied as field manager "chant:web"');
+    expect(text).toContain("chant does not force this for you");
+    expect(text).toContain("force-conflicts");
+  });
+
+  test("nothing in the rendering recommends forcing — both ways out are stated", () => {
+    expect(error.message).toContain("remove the contested fields from your chant source");
+    expect(error.message).toContain("deliberately");
+  });
+
+  test("a 409 with no parseable causes still says what happened and quotes the server", () => {
+    const bare = asFieldManagerConflict(
+      apiError({ reason: "Conflict", code: 409, message: "the object has been modified" }),
+      "chant",
+    ) as FieldManagerConflictError;
+    expect(bare.conflicts).toEqual([]);
+    expect(bare.message).toContain("the object has been modified");
+    expect(bare.message).toContain('field manager "chant"');
+  });
+
+  test("singular and plural both read correctly", () => {
+    const one = renderConflictReport({
+      conflicts: [{ manager: "helm", field: ".spec.replicas" }],
+      fieldManager: "chant",
+      target: "apps/v1 Deployment prod/web",
+    });
+    expect(one).toContain("1 field is owned by another field manager");
+    const two = renderConflictReport({
+      conflicts: [
+        { manager: "helm", field: ".spec.replicas" },
+        { manager: "helm", field: ".spec.paused" },
+      ],
+      fieldManager: "chant",
+    });
+    expect(two).toContain("2 fields are owned by another field manager");
+  });
+});
+
+describe("asFieldManagerConflict is a narrowing, not a catch-all", () => {
+  test("a non-409 API error passes through untouched", () => {
+    const notFound = new K8sApiError(404, "NotFound", "not found", "apps/v1 Deployment prod/web");
+    expect(asFieldManagerConflict(notFound, "chant")).toBe(notFound);
+  });
+
+  test("something that is not an API error at all passes through untouched", () => {
+    const boom = new Error("socket hang up");
+    expect(asFieldManagerConflict(boom, "chant")).toBe(boom);
+  });
+
+  test("an already-presented conflict is not re-wrapped", () => {
+    const once = asFieldManagerConflict(apiError(CAUSES_STATUS), "chant:web");
+    expect(asFieldManagerConflict(once, "chant:web")).toBe(once);
+  });
+});