@intentius/chant-lexicon-k8s 0.124.31 → 0.124.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.124.31",
+  "version": "0.124.33",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -32,32 +32,32 @@
     ".": {
       "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
-      "default": "./src/index.ts"
+      "default": "./dist/index.js"
     },
     "./*": {
       "development": "./src/*.ts",
       "types": "./dist/*.d.ts",
-      "default": "./src/*.ts"
+      "default": "./dist/*.js"
     },
     "./detect": {
       "development": "./src/detect.ts",
       "types": "./dist/detect.d.ts",
-      "default": "./src/detect.ts"
+      "default": "./dist/detect.js"
     },
     "./components": {
       "development": "./src/components/index.ts",
       "types": "./dist/components/index.d.ts",
-      "default": "./src/components/index.ts"
+      "default": "./dist/components/index.js"
     },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
-      "default": "./src/lint/post-synth/index.ts"
+      "default": "./dist/lint/post-synth/index.js"
     },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
-      "default": "./src/op/activities/index.ts"
+      "default": "./dist/op/activities/index.js"
     },
     "./manifest": "./dist/manifest.json",
     "./meta": "./dist/meta.json",
@@ -69,16 +69,16 @@
     "validate": "tsx src/validate-cli.ts",
     "docs": "tsx src/codegen/docs-cli.ts",
     "prepack": "npm run generate && npm run bundle && npm run validate && npm run build",
-    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete && cp src/generated/index.d.ts dist/generated/index.d.d.ts"
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json --sourceMap false && tsc-alias -p tsconfig.build.json && cp src/generated/index.d.ts dist/generated/index.d.d.ts"
   },
   "dependencies": {
-    "@intentius/chant-lexicon-otel": "^0.124.31",
-    "@intentius/chant-lexicon-prometheus": "^0.124.31",
+    "@intentius/chant-lexicon-otel": "^0.124.33",
+    "@intentius/chant-lexicon-prometheus": "^0.124.33",
     "js-yaml": "^4.3.1",
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.124.31"
+    "@intentius/chant-k8s-client": "^0.124.33"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -86,6 +86,6 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.124.31"
+    "@intentius/chant": "^0.124.33"
   }
 }

package/src/api/operation-surface.ts

@@ -13,8 +13,9 @@
  */
 
 import { createRequire } from "module";
+import { moduleSourceUrl } from "@intentius/chant/module-source";
 
