@dxos/plugin-github 0.7.4 → 0.13.0

package/src/operations/add-pull-request-review-comment.ts

@@ -0,0 +1,32 @@
+//
+// 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 { GitHubOperation } from '#types';
+
+import { GitHubApi } from '../services/index.ts';
+import { resolvePullRequest } from './pull-request.ts';
+
+const handler: Operation.WithHandler<typeof GitHubOperation.AddPullRequestReviewComment> =
+  GitHubOperation.AddPullRequestReviewComment.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ pullRequest: ref, body, commit, path, line, side }) {
+        const { pullRequest, credentials } = yield* resolvePullRequest(ref);
+        const comment = yield* GitHubApi.createReviewComment(pullRequest.owner, pullRequest.repo, pullRequest.number, {
+          body,
+          commit_id: commit,
+          path,
+          line,
+          side,
+        }).pipe(Effect.provide(credentials));
+        return { commentId: comment.id, url: comment.html_url ?? undefined };
+      }, Effect.provide(FetchHttpClient.layer)),
+    ),
+  );
+
+export default handler;

package/src/operations/generate-walkthrough.ts

@@ -0,0 +1,124 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as Layer from 'effect/Layer';
+
+import { AiService } from '@dxos/ai';
+import * as Progress from '@dxos/app-toolkit/Progress';
+import * as Operation from '@dxos/compute/Operation';
+import * as Trace from '@dxos/compute/Trace';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+
+import { GitHubOperation } from '#types';
+
+import { GitHubPullRequestUnstoredError } from '../errors.ts';
+import { GitHubApi } from '../services/index.ts';
+import { GENERATE_PHASES, generateWalkthrough } from '../walkthrough/index.ts';
+import { githubToken } from './pull-request.ts';
+
+/**
+ * One-shot for now; a multi-turn agent that reads the repository is the obvious next step.
+ *
+ * The prompt's diff budget matters more than it looks: this model's output allowance covers its
+ * reasoning as well as its answer, so an unbounded diff yields a response that is all reasoning and
+ * no walkthrough. See `DEFAULT_MAX_DIFF_CHARS`.
+ */
+const MODEL = 'com.anthropic.model.claude-sonnet-5.default';
+
+/**
+ * Generate a walkthrough of a pull request.
+ *
+ * Only the I/O is here — fetch the pull request, fetch its diff, run the model — because that is the
+ * part a test cannot reach. The decisions live in {@link generateWalkthrough}.
+ */
+const handler: Operation.WithHandler<typeof GitHubOperation.GenerateWalkthrough> =
+  GitHubOperation.GenerateWalkthrough.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ pullRequest: pullRequestRef, force }) {
+        // The invoker carries no database resolver, so the handler derives one from its input, as
+        // every other operation in this plugin does.
+        const pullRequest = pullRequestRef.target;
+        const db = pullRequest ? Obj.getDatabase(pullRequest) : undefined;
+        if (!pullRequest || !db) {
+          // A preview card mints a pull request in memory rather than storing it, and there is
+          // nowhere to put a walkthrough of one.
+          return yield* Effect.die(new GitHubPullRequestUnstoredError());
+        }
+
+        const traceWriter = yield* Trace.TraceService;
+        const progressKey = GitHubOperation.createWalkthroughProgressKey(pullRequest);
+        const label = `Walkthrough of ${PullRequest.reference(pullRequest)}`;
+        // Phase-first, since several meters on one object otherwise truncate to the same text.
+        const report = (message: string, current: number) =>
+          traceWriter.write(Trace.StatusUpdate, {
+            message,
+            progress: { key: progressKey, current, total: GENERATE_PHASES },
+          });
+
+        return yield* Effect.gen(function* () {
+          report(label, 0);
+          const { owner, repo, number } = pullRequest;
+          const credentials = Layer.succeed(GitHubApi.GitHubCredentials, { token: yield* githubToken() });
+
+          report(`${label}: reading the pull request`, 1);
+          const remote = yield* GitHubApi.fetchPullRequest(owner, repo, number).pipe(Effect.provide(credentials));
+
+          report(`${label}: fetching the diff`, 2);
+          const diff = yield* GitHubApi.fetchPullRequestDiff(owner, repo, number).pipe(Effect.provide(credentials));
+
+          const result = yield* generateWalkthrough({
+            pullRequest,
+            remote: {
+              title: remote.title,
+              description: remote.body ?? undefined,
+              baseBranch: remote.base?.ref,
+              headBranch: remote.head?.ref,
+              commit: remote.head?.sha,
+            },
+            diff,
+            force,
+            model: MODEL,
+            report,
+            narrate: (prompt) =>
+              LanguageModel.generateText({ prompt }).pipe(
+                Effect.map((response) => response.text),
+                Effect.provide(AiService.languageModel(MODEL).pipe(Layer.orDie)),
+                Effect.orDie,
+              ),
+          });
+
+          return {
+            walkthrough: Ref.make(result.walkthrough),
+            generated: result.generated,
+            covered: result.covered,
+            total: result.total,
+          };
+        }).pipe(
+          // The meter stays open forever without a terminal, and the sentinel is all the UI shows —
+          // the failure itself goes to the log.
+          // `onExit`, not `tapError`: the model call and the database both surface as DEFECTS rather
+          // than typed errors, and interruption raises neither. A meter with no terminal stays open
+          // and leaves the action disabled.
+          Effect.onExit((exit) =>
+            Effect.sync(() => {
+              if (Exit.isSuccess(exit)) {
+                return;
+              }
+              const terminal = Cause.hasInterrupts(exit.cause) ? Progress.STATUS_CANCELLED : Progress.STATUS_FAILED;
+              report(terminal, GENERATE_PHASES);
+            }),
+          ),
+          Effect.provide(Database.layer(db)),
+        );
+      }, Effect.provide(FetchHttpClient.layer)),
+    ),
+  );
+
+export default handler;

