@kustodian/nodes 1.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kustodian/nodes",
+  "version": "1.0.0",
+  "description": "Node definitions, roles, and labeling 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",
+    "nodes",
+    "kubernetes"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "packages/nodes"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "workspace:*",
+    "@kustodian/schema": "workspace:*"
+  },
+  "devDependencies": {}
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './labeler.js';
+export * from './profile.js';

package/src/labeler.ts

@@ -0,0 +1,201 @@
+import { type ResultType, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+
+import { type NodeListType, type NodeType, format_node_labels } from './types.js';
+
+/**
+ * Label operation types.
+ */
+export type LabelOperationType = 'add' | 'update' | 'remove';
+
+/**
+ * A single label change to be applied.
+ */
+export interface LabelChangeType {
+  node: string;
+  key: string;
+  value?: string;
+  operation: LabelOperationType;
+}
+
+/**
+ * Options for the label sync operation.
+ */
+export interface LabelSyncOptionsType {
+  dry_run?: boolean;
+  verify?: boolean;
+}
+
+/**
+ * Result of a label sync operation.
+ */
+export interface LabelSyncResultType {
+  changes: LabelChangeType[];
+  applied: number;
+  skipped: number;
+}
+
+/**
+ * Calculates the label changes needed for a node.
+ */
+export function calculate_label_changes(
+  node: NodeType,
+  current_labels: Record<string, string>,
+  prefix: string,
+): LabelChangeType[] {
+  const changes: LabelChangeType[] = [];
+  const desired_labels = format_node_labels(node.labels, prefix);
+
+  // Find labels to add or update
+  for (const [key, value] of Object.entries(desired_labels)) {
+    const current_value = current_labels[key];
+
+    if (current_value === undefined) {
+      changes.push({
+        node: node.name,
+        key,
+        value,
+        operation: 'add',
+      });
+    } else if (current_value !== value) {
+      changes.push({
+        node: node.name,
+        key,
+        value,
+        operation: 'update',
+      });
+    }
+  }
+
+  // Find labels to remove (labels with prefix that aren't in desired)
+  for (const key of Object.keys(current_labels)) {
+    if (key.startsWith(`${prefix}/`) && !(key in desired_labels)) {
+      changes.push({
+        node: node.name,
+        key,
+        operation: 'remove',
+      });
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Calculates all label changes for a node list.
+ */
+export function calculate_all_label_changes(
+  node_list: NodeListType,
+  current_labels_by_node: Map<string, Record<string, string>>,
+): LabelChangeType[] {
+  const prefix = node_list.label_prefix ?? 'kustodian.io';
+  const all_changes: LabelChangeType[] = [];
+
+  for (const node of node_list.nodes) {
+    const current_labels = current_labels_by_node.get(node.name) ?? {};
+    const changes = calculate_label_changes(node, current_labels, prefix);
+    all_changes.push(...changes);
+  }
+
+  return all_changes;
+}
+
+/**
+ * Formats a label change for display.
+ */
+export function format_label_change(change: LabelChangeType): string {
+  switch (change.operation) {
+    case 'add':
+      return `[+] ${change.node}: ${change.key}=${change.value}`;
+    case 'update':
+      return `[~] ${change.node}: ${change.key}=${change.value}`;
+    case 'remove':
+      return `[-] ${change.node}: ${change.key}`;
+  }
+}
+
+/**
+ * Groups label changes by node.
+ */
+export function group_changes_by_node(changes: LabelChangeType[]): Map<string, LabelChangeType[]> {
+  const grouped = new Map<string, LabelChangeType[]>();
+
+  for (const change of changes) {
+    const node_changes = grouped.get(change.node) ?? [];
+    node_changes.push(change);
+    grouped.set(change.node, node_changes);
+  }
+
+  return grouped;
+}
+
+/**
+ * Creates a dry-run result from label changes.
+ */
+export function create_dry_run_result(changes: LabelChangeType[]): LabelSyncResultType {
+  return {
+    changes,
+    applied: 0,
+    skipped: changes.length,
+  };
+}
+
+/**
+ * Node labeler service interface.
+ * This is implemented by the actual Kubernetes client.
+ */
+export interface NodeLabelerType {
+  /**
+   * Gets the current labels for a node.
+   */
+  get_labels(node_name: string): Promise<ResultType<Record<string, string>, KustodianErrorType>>;
+
+  /**
+   * Applies a label change to a node.
+   */
+  apply_change(change: LabelChangeType): Promise<ResultType<void, KustodianErrorType>>;
+
+  /**
+   * Syncs labels for all nodes in the list.
+   */
+  sync_labels(
+    node_list: NodeListType,
+    options?: LabelSyncOptionsType,
+  ): Promise<ResultType<LabelSyncResultType, KustodianErrorType>>;
+}
+
+/**
+ * Creates a mock labeler for testing.
+ */
+export function create_mock_labeler(
+  labels_by_node: Map<string, Record<string, string>>,
+): NodeLabelerType {
+  return {
+    async get_labels(node_name) {
+      const labels = labels_by_node.get(node_name);
+      if (!labels) {
+        return success({});
+      }
+      return success(labels);
+    },
+
+    async apply_change(_change) {
+      return success(undefined);
+    },
+
+    async sync_labels(node_list, options) {
+      const changes = calculate_all_label_changes(node_list, labels_by_node);
+
+      if (options?.dry_run) {
+        return success(create_dry_run_result(changes));
+      }
+
+      // In mock, all changes are "applied"
+      return success({
+        changes,
+        applied: changes.length,
+        skipped: 0,
+      });
+    },
+  };
+}

package/src/profile.ts

@@ -0,0 +1,190 @@
+import type { NodeType, TaintType } from './types.js';
+
+/**
+ * Node profile type for profile resolution.
+ * This mirrors the NodeProfileType from @kustodian/schema but is defined here
+ * to avoid circular dependencies.
+ */
+export interface NodeProfileType {
+  name: string;
+  display_name?: string;
+  description?: string;
+  labels?: Record<string, string | boolean | number>;
+  taints?: TaintType[];
+  annotations?: Record<string, string>;
+}
+
+/**
+ * Resolved node type with profile values merged.
+ * The profile field is removed after resolution.
+ */
+export type ResolvedNodeType = Omit<NodeType, 'profile'>;
+
+/**
+ * Merges taints from profile and node.
+ * Node taints are appended after profile taints.
+ * Duplicate taints (same key+effect) from node override profile taints.
+ */
+function merge_taints(
+  profile_taints: TaintType[] | undefined,
+  node_taints: TaintType[] | undefined,
+): TaintType[] | undefined {
+  if (!profile_taints && !node_taints) {
+    return undefined;
+  }
+
+  if (!profile_taints) {
+    return node_taints;
+  }
+
+  if (!node_taints) {
+    return profile_taints;
+  }
+
+  // Create a map of node taints keyed by key+effect for deduplication
+  const node_taint_keys = new Set(
+    node_taints.map((t) => `${t.key}:${t.effect}`),
+  );
+
+  // Filter out profile taints that are overridden by node taints
+  const filtered_profile_taints = profile_taints.filter(
+    (t) => !node_taint_keys.has(`${t.key}:${t.effect}`),
+  );
+
+  return [...filtered_profile_taints, ...node_taints];
+}
+
+/**
+ * Resolves a node with its profile configuration.
+ * Profile values are merged with node values, where node values take precedence.
+ *
+ * Merge strategy:
+ * - labels: Profile labels are base, node labels override/extend
+ * - taints: Node taints override profile taints with same key+effect, others are combined
+ * - annotations: Profile annotations are base, node annotations override/extend
+ * - ssh: Not inherited from profile (kept as node-specific)
+ *
+ * @param node - The node to resolve
+ * @param profile - The profile to apply, or undefined if no profile
+ * @returns The resolved node with profile values merged
+ */
+export function resolve_node_profile(
+  node: NodeType,
+  profile: NodeProfileType | undefined,
+): ResolvedNodeType {
+  if (!profile) {
+    // No profile to apply, return node without profile field
+    const { profile: _, ...resolved } = node;
+    return resolved;
+  }
+
+  // Merge labels: profile as base, node overrides
+  const merged_labels =
+    profile.labels || node.labels
+      ? { ...profile.labels, ...node.labels }
+      : undefined;
+
+  // Merge taints: deduplicate by key+effect, node wins
+  const merged_taints = merge_taints(profile.taints, node.taints);
+
+  // Merge annotations: profile as base, node overrides
+  const merged_annotations =
+    profile.annotations || node.annotations
+      ? { ...profile.annotations, ...node.annotations }
+      : undefined;
+
+  const resolved: ResolvedNodeType = {
+    name: node.name,
+    role: node.role,
+    address: node.address,
+  };
+
+  if (node.ssh !== undefined) {
+    resolved.ssh = node.ssh;
+  }
+  if (merged_labels !== undefined) {
+    resolved.labels = merged_labels;
+  }
+  if (merged_taints !== undefined) {
+    resolved.taints = merged_taints;
+  }
+  if (merged_annotations !== undefined) {
+    resolved.annotations = merged_annotations;
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolves all nodes in a list with their profiles.
+ *
+ * @param nodes - The nodes to resolve
+ * @param profiles - Map of profile name to profile
+ * @returns Object with resolved nodes and any missing profile errors
+ */
+export function resolve_all_node_profiles(
+  nodes: NodeType[],
+  profiles: Map<string, NodeProfileType>,
+): { resolved: ResolvedNodeType[]; errors: string[] } {
+  const resolved: ResolvedNodeType[] = [];
+  const errors: string[] = [];
+
+  for (const node of nodes) {
+    if (node.profile) {
+      const profile = profiles.get(node.profile);
+      if (!profile) {
+        errors.push(`Node '${node.name}' references unknown profile '${node.profile}'`);
+        // Still resolve the node without the profile
+        const { profile: _, ...node_without_profile } = node;
+        resolved.push(node_without_profile);
+      } else {
+        resolved.push(resolve_node_profile(node, profile));
+      }
+    } else {
+      resolved.push(resolve_node_profile(node, undefined));
+    }
+  }
+
+  return { resolved, errors };
+}
+
+/**
+ * Collects all unique profile names referenced by nodes.
+ */
+export function get_referenced_profiles(nodes: NodeType[]): Set<string> {
+  const profiles = new Set<string>();
+  for (const node of nodes) {
+    if (node.profile) {
+      profiles.add(node.profile);
+    }
+  }
+  return profiles;
+}
+
+/**
+ * Validates that all referenced profiles exist.
+ *
+ * @param nodes - The nodes to check
+ * @param profiles - Map of available profiles
+ * @returns Array of error messages for missing profiles
+ */
+export function validate_profile_references(
+  nodes: NodeType[],
+  profiles: Map<string, NodeProfileType>,
+): string[] {
+  const errors: string[] = [];
+  const referenced = get_referenced_profiles(nodes);
+
+  for (const profile_name of referenced) {
+    if (!profiles.has(profile_name)) {
+      const nodes_using = nodes
+        .filter((n) => n.profile === profile_name)
+        .map((n) => n.name);
+      errors.push(
+        `Profile '${profile_name}' not found, referenced by nodes: ${nodes_using.join(', ')}`,
+      );
+    }
+  }
+
+  return errors;
+}

package/src/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Node role in the cluster.
+ */
+export type NodeRoleType = 'controller' | 'worker' | 'controller+worker';
+
+/**
+ * SSH configuration for connecting to a node.
+ */
+export interface SshConfigType {
+  user?: string;
+  key_path?: string;
+  known_hosts_path?: string;
+  port?: number;
+}
+
+/**
+ * Kubernetes taint configuration.
+ */
+export interface TaintType {
+  key: string;
+  value?: string;
+  effect: 'NoSchedule' | 'PreferNoSchedule' | 'NoExecute';
+}
+
+/**
+ * Node definition with its configuration.
+ */
+export interface NodeType {
+  name: string;
+  role: NodeRoleType;
+  address: string;
+  profile?: string;
+  ssh?: SshConfigType;
+  labels?: Record<string, string | boolean | number>;
+  taints?: TaintType[];
+  annotations?: Record<string, string>;
+}
+
+/**
+ * Node list with default SSH configuration.
+ */
+export interface NodeListType {
+  cluster: string;
+  label_prefix?: string;
+  ssh?: SshConfigType;
+  nodes: NodeType[];
+}
+
+/**
+ * Default label prefix.
+ */
+export const DEFAULT_LABEL_PREFIX = 'kustodian.io';
+
+/**
+ * Formats a label key with the configured prefix.
+ */
+export function format_label_key(key: string, prefix: string = DEFAULT_LABEL_PREFIX): string {
+  // If key already has a prefix (contains /), return as-is
+  if (key.includes('/')) {
+    return key;
+  }
+  return `${prefix}/${key}`;
+}
+
+/**
+ * Formats a label value as a string.
+ */
+export function format_label_value(value: string | boolean | number): string {
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false';
+  }
+  return String(value);
+}
+
+/**
+ * Formats all labels for a node with the configured prefix.
+ */
+export function format_node_labels(
+  labels: Record<string, string | boolean | number> | undefined,
+  prefix: string = DEFAULT_LABEL_PREFIX,
+): Record<string, string> {
+  if (!labels) {
+    return {};
+  }
+
+  const result: Record<string, string> = {};
+  for (const [key, value] of Object.entries(labels)) {
+    const formatted_key = format_label_key(key, prefix);
+    result[formatted_key] = format_label_value(value);
+  }
+  return result;
+}
+
+/**
+ * Gets the SSH configuration for a node, merging with defaults.
+ */
+export function get_node_ssh_config(node: NodeType, default_ssh?: SshConfigType): SshConfigType {
+  return {
+    ...default_ssh,
+    ...node.ssh,
+  };
+}
+
+/**
+ * Checks if a node has a controller role.
+ */
+export function is_controller(node: NodeType): boolean {
+  return node.role === 'controller' || node.role === 'controller+worker';
+}
+
+/**
+ * Checks if a node has a worker role.
+ */
+export function is_worker(node: NodeType): boolean {
+  return node.role === 'worker' || node.role === 'controller+worker';
+}
+
+/**
+ * Gets all controller nodes from a node list.
+ */
+export function get_controllers(nodes: NodeType[]): NodeType[] {
+  return nodes.filter(is_controller);
+}
+
+/**
+ * Gets all worker nodes from a node list.
+ */
+export function get_workers(nodes: NodeType[]): NodeType[] {
+  return nodes.filter(is_worker);
+}
+
+/**
+ * Gets the primary controller node (first controller).
+ */
+export function get_primary_controller(nodes: NodeType[]): NodeType | undefined {
+  return nodes.find(is_controller);
+}