@shepherdjerred/helm-types 1.1.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@shepherdjerred/helm-types",
+  "version": "1.1.0",
+  "description": "Generate TypeScript types from Helm chart values.yaml and values.schema.json",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "helm-types": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/__snapshots__"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts src/cli.ts --outdir dist --target node",
+    "generate": "bun run src/cli.ts",
+    "test": "bun test",
+    "test:helm-types": "bun test src/helm-types.test.ts",
+    "test:cli": "bun test src/cli.test.ts",
+    "lint": "bunx eslint .",
+    "lint:fix": "bunx eslint . --fix",
+    "typecheck": "bunx tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "helm",
+    "kubernetes",
+    "typescript",
+    "types",
+    "codegen",
+    "k8s"
+  ],
+  "author": "Jerred Shepherd",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shepherdjerred/homelab.git",
+    "directory": "src/helm-types"
+  },
+  "bugs": {
+    "url": "https://github.com/shepherdjerred/homelab/issues"
+  },
+  "homepage": "https://github.com/shepherdjerred/homelab/tree/main/src/helm-types#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "yaml": "^2.8.1",
+    "zod": "^4.1.11"
+  }
+}

package/src/chart-fetcher.ts

@@ -0,0 +1,150 @@
+// Using Bun.$ for path operations instead of node:path
+import { parse as yamlParse } from "yaml";
+import type { ChartInfo, JSONSchemaProperty } from "./types.js";
+import { HelmValueSchema, RecordSchema, ErrorSchema } from "./schemas.js";
+import type { HelmValue } from "./schemas.js";
+import { parseYAMLComments } from "./yaml-comments.js";
+
+/**
+ * Load JSON schema if it exists in the chart
+ */
+async function loadJSONSchema(chartPath: string): Promise<JSONSchemaProperty | null> {
+  try {
+    const schemaPath = `${chartPath}/values.schema.json`;
+    const schemaContent = await Bun.file(schemaPath).text();
+    const parsed: unknown = JSON.parse(schemaContent);
+    // Validate that parsed is an object
+    const recordCheck = RecordSchema.safeParse(parsed);
+    if (!recordCheck.success) {
+      return null;
+    }
+    // Note: JSONSchemaProperty is a structural type
+    const schema: JSONSchemaProperty = recordCheck.data;
+    console.log(`  📋 Loaded values.schema.json`);
+    return schema;
+  } catch {
+    // Schema doesn't exist or couldn't be parsed - that's okay
+    return null;
+  }
+}
+
+/**
+ * Run a command and return its output using Bun
+ */
+async function runCommand(command: string, args: string[]): Promise<string> {
+  try {
+    const proc = Bun.spawn([command, ...args], {
+      stdout: "pipe",
+      stderr: "inherit",
+    });
+
+    const output = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    if (exitCode === 0) {
+      return output;
+    } else {
+      throw new Error(`Command "${command} ${args.join(" ")}" failed with code ${exitCode.toString()}`);
+    }
+  } catch (error) {
+    const parseResult = ErrorSchema.safeParse(error);
+    const errorMessage = parseResult.success ? parseResult.data.message : String(error);
+    throw new Error(`Failed to spawn command "${command} ${args.join(" ")}": ${errorMessage}`);
+  }
+}
+
+/**
+ * Fetch a Helm chart and extract its values.yaml and optional schema
+ */
+export async function fetchHelmChart(
+  chart: ChartInfo,
+): Promise<{ values: HelmValue; schema: JSONSchemaProperty | null; yamlComments: Map<string, string> }> {
+  const pwd = Bun.env["PWD"] ?? process.cwd();
+  const tempDir = `${pwd}/temp/helm-${chart.name}`;
+  const repoName = `temp-repo-${chart.name}-${String(Date.now())}`;
+
+  try {
+    // Ensure temp directory exists
+    await Bun.$`mkdir -p ${tempDir}`.quiet();
+
+    console.log(`  📦 Adding Helm repo: ${chart.repoUrl}`);
+    // Add the helm repo
+    await runCommand("helm", ["repo", "add", repoName, chart.repoUrl]);
+
+    console.log(`  🔄 Updating Helm repos...`);
+    // Update repo
+    await runCommand("helm", ["repo", "update"]);
+
+    console.log(`  ⬇️  Pulling chart ${chart.chartName}:${chart.version}...`);
+    // Pull the chart
+    await runCommand("helm", [
+      "pull",
+      `${repoName}/${chart.chartName}`,
+      "--version",
+      chart.version,
+      "--destination",
+      tempDir,
+      "--untar",
+    ]);
+
+    // Read values.yaml
+    const valuesPath = `${tempDir}/${chart.chartName}/values.yaml`;
+    console.log(`  📖 Reading values.yaml from ${valuesPath}`);
+
+    try {
+      const valuesContent = await Bun.file(valuesPath).text();
+
+      // Parse YAML comments
+      const yamlComments = parseYAMLComments(valuesContent);
+      console.log(`  💬 Extracted ${String(yamlComments.size)} comments from values.yaml`);
+
+      // Parse YAML using yaml package
+      const parsedValues = yamlParse(valuesContent) as unknown;
+      console.log(`  ✅ Successfully parsed values.yaml`);
+      const recordParseResult = RecordSchema.safeParse(parsedValues);
+      if (recordParseResult.success) {
+        console.log(
+          `  🔍 Parsed values keys: ${Object.keys(recordParseResult.data)
+            .slice(0, 10)
+            .join(", ")}${Object.keys(recordParseResult.data).length > 10 ? "..." : ""}`,
+        );
+      }
+
+      // Check if parsedValues is a valid object using Zod before validation
+      if (!recordParseResult.success) {
+        console.warn(`  ⚠️  Parsed values is not a valid record object: ${String(parsedValues)}`);
+        return { values: {}, schema: null, yamlComments: new Map() };
+      }
+
+      // Validate and parse with Zod for runtime type safety
+      const parseResult = HelmValueSchema.safeParse(recordParseResult.data);
+
+      // Try to load JSON schema
+      const chartPath = `${tempDir}/${chart.chartName}`;
+      const schema = await loadJSONSchema(chartPath);
+
+      if (parseResult.success) {
+        console.log(`  ✅ Zod validation successful`);
+        return { values: parseResult.data, schema, yamlComments };
+      } else {
+        console.warn(`  ⚠️  Zod validation failed for ${chart.name}:`);
+        console.warn(`    First few errors:`, parseResult.error.issues.slice(0, 3));
+        console.warn(`  ⚠️  Falling back to unvalidated object for type generation`);
+        // Return the validated record data from the successful parse result
+        return { values: recordParseResult.data, schema, yamlComments };
+      }
+    } catch (error) {
+      console.warn(`  ⚠️  Failed to read/parse values.yaml: ${String(error)}`);
+      return { values: {}, schema: null, yamlComments: new Map() };
+    }
+  } finally {
+    // Cleanup
+    try {
+      console.log(`  🧹 Cleaning up...`);
+      await runCommand("helm", ["repo", "remove", repoName]);
+      await Bun.$`rm -rf ${tempDir}`.quiet();
+    } catch (cleanupError) {
+      console.warn(`Cleanup failed for ${chart.name}:`, String(cleanupError));
+    }
+  }
+}

