@dxos/plugin-github 0.7.4 → 0.13.0

package/src/capabilities/schema.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { PullRequest } from '@dxos/types';
+
+import { Walkthrough } from '#types';
+
+/**
+ * Schemas this plugin registers, in a module of their own so they are loaded on demand rather than
+ * from the plugin body's graph.
+ *
+ * `PullRequest` comes with `Walkthrough` because a walkthrough holds a ref to one, and a space that
+ * can read the walkthrough has to be able to resolve what it points at.
+ */
+export default [Walkthrough.Walkthrough, PullRequest.PullRequest];

package/src/capabilities/skill-definition.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+
+import { GitHubSkill } from '#skills';
+
+const skillDefinition = () => Effect.succeed([Capability.contribute(AppCapabilities.SkillDefinition, GitHubSkill)]);
+
+export default skillDefinition;

package/src/cards/GitHubCard.stories.tsx

@@ -0,0 +1,165 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+import { expect, within } from 'storybook/test';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import * as ObjectCard from '@dxos/app-toolkit/ObjectCard';
+import { Obj } from '@dxos/echo';
+import * as Button from '@dxos/react-ui/Button';
+import * as Layout from '@dxos/react-ui/Layout';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { createIssue, createPullRequest, createRepo } from '../testing/index.ts';
+import { GitHubCard } from './GitHubCard.tsx';
+
+const subjects = {
+  repo: createRepo,
+  pr: createPullRequest,
+  issue: createIssue,
+};
+
+type StoryArgs = {
+  kind: keyof typeof subjects;
+  /** Replaces the subject's label, to try a title longer than the card. */
+  title?: string;
+};
+
+/**
+ * The card as the popover hosts it: the host's header carries the label, the plugin's card the body.
+ * `dx-card-popover` is the deck popover's own sizing, so every kind renders at the same width.
+ */
+const DefaultStory = ({ kind, title }: StoryArgs) => {
+  const subject = useMemo(() => subjects[kind](), [kind]);
+  return (
+    <ObjectCard.Root classNames='dx-card-popover dx-card-min-width'>
+      <ObjectCard.Header subject={subject}>{title ?? Obj.getLabel(subject)}</ObjectCard.Header>
+      <GitHubCard role='card--content' subject={subject} />
+    </ObjectCard.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-github/cards/GitHubCard',
+  render: DefaultStory,
+  argTypes: {
+    kind: { control: 'select', options: Object.keys(subjects) },
+  },
+  decorators: [withTheme(), withLayout({ layout: 'centered' }), withPluginManager()],
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Repo: Story = {
+  args: {
+    kind: 'repo',
+  },
+};
+
+export const PullRequest: Story = {
+  args: {
+    kind: 'pr',
+  },
+};
+
+export const Issue: Story = {
+  args: {
+    kind: 'issue',
+  },
+};
+
+/** A title longer than the card stays on one line, truncated, as the popover and gallery show it. */
+export const TestLongTitle: Story = {
+  args: {
+    kind: 'pr',
+    title: 'plugin-tasks: order-by and group-by controls for the task list, with persistent filters',
+  },
+  play: async ({ canvasElement }) => {
+    const title = within(canvasElement).getByRole('heading');
+    const { lineHeight } = getComputedStyle(title);
+    // Under two lines tall (the box has padding, so not exactly one), and its text runs past the end.
+    await expect(title.getBoundingClientRect().height).toBeLessThan(2 * Number.parseFloat(lineHeight));
+    await expect(title.scrollWidth).toBeGreaterThan(title.clientWidth);
+  },
+};
+
+const LONG_TITLE =
+  'plugin-interlocutor: agents reachable from Discord threads, with a memory graph and an interview skill';
+
+const LONG_DESCRIPTION = [
+  '## Summary',
+  'Adds `@dxos/plugin-agent`, a plugin that lets agents be reached from Discord threads. It keeps a memory graph per',
+  'thread and ships an interview skill, so the agent can gather requirements before it acts.',
+  'It also adds stories and a fixture for the interview flow.',
+].join('\n\n');
+
+/** The deck popover's host: the regular size, a header menu in the end rail, and the card body under it. */
+const PopoverStory = () => {
+  const subject = useMemo(() => {
+    const pullRequest = createPullRequest();
+    Obj.update(pullRequest, (pullRequest) => {
+      pullRequest.description = LONG_DESCRIPTION;
+    });
+    return pullRequest;
+  }, []);
+
+  return (
+    <div className='dx-scope' data-size='md'>
+      <ObjectCard.Root border={false} classNames='dx-card-popover dx-card-min-width'>
+        <ObjectCard.Header
+          subject={subject}
+          menu={
+            <Layout.Block rail='end'>
+              <Button.Root variant='ghost' icon='ph--dots-three-vertical--regular' iconOnly label='Actions' />
+            </Layout.Block>
+          }
+        >
+          {LONG_TITLE}
+        </ObjectCard.Header>
+        <GitHubCard role='card--content' subject={subject} />
+      </ObjectCard.Root>
+    </div>
+  );
+};
+
+/**
+ * In the popover a long title stays on one line, the description wraps to at most three lines with its icon beside the
+ * first, and the card ends at its last row.
+ */
+export const TestPopover: Story = {
+  args: { kind: 'pr' },
+  render: () => <PopoverStory />,
+  play: async ({ canvasElement }) => {
+    const card = canvasElement.querySelector<HTMLElement>('.dx-card-popover');
+    await expect(card).not.toBeNull();
+    const title = within(canvasElement).getByRole('heading');
+    const lineHeight = Number.parseFloat(getComputedStyle(title).lineHeight);
+    await expect(title.getBoundingClientRect().height).toBeLessThan(2 * lineHeight);
+    await expect(title.scrollWidth).toBeGreaterThan(title.clientWidth);
+
+    const description = within(canvasElement).getByText(/^## Summary/);
+    const descriptionStyle = getComputedStyle(description);
+    const padding = Number.parseFloat(descriptionStyle.paddingTop) + Number.parseFloat(descriptionStyle.paddingBottom);
+    const lines = Math.round((description.clientHeight - padding) / Number.parseFloat(descriptionStyle.lineHeight));
+    await expect(lines).toBe(3);
+    const row = description.closest<HTMLElement>('.dx-card-row');
+    const icon = row?.querySelector<HTMLElement>('.dx-block, [data-rail="start"]');
+    await expect(
+      Math.abs((icon?.getBoundingClientRect().top ?? Number.NaN) - (row?.getBoundingClientRect().top ?? 0)),
+    ).toBeLessThanOrEqual(1);
+
+    // As far below the last row as the header is below the top: no empty band at the foot.
+    const rows = Array.from(card?.querySelectorAll<HTMLElement>('.dx-card-row') ?? []);
+    const header = card?.querySelector<HTMLElement>('.dx-card-header');
+    const cardRect = card?.getBoundingClientRect();
+    const top = (header?.getBoundingClientRect().top ?? 0) - (cardRect?.top ?? 0);
+    const bottom = (cardRect?.bottom ?? 0) - (rows.at(-1)?.getBoundingClientRect().bottom ?? 0);
+    await expect(Math.abs(bottom - top)).toBeLessThanOrEqual(2);
+  },
+};

package/src/cards/GitHubCard.tsx

@@ -0,0 +1,93 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import type * as AppSurface from '@dxos/app-toolkit/AppSurface';
+import * as Card from '@dxos/react-ui/Card';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Layout from '@dxos/react-ui/Layout';
+import * as Tag from '@dxos/react-ui/Tag';
+import { type Issue, type PullRequest, type Repo } from '@dxos/types';
+
+import { meta } from '#meta';
+
+type Subject = Repo.Repo | Issue.Issue | PullRequest.PullRequest;
+
+/**
+ * What the card reads off any of the three types: each field is present on some of them and
+ * optional here, so one render path shows whatever the subject carries.
+ */
+type Fields = {
+  owner: string;
+  number?: number;
+  state?: PullRequest.State;
+  author?: string;
+  additions?: number;
+  deletions?: number;
+  defaultBranch?: string;
+  description?: string;
+  url?: string;
+};
+
+const stateHue: Record<PullRequest.State, Tag.TagHue> = {
+  open: 'green',
+  closed: 'red',
+  merged: 'purple',
+  draft: 'neutral',
+};
+
+/**
+ * Card content for a repository, pull request or issue: reference, state or branch, author, diff size, description and
+ * the link out. Each row leads with an icon in the card's start rail, so the text lines up with the title.
+ */
+export const GitHubCard = ({ subject }: AppSurface.ObjectCardProps<Subject>) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const { owner, number, state, author, additions, deletions, defaultBranch, description, url }: Fields = subject;
+  const name = 'name' in subject ? subject.name : subject.repo;
+
+  return (
+    <Card.Body>
+      <Card.Row
+        icon='ph--github-logo--regular'
+        trailing={
+          state ? (
+            <Tag.Tag hue={stateHue[state]}>{state}</Tag.Tag>
+          ) : defaultBranch ? (
+            <Tag.Tag hue='neutral'>{defaultBranch}</Tag.Tag>
+          ) : undefined
+        }
+      >
+        <Card.Text variant='muted'>{[`${owner}/${name}`, number].filter(Boolean).join('#')}</Card.Text>
+      </Card.Row>
+      {author && (
+        <Card.Row icon='ph--user--regular'>
+          <Card.Text variant='muted'>{author}</Card.Text>
+        </Card.Row>
+      )}
+      {(additions !== undefined || deletions !== undefined) && (
+        <Card.Row icon='ph--plus-minus--regular'>
+          <Layout.Flex gap='sm' align='center'>
+            {additions !== undefined && <span className='text-green-500'>+{additions}</span>}
+            {deletions !== undefined && <span className='text-red-500'>−{deletions}</span>}
+          </Layout.Flex>
+        </Card.Row>
+      )}
+      {description && (
+        <Card.Row icon='ph--text-align-left--regular'>
+          <Card.Text lines={3} variant='muted'>
+            {description}
+          </Card.Text>
+        </Card.Row>
+      )}
+      {url && (
+        <Card.Row icon='ph--arrow-square-out--regular'>
+          <a className='dx-link-accent' href={url} target='_blank' rel='noopener noreferrer'>
+            {t('open-on-github.label')}
+          </a>
+        </Card.Row>
+      )}
+    </Card.Body>
+  );
+};

package/src/cards/PullRequestCard.tsx

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import type * as AppSurface from '@dxos/app-toolkit/AppSurface';
+import { useObject } from '@dxos/echo-react';
+import { type PullRequest } from '@dxos/types';
+
+import { useSyncPullRequest } from '../hooks/index.ts';
+import { GitHubCard } from './GitHubCard.tsx';
+
+/**
+ * A pull request's card, re-synced from GitHub whenever it is shown: the card is often where a stale
+ * pull request is first read, e.g. in a task list's popover.
+ */
+export const PullRequestCard = ({ role, subject }: AppSurface.ObjectCardProps<PullRequest.PullRequest>) => {
+  // Subscribed so the fields the sync writes back re-render the card.
+  useObject(subject);
+  useSyncPullRequest(subject);
+  return <GitHubCard role={role} subject={subject} />;
+};

package/src/cards/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './GitHubCard.tsx';
+export * from './PullRequestCard.tsx';

package/src/components/CommentComposer/CommentComposer.tsx

@@ -0,0 +1,109 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type KeyboardEvent, type RefObject, useCallback } from 'react';
+
+import * as Button from '@dxos/react-ui/Button';
+import * as Field from '@dxos/react-ui/Field';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Input from '@dxos/react-ui/Input';
+import * as Layout from '@dxos/react-ui/Layout';
+import * as Popover from '@dxos/react-ui/Popover';
+import * as VirtualAnchor from '@dxos/react-ui/VirtualAnchor';
+import { type DiffLineTarget } from '@dxos/ui-editor';
+
+import { meta } from '#meta';
+
+export type CommentComposerProps = {
+  value: string;
+  busy?: boolean;
+  /** The diff line the comment is addressed to, named above the field; absent for a pull request comment. */
+  target?: DiffLineTarget;
+  onValueChange: (value: string) => void;
+  onSubmit: () => void;
+  onCancel: () => void;
+};
+
+/**
+ * The comment field, its target and its buttons — rendered as a band under the pull request header
+ * when the comment is about the pull request, and inside {@link LineCommentPopover} when it is
+ * about one line of a diff.
+ */
+export const CommentComposer = ({ value, busy, target, onValueChange, onSubmit, onCancel }: CommentComposerProps) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+
+  // Cmd/Ctrl+Enter submits, matching GitHub's own comment form.
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>) => {
+      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        if (!busy && value.trim()) {
+          onSubmit();
+        }
+      }
+    },
+    [busy, value, onSubmit],
+  );
+
+  return (
+    <>
+      {target && (
+        <span className='text-sm text-fg-muted'>
+          {t('comment-line.label', { file: target.file, line: target.line })}
+        </span>
+      )}
+      <Field.Root>
+        <Input.Textarea
+          autoFocus
+          rows={4}
+          placeholder={t('comment-placeholder.label')}
+          value={value}
+          onChange={(event) => onValueChange(event.target.value)}
+          onKeyDown={handleKeyDown}
+        />
+      </Field.Root>
+      <Layout.Flex justify='end' gap='sm'>
+        <Button.Root onClick={onCancel}>{t('comment-cancel.label')}</Button.Root>
+        <Button.Root variant='primary' disabled={busy || !value.trim()} onClick={onSubmit}>
+          {t('comment-submit.label')}
+        </Button.Root>
+      </Layout.Flex>
+    </>
+  );
+};
+
+/** The composer as a band under the toolbar, for a comment on the pull request as a whole. */
+export const CommentBand = (props: CommentComposerProps) => (
+  <Layout.Flex column gap='sm' classNames='p-3 border-b border-separator'>
+    <CommentComposer {...props} />
+  </Layout.Flex>
+);
+
+export type LineCommentPopoverProps = CommentComposerProps & {
+  open: boolean;
+  /** The diff line's comment button, which CodeMirror owns; the popover is positioned at it. */
+  anchorRef: RefObject<HTMLElement | null>;
+};
+
+/**
+ * The composer floated at the diff line it addresses, so the reader reads the comment against the
+ * code it is about rather than against a band at the other end of the document.
+ */
+export const LineCommentPopover = ({ open, anchorRef, ...props }: LineCommentPopoverProps) => (
+  <Popover.Root
+    open={open}
+    onOpenChange={({ open: next }) => {
+      if (!next) {
+        props.onCancel();
+      }
+    }}
+    positioning={{ ...VirtualAnchor.virtualAnchor(anchorRef), placement: 'bottom-start' }}
+  >
+    <Popover.Content classNames='w-[28rem] max-w-[90cqi]'>
+      <Popover.Body classNames='flex flex-col gap-2 p-2'>
+        <CommentComposer {...props} />
+      </Popover.Body>
+    </Popover.Content>
+  </Popover.Root>
+);