package/src/operations/get-pull-request-diff.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 { GitHubOperation } from '#types';
+
+import { GitHubApi } from '../services/index.ts';
+import { resolvePullRequest } from './pull-request.ts';
+
+const handler: Operation.WithHandler<typeof GitHubOperation.GetPullRequestDiff> =
+  GitHubOperation.GetPullRequestDiff.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ pullRequest: ref }) {
+        const { pullRequest, credentials } = yield* resolvePullRequest(ref);
+        const { owner, repo, number } = pullRequest;
+        const [before, diff, after] = yield* Effect.all(
+          [
+            GitHubApi.fetchPullRequest(owner, repo, number),
+            GitHubApi.fetchPullRequestDiff(owner, repo, number),
+            GitHubApi.fetchPullRequest(owner, repo, number),
+          ],
+          { concurrency: 1 },
+        ).pipe(Effect.provide(credentials));
+        // A push between the reads would pair the diff with another commit's line numbers, so the
+        // commit is only reported when the head held still across the diff.
+        const commit = before.head?.sha;
+        return { diff, ...(commit && commit === after.head?.sha ? { commit } : {}) };
+      }, Effect.provide(FetchHttpClient.layer)),
+    ),
+  );
+
+export default handler;

package/src/operations/get-pull-request-status.ts

@@ -0,0 +1,44 @@
+//
+// 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 { type PullRequest } from '@dxos/types';
+
+import { GitHubOperation } from '#types';
+
+import { GitHubApi } from '../services/index.ts';
+import { resolvePullRequest, summarizeCheckRuns, summarizeReviews, toCheckRun } from './pull-request.ts';
+
+const toState = (pull: GitHubApi.GitHubPull): PullRequest.State =>
+  pull.merged || pull.merged_at ? 'merged' : pull.draft ? 'draft' : pull.state === 'closed' ? 'closed' : 'open';
+
+const handler: Operation.WithHandler<typeof GitHubOperation.GetPullRequestStatus> =
+  GitHubOperation.GetPullRequestStatus.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ pullRequest: ref }) {
+        const { pullRequest, credentials } = yield* resolvePullRequest(ref);
+        const { owner, repo, number } = pullRequest;
+        const pull = yield* GitHubApi.fetchPullRequest(owner, repo, number).pipe(Effect.provide(credentials));
+        const commit = pull.head?.sha;
+        const runs = commit
+          ? yield* GitHubApi.fetchCheckRuns(owner, repo, commit).pipe(Effect.provide(credentials))
+          : [];
+        const reviews = yield* GitHubApi.fetchReviews(owner, repo, number).pipe(Effect.provide(credentials));
+        return {
+          state: toState(pull),
+          title: pull.title,
+          commit,
+          ...(pull.body ? { body: pull.body } : {}),
+          ...summarizeCheckRuns(runs),
+          runs: runs.map(toCheckRun),
+          ...summarizeReviews(reviews),
+        };
+      }, Effect.provide(FetchHttpClient.layer)),
+    ),
+  );
+
+export default handler;

