@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/op/activities/kubectl.ts

@@ -7,16 +7,26 @@
  * that signature; what changed is underneath. The name is kept for the same
  * reason.
  *
+ * chant #1075 finished the job on two axes:
+ *
+ * - **Identity.** The field manager is no longer the bare `chant` but
+ *   `chant:<stack>`, derived from the project's `ownership.stack` — the same
+ *   identity the ownership label already carries. See
+ *   `@intentius/chant-k8s-client`'s `field-manager.ts`.
+ * - **Deletes.** `nativeApply`'s kubectl branch used to shell
+ *   `kubectl apply --prune --selector <marker>`; that branch now routes here,
+ *   so the prune had to come with it. {@link applyManifest} implements it
+ *   against the typed client, scoped to the ownership marker exactly as the
+ *   shelled prune was, and never touching an object that does not carry it.
+ *
  * Consequences worth knowing:
  *
  * - **A worker image needs no `kubectl` binary.** That was the point.
- * - **It is a server-side apply**, with `chant` as the field manager, rather
- *   than the client-side three-way merge `kubectl apply` performs by default.
- *   Server-side apply is the direction Kubernetes itself has taken, it removes
- *   the `last-applied-configuration` annotation from the story, and it is what
- *   chant #1075 builds the field-ownership and conflict surface on. A conflict
- *   with another field manager arrives here as a typed 409 rather than a line
- *   of stderr; #1075 is where it gets a proper presentation.
+ * - **It is a server-side apply**, rather than the client-side three-way merge
+ *   `kubectl apply` performs by default. A conflict with another field manager
+ *   arrives as a `FieldManagerConflictError` naming the competing manager and
+ *   the contested paths — never as a silent overwrite, and never force-resolved
+ *   on chant's initiative.
  * - **Documents apply in file order**, as `kubectl apply -f` does, and a
  *   directory's files are read in sorted order.
  */
@@ -25,8 +35,24 @@ import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { loadAll } from "js-yaml";
 import { safeHeartbeat } from "@intentius/chant/op";
-import type { K8sObject } from "@intentius/chant-k8s-client";
+import { loadChantConfig, resolveOwnershipMarker } from "@intentius/chant/config";
+import {
+  hasOwnershipMarker,
+  LABEL_OWNERSHIP_KEYS,
+  OWNERSHIP_MANAGED_BY_VALUE,
+} from "@intentius/chant/ownership";
+import type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
 import { defaultK8sConnector, type K8sConnector } from "../../api/connect";
