@oasissys/k8s-cli 0.1.2

package/dist/src/cli.js

@@ -0,0 +1,768 @@
+/**
+ * oasis-k8s — AXI CLI for read-only Kubernetes access across the Oasis clusters.
+ *
+ * Talks straight to each cluster's kube-apiserver with a ServiceAccount bearer
+ * token (no kubeconfig, no certs). Multiple clusters are saved by name in
+ * ~/.oasis.json (shared store) with one marked active — same model as
+ * oasis-sqlcl connections. Every command is read-only.
+ *
+ * Output is TOON on stdout; diagnostics on stderr; exit codes 0/1/2
+ * (success/error/usage). See ./axi and `oasis-k8s --help`.
+ */
+import { K8sClient, K8sError, normalizeKind, SUPPORTED_KINDS, } from "./client.js";
+import { loadSection, saveSection } from "./storage.js";
+import { EXIT, emit, emitRaw, fail, binPath, parseArgs, flagStr, flagBool, flagInt, renderSkillDoc, runSetup, } from "./axi.js";
+const DESCRIPTION = "Read-only Kubernetes access across the Oasis clusters (token-only, multi-cluster)";
+const BIN = "oasis-k8s";
+const LOGS_TAIL_DEFAULT = 200; // log lines shown when --tail is omitted
+function loadClusters() {
+    return loadSection("k8s").clusters ?? {};
+}
+function getActive() {
+    return loadSection("k8s").active;
+}
+function setActive(name) {
+    return saveSection("k8s", s => {
+        s.active = name;
+        return s;
+    });
+}
+function saveCluster(name, cluster) {
+    return saveSection("k8s", s => {
+        s.clusters = { ...s.clusters, [name]: cluster };
+        return s;
+    });
+}
+function deleteCluster(name) {
+    return saveSection("k8s", s => {
+        if (s.clusters)
+            delete s.clusters[name];
+        if (s.active === name)
+            delete s.active;
+        return s;
+    });
+}
+/** Resolve which cluster to target: --cluster > active > sole cluster > error. */
+function resolveCluster(parsed) {
+    const clusters = loadClusters();
+    const names = Object.keys(clusters);
+    const explicit = flagStr(parsed, "--cluster");
+    if (explicit) {
+        if (!clusters[explicit]) {
+            fail(`cluster '${explicit}' not found`, `Run \`${BIN} clusters\` to list saved clusters`);
+        }
+        return { name: explicit, cluster: clusters[explicit] };
+    }
+    const active = getActive();
+    if (active && clusters[active])
+        return { name: active, cluster: clusters[active] };
+    if (names.length === 1)
+        return { name: names[0], cluster: clusters[names[0]] };
+    if (names.length === 0) {
+        fail("no saved clusters", `Add one with \`${BIN} add <name> --url <apiserver> --token <token>\``);
+    }
+    fail("no active cluster selected", `Run \`${BIN} use <name>\` to pick one, or pass \`--cluster <name>\``);
+}
+function getClient(parsed) {
+    const { name, cluster } = resolveCluster(parsed);
+    return { name, client: new K8sClient(cluster.url, cluster.token) };
+}
+/** Map a K8sError into an AXI error and exit — 401/403 get actionable advice. */
+function bail(err, ctx) {
+    if (err instanceof K8sError) {
+        if (err.forbidden) {
+            fail(`forbidden: the '${ctx.cluster}' token lacks RBAC to ${ctx.what}`, "This ServiceAccount is scoped — use a token with broader read access, or try a resource it can read");
+        }
+        if (err.unauthorized) {
+            fail(`unauthorized on '${ctx.cluster}' (token rejected or expired)`, `Re-add the cluster with a fresh token: \`${BIN} add ${ctx.cluster} --url <apiserver> --token <token>\``);
+        }
+        if (err.notFound)
+            fail(`not found: ${ctx.what} on '${ctx.cluster}'`);
+        fail(`k8s error on '${ctx.cluster}': ${err.message}`);
+    }
+    fail(err instanceof Error ? err.message : String(err));
+}
+// ─── Formatting helpers ──────────────────────────────────────────────
+/** kubectl-style compact age from a creation timestamp (e.g. 5d, 3h, 20m, 45s). */
+function age(iso) {
+    if (!iso)
+        return "-";
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return "-";
+    const sec = Math.max(0, Math.floor((Date.now() - then) / 1000));
+    if (sec < 60)
+        return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60)
+        return `${min}m`;
+    const hr = Math.floor(min / 60);
+    if (hr < 48)
+        return `${hr}h`;
+    return `${Math.floor(hr / 24)}d`;
+}
+function podReady(pod) {
+    const cs = pod.status?.containerStatuses ?? [];
+    const total = pod.spec?.containers?.length ?? cs.length;
+    const ready = cs.filter(c => c.ready).length;
+    return `${ready}/${total}`;
+}
+function podRestarts(pod) {
+    return (pod.status?.containerStatuses ?? []).reduce((n, c) => n + (c.restartCount ?? 0), 0);
+}
+/** Refine a pod's phase with the real waiting/terminated reason (CrashLoopBackOff etc). */
+function podStatus(pod) {
+    const cs = pod.status?.containerStatuses ?? [];
+    for (const c of cs) {
+        const waiting = c.state?.waiting?.reason;
+        const terminated = c.state?.terminated?.reason;
+        if (waiting && waiting !== "ContainerCreating")
+            return waiting;
+        if (terminated && terminated !== "Completed")
+            return terminated;
+    }
+    return pod.status?.phase ?? "Unknown";
+}
+function nodeReady(node) {
+    const cond = (node.status?.conditions ?? []).find(c => c.type === "Ready");
+    if (!cond)
+        return "Unknown";
+    return cond.status === "True" ? "Ready" : "NotReady";
+}
+function deployReady(d) {
+    const want = d.spec?.replicas ?? d.status?.replicas ?? 0;
+    const ready = d.status?.readyReplicas ?? 0;
+    return `${ready}/${want}`;
+}
+function svcPorts(s) {
+    const ports = s.spec?.ports ?? [];
+    if (ports.length === 0)
+        return "-";
+    return ports
+        .map(p => (p.nodePort ? `${p.port}:${p.nodePort}/${p.protocol ?? "TCP"}` : `${p.port}/${p.protocol ?? "TCP"}`))
+        .join(",");
+}
+function eventTime(e) {
+    return e.lastTimestamp ?? e.eventTime ?? e.metadata?.creationTimestamp ?? "-";
+}
+/** Namespace flag shared by list commands: `--namespace <ns>`; absent = all namespaces. */
+function nsOf(parsed) {
+    return flagStr(parsed, "--namespace");
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error("timeout")), ms);
+        p.then(v => {
+            clearTimeout(t);
+            resolve(v);
+        }, e => {
+            clearTimeout(t);
+            reject(e);
+        });
+    });
+}
+// ─── Cluster-management commands ─────────────────────────────────────
+function clusterRows(clusters) {
+    return Object.entries(clusters).map(([name, c]) => ({ name, url: c.url }));
+}
+async function cmdHome() {
+    const clusters = loadClusters();
+    const names = Object.keys(clusters);
+    const active = getActive();
+    const doc = {
+        bin: binPath(),
+        description: DESCRIPTION,
+        active: active && clusters[active] ? active : names.length === 1 ? `${names[0]} (only cluster)` : "none",
+        count: names.length,
+    };
+    if (names.length === 0) {
+        doc.clusters = [];
+        doc.help = [`Run \`${BIN} add <name> --url <apiserver> --token <token>\` to register a cluster`];
+        emit(doc);
+        return;
+    }
+    doc.clusters = clusterRows(clusters);
+    doc.help = [
+        `Run \`${BIN} use <name>\` to switch the active cluster`,
+        `Run \`${BIN} pods\` / \`${BIN} nodes\` / \`${BIN} namespaces\` to inspect the active cluster`,
+        `Run \`${BIN} logs <pod> --namespace <ns>\` to read container logs`,
+    ];
+    emit(doc);
+}
+async function cmdClusters() {
+    const clusters = loadClusters();
+    const active = getActive();
+    if (Object.keys(clusters).length === 0) {
+        emit({ clusters: [] });
+        emitRaw("clusters: 0 saved clusters");
+        emit({ help: [`Run \`${BIN} add <name> --url <apiserver> --token <token>\` to add one`] });
+        return;
+    }
+    emit({
+        active: active && clusters[active] ? active : "none",
+        count: Object.keys(clusters).length,
+        clusters: clusterRows(clusters),
+        help: [`Run \`${BIN} use <name>\` to set the active cluster`],
+    });
+}
+async function cmdUse(parsed) {
+    const name = parsed.positionals[0];
+    if (!name)
+        fail("cluster name is required", `${BIN} use <name>`, EXIT.USAGE);
+    if (!loadClusters()[name])
+        fail(`cluster '${name}' not found`, `Run \`${BIN} clusters\` to list saved clusters`);
+    if (getActive() === name) {
+        emit({ active: name, note: "already active (no-op)" });
+        return;
+    }
+    await setActive(name);
+    emit({ active: name });
+}
+async function cmdAdd(parsed) {
+    const name = parsed.positionals[0];
+    if (!name)
+        fail("cluster name is required", `${BIN} add <name> --url <apiserver> --token <token>`, EXIT.USAGE);
+    const url = flagStr(parsed, "--url");
+    const token = flagStr(parsed, "--token");
+    const missing = [!url && "--url", !token && "--token"].filter(Boolean);
+    if (missing.length) {
+        fail(`missing required flag(s): ${missing.join(", ")}`, `${BIN} add ${name} --url <apiserver> --token <token>`, EXIT.USAGE);
+    }
+    if (!/^https?:\/\//.test(url)) {
+        fail(`--url must be the kube-apiserver base URL, e.g. https://<host>:6443 (got '${url}')`, "Do NOT use the Dashboard URL (the :3xxxx /#/login page) — that is the web UI, not the API", EXIT.USAGE);
+    }
+    // Verify the token reaches the apiserver before persisting (fail with the real reason).
+    const client = new K8sClient(url, token);
+    let version;
+    try {
+        version = await client.version();
+    }
+    catch (err) {
+        const reason = err instanceof K8sError ? err.message : err instanceof Error ? err.message : String(err);
+        fail(`could not reach '${name}' at ${url}: ${reason}`, "Check the apiserver URL and that the token is valid");
+    }
+    await saveCluster(name, { url: url, token: token });
+    if (!getActive())
+        await setActive(name);
+    emit({ added: name, url, server: version.gitVersion ?? "?", active: getActive() === name });
+}
+async function cmdRm(parsed) {
+    const name = parsed.positionals[0];
+    if (!name)
+        fail("cluster name is required", `${BIN} rm <name>`, EXIT.USAGE);
+    if (!loadClusters()[name]) {
+        emit({ removed: name, note: "not found (no-op)" });
+        return;
+    }
+    await deleteCluster(name);
+    emit({ removed: name });
+}
+// ─── Read commands ───────────────────────────────────────────────────
+async function cmdNamespaces(parsed) {
+    const { name, client } = getClient(parsed);
+    let list;
+    try {
+        list = await client.namespaces();
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: "list namespaces" });
+    }
+    emit({
+        cluster: name,
+        count: list.items.length,
+        namespaces: list.items.map(n => ({
+            name: n.metadata?.name ?? "?",
+            status: n.status?.phase ?? "?",
+            age: age(n.metadata?.creationTimestamp),
+        })),
+    });
+}
+async function cmdNodes(parsed) {
+    const { name, client } = getClient(parsed);
+    let list;
+    try {
+        list = await client.nodes();
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: "list nodes" });
+    }
+    emit({
+        cluster: name,
+        count: list.items.length,
+        nodes: list.items.map(n => ({
+            name: n.metadata?.name ?? "?",
+            status: nodeReady(n),
+            version: n.status?.nodeInfo?.kubeletVersion ?? "-",
+            age: age(n.metadata?.creationTimestamp),
+        })),
+    });
+}
+async function cmdPods(parsed) {
+    const ns = nsOf(parsed);
+    const { name, client } = getClient(parsed);
+    let list;
+    try {
+        list = await client.pods(ns);
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: ns ? `list pods in '${ns}'` : "list pods (all namespaces)" });
+    }
+    const rows = list.items.map(p => ({
+        namespace: p.metadata?.namespace ?? "-",
+        name: p.metadata?.name ?? "?",
+        ready: podReady(p),
+        status: podStatus(p),
+        restarts: podRestarts(p),
+        age: age(p.metadata?.creationTimestamp),
+        node: p.spec?.nodeName ?? "-",
+    }));
+    emit({
+        cluster: name,
+        scope: ns ? `namespace '${ns}'` : "all namespaces",
+        count: rows.length,
+        pods: rows,
+        help: rows.length > 0
+            ? [`Run \`${BIN} logs <pod> --namespace <ns>\` to read a pod's logs`]
+            : undefined,
+    });
+}
+async function cmdDeployments(parsed) {
+    const ns = nsOf(parsed);
+    const { name, client } = getClient(parsed);
+    let list;
+    try {
+        list = await client.deployments(ns);
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: ns ? `list deployments in '${ns}'` : "list deployments (all namespaces)" });
+    }
+    emit({
+        cluster: name,
+        scope: ns ? `namespace '${ns}'` : "all namespaces",
+        count: list.items.length,
+        deployments: list.items.map(d => ({
+            namespace: d.metadata?.namespace ?? "-",
+            name: d.metadata?.name ?? "?",
+            ready: deployReady(d),
+            upToDate: d.status?.updatedReplicas ?? 0,
+            available: d.status?.availableReplicas ?? 0,
+            age: age(d.metadata?.creationTimestamp),
+        })),
+    });
+}
+async function cmdServices(parsed) {
+    const ns = nsOf(parsed);
+    const { name, client } = getClient(parsed);
+    let list;
+    try {
+        list = await client.services(ns);
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: ns ? `list services in '${ns}'` : "list services (all namespaces)" });
+    }
+    emit({
+        cluster: name,
+        scope: ns ? `namespace '${ns}'` : "all namespaces",
+        count: list.items.length,
+        services: list.items.map(s => ({
+            namespace: s.metadata?.namespace ?? "-",
+            name: s.metadata?.name ?? "?",
+            type: s.spec?.type ?? "ClusterIP",
+            clusterIP: s.spec?.clusterIP ?? "-",
+            ports: svcPorts(s),
+            age: age(s.metadata?.creationTimestamp),
+        })),
+    });
+}
+async function cmdEvents(parsed) {
+    const ns = nsOf(parsed);
+    const { name, client } = getClient(parsed);
+    let list;
+    try {
+        list = await client.events(ns);
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: ns ? `list events in '${ns}'` : "list events (all namespaces)" });
+    }
+    // Newest last — sort ascending by timestamp so the tail is the most recent.
+    const sorted = [...list.items].sort((a, b) => eventTime(a).localeCompare(eventTime(b)));
+    emit({
+        cluster: name,
+        scope: ns ? `namespace '${ns}'` : "all namespaces",
+        count: sorted.length,
+        events: sorted.map(e => ({
+            when: eventTime(e),
+            type: e.type ?? "-",
+            reason: e.reason ?? "-",
+            object: `${e.involvedObject?.kind ?? "?"}/${e.involvedObject?.name ?? "?"}`,
+            namespace: e.involvedObject?.namespace ?? e.metadata?.namespace ?? "-",
+            message: (e.message ?? "").replace(/\s+/g, " ").trim(),
+        })),
+    });
+}
+async function cmdLogs(parsed) {
+    const pod = parsed.positionals[0];
+    if (!pod)
+        fail("pod name is required", `${BIN} logs <pod> --namespace <ns>`, EXIT.USAGE);
+    const ns = nsOf(parsed);
+    if (!ns)
+        fail("--namespace is required for logs", `${BIN} logs ${pod} --namespace <ns>`, EXIT.USAGE);
+    const container = flagStr(parsed, "--container");
+    const previous = flagBool(parsed, "--previous");
+    const tail = flagInt(parsed, "--tail") ?? LOGS_TAIL_DEFAULT;
+    const { name, client } = getClient(parsed);
+    let text;
+    try {
+        text = await client.podLogs(ns, pod, { container, tailLines: tail, previous });
+    }
+    catch (err) {
+        bail(err, { cluster: name, what: `read logs of pod '${pod}' in '${ns}'` });
+    }
+    const lines = text.replace(/\s+$/, "").split(/\r?\n/);
+    const nonEmpty = lines.length === 1 && lines[0] === "" ? 0 : lines.length;
+    emit({
+        cluster: name,
+        namespace: ns,
+        pod,
+        container: container ?? "(default)",
+        lines: nonEmpty,
+        tail: previous ? `${tail} (previous instance)` : String(tail),
+    });
+    emitRaw("");
+    emitRaw(nonEmpty === 0 ? "(no log output)" : lines.join("\n"));
+}
+async function cmdDescribe(parsed) {
+    const kindRaw = parsed.positionals[0];
+    const objName = parsed.positionals[1];
+    if (!kindRaw || !objName) {
+        fail("kind and name are required", `${BIN} describe <kind> <name> [--namespace <ns>]`, EXIT.USAGE);
+    }
+    const kind = normalizeKind(kindRaw);
+    if (!kind) {
+        fail(`unsupported kind '${kindRaw}'`, `supported kinds: ${SUPPORTED_KINDS.join(", ")}`, EXIT.USAGE);
+    }
+    const ns = nsOf(parsed);
+    const { name, client } = getClient(parsed);
+    let obj;
+    try {
+        obj = await client.getObject(kind, objName, ns);
+    }
+    catch (err) {
+        if (err instanceof K8sError && err.status === 400) {
+            fail(err.message, `${BIN} describe ${kind} ${objName} --namespace <ns>`, EXIT.USAGE);
+        }
+        bail(err, { cluster: name, what: `describe ${kind} '${objName}'` });
+    }
+    const meta = (obj.metadata ?? {});
+    emit({
+        cluster: name,
+        kind,
+        name: meta.name ?? objName,
+        namespace: meta.namespace ?? ns ?? "-",
+        // Full object as raw JSON below — TOON would lose fidelity on deep k8s specs.
+    });
+    emitRaw("");
+    emitRaw(JSON.stringify(obj, null, 2));
+}
+/**
+ * Ambient session-start snapshot (AXI §7). Never fails loudly: on no clusters
+ * or an unreachable apiserver it prints nothing and exits 0, so session start
+ * is never blocked or polluted.
+ */
+async function cmdAmbient() {
+    const clusters = loadClusters();
+    const names = Object.keys(clusters);
+    if (names.length === 0)
+        return;
+    const active = getActive();
+    const bin = binPath();
+    emitRaw(`oasis-k8s CLI ready — invoke: ${bin} (append \`help\` for all commands)`);
+    const doc = {
+        active: active && clusters[active] ? active : names.length === 1 ? names[0] : "none",
+        count: names.length,
+        clusters: clusterRows(clusters),
+        help: [
+            `Run \`${bin} use <name>\` to switch clusters`,
+            `Run \`${bin} pods\` / \`${bin} nodes\` to inspect the active cluster`,
+        ],
+    };
+    // Best-effort reachability of the active cluster — silent on any failure.
+    const target = active && clusters[active] ? active : names.length === 1 ? names[0] : undefined;
+    if (target) {
+        try {
+            const v = await withTimeout(new K8sClient(clusters[target].url, clusters[target].token).version(), 2500);
+            doc.activeVersion = v.gitVersion ?? "?";
+        }
+        catch {
+            /* unreachable — omit version, still show the registry */
+        }
+    }
+    emit(doc);
+}
+// ─── Help ────────────────────────────────────────────────────────────
+const HELP = {
+    add: [
+        `${BIN} add <name> — register a cluster (verified against /version before saving)`,
+        "",
+        "flags:",
+        "  --url <apiserver>   kube-apiserver base URL, e.g. https://128.55.0.212:6443",
+        "  --token <token>     ServiceAccount bearer token",
+        "",
+        "Note: use the API server (:6443), NOT the Dashboard UI (:3xxxx /#/login).",
+        "TLS verification is skipped (self-signed internal CAs).",
+        "",
+        "examples:",
+        `  ${BIN} add jeddah --url https://128.55.0.212:6443 --token eyJhbGci...`,
+    ].join("\n"),
+    clusters: [`${BIN} clusters — list saved clusters and the active one`, "", "examples:", `  ${BIN} clusters`].join("\n"),
+    use: [`${BIN} use <name> — set the active cluster`, "", "examples:", `  ${BIN} use jordan`].join("\n"),
+    rm: [`${BIN} rm <name> — remove a saved cluster`, "", "examples:", `  ${BIN} rm jeddah`].join("\n"),
+    pods: [
+        `${BIN} pods — list pods on the active cluster`,
+        "",
+        "flags:",
+        "  --namespace <ns>   restrict to one namespace (default: all namespaces)",
+        "  --cluster <name>   target a specific cluster instead of the active one",
+        "",
+        "examples:",
+        `  ${BIN} pods`,
+        `  ${BIN} pods --namespace kube-system`,
+    ].join("\n"),
+    namespaces: [`${BIN} namespaces — list namespaces on the active cluster`, "", "examples:", `  ${BIN} namespaces`].join("\n"),
+    nodes: [`${BIN} nodes — list nodes (status + kubelet version)`, "", "examples:", `  ${BIN} nodes`].join("\n"),
+    deployments: [
+        `${BIN} deployments — list deployments (ready/available replicas)`,
+        "",
+        "flags:",
+        "  --namespace <ns>   restrict to one namespace (default: all namespaces)",
+        "",
+        "examples:",
+        `  ${BIN} deployments --namespace default`,
+    ].join("\n"),
+    services: [
+        `${BIN} services — list services (type, clusterIP, ports)`,
+        "",
+        "flags:",
+        "  --namespace <ns>   restrict to one namespace (default: all namespaces)",
+        "",
+        "examples:",
+        `  ${BIN} services --namespace default`,
+    ].join("\n"),
+    events: [
+        `${BIN} events — list events (newest last)`,
+        "",
+        "flags:",
+        "  --namespace <ns>   restrict to one namespace (default: all namespaces)",
+        "",
+        "examples:",
+        `  ${BIN} events --namespace default`,
+    ].join("\n"),
+    logs: [
+        `${BIN} logs <pod> — print a pod's container logs (tail by default)`,
+        "",
+        "flags:",
+        "  --namespace <ns>    namespace of the pod (required)",
+        "  --container <name>  container to read (default: first container)",
+        `  --tail <n>          show the last n lines (default ${LOGS_TAIL_DEFAULT})`,
+        "  --previous          logs from the previous (crashed) instance",
+        "",
+        "examples:",
+        `  ${BIN} logs my-pod --namespace default`,
+        `  ${BIN} logs my-pod --namespace default --container app --tail 50`,
+    ].join("\n"),
+    describe: [
+        `${BIN} describe <kind> <name> — dump one object as JSON`,
+        "",
+        `kinds: ${SUPPORTED_KINDS.join(", ")} (plurals/aliases ok: po, svc, deploy, ns, no)`,
+        "",
+        "flags:",
+        "  --namespace <ns>   namespace (required for namespaced kinds)",
+        "",
+        "examples:",
+        `  ${BIN} describe pod my-pod --namespace default`,
+        `  ${BIN} describe node worker-1`,
+    ].join("\n"),
+};
+const SKILL_SPEC = {
+    name: "k8s-cli",
+    binName: BIN,
+    description: "Read-only Kubernetes access across the Oasis clusters from the shell — list namespaces/nodes/pods/deployments/services/events, read pod logs, and describe objects, against multiple clusters selected by name. Use when the user asks about Kubernetes/k8s pods, nodes, deployments, cluster status, pod logs, why a pod is crashing, or the Oasis Jeddah/Jordan clusters.",
+    intro: `Shell CLI for read-only Kubernetes access to the Oasis clusters. Talks straight to each kube-apiserver with a ServiceAccount token — no kubeconfig, no certs. Add a cluster: \`${BIN} add <name> --url https://<host>:6443 --token <token>\`.`,
+    extra: [
+        "## Multiple clusters",
+        "",
+        "Clusters are saved by name (like `oasis-sqlcl` connections), with one",
+        "**active**. Commands run against the active cluster; override per-command",
+        "with `--cluster <name>`. Switch the default with `use <name>`.",
+        "",
+        "## Token-only, read-only",
+        "",
+        "Every command is a GET — the CLI never mutates cluster state. A scoped",
+        "token may lack RBAC for some resources; those calls report a clear",
+        "`forbidden` error rather than crashing. TLS verification is skipped",
+        "(internal self-signed CAs) — point it only at clusters you control.",
+    ],
+    commands: [
+        { cmd: "(no args)", summary: "live view: saved clusters + which is active" },
+        { cmd: "clusters", summary: "list saved clusters and the active one" },
+        { cmd: "use <name>", summary: "set the active cluster" },
+        { cmd: "add <name> --url <apiserver> --token <t>", summary: "register a cluster (verified before saving)" },
+        { cmd: "rm <name>", summary: "remove a saved cluster" },
+        { cmd: "namespaces", summary: "list namespaces" },
+        { cmd: "nodes", summary: "list nodes (status + kubelet version)" },
+        { cmd: "pods [--namespace <ns>]", summary: "list pods (all namespaces by default)" },
+        { cmd: "deployments [--namespace <ns>]", summary: "list deployments (ready/available replicas)" },
+        { cmd: "services [--namespace <ns>]", summary: "list services (type, clusterIP, ports)" },
+        { cmd: "events [--namespace <ns>]", summary: "list events, newest last" },
+        { cmd: "logs <pod> --namespace <ns> [--container <c>] [--tail <n>] [--previous]", summary: "print a pod's container logs" },
+        { cmd: "describe <kind> <name> [--namespace <ns>]", summary: "dump one object as JSON" },
+    ],
+    examples: [
+        "# Which clusters are configured, and which is active?",
+        `${BIN} clusters`,
+        "",
+        "# Inspect the active cluster",
+        `${BIN} pods --namespace default`,
+        `${BIN} nodes`,
+        "",
+        "# Why is a pod crashing? tail its logs, then the previous instance",
+        `${BIN} logs my-pod --namespace default --tail 80`,
+        `${BIN} logs my-pod --namespace default --previous`,
+        "",
+        "# Target a specific cluster without switching the active one",
+        `${BIN} deployments --cluster jordan --namespace default`,
+    ],
+    notes: [
+        "`--cluster <name>` targets one cluster per-command; `use <name>` sets the default.",
+        "Pod `status` reflects the real container reason (CrashLoopBackOff, ImagePullBackOff, …), not just the phase.",
+        "A `forbidden` error means the cluster's token lacks RBAC for that resource — try another resource or a broader token.",
+    ],
+};
+function topHelp() {
+    return [
+        `${BIN} — ${DESCRIPTION}`,
+        `bin: ${binPath()}`,
+        "",
+        "commands:",
+        "  (no args)              live view: saved clusters + active",
+        "  clusters               list saved clusters",
+        "  use <name>             set the active cluster",
+        "  add <name> --url --token   register a cluster",
+        "  rm <name>              remove a saved cluster",
+        "  namespaces             list namespaces",
+        "  nodes                  list nodes",
+        "  pods [--namespace]     list pods",
+        "  deployments [--namespace]  list deployments",
+        "  services [--namespace]     list services",
+        "  events [--namespace]   list events",
+        "  logs <pod> --namespace <ns>   print pod logs",
+        "  describe <kind> <name>        dump one object as JSON",
+        "  setup                  register ambient context for Codex + OpenCode",
+        "",
+        "Every read command accepts `--cluster <name>` to target a specific cluster.",
+        `Run \`${BIN} <command> --help\` for flags and examples.`,
+    ].join("\n");
+}
+// ─── Dispatch ────────────────────────────────────────────────────────
+const NS_CLUSTER = { "--namespace": "value", "--cluster": "value" };
+const COMMAND_FLAGS = {
+    clusters: {},
+    use: {},
+    add: { "--url": "value", "--token": "value" },
+    rm: {},
+    namespaces: { "--cluster": "value" },
+    nodes: { "--cluster": "value" },
+    pods: NS_CLUSTER,
+    deployments: NS_CLUSTER,
+    services: NS_CLUSTER,
+    events: NS_CLUSTER,
+    logs: { "--namespace": "value", "--cluster": "value", "--container": "value", "--tail": "value", "--previous": "bool" },
+    describe: NS_CLUSTER,
+};
+// Command aliases → canonical command.
+const ALIASES = {
+    ns: "namespaces",
+    no: "nodes",
+    po: "pods",
+    pod: "pods",
+    deploy: "deployments",
+    deployment: "deployments",
+    svc: "services",
+    service: "services",
+    event: "events",
+    ls: "clusters",
+    remove: "rm",
+    log: "logs",
+};
+export async function main() {
+    const [, , rawCommand, ...rest] = process.argv;
+    if (rawCommand === "--ambient") {
+        await cmdAmbient().catch(() => { });
+        return;
+    }
+    if (rawCommand === "--skill-doc") {
+        emitRaw(renderSkillDoc(SKILL_SPEC));
+        return;
+    }
+    if (rawCommand === "setup") {
+        runSetup(BIN);
+        return;
+    }
+    if (rawCommand === undefined) {
+        await cmdHome();
+        return;
+    }
+    if (rawCommand === "help" || rawCommand === "--help" || rawCommand === "-h") {
+        const topic = rest[0];
+        const canonical = topic ? ALIASES[topic] ?? topic : undefined;
+        emitRaw(canonical && HELP[canonical] ? HELP[canonical] : topHelp());
+        return;
+    }
+    const command = (ALIASES[rawCommand] ?? rawCommand);
+    if (!(command in COMMAND_FLAGS)) {
+        fail(`unknown command '${rawCommand}'`, `valid commands: ${Object.keys(COMMAND_FLAGS).join(", ")} (run \`${BIN} help\`)`, EXIT.USAGE);
+    }
+    const known = COMMAND_FLAGS[command];
+    const parsed = parseArgs(rest, known, `${BIN} ${command}`);
+    if (flagBool(parsed, "--help")) {
+        emitRaw(HELP[command] ?? topHelp());
+        return;
+    }
+    switch (command) {
+        case "clusters":
+            return cmdClusters();
+        case "use":
+            return cmdUse(parsed);
+        case "add":
+            return cmdAdd(parsed);
+        case "rm":
+            return cmdRm(parsed);
+        case "namespaces":
+            return cmdNamespaces(parsed);
+        case "nodes":
+            return cmdNodes(parsed);
+        case "pods":
+            return cmdPods(parsed);
+        case "deployments":
+            return cmdDeployments(parsed);
+        case "services":
+            return cmdServices(parsed);
+        case "events":
+            return cmdEvents(parsed);
+        case "logs":
+            return cmdLogs(parsed);
+        case "describe":
+            return cmdDescribe(parsed);
+    }
+}
+/** Entry used by bin/: run main() and convert any escaped error into an AXI error (§6). */
+export function run() {
+    main().catch(err => {
+        fail(err instanceof Error ? err.message : String(err));
+    });
+}
+/** Single source of truth for skills/k8s-cli/SKILL.md (§7). */
+export function skillMarkdown() {
+    return renderSkillDoc(SKILL_SPEC);
+}
+//# sourceMappingURL=cli.js.map