@forge-glance/sdk 0.1.0 → 0.2.0

package/src/GitProvider.ts

@@ -1,4 +1,14 @@
-import type { Discussion, MRDetail, PullRequest, UserRef } from "./types.ts";
+import type {
+  BranchProtectionRule,
+  CreatePullRequestInput,
+  Discussion,
+  MergePullRequestInput,
+  MRDetail,
+  ProviderCapabilities,
+  PullRequest,
+  UpdatePullRequestInput,
+  UserRef
+} from './types.ts';
 
 /**
  * Provider-agnostic interface for a Git hosting service.
@@ -31,17 +41,153 @@ export interface GitProvider {
   fetchSingleMR(
     projectPath: string,
     mrIid: number,
-    currentUserNumericId: number | null,
+    currentUserNumericId: number | null
   ): Promise<PullRequest | null>;
 
+  /**
+   * Fetch a single MR/PR by its source branch within a project.
+   * Returns null if no open MR/PR exists for that branch.
+   */
+  fetchPullRequestByBranch(
+    projectPath: string,
+    sourceBranch: string
+  ): Promise<PullRequest | null>;
+
+  /**
+   * Create a new merge request / pull request.
+   * Returns the created PullRequest.
+   */
+  createPullRequest(input: CreatePullRequestInput): Promise<PullRequest>;
+
+  /**
+   * Update an existing merge request / pull request.
+   * Returns the updated PullRequest.
+   */
+  updatePullRequest(
+    projectPath: string,
+    mrIid: number,
+    input: UpdatePullRequestInput
+  ): Promise<PullRequest>;
+
+  /**
+   * Fetch branch protection rules for a repository.
+   * Returns an array of rules (one per protected branch/pattern).
+   */
+  fetchBranchProtectionRules(
+    projectPath: string
+  ): Promise<BranchProtectionRule[]>;
+
+  /**
+   * Delete a branch from the repository.
+   * @throws if the branch doesn't exist or is protected.
+   */
+  deleteBranch(projectPath: string, branch: string): Promise<void>;
+
   /**
    * Fetch discussions (comments, threads) for a specific MR/PR.
    * Returns the MRDetail with discussions populated.
    */
-  fetchMRDiscussions(
-    repositoryId: string,
+  fetchMRDiscussions(repositoryId: string, mrIid: number): Promise<MRDetail>;
+
+  // ── Mutation capabilities ───────────────────────────────────────────────
+
+  /**
+   * Reports which mutation operations this provider supports.
+   * Callers should check these flags to conditionally show/hide UI
+   * affordances without knowing which provider they're talking to.
+   */
+  readonly capabilities: ProviderCapabilities;
+
+  // ── MR lifecycle mutations ──────────────────────────────────────────────
+
+  /**
+   * Merge (accept) a pull request / merge request.
+   * All input fields are optional — omitting them defers to the project's
+   * configured defaults (merge method, squash policy, delete-source-branch).
+   */
+  mergePullRequest(
+    projectPath: string,
+    mrIid: number,
+    input?: MergePullRequestInput
+  ): Promise<PullRequest>;
+
+  /**
+   * Approve a pull request / merge request.
+   * On GitLab: POST /merge_requests/:iid/approve
+   * On GitHub: POST /pulls/:number/reviews with event "APPROVE"
+   */
+  approvePullRequest(projectPath: string, mrIid: number): Promise<void>;
+
+  /**
+   * Revoke an existing approval.
+   * GitLab-only — GitHub does not support unapproving via API.
+   * Check `capabilities.canUnapprove` before calling.
+   */
+  unapprovePullRequest(projectPath: string, mrIid: number): Promise<void>;
+
+  /**
+   * Rebase the MR source branch onto the target branch.
+   * GitLab-only — GitHub does not have a native rebase API.
+   * Check `capabilities.canRebase` before calling.
+   */
+  rebasePullRequest(projectPath: string, mrIid: number): Promise<void>;
+
+  /**
+   * Enable auto-merge: the MR will be merged automatically when the
+   * pipeline succeeds and all approval rules are met.
+   * GitLab-only — check `capabilities.canAutoMerge` before calling.
+   */
+  setAutoMerge(projectPath: string, mrIid: number): Promise<void>;
+
+  /**
+   * Cancel a previously enabled auto-merge.
+   * GitLab-only — check `capabilities.canAutoMerge` before calling.
+   */
+  cancelAutoMerge(projectPath: string, mrIid: number): Promise<void>;
+
+  // ── Discussion mutations ────────────────────────────────────────────────
+
+  /**
+   * Resolve a discussion thread on an MR.
+   * GitLab-only — check `capabilities.canResolveDiscussions` before calling.
+   */
+  resolveDiscussion(
+    projectPath: string,
+    mrIid: number,
+    discussionId: string
+  ): Promise<void>;
+
+  /**
+   * Unresolve a previously resolved discussion thread.
+   * GitLab-only — check `capabilities.canResolveDiscussions` before calling.
+   */
+  unresolveDiscussion(
+    projectPath: string,
+    mrIid: number,
+    discussionId: string
+  ): Promise<void>;
+
+  // ── Pipeline mutations ──────────────────────────────────────────────────
+
+  /**
+   * Retry a failed or canceled pipeline.
+   * On GitLab: POST /pipelines/:id/retry
+   * On GitHub: POST re-run for the workflow run.
+   */
+  retryPipeline(projectPath: string, pipelineId: number): Promise<void>;
+
+  // ── Review mutations ────────────────────────────────────────────────────
+
+  /**
+   * Re-request review attention on an MR from its reviewers.
+   * If `reviewerUsernames` is provided, only those reviewers are pinged;
+   * otherwise all current reviewers are re-requested.
+   */
+  requestReReview(
+    projectPath: string,
     mrIid: number,
-  ): Promise<MRDetail>;
+    reviewerUsernames?: string[]
+  ): Promise<void>;
 
   // ── REST pass-through (used by note mutations, job traces, etc.) ────────
 
