@oasissys/k8s-cli 0.1.2

package/dist/src/toon.js

@@ -0,0 +1,148 @@
+/**
+ * Minimal TOON (Token-Oriented Object Notation) encoder.
+ *
+ * TOON is the stdout format for AXI CLIs — ~40% fewer tokens than JSON while
+ * staying readable by agents. See https://toonformat.dev/reference/spec.html.
+ *
+ * Keep all internal logic on plain JS objects; call `encode()` only at the
+ * output boundary. This encoder covers the shapes an AXI CLI actually emits:
+ *
+ *   - objects            key: value
+ *   - nested objects     key:\n  child: value
+ *   - tabular arrays      key[N]{f1,f2}:\n  a,b\n  c,d
+ *   - primitive arrays    key[N]: a,b,c
+ *   - empty arrays        key[0]:
+ *
+ * Two-space indentation, no tabs, no trailing newline (§12).
+ */
+const INDENT = "  ";
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isScalar(v) {
+    return v === null || v === undefined || ["string", "number", "boolean"].includes(typeof v);
+}
+// §7.2 — a string MUST be quoted when it would otherwise be ambiguous with a
+// structural token, a literal (true/false/null), or a number. We also quote on
+// the comma delimiter so the same formatter is safe inside tabular rows.
+const NUMERIC_LIKE = /^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
+const NEEDS_QUOTE = /[:"\\[\]{},]/;
+function hasControlChar(s) {
+    for (let i = 0; i < s.length; i++) {
+        if (s.charCodeAt(i) <= 0x1f)
+            return true;
+    }
+    return false;
+}
+function quoteString(s) {
+    const needs = s.length === 0 ||
+        s !== s.trim() ||
+        s === "true" ||
+        s === "false" ||
+        s === "null" ||
+        NUMERIC_LIKE.test(s) ||
+        NEEDS_QUOTE.test(s) ||
+        hasControlChar(s);
+    if (!needs)
+        return s;
+    const escaped = s
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    return `"${escaped}"`;
+}
+function formatScalar(v) {
+    if (v === null || v === undefined)
+        return "null";
+    if (typeof v === "boolean")
+        return v ? "true" : "false";
+    if (typeof v === "number") {
+        if (!Number.isFinite(v))
+            return "null";
+        return Object.is(v, -0) ? "0" : String(v);
+    }
+    if (typeof v === "string")
+        return quoteString(v);
+    // Non-scalar leaked into a scalar slot — stringify defensively rather than throw.
+    return quoteString(JSON.stringify(v));
+}
+function tableFields(arr) {
+    // Tabular form is only valid when every row is a flat object (scalar values)
+    // sharing the first row's key set. Otherwise fall back to a list.
+    const fields = Object.keys(arr[0]);
+    if (fields.length === 0)
+        return null;
+    for (const row of arr) {
+        const keys = Object.keys(row);
+        if (keys.length !== fields.length || !fields.every(f => f in row))
+            return null;
+        if (!fields.every(f => isScalar(row[f])))
+            return null;
+    }
+    return fields;
+}
+function emitArray(key, arr, depth, lines) {
+    const pad = INDENT.repeat(depth);
+    if (arr.length === 0) {
+        lines.push(`${pad}${key}[0]:`);
+        return;
+    }
+    if (arr.every(isScalar)) {
+        lines.push(`${pad}${key}[${arr.length}]: ${arr.map(formatScalar).join(",")}`);
+        return;
+    }
+    if (arr.every(isPlainObject)) {
+        const rows = arr;
+        const fields = tableFields(rows);
+        if (fields) {
+            lines.push(`${pad}${key}[${arr.length}]{${fields.join(",")}}:`);
+            for (const row of rows) {
+                lines.push(`${INDENT.repeat(depth + 1)}${fields.map(f => formatScalar(row[f])).join(",")}`);
+            }
+            return;
+        }
+        // Non-uniform / nested objects → list of blocks.
+        lines.push(`${pad}${key}[${arr.length}]:`);
+        for (const row of rows) {
+            lines.push(`${INDENT.repeat(depth + 1)}-`);
+            emitObject(row, depth + 2, lines);
+        }
+        return;
+    }
+    // Mixed array — stringify each element as a scalar.
+    lines.push(`${pad}${key}[${arr.length}]: ${arr.map(formatScalar).join(",")}`);
+}
+function emitObject(obj, depth, lines) {
+    const pad = INDENT.repeat(depth);
+    for (const [key, value] of Object.entries(obj)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            emitArray(key, value, depth, lines);
+        }
+        else if (isPlainObject(value)) {
+            lines.push(`${pad}${key}:`);
+            emitObject(value, depth + 1, lines);
+        }
+        else {
+            lines.push(`${pad}${key}: ${formatScalar(value)}`);
+        }
+    }
+}
+/** Encode a JS value to a TOON document (no trailing newline). */
+export function encode(value) {
+    const lines = [];
+    if (Array.isArray(value)) {
+        // Root array: emit with an empty key so the header is a bare `[N]{...}:`.
+        emitArray("", value, 0, lines);
+        return lines.join("\n");
+    }
+    if (isPlainObject(value)) {
+        emitObject(value, 0, lines);
+        return lines.join("\n");
+    }
+    return formatScalar(value);
+}
+//# sourceMappingURL=toon.js.map

