@dxos/plugin-github 0.7.4 → 0.14.0

package/src/translations.ts

@@ -1,72 +1,144 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-import { GITHUB_PLUGIN } from './meta';
+import { Type } from '@dxos/echo';
+import type * as Theme from '@dxos/react-ui/Theme';
+import { PullRequest } from '@dxos/types';
 
-export default [
+import { meta } from '#meta';
+import { Walkthrough } from '#types';
+
+export const translations = [
   {
     'en-US': {
-      [GITHUB_PLUGIN]: {
-        'plugin name': 'GitHub',
-        'markdown actions label': 'GitHub actions',
-        'unbind to file in github label': 'Disconnect from GitHub',
-        'bind to file in github label': 'Connect to issue or file in GitHub',
-        'github pat label': 'GitHub personal access token:',
-        'github pat description':
-          'Composer needs this in order to communicate with GitHub. <docsLink>GitHub’s documentation describes how to create a token.</docsLink> Composer only needs write access to issues, contents, and pull requests.',
-        'github pat description href':
-          'https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens',
-        'empty github pat message': 'Set a GitHub personal access token to continue.',
-        'set github pat label': 'Set GitHub token',
-        'error github pat message':
-          'There was a problem authenticating with GitHub using the personal access token provided.',
-        'error github markdown path message': 'This is not a valid path to a Markdown file or Issue in GitHub.',
-        'paste url to file in github label': 'Paste the URL to the Issue or Markdown file in GitHub.',
-        'paste url to file in github description':
-          'Navigate to the issue or file in GitHub, then copy the URL in your browser and paste it here.',
-        'paste url to file in github placeholder': 'https://github.com/owner/repo/blob/main/path/to/README.md',
-        'confirm export title': 'Export to GitHub',
-        'export to github success message':
-          '<resultStyle>Success!</resultStyle> Your changes are now live here: <prLink>{{linkText}}</prLink>',
-        'github branch name label': 'Name of the branch to create',
-        'github branch name placeholder': 'update-readme',
-        'github commit message label': 'Commit message',
-        'github commit message placeholder': 'Updated README.md',
-        'save and close description': 'Save changes to GitHub and close the editor',
-        'close embed description':
-          'Close the editor without saving changes to GitHub. Your changes will still persist in Composer.',
-        'resolver init document message': 'Syncing this document, one moment…',
-        'comment stale title': 'No longer in-sync',
-        'comment stale body':
-          'The document in GitHub was updated in another session. To re-sync, please save your changes, reload the page, and choose to edit from GitHub again.',
-        'open in github label': 'Open in GitHub',
-        'stale rescue title': 'Set a personal access token',
-        'stale rescue description':
-          'Another user has recently updated this issue, so GitHub won’t accept your changes unless you set a personal access token (a PAT) here, or refresh the page.',
-        'embedded options label': 'Options',
-        'unset repo space label': 'Select a different space for this repository',
-        'loading preview message': 'Loading preview…',
-        'preview gfm label': 'Preview Markdown',
-        'exit gfm preview label': 'Exit preview',
-        'save and close label': 'Save & close',
-        'export to github label': 'Export to GitHub',
-        'import from github label': 'Import from GitHub',
-        'resolver tree label': 'Choose a Space',
-        'resolver tree description':
-          'To collaborate on documents in this repository, choose the Space that will store and control access to the documents.',
-        'resolver no spaces message': 'You aren’t in any spaces yet',
-        'resolver create space label': 'Create a space for this repository',
-        'bound members message_one': 'One member uses this space for this repository',
-        'bound members message_other': '{{count}} members use this space for this repository',
-        'select label': 'Select',
-        'selected label': 'Selected',
-        'open in composer label': 'Open in Composer',
-        'confirm import title': 'Overwrite this document’s content?',
-        'confirm import body':
-          'Importing will overwrite this document’s content. If you’d rather import into a new document, first create a new document and then import into it.',
-        'target blank description': 'Link opens in a new tab.',
+      [Type.getTypename(PullRequest.PullRequest)]: {
+        'typename.label': 'Pull request',
+        'typename.label_zero': 'Pull requests',
+        'typename.label_one': 'Pull request',
+        'typename.label_other': 'Pull requests',
+        'object-name.placeholder': 'New pull request',
+        'rename-object.label': 'Rename pull request',
+        'delete-object.label': 'Delete pull request',
+        'object-deleted.label': 'Pull request deleted',
+      },
+      [Type.getTypename(Walkthrough.Walkthrough)]: {
+        'typename.label': 'Walkthrough',
+        'typename.label_zero': 'Walkthroughs',
+        'typename.label_one': 'Walkthrough',
+        'typename.label_other': 'Walkthroughs',
+        'object-name.placeholder': 'New walkthrough',
+        'rename-object.label': 'Rename walkthrough',
+        'delete-object.label': 'Delete walkthrough',
+        'object-deleted.label': 'Walkthrough deleted',
+      },
+      [meta.profile.key]: {
+        'plugin.name': 'GitHub',
+        'sync-now.label': 'Sync now',
+        'sync-toast.success.label': 'Sync complete',
+        'sync-toast.error.label': 'Sync failed',
+        'open-walkthrough.label': 'Open walkthrough',
+        'generate-walkthrough.label': 'Generate walkthrough',
+        'regenerate-walkthrough.label': 'Regenerate walkthrough',
+        'no-walkthrough.message': 'No walkthrough yet for this pull request.',
+        'walkthrough-generating.message': 'Writing the walkthrough…',
+        'import-pull-request.label': 'Import pull request',
+        'import-pull-request-dialog.title': 'Import pull request',
+        'import-pull-request-submit.label': 'Import',
+        'import-pull-request-failed.title': 'Could not import the pull request',
+        'import-pull-request-token-rejected.title': 'GitHub rejected your connection — reconnect GitHub and try again',
+        'import-pull-request-not-connected.title':
+          'Pull request not found — connect GitHub to import one from a private repository',
+        'import-pull-request-inaccessible.title':
+          'Pull request not found, or not accessible with your GitHub connection',
+        'import-pull-request-no-space.title': 'Open a space to import a pull request into',
+        'open-pull-request.label': 'Open pull request',
+        'github-token-rejected.title': 'GitHub rejected your connection — reconnect GitHub and try again',
+        'open-github-connection.label': 'Go to connection',
+        'walkthrough-ready.title': 'Walkthrough ready',
+        'walkthrough-failed.title': 'Walkthrough generation failed',
+        'approve-pull-request.label': 'Approve',
+        'approve-pull-request-success.title': 'Pull request approved',
+        'approve-pull-request-commented.title': 'Approval posted as a comment',
+        'approve-pull-request-error.title': 'Could not approve the pull request',
+        'comment-pull-request.label': 'Comment',
+        'comment-placeholder.label': 'Leave a comment on the pull request',
+        'comment-line.label': 'Commenting on {{file}}:{{line}}',
+        'comment-submit.label': 'Post comment',
+        'comment-cancel.label': 'Cancel',
+        'comment-success.title': 'Comment posted',
+        'comment-error.title': 'Could not post the comment',
+        'open-on-github.label': 'Open on GitHub',
+        'copy-link.label': 'Copy link to pull request',
+        'copy-link-success.title': 'Link copied',
+        'copy-link-error.title': 'Could not copy the link',
+        'pull-requests-sort.label': 'Sort',
+        'pull-requests-sort-relevance.label': 'Relevance',
+        'pull-requests-sort-updated.label': 'Updated',
+        'pull-requests-sort-created.label': 'Created',
+        'pull-requests-sort-number.label': 'Number',
+        'pull-requests-sort-title.label': 'Title',
+        'pull-requests-sort-asc.label': 'Ascending',
+        'pull-requests-sort-desc.label': 'Descending',
+        'pull-requests-group.label': 'Group',
+        'pull-requests-group-none.label': 'No grouping',
+        'pull-requests-group-repo.label': 'Repository',
+        'pull-requests-group-state.label': 'State',
+        'pull-requests-group-checks.label': 'Checks',
+        'pull-requests-group-author.label': 'Author',
+        'pull-requests-filter-clear.label': 'Clear filter',
+        'pull-requests-empty.message': 'No pull requests in this space yet.',
+        'pull-requests-no-match.message': 'No pull requests match the filter.',
+        'group-no-author.label': 'Unknown author',
+        'untitled-task.label': 'Untitled task',
+        'ci-status.success.label': 'CI passing',
+        'ci-status.failure.label': 'CI failing',
+        'ci-status.pending.label': 'CI running',
+        'ci-status.none.label': 'No CI',
+        'ci-status.unknown.label': 'CI unknown',
+        'pull-request-state.open.label': 'Open',
+        'pull-request-state.closed.label': 'Closed',
+        'pull-request-state.merged.label': 'Merged',
+        'pull-request-state.draft.label': 'Draft',
+        'review-status.approved.label_one': 'Approved',
+        'review-status.approved.label_other': 'Approved ×{{count}}',
+        'review-status.changes_requested.label': 'Changes requested',
+        'review-status.none.label': 'Awaiting review',
+        'review-status.unknown.label': 'Review unknown',
+        'views.label': 'Views',
+        'overview-tab.label': 'Overview',
+        'walkthrough-tab.label': 'Walkthrough',
+        'files-tab.label': 'Files',
+        'files-tree.label': 'Changed files',
+        'files-reviewed.label': '{{reviewed}} of {{total}} files reviewed',
+        'files-loading.message': 'Loading the changed files…',
+        'files-error.message': 'Could not read the changed files.',
+        'no-files.message': 'This pull request changes no files.',
+        'file-no-diff.message': 'No text changes to show — a binary file, or a rename without edits.',
+        'file-reviewed.label': 'Reviewed',
+        'previous-file.label': 'Previous file',
+        'next-file.label': 'Next file',
+        'details.label': 'Details',
+        'no-description.message': 'No description provided.',
+        'related.label': 'Related',
+        'checks.label': 'Checks',
+        'checks-summary.label': '{{passed}} passed · {{failed}} failed · {{pending}} running · {{skipped}} skipped',
+        'checks-loading.message': 'Loading checks…',
+        'no-checks.message': 'No checks ran on the head commit.',
+        'check-outcome.success.label': 'Passed',
+        'check-outcome.failure.label': 'Failed',
+        'check-outcome.pending.label': 'Running',
+        'check-outcome.skipped.label': 'Skipped',
+        'check-outcome.neutral.label': 'Neutral',
+        'preview-deployment.label': 'Composer preview',
+        'claude-session.label': 'Claude Code session',
+        'claude-generated.label': 'Generated with Claude Code',
+        'artifact-video.label': 'Demo video',
+        'artifact-image.label': 'Screenshot',
+        'artifact-file.label': 'Artifact',
+        'branches.label': 'Branches',
+        'open-link.label': 'Open',
       },
     },
   },
-];
+] as const satisfies Theme.Resource[];

package/src/types/GitHubCapabilities.ts

@@ -0,0 +1,27 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import type * as Effect from 'effect/Effect';
+
+import * as Capability from '@dxos/app-framework/Capability';
+import type * as PreviewCapabilities from '@dxos/plugin-preview/PreviewCapabilities';
+import { type Issue, type PullRequest, type Repo } from '@dxos/types';
+
+import { meta } from '#meta';
+
+import { type GitHubLink } from '../extensions/index.ts';
+
+/**
+ * Where a previewed link's repository, pull request or issue comes from. The plugin's default fetches it from
+ * the GitHub API with the space's connection token (anonymously when there is none); a host that
+ * contributes one — a story, a test, an offline build — replaces the fetch.
+ */
+export type GitHubLinkSource = (
+  link: GitHubLink,
+  context: PreviewCapabilities.PreviewLinkContext,
+) => Effect.Effect<Repo.Repo | Issue.Issue | PullRequest.PullRequest | undefined>;
+
+export const LinkSource = Capability.make<GitHubLinkSource>()(`${meta.profile.key}.capability.linkSource`);

package/src/types/GitHubEvents.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as ActivationEvent from '@dxos/app-framework/ActivationEvent';
+
+import { meta } from '#meta';
+
+/**
+ * The feature's start event: the plugin's start-gated modules (and cross-plugin
+ * contributions consumed by this feature) activate here. Fired on demand and by the
+ * host's idle trickle.
+ */
+export const Start = ActivationEvent.pluginStart(meta.profile.key);

package/src/types/GitHubOperation.ts

@@ -0,0 +1,397 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { AiService } from '@dxos/ai';
+import * as Operation from '@dxos/compute/Operation';
+import * as Trace from '@dxos/compute/Trace';
+import { Database, DXN, Obj, Ref } from '@dxos/echo';
+// Referenced in the emitted .d.ts of the operations (via `ConnectorSpec`'s schemas); importing it
+// lets TypeScript name it (TS2883).
+// eslint-disable-next-line unused-imports/no-unused-imports
+import { Connection } from '@dxos/link';
+import * as ConnectorSpec from '@dxos/plugin-connector/ConnectorSpec';
+import * as PageAction from '@dxos/plugin-crx/PageAction';
+import { PullRequest } from '@dxos/types';
+
+import * as Walkthrough from './Walkthrough.ts';
+
+/**
+ * Discovery only — list GitHub repositories the connection's token can see.
+ * Returns one descriptor per repo across all the user's orgs (and personal
+ * account). Read-only: NEVER materializes local objects — materialization is
+ * handled by the connector's `materializeTarget` when a `Cursor` is created.
+ *
+ * Orgs and their members are NOT presented as sync targets — they are
+ * auto-synced as part of the sync of any repo they own.
+ */
+export const GetGitHubRepositories = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.getRepositories'),
+    name: 'Get GitHub Repositories',
+    description: 'List GitHub repositories reachable from a connection without materializing local objects.',
+    icon: 'ph--github-logo--regular',
+  },
+  input: ConnectorSpec.GetSyncTargetsInput,
+  output: ConnectorSpec.GetSyncTargetsOutput,
+});
+
+/**
+ * Find-or-create the empty local root Project for a selected GitHub repo so a
+ * cursor can reference it as its `spec.target`. Keyed by the repo's
+ * GitHub foreign id (`remoteTarget.id`), so it is idempotent across re-selection.
+ */
+export const MaterializeGitHubTarget = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.materializeTarget'),
+    name: 'Materialize GitHub Target',
+    description: 'Create the empty local root Project bound to a selected GitHub repository.',
+    icon: 'ph--github-logo--regular',
+  },
+  input: ConnectorSpec.MaterializeTargetInput,
+  output: ConnectorSpec.MaterializeTargetOutput,
+});
+
+/**
+ * Per-target options. `maxDaysBack` caps how far back issues/PRs are pulled
+ * (mirrors the Gmail mailbox `daysBack`). Default — when unset — is "sync
+ * everything ever opened or edited."
+ */
+export const SyncOptions = Schema.Struct({
+  maxDaysBack: Schema.Number.annotate({
+    title: 'Sync history (days)',
+    description: 'Pull issues and PRs updated within this many days. Leave empty to sync everything.',
+  }).pipe(Schema.optional),
+});
+
+export interface SyncOptions extends Schema.Schema.Type<typeof SyncOptions> {}
+
+/**
+ * Reconcile GitHub data for every repo bound to a connection (one cursor per repo).
+ *
+ * Pull-then-push per bound repo: auto-upsert its owning org + members,
+ * three-way merge the repo as a Project and its issues/PRs as Tasks (respecting
+ * `maxDaysBack` if set), then push diverged Project/Task fields back to GitHub.
+ * Sync state (`lastTick`/`lastError`/`spec.snapshots`) is written onto each binding.
+ */
+export const SyncGitHubRepositories = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.syncRepositories'),
+    name: 'Sync GitHub Repositories',
+    description: 'Reconcile every bound GitHub repo plus its owning org, members, issues, PRs, and comments.',
+    icon: 'ph--arrows-clockwise--regular',
+  },
+  input: ConnectorSpec.SyncInput,
+  output: Schema.Struct({
+    pulled: Schema.Struct({
+      organizations: Schema.Number,
+      people: Schema.Number,
+      projects: Schema.Number,
+      tasks: Schema.Number,
+      comments: Schema.Number,
+    }),
+  }),
+}).pipe(Operation.visible);
+
+/**
+ * Import a pull request named by a github.com URL or `owner/repo#123` into the space, so it can be
+ * opened, reviewed and walked through without waiting for a sync of the whole repository.
+ *
+ * Idempotent by coordinates — a pull request the space already holds is returned as it stands
+ * rather than duplicated.
+ */
+export const ImportPullRequest = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.importPullRequest'),
+    name: 'Import Pull Request',
+    description: 'Add a pull request to the space, named by its URL or as owner/repo#number.',
+    icon: 'ph--git-pull-request--regular',
+  },
+  services: [Database.Service],
+  input: Schema.Struct({
+    /** A github.com pull request URL, or `owner/repo#123`. */
+    reference: Schema.String,
+  }),
+  output: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+    /** False where the space already held the pull request, which is then returned unchanged. */
+    imported: Schema.Boolean,
+  }),
+  types: [PullRequest.PullRequest],
+}).pipe(Operation.visible, Operation.mutation('write'));
+
+/**
+ * Import the pull request the browser extension is looking at, named by the page's own URL.
+ *
+ * Separate from {@link ImportPullRequest} because the extension bridge invokes every page action
+ * with the fixed `{ snapshot, target }` shape and reads an `{ id }` back. Nothing is extracted from
+ * the page: the URL in the snapshot's source names the pull request, and GitHub is the authority on
+ * everything else.
+ */
+export const ImportPullRequestFromSnapshot = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.importPullRequestFromSnapshot'),
+    name: 'Open pull request in Composer',
+    description: "Import the pull request a browser page shows, named by that page's URL.",
+    icon: 'ph--git-pull-request--regular',
+  },
+  input: Schema.Struct({
+    snapshot: PageAction.Snapshot,
+    target: Database.Database.annotate({ description: 'The database to add the pull request to.' }),
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+  }),
+  types: [PullRequest.PullRequest],
+}).pipe(Operation.mutation('write'));
+
+/**
+ * Generate a walkthrough of a pull request: one markdown document narrating the change in reading
+ * order, with its diff chunks spliced in from the patch itself.
+ *
+ * Idempotent by commit — a walkthrough already generated for the pull request's head is returned
+ * unchanged unless `force` says otherwise, since the answer cannot have changed.
+ */
+export const GenerateWalkthrough = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.generateWalkthrough'),
+    name: 'Generate Walkthrough',
+    description: "Narrate a pull request as one markdown document, with the change's diffs embedded in it.",
+    icon: 'ph--path--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+    /** Regenerate even where a walkthrough for this head already exists. */
+    force: Schema.Boolean.pipe(Schema.optional),
+  }),
+  output: Schema.Struct({
+    walkthrough: Ref.Ref(Walkthrough.Walkthrough),
+    /** Whether the model ran, as against an existing walkthrough being returned unchanged. */
+    generated: Schema.Boolean,
+    /** Hunks the prose accounts for, over the patch's total. */
+    covered: Schema.Number,
+    total: Schema.Number,
+  }),
+  types: [Walkthrough.Walkthrough, PullRequest.PullRequest],
+  // `AiService` must be declared, not merely provided: the invoker builds the runtime from THIS list
+  // and `Layer.orDie` clears a layer's error channel, never its requirement.
+  services: [Trace.TraceService, AiService.AiService],
+}).pipe(Operation.visible);
+
+/**
+ * Submit an approving review on a pull request, as the space's GitHub connection.
+ *
+ * Falls back to a marked conversation comment where GitHub refuses the review — the author's own
+ * pull request, or a token with no review permission — so the approval is still recorded and still
+ * detectable by an agent deciding whether the pull request is good to land.
+ */
+export const SubmitPullRequestApproval = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.submitPullRequestApproval'),
+    name: 'Submit Pull Request Approval',
+    description: 'Submit an approving review on a pull request, or record the approval as a comment.',
+    icon: 'ph--check-circle--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+    /** Optional review summary. */
+    body: Schema.String.pipe(Schema.optional),
+  }),
+  output: Schema.Struct({
+    /** Set where the approving review was accepted. */
+    reviewId: Schema.Number.pipe(Schema.optional),
+    /** Set instead where the approval was recorded as a comment. */
+    commentId: Schema.Number.pipe(Schema.optional),
+    url: Schema.String.pipe(Schema.optional),
+    /** Whether the approval is a comment rather than a review. */
+    commented: Schema.Boolean,
+  }),
+  types: [PullRequest.PullRequest],
+});
+
+/** Post a conversation comment on a pull request, as the space's GitHub connection. */
+export const AddPullRequestComment = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.addPullRequestComment'),
+    name: 'Add Pull Request Comment',
+    description: 'Post a comment on a pull request.',
+    icon: 'ph--chat-text--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+    body: Schema.String,
+  }),
+  output: Schema.Struct({
+    commentId: Schema.Number,
+    url: Schema.String.pipe(Schema.optional),
+  }),
+  types: [PullRequest.PullRequest],
+});
+
+/** Post a review comment on one line of a pull request's diff, as the space's GitHub connection. */
+export const AddPullRequestReviewComment = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.addPullRequestReviewComment'),
+    name: 'Add Pull Request Review Comment',
+    description: 'Post a review comment on a line of a pull request diff.',
+    icon: 'ph--chat-centered-text--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+    body: Schema.String,
+    /** Head SHA the line numbers refer to; a walkthrough's `commit`. */
+    commit: Schema.String,
+    path: Schema.String,
+    line: Schema.Number,
+    /** `LEFT` for the removed side, `RIGHT` for added and context lines. */
+    side: Schema.Literals(['LEFT', 'RIGHT']),
+  }),
+  output: Schema.Struct({
+    commentId: Schema.Number,
+    url: Schema.String.pipe(Schema.optional),
+  }),
+  types: [PullRequest.PullRequest],
+});
+
+/**
+ * Re-read a stored pull request from GitHub and write back whatever has changed — its title, state,
+ * description, branches and size — so the object in the space does not go stale between syncs.
+ */
+export const SyncPullRequest = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.syncPullRequest'),
+    name: 'Sync Pull Request',
+    description: 'Refresh a stored pull request from GitHub.',
+    icon: 'ph--arrows-clockwise--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+  }),
+  output: Schema.Struct({
+    /** Names of the fields that changed; empty where the stored pull request was already current. */
+    updated: Schema.Array(Schema.String),
+  }),
+  types: [PullRequest.PullRequest],
+}).pipe(Operation.mutation('write'));
+
+/**
+ * Refresh every pull request in the space that is still in flight (open or draft) from GitHub.
+ *
+ * Run on a schedule by the space's refresh trigger (see `ensureRefreshTrigger`), so pull requests the
+ * user is not looking at still track their state; one unreachable pull request does not fail the rest.
+ */
+export const RefreshPullRequests = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.refreshPullRequests'),
+    name: 'Refresh Pull Requests',
+    description: 'Refresh every open pull request in the space from GitHub.',
+    icon: 'ph--arrows-clockwise--regular',
+  },
+  services: [Database.Service],
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    /** Open pull requests read from GitHub. */
+    checked: Schema.Number,
+    /** Of those, the ones whose stored fields changed. */
+    updated: Schema.Number,
+    /** Of those, the ones GitHub could not be read for. */
+    failed: Schema.Number,
+  }),
+  types: [PullRequest.PullRequest],
+}).pipe(Operation.mutation('write'));
+
+/** Aggregate outcome of a commit's check runs; `none` when the commit has no checks at all. */
+export const CiState = Schema.Literals(['success', 'failure', 'pending', 'none']);
+export type CiState = Schema.Schema.Type<typeof CiState>;
+
+export const CheckCounts = Schema.Struct({
+  total: Schema.Number,
+  passed: Schema.Number,
+  failed: Schema.Number,
+  pending: Schema.Number,
+});
+export interface CheckCounts extends Schema.Schema.Type<typeof CheckCounts> {}
+
+/**
+ * Where the reviews stand, from each reviewer's latest verdict: any outstanding request for changes
+ * outweighs approvals, and `none` means no reviewer has approved or asked for changes.
+ */
+export const ReviewState = Schema.Literals(['approved', 'changes_requested', 'none']);
+export type ReviewState = Schema.Schema.Type<typeof ReviewState>;
+
+/** How one check run ended, folded to what a reader acts on; `skipped` is neither passing nor failing. */
+export const CheckOutcome = Schema.Literals(['success', 'failure', 'pending', 'skipped', 'neutral']);
+export type CheckOutcome = Schema.Schema.Type<typeof CheckOutcome>;
+
+/** One check run on the head commit, as the article lists it. */
+export const CheckRun = Schema.Struct({
+  name: Schema.String,
+  outcome: CheckOutcome,
+  /** GitHub's own `conclusion` (`timed_out`, `cancelled`, …), kept for the label when it says more than the outcome. */
+  conclusion: Schema.String.pipe(Schema.optional),
+  /** Where the run's logs live: the provider's page when it has one, else GitHub's. */
+  url: Schema.String.pipe(Schema.optional),
+  startedAt: Schema.String.pipe(Schema.optional),
+  completedAt: Schema.String.pipe(Schema.optional),
+});
+export interface CheckRun extends Schema.Schema.Type<typeof CheckRun> {}
+
+/** Read a pull request's live state and the CI outcome of its head commit from GitHub. */
+export const GetPullRequestStatus = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.getPullRequestStatus'),
+    name: 'Get Pull Request Status',
+    description: "Read a pull request's state, its review verdict and the CI status of its head commit.",
+    icon: 'ph--git-pull-request--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+  }),
+  output: Schema.Struct({
+    state: PullRequest.State,
+    title: Schema.String,
+    commit: Schema.String.pipe(Schema.optional),
+    /** The live description, which may have changed since the pull request was imported. */
+    body: Schema.String.pipe(Schema.optional),
+    ci: CiState,
+    checks: CheckCounts,
+    runs: Schema.Array(CheckRun),
+    review: ReviewState,
+    /** Reviewers whose latest verdict is an approval. */
+    approvals: Schema.Number,
+  }),
+  types: [PullRequest.PullRequest],
+});
+
+/**
+ * Read a pull request's whole change as a unified diff, with the head commit it was taken at so a
+ * line comment on it anchors to the lines the reader saw.
+ */
+export const GetPullRequestDiff = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.github.getPullRequestDiff'),
+    name: 'Get Pull Request Diff',
+    description: "Read a pull request's changed files as a unified diff.",
+    icon: 'ph--git-diff--regular',
+  },
+  input: Schema.Struct({
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+  }),
+  output: Schema.Struct({
+    commit: Schema.String.pipe(Schema.optional),
+    diff: Schema.String,
+  }),
+  types: [PullRequest.PullRequest],
+});
+
+/**
+ * Progress key for {@link GenerateWalkthrough}, derived from the pull request rather than passed, so
+ * the UI can watch a run it did not start. The absolute URI form is required: a hydration-dependent
+ * one would not match the key the producer mints.
+ */
+export const createWalkthroughProgressKey = (pullRequest: PullRequest.PullRequest): string =>
+  Obj.getURI(pullRequest, { prefer: 'absolute' }).toString() + '#walkthrough';