@@ -52,11 +198,7 @@ export interface GitProvider {
    *
    * Implementations translate the path to the provider's API URL format.
    */
-  restRequest(
-    method: string,
-    path: string,
-    body?: unknown,
-  ): Promise<Response>;
+  restRequest(method: string, path: string, body?: unknown): Promise<Response>;
 }
 
 /**
@@ -64,8 +206,8 @@ export interface GitProvider {
  * e.g. "gitlab:42" → 42, "github:12345" → 12345
  */
 export function parseRepoId(repositoryId: string): number {
-  const parts = repositoryId.split(":");
-  return parseInt(parts.at(-1) ?? "0", 10);
+  const parts = repositoryId.split(':');
+  return parseInt(parts.at(-1) ?? '0', 10);
 }
 
 /**
@@ -73,5 +215,5 @@ export function parseRepoId(repositoryId: string): number {
  * e.g. "gitlab:42" → "gitlab", "github:12345" → "github"
  */
 export function repoIdProvider(repositoryId: string): string {
-  return repositoryId.split(":")[0] ?? "unknown";
+  return repositoryId.split(':')[0] ?? 'unknown';
 }

package/src/index.ts

@@ -16,6 +16,12 @@
 export type {
   PullRequest,
   PullRequestsSnapshot,
+  CreatePullRequestInput,
+  UpdatePullRequestInput,
+  MergePullRequestInput,
+  MergeMethod,
+  ProviderCapabilities,
+  BranchProtectionRule,
   Pipeline,
   PipelineJob,
   UserRef,
@@ -27,28 +33,32 @@ export type {
   MRDetail,
   FeedEvent,
   FeedSnapshot,
-  ServerNotification,
-} from "./types.ts";
+  ServerNotification
+} from './types.ts';
 
 // ── Provider interface ────────────────────────────────────────────────────────
-export type { GitProvider } from "./GitProvider.ts";
-export { parseRepoId, repoIdProvider } from "./GitProvider.ts";
+export type { GitProvider } from './GitProvider.ts';
+export { parseRepoId, repoIdProvider } from './GitProvider.ts';
 
 // ── Logger ────────────────────────────────────────────────────────────────────
-export type { ForgeLogger } from "./logger.ts";
-export { noopLogger } from "./logger.ts";
+export type { ForgeLogger } from './logger.ts';
+export { noopLogger } from './logger.ts';
 
 // ── Providers ─────────────────────────────────────────────────────────────────
-export { GitLabProvider, parseGitLabRepoId, MR_DASHBOARD_FRAGMENT } from "./GitLabProvider.ts";
-export { GitHubProvider } from "./GitHubProvider.ts";
-export { createProvider, SUPPORTED_PROVIDERS } from "./providers.ts";
-export type { ProviderSlug } from "./providers.ts";
+export {
+  GitLabProvider,
+  parseGitLabRepoId,
+  MR_DASHBOARD_FRAGMENT
+} from './GitLabProvider.ts';
+export { GitHubProvider } from './GitHubProvider.ts';
+export { createProvider, SUPPORTED_PROVIDERS } from './providers.ts';
+export type { ProviderSlug } from './providers.ts';
 
 // ── GitLab real-time ──────────────────────────────────────────────────────────
-export { ActionCableClient } from "./ActionCableClient.ts";
-export type { ActionCableCallbacks } from "./ActionCableClient.ts";
+export { ActionCableClient } from './ActionCableClient.ts';
+export type { ActionCableCallbacks } from './ActionCableClient.ts';
 
 // ── GitLab detail + mutations ─────────────────────────────────────────────────
