@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/kube/render.ts

@@ -0,0 +1,252 @@
+/**
+ * Output rendering for `chant kube get`/`describe` (chant #1079).
+ *
+ * kubectl's own `-o` vocabulary, minus the one form the issue says to drop
+ * openly rather than half-implement: `-o go-template[-file]` is Go template
+ * syntax, and chant does not carry a Go template engine — {@link parseOutput}
+ * refuses it by name rather than pretending a partial implementation covers
+ * it. `-o jsonpath` and `-o custom-columns` are "tractable" per the issue's
+ * own notes, and are implemented here as a deliberately small subset: dot
+ * paths, bracket indices, and a `[*]` wildcard — the paths kubectl one-liners
+ * actually use — not the full jsonpath grammar (filters, `range`/`end`
+ * templates). `-o chant` is chant's own addition: a live object rendered as
+ * the typed source that would declare it, reusing `./import/live-export.ts`
+ * and the lexicon's own `K8sGenerator` — the same machinery `chant import`
+ * uses, so every read is an adoption path, per the issue's framing.
+ */
+
+import type { K8sObject } from "@intentius/chant-k8s-client";
+import { dump } from "js-yaml";
+import { buildExportFromObjects } from "../import/live-export";
+import { K8sGenerator } from "../import/generator";
+import type { KubeVerdict } from "./verdict";
+
+export type OutputFormat =
+  | { kind: "text" }
+  | { kind: "wide" }
+  | { kind: "json" }
+  | { kind: "yaml" }
+  | { kind: "name" }
+  | { kind: "chant" }
+  | { kind: "jsonpath"; expr: string }
+  | { kind: "custom-columns"; spec: string };
+
+/** Parse an `-o`/`--output` value. Throws on `go-template[-file]`. */
+export function parseOutput(value: string | undefined): OutputFormat {
+  if (value === undefined || value === "" || value === "text") return { kind: "text" };
+  if (value === "wide") return { kind: "wide" };
+  if (value === "json") return { kind: "json" };
+  if (value === "yaml") return { kind: "yaml" };
+  if (value === "name") return { kind: "name" };
+  if (value === "chant") return { kind: "chant" };
+  if (value.startsWith("jsonpath=")) return { kind: "jsonpath", expr: value.slice("jsonpath=".length) };
+  if (value.startsWith("custom-columns=")) return { kind: "custom-columns", spec: value.slice("custom-columns=".length) };
+  if (value === "go-template" || value === "go-template-file" || value.startsWith("go-template")) {
+    throw new Error(
+      "-o go-template is not supported — chant kube does not carry a Go template engine, and a partial " +
+        "implementation would be worse than none. Use -o jsonpath=, -o custom-columns=, or -o chant instead.",
+    );
+  }
+  throw new Error(`unsupported -o value: ${value}`);
+}
+
+// ── table rendering (text / wide) ──────────────────────────────────────────
+
+export interface KubeRow {
+  namespace?: string;
+  name: string;
+  kind: string;
+  status: string;
+  age?: string;
+  verdict?: KubeVerdict;
+  labels?: Record<string, string>;
+  object: K8sObject;
+}
+
+/** kubectl-style relative age, e.g. "45s", "12m", "3h", "5d". */
+export function relativeAge(creationTimestamp: string | undefined, now: number = Date.now()): string {
+  if (!creationTimestamp) return "<unknown>";
+  const then = Date.parse(creationTimestamp);
+  if (Number.isNaN(then)) return "<unknown>";
+  const seconds = Math.max(0, Math.floor((now - then) / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  if (days < 365) return `${days}d`;
+  return `${Math.floor(days / 365)}y`;
+}
+
+/** Render a fixed-width table. `columns` is header → per-row value. */
+export function renderTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+  const line = (cells: string[]): string => cells.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd();
+  return [line(headers), ...rows.map(line)].join("\n");
+}
+
+export function renderKubeTable(rows: KubeRow[], opts: { allNamespaces: boolean; wide: boolean; showVerdict: boolean }): string {
+  if (rows.length === 0) return "No resources found.";
+  const headers: string[] = [];
+  if (opts.allNamespaces) headers.push("NAMESPACE");
+  headers.push("NAME", "STATUS", "AGE");
+  if (opts.showVerdict) headers.push("CHANT");
+  if (opts.wide) headers.push("LABELS");
+
+  const cells = rows.map((r) => {
+    const row: string[] = [];
+    if (opts.allNamespaces) row.push(r.namespace ?? "");
+    row.push(r.name, r.status, r.age ?? "<unknown>");
+    if (opts.showVerdict) row.push(r.verdict ?? "unavailable");
+    if (opts.wide) row.push(labelsText(r.labels));
+    return row;
+  });
+
+  return renderTable(headers, cells);
+}
+
+function labelsText(labels: Record<string, string> | undefined): string {
+  if (!labels || Object.keys(labels).length === 0) return "<none>";
+  return Object.entries(labels)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(",");
+}
+
+// ── json / yaml / name ─────────────────────────────────────────────────────
+
+/** kubectl wraps >1 item in a synthetic List; a single item is printed bare. */
+function asPrintable(objects: readonly K8sObject[]): unknown {
+  if (objects.length === 1) return objects[0];
+  return { apiVersion: "v1", kind: "List", items: objects, metadata: {} };
+}
+
+export function renderJson(objects: readonly K8sObject[]): string {
+  return JSON.stringify(asPrintable(objects), null, 2);
+}
+
+export function renderYaml(objects: readonly K8sObject[]): string {
+  return dump(asPrintable(objects));
+}
+
+/** `kubectl get -o name`: `<lowercased-kind>.<group>/<name>` (`<lowercased-kind>/<name>` for the core group). */
+export function renderName(objects: readonly K8sObject[]): string {
+  return objects
+    .map((o) => {
+      const [group] = (o.apiVersion ?? "").includes("/") ? [o.apiVersion!.split("/")[0]] : [""];
+      const kind = (o.kind ?? "").toLowerCase();
+      const prefix = group ? `${kind}.${group}` : kind;
+      return `${prefix}/${o.metadata?.name ?? ""}`;
+    })
+    .join("\n");
+}
+
+// ── -o chant ────────────────────────────────────────────────────────────────
+
+/** Render live objects as the typed chant source that would declare them. */
+export function renderChantSource(objects: readonly K8sObject[]): string {
+  const ir = buildExportFromObjects(objects as unknown[]);
+  const files = new K8sGenerator().generate(ir);
+  return files.map((f) => f.content).join("\n\n");
+}
+
+// ── jsonpath (subset) ───────────────────────────────────────────────────────
+
+type PathSegment = { key: string } | { index: number } | { wildcard: true };
+
+function parsePath(path: string): PathSegment[] {
+  // ".a.b[0].c[*]" → segments; a leading "." (or none) both mean "from root".
+  const segments: PathSegment[] = [];
+  const re = /\.([^.[\]]+)|\[(\*|\d+)\]/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(path))) {
+    if (match[1] !== undefined) segments.push({ key: match[1] });
+    else if (match[2] === "*") segments.push({ wildcard: true });
+    else segments.push({ index: Number(match[2]) });
+  }
+  return segments;
+}
+
+function evalPath(root: unknown, segments: readonly PathSegment[]): unknown[] {
+  let current: unknown[] = [root];
+  for (const seg of segments) {
+    const next: unknown[] = [];
+    for (const value of current) {
+      if (value === null || value === undefined) continue;
+      if ("wildcard" in seg) {
+        if (Array.isArray(value)) next.push(...value);
+        else if (typeof value === "object") next.push(...Object.values(value as Record<string, unknown>));
+        continue;
+      }
+      if ("index" in seg) {
+        if (Array.isArray(value)) next.push(value[seg.index]);
+        continue;
+      }
+      if (typeof value === "object") next.push((value as Record<string, unknown>)[seg.key]);
+    }
+    current = next;
+  }
+  return current;
+}
+
+function scalarText(v: unknown): string {
+  if (v === undefined || v === null) return "";
+  if (typeof v === "string") return v;
+  return JSON.stringify(v);
+}
+
+/**
+ * Evaluate a kubectl-style jsonpath template against one root value: literal
+ * text passes through, `{"..."}` is a quoted literal, `{.a.b[*].c}` extracts
+ * and space-joins matches. Multiple `{...}` blocks concatenate directly, as
+ * kubectl's own `-o jsonpath` does.
+ */
+export function evalJsonPath(template: string, root: unknown): string {
+  let out = "";
+  const re = /\{([^}]*)\}/g;
+  let lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(template))) {
+    out += template.slice(lastIndex, match.index);
+    const inner = match[1];
+    if (inner.startsWith('"') && inner.endsWith('"')) {
+      out += inner.slice(1, -1);
+    } else {
+      const segments = parsePath(inner);
+      out += evalPath(root, segments).map(scalarText).join(" ");
+    }
+    lastIndex = match.index + match[0].length;
+  }
+  out += template.slice(lastIndex);
+  return out;
+}
+
+/** `-o jsonpath=`: kubectl runs the whole template once per top-level object printed. */
+export function renderJsonPath(expr: string, objects: readonly K8sObject[]): string {
+  const root = asPrintable(objects);
+  return evalJsonPath(expr, root);
+}
+
+// ── custom-columns ──────────────────────────────────────────────────────────
+
+interface ColumnSpec {
+  header: string;
+  path: PathSegment[];
+}
+
+function parseCustomColumns(spec: string): ColumnSpec[] {
+  return spec.split(",").map((entry) => {
+    const colon = entry.indexOf(":");
+    if (colon === -1) throw new Error(`custom-columns entry "${entry}" is missing ":" — expected HEADER:.json.path`);
+    const header = entry.slice(0, colon);
+    const path = entry.slice(colon + 1);
+    return { header, path: parsePath(path.startsWith(".") ? path : `.${path}`) };
+  });
+}
+
+export function renderCustomColumns(spec: string, objects: readonly K8sObject[]): string {
+  const columns = parseCustomColumns(spec);
+  const headers = columns.map((c) => c.header);
+  const rows = objects.map((o) => columns.map((c) => evalPath(o, c.path).map(scalarText).join(",") || "<none>"));
+  return renderTable(headers, rows);
+}

