@oasissys/k8s-cli 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oasis Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# k8s-cli
+
+`oasis-k8s` — an AXI-compliant CLI for read-only Kubernetes access across the Oasis clusters.
+List namespaces, nodes, pods, deployments, services, and events, read pod logs, and describe objects — with token-efficient [TOON](https://toonformat.dev/) output built for autonomous agents.
+
+Extracted from the `oasis-core` Claude Code plugin so it can be installed, versioned, and released on its own.
+
+## Quick Start
+
+Install the k8s-cli skill in the [Agent Skills](https://agentskills.io) format with [`npx skills`](https://github.com/vercel-labs/skills):
+
+```sh
+npx skills add oasissys/k8s-cli --skill k8s-cli -g
+```
+
+That is the entire setup — the skill teaches your agent the CLI, and it runs without a global install as `npx -y @oasissys/k8s-cli` (Node 20+ required). Installing the skill itself needs GitHub access to this private repo.
+
+`-g` installs the skill for all projects (`~/.claude/skills/`); drop it to install for the current project only.
+
+## Other ways to install
+
+### Zero setup
+
+Any capable agent can run the CLI directly with nothing installed. Just tell your agent:
+
+```
+Execute `npx -y @oasissys/k8s-cli` to get Oasis Kubernetes tools.
+```
+
+### Global install + session hook
+
+Want the CLI on PATH and the saved clusters fed into every agent session?
+
+```sh
+npm install -g @oasissys/k8s-cli
+oasis-k8s setup
+```
+
+`setup` registers a `SessionStart` hook for **Claude Code**, **Codex**, and **OpenCode** that surfaces the saved clusters at session start — restart your agent session after running it.
+If you use the `oasis-core` Claude Code plugin, it already ships this hook; skip `setup` or remove one of the two.
+
+### From a clone (development)
+
+```sh
+pnpm install && pnpm run build && pnpm link --global
+```
+
+## Register clusters
+
+Clusters live in `~/.oasis.json` (shared with the other oasis CLIs and the Oasis dashboard) and are verified against the apiserver's `/version` before being saved.
+The CLI talks straight to each kube-apiserver with a ServiceAccount bearer token — no kubeconfig, no certs.
+
+```sh
+oasis-k8s add jeddah --url https://<host>:6443 --token <token>
+oasis-k8s clusters              # list saved clusters and the active one
+oasis-k8s use jordan            # switch the active cluster
+oasis-k8s rm jeddah             # remove a saved cluster
+```
+
+## Use
+
+```sh
+oasis-k8s                                        # live view: saved clusters + active
+oasis-k8s pods --namespace default               # pods in one namespace
+oasis-k8s nodes                                  # nodes (status + kubelet version)
+oasis-k8s logs my-pod --namespace default        # tail a pod's logs (200 lines)
+oasis-k8s describe pod my-pod --namespace default # dump one object as JSON
+oasis-k8s deployments --cluster jordan           # target a cluster without switching
+```
+
+Every command supports `--help`. Output is TOON on stdout, diagnostics on stderr, exit codes 0/1/2 (success/error/usage).
+Every read command is a GET — the CLI never mutates cluster state.
+
+## Development
+
+```sh
+pnpm run dev -- pods --namespace default   # run from source
+pnpm test                                   # vitest
+pnpm run lint                               # eslint
+pnpm run build:skill                        # regenerate SKILL.md
+```
+
+Releases are cut by release-please from conventional commits on `main`.
+Do not hand-edit `CHANGELOG.md`, `.release-please-manifest.json`, or `skills/k8s-cli/SKILL.md` — they are generated.

package/dist/bin/oasis-k8s.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/oasis-k8s.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/cli.js";
+run();
+//# sourceMappingURL=oasis-k8s.js.map

package/dist/bin/oasis-k8s.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oasis-k8s.js","sourceRoot":"","sources":["../../bin/oasis-k8s.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAEpC,GAAG,EAAE,CAAC"}

package/dist/src/axi.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Shared harness for AXI (Agent eXperience Interface) CLIs.
+ *
+ * Encodes the cross-cutting AXI standards so each service CLI only has to
+ * declare its commands:
+ *   - stdout carries all agent-consumable output (data + errors), stderr is
+ *     for diagnostics only, exit codes are 0/1/2 (success/error/usage) (§6)
+ *   - structured errors on stdout with an actionable `help` line (§6)
+ *   - unknown flags/commands are rejected by name with the valid set inline (§6)
+ *   - `bin:` identity line with the home directory collapsed to `~` (§10)
+ *
+ * See https://toonformat.dev/reference/spec.html for the output format.
+ */
+import { type ServiceId } from "./config.js";
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly ERROR: 1;
+    readonly USAGE: 2;
+};
+/** Collapse the user's home directory prefix to `~` for display (§10). */
+export declare function collapseHome(p: string): string;
+/**
+ * Best-effort absolute path of the running CLI, home-collapsed (§10).
+ * `OASIS_CLI_BIN` lets a launcher advertise the on-PATH name it was invoked as
+ * instead of the bundled entrypoint.
+ */
+export declare function binPath(): string;
+/**
+ * Print a TOON document to stdout.
+ *
+ * A top-level `help: string[]` is rendered as a readable block — one command
+ * template per indented line, unquoted — instead of a comma-joined primitive
+ * array, since suggestions contain colons, commas, and backticks that would
+ * otherwise force heavy quoting. This matches the AXI help convention.
+ */
+export declare function emit(doc: unknown): void;
+/** Print raw text to stdout (for console logs, help blocks — already formatted). */
+export declare function emitRaw(text: string): void;
+/**
+ * Emit a structured error on stdout and exit. `help` is the specific command
+ * that resolves the problem — never "see --help" (§9).
+ */
+export declare function fail(message: string, help?: string | string[], code?: number): never;
+export type FlagKind = "bool" | "value" | "multi";
+export interface ParsedArgs {
+    positionals: string[];
+    /** bool → true; value → last string; multi → string[] */
+    flags: Record<string, string | string[] | true>;
+}
+/**
+ * Parse `--flag`, `--flag value`, and `--flag=value`. Every recognized flag is
+ * declared in `known` with its kind. Unknown flags are rejected by name with
+ * the command's valid set inline, so the agent self-corrects in one turn (§6).
+ *
+ * `--help` is always allowed and surfaces as `flags["--help"] === true`.
+ */
+export declare function parseArgs(argv: string[], known: Record<string, FlagKind>, usageContext: string): ParsedArgs;
+export declare function flagStr(parsed: ParsedArgs, name: string): string | undefined;
+export declare function flagBool(parsed: ParsedArgs, name: string): boolean;
+/**
+ * Register the `<cli> --ambient` SessionStart hook for Claude Code, Codex,
+ * and OpenCode. Idempotent and path-repairing: re-running after a reinstall
+ * updates the path. Reports every target so the agent/user can see exactly
+ * what changed (§7).
+ */
+export declare function runSetup(binName: string): void;
+export interface AuthOptions {
+    /** Executable name for help/suggestions, e.g. "oasis-jenkins". */
+    binName: string;
+    /** Human service label, e.g. "Jenkins". */
+    label: string;
+    /** Whether the service accepts a `--url` override (Jenkins does). */
+    hasUrl?: boolean;
+    /** Probe that throws if the credentials are rejected by the live service. */
+    verify: (creds: {
+        username: string;
+        password: string;
+        url?: string;
+    }) => Promise<void>;
+}
+export declare function runAuth(service: ServiceId, parsed: ParsedArgs, opts: AuthOptions): Promise<void>;
+export declare function flagInt(parsed: ParsedArgs, name: string): number | undefined;
+export declare function flagList(parsed: ParsedArgs, name: string): string[];
+/** Parse a repeatable, comma-separated `--fields a,b --fields c` into ["a","b","c"]. */
+export declare function fieldList(parsed: ParsedArgs, name?: string): string[];
+/**
+ * Resolve which columns a list view should emit. Defaults are the minimal
+ * schema; `requested` (from --fields) adds columns, validated against the full
+ * `available` set — an unknown field fails loud with the valid set (§2, §6).
+ * Output preserves `available` order for stable tables.
+ */
+export declare function resolveColumns(available: string[], defaults: string[], requested: string[], usage: string): string[];
+/** Project a full row down to the selected columns, preserving column order. */
+export declare function pick(row: Record<string, unknown>, cols: string[]): Record<string, unknown>;
+export interface SkillCommand {
+    cmd: string;
+    summary: string;
+}
+export interface SkillSpec {
+    /** Skill name (frontmatter + directory). */
+    name: string;
+    /** Executable base name, e.g. "oasis-jenkins". */
+    binName: string;
+    /** Trigger-shaped one-line frontmatter description. */
+    description: string;
+    /** Opening paragraph(s) of the body. */
+    intro: string;
+    /** Command table rows. */
+    commands: SkillCommand[];
+    /** Shell example lines (no fence). */
+    examples: string[];
+    /** Trailing bullet notes (no leading dash). */
+    notes?: string[];
+    /** Optional extra section inserted before Commands (markdown lines). */
+    extra?: string[];
+}
+/**
+ * Render a SKILL.md from a SkillSpec. The CLI owns the spec, so the committed
+ * skill file is generated — never hand-edited — and `build-cli.sh --check`
+ * fails CI if the committed copy drifts from this output (§7).
+ */
+export declare function renderSkillDoc(spec: SkillSpec): string;

package/dist/src/axi.js

@@ -0,0 +1,406 @@
+/**
+ * Shared harness for AXI (Agent eXperience Interface) CLIs.
+ *
+ * Encodes the cross-cutting AXI standards so each service CLI only has to
+ * declare its commands:
+ *   - stdout carries all agent-consumable output (data + errors), stderr is
+ *     for diagnostics only, exit codes are 0/1/2 (success/error/usage) (§6)
+ *   - structured errors on stdout with an actionable `help` line (§6)
+ *   - unknown flags/commands are rejected by name with the valid set inline (§6)
+ *   - `bin:` identity line with the home directory collapsed to `~` (§10)
+ *
+ * See https://toonformat.dev/reference/spec.html for the output format.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { encode } from "./toon.js";
+import { loadCreds, saveCreds, removeCreds } from "./storage.js";
+import { getServiceBaseUrl } from "./config.js";
+export const EXIT = { OK: 0, ERROR: 1, USAGE: 2 };
+/** Collapse the user's home directory prefix to `~` for display (§10). */
+export function collapseHome(p) {
+    const home = os.homedir();
+    return p === home || p.startsWith(home + path.sep) ? "~" + p.slice(home.length) : p;
+}
+/**
+ * Best-effort absolute path of the running CLI, home-collapsed (§10).
+ * `OASIS_CLI_BIN` lets a launcher advertise the on-PATH name it was invoked as
+ * instead of the bundled entrypoint.
+ */
+export function binPath() {
+    const raw = process.env.OASIS_CLI_BIN || process.argv[1] || "oasis-cli";
+    // A bare command name (no path separator) is an on-PATH launcher name — a
+    // `bin/` shim advertising how it was invoked. Surface it verbatim rather than
+    // resolving it against the cwd, which would fabricate a bogus absolute path.
+    if (!raw.includes("/") && !raw.includes("\\"))
+        return raw;
+    try {
+        return collapseHome(path.resolve(raw));
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Print a TOON document to stdout.
+ *
+ * A top-level `help: string[]` is rendered as a readable block — one command
+ * template per indented line, unquoted — instead of a comma-joined primitive
+ * array, since suggestions contain colons, commas, and backticks that would
+ * otherwise force heavy quoting. This matches the AXI help convention.
+ */
+export function emit(doc) {
+    if (doc && typeof doc === "object" && !Array.isArray(doc) && Array.isArray(doc.help)) {
+        const { help, ...rest } = doc;
+        const body = encode(rest);
+        const helpBlock = help.length > 0
+            ? `help[${help.length}]:\n` + help.map(h => `  ${String(h)}`).join("\n")
+            : "";
+        const out = [body, helpBlock].filter(Boolean).join("\n");
+        process.stdout.write(out + "\n");
+        return;
+    }
+    process.stdout.write(encode(doc) + "\n");
+}
+/** Print raw text to stdout (for console logs, help blocks — already formatted). */
+export function emitRaw(text) {
+    process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+}
+/**
+ * Emit a structured error on stdout and exit. `help` is the specific command
+ * that resolves the problem — never "see --help" (§9).
+ */
+export function fail(message, help, code = EXIT.ERROR) {
+    const doc = { error: message };
+    if (help !== undefined)
+        doc.help = Array.isArray(help) ? help : [help];
+    emit(doc);
+    process.exit(code);
+}
+/**
+ * Parse `--flag`, `--flag value`, and `--flag=value`. Every recognized flag is
+ * declared in `known` with its kind. Unknown flags are rejected by name with
+ * the command's valid set inline, so the agent self-corrects in one turn (§6).
+ *
+ * `--help` is always allowed and surfaces as `flags["--help"] === true`.
+ */
+export function parseArgs(argv, known, usageContext) {
+    const spec = { "--help": "bool", ...known };
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const name = eq === -1 ? arg : arg.slice(0, eq);
+        const kind = spec[name];
+        if (!kind) {
+            const valid = Object.keys(spec).join(", ");
+            fail(`unknown flag ${name} for \`${usageContext}\``, `valid flags: ${valid}`, EXIT.USAGE);
+        }
+        if (kind === "bool") {
+            if (eq !== -1) {
+                fail(`flag ${name} does not take a value`, `use: ${name}`, EXIT.USAGE);
+            }
+            flags[name] = true;
+            continue;
+        }
+        // value / multi
+        let value;
+        if (eq !== -1) {
+            value = arg.slice(eq + 1);
+        }
+        else {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith("--")) {
+                fail(`flag ${name} requires a value`, `use: ${name} <value>`, EXIT.USAGE);
+            }
+            value = next;
+            i++;
+        }
+        if (kind === "multi") {
+            const existing = flags[name];
+            flags[name] = Array.isArray(existing) ? [...existing, value] : [value];
+        }
+        else {
+            flags[name] = value;
+        }
+    }
+    return { positionals, flags };
+}
+export function flagStr(parsed, name) {
+    const v = parsed.flags[name];
+    return typeof v === "string" ? v : undefined;
+}
+export function flagBool(parsed, name) {
+    return parsed.flags[name] === true;
+}
+function upsertJsonHook(file, command, marker) {
+    let data = {};
+    let existed = false;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (parsed && typeof parsed === "object") {
+            data = parsed;
+            existed = true;
+        }
+    }
+    catch { /* new file */ }
+    const hooks = data.hooks && typeof data.hooks === "object" ? data.hooks : {};
+    data.hooks = hooks;
+    const arr = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    let status = "installed";
+    let found = false;
+    for (const group of arr) {
+        if (!group || !Array.isArray(group.hooks))
+            continue;
+        for (const h of group.hooks) {
+            if (h && typeof h.command === "string" && h.command.includes(marker)) {
+                found = true;
+                if (h.command === command)
+                    status = "unchanged";
+                else {
+                    h.command = command;
+                    status = "updated";
+                }
+            }
+        }
+    }
+    if (!found) {
+        arr.push({ hooks: [{ type: "command", command }] });
+        status = existed ? "updated" : "installed";
+    }
+    hooks.SessionStart = arr;
+    if (status !== "unchanged") {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+    }
+    return status;
+}
+function setupCodexConfig() {
+    const file = path.join(os.homedir(), ".codex", "config.toml");
+    let content = "";
+    try {
+        content = fs.readFileSync(file, "utf-8");
+    }
+    catch { /* new file */ }
+    if (/^\s*hooks\s*=\s*true/m.test(content)) {
+        return { target: "codex-config.toml", path: file, status: "unchanged" };
+    }
+    let next;
+    if (/^\s*\[features\]/m.test(content)) {
+        next = content.replace(/^(\s*\[features\]\s*\n)/m, `$1hooks = true\n`);
+    }
+    else {
+        const sep = content && !content.endsWith("\n") ? "\n" : "";
+        next = `${content}${sep}\n[features]\nhooks = true\n`;
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, next);
+    return { target: "codex-config.toml", path: file, status: content ? "updated" : "installed", note: "enabled [features].hooks" };
+}
+function openCodePlugin(binAbs, binName) {
+    // Fail-safe OpenCode plugin: injects the CLI's ambient snapshot as session
+    // context. Wrapped so a schema mismatch can never break OpenCode startup.
+    return [
+        `// Auto-generated by \`${binName} setup\`. Injects Oasis ambient context at session start.`,
+        `import { execFile } from "node:child_process";`,
+        ``,
+        `export const OasisAmbient = async () => {`,
+        `  const run = () => new Promise((resolve) => {`,
+        `    execFile("node", [${JSON.stringify(binAbs)}, "--ambient"], { timeout: 4000 }, (_e, out) => resolve(out || ""));`,
+        `  });`,
+        `  return {`,
+        `    // OpenCode injects the returned text into the session's system context.`,
+        `    "chat.system": async (_input, output) => {`,
+        `      try { const t = await run(); if (t.trim()) output.parts.push(t); } catch {}`,
+        `    },`,
+        `  };`,
+        `};`,
+        ``,
+    ].join("\n");
+}
+function setupOpenCode(binAbs, binName) {
+    const file = path.join(os.homedir(), ".config", "opencode", "plugin", `${binName}.js`);
+    const content = openCodePlugin(binAbs, binName);
+    let existing = "";
+    try {
+        existing = fs.readFileSync(file, "utf-8");
+    }
+    catch { /* new */ }
+    if (existing === content)
+        return { target: "opencode-plugin", path: file, status: "unchanged", note: "unverified against a live OpenCode" };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    return { target: "opencode-plugin", path: file, status: existing ? "updated" : "installed", note: "unverified against a live OpenCode" };
+}
+/**
+ * Register the `<cli> --ambient` SessionStart hook for Claude Code, Codex,
+ * and OpenCode. Idempotent and path-repairing: re-running after a reinstall
+ * updates the path. Reports every target so the agent/user can see exactly
+ * what changed (§7).
+ */
+export function runSetup(binName) {
+    const binAbs = path.resolve(process.argv[1] || binName);
+    const command = `node "${binAbs}" --ambient`;
+    const marker = path.basename(binAbs); // e.g. oasis-bitbucket.js
+    const results = [];
+    try {
+        const claudeSettings = path.join(os.homedir(), ".claude", "settings.json");
+        results.push({ target: "claude-settings.json", path: claudeSettings, status: upsertJsonHook(claudeSettings, command, marker) });
+    }
+    catch (e) {
+        results.push({ target: "claude-code", path: "~/.claude", status: "skipped", note: e instanceof Error ? e.message : String(e) });
+    }
+    try {
+        const codexHooks = path.join(os.homedir(), ".codex", "hooks.json");
+        results.push({ target: "codex-hooks.json", path: codexHooks, status: upsertJsonHook(codexHooks, command, marker) });
+        results.push(setupCodexConfig());
+    }
+    catch (e) {
+        results.push({ target: "codex", path: "~/.codex", status: "skipped", note: e instanceof Error ? e.message : String(e) });
+    }
+    try {
+        results.push(setupOpenCode(binAbs, binName));
+    }
+    catch (e) {
+        results.push({ target: "opencode", path: "~/.config/opencode", status: "skipped", note: e instanceof Error ? e.message : String(e) });
+    }
+    emit({
+        setup: binName,
+        hook: command,
+        note: "If the oasis-core Claude Code plugin is installed, its hooks.json already runs this ambient hook — remove one of the two to avoid duplication",
+        targets: results,
+        help: [
+            "Re-run this after reinstalling to repair the path",
+            "Codex also needs [features].hooks = true (set above) and a Codex restart",
+        ],
+    });
+}
+export async function runAuth(service, parsed, opts) {
+    const setHint = `${opts.binName} auth --user <u> --password <p>${opts.hasUrl ? " [--url <url>]" : ""}`;
+    if (flagBool(parsed, "--clear")) {
+        const had = !!loadCreds(service)?.username;
+        await removeCreds(service);
+        emit({ auth: service, status: had ? "cleared" : "already cleared (no-op)" });
+        return;
+    }
+    const user = flagStr(parsed, "--user");
+    const password = flagStr(parsed, "--password");
+    const url = opts.hasUrl ? flagStr(parsed, "--url") : undefined;
+    // No creds supplied → report current status.
+    if (!user && !password) {
+        const creds = loadCreds(service);
+        if (!creds?.username) {
+            emit({ auth: service, status: "not configured", help: [`Run \`${setHint}\` to sign in`] });
+            return;
+        }
+        emit({ auth: service, status: "configured", user: creds.username, server: getServiceBaseUrl(service, creds.url) });
+        return;
+    }
+    const missing = [!user && "--user", !password && "--password"].filter(Boolean);
+    if (missing.length)
+        fail(`missing required flag(s): ${missing.join(", ")}`, setHint, EXIT.USAGE);
+    const creds = { username: user, password: password, ...(url ? { url } : {}) };
+    try {
+        await opts.verify(creds);
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        fail(`${opts.label} rejected these credentials (${reason})`, `Check the username/password${opts.hasUrl ? "/url" : ""} and re-run \`${setHint}\``);
+    }
+    await saveCreds(service, creds);
+    emit({ auth: service, status: "saved", user, server: getServiceBaseUrl(service, url) });
+}
+export function flagInt(parsed, name) {
+    const v = flagStr(parsed, name);
+    if (v === undefined)
+        return undefined;
+    const n = Number.parseInt(v, 10);
+    if (!Number.isFinite(n))
+        fail(`flag ${name} expects an integer, got '${v}'`, undefined, EXIT.USAGE);
+    return n;
+}
+export function flagList(parsed, name) {
+    const v = parsed.flags[name];
+    if (v === undefined)
+        return [];
+    return Array.isArray(v) ? v : [v];
+}
+// ─── Field selection (§2 minimal schemas + --fields escape hatch) ────
+/** Parse a repeatable, comma-separated `--fields a,b --fields c` into ["a","b","c"]. */
+export function fieldList(parsed, name = "--fields") {
+    return flagList(parsed, name).flatMap(v => v.split(",")).map(s => s.trim()).filter(Boolean);
+}
+/**
+ * Resolve which columns a list view should emit. Defaults are the minimal
+ * schema; `requested` (from --fields) adds columns, validated against the full
+ * `available` set — an unknown field fails loud with the valid set (§2, §6).
+ * Output preserves `available` order for stable tables.
+ */
+export function resolveColumns(available, defaults, requested, usage) {
+    for (const f of requested) {
+        if (!available.includes(f)) {
+            fail(`unknown field '${f}' for \`${usage}\``, `available fields: ${available.join(", ")}`, EXIT.USAGE);
+        }
+    }
+    const want = new Set([...defaults, ...requested]);
+    return available.filter(f => want.has(f));
+}
+/** Project a full row down to the selected columns, preserving column order. */
+export function pick(row, cols) {
+    const out = {};
+    for (const c of cols)
+        out[c] = row[c];
+    return out;
+}
+/**
+ * Render a SKILL.md from a SkillSpec. The CLI owns the spec, so the committed
+ * skill file is generated — never hand-edited — and `build-cli.sh --check`
+ * fails CI if the committed copy drifts from this output (§7).
+ */
+export function renderSkillDoc(spec) {
+    const F = "```";
+    const bin = spec.binName;
+    const out = [];
+    out.push("---");
+    out.push(`name: ${spec.name}`);
+    out.push(`description: ${spec.description}`);
+    out.push("---");
+    out.push("");
+    out.push(`# ${bin}`);
+    out.push("");
+    out.push(spec.intro);
+    out.push(`Invoke as \`${bin}\` (on PATH after a global install; no install: \`npx -y @oasissys/${spec.name}\`). TOON output; exit 0/1/2; every command has \`--help\`.`);
+    if (spec.extra && spec.extra.length) {
+        out.push("");
+        out.push(...spec.extra);
+    }
+    out.push("");
+    out.push("## Commands");
+    out.push("");
+    out.push("| Command | What it does |");
+    out.push("|---|---|");
+    for (const c of spec.commands) {
+        out.push(`| \`${bin} ${c.cmd}\` | ${c.summary} |`);
+    }
+    out.push("");
+    out.push("## Examples");
+    out.push("");
+    out.push(F + "sh");
+    out.push(...spec.examples);
+    out.push(F);
+    if (spec.notes && spec.notes.length) {
+        out.push("");
+        out.push("## Notes");
+        for (const n of spec.notes)
+            out.push(`- ${n}`);
+    }
+    out.push("");
+    return out.join("\n");
+}
+//# sourceMappingURL=axi.js.map