package/src/operations/get-repositories.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as Layer from 'effect/Layer';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Obj } from '@dxos/echo';
+
+import { GitHubOperation } from '#types';
+
+import { GitHubApi } from '../services/index.ts';
+
+/**
+ * Discovery only — list GitHub repositories reachable from the connection's
+ * token. Read-only: NO local Projects are created here. Materialization is
+ * handled by the connector's `materializeTarget` when a binding is created.
+ *
+ * Output is sorted by `full_name` (case-insensitive) so the picker is stable
+ * regardless of GitHub's response order.
+ */
+const handler: Operation.WithHandler<typeof GitHubOperation.GetGitHubRepositories> =
+  GitHubOperation.GetGitHubRepositories.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ connection }) {
+        // TODO(wittjosiah): Mirror the Trello pattern — derive the db from the input ref's
+        //   target until the OperationInvoker has a `databaseResolver` and the operation
+        //   can declare `services: [Database.Service]` directly.
+        const target = connection.target;
+        const db = target ? Obj.getDatabase(target) : undefined;
+        if (!db) {
+          return yield* Effect.die(new Error('No database for connection ref.'));
+        }
+
+        return yield* Effect.gen(function* () {
+          const remoteRepos = yield* GitHubApi.fetchUserRepos();
+          const sorted = [...remoteRepos].sort((left, right) =>
+            left.full_name.toLowerCase().localeCompare(right.full_name.toLowerCase()),
+          );
+          const targets = sorted.map((repo) => ({
+            id: String(repo.id),
+            name: repo.full_name,
+            description: repo.description ?? undefined,
+          }));
+          return { targets };
+        }).pipe(Effect.provide(Layer.provideMerge(Database.layer(db), GitHubApi.fromConnection(connection))));
+      }, Effect.provide(FetchHttpClient.layer)),
+    ),
+  );
+
+export default handler;

package/src/operations/import-pull-request-from-snapshot.ts

@@ -0,0 +1,48 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '@dxos/compute/Operation';
+
+import { GitHubOperation } from '#types';
+
+import { GitHubPullRequestReferenceError } from '../errors.ts';
+import { parsePullRequestReference } from '../github-link.ts';
+
+/**
+ * Import the pull request the extension's page is showing.
+ *
+ * The snapshot is read for its URL alone — the page's DOM says nothing GitHub's API does not say
+ * better — and the import itself is delegated, so the anonymous fallback and the existing-object
+ * check stay in one place.
+ */
+const handler: Operation.WithHandler<typeof GitHubOperation.ImportPullRequestFromSnapshot> =
+  GitHubOperation.ImportPullRequestFromSnapshot.pipe(
+    Operation.withHandler(
+      Effect.fn(function* ({ snapshot, target }) {
+        const reference = snapshot.source.url;
+        if (!parsePullRequestReference(reference)) {
+          return yield* Effect.die(new GitHubPullRequestReferenceError({ context: { reference } }));
+        }
+
+        const { pullRequest } = yield* Operation.invoke(
+          GitHubOperation.ImportPullRequest,
+          { reference },
+          { spaceId: target.spaceId },
+        );
+
+        // The extension acks with an object id so the page can open what it just imported; a ref
+        // whose target did not resolve would ack success on nothing.
+        const object = pullRequest.target;
+        if (!object) {
+          return yield* Effect.die(new GitHubPullRequestReferenceError({ context: { reference } }));
+        }
+
+        return { id: object.id };
+      }),
+    ),
+  );
+
+export default handler;

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

