@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/kube/flags.ts

@@ -0,0 +1,114 @@
+/**
+ * Flag parsing shared by every `chant kube <verb>` (chant #1079).
+ *
+ * `CommandGroupContext.rawArgs` is unparsed argv — core has no vocabulary for
+ * a lexicon's own verbs (chant #1078) — so every verb here does its own
+ * parsing, reusing `splitJoinedFlags`/`unknownFlagError` for the same
+ * `--flag=value` splitting and rejection discipline core's own parser
+ * applies (chant #1127). This module adds the flag vocabulary every verb
+ * shares (namespace, selector, output, cluster targeting) so each verb file
+ * only has to declare what is actually its own (`--tail`, `--for`, ...).
+ */
+
+import { splitJoinedFlags, unknownFlagError } from "@intentius/chant/cli/command-group";
+import type { ConnectOptions } from "../api/connect";
+
+/** A verb's own flag vocabulary, merged with the common set below. */
+export interface FlagSpec {
+  /** Value flags this verb accepts, alias → canonical key (e.g. `{ "--tail": "tail" }`). */
+  value?: Record<string, string>;
+  /** Boolean flags this verb accepts, alias → canonical key. */
+  boolean?: Record<string, string>;
+}
+
+/** Every `chant kube` verb accepts these — kubectl's own names. */
+const COMMON_VALUE: Record<string, string> = {
+  "-n": "namespace",
+  "--namespace": "namespace",
+  "-l": "selector",
+  "--selector": "selector",
+  "-o": "output",
+  "--output": "output",
+  "--context": "context",
+  "--env": "env",
+  "--kubeconfig": "kubeconfig",
+};
+
+const COMMON_BOOLEAN: Record<string, string> = {
+  "-A": "allNamespaces",
+  "--all-namespaces": "allNamespaces",
+};
+
+export interface ParsedFlags {
+  /** Non-flag tokens, in order — the verb's own positional arguments (kind, name, ...). */
+  positional: string[];
+  /** Resolved value-flag key → the value given. */
+  values: Record<string, string>;
+  /** Resolved boolean-flag key → true (absent keys are false). */
+  flags: Record<string, boolean>;
+}
+
+/**
+ * Parse `rawArgs` against the common flag set plus `spec`. Throws
+ * {@link unknownFlagError}'s shape on anything starting with `-` that
+ * neither set recognizes, and on a value flag given with nothing after it.
+ */
+export function parseKubeFlags(rawArgs: string[], spec: FlagSpec = {}): ParsedFlags {
+  const valueFlags: Record<string, string> = { ...COMMON_VALUE, ...(spec.value ?? {}) };
+  const booleanFlags: Record<string, string> = { ...COMMON_BOOLEAN, ...(spec.boolean ?? {}) };
+  const args = splitJoinedFlags(rawArgs, new Set(Object.keys(booleanFlags)));
+
+  const positional: string[] = [];
+  const values: Record<string, string> = {};
+  const flags: Record<string, boolean> = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg.startsWith("-") || arg === "-") {
+      positional.push(arg);
+      continue;
+    }
+    if (arg in booleanFlags) {
+      flags[booleanFlags[arg]] = true;
+      continue;
+    }
+    if (arg in valueFlags) {
+      const value = args[++i];
+      if (value === undefined) throw new Error(`${arg} requires a value`);
+      values[valueFlags[arg]] = value;
+      continue;
+    }
+    throw unknownFlagError(arg);
+  }
+
+  return { positional, values, flags };
+}
+
+/** Build the typed client's `ConnectOptions` from a parsed common flag set. */
+export function connectOptionsFrom(values: Record<string, string>): ConnectOptions {
+  const options: ConnectOptions = {};
+  if (values.env !== undefined) options.environment = values.env;
+  if (values.context !== undefined) options.context = values.context;
+  if (values.kubeconfig !== undefined) options.client = { kubeconfigPath: values.kubeconfig };
+  return options;
+}
+
+/** kubectl duration shorthand: "3600" (bare seconds), "1h", "90m", "45s". Shared by `logs --since` and `wait --timeout`. */
+export function parseDurationSeconds(value: string): number {
+  const match = /^(\d+)(s|m|h)?$/.exec(value.trim());
+  if (!match) throw new Error(`expected a duration like "1h", "90m", "45s", or a bare second count, got "${value}"`);
+  const n = Number(match[1]);
+  switch (match[2]) {
+    case "h":
+      return n * 3600;
+    case "m":
+      return n * 60;
+    default:
+      return n;
+  }
+}
+
+/** {@link parseDurationSeconds} in milliseconds. */
+export function parseDurationMs(value: string): number {
+  return parseDurationSeconds(value) * 1000;
+}