package/src/components/CommentComposer/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './CommentComposer.tsx';

package/src/components/PullRequestFiles/DiffStat.tsx

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+export type DiffStatProps = { added: number; removed: number };
+
+/** `+12 -3`, coloured as the diff gutters are, with a zero count left out. */
+export const DiffStat = ({ added, removed }: DiffStatProps) => (
+  <span className='flex items-center gap-1 ps-2 text-xs tabular-nums whitespace-nowrap'>
+    {added > 0 && <span className='text-(--color-cm-diff-add-gutter)'>+{added}</span>}
+    {removed > 0 && <span className='text-(--color-cm-diff-remove-gutter)'>-{removed}</span>}
+  </span>
+);

package/src/components/PullRequestFiles/FileTree.tsx

@@ -0,0 +1,102 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { Tree, type TreeNode, type TreeSelectEvent, createStaticTreeModel } from '@dxos/react-ui-list';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Input from '@dxos/react-ui/Input';
+
+import { meta } from '#meta';
+
+import { DiffStat } from './DiffStat.tsx';
+import { type FileNode } from './files.ts';
+
+export type FileTreeProps = {
+  root: FileNode;
+  /** Path of the file on screen. */
+  selected?: string;
+  /** Paths of the files the reader has checked off. */
+  reviewed: ReadonlySet<string>;
+  onSelect: (path: string) => void;
+  onReviewedChange: (path: string, reviewed: boolean) => void;
+};
+
+/**
+ * The changed files as a tree: a checkbox per file to mark it reviewed, its change counts at the
+ * trailing edge, and the file on screen as the current row.
+ */
+export const FileTree = ({ root, selected, reviewed, onSelect, onReviewedChange }: FileTreeProps) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  // The model is rebuilt whenever the selection moves, so the reader's collapses live outside it.
+  const [closed, setClosed] = useState<ReadonlySet<string>>(() => new Set());
+
+  const model = useMemo(
+    () =>
+      createStaticTreeModel<FileNode>(root, {
+        getChildren: (node) => node.children,
+        // `count` off: the counts that matter here are the change counts in the trailing column.
+        getProps: (node) => ({ label: node.name, count: undefined, testId: 'pull-request.files.row' }),
+        isOpen: (node) => !closed.has(node.id),
+        isCurrent: (node) => node.file !== undefined && node.path === selected,
+      }),
+    [root, selected, closed],
+  );
+
+  const handleOpenChange = useCallback(
+    ({ item, open }: { item: FileNode; open: boolean }) =>
+      setClosed((previous) => {
+        const next = new Set(previous);
+        if (open) {
+          next.delete(item.id);
+        } else {
+          next.add(item.id);
+        }
+        return next;
+      }),
+    [],
+  );
+
+  const handleSelect = useCallback(
+    ({ item }: TreeSelectEvent<FileNode>) => {
+      if (item.file) {
+        onSelect(item.path);
+      }
+    },
+    [onSelect],
+  );
+
+  const renderRow = useCallback(
+    (node: TreeNode<FileNode>) => {
+      const item = node.item;
+      return (
+        <Tree.Item node={node}>
+          <Tree.ItemIndicator />
+          <Tree.ItemIcon icon={item?.file ? undefined : 'ph--folder--regular'}>
+            {item?.file && (
+              <Input.Checkbox
+                checked={reviewed.has(item.path)}
+                onCheckedChange={({ checked }) => onReviewedChange(item.path, checked === true)}
+                // Checking a file off is not a request to open it.
+                onClick={(event) => event.stopPropagation()}
+                aria-label={t('file-reviewed.label')}
+                data-testid='pull-request.files.reviewed'
+              />
+            )}
+          </Tree.ItemIcon>
+          <Tree.ItemText />
+          {item && <DiffStat added={item.added} removed={item.removed} />}
+        </Tree.Item>
+      );
+    },
+    [reviewed, onReviewedChange, t],
+  );
+
+  return (
+    <Tree.Root id={root.id} model={model} size='sm' onOpenChange={handleOpenChange} onSelect={handleSelect}>
+      <Tree.Label srOnly>{t('files-tree.label')}</Tree.Label>
+      <Tree.Content>{renderRow}</Tree.Content>
+    </Tree.Root>
+  );
+};