@@ -0,0 +1,151 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as HttpClient from 'effect/http/HttpClient';
+import * as HttpClientError from 'effect/http/HttpClientError';
+import * as HttpClientRequest from 'effect/http/HttpClientRequest';
+import * as HttpClientResponse from 'effect/http/HttpClientResponse';
+import { describe, test } from 'vitest';
+
+import * as EffectEx from '@dxos/effect/EffectEx';
+
+import { GitHubRepoInaccessibleError } from '../errors.ts';
+import { GitHubApi } from '../services/index.ts';
+import { fetchPullRequestWithFallback } from './import-pull-request.ts';
+
+const reference = { owner: 'dxos', repo: 'dxos', number: 13188 };
+
+/** The stubs answer without a request, but the fetch signature still carries the client the real one needs. */
+const run = <T>(effect: Effect.Effect<T, never, HttpClient.HttpClient>) =>
+  EffectEx.runAndForwardErrors(effect.pipe(Effect.provide(FetchHttpClient.layer)));
+
+const pull: GitHubApi.GitHubPull = { id: 1, number: reference.number, title: 'Walkthroughs', state: 'open' };
+
+/** The failure `HttpClient.filterStatusOk` produces for a non-2xx GitHub response. */
+const statusError = (status: number) => {
+  const request = HttpClientRequest.get('https://api.github.com/repos/dxos/dxos/pulls/13188');
+  return new HttpClientError.HttpClientError({
+    reason: new HttpClientError.StatusCodeError({
+      request,
+      response: HttpClientResponse.fromWeb(request, new Response(null, { status })),
+    }),
+  });
+};
+
+/** Answers every authenticated request with `status` and every anonymous one with the pull request. */
+const fetchRejectingToken = (status: number, tokens: string[]) => (_owner: string, _repo: string, _number: number) =>
+  Effect.gen(function* () {
+    const { token } = yield* GitHubApi.GitHubCredentials;
+    tokens.push(token);
+    if (token !== '') {
+      return yield* Effect.fail(statusError(status));
+    }
+    return pull;
+  });
+
+describe('import — token fallback', () => {
+  test('a token GitHub rejects is retried anonymously', async ({ expect }) => {
+    const tokens: string[] = [];
+    const result = await run(fetchPullRequestWithFallback(reference, 'dead-token', fetchRejectingToken(401, tokens)));
+
+    expect(result).toEqual(pull);
+    expect(tokens).toEqual(['dead-token', '']);
+  });
+
+  test('a token that works is not retried', async ({ expect }) => {
+    const tokens: string[] = [];
+    const result = await run(
+      fetchPullRequestWithFallback(reference, 'live-token', (_owner, _repo, _number) =>
+        Effect.gen(function* () {
+          tokens.push((yield* GitHubApi.GitHubCredentials).token);
+          return pull;
+        }),
+      ),
+    );
+
+    expect(result).toEqual(pull);
+    expect(tokens).toEqual(['live-token']);
+  });
+
+  test('unauthorized anonymously too reports the repository as inaccessible', async ({ expect }) => {
+    const tokens: string[] = [];
+    const error = await run(
+      fetchPullRequestWithFallback(reference, 'dead-token', (_owner, _repo, _number) =>
+        Effect.gen(function* () {
+          tokens.push((yield* GitHubApi.GitHubCredentials).token);
+          return yield* Effect.fail(statusError(401));
+        }),
+      ),
+    ).then(
+      () => undefined,
+      (error) => error,
+    );
+
+    expect(GitHubRepoInaccessibleError.is(error)).toBe(true);
+    expect((error as GitHubRepoInaccessibleError).context).toMatchObject({
+      ...reference,
+      status: 401,
+      connected: true,
+      tokenStatus: 401,
+    });
+    expect(tokens).toEqual(['dead-token', '']);
+  });
+
+  // GitHub answers 404 rather than 403 wherever a credential lacks access, so a GitHub App token
+  // whose installation does not cover the repository reports a PUBLIC pull request as absent.
+  // Retrying anonymously is the only way to tell that apart from one that really does not exist.
+  for (const status of [403, 404]) {
+    test(`a public pull request survives a token scoped away from it (${status})`, async ({ expect }) => {
+      const tokens: string[] = [];
+      const result = await run(
+        fetchPullRequestWithFallback(reference, 'scoped-token', fetchRejectingToken(status, tokens)),
+      );
+
+      expect(result).toEqual(pull);
+      expect(tokens).toEqual(['scoped-token', '']);
+    });
+  }
+
+  test('a pull request unreachable with and without the token keeps the token status', async ({ expect }) => {
+    const error = await run(
+      fetchPullRequestWithFallback(reference, 'scoped-token', () => Effect.fail(statusError(404))),
+    ).then(
+      () => undefined,
+      (error) => error,
+    );
+
+    expect(GitHubRepoInaccessibleError.is(error)).toBe(true);
+    expect((error as GitHubRepoInaccessibleError).context).toMatchObject({
+      status: 404,
+      connected: true,
+      tokenStatus: 404,
+    });
+  });
+
+  test('a space with no connection reports itself as unconnected', async ({ expect }) => {
+    const tokens: string[] = [];
+    const error = await run(
+      fetchPullRequestWithFallback(reference, '', (_owner, _repo, _number) =>
+        Effect.gen(function* () {
+          tokens.push((yield* GitHubApi.GitHubCredentials).token);
+          return yield* Effect.fail(statusError(404));
+        }),
+      ),
+    ).then(
+      () => undefined,
+      (error) => error,
+    );
+
+    expect(GitHubRepoInaccessibleError.is(error)).toBe(true);
+    expect((error as GitHubRepoInaccessibleError).context).toMatchObject({
+      status: 404,
+      connected: false,
+      tokenStatus: undefined,
+    });
+    // No credential to fall back from, so the anonymous request is the only one made.
+    expect(tokens).toEqual(['']);
+  });
+});

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

