Interface: IVCSProvider

Makaio Framework / contracts / IVCSProvider

Interface: IVCSProvider

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:77

VCS provider capability for source control platform integration.

Enables GitHub, GitLab, Bitbucket, and other version control systems to be pluggable providers of VCS functionality.

This interface defines both the core Phase 1 methods and Phase 2 optional extension seams for write operations.

Example

class GitHubVCSProvider implements IVCSProvider {
  readonly id = 'github-vcs';
  readonly displayName = 'GitHub';
  readonly capabilityId = 'vcs';

  async getRepository(repoPath: string) {
    // Detect GitHub repo and return metadata
  }

  async getPullRequests(repoPath: string, branch: string) {
    // Fetch PRs via GitHub API
  }

  // Phase 2: Optional write operations
  async createPullRequest?(repoPath: string, options: CreatePROptions) {
    // Create PR via GitHub API
  }
}

Extends

ICapabilityProvider

Properties

capabilityId

readonly capabilityId: "vcs"

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:79

Capability identifier - must be ‘vcs’

displayName

readonly displayName: string

Defined in: ../../../packages/contracts/src/capability/types.ts:11

Human-readable name for display in UI

Inherited from

ICapabilityProvider.displayName

id

readonly id: string

Defined in: ../../../packages/contracts/src/capability/types.ts:9

Unique identifier for this provider instance

Inherited from

ICapabilityProvider.id

providerKey?

readonly optional providerKey?: string

Defined in: ../../../packages/contracts/src/capability/types.ts:17

Stable provider identity used for joins across registries.

Unlike id, this should remain stable across runtime re-registration.

Inherited from

ICapabilityProvider.providerKey

Methods

createPullRequest()?

optional createPullRequest(repoPath, options): Promise<{ additions?: number; author: string; baseBranch: string; branch: string; changedFiles?: number; commentCount?: number; createdAt: string; deletions?: number; draft: boolean; head?: { ref: string; sha: string; } | null; id: string; mergedAt: string | null; number: number; reviewCount?: number; state: "merged" | "closed" | "open"; title: string; updatedAt: string; url: string; }>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:168

Create a new pull request (Phase 2).

Optional method for providers that support PR creation.

Parameters

repoPath

string

Local filesystem path to the repository

options

CreatePROptions

PR creation options

Returns

Promise<{ additions?: number; author: string; baseBranch: string; branch: string; changedFiles?: number; commentCount?: number; createdAt: string; deletions?: number; draft: boolean; head?: { ref: string; sha: string; } | null; id: string; mergedAt: string | null; number: number; reviewCount?: number; state: "merged" | "closed" | "open"; title: string; updatedAt: string; url: string; }>

Created pull request information

createReviewComment()?

optional createReviewComment(repoPath, prNumber, path, line, commitId, body, side?): Promise<{ author: string; body: string; createdAt: string; diffHunk?: string | null; id: number; inReplyToId: number | null; isResolved?: boolean | null; line: number | null; path: string | null; threadId?: string | null; updatedAt: string; }>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:228

Post a new inline comment on a file:line (Phase 2).

Optional method for providers that support inline code comments.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

path

string

File path relative to repo root

line

number

Line number (1-based)

commitId

string

Commit SHA the comment refers to

body

string

Comment body text

side?

"LEFT" | "RIGHT"

Which side of diff (LEFT=base, RIGHT=head)

Returns

Promise<{ author: string; body: string; createdAt: string; diffHunk?: string | null; id: number; inReplyToId: number | null; isResolved?: boolean | null; line: number | null; path: string | null; threadId?: string | null; updatedAt: string; }>

Created comment

getChecks()

getChecks(repoPath, commitSha): Promise<object[]>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:133

Get CI/CD check runs for a commit.

Returns the status of CI/CD workflows and checks for a given commit.

Parameters

repoPath

string

Local filesystem path to the repository

commitSha

string

Commit SHA to get checks for

Returns

Promise<object[]>

Array of check runs

getPRsForFile()

getPRsForFile(repoPath, filePath): Promise<object[]>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:121

Get open PRs that have changes affecting a specific file.

Parameters

repoPath

string

Local filesystem path to the repository

filePath

string

Path to file relative to repo root

Returns

Promise<object[]>

Array of pull requests affecting the file

getPullRequest()

getPullRequest(repoPath, prNumber): Promise<{ additions?: number; assignees: string[]; author: string; baseBranch: string; body: string | null; branch: string; changedFiles?: number; commentCount?: number; createdAt: string; deletions?: number; draft: boolean; head?: { ref: string; sha: string; } | null; id: string; labels: string[]; mergeable: boolean | null; mergeableState?: string; mergedAt: string | null; number: number; requestedReviewers: string[]; reviewCount?: number; reviews: object[]; state: "merged" | "closed" | "open"; title: string; updatedAt: string; url: string; }>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:113

Get detailed information about a specific pull request.

