@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

package/dist/kube/apply.js

@@ -0,0 +1,90 @@
+/**
+ * `chant kube apply` (chant #1079) — "writes are not cloned": this calls
+ * `applyManifest` (`../op/activities/kubectl.ts`) directly, the exact
+ * function the k8s Op activity registers under `kubectlApply` — server-side
+ * apply, chant's field-manager identity, the same `FieldManagerConflictError`
+ * surface (chant #1075/#1178) — never a second implementation of `kubectl
+ * apply`. An explicit manifest path is mandatory; there is no bare-sweep form.
+ *
+ * The one thing this verb adds on top of the activity is a confirmation
+ * gate, matching the issue's "route through plan, gate, and ownership": a
+ * bare `chant kube apply -f x.yaml` performs a server-side dry run — every
+ * document validated and previewed, nothing persisted — and says so; only
+ * `--yes` performs the real, persisting apply. That is a deliberate
+ * divergence from `kubectl apply`, which persists by default; a terminal
+ * command that can rewrite a live Deployment is worth one extra keystroke of
+ * intent.
+ */
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector } from "../api/connect.js";
+import { classifyApiFailure, isMissingClientPackage, MISSING_CLIENT_DETAIL } from "../api/classify.js";
+import { applyManifest } from "../op/activities/kubectl.js";
+import { parseKubeFlags } from "./flags.js";
+export async function runApply(rawArgs, deps = {}) {
+    const connect = deps.connect ?? defaultK8sConnector;
+    const apply = deps.apply ?? applyManifest;
+    let flags;
+    try {
+        flags = parseKubeFlags(rawArgs, {
+            value: { "-f": "filename", "--filename": "filename", "--field-manager": "fieldManager" },
+            boolean: { "--force-conflicts": "forceConflicts", "--yes": "yes", "-y": "yes" },
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const manifest = flags.values.filename;
+    if (!manifest) {
+        console.error("error: --filename/-f is required — chant kube apply never applies without an explicit manifest path (no bare sweeps)");
+        return 1;
+    }
+    const dryRun = !(flags.flags.yes ?? false);
+    const args = {
+        manifest,
+        ...(flags.values.env !== undefined ? { environment: flags.values.env } : {}),
+        ...(flags.values.context !== undefined ? { context: flags.values.context } : {}),
+        ...(flags.values.fieldManager !== undefined ? { fieldManager: flags.values.fieldManager } : {}),
+        force: flags.flags.forceConflicts ?? false,
+        dryRun,
+    };
+    let result;
+    try {
+        result = await apply(args, undefined, connect);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "FieldManagerConflictError") {
+            console.error(err.message);
+            return 1;
+        }
+        if (err instanceof ClusterBindingMismatchError) {
+            console.error(formatUnobserved(manifest, { reason: "no-binding", detail: err.message }));
+            return 1;
+        }
+        if (isMissingClientPackage(err)) {
+            console.error(formatUnobserved(manifest, { reason: "read-failed", detail: MISSING_CLIENT_DETAIL }));
+            return 1;
+        }
+        const outcome = classifyApiFailure(err);
+        console.error(formatUnobserved(manifest, {
+            reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+            detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+        }));
+        return 1;
+    }
+    // applyManifest already logged one line per applied object (including,
+    // since chant #1079, whether it was a dry run) — this is the summary.
+    if (dryRun) {
+        console.log(`DRY RUN — ${result.applied.length} object(s) server-validated, nothing persisted. Pass --yes to apply for real.`);
+    }
+    else {
+        console.log(`applied ${result.applied.length} object(s) as field manager "${result.fieldManager}"`);
+        if (result.pruned.length > 0)
+            console.log(`pruned ${result.pruned.length} chant-owned object(s) no longer declared`);
+        if ((result.retained ?? []).length > 0) {
+            console.log(`retained ${result.retained.length} generated-once secret(s) no longer declared — never pruned; delete explicitly if you mean to`);
+        }
+    }
+    return 0;
+}

package/dist/kube/connect.js

@@ -0,0 +1,46 @@
+/**
+ * Connecting to a cluster on `chant kube`'s behalf (chant #1079), honoring
+ * the exact same environment→cluster binding every other observing path
+ * does (chant #1100/#1155, revised by #1488): `--env` resolves
+ * `k8s.profiles.<env>.context` and uses it regardless of the ambient
+ * context, `--context` is an explicit override that skips the binding
+ * entirely, and neither given falls back to the ambient kubeconfig
+ * context — the same three modes `describeResources` and the Op
+ * activities already use, via the same `defaultK8sConnector`. Nothing here
+ * reimplements that resolution; this only turns a connect failure into the
+ * observation tri-state so a verb can render NOT-OBSERVED-with-reason
+ * instead of a stack trace.
+ */
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { defaultK8sConnector } from "../api/connect.js";
+import { classifyApiFailure, isMissingClientPackage, isWholeLexiconFailure, MISSING_CLIENT_DETAIL } from "../api/classify.js";
+/**
+ * Connect, or classify the failure into the tri-state. A bound-but-mismatched
+ * `--env` (`ClusterBindingMismatchError`), a missing `@intentius/chant-k8s-client`
+ * install, and a refused exec-credential plugin are the "nothing left the
+ * process" failures every verb must treat identically: NOT-OBSERVED, never
+ * an empty/absent result.
+ */
+export async function kubeConnect(options, connect = defaultK8sConnector) {
+    try {
+        const connected = await connect(options);
+        return { kind: "connected", ...connected };
+    }
+    catch (err) {
+        if (isMissingClientPackage(err)) {
+            return { kind: "unobserved", reason: "read-failed", detail: MISSING_CLIENT_DETAIL };
+        }
+        if (err instanceof ClusterBindingMismatchError) {
+            return { kind: "unobserved", reason: "no-binding", detail: err.message };
+        }
+        if (isWholeLexiconFailure(err)) {
+            const outcome = classifyApiFailure(err);
+            return {
+                kind: "unobserved",
+                reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+                detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+            };
+        }
+        throw err;
+    }
+}

package/dist/kube/delete.js

@@ -0,0 +1,138 @@
+/**
+ * `chant kube delete` (chant #1079) — routes through the typed client's own
+ * `delete()` (`packages/k8s-client/src/client.ts`), the identical typed
+ * delete `applyManifest`'s prune step already uses (chant #1075) — never a
+ * second implementation. A kind and a name are both mandatory: there is no
+ * bare `chant kube delete deployments` form, so nothing here can become a
+ * sweep by omission (the issue's "nothing destructive happens without an
+ * explicit resource argument").
+ *
+ * Two guardrails on top of the typed delete itself:
+ *
+ * - **Gate.** A bare invocation reads the object, reports what it found (and
+ *   whether chant owns it), and stops — only `--yes` performs the delete.
+ * - **Ownership, surfaced not enforced.** kubectl itself deletes anything
+ *   RBAC allows, chant-applied or not, and this keeps that: an explicit name
+ *   is already an informed decision. What's added is visibility — a
+ *   warning when the object carries no chant ownership marker, so the
+ *   operator knows they are about to delete something chant did not apply.
+ */
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { formatUnobserved } from "@intentius/chant/observation";
+import { hasOwnershipMarker, LABEL_OWNERSHIP_KEYS } from "@intentius/chant/ownership";
+import { defaultK8sConnector } from "../api/connect.js";
+import { classifyApiFailure } from "../api/classify.js";
+import { kubeConnect } from "./connect.js";
+import { parseKubeFlags, connectOptionsFrom } from "./flags.js";
+import { loadKubeProjectContext } from "./project.js";
+import { resolveKubeTarget, isTargetError } from "./target.js";
+function targetLabel(target) {
+    return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+const PROPAGATION_POLICIES = new Set(["Foreground", "Background", "Orphan"]);
+export async function runDelete(rawArgs, deps = {}) {
+    const connect = deps.connect ?? defaultK8sConnector;
+    const loadProject = deps.loadProject ?? loadKubeProjectContext;
+    let flags;
+    try {
+        flags = parseKubeFlags(rawArgs, {
+            value: { "--propagation-policy": "propagationPolicy" },
+            boolean: { "--yes": "yes", "-y": "yes" },
+        });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    if (flags.values.propagationPolicy !== undefined && !PROPAGATION_POLICIES.has(flags.values.propagationPolicy)) {
+        console.error(`error: --propagation-policy must be one of Foreground, Background, Orphan`);
+        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;
+    }
+    if (!target.name) {
+        console.error("error: chant kube delete requires an explicit resource name — no bare kind sweeps " +
+            "(e.g. `chant kube delete deployment web`, not `chant kube delete deployment`)");
+        return 1;
+    }
+    const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+    if (connected.kind === "unobserved") {
+        console.error(formatUnobserved(targetLabel(target), { reason: connected.reason, detail: connected.detail }));
+        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 = target.namespace ?? client.defaultNamespace;
+    const ref = { apiVersion: info.apiVersion, kind: info.kind, name: target.name, namespace };
+    const object = await readForDelete(client, ref);
+    if (object.kind === "unobserved") {
+        console.error(formatUnobserved(`${info.kind}/${target.name}`, { reason: object.reason, detail: object.detail }));
+        return 1;
+    }
+    if (!object.found) {
+        console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+        return 1;
+    }
+    const owned = hasOwnershipMarker(object.labels, LABEL_OWNERSHIP_KEYS);
+    const label = `${info.kind}/${target.name}${namespace ? ` -n ${namespace}` : ""}`;
+    if (!(flags.flags.yes ?? false)) {
+        console.log(`Would delete ${label}${owned ? "" : " (warning: not chant-owned)"}. Pass --yes to delete for real.`);
+        return 0;
+    }
+    if (!owned) {
+        console.log(`warning: ${label} carries no chant ownership marker — deleting an object chant did not apply`);
+    }
+    try {
+        await client.delete({ apiVersion: info.apiVersion, kind: info.kind, name: target.name, ...(namespace ? { namespace } : {}) }, { ...(flags.values.propagationPolicy ? { propagationPolicy: flags.values.propagationPolicy } : {}) });
+    }
+    catch (err) {
+        const outcome = classifyApiFailure(err);
+        if (outcome.kind === "absent") {
+            console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+            return 1;
+        }
+        console.error(formatUnobserved(label, {
+            reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+            detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+        }));
+        return 1;
+    }
+    console.log(`${label} deleted`);
+    return 0;
+}
+async function readForDelete(client, ref) {
+    try {
+        const obj = await client.readIfPresent(ref);
+        return obj ? { kind: "found", found: true, labels: obj.metadata?.labels } : { kind: "found", found: false, labels: undefined };
+    }
+    catch (err) {
+        if (err instanceof ClusterBindingMismatchError) {
+            return { kind: "unobserved", reason: "no-binding", detail: err.message };
+        }
+        const outcome = classifyApiFailure(err);
+        return {
+            kind: "unobserved",
+            reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+            detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+        };
+    }
+}

package/dist/kube/describe.js

@@ -0,0 +1,169 @@
+/**
+ * `chant kube describe` (chant #1079) — a generic, multi-section human view:
+ * identity, chant's own verdict + provenance (when inside a project), a
+ * pretty-printed spec/status, and the object's Events (reusing `./events.ts`'s
+ * `listEvents`/`filterInvolved`, the same machinery `chant kube events`
+ * itself uses — one implementation, not two). This is not kubectl's
+ * per-kind template set (`OldReplicaSets`/`NewReplicaSet` for a Deployment,
+ * per-container detail for a Pod, and so on for every built-in kind) — a
+ * generic describe covering the fields every object carries, plus the
+ * context only chant can add.
+ */
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector } from "../api/connect.js";
+import { classifyApiFailure } from "../api/classify.js";
+import { statusFromObject } from "../describe-resources.js";
+import { kubeConnect } from "./connect.js";
+import { parseKubeFlags, connectOptionsFrom } from "./flags.js";
+import { loadKubeProjectContext, relativeProvenance } from "./project.js";
+import { resolveKubeTarget, matchLiveObject, isTargetError } from "./target.js";
+import { verdictFor } from "./verdict.js";
+import { relativeAge } from "./render.js";
+import { listEvents, filterInvolved, renderEvents } from "./events.js";
+function targetLabel(target) {
+    return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+function keyValueBlock(m) {
+    if (!m || Object.keys(m).length === 0)
+        return "<none>";
+    const entries = Object.entries(m);
+    return entries.map(([k, v], i) => (i === 0 ? `${k}=${v}` : `              ${k}=${v}`)).join("\n");
+}
+function indentedJson(value) {
+    return JSON.stringify(value, null, 2)
+        .split("\n")
+        .map((l) => `  ${l}`)
+        .join("\n");
+}
+async function renderBlock(client, obj, info, project) {
+    const lines = [];
+    lines.push(`Name:         ${obj.metadata?.name ?? ""}`);
+    if (obj.metadata?.namespace)
+        lines.push(`Namespace:    ${obj.metadata.namespace}`);
+    lines.push(`API Version:  ${obj.apiVersion ?? info.apiVersion}`);
+    lines.push(`Kind:         ${obj.kind ?? info.kind}`);
+    lines.push(`Labels:       ${keyValueBlock(obj.metadata?.labels)}`);
+    lines.push(`Annotations:  ${keyValueBlock(obj.metadata?.annotations)}`);
+    lines.push(`Created:      ${obj.metadata?.creationTimestamp ?? "<unknown>"} (${relativeAge(obj.metadata?.creationTimestamp)} ago)`);
+    lines.push(`Status:       ${statusFromObject(obj)}`);
+    lines.push("Chant:");
+    if (!project) {
+        lines.push("  Verdict:    unavailable (not running inside a chant project)");
+    }
+    else {
+        const match = matchLiveObject(project, {
+            apiVersion: obj.apiVersion ?? info.apiVersion,
+            kind: obj.kind ?? info.kind,
+            name: obj.metadata?.name ?? "",
+            namespace: obj.metadata?.namespace,
+        });
+        lines.push(`  Verdict:    ${verdictFor(obj, match)}`);
+        if (match) {
+            const prov = relativeProvenance(project, match.entity);
+            lines.push(`  Entity:     ${match.entityName}`);
+            lines.push(`  Source:     ${prov?.sourceFile ?? "(unknown)"}${prov?.composite ? ` (via ${prov.composite})` : ""}`);
+        }
+    }
+    if (obj.spec !== undefined) {
+        lines.push("Spec:");
+        lines.push(indentedJson(obj.spec));
+    }
+    if (obj.status !== undefined) {
+        lines.push("Status:");
+        lines.push(indentedJson(obj.status));
+    }
+    try {
+        const events = await listEvents(client, { namespace: obj.metadata?.namespace });
+        const involved = filterInvolved(events, { kind: obj.kind ?? info.kind, name: obj.metadata?.name ?? "" });
+        lines.push("Events:");
+        lines.push(renderEvents(involved));
+    }
+    catch {
+        lines.push("Events:       <could not be read>");
+    }
+    return lines.join("\n");
+}
+export async function runDescribe(rawArgs, deps = {}) {
+    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;
+    }
+    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), { reason: connected.reason, detail: connected.detail }));
+        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;
+    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) {
+            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;
+        }
+    }
+    if (objects.length === 0) {
+        console.log("No resources found.");
+        return 0;
+    }
+    const blocks = await Promise.all(objects.map((obj) => renderBlock(client, obj, info, project)));
+    console.log(blocks.join("\n\n\n"));
+    return 0;
+}

