kubepile 0.0.1

package/README.md

@@ -0,0 +1,87 @@
+# Kubepile
+
+Have you ever tried to maintain a Kubernetes config for multiple clusters, and
+multiple Kubernetes providers? It's gross! It's hard to visually track which
+users, clusters, and contexts relate to each other, and as you add and remove
+clusters your config inevitably bloats into a mess and becomes hard to reason
+about.
+
+![messy
+boxes](https://raw.githubusercontent.com/reissbaker/kubepile/refs/heads/main/boxes.png)
+
+Kubepile lets you maintain individual, per-provider kubeconfigs in a
+`~/.config/kubepile` directory, and compile them into a single, merged
+kubeconfig.
+
+Each `*.yaml` file is a normal kubeconfig. You can paste in kubeconfigs from
+providers without converting them to a kubepile-specific schema. During
+`compile`, kubepile reads every file and merges its `clusters`, `users`, and
+`contexts` directly into the generated kubeconfig.
+
+Kubepile automatically ensures the following:
+
+- No kubepile files set a `current-context`.
+- No cluster, user, or context names clash.
+
+If a new file is added that clashes or sets a `current-context`, kubepile will
+intentionally fail compilation with a helpful message explaining which file
+broke the kubepile rules.
+
+Kubepile will never set a `current-context`, out of the design belief that
+`current-context` is a dangerous footgun in multi-cluster setups.
+
+## Install
+
+```sh
+npm install -g kubepile
+```
+
+## Compile
+
+```sh
+kubepile compile
+```
+
+This reads `~/.config/kubepile/*.yaml`, then writes `~/.kube/config`. If
+`~/.kube/config` already exists, `kubepile compile` prompts before copying it to
+`~/.kube/config.bak`.
+
+Explicit command and options:
+
+```sh
+kubepile compile --config-dir ~/.config/kubepile --output ~/.kube/config
+kubepile compile --backup
+kubepile compile --no-backup
+```
+
+Running `kubepile` with no command prints help.
+
+## Split
+
+Do you already have a giant unmaintainable mess of a kubeconfig? No worries!
+Kubepile ships a `split` command that auto-splits your existing kubeconfig into
+separate per-context kubepile config files, and tells you on the command line
+if you have unsplittable configs due to impossible settings from config drift —
+and which keys exactly are the problem, so you can clean up your config before
+splitting it.
+
+To split your config, run:
+
+```sh
+kubepile split
+```
+
+This reads `~/.kube/config` and writes one kubeconfig per context into
+`~/.config/kubepile`.
+
+If there are errors in your kubeconfig that prevent splitting, it'll tell you
+what they are.
+
+You can optionally override the source kubeconfig and the output kubepile
+directory. These are the defaults:
+
+```sh
+kubepile split --source ~/.kube/config --output-dir ~/.config/kubepile
+```
+
+Context names that are not safe as filenames are percent-encoded when split.

package/dist/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "kubepile",
+    "version": "0.0.1",
+    "description": "Compile and split kubeconfig files from ~/.config/kubepile.",
+    "type": "module",
+    "main": "./dist/src/kubepile.js",
+    "types": "./dist/src/kubepile.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/src/kubepile.d.ts",
+            "import": "./dist/src/kubepile.js"
+        }
+    },
+    "bin": {
+        "kubepile": "./dist/src/cli.js"
+    },
+    "files": [
+        "dist/package.json",
+        "dist/src",
+        "README.md",
+        "package.json"
+    ],
+    "scripts": {
+        "clean": "rm -rf dist",
+        "build": "npm run clean && tsc",
+        "typecheck": "tsc --noEmit",
+        "test": "vitest run --dir test",
+        "prepublishOnly": "npm run typecheck && npm run build && npm test"
+    },
+    "keywords": [
+        "kubernetes",
+        "kubeconfig",
+        "kubectl"
+    ],
+    "license": "MIT",
+    "engines": {
+        "node": ">=22.12.0"
+    },
+    "dependencies": {
+        "@commander-js/extra-typings": "^15.0.0",
+        "commander": "^15.0.0",
+        "yaml": "^2.9.0"
+    },
+    "devDependencies": {
+        "@types/node": "^25.9.3",
+        "typescript": "^6.0.3",
+        "vitest": "^4.1.8"
+    }
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(argv: string[]): Promise<void>;

