@kustodian/generator 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kustodian/generator",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Template processing and Flux generation for Kustodian",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,10 +35,10 @@
     "registry": "https://npm.pkg.github.com"
   },
   "dependencies": {
-    "@kustodian/core": "workspace:*",
-    "@kustodian/loader": "workspace:*",
-    "@kustodian/plugins": "workspace:*",
-    "@kustodian/schema": "workspace:*",
+    "@kustodian/core": "1.1.0",
+    "@kustodian/loader": "1.1.0",
+    "@kustodian/plugins": "1.0.1",
+    "@kustodian/schema": "1.3.0",
     "yaml": "^2.8.2"
   },
   "devDependencies": {}

package/src/flux.ts

@@ -2,15 +2,19 @@ import type {
   ClusterType,
   KustomizationType,
   OciConfigType,
+  PreservationPolicyType,
+  DependencyRefType as SchemaDependencyRefType,
   TemplateType,
 } from '@kustodian/schema';
 
+import { generate_preservation_patches, get_preserved_resource_types } from './preservation.js';
 import type {
   FluxKustomizationType,
   FluxOCIRepositoryType,
   ResolvedKustomizationType,
 } from './types.js';
 import { is_parse_error, parse_dependency_ref } from './validation/reference.js';
+import { is_raw_dependency_ref } from './validation/types.js';
 
 /**
  * Default interval for Flux reconciliation.
@@ -45,14 +49,15 @@ export function generate_flux_path(
 /**
  * Generates the dependency references for a Flux Kustomization.
  *
- * Supports both within-template and cross-template references:
+ * Supports three formats:
  * - Within-template: `database` → uses current template name
  * - Cross-template: `secrets/doppler` → uses explicit template name
+ * - Raw external: `{ raw: { name: 'legacy-infrastructure', namespace: 'gitops-system' } }`
  */
 export function generate_depends_on(
   template_name: string,
-  depends_on: string[] | undefined,
-): Array<{ name: string }> | undefined {
+  depends_on: SchemaDependencyRefType[] | undefined,
+): Array<{ name: string; namespace?: string }> | undefined {
   if (!depends_on || depends_on.length === 0) {
     return undefined;
   }
@@ -61,8 +66,23 @@ export function generate_depends_on(
     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) };
+      // This should only happen with string refs
+      if (typeof dep === 'string') {
+        return { name: generate_flux_name(template_name, dep) };
+      }
+      // If somehow we have an invalid object ref, use a placeholder
+      return { name: 'invalid-reference' };
     }
+
+    // Handle raw dependencies - pass through name and namespace directly
+    if (is_raw_dependency_ref(parsed)) {
+      return {
+        name: parsed.name,
+        namespace: parsed.namespace,
+      };
+    }
+
+    // Handle string-based dependencies (within-template and cross-template)
     const effective_template = parsed.template ?? template_name;
     return { name: generate_flux_name(effective_template, parsed.kustomization) };
   });
@@ -80,13 +100,49 @@ export function generate_health_checks(
   }
 
   return kustomization.health_checks.map((check) => ({
-    apiVersion: 'apps/v1',
+    apiVersion: check.api_version ?? 'apps/v1',
     kind: check.kind,
     name: check.name,
     namespace: check.namespace ?? namespace,
   }));
 }
 
+/**
+ * Generates custom health checks with CEL expressions for a Flux Kustomization.
+ */
+export function generate_custom_health_checks(
+  kustomization: KustomizationType,
+  namespace: string,
+): FluxKustomizationType['spec']['customHealthChecks'] {
+  if (!kustomization.health_check_exprs || kustomization.health_check_exprs.length === 0) {
+    return undefined;
+  }
+
+  return kustomization.health_check_exprs.map((check) => {
+    const healthCheck: {
+      apiVersion: string;
+      kind: string;
+      namespace?: string;
+      current?: string;
+      failed?: string;
+    } = {
+      apiVersion: check.api_version,
+      kind: check.kind,
+      namespace: check.namespace ?? namespace,
+    };
+
+    if (check.current !== undefined) {
+      healthCheck.current = check.current;
+    }
+
+    if (check.failed !== undefined) {
+      healthCheck.failed = check.failed;
+    }
+
+    return healthCheck;
+  });
+}
+
 /**
  * Generates a Flux OCIRepository resource.
  */
