@a5c-ai/krate 5.0.1-staging.00fa5317c

package/src/data-plane.js

@@ -0,0 +1,179 @@
+import { giteaIssueSyncPlan, giteaRepositoryIntegrationPlan, orgMemoryRepositoryName } from './gitea-backend.js';
+import { clone, createResource } from './resource-model.js';
+
+
+export function createDefaultGiteaGitBackend({ baseUrl = 'http://krate-gitea-http:3000', sshDomain = 'krate-gitea-ssh', owner = 'krate', webhookBaseUrl = 'http://krate-webhook-worker' } = {}) {
+  return { type: 'gitea', baseUrl: baseUrl.replace(/\/$/, ''), sshDomain, owner, webhookBaseUrl: webhookBaseUrl.replace(/\/$/, '') };
+}
+
+export function createGiteaRepositoryHosting({ backend = createDefaultGiteaGitBackend(), namespace = 'default', repository, branch = 'main' }) {
+  const owner = backend.owner || namespace;
+  const httpUrl = `${backend.baseUrl}/${owner}/${repository}.git`;
+  const sshUrl = `ssh://git@${backend.sshDomain}/${owner}/${repository}.git`;
+  const webhookUrl = `${backend.webhookBaseUrl}/repositories/${namespace}/${repository}`;
+  return {
+    backend: 'gitea',
+    owner,
+    repository,
+    branch,
+    httpUrl,
+    sshUrl,
+    deployKeyTitle: 'krate-argocd',
+    organization: { kind: 'Organization', name: owner, delegatedTo: 'Gitea /api/v1/orgs' },
+    sshKeys: { kind: 'SSHKey', scopes: ['user', 'deploy', 'argocd'], delegatedTo: 'Gitea /api/v1/user/keys and /repos/{owner}/{repo}/keys' },
+    permissions: { kind: 'RepositoryPermission', defaultCollaborator: 'write', adminTeam: 'maintainers', delegatedTo: 'Gitea collaborators and team repository APIs' },
+    forgeRecords: { issues: `Gitea /repos/${owner}/${orgMemoryRepositoryName(namespace)}/issues`, pullRequests: 'Gitea /repos/{owner}/{repo}/pulls' },
+    issueSync: giteaIssueSyncPlan({ org: namespace, repositories: [repository] }),
+    webhookUrl,
+    integrationPlan: giteaRepositoryIntegrationPlan({ owner, repo: repository, deployKeyTitle: 'krate-argocd', permission: 'write', branch, webhookUrl })
+  };
+}
+
+export function stableRepositoryStoreIndex(repositoryName, storeCount) {
+  let hash = 0;
+  for (const character of repositoryName) hash = (hash * 31 + character.charCodeAt(0)) >>> 0;
+  return hash % storeCount;
+}
+
+export class GiteaRepositoryStore {
+  constructor({ name = 'gitea-primary', receivePackReady = true, capacity = 1000 } = {}) {
+    this.name = name;
+    this.receivePackReady = receivePackReady;
+    this.capacity = capacity;
+    this.repositories = new Map();
+    this.objects = new Map();
+    this.searchIndex = new Map();
+  }
+
+  assign(repository) { this.repositories.set(repository.metadata.name, repository); return this; }
+  isReceivePackReady() { return this.receivePackReady; }
+
+  putObject(repository, object) {
+    const objects = this.objects.get(repository) || [];
+    objects.push(object);
+    this.objects.set(repository, objects);
+    return object;
+  }
+
+  index(repository, entry) {
+    const entries = this.searchIndex.get(repository) || [];
+    entries.push(entry);
+    this.searchIndex.set(repository, entries);
+    return entry;
+  }
+
+  snapshot() {
+    return {
+      name: this.name,
+      receivePackReady: this.receivePackReady,
+      capacity: this.capacity,
+      repositories: Object.fromEntries([...this.repositories.entries()].map(([name, resource]) => [name, clone(resource)])),
+      objects: Object.fromEntries([...this.objects.entries()].map(([repository, objects]) => [repository, clone(objects)])),
+      searchIndex: Object.fromEntries([...this.searchIndex.entries()].map(([repository, entries]) => [repository, clone(entries)]))
+    };
+  }
+
+  importSnapshot(snapshot = {}) {
+    this.receivePackReady = snapshot.receivePackReady ?? this.receivePackReady;
+    this.capacity = snapshot.capacity ?? this.capacity;
+    this.repositories = new Map(Object.entries(snapshot.repositories || {}).map(([name, resource]) => [name, clone(resource)]));
+    this.objects = new Map(Object.entries(snapshot.objects || {}).map(([repository, objects]) => [repository, clone(objects)]));
+    this.searchIndex = new Map(Object.entries(snapshot.searchIndex || {}).map(([repository, entries]) => [repository, clone(entries)]));
+    return this;
+  }
+}
+
+export class GiteaGitService {
+  constructor({ controlPlane, stores = [new GiteaRepositoryStore()], gitBackend = createDefaultGiteaGitBackend() }) {
+    if (!controlPlane) throw new Error('GiteaGitService requires a controlPlane');
+    this.controlPlane = controlPlane;
+    this.stores = stores;
+    this.gitBackend = gitBackend.type === 'gitea' ? gitBackend : createDefaultGiteaGitBackend(gitBackend);
+    this.integrationPlans = new Map();
+  }
+
+  snapshot() {
+    return {
+      apiVersion: 'krate.a5c.ai/v1alpha1',
+      kind: 'GiteaGitServiceSnapshot',
+      backend: clone(this.gitBackend),
+      integrationPlans: Object.fromEntries([...this.integrationPlans.entries()].map(([repository, plan]) => [repository, clone(plan)])),
+      stores: this.stores.map((store) => store.snapshot())
+    };
+  }
+
+  importSnapshot(snapshot = {}) {
+    if (snapshot.backend?.type === 'gitea') this.gitBackend = clone(snapshot.backend);
+    this.integrationPlans = new Map(Object.entries(snapshot.integrationPlans || {}).map(([repository, plan]) => [repository, clone(plan)]));
+    if (!Array.isArray(snapshot.stores)) return this;
+    this.stores = snapshot.stores.map((storeSnapshot) => new GiteaRepositoryStore({
+      name: storeSnapshot.name,
+      receivePackReady: storeSnapshot.receivePackReady,
+      capacity: storeSnapshot.capacity
+    }).importSnapshot(storeSnapshot));
+    return this;
+  }
+
+  route(repositoryName) {
+    const store = this.stores[stableRepositoryStoreIndex(repositoryName, this.stores.length)];
+    const owner = this.gitBackend.owner || 'krate';
+    return { repositoryName, backend: 'gitea', owner, store: store.name, receivePackReady: store.isReceivePackReady(), httpUrl: `${this.gitBackend.baseUrl}/${owner}/${repositoryName}.git`, sshUrl: `ssh://git@${this.gitBackend.sshDomain}/${owner}/${repositoryName}.git` };
+  }
+
+  createRepository({ name, namespace = 'krate-org-default', organizationRef = 'default', visibility = 'private' }, user) {
+    const route = this.route(name);
+    const hosting = createGiteaRepositoryHosting({ backend: this.gitBackend, namespace, repository: name });
+    const repository = createResource('Repository', { name, namespace, labels: { gitBackend: 'gitea' } }, {
+      organizationRef,
+      visibility,
+      gitHosting: hosting,
+      storage: { mode: 'gitea', persistentVolumeClaim: 'krate-gitea-data', owner: hosting.owner, repository: name, httpUrl: hosting.httpUrl, sshUrl: hosting.sshUrl },
+      objectStorage: { lfs: true, artifacts: true },
+      search: { provider: 'zoekt', enabled: false }
+    }, { ready: true, route: { ...route, backend: 'gitea' }, gitHosting: { backend: 'gitea', httpUrl: hosting.httpUrl, sshUrl: hosting.sshUrl, integrationPlan: hosting.integrationPlan } });
+    const created = this.controlPlane.create(repository, user);
+    this.integrationPlans.set(name, hosting.integrationPlan);
+    this.stores.find((store) => store.name === route.store).assign(created);
+    return created;
+  }
+
+  receivePack({ repository, namespace = 'krate-org-default', ref, oldRev = '0'.repeat(40), newRev, actor }) {
+    const route = this.route(repository);
+    if (!route.receivePackReady) throw new Error(`receive-pack for ${repository} is not ready`);
+    const refPolicies = this.controlPlane.list('RefPolicy', { namespace }).items;
+    const branchProtections = this.controlPlane.list('BranchProtection', { namespace }).items;
+    const deniedByPolicy = refPolicies.find((policy) => (policy.spec.deny || []).some((prefix) => ref.startsWith(prefix)));
+    if (deniedByPolicy) throw new Error(`RefPolicy ${deniedByPolicy.metadata.name} denied ${ref}`);
+    const protectedBranch = branchProtections.find((policy) => (policy.spec.refs || []).includes(ref));
+    const isRepoAdmin = actor.groups?.includes('krate:repo-admins') || actor.groups?.includes('krate:platform-engineers');
+    if (protectedBranch && protectedBranch.spec.requirePullRequest && !isRepoAdmin) {
+      throw new Error(`BranchProtection ${protectedBranch.metadata.name} requires pull request for ${ref}`);
+    }
+    const event = { repository, namespace, ref, oldRev, newRev, actor: actor.name, backend: 'gitea', store: route.store, remoteUrl: route.httpUrl, at: new Date().toISOString() };
+    this.controlPlane.events.push({ type: 'git.receive-pack', resource: event, storage: 'gitea' });
+    return event;
+  }
+
+  uploadPack({ repository }) {
+    const route = this.route(repository);
+    return { repository, backend: 'gitea', store: route.store, remoteUrl: route.httpUrl, cacheable: true };
+  }
+
+  recordObject({ repository, namespace = 'default', key, size, mediaType = 'application/octet-stream' }) {
+    const route = this.route(repository);
+    const store = this.stores.find((candidate) => candidate.name === route.store);
+    const object = { repository, namespace, key, size, mediaType, store: route.store, storage: 'object-storage', at: new Date().toISOString() };
+    store.putObject(repository, object);
+    this.controlPlane.events.push({ type: 'git.object-recorded', resource: object, storage: 'object-storage' });
+    return object;
+  }
+
+  enqueueSearchIndex({ repository, namespace = 'default', commit, paths = [] }) {
+    const route = this.route(repository);
+    const store = this.stores.find((candidate) => candidate.name === route.store);
+    const entry = { repository, namespace, commit, paths, store: route.store, provider: 'zoekt', status: 'queued', at: new Date().toISOString() };
+    store.index(repository, entry);
+    this.controlPlane.events.push({ type: 'search.index-queued', resource: entry, storage: 'search-index' });
+    return entry;
+  }
+}