package/dist/src/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { createInterface } from "node:readline/promises";
+import { pathToFileURL } from "node:url";
+import { Command } from "@commander-js/extra-typings";
+import packageJson from "../package.json" with { type: "json" };
+import { compileToKubeConfig, defaultKubeConfigPath, defaultKubepileDir, splitKubeConfigFile, } from "./kubepile.js";
+export async function runCli(argv) {
+    const program = createProgram();
+    if (argv.length === 0) {
+        program.outputHelp();
+        return;
+    }
+    await program.parseAsync(argv, { from: "user" });
+}
+async function askBackup(existingPath, backupPath) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await rl.question(`Existing kubeconfig found at ${existingPath}. Back it up to ${backupPath}? [y/N] `);
+        return /^(y|yes)$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+function createProgram() {
+    const program = new Command()
+        .name("kubepile")
+        .description("Compile and split kubeconfig files.")
+        .version(packageJson.version)
+        .showHelpAfterError()
+        .allowExcessArguments(false)
+        .addHelpText("after", `
+
+Defaults:
+  config dir: ${defaultKubepileDir()}
+  kubeconfig: ${defaultKubeConfigPath()}`);
+    program
+        .command("compile")
+        .description("Compile ~/.config/kubepile/*.yaml into ~/.kube/config.")
+        .option("--config-dir <dir>", "directory containing kubeconfig YAML files")
+        .option("--input-dir <dir>", "alias for --config-dir")
+        .option("--output <file>", "output kubeconfig path")
+        .option("--backup", "back up an existing output file without prompting")
+        .option("--no-backup", "replace an existing output file without prompting")
+        .action(async (options) => {
+        const result = await compileToKubeConfig({
+            inputDir: options.configDir ?? options.inputDir,
+            outputPath: options.output,
+            shouldBackup: options.backup === undefined
+                ? askBackup
+                : () => options.backup === true,
+        });
+        if (result.backedUpTo) {
+            process.stdout.write(`Backed up existing kubeconfig to ${result.backedUpTo}\n`);
+        }
+        process.stdout.write(`Compiled ${result.inputFiles.length} kubeconfig file(s) into ${result.outputPath}\n`);
+    });
+    program
+        .command("split")
+        .description("Split an existing kubeconfig into one file per context.")
+        .option("--source <file>", "source kubeconfig path")
+        .option("--output-dir <dir>", "directory to write split kubeconfigs")
+        .action(async (options) => {
+        const result = await splitKubeConfigFile({
+            sourcePath: options.source,
+            outputDir: options.outputDir,
+        });
+        process.stdout.write(`Wrote ${result.writtenFiles.length} kubeconfig file(s) into ${result.outputDir}\n`);
+    });
+    return program;
+}
+const entryPoint = process.argv[1] ? pathToFileURL(process.argv[1]).href : undefined;
+if (import.meta.url === entryPoint) {
+    runCli(process.argv.slice(2)).catch((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`kubepile: ${message}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/src/kubepile.d.ts

@@ -0,0 +1,68 @@
+export interface NamedCluster {
+    name: string;
+    cluster: Record<string, unknown>;
+}
+export interface NamedUser {
+    name: string;
+    user: Record<string, unknown>;
+}
+export interface KubeContext {
+    cluster: string;
+    user?: string;
+    namespace?: string;
+    [key: string]: unknown;
+}
+export interface NamedContext {
+    name: string;
+    context: KubeContext;
+}
+export interface KubeConfig {
+    apiVersion?: string;
+    kind?: string;
+    preferences?: Record<string, unknown>;
+    clusters?: NamedCluster[];
+    users?: NamedUser[];
+    contexts?: NamedContext[];
+    "current-context"?: string;
+    [key: string]: unknown;
+}
+export interface CompileOptions {
+    inputDir?: string;
+}
+export interface CompileToFileOptions extends CompileOptions {
+    outputPath?: string;
+    shouldBackup?: (existingPath: string, backupPath: string) => Promise<boolean> | boolean;
+}
+export interface CompileResult {
+    config: KubeConfig;
+    inputFiles: string[];
+    outputPath: string;
+    backedUpTo?: string;
+}
+export interface SplitOptions {
+    sourcePath?: string;
+    outputDir?: string;
+}
+export interface SplitConfig {
+    contextName: string;
+    fileName: string;
+    config: KubeConfig;
+}
+export interface SplitResult {
+    outputDir: string;
+    writtenFiles: string[];
+}
+export declare function defaultKubepileDir(): string;
+export declare function defaultKubeConfigPath(): string;
+export declare function buildMergedConfig(options?: CompileOptions): Promise<{
+    config: KubeConfig;
+    inputFiles: string[];
+}>;
+export declare function compileToKubeConfig(options?: CompileToFileOptions): Promise<CompileResult>;
+export declare function splitKubeConfigFile(options?: SplitOptions): Promise<SplitResult>;
+export declare function splitKubeConfig(config: KubeConfig, sourceLabel?: string): SplitConfig[];
+export declare function readKubeConfigFile(filePath: string): Promise<KubeConfig>;
+export declare function parseKubeConfig(source: string, sourceLabel?: string): KubeConfig;
+export declare function serializeKubeConfig(config: KubeConfig): string;
+export declare function serializeGeneratedKubeConfig(config: KubeConfig, inputDir?: string): string;
+export declare function fileNameForContext(contextName: string): string;

package/dist/src/kubepile.js

@@ -0,0 +1,271 @@
+import { mkdir, readdir, readFile, stat, copyFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parse, stringify } from "yaml";
+export function defaultKubepileDir() {
+    return path.join(os.homedir(), ".config", "kubepile");
+}
+export function defaultKubeConfigPath() {
+    return path.join(os.homedir(), ".kube", "config");
+}
+export async function buildMergedConfig(options = {}) {
+    const inputDir = options.inputDir ?? defaultKubepileDir();
+    const inputFiles = await listKubeConfigFiles(inputDir);
+    const configs = await Promise.all(inputFiles.map(async (filePath) => ({
+        filePath,
+        config: await readKubeConfigFile(filePath),
+    })));
+    const seenNames = {
+        clusters: new Set(),
+        users: new Set(),
+        contexts: new Set(),
+    };
+    const merged = {
+        apiVersion: "v1",
+        kind: "Config",
+        preferences: {},
+        clusters: [],
+        users: [],
+        contexts: [],
+    };
+    for (const source of configs) {
+        appendSourceConfig(merged, source.config, source.filePath, seenNames);
+    }
+    delete merged["current-context"];
+    return { config: merged, inputFiles };
+}
+export async function compileToKubeConfig(options = {}) {
+    const inputDir = options.inputDir ?? defaultKubepileDir();
+    const outputPath = options.outputPath ?? defaultKubeConfigPath();
+    const backupPath = `${outputPath}.bak`;
+    const { config, inputFiles } = await buildMergedConfig({ ...options, inputDir });
+    let backedUpTo;
+    if (await pathExists(outputPath)) {
+        const shouldBackup = await options.shouldBackup?.(outputPath, backupPath);
+        if (shouldBackup) {
+            await mkdir(path.dirname(backupPath), { recursive: true });
+            await copyFile(outputPath, backupPath);
+            backedUpTo = backupPath;
+        }
+    }
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, serializeGeneratedKubeConfig(config, inputDir), "utf8");
+    return { config, inputFiles, outputPath, backedUpTo };
+}
+async function pathExists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function splitKubeConfigFile(options = {}) {
+    const sourcePath = options.sourcePath ?? defaultKubeConfigPath();
+    const outputDir = options.outputDir ?? defaultKubepileDir();
+    const sourceConfig = await readKubeConfigFile(sourcePath);
+    const splitConfigs = splitKubeConfig(sourceConfig, sourcePath);
+    const writtenFiles = [];
+    await mkdir(outputDir, { recursive: true });
+    for (const splitConfig of splitConfigs) {
+        const outputPath = path.join(outputDir, splitConfig.fileName);
+        await writeFile(outputPath, serializeKubeConfig(splitConfig.config), "utf8");
+        writtenFiles.push(outputPath);
+    }
+    return { outputDir, writtenFiles };
+}
+export function splitKubeConfig(config, sourceLabel = "kubeconfig") {
+    const contexts = getNamedContexts(config, sourceLabel);
+    const clusters = getNamedClusters(config, sourceLabel);
+    const users = getNamedUsers(config, sourceLabel);
+    validateAndTrackUniqueNamedEntries(clusters, "cluster", sourceLabel, new Set());
+    validateAndTrackUniqueNamedEntries(users, "user", sourceLabel, new Set());
+    validateAndTrackUniqueNamedEntries(contexts, "context", sourceLabel, new Set());
+    return contexts.map((context) => {
+        const contextName = getNonEmptyString(context.name, `${sourceLabel} context name`);
+        const contextBody = getContextBody(context, sourceLabel);
+        const clusterName = getNonEmptyString(contextBody.cluster, `${sourceLabel} context "${contextName}" cluster`);
+        const userName = getOptionalString(contextBody.user, `${sourceLabel} context "${contextName}" user`);
+        const cluster = findNamedEntry(clusters, clusterName, "cluster", sourceLabel);
+        const user = userName
+            ? findNamedEntry(users, userName, "user", sourceLabel)
+            : undefined;
+        const splitContext = deepClone(contextBody);
+        return {
+            contextName,
+            fileName: fileNameForContext(contextName),
+            config: {
+                apiVersion: "v1",
+                kind: "Config",
+                preferences: deepClone(config.preferences ?? {}),
+                clusters: [deepClone(cluster)],
+                users: user ? [deepClone(user)] : [],
+                contexts: [
+                    {
+                        name: contextName,
+                        context: splitContext,
+                    },
+                ],
+            },
+        };
+    });
+}
+export async function readKubeConfigFile(filePath) {
+    const source = await readFile(filePath, "utf8");
+    return parseKubeConfig(source, filePath);
+}
+export function parseKubeConfig(source, sourceLabel = "kubeconfig") {
+    const parsed = parse(source);
+    if (!isRecord(parsed)) {
+        throw new Error(`${sourceLabel} must be a YAML object`);
+    }
+    return parsed;
+}
+export function serializeKubeConfig(config) {
+    return stringify(config, { lineWidth: 0 });
+}
+export function serializeGeneratedKubeConfig(config, inputDir = defaultKubepileDir()) {
+    return `${generatedKubeConfigHeader(inputDir)}${serializeKubeConfig(config)}`;
+}
+export function fileNameForContext(contextName) {
+    const safeName = getNonEmptyString(contextName, "context name");
+    if (/^[A-Za-z0-9._-]+$/.test(safeName)) {
+        return `${safeName}.yaml`;
+    }
+    return `${encodeURIComponent(safeName)}.yaml`;
+}
+function generatedKubeConfigHeader(inputDir) {
+    const exampleConfigPath = path.join(inputDir, "dev.yaml");
+    const compileCommand = inputDir === defaultKubepileDir()
+        ? "kubepile compile"
+        : `kubepile compile --config-dir ${shellQuote(inputDir)}`;
+    return [
+        "# GENERATED BY KUBEPILE: DO NOT MODIFY",
+        "#",
+        "# To add a kubepile config:",
+        `# 1. Save a kubeconfig file in ${inputDir}.`,
+        `#    Example: ${exampleConfigPath}`,
+        "# 2. Rebuild this generated config with:",
+        `#    ${compileCommand}`,
+        "",
+        "",
+    ].join("\n");
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:=@%+-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+async function listKubeConfigFiles(inputDir) {
+    try {
+        const inputStat = await stat(inputDir);
+        if (!inputStat.isDirectory()) {
+            throw new Error(`Config path is not a directory: ${inputDir}`);
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Config directory does not exist: ${inputDir}`);
+        }
+        throw error;
+    }
+    const entries = await readdir(inputDir, { withFileTypes: true });
+    const unsupportedYamlFiles = entries
+        .filter((entry) => entry.isFile() && /\.ya?ml$/i.test(entry.name) && !entry.name.endsWith(".yaml"))
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+    if (unsupportedYamlFiles.length > 0) {
+        throw new Error(`Unsupported kubeconfig file extension in ${inputDir}: ${unsupportedYamlFiles.join(", ")}. Use .yaml only.`);
+    }
+    const files = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+        .map((entry) => path.join(inputDir, entry.name))
+        .sort((a, b) => a.localeCompare(b));
+    if (files.length === 0) {
+        throw new Error(`No kubeconfig files found in ${inputDir}`);
+    }
+    return files;
+}
+function appendSourceConfig(merged, sourceConfig, sourceLabel, seenNames) {
+    rejectCurrentContext(sourceConfig, sourceLabel);
+    const sourceClusters = getNamedClusters(sourceConfig, sourceLabel);
+    const sourceUsers = getNamedUsers(sourceConfig, sourceLabel);
+    const sourceContexts = getNamedContexts(sourceConfig, sourceLabel);
+    validateAndTrackUniqueNamedEntries(sourceClusters, "cluster", sourceLabel, seenNames.clusters);
+    validateAndTrackUniqueNamedEntries(sourceUsers, "user", sourceLabel, seenNames.users);
+    validateAndTrackUniqueNamedEntries(sourceContexts, "context", sourceLabel, seenNames.contexts);
+    merged.clusters?.push(...deepClone(sourceClusters));
+    merged.users?.push(...deepClone(sourceUsers));
+    merged.contexts?.push(...deepClone(sourceContexts));
+}
+function rejectCurrentContext(config, sourceLabel) {
+    if (Object.hasOwn(config, "current-context")) {
+        throw new Error(`${sourceLabel} must not set current-context`);
+    }
+}
+function getNamedClusters(config, sourceLabel) {
+    return getArray(config.clusters, `${sourceLabel} clusters`);
+}
+function getNamedUsers(config, sourceLabel) {
+    return getArray(config.users, `${sourceLabel} users`);
+}
+function getNamedContexts(config, sourceLabel) {
+    return getArray(config.contexts, `${sourceLabel} contexts`);
+}
+function getArray(value, label) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} must be an array`);
+    }
+    return value;
+}
+function validateAndTrackUniqueNamedEntries(entries, entryType, sourceLabel, seen) {
+    for (const entry of entries) {
+        const name = getNonEmptyString(entry.name, `${sourceLabel} ${entryType} name`);
+        if (seen.has(name)) {
+            throw new Error(`Duplicate ${entryType} name "${name}" found in ${sourceLabel}`);
+        }
+        seen.add(name);
+    }
+}
+function getContextBody(context, sourceLabel) {
+    if (!isRecord(context) || !isRecord(context.context)) {
+        throw new Error(`${sourceLabel} context "${String(context.name)}" must contain a context object`);
+    }
+    return context.context;
+}
+function findNamedEntry(entries, name, entryType, sourceLabel) {
+    const entry = entries.find((candidate) => candidate.name === name);
+    if (!entry) {
+        throw new Error(`${sourceLabel} references missing ${entryType} "${name}"`);
+    }
+    return entry;
+}
+function getNonEmptyString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+function getOptionalString(value, label) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${label} must be a string`);
+    }
+    return value.length > 0 ? value : undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "kubepile",
+  "version": "0.0.1",
+  "description": "Compile and split kubeconfig files from ~/.config/kubepile.",
+  "type": "module",
+  "main": "./dist/src/kubepile.js",
+  "types": "./dist/src/kubepile.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/kubepile.d.ts",
+      "import": "./dist/src/kubepile.js"
+    }
+  },
+  "bin": {
+    "kubepile": "./dist/src/cli.js"
+  },
+  "files": [
+    "dist/package.json",
+    "dist/src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --dir test",
+    "prepublishOnly": "npm run typecheck && npm run build && npm test"
+  },
+  "keywords": [
+    "kubernetes",
+    "kubeconfig",
+    "kubectl"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^15.0.0",
+    "commander": "^15.0.0",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}