Returns full PR details including reviews, labels, and assignees.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

Returns

Promise<{ additions?: number; assignees: string[]; author: string; baseBranch: string; body: string | null; branch: string; changedFiles?: number; commentCount?: number; createdAt: string; deletions?: number; draft: boolean; head?: { ref: string; sha: string; } | null; id: string; labels: string[]; mergeable: boolean | null; mergeableState?: string; mergedAt: string | null; number: number; requestedReviewers: string[]; reviewCount?: number; reviews: object[]; state: "merged" | "closed" | "open"; title: string; updatedAt: string; url: string; }>

Detailed pull request information

getPullRequests()

getPullRequests(repoPath, branch): Promise<object[]>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:103

List pull requests for a repository branch.

Returns summary information for PRs, suitable for list views.

Parameters

repoPath

string

Local filesystem path to the repository

branch

string

Branch name to filter by (empty for all branches)

Returns

Promise<object[]>

Array of pull request summaries

getRepository()

getRepository(repoPath): Promise<{ defaultBranch?: string; owner: string; provider: string; repo: string; url: string; } | null>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:91

Get repository metadata for a local filesystem path.

Detects if the given path is a VCS repository and returns metadata about the remote repository (provider, owner, repo name, etc.).

Parameters

repoPath

string

Local filesystem path to the repository

Returns

Promise<{ defaultBranch?: string; owner: string; provider: string; repo: string; url: string; } | null>

Repository metadata, or null if not a VCS repository

getReviewComments()

getReviewComments(repoPath, prNumber): Promise<object[]>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:156

Get review comments for a pull request.

Returns both inline code comments and general PR comments.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

Returns

Promise<object[]>

Array of review comments

getStatuses()

getStatuses(repoPath, commitSha): Promise<object[]>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:144

Get commit statuses for a commit (legacy status API).

Returns statuses reported via the commit status API (e.g., CodeRabbit). Distinct from check runs which come from GitHub Actions / Apps.

Parameters

repoPath

string

Local filesystem path to the repository

commitSha

string

Commit SHA to get statuses for

Returns

Promise<object[]>

Array of commit statuses

getWriteCapability()?

optional getWriteCapability(repoPath): Promise<{ canWrite: boolean; level: "none" | "read" | "triage" | "write" | "maintain" | "admin"; }>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:256

Get write capability level for current user (Phase 2).

Optional method for checking user’s write permissions.

Parameters

repoPath

string

Local filesystem path to the repository

Returns

Promise<{ canWrite: boolean; level: "none" | "read" | "triage" | "write" | "maintain" | "admin"; }>

Permission capability

mergePullRequest()?

optional mergePullRequest(repoPath, prNumber, options?): Promise<void>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:199

Merge a pull request (Phase 2).

Optional method for providers that support PR merging.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

options?

MergeOptions

Merge options

Returns

Promise<void>

postComment()?

optional postComment(repoPath, prNumber, body): Promise<{ author: string; body: string; createdAt: string; diffHunk?: string | null; id: number; inReplyToId: number | null; isResolved?: boolean | null; line: number | null; path: string | null; threadId?: string | null; updatedAt: string; }>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:179

Post a comment on a pull request (Phase 2).

Optional method for providers that support posting comments.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

body

string

Comment body text

Returns

Created comment information

replyToComment()?

optional replyToComment(repoPath, prNumber, commentId, body): Promise<{ author: string; body: string; createdAt: string; diffHunk?: string | null; id: number; inReplyToId: number | null; isResolved?: boolean | null; line: number | null; path: string | null; threadId?: string | null; updatedAt: string; }>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:213

Reply to an existing review comment (Phase 2).

Optional method for providers that support comment replies.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

commentId

number

ID of the comment to reply to

body

string

Reply body text

Returns

Created reply comment

requestReview()?

optional requestReview(repoPath, prNumber, reviewers): Promise<void>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:189

Request reviews from users for a pull request (Phase 2).

Optional method for providers that support review requests.

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

reviewers

string[]

Usernames to request reviews from

Returns

Promise<void>

resolveThread()?

optional resolveThread(repoPath, prNumber, threadId): Promise<void>

Defined in: ../../../packages/contracts/src/capabilities/vcs/types.ts:247

Resolve a review thread (Phase 2).

Optional method for providers that support thread resolution. Uses GraphQL for GitHub (resolveReviewThread mutation).

Parameters

repoPath

string

Local filesystem path to the repository

prNumber

number

Pull request number

threadId

string

Thread ID (GraphQL node ID)

Returns

Promise<void>

validate()?

optional validate(): Promise<{ error?: string; valid: boolean; }>

Defined in: ../../../packages/contracts/src/capability/types.ts:22

Optional validation method to check provider configuration/credentials.

Returns

Promise<{ error?: string; valid: boolean; }>

Validation result with optional error message

Inherited from

ICapabilityProvider.validate