package/src/event-bus.js

@@ -0,0 +1,61 @@
+/**
+ * Module-level event bus for SSE real-event streaming.
+ * Provides a pub/sub mechanism for resource change events.
+ */
+
+/**
+ * Creates a new event bus with subscribe, unsubscribe, and emit methods.
+ * @returns {{ subscribe: Function, unsubscribe: Function, emit: Function, emitResourceChange: Function }}
+ */
+export function createEventBus() {
+  const listeners = new Set();
+
+  return {
+    /**
+     * Subscribe a listener function to receive emitted events.
+     * @param {Function} fn - listener receiving the event object
+     */
+    subscribe(fn) {
+      listeners.add(fn);
+    },
+
+    /**
+     * Remove a previously subscribed listener.
+     * @param {Function} fn - the listener to remove
+     */
+    unsubscribe(fn) {
+      listeners.delete(fn);
+    },
+
+    /**
+     * Emit an event to all current subscribers.
+     * @param {object} event - the event payload to broadcast
+     */
+    emit(event) {
+      for (const fn of listeners) {
+        fn(event);
+      }
+    },
+
+    /**
+     * Emit a resource-change event with kind, name, operation, and timestamp.
+     * @param {string} kind - resource kind (e.g. 'Repository')
+     * @param {string} name - resource name
+     * @param {string} operation - operation performed (e.g. 'apply', 'delete')
+     */
+    emitResourceChange(kind, name, operation) {
+      this.emit({
+        type: 'resource-change',
+        kind,
+        name,
+        operation,
+        timestamp: new Date().toISOString()
+      });
+    }
+  };
+}
+
+/**
+ * Module-level singleton event bus shared across the HTTP server and API controller.
+ */
+export const globalEventBus = createEventBus();

