@dxos/plugin-github 0.7.4 → 0.13.0

package/src/operations/materialize-target.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Filter, Obj, Query, Ref } from '@dxos/echo';
+import { TaskSet } from '@dxos/types';
+
+import { GitHubOperation } from '#types';
+
+import { GITHUB_SOURCE } from '../constants.ts';
+
+const fkFor = (id: string) => ({ source: GITHUB_SOURCE, id });
+
+/**
+ * Find-or-create the empty local root Project for a GitHub repo so a `Cursor`
+ * can reference it as its `spec.target`. Idempotent: keyed by the repo's
+ * GitHub foreign id (`remoteTarget.id`), it returns the existing Project
+ * when one already carries that key. The repo's data is filled in lazily by the
+ * sync operation; here we only stamp the foreign key + a display name.
+ */
+const handler: Operation.WithHandler<typeof GitHubOperation.MaterializeGitHubTarget> =
+  GitHubOperation.MaterializeGitHubTarget.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ connection, remoteTarget }) {
+        if (!remoteTarget) {
+          return yield* Effect.die(new Error('GitHub materializeTarget requires a remoteTarget (repo descriptor).'));
+        }
+        // TODO(wittjosiah): the operation should just depend on `Database.Service` and
+        //   have it provided by the OperationInvoker — composer's invoker is wired
+        //   without a `databaseResolver`, so we derive the db from the connection ref's
+        //   target and provide `Database.layer(db)` ourselves.
+        const db = connection.target ? Obj.getDatabase(connection.target) : undefined;
+        if (!db) {
+          return yield* Effect.die(new Error('No database for connection ref.'));
+        }
+
+        return yield* Effect.gen(function* () {
+          const existing = yield* Database.query(
+            Query.select(Filter.foreignKeys(TaskSet.TaskSet, [fkFor(remoteTarget.id)])),
+          ).run;
+          if (existing.length > 0) {
+            return { target: Ref.make(existing[0]) };
+          }
+
+          const created = yield* Database.add(
+            TaskSet.make({
+              [Obj.Meta]: { keys: [fkFor(remoteTarget.id)] },
+              name: remoteTarget.name,
+            }),
+          );
+          return { target: Ref.make(created) };
+        }).pipe(Effect.provide(Database.layer(db)));
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/pull-request.test.ts

@@ -0,0 +1,120 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { summarizeCheckRuns, summarizeReviews, toCheckRun } from './pull-request.ts';
+
+describe('summarizeCheckRuns', () => {
+  test('no runs is none', () => {
+    expect(summarizeCheckRuns([])).toEqual({ ci: 'none', checks: { total: 0, passed: 0, failed: 0, pending: 0 } });
+  });
+
+  test('all completed without failure is success, skipped and neutral included', () => {
+    const { ci, checks } = summarizeCheckRuns([
+      { name: 'build', status: 'completed', conclusion: 'success' },
+      { name: 'lint', status: 'completed', conclusion: 'skipped' },
+      { name: 'docs', status: 'completed', conclusion: 'neutral' },
+    ]);
+    expect(ci).toEqual('success');
+    expect(checks).toEqual({ total: 3, passed: 3, failed: 0, pending: 0 });
+  });
+
+  test('an unfinished run is pending', () => {
+    const { ci } = summarizeCheckRuns([
+      { name: 'build', status: 'completed', conclusion: 'success' },
+      { name: 'test', status: 'in_progress', conclusion: null },
+    ]);
+    expect(ci).toEqual('pending');
+  });
+
+  test('a stale run does not count as passed', () => {
+    const { ci, checks } = summarizeCheckRuns([
+      { name: 'build', status: 'completed', conclusion: 'success' },
+      { name: 'test', status: 'completed', conclusion: 'stale' },
+    ]);
+    expect(ci).toEqual('failure');
+    expect(checks).toEqual({ total: 2, passed: 1, failed: 1, pending: 0 });
+  });
+
+  test('a failure wins over pending runs', () => {
+    const { ci, checks } = summarizeCheckRuns([
+      { name: 'build', status: 'completed', conclusion: 'timed_out' },
+      { name: 'test', status: 'queued' },
+    ]);
+    expect(ci).toEqual('failure');
+    expect(checks).toEqual({ total: 2, passed: 0, failed: 1, pending: 1 });
+  });
+});
+
+describe('toCheckRun', () => {
+  test('folds a conclusion into the outcome the list shows', () => {
+    expect(toCheckRun({ name: 'test', status: 'completed', conclusion: 'timed_out' }).outcome).toEqual('failure');
+    expect(toCheckRun({ name: 'cli', status: 'completed', conclusion: 'skipped' }).outcome).toEqual('skipped');
+    expect(toCheckRun({ name: 'e2e', status: 'in_progress', conclusion: null }).outcome).toEqual('pending');
+    expect(toCheckRun({ name: 'build', status: 'completed', conclusion: 'success' }).outcome).toEqual('success');
+  });
+
+  test("links the provider's page over GitHub's", () => {
+    const run = toCheckRun({
+      name: 'Check / check',
+      status: 'completed',
+      conclusion: 'success',
+      html_url: 'https://github.com/dxos/dxos/runs/1',
+      details_url: 'https://depot.dev/orgs/acme/workflows/abc?job=1',
+      started_at: '2026-09-23T12:47:05Z',
+      completed_at: '2026-09-23T12:51:13Z',
+    });
+    expect(run).toEqual({
+      name: 'Check / check',
+      outcome: 'success',
+      conclusion: 'success',
+      url: 'https://depot.dev/orgs/acme/workflows/abc?job=1',
+      startedAt: '2026-09-23T12:47:05Z',
+      completedAt: '2026-09-23T12:51:13Z',
+    });
+  });
+});
+
+describe('summarizeReviews', () => {
+  const review = (id: number, login: string, state: string) => ({ id, state, user: { login } });
+
+  test('no reviews is none', () => {
+    expect(summarizeReviews([])).toEqual({ review: 'none', approvals: 0 });
+  });
+
+  test('a comment alone is no verdict', () => {
+    expect(summarizeReviews([review(1, 'alice', 'COMMENTED')])).toEqual({ review: 'none', approvals: 0 });
+  });
+
+  test('approvals are counted per reviewer', () => {
+    expect(
+      summarizeReviews([review(1, 'alice', 'APPROVED'), review(2, 'alice', 'APPROVED'), review(3, 'bob', 'APPROVED')]),
+    ).toEqual({ review: 'approved', approvals: 2 });
+  });
+
+  test('an outstanding request for changes outweighs approvals', () => {
+    expect(summarizeReviews([review(1, 'alice', 'APPROVED'), review(2, 'bob', 'CHANGES_REQUESTED')])).toEqual({
+      review: 'changes_requested',
+      approvals: 1,
+    });
+  });
+
+  test("a reviewer's later approval clears their request, and a later comment does not undo it", () => {
+    expect(
+      summarizeReviews([
+        review(1, 'bob', 'CHANGES_REQUESTED'),
+        review(2, 'bob', 'APPROVED'),
+        review(3, 'bob', 'COMMENTED'),
+      ]),
+    ).toEqual({ review: 'approved', approvals: 1 });
+  });
+
+  test('a dismissed review withdraws the verdict', () => {
+    expect(summarizeReviews([review(1, 'bob', 'APPROVED'), review(2, 'bob', 'DISMISSED')])).toEqual({
+      review: 'none',
+      approvals: 0,
+    });
+  });
+});

package/src/operations/pull-request.ts

@@ -0,0 +1,141 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Database, Filter, Obj, type Ref } from '@dxos/echo';
+import { Connection } from '@dxos/link';
+import { type PullRequest } from '@dxos/types';
+
+import { type GitHubOperation } from '#types';
+
+import { GITHUB_PROVIDER_ID } from '../constants.ts';
+import { GitHubPullRequestUnstoredError } from '../errors.ts';
+import { GitHubApi } from '../services/index.ts';
+
+/**
+ * The GitHub connection whose token requests are sent with: the first one holding a token. Shared by
+ * the handlers and by the UI that sends the user to reconnect, so both name the same connection.
+ */
+export const githubConnection = () =>
+  Effect.gen(function* () {
+    const connections = yield* Database.query(Filter.type(Connection.Connection)).run;
+    for (const connection of connections) {
+      if (connection.connectorId !== GITHUB_PROVIDER_ID) {
+        continue;
+      }
+      const accessToken = yield* Database.load(connection.accessToken);
+      if (accessToken.token) {
+        return { connection, token: accessToken.token };
+      }
+    }
+
+    return undefined;
+  });
+
+/**
+ * The token of {@link githubConnection}, or empty for anonymous — which reaches any public pull
+ * request, and is the only option in a space that has not connected GitHub.
+ */
+export const githubToken = () => githubConnection().pipe(Effect.map((selected) => selected?.token ?? ''));
+
+/**
+ * The stored pull request behind an operation's input and credentials for its space.
+ *
+ * The invoker carries no database resolver, so handlers derive one from the pull request itself; a
+ * preview card's in-memory pull request has none and cannot be acted on.
+ */
+export const resolvePullRequest = (ref: Ref.Ref<PullRequest.PullRequest>) =>
+  Effect.gen(function* () {
+    const pullRequest = ref.target;
+    const db = pullRequest ? Obj.getDatabase(pullRequest) : undefined;
+    if (!pullRequest || !db) {
+      return yield* Effect.die(new GitHubPullRequestUnstoredError());
+    }
+    const token = yield* githubToken().pipe(Effect.provide(Database.layer(db)));
+    return { pullRequest, db, credentials: Layer.succeed(GitHubApi.GitHubCredentials, { token }) };
+  });
+
+// `stale` is a completed run GitHub never re-ran, which branch protection does not count as passing.
+const FAILED_CONCLUSIONS = new Set([
+  'failure',
+  'cancelled',
+  'timed_out',
+  'action_required',
+  'startup_failure',
+  'stale',
+]);
+
+/** One check run as the article lists it: its outcome folded the way {@link summarizeCheckRuns} counts it. */
+export const toCheckRun = (run: GitHubApi.GitHubCheckRun): GitHubOperation.CheckRun => {
+  const outcome: GitHubOperation.CheckOutcome =
+    run.status !== 'completed'
+      ? 'pending'
+      : run.conclusion && FAILED_CONCLUSIONS.has(run.conclusion)
+        ? 'failure'
+        : run.conclusion === 'skipped'
+          ? 'skipped'
+          : run.conclusion === 'neutral'
+            ? 'neutral'
+            : 'success';
+  const url = run.details_url ?? run.html_url;
+  return {
+    name: run.name,
+    outcome,
+    ...(run.conclusion ? { conclusion: run.conclusion } : {}),
+    ...(url ? { url } : {}),
+    ...(run.started_at ? { startedAt: run.started_at } : {}),
+    ...(run.completed_at ? { completedAt: run.completed_at } : {}),
+  };
+};
+
+/** Folds a commit's check runs into one outcome: any failure fails, then any unfinished run is pending. */
+export const summarizeCheckRuns = (
+  runs: readonly GitHubApi.GitHubCheckRun[],
+): { ci: GitHubOperation.CiState; checks: GitHubOperation.CheckCounts } => {
+  const checks = { total: runs.length, passed: 0, failed: 0, pending: 0 };
+  for (const run of runs) {
+    if (run.status !== 'completed') {
+      checks.pending++;
+    } else if (run.conclusion && FAILED_CONCLUSIONS.has(run.conclusion)) {
+      checks.failed++;
+    } else {
+      checks.passed++;
+    }
+  }
+
+  const ci: GitHubOperation.CiState =
+    checks.total === 0 ? 'none' : checks.failed > 0 ? 'failure' : checks.pending > 0 ? 'pending' : 'success';
+  return { ci, checks };
+};
+
+/** Review states that set a reviewer's standing verdict; a comment leaves the previous one in place. */
+const VERDICT_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED']);
+
+/**
+ * Folds a pull request's reviews into where they stand, from each reviewer's latest verdict — the
+ * way GitHub reads them: a later approval clears that reviewer's request for changes, and a dismissal
+ * withdraws whichever verdict it replaced.
+ */
+export const summarizeReviews = (
+  reviews: readonly GitHubApi.GitHubSubmittedReview[],
+): { review: GitHubOperation.ReviewState; approvals: number } => {
+  const verdicts = new Map<string, string>();
+  for (const review of reviews) {
+    const login = review.user?.login;
+    if (login && VERDICT_STATES.has(review.state)) {
+      verdicts.set(login, review.state);
+    }
+  }
+
+  const states = [...verdicts.values()];
+  const approvals = states.filter((state) => state === 'APPROVED').length;
+  const review: GitHubOperation.ReviewState = states.includes('CHANGES_REQUESTED')
+    ? 'changes_requested'
+    : approvals > 0
+      ? 'approved'
+      : 'none';
+  return { review, approvals };
+};