package/dist/kube/events.js

@@ -0,0 +1,132 @@
+/**
+ * `chant kube events` (chant #1079) — the core `v1 Event` kind is addressed
+ * exactly like any other read (`client.list`), no client extension needed.
+ * The one thing the typed client's `ListOptions` does not carry is a field
+ * selector, so `--for <kind>/<name>` (kubectl's own `kubectl events
+ * --for=kind/name` shape) filters client-side against `involvedObject` after
+ * the list comes back, rather than asking the server to. Event volume in a
+ * single namespace is small enough that this is a fine trade for not
+ * widening the client's surface for one caller.
+ */
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector } from "../api/connect.js";
+import { classifyApiFailure } from "../api/classify.js";
+import { kubeConnect } from "./connect.js";
+import { parseKubeFlags, connectOptionsFrom } from "./flags.js";
+import { renderTable, renderJson, renderYaml, relativeAge, parseOutput } from "./render.js";
+function involvedOf(event) {
+    return event.involvedObject ?? {};
+}
+function eventTimestamp(event) {
+    return (event.lastTimestamp ??
+        event.eventTime ??
+        event.metadata?.creationTimestamp);
+}
+/** Events whose `involvedObject` names `ref`, oldest first — kubectl's own default order. */
+export function filterInvolved(events, ref) {
+    return events.filter((e) => {
+        const involved = involvedOf(e);
+        return involved.kind === ref.kind && involved.name === ref.name;
+    });
+}
+function sortByTime(events) {
+    return [...events].sort((a, b) => {
+        const ta = eventTimestamp(a);
+        const tb = eventTimestamp(b);
+        if (!ta && !tb)
+            return 0;
+        if (!ta)
+            return -1;
+        if (!tb)
+            return 1;
+        return Date.parse(ta) - Date.parse(tb);
+    });
+}
+/**
+ * List Events for `namespace` (or every namespace, when `namespace` is
+ * undefined), sorted oldest first. Shared by `runEvents` and `describe`'s own
+ * Events section, so the two verbs agree on what "the events for this object"
+ * means.
+ */
+export async function listEvents(client, options = {}) {
+    const events = await client.list({ apiVersion: "v1", kind: "Event" }, { ...(options.namespace ? { namespace: options.namespace } : {}), ...(options.labelSelector ? { labelSelector: options.labelSelector } : {}) });
+    return sortByTime(events);
+}
+function eventRow(e) {
+    const involved = involvedOf(e);
+    const count = typeof e.count === "number" ? e.count : undefined;
+    return [
+        relativeAge(eventTimestamp(e)),
+        e.type ?? "",
+        e.reason ?? "",
+        `${involved.kind ?? ""}/${involved.name ?? ""}`,
+        `${e.message ?? ""}${count && count > 1 ? ` (x${count})` : ""}`,
+    ];
+}
+/** Render an events table — reused by `describe`'s Events section. */
+export function renderEvents(events) {
+    if (events.length === 0)
+        return "No events found.";
+    return renderTable(["LAST SEEN", "TYPE", "REASON", "OBJECT", "MESSAGE"], events.map(eventRow));
+}
+function parseFor(value) {
+    if (!value)
+        return undefined;
+    const slash = value.indexOf("/");
+    if (slash === -1)
+        throw new Error(`--for expects KIND/NAME, e.g. --for=Pod/web-abc123`);
+    return { kind: value.slice(0, slash), name: value.slice(slash + 1) };
+}
+export async function runEvents(rawArgs, deps = {}) {
+    const connect = deps.connect ?? defaultK8sConnector;
+    let flags;
+    try {
+        flags = parseKubeFlags(rawArgs, { value: { "--for": "for" } });
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    let output;
+    let forRef;
+    try {
+        output = parseOutput(flags.values.output);
+        forRef = parseFor(flags.values.for);
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+    if (connected.kind === "unobserved") {
+        console.error(formatUnobserved("events", { reason: connected.reason, detail: connected.detail }));
+        return 1;
+    }
+    const { client } = connected;
+    const namespace = flags.flags.allNamespaces ? undefined : (flags.values.namespace ?? client.defaultNamespace);
+    let events;
+    try {
+        events = await listEvents(client, { namespace, ...(flags.values.selector ? { labelSelector: flags.values.selector } : {}) });
+    }
+    catch (err) {
+        const outcome = classifyApiFailure(err);
+        console.error(formatUnobserved("events", {
+            reason: outcome.kind === "unobserved" ? outcome.reason : "read-failed",
+            detail: outcome.kind === "unobserved" ? outcome.detail : String(err),
+        }));
+        return 1;
+    }
+    if (forRef)
+        events = filterInvolved(events, forRef);
+    switch (output.kind) {
+        case "json":
+            console.log(renderJson(events));
+            return 0;
+        case "yaml":
+            console.log(renderYaml(events));
+            return 0;
+        default:
+            console.log(renderEvents(events));
+            return 0;
+    }
+}

package/dist/kube/flags.js

@@ -0,0 +1,91 @@
+/**
+ * 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";
+/** Every `chant kube` verb accepts these — kubectl's own names. */
+const COMMON_VALUE = {
+    "-n": "namespace",
+    "--namespace": "namespace",
+    "-l": "selector",
+    "--selector": "selector",
+    "-o": "output",
+    "--output": "output",
+    "--context": "context",
+    "--env": "env",
+    "--kubeconfig": "kubeconfig",
+};
+const COMMON_BOOLEAN = {
+    "-A": "allNamespaces",
+    "--all-namespaces": "allNamespaces",
+};
+/**
+ * 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, spec = {}) {
+    const valueFlags = { ...COMMON_VALUE, ...(spec.value ?? {}) };
+    const booleanFlags = { ...COMMON_BOOLEAN, ...(spec.boolean ?? {}) };
+    const args = splitJoinedFlags(rawArgs, new Set(Object.keys(booleanFlags)));
+    const positional = [];
+    const values = {};
+    const flags = {};
+    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) {
+    const options = {};
+    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) {
+    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) {
+    return parseDurationSeconds(value) * 1000;
+}