@intentius/chant-lexicon-k8s 0.31.0 → 0.32.0

package/src/kube/logs.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect, vi, afterEach } from "vitest";
+import { ClusterBindingMismatchError } from "@intentius/chant/kubectl-context";
+import { fakeCluster } from "../api/fake-cluster";
+import { runLogs } from "./logs";
+import { fakeDeclarable, fakeProjectContext } from "./testing";
+
+afterEach(() => vi.restoreAllMocks());
+
+function spyStdout() {
+  return vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+}
+
+function spyConsole() {
+  const log = vi.spyOn(console, "log").mockImplementation(() => {});
+  const error = vi.spyOn(console, "error").mockImplementation(() => {});
+  return { log, error };
+}
+
+describe("chant kube logs (#1079)", () => {
+  test("happy path: prints the pod's raw log text", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/api/v1/namespaces/prod/pods/web-abc/log" ? { body: "hello from the container\n" } : undefined,
+    });
+    const stdout = spyStdout();
+
+    const code = await runLogs(["web-abc", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(0);
+    expect(stdout).toHaveBeenCalledWith("hello from the container\n");
+  });
+
+  test("--container/--tail/--since/--previous/--timestamps become query parameters", async () => {
+    const cluster = fakeCluster({
+      respond: (req) => (req.path === "/api/v1/namespaces/prod/pods/web-abc/log" ? { body: "x" } : undefined),
+    });
+    spyStdout();
+
+    await runLogs(
+      ["web-abc", "-n", "prod", "-c", "app", "--tail", "50", "--since", "1h", "-p", "--timestamps"],
+      { connect: cluster.connector },
+    );
+
+    const req = cluster.layer.requests.find((r) => r.path === "/api/v1/namespaces/prod/pods/web-abc/log")!;
+    expect(req.query).toEqual({ container: "app", tailLines: "50", sinceSeconds: "3600", previous: "true", timestamps: "true" });
+  });
+
+  test("resolves a declared entity name to its Pod, when the entity is a Pod", async () => {
+    const cluster = fakeCluster({
+      respond: (req) => (req.path === "/api/v1/namespaces/prod/pods/web-abc/log" ? { body: "log text" } : undefined),
+    });
+    const project = fakeProjectContext({
+      myPod: fakeDeclarable("K8s::Core::Pod", { metadata: { name: "web-abc", namespace: "prod" } }),
+    });
+    const stdout = spyStdout();
+
+    const code = await runLogs(["myPod"], { connect: cluster.connector, loadProject: async () => project });
+
+    expect(code).toBe(0);
+    expect(stdout).toHaveBeenCalledWith("log text\n");
+  });
+
+  test("a declared entity that is not a Pod is refused with a clear message", async () => {
+    const project = fakeProjectContext({
+      web: fakeDeclarable("K8s::Apps::Deployment", { metadata: { name: "web", namespace: "prod" } }),
+    });
+    const { error } = spyConsole();
+    const connect = vi.fn();
+
+    const code = await runLogs(["web"], { connect, loadProject: async () => project });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("not a Pod");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("binding mismatch refuses loudly", async () => {
+    const { error } = spyConsole();
+    const connect = async () => {
+      throw new ClusterBindingMismatchError("prod", "prod-eks", "dev-eks");
+    };
+
+    const code = await runLogs(["web-abc", "--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 runLogs(["web-abc", "--bogus"], { connect });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("Unknown flag");
+    expect(connect).not.toHaveBeenCalled();
+  });
+
+  test("tri-state: RBAC-denied log read renders NOT-OBSERVED, not empty output", async () => {
+    const cluster = fakeCluster({
+      respond: (req) =>
+        req.path === "/api/v1/namespaces/prod/pods/web-abc/log"
+          ? { status: 403, body: { kind: "Status", reason: "Forbidden", message: "pods/log is forbidden" } }
+          : undefined,
+    });
+    const { error } = spyConsole();
+    const stdout = spyStdout();
+
+    const code = await runLogs(["web-abc", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("no credentials");
+    expect(stdout).not.toHaveBeenCalled();
+  });
+
+  test("a missing pod reports NotFound, kubectl-style", async () => {
+    const cluster = fakeCluster({});
+    const { error } = spyConsole();
+
+    const code = await runLogs(["ghost", "-n", "prod"], { connect: cluster.connector });
+
+    expect(code).toBe(1);
+    expect(error.mock.calls[0][0]).toContain("NotFound");
+  });
+});

package/src/kube/logs.ts

@@ -0,0 +1,96 @@
+/**
+ * `chant kube logs` (chant #1079) — a Pod's `/log` subresource, over the
+ * typed client's new `readLog` (`packages/k8s-client/src/client.ts`). A
+ * snapshot only: `--follow`/`-f` would need the transport seam to expose a
+ * stream rather than a completed response body, which it does not today —
+ * left out deliberately (see `readLog`'s own doc) rather than faked with a
+ * poll loop that isn't actually following anything.
+ */
+
+import { formatUnobserved } from "@intentius/chant/observation";
+import { defaultK8sConnector, type K8sConnector } from "../api/connect";
+import { classifyApiFailure } from "../api/classify";
+import { operationFor } from "../api/operation-surface";
+import { kubeConnect } from "./connect";
+import { parseKubeFlags, connectOptionsFrom, parseDurationSeconds } from "./flags";
+import { loadKubeProjectContext, type KubeProjectContext } from "./project";
+
+export interface LogsDeps {
+  connect?: K8sConnector;
+  loadProject?: (cwd?: string) => Promise<KubeProjectContext | undefined>;
+}
+
+export async function runLogs(rawArgs: string[], deps: LogsDeps = {}): Promise<number> {
+  const connect = deps.connect ?? defaultK8sConnector;
+  const loadProject = deps.loadProject ?? loadKubeProjectContext;
+
+  let flags;
+  try {
+    flags = parseKubeFlags(rawArgs, {
+      value: { "-c": "container", "--container": "container", "--tail": "tail", "--since": "since" },
+      boolean: { "-p": "previous", "--previous": "previous", "--timestamps": "timestamps" },
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const podArg = flags.positional[0];
+  if (!podArg) {
+    console.error("error: a pod name (or a declared entity name) is required — e.g. `chant kube logs web-6c8f`");
+    return 1;
+  }
+
+  const project = await loadProject();
+  let podName = podArg;
+  let namespace = flags.values.namespace;
+  const entity = project?.entities.get(podArg);
+  if (entity && entity.lexicon === "k8s") {
+    const operation = operationFor(entity.entityType);
+    if (operation && operation.kind !== "Pod") {
+      console.error(`error: "${podArg}" declares a ${operation.kind}, not a Pod — chant kube logs only reads Pod logs`);
+      return 1;
+    }
+    if (operation?.kind === "Pod") {
+      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 (metadata?.name) {
+        podName = metadata.name;
+        namespace = namespace ?? metadata.namespace;
+      }
+    }
+  }
+
+  const connected = await kubeConnect(connectOptionsFrom(flags.values), connect);
+  if (connected.kind === "unobserved") {
+    console.error(formatUnobserved(`pod/${podName}`, { reason: connected.reason, detail: connected.detail }));
+    return 1;
+  }
+  const { client } = connected;
+
+  const tailLines = flags.values.tail !== undefined ? Number(flags.values.tail) : undefined;
+  const sinceSeconds = flags.values.since !== undefined ? parseDurationSeconds(flags.values.since) : undefined;
+
+  try {
+    const text = await client.readLog(
+      { apiVersion: "v1", kind: "Pod", name: podName, namespace: namespace ?? client.defaultNamespace },
+      {
+        ...(flags.values.container ? { container: flags.values.container } : {}),
+        ...(tailLines !== undefined ? { tailLines } : {}),
+        ...(sinceSeconds !== undefined ? { sinceSeconds } : {}),
+        previous: flags.flags.previous ?? false,
+        timestamps: flags.flags.timestamps ?? false,
+      },
+    );
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+    return 0;
+  } catch (err) {
+    const outcome = classifyApiFailure(err);
+    if (outcome.kind === "absent") {
+      console.error(`Error from server (NotFound): pods "${podName}" not found`);
+      return 1;
+    }
+    console.error(formatUnobserved(`pod/${podName}`, { reason: outcome.reason, detail: outcome.detail }));
+    return 1;
+  }
+}

package/src/kube/project.test.ts

@@ -0,0 +1,57 @@
+/**
+ * `loadKubeProjectContext` exercised for real (chant #1079) — real
+ * `chant.config.ts` discovery, a real `build()`, and real `getProvenance()`
+ * results. Every verb test elsewhere injects a fake `KubeProjectContext`
+ * (`./testing.ts`); this file is what proves the real implementation these
+ * tests are all standing in for actually resolves a project and its
+ * provenance, and — the specific thing chant #1079 asks for — genuinely
+ * returns `undefined` outside one rather than treating an arbitrary
+ * directory as a chant project rooted right there.
+ */
+import { describe, test, expect } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { loadKubeProjectContext, findDeclaredMatch, relativeProvenance } from "./project";
+
+const GETTING_STARTED = resolve(import.meta.dirname, "../../../../examples/getting-started");
+
+describe("loadKubeProjectContext (chant #1079)", () => {
+  test("outside a chant project (no chant.config.ts anywhere): undefined, and fast — no build is attempted", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-kube-no-project-"));
+    try {
+      const ctx = await loadKubeProjectContext(dir);
+      expect(ctx).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("a real project: builds, resolves a declared entity, and its provenance names the source file (relative to the project root)", async () => {
+    const ctx = await loadKubeProjectContext(GETTING_STARTED);
+    expect(ctx).toBeDefined();
+    if (!ctx) return;
+
+    const deploymentEntry = [...ctx.entities].find(([, e]) => e.entityType === "K8s::Apps::Deployment");
+    expect(deploymentEntry).toBeDefined();
+    const [entityName, entity] = deploymentEntry!;
+
+    const props = (entity as { props: { metadata?: { name?: string; namespace?: string } } }).props;
+    const match = findDeclaredMatch(ctx.entities, {
+      apiVersion: "apps/v1",
+      kind: "Deployment",
+      name: props.metadata!.name!,
+      namespace: props.metadata?.namespace,
+    });
+    expect(match?.entityName).toBe(entityName);
+
+    // Entity-level provenance (chant #1064): the declaring file, relativized
+    // to the project root. This fixture re-exports the composite's own
+    // members individually (`export const deployment = web.deployment`)
+    // rather than exporting the composite call itself, so `composite` isn't
+    // stamped here — `./describe.test.ts` and `./source.test.ts` cover that
+    // field directly against a fake entity that does carry it.
+    const prov = relativeProvenance(ctx, entity);
+    expect(prov?.sourceFile).toBe("src/web.ts");
+  });
+});

package/src/kube/project.ts

@@ -0,0 +1,106 @@
+/**
+ * Best-effort chant-project context for `chant kube` (chant #1079).
+ *
+ * `get`'s chant-verdict column and `source` both need to answer "does a
+ * declared entity in this project's source name this live object" — which
+ * needs the project built (chant.config.ts read, source discovered and
+ * resolved). `chant kube` is also usable against a bare cluster with no
+ * chant project in sight (a checkout of someone else's manifests, a
+ * throwaway directory) — the acceptance criterion is that reads still work
+ * there and only the chant-specific parts degrade, quietly, to
+ * "unavailable" rather than erroring. Every failure mode here — no
+ * `chant.config.ts`, a project with build errors, an unreadable directory —
+ * collapses to `undefined` for exactly that reason.
+ *
+ * Deliberately does not import anything client-shaped: this runs before a
+ * cluster is ever reached (`source`/`get` need it to compute a verdict for
+ * objects the client already read), and matching is pure once given a live
+ * object's coordinates.
+ */
+
+import { resolve, relative, isAbsolute } from "node:path";
+import { build } from "@intentius/chant/build";
+import { loadChantConfig, type ChantConfig } from "@intentius/chant/config";
+import { getProvenance, type EntityProvenance } from "@intentius/chant/provenance";
+import type { Declarable } from "@intentius/chant/declarable";
+import { k8sSerializer } from "../serializer";
+import { operationFor } from "../api/operation-surface";
+
+export interface KubeProjectContext {
+  cwd: string;
+  config: ChantConfig;
+  entities: Map<string, Declarable>;
+}
+
+/**
+ * Build the project rooted at `cwd` (or its configured `sourceDir`) with the
+ * k8s serializer, so `entities` carries resolved props (composites expanded,
+ * AttrRefs resolved) and build provenance (chant #1064's entity-level
+ * `sourceFile`/`composite`, stamped during discovery). Returns undefined —
+ * never throws — for anything that stops the project from resolving: no
+ * `chant.config.ts` here or above, a build with errors, an inaccessible
+ * directory. This IS the "outside a chant project" signal every caller
+ * checks for.
+ */
+export async function loadKubeProjectContext(cwd: string = process.cwd()): Promise<KubeProjectContext | undefined> {
+  try {
+    const { config, configPath } = await loadChantConfig(cwd);
+    // `loadChantConfig` does not throw when neither `chant.config.ts` nor
+    // `chant.config.json` exists at `cwd` — it returns the default empty
+    // config instead (`configPath` absent). Building anyway would treat an
+    // arbitrary directory (a bare cluster checkout, chant's own monorepo
+    // root run from the wrong cwd) as a chant project rooted right there —
+    // exactly the "outside a chant project" case this function exists to
+    // detect, not paper over.
+    if (!configPath) return undefined;
+    const root = resolve(cwd, config.sourceDir ?? ".");
+    const result = await build(root, [k8sSerializer]);
+    if (result.errors.length > 0) return undefined;
+    return { cwd, config, entities: result.entities };
+  } catch {
+    return undefined;
+  }
+}
+
+function propsOf(entity: Declarable): Record<string, unknown> | undefined {
+  return "props" in entity ? ((entity as { props: unknown }).props as Record<string, unknown>) : undefined;
+}
+
+export interface DeclaredMatch {
+  entityName: string;
+  entity: Declarable;
+  props: Record<string, unknown> | undefined;
+}
+
+/**
+ * Reverse-map a live object's coordinates (apiVersion/kind/name/namespace) to
+ * the declared k8s entity that names it, if this project declares one.
+ * `operationFor` is the same generated operation surface `describeResources`
+ * addresses entities with, so a match here is addressed exactly the way the
+ * live read that produced the object was — no separate naming convention.
+ */
+export function findDeclaredMatch(
+  entities: Map<string, Declarable>,
+  ref: { apiVersion: string; kind: string; name: string; namespace?: string },
+): DeclaredMatch | undefined {
+  for (const [entityName, entity] of entities) {
+    if (entity.lexicon !== "k8s") continue;
+    const operation = operationFor(entity.entityType);
+    if (!operation || operation.apiVersion !== ref.apiVersion || operation.kind !== ref.kind) continue;
+    const props = propsOf(entity);
+    const metadata = props?.metadata as { name?: string; namespace?: string } | undefined;
+    if (metadata?.name !== ref.name) continue;
+    if ((metadata?.namespace ?? undefined) !== (ref.namespace ?? undefined)) continue;
+    return { entityName, entity, props };
+  }
+  return undefined;
+}
+
+/** Provenance for a matched entity, relative to the project root when possible. */
+export function relativeProvenance(ctx: KubeProjectContext, entity: Declarable): EntityProvenance | undefined {
+  const prov = getProvenance(entity);
+  if (!prov) return undefined;
+  if (!prov.sourceFile || !isAbsolute(prov.sourceFile)) return prov;
+  const rel = relative(ctx.cwd, prov.sourceFile);
+  return { ...prov, sourceFile: rel.startsWith("..") ? prov.sourceFile : rel };
+}

package/src/kube/render.test.ts

@@ -0,0 +1,142 @@
+import { describe, test, expect } from "vitest";
+import {
+  parseOutput,
+  relativeAge,
+  renderTable,
+  evalJsonPath,
+  renderJsonPath,
+  renderCustomColumns,
+  renderJson,
+  renderYaml,
+  renderName,
+} from "./render";
+import type { K8sObject } from "@intentius/chant-k8s-client";
+
+describe("parseOutput (chant #1079)", () => {
+  test("defaults to text", () => {
+    expect(parseOutput(undefined)).toEqual({ kind: "text" });
+  });
+
+  test("parses every recognized form", () => {
+    expect(parseOutput("wide")).toEqual({ kind: "wide" });
+    expect(parseOutput("json")).toEqual({ kind: "json" });
+    expect(parseOutput("yaml")).toEqual({ kind: "yaml" });
+    expect(parseOutput("name")).toEqual({ kind: "name" });
+    expect(parseOutput("chant")).toEqual({ kind: "chant" });
+    expect(parseOutput("jsonpath={.metadata.name}")).toEqual({ kind: "jsonpath", expr: "{.metadata.name}" });
+    expect(parseOutput("custom-columns=NAME:.metadata.name")).toEqual({
+      kind: "custom-columns",
+      spec: "NAME:.metadata.name",
+    });
+  });
+
+  test("go-template is refused by name, not half-implemented", () => {
+    expect(() => parseOutput("go-template={{.metadata.name}}")).toThrow(/go-template/);
+    expect(() => parseOutput("go-template-file=x.tmpl")).toThrow(/go-template/);
+  });
+
+  test("an unrecognized value is refused", () => {
+    expect(() => parseOutput("bogus")).toThrow(/unsupported/);
+  });
+});
+
+describe("relativeAge", () => {
+  test("renders seconds, minutes, hours, days", () => {
+    const now = Date.parse("2026-01-02T00:00:00Z");
+    expect(relativeAge("2026-01-02T00:00:00Z", now)).toBe("0s");
+    expect(relativeAge("2026-01-01T23:59:30Z", now)).toBe("30s");
+    expect(relativeAge("2026-01-01T23:50:00Z", now)).toBe("10m");
+    expect(relativeAge("2026-01-01T18:00:00Z", now)).toBe("6h");
+    expect(relativeAge("2025-12-30T00:00:00Z", now)).toBe("3d");
+  });
+
+  test("undefined/unparseable input is honest, not a crash", () => {
+    expect(relativeAge(undefined)).toBe("<unknown>");
+    expect(relativeAge("not-a-date")).toBe("<unknown>");
+  });
+});
+
+describe("renderTable", () => {
+  test("pads columns to the widest cell and trims trailing whitespace", () => {
+    const out = renderTable(["NAME", "AGE"], [["web", "3d"], ["a-much-longer-name", "1h"]]);
+    const lines = out.split("\n");
+    expect(lines[0]).toBe("NAME                AGE");
+    expect(lines[2]).toBe("a-much-longer-name  1h");
+  });
+});
+
+describe("jsonpath (subset)", () => {
+  const root = { metadata: { name: "web" }, items: [{ metadata: { name: "a" } }, { metadata: { name: "b" } }] };
+
+  test("a dot path extracts a scalar", () => {
+    expect(evalJsonPath("{.metadata.name}", root)).toBe("web");
+  });
+
+  test("a wildcard collects and space-joins matches", () => {
+    expect(evalJsonPath("{.items[*].metadata.name}", root)).toBe("a b");
+  });
+
+  test("an index selects one element", () => {
+    expect(evalJsonPath("{.items[1].metadata.name}", root)).toBe("b");
+  });
+
+  test("literal text and quoted literals pass through untouched", () => {
+    expect(evalJsonPath('name={.metadata.name}{"!"}', root)).toBe("name=web!");
+  });
+
+  test("renderJsonPath wraps >1 object in a synthetic List, matching kubectl", () => {
+    const objects = [
+      { apiVersion: "v1", kind: "Pod", metadata: { name: "a" } },
+      { apiVersion: "v1", kind: "Pod", metadata: { name: "b" } },
+    ] as K8sObject[];
+    expect(renderJsonPath("{.items[*].metadata.name}", objects)).toBe("a b");
+  });
+
+  test("a single object is printed bare, not wrapped in a List", () => {
+    const objects = [{ apiVersion: "v1", kind: "Pod", metadata: { name: "a" } }] as K8sObject[];
+    expect(renderJsonPath("{.metadata.name}", objects)).toBe("a");
+  });
+});
+
+describe("custom-columns", () => {
+  test("renders a header per entry and evaluates its path per object", () => {
+    const objects = [
+      { apiVersion: "v1", kind: "Pod", metadata: { name: "a", namespace: "prod" } },
+      { apiVersion: "v1", kind: "Pod", metadata: { name: "b", namespace: "staging" } },
+    ] as K8sObject[];
+    const out = renderCustomColumns("NAME:.metadata.name,NS:.metadata.namespace", objects);
+    expect(out).toContain("NAME");
+    expect(out).toContain("NS");
+    expect(out).toMatch(/a\s+prod/);
+    expect(out).toMatch(/b\s+staging/);
+  });
+
+  test("a missing ':' is a clear parse error", () => {
+    expect(() => renderCustomColumns("NAME.metadata.name", [])).toThrow(/":"/);
+  });
+});
+
+describe("json / yaml / name", () => {
+  const one = [{ apiVersion: "v1", kind: "Pod", metadata: { name: "a" } }] as K8sObject[];
+  const many = [
+    { apiVersion: "v1", kind: "Pod", metadata: { name: "a" } },
+    { apiVersion: "v1", kind: "Pod", metadata: { name: "b" } },
+  ] as K8sObject[];
+
+  test("a single object prints bare in json/yaml", () => {
+    expect(JSON.parse(renderJson(one)).metadata.name).toBe("a");
+    expect(renderYaml(one)).toContain("name: a");
+  });
+
+  test("multiple objects wrap in a List", () => {
+    expect(JSON.parse(renderJson(many)).kind).toBe("List");
+    expect(renderYaml(many)).toContain("kind: List");
+  });
+
+  test("-o name renders <kind>.<group>/<name>, or <kind>/<name> for the core group", () => {
+    expect(renderName([{ apiVersion: "v1", kind: "Pod", metadata: { name: "a" } }] as K8sObject[])).toBe("pod/a");
+    expect(
+      renderName([{ apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "web" } }] as K8sObject[]),
+    ).toBe("deployment.apps/web");
+  });
+});