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

package/src/external/conflict-controller.js

@@ -0,0 +1,225 @@
+// External Conflict Controller — Slice 3.5
+// Detects field divergence between local Kradle 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-kradle', '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-kradle:    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-kradle') {
+          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
+  };
+}

package/src/external/github/cicd.js

@@ -0,0 +1,180 @@
+// GitHub CI/CD implementation — Slice 3.3b
+// Implements the cicd interface contract:
+//   listWorkflowRuns, listJobs, rerunWorkflow, cancelWorkflow, createCheck, updateCheck
+//
+// All HTTP calls are injected via fetchImpl for full testability.
+
+const GITHUB_API = 'https://api.github.com';
+
+/**
+ * @typedef {{ id: number, name: string, status: string, conclusion: string|null, headBranch: string, headSha: string, htmlUrl: string, createdAt: string, updatedAt: string }} NormalizedWorkflowRun
+ * @typedef {{ id: number, name: string, status: string, conclusion: string|null, startedAt: string, completedAt: string, htmlUrl: string }} NormalizedJob
+ * @typedef {{ id: number, name: string, status: string, conclusion: string|null, htmlUrl: string }} NormalizedCheckRun
+ */
+
+/**
+ * GitHub implementation of the cicd interface.
+ *
+ * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+ */
+export class GitHubCicd {
+  constructor({ owner, installationToken, fetchImpl = globalThis.fetch } = {}) {
+    if (!owner) throw new Error('GitHubCicd: owner (org or user) is required');
+    if (!installationToken) throw new Error('GitHubCicd: installationToken is required');
+    if (!fetchImpl) throw new Error('GitHubCicd: a fetch implementation is required');
+
+    this.role = 'github-cicd';
+    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
+  // ---------------------------------------------------------------------------
+
+  _normalizeRun(data) {
+    return {
+      id: data.id,
+      name: data.name ?? '',
+      status: data.status ?? '',
+      conclusion: data.conclusion ?? null,
+      headBranch: data.head_branch ?? '',
+      headSha: data.head_sha ?? '',
+      htmlUrl: data.html_url ?? '',
+      createdAt: data.created_at ?? '',
+      updatedAt: data.updated_at ?? ''
+    };
+  }
+
+  _normalizeJob(data) {
+    return {
+      id: data.id,
+      name: data.name ?? '',
+      status: data.status ?? '',
+      conclusion: data.conclusion ?? null,
+      startedAt: data.started_at ?? '',
+      completedAt: data.completed_at ?? '',
+      htmlUrl: data.html_url ?? ''
+    };
+  }
+
+  _normalizeCheckRun(data) {
+    return {
+      id: data.id,
+      name: data.name ?? '',
+      status: data.status ?? '',
+      conclusion: data.conclusion ?? null,
+      htmlUrl: data.html_url ?? ''
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Interface methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * List workflow runs for a repository (optionally filtered by workflow file name).
+   * @param {{ repo: string, workflowId?: string|number }} opts
+   * @returns {Promise<NormalizedWorkflowRun[]>}
+   */
+  async listWorkflowRuns({ repo, workflowId } = {}) {
+    const path = workflowId
+      ? this._repoPath(repo, `/actions/workflows/${encodeURIComponent(workflowId)}/runs`)
+      : this._repoPath(repo, '/actions/runs');
+    const data = await this._request('GET', path);
+    const runs = data?.workflow_runs ?? data ?? [];
+    return runs.map(r => this._normalizeRun(r));
+  }
+
+  /**
+   * List jobs for a specific workflow run.
+   * @param {{ repo: string, runId: number }} opts
+   * @returns {Promise<NormalizedJob[]>}
+   */
+  async listJobs({ repo, runId } = {}) {
+    const data = await this._request('GET', this._repoPath(repo, `/actions/runs/${runId}/jobs`));
+    const jobs = data?.jobs ?? data ?? [];
+    return jobs.map(j => this._normalizeJob(j));
+  }
+
+  /**
+   * Trigger a re-run of a workflow run.
+   * @param {{ repo: string, runId: number }} opts
+   * @returns {Promise<{ triggered: boolean, runId: number }>}
+   */
+  async rerunWorkflow({ repo, runId } = {}) {
+    await this._request('POST', this._repoPath(repo, `/actions/runs/${runId}/rerun`));
+    return { triggered: true, runId };
+  }
+
+  /**
+   * Cancel a workflow run.
+   * @param {{ repo: string, runId: number }} opts
+   * @returns {Promise<{ cancelled: boolean, runId: number }>}
+   */
+  async cancelWorkflow({ repo, runId } = {}) {
+    await this._request('POST', this._repoPath(repo, `/actions/runs/${runId}/cancel`));
+    return { cancelled: true, runId };
+  }
+
+  /**
+   * Create a check run on a commit.
+   * @param {{ repo: string, name: string, headSha: string, status?: string, conclusion?: string, detailsUrl?: string, output?: object }} opts
+   * @returns {Promise<NormalizedCheckRun>}
+   */
+  async createCheck({ repo, name, headSha, status = 'queued', conclusion, detailsUrl, output } = {}) {
+    const payload = { name, head_sha: headSha, status };
+    if (conclusion !== undefined) payload.conclusion = conclusion;
+    if (detailsUrl !== undefined) payload.details_url = detailsUrl;
+    if (output !== undefined) payload.output = output;
+    const data = await this._request('POST', this._repoPath(repo, '/check-runs'), payload);
+    return this._normalizeCheckRun(data);
+  }
+
+  /**
+   * Update an existing check run.
+   * @param {{ repo: string, checkRunId: number, status?: string, conclusion?: string, output?: object }} opts
+   * @returns {Promise<NormalizedCheckRun>}
+   */
+  async updateCheck({ repo, checkRunId, status, conclusion, output } = {}) {
+    const payload = {};
+    if (status !== undefined) payload.status = status;
+    if (conclusion !== undefined) payload.conclusion = conclusion;
+    if (output !== undefined) payload.output = output;
+    const data = await this._request('PATCH', this._repoPath(repo, `/check-runs/${checkRunId}`), payload);
+    return this._normalizeCheckRun(data);
+  }
+}