package/src/operations/submit-pull-request-approval.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as Option from 'effect/Option';
+
+import * as Operation from '@dxos/compute/Operation';
+
+import { GitHubOperation } from '#types';
+
+import { approvalCommentBody, isApprovalRefused } from '../approval.ts';
+import { GitHubApi } from '../services/index.ts';
+import { resolvePullRequest } from './pull-request.ts';
+
+const handler: Operation.WithHandler<typeof GitHubOperation.SubmitPullRequestApproval> =
+  GitHubOperation.SubmitPullRequestApproval.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ pullRequest: ref, body }) {
+        const { pullRequest, credentials } = yield* resolvePullRequest(ref);
+        const { owner, repo, number } = pullRequest;
+        const review = yield* GitHubApi.approvePullRequest(owner, repo, number, body).pipe(
+          Effect.provide(credentials),
+          Effect.asSome,
+          // Only a refusal to review becomes a comment; every other failure stays a failure.
+          Effect.catchIf(isApprovalRefused, () => Effect.succeedNone),
+        );
+        if (Option.isSome(review)) {
+          return { reviewId: review.value.id, commented: false };
+        }
+
+        const comment = yield* GitHubApi.createIssueComment(owner, repo, number, approvalCommentBody(body)).pipe(
+          Effect.provide(credentials),
+        );
+        return { commentId: comment.id, url: comment.html_url ?? undefined, commented: true };
+      }, Effect.provide(FetchHttpClient.layer)),
+    ),
+  );
+
+export default handler;

package/src/operations/sync-pull-request.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Obj } from '@dxos/echo';
+
+import { GitHubOperation } from '#types';
+
+import { pullRequestChanges } from '../pull-request.ts';
+import { fetchPullRequestWithFallback } from './import-pull-request.ts';
+import { githubToken, resolvePullRequest } from './pull-request.ts';
+
+const handler: Operation.WithHandler<typeof GitHubOperation.SyncPullRequest> = GitHubOperation.SyncPullRequest.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ pullRequest: ref }) {
+      const { pullRequest, db } = yield* resolvePullRequest(ref);
+      const token = yield* githubToken().pipe(Effect.provide(Database.layer(db)));
+      // With the anonymous fallback, so a public pull request still refreshes behind a revoked token.
+      const pull = yield* fetchPullRequestWithFallback(pullRequest, token);
+      const changes = pullRequestChanges(pullRequest, pull);
+      const updated = Object.keys(changes);
+      if (updated.length > 0) {
+        Obj.update(pullRequest, (pullRequest) => {
+          Object.assign(pullRequest, changes);
+        });
+      }
+
+      return { updated };
+    }, Effect.provide(FetchHttpClient.layer)),
+  ),
+);
+
+export default handler;