package/src/kube/source.test.ts

@@ -0,0 +1,138 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster, objectKey } from "../api/fake-cluster";
+import { runSource } from "./source";
+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 source (#1079)", () => {
+  test("happy path: resolves a live object to its declaring file and composite", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1" },
+        },
+      },
+    });
+    const project = fakeProjectContext({
+      web: fakeDeclarable(
+        "K8s::Apps::Deployment",
+        { metadata: { name: "web", namespace: "prod" } },
+        { sourceFile: "/project/src/infra.ts", composite: "WebApp", compositeInstance: "web" },
+      ),
+    });
+    const { log } = spyConsole();
+
+    const code = await runSource(["deployment", "web", "-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).toContain("web <- web");
+    expect(out).toContain("src/infra.ts");
+    expect(out).toContain("composite: WebApp");
+    expect(out).toContain("line:      not tracked");
+  });
+
+  test("-o json emits a machine-readable envelope", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "web", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "web", namespace: "prod", uid: "u1" },
+        },
+      },
+    });
+    const project = fakeProjectContext({
+      web: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "web", namespace: "prod" } }, { sourceFile: "/project/src/infra.ts" }),
+    });
+    const { log } = spyConsole();
+
+    await runSource(["deployment", "web", "-n", "prod", "-o", "json"], { connect: cluster.connector, loadProject: async () => project });
+
+    const parsed = JSON.parse(log.mock.calls[0][0] as string);
+    expect(parsed).toMatchObject({ found: true, entity: "web", file: "src/infra.ts" });
+  });
+
+  test("a live object with no declared source reports found:false, not an error", async () => {
+    const cluster = fakeCluster({
+      objects: {
+        [objectKey("apps/v1", "Deployment", "unrelated", "prod")]: {
+          apiVersion: "apps/v1",
+          kind: "Deployment",
+          metadata: { name: "unrelated", namespace: "prod", uid: "u2" },
+        },
+      },
+    });
+    const project = fakeProjectContext({});
+    const { log } = spyConsole();
+
+    const code = await runSource(["deployment", "unrelated", "-n", "prod"], { connect: cluster.connector, loadProject: async () => project });
+
+    expect(code).toBe(0);
+    expect(log.mock.calls[0][0]).toContain("no declared entity");
+  });
+
+  test("degrades gracefully outside a chant project — reports unavailable, does not connect", async () => {
+    const { log } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runSource(["deployment", "web"], { connect, loadProject: async () => undefined });
+
+    expect(code).toBe(1);
+    expect(log.mock.calls[0][0]).toContain("unavailable");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("binding mismatch refuses loudly", async () => {
+    const project = fakeProjectContext({});
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runSource(["deployment", "web", "--env", "prod"], { connect, loadProject: async () => project });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no binding for this environment");
+  });
+
+  test("unknown flag is rejected before loading the project or connecting", async () => {
+    const { error } = spyConsole();
+    const loadProject = vi.fn();
+    const connect = vi.fn();
+
+    const code = await runSource(["deployment", "web", "--bogus"], { connect, loadProject });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(loadProject).not.toHaveBeenCalled();
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: an RBAC-denied read renders NOT-OBSERVED, not a false negative", async () => {
+    const project = fakeProjectContext({});
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/apis/apps/v1/namespaces/prod/deployments/web"
+          ? { status: 403, body: { kind: "Status", reason: "Forbidden", message: "forbidden" } }
+          : undefined,
+    });
+    const { error, log } = spyConsole();
+
+    const code = await runSource(["deployment", "web", "-n", "prod"], { connect: cluster.connector, loadProject: async () => project });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no credentials");
+    expect(log).not.toHaveBeenCalled();
+  });
+});