package/src/chart-info-parser.ts

@@ -0,0 +1,52 @@
+import type { ChartInfo } from "./types.js";
+
+/**
+ * Parse chart information from versions.ts comments and values
+ */
+export async function parseChartInfoFromVersions(versionsPath = "src/versions.ts"): Promise<ChartInfo[]> {
+  const content = await Bun.file(versionsPath).text();
+  const lines = content.split("\n");
+  const charts: ChartInfo[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const nextLine = lines[i + 1];
+
+    // Look for renovate comments that indicate Helm charts
+    if (line?.includes("renovate: datasource=helm") && nextLine) {
+      const repoUrlMatch = /registryUrl=([^\s]+)/.exec(line);
+      const versionKeyMatch = /^\s*"?([^":]+)"?:/.exec(nextLine);
+
+      if (repoUrlMatch && versionKeyMatch) {
+        const repoUrl = repoUrlMatch[1];
+        const versionKey = versionKeyMatch[1];
+
+        if (!repoUrl || !versionKey) continue;
+
+        // Extract version value
+        const versionMatch = /:\s*"([^"]+)"/.exec(nextLine);
+        if (versionMatch) {
+          const version = versionMatch[1];
+          if (!version) continue;
+
+          // Try to determine chart name from the version key or URL
+          let chartName = versionKey;
+
+          // Handle special cases like "argo-cd" vs "argocd"
+          if (versionKey === "argo-cd") {
+            chartName = "argo-cd";
+          }
+
+          charts.push({
+            name: versionKey,
+            repoUrl: repoUrl.replace(/\/$/, ""), // Remove trailing slash
+            version,
+            chartName,
+          });
+        }
+      }
+    }
+  }
+
+  return charts;
+}