-export { MRDetailFetcher } from "./MRDetailFetcher.ts";
-export { NoteMutator } from "./NoteMutator.ts";
-export type { CreatedNote } from "./NoteMutator.ts";
+export { MRDetailFetcher } from './MRDetailFetcher.ts';
+export { NoteMutator } from './NoteMutator.ts';
+export type { CreatedNote } from './NoteMutator.ts';

package/src/types.ts

@@ -84,6 +84,117 @@ export interface PullRequest {
   detailedMergeStatus: string | null;
 }
 
+// ── MR/PR mutation inputs ─────────────────────────────────────────────────────
+
+/** Input for creating a new merge request / pull request. */
+export interface CreatePullRequestInput {
+  /** Project path (GitLab: "group/project") or owner/repo (GitHub: "owner/repo"). */
+  projectPath: string;
+  title: string;
+  description?: string;
+  sourceBranch: string;
+  targetBranch: string;
+  draft?: boolean;
+  /** Usernames to assign as reviewers. */
+  reviewers?: string[];
+  /** Usernames to assign. */
+  assignees?: string[];
+  /** Labels to apply (string names). */
+  labels?: string[];
+}
+
+/** Input for updating an existing merge request / pull request. */
+export interface UpdatePullRequestInput {
+  title?: string;
+  description?: string;
+  /** Set draft status. */
+  draft?: boolean;
+  /** Change the target branch. */
+  targetBranch?: string;
+  /** Usernames to assign as reviewers (replaces current set). */
+  reviewers?: string[];
+  /** Usernames to assign (replaces current set). */
+  assignees?: string[];
+  /** Labels (replaces current set). */
+  labels?: string[];
+  /** Set MR state: "close" or "reopen". */
+  stateEvent?: 'close' | 'reopen';
+}
+
+/**
+ * Merge strategy override.
+ * - "merge"  — Standard merge commit.
+ * - "squash" — Squash all commits into one before merging.
+ * - "rebase" — Rebase the source branch onto the target (fast-forward).
+ *
+ * When omitted, the provider uses the project's configured default merge method.
+ */
+export type MergeMethod = 'merge' | 'squash' | 'rebase';
+
+/**
+ * Input for merging (accepting) a pull request / merge request.
+ *
+ * All fields are **optional**. Omitting them defers to the project-level
+ * settings configured in the forge UI (merge method, squash policy,
+ * delete-source-branch, etc.). This matches how the web UI works.
+ */
+export interface MergePullRequestInput {
+  /** Merge commit message. Omit to use the provider/project default. */
+  commitMessage?: string;
+  /** Squash commit message (when merge method is "squash"). */
+  squashCommitMessage?: string;
+  /** Whether to squash commits. Omit to use the MR / project default. */
+  squash?: boolean;
+  /** Merge strategy override. Omit to use the project's default merge method. */
+  mergeMethod?: MergeMethod;
+  /** Delete source branch after merge. Omit to use project default. */
+  shouldRemoveSourceBranch?: boolean;
+  /** SHA that HEAD must match for the merge to proceed (optimistic locking). */
+  sha?: string;
+}
+
+/**
+ * Reports which mutation operations a provider supports.
+ *
+ * Callers should check these flags before invoking vendor-specific methods
+ * so they can conditionally show/hide UI affordances without
+ * knowing which provider they're talking to.
+ */
+export interface ProviderCapabilities {
+  /** Can merge / accept a pull request. */
+  canMerge: boolean;
+  /** Can approve a pull request. */
+  canApprove: boolean;
+  /** Can revoke an existing approval. */
+  canUnapprove: boolean;
+  /** Can rebase the source branch onto the target. */
+  canRebase: boolean;
+  /** Can enable automatic merge when pipeline succeeds. */
+  canAutoMerge: boolean;
+  /** Can resolve / unresolve discussion threads. */
+  canResolveDiscussions: boolean;
+  /** Can retry a pipeline. */
+  canRetryPipeline: boolean;
+  /** Can re-request review attention from reviewers. */
+  canRequestReReview: boolean;
+}
+
+/** Branch protection rule (provider-agnostic). */
+export interface BranchProtectionRule {
+  /** Branch name or pattern, e.g. "main" or "release/*". */
+  pattern: string;
+  /** Whether force-pushes are allowed. */
+  allowForcePush: boolean;
+  /** Whether branch deletions are allowed. */
+  allowDeletion: boolean;
+  /** Number of required approving reviews (0 = none required). */
+  requiredApprovals: number;
+  /** Whether the branch requires status checks to pass before merge. */
+  requireStatusChecks: boolean;
+  /** Raw provider-specific data for fields not covered above. */
+  raw?: Record<string, unknown>;
+}
+
 /** Snapshot payload sent when a client first connects. */
 export interface PullRequestsSnapshot {
   items: PullRequest[];