package/src/kube/get.test.ts

@@ -0,0 +1,195 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster, objectKey, ownedObject } from "../api/fake-cluster";
+import { runGet } from "./get";
+import { fakeDeclarable, fakeProjectContext } from "./testing";
+
+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 get (#1079)", () => {
+  test("happy path: lists live objects in a table, chant column reads unavailable with no project", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedObject("apps/v1", "Deployment", "web", "prod", {
+          status: { readyReplicas: 2, replicas: 2 },
+        }),
+      },
+    });
+    const { log } = spyConsole();
+
+    const code = await runGet(["deployments", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls.map((c) => c[0]).join("\n");
+    expect(out).toContain("NAME");
+    expect(out).toContain("CHANT");
+    expect(out).toContain("web");
+    expect(out).toContain("unavailable");
+  });
+
+  test("with a project: a matching declared entity renders as declared, an unmatched foreign object as foreign-owned", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1", labels: { app: "web" } },
+          spec: { replicas: 2 },
+          status: { readyReplicas: 2, replicas: 2 },
+        },
+        [objectKey("apps/v1", "Deployment", "unrelated", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "unrelated", namespace: "prod", uid: "u2" },
+          status: { readyReplicas: 1, replicas: 1 },
+        },
+      },
+    });
+    const project = fakeProjectContext({
+      web: fakeDeclarable("K8s::Apps::Deployment", {
+        metadata: { name: "web", namespace: "prod" },
+        spec: { replicas: 2 },
+      }),
+    });
+    const { log } = spyConsole();
+
+    const code = await runGet(["deployments", "-n", "prod"], {
+      connect: cluster.connector,
+      loadProject: async () => project,
+    });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls.map((c) => c[0]).join("\n");
+    expect(out).toMatch(/web\s+.*declared/);
+    expect(out).toMatch(/unrelated\s+.*foreign-owned/);
+  });
+
+  test("a declared match whose live spec disagrees renders as drifted", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1" },
+          spec: { replicas: 9 },
+          status: { readyReplicas: 9, replicas: 9 },
+        },
+      },
+    });
+    const project = fakeProjectContext({
+      web: fakeDeclarable("K8s::Apps::Deployment", {
+        metadata: { name: "web", namespace: "prod" },
+        spec: { replicas: 2 },
+      }),
+    });
+    const { log } = spyConsole();
+
+    await runGet(["deployments", "-n", "prod"], { connect: cluster.connector, loadProject: async () => project });
+
+    const out = log.mock.calls.map((c) => c[0]).join("\n");
+    expect(out).toMatch(/web\s+.*drifted/);
+  });
+
+  test("binding mismatch: refuses loudly, renders NOT-OBSERVED, no resources printed", async () => {
+    const { error, log } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runGet(["deployments", "--env", "prod"], { connect });
+
+    expect(code).toBe(1);
+    expect(error).toHaveBeenCalled();
+    const message = error.mock.calls.map((c) => c[0]).join("\n");
+    expect(message).toContain("no binding for this environment");
+    expect(message).toContain("prod-eks");
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  test("unknown flag is rejected before any connection is attempted", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runGet(["deployments", "--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 list renders NOT-OBSERVED, not an empty table", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/apis/apps/v1/namespaces/prod/deployments"
+          ? { status: 403, body: { kind: "Status", reason: "Forbidden", message: "deployments is forbidden", code: 403 } }
+          : undefined,
+    });
+    const { error, log } = spyConsole();
+
+    const code = await runGet(["deployments", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    const message = error.mock.calls.map((c) => c[0]).join("\n");
+    expect(message).toContain("no credentials");
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: a kind the cluster's discovery has never heard of is an explicit error, not \"No resources found.\"", async () => {
+    const cluster = fakeCluster({ serves: [] });
+    const { error, log } = spyConsole();
+
+    const code = await runGet(["widgets"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain(`doesn't have a resource type "widgets"`);
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  test("a single get with a name that does not exist reports NotFound, kubectl-style", async () => {
+    const cluster = fakeCluster({});
+    const { error } = spyConsole();
+
+    const code = await runGet(["deployment", "ghost", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("NotFound");
+  });
+
+  test("-o json prints the raw object, not the table", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedObject("apps/v1", "Deployment", "web", "prod"),
+      },
+    });
+    const { log } = spyConsole();
+
+    await runGet(["deployment", "web", "-n", "prod", "-o", "json"], { connect: cluster.connector });
+
+    const parsed = JSON.parse(log.mock.calls[0][0] as string);
+    expect(parsed.metadata.name).toBe("web");
+  });
+
+  test("resolves a declared entity name directly, chant vocabulary first", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: ownedObject("apps/v1", "Deployment", "web", "prod"),
+      },
+    });
+    const project = fakeProjectContext({
+      myWeb: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "web", namespace: "prod" } }),
+    });
+    const { log } = spyConsole();
+
+    const code = await runGet(["myWeb"], { connect: cluster.connector, loadProject: async () => project });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls.map((c) => c[0]).join("\n");
+    expect(out).toContain("web");
+  });
+});

