@dxos/plugin-github 0.7.4 → 0.14.0

package/src/plugin.test.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as AppActivationEvents from '@dxos/app-toolkit/AppActivationEvents';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as ClientPlugin from '@dxos/plugin-client/ClientPlugin';
+import * as ConnectorPlugin from '@dxos/plugin-connector/ConnectorPlugin';
+import * as Harness from '@dxos/plugin-testing/Harness';
+
+import { meta } from '#meta';
+import { GitHubPlugin } from '#plugin';
+import { GitHubSkill } from '#skills';
+
+const moduleId = (name: string) => `${meta.profile.key}.module.${name}`;
+
+describe('GitHubPlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    await using harness = await Harness.createComposerTestApp({
+      plugins: [ClientPlugin.make({}), ConnectorPlugin.make(), GitHubPlugin()],
+    });
+
+    // The harness fires every plugin's start event after startup, so both start-gated modules are active.
+    expect(harness.manager.getActive()).toEqual(
+      expect.arrayContaining([moduleId('GitHubConnector'), moduleId('OperationHandler')]),
+    );
+  }, 30_000);
+
+  test('contributes the GitHub skill when the assistant starts', async ({ expect }) => {
+    await using harness = await Harness.createComposerTestApp({
+      plugins: [ClientPlugin.make({}), ConnectorPlugin.make(), GitHubPlugin()],
+    });
+
+    await harness.fire(AppActivationEvents.AssistantStart);
+    const definition = harness.getAll(AppCapabilities.SkillDefinition).find(({ key }) => key === GitHubSkill.key);
+    expect(definition?.make().tools).toHaveLength(GitHubSkill.operations.length);
+  }, 30_000);
+});

package/src/plugin.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+
+import {
+  AppGraphBuilder,
+  Connector,
+  LinkResolver,
+  MarkdownExtension,
+  OperationHandler,
+  PageActionProvider,
+  PluginAsset,
+  ReactSurface,
+  Schema,
+  SkillDefinition,
+  Translations,
+} from '#capabilities';
+import { meta } from '#meta';
+
+export const GitHubPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule(AppGraphBuilder),
+  Plugin.addModule(Connector),
+  Plugin.addModule(LinkResolver),
+  Plugin.addModule(MarkdownExtension),
+  Plugin.addModule(OperationHandler),
+  Plugin.addModule(PageActionProvider),
+  Plugin.addModule(PluginAsset),
+  Plugin.addModule(ReactSurface),
+  Plugin.addModule(Schema),
+  Plugin.addModule(SkillDefinition),
+  Plugin.addModule(Translations),
+  Plugin.make,
+);
+
+export default GitHubPlugin;

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

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { parseArtifactLink, parsePullRequestBody } from './pull-request-body.ts';
+import { PULL_REQUEST_13348_BODY } from './testing/pull-request-13348.ts';
+
+const BASE = 'https://pub-39066a86073446d7b77b1c157b660bb5.r2.dev/demos/2026-09-23-artifact';
+
+describe('parsePullRequestBody', () => {
+  test('a real body: footers out of the prose, into fields', ({ expect }) => {
+    const { markdown, claudeCode, previewUrl, artifacts } = parsePullRequestBody(PULL_REQUEST_13348_BODY);
+    expect(claudeCode).toEqual({ sessionUrl: 'https://claude.ai/code/session_016GM9fXXzbrr6JGNeeQBCmj' });
+    expect(previewUrl).toEqual('https://pr-13348-composer-dev.dxos.workers.dev');
+    expect(markdown).not.toContain('Generated with');
+    expect(markdown).not.toContain('Generated by');
+    expect(markdown).not.toContain('claude.ai/code');
+    expect(markdown).not.toContain('Composer preview');
+    expect(markdown).not.toContain('composer-preview');
+    expect(markdown.endsWith('`DescriptionLinks` still passes.')).toBe(true);
+    expect(artifacts).toEqual([
+      { url: `${BASE}/pr-pill-hover-card.webm`, kind: 'video', name: 'pr-pill-hover-card.webm' },
+      { url: `${BASE}/before.png`, kind: 'image', name: 'before.png', label: 'before' },
+      { url: `${BASE}/after.png`, kind: 'image', name: 'after.png', label: 'after' },
+    ]);
+  });
+
+  test('a body with no footers is left as written', ({ expect }) => {
+    const body = 'Fixes the thing.\n\n---\n\nMore.';
+    expect(parsePullRequestBody(body)).toEqual({ markdown: body, artifacts: [] });
+  });
+
+  test('the bare preview line, without the CI block', ({ expect }) => {
+    const { markdown, previewUrl, claudeCode } = parsePullRequestBody(
+      'Body.\n\n🤖 Generated with Claude Code\n\n🚀 Composer preview: https://pr-1-composer-dev.dxos.workers.dev\n',
+    );
+    expect(markdown).toEqual('Body.');
+    expect(previewUrl).toEqual('https://pr-1-composer-dev.dxos.workers.dev');
+    expect(claudeCode).toEqual({});
+  });
+
+  test('an artifact linked twice is listed once', ({ expect }) => {
+    const { artifacts } = parsePullRequestBody(`[demo](${BASE}/a.webm) and again ${BASE}/a.webm`);
+    expect(artifacts).toHaveLength(1);
+  });
+
+  test('handles an empty body', ({ expect }) => {
+    expect(parsePullRequestBody(undefined)).toEqual({ markdown: '', artifacts: [] });
+  });
+});
+
+describe('parseArtifactLink', () => {
+  test('only the artifacts bucket', ({ expect }) => {
+    expect(parseArtifactLink(`${BASE}/clip.MP4`)?.kind).toEqual('video');
+    expect(parseArtifactLink(`${BASE}/logs.ndjson`)?.kind).toEqual('file');
+    expect(parseArtifactLink('https://example.com/clip.webm')).toBeUndefined();
+    expect(parseArtifactLink('not a url')).toBeUndefined();
+  });
+});

