Files
PaperClipAI/packages/shared/src/app-definitions.ts
T
DottaandClaude Opus 5.5 53fedd653b fix(connections): split GitHub Copilot into its own connector (#22238)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The Connectors catalog lets people give agents tools and AI
accounts.
> - GitHub showed repository access and GitHub Copilot authentication on
one card.
> - The card had an extra "Connect Copilot" button. Saved Copilot
accounts showed in the GitHub account list.
> - These are two different products. People must find each one by its
own name.
> - This pull request makes GitHub Copilot a separate connector. GitHub
keeps repository and MCP access only.
> - The benefit is a clear catalog. Each card opens its own setup, and
saved accounts show on the correct card.

## Linked Issues or Issue Description

**What existing behavior does this improve?**

Discovery and setup of the GitHub and GitHub Copilot connectors.

**Current behavior**

The GitHub card says "Connect GitHub repository access or authenticate
GitHub Copilot agents." It shows a "Connect Copilot" button next to its
own Connect button. Saved Copilot accounts show in the GitHub account
list. Agent connection search returns Copilot as a method of GitHub. The
Copilot setup link that search gives to agents opens the GitHub tool
setup.

**Proposed behavior**

GitHub and GitHub Copilot are two cards. GitHub says "Give agents access
to GitHub repositories, issues, and pull requests." GitHub Copilot has
its own logo and opens Copilot token setup. Saved Copilot accounts,
including accounts saved before this change, show on the GitHub Copilot
card.

**Reason and benefit**

People do not have to know that Copilot is behind the GitHub card. The
catalog names the two products. The Copilot runtime keeps the same
provider identity, token storage, grants, and model discovery.

**Additional context**

This follows the same pattern as the GitHub Code Review Bot split in
#14750. Copilot setup was added in #15705.

## What Changed

- Add a `github-copilot` app definition with the existing
`copilot-token` method. Remove that method from `github`. Restore the
GitHub description and the `developer` category.
- Add the GitHub Octicons Copilot mark (MIT license, from
`primer/octicons`) as light and dark brand assets.
- Map the `github` AI provider to the `github-copilot` catalog entry in
`aiConnectionCatalogSlug`. New Copilot accounts save under a "GitHub
Copilot" application.
- Remove the "Connect Copilot" button from the GitHub card.
- Show saved AI accounts on the card for their provider. This includes
Copilot accounts that were saved under the GitHub application. The
connection page and its reconnect link use the same rule.
- Redirect old `/apps/connect?source=github&method=copilot-token` links
to `source=github-copilot`. Keep the other query values.
- Keep the "My GitHub account" identity wording on the Copilot access
step.
- In connection search and connection requests, file AI accounts under
their catalog entry. Accept the `github` provider for the
`github-copilot` service. Copilot authentication recovery cards now open
GitHub Copilot setup, not GitHub tool setup.
- Keep older Copilot accounts and requests working. An older account
saved under the GitHub application reconnects through GitHub Copilot,
and an older Copilot draft resumes through GitHub Copilot. A recovery
request saved with the `github` service name can complete. A Copilot
request declined before this change stays declined in its continuation.
Adoption accepts the `github` provider binding for a `github-copilot`
request.
- Move the rule that finds an AI account's catalog entry
(`aiConnectionSourceSlug`) into `@paperclipai/shared`, so the UI and
server use one copy.
- Use the Copilot logo for Copilot in the AI account picker and account
details.
- Update the GitHub Copilot connection doc and the GitHub connections
Storybook story. The GitHub and GitHub Copilot setup stories open
**Change** before checking "Connect GitHub as", because that heading
sits in the collapsed access section.

## Verification

- New and updated tests fail on `master` and pass with this change:
  - `pnpm exec vitest run packages/shared/src/app-definitions.test.ts`
- `pnpm exec vitest run ui/src/pages/apps/Browse.test.tsx
ui/src/pages/apps/AppsConnect.test.tsx
ui/src/pages/apps/AppDetail.test.tsx
ui/src/pages/apps/app-connect-policy.test.ts
ui/src/pages/apps/Connections.test.tsx`
- `pnpm exec vitest run
server/src/__tests__/connection-intents-service.test.ts
server/src/__tests__/ai-connections.test.ts`
- `pnpm exec vitest run
ui/src/features/connections/ConnectionSetupFlow.oauth.test.ts`
- Older-account tests cover reconnect, draft resume, completion of a
request saved with `github`, a request declined before the split, and
Copilot adoption. Each test fails without its fix.
- The play functions of all 8 stories in
`github-connections.stories.tsx` pass when rendered with
`composeStories` in jsdom.
- Brand checks: `node scripts/check-app-brand-assets.mjs`,
`ui/src/lib/app-brand-assets.test.ts`, and
`ui/src/pages/apps/AppLogo.brand-assets.test.tsx`.
- Typecheck: `@paperclipai/shared`, `@paperclipai/ui`, and
`@paperclipai/server`.
- Manual check in `pnpm dev:once` with a local company:
1. Open Connectors and search for "GitHub". Two cards show: "GitHub" and
"GitHub Copilot". GitHub has no "Connect Copilot" button.
2. Seed one GitHub tool account and one Copilot account under the GitHub
application, as older installs have them. The GitHub tool account shows
on GitHub. The Copilot account shows on GitHub Copilot.
3. Click Connect on GitHub Copilot. The "Connect GitHub Copilot" page
opens with the Copilot logo and the token field.
4. Open `/apps/connect?source=github&method=copilot-token`. The page
redirects to `source=github-copilot`.
  5. Open GitHub setup. It offers repository access only.
  6. Check the catalog in light and dark themes.

## Risks

- Low risk. There is no database migration. Existing Copilot accounts
keep their application and stored source. The UI and connection search
group them by their AI provider.
- New Copilot accounts save under a new "GitHub Copilot" application and
record `github-copilot` as their source. Code that finds GitHub
repository identities by `sourceTemplateKey === "github"` no longer sees
new Copilot accounts. These are AI accounts, so this is the intended
separation.
- A pending Copilot recovery card from before this change keeps the
`github` service slug. The server still resolves it to GitHub Copilot,
and the card can complete.
- Search for "github" now returns two results: GitHub and GitHub
Copilot.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) through Claude Code, with tool use
(shell, file edits, test runs, and a headless browser for the manual
check).

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 08:51:36 -06:00

