@kustodian/generator 1.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kustodian/generator",
+  "version": "1.0.0",
+  "description": "Template processing and Flux generation for Kustodian",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "bun run tsc --noEmit"
+  },
+  "keywords": [
+    "kustodian",
+    "generator",
+    "flux"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "packages/generator"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "workspace:*",
+    "@kustodian/loader": "workspace:*",
+    "@kustodian/plugins": "workspace:*",
+    "@kustodian/schema": "workspace:*",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {}
+}

package/src/external-substitutions.ts

@@ -0,0 +1,71 @@
+import type {
+  DopplerSubstitutionType,
+  OnePasswordSubstitutionType,
+  SubstitutionType,
+  TemplateType,
+} from '@kustodian/schema';
+import {
+  is_doppler_substitution,
+  is_onepassword_substitution,
+} from '@kustodian/schema';
+
+/**
+ * Extracts 1Password substitutions from templates.
+ */
+export function extract_onepassword_substitutions(
+  templates: TemplateType[],
+): OnePasswordSubstitutionType[] {
+  const substitutions: OnePasswordSubstitutionType[] = [];
+
+  for (const template of templates) {
+    for (const kustomization of template.spec.kustomizations) {
+      for (const sub of kustomization.substitutions ?? []) {
+        if (is_onepassword_substitution(sub)) {
+          substitutions.push(sub);
+        }
+      }
+    }
+  }
+
+  return substitutions;
+}
+
+/**
+ * Extracts Doppler substitutions from templates.
+ */
+export function extract_doppler_substitutions(
+  templates: TemplateType[],
+): DopplerSubstitutionType[] {
+  const substitutions: DopplerSubstitutionType[] = [];
+
+  for (const template of templates) {
+    for (const kustomization of template.spec.kustomizations) {
+      for (const sub of kustomization.substitutions ?? []) {
+        if (is_doppler_substitution(sub)) {
+          substitutions.push(sub);
+        }
+      }
+    }
+  }
+
+  return substitutions;
+}
+
+/**
+ * Extracts all external substitutions (1Password and Doppler) from templates.
+ */
+export function extract_external_substitutions(
+  templates: TemplateType[],
+): { onepassword: OnePasswordSubstitutionType[]; doppler: DopplerSubstitutionType[] } {
+  return {
+    onepassword: extract_onepassword_substitutions(templates),
+    doppler: extract_doppler_substitutions(templates),
+  };
+}
+
+/**
+ * Checks if a substitution requires external resolution.
+ */
+export function is_external_substitution(sub: SubstitutionType): boolean {
+  return is_onepassword_substitution(sub) || is_doppler_substitution(sub);
+}

package/src/flux.ts

