@forge-glance/sdk 0.1.0

package/src/GitLabProvider.ts

@@ -0,0 +1,471 @@
+import type { GitProvider } from "./GitProvider.ts";
+import type {
+  DiffStats,
+  MRDetail,
+  Pipeline,
+  PipelineJob,
+  PullRequest,
+  UserRef,
+} from "./types.ts";
+import { type ForgeLogger, noopLogger } from "./logger.ts";
+import { MRDetailFetcher } from "./MRDetailFetcher.ts";
+
+// ---------------------------------------------------------------------------
+// Repository ID helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Strips the provider prefix from a scoped repositoryId and returns the
+ * numeric GitLab project ID needed for REST API calls.
+ * e.g. "gitlab:42" → 42
+ */
+export function parseGitLabRepoId(repositoryId: string): number {
+  const parts = repositoryId.split(":");
+  return parseInt(parts.at(-1) ?? "0", 10);
+}
+
+// ---------------------------------------------------------------------------
+// GraphQL query (same fragment as GraphQLQueries.swift mrDashboardFieldsFragment)
+// ---------------------------------------------------------------------------
+
+export const MR_DASHBOARD_FRAGMENT = `
+  fragment MRDashboardFields on MergeRequest {
+    id iid projectId title description state draft
+    sourceBranch targetBranch webUrl
+    diffHeadSha
+    updatedAt createdAt
+    conflicts
+    detailedMergeStatus
+    approved
+    diffStatsSummary { additions deletions fileCount }
+    author { id username name avatarUrl }
+    assignees(first: 20) { nodes { id username name avatarUrl } }
+    reviewers(first: 20) { nodes { id username name avatarUrl } }
+    approvedBy(first: 20) { nodes { id username name avatarUrl } }
+    approvalsLeft
+    resolvableDiscussionsCount
+    resolvedDiscussionsCount
+    headPipeline {
+      id iid status
+      createdAt
+      path
+      stages(first: 20) { nodes {
+        name
+        jobs(first: 50) { nodes {
+          id name status
+          allowFailure
+          webPath
+          stage { name }
+        }}
+      }}
+    }
+  }
+`;
+
+const AUTHORED_QUERY = `
+  query GlanceDashboardAuthored {
+    currentUser {
+      authoredMergeRequests(state: opened, first: 100) {
+        nodes { ...MRDashboardFields }
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+
+const REVIEWING_QUERY = `
+  query GlanceDashboardReviewing {
+    currentUser {
+      reviewRequestedMergeRequests(state: opened, first: 100) {
+        nodes { ...MRDashboardFields }
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+
+const ASSIGNED_QUERY = `
+  query GlanceDashboardAssigned {
+    currentUser {
+      assignedMergeRequests(state: opened, first: 100) {
+        nodes { ...MRDashboardFields }
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+
+// ---------------------------------------------------------------------------
+// Raw GQL response shapes (only the fields we use)
+// ---------------------------------------------------------------------------
+
+interface GQLUser {
+  id: string;
+  username: string;
+  name: string;
+  avatarUrl: string | null;
+}
+
+interface GQLJob {
+  id: string;
+  name: string;
+  status: string;
+  allowFailure: boolean;
+  webPath: string | null;
+  stage: { name: string };
+}
+
+interface GQLStage {
+  name: string;
+  jobs: { nodes: GQLJob[] };
+}
+
+interface GQLPipeline {
+  id: string;
+  status: string;
+  createdAt: string | null;
+  path: string | null;
+  stages: { nodes: GQLStage[] };
+}
+
+interface GQLDiffStats {
+  additions: number;
+  deletions: number;
+  fileCount: number;
+}
+
+interface GQLMR {
+  id: string;
+  iid: string;
+  projectId: number;
+  title: string;
+  description: string | null;
+  state: string;
+  draft: boolean;
+  sourceBranch: string;
+  targetBranch: string;
+  webUrl: string;
+  diffHeadSha: string | null;
+  updatedAt: string;
+  createdAt: string;
+  conflicts: boolean;
+  detailedMergeStatus: string | null;
+  approved: boolean;
+  diffStatsSummary: GQLDiffStats | null;
+  author: GQLUser;
+  assignees: { nodes: GQLUser[] };
+  reviewers: { nodes: GQLUser[] };
+  approvedBy: { nodes: GQLUser[] };
+  approvalsLeft: number | null;
+  resolvableDiscussionsCount: number | null;
+  resolvedDiscussionsCount: number | null;
+  headPipeline: GQLPipeline | null;
+}
+
+interface AuthoredResponse {
+  currentUser: { authoredMergeRequests: { nodes: GQLMR[] } };
+}
+interface ReviewingResponse {
+  currentUser: { reviewRequestedMergeRequests: { nodes: GQLMR[] } };
+}
+interface AssignedResponse {
+  currentUser: { assignedMergeRequests: { nodes: GQLMR[] } };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Extract numeric ID from a GQL global ID like "gid://gitlab/MergeRequest/12345". */
+function numericId(gid: string): number {
+  const parts = gid.split("/");
+  return parseInt(parts[parts.length - 1] ?? "0", 10);
+}
+
+/** Build a scoped domain ID from a GitLab numeric integer. */
+function domainId(type: string, id: number | string): string {
+  return `gitlab:${type}:${id}`;
+}
+
+function toUserRef(u: GQLUser): UserRef {
+  return {
+    id: `gitlab:user:${numericId(u.id)}`,
+    username: u.username,
+    name: u.name,
+    avatarUrl: u.avatarUrl,
+  };
+}
+
+
+function toPipeline(p: GQLPipeline, baseURL: string): Pipeline {
+  const allJobs: PipelineJob[] = p.stages.nodes.flatMap((stage) =>
+    stage.jobs.nodes.map((job) => ({
+      id: `gitlab:job:${numericId(job.id)}`,
+      name: job.name,
+      stage: job.stage.name,
+      status: job.status,
+      allowFailure: job.allowFailure,
+      webUrl: job.webPath ? `${baseURL}${job.webPath}` : null,
+    })),
+  );
+
+  return {
+    id: domainId("pipeline", numericId(p.id)),
+    status: normalizePipelineStatus(p),
+    createdAt: p.createdAt,
+    webUrl: p.path ? `${baseURL}${p.path}` : null,
+    jobs: allJobs,
+  };
+}
+
+/**
+ * Mirrors PipelineStatus.successWithWarnings logic from Swift:
+ * if any non-allow-failure job failed → "failed"
+ * if any allow-failure job failed but overall status is success → "success_with_warnings"
+ */
+function normalizePipelineStatus(p: GQLPipeline): string {
+  const allJobs = p.stages.nodes.flatMap((s) => s.jobs.nodes);
+  const hasAllowFailFailed = allJobs.some(
+    (j) => j.allowFailure && j.status === "failed",
+  );
+  if (p.status === "success" && hasAllowFailFailed) {
+    return "success_with_warnings";
+  }
+  return p.status;
+}
+
+function toMR(gql: GQLMR, role: string, baseURL: string): PullRequest {
+  const resolvable = gql.resolvableDiscussionsCount ?? 0;
+  const resolved = gql.resolvedDiscussionsCount ?? 0;
+  const unresolvedThreadCount = Math.max(0, resolvable - resolved);
+
+  const diffStats: DiffStats | null = gql.diffStatsSummary
+    ? {
+        additions: gql.diffStatsSummary.additions,
+        deletions: gql.diffStatsSummary.deletions,
+        filesChanged: gql.diffStatsSummary.fileCount,
+      }
+    : null;
+
+  return {
+    id: `gitlab:mr:${numericId(gql.id)}`,
+    iid: parseInt(gql.iid, 10),
+    repositoryId: `gitlab:${gql.projectId}`,
+    title: gql.title,
+    description: gql.description ?? null,
+    state: gql.state,
+    draft: gql.draft,
+    conflicts: gql.conflicts || gql.detailedMergeStatus === "conflict",
+    webUrl: gql.webUrl,
+    sourceBranch: gql.sourceBranch,
+    targetBranch: gql.targetBranch,
+    createdAt: gql.createdAt,
+    updatedAt: gql.updatedAt,
+    sha: gql.diffHeadSha,
+    author: toUserRef(gql.author),
+    assignees: gql.assignees.nodes.map(toUserRef),
+    reviewers: gql.reviewers.nodes.map(toUserRef),
+    roles: [role],
+    pipeline: gql.headPipeline ? toPipeline(gql.headPipeline, baseURL) : null,
+    unresolvedThreadCount,
+    approvalsLeft: gql.approvalsLeft ?? 0,
+    approved: gql.approved ?? false,
+    approvedBy: gql.approvedBy.nodes.map(toUserRef),
+    diffStats,
+    detailedMergeStatus: gql.detailedMergeStatus ?? null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Single-MR detail query (used by SubscriptionManager on userMergeRequestUpdated)
+// ---------------------------------------------------------------------------
+
+const MR_DETAIL_QUERY = `
+  query GlanceMRDetail($projectPath: ID!, $iid: String!) {
+    project(fullPath: $projectPath) {
+      mergeRequest(iid: $iid) {
+        ...MRDashboardFields
+      }
+    }
+  }
+  ${MR_DASHBOARD_FRAGMENT}
+`;
+
+interface MRDetailResponse {
+  project: { mergeRequest: GQLMR | null } | null;
+}
+
+// ---------------------------------------------------------------------------
+// GitLabProvider
+// ---------------------------------------------------------------------------
+
+export class GitLabProvider implements GitProvider {
+  readonly providerName = "gitlab" as const;
+  readonly baseURL: string;
+  private readonly token: string;
+  private readonly log: ForgeLogger;
+  private readonly mrDetailFetcher: MRDetailFetcher;
+
+  constructor(baseURL: string, token: string, options: { logger?: ForgeLogger } = {}) {
+    // Strip trailing slash for consistent URL building
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+    this.log = options.logger ?? noopLogger;
+    this.mrDetailFetcher = new MRDetailFetcher(this.baseURL, token, { logger: this.log });
+  }
+
+  // MARK: - GitProvider
+
+  async validateToken(): Promise<UserRef> {
+    const url = `${this.baseURL}/api/v4/user`;
+    const res = await fetch(url, {
+      headers: { "PRIVATE-TOKEN": this.token },
+    });
+    if (!res.ok) {
+      throw new Error(`Token validation failed: ${res.status} ${res.statusText}`);
+    }
+    const user = (await res.json()) as {
+      id: number;
+      username: string;
+      name: string;
+      avatar_url: string | null;
+    };
+    return {
+      id: `gitlab:user:${user.id}`,
+      username: user.username,
+      name: user.name,
+      avatarUrl: user.avatar_url,
+    };
+  }
+
+  /**
+   * Fetch a single MR by project path and IID.
+   * Used by SubscriptionManager when `userMergeRequestUpdated` fires.
+   * Returns null if the project or MR doesn't exist.
+   *
+   * Roles are computed by matching `currentUserNumericId` against the MR's
+   * author, assignees, and reviewers.
+   */
+  async fetchSingleMR(
+    projectPath: string,
+    mrIid: number,
+    currentUserNumericId: number | null,
+  ): Promise<PullRequest | null> {
+    let resp: MRDetailResponse;
+    try {
+      resp = await this.runQuery<MRDetailResponse>(MR_DETAIL_QUERY, {
+        projectPath,
+        iid: String(mrIid),
+      });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.log.warn("fetchSingleMR failed", { projectPath, mrIid, message });
+      return null;
+    }
+
+    const gql = resp.project?.mergeRequest;
+    if (!gql) return null;
+
+    // Compute roles from the fresh response.
+    const roles: string[] = [];
+    if (currentUserNumericId !== null) {
+      const userGqlId = `gid://gitlab/User/${currentUserNumericId}`;
+      if (gql.author.id === userGqlId) roles.push("author");
+      if (gql.assignees.nodes.some((u) => u.id === userGqlId)) roles.push("assignee");
+      if (gql.reviewers.nodes.some((u) => u.id === userGqlId)) roles.push("reviewer");
+    }
+
+    // Use "author" as the primary role for toMR, then overwrite with full computed roles.
+    const pr = toMR(gql, roles[0] ?? "author", this.baseURL);
+    pr.roles = roles.length > 0 ? roles : pr.roles;
+    return pr;
+  }
+
+  async fetchPullRequests(): Promise<PullRequest[]> {
+    const [authored, reviewing, assigned] = await Promise.all([
+      this.runQuery<AuthoredResponse>(AUTHORED_QUERY),
+      this.runQuery<ReviewingResponse>(REVIEWING_QUERY),
+      this.runQuery<AssignedResponse>(ASSIGNED_QUERY),
+    ]);
+
+    // Merge all three sets, deduplicating by MR global ID.
+    // For duplicates, accumulate all roles (a user can be both author and assignee).
+    const byId = new Map<string, PullRequest>();
+
+    const addAll = (mrs: GQLMR[], role: string) => {
+      for (const gql of mrs) {
+        const existing = byId.get(gql.id);
+        if (existing) {
+          if (!existing.roles.includes(role)) {
+            existing.roles.push(role);
+          }
+        } else {
+          byId.set(gql.id, toMR(gql, role, this.baseURL));
+        }
+      }
+    };
+
+    addAll(authored.currentUser.authoredMergeRequests.nodes, "author");
+    addAll(reviewing.currentUser.reviewRequestedMergeRequests.nodes, "reviewer");
+    addAll(assigned.currentUser.assignedMergeRequests.nodes, "assignee");
+
+    const prs = [...byId.values()];
+    this.log.debug("fetchPullRequests", { count: prs.length });
+    return prs;
+  }
+
+  async fetchMRDiscussions(repositoryId: string, mrIid: number): Promise<MRDetail> {
+    const projectId = parseGitLabRepoId(repositoryId);
+    return this.mrDetailFetcher.fetchDetail(projectId, mrIid);
+  }
+
+  async restRequest(method: string, path: string, body?: unknown): Promise<Response> {
+    const url = `${this.baseURL}${path}`;
+    const headers: Record<string, string> = {
+      "PRIVATE-TOKEN": this.token,
+    };
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+    return fetch(url, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+  }
+
+  // MARK: - Private
+
+  private async runQuery<T>(query: string, variables?: Record<string, unknown>): Promise<T> {
+    const url = `${this.baseURL}/api/graphql`;
+    const body = JSON.stringify({ query, variables: variables ?? {} });
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`,
+      },
+      body,
+    });
+
+    if (!res.ok) {
+      throw new Error(`GraphQL request failed: ${res.status} ${res.statusText}`);
+    }
+
+    const envelope = (await res.json()) as {
+      data?: T;
+      errors?: Array<{ message: string }>;
+    };
+
+    if (envelope.errors?.length) {
+      const msg = envelope.errors.map((e) => e.message).join("; ");
+      throw new Error(`GraphQL errors: ${msg}`);
+    }
+
+    if (!envelope.data) {
+      throw new Error("GraphQL response missing data");
+    }
+
+    return envelope.data;
+  }
+}

package/src/GitProvider.ts

@@ -0,0 +1,77 @@
+import type { Discussion, MRDetail, PullRequest, UserRef } from "./types.ts";
+
+/**
+ * Provider-agnostic interface for a Git hosting service.
+ *
+ * `GitLabProvider` implements this today; `GitHubProvider` will follow.
+ * `Connection` stores a `GitProvider` and uses only this interface — it never
+ * reaches into provider-specific internals.
+ */
+export interface GitProvider {
+  /** The provider slug stored in `connected_accounts.provider`. */
+  readonly providerName: string;
+
+  /** The base URL for this provider instance, e.g. "https://gitlab.com". */
+  readonly baseURL: string;
+
+  /** Validate the stored credentials and return the authenticated user. */
+  validateToken(): Promise<UserRef>;
+
+  /**
+   * Fetch all pull/merge requests the current user is involved in
+   * (authored, assigned, reviewing).
+   */
+  fetchPullRequests(): Promise<PullRequest[]>;
+
+  /**
+   * Fetch a single MR/PR by project path and IID.
+   * Returns null if the project or MR doesn't exist.
+   * Used by SubscriptionManager for real-time update handling.
+   */
+  fetchSingleMR(
+    projectPath: string,
+    mrIid: number,
+    currentUserNumericId: number | null,
+  ): Promise<PullRequest | null>;
+
+  /**
+   * Fetch discussions (comments, threads) for a specific MR/PR.
+   * Returns the MRDetail with discussions populated.
+   */
+  fetchMRDiscussions(
+    repositoryId: string,
+    mrIid: number,
+  ): Promise<MRDetail>;
+
+  // ── REST pass-through (used by note mutations, job traces, etc.) ────────
+
+  /**
+   * Make an authenticated REST API request to the provider.
+   * Used for operations that don't have a typed method yet (job traces,
+   * pipeline retries, etc.).
+   *
+   * Implementations translate the path to the provider's API URL format.
+   */
+  restRequest(
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<Response>;
+}
+
+/**
+ * Parse the numeric project/repo ID from a scoped repositoryId string.
+ * 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);
+}
+
+/**
+ * Extract the provider prefix from a scoped repositoryId.
+ * e.g. "gitlab:42" → "gitlab", "github:12345" → "github"
+ */
+export function repoIdProvider(repositoryId: string): string {
+  return repositoryId.split(":")[0] ?? "unknown";
+}

package/src/MRDetailFetcher.ts

@@ -0,0 +1,133 @@
+/**
+ * Fetches MR detail (discussions) from GitLab via the REST API.
+ *
+ * Accepts numeric projectId for REST URL construction; returns DomainMRDetail
+ * with a scoped repositoryId string (e.g. "gitlab:42").
+ * Endpoint: GET /api/v4/projects/:id/merge_requests/:iid/discussions?per_page=100
+ */
+
+import type {
+  Discussion,
+  MRDetail,
+  Note,
+  NoteAuthor,
+  NotePosition,
+} from "./types.ts";
+import { type ForgeLogger, noopLogger } from "./logger.ts";
+
+// ---------------------------------------------------------------------------
+// Raw REST response shapes
+// ---------------------------------------------------------------------------
+
+interface RESTNoteAuthor {
+  id: number;
+  username: string;
+  name: string;
+  avatar_url: string | null;
+}
+
+interface RESTNotePosition {
+  old_path?: string | null;
+  new_path?: string | null;
+  old_line?: number | null;
+  new_line?: number | null;
+  position_type?: string | null;
+}
+
+interface RESTNote {
+  id: number;
+  type: string | null;
+  body: string;
+  author: RESTNoteAuthor;
+  created_at: string;
+  system: boolean;
+  resolvable?: boolean | null;
+  resolved?: boolean | null;
+  position?: RESTNotePosition | null;
+}
+
+interface RESTDiscussion {
+  id: string;
+  notes: RESTNote[];
+}
+
+// ---------------------------------------------------------------------------
+// MRDetailFetcher
+// ---------------------------------------------------------------------------
+
+export class MRDetailFetcher {
+  private readonly baseURL: string;
+  private readonly token: string;
+  private readonly log: ForgeLogger;
+
+  constructor(baseURL: string, token: string, options: { logger?: ForgeLogger } = {}) {
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.token = token;
+    this.log = options.logger ?? noopLogger;
+  }
+
+  async fetchDetail(projectId: number, mrIid: number): Promise<MRDetail> {
+    const url = `${this.baseURL}/api/v4/projects/${projectId}/merge_requests/${mrIid}/discussions?per_page=100`;
+    const res = await fetch(url, {
+      headers: { "PRIVATE-TOKEN": this.token },
+    });
+
+    if (!res.ok) {
+      throw new Error(`MR discussions fetch failed: ${res.status} ${res.statusText}`);
+    }
+
+    const raw = (await res.json()) as RESTDiscussion[];
+
+    const discussions: Discussion[] = raw.map((d) => ({
+      id: d.id,
+      resolvable: null,
+      resolved: null,
+      notes: d.notes.map(toNote),
+    }));
+
+    this.log.debug("MRDetailFetcher.fetchDetail", {
+      projectId,
+      mrIid,
+      discussionCount: discussions.length,
+    });
+
+    return { mrIid, repositoryId: `gitlab:${projectId}`, discussions };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Mapping helpers
+// ---------------------------------------------------------------------------
+
+function toNote(n: RESTNote): Note {
+  return {
+    id: n.id,
+    body: n.body,
+    author: toAuthor(n.author),
+    createdAt: n.created_at,
+    system: n.system,
+    type: n.type,
+    resolvable: n.resolvable ?? null,
+    resolved: n.resolved ?? null,
+    position: n.position ? toPosition(n.position) : null,
+  };
+}
+
+function toAuthor(a: RESTNoteAuthor): NoteAuthor {
+  return {
+    id: `gitlab:user:${a.id}`,
+    username: a.username,
+    name: a.name,
+    avatarUrl: a.avatar_url,
+  };
+}
+
+function toPosition(p: RESTNotePosition): NotePosition {
+  return {
+    newPath: p.new_path ?? null,
+    oldPath: p.old_path ?? null,
+    newLine: p.new_line ?? null,
+    oldLine: p.old_line ?? null,
+    positionType: p.position_type ?? null,
+  };
+}