@@ -143,6 +199,7 @@ export function generate_flux_kustomization(
   resolved: ResolvedKustomizationType,
   source_repository_name = 'flux-system',
   source_kind: 'GitRepository' | 'OCIRepository' = 'GitRepository',
+  preservation?: PreservationPolicyType,
 ): FluxKustomizationType {
   const { template, kustomization, values, namespace } = resolved;
   const name = generate_flux_name(template.metadata.name, kustomization.name);
@@ -160,6 +217,15 @@ export function generate_flux_kustomization(
     },
   };
 
+  // Add preservation patches if preservation is configured
+  if (preservation) {
+    const preserved_types = get_preserved_resource_types(preservation);
+    if (preserved_types.length > 0) {
+      const patches = generate_preservation_patches(preserved_types);
+      spec.patches = patches;
+    }
+  }
+
   // Add timeout if specified
   if (kustomization.timeout) {
     spec.timeout = kustomization.timeout;
@@ -191,6 +257,12 @@ export function generate_flux_kustomization(
     spec.healthChecks = health_checks;
   }
 
+  // Add custom health checks with CEL expressions
+  const custom_health_checks = generate_custom_health_checks(kustomization, namespace);
+  if (custom_health_checks) {
+    spec.customHealthChecks = custom_health_checks;
+  }
+
   return {
     apiVersion: 'kustomize.toolkit.fluxcd.io/v1',
     kind: 'Kustomization',

package/src/generator.ts

@@ -17,6 +17,7 @@ import {
   generate_health_checks,
   resolve_kustomization,
 } from './flux.js';
+import { get_template_config, resolve_kustomization_state } from './kustomization-resolution.js';
 import { generate_namespace_resources } from './namespace.js';
 import { serialize_resource, serialize_resources, write_generation_result } from './output.js';
 import type {
@@ -169,7 +170,7 @@ export function create_generator(
 
       // Validate dependency graph before generation (unless skipped)
       if (!skip_validation) {
-        const validation_result = validate_dependencies(templates);
+        const validation_result = validate_dependencies(cluster, templates);
         if (!validation_result.success) {
           return validation_result;
         }
@@ -201,7 +202,22 @@ export function create_generator(
           continue;
         }
 
+        // Get template configuration from cluster for kustomization overrides
+        const template_config = get_template_config(cluster, resolved.template.metadata.name);
+
         for (const kustomization of resolved.template.spec.kustomizations) {
+          // Resolve kustomization state (enabled + preservation)
+          const kustomization_state = resolve_kustomization_state(
+            kustomization,
+            template_config,
+            kustomization.name,
+          );
+
+          // Skip disabled kustomizations
+          if (!kustomization_state.enabled) {
+            continue;
+          }
+
           const resolved_kustomization = resolve_kustomization(
             resolved.template,
             kustomization,
@@ -213,6 +229,7 @@ export function create_generator(
             resolved_kustomization,
             source_repository_name,
             source_kind,
+            kustomization_state.preservation,
           );
 
           // Override namespace to configured value

package/src/kustomization-resolution.ts

@@ -0,0 +1,133 @@
+import type {
+  ClusterType,
+  KustomizationType,
+  PreservationPolicyType,
+  TemplateConfigType,
+} from '@kustodian/schema';
+
+/**
+ * Resolved kustomization enablement and preservation state.
+ */
+export interface ResolvedKustomizationStateType {
+  enabled: boolean;
+  preservation: PreservationPolicyType;
+}
+
+/**
+ * Resolves kustomization enablement state from template defaults and cluster overrides.
+ *
+ * Resolution order (last wins):
+ * 1. Template kustomization default (enabled field, defaults to true)
+ * 2. Cluster kustomization override (if specified)
+ *
+ * @param kustomization - Template kustomization definition
+ * @param template_config - Cluster template configuration (may be undefined)
+ * @param kustomization_name - Name of the kustomization to resolve
+ * @returns Resolved enablement state
+ */
+export function resolve_kustomization_enabled(
+  kustomization: KustomizationType,
+  template_config: TemplateConfigType | undefined,
+  kustomization_name: string,
+): boolean {
+  // Start with template default (defaults to true via schema)
+  const template_default = kustomization.enabled ?? true;
+
+  // Check for cluster override
+  if (!template_config?.kustomizations) {
+    return template_default;
+  }
+
+  const override = template_config.kustomizations[kustomization_name];
+  if (override === undefined) {
+    return template_default;
+  }
+
+  // Handle simple boolean override
+  if (typeof override === 'boolean') {
+    return override;
+  }
+
+  // Handle complex override object
+  return override.enabled;
+}
+
+/**
+ * Resolves kustomization preservation policy from template defaults and cluster overrides.
+ *
+ * Resolution order (last wins):
+ * 1. Template kustomization preservation policy (defaults to 'stateful')
+ * 2. Cluster kustomization override preservation (if specified)
+ *
+ * @param kustomization - Template kustomization definition
+ * @param template_config - Cluster template configuration (may be undefined)
+ * @param kustomization_name - Name of the kustomization to resolve
+ * @returns Resolved preservation policy
+ */
+export function resolve_kustomization_preservation(
+  kustomization: KustomizationType,
+  template_config: TemplateConfigType | undefined,
+  kustomization_name: string,
+): PreservationPolicyType {
+  // Start with template default
+  const template_default: PreservationPolicyType = kustomization.preservation ?? {
+    mode: 'stateful',
+  };
+
+  // Check for cluster override
+  if (!template_config?.kustomizations) {
+    return template_default;
+  }
+
+  const override = template_config.kustomizations[kustomization_name];
+  if (override === undefined || typeof override === 'boolean') {
+    return template_default;
+  }
+
+  // Merge cluster override with template default
+  if (override.preservation) {
+    return {
+      mode: override.preservation.mode,
+      keep_resources: template_default.keep_resources,
+    };
+  }
+
+  return template_default;
+}
+
+/**
+ * Resolves complete kustomization state (enabled + preservation).
+ *
+ * @param kustomization - Template kustomization definition
+ * @param template_config - Cluster template configuration (may be undefined)
+ * @param kustomization_name - Name of the kustomization to resolve
+ * @returns Resolved kustomization state
+ */
+export function resolve_kustomization_state(
+  kustomization: KustomizationType,
+  template_config: TemplateConfigType | undefined,
+  kustomization_name: string,
+): ResolvedKustomizationStateType {
+  return {
+    enabled: resolve_kustomization_enabled(kustomization, template_config, kustomization_name),
+    preservation: resolve_kustomization_preservation(
+      kustomization,
+      template_config,
+      kustomization_name,
+    ),
+  };
+}
+
+/**
+ * Gets template configuration for a specific template from cluster spec.
+ *
+ * @param cluster - Cluster configuration
+ * @param template_name - Name of the template to find
+ * @returns Template configuration or undefined if not found
+ */
+export function get_template_config(
+  cluster: ClusterType,
+  template_name: string,
+): TemplateConfigType | undefined {
+  return cluster.spec.templates?.find((t) => t.name === template_name);
+}

package/src/preservation.ts

@@ -0,0 +1,88 @@
+import type { PreservationPolicyType } from '@kustodian/schema';
+
+/**
+ * Resource types that are considered stateful and should be preserved by default.
+ *
+ * This list defines which Kubernetes resources contain state that should not be
+ * accidentally deleted when disabling a kustomization.
+ */
+export const DEFAULT_STATEFUL_RESOURCES = ['PersistentVolumeClaim', 'Secret', 'ConfigMap'] as const;
+
+/**
+ * Gets the list of resource types that should be preserved based on preservation policy.
+ *
+ * @param policy - Preservation policy from kustomization configuration
+ * @returns Array of Kubernetes resource kinds to preserve
+ */
+export function get_preserved_resource_types(policy: PreservationPolicyType): string[] {
+  switch (policy.mode) {
+    case 'none':
+      return [];
+
+    case 'stateful':
+      return [...DEFAULT_STATEFUL_RESOURCES];
+
+    case 'custom':
+      return policy.keep_resources ?? [];
+
+    default: {
+      // Exhaustiveness check
+      const _exhaustive: never = policy.mode;
+      throw new Error(`Unknown preservation mode: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Generates Flux Kustomization patches to label preserved resources.
+ *
+ * This function creates patches that add a `kustodian.io/preserve: "true"` label
+ * to resources that should be kept when a kustomization is disabled.
+ *
+ * The label-based approach works as follows:
+ * 1. Add labels to resources we want to preserve
+ * 2. Configure Flux to not prune resources with the preserve label
+ * 3. When kustomization is disabled, non-preserved resources are deleted
+ * 4. Preserved resources (PVCs, Secrets, etc.) remain in the cluster
+ *
+ * @param preserved_types - Resource types to keep (from get_preserved_resource_types)
+ * @returns Flux patch objects that add preservation labels
+ */
+export function generate_preservation_patches(preserved_types: string[]): Array<{
+  patch: string;
+  target: {
+    kind: string;
+  };
+}> {
+  if (preserved_types.length === 0) {
+    return [];
+  }
+
+  return preserved_types.map((kind) => ({
+    patch: `
+apiVersion: v1
+kind: ${kind}
+metadata:
+  labels:
+    kustodian.io/preserve: "true"
+`,
+    target: {
+      kind,
+    },
+  }));
+}
+
+/**
+ * Checks if a resource type should be preserved based on the preservation policy.
+ *
+ * @param resource_kind - Kubernetes resource kind (e.g., 'Deployment', 'PersistentVolumeClaim')
+ * @param policy - Preservation policy
+ * @returns true if the resource should be preserved, false if it should be deleted
+ */
+export function should_preserve_resource(
+  resource_kind: string,
+  policy: PreservationPolicyType,
+): boolean {
+  const preserved_types = get_preserved_resource_types(policy);
+  return preserved_types.includes(resource_kind);
+}

package/src/types.ts

@@ -84,6 +84,25 @@ export interface FluxOCIRepositoryType {
   };
 }
 
+/**
+ * Flux Kustomization patch target selector.
+ */
+export interface FluxPatchTargetType {
+  kind: string;
+  name?: string;
+  namespace?: string;
+  labelSelector?: string;
+  annotationSelector?: string;
+}
+
+/**
+ * Flux Kustomization patch.
+ */
+export interface FluxPatchType {
+  patch: string;
+  target: FluxPatchTargetType;
+}
+
 /**
  * Flux Kustomization resource type.
  */
@@ -116,5 +135,15 @@ export interface FluxKustomizationType {
       name: string;
       namespace: string;
     }>;
+    customHealthChecks?: Array<{
+      apiVersion: string;
+      kind: string;
+      namespace?: string;
+      /** CEL expression for when resource is healthy/current */
+      current?: string;
+      /** CEL expression for when resource has failed */
+      failed?: string;
+    }>;
+    patches?: FluxPatchType[];
   };
 }

package/src/validation/enablement.ts

@@ -0,0 +1,111 @@
+import type { ClusterType, TemplateType } from '@kustodian/schema';
+
+import { get_template_config, resolve_kustomization_state } from '../kustomization-resolution.js';
+import { create_node_id } from './reference.js';
+
+/**
+ * Disabled dependency error - an enabled kustomization depends on a disabled one.
+ */
+export interface DisabledDependencyErrorType {
+  readonly type: 'disabled_dependency';
+  /** Node ID of the enabled kustomization */
+  readonly source: string;
+  /** Node ID of the disabled dependency */
+  readonly target: string;
+  readonly message: string;
+}
+
+/**
+ * Validates that no enabled kustomizations depend on disabled ones.
+ *
+ * This implements the "block by default" policy: you cannot disable a kustomization
+ * if other enabled kustomizations depend on it.
+ *
+ * @param cluster - Cluster configuration
+ * @param templates - Array of templates
+ * @returns Array of validation errors (empty if valid)
+ */
+export function validate_enablement_dependencies(
+  cluster: ClusterType,
+  templates: TemplateType[],
+): DisabledDependencyErrorType[] {
+  const errors: DisabledDependencyErrorType[] = [];
+
+  // Build a map of kustomization ID to enabled state
+  const enablement_map = new Map<string, boolean>();
+
+  for (const template of templates) {
+    const template_config = get_template_config(cluster, template.metadata.name);
+
+    // Check if template itself is enabled
+    const template_enabled = template_config?.enabled ?? true;
+    if (!template_enabled) {
+      // All kustomizations in disabled templates are disabled
+      for (const kustomization of template.spec.kustomizations) {
+        const node_id = create_node_id(template.metadata.name, kustomization.name);
+        enablement_map.set(node_id, false);
+      }
+      continue;
+    }
+
+    // Template is enabled, check individual kustomizations
+    for (const kustomization of template.spec.kustomizations) {
+      const node_id = create_node_id(template.metadata.name, kustomization.name);
+      const state = resolve_kustomization_state(kustomization, template_config, kustomization.name);
+      enablement_map.set(node_id, state.enabled);
+    }
+  }
+
+  // Check each enabled kustomization's dependencies
+  for (const template of templates) {
+    const template_config = get_template_config(cluster, template.metadata.name);
+    const template_enabled = template_config?.enabled ?? true;
+
+    if (!template_enabled) {
+      continue;
+    }
+
+    for (const kustomization of template.spec.kustomizations) {
+      const node_id = create_node_id(template.metadata.name, kustomization.name);
+      const state = resolve_kustomization_state(kustomization, template_config, kustomization.name);
+
+      // Skip if this kustomization is disabled
+      if (!state.enabled) {
+        continue;
+      }
+
+      // This kustomization is enabled - check its dependencies
+      for (const dep of kustomization.depends_on ?? []) {
+        // Skip raw dependencies - they're external to kustodian
+        if (typeof dep !== 'string') {
+          continue;
+        }
+
+        // Parse dependency to get target node ID
+        const dep_parts = dep.split('/');
+        let target_node_id: string;
+
+        if (dep_parts.length === 2) {
+          // Cross-template reference: template/kustomization
+          target_node_id = dep;
+        } else {
+          // Within-template reference: kustomization
+          target_node_id = create_node_id(template.metadata.name, dep);
+        }
+
+        // Check if the dependency is disabled
+        const dep_enabled = enablement_map.get(target_node_id);
+        if (dep_enabled === false) {
+          errors.push({
+            type: 'disabled_dependency',
+            source: node_id,
+            target: target_node_id,
+            message: `Enabled kustomization '${node_id}' depends on disabled kustomization '${target_node_id}'. Either enable '${target_node_id}' or disable '${node_id}'.`,
+          });
+        }
+      }
+    }
+  }
+
+  return errors;
+}

package/src/validation/graph.ts

@@ -62,6 +62,11 @@ export function build_dependency_graph(templates: TemplateType[]): BuildGraphRes
         // Resolve to full node ID
         const target_id = resolve_dependency_ref(parse_result, template_name);
 
+        // Skip raw dependencies - they're external and don't participate in graph validation
+        if (target_id === null) {
+          continue;
+        }
+
         // Check for self-reference
         if (target_id === node_id) {
           errors.push({

package/src/validation/index.ts

@@ -1,8 +1,9 @@
 import { type ResultType, failure, success } from '@kustodian/core';
 import type { KustodianErrorType } from '@kustodian/core';
-import type { TemplateType } from '@kustodian/schema';
+import type { ClusterType, TemplateType } from '@kustodian/schema';
 
 import { detect_cycles } from './cycle-detection.js';
+import { validate_enablement_dependencies } from './enablement.js';
 import { build_dependency_graph } from './graph.js';
 import type { GraphValidationResultType } from './types.js';
 
@@ -19,6 +20,11 @@ export type {
   MissingReferenceErrorType,
   SelfReferenceErrorType,
 } from './types.js';
+export type {
+  RequirementValidationErrorType,
+  RequirementValidationResultType,
+} from './requirements.js';
+export type { DisabledDependencyErrorType } from './enablement.js';
 
 // Re-export functions
 export { build_dependency_graph, get_all_nodes, get_node } from './graph.js';
@@ -30,6 +36,8 @@ export {
   parse_node_id,
   resolve_dependency_ref,
 } from './reference.js';
+export { validate_template_requirements } from './requirements.js';
+export { validate_enablement_dependencies } from './enablement.js';
 
 /**
  * Validates the dependency graph for a set of templates.
@@ -72,16 +80,22 @@ export function validate_dependency_graph(templates: TemplateType[]): GraphValid
  * Returns a success with the topological order, or a failure with
  * detailed error information.
  *
+ * @param cluster - Cluster configuration
  * @param templates - Array of templates to validate
  * @returns Result with topological order on success, or error on failure
  */
 export function validate_dependencies(
+  cluster: ClusterType,
   templates: TemplateType[],
 ): ResultType<string[], KustodianErrorType> {
   const result = validate_dependency_graph(templates);
+  const enablement_errors = validate_enablement_dependencies(cluster, templates);
+
+  // Combine all errors
+  const all_errors = [...result.errors, ...enablement_errors];
 
-  if (!result.valid) {
-    const error_messages = result.errors.map((e) => e.message);
+  if (all_errors.length > 0) {
+    const error_messages = all_errors.map((e) => e.message);
     return failure({
       code: 'DEPENDENCY_VALIDATION_ERROR',
       message: `Dependency validation failed:\n${error_messages.map((m) => `  - ${m}`).join('\n')}`,

package/src/validation/reference.ts

@@ -1,4 +1,45 @@
-import type { DependencyRefType, InvalidReferenceErrorType } from './types.js';
+import type { DependencyRefType as SchemaDependencyRefType } from '@kustodian/schema';
+import type {
+  DependencyRefType,
+  InvalidReferenceErrorType,
+  ParsedDependencyRefType,
+  RawDependencyRefType,
+} from './types.js';
+
+/**
+ * Checks if a dependency reference is a raw object reference.
+ */
+function is_raw_object(
+  ref: SchemaDependencyRefType,
+): ref is { raw: { name: string; namespace: string } } {
+  return typeof ref === 'object' && 'raw' in ref;
+}
+
+/**
+ * Parses a dependency reference from the schema.
+ *
+ * Supports three formats:
+ * - Within-template: `kustomization-name` (e.g., `operator`)
+ * - Cross-template: `template-name/kustomization-name` (e.g., `001-secrets/doppler`)
+ * - Raw external: `{ raw: { name: 'legacy-infrastructure', namespace: 'gitops-system' } }`
+ *
+ * @param ref - The dependency reference from schema (string or raw object)
+ * @returns Parsed dependency reference or error
+ */
+export function parse_dependency_ref(
+  ref: SchemaDependencyRefType,
+): DependencyRefType | InvalidReferenceErrorType {
+  // Handle raw object references
+  if (is_raw_object(ref)) {
+    return {
+      name: ref.raw.name,
+      namespace: ref.raw.namespace,
+    } satisfies RawDependencyRefType;
+  }
+
+  // Handle string references
+  return parse_string_dependency_ref(ref);
+}
 
 /**
  * Parses a dependency reference string.
@@ -10,7 +51,9 @@ import type { DependencyRefType, InvalidReferenceErrorType } from './types.js';
  * @param ref - The raw dependency reference string
  * @returns Parsed dependency reference or error
  */
-export function parse_dependency_ref(ref: string): DependencyRefType | InvalidReferenceErrorType {
+function parse_string_dependency_ref(
+  ref: string,
+): ParsedDependencyRefType | InvalidReferenceErrorType {
   const trimmed = ref.trim();
 
   if (trimmed.length === 0) {
@@ -90,9 +133,18 @@ export function is_parse_error(
  *
  * @param ref - Parsed dependency reference
  * @param current_template - The template containing the reference
- * @returns Full node ID in format `template/kustomization`
+ * @returns Full node ID in format `template/kustomization` for string refs, or null for raw refs
  */
-export function resolve_dependency_ref(ref: DependencyRefType, current_template: string): string {
+export function resolve_dependency_ref(
+  ref: DependencyRefType,
+  current_template: string,
+): string | null {
+  // Raw dependencies don't resolve to node IDs - they're external
+  if ('name' in ref && 'namespace' in ref) {
+    return null;
+  }
+
+  // String-based dependency references
   const template = ref.template ?? current_template;
   return `${template}/${ref.kustomization}`;
 }

package/src/validation/requirements.ts

@@ -0,0 +1,108 @@
+import type { NodeSchemaType, TemplateRequirementType, TemplateType } from '@kustodian/schema';
+
+/**
+ * Validation error for a template requirement.
+ */
+export interface RequirementValidationErrorType {
+  template: string;
+  requirement: TemplateRequirementType;
+  message: string;
+}
+
+/**
+ * Result of validating template requirements against cluster nodes.
+ */
+export interface RequirementValidationResultType {
+  valid: boolean;
+  errors: RequirementValidationErrorType[];
+}
+
+/**
+ * Checks if a node label matches the requirement.
+ */
+function node_matches_label_requirement(
+  node: NodeSchemaType,
+  key: string,
+  value?: string,
+): boolean {
+  if (!node.labels) {
+    return false;
+  }
+
+  const label_value = node.labels[key];
+
+  // Label must exist
+  if (label_value === undefined) {
+    return false;
+  }
+
+  // If no specific value required, just presence is enough
+  if (value === undefined) {
+    return true;
+  }
+
+  // Check if label value matches
+  // Node labels can be string, boolean, or number, so convert both to strings for comparison
+  return String(label_value) === value;
+}
+
+/**
+ * Validates node label requirements for a template against cluster nodes.
+ */
+function validate_node_label_requirements(
+  template: TemplateType,
+  nodes: NodeSchemaType[],
+): RequirementValidationErrorType[] {
+  const errors: RequirementValidationErrorType[] = [];
+
+  if (!template.spec.requirements) {
+    return errors;
+  }
+
+  for (const requirement of template.spec.requirements) {
+    if (requirement.type !== 'nodeLabel') {
+      continue;
+    }
+
+    const matching_nodes = nodes.filter((node) =>
+      node_matches_label_requirement(node, requirement.key, requirement.value),
+    );
+
+    if (matching_nodes.length < requirement.atLeast) {
+      const value_part = requirement.value !== undefined ? `=${requirement.value}` : '';
+      const message = `Template requires at least ${requirement.atLeast} node(s) with label '${requirement.key}${value_part}', but found ${matching_nodes.length}`;
+
+      errors.push({
+        template: template.metadata.name,
+        requirement,
+        message,
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validates all template requirements against cluster nodes.
+ *
+ * @param templates - Templates to validate (only enabled ones should be passed)
+ * @param nodes - Cluster nodes to validate against
+ * @returns Validation result with any requirement errors
+ */
+export function validate_template_requirements(
+  templates: TemplateType[],
+  nodes: NodeSchemaType[],
+): RequirementValidationResultType {
+  const all_errors: RequirementValidationErrorType[] = [];
+
+  for (const template of templates) {
+    const errors = validate_node_label_requirements(template, nodes);
+    all_errors.push(...errors);
+  }
+
+  return {
+    valid: all_errors.length === 0,
+    errors: all_errors,
+  };
+}

package/src/validation/types.ts

@@ -13,9 +13,9 @@ export interface GraphNodeType {
 }
 
 /**
- * Parsed dependency reference.
+ * Parsed dependency reference for string-based dependencies.
  */
-export interface DependencyRefType {
+export interface ParsedDependencyRefType {
   /** Template name (undefined for within-template refs) */
   readonly template?: string;
   /** Kustomization name */
@@ -24,6 +24,35 @@ export interface DependencyRefType {
   readonly raw: string;
 }
 
+/**
+ * Raw external dependency reference.
+ */
+export interface RawDependencyRefType {
+  /** Flux Kustomization name */
+  readonly name: string;
+  /** Flux Kustomization namespace */
+  readonly namespace: string;
+}
+
+/**
+ * Union type for all parsed dependency references.
+ */
+export type DependencyRefType = ParsedDependencyRefType | RawDependencyRefType;
+
+/**
+ * Type guard to check if a dependency reference is a raw reference.
+ */
+export function is_raw_dependency_ref(ref: DependencyRefType): ref is RawDependencyRefType {
+  return 'name' in ref && 'namespace' in ref;
+}
+
+/**
+ * Type guard to check if a dependency reference is a parsed string reference.
+ */
+export function is_parsed_dependency_ref(ref: DependencyRefType): ref is ParsedDependencyRefType {
+  return 'kustomization' in ref;
+}
+
 /**
  * Cycle error - circular dependency detected.
  */