package/src/external/conflict-controller.js

@@ -0,0 +1,225 @@
+// External Conflict Controller — Slice 3.5
+// Detects field divergence between local Krate state and external provider state,
+// manages resolution workflows, and handles superseded conflict cleanup.
+
+import { createResource, clone } from '../resource-model.js';
+
+export const CONFLICT_CONTROLLER_BOUNDARY = {
+  role: 'external-conflict-controller',
+  scope: 'Field-level conflict detection and resolution for ExternalSyncConflict resources',
+  owns: ['conflict detection', 'resolution workflow', 'superseded cleanup', 'open conflict listing'],
+  delegatesTo: ['resource-model'],
+  mustNotOwn: ['write intent lifecycle', 'sync scheduling', 'external API client']
+};
+
+const VALID_STRATEGIES = ['prefer-external', 'prefer-krate', 'manual', 'ignore'];
+const OPEN_PHASES = new Set(['Open']);
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate a conflict detection input object.
+ *
+ * @param {object} input
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateConflict(input) {
+  const errors = [];
+  if (!input) {
+    return { valid: false, errors: ['input must not be null or undefined'] };
+  }
+  if (!input.resourceRef || typeof input.resourceRef !== 'string') {
+    errors.push('resourceRef is required and must be a non-empty string');
+  }
+  if (!input.fieldPath || typeof input.fieldPath !== 'string') {
+    errors.push('fieldPath is required and must be a non-empty string');
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Controller factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a ConflictController that manages ExternalSyncConflict resources.
+ *
+ * @param {{ persistFn?: (resource: object) => Promise<any> }} [opts]
+ *   Optional persistFn is called (fire-and-forget) after conflict state changes.
+ * @returns {object}
+ */
+export function createConflictController({ persistFn } = {}) {
+  /**
+   * Fire-and-forget persistence helper.
+   * @param {object} resource
+   */
+  function persist(resource) {
+    if (typeof persistFn === 'function') {
+      Promise.resolve(persistFn(resource)).catch(() => {});
+    }
+  }
+
+  return {
+    role: 'conflict-controller',
+
+    /**
+     * Detect a conflict between local and external field values.
+     * Returns { conflict: null } when values match (no conflict).
+     * Returns { conflict: ExternalSyncConflict } when values differ.
+     *
+     * @param {{ resourceRef, fieldPath, localValue, externalValue, namespace?, organizationRef? }} input
+     * @returns {{ conflict: object|null }}
+     */
+    detectConflict({
+      resourceRef,
+      fieldPath,
+      localValue,
+      externalValue,
+      namespace = 'default',
+      organizationRef = 'default'
+    }) {
+      const validation = validateConflict({ resourceRef, fieldPath });
+      if (!validation.valid) {
+        return { conflict: null, error: true, message: validation.errors.join('; ') };
+      }
+
+      // Values match — no conflict
+      if (localValue === externalValue) {
+        return { conflict: null };
+      }
+
+      const now = new Date().toISOString();
+      const conflictName = `conflict-${resourceRef.replace(/[^a-zA-Z0-9]/g, '-')}-${fieldPath.replace(/[^a-zA-Z0-9]/g, '-')}-${Date.now()}`;
+
+      const conflict = createResource('ExternalSyncConflict', { name: conflictName, namespace }, {
+        organizationRef,
+        resourceRef,
+        fieldPath,
+        localValue,
+        externalValue,
+        detectedAt: now
+      });
+      conflict.status = {
+        phase: 'Open',
+        detectedAt: now
+      };
+
+      persist(conflict);
+      return { conflict };
+    },
+
+    /**
+     * Resolve an Open conflict using the specified strategy.
+     *
+     * Strategies:
+     *   - prefer-external: choose externalValue, phase → Resolved
+     *   - prefer-krate:    choose localValue, phase → Resolved
+     *   - manual:          choose resolvedValue, phase → Resolved (requires resolvedValue)
+     *   - ignore:          phase → Ignored (no value chosen)
+     *
+     * @param {{ conflictName, strategy, resolvedValue?, resources }} opts
+     * @returns {{ conflict: object, resolution: object } | { error: true, message: string }}
+     */
+    resolveConflict({ conflictName, strategy, resolvedValue, resources = {} }) {
+      if (!conflictName) {
+        return { error: true, reason: 'missing-name', message: 'conflictName is required' };
+      }
+      if (!strategy || !VALID_STRATEGIES.includes(strategy)) {
+        return {
+          error: true,
+          reason: 'invalid-strategy',
+          message: `strategy must be one of: ${VALID_STRATEGIES.join(', ')}`
+        };
+      }
+
+      const conflicts = resources.ExternalSyncConflict || [];
+      const found = conflicts.find((c) => c.metadata?.name === conflictName);
+      if (!found) {
+        return { error: true, reason: 'not-found', message: `ExternalSyncConflict not found: ${conflictName}` };
+      }
+      if (found.status?.phase !== 'Open') {
+        return { error: true, reason: 'invalid-phase', message: `Conflict is not Open: ${found.status?.phase}` };
+      }
+
+      const updated = clone(found);
+      const now = new Date().toISOString();
+      let chosenValue;
+      let newPhase;
+
+      if (strategy === 'ignore') {
+        newPhase = 'Ignored';
+        chosenValue = undefined;
+      } else {
+        newPhase = 'Resolved';
+        if (strategy === 'prefer-external') {
+          chosenValue = found.spec.externalValue;
+        } else if (strategy === 'prefer-krate') {
+          chosenValue = found.spec.localValue;
+        } else if (strategy === 'manual') {
+          if (resolvedValue === undefined) {
+            return { error: true, reason: 'missing-resolved-value', message: 'resolvedValue is required for manual strategy' };
+          }
+          chosenValue = resolvedValue;
+        }
+      }
+
+      updated.status = {
+        ...updated.status,
+        phase: newPhase,
+        resolvedAt: now,
+        strategy,
+        chosenValue
+      };
+
+      const resolution = { strategy, chosenValue };
+
+      persist(updated);
+      return { conflict: updated, resolution };
+    },
+
+    /**
+     * Mark all Open conflicts for a given (resourceRef, fieldPath) pair as Superseded.
+     * Used when a new sync event arrives that makes old conflicts irrelevant.
+     *
+     * @param {{ resourceRef, fieldPath, resources }} opts
+     * @returns {{ superseded: object[] }}
+     */
+    supersededCheck({ resourceRef, fieldPath, resources = {} }) {
+      const conflicts = resources.ExternalSyncConflict || [];
+      const now = new Date().toISOString();
+
+      const superseded = [];
+      for (const c of conflicts) {
+        if (
+          c.spec?.resourceRef === resourceRef &&
+          c.spec?.fieldPath === fieldPath &&
+          c.status?.phase === 'Open'
+        ) {
+          const updated = clone(c);
+          updated.status = {
+            ...updated.status,
+            phase: 'Superseded',
+            supersededAt: now
+          };
+          superseded.push(updated);
+        }
+      }
+
+      return { superseded };
+    },
+
+    /**
+     * Return all Open (non-resolved, non-ignored, non-superseded) conflicts.
+     *
+     * @param {{ resources }} opts
+     * @returns {{ conflicts: object[] }}
+     */
+    getOpenConflicts({ resources = {} } = {}) {
+      const conflicts = resources.ExternalSyncConflict || [];
+      const open = conflicts.filter((c) => OPEN_PHASES.has(c.status?.phase));
+      return { conflicts: open };
+    }
+  };
+}

package/src/external/github/auth.js

@@ -0,0 +1,96 @@
+// GitHub App authentication helpers — Slice 3.3a
+// Provides JWT signing (HMAC-SHA256 for test, RSA-SHA256 for production)
+// and installation token exchange. No external dependencies; uses node:crypto.
+
+import { createHmac, createSign } from 'node:crypto';
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * Encode a value as Base64url (RFC 4648 §5, no padding).
+ * @param {string|Buffer} data
+ * @returns {string}
+ */
+function b64url(data) {
+  const buf = Buffer.isBuffer(data) ? data : Buffer.from(data, 'utf8');
+  return buf.toString('base64url');
+}
+
+/**
+ * Create a GitHub App JWT.
+ *
+ * In production, pass a PEM-encoded RSA private key and the function will
+ * use RS256. For unit tests, pass any string key; if it does not look like
+ * a PEM file the function falls back to HS256 (HMAC-SHA256) so tests can
+ * run without real RSA keys.
+ *
+ * @param {{ appId: string, privateKey: string, expiresInSeconds?: number }} opts
+ * @returns {Promise<string>} A signed JWT string.
+ */
+export async function createGitHubJwt({ appId, privateKey, expiresInSeconds = 600 } = {}) {
+  if (!appId) throw new Error('createGitHubJwt: appId is required');
+  if (!privateKey) throw new Error('createGitHubJwt: privateKey is required');
+
+  const now = Math.floor(Date.now() / 1000);
+  const isRsa = privateKey.includes('-----BEGIN');
+
+  const alg = isRsa ? 'RS256' : 'HS256';
+
+  const header = b64url(JSON.stringify({ alg, typ: 'JWT' }));
+  const payload = b64url(JSON.stringify({
+    iat: now,
+    exp: now + expiresInSeconds,
+    iss: appId
+  }));
+
+  const signingInput = `${header}.${payload}`;
+
+  let signature;
+  if (isRsa) {
+    const sign = createSign('RSA-SHA256');
+    sign.update(signingInput);
+    sign.end();
+    signature = sign.sign(privateKey, 'base64url');
+  } else {
+    // HMAC-SHA256 fallback (test mode only)
+    const hmac = createHmac('sha256', privateKey);
+    hmac.update(signingInput);
+    signature = hmac.digest('base64url');
+  }
+
+  return `${signingInput}.${signature}`;
+}
+
+/**
+ * Exchange a GitHub App JWT for an installation access token.
+ *
+ * @param {{ appJwt: string, installationId: string|number, fetchImpl?: Function }} opts
+ * @returns {Promise<{ token: string, expiresAt: string }>}
+ */
+export async function exchangeInstallationToken({ appJwt, installationId, fetchImpl = globalThis.fetch } = {}) {
+  if (!appJwt) throw new Error('exchangeInstallationToken: appJwt is required');
+  if (!installationId) throw new Error('exchangeInstallationToken: installationId is required');
+  if (!fetchImpl) throw new Error('exchangeInstallationToken: a fetch implementation is required');
+
+  const url = `${GITHUB_API}/app/installations/${installationId}/access_tokens`;
+
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      Authorization: `Bearer ${appJwt}`,
+      'X-GitHub-Api-Version': '2022-11-28',
+      'Content-Type': 'application/json'
+    }
+  });
+
+  if (!response.ok) {
+    throw new Error(`exchangeInstallationToken: GitHub API returned ${response.status} — authentication or token exchange failed`);
+  }
+
+  const data = await response.json();
+  return {
+    token: data.token,
+    expiresAt: data.expires_at
+  };
+}