package/src/components/PullRequestFiles/PullRequestFiles.tsx

@@ -0,0 +1,87 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import * as Field from '@dxos/react-ui/Field';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Layout from '@dxos/react-ui/Layout';
+import * as ScrollArea from '@dxos/react-ui/ScrollArea';
+import * as Status from '@dxos/react-ui/Status';
+import { type DiffLineTarget } from '@dxos/ui-editor';
+
+import { meta } from '#meta';
+
+import { type PatchFile } from '../../walkthrough/patch.ts';
+import { WalkthroughView } from '../WalkthroughView/index.ts';
+import { type FileNode, diffFence } from './files.ts';
+import { FileTree } from './FileTree.tsx';
+
+export type PullRequestFilesProps = {
+  /** Undefined while the diff is loading. */
+  tree?: FileNode;
+  /** The file on screen. */
+  file?: PatchFile;
+  reviewed: ReadonlySet<string>;
+  total: number;
+  /** Shown in place of the files when the diff could not be read. */
+  error?: string;
+  onSelect: (path: string) => void;
+  onReviewedChange: (path: string, reviewed: boolean) => void;
+  onLineComment?: (target: DiffLineTarget, anchor: HTMLElement) => void;
+};
+
+/**
+ * Every changed file, one at a time: the file's diff rendered as a walkthrough chunk, beside a rail
+ * listing the changed files as a tree the reader checks off as they go.
+ */
+export const PullRequestFiles = ({
+  tree,
+  file,
+  reviewed,
+  total,
+  error,
+  onSelect,
+  onReviewedChange,
+  onLineComment,
+}: PullRequestFilesProps) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const fence = useMemo(() => (file && file.hunks.length > 0 ? diffFence(file) : undefined), [file]);
+
+  if (error) {
+    return (
+      <Status.Empty icon='ph--warning--regular' classNames='dx-expand'>
+        {error}
+      </Status.Empty>
+    );
+  }
+  if (!tree) {
+    return <Status.Empty classNames='dx-expand'>{t('files-loading.message')}</Status.Empty>;
+  }
+
+  return (
+    <Layout.Grid grow cols={['fill', '18rem']} data-testid='pull-request.files'>
+      {fence ? (
+        // Keyed by file so the next file opens at its top rather than at the previous one's scroll.
+        <WalkthroughView key={file?.path} value={fence} onLineComment={onLineComment} />
+      ) : (
+        <Status.Empty classNames='dx-expand'>{t(file ? 'file-no-diff.message' : 'no-files.message')}</Status.Empty>
+      )}
+      <ScrollArea.Root classNames='border-s border-separator-subtle'>
+        <ScrollArea.Viewport classNames='p-2'>
+          <Field.Root>
+            <Field.Label classNames='px-2'>{t('files-reviewed.label', { reviewed: reviewed.size, total })}</Field.Label>
+          </Field.Root>
+          <FileTree
+            root={tree}
+            selected={file?.path}
+            reviewed={reviewed}
+            onSelect={onSelect}
+            onReviewedChange={onReviewedChange}
+          />
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    </Layout.Grid>
+  );
+};