package/src/pull-request-body.ts

@@ -0,0 +1,144 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/** Public host of the `agent-artifacts` R2 bucket that demo videos and screenshots are linked from. */
+export const ARTIFACTS_HOST = 'pub-39066a86073446d7b77b1c157b660bb5.r2.dev';
+
+export type ArtifactKind = 'video' | 'image' | 'file';
+
+/** A file in the artifacts bucket that a pull request body links to. */
+export type ArtifactLink = {
+  url: string;
+  kind: ArtifactKind;
+  /** The file name, the last path segment. */
+  name: string;
+  /** The link's own text, when it was written as `[label](url)` rather than bare. */
+  label?: string;
+};
+
+/** What a pull request body says beyond its prose: the footers the harness and CI append, and the media it links. */
+export type PullRequestBody = {
+  /** The prose, with the footers taken out. */
+  markdown: string;
+  /** Present when the body carries the Claude Code footer. */
+  claudeCode?: {
+    /** The session that wrote the pull request. */
+    sessionUrl?: string;
+  };
+  /** The Composer deployment built from the pull request's head. */
+  previewUrl?: string;
+  /** Artifacts in first-mention order, each once. */
+  artifacts: ArtifactLink[];
+};
+
+const VIDEO_EXTENSIONS = ['webm', 'mp4', 'mov', 'm4v', 'ogv'];
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'avif'];
+
+/** The artifact a URL names, or undefined when it is not in the artifacts bucket. */
+export const parseArtifactLink = (url: string): Omit<ArtifactLink, 'label'> | undefined => {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return undefined;
+  }
+  if (parsed.protocol !== 'https:' || parsed.hostname !== ARTIFACTS_HOST) {
+    return undefined;
+  }
+  const segment = parsed.pathname.split('/').at(-1) ?? '';
+  if (!segment) {
+    return undefined;
+  }
+  const name = safeDecode(segment);
+  const extension = name.split('.').at(-1)?.toLowerCase() ?? '';
+  const kind: ArtifactKind = VIDEO_EXTENSIONS.includes(extension)
+    ? 'video'
+    : IMAGE_EXTENSIONS.includes(extension)
+      ? 'image'
+      : 'file';
+  return { url, kind, name };
+};
+
+const CLAUDE_SESSION = /https:\/\/claude\.ai\/code\/session_[A-Za-z0-9]+/;
+const PREVIEW_BLOCK = /<!--\s*composer-preview:begin\s*-->([\s\S]*?)<!--\s*composer-preview:end\s*-->/;
+const PREVIEW_LINE = /^\s*🚀\s*Composer preview:\s*(https?:\/\/\S+)\s*$/m;
+// Each footer line is removed whole; they are recognised by their text, not their position.
+const FOOTER_LINES: RegExp[] = [
+  /^\s*🤖\s*Generated with \[?Claude Code\]?(\([^)]*\))?\s*$/,
+  /^\s*_?Generated by \[Claude Code\]\([^)]*\)_?\s*$/,
+  new RegExp(`^\\s*<?${CLAUDE_SESSION.source}>?\\s*$`),
+];
+// `[label](url)` first so a labelled link is not also counted bare.
+const MARKDOWN_LINK = /!?\[([^\]]*)\]\((https?:\/\/[^\s)]+)\)/g;
+const BARE_URL = /https?:\/\/[^\s)<>\]|]+/g;
+
+/**
+ * Splits a pull request body into its prose and what the footers and links say.
+ *
+ * The footers are the harness's (`🤖 Generated with Claude Code` and the session URL) and CI's
+ * (the Composer preview block); the article shows them as cards, so they are taken out of the prose
+ * rather than rendered twice.
+ */
+export const parsePullRequestBody = (body: string | undefined): PullRequestBody => {
+  let text = (body ?? '').replace(/\r\n/g, '\n');
+
+  const sessionUrl = text.match(CLAUDE_SESSION)?.[0];
+  const hasClaudeFooter = FOOTER_LINES.slice(0, 2).some((pattern) =>
+    text.split('\n').some((line) => pattern.test(line)),
+  );
+
+  let previewUrl: string | undefined;
+  const block = text.match(PREVIEW_BLOCK);
+  if (block) {
+    previewUrl = block[1].match(PREVIEW_LINE)?.[1];
+    text = text.replace(PREVIEW_BLOCK, '');
+  }
+  const line = text.match(PREVIEW_LINE);
+  if (line) {
+    previewUrl ??= line[1];
+    text = text.replace(PREVIEW_LINE, '');
+  }
+
+  const lines = text.split('\n').filter((line) => !FOOTER_LINES.some((pattern) => pattern.test(line)));
+  // The footers leave their `---` rules and blank lines behind at the end.
+  while (lines.length > 0 && /^\s*(---+|\*\*\*+|___+)?\s*$/.test(lines[lines.length - 1])) {
+    lines.pop();
+  }
+  const markdown = lines.join('\n').trim();
+
+  return {
+    markdown,
+    ...(hasClaudeFooter || sessionUrl ? { claudeCode: sessionUrl ? { sessionUrl } : {} } : {}),
+    ...(previewUrl ? { previewUrl } : {}),
+    artifacts: findArtifacts(markdown),
+  };
+};
+
+/** Every artifact the prose links, in order of first mention. */
+const findArtifacts = (markdown: string): ArtifactLink[] => {
+  const found = new Map<string, ArtifactLink>();
+  const add = (url: string, label?: string) => {
+    const artifact = found.has(url) ? undefined : parseArtifactLink(url);
+    if (artifact) {
+      found.set(url, { ...artifact, ...(label && label !== url ? { label } : {}) });
+    }
+  };
+  for (const [, label, url] of markdown.matchAll(MARKDOWN_LINK)) {
+    add(url, label);
+  }
+  for (const [url] of markdown.replace(MARKDOWN_LINK, '').matchAll(BARE_URL)) {
+    add(url);
+  }
+
+  // Order by where each first appears, since labelled links were collected before bare ones.
+  return [...found.values()].sort((a, b) => markdown.indexOf(a.url) - markdown.indexOf(b.url));
+};
+
+const safeDecode = (segment: string): string => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+};