315 lines
11 KiB
TypeScript

import { APP_DEFINITIONS } from "./app-definitions.generated.js";
import { SELF_SERVE_MCP_CANDIDATES } from "./self-serve-mcp-research.js";
import type { AppDefinition, ConnectionMethodDef, FieldDef } from "./types/app-definition.js";
import type { ToolConnectionOwnership } from "./types/tool-access.js";
export const CONNECTABLE_APP_SLUGS = new Set([
"anthropic", "openai", "openrouter", "xai", "google", "bedrock",
"responses-api", "messages-api", "chat-completions-api", "local",
"agentmail",
"browser-use-cloud",
"daytona",
"unikraft",
"vercel",
"1password",
"cognee",
...SELF_SERVE_MCP_CANDIDATES.map((entry) => entry.slug),
"monday",
"enterpret",
"zapier",
"arcade",
"executor",
"slack",
"notion",
"paperclip-notebook",
"railway",
"aws",
"posthog",
"linear",
"google-sheets",
"context7",
"shopify",
"composio",
"gmail",
"google-drive",
"google-docs",
"google-slides",
"google-calendar",
"google-chat",
"google-people",
"google-workspace-search",
"google-workspace",
"github",
"github-code-review-bot",
"github-copilot",
"discord",
"speko",
"microsoft-teams",
"telegram",
"imessage-photon",
]);
export const CONNECTABLE_APP_DEFINITIONS = APP_DEFINITIONS.filter((app) =>
CONNECTABLE_APP_SLUGS.has(app.slug)
);
/**
* Definitions retained for existing connections and later verification, but
* intentionally withheld from the customer-facing store. Keeping visibility
* separate from recognition avoids breaking saved connections when a provider
* is pulled from Browse or reserved for a future first-party experience.
*/
export const APP_STORE_HIDDEN_SLUGS = new Set([
"beehiiv",
"brex",
"candid",
"clickup",
"coda",
"egnyte",
"embat",
"kernel",
"klaviyo",
"local-falcon",
"manufact",
"monday",
"oreilly",
"planetscale",
"razorpay",
"sanity",
"similarweb",
"ticket-tailor",
"ticktick",
"xero",
]);
export const APP_STORE_DEFINITIONS = CONNECTABLE_APP_DEFINITIONS.filter((app) =>
!APP_STORE_HIDDEN_SLUGS.has(app.slug)
);
export const DEFAULT_OWNERSHIP_AVAILABILITY: Record<ToolConnectionOwnership, boolean> = {
platform_shared: false,
platform_provisioned: false,
customer: true,
dcr: true,
};
/**
* Connector types contributed by enabled plugins (see `plugin-apps.ts`). The
* host replaces the whole set whenever it reads plugin state, and the board UI
* replaces it from each gallery response, so a disabled plugin's apps drop out
* of every lookup below. Slugs are namespaced, so this set can never shadow a
* built-in app.
*/
let pluginAppDefinitions = new Map<string, AppDefinition>();
export function setPluginAppDefinitions(definitions: readonly AppDefinition[]): void {
pluginAppDefinitions = new Map(definitions.filter((app) => app.plugin).map((app) => [app.slug, app]));
}
export function listPluginAppDefinitions(): AppDefinition[] {
return [...pluginAppDefinitions.values()];
}
export function getConnectableAppDefinition(slug: string): AppDefinition | null {
return CONNECTABLE_APP_DEFINITIONS.find((app) => app.slug === slug) ?? pluginAppDefinitions.get(slug) ?? null;
}
export function getAppStoreDefinition(slug: string): AppDefinition | null {
return APP_STORE_DEFINITIONS.find((app) => app.slug === slug) ?? pluginAppDefinitions.get(slug) ?? null;
}
export function isAppStoreVisibleSlug(slug: string | null | undefined): boolean {
return Boolean(slug && ((!APP_STORE_HIDDEN_SLUGS.has(slug) && CONNECTABLE_APP_SLUGS.has(slug)) || pluginAppDefinitions.has(slug)));
}
function wildcardPatternToRegExp(pattern: string): RegExp {
const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
return new RegExp(`^${escaped}$`, "i");
}
export function getAppDefinitionForUrl(
link: string,
definitions: readonly AppDefinition[] = CONNECTABLE_APP_DEFINITIONS,
): AppDefinition | null {
let normalized: string;
try {
normalized = new URL(link.trim()).toString();
} catch {
return null;
}
return definitions.find((app) =>
app.urlPatterns.some((pattern) => wildcardPatternToRegExp(pattern).test(normalized))
) ?? null;
}
export function getAvailableConnectionMethods(app: AppDefinition): ConnectionMethodDef[] {
const availability = app.ownershipAvailability ?? DEFAULT_OWNERSHIP_AVAILABILITY;
return app.methods.filter((method) =>
method.ownershipModes.some((ownership) => availability[ownership] !== false)
);
}
/**
* Pick the method that gives a new connection the app's useful write surface.
*
* Google Workspace publishes separate read and write capability groups. The
* read method is intentionally listed first for documentation, but treating
* array order as a product default silently created read-only connections and
* left every write action Off. Capability metadata is the durable signal; apps
* without an explicit write/draft capability retain their declared order.
*/
export function getRecommendedConnectionMethod(
methods: readonly ConnectionMethodDef[],
): ConnectionMethodDef | null {
const recommendedCapability = (candidates: readonly ConnectionMethodDef[]) => candidates.find((method) => {
const capabilityKey = method.capabilityProfile?.key;
return capabilityKey === "write" || capabilityKey === "draft";
});
const managedMethods = methods.filter((method) =>
method.oauthStrategy === "paperclip_cloud_connector"
|| method.oauthStrategy === "paperclip_id_connector"
);
// Prefer the permissions needed for agent work, then the simplest sign-in.
// Explicit read-only selections pass their own capability group here.
return recommendedCapability(managedMethods)
?? recommendedCapability(methods)
?? managedMethods[0]
?? methods[0]
?? null;
}
export function getAvailableConnectionMethod(
app: AppDefinition,
methodKey?: string | null,
): ConnectionMethodDef | null {
const methods = getAvailableConnectionMethods(app);
return methodKey
? methods.find((method) => method.key === methodKey) ?? null
: getRecommendedConnectionMethod(methods);
}
export function connectionMethodSupportsAutomaticOAuth(method: ConnectionMethodDef | null | undefined): boolean {
return method?.auth === "oauth" && (
(method.oauthStrategy === "paperclip_cloud_connector" || method.oauthStrategy === "paperclip_id_connector")
|| method.ownershipModes.includes("dcr")
);
}
export function connectionMethodAcceptsCustomerOAuthClient(method: ConnectionMethodDef | null | undefined): boolean {
return method?.auth === "oauth"
&& !method.oauthStrategy
&& method.ownershipModes.includes("customer");
}
export function connectionMethodSupportsCatalogSetup(method: ConnectionMethodDef | null | undefined): boolean {
if (!method) return false;
if (method.transport === "runtime_auth") return Boolean(method.ai);
if (method.auth === "none" || method.auth === "api_key") return true;
return connectionMethodSupportsAutomaticOAuth(method)
|| connectionMethodAcceptsCustomerOAuthClient(method);
}
export function connectionMethodRequiresConfiguration(method: ConnectionMethodDef | null | undefined): boolean {
if (!method) return false;
const visibleTenantFields = method.tenantFields?.filter((field) => !field.hidden) ?? [];
const visibleExtensionFields = method.extensionFields?.filter((field) => !field.hidden) ?? [];
return Boolean(
method.credentialFields?.length
|| visibleTenantFields.length
|| visibleExtensionFields.length
|| method.configRequirements?.atLeastOneOf?.length
|| Object.keys((method.settingsSchema?.properties as Record<string, unknown> | undefined) ?? {}).length
// "Use your own OAuth app" is an advanced alternative when DCR/CIMD is
// available, not a required setup field. Only customer-client-only methods
// must stop on the configuration screen.
|| (
connectionMethodAcceptsCustomerOAuthClient(method)
&& !connectionMethodSupportsAutomaticOAuth(method)
),
);
}
export function appSupportsCatalogSetup(app: AppDefinition | null | undefined): boolean {
return Boolean(app && getAvailableConnectionMethods(app).some(connectionMethodSupportsCatalogSetup));
}
export function isConnectableAppSlug(slug: string | null | undefined): boolean {
return Boolean(slug && (CONNECTABLE_APP_SLUGS.has(slug) || pluginAppDefinitions.has(slug)));
}
export function appSupportsAutomaticOAuth(app: AppDefinition | null | undefined): boolean {
return Boolean(app && getAvailableConnectionMethods(app).some(connectionMethodSupportsAutomaticOAuth));
}
export function appAcceptsCustomerOAuthClient(app: AppDefinition | null | undefined): boolean {
return Boolean(app && getAvailableConnectionMethods(app).some(connectionMethodAcceptsCustomerOAuthClient));
}
export function credentialConfigPath(field: FieldDef, method?: ConnectionMethodDef | null): string {
if (method?.transport === "local_stdio" && method.keyPlacement?.location === "env") return `env.${field.key}`;
return `credentials.${field.key}`;
}
/** Older credential references used bare names; current references use paths. */
export function connectionCredentialConfigPath(ref: { name: string }): string {
return /^(credentials|headers|oauth|remote)\./.test(ref.name)
? ref.name
: `credentials.${ref.name}`;
}
export function resolveConnectionMethodServerUrl(
method: ConnectionMethodDef,
configValues: Record<string, string | boolean>,
): string | null {
const template = method.defaults?.serverUrlTemplate;
if (!template) return method.defaults?.serverUrl ?? null;
let missingValue = false;
const resolved = template.replace(/\{([a-zA-Z0-9_-]+)\}/g, (_placeholder, key: string) => {
const value = configValues[key];
if (value === undefined || String(value).trim().length === 0) {
missingValue = true;
return "";
}
return encodeURIComponent(String(value).trim());
});
if (missingValue) return null;
try {
return new URL(resolved).toString();
} catch {
return null;
}
}
export function recommendedDefaultsForApp(app: AppDefinition, methodKey?: string | null): Record<string, unknown> {
// Keep the parameters in the public contract: callers resolve defaults for a
// concrete app/method. Connection finalization remains a configure-authorized,
// audited operation, and Ask first stays available as an operator-selected
// policy for any action after the connection is made.
const method = methodKey
? app.methods.find((candidate) => candidate.key === methodKey)
: null;
if (app.slug === "gmail" && method?.capabilityProfile?.key === "archive") {
return {
access: "all_agents",
askFirstRiskLevels: ["write", "destructive"],
};
}
// Enterpret's run_graph_query self-reports readOnlyHint but executes Cypher
// and has not been established as read-only. Classify it as write (server
// classifyRisk) and require Ask first so new token connections do not ship
// that action as Allowed.
if (app.slug === "enterpret") {
return {
access: "all_agents",
askFirstRiskLevels: ["write", "destructive"],
};
}
return {
access: "all_agents",
askFirstRiskLevels: [],
};
}