package/src/cli.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env bun
+/**
+ * CLI for @homelab/helm-types
+ *
+ * Generate TypeScript types from Helm charts
+ */
+import { z } from "zod";
+import { fetchHelmChart, convertToTypeScriptInterface, generateTypeScriptCode } from "./helm-types.ts";
+import type { ChartInfo } from "./helm-types.ts";
+
+const ErrorSchema = z.object({
+  message: z.string(),
+});
+
+const HELP_TEXT = `
+helm-types - Generate TypeScript types from Helm charts
+
+USAGE:
+  bunx @homelab/helm-types [options]
+
+OPTIONS:
+  --name, -n          Unique identifier for the chart (required)
+  --chart, -c         Chart name in the repository (defaults to --name)
+  --repo, -r          Helm repository URL (required)
+  --version, -v       Chart version (required)
+  --output, -o        Output file path (defaults to stdout)
+  --interface, -i     Interface name (auto-generated from chart name if not provided)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Generate types for ArgoCD and print to stdout
+  bunx @homelab/helm-types \\
+    --name argo-cd \\
+    --repo https://argoproj.github.io/argo-helm \\
+    --version 8.3.1
+
+  # Generate types with custom output file
+  bunx @homelab/helm-types \\
+    --name argo-cd \\
+    --repo https://argoproj.github.io/argo-helm \\
+    --version 8.3.1 \\
+    --output argo-cd.types.ts
+
+  # Generate types with custom chart name and interface name
+  bunx @homelab/helm-types \\
+    --name argocd \\
+    --chart argo-cd \\
+    --repo https://argoproj.github.io/argo-helm \\
+    --version 8.3.1 \\
+    --interface ArgocdHelmValues \\
+    --output argocd.types.ts
+`;
+
+type CliArgs = {
+  name?: string;
+  chart?: string;
+  repo?: string;
+  version?: string;
+  output?: string;
+  interface?: string;
+  help?: boolean;
+};
+
+/**
+ * Simple argument parser for Bun CLI
+ */
+function parseCliArgs(args: string[]): CliArgs {
+  const result: CliArgs = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+    } else if (arg === "--name" || arg === "-n") {
+      const value = args[i + 1];
+      if (value) {
+        result.name = value;
+        i += 1;
+      }
+    } else if (arg === "--chart" || arg === "-c") {
+      const value = args[i + 1];
+      if (value) {
+        result.chart = value;
+        i += 1;
+      }
+    } else if (arg === "--repo" || arg === "-r") {
+      const value = args[i + 1];
+      if (value) {
+        result.repo = value;
+        i += 1;
+      }
+    } else if (arg === "--version" || arg === "-v") {
+      const value = args[i + 1];
+      if (value) {
+        result.version = value;
+        i += 1;
+      }
+    } else if (arg === "--output" || arg === "-o") {
+      const value = args[i + 1];
+      if (value) {
+        result.output = value;
+        i += 1;
+      }
+    } else if (arg === "--interface" || arg === "-i") {
+      const value = args[i + 1];
+      if (value) {
+        result.interface = value;
+        i += 1;
+      }
+    } else if (arg.startsWith("-")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return result;
+}
+
+async function main() {
+  try {
+    const args = parseCliArgs(Bun.argv.slice(2));
+
+    // Show help
+    if (args.help) {
+      console.log(HELP_TEXT);
+      process.exit(0);
+    }
+
+    // Validate required arguments
+    if (!args.name || !args.repo || !args.version) {
+      console.error("Error: Missing required arguments");
+      console.error("Required: --name, --repo, --version");
+      console.error("\nRun with --help for usage information");
+      process.exit(1);
+    }
+
+    // Build chart info
+    const chartInfo: ChartInfo = {
+      name: args.name,
+      chartName: args.chart ?? args.name,
+      repoUrl: args.repo,
+      version: args.version,
+    };
+
+    // Generate interface name from chart name if not provided
+    const interfaceName = args.interface ?? `${toPascalCase(args.name)}HelmValues`;
+
+    console.error(`Fetching chart: ${chartInfo.chartName}@${chartInfo.version}`);
+    console.error(`Repository: ${chartInfo.repoUrl}`);
+    console.error("");
+
+    // Fetch chart
+    const { values, schema, yamlComments } = await fetchHelmChart(chartInfo);
+
+    console.error("");
+    console.error(`Converting to TypeScript interface: ${interfaceName}`);
+
+    // Convert to TypeScript interface
+    const tsInterface = convertToTypeScriptInterface(values, interfaceName, schema, yamlComments, "", args.name);
+
+    // Generate TypeScript code
+    const code = generateTypeScriptCode(tsInterface, args.name);
+
+    // Write to file or stdout
+    if (args.output) {
+      await Bun.write(args.output, code);
+      console.error("");
+      console.error(`✅ Types written to: ${args.output}`);
+    } else {
+      // Write to stdout (so it can be piped)
+      console.log(code);
+    }
+
+    process.exit(0);
+  } catch (error) {
+    const parseResult = ErrorSchema.safeParse(error);
+    if (parseResult.success) {
+      console.error(`Error: ${parseResult.data.message}`);
+    } else {
+      console.error(`Error: ${String(error)}`);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Convert a string to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split(/[-_\s]+/)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join("");
+}
+
+void main();

package/src/code-generator.ts

@@ -0,0 +1,191 @@
+import type { TypeScriptInterface } from "./types.js";
+import { StringSchema, ArraySchema, RecordSchema, ActualNumberSchema, ActualBooleanSchema } from "./schemas.js";
+import { capitalizeFirst } from "./utils.js";
+
+/**
+ * Generate TypeScript code from interface definition
+ */
+export function generateTypeScriptCode(mainInterface: TypeScriptInterface, chartName: string): string {
+  const interfaces: TypeScriptInterface[] = [];
+
+  // Collect all nested interfaces
+  collectNestedInterfaces(mainInterface, interfaces);
+
+  let code = `// Generated TypeScript types for ${chartName} Helm chart\n\n`;
+
+  // Generate all interfaces
+  for (const iface of interfaces) {
+    code += generateInterfaceCode(iface);
+    code += "\n";
+  }
+
+  // Generate parameter type (flattened dot notation)
+  code += generateParameterType(mainInterface, chartName);
+
+  // Check if any 'any' types were generated and add ESLint disable if needed
+  if (code.includes(": any")) {
+    code = `// Generated TypeScript types for ${chartName} Helm chart
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+${code.substring(code.indexOf("\n\n") + 2)}`;
+  }
+
+  return code;
+}
+
+function collectNestedInterfaces(iface: TypeScriptInterface, collected: TypeScriptInterface[]): void {
+  for (const prop of Object.values(iface.properties)) {
+    if (prop.nested) {
+      collected.push(prop.nested);
+      collectNestedInterfaces(prop.nested, collected);
+    }
+  }
+
+  // Add main interface last so dependencies come first
+  if (!collected.some((i) => i.name === iface.name)) {
+    collected.push(iface);
+  }
+}
+
+function generateInterfaceCode(iface: TypeScriptInterface): string {
+  const hasProperties = Object.keys(iface.properties).length > 0;
+
+  if (!hasProperties) {
+    // Use 'object' for empty interfaces instead of '{}'
+    return `export type ${iface.name} = object;\n`;
+  }
+
+  let code = `export type ${iface.name} = {\n`;
+
+  for (const [key, prop] of Object.entries(iface.properties)) {
+    const optional = prop.optional ? "?" : "";
+
+    // Generate JSDoc comment if we have description or default
+    if (prop.description || prop.default !== undefined) {
+      code += `  /**\n`;
+
+      if (prop.description) {
+        // Format multi-line descriptions properly with " * " prefix
+        // Escape */ sequences to prevent premature comment closure
+        const escapedDescription = prop.description.replace(/\*\//g, "*\\/");
+        const descLines = escapedDescription.split("\n");
+        for (const line of descLines) {
+          code += `   * ${line}\n`;
+        }
+      }
+
+      if (prop.default !== undefined) {
+        const defaultStr = formatDefaultValue(prop.default);
+        if (defaultStr) {
+          if (prop.description) code += `   *\n`;
+          code += `   * @default ${defaultStr}\n`;
+        }
+      }
+
+      code += `   */\n`;
+    }
+
+    code += `  ${key}${optional}: ${prop.type};\n`;
+  }
+
+  code += "};\n";
+  return code;
+}
+
+/**
+ * Format a default value for display in JSDoc
+ */
+function formatDefaultValue(value: unknown): string | null {
+  if (value === null) return "null";
+  if (value === undefined) return null;
+
+  // Handle arrays
+  const arrayCheck = ArraySchema.safeParse(value);
+  if (arrayCheck.success) {
+    if (arrayCheck.data.length === 0) return "[]";
+    if (arrayCheck.data.length <= 3) {
+      try {
+        return JSON.stringify(arrayCheck.data);
+      } catch {
+        return "[...]";
+      }
+    }
+    return `[...] (${String(arrayCheck.data.length)} items)`;
+  }
+
+  // Handle objects
+  const recordCheck = RecordSchema.safeParse(value);
+  if (recordCheck.success) {
+    const keys = Object.keys(recordCheck.data);
+    if (keys.length === 0) return "{}";
+    if (keys.length <= 3) {
+      try {
+        return JSON.stringify(recordCheck.data);
+      } catch {
+        return "{...}";
+      }
+    }
+    return `{...} (${String(keys.length)} keys)`;
+  }
+
+  // Primitives
+  const stringCheck = StringSchema.safeParse(value);
+  if (stringCheck.success) {
+    // Truncate long strings
+    if (stringCheck.data.length > 50) {
+      return `"${stringCheck.data.substring(0, 47)}..."`;
+    }
+    return `"${stringCheck.data}"`;
+  }
+
+  // Handle other primitives (numbers, booleans, etc.)
+  const numberCheck = ActualNumberSchema.safeParse(value);
+  if (numberCheck.success) {
+    return String(numberCheck.data);
+  }
+
+  const booleanCheck = ActualBooleanSchema.safeParse(value);
+  if (booleanCheck.success) {
+    return String(booleanCheck.data);
+  }
+
+  // Fallback for unknown types - try JSON.stringify
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "unknown";
+  }
+}
+
+function generateParameterType(iface: TypeScriptInterface, chartName: string): string {
+  const parameterKeys = flattenInterfaceKeys(iface);
+
+  const normalizedChartName = capitalizeFirst(chartName).replace(/-/g, "");
+  let code = `export type ${normalizedChartName}HelmParameters = {\n`;
+
+  for (const key of parameterKeys) {
+    code += `  "${key}"?: string;\n`;
+  }
+
+  code += "};\n";
+
+  return code;
+}
+
+function flattenInterfaceKeys(iface: TypeScriptInterface, prefix = ""): string[] {
+  const keys: string[] = [];
+
+  for (const [key, prop] of Object.entries(iface.properties)) {
+    // Remove quotes from key for parameter names
+    const cleanKey = key.replace(/"/g, "");
+    const fullKey = prefix ? `${prefix}.${cleanKey}` : cleanKey;
+
+    if (prop.nested) {
+      keys.push(...flattenInterfaceKeys(prop.nested, fullKey));
+    } else {
+      keys.push(fullKey);
+    }
+  }
+
+  return keys;
+}