@intentius/chant 0.30.0 → 0.32.0

package/dist/managed-fields.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Kubernetes-object-shape utilities shared by every lexicon whose live model
+ * is a Kubernetes API object — the k8s lexicon itself (chant #1076) and GCP's
+ * Config Connector custom resources (chant #1087).
+ *
+ * A Config Connector custom resource *is* a Kubernetes object: it carries the
+ * same envelope (`status`, `metadata.{uid,resourceVersion,generation,
+ * creationTimestamp,managedFields,selfLink}`), the same SSA `fieldsV1`
+ * encoding for `metadata.managedFields`, and some CNRM kinds even embed
+ * genuinely k8s-shaped substructures (Cloud Run's `RunService` wraps a
+ * Knative pod spec with `containers`/`env`/`ports`, keyed the same way a
+ * Deployment's are). None of that is specific to chant's k8s *lexicon* — it
+ * is a fact about the Kubernetes API that any reader of a Kubernetes-shaped
+ * object needs, regardless of which lexicon is doing the reading.
+ *
+ * This module lives in core rather than in the k8s lexicon for the same
+ * reason `./kubectl-context.ts`'s `resolveClusterTarget` does (chant #1100):
+ * GCP's observation needs it too, without taking a dependency on the k8s
+ * lexicon package. Nothing here is keyed by chant's own k8s entityType
+ * catalog (`K8s::Apps::Deployment`, …) or by any lexicon's service-default
+ * table — that stays lexicon-specific, layered on top of what's here
+ * (`lexicons/k8s/src/deep-observe-hooks.ts`'s `K8S_SERVICE_DEFAULTS`,
+ * `lexicons/gcp/src/deep-observe.ts`'s CNRM-specific annotation noise).
+ */
+import type { DeepArrayElement, DeepNode } from "./deep-observation.js";
+/**
+ * Paths every Kubernetes API object carries regardless of kind, matched on
+ * the exact index-erased pattern (there is exactly one `status`, one
+ * `metadata.managedFields`, per object — no per-type variation the way AWS's
+ * `Arn`/`RoleId` repeat at every nesting depth).
+ *
+ * - `status` — the whole subtree is server-computed; no declarative source
+ *   (chant's k8s manifests, chant's Config Connector CRs) ever authors it.
+ * - `metadata.uid`/`resourceVersion`/`generation`/`creationTimestamp` — minted
+ *   and incremented by the API server, never authored.
+ * - `metadata.managedFields` — the bookkeeping the ownership walk below reads
+ *   to decide everything else. Left in the tree it would report as permanent
+ *   drift (a timestamp changes on every write) and would recurse into the
+ *   encoded `fieldsV1` structure as if it were ordinary properties.
+ * - `metadata.selfLink` — deprecated API-server bookkeeping some clusters
+ *   still echo; never a declared field.
+ */
+export declare const K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS: ReadonlySet<string>;
+/**
+ * Kubernetes' own well-known list-map-key conventions for the substructures
+ * that recur across kinds and across lexicons: containers/initContainers/
+ * ephemeralContainers and `env`/`volumes` keyed by `name` — the same field
+ * Kubernetes' strategic-merge-patch and SSA's `list-map-keys` key on for
+ * these lists — and container ports keyed by `containerPort`+`protocol`,
+ * Service ports keyed by `port`+`protocol` (Kubernetes' own SSA
+ * `list-map-keys` for each). Both port shapes are handled under one `ports`
+ * branch by checking which field is present.
+ *
+ * Entity-type-agnostic on purpose: whether an array named `containers`
+ * belongs to a `K8s::Apps::Deployment` or to a GCP `RunService`'s embedded
+ * pod spec, the identity Kubernetes assigns each element is the same.
+ */
+export declare function k8sListMapOrderKey(element: DeepArrayElement): string | undefined;
+/**
+ * The structural shape of one `metadata.managedFields` entry this module
+ * needs. Matches `@intentius/chant-k8s-client`'s `ManagedFieldsEntry`
+ * (chant #1075) field-for-field, but is declared independently here rather
+ * than imported from that package: core must stay reachable from any
+ * lexicon's build path, and the k8s client package is deliberately *not*
+ * reachable from one (chant #1074's structural boundary,
+ * `examples/k8s-client-boundary.test.ts`). A caller that already has a real
+ * `ManagedFieldsEntry[]` (the k8s lexicon) passes it straight through —
+ * TypeScript's structural typing accepts it with no cast.
+ */
+export interface ManagedFieldsEntryLike {
+    manager?: string;
+    operation?: string;
+    subresource?: string;
+    fieldsV1?: Record<string, unknown>;
+}
+/** One live object's managed-fields ownership, resolved to chant dot-paths. */
+export interface OwnershipSets {
+    /** Paths any chant field manager owns on this object. */
+    chantOwned: ReadonlySet<string>;
+    /** Paths owned by a manager that is not chant. */
+    foreignOwned: ReadonlySet<string>;
+    /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
+    foreignContested: ReadonlySet<string>;
+}
+/**
+ * Build the three ownership sets for one live object. `entries` is
+ * `metadata.managedFields`, already decoded (`@intentius/chant-k8s-client`'s
+ * `managedFieldsOf` for the k8s lexicon; a plain `JSON.parse` of `kubectl get
+ * -o json` for gcp); `isChantManager` classifies each entry's manager name
+ * — matched on the `chant`/`chant:<stack>` family per chant #1075, but the
+ * matcher itself is supplied by the caller rather than fixed here, because
+ * what counts as "chant" is not the same fact on every lexicon's apply path
+ * (see gcp's `deep-observe.ts` module doc for why that matters there).
+ *
+ * Subresource entries (`status`, `scale`) are excluded: a controller writing
+ * a Deployment's `status` is not competing for the spec chant declared, the
+ * same reasoning `@intentius/chant-k8s-client`'s `fieldsOwnedBy` default
+ * already encodes.
+ */
+export declare function buildOwnershipSets(entries: readonly ManagedFieldsEntryLike[], liveRoot: Record<string, unknown>, declaredRoot: Record<string, unknown>, isChantManager: (manager: string | undefined) => boolean): OwnershipSets;
+/**
+ * The three-question managed-fields prune rule, as a predicate over a
+ * {@link DeepNode} plus one object's precomputed {@link OwnershipSets} —
+ * shared by every lexicon layering a per-resource managed-fields prune on
+ * top of its own static rules (k8s's `perResourceHooks`, gcp's equivalent):
+ *
+ * 1. Chant owns the path (any chant manager) → never pruned by this rule.
+ * 2. A different manager owns it, chant does not, and it is not declared →
+ *    controller-managed noise, pruned.
+ * 3. It is declared, regardless of who owns it live → never pruned by this
+ *    rule, because chant's source is a statement of intent independent of
+ *    which write currently holds the field.
+ *
+ * Only applies to the live side — the declared tree carries no managedFields
+ * to prune by.
+ */
+export declare function pruneByOwnership(node: DeepNode, sets: OwnershipSets): boolean;
+//# sourceMappingURL=managed-fields.d.ts.map

package/dist/managed-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-fields.d.ts","sourceRoot":"","sources":["../src/managed-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIrE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kCAAkC,EAAE,WAAW,CAAC,MAAM,CAQjE,CAAC;AAwBH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAwBhF;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAChC,kDAAkD;IAClD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC,8HAA8H;IAC9H,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACvC;AAsHD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,cAAc,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,GACvD,aAAa,CAmBf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAM7E"}

package/dist/owner-chain.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Owner-chain classification (chant #1077).
+ *
+ * `describeResources()` already lets a lexicon report a live object it never
+ * asked about by name — that is how `orphan` has always worked (a resource
+ * present in `observedNow` that is not in `declared`). Every existing consumer
+ * treats every such object the same way: undeclared, so a delete/adopt
+ * candidate.
+ *
+ * On Kubernetes that conflates two different things. A console-added SNS
+ * subscription (the AWS case #1014/#1015 was built for) really is out-of-band
+ * drift. A Pod a declared Deployment's controller created is not drift at
+ * all — it is the runtime doing its job, and it will be recreated the moment
+ * it is deleted. `ownerReferences` is what tells them apart: the Pod's chain
+ * of owners terminates at the Deployment, which is declared.
+ *
+ * This module owns the *category* — the four possible answers to "where does
+ * this object's owner chain lead" — and the pure algorithm that walks a chain
+ * to one of them. A lexicon supplies the chain (reading `ownerReferences`,
+ * possibly across several API reads to walk past an intermediate object chant
+ * never declared, e.g. a ReplicaSet between a Pod and its Deployment); this
+ * module supplies the bounded, cycle-safe interpretation, so that logic is
+ * written and tested once rather than once per lexicon.
+ */
+/**
+ * Where a live, undeclared resource's owner-reference chain leads.
+ *
+ * - `declared` — the chain reaches an entity chant's own build declared. This
+ *   is the whole point of #1077: the diff engine reads this as `runtime`, not
+ *   `orphan`, and never proposes deleting it.
+ * - `unowned` — the resource carries no owner reference at all. A genuinely
+ *   standalone live object; classifies as `orphan`, unchanged from before this
+ *   module existed.
+ * - `foreign` — the chain fully resolves (every hop was readable, no cycle, no
+ *   depth bound hit) but terminates at a live root that is not declared.
+ *   Still `orphan` — it belongs to something real, just not to this build.
+ * - `unknown` — some hop could not be resolved: an unreadable owner, a cycle,
+ *   or the depth bound. Composes with #1168's tri-state precedent: an owner
+ *   chain chant could not fully verify is not a confirmed anything, so it is
+ *   never escalated to `declared` and stays routed as `orphan` today, exactly
+ *   as `foreign`/`unowned` are — never treated as a safer-than-warranted
+ *   `runtime` classification just because the read was incomplete.
+ */
+export type OwnerChainVerdict = {
+    readonly root: "declared";
+    readonly entity: string;
+} | {
+    readonly root: "unowned";
+} | {
+    readonly root: "foreign";
+} | {
+    readonly root: "unknown";
+};
+/**
+ * One node in the owner graph a lexicon assembles for {@link classifyOwnerChain}.
+ * Keyed externally (in the `nodes` map passed to the walk) by whatever stable
+ * identity the lexicon's provider uses — a Kubernetes UID, for instance.
+ */
+export interface OwnerChainNode {
+    /**
+     * This node's immediate owner, by its key in the same `nodes` map. Omit
+     * (`undefined`) when the object carries no owner reference at all — that is
+     * how a chain's *starting* node reports `unowned` rather than `unknown`.
+     */
+    ownerId?: string;
+    /**
+     * True when this node's own owner could not be determined — the read
+     * failed, was denied, or the object simply could not be fetched. Distinct
+     * from having no owner: this says "unknown", not "none".
+     */
+    ownerUnreadable?: boolean;
+    /**
+     * The declared chant entity name, when this node corresponds to one. A node
+     * with this set ends the walk immediately with `{ root: "declared" }` —
+     * whatever `ownerId`/`ownerUnreadable` it might also carry is irrelevant,
+     * since the chain already reached what it was looking for.
+     */
+    declaredEntity?: string;
+}
+/** Default bound on how many owner hops {@link classifyOwnerChain} will walk
+ * before giving up conservatively. Kubernetes' own garbage collector does not
+ * bound this at all, but a live read has to — a bound this generous is well
+ * past any real ownership depth (Pod → ReplicaSet → Deployment is 2 hops) and
+ * exists only to turn a corrupt or adversarial chain into `unknown` rather
+ * than an infinite walk. */
+export declare const DEFAULT_MAX_OWNER_CHAIN_DEPTH = 12;
+/**
+ * Walk the owner chain starting at `startId` through `nodes`, bounded and
+ * cycle-safe. Pure — the caller has already done whatever I/O was needed to
+ * populate `nodes`; this function only interprets the graph it was given.
+ *
+ * `nodes` need not contain every ancestor: a node the caller never resolved
+ * (because it gave up, hit the caller's own fetch bound, or the read failed)
+ * is simply absent from the map, and a reference to an absent node classifies
+ * as `unknown` — the conservative answer, same as an explicit
+ * `ownerUnreadable`.
+ */
+export declare function classifyOwnerChain(startId: string, nodes: ReadonlyMap<string, OwnerChainNode>, maxDepth?: number): OwnerChainVerdict;
+//# sourceMappingURL=owner-chain.d.ts.map

package/dist/owner-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-chain.d.ts","sourceRoot":"","sources":["../src/owner-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;4BAK4B;AAC5B,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAAC,EAC1C,QAAQ,GAAE,MAAsC,GAC/C,iBAAiB,CA2BnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/command-group.test.ts

@@ -0,0 +1,208 @@
+import { describe, test, expect } from "vitest";
+import type { LexiconPlugin } from "../lexicon";
+import {
+  resolveCommandGroupVerb,
+  collectCommandGroups,
+  dispatchCommandGroup,
+  formatCommandGroupsHelp,
+  splitJoinedFlags,
+  unknownFlagError,
+  RESERVED_COMMAND_NAMES,
+  type CommandGroup,
+} from "./command-group";
+
+const noopAsync = async () => {};
+
+/** Minimal LexiconPlugin — only the fields relevant to a given test. */
+function makePlugin(name: string, group?: CommandGroup): LexiconPlugin {
+  const plugin: LexiconPlugin = {
+    name,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serializer: { name, serialize: () => "" } as any,
+    generate: noopAsync,
+    validate: noopAsync,
+    coverage: noopAsync,
+    package: noopAsync,
+  };
+  if (group) plugin.commands = () => group;
+  return plugin;
+}
+
+function makeGroup(overrides: Partial<CommandGroup> = {}): CommandGroup {
+  return {
+    name: "kube",
+    description: "Kubernetes verb group",
+    commands: [
+      { name: "get", description: "Get resources", handler: async () => 0 },
+      { name: "version", description: "Print schema version", handler: async () => 0 },
+    ],
+    ...overrides,
+  };
+}
+
+describe("resolveCommandGroupVerb", () => {
+  test("mounts: finds the group and verb contributed by a plugin", () => {
+    const group = makeGroup();
+    const plugins = [makePlugin("k8s", group)];
+    const result = resolveCommandGroupVerb(plugins, "kube", "get");
+    expect(result.kind).toBe("matched");
+    if (result.kind === "matched") {
+      expect(result.plugin.name).toBe("k8s");
+      expect(result.group).toBe(group);
+      expect(result.command.name).toBe("get");
+    }
+  });
+
+  test("no-capability lexicon is unaffected: a plugin with no commands() is skipped", () => {
+    const plugins = [makePlugin("aws"), makePlugin("k8s", makeGroup())];
+    const result = resolveCommandGroupVerb(plugins, "kube", "get");
+    expect(result.kind).toBe("matched");
+  });
+
+  test("returns no-group when nothing claims the namespace", () => {
+    const plugins = [makePlugin("aws"), makePlugin("gcp")];
+    const result = resolveCommandGroupVerb(plugins, "kube", "get");
+    expect(result.kind).toBe("no-group");
+  });
+
+  test("returns no-group for an empty plugin list", () => {
+    expect(resolveCommandGroupVerb([], "kube", "get").kind).toBe("no-group");
+  });
+
+  test("returns unknown-verb when the group matches but the verb doesn't", () => {
+    const plugins = [makePlugin("k8s", makeGroup())];
+    const result = resolveCommandGroupVerb(plugins, "kube", "bogus");
+    expect(result.kind).toBe("unknown-verb");
+    if (result.kind === "unknown-verb") {
+      expect(result.group.name).toBe("kube");
+    }
+  });
+
+  test("returns no-verb when the group matches and no verb was given", () => {
+    const plugins = [makePlugin("k8s", makeGroup())];
+    const result = resolveCommandGroupVerb(plugins, "kube", undefined);
+    expect(result.kind).toBe("no-verb");
+  });
+
+  test("never invokes a verb's handler while resolving — registration is data, not execution", () => {
+    let invoked = false;
+    const group: CommandGroup = {
+      name: "kube",
+      description: "d",
+      commands: [{ name: "get", description: "d", handler: async () => { invoked = true; return 0; } }],
+    };
+    resolveCommandGroupVerb([makePlugin("k8s", group)], "kube", "get");
+    expect(invoked).toBe(false);
+  });
+});
+
+describe("collectCommandGroups", () => {
+  test("lists groups from plugins in order; skips plugins without one", () => {
+    const g1 = makeGroup({ name: "kube" });
+    const g2 = makeGroup({ name: "flycmd", description: "Fly verb group" });
+    const groups = collectCommandGroups([makePlugin("aws"), makePlugin("k8s", g1), makePlugin("fly", g2)]);
+    expect(groups).toEqual([g1, g2]);
+  });
+
+  test("empty when no plugin contributes a group — an absent slot changes nothing", () => {
+    expect(collectCommandGroups([makePlugin("aws"), makePlugin("gcp")])).toEqual([]);
+  });
+});
+
+describe("dispatchCommandGroup", () => {
+  test("dispatches: runs the matched verb's handler and returns its exit code", async () => {
+    let seenCtx: unknown;
+    const group: CommandGroup = {
+      name: "kube",
+      description: "d",
+      commands: [
+        {
+          name: "get",
+          description: "d",
+          handler: async (ctx) => {
+            seenCtx = ctx;
+            return 3;
+          },
+        },
+      ],
+    };
+    const result = await dispatchCommandGroup([makePlugin("k8s", group)], "kube", "get", ["pods", "-o", "wide"]);
+    expect(result).toEqual({ kind: "ran", exitCode: 3 });
+    expect(seenCtx).toEqual({ verb: "get", rawArgs: ["pods", "-o", "wide"] });
+  });
+
+  test("propagates a no-group result unchanged", async () => {
+    const result = await dispatchCommandGroup([makePlugin("aws")], "kube", "get", []);
+    expect(result).toEqual({ kind: "no-group" });
+  });
+
+  test("unknown verb produces a usage-error listing the group's real verbs", async () => {
+    const result = await dispatchCommandGroup([makePlugin("k8s", makeGroup())], "kube", "bogus", []);
+    expect(result.kind).toBe("usage-error");
+    if (result.kind === "usage-error") {
+      expect(result.message).toMatch(/Unknown kube subcommand: bogus/);
+      expect(result.hint).toMatch(/get/);
+      expect(result.hint).toMatch(/version/);
+    }
+  });
+
+  test("bare group with no verb produces a usage-error, not a crash", async () => {
+    const result = await dispatchCommandGroup([makePlugin("k8s", makeGroup())], "kube", undefined, []);
+    expect(result.kind).toBe("usage-error");
+    if (result.kind === "usage-error") {
+      expect(result.message).toMatch(/Usage: chant kube <verb>/);
+    }
+  });
+});
+
+describe("formatCommandGroupsHelp", () => {
+  test("composes group + verb listing for --help", () => {
+    const text = formatCommandGroupsHelp([makeGroup()]);
+    expect(text).toMatch(/Lexicon commands:/);
+    expect(text).toMatch(/kube/);
+    expect(text).toMatch(/get/);
+    expect(text).toMatch(/version/);
+  });
+
+  test("empty string when there are no groups", () => {
+    expect(formatCommandGroupsHelp([])).toBe("");
+  });
+});
+
+describe("splitJoinedFlags (#1127 discipline, reused by mounted commands)", () => {
+  test("splits a joined --flag=value token into two elements", () => {
+    expect(splitJoinedFlags(["--format=json"])).toEqual(["--format", "json"]);
+  });
+
+  test("splits only at the first =, preserving a value that itself contains =", () => {
+    expect(splitJoinedFlags(["--selector=env=prod"])).toEqual(["--selector", "env=prod"]);
+  });
+
+  test("leaves non-joined tokens untouched", () => {
+    expect(splitJoinedFlags(["get", "pods", "-o", "wide"])).toEqual(["get", "pods", "-o", "wide"]);
+  });
+
+  test("throws when a declared boolean flag is given a joined value", () => {
+    expect(() => splitJoinedFlags(["--watch=true"], new Set(["--watch"]))).toThrow(/--watch is a boolean flag/);
+  });
+});
+
+describe("unknownFlagError (mounted-command unknown-flag error)", () => {
+  test("produces the same 'Unknown flag' message shape core's own parser uses", () => {
+    const err = unknownFlagError("--bogus");
+    expect(err.message).toMatch(/^Unknown flag: --bogus/);
+  });
+
+  test("accepts a custom hint for the mounted command's own usage", () => {
+    const err = unknownFlagError("--bogus", "chant kube version only accepts --format.");
+    expect(err.message).toMatch(/only accepts --format/);
+  });
+});
+
+describe("RESERVED_COMMAND_NAMES", () => {
+  test("includes every core top-level word a lexicon must not shadow", () => {
+    for (const name of ["build", "lint", "run", "emulator", "lifecycle", "components", "serve", "dev", "carve"]) {
+      expect(RESERVED_COMMAND_NAMES.has(name)).toBe(true);
+    }
+  });
+});

package/src/cli/command-group.ts

@@ -0,0 +1,199 @@
+import type { LexiconPlugin } from "../lexicon";
+
+/**
+ * The lexicon command-group seam (chant #1078).
+ *
+ * A lexicon may contribute one CLI verb group, mounted under `chant <name>
+ * <verb>` (e.g. `chant kube get`). Core's only job is to find the group and
+ * call the matched verb's handler — it never inspects, validates, or
+ * special-cases what a verb does. That is the whole point: `get -o wide -l
+ * app=x --field-selector` is Kubernetes vocabulary, not something core could
+ * generalize even if it tried (see #1078's motivating case, consumed by
+ * #1079's `chant kube`).
+ *
+ * This is a DIFFERENT shape from `LexiconPlugin.emulator` (#920): the
+ * emulator capability is DATA that core itself aggregates across every
+ * configured lexicon (`chant emulator up --all` loops every plugin with an
+ * `emulator`). A command group is BEHAVIOR owned end-to-end by one lexicon —
+ * core dispatches to it wholesale and never loops or merges across plugins.
+ * The two capabilities are not layers of the same thing; migrating
+ * `emulator` onto this seam would be a worse fit, not a simplification.
+ */
+
+/** Context handed to a mounted command's handler. */
+export interface CommandGroupContext {
+  /** The verb invoked, e.g. `"get"` for `chant kube get pods`. */
+  verb: string;
+  /**
+   * Every CLI token after the group name and verb, unparsed — e.g. `chant
+   * kube get pods -o wide` hands `["pods", "-o", "wide"]`. Core does not
+   * interpret these: it has no vocabulary for a lexicon's own verbs. A
+   * handler that wants #1127's joined-`--flag=value` splitting and
+   * unknown-flag rejection can reuse {@link splitJoinedFlags} /
+   * {@link unknownFlagError} from this module for the same discipline core's
+   * own parser applies, scoped to whatever flags this verb actually accepts.
+   */
+  rawArgs: string[];
+}
+
+/** One verb within a lexicon-contributed command group. */
+export interface CommandGroupCommand {
+  /** Verb name, e.g. `"get"`, `"logs"`, `"version"`. */
+  name: string;
+  /** One-line description shown in `chant --help` and in usage errors. */
+  description: string;
+  /** Runs the verb. Returns the process exit code. */
+  handler: (ctx: CommandGroupContext) => Promise<number>;
+}
+
+/**
+ * A CLI verb group contributed by a lexicon (chant #1078). Mounted under
+ * `chant <name> <verb>`. Returned from {@link LexiconPlugin.commands}.
+ */
+export interface CommandGroup {
+  /** Namespace this group mounts under, e.g. `"kube"` for `chant kube <verb>`. */
+  name: string;
+  /** One-line description shown in `chant --help`'s composed listing. */
+  description: string;
+  /** Verbs in this group. */
+  commands: CommandGroupCommand[];
+}
+
+/**
+ * Top-level command words core's own static registry already owns
+ * (`packages/core/src/cli/main.ts`'s `registry`). A lexicon's `commands()`
+ * group name colliding with one of these is always unreachable — core's own
+ * registry is resolved first, unconditionally — so `checkConflicts`
+ * (./conflict-check.ts) treats a collision as a hard, loud failure at
+ * plugin-load time rather than a silently-ignored command group. Hand
+ * maintained alongside the registry; update both together.
+ */
+export const RESERVED_COMMAND_NAMES: ReadonlySet<string> = new Set([
+  "build", "lint", "list", "describe", "import", "audit", "migrate", "carve",
+  "init", "update", "doctor", "dev", "run", "graph", "vendor", "lifecycle",
+  "lc", "components", "emulator", "serve",
+]);
+
+/**
+ * chant #1127 — split a joined `--flag=value` token into two array elements
+ * (`--flag`, `value`), the same discipline core's own `parseArgs` applies,
+ * generalized so a lexicon's mounted command can reuse it for its own flag
+ * vocabulary instead of reimplementing the split. Throws the same shape of
+ * error as core's parser when `flag` is declared boolean but was given a
+ * value — a boolean has nothing to assign, and silently reinterpreting the
+ * joined value as the next positional would be exactly the silent misparse
+ * #1127 closed for core's own flags.
+ */
+export function splitJoinedFlags(args: string[], booleanFlags: ReadonlySet<string> = new Set()): string[] {
+  const out: string[] = [];
+  for (const arg of args) {
+    if (arg.startsWith("--") && arg.includes("=")) {
+      const eq = arg.indexOf("=");
+      const flag = arg.slice(0, eq);
+      const value = arg.slice(eq + 1);
+      if (booleanFlags.has(flag)) {
+        throw new Error(`${arg} — ${flag} is a boolean flag and does not take a value. Pass ${flag} on its own.`);
+      }
+      out.push(flag, value);
+    } else {
+      out.push(arg);
+    }
+  }
+  return out;
+}
+
+/**
+ * Same "Unknown flag" error shape core's own `parseArgs` throws (#1127), for
+ * a mounted command's own flag vocabulary — core doesn't know that
+ * vocabulary, so it can't produce this error itself; the handler does, using
+ * this helper for a consistent message.
+ */
+export function unknownFlagError(flag: string, hint = `Run "chant --help" to see supported flags.`): Error {
+  return new Error(`Unknown flag: ${flag}\n${hint}`);
+}
+
+/** Result of looking up a command group + verb among loaded plugins. */
+export type CommandGroupLookup =
+  | { kind: "no-group" }
+  | { kind: "no-verb"; group: CommandGroup }
+  | { kind: "unknown-verb"; group: CommandGroup }
+  | { kind: "matched"; plugin: LexiconPlugin; group: CommandGroup; command: CommandGroupCommand };
+
+/**
+ * Find the plugin (if any) whose `commands()` group is named `groupName`,
+ * and the verb within it named `verbName`. Pure — does no I/O, calls
+ * `plugin.commands()` at most once per plugin (registration, not execution:
+ * this never invokes a verb's handler).
+ */
+export function resolveCommandGroupVerb(
+  plugins: readonly LexiconPlugin[],
+  groupName: string,
+  verbName: string | undefined,
+): CommandGroupLookup {
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (!group || group.name !== groupName) continue;
+    if (verbName === undefined) return { kind: "no-verb", group };
+    const command = group.commands.find((c) => c.name === verbName);
+    if (!command) return { kind: "unknown-verb", group };
+    return { kind: "matched", plugin, group, command };
+  }
+  return { kind: "no-group" };
+}
+
+/** Every command group contributed by the given loaded plugins, in plugin order. */
+export function collectCommandGroups(plugins: readonly LexiconPlugin[]): CommandGroup[] {
+  const groups: CommandGroup[] = [];
+  for (const plugin of plugins) {
+    const group = plugin.commands?.();
+    if (group) groups.push(group);
+  }
+  return groups;
+}
+
+/** Result of {@link dispatchCommandGroup}. */
+export type CommandGroupDispatch =
+  | { kind: "no-group" }
+  | { kind: "usage-error"; message: string; hint: string }
+  | { kind: "ran"; exitCode: number };
+
+/**
+ * Resolve `groupName`/`verbName` against the loaded plugins and, if matched,
+ * run the verb's handler with `rawArgs`. Returns `{ kind: "no-group" }` when
+ * nothing claims `groupName` at all — the caller's cue to fall back to its
+ * own "unknown command" handling — and a printable usage error when the
+ * group matched but the verb didn't (or was omitted).
+ */
+export async function dispatchCommandGroup(
+  plugins: readonly LexiconPlugin[],
+  groupName: string,
+  verbName: string | undefined,
+  rawArgs: string[],
+): Promise<CommandGroupDispatch> {
+  const lookup = resolveCommandGroupVerb(plugins, groupName, verbName);
+  if (lookup.kind === "no-group") return { kind: "no-group" };
+  if (lookup.kind === "matched") {
+    const exitCode = await lookup.command.handler({ verb: verbName as string, rawArgs });
+    return { kind: "ran", exitCode };
+  }
+  const verbs = lookup.group.commands.map((c) => `  ${c.name.padEnd(14)} ${c.description}`).join("\n");
+  const message =
+    lookup.kind === "unknown-verb"
+      ? `Unknown ${groupName} subcommand: ${verbName}`
+      : `Usage: chant ${groupName} <verb> [args...]`;
+  return { kind: "usage-error", message, hint: `Available verbs:\n${verbs}` };
+}
+
+/**
+ * Render the `--help` section listing every lexicon-contributed command
+ * group. Empty string when there are none, so a caller can splice it in
+ * unconditionally without an extra length check.
+ */
+export function formatCommandGroupsHelp(groups: readonly CommandGroup[]): string {
+  if (groups.length === 0) return "";
+  const lines = groups.flatMap((g) => [
+    `  ${g.name.padEnd(20)}  ${g.description}`,
+    ...g.commands.map((c) => `    ${g.name} ${c.name.padEnd(Math.max(1, 17 - g.name.length))}${c.description}`),
+  ]);
+  return `Lexicon commands:\n${lines.join("\n")}\n`;
+}