@kustodian/schema 1.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@kustodian/schema",
+  "version": "1.0.0",
+  "description": "JSON Schema definitions for Kustodian YAML validation",
+  "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",
+    "schema",
+    "validation",
+    "zod"
+  ],
+  "author": "Luca Silverentand <luca@onezero.company>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lucasilverentand/kustodian.git",
+    "directory": "packages/schema"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "dependencies": {
+    "zod": "^3.25.30"
+  },
+  "devDependencies": {}
+}

package/src/cluster.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+
+import { api_version_schema, metadata_schema, values_schema } from './common.js';
+import { ssh_config_schema } from './node-list.js';
+
+/**
+ * Git repository configuration for a cluster.
+ */
+export const git_config_schema = z.object({
+  owner: z.string().min(1),
+  repository: z.string().min(1),
+  branch: z.string().min(1).optional().default('main'),
+  path: z.string().optional(),
+});
+
+export type GitConfigType = z.infer<typeof git_config_schema>;
+
+/**
+ * OCI repository configuration for a cluster.
+ */
+export const oci_config_schema = z.object({
+  registry: z.string().min(1),
+  repository: z.string().min(1),
+  tag_strategy: z.enum(['cluster', 'git-sha', 'version', 'manual']).optional().default('git-sha'),
+  tag: z.string().optional(),
+  secret_ref: z.string().optional(),
+  provider: z.enum(['aws', 'azure', 'gcp', 'generic']).optional().default('generic'),
+  insecure: z.boolean().optional().default(false),
+});
+
+export type OciConfigType = z.infer<typeof oci_config_schema>;
+
+/**
+ * Template enablement configuration within a cluster.
+ */
+export const template_config_schema = z.object({
+  name: z.string().min(1),
+  enabled: z.boolean().optional().default(true),
+  values: values_schema.optional(),
+});
+
+export type TemplateConfigType = z.infer<typeof template_config_schema>;
+
+/**
+ * Plugin configuration within a cluster.
+ */
+export const plugin_config_schema = z.object({
+  name: z.string().min(1),
+  config: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type PluginConfigType = z.infer<typeof plugin_config_schema>;
+
+/**
+ * Node defaults configuration within a cluster.
+ */
+export const node_defaults_schema = z.object({
+  label_prefix: z.string().optional(),
+  ssh: ssh_config_schema.optional(),
+});
+
+export type NodeDefaultsType = z.infer<typeof node_defaults_schema>;
+
+/**
+ * GitHub repository configuration for GitOps metadata.
+ */
+export const github_config_schema = z.object({
+  organization: z.string().min(1),
+  repository: z.string().min(1),
+  branch: z.string().min(1).optional().default('main'),
+});
+
+export type GithubConfigType = z.infer<typeof github_config_schema>;
+
+/**
+ * Cluster specification.
+ */
+export const cluster_spec_schema = z
+  .object({
+    code: z.string().min(1).optional(),
+    domain: z.string().min(1),
+    git: git_config_schema.optional(),
+    oci: oci_config_schema.optional(),
+    github: github_config_schema.optional(),
+    templates: z.array(template_config_schema).optional(),
+    plugins: z.array(plugin_config_schema).optional(),
+    node_defaults: node_defaults_schema.optional(),
+    nodes: z.array(z.string()).optional(),
+  })
+  .refine((data) => data.git || data.oci, {
+    message: "Either 'git' or 'oci' must be specified",
+  });
+
+export type ClusterSpecType = z.infer<typeof cluster_spec_schema>;
+
+/**
+ * Complete Cluster resource definition.
+ */
+export const cluster_schema = z.object({
+  apiVersion: api_version_schema,
+  kind: z.literal('Cluster'),
+  metadata: metadata_schema,
+  spec: cluster_spec_schema,
+});
+
+export type ClusterType = z.infer<typeof cluster_schema>;
+
+/**
+ * Validates a cluster object and returns the result.
+ */
+export function validate_cluster(data: unknown): z.SafeParseReturnType<unknown, ClusterType> {
+  return cluster_schema.safeParse(data);
+}

package/src/common.ts

@@ -0,0 +1,181 @@
+import { z } from 'zod';
+
+/**
+ * Common API version for all Kustodian resources.
+ */
+export const api_version_schema = z.literal('kustodian.io/v1');
+
+/**
+ * Standard metadata for all Kustodian resources.
+ */
+export const metadata_schema = z.object({
+  name: z.string().min(1),
+});
+
+export type MetadataType = z.infer<typeof metadata_schema>;
+
+/**
+ * Health check configuration for waiting on resources.
+ */
+export const health_check_schema = z.object({
+  kind: z.string().min(1),
+  name: z.string().min(1),
+  namespace: z.string().min(1).optional(),
+});
+
+export type HealthCheckType = z.infer<typeof health_check_schema>;
+
+/**
+ * Registry configuration for version substitutions.
+ */
+export const registry_config_schema = z.object({
+  /** Full image reference: registry/namespace/image or just namespace/image for Docker Hub */
+  image: z.string().min(1),
+  /** Registry type for API selection */
+  type: z.enum(['dockerhub', 'ghcr']).optional(),
+});
+
+export type RegistryConfigType = z.infer<typeof registry_config_schema>;
+
+/**
+ * Generic substitution (backward compatible, default type).
+ */
+export const generic_substitution_schema = z.object({
+  type: z.literal('generic').optional(),
+  name: z.string().min(1),
+  default: z.string().optional(),
+  secret: z.string().optional(),
+});
+
+export type GenericSubstitutionType = z.infer<typeof generic_substitution_schema>;
+
+/**
+ * Version substitution for tracking container image versions.
+ */
+export const version_substitution_schema = z.object({
+  type: z.literal('version'),
+  name: z.string().min(1),
+  default: z.string().optional(),
+  /** Semver constraint: ^1.0.0, ~2.3.0, >=1.0.0 <2.0.0 */
+  constraint: z.string().optional(),
+  /** Registry configuration for fetching available versions */
+  registry: registry_config_schema,
+  /** Regex pattern for filtering valid tags (default: semver-like) */
+  tag_pattern: z.string().optional(),
+  /** Exclude pre-release versions (default: true) */
+  exclude_prerelease: z.boolean().optional(),
+});
+
+export type VersionSubstitutionType = z.infer<typeof version_substitution_schema>;
+
+/**
+ * Namespace substitution with Kubernetes naming validation.
+ */
+export const namespace_substitution_schema = z.object({
+  type: z.literal('namespace'),
+  name: z.string().min(1),
+  default: z.string().optional(),
+});
+
+export type NamespaceSubstitutionType = z.infer<typeof namespace_substitution_schema>;
+
+/**
+ * 1Password substitution for fetching secrets from 1Password vaults.
+ * Uses the op:// secret reference format.
+ */
+export const onepassword_substitution_schema = z.object({
+  type: z.literal('1password'),
+  name: z.string().min(1),
+  /** 1Password secret reference: op://vault/item[/section]/field */
+  ref: z.string().min(1),
+  /** Optional default value if secret cannot be fetched */
+  default: z.string().optional(),
+});
+
+export type OnePasswordSubstitutionType = z.infer<typeof onepassword_substitution_schema>;
+
+/**
+ * Doppler substitution for fetching secrets from Doppler projects.
+ */
+export const doppler_substitution_schema = z.object({
+  type: z.literal('doppler'),
+  name: z.string().min(1),
+  /** Doppler project name */
+  project: z.string().min(1),
+  /** Doppler config name (e.g., 'dev', 'stg', 'prd') */
+  config: z.string().min(1),
+  /** Secret key name in Doppler */
+  secret: z.string().min(1),
+  /** Optional default value if secret cannot be fetched */
+  default: z.string().optional(),
+});
+
+export type DopplerSubstitutionType = z.infer<typeof doppler_substitution_schema>;
+
+/**
+ * Union of all substitution types.
+ * Supports backward compatibility: substitutions without 'type' are treated as generic.
+ */
+export const substitution_schema = z.union([
+  version_substitution_schema,
+  namespace_substitution_schema,
+  onepassword_substitution_schema,
+  doppler_substitution_schema,
+  generic_substitution_schema, // Must be last due to optional 'type' field
+]);
+
+export type SubstitutionType = z.infer<typeof substitution_schema>;
+
+/**
+ * Type guard for version substitutions.
+ */
+export function is_version_substitution(sub: SubstitutionType): sub is VersionSubstitutionType {
+  return 'type' in sub && sub.type === 'version';
+}
+
+/**
+ * Type guard for namespace substitutions.
+ */
+export function is_namespace_substitution(sub: SubstitutionType): sub is NamespaceSubstitutionType {
+  return 'type' in sub && sub.type === 'namespace';
+}
+
+/**
+ * Type guard for generic substitutions.
+ */
+export function is_generic_substitution(sub: SubstitutionType): sub is GenericSubstitutionType {
+  return !('type' in sub) || sub.type === 'generic' || sub.type === undefined;
+}
+
+/**
+ * Type guard for 1Password substitutions.
+ */
+export function is_onepassword_substitution(
+  sub: SubstitutionType,
+): sub is OnePasswordSubstitutionType {
+  return 'type' in sub && sub.type === '1password';
+}
+
+/**
+ * Type guard for Doppler substitutions.
+ */
+export function is_doppler_substitution(sub: SubstitutionType): sub is DopplerSubstitutionType {
+  return 'type' in sub && sub.type === 'doppler';
+}
+
+/**
+ * Namespace configuration with fallback behavior.
+ */
+export const namespace_config_schema = z.object({
+  default: z.string().min(1),
+  create: z.boolean().optional().default(true),
+});
+
+export type NamespaceConfigType = z.infer<typeof namespace_config_schema>;
+
+/**
+ * Key-value pairs for substitution values.
+ */
+export const values_schema = z.record(z.string(), z.string());
+
+export type ValuesType = z.infer<typeof values_schema>;

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './template.js';
+export * from './cluster.js';
+export * from './common.js';
+export * from './node-list.js';
+export * from './profile.js';

package/src/node-list.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+
+import { api_version_schema } from './common.js';
+
+/**
+ * SSH configuration schema.
+ */
+export const ssh_config_schema = z.object({
+  user: z.string().optional(),
+  key_path: z.string().optional(),
+  known_hosts_path: z.string().optional(),
+  port: z.number().int().positive().optional(),
+});
+
+export type SshConfigSchemaType = z.infer<typeof ssh_config_schema>;
+
+/**
+ * Kubernetes taint effect.
+ */
+export const taint_effect_schema = z.enum(['NoSchedule', 'PreferNoSchedule', 'NoExecute']);
+
+export type TaintEffectType = z.infer<typeof taint_effect_schema>;
+
+/**
+ * Kubernetes taint schema.
+ */
+export const taint_schema = z.object({
+  key: z.string().min(1),
+  value: z.string().optional(),
+  effect: taint_effect_schema,
+});
+
+export type TaintSchemaType = z.infer<typeof taint_schema>;
+
+/**
+ * Node role in the cluster.
+ */
+export const node_role_schema = z.enum(['controller', 'worker', 'controller+worker']);
+
+export type NodeRoleType = z.infer<typeof node_role_schema>;
+
+/**
+ * Single node definition schema (for inline use in NodeList).
+ */
+export const node_schema = z.object({
+  name: z.string().min(1),
+  role: node_role_schema,
+  address: z.string().min(1),
+  profile: z.string().min(1).optional(),
+  ssh: ssh_config_schema.optional(),
+  labels: z.record(z.union([z.string(), z.boolean(), z.number()])).optional(),
+  taints: z.array(taint_schema).optional(),
+  annotations: z.record(z.string()).optional(),
+});
+
+export type NodeSchemaType = z.infer<typeof node_schema>;
+
+/**
+ * Node metadata schema (for standalone Node resources).
+ */
+export const node_metadata_schema = z.object({
+  name: z.string().min(1),
+  cluster: z.string().min(1),
+});
+
+export type NodeMetadataType = z.infer<typeof node_metadata_schema>;
+
+/**
+ * Node spec schema (for standalone Node resources).
+ */
+export const node_spec_schema = z.object({
+  role: node_role_schema,
+  address: z.string().min(1),
+  profile: z.string().min(1).optional(),
+  ssh: ssh_config_schema.optional(),
+  labels: z.record(z.union([z.string(), z.boolean(), z.number()])).optional(),
+  taints: z.array(taint_schema).optional(),
+  annotations: z.record(z.string()).optional(),
+});
+
+export type NodeSpecType = z.infer<typeof node_spec_schema>;
+
+/**
+ * Standalone Node resource definition.
+ * Used for individual node files at clusters/<cluster>/nodes/<node>.yml
+ */
+export const node_resource_schema = z.object({
+  apiVersion: api_version_schema,
+  kind: z.literal('Node'),
+  metadata: node_metadata_schema,
+  spec: node_spec_schema,
+});
+
+export type NodeResourceType = z.infer<typeof node_resource_schema>;
+
+/**
+ * Validates a Node resource and returns the result.
+ */
+export function validate_node_resource(
+  data: unknown,
+): z.SafeParseReturnType<unknown, NodeResourceType> {
+  return node_resource_schema.safeParse(data);
+}
+
+/**
+ * Converts a Node resource to a NodeType for internal use.
+ */
+export function node_resource_to_node(resource: NodeResourceType): NodeSchemaType {
+  const node: NodeSchemaType = {
+    name: resource.metadata.name,
+    role: resource.spec.role,
+    address: resource.spec.address,
+  };
+
+  if (resource.spec.profile !== undefined) {
+    node.profile = resource.spec.profile;
+  }
+  if (resource.spec.ssh !== undefined) {
+    node.ssh = resource.spec.ssh;
+  }
+  if (resource.spec.labels !== undefined) {
+    node.labels = resource.spec.labels;
+  }
+  if (resource.spec.taints !== undefined) {
+    node.taints = resource.spec.taints;
+  }
+  if (resource.spec.annotations !== undefined) {
+    node.annotations = resource.spec.annotations;
+  }
+
+  return node;
+}
+
+// NodeList is no longer a schema kind - it's just an internal construct
+// Nodes are defined as individual Node resources and aggregated in code

package/src/profile.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+
+import { api_version_schema } from './common.js';
+import { taint_schema } from './node-list.js';
+
+/**
+ * Node profile specification schema.
+ * Defines reusable configuration for labels, taints, and annotations.
+ */
+export const node_profile_spec_schema = z.object({
+  name: z.string().min(1).optional(),
+  description: z.string().optional(),
+  labels: z.record(z.union([z.string(), z.boolean(), z.number()])).optional(),
+  taints: z.array(taint_schema).optional(),
+  annotations: z.record(z.string()).optional(),
+});
+
+export type NodeProfileSpecType = z.infer<typeof node_profile_spec_schema>;
+
+/**
+ * Node profile metadata schema.
+ */
+export const node_profile_metadata_schema = z.object({
+  name: z.string().min(1),
+});
+
+export type NodeProfileMetadataType = z.infer<typeof node_profile_metadata_schema>;
+
+/**
+ * Standalone NodeProfile resource definition.
+ * Used for profile files at profiles/<profile-name>.yaml
+ */
+export const node_profile_resource_schema = z.object({
+  apiVersion: api_version_schema,
+  kind: z.literal('NodeProfile'),
+  metadata: node_profile_metadata_schema,
+  spec: node_profile_spec_schema,
+});
+
+export type NodeProfileResourceType = z.infer<typeof node_profile_resource_schema>;
+
+/**
+ * Validates a NodeProfile resource and returns the result.
+ */
+export function validate_node_profile_resource(
+  data: unknown,
+): z.SafeParseReturnType<unknown, NodeProfileResourceType> {
+  return node_profile_resource_schema.safeParse(data);
+}
+
+/**
+ * Internal node profile type for use after loading.
+ */
+export interface NodeProfileType {
+  name: string;
+  display_name?: string;
+  description?: string;
+  labels?: Record<string, string | boolean | number>;
+  taints?: z.infer<typeof taint_schema>[];
+  annotations?: Record<string, string>;
+}
+
+/**
+ * Converts a NodeProfile resource to a NodeProfileType for internal use.
+ */
+export function node_profile_resource_to_profile(
+  resource: NodeProfileResourceType,
+): NodeProfileType {
+  const profile: NodeProfileType = {
+    name: resource.metadata.name,
+  };
+
+  if (resource.spec.name !== undefined) {
+    profile.display_name = resource.spec.name;
+  }
+  if (resource.spec.description !== undefined) {
+    profile.description = resource.spec.description;
+  }
+  if (resource.spec.labels !== undefined) {
+    profile.labels = resource.spec.labels;
+  }
+  if (resource.spec.taints !== undefined) {
+    profile.taints = resource.spec.taints;
+  }
+  if (resource.spec.annotations !== undefined) {
+    profile.annotations = resource.spec.annotations;
+  }
+
+  return profile;
+}

package/src/template.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+import {
+  api_version_schema,
+  health_check_schema,
+  metadata_schema,
+  namespace_config_schema,
+  substitution_schema,
+} from './common.js';
+
+/**
+ * A single kustomization within a template.
+ * Maps to a Flux Kustomization resource.
+ */
+export const kustomization_schema = z.object({
+  name: z.string().min(1),
+  path: z.string().min(1),
+  namespace: namespace_config_schema.optional(),
+  depends_on: z.array(z.string()).optional(),
+  substitutions: z.array(substitution_schema).optional(),
+  health_checks: z.array(health_check_schema).optional(),
+  prune: z.boolean().optional().default(true),
+  wait: z.boolean().optional().default(true),
+  timeout: z.string().optional(),
+  retry_interval: z.string().optional(),
+});
+
+export type KustomizationType = z.infer<typeof kustomization_schema>;
+
+/**
+ * Template specification containing kustomizations.
+ */
+export const template_spec_schema = z.object({
+  kustomizations: z.array(kustomization_schema).min(1),
+});
+
+export type TemplateSpecType = z.infer<typeof template_spec_schema>;
+
+/**
+ * Complete Template resource definition.
+ */
+export const template_schema = z.object({
+  apiVersion: api_version_schema,
+  kind: z.literal('Template'),
+  metadata: metadata_schema,
+  spec: template_spec_schema,
+});
+
+export type TemplateType = z.infer<typeof template_schema>;
+
+/**
+ * Validates a template object and returns the result.
+ */
+export function validate_template(data: unknown): z.SafeParseReturnType<unknown, TemplateType> {
+  return template_schema.safeParse(data);
+}