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

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);
+  }
+}

package/src/external/github/git-forge.js

@@ -0,0 +1,240 @@
+// GitHub Git Forge implementation — Slice 3.3a
+// Implements the gitForge interface contract:
+//   listRepositories, getPullRequest, createPullRequest, mergePullRequest,
+//   listRefs, syncDeployKeys, syncBranchProtection
+//
+// All HTTP calls are injected via fetchImpl for full testability.
+
+const GITHUB_API = 'https://api.github.com';
+const VALID_MERGE_METHODS = new Set(['merge', 'squash', 'rebase']);
+
+/**
+ * @typedef {{ name: string, fullName: string, private: boolean, defaultBranch: string, cloneUrl: string }} NormalizedRepo
+ * @typedef {{ number: number, title: string, state: string, head: object, base: object, body: string, merged: boolean, htmlUrl: string }} NormalizedPR
+ * @typedef {{ name: string, sha: string, protected: boolean }} NormalizedBranch
+ * @typedef {{ name: string, sha: string }} NormalizedTag
+ */
+
+/**
+ * GitHub implementation of the git forge interface.
+ *
+ * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+ */
+export class GitHubGitForge {
+  constructor({ owner, installationToken, fetchImpl = globalThis.fetch } = {}) {
+    if (!owner) throw new Error('GitHubGitForge: owner (org or user) is required');
+    if (!installationToken) throw new Error('GitHubGitForge: installationToken is required');
+    if (!fetchImpl) throw new Error('GitHubGitForge: a fetch implementation is required');
+
+    this.role = 'github-git-forge';
+    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}`;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Interface methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * List all repositories for the installation.
+   * @returns {Promise<NormalizedRepo[]>}
+   */
+  async listRepositories() {
+    const data = await this._request('GET', `/installation/repositories`);
+    const repos = data?.repositories ?? data ?? [];
+    return repos.map(r => ({
+      id: r.id,
+      name: r.name,
+      fullName: r.full_name,
+      private: r.private,
+      defaultBranch: r.default_branch,
+      cloneUrl: r.clone_url,
+      sshUrl: r.ssh_url
+    }));
+  }
+
+  /**
+   * Get a single pull request by number.
+   * @param {{ repo: string, pullNumber: number }} opts
+   * @returns {Promise<NormalizedPR>}
+   */
+  async getPullRequest({ repo, pullNumber }) {
+    const data = await this._request('GET', this._repoPath(repo, `/pulls/${pullNumber}`));
+    return this._normalizePR(data);
+  }
+
+  /**
+   * Create a pull request.
+   * @param {{ repo: string, title: string, head: string, base: string, body?: string }} opts
+   * @returns {Promise<NormalizedPR>}
+   */
+  async createPullRequest({ repo, title, head, base, body = '' }) {
+    const data = await this._request('POST', this._repoPath(repo, '/pulls'), {
+      title,
+      head,
+      base,
+      body
+    });
+    return this._normalizePR(data);
+  }
+
+  /**
+   * Merge a pull request.
+   * @param {{ repo: string, pullNumber: number, mergeMethod?: 'merge'|'squash'|'rebase', commitTitle?: string }} opts
+   * @returns {Promise<{ merged: boolean, sha: string, message: string }>}
+   */
+  async mergePullRequest({ repo, pullNumber, mergeMethod = 'merge', commitTitle } = {}) {
+    if (!VALID_MERGE_METHODS.has(mergeMethod)) {
+      throw new Error(
+        `GitHubGitForge.mergePullRequest: invalid mergeMethod "${mergeMethod}". ` +
+        `Valid values are: ${[...VALID_MERGE_METHODS].join(', ')}`
+      );
+    }
+    const payload = { merge_method: mergeMethod };
+    if (commitTitle) payload.commit_title = commitTitle;
+    const data = await this._request('PUT', this._repoPath(repo, `/pulls/${pullNumber}/merge`), payload);
+    return {
+      merged: data?.merged ?? true,
+      sha: data?.sha ?? '',
+      message: data?.message ?? ''
+    };
+  }
+
+  /**
+   * List branches and tags for a repository.
+   * @param {{ repo: string }} opts
+   * @returns {Promise<{ branches: NormalizedBranch[], tags: NormalizedTag[] }>}
+   */
+  async listRefs({ repo }) {
+    const [branchData, tagData] = await Promise.all([
+      this._request('GET', this._repoPath(repo, '/branches')),
+      this._request('GET', this._repoPath(repo, '/tags'))
+    ]);
+
+    const branches = (branchData ?? []).map(b => ({
+      name: b.name,
+      sha: b.commit?.sha ?? b.sha,
+      protected: b.protected ?? false
+    }));
+
+    const tags = (tagData ?? []).map(t => ({
+      name: t.name,
+      sha: t.commit?.sha ?? t.sha
+    }));
+
+    return { branches, tags };
+  }
+
+  /**
+   * Sync deploy keys: add missing, remove extra.
+   * @param {{ repo: string, desiredKeys: Array<{ title: string, key: string, readOnly: boolean }> }} opts
+   * @returns {Promise<{ added: number, removed: number }>}
+   */
+  async syncDeployKeys({ repo, desiredKeys = [] }) {
+    const current = await this._request('GET', this._repoPath(repo, '/keys'));
+    const currentList = current ?? [];
+
+    // Find keys to remove (title not in desired)
+    const desiredTitles = new Set(desiredKeys.map(k => k.title));
+    const toRemove = currentList.filter(k => !desiredTitles.has(k.title));
+
+    // Find keys to add (title not in current)
+    const currentTitles = new Set(currentList.map(k => k.title));
+    const toAdd = desiredKeys.filter(k => !currentTitles.has(k.title));
+
+    // Perform deletions
+    await Promise.all(toRemove.map(k =>
+      this._request('DELETE', this._repoPath(repo, `/keys/${k.id}`))
+    ));
+
+    // Perform additions
+    await Promise.all(toAdd.map(k =>
+      this._request('POST', this._repoPath(repo, '/keys'), {
+        title: k.title,
+        key: k.key,
+        read_only: k.readOnly ?? true
+      })
+    ));
+
+    return { added: toAdd.length, removed: toRemove.length };
+  }
+
+  /**
+   * Sync branch protection rules.
+   * @param {{ repo: string, branch: string, requiredReviews?: number, requiredStatusChecks?: string[], dismissStaleReviews?: boolean, enforceAdmins?: boolean }} opts
+   * @returns {Promise<object>}
+   */
+  async syncBranchProtection({
+    repo,
+    branch = 'main',
+    requiredReviews = 1,
+    requiredStatusChecks = [],
+    dismissStaleReviews = false,
+    enforceAdmins = false
+  } = {}) {
+    const payload = {
+      required_status_checks: requiredStatusChecks.length > 0
+        ? { strict: true, contexts: requiredStatusChecks }
+        : null,
+      enforce_admins: enforceAdmins,
+      required_pull_request_reviews: {
+        dismiss_stale_reviews: dismissStaleReviews,
+        require_code_owner_reviews: false,
+        required_approving_review_count: requiredReviews
+      },
+      restrictions: null
+    };
+
+    return this._request('PUT', this._repoPath(repo, `/branches/${encodeURIComponent(branch)}/protection`), payload);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal normalizer
+  // ---------------------------------------------------------------------------
+
+  _normalizePR(data) {
+    return {
+      number: data.number,
+      title: data.title,
+      state: data.state,
+      head: { ref: data.head?.ref, sha: data.head?.sha },
+      base: { ref: data.base?.ref, sha: data.base?.sha },
+      body: data.body ?? '',
+      merged: data.merged ?? false,
+      htmlUrl: data.html_url ?? ''
+    };
+  }
+}

package/src/external/github/index.js

@@ -0,0 +1,144 @@
+// GitHub External Provider — Slice 3.3a / 3.3b
+// Entry point for the GitHub provider adapter.
+// Re-exports auth helpers, git forge class, issue tracking, CI/CD, boundary objects, and provider factory.
+
+export { createGitHubJwt, exchangeInstallationToken } from './auth.js';
+
+import { GitHubGitForge } from './git-forge.js';
+import { GitHubIssueTracking } from './issue-tracking.js';
+import { GitHubCicd } from './cicd.js';
+
+export { GitHubGitForge };
+export { GitHubIssueTracking };
+export { GitHubCicd };
+
+// ---------------------------------------------------------------------------
+// Boundary declarations
+// ---------------------------------------------------------------------------
+
+export const GITHUB_GIT_FORGE_BOUNDARY = Object.freeze({
+  role: 'github-git-forge',
+  scope: 'GitHub App authentication (JWT signing, installation token exchange) and Git forge operations (repositories, PRs, refs, deploy keys, branch protection)',
+  owns: [
+    'GitHub App JWT creation',
+    'installation token exchange',
+    'repository listing',
+    'pull request lifecycle',
+    'ref enumeration',
+    'deploy key synchronisation',
+    'branch protection synchronisation'
+  ],
+  delegatesTo: [],
+  mustNotOwn: [
+    'GitHub secret storage',
+    'Kubernetes resources',
+    'CI pipeline execution',
+    'webhook delivery'
+  ]
+});
+
+export const GITHUB_ISSUE_TRACKING_BOUNDARY = Object.freeze({
+  role: 'github-issue-tracking',
+  scope: 'GitHub Issues API: listing, creating, updating, closing issues and managing issue comments',
+  owns: [
+    'issue listing',
+    'issue creation',
+    'issue updates',
+    'issue closing',
+    'comment listing',
+    'comment creation'
+  ],
+  delegatesTo: [],
+  mustNotOwn: [
+    'GitHub secret storage',
+    'Kubernetes resources',
+    'CI pipeline execution',
+    'webhook delivery',
+    'pull requests',
+    'branch protection'
+  ]
+});
+
+export const GITHUB_CICD_BOUNDARY = Object.freeze({
+  role: 'github-cicd',
+  scope: 'GitHub Actions API: workflow runs, jobs, rerun/cancel operations, and check runs',
+  owns: [
+    'workflow run listing',
+    'job listing',
+    'workflow rerun',
+    'workflow cancellation',
+    'check run creation',
+    'check run updates'
+  ],
+  delegatesTo: [],
+  mustNotOwn: [
+    'GitHub secret storage',
+    'Kubernetes resources',
+    'webhook delivery',
+    'issue tracking',
+    'pull requests'
+  ]
+});
+
+// ---------------------------------------------------------------------------
+// Provider factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a GitHub ExternalProviderAdapter.
+ *
+ * Returns a lightweight descriptor that carries GitHub App credentials and
+ * exposes factory methods for constructing GitHubGitForge, GitHubIssueTracking,
+ * and GitHubCicd instances bound to specific installation tokens.
+ *
+ * @param {{ appId: string, privateKey: string, installationId?: string, fetchImpl?: Function }} opts
+ * @returns {{ type: string, config: object, createForge: Function, createIssueTracker: Function, createCicd: Function }}
+ */
+export function createGitHubProvider({ appId, privateKey, installationId, fetchImpl } = {}) {
+  if (!appId) throw new Error('createGitHubProvider: appId is required');
+  if (!privateKey) throw new Error('createGitHubProvider: privateKey is required');
+
+  return {
+    type: 'github',
+    config: Object.freeze({ appId, installationId }),
+
+    /**
+     * Construct a GitHubGitForge for the given owner and installation token.
+     * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} forgeOpts
+     * @returns {GitHubGitForge}
+     */
+    createForge({ owner, installationToken, fetchImpl: forgeFetch } = {}) {
+      return new GitHubGitForge({
+        owner,
+        installationToken,
+        fetchImpl: forgeFetch ?? fetchImpl ?? globalThis.fetch
+      });
+    },
+
+    /**
+     * Construct a GitHubIssueTracking for the given owner and installation token.
+     * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+     * @returns {GitHubIssueTracking}
+     */
+    createIssueTracker({ owner, installationToken, fetchImpl: trackerFetch } = {}) {
+      return new GitHubIssueTracking({
+        owner,
+        installationToken,
+        fetchImpl: trackerFetch ?? fetchImpl ?? globalThis.fetch
+      });
+    },
+
+    /**
+     * Construct a GitHubCicd for the given owner and installation token.
+     * @param {{ owner: string, installationToken: string, fetchImpl?: Function }} opts
+     * @returns {GitHubCicd}
+     */
+    createCicd({ owner, installationToken, fetchImpl: cicdFetch } = {}) {
+      return new GitHubCicd({
+        owner,
+        installationToken,
+        fetchImpl: cicdFetch ?? fetchImpl ?? globalThis.fetch
+      });
+    }
+  };
+}