@@ -0,0 +1,233 @@
+import type {
+  ClusterType,
+  KustomizationType,
+  OciConfigType,
+  TemplateType,
+} from '@kustodian/schema';
+
+import type {
+  FluxKustomizationType,
+  FluxOCIRepositoryType,
+  ResolvedKustomizationType,
+} from './types.js';
+import { is_parse_error, parse_dependency_ref } from './validation/reference.js';
+
+/**
+ * Default interval for Flux reconciliation.
+ */
+export const DEFAULT_INTERVAL = '10m';
+
+/**
+ * Default timeout for Flux reconciliation.
+ */
+export const DEFAULT_TIMEOUT = '5m';
+
+/**
+ * Generates a Flux Kustomization name from template and kustomization.
+ */
+export function generate_flux_name(template_name: string, kustomization_name: string): string {
+  return `${template_name}-${kustomization_name}`;
+}
+
+/**
+ * Generates the path for a Flux Kustomization.
+ */
+export function generate_flux_path(
+  template_name: string,
+  kustomization_path: string,
+  base_path = './templates',
+): string {
+  // Normalize the path
+  const normalized = kustomization_path.replace(/^\.\//, '');
+  return `${base_path}/${template_name}/${normalized}`;
+}
+
+/**
+ * Generates the dependency references for a Flux Kustomization.
+ *
+ * Supports both within-template and cross-template references:
+ * - Within-template: `database` → uses current template name
+ * - Cross-template: `secrets/doppler` → uses explicit template name
+ */
+export function generate_depends_on(
+  template_name: string,
+  depends_on: string[] | undefined,
+): Array<{ name: string }> | undefined {
+  if (!depends_on || depends_on.length === 0) {
+    return undefined;
+  }
+
+  return depends_on.map((dep) => {
+    const parsed = parse_dependency_ref(dep);
+    if (is_parse_error(parsed)) {
+      // Invalid references are caught during validation, fall back to current behavior
+      return { name: generate_flux_name(template_name, dep) };
+    }
+    const effective_template = parsed.template ?? template_name;
+    return { name: generate_flux_name(effective_template, parsed.kustomization) };
+  });
+}
+
+/**
+ * Generates health checks for a Flux Kustomization.
+ */
+export function generate_health_checks(
+  kustomization: KustomizationType,
+  namespace: string,
+): FluxKustomizationType['spec']['healthChecks'] {
+  if (!kustomization.health_checks || kustomization.health_checks.length === 0) {
+    return undefined;
+  }
+
+  return kustomization.health_checks.map((check) => ({
+    apiVersion: 'apps/v1',
+    kind: check.kind,
+    name: check.name,
+    namespace: check.namespace ?? namespace,
+  }));
+}
+
+/**
+ * Generates a Flux OCIRepository resource.
+ */
+export function generate_flux_oci_repository(
+  cluster: ClusterType,
+  oci_config: OciConfigType,
+  repository_name: string,
+  flux_namespace: string,
+): FluxOCIRepositoryType {
+  const url = `oci://${oci_config.registry}/${oci_config.repository}`;
+
+  const ref: FluxOCIRepositoryType['spec']['ref'] = {};
+  switch (oci_config.tag_strategy) {
+    case 'cluster':
+      ref.tag = cluster.metadata.name;
+      break;
+    case 'manual':
+      ref.tag = oci_config.tag || 'latest';
+      break;
+    default:
+      ref.tag = 'latest'; // CI will update this
+  }
+
+  const spec: FluxOCIRepositoryType['spec'] = {
+    interval: DEFAULT_INTERVAL,
+    url,
+    ref,
+    provider: oci_config.provider || 'generic',
+  };
+
+  if (oci_config.secret_ref) {
+    spec.secretRef = { name: oci_config.secret_ref };
+  }
+
+  if (oci_config.insecure) {
+    spec.insecure = true;
+  }
+
+  return {
+    apiVersion: 'source.toolkit.fluxcd.io/v1',
+    kind: 'OCIRepository',
+    metadata: {
+      name: repository_name,
+      namespace: flux_namespace,
+    },
+    spec,
+  };
+}
+
+/**
+ * Generates a Flux Kustomization resource.
+ */
+export function generate_flux_kustomization(
+  resolved: ResolvedKustomizationType,
+  source_repository_name = 'flux-system',
+  source_kind: 'GitRepository' | 'OCIRepository' = 'GitRepository',
+): FluxKustomizationType {
+  const { template, kustomization, values, namespace } = resolved;
+  const name = generate_flux_name(template.metadata.name, kustomization.name);
+  const path = generate_flux_path(template.metadata.name, kustomization.path);
+
+  const spec: FluxKustomizationType['spec'] = {
+    interval: DEFAULT_INTERVAL,
+    targetNamespace: namespace,
+    path,
+    prune: kustomization.prune ?? true,
+    wait: kustomization.wait ?? true,
+    sourceRef: {
+      kind: source_kind,
+      name: source_repository_name,
+    },
+  };
+
+  // Add timeout if specified
+  if (kustomization.timeout) {
+    spec.timeout = kustomization.timeout;
+  } else {
+    spec.timeout = DEFAULT_TIMEOUT;
+  }
+
+  // Add retry interval if specified
+  if (kustomization.retry_interval) {
+    spec.retryInterval = kustomization.retry_interval;
+  }
+
+  // Add dependencies
+  const depends_on = generate_depends_on(template.metadata.name, kustomization.depends_on);
+  if (depends_on) {
+    spec.dependsOn = depends_on;
+  }
+
+  // Add substitutions if there are values
+  if (Object.keys(values).length > 0) {
+    spec.postBuild = {
+      substitute: values,
+    };
+  }
+
+  // Add health checks
+  const health_checks = generate_health_checks(kustomization, namespace);
+  if (health_checks) {
+    spec.healthChecks = health_checks;
+  }
+
+  return {
+    apiVersion: 'kustomize.toolkit.fluxcd.io/v1',
+    kind: 'Kustomization',
+    metadata: {
+      name,
+      namespace: 'flux-system',
+    },
+    spec,
+  };
+}
+
+/**
+ * Resolves a kustomization with values from the cluster config.
+ */
+export function resolve_kustomization(
+  template: TemplateType,
+  kustomization: KustomizationType,
+  cluster_values: Record<string, string> = {},
+): ResolvedKustomizationType {
+  // Collect values with defaults
+  const values: Record<string, string> = {};
+
+  for (const sub of kustomization.substitutions ?? []) {
+    // Check cluster-provided value first, then fall back to default
+    const value = cluster_values[sub.name] ?? sub.default;
+    if (value !== undefined) {
+      values[sub.name] = value;
+    }
+  }
+
+  // Determine namespace
+  const namespace = kustomization.namespace?.default ?? 'default';
+
+  return {
+    template,
+    kustomization,
+    values,
+    namespace,
+  };
+}

package/src/generator.ts

@@ -0,0 +1,311 @@
+import { type ResultType, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import type {
+  GeneratedResourceType,
+  LegacyPluginRegistryType,
+  PluginContextType,
+} from '@kustodian/plugins';
+import type { ClusterType, TemplateConfigType, TemplateType } from '@kustodian/schema';
+
+import {
+  DEFAULT_INTERVAL,
+  DEFAULT_TIMEOUT,
+  generate_depends_on,
+  generate_flux_kustomization,
+  generate_flux_name,
+  generate_flux_oci_repository,
+  generate_health_checks,
+  resolve_kustomization,
+} from './flux.js';
+import { generate_namespace_resources } from './namespace.js';
+import { serialize_resource, serialize_resources, write_generation_result } from './output.js';
+import type {
+  FluxKustomizationType,
+  GenerateOptionsType,
+  GeneratedKustomizationType,
+  GenerationResultType,
+  ResolvedKustomizationType,
+  ResolvedTemplateType,
+} from './types.js';
+import { validate_dependencies } from './validation/index.js';
+
+/**
+ * Options for the Generator.
+ */
+export interface GeneratorOptionsType {
+  flux_namespace?: string;
+  git_repository_name?: string;
+  base_path?: string;
+}
+
+/**
+ * Generator hook phases.
+ */
+export type GeneratorHookPhaseType =
+  | 'before_generate'
+  | 'after_resolve_template'
+  | 'after_generate_kustomization'
+  | 'after_generate';
+
+/**
+ * Hook handler function type.
+ */
+export type GeneratorHookHandlerType = (
+  phase: GeneratorHookPhaseType,
+  context: GeneratorHookContextType,
+) => void | Promise<void>;
+
+/**
+ * Context passed to generator hooks.
+ */
+export interface GeneratorHookContextType {
+  cluster: ClusterType;
+  templates?: ResolvedTemplateType[];
+  kustomization?: ResolvedKustomizationType;
+  flux_kustomization?: FluxKustomizationType;
+  result?: GenerationResultType;
+}
+
+/**
+ * Generator class for processing templates into Flux resources.
+ */
+export interface GeneratorType {
+  /**
+   * Registers a hook handler.
+   */
+  on_hook(handler: GeneratorHookHandlerType): void;
+
+  /**
+   * Resolves templates for a cluster.
+   */
+  resolve_templates(cluster: ClusterType, templates: TemplateType[]): ResolvedTemplateType[];
+
+  /**
+   * Generates Flux resources for a cluster.
+   */
+  generate(
+    cluster: ClusterType,
+    templates: TemplateType[],
+    options?: GenerateOptionsType,
+  ): Promise<ResultType<GenerationResultType, KustodianErrorType>>;
+
+  /**
+   * Generates resources from plugins.
+   */
+  generate_plugin_resources(
+    cluster: ClusterType,
+    templates: ResolvedTemplateType[],
+  ): ResultType<GeneratedResourceType[], KustodianErrorType>;
+
+  /**
+   * Writes generation result to disk.
+   */
+  write(result: GenerationResultType): Promise<ResultType<string[], KustodianErrorType>>;
+}
+
+/**
+ * Creates a new Generator instance.
+ */
+export function create_generator(
+  options: GeneratorOptionsType = {},
+  registry?: LegacyPluginRegistryType,
+): GeneratorType {
+  const flux_namespace = options.flux_namespace ?? 'flux-system';
+  const git_repository_name = options.git_repository_name ?? 'flux-system';
+  // base_path is available for future template path customization
+  const _base_path = options.base_path ?? './templates';
+  void _base_path; // Suppress unused variable warning
+
+  const hooks: GeneratorHookHandlerType[] = [];
+
+  async function run_hooks(
+    phase: GeneratorHookPhaseType,
+    context: GeneratorHookContextType,
+  ): Promise<void> {
+    for (const handler of hooks) {
+      await handler(phase, context);
+    }
+  }
+
+  function get_template_values(
+    cluster: ClusterType,
+    template_name: string,
+  ): Record<string, string> {
+    const template_config = cluster.spec.templates?.find(
+      (t: TemplateConfigType) => t.name === template_name,
+    );
+    return template_config?.values ?? {};
+  }
+
+  function is_template_enabled(cluster: ClusterType, template_name: string): boolean {
+    const template_config = cluster.spec.templates?.find(
+      (t: TemplateConfigType) => t.name === template_name,
+    );
+    // Default to enabled if not specified
+    return template_config?.enabled ?? true;
+  }
+
+  return {
+    on_hook(handler) {
+      hooks.push(handler);
+    },
+
+    resolve_templates(cluster, templates) {
+      return templates.map((template) => {
+        const values = get_template_values(cluster, template.metadata.name);
+        const enabled = is_template_enabled(cluster, template.metadata.name);
+
+        return {
+          template,
+          values,
+          enabled,
+        };
+      });
+    },
+
+    async generate(cluster, templates, generate_options = {}) {
+      const output_dir = generate_options.output_dir ?? './output';
+      const skip_validation = generate_options.skip_validation ?? false;
+
+      // Validate dependency graph before generation (unless skipped)
+      if (!skip_validation) {
+        const validation_result = validate_dependencies(templates);
+        if (!validation_result.success) {
+          return validation_result;
+        }
+      }
+
+      // Detect source kind and repository name
+      const source_kind = cluster.spec.oci ? 'OCIRepository' : 'GitRepository';
+      const source_repository_name = git_repository_name;
+
+      // Run before_generate hook
+      await run_hooks('before_generate', { cluster });
+
+      // Resolve templates
+      const resolved_templates = this.resolve_templates(cluster, templates);
+
+      // Run after_resolve_template hook for each
+      for (const resolved of resolved_templates) {
+        await run_hooks('after_resolve_template', {
+          cluster,
+          templates: [resolved],
+        });
+      }
+
+      // Generate kustomizations
+      const generated_kustomizations: GeneratedKustomizationType[] = [];
+
+      for (const resolved of resolved_templates) {
+        if (!resolved.enabled) {
+          continue;
+        }
+
+        for (const kustomization of resolved.template.spec.kustomizations) {
+          const resolved_kustomization = resolve_kustomization(
+            resolved.template,
+            kustomization,
+            resolved.values,
+          );
+
+          // Generate Flux resource with configurable namespace
+          const flux_kustomization = generate_flux_kustomization(
+            resolved_kustomization,
+            source_repository_name,
+            source_kind,
+          );
+
+          // Override namespace to configured value
+          flux_kustomization.metadata.namespace = flux_namespace;
+
+          // Run after_generate_kustomization hook
+          await run_hooks('after_generate_kustomization', {
+            cluster,
+            kustomization: resolved_kustomization,
+            flux_kustomization,
+          });
+
+          generated_kustomizations.push({
+            name: flux_kustomization.metadata.name,
+            template: resolved.template.metadata.name,
+            path: flux_kustomization.spec.path,
+            flux_kustomization,
+          });
+        }
+      }
+
+      const result: GenerationResultType = {
+        cluster: cluster.metadata.name,
+        output_dir,
+        kustomizations: generated_kustomizations,
+      };
+
+      // Generate OCIRepository if using OCI mode
+      if (cluster.spec.oci) {
+        result.oci_repository = generate_flux_oci_repository(
+          cluster,
+          cluster.spec.oci,
+          source_repository_name,
+          flux_namespace,
+        );
+      }
+
+      // Run after_generate hook
+      await run_hooks('after_generate', {
+        cluster,
+        templates: resolved_templates,
+        result,
+      });
+
+      return success(result);
+    },
+
+    generate_plugin_resources(cluster, templates) {
+      if (!registry) {
+        return success([]);
+      }
+
+      const all_resources: GeneratedResourceType[] = [];
+
+      // Generate resources from plugins
+      for (const generator of registry.get_resource_generators()) {
+        for (const resolved of templates) {
+          if (!resolved.enabled) {
+            continue;
+          }
+
+          const ctx: PluginContextType = {
+            cluster,
+            template: resolved.template,
+          };
+
+          const result = generator.generate(ctx);
+          if (!result.success) {
+            return result;
+          }
+
+          all_resources.push(...result.value);
+        }
+      }
+
+      return success(all_resources);
+    },
+
+    async write(result) {
+      return write_generation_result(result);
+    },
+  };
+}
+
+// Re-export commonly used utilities
+export { serialize_resource, serialize_resources };
+export { generate_namespace_resources };
+export {
+  DEFAULT_INTERVAL,
+  DEFAULT_TIMEOUT,
+  generate_depends_on,
+  generate_flux_kustomization,
+  generate_flux_name,
+  generate_health_checks,
+  resolve_kustomization,
+};

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './flux.js';
+export * from './substitution.js';
+export * from './namespace.js';
+export * from './output.js';
+export * from './generator.js';
+export * from './validation/index.js';
+export * from './external-substitutions.js';