package/src/kube/source.ts

@@ -0,0 +1,139 @@
+/**
+ * `chant kube source` (chant #1079) — resolve a live object back to the
+ * `.ts` file and composite that declared it, reusing the exact build
+ * provenance the gitlab/forgejo lexicons' own `:source` context tools already
+ * expose (`@intentius/chant/provenance`, stamped during discovery — chant
+ * #1064). That precedent is explicit that provenance here is **entity-level
+ * (file + composite), not a YAML-line source map** — chant does not carry
+ * one, for k8s or for anything else — so this verb reports the same two
+ * facts (never a fabricated line number) and says so plainly rather than
+ * silently coming up one field short of the issue's wording.
+ */
+
+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 { loadKubeProjectContext, relativeProvenance, type KubeProjectContext } from "./project";
+import { resolveKubeTarget, matchLiveObject, isTargetError, type KubeTarget } from "./target";
+
+export interface SourceDeps {
+  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 runSource(rawArgs: string[], deps: SourceDeps = {}): 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 json = flags.values.output === "json";
+
+  const project = await loadProject();
+  if (!project) {
+    if (json) console.log(JSON.stringify({ available: false, note: "not running inside a chant project (no chant.config.ts, or the project has build errors)" }));
+    else console.log("chant source: unavailable — not running inside a chant project (no chant.config.ts, or the project has build errors)");
+    return 1;
+  }
+
+  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 source requires a single named resource, e.g. `chant kube source deployment web`");
+    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;
+  let obj;
+  try {
+    obj = await client.readIfPresent({ apiVersion: info.apiVersion, kind: info.kind, name: target.name, namespace });
+  } 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;
+  }
+  if (!obj) {
+    console.error(`Error from server (NotFound): ${info.name} "${target.name}" not found`);
+    return 1;
+  }
+
+  const match =
+    target.declaredMatch ??
+    matchLiveObject(project, {
+      apiVersion: obj.apiVersion ?? info.apiVersion,
+      kind: obj.kind ?? info.kind,
+      name: obj.metadata?.name ?? target.name,
+      namespace: obj.metadata?.namespace ?? namespace,
+    });
+
+  if (!match) {
+    const note = `no declared entity in this project names ${info.kind}/${target.name}`;
+    if (json) console.log(JSON.stringify({ found: false, note }));
+    else console.log(`${info.kind}/${target.name}: ${note}`);
+    return 0;
+  }
+
+  const prov = relativeProvenance(project, match.entity);
+  if (json) {
+    console.log(
+      JSON.stringify({
+        found: true,
+        entity: match.entityName,
+        file: prov?.sourceFile ?? null,
+        composite: prov?.composite ?? null,
+        compositeInstance: prov?.compositeInstance ?? null,
+      }),
+    );
+  } else {
+    console.log(`${info.kind}/${target.name} <- ${match.entityName}`);
+    console.log(`  file:      ${prov?.sourceFile ?? "(unknown)"}`);
+    console.log(`  composite: ${prov?.composite ?? "(none — declared directly)"}`);
+    console.log(`  line:      not tracked — chant's build provenance is entity-level (file + composite), not a source map`);
+  }
+  return 0;
+}