package/src/pull-request.test.ts

@@ -0,0 +1,67 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { PullRequest } from '@dxos/types';
+
+import { pullRequestChanges, toPullRequestProps } from './pull-request.ts';
+import { type GitHubApi } from './services/index.ts';
+
+const reference = { owner: 'dxos', repo: 'dxos', number: 13031 };
+
+describe('toPullRequestProps', () => {
+  test('a reference with no URL of its own gets the canonical one', () => {
+    expect(toPullRequestProps(reference, pull()).url).toEqual('https://github.com/dxos/dxos/pull/13031');
+    expect(
+      toPullRequestProps(reference, pull({ html_url: 'https://github.com/dxos/dxos/pull/13031/files' })).url,
+    ).toEqual('https://github.com/dxos/dxos/pull/13031/files');
+  });
+
+  test('the four state signals fold into one', () => {
+    expect(toPullRequestProps(reference, pull()).state).toEqual('open');
+    expect(toPullRequestProps(reference, pull({ draft: true })).state).toEqual('draft');
+    expect(toPullRequestProps(reference, pull({ state: 'closed' })).state).toEqual('closed');
+    // A merged pull request is closed too, and merged is the more specific answer.
+    expect(toPullRequestProps(reference, pull({ state: 'closed', merged_at: '2026-09-01T00:00:00Z' })).state).toEqual(
+      'merged',
+    );
+  });
+});
+
+describe('pullRequestChanges', () => {
+  const stored = (description?: string) =>
+    PullRequest.make({
+      ...reference,
+      title: 'Walkthroughs',
+      state: 'open',
+      url: 'https://github.com/dxos/dxos/pull/13031',
+      description,
+    });
+
+  test('an unchanged pull request has no changes', () => {
+    expect(pullRequestChanges(stored(), pull())).toEqual({});
+  });
+
+  test('only the fields that moved on GitHub are written', () => {
+    expect(
+      pullRequestChanges(
+        stored(),
+        pull({ title: 'Walkthroughs v2', state: 'closed', merged_at: '2026-09-01T00:00:00Z' }),
+      ),
+    ).toEqual({ title: 'Walkthroughs v2', state: 'merged' });
+  });
+
+  test('a field the payload leaves out is kept, not cleared', () => {
+    expect(pullRequestChanges(stored('Stored description.'), pull({ body: null }))).toEqual({});
+  });
+});
+
+const pull = (overrides: Partial<GitHubApi.GitHubPull> = {}): GitHubApi.GitHubPull => ({
+  id: 1,
+  number: reference.number,
+  title: 'Walkthroughs',
+  state: 'open',
+  ...overrides,
+});

