@intentius/chant-lexicon-k8s 0.30.0 → 0.32.0

package/src/kube/describe.ts

@@ -0,0 +1,195 @@
+/**
+ * `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 type { K8sObject } from "@intentius/chant-k8s-client";
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import { statusFromObject } from "../describe-resources";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom } from "./flags";
+import { loadKubeProjectContext, relativeProvenance, type KubeProjectContext } from "./project";
+import { resolveKubeTarget, matchLiveObject, isTargetError, type KubeTarget } from "./target";
+import { verdictFor } from "./verdict";
+import { relativeAge } from "./render";
+import { listEvents, filterInvolved, renderEvents } from "./events";
+
+export interface DescribeDeps {
+  connect?: K8sConnector;
+  loadProject?: (cwd?: string) => Promise<KubeProjectContext | undefined>;
+}
+
+function targetLabel(target: KubeTarget): string {
+  return "apiVersion" in target.selector ? target.selector.kind : target.selector.resource;
+}
+
+function keyValueBlock(m: Record<string, string> | undefined): string {
+  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: unknown): string {
+  return JSON.stringify(value, null, 2)
+    .split("\n")
+    .map((l) => `  ${l}`)
+    .join("\n");
+}
+
+async function renderBlock(
+  client: Parameters<typeof listEvents>[0],
+  obj: K8sObject,
+  info: { apiVersion: string; kind: string },
+  project: KubeProjectContext | undefined,
+): Promise<string> {
+  const lines: string[] = [];
+  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: string[], deps: DescribeDeps = {}): 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;
+  }
+
+  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: 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) {
+      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/src/kube/events.test.ts

@@ -0,0 +1,115 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster } from "../api/fake-cluster";
+import { runEvents } from "./events";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+function event(name: string, reason: string, involved: { kind: string; name: string }, lastTimestamp: string) {
+  return {
+    apiVersion: "v1",
+    kind: "Event",
+    metadata: { name, namespace: "prod", uid: `uid-${name}` },
+    involvedObject: involved,
+    reason,
+    type: "Normal",
+    message: `${reason} happened`,
+    lastTimestamp,
+  };
+}
+
+describe("chant kube events (#1079)", () => {
+  test("happy path: lists events oldest first", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/api/v1/namespaces/prod/events"
+          ? {
+              body: {
+                items: [
+                  event("e2", "Started", { kind: "Pod", name: "web" }, "2026-01-01T00:02:00Z"),
+                  event("e1", "Scheduled", { kind: "Pod", name: "web" }, "2026-01-01T00:00:00Z"),
+                ],
+              },
+            }
+          : undefined,
+    });
+    const { log } = spyConsole();
+
+    const code = await runEvents(["-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    const out = log.mock.calls[0][0] as string;
+    const scheduledIdx = out.indexOf("Scheduled");
+    const startedIdx = out.indexOf("Started");
+    expect(scheduledIdx).toBeGreaterThan(-1);
+    expect(startedIdx).toBeGreaterThan(scheduledIdx);
+  });
+
+  test("--for filters by involvedObject kind/name", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/api/v1/namespaces/prod/events"
+          ? {
+              body: {
+                items: [
+                  event("e1", "Started", { kind: "Pod", name: "web" }, "2026-01-01T00:00:00Z"),
+                  event("e2", "Started", { kind: "Pod", name: "other" }, "2026-01-01T00:00:00Z"),
+                ],
+              },
+            }
+          : undefined,
+    });
+    const { log } = spyConsole();
+
+    await runEvents(["-n", "prod", "--for=Pod/web"], { connect: cluster.connector });
+
+    const out = log.mock.calls[0][0] as string;
+    expect(out).toContain("Pod/web");
+    expect(out).not.toContain("Pod/other");
+  });
+
+  test("binding mismatch refuses loudly", async () => {
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runEvents(["--env", "prod"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before any connection", async () => {
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runEvents(["--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 list", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/api/v1/namespaces/prod/events"
+          ? { status: 403, body: { kind: "Status", reason: "Forbidden", message: "events is forbidden" } }
+          : undefined,
+    });
+    const { error, log } = spyConsole();
+
+    const code = await runEvents(["-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no credentials");
+    expect(log).not.toHaveBeenCalled();
+  });
+});

package/src/kube/events.ts

@@ -0,0 +1,160 @@
+/**
+ * `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 type { K8sClient, K8sObject } from "@intentius/chant-k8s-client";
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom } from "./flags";
+import { renderTable, renderJson, renderYaml, relativeAge, parseOutput } from "./render";
+
+export interface EventsDeps {
+  connect?: K8sConnector;
+}
+
+interface InvolvedObject {
+  kind?: string;
+  name?: string;
+  namespace?: string;
+}
+
+function involvedOf(event: K8sObject): InvolvedObject {
+  return (event.involvedObject as InvolvedObject | undefined) ?? {};
+}
+
+function eventTimestamp(event: K8sObject): string | undefined {
+  return (
+    (event.lastTimestamp as string | undefined) ??
+    (event.eventTime as string | undefined) ??
+    event.metadata?.creationTimestamp
+  );
+}
+
+/** Events whose `involvedObject` names `ref`, oldest first — kubectl's own default order. */
+export function filterInvolved(events: readonly K8sObject[], ref: { kind: string; name: string }): K8sObject[] {
+  return events.filter((e) => {
+    const involved = involvedOf(e);
+    return involved.kind === ref.kind && involved.name === ref.name;
+  });
+}
+
+function sortByTime(events: readonly K8sObject[]): K8sObject[] {
+  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: K8sClient,
+  options: { namespace?: string; labelSelector?: string } = {},
+): Promise<K8sObject[]> {
+  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: K8sObject): string[] {
+  const involved = involvedOf(e);
+  const count = typeof e.count === "number" ? e.count : undefined;
+  return [
+    relativeAge(eventTimestamp(e)),
+    (e.type as string | undefined) ?? "",
+    (e.reason as string | undefined) ?? "",
+    `${involved.kind ?? ""}/${involved.name ?? ""}`,
+    `${(e.message as string | undefined) ?? ""}${count && count > 1 ? ` (x${count})` : ""}`,
+  ];
+}
+
+/** Render an events table — reused by `describe`'s Events section. */
+export function renderEvents(events: readonly K8sObject[]): string {
+  if (events.length === 0) return "No events found.";
+  return renderTable(["LAST SEEN", "TYPE", "REASON", "OBJECT", "MESSAGE"], events.map(eventRow));
+}
+
+function parseFor(value: string | undefined): { kind: string; name: string } | undefined {
+  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: string[], deps: EventsDeps = {}): Promise<number> {
+  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: K8sObject[];
+  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/src/kube/flags.test.ts

@@ -0,0 +1,65 @@
+import { describe, test, expect } from "vitest";
+import { parseKubeFlags, connectOptionsFrom, parseDurationSeconds, parseDurationMs } from "./flags";
+
+describe("parseKubeFlags (chant #1079)", () => {
+  test("splits positional args from the common flag set", () => {
+    const { positional, values, flags } = parseKubeFlags(["deployment", "web", "-n", "prod", "-A"]);
+    expect(positional).toEqual(["deployment", "web"]);
+    expect(values.namespace).toBe("prod");
+    expect(flags.allNamespaces).toBe(true);
+  });
+
+  test("accepts a joined --flag=value form (#1127 discipline)", () => {
+    const { values } = parseKubeFlags(["--namespace=prod", "--output=json"]);
+    expect(values).toEqual({ namespace: "prod", output: "json" });
+  });
+
+  test("merges a verb's own flag spec with the common set", () => {
+    const { values, flags } = parseKubeFlags(["--tail", "50", "--previous"], {
+      value: { "--tail": "tail" },
+      boolean: { "--previous": "previous" },
+    });
+    expect(values.tail).toBe("50");
+    expect(flags.previous).toBe(true);
+  });
+
+  test("an unrecognized flag throws the shared unknown-flag error", () => {
+    expect(() => parseKubeFlags(["--bogus"])).toThrow(/Unknown flag: --bogus/);
+  });
+
+  test("a value flag given as a boolean via = throws (#1127)", () => {
+    expect(() => parseKubeFlags(["--all-namespaces=yes"])).toThrow(/boolean flag/);
+  });
+
+  test("a value flag with nothing after it is an error, not a silent positional swallow", () => {
+    expect(() => parseKubeFlags(["--namespace"])).toThrow(/requires a value/);
+  });
+
+  test("a bare '-' is a positional, not a flag (kubectl's stdin convention)", () => {
+    const { positional } = parseKubeFlags(["apply", "-"]);
+    expect(positional).toEqual(["apply", "-"]);
+  });
+});
+
+describe("connectOptionsFrom", () => {
+  test("maps env/context/kubeconfig to ConnectOptions", () => {
+    expect(connectOptionsFrom({ env: "prod" })).toEqual({ environment: "prod" });
+    expect(connectOptionsFrom({ context: "prod-eks" })).toEqual({ context: "prod-eks" });
+    expect(connectOptionsFrom({ kubeconfig: "/tmp/kc" })).toEqual({ client: { kubeconfigPath: "/tmp/kc" } });
+    expect(connectOptionsFrom({})).toEqual({});
+  });
+});
+
+describe("parseDurationSeconds / parseDurationMs", () => {
+  test("parses bare seconds and suffixed durations", () => {
+    expect(parseDurationSeconds("45")).toBe(45);
+    expect(parseDurationSeconds("45s")).toBe(45);
+    expect(parseDurationSeconds("90m")).toBe(5400);
+    expect(parseDurationSeconds("2h")).toBe(7200);
+    expect(parseDurationMs("1h")).toBe(3_600_000);
+  });
+
+  test("rejects a nonsense duration", () => {
+    expect(() => parseDurationSeconds("soon")).toThrow(/expected a duration/);
+  });
+});

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;
+}