package/dist/src/toon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toon.js","sourceRoot":"","sources":["../../src/toon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,GAAG,IAAI,CAAC;AAIpB,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,6EAA6E;AAC7E,+EAA+E;AAC/E,yEAAyE;AACzE,MAAM,YAAY,GAAG,kCAAkC,CAAC;AACxD,MAAM,WAAW,GAAG,cAAc,CAAC;AAEnC,SAAS,cAAc,CAAC,CAAS;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,CAAS;IAC5B,MAAM,KAAK,GACT,CAAC,CAAC,MAAM,KAAK,CAAC;QACd,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE;QACd,CAAC,KAAK,MAAM;QACZ,CAAC,KAAK,OAAO;QACb,CAAC,KAAK,MAAM;QACZ,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QACpB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;QACnB,cAAc,CAAC,CAAC,CAAC,CAAC;IACpB,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC;IACrB,MAAM,OAAO,GAAG,CAAC;SACd,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACzB,OAAO,IAAI,OAAO,GAAG,CAAC;AACxB,CAAC;AAED,SAAS,YAAY,CAAC,CAAU;IAC9B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACjD,IAAI,OAAO,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACxD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;YAAE,OAAO,MAAM,CAAC;QACvC,OAAO,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;IACjD,kFAAkF;IAClF,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,WAAW,CAAC,GAA8B;IACjD,6EAA6E;IAC7E,kEAAkE;IAClE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC/E,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;IACxD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,GAAW,EAAE,GAAc,EAAE,KAAa,EAAE,KAAe;IAC5E,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC;QAC/B,OAAO;IACT,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9E,OAAO;IACT,CAAC;IACD,IAAI,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,GAAgC,CAAC;QAC9C,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,MAAM,EAAE,CAAC;YACX,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChE,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9F,CAAC;YACD,OAAO;QACT,CAAC;QACD,iDAAiD;QACjD,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YAC3C,UAAU,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,OAAO;IACT,CAAC;IACD,oDAAoD;IACpD,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC;AAED,SAAS,UAAU,CAAC,GAA4B,EAAE,KAAa,EAAE,KAAe;IAC9E,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC;YAC5B,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,GAAG,GAAG,GAAG,GAAG,KAAK,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,MAAM,CAAC,KAAc;IACnC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,0EAA0E;QAC1E,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,UAAU,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5B,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IACD,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@oasissys/k8s-cli",
+  "version": "0.1.2",
+  "packageManager": "pnpm@11.9.0",
+  "description": "oasis-k8s — AXI CLI for read-only Kubernetes access across the Oasis clusters (token-only, multi-cluster) with token-efficient TOON output",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oasissys/k8s-cli.git"
+  },
+  "keywords": [
+    "kubernetes",
+    "k8s",
+    "cli",
+    "agent",
+    "axi",
+    "toon",
+    "oasis"
+  ],
+  "bin": {
+    "oasis-k8s": "./dist/bin/oasis-k8s.js"
+  },
+  "files": [
+    "dist",
+    "skills/k8s-cli",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:skill": "tsx scripts/build-skill.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "dev": "tsx bin/oasis-k8s.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.1.0",
+    "globals": "^17.4.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/k8s-cli/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: k8s-cli
+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.
+---
+
+# oasis-k8s
+
+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: `oasis-k8s add <name> --url https://<host>:6443 --token <token>`.
+Invoke as `oasis-k8s` (on PATH after a global install; no install: `npx -y @oasissys/k8s-cli`). TOON output; exit 0/1/2; every command has `--help`.
+
+## 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
+
+| Command | What it does |
+|---|---|
+| `oasis-k8s (no args)` | live view: saved clusters + which is active |
+| `oasis-k8s clusters` | list saved clusters and the active one |
+| `oasis-k8s use <name>` | set the active cluster |
+| `oasis-k8s add <name> --url <apiserver> --token <t>` | register a cluster (verified before saving) |
+| `oasis-k8s rm <name>` | remove a saved cluster |
+| `oasis-k8s namespaces` | list namespaces |
+| `oasis-k8s nodes` | list nodes (status + kubelet version) |
+| `oasis-k8s pods [--namespace <ns>]` | list pods (all namespaces by default) |
+| `oasis-k8s deployments [--namespace <ns>]` | list deployments (ready/available replicas) |
+| `oasis-k8s services [--namespace <ns>]` | list services (type, clusterIP, ports) |
+| `oasis-k8s events [--namespace <ns>]` | list events, newest last |
+| `oasis-k8s logs <pod> --namespace <ns> [--container <c>] [--tail <n>] [--previous]` | print a pod's container logs |
+| `oasis-k8s describe <kind> <name> [--namespace <ns>]` | dump one object as JSON |
+
+## Examples
+
+```sh
+# Which clusters are configured, and which is active?
+oasis-k8s clusters
+
+# Inspect the active cluster
+oasis-k8s pods --namespace default
+oasis-k8s nodes
+
+# Why is a pod crashing? tail its logs, then the previous instance
+oasis-k8s logs my-pod --namespace default --tail 80
+oasis-k8s logs my-pod --namespace default --previous
+
+# Target a specific cluster without switching the active one
+oasis-k8s 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.