package/src/pull-request.ts

@@ -0,0 +1,80 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Obj } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+
+import { type PullRequestReference } from './github-link.ts';
+import { type GitHubApi } from './services/index.ts';
+
+/** Where a pull request lives on github.com, for a reference that carried no URL of its own. */
+export const pullRequestUrl = ({ owner, repo, number }: PullRequestReference): string =>
+  `https://github.com/${owner}/${repo}/pull/${number}`;
+
+/**
+ * GitHub's pull payload as the fields a local {@link PullRequest.PullRequest} holds.
+ *
+ * Shared by the link preview and the import command so the two cannot disagree about what a pull
+ * request looks like once it is in a space.
+ */
+export const toPullRequestProps = (
+  reference: PullRequestReference & { url?: string },
+  pull: GitHubApi.GitHubPull,
+): Obj.MakeProps<typeof PullRequest.PullRequest> => ({
+  owner: reference.owner,
+  repo: reference.repo,
+  number: reference.number,
+  title: pull.title,
+  url: pull.html_url ?? reference.url ?? pullRequestUrl(reference),
+  // `merged_at` as well as `merged`: the list endpoints carry only the timestamp.
+  state: pull.merged || pull.merged_at ? 'merged' : pull.draft ? 'draft' : pull.state === 'closed' ? 'closed' : 'open',
+  author: pull.user?.login,
+  description: pull.body ?? undefined,
+  baseBranch: pull.base?.ref,
+  headBranch: pull.head?.ref,
+  additions: pull.additions,
+  deletions: pull.deletions,
+  createdAt: pull.created_at ?? undefined,
+  updatedAt: pull.updated_at ?? undefined,
+});
+
+/** Fields a re-sync may overwrite; the coordinates and URL name the pull request and never drift. */
+const SYNCED_FIELDS = [
+  'title',
+  'state',
+  'author',
+  'description',
+  'baseBranch',
+  'headBranch',
+  'additions',
+  'deletions',
+  'createdAt',
+  'updatedAt',
+] as const;
+
+type SyncedField = (typeof SYNCED_FIELDS)[number];
+
+export type PullRequestChanges = Partial<Pick<PullRequest.PullRequest, SyncedField>>;
+
+/**
+ * The fields where GitHub's payload differs from the stored pull request, so a re-sync writes only
+ * what changed and an unchanged pull request costs no mutation.
+ *
+ * A field GitHub's payload leaves out is kept rather than cleared: an absent value is unknown, not empty.
+ */
+export const pullRequestChanges = (
+  pullRequest: PullRequest.PullRequest,
+  pull: GitHubApi.GitHubPull,
+): PullRequestChanges => {
+  const next = toPullRequestProps(pullRequest, pull);
+  const changes: PullRequestChanges = {};
+  const copy = <Field extends SyncedField>(field: Field) => {
+    const value = next[field];
+    if (value !== undefined && value !== pullRequest[field]) {
+      changes[field] = value;
+    }
+  };
+  SYNCED_FIELDS.forEach(copy);
+  return changes;
+};