@kustodian/loader 1.0.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@kustodian/loader",
+  "version": "1.0.0",
+  "description": "YAML file loading and validation 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",
+    "loader",
+    "yaml"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "packages/loader"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "@kustodian/core": "workspace:*",
+    "@kustodian/schema": "workspace:*",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {}
+}

package/src/file.ts

@@ -0,0 +1,155 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import { Errors, type ResultType, failure, from_promise, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+
+import { parse_yaml, stringify_yaml } from './yaml.js';
+
+/**
+ * Checks if a file exists.
+ */
+export async function file_exists(file_path: string): Promise<boolean> {
+  try {
+    await fs.access(file_path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks if a path is a directory.
+ */
+export async function is_directory(dir_path: string): Promise<boolean> {
+  try {
+    const stats = await fs.stat(dir_path);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reads a file and returns its contents as a string.
+ */
+export async function read_file(
+  file_path: string,
+): Promise<ResultType<string, KustodianErrorType>> {
+  const exists = await file_exists(file_path);
+  if (!exists) {
+    return failure(Errors.file_not_found(file_path));
+  }
+
+  return from_promise(fs.readFile(file_path, 'utf-8'), (error) =>
+    Errors.file_read_error(file_path, error),
+  );
+}
+
+/**
+ * Writes content to a file, creating directories as needed.
+ */
+export async function write_file(
+  file_path: string,
+  content: string,
+): Promise<ResultType<void, KustodianErrorType>> {
+  try {
+    const dir = path.dirname(file_path);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(file_path, content, 'utf-8');
+    return success(undefined);
+  } catch (error) {
+    return failure(Errors.file_write_error(file_path, error));
+  }
+}
+
+/**
+ * Reads a YAML file and parses it.
+ */
+export async function read_yaml_file<T>(
+  file_path: string,
+): Promise<ResultType<T, KustodianErrorType>> {
+  const content_result = await read_file(file_path);
+  if (!content_result.success) {
+    return content_result;
+  }
+
+  return parse_yaml<T>(content_result.value);
+}
+
+/**
+ * Reads a multi-document YAML file and parses it.
+ */
+export async function read_multi_yaml_file<T>(
+  file_path: string,
+): Promise<ResultType<T[], KustodianErrorType>> {
+  const content_result = await read_file(file_path);
+  if (!content_result.success) {
+    return content_result;
+  }
+
+  const { parse_multi_yaml } = await import('./yaml.js');
+  return parse_multi_yaml<T>(content_result.value);
+}
+
+/**
+ * Writes an object to a YAML file.
+ */
+export async function write_yaml_file<T>(
+  file_path: string,
+  data: T,
+): Promise<ResultType<void, KustodianErrorType>> {
+  const yaml_result = stringify_yaml(data);
+  if (!yaml_result.success) {
+    return yaml_result;
+  }
+
+  return write_file(file_path, yaml_result.value);
+}
+
+/**
+ * Lists all files in a directory matching a pattern.
+ */
+export async function list_files(
+  dir_path: string,
+  extension?: string,
+): Promise<ResultType<string[], KustodianErrorType>> {
+  const exists = await is_directory(dir_path);
+  if (!exists) {
+    return failure(Errors.not_found('Directory', dir_path));
+  }
+
+  try {
+    const entries = await fs.readdir(dir_path, { withFileTypes: true });
+    let files = entries.filter((e) => e.isFile()).map((e) => path.join(dir_path, e.name));
+
+    if (extension) {
+      files = files.filter((f) => f.endsWith(extension));
+    }
+
+    return success(files);
+  } catch (error) {
+    return failure(Errors.file_read_error(dir_path, error));
+  }
+}
+
+/**
+ * Lists all subdirectories in a directory.
+ */
+export async function list_directories(
+  dir_path: string,
+): Promise<ResultType<string[], KustodianErrorType>> {
+  const exists = await is_directory(dir_path);
+  if (!exists) {
+    return failure(Errors.not_found('Directory', dir_path));
+  }
+
+  try {
+    const entries = await fs.readdir(dir_path, { withFileTypes: true });
+    const dirs = entries.filter((e) => e.isDirectory()).map((e) => path.join(dir_path, e.name));
+
+    return success(dirs);
+  } catch (error) {
+    return failure(Errors.file_read_error(dir_path, error));
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './yaml.js';
+export * from './file.js';
+export * from './project.js';
+export * from './profile.js';

package/src/profile.ts

@@ -0,0 +1,124 @@
+import * as path from 'node:path';
+
+import { Errors, type ResultType, failure, is_success, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import {
+  type NodeProfileType,
+  node_profile_resource_to_profile,
+  validate_node_profile_resource,
+} from '@kustodian/schema';
+
+import { file_exists, is_directory, list_files, read_multi_yaml_file } from './file.js';
+
+/**
+ * Standard directory name for profiles.
+ */
+export const PROFILES_DIR = 'profiles';
+
+/**
+ * Loaded profile with its source path.
+ */
+export interface LoadedProfileType {
+  path: string;
+  profile: NodeProfileType;
+}
+
+/**
+ * Loads profiles from a single YAML file (supports multi-document).
+ */
+async function load_profiles_from_file(
+  file_path: string,
+): Promise<ResultType<NodeProfileType[], KustodianErrorType>> {
+  const docs_result = await read_multi_yaml_file<unknown>(file_path);
+
+  if (!is_success(docs_result)) {
+    return docs_result;
+  }
+
+  const profiles: NodeProfileType[] = [];
+  const errors: string[] = [];
+
+  for (const doc of docs_result.value) {
+    const validation = validate_node_profile_resource(doc);
+    if (!validation.success) {
+      const validation_errors = validation.error.issues.map(
+        (issue) => `${issue.path.join('.')}: ${issue.message}`,
+      );
+      errors.push(`${path.basename(file_path)}:\n  ${validation_errors.join('\n  ')}`);
+      continue;
+    }
+
+    profiles.push(node_profile_resource_to_profile(validation.data));
+  }
+
+  if (errors.length > 0) {
+    return failure(Errors.validation_error(`Failed to load profiles:\n${errors.join('\n')}`));
+  }
+
+  return success(profiles);
+}
+
+/**
+ * Loads all profiles from the profiles directory.
+ */
+export async function load_all_profiles(
+  project_root: string,
+): Promise<ResultType<Map<string, NodeProfileType>, KustodianErrorType>> {
+  const profiles_dir = path.join(project_root, PROFILES_DIR);
+  const profiles_map = new Map<string, NodeProfileType>();
+
+  // Return empty map if profiles directory doesn't exist
+  if (!(await file_exists(profiles_dir))) {
+    return success(profiles_map);
+  }
+
+  if (!(await is_directory(profiles_dir))) {
+    return success(profiles_map);
+  }
+
+  const errors: string[] = [];
+
+  // Load all YAML files from directory
+  const yml_files = await list_files(profiles_dir, '.yml');
+  const yaml_files = await list_files(profiles_dir, '.yaml');
+
+  const all_files = [
+    ...(is_success(yml_files) ? yml_files.value : []),
+    ...(is_success(yaml_files) ? yaml_files.value : []),
+  ];
+
+  for (const file_path of all_files) {
+    const result = await load_profiles_from_file(file_path);
+    if (is_success(result)) {
+      for (const profile of result.value) {
+        if (profiles_map.has(profile.name)) {
+          errors.push(`Duplicate profile name: ${profile.name}`);
+          continue;
+        }
+        profiles_map.set(profile.name, profile);
+      }
+    } else {
+      errors.push(result.error.message);
+    }
+  }
+
+  if (errors.length > 0) {
+    return failure(Errors.validation_error(`Failed to load profiles:\n${errors.join('\n')}`));
+  }
+
+  return success(profiles_map);
+}
+
+/**
+ * Gets a profile by name from a profiles map.
+ */
+export function get_profile(
+  profiles: Map<string, NodeProfileType>,
+  name: string,
+): ResultType<NodeProfileType, KustodianErrorType> {
+  const profile = profiles.get(name);
+  if (!profile) {
+    return failure(Errors.profile_not_found(name));
+  }
+  return success(profile);
+}

package/src/project.ts

@@ -0,0 +1,348 @@
+import * as path from 'node:path';
+
+import { Errors, type ResultType, failure, is_success, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import {
+  type ClusterType,
+  type NodeProfileType,
+  type NodeSchemaType,
+  type TemplateType,
+  node_resource_to_node,
+  validate_cluster,
+  validate_node_resource,
+  validate_template,
+} from '@kustodian/schema';
+
+import { file_exists, list_directories, list_files, read_yaml_file } from './file.js';
+import { load_all_profiles } from './profile.js';
+
+/**
+ * Standard file names used in Kustodian projects.
+ */
+export const StandardFiles = {
+  TEMPLATE: 'template.yaml',
+  CLUSTER: 'cluster.yaml',
+  NODES: 'nodes.yaml',
+  PROJECT: 'kustodian.yaml',
+} as const;
+
+/**
+ * Standard directory names used in Kustodian projects.
+ */
+export const StandardDirs = {
+  TEMPLATES: 'templates',
+  CLUSTERS: 'clusters',
+  NODES: 'nodes',
+  PROFILES: 'profiles',
+} as const;
+
+/**
+ * Loaded template with its source path.
+ */
+export interface LoadedTemplateType {
+  path: string;
+  template: TemplateType;
+}
+
+/**
+ * Loaded cluster with its source path.
+ */
+export interface LoadedClusterType {
+  path: string;
+  cluster: ClusterType;
+  nodes: NodeSchemaType[];
+}
+
+/**
+ * A fully loaded Kustodian project.
+ */
+export interface ProjectType {
+  root: string;
+  templates: LoadedTemplateType[];
+  clusters: LoadedClusterType[];
+  profiles: Map<string, NodeProfileType>;
+}
+
+/**
+ * Finds the project root by looking for kustodian.yaml.
+ */
+export async function find_project_root(
+  start_path: string,
+): Promise<ResultType<string, KustodianErrorType>> {
+  let current = path.resolve(start_path);
+  const root = path.parse(current).root;
+
+  while (current !== root) {
+    const project_file = path.join(current, StandardFiles.PROJECT);
+    if (await file_exists(project_file)) {
+      return success(current);
+    }
+    current = path.dirname(current);
+  }
+
+  return failure(
+    Errors.config_not_found('Project', `${StandardFiles.PROJECT} not found in parent directories`),
+  );
+}
+
+/**
+ * Loads a single template from its directory.
+ */
+export async function load_template(
+  template_dir: string,
+): Promise<ResultType<LoadedTemplateType, KustodianErrorType>> {
+  const template_path = path.join(template_dir, StandardFiles.TEMPLATE);
+  const yaml_result = await read_yaml_file<unknown>(template_path);
+
+  if (!is_success(yaml_result)) {
+    return yaml_result;
+  }
+
+  const validation = validate_template(yaml_result.value);
+  if (!validation.success) {
+    const errors = validation.error.issues.map(
+      (issue) => `${issue.path.join('.')}: ${issue.message}`,
+    );
+    return failure(Errors.schema_validation_error(errors));
+  }
+
+  return success({
+    path: template_dir,
+    template: validation.data,
+  });
+}
+
+/**
+ * Loads nodes from a single YAML file (supports multi-document).
+ */
+async function load_nodes_from_file(
+  file_path: string,
+): Promise<ResultType<NodeSchemaType[], KustodianErrorType>> {
+  const { read_multi_yaml_file } = await import('./file.js');
+  const docs_result = await read_multi_yaml_file<unknown>(file_path);
+
+  if (!is_success(docs_result)) {
+    return docs_result;
+  }
+
+  const nodes: NodeSchemaType[] = [];
+  const errors: string[] = [];
+
+  for (const doc of docs_result.value) {
+    const validation = validate_node_resource(doc);
+    if (!validation.success) {
+      const validation_errors = validation.error.issues.map(
+        (issue) => `${issue.path.join('.')}: ${issue.message}`,
+      );
+      errors.push(`${path.basename(file_path)}:\n  ${validation_errors.join('\n  ')}`);
+      continue;
+    }
+
+    nodes.push(node_resource_to_node(validation.data));
+  }
+
+  if (errors.length > 0) {
+    return failure(Errors.validation_error(`Failed to load nodes:\n${errors.join('\n')}`));
+  }
+
+  return success(nodes);
+}
+
+/**
+ * Loads all node files from specified paths (files or directories).
+ */
+export async function load_cluster_nodes(
+  cluster_dir: string,
+  node_file_paths?: string[],
+): Promise<ResultType<NodeSchemaType[], KustodianErrorType>> {
+  const nodes: NodeSchemaType[] = [];
+  const errors: string[] = [];
+
+  // If no paths specified, try default nodes/ directory
+  const paths_to_scan = node_file_paths || [StandardDirs.NODES];
+
+  for (const ref_path of paths_to_scan) {
+    const full_path = path.isAbsolute(ref_path) ? ref_path : path.join(cluster_dir, ref_path);
+
+    // Check if it's a directory
+    const { is_directory } = await import('./file.js');
+    if (await is_directory(full_path)) {
+      // Load all YAML files from directory
+      const yml_files = await list_files(full_path, '.yml');
+      const yaml_files = await list_files(full_path, '.yaml');
+
+      const all_files = [
+        ...(is_success(yml_files) ? yml_files.value : []),
+        ...(is_success(yaml_files) ? yaml_files.value : []),
+      ];
+
+      for (const file_path of all_files) {
+        const result = await load_nodes_from_file(file_path);
+        if (is_success(result)) {
+          nodes.push(...result.value);
+        } else {
+          errors.push(result.error.message);
+        }
+      }
+    } else if (await file_exists(full_path)) {
+      // Load single file (may contain multiple documents)
+      const result = await load_nodes_from_file(full_path);
+      if (is_success(result)) {
+        nodes.push(...result.value);
+      } else {
+        errors.push(result.error.message);
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return failure(Errors.validation_error(`Failed to load nodes:\n${errors.join('\n')}`));
+  }
+
+  return success(nodes);
+}
+
+/**
+ * Loads a single cluster from its directory.
+ */
+export async function load_cluster(
+  cluster_dir: string,
+): Promise<ResultType<LoadedClusterType, KustodianErrorType>> {
+  const cluster_path = path.join(cluster_dir, StandardFiles.CLUSTER);
+  const yaml_result = await read_yaml_file<unknown>(cluster_path);
+
+  if (!is_success(yaml_result)) {
+    return yaml_result;
+  }
+
+  const validation = validate_cluster(yaml_result.value);
+  if (!validation.success) {
+    const errors = validation.error.issues.map(
+      (issue) => `${issue.path.join('.')}: ${issue.message}`,
+    );
+    return failure(Errors.schema_validation_error(errors));
+  }
+
+  // Load nodes from specified paths or default nodes/ directory
+  const node_file_paths = validation.data.spec.nodes;
+  const nodes_result = await load_cluster_nodes(cluster_dir, node_file_paths);
+  if (!is_success(nodes_result)) {
+    return nodes_result;
+  }
+
+  return success({
+    path: cluster_dir,
+    cluster: validation.data,
+    nodes: nodes_result.value,
+  });
+}
+
+/**
+ * Loads all templates from the templates directory.
+ */
+export async function load_all_templates(
+  project_root: string,
+): Promise<ResultType<LoadedTemplateType[], KustodianErrorType>> {
+  const templates_dir = path.join(project_root, StandardDirs.TEMPLATES);
+  const dirs_result = await list_directories(templates_dir);
+
+  if (!is_success(dirs_result)) {
+    // Return empty array if templates directory doesn't exist
+    if (dirs_result.error.code === 'NOT_FOUND') {
+      return success([]);
+    }
+    return dirs_result;
+  }
+
+  const templates: LoadedTemplateType[] = [];
+  const errors: string[] = [];
+
+  for (const dir of dirs_result.value) {
+    const result = await load_template(dir);
+    if (is_success(result)) {
+      templates.push(result.value);
+    } else {
+      errors.push(`${path.basename(dir)}: ${result.error.message}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return failure(Errors.validation_error(`Failed to load templates:\n${errors.join('\n')}`));
+  }
+
+  return success(templates);
+}
+
+/**
+ * Loads all clusters from the clusters directory.
+ */
+export async function load_all_clusters(
+  project_root: string,
+): Promise<ResultType<LoadedClusterType[], KustodianErrorType>> {
+  const clusters_dir = path.join(project_root, StandardDirs.CLUSTERS);
+  const dirs_result = await list_directories(clusters_dir);
+
+  if (!is_success(dirs_result)) {
+    // Return empty array if clusters directory doesn't exist
+    if (dirs_result.error.code === 'NOT_FOUND') {
+      return success([]);
+    }
+    return dirs_result;
+  }
+
+  const clusters: LoadedClusterType[] = [];
+  const errors: string[] = [];
+
+  for (const dir of dirs_result.value) {
+    const result = await load_cluster(dir);
+    if (is_success(result)) {
+      clusters.push(result.value);
+    } else {
+      errors.push(`${path.basename(dir)}: ${result.error.message}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return failure(Errors.validation_error(`Failed to load clusters:\n${errors.join('\n')}`));
+  }
+
+  return success(clusters);
+}
+
+/**
+ * Loads a complete Kustodian project.
+ */
+export async function load_project(
+  project_root: string,
+): Promise<ResultType<ProjectType, KustodianErrorType>> {
+  // Verify project exists
+  const project_file = path.join(project_root, StandardFiles.PROJECT);
+  if (!(await file_exists(project_file))) {
+    return failure(Errors.config_not_found('Project', project_file));
+  }
+
+  // Load profiles first (they may be referenced by nodes)
+  const profiles_result = await load_all_profiles(project_root);
+  if (!is_success(profiles_result)) {
+    return profiles_result;
+  }
+
+  // Load templates
+  const templates_result = await load_all_templates(project_root);
+  if (!is_success(templates_result)) {
+    return templates_result;
+  }
+
+  // Load clusters
+  const clusters_result = await load_all_clusters(project_root);
+  if (!is_success(clusters_result)) {
+    return clusters_result;
+  }
+
+  return success({
+    root: project_root,
+    templates: templates_result.value,
+    clusters: clusters_result.value,
+    profiles: profiles_result.value,
+  });
+}

package/src/yaml.ts

@@ -0,0 +1,50 @@
+import { Errors, type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import { parse, parseAllDocuments, stringify } from 'yaml';
+
+/**
+ * Parses a YAML string into an object.
+ */
+export function parse_yaml<T>(content: string): ResultType<T, KustodianErrorType> {
+  try {
+    const result = parse(content) as T;
+    return success(result);
+  } catch (error) {
+    return failure(
+      Errors.yaml_parse_error(error instanceof Error ? error.message : String(error), error),
+    );
+  }
+}
+
+/**
+ * Parses a multi-document YAML string (separated by ---) into an array of objects.
+ */
+export function parse_multi_yaml<T>(content: string): ResultType<T[], KustodianErrorType> {
+  try {
+    const docs = parseAllDocuments(content);
+    const results = docs.map((doc) => doc.toJSON() as T);
+    return success(results);
+  } catch (error) {
+    return failure(
+      Errors.yaml_parse_error(error instanceof Error ? error.message : String(error), error),
+    );
+  }
+}
+
+/**
+ * Converts an object to a YAML string.
+ */
+export function stringify_yaml<T>(data: T): ResultType<string, KustodianErrorType> {
+  try {
+    const result = stringify(data, {
+      indent: 2,
+      lineWidth: 0,
+      singleQuote: false,
+    });
+    return success(result);
+  } catch (error) {
+    return failure(
+      Errors.parse_error('YAML', error instanceof Error ? error.message : String(error), error),
+    );
+  }
+}