package/src/kube/target.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "vitest";
+import { resolveKubeTarget, isTargetError, matchLiveObject } from "./target";
+import { fakeDeclarable, fakeProjectContext } from "./testing";
+
+describe("resolveKubeTarget (chant #1079)", () => {
+  test("kubectl-style: <kind> <name> — never consults the project even when a project is present", () => {
+    const project = fakeProjectContext({
+      web: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "different-name", namespace: "prod" } }),
+    });
+    const target = resolveKubeTarget(["deployment", "web"], undefined, project);
+    expect(isTargetError(target)).toBe(false);
+    if (!isTargetError(target)) {
+      expect(target.selector).toEqual({ resource: "deployment" });
+      expect(target.name).toBe("web");
+      expect(target.declaredMatch).toBeUndefined();
+    }
+  });
+
+  test("kubectl-style: a bare <kind> lists — name is undefined", () => {
+    const target = resolveKubeTarget(["deployments"], undefined, undefined);
+    if (!isTargetError(target)) {
+      expect(target.name).toBeUndefined();
+    } else {
+      throw new Error("expected a resolved target");
+    }
+  });
+
+  test("chant vocabulary: a single token matching a declared entity resolves via its own metadata", () => {
+    const project = fakeProjectContext({
+      myWeb: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "web", namespace: "prod" } }),
+    });
+    const target = resolveKubeTarget(["myWeb"], undefined, project);
+    if (isTargetError(target)) throw new Error("expected a resolved target");
+    expect(target.selector).toEqual({ apiVersion: "apps/v1", kind: "Deployment" });
+    expect(target.name).toBe("web");
+    expect(target.namespace).toBe("prod");
+    expect(target.declaredMatch?.entityName).toBe("myWeb");
+  });
+
+  test("an explicit -n overrides the declared namespace", () => {
+    const project = fakeProjectContext({
+      myWeb: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "web", namespace: "prod" } }),
+    });
+    const target = resolveKubeTarget(["myWeb"], "staging", project);
+    if (isTargetError(target)) throw new Error("expected a resolved target");
+    expect(target.namespace).toBe("staging");
+  });
+
+  test("no arguments is an error, not a crash", () => {
+    const target = resolveKubeTarget([], undefined, undefined);
+    expect(isTargetError(target)).toBe(true);
+  });
+});
+
+describe("matchLiveObject", () => {
+  test("undefined project means no match, cheaply (no iteration)", () => {
+    expect(matchLiveObject(undefined, { apiVersion: "v1", kind: "Pod", name: "a" })).toBeUndefined();
+  });
+
+  test("matches on apiVersion + kind + name + namespace, all four", () => {
+    const project = fakeProjectContext({
+      web: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "web", namespace: "prod" } }),
+    });
+    expect(matchLiveObject(project, { apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "prod" })?.entityName).toBe("web");
+    expect(matchLiveObject(project, { apiVersion: "apps/v1", kind: "Deployment", name: "web", namespace: "staging" })).toBeUndefined();
+  });
+});