+import { operationFor } from "../../api/operation-surface";
+import { DEFAULT_IMPORT_TYPES } from "../../api/sweep-types";
+
+/**
+ * How the apply treats chant-owned objects that are no longer declared. The
+ * same three values `nativeApply` has always taken; `gated` differs from
+ * `owned-only` only in that the workflow pauses for approval first, which is
+ * the composite's business, not this activity's.
+ */
+export type ApplyDeleteMode = "never" | "owned-only" | "gated";
 
 export interface KubectlApplyArgs {
   /** Path to a manifest file, or a directory of them. */
@@ -44,10 +70,56 @@ export interface KubectlApplyArgs {
    * the previous behavior of using whatever the kubeconfig selects.
    */
   environment?: string;
-  /** Field manager recorded on the applied objects. Default `chant`. */
+  /**
+   * Field manager recorded on the applied fields. Omitted derives it from the
+   * project's `ownership.stack` (chant #1075) — `chant:<stack>`, or the bare
+   * `chant` when the project sets none.
+   */
   fieldManager?: string;
-  /** Take ownership of fields another manager owns instead of failing (chant #1075). */
+  /**
+   * Ownership stack, when the caller already knows it and would rather not
+   * have the project config read. Ignored if `fieldManager` is set.
+   */
+  stack?: string;
+  /**
+   * Take ownership of fields another manager owns instead of failing with a
+   * `FieldManagerConflictError`. **Never defaulted on** — see chant #1075.
+   */
   force?: boolean;
+  /**
+   * Delete chant-owned objects that are no longer declared. Default `never`.
+   * Deletes are scoped to the ownership marker, so an object chant did not
+   * stamp is never a candidate.
+   */
+  deleteMode?: ApplyDeleteMode;
+  /**
+   * Server-side dry run — every document is validated and would-be-applied,
+   * nothing is persisted, and pruning is skipped entirely (a prune candidate
+   * list computed from a state that was never written would be misleading).
+   * Optional and additive (chant #1079): `chant kube apply`'s confirmation
+   * gate uses this to preview an apply before anything mutates the cluster;
+   * Op callers keep the previous behavior by leaving it unset.
+   */
+  dryRun?: boolean;
+  /** Project directory whose `chant.config.ts` carries `ownership`. Defaults to cwd. */
+  cwd?: string;
+}
+
+/** One object the apply touched. */
+export interface AppliedRef {
+  apiVersion: string;
+  kind: string;
+  name: string;
+  namespace?: string;
+}
+
+/** What {@link applyManifest} did. */
+export interface ApplyManifestResult {
+  /** The field manager every object was applied as. */
+  fieldManager: string;
+  applied: AppliedRef[];
+  /** Objects deleted because they carried chant's marker and are no longer declared. */
+  pruned: AppliedRef[];
 }
 
 /** Read a manifest path — one file, or every YAML/JSON file in a directory. */
@@ -71,15 +143,69 @@ export function readManifestDocuments(path: string): Record<string, unknown>[] {
 }
 
 /**
- * Apply every document in `args.manifest`.
- * Uses longInfra profile — 20m timeout, heartbeat every 15s.
+ * The field manager to apply as: an explicit one, else `chant:<stack>` from a
+ * caller-supplied stack, else `chant:<stack>` from the project's `ownership`
+ * config, else the bare `chant`.
+ *
+ * A project config that cannot be read falls back to the bare `chant` with a
+ * warning rather than failing the apply — an activity handed a manifest path
+ * and nothing else is a supported way to call this, and its cwd need not be a
+ * chant project at all. The warning is there because a *silent* downgrade
+ * would change which fields chant owns without saying so.
  */
-export async function kubectlApply(
+export async function resolveFieldManager(args: KubectlApplyArgs): Promise<string> {
+  return (await resolveApplyIdentity(args)).fieldManager;
+}
+
+/**
+ * The stack and the field manager together, resolved once. The prune needs the
+ * stack for its selector and the apply needs the manager; reading the project
+ * config twice for one apply would be silly, and could disagree with itself if
+ * the file changed in between.
+ */
+async function resolveApplyIdentity(
+  args: KubectlApplyArgs,
+): Promise<{ fieldManager: string; stack?: string }> {
+  const { fieldManagerFor, assertValidFieldManager } = await import("@intentius/chant-k8s-client");
+
+  let stack = args.stack;
+  if (stack === undefined) {
+    try {
+      const { config } = await loadChantConfig(args.cwd ?? process.cwd());
+      stack = resolveOwnershipMarker(config)?.stack;
+    } catch (err) {
+      console.warn(
+        `[k8s] could not read the project config to derive a field manager ` +
+          `(${err instanceof Error ? err.message : String(err)}); applying as the unqualified "chant"`,
+      );
+    }
+  }
+
+  if (args.fieldManager !== undefined) {
+    assertValidFieldManager(args.fieldManager);
+    return { fieldManager: args.fieldManager, ...(stack !== undefined ? { stack } : {}) };
+  }
+  return {
+    fieldManager: fieldManagerFor(stack !== undefined ? { stack } : undefined),
+    ...(stack !== undefined ? { stack } : {}),
+  };
+}
+
+/**
+ * Apply every document in `args.manifest`, then prune when asked.
+ *
+ * Returns what it did. `kubectlApply` is the registered activity and keeps its
+ * `Promise<void>` contract; this is the function `nativeApply` calls, because a
+ * dispatcher that reports "applied 12, pruned 2" is worth more than one that
+ * reports the shell command it ran.
+ */
+export async function applyManifest(
   args: KubectlApplyArgs,
   signal?: AbortSignal,
   connect: K8sConnector = defaultK8sConnector,
-): Promise<void> {
+): Promise<ApplyManifestResult> {
   const documents = readManifestDocuments(args.manifest);
+  const { fieldManager, stack } = await resolveApplyIdentity(args);
   const heartbeatInterval = setInterval(() => {
     safeHeartbeat({ step: "kubectl apply", manifest: args.manifest });
   }, 15_000);
@@ -88,24 +214,191 @@ export async function kubectlApply(
     const { client } = await connect({
       ...(args.environment !== undefined ? { environment: args.environment } : {}),
       ...(args.context !== undefined ? { context: args.context } : {}),
+      ...(args.cwd !== undefined ? { cwd: args.cwd } : {}),
     });
 
+    const applied: AppliedRef[] = [];
     for (const document of documents) {
-      const applied = await client.apply(document as K8sObject, {
-        fieldManager: args.fieldManager ?? "chant",
+      const result = await client.apply(document as K8sObject, {
+        fieldManager,
         force: args.force ?? false,
+        dryRun: args.dryRun,
         signal,
       });
+      const ref: AppliedRef = {
+        apiVersion: String(result.apiVersion ?? document.apiVersion ?? ""),
+        kind: String(result.kind ?? document.kind ?? ""),
+        name: String(result.metadata?.name ?? ""),
+        ...(result.metadata?.namespace !== undefined
+          ? { namespace: String(result.metadata.namespace) }
+          : {}),
+      };
+      applied.push(ref);
       safeHeartbeat({
         step: "kubectl apply",
         manifest: args.manifest,
-        applied: `${applied.kind ?? document.kind}/${applied.metadata?.name ?? "?"}`,
+        applied: `${ref.kind}/${ref.name}`,
       });
-      console.log(
-        `${String(applied.apiVersion ?? document.apiVersion)} ${String(applied.kind ?? document.kind)}/${String(applied.metadata?.name ?? "")} applied`,
-      );
+      console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} applied${args.dryRun ? " (dry run — nothing persisted)" : ""}`);
     }
+
+    const deleteMode = args.deleteMode ?? "never";
+    const pruned =
+      deleteMode === "never" || args.dryRun
+        ? []
+        : await pruneOrphans(client, applied, {
+            ...(stack !== undefined ? { stack } : {}),
+            signal,
+          });
+
+    return { fieldManager, applied, pruned };
   } finally {
     clearInterval(heartbeatInterval);
   }
 }
+
+/**
+ * Apply every document in `args.manifest`.
+ * Uses longInfra profile — 20m timeout, heartbeat every 15s.
+ */
+export async function kubectlApply(
+  args: KubectlApplyArgs,
+  signal?: AbortSignal,
+  connect: K8sConnector = defaultK8sConnector,
+): Promise<void> {
+  await applyManifest(args, signal, connect);
+}
+
+/**
+ * Delete chant-owned objects that the apply set no longer declares.
+ *
+ * This replaces `kubectl apply --prune --selector <marker>=chant`, and keeps
+ * its two safety properties exactly:
+ *
+ * - **Marker-scoped.** Only objects carrying chant's managed-by label are
+ *   candidates; the label selector is sent to the server, and the marker is
+ *   re-checked on every object before it is deleted. An unmarked resource is
+ *   never a candidate, so a hand-made object in the same namespace is safe.
+ * - **Namespace-scoped to the apply.** Namespaced kinds are swept only in the
+ *   namespaces the apply set touched (the context's default namespace when it
+ *   named none), which is what kubectl's prune does. A manifest that mentions
+ *   `prod` never reaches into `staging`. Whether a kind *is* namespaced comes
+ *   from the cluster's own discovery, never from whether a document happened
+ *   to name a namespace — guessing that wrong is the one way this could widen
+ *   into a cluster-wide sweep.
+ *
+ * Which *kinds* get swept is the union of the kinds the apply set contains and
+ * chant's default sweep set (`DEFAULT_IMPORT_TYPES` — the same list `chant
+ * import` uses when nothing narrows it). The union matters: a kind removed
+ * from source entirely appears nowhere in the apply set, and pruning only what
+ * is still declared would leave it behind forever. Per-namespace lists rather
+ * than one cluster-wide list per kind, so a namespace-scoped service account
+ * can still prune.
+ */
+async function pruneOrphans(
+  client: K8sClient,
+  applied: readonly AppliedRef[],
+  options: { stack?: string; signal?: AbortSignal },
+): Promise<AppliedRef[]> {
+  const stack = options.stack;
+  const selector = [
+    `${LABEL_OWNERSHIP_KEYS.managedBy}=${OWNERSHIP_MANAGED_BY_VALUE}`,
+    ...(stack ? [`${LABEL_OWNERSHIP_KEYS.stack}=${stack}`] : []),
+  ].join(",");
+
+  const namespaces = [...new Set(applied.map((a) => a.namespace).filter((n): n is string => !!n))];
+  if (namespaces.length === 0 && applied.length > 0) namespaces.push(client.defaultNamespace);
+  const declared = new Set(applied.map(refKey));
+
+  // Every kind that could hold an orphan: the apply set's own, plus the
+  // default sweep set so a kind deleted from source entirely is still reached.
+  const sweeps = new Map<string, { apiVersion: string; kind: string }>();
+  for (const entityType of DEFAULT_IMPORT_TYPES) {
+    const operation = operationFor(entityType);
+    if (!operation) continue;
+    sweeps.set(`${operation.apiVersion}/${operation.kind}`, {
+      apiVersion: operation.apiVersion,
+      kind: operation.kind,
+    });
+  }
+  for (const ref of applied) {
+    if (!ref.apiVersion || !ref.kind) continue;
+    sweeps.set(`${ref.apiVersion}/${ref.kind}`, { apiVersion: ref.apiVersion, kind: ref.kind });
+  }
+
+  // (kind, namespace) pairs to list. Scope comes from the cluster's discovery,
+  // which is the only thing that knows it for the version this cluster serves;
+  // a kind discovery does not report is dropped rather than swept blindly.
+  const resolved = await client.concurrently([...sweeps.values()], async (sweep) => {
+    const info = await client
+      .resolve({ apiVersion: sweep.apiVersion, kind: sweep.kind }, options.signal)
+      .catch(() => undefined);
+    return info ? { ...sweep, namespaced: info.namespaced } : undefined;
+  });
+
+  const targets: Array<{ apiVersion: string; kind: string; namespace?: string }> = [];
+  for (const sweep of resolved) {
+    if (!sweep) continue;
+    if (!sweep.namespaced) {
+      targets.push({ apiVersion: sweep.apiVersion, kind: sweep.kind });
+      continue;
+    }
+    for (const namespace of namespaces) {
+      targets.push({ apiVersion: sweep.apiVersion, kind: sweep.kind, namespace });
+    }
+  }
+
+  const found = await client.concurrently(targets, async (target) => {
+    try {
+      const items = await client.list(
+        { apiVersion: target.apiVersion, kind: target.kind },
+        {
+          labelSelector: selector,
+          ...(target.namespace !== undefined ? { namespace: target.namespace } : {}),
+          ...(options.signal ? { signal: options.signal } : {}),
+        },
+      );
+      return items.map((item) => ({ target, item }));
+    } catch {
+      // Kind not served here, or the read was denied. Neither is evidence that
+      // something should be deleted, so the sweep skips it rather than failing
+      // the apply that already succeeded.
+      return [];
+    }
+  });
+
+  const candidates: AppliedRef[] = [];
+  const seen = new Set<string>();
+  for (const { target, item } of found.flat()) {
+    const name = item.metadata?.name;
+    if (!name) continue;
+    // The server filtered by label already; this re-check is the one that
+    // matters, because a delete is not undoable.
+    if (!hasOwnershipMarker(item.metadata?.labels, LABEL_OWNERSHIP_KEYS)) continue;
+    // Already terminating — deleting again is noise, not progress.
+    if (item.metadata?.deletionTimestamp !== undefined) continue;
+    const ref: AppliedRef = {
+      apiVersion: target.apiVersion,
+      kind: target.kind,
+      name,
+      ...(item.metadata?.namespace !== undefined ? { namespace: item.metadata.namespace } : {}),
+    };
+    const key = refKey(ref);
+    if (declared.has(key) || seen.has(key)) continue;
+    seen.add(key);
+    candidates.push(ref);
+  }
+
+  const pruned: AppliedRef[] = [];
+  for (const ref of candidates) {
+    await client.delete(ref, { ...(options.signal ? { signal: options.signal } : {}) });
+    pruned.push(ref);
+    safeHeartbeat({ step: "prune", pruned: `${ref.kind}/${ref.name}` });
+    console.log(`${ref.apiVersion} ${ref.kind}/${ref.name} pruned (chant-owned, no longer declared)`);
+  }
+  return pruned;
+}
+
+function refKey(ref: AppliedRef): string {
+  return `${ref.apiVersion}/${ref.kind}/${ref.namespace ?? ""}/${ref.name}`;
+}

package/src/plugin.test.ts

@@ -1,4 +1,4 @@
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { existsSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
@@ -211,4 +211,61 @@ describe("k8sPlugin", () => {
   test("package() method exists", () => {
     expect(typeof k8sPlugin.package).toBe("function");
   });
+
+  // chant #1078 — the command-group seam's first real tenant: `commands()`
+  // mounts a "kube" verb group, reserving the namespace #1079's `chant kube`
+  // terminal surface will add its own verbs to.
+  describe("commands() — the `kube` command group (#1078)", () => {
+    test("contributes a group named kube with a version verb", () => {
+      const group = k8sPlugin.commands!();
+      expect(group.name).toBe("kube");
+      expect(group.commands.map((c) => c.name)).toContain("version");
+    });
+
+    test("kube version prints the pinned K8S_SCHEMA_VERSION", async () => {
+      const { K8S_SCHEMA_VERSION } = await import("./spec/fetch");
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const exitCode = await version.handler({ verb: "version", rawArgs: [] });
+        expect(exitCode).toBe(0);
+        expect(logSpy).toHaveBeenCalledWith(K8S_SCHEMA_VERSION);
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    test("kube version --format json emits a JSON envelope", async () => {
+      const { K8S_SCHEMA_VERSION } = await import("./spec/fetch");
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        const exitCode = await version.handler({ verb: "version", rawArgs: ["--format", "json"] });
+        expect(exitCode).toBe(0);
+        expect(logSpy).toHaveBeenCalledWith(JSON.stringify({ schemaVersion: K8S_SCHEMA_VERSION }));
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    test("kube version --format=json (joined form, #1127 discipline) works identically", async () => {
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+      try {
+        await version.handler({ verb: "version", rawArgs: ["--format=json"] });
+        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("schemaVersion"));
+      } finally {
+        logSpy.mockRestore();
+      }
+    });
+
+    test("kube version rejects an unknown flag (#1127 discipline applies to mounted commands)", async () => {
+      const group = k8sPlugin.commands!();
+      const version = group.commands.find((c) => c.name === "version")!;
+      await expect(version.handler({ verb: "version", rawArgs: ["--bogus"] })).rejects.toThrow(/Unknown flag: --bogus/);
+    });
+  });
 });

package/src/plugin.ts

@@ -6,6 +6,8 @@
  */
 
 import type { LexiconPlugin, InitTemplateSet, ResourceMetadata } from "@intentius/chant/lexicon";
+import type { CommandGroup } from "@intentius/chant/cli/command-group";
+import { kubeCommandGroup } from "./kube/group";
 import { detectTemplate } from "./detect";
 import type { LintRule } from "@intentius/chant/lint/rule";
 import { postSynthChecks as postSynthCheckList } from "./lint/post-synth";
@@ -23,6 +25,7 @@ import { k8sCompletions } from "./lsp/completions";
 import { k8sHover } from "./lsp/hover";
 import { K8sParser } from "./import/parser";
 import { K8sGenerator } from "./import/generator";
+import { k8sDeepNormalizationHooks } from "./deep-observe-hooks";
 
 export const k8sPlugin: LexiconPlugin = {
   name: "k8s",
@@ -37,6 +40,17 @@ export const k8sPlugin: LexiconPlugin = {
     upstream: { owner: "kubernetes", repo: "kubernetes", kind: "releases" },
   },
 
+  // chant #1078/#1079 — the command-group seam's tenant. `kube` mounts the
+  // terminal surface over the typed client: kubectl-compatible reads (get,
+  // describe, logs, events, top, wait), chant's own additions (source, the
+  // `get` verdict column, -o chant), and gated writes (apply, delete) that
+  // route through the exact same machinery the Op activities use — never a
+  // parallel implementation. See ./kube/group.ts for the full verb list;
+  // this plugin only mounts it.
+  commands(): CommandGroup {
+    return kubeCommandGroup();
+  },
+
   lintRules(): LintRule[] {
     return [
       hardcodedNamespaceRule,
@@ -617,4 +631,19 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
     const { exportResources } = await import("./export-resources");
     return exportResources(options);
   },
+
+  // Property-level live drift via SSA managed-fields (#1076, epic #1073).
+  // The reader lives in ./deep-observe.ts, loaded only through this dynamic
+  // import — same reason describeResources/exportResources are — so the API
+  // client never becomes reachable from the build path (chant #1074,
+  // examples/k8s-client-boundary.test.ts). deepNormalizationHooks is plain
+  // data with no client dependency (./deep-observe-hooks.ts) and is imported
+  // statically above, because core applies it to the *declared* tree whether
+  // or not a live read ever happens.
+  async observeResourcesDeep(options) {
+    const { observeResourcesDeepK8s } = await import("./deep-observe");
+    return observeResourcesDeepK8s(options);
+  },
+
+  deepNormalizationHooks: k8sDeepNormalizationHooks,
 };