@@ -0,0 +1,141 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/http/FetchHttpClient';
+import * as Layer from 'effect/Layer';
+
+import * as Operation from '@dxos/compute/Operation';
+import { Database, Filter, Ref } from '@dxos/echo';
+import * as SpaceOperation from '@dxos/plugin-space/SpaceOperation';
+import { PullRequest } from '@dxos/types';
+
+import { GitHubOperation } from '#types';
+
+import { GitHubPullRequestReferenceError, GitHubRepoInaccessibleError } from '../errors.ts';
+import { type PullRequestReference, parsePullRequestReference } from '../github-link.ts';
+import { toPullRequestProps } from '../pull-request.ts';
+import { GitHubApi } from '../services/index.ts';
+import { githubToken } from './pull-request.ts';
+
+/**
+ * Statuses that may report the token's reach rather than the repository's absence, and so are worth
+ * a second, anonymous attempt.
+ *
+ * 404 is the load-bearing one. GitHub answers 404 rather than 403 wherever a credential lacks access,
+ * so as not to confirm what it cannot show, and a GitHub App user-to-server token — what this
+ * connector holds — reaches only the repositories the App is installed on. A public repository the
+ * App was never installed on therefore reads as absent. (A fine-grained PAT would not behave this
+ * way: those carry read access to every public repository regardless of their selection.)
+ *
+ * Whatever produced it, the rule is the same: a status that a credential could have caused says
+ * nothing about what an anonymous reader can see, and only the anonymous request settles it.
+ */
+const MAY_REFLECT_TOKEN_SCOPE = new Set([401, 403, 404]);
+
+/**
+ * The pull request as the space's GitHub connection, falling back to an anonymous read whenever the
+ * stored token is what stood in the way.
+ *
+ * A public pull request must never fail because of a credential. Three separate conditions make one
+ * look unreachable — a revoked token (401), a suspended or SSO-blocked one (403), and a repository
+ * outside the App installation the token belongs to (404) — and the anonymous retry, which is the
+ * same request a space with no connection would make, resolves all three. The cost is one extra
+ * request on a pull request that genuinely does not exist.
+ *
+ * `fetch` is injected so the fallback can be exercised without an HTTP client.
+ */
+export const fetchPullRequestWithFallback = (
+  { owner, repo, number }: PullRequestReference,
+  token: string,
+  fetch: (
+    owner: string,
+    repo: string,
+    number: number,
+  ) => GitHubApi.GitHubEffect<GitHubApi.GitHubPull> = GitHubApi.fetchPullRequest,
+) =>
+  // Suspended so each run starts with its own `tokenStatus`, which the fallback sets as it runs.
+  Effect.suspend(() => {
+    const fetchAs = (token: string) =>
+      fetch(owner, repo, number).pipe(Effect.provide(Layer.succeed(GitHubApi.GitHubCredentials, { token })));
+
+    // What the authenticated attempt answered, kept so a rejected credential (401) can be told from a
+    // repository the credential simply does not reach (403/404) once the retry has also failed.
+    let tokenStatus: number | undefined;
+
+    return fetchAs(token).pipe(
+      Effect.catchIf(
+        (error) => {
+          const status = GitHubApi.responseStatus(error);
+          return token !== '' && status !== undefined && MAY_REFLECT_TOKEN_SCOPE.has(status);
+        },
+        (error) => {
+          tokenStatus = GitHubApi.responseStatus(error);
+          return fetchAs('');
+        },
+      ),
+      // Out of reach anonymously too (GitHub answers 404 for a private repository seen without
+      // credentials): a typed failure lets the dialog name the connection rather than the reference.
+      Effect.catchIf(
+        (error) => {
+          const status = GitHubApi.responseStatus(error);
+          return status !== undefined && MAY_REFLECT_TOKEN_SCOPE.has(status);
+        },
+        (error) =>
+          Effect.die(
+            new GitHubRepoInaccessibleError({
+              context: {
+                owner,
+                repo,
+                number,
+                status: GitHubApi.responseStatus(error),
+                connected: token !== '',
+                tokenStatus,
+              },
+            }),
+          ),
+      ),
+      Effect.orDie,
+    );
+  });
+
+/**
+ * Import a pull request the user named, as the space's GitHub connection or anonymously.
+ *
+ * The object is filed through `SpaceOperation.AddObject` rather than added directly: an imported
+ * pull request is something the user went looking for, so it belongs where they can find it again.
+ */
+const handler: Operation.WithHandler<typeof GitHubOperation.ImportPullRequest> = GitHubOperation.ImportPullRequest.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ reference }) {
+      const parsed = parsePullRequestReference(reference);
+      if (!parsed) {
+        return yield* Effect.die(new GitHubPullRequestReferenceError({ context: { reference } }));
+      }
+
+      const { owner, repo, number } = parsed;
+      const [existing] = yield* Database.query(Filter.type(PullRequest.PullRequest, { owner, repo, number })).run.pipe(
+        Effect.orDie,
+      );
+      if (existing) {
+        return { pullRequest: Ref.make(existing), imported: false };
+      }
+
+      const pull = yield* fetchPullRequestWithFallback(parsed, yield* githubToken());
+
+      const { object } = yield* Operation.invoke(SpaceOperation.AddObject, {
+        object: PullRequest.make(toPullRequestProps(parsed, pull)),
+      });
+      // `AddObject` answers with what it filed, typed as any object; the narrowing is what makes the
+      // returned ref a pull request's rather than a cast.
+      if (!PullRequest.instanceOf(object)) {
+        return yield* Effect.die(new GitHubPullRequestReferenceError({ context: { reference } }));
+      }
+
+      return { pullRequest: Ref.make(object), imported: true };
+    }, Effect.provide(FetchHttpClient.layer)),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Operation from '@dxos/compute/Operation';
+import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
+
+import { GitHubOperation } from '#types';
+
+export const GitHubOperationHandlerSet = OperationHandlerSet.lazy([
+  GitHubOperation.GetGitHubRepositories.pipe(Operation.lazyHandler(() => import('./get-repositories.ts'))),
+  GitHubOperation.MaterializeGitHubTarget.pipe(Operation.lazyHandler(() => import('./materialize-target.ts'))),
+  GitHubOperation.SyncGitHubRepositories.pipe(Operation.lazyHandler(() => import('./sync.ts'))),
+  GitHubOperation.GenerateWalkthrough.pipe(Operation.lazyHandler(() => import('./generate-walkthrough.ts'))),
+  GitHubOperation.ImportPullRequest.pipe(Operation.lazyHandler(() => import('./import-pull-request.ts'))),
+  GitHubOperation.ImportPullRequestFromSnapshot.pipe(
+    Operation.lazyHandler(() => import('./import-pull-request-from-snapshot.ts')),
+  ),
+  GitHubOperation.SubmitPullRequestApproval.pipe(
+    Operation.lazyHandler(() => import('./submit-pull-request-approval.ts')),
+  ),
+  GitHubOperation.AddPullRequestComment.pipe(Operation.lazyHandler(() => import('./add-pull-request-comment.ts'))),
+  GitHubOperation.AddPullRequestReviewComment.pipe(
+    Operation.lazyHandler(() => import('./add-pull-request-review-comment.ts')),
+  ),
+  GitHubOperation.GetPullRequestStatus.pipe(Operation.lazyHandler(() => import('./get-pull-request-status.ts'))),
+  GitHubOperation.SyncPullRequest.pipe(Operation.lazyHandler(() => import('./sync-pull-request.ts'))),
+  GitHubOperation.GetPullRequestDiff.pipe(Operation.lazyHandler(() => import('./get-pull-request-diff.ts'))),
+]);