package/src/kube/target.ts

@@ -0,0 +1,89 @@
+/**
+ * Resolving `chant kube <verb> <target...>`'s positional arguments to an
+ * addressable resource (chant #1079).
+ *
+ * "Every verb resolves entity names through chant's own vocabulary where
+ * applicable ... while also accepting raw kind/name kubectl-style." Both
+ * forms share one positional shape, disambiguated by arity:
+ *
+ * - One token, and it names a declared entity in this project → chant's own
+ *   vocabulary: the entity's `metadata.name`(/`namespace`) is looked up in
+ *   its own source, not typed twice.
+ * - One or two tokens otherwise → kubectl's own shape, `<kind> [name]`; a
+ *   bare kind with no name is a list, matching `kubectl get <kind>`.
+ *
+ * `<kind>` is never parsed here beyond splitting the `.group` suffix — that
+ * job belongs to the typed client's own `resolve()` (kubectl's own
+ * plural/singular/kind/short-name precedence, `packages/k8s-client/src/client.ts`),
+ * so a raw kind string reaches the cluster exactly as `kubectl get raycluster.ray.io`
+ * would.
+ */
+
+import type { ResourceSelector } from "@intentius/chant-k8s-client";
+import { findDeclaredMatch, type DeclaredMatch, type KubeProjectContext } from "./project";
+import { operationFor } from "../api/operation-surface";
+
+export interface KubeTarget {
+  selector: ResourceSelector;
+  /** Object name. Undefined means "list every object this selector addresses". */
+  name?: string;
+  namespace?: string;
+  /** Set when resolution went through chant's own vocabulary rather than a kubectl kind string. */
+  declaredMatch?: DeclaredMatch;
+}
+
+export interface KubeTargetError {
+  error: string;
+}
+
+export function isTargetError(t: KubeTarget | KubeTargetError): t is KubeTargetError {
+  return "error" in t;
+}
+
+/**
+ * Resolve `positional` (whatever's left after flags) plus an explicit
+ * `-n/--namespace`, against `project`'s declared entities when available.
+ */
+export function resolveKubeTarget(
+  positional: readonly string[],
+  namespaceFlag: string | undefined,
+  project: KubeProjectContext | undefined,
+): KubeTarget | KubeTargetError {
+  if (positional.length === 0) {
+    return { error: "a resource kind (and, usually, a name) is required — e.g. `chant kube get deployments` or `chant kube get deployment web`" };
+  }
+  const [first, second] = positional;
+
+  if (project && second === undefined) {
+    const entity = project.entities.get(first);
+    if (entity && entity.lexicon === "k8s") {
+      const operation = operationFor(entity.entityType);
+      const props = "props" in entity ? ((entity as { props: unknown }).props as Record<string, unknown>) : undefined;
+      const metadata = props?.metadata as { name?: string; namespace?: string } | undefined;
+      if (operation && metadata?.name) {
+        return {
+          selector: { apiVersion: operation.apiVersion, kind: operation.kind },
+          name: metadata.name,
+          namespace: namespaceFlag ?? metadata.namespace,
+          declaredMatch: { entityName: first, entity, props },
+        };
+      }
+    }
+  }
+
+  return { selector: { resource: first }, name: second, namespace: namespaceFlag };
+}
+
+/**
+ * After a live read resolves an object's real `apiVersion`/`kind` (a kubectl
+ * kind string like `deploy` isn't one), reverse-map it against the project
+ * for the verdict column / `source` — reusing the exact match `resolveKubeTarget`
+ * would have made had the caller spelled out the entity name.
+ */
+export function matchLiveObject(
+  project: KubeProjectContext | undefined,
+  ref: { apiVersion: string; kind: string; name: string; namespace?: string },
+): DeclaredMatch | undefined {
+  if (!project) return undefined;
+  return findDeclaredMatch(project.entities, ref);
+}