@a5c-ai/krate 5.0.1-staging.04a3db697

package/src/external/github/issue-tracking.js

@@ -0,0 +1,163 @@
+// GitHub Issue Tracking implementation — Slice 3.3b
+// Implements the issueTracking interface contract:
+//   listIssues, createIssue, updateIssue, closeIssue, listComments, createComment
+//
+// All HTTP calls are injected via fetchImpl for full testability.
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * @typedef {{ number: number, title: string, state: string, body: string, labels: string[], author: string, htmlUrl: string }} NormalizedIssue
+ * @typedef {{ id: number, body: string, author: string, createdAt: string, htmlUrl: string }} NormalizedComment
+ */
+
+/**
+ * GitHub implementation of the issueTracking interface.
+ *
+ * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+ */
+export class GitHubIssueTracking {
+  constructor({ owner, installationToken, fetchImpl = globalThis.fetch } = {}) {
+    if (!owner) throw new Error('GitHubIssueTracking: owner (org or user) is required');
+    if (!installationToken) throw new Error('GitHubIssueTracking: installationToken is required');
+    if (!fetchImpl) throw new Error('GitHubIssueTracking: a fetch implementation is required');
+
+    this.role = 'github-issue-tracking';
+    this._owner = owner;
+    this._token = installationToken;
+    this._fetch = fetchImpl;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal helpers
+  // ---------------------------------------------------------------------------
+
+  _headers() {
+    return {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${this._token}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'Content-Type': 'application/json'
+    };
+  }
+
+  async _request(method, path, body) {
+    const url = `${GITHUB_API}${path}`;
+    const options = {
+      method,
+      headers: this._headers(),
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {})
+    };
+    const response = await this._fetch(url, options);
+    if (!response.ok) {
+      throw new Error(`GitHub ${method} ${path} failed with status ${response.status}`);
+    }
+    if (response.status === 204) return null;
+    return response.json();
+  }
+
+  _repoPath(repo, suffix = '') {
+    return `/repos/${encodeURIComponent(this._owner)}/${encodeURIComponent(repo)}${suffix}`;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Normalizers
+  // ---------------------------------------------------------------------------
+
+  _normalizeIssue(data) {
+    return {
+      id: data.id,
+      number: data.number,
+      title: data.title,
+      state: data.state,
+      body: data.body ?? '',
+      labels: (data.labels ?? []).map(l => (typeof l === 'string' ? l : l.name)),
+      author: data.user?.login ?? '',
+      htmlUrl: data.html_url ?? ''
+    };
+  }
+
+  _normalizeComment(data) {
+    return {
+      id: data.id,
+      body: data.body ?? '',
+      author: data.user?.login ?? '',
+      createdAt: data.created_at ?? '',
+      htmlUrl: data.html_url ?? ''
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Interface methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * List issues for a repository.
+   * @param {{ repo: string, state?: 'open'|'closed'|'all' }} opts
+   * @returns {Promise<NormalizedIssue[]>}
+   */
+  async listIssues({ repo, state = 'open' } = {}) {
+    const data = await this._request('GET', this._repoPath(repo, `/issues?state=${state}`));
+    const issues = data ?? [];
+    return issues.map(i => this._normalizeIssue(i));
+  }
+
+  /**
+   * Create an issue.
+   * @param {{ repo: string, title: string, body?: string, labels?: string[] }} opts
+   * @returns {Promise<NormalizedIssue>}
+   */
+  async createIssue({ repo, title, body = '', labels = [] }) {
+    const data = await this._request('POST', this._repoPath(repo, '/issues'), {
+      title,
+      body,
+      ...(labels.length > 0 ? { labels } : {})
+    });
+    return this._normalizeIssue(data);
+  }
+
+  /**
+   * Update an issue (title, body, labels).
+   * @param {{ repo: string, issueNumber: number, title?: string, body?: string, labels?: string[] }} opts
+   * @returns {Promise<NormalizedIssue>}
+   */
+  async updateIssue({ repo, issueNumber, title, body, labels } = {}) {
+    const payload = {};
+    if (title !== undefined) payload.title = title;
+    if (body !== undefined) payload.body = body;
+    if (labels !== undefined) payload.labels = labels;
+    const data = await this._request('PATCH', this._repoPath(repo, `/issues/${issueNumber}`), payload);
+    return this._normalizeIssue(data);
+  }
+
+  /**
+   * Close an issue by setting its state to 'closed'.
+   * @param {{ repo: string, issueNumber: number }} opts
+   * @returns {Promise<NormalizedIssue>}
+   */
+  async closeIssue({ repo, issueNumber } = {}) {
+    const data = await this._request('PATCH', this._repoPath(repo, `/issues/${issueNumber}`), { state: 'closed' });
+    return this._normalizeIssue(data);
+  }
+
+  /**
+   * List comments for an issue.
+   * @param {{ repo: string, issueNumber: number }} opts
+   * @returns {Promise<NormalizedComment[]>}
+   */
+  async listComments({ repo, issueNumber } = {}) {
+    const data = await this._request('GET', this._repoPath(repo, `/issues/${issueNumber}/comments`));
+    const comments = data ?? [];
+    return comments.map(c => this._normalizeComment(c));
+  }
+
+  /**
+   * Create a comment on an issue.
+   * @param {{ repo: string, issueNumber: number, body: string }} opts
+   * @returns {Promise<NormalizedComment>}
+   */
+  async createComment({ repo, issueNumber, body }) {
+    const data = await this._request('POST', this._repoPath(repo, `/issues/${issueNumber}/comments`), { body });
+    return this._normalizeComment(data);
+  }
+}

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 Krate 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,161 @@
+// External Provider Resource Factory — Slice B3+D1
+//
+// Provides:
+//   - createDefaultProviderRegistry() — auto-registers GitHub provider
+//   - createExternalBackendProvider() — creates ExternalBackendProvider CRD resources
+
+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 };
+
+// ---------------------------------------------------------------------------
+// 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: createExternalBackendProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an ExternalBackendProvider CRD resource.
+ * Used by the external backend wizard to persist provider registrations.
+ *
+ * @param {{ name: string, namespace?: string, providerType: string,
+ *           displayName: string, config?: object, organizationRef?: string }} opts
+ * @returns {object} K8s-style ExternalBackendProvider 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: 'krate.a5c.ai/v1alpha1',
+    kind: 'ExternalBackendProvider',
+    metadata: {
+      name,
+      namespace,
+      labels: {},
+      annotations: {}
+    },
+    spec: {
+      organizationRef,
+      providerType,
+      displayName: displayName || providerType,
+      config: { ...config }
+    },
+    status: {
+      phase: 'Pending',
+      createdAt: now
+    }
+  };
+}