package/src/kube/get.ts

@@ -0,0 +1,190 @@
+/**
+ * `chant kube get` (chant #1079) — kubectl's own muscle-memory verb, plus the
+ * chant verdict column the issue's acceptance criterion names.
+ *
+ * The cluster edge is the typed client (chant #1074/#1177), reached the same
+ * way every other read does: `--env` resolves and honors the cluster
+ * binding (chant #1100/#1155, refusing loudly on a mismatch), `--context` is
+ * an explicit override, neither given falls back to the ambient kubeconfig
+ * context. A connect failure, an RBAC-denied read, or a kind the cluster's
+ * discovery has never heard of all render as an honest message rather than
+ * an empty table — "No resources found." is reserved for the one case that
+ * actually means it: the kind is real and there are zero live instances.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { formatUnobserved, type UnobservedEntity } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure, isUnknownResource } from "../api/classify";
+import { statusFromObject } from "../describe-resources";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom } from "./flags";
+import { loadKubeProjectContext, type KubeProjectContext } from "./project";
+import { resolveKubeTarget, matchLiveObject, isTargetError, type KubeTarget } from "./target";
+import { verdictFor } from "./verdict";
+import {
+  parseOutput,
+  renderKubeTable,
+  relativeAge,
+  renderJson,
+  renderYaml,
+  renderName,
+  renderChantSource,
+  renderJsonPath,
+  renderCustomColumns,
+  type KubeRow,
+} from "./render";
+
+export interface GetDeps {
+  connect?: K8sConnector;
+  loadProject?: (cwd?: string) => Promise<KubeProjectContext | undefined>;
+}
+
+function targetLabel(target: KubeTarget): string {
+  return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+
+export async function runGet(rawArgs: string[], deps: GetDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+  const loadProject = deps.loadProject ?? loadKubeProjectContext;
+
+  let flags;
+  try {
+    flags = parseKubeFlags(rawArgs);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  let output;
+  try {
+    output = parseOutput(flags.values.output);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    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;
+  }
+
+  const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+  if (connected.kind === "unobserved") {
+    console.error(formatUnobserved(targetLabel(target), unobservedEntity(connected)));
+    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 = flags.flags.allNamespaces ? undefined : (target.namespace ?? client.defaultNamespace);
+  const ref = { apiVersion: info.apiVersion, kind: info.kind };
+
+  let objects: K8sObject[];
+  if (target.name) {
+    try {
+      const obj = await client.readIfPresent({ ...ref, name: target.name, ...(namespace ? { namespace } : {}) });
+      if (!obj) {
+        console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+        return 1;
+      }
+      objects = [obj];
+    } catch (err) {
+      if (isUnknownResource(err)) {
+        console.error(`error: the server doesn't have a resource type "${targetLabel(target)}"`);
+        return 1;
+      }
+      const outcome = classifyApiFailure(err);
+      console.error(
+        formatUnobserved(`${info.kind}/${target.name}`, {
+          reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+          detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+        }),
+      );
+      return 1;
+    }
+  } else {
+    try {
+      objects = await client.list(ref, {
+        ...(namespace ? { namespace } : {}),
+        ...(flags.values.selector ? { labelSelector: flags.values.selector } : {}),
+      });
+    } catch (err) {
+      const outcome = classifyApiFailure(err);
+      console.error(
+        formatUnobserved(info.kind, {
+          reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+          detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+        }),
+      );
+      return 1;
+    }
+  }
+
+  switch (output.kind) {
+    case "json":
+      console.log(renderJson(objects));
+      return 0;
+    case "yaml":
+      console.log(renderYaml(objects));
+      return 0;
+    case "name":
+      console.log(renderName(objects));
+      return 0;
+    case "chant":
+      console.log(renderChantSource(objects));
+      return 0;
+    case "jsonpath":
+      console.log(renderJsonPath(output.expr, objects));
+      return 0;
+    case "custom-columns":
+      console.log(renderCustomColumns(output.spec, objects));
+      return 0;
+  }
+
+  const allNamespaces = flags.flags.allNamespaces ?? false;
+  const rows: KubeRow[] = objects.map((obj) => {
+    const match = matchLiveObject(project, {
+      apiVersion: obj.apiVersion ?? info.apiVersion,
+      kind: obj.kind ?? info.kind,
+      name: obj.metadata?.name ?? "",
+      namespace: obj.metadata?.namespace,
+    });
+    return {
+      namespace: obj.metadata?.namespace,
+      name: obj.metadata?.name ?? "",
+      kind: info.kind,
+      status: statusFromObject(obj),
+      age: relativeAge(obj.metadata?.creationTimestamp),
+      verdict: project ? verdictFor(obj, match) : "unavailable",
+      labels: obj.metadata?.labels,
+      object: obj,
+    };
+  });
+
+  console.log(renderKubeTable(rows, { allNamespaces, wide: output.kind === "wide", showVerdict: true }));
+  return 0;
+}
+
+function unobservedEntity(connected: { reason: UnobservedEntity["reason"]; detail: string }): UnobservedEntity {
+  return { reason: connected.reason, detail: connected.detail };
+}

package/src/kube/group.test.ts

@@ -0,0 +1,33 @@
+import { describe, test, expect } from "vitest";
+import { kubeCommandGroup } from "./group";
+
+describe("kubeCommandGroup (chant #1079)", () => {
+  test("mounts as \"kube\" and carries every verb the issue names", () => {
+    const group = kubeCommandGroup();
+    expect(group.name).toBe("kube");
+    const names = group.commands.map((c) => c.name);
+    expect(names).toEqual(
+      expect.arrayContaining(["version", "get", "describe", "logs", "events", "top", "wait", "source", "apply", "delete"]),
+    );
+  });
+
+  test("every verb carries a non-empty description (shown in --help composition)", () => {
+    const group = kubeCommandGroup();
+    for (const command of group.commands) {
+      expect(command.description.length).toBeGreaterThan(0);
+    }
+  });
+
+  test("version still behaves exactly as #1078 shipped it (unchanged tenant)", async () => {
+    const group = kubeCommandGroup();
+    const version = group.commands.find((c) => c.name === "version")!;
+    const logSpy = (await import("vitest")).vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const code = await version.handler({ verb: "version", rawArgs: ["--format", "json"] });
+      expect(code).toBe(0);
+      expect(JSON.parse(logSpy.mock.calls[0][0] as string)).toHaveProperty("schemaVersion");
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});

package/src/kube/group.ts

@@ -0,0 +1,125 @@
+/**
+ * `chant kube` — the terminal surface over the typed client (chant #1079),
+ * mounted through the command-group seam #1078 built and reserved this exact
+ * namespace for (`lexicons/k8s/src/plugin.ts`'s `commands()`).
+ *
+ * Every verb below except `version` dynamically imports its own module. That
+ * is not a style choice: `describe-resources.ts`, `api/connect.ts` and the
+ * rest of the read/write paths sit behind a dynamic import specifically so
+ * `chant build` never has to resolve `@intentius/chant-k8s-client`
+ * (chant #1074, `examples/k8s-client-boundary.test.ts`). This module IS
+ * statically reachable from `plugin.ts` — it is plain data, a list of verb
+ * names and descriptions — so every verb whose implementation touches the
+ * client must be reached from here only through `await import(...)`, exactly
+ * like `version`'s existing `await import("../spec/fetch")`.
+ */
+
+import type { CommandGroup, CommandGroupContext } from "@intentius/chant/cli/command-group";
+import { splitJoinedFlags, unknownFlagError } from "@intentius/chant/cli/command-group";
+
+async function versionHandler(ctx: CommandGroupContext): Promise<number> {
+  const args = splitJoinedFlags(ctx.rawArgs);
+  let format: "text" | "json" = "text";
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--format" || a === "-f") {
+      format = args[++i] === "json" ? "json" : "text";
+    } else if (a.startsWith("-")) {
+      throw unknownFlagError(a, `"chant kube version" only accepts --format <text|json>.`);
+    }
+  }
+  const { K8S_SCHEMA_VERSION } = await import("../spec/fetch");
+  if (format === "json") {
+    console.log(JSON.stringify({ schemaVersion: K8S_SCHEMA_VERSION }));
+  } else {
+    console.log(K8S_SCHEMA_VERSION);
+  }
+  return 0;
+}
+
+/** The full `chant kube` verb group. */
+export function kubeCommandGroup(): CommandGroup {
+  return {
+    name: "kube",
+    description: "Terminal surface over the k8s typed client — kubectl-compatible reads plus chant's own verdict, source, and gated writes",
+    commands: [
+      {
+        name: "version",
+        description: "Print the pinned Kubernetes API schema version this lexicon was generated from",
+        handler: versionHandler,
+      },
+      {
+        name: "get",
+        description: "List or read live resources — kubectl's own flags, plus a declared/owned/drifted/foreign-owned column",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runGet } = await import("./get");
+          return runGet(ctx.rawArgs);
+        },
+      },
+      {
+        name: "describe",
+        description: "Human-readable detail for one or more resources, including chant's provenance and the object's Events",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runDescribe } = await import("./describe");
+          return runDescribe(ctx.rawArgs);
+        },
+      },
+      {
+        name: "logs",
+        description: "A Pod's log (snapshot only — no --follow)",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runLogs } = await import("./logs");
+          return runLogs(ctx.rawArgs);
+        },
+      },
+      {
+        name: "events",
+        description: "List Events, oldest first, optionally filtered with --for=Kind/name",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runEvents } = await import("./events");
+          return runEvents(ctx.rawArgs);
+        },
+      },
+      {
+        name: "top",
+        description: "Pod/node resource usage from metrics.k8s.io, when the cluster runs metrics-server",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runTop } = await import("./top");
+          return runTop(ctx.rawArgs);
+        },
+      },
+      {
+        name: "wait",
+        description: "Block until a resource's readiness spec is met (registry-driven — the same one op/activities/wait-for-ready.ts uses)",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runWait } = await import("./wait");
+          return runWait(ctx.rawArgs);
+        },
+      },
+      {
+        name: "source",
+        description: "Resolve a live object back to the .ts file and composite that declared it",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runSource } = await import("./source");
+          return runSource(ctx.rawArgs);
+        },
+      },
+      {
+        name: "apply",
+        description: "Server-side apply a manifest (dry-run preview by default — pass --yes to persist); same machinery the Op activity uses",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runApply } = await import("./apply");
+          return runApply(ctx.rawArgs);
+        },
+      },
+      {
+        name: "delete",
+        description: "Delete one named resource (never a bare kind sweep; preview by default — pass --yes to delete)",
+        async handler(ctx: CommandGroupContext): Promise<number> {
+          const { runDelete } = await import("./delete");
+          return runDelete(ctx.rawArgs);
+        },
+      },
+    ],
+  };
+}