mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-10 20:50:08 +02:00
## Thinking Path > - Paperclip is the open source control plane people use to coordinate AI agents, issues, approvals, comments, and work products. > - The involved subsystem is issue context: markdown links, issue properties, related work, lists, filters, inbox/sidebar status, and plugin-provided external context. > - The gap is that URLs to external systems currently remain mostly plain links, so humans and agents must manually open them to understand status, identity, and liveness. > - This matters because external work objects such as GitHub issues and pull requests are part of the operational state of a Paperclip company. > - The implementation keeps core provider-neutral: shared contracts, storage, sync, routes, and UI surfaces live in core while providers can contribute detection and status resolution. > - This pull request adds the external object reference foundation, GitHub provider support, issue-surface rendering, filters, sidebar/list/inbox signals, and test/story coverage. > - The benefit is that linked external work becomes inspectable Paperclip context without hardcoding every provider directly into the UI. ## Linked Issues or Issue Description No public GitHub issue exists for this work. Feature request: - Problem: URLs in Paperclip issues, comments, documents, and related surfaces do not expose provider status or object identity inline. - Proposed behavior: detect supported external object URLs, persist normalized references, refresh provider status, and render concise status-aware links across issue surfaces. - Users affected: board users, agents, and maintainers who triage issues containing external work links. - Acceptance: external object references are company-scoped, provider-extensible, visible in key issue surfaces, filterable where relevant, and covered by focused shared/server/UI tests. Related PR search: - No open duplicate PRs found for `external object references`. - Closed related prior attempt: #4556. ## What Changed - Added shared external-object contracts, validators, status/liveness helpers, and plugin protocol declarations. - Added database schema and additive migrations for external objects, source mentions, and display metadata. - Added server services/routes for detecting, syncing, summarizing, refreshing, and resolving external objects across issues, documents, comments, projects, and plugins. - Added a GitHub external-object provider plus plugin SDK authoring docs. - Wired UI presentation across markdown links, comments, issue chat, documents, properties, related work, issue rows, filters, inbox/sidebar badges, and Storybook stories. - Rebasing cleanup: moved the branch onto current `master`, repaired stale worktree provision config, hardened environment-sensitive tests/mocks, and removed committed screenshot artifacts from the PR branch to keep the reviewable file set below tool limits. ## Verification - `pnpm exec vitest run packages/shared/src/external-objects.test.ts server/src/__tests__/external-object-routes.test.ts server/src/__tests__/external-objects-service.test.ts ui/src/components/ExternalObjectPill.test.tsx ui/src/lib/external-objects.test.ts` passed after rebasing: 5 files, 56 tests. - Historical branch verification before this PR creation included `pnpm test:run`, `pnpm -r typecheck`, and `pnpm build`; this PR body does not claim those were rerun after the final rebase. ## Risks - Medium: this adds a new cross-surface sync path on issue/document/comment writes. The implementation uses safe sync wrappers so external-object failures warn instead of blocking core mutations. - Medium: the migrations introduce new tables and indexes. They are additive and company-scoped. - Medium: provider-specific URL parsing can miss or misclassify edge cases. Shared canonicalization tests and provider tests cover current GitHub shapes. - Low: UI badge/filter behavior could add visual noise for object-heavy issues; component tests and Storybook stories cover the intended surfaces. > Roadmap checked: `ROADMAP.md` references the plugin system as the current extension path and does not list a duplicate core feature. Related long-range docs discuss external references, work products, preview URLs, and plugin extension points; this PR implements the scoped external-object reference foundation. ## Model Used OpenAI Codex, GPT-5 coding-agent runtime, with shell and GitHub CLI tool use. Reasoning mode: medium. Exact deployed runtime model ID and context window were not exposed in the environment. ## 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
115 lines
3.8 KiB
TypeScript
115 lines
3.8 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import { act } from "react";
|
|
import type { ReactNode } from "react";
|
|
import { createRoot } from "react-dom/client";
|
|
import { MemoryRouter } from "react-router-dom";
|
|
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
|
import type { Approval } from "@paperclipai/shared";
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import { ThemeProvider } from "../context/ThemeContext";
|
|
import { CommentThread } from "./CommentThread";
|
|
|
|
vi.mock("./MarkdownEditor", () => ({
|
|
MarkdownEditor: () => null,
|
|
}));
|
|
|
|
vi.mock("./InlineEntitySelector", () => ({
|
|
InlineEntitySelector: () => null,
|
|
}));
|
|
|
|
vi.mock("./ApprovalCard", () => ({
|
|
ApprovalCard: ({ approval }: { approval: Approval }) => <div>{approval.type}</div>,
|
|
}));
|
|
|
|
vi.mock("@/plugins/slots", () => ({
|
|
PluginSlotOutlet: () => null,
|
|
}));
|
|
|
|
vi.mock("../api/issues", () => ({
|
|
issuesApi: { get: vi.fn() },
|
|
}));
|
|
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
|
|
|
describe("CommentThread external object decoration (integration)", () => {
|
|
let container: HTMLDivElement;
|
|
|
|
beforeEach(() => {
|
|
container = document.createElement("div");
|
|
document.body.appendChild(container);
|
|
});
|
|
|
|
afterEach(() => {
|
|
container.remove();
|
|
});
|
|
|
|
it("decorates a resolved URL and leaves an unknown URL unchanged when rendered through the real MarkdownBody", () => {
|
|
const queryClient = new QueryClient({
|
|
defaultOptions: { queries: { retry: false } },
|
|
});
|
|
const root = createRoot(container);
|
|
|
|
act(() => {
|
|
root.render(
|
|
<QueryClientProvider client={queryClient}>
|
|
<ThemeProvider>
|
|
<MemoryRouter>
|
|
<CommentThread
|
|
comments={[{
|
|
id: "comment-mixed",
|
|
companyId: "company-1",
|
|
issueId: "issue-1",
|
|
authorAgentId: null,
|
|
authorUserId: "user-1",
|
|
authorType: "user",
|
|
presentation: null,
|
|
metadata: null,
|
|
body: [
|
|
"Tracked: https://github.com/example/repo/pull/77",
|
|
"Untracked: https://elsewhere.example.com/page",
|
|
].join("\n\n"),
|
|
createdAt: new Date("2026-04-24T12:00:00.000Z"),
|
|
updatedAt: new Date("2026-04-24T12:00:00.000Z"),
|
|
}]}
|
|
externalReferences={{
|
|
"https://github.com/example/repo/pull/77": {
|
|
providerKey: "github",
|
|
objectType: "pull_request",
|
|
statusCategory: "open",
|
|
liveness: "fresh",
|
|
statusLabel: "Open",
|
|
displayTitle: "PR #77",
|
|
},
|
|
}}
|
|
onAdd={async () => {}}
|
|
/>
|
|
</MemoryRouter>
|
|
</ThemeProvider>
|
|
</QueryClientProvider>,
|
|
);
|
|
});
|
|
|
|
const resolvedLink = container.querySelector(
|
|
'a[href="https://github.com/example/repo/pull/77"]',
|
|
);
|
|
expect(resolvedLink, "resolved URL should be wrapped by the external-link decorator").not.toBeNull();
|
|
expect(resolvedLink?.getAttribute("data-external-link")).toBe("resolved");
|
|
expect(resolvedLink?.getAttribute("data-external-status")).toBe("open");
|
|
expect(resolvedLink?.classList.contains("paperclip-markdown-external-ref")).toBe(true);
|
|
|
|
const unknownLink = container.querySelector(
|
|
'a[href="https://elsewhere.example.com/page"]',
|
|
);
|
|
expect(unknownLink, "unknown URL should still render as a plain link").not.toBeNull();
|
|
expect(unknownLink?.getAttribute("data-external-link")).toBeNull();
|
|
expect(unknownLink?.classList.contains("paperclip-markdown-external-ref")).toBe(false);
|
|
|
|
act(() => {
|
|
root.unmount();
|
|
});
|
|
queryClient.clear();
|
|
});
|
|
});
|