@kustodian/registry 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @kustodian/registry
+
+Container registry client for fetching image tags from Docker Hub and GitHub Container Registry (GHCR).
+
+## Installation
+
+```bash
+bun add @kustodian/registry
+```
+
+## API
+
+### Client Functions
+
+- **`parse_image_reference(image: string)`** - Parse an image string into its components (registry, namespace, repository, tag)
+- **`detect_registry_type(image)`** - Auto-detect registry type from an image reference
+- **`create_registry_client(type, config?)`** - Create a client for a specific registry type
+- **`create_client_for_image(image)`** - Create a client with auto-detected type and authentication
+- **`create_dockerhub_client(config?)`** - Create a Docker Hub client
+- **`create_ghcr_client(config?)`** - Create a GitHub Container Registry client
+
+### Authentication
+
+- **`get_dockerhub_auth()`** - Get Docker Hub auth from `DOCKER_USERNAME` and `DOCKER_PASSWORD`
+- **`get_ghcr_auth()`** - Get GHCR auth from `GITHUB_TOKEN` or `GH_TOKEN`
+- **`get_auth_for_registry(registry)`** - Get auth for a registry by hostname
+
+### Version Utilities
+
+- **`filter_semver_tags(tags, options?)`** - Filter tags to semver-valid versions
+- **`find_latest_matching(versions, constraint?)`** - Find the latest version matching a constraint
+- **`check_version_update(current, available, constraint?)`** - Check if a newer version is available
+- **`DEFAULT_SEMVER_PATTERN`** - Default regex for semver-like tags
+
+### Types
+
+- `ImageReferenceType` - Parsed image reference components
+- `RegistryAuthType` - Authentication configuration
+- `RegistryClientType` - Registry client interface
+- `RegistryClientConfigType` - Client configuration options
+- `TagInfoType` - Tag information from registry
+- `VersionCheckResultType` - Version check result
+
+## Usage
+
+```typescript
+import {
+  parse_image_reference,
+  create_client_for_image,
+  filter_semver_tags,
+  check_version_update,
+} from '@kustodian/registry';
+
+// Parse image reference
+const image = parse_image_reference('ghcr.io/org/app:v1.0.0');
+
+// Create client and fetch tags
+const client = create_client_for_image(image);
+const result = await client.list_tags(image);
+
+if (result.success) {
+  // Filter to semver tags and check for updates
+  const versions = filter_semver_tags(result.value);
+  const update = check_version_update('1.0.0', versions);
+
+  if (update.has_update) {
+    console.log(`Update available: ${update.latest_version}`);
+  }
+}
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Repository](https://github.com/lucasilverentand/kustodian)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kustodian/registry",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Container registry client for fetching image tags from Docker Hub and GHCR",
   "type": "module",
   "main": "./src/index.ts",
@@ -37,8 +37,9 @@
     "registry": "https://npm.pkg.github.com"
   },
   "dependencies": {
-    "@kustodian/core": "workspace:*",
-    "semver": "^7.6.0"
+    "@kustodian/core": "1.1.0",
+    "semver": "^7.6.0",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/semver": "^7.5.0"

package/src/helm.ts

@@ -0,0 +1,179 @@
+import { type ResultType, failure, success } from '@kustodian/core';
+import type { KustodianErrorType } from '@kustodian/core';
+import { parse } from 'yaml';
+import { create_ghcr_client } from './ghcr.js';
+import type {
+  ImageReferenceType,
+  RegistryClientConfigType,
+  RegistryClientType,
+  TagInfoType,
+} from './types.js';
+
+const DEFAULT_TIMEOUT = 30000;
+
+/**
+ * Helm index.yaml entry structure.
+ */
+interface HelmChartEntry {
+  name: string;
+  version: string;
+  created?: string;
+  description?: string;
+  digest?: string;
+}
+
+/**
+ * Helm index.yaml structure.
+ */
+interface HelmIndexType {
+  apiVersion: string;
+  entries: Record<string, HelmChartEntry[]>;
+  generated?: string;
+}
+
+/**
+ * Creates an abort signal with timeout.
+ */
+function create_abort_signal(timeout_ms: number): AbortSignal {
+  const controller = new AbortController();
+  setTimeout(() => controller.abort(), timeout_ms);
+  return controller.signal;
+}
+
+/**
+ * Fetches and parses a Helm repository index.yaml file.
+ */
+async function fetch_helm_index(
+  repository_url: string,
+  config?: RegistryClientConfigType,
+): Promise<ResultType<HelmIndexType, KustodianErrorType>> {
+  // Ensure URL doesn't have trailing slash
+  const base_url = repository_url.replace(/\/$/, '');
+  const index_url = `${base_url}/index.yaml`;
+
+  try {
+    const response = await fetch(index_url, {
+      signal: create_abort_signal(config?.timeout ?? DEFAULT_TIMEOUT),
+    });
+
+    if (!response.ok) {
+      return failure({
+        code: 'HELM_REPO_ERROR',
+        message: `Failed to fetch Helm index: ${response.status} ${response.statusText}`,
+      });
+    }
+
+    const content = await response.text();
+    const index = parse(content) as HelmIndexType;
+
+    if (!index.entries) {
+      return failure({
+        code: 'HELM_REPO_ERROR',
+        message: 'Invalid Helm index: missing entries',
+      });
+    }
+
+    return success(index);
+  } catch (error) {
+    return failure({
+      code: 'HELM_REPO_ERROR',
+      message: `Failed to fetch Helm index: ${error instanceof Error ? error.message : String(error)}`,
+    });
+  }
+}
+
+/**
+ * Parses an OCI Helm reference into components.
+ * Example: oci://ghcr.io/traefik/helm/traefik -> {registry: ghcr.io, namespace: traefik/helm, repository: traefik}
+ */
+function parse_oci_helm_reference(oci_url: string, chart_name: string): ImageReferenceType {
+  // Remove oci:// prefix
+  const url_without_prefix = oci_url.replace(/^oci:\/\//, '');
+
+  // Split into parts
+  const parts = url_without_prefix.split('/');
+
+  if (parts.length < 2) {
+    // Fallback for invalid format
+    return {
+      registry: parts[0] || 'ghcr.io',
+      namespace: 'library',
+      repository: chart_name,
+    };
+  }
+
+  // First part is registry
+  const registry = parts[0] || 'ghcr.io';
+
+  // Everything except first part and last part (if it matches chart name) is namespace
+  const last_part = parts[parts.length - 1];
+  let namespace: string;
+
+  if (last_part === chart_name && parts.length > 2) {
+    // If last part is the chart name, use everything in between as namespace
+    const intermediate_namespace = parts.slice(1, -1).join('/');
+    namespace = intermediate_namespace || 'library';
+  } else {
+    // Otherwise, use everything after registry as namespace
+    const full_namespace = parts.slice(1).join('/');
+    namespace = full_namespace || 'library';
+  }
+
+  return {
+    registry,
+    namespace,
+    repository: chart_name,
+  };
+}
+
+/**
+ * Creates a Helm repository client.
+ * Supports both traditional Helm repositories and OCI registries.
+ */
+export function create_helm_client(
+  helm_config: { repository?: string; oci?: string; chart: string },
+  config?: RegistryClientConfigType,
+): RegistryClientType {
+  // OCI registry
+  if (helm_config.oci) {
+    const image_ref = parse_oci_helm_reference(helm_config.oci, helm_config.chart);
+    // Use GHCR client for OCI registries (they all use the same OCI Distribution spec)
+    const oci_client = create_ghcr_client(config);
+    return {
+      list_tags: () => oci_client.list_tags(image_ref),
+    };
+  }
+
+  // Traditional Helm repository
+  return {
+    async list_tags(
+      _image?: ImageReferenceType,
+    ): Promise<ResultType<TagInfoType[], KustodianErrorType>> {
+      if (!helm_config.repository) {
+        return failure({
+          code: 'HELM_REPO_ERROR',
+          message: 'No repository URL provided for Helm chart',
+        });
+      }
+
+      const index_result = await fetch_helm_index(helm_config.repository, config);
+      if (!index_result.success) {
+        return index_result;
+      }
+
+      const chart_entries = index_result.value.entries[helm_config.chart];
+      if (!chart_entries || chart_entries.length === 0) {
+        return failure({
+          code: 'HELM_CHART_NOT_FOUND',
+          message: `Chart "${helm_config.chart}" not found in Helm repository`,
+        });
+      }
+
+      const tags: TagInfoType[] = chart_entries.map((entry) =>
+        entry.digest ? { name: entry.version, digest: entry.digest } : { name: entry.version },
+      );
+
+      return success(tags);
+    },
+  };
+}

package/src/index.ts

@@ -19,6 +19,7 @@ export {
 // Registry implementations
 export { create_dockerhub_client } from './dockerhub.js';
 export { create_ghcr_client } from './ghcr.js';
+export { create_helm_client } from './helm.js';
 
 // Auth utilities
 export { get_dockerhub_auth, get_ghcr_auth, get_auth_for_registry } from './auth.js';