@a5c-ai/kradle 5.0.1-staging.3abdf9534c25

package/src/external/provider-adapter.js

@@ -0,0 +1,161 @@
+// External Provider Adapter — Slice 3.2
+// Defines the ExternalProviderAdapter contract and ProviderRegistry.
+//
+// Each provider (GitHub, GitLab, Gitea, etc.) implements this interface to
+// integrate with the Kradle platform.
+
+/**
+ * Valid optional interface keys that a provider adapter may implement.
+ */
+const VALID_INTERFACES = ['issueTracking', 'cicd', 'gitForge'];
+
+/**
+ * Valid health status values returned by health().
+ */
+const VALID_HEALTH_STATUSES = ['healthy', 'degraded', 'unavailable'];
+
+// ---------------------------------------------------------------------------
+// Provider Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a provider registry that stores and retrieves ExternalProviderAdapter
+ * instances by provider type string.
+ *
+ * @returns {{ register(type: string, adapter: object): void, get(type: string): object|null, list(): string[] }}
+ */
+export function createProviderRegistry() {
+  /** @type {Map<string, object>} */
+  const adapters = new Map();
+
+  return {
+    /**
+     * Register a provider adapter under the given type key.
+     * Re-registering the same type replaces the existing adapter.
+     * @param {string} type
+     * @param {object} adapter
+     */
+    register(type, adapter) {
+      adapters.set(type, adapter);
+    },
+
+    /**
+     * Retrieve a registered adapter by provider type, or null if not found.
+     * @param {string} type
+     * @returns {object|null}
+     */
+    get(type) {
+      return adapters.has(type) ? adapters.get(type) : null;
+    },
+
+    /**
+     * List all registered provider type keys.
+     * @returns {string[]}
+     */
+    list() {
+      return [...adapters.keys()];
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Adapter validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an ExternalProviderAdapter object against the contract.
+ *
+ * Required contract:
+ *   - descriptor() → { providerType, displayName, hosting, authModes, apiCapabilities }
+ *   - health()     → { status: 'healthy'|'degraded'|'unavailable', message }
+ *   - at least one of: issueTracking, cicd, gitForge
+ *   - normalizeWebhook(payload) → NormalizedEvent[]
+ *   - verifyWebhook(request)    → { valid, reason }
+ *
+ * @param {object} adapter
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateProviderAdapter(adapter) {
+  const errors = [];
+
+  if (adapter == null) {
+    errors.push('adapter must not be null or undefined');
+    return { valid: false, errors };
+  }
+
+  // descriptor must be a function
+  if (typeof adapter.descriptor !== 'function') {
+    errors.push('adapter.descriptor must be a function returning { providerType, displayName, hosting, authModes }');
+  }
+
+  // health must be a function
+  if (typeof adapter.health !== 'function') {
+    errors.push('adapter.health must be a function returning { status, message }');
+  }
+
+  // At least one optional interface must be present
+  const presentInterfaces = VALID_INTERFACES.filter((key) => adapter[key] != null);
+  if (presentInterfaces.length === 0) {
+    errors.push(
+      `adapter must implement at least one provider interface: ${VALID_INTERFACES.join(', ')} (issueTracking, cicd, or gitForge)`
+    );
+  }
+
+  // normalizeWebhook must be a function
+  if (typeof adapter.normalizeWebhook !== 'function') {
+    errors.push('adapter.normalizeWebhook must be a function(payload) → NormalizedEvent[]');
+  }
+
+  // verifyWebhook must be a function
+  if (typeof adapter.verifyWebhook !== 'function') {
+    errors.push('adapter.verifyWebhook must be a function(request) → { valid, reason }');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Capability manifest validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a capability manifest object.
+ *
+ * A capability manifest declares which provider interfaces a concrete adapter
+ * supports, so the platform can route requests accordingly.
+ *
+ * Required shape:
+ *   { providerType: string, interfaces: string[] }
+ *
+ * @param {object} manifest
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateCapabilityManifest(manifest) {
+  const errors = [];
+
+  if (manifest == null) {
+    errors.push('manifest must not be null or undefined');
+    return { valid: false, errors };
+  }
+
+  // providerType is required
+  if (!manifest.providerType || typeof manifest.providerType !== 'string') {
+    errors.push('manifest.providerType is required and must be a non-empty string');
+  }
+
+  // interfaces must be a non-empty array of known interface names
+  if (!Array.isArray(manifest.interfaces) || manifest.interfaces.length === 0) {
+    errors.push(
+      `manifest.interfaces must be a non-empty array; supported interfaces are: ${VALID_INTERFACES.join(', ')}`
+    );
+  } else {
+    const unknown = manifest.interfaces.filter((iface) => !VALID_INTERFACES.includes(iface));
+    if (unknown.length > 0) {
+      errors.push(
+        `manifest.interfaces contains unknown or invalid interface(s): ${unknown.join(', ')}; valid interfaces are: ${VALID_INTERFACES.join(', ')}`
+      );
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/external/provider-resource-factory.js

@@ -0,0 +1,221 @@
+// External Provider Resource Factory — Slice B3+D1
+//
+// Provides:
+//   - createDefaultProviderRegistry() — auto-registers GitHub provider
+//   - createTypedProvider() — creates typed provider CRD resources (GitProvider, CiProvider, etc.)
+//   - createExternalBackendProvider() — DEPRECATED, use createTypedProvider()
+
+import { createProviderRegistry } from './provider-adapter.js';
+import { GitHubGitForge } from './github/git-forge.js';
+import { GitHubIssueTracking } from './github/issue-tracking.js';
+import { GitHubCicd } from './github/cicd.js';
+
+// Re-export for consumers that want the real classes from this module
+export { GitHubGitForge, GitHubIssueTracking, GitHubCicd };
+
+// Valid typed provider kinds
+const TYPED_PROVIDER_KINDS = new Set([
+  'GitProvider',
+  'CiProvider',
+  'IssueTrackerProvider',
+  'AppHostingProvider',
+  'ArtifactRegistryProvider',
+]);
+
+// ---------------------------------------------------------------------------
+// GitHub provider descriptor — wraps real GitHub classes
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a GitHub provider adapter descriptor for the registry.
+ * This descriptor exposes real GitHubGitForge, GitHubIssueTracking, and
+ * GitHubCicd classes as factory methods.  Credential-free listing operations
+ * return empty arrays; authenticated operations are created via createGitHubProvider().
+ *
+ * @returns {object} ExternalProviderAdapter descriptor
+ */
+function buildGitHubAdapterDescriptor() {
+  return {
+    descriptor() {
+      return {
+        providerType: 'github',
+        displayName: 'GitHub',
+        hosting: ['cloud', 'self-hosted'],
+        authModes: ['github-app', 'pat'],
+        interfaces: ['gitForge', 'issueTracking', 'cicd']
+      };
+    },
+
+    health() {
+      return { status: 'healthy', message: 'GitHub provider registered (no live connection)' };
+    },
+
+    /**
+     * Create a GitHubGitForge instance bound to specific credentials.
+     *
+     * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+     * @returns {GitHubGitForge}
+     */
+    createForge({ owner, installationToken, fetchImpl } = {}) {
+      return new GitHubGitForge({ owner, installationToken, fetchImpl: fetchImpl ?? globalThis.fetch });
+    },
+
+    /**
+     * Create a GitHubIssueTracking instance bound to specific credentials.
+     *
+     * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+     * @returns {GitHubIssueTracking}
+     */
+    createIssueTracker({ owner, installationToken, fetchImpl } = {}) {
+      return new GitHubIssueTracking({ owner, installationToken, fetchImpl: fetchImpl ?? globalThis.fetch });
+    },
+
+    /**
+     * Create a GitHubCicd instance bound to specific credentials.
+     *
+     * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+     * @returns {GitHubCicd}
+     */
+    createCicd({ owner, installationToken, fetchImpl } = {}) {
+      return new GitHubCicd({ owner, installationToken, fetchImpl: fetchImpl ?? globalThis.fetch });
+    },
+
+    // Credential-free listing stubs — real operations require authenticated instances
+    gitForge: {
+      listRepositories: async () => [],
+      createRepository: async () => { throw new Error('Use createForge() for authenticated git forge operations'); }
+    },
+
+    issueTracking: {
+      listIssues: async () => [],
+      createIssue: async () => { throw new Error('Use createIssueTracker() for authenticated issue tracking operations'); }
+    },
+
+    cicd: {
+      listWorkflowRuns: async () => [],
+      triggerWorkflow: async () => { throw new Error('Use createCicd() for authenticated CI/CD operations'); }
+    },
+
+    normalizeWebhook(payload) {
+      // Passthrough — real normalization lives in the GitHub webhook controller
+      return [{ type: payload?.action ?? 'unknown', payload }];
+    },
+
+    verifyWebhook(_request) {
+      // Default: unverified; real HMAC verification is in webhook-controller
+      return { valid: false, reason: 'use webhook-controller for HMAC verification' };
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// D1: createDefaultProviderRegistry
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a provider registry pre-loaded with the GitHub provider.
+ *
+ * @returns {object} ProviderRegistry with github auto-registered
+ */
+export function createDefaultProviderRegistry() {
+  const registry = createProviderRegistry();
+  registry.register('github', buildGitHubAdapterDescriptor());
+  return registry;
+}
+
+// ---------------------------------------------------------------------------
+// D1: createTypedProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed provider CRD resource (GitProvider, CiProvider, etc.).
+ * Used by the external backend wizard to persist provider registrations.
+ *
+ * @param {string} kind - One of GitProvider, CiProvider, IssueTrackerProvider, AppHostingProvider, ArtifactRegistryProvider
+ * @param {string} platform - Platform identifier (e.g. 'github', 'gitlab', 'vercel')
+ * @param {{ name?: string, namespace?: string, organizationRef?: string, endpoint?: string, secretRef?: string }} spec
+ * @returns {object} K8s-style typed provider resource
+ */
+export function createTypedProvider(kind, platform, {
+  name,
+  namespace = 'default',
+  organizationRef = 'default',
+  endpoint = '',
+  secretRef = '',
+} = {}) {
+  if (!kind) throw new Error('createTypedProvider: kind is required');
+  if (!TYPED_PROVIDER_KINDS.has(kind)) throw new Error(`createTypedProvider: unknown kind "${kind}", expected one of ${[...TYPED_PROVIDER_KINDS].join(', ')}`);
+  if (!platform) throw new Error('createTypedProvider: platform is required');
+  const resourceName = name || `${platform}-${kind.toLowerCase()}`;
+
+  const now = new Date().toISOString();
+
+  return {
+    apiVersion: 'kradle.a5c.ai/v1alpha1',
+    kind,
+    metadata: {
+      name: resourceName,
+      namespace,
+      labels: {},
+      annotations: {}
+    },
+    spec: {
+      organizationRef,
+      platform,
+      endpoint,
+      ...(secretRef ? { secretRef } : {}),
+    },
+    status: {
+      phase: 'Pending',
+      createdAt: now
+    }
+  };
+}
+
+// ---------------------------------------------------------------------------
+// D1: createExternalBackendProvider (DEPRECATED — use createTypedProvider)
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated Use createTypedProvider() instead.
+ * Create an ExternalBackendProvider CRD resource.
+ * Retained for backward compatibility. Maps to createTypedProvider('GitProvider', ...).
+ *
+ * @param {{ name: string, namespace?: string, providerType: string,
+ *           displayName: string, config?: object, organizationRef?: string }} opts
+ * @returns {object} K8s-style provider resource
+ */
+export function createExternalBackendProvider({
+  name,
+  namespace = 'default',
+  providerType,
+  displayName,
+  config = {},
+  organizationRef = 'default'
+} = {}) {
+  if (!name) throw new Error('createExternalBackendProvider: name is required');
+  if (!providerType) throw new Error('createExternalBackendProvider: providerType is required');
+
+  const now = new Date().toISOString();
+
+  return {
+    apiVersion: 'kradle.a5c.ai/v1alpha1',
+    kind: 'ExternalBackendProvider',
+    metadata: {
+      name,
+      namespace,
+      labels: {},
+      annotations: {}
+    },
+    spec: {
+      organizationRef,
+      providerType,
+      displayName: displayName || providerType,
+      config: { ...config }
+    },
+    status: {
+      phase: 'Pending',
+      createdAt: now
+    }
+  };
+}

package/src/external/sync-controller.js

@@ -0,0 +1,235 @@
+// External Sync Controller — Slice 3.4
+//
+// Manages bidirectional sync between external providers and the Kradle resource store.
+//
+// Responsibilities:
+//   - Event normalization (raw provider event → canonical internal format)
+//   - Resource upsert with external identity envelope (nativeId, url, etag)
+//   - High-watermark tracking per binding
+//   - Ownership mode arbitration (bidirectional / external-owned / kradle-owned)
+//   - Tombstone creation for deleted external resources
+
+export const SYNC_CONTROLLER_BOUNDARY = {
+  role: 'sync-controller',
+  scope: 'Bidirectional sync — event normalization, resource upsert, watermark, ownership, tombstones',
+  owns: ['event normalization', 'resource upsert', 'watermark tracking', 'ownership modes', 'tombstones'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['HMAC verification', 'webhook delivery tracking']
+};
+
+/**
+ * Create a sync controller that manages bidirectional sync between external
+ * providers and the Kradle resource store.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ *   Optional persistFn is called (fire-and-forget) after watermark/resource changes.
+ *   It receives a K8s-style CRD resource representing the changed state.
+ * @returns {object}
+ */
+export function createSyncController({ persistFn } = {}) {
+  /** @type {Map<string, string>} bindingRef → ISO timestamp watermark */
+  const watermarks = new Map();
+
+  /** @type {Map<string, object>} `${namespace}/${kind}/${localName}` → resource */
+  const resources = new Map();
+
+  /** @type {Map<string, object>} nativeId → tombstone record */
+  const tombstones = new Map();
+
+  /**
+   * Fire-and-forget persistence: call persistFn without blocking the caller.
+   * @param {object} resource
+   */
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      // Intentionally not awaited — persistence is async and non-blocking
+      Promise.resolve(persistFn(resource)).catch(() => {
+        // Swallow errors in fire-and-forget path; caller may wire monitoring separately
+      });
+    }
+  }
+
+  return {
+    /**
+     * Normalize a raw provider event into a canonical internal format.
+     *
+     * @param {{ eventType: string, action?: string, nativeId: string, providerRef: string,
+     *           resourceKind: string, data?: object, receivedAt?: string }} rawEvent
+     * @returns {{ eventType: string, action: string, nativeId: string, providerRef: string,
+     *             resourceKind: string, data: object, receivedAt: string, canonicalAt: string }}
+     */
+    normalizeEvent(rawEvent) {
+      return {
+        eventType: rawEvent.eventType,
+        action: rawEvent.action || 'unknown',
+        nativeId: rawEvent.nativeId,
+        providerRef: rawEvent.providerRef,
+        resourceKind: rawEvent.resourceKind,
+        data: rawEvent.data || {},
+        receivedAt: rawEvent.receivedAt || new Date().toISOString(),
+        canonicalAt: new Date().toISOString()
+      };
+    },
+
+    /**
+     * Upsert a resource in the local store with an external identity envelope.
+     *
+     * If the resource already exists (matched by localName + namespace + kind), it will
+     * be updated while preserving the nativeId and firstSyncedAt from the first sync.
+     *
+     * @param {{ kind: string, localName: string, namespace?: string, spec: object,
+     *           externalEnvelope: { nativeId: string, url: string, etag: string, providerRef: string } }} params
+     * @returns {object} The created/updated resource
+     */
+    upsertResource({ kind, localName, namespace = 'default', spec, externalEnvelope }) {
+      const key = `${namespace}/${kind}/${localName}`;
+      const existing = resources.get(key);
+      const now = new Date().toISOString();
+
+      const resource = {
+        apiVersion: 'kradle.a5c.ai/v1alpha1',
+        kind,
+        metadata: {
+          name: localName,
+          namespace,
+          labels: {},
+          annotations: {}
+        },
+        spec: { ...spec },
+        status: {
+          phase: 'Synced',
+          external: {
+            nativeId: externalEnvelope.nativeId,
+            url: externalEnvelope.url,
+            etag: externalEnvelope.etag,
+            providerRef: externalEnvelope.providerRef,
+            lastSyncedAt: now,
+            firstSyncedAt: existing
+              ? existing.status.external.firstSyncedAt
+              : now
+          }
+        }
+      };
+
+      resources.set(key, resource);
+      persist(resource);
+      return resource;
+    },
+
+    /**
+     * Advance the high-watermark timestamp for a given binding.
+     * If the new timestamp is not later than the existing one, it is ignored.
+     *
+     * @param {string} bindingRef
+     * @param {string} timestamp  ISO 8601 timestamp
+     */
+    updateWatermark(bindingRef, timestamp) {
+      const current = watermarks.get(bindingRef);
+      if (!current || timestamp > current) {
+        watermarks.set(bindingRef, timestamp);
+        // Persist watermark as a CRD-shaped resource
+        persist({
+          apiVersion: 'kradle.a5c.ai/v1alpha1',
+          kind: 'ExternalSyncWatermark',
+          metadata: {
+            name: `watermark-${bindingRef.replace(/[^a-zA-Z0-9]/g, '-')}`,
+            namespace: 'default',
+            labels: {},
+            annotations: {}
+          },
+          spec: {
+            bindingRef,
+            watermark: timestamp
+          },
+          status: {
+            lastUpdatedAt: new Date().toISOString()
+          }
+        });
+      }
+    },
+
+    /**
+     * Retrieve the current high-watermark for a given binding.
+     *
+     * @param {string} bindingRef
+     * @returns {string|null}
+     */
+    getWatermark(bindingRef) {
+      return watermarks.has(bindingRef) ? watermarks.get(bindingRef) : null;
+    },
+
+    /**
+     * Apply an ownership mode policy to determine whether an operation is allowed.
+     *
+     * Modes:
+     *   - 'bidirectional'  — both kradle and external provider may write
+     *   - 'external-owned' — only the external provider may write; kradle is read-only
+     *   - 'kradle-owned'    — only kradle may write; external provider is read-only
+     *
+     * @param {{ ownershipMode: string, operation: string, origin: string }} params
+     * @returns {{ allowed: boolean, reason: string|null }}
+     */
+    applyOwnershipMode({ ownershipMode, operation, origin }) {
+      if (ownershipMode === 'bidirectional') {
+        return { allowed: true, reason: null };
+      }
+
+      if (ownershipMode === 'external-owned') {
+        if (origin === 'kradle' && operation === 'write') {
+          return {
+            allowed: false,
+            reason: 'external-owned mode — kradle writes are blocked; this resource is read-only from kradle perspective'
+          };
+        }
+        return { allowed: true, reason: null };
+      }
+
+      if (ownershipMode === 'kradle-owned') {
+        if (origin === 'external' && operation === 'write') {
+          return {
+            allowed: false,
+            reason: 'kradle-owned mode — external provider writes are blocked; kradle is the authoritative source'
+          };
+        }
+        return { allowed: true, reason: null };
+      }
+
+      // Unknown mode — deny by default
+      return {
+        allowed: false,
+        reason: `unknown ownership mode: ${ownershipMode}`
+      };
+    },
+
+    /**
+     * Create a tombstone record marking that an external resource has been deleted.
+     *
+     * @param {{ nativeId: string, providerRef: string, resourceKind: string,
+     *           localRef: string, deletedAt?: string }} params
+     * @returns {{ nativeId: string, providerRef: string, resourceKind: string,
+     *             localRef: string, tombstoned: true, deletedAt: string }}
+     */
+    createTombstone({ nativeId, providerRef, resourceKind, localRef, deletedAt }) {
+      const record = {
+        nativeId,
+        providerRef,
+        resourceKind,
+        localRef,
+        tombstoned: true,
+        deletedAt: deletedAt || new Date().toISOString()
+      };
+      tombstones.set(nativeId, record);
+      return record;
+    },
+
+    /**
+     * Retrieve a tombstone record by nativeId, or null if not found.
+     *
+     * @param {string} nativeId
+     * @returns {object|null}
+     */
+    getTombstone(nativeId) {
+      return tombstones.has(nativeId) ? tombstones.get(nativeId) : null;
+    }
+  };
+}