-const require = createRequire(import.meta.url);
+const require = createRequire(moduleSourceUrl(import.meta.url));
 
 /** One resource's addressing information, as `chant generate` emits it. */
 export interface K8sOperationDescriptor {

package/src/codegen/package.ts

@@ -6,7 +6,7 @@
 import { readFileSync } from "fs";
 import { k8sPlugin } from "../plugin";
 import { join, dirname } from "path";
-import { fileURLToPath } from "url";
+import { moduleSourceDir } from "@intentius/chant/module-source";
 import {
   packagePipeline,
   collectSkills,
@@ -17,7 +17,7 @@ import { generate } from "./generate";
 
 export type { PackageOptions, PackageResult };
 
-const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+const pkgDir = dirname(moduleSourceDir(import.meta.url));
 
 /**
  * Package the Kubernetes lexicon into a distributable BundleSpec.

package/src/components/index.ts

@@ -16,8 +16,11 @@ export * from "./builders";
 export {
   kubectlApplyCapability,
   createKubectlApplyCapability,
+  KubectlApplyPlanMovedError,
   type KubectlApplyInput,
   type KubectlApplyOutcome,
+  type KubectlApplyDryRun,
+  type KubectlApplyPlanArtifact,
 } from "./kubectl-apply";
 export {
   kustomizeApplyCapability,

package/src/components/kubectl-apply-plan.k3d.e2e.test.ts

@@ -0,0 +1,127 @@
+/**
+ * `kubectl-apply` plan against a real API server (#3998).
+ *
+ * Skipped unless `CHANT_K3D_CONTEXT` names a kubeconfig context, such as
+ * the one `k3d cluster create chant-e2e` writes (`k3d-chant-e2e`). Each run
+ * works in a namespace of its own and deletes it afterwards.
+ *
+ * What only a real server shows: the defaults it fills in on a dry run match
+ * the live object's, so applying a manifest and planning it again plans no
+ * change.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { dump } from "js-yaml";
+import { createKubectlApplyCapability, KubectlApplyPlanMovedError, type KubectlApplyInput } from "./kubectl-apply";
+
+const context = process.env.CHANT_K3D_CONTEXT;
+const suffix = Math.random().toString(36).slice(2, 8);
+const ns = `chant-plan-${suffix}`;
+const stack = `plan-e2e-${suffix}`;
+
+const namespace = { apiVersion: "v1", kind: "Namespace", metadata: { name: ns } };
+const config = { apiVersion: "v1", kind: "ConfigMap", metadata: { name: "cfg", namespace: ns }, data: { a: "1" } };
+const deployment = (replicas: number, app = "web") => ({
+  apiVersion: "apps/v1",
+  kind: "Deployment",
+  metadata: { name: "web", namespace: ns },
+  spec: {
+    replicas,
+    selector: { matchLabels: { app } },
+    template: {
+      metadata: { labels: { app } },
+      spec: { containers: [{ name: "pause", image: "registry.k8s.io/pause:3.9" }] },
+    },
+  },
+});
+
+describe.skipIf(!context)("kubectl-apply plan on k3d (#3998)", () => {
+  let dir: string;
+  const cap = createKubectlApplyCapability();
+  const ctx = { env: "e2e", component: "web" };
+  const write = (documents: object[]): string => {
+    const file = join(dir, `k8s-${Math.random().toString(36).slice(2)}.yaml`);
+    writeFileSync(file, documents.map((d) => dump(d)).join("---\n"));
+    return file;
+  };
+  const input = (documents: object[], extra: Partial<KubectlApplyInput> = {}): KubectlApplyInput => ({
+    manifest: write(documents),
+    stack,
+    context: context!,
+    ...extra,
+  });
+  const actions = (entries: Array<{ address: string; action: string }>) =>
+    Object.fromEntries(entries.map((e) => [e.address, e.action]));
+
+  beforeAll(() => {
+    dir = mkdtempSync(join(tmpdir(), "chant-3998-"));
+  });
+  afterAll(() => {
+    rmSync(dir, { recursive: true, force: true });
+    execFileSync("kubectl", ["--context", context!, "delete", "namespace", ns, "--wait=false", "--ignore-not-found"]);
+  });
+
+  test("a new manifest plans creates, the namespace's objects included, and run applies the plan", async () => {
+    const step = input([namespace, config, deployment(1)]);
+    const planned = await cap.plan!(ctx, step);
+    expect(planned.member).toBe(stack);
+    expect(actions(planned.changeSet!.entries)).toEqual({
+      [`Namespace/${ns}`]: "create",
+      [`ConfigMap/${ns}/cfg`]: "create",
+      [`Deployment/${ns}/web`]: "create",
+    });
+    const applied = await cap.run({ ...ctx, plans: { [stack]: planned.artifact } }, step);
+    expect(applied.applied.map((r) => r.kind)).toEqual(["Namespace", "ConfigMap", "Deployment"]);
+  }, 60_000);
+
+  test("the same manifest planned again is no change: server defaults and bookkeeping drop out", async () => {
+    const planned = await cap.plan!(ctx, input([namespace, config, deployment(1)]));
+    expect(planned.changeSet!.entries.map((e) => [e.address, e.action, e.attributes])).toEqual([
+      [`Namespace/${ns}`, "no-op", []],
+      [`ConfigMap/${ns}/cfg`, "no-op", []],
+      [`Deployment/${ns}/web`, "no-op", []],
+    ]);
+  }, 60_000);
+
+  test("a changed field is an update naming it, and owned-only plans the removed object's delete", async () => {
+    const planned = await cap.plan!(ctx, input([namespace, deployment(2)], { delete: "owned-only" }));
+    const byAddress = Object.fromEntries(planned.changeSet!.entries.map((e) => [e.address, e]));
+    expect(byAddress[`Deployment/${ns}/web`]).toMatchObject({
+      action: "update",
+      disruption: "in-place",
+      attributes: [{ path: "spec.replicas", before: 1, after: 2 }],
+    });
+    expect(byAddress[`ConfigMap/${ns}/cfg`]).toMatchObject({ action: "delete", disruption: "destroy" });
+    expect(byAddress[`Namespace/${ns}`]).toMatchObject({ action: "no-op" });
+  }, 60_000);
+
+  test("run refuses an approved plan once the cluster moved, and applies nothing", async () => {
+    // Approved while nothing undeclared is owned: no deletes.
+    const approved = await cap.plan!(ctx, input([namespace, config, deployment(2)], { delete: "owned-only" }));
+    expect(approved.changeSet!.entries.some((e) => e.action === "delete")).toBe(false);
+    // Then another apply under the same stack adds an owned object the approved manifest does not declare.
+    const extra = { apiVersion: "v1", kind: "ConfigMap", metadata: { name: "extra", namespace: ns }, data: { b: "2" } };
+    await cap.run(ctx, input([namespace, config, extra, deployment(1)]));
+    const moved = cap.run(
+      { ...ctx, plans: { [stack]: approved.artifact } },
+      input([namespace, config, deployment(2)], { delete: "owned-only" }),
+    );
+    await expect(moved).rejects.toBeInstanceOf(KubectlApplyPlanMovedError);
+    const kubectl = (...args: string[]) => String(execFileSync("kubectl", ["--context", context!, "-n", ns, ...args]));
+    expect(kubectl("get", "configmap", "extra", "-o", "jsonpath={.data.b}")).toBe("2");
+    expect(kubectl("get", "deployment", "web", "-o", "jsonpath={.spec.replicas}")).toBe("1");
+  }, 60_000);
+
+  test("an immutable selector change is an update with a hole saying the apply would fail", async () => {
+    const planned = await cap.plan!(ctx, input([namespace, config, deployment(1, "web2")]));
+    const entry = planned.changeSet!.entries.find((e) => e.address === `Deployment/${ns}/web`);
+    expect(entry).toMatchObject({ action: "update", disruption: "unknown" });
+    expect(planned.changeSet!.member.holes).toEqual([
+      expect.objectContaining({ address: `Deployment/${ns}/web`, reason: expect.stringMatching(/immutable/) }),
+    ]);
+  }, 60_000);
+});

package/src/components/kubectl-apply.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { createKubectlApplyCapability, k8sCapabilityPlugin } from "../index";
 import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { isPlanDigest } from "@intentius/chant/lifecycle/plan-digest";
 
 describe("kubectl-apply capability (#1495 piece 2)", () => {
   test("the plugin satisfies the CapabilityPlugin contract and registers the verb", () => {
@@ -126,3 +127,264 @@ describe("kubectl-apply with a release (#3061, ws-081)", () => {
     }
   });
 });
+
+describe("kubectl-apply plan: a server-side dry-run diff (#3998)", () => {
+  type DryRun = import("./kubectl-apply").KubectlApplyDryRun;
+  const web = { apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" };
+  const deployment = () => ({ apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "web", namespace: "prod" }, spec: { replicas: 3 } });
+  const unchanged = (): DryRun => ({ fieldManager: "chant:web", stack: "web", objects: [{ ref: web, action: "no-op", changes: [] }], deletes: [], retained: [] });
+  const scaled = (to: number): DryRun => ({
+    fieldManager: "chant:web",
+    stack: "web",
+    objects: [{ ref: web, action: "update", changes: [{ path: "spec.replicas", before: 3, after: to }] }],
+    deletes: [],
+    retained: [],
+  });
+  const noApply = async (): Promise<never> => {
+    throw new Error("applied");
+  };
+
+  test("plan dry-runs the documents run would apply and answers the stack as the member", async () => {
+    let seen: Record<string, unknown> = {};
+    const cap = createKubectlApplyCapability(noApply, () => [deployment()], async (args) => {
+      seen = args as never;
+      return scaled(5);
+    });
+    const planned = await cap.plan!({ env: "prod", component: "api" }, { manifest: "k8s.yaml", stack: "web", delete: "owned-only" });
+    expect(seen).toMatchObject({ manifest: "k8s.yaml", documents: [deployment()], environment: "prod", stack: "web", deleteMode: "owned-only" });
+    expect(planned.member).toBe("web");
+    expect(isPlanDigest(planned.planDigest)).toBe(true);
+    expect(planned.changeSet!.member).toMatchObject({ member: "web", lexicon: "k8s", planner: "chant", status: "planned", planDigest: planned.planDigest, holes: [] });
+    expect(planned.changeSet!.entries).toEqual([
+      {
+        member: "web",
+        lexicon: "k8s",
+        planner: "chant",
+        address: "Deployment/prod/web",
+        type: "apps/v1/Deployment",
+        name: "web",
+        action: "update",
+        disruption: "in-place",
+        attributes: [{ path: "spec.replicas", before: 3, after: 5 }],
+      },
+    ]);
+  });
+
+  test("without a stack the component is the member", async () => {
+    const cap = createKubectlApplyCapability(noApply, () => [deployment()], async () => unchanged());
+    expect((await cap.plan!({ env: "prod", component: "api" }, { manifest: "k8s.yaml" })).member).toBe("api");
+  });
+
+  test("a manifest equal to the live objects plans as no change", async () => {
+    const cap = createKubectlApplyCapability(noApply, () => [deployment()], async () => unchanged());
+    const planned = await cap.plan!({ env: "prod", component: "api" }, { manifest: "k8s.yaml", stack: "web" });
+    expect(planned.changeSet!.entries.map((e) => e.action)).toEqual(["no-op"]);
+  });
+
+  test("creates list the declared fields, a Secret's data marked sensitive, deletes are destroys, a pod-template change rolls", async () => {
+    const dryRun: DryRun = {
+      fieldManager: "chant:web",
+      objects: [
+        {
+          ref: { apiVersion: "v1", kind: "Secret", name: "s", namespace: "prod" },
+          action: "create",
+          object: { apiVersion: "v1", kind: "Secret", metadata: { name: "s", namespace: "prod" }, data: { password: "aHVudGVyMg==" } },
+          changes: [],
+        },
+        { ref: web, action: "update", changes: [{ path: "spec.template.spec.containers", before: [{ image: "a" }], after: [{ image: "b" }] }] },
+      ],
+      deletes: [{ apiVersion: "v1", kind: "ConfigMap", name: "old", namespace: "prod" }],
+      retained: [],
+    };
+    const cap = createKubectlApplyCapability(noApply, () => [], async () => dryRun);
+    const { entries } = (await cap.plan!({ env: "prod", component: "api" }, { manifest: "k8s.yaml", stack: "web", delete: "owned-only" })).changeSet!;
+    expect(entries[0]).toMatchObject({
+      action: "create",
+      address: "Secret/prod/s",
+      attributes: [{ path: "data.password", sensitive: true }, { path: "metadata.name", after: "s" }, { path: "metadata.namespace", after: "prod" }],
+    });
+    expect(JSON.stringify(entries)).not.toContain("aHVudGVyMg==");
+    expect(entries[1]).toMatchObject({ action: "update", disruption: "rolling" });
+    expect(entries[2]).toMatchObject({ action: "delete", disruption: "destroy", address: "ConfigMap/prod/old", type: "v1/ConfigMap" });
+  });
+
+  test("an immutable-field refusal is an update with unknown disruption and a hole saying the apply would fail", async () => {
+    const cap = createKubectlApplyCapability(noApply, () => [deployment()], async () => ({
+      fieldManager: "chant:web",
+      objects: [{ ref: web, action: "update", changes: [], refused: "spec.selector: field is immutable" }],
+      deletes: [],
+      retained: [],
+    }));
+    const part = (await cap.plan!({ env: "prod", component: "api" }, { manifest: "k8s.yaml", stack: "web" })).changeSet!;
+    expect(part.entries[0]).toMatchObject({ action: "update", disruption: "unknown", attributes: [] });
+    expect(part.member.holes).toEqual([
+      expect.objectContaining({ address: "Deployment/prod/web", reason: expect.stringContaining("field is immutable") }),
+    ]);
+  });
+
+  test("the digest is stable for the same dry run and moves with what it would change", async () => {
+    let to = 5;
+    const cap = createKubectlApplyCapability(noApply, () => [deployment()], async () => scaled(to));
+    const ctx = { env: "prod", component: "api" };
+    const input = { manifest: "k8s.yaml", stack: "web" };
+    const a = (await cap.plan!(ctx, input)).planDigest;
+    expect((await cap.plan!(ctx, input)).planDigest).toBe(a);
+    to = 6;
+    expect((await cap.plan!(ctx, input)).planDigest).not.toBe(a);
+    to = 5;
+    expect((await cap.plan!({ ...ctx, env: "staging" }, input)).planDigest).not.toBe(a);
+  });
+
+  test("a live value moving under a field the apply sets to the same value leaves the digest alone", async () => {
+    let from = 3;
+    const cap = createKubectlApplyCapability(noApply, () => [deployment()], async () => ({
+      fieldManager: "chant:web",
+      objects: [{ ref: web, action: "update", changes: [{ path: "spec.replicas", before: from, after: 5 }] }],
+      deletes: [],
+      retained: [],
+    }));
+    const ctx = { env: "prod", component: "api" };
+    const a = (await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web" })).planDigest;
+    from = 4;
+    expect((await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web" })).planDigest).toBe(a);
+  });
+
+  test("release attributes are set before the dry run, so the plan covers what run applies", async () => {
+    const stampedDeployment = () => ({
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      metadata: { name: "api" },
+      spec: {
+        template: {
+          metadata: {},
+          spec: { containers: [{ name: "api", image: "x", env: [{ name: "CHANT_RELEASE_ATTRIBUTES", valueFrom: { fieldRef: { fieldPath: "metadata.annotations['chant.intentius.io/release-attributes']" } } }] }] },
+        },
+      },
+    });
+    let planned: Record<string, any>[] = [];
+    const cap = createKubectlApplyCapability(noApply, () => [stampedDeployment()], async (args) => {
+      planned = args.documents as never;
+      return unchanged();
+    });
+    const result = await cap.plan!({ env: "prod", component: "api", release: { revision: "0123abc" } }, { manifest: "k8s.yaml", stack: "web" });
+    expect(planned[0].spec.template.metadata.annotations["chant.intentius.io/release-attributes"]).toContain("0123abc");
+    expect((result.artifact as { documents: unknown[] }).documents).toEqual(planned);
+  });
+
+  test("run handed the plan applies the planned documents after a fresh dry run agrees", async () => {
+    let to = 5;
+    const applied: Record<string, unknown>[] = [];
+    let reads = 0;
+    const cap = createKubectlApplyCapability(
+      async (args) => {
+        applied.push(args as never);
+        return { applied: [web], pruned: [], fieldManager: "chant:web" };
+      },
+      () => {
+        reads++;
+        return [deployment()];
+      },
+      async () => scaled(to),
+    );
+    const input = { manifest: "k8s.yaml", stack: "web", delete: "owned-only" as const };
+    const planned = await cap.plan!({ env: "prod", component: "api" }, input);
+    await cap.run({ env: "prod", component: "api", plans: { web: planned.artifact } }, input);
+    expect(reads).toBe(1);
+    expect(applied).toEqual([{ manifest: "k8s.yaml", documents: [deployment()], environment: "prod", stack: "web", deleteMode: "owned-only" }]);
+
+    to = 7;
+    const { KubectlApplyPlanMovedError } = await import("./kubectl-apply");
+    const moved = cap.run({ env: "prod", component: "api", plans: { web: planned.artifact } }, input);
+    await expect(moved).rejects.toBeInstanceOf(KubectlApplyPlanMovedError);
+    await expect(moved).rejects.toMatchObject({ planMoved: true, exitCode: 3, approved: planned.planDigest });
+    // Core's mark for a moved plan, so the command that applied it exits 3 (#3997).
+    const { isPlanMovedError } = await import("@intentius/chant/components/capability");
+    expect(isPlanMovedError(await moved.catch((e: unknown) => e))).toBe(true);
+    expect(applied).toHaveLength(1);
+  });
+
+  test("a plan for another member is not this step's: run applies as it would without one", async () => {
+    const applied: Record<string, unknown>[] = [];
+    const cap = createKubectlApplyCapability(
+      async (args) => {
+        applied.push(args as never);
+        return { applied: [], pruned: [], fieldManager: "chant:web" };
+      },
+      () => [deployment()],
+      async () => {
+        throw new Error("no dry run expected");
+      },
+    );
+    await cap.run({ env: "prod", component: "api", plans: { other: { kind: "kubectl-apply-plan", planDigest: "sha256:x", documents: [] } } }, { manifest: "k8s.yaml", stack: "web" });
+    expect(applied).toEqual([{ manifest: "k8s.yaml", environment: "prod", stack: "web" }]);
+  });
+});
+
+describe("kubectl-apply outputs: the fields a step names (#3999)", () => {
+  type DryRun = import("./kubectl-apply").KubectlApplyDryRun;
+  const svcRef = { apiVersion: "v1", kind: "Service", name: "web", namespace: "prod" };
+  const service = () => ({ apiVersion: "v1", kind: "Service", metadata: { name: "web", namespace: "prod" }, spec: { type: "LoadBalancer", ports: [{ port: 80 }] } });
+  const live = () => ({ ...service(), spec: { ...service().spec, clusterIP: "10.0.0.9" }, status: { loadBalancer: { ingress: [{ hostname: "web.example" }] } } });
+  const outputs = {
+    host: { object: "Service/prod/web", field: "status.loadBalancer.ingress.0.hostname" },
+    port: { object: "Service/prod/web", field: "spec.ports.0.port" },
+  };
+  const dryRun = (action: "create" | "update" | "no-op"): DryRun => ({ fieldManager: "chant:web", stack: "web", objects: [{ ref: svcRef, action, changes: [] }], deletes: [], retained: [] });
+  const ctx = { env: "prod", component: "web" };
+  const applied = async () => ({ applied: [], pruned: [], fieldManager: "chant:web" });
+
+  test("outputs reads each named field from the cluster, applying nothing; a step that names none has none", async () => {
+    const reads: unknown[] = [];
+    const cap = createKubectlApplyCapability(
+      async () => {
+        throw new Error("applied");
+      },
+      () => [service()],
+      undefined,
+      async (args) => {
+        reads.push(args);
+        return [live()];
+      },
+    );
+    expect(await cap.outputs!(ctx, { manifest: "k8s.yaml", stack: "web", outputs })).toEqual({ host: "web.example", port: 80 });
+    expect(reads).toEqual([{ refs: [svcRef], environment: "prod" }]);
+    expect(await cap.outputs!(ctx, { manifest: "k8s.yaml", stack: "web" })).toEqual({});
+  });
+
+  test("an object not made yet leaves its outputs out", async () => {
+    const cap = createKubectlApplyCapability(applied, () => [service()], undefined, async () => [undefined]);
+    expect(await cap.outputs!(ctx, { manifest: "k8s.yaml", stack: "web", outputs })).toEqual({});
+  });
+
+  test("run returns the named fields as outputs, read once the apply landed, which a dependent's stackOutput() reads", async () => {
+    const cap = createKubectlApplyCapability(applied, () => [service()], undefined, async () => [live()]);
+    const out = await cap.run(ctx, { manifest: "k8s.yaml", stack: "web", outputs });
+    expect(out.outputs).toEqual({ host: "web.example", port: 80 });
+  });
+
+  test("an output naming an object the manifest does not declare is an error that says what it declares", async () => {
+    const cap = createKubectlApplyCapability(applied, () => [service()], undefined, async () => [live()]);
+    await expect(cap.outputs!(ctx, { manifest: "k8s.yaml", stack: "web", outputs: { x: { object: "Service/prod/api", field: "spec" } } })).rejects.toThrow(
+      'kubectl-apply "web": output "x" names Service/prod/api, which k8s.yaml does not declare (it declares Service/prod/web)',
+    );
+  });
+
+  test("a plan knows a field the manifest sets; a field the server fills is known only after apply", async () => {
+    const cap = createKubectlApplyCapability(applied, () => [service()], async () => dryRun("create"), async () => {
+      throw new Error("a created object has nothing live to read");
+    });
+    const planned = await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web", outputs });
+    expect(planned.outputs).toEqual({ known: { port: 80 }, unknown: ["host"] });
+  });
+
+  test("a plan that leaves the object as it is knows every named field, as the cluster holds it", async () => {
+    const cap = createKubectlApplyCapability(applied, () => [service()], async () => dryRun("no-op"), async () => [live()]);
+    const planned = await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web", outputs });
+    expect(planned.outputs).toEqual({ known: { host: "web.example", port: 80 }, unknown: [] });
+  });
+
+  test("a step that names no outputs plans none", async () => {
+    const cap = createKubectlApplyCapability(applied, () => [service()], async () => dryRun("update"));
+    expect((await cap.plan!(ctx, { manifest: "k8s.yaml", stack: "web" })).outputs).toBeUndefined();
+  });
+});