[codex] Add resource membership controls (#6677)

## Thinking Path

> - Paperclip orchestrates AI-agent companies through company-scoped
issues, projects, agents, and board-visible workflows.
> - The board sidebar and project list are the daily navigation surface
for that control plane.
> - Users need to keep all projects and agents accessible while hiding
resources they have intentionally left from their own sidebar.
> - That requires user-scoped resource membership state backed by
company-scoped API and database contracts.
> - The branch also needed to preserve HTTP worktree login sessions and
keep the project list easier to scan after membership grouping.
> - This pull request adds resource membership controls, sidebar leave
actions, grouped/sortable project listings, and focused tests.
> - The benefit is a cleaner personal workspace view without weakening
company-scoped access to the underlying project or agent detail pages.

## What Changed

- Added `project_memberships` and `agent_memberships` tables with
API/shared/server contracts for current-user join/leave state.
- Renumbered the membership migration to `0090_resource_memberships`
after rebasing onto current `master`, and made it idempotent for anyone
who had applied the old branch-local `0087` migration.
- Added project and agent sidebar leave actions, plus list filtering
that waits for membership state before hiding resources.
- Added grouped project listing, project sorting controls, and reserved
row subtitle height for cleaner scanning.
- Fixed HTTP auth cookie security handling so HTTP worktree sessions can
persist.
- Updated focused server and UI tests for the new membership, sidebar,
project list, and auth behavior.

## Verification

- `pnpm exec vitest run server/src/__tests__/better-auth.test.ts
server/src/__tests__/resource-memberships-routes.test.ts
ui/src/pages/Projects.test.tsx
ui/src/components/SidebarProjects.test.tsx
ui/src/components/SidebarAgents.test.tsx
ui/src/components/MembershipAction.test.tsx
ui/src/components/EntityRow.test.tsx`
- Confirmed the branch is rebased on current `origin/master`.
- Confirmed the PR diff does not include `pnpm-lock.yaml` or
`.github/workflows` changes.

## Risks

- Migration safety: low to medium. The migration now uses `IF NOT
EXISTS` / guarded constraints and is numbered after current master
migrations, but it should still get CI coverage against fresh databases.
- UI behavior: low. Left resources are hidden from sidebar only after
membership state loads; direct detail access remains available.
- Auth behavior: low. Cookie security is relaxed only for HTTP/private
local-style origins where secure cookies would prevent login
persistence.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI GPT-5 Codex coding agent, tool-enabled shell/git workflow,
context window not exposed by runtime.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

Screenshot note: no browser screenshots were captured in this heartbeat;
the UI changes are covered by focused component tests above.

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta 2026-05-25 13:12:41 -05:00 committed by GitHub
parent 60efa38f86
commit 9aea3e3d35
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
42 changed files with 20241 additions and 201 deletions

View file

@ -36,6 +36,7 @@ import { agentStatusDot, agentStatusDotDefault } from "../lib/status-colors";
import { MarkdownBody } from "../components/MarkdownBody";
import { CopyText } from "../components/CopyText";
import { EntityRow } from "../components/EntityRow";
import { MembershipAction } from "../components/MembershipAction";
import { Identity } from "../components/Identity";
import { PageSkeleton } from "../components/PageSkeleton";
import { RunButton, PauseResumeButton } from "../components/AgentActionButtons";
@ -102,6 +103,11 @@ import {
} from "@paperclipai/shared";
import { redactHomePathUserSegments, redactHomePathUserSegmentsInValue } from "@paperclipai/adapter-utils";
import { agentRouteRef } from "../lib/utils";
import {
resourceMembershipState,
useResourceMembershipMutation,
useResourceMemberships,
} from "../hooks/useResourceMemberships";
import {
applyAgentSkillSnapshot,
arraysEqual,
@ -675,6 +681,7 @@ export function AgentDetail() {
const queryClient = useQueryClient();
const navigate = useNavigate();
const [actionError, setActionError] = useState<string | null>(null);
const [dismissedLeftAgentIds, setDismissedLeftAgentIds] = useState<Set<string>>(() => new Set());
const [moreOpen, setMoreOpen] = useState(false);
const activeView = urlRunId ? "runs" as AgentDetailView : parseAgentDetailView(urlTab ?? null);
const needsDashboardData = activeView === "dashboard";
@ -705,6 +712,11 @@ export function AgentDetail() {
const canonicalAgentRef = agent ? agentRouteRef(agent) : routeAgentRef;
const agentLookupRef = agent?.id ?? routeAgentRef;
const resolvedAgentId = agent?.id ?? null;
const membershipsQuery = useResourceMemberships(resolvedCompanyId);
const membershipMutation = useResourceMembershipMutation(resolvedCompanyId);
const agentMembershipState = resolvedAgentId
? resourceMembershipState(membershipsQuery.data, "agent", resolvedAgentId)
: "joined";
const { data: runtimeState } = useQuery({
queryKey: queryKeys.agents.runtimeState(resolvedAgentId ?? routeAgentRef),
@ -984,6 +996,16 @@ export function AgentDetail() {
return () => closePanel();
}, [closePanel]);
useEffect(() => {
if (!resolvedAgentId || agentMembershipState !== "joined") return;
setDismissedLeftAgentIds((current) => {
if (!current.has(resolvedAgentId)) return current;
const next = new Set(current);
next.delete(resolvedAgentId);
return next;
});
}, [resolvedAgentId, agentMembershipState]);
useBeforeUnload(
useCallback((event) => {
if (!configDirty) return;
@ -1000,9 +1022,48 @@ export function AgentDetail() {
}
const isPendingApproval = agent.status === "pending_approval";
const showConfigActionBar = (activeView === "configuration" || activeView === "instructions") && (configDirty || configSaving);
const showLeftAgentNotice = agentMembershipState === "left" && !dismissedLeftAgentIds.has(agent.id);
const agentMembershipPending =
membershipMutation.isPending &&
membershipMutation.variables?.resourceType === "agent" &&
membershipMutation.variables.resourceId === agent.id;
return (
<div className={cn("space-y-6", isMobile && showConfigActionBar && "pb-24")}>
{showLeftAgentNotice ? (
<div className="flex items-center gap-3 border border-yellow-300/35 bg-yellow-300/10 px-3 py-2 text-sm text-yellow-100">
<p className="min-w-0 flex-1">
You left this agent. It no longer appears in your sidebar.
</p>
<MembershipAction
compact
state="left"
pending={agentMembershipPending}
pendingState={agentMembershipPending ? membershipMutation.variables?.state : null}
resourceName={agent.name}
onJoin={() => membershipMutation.mutate({
resourceType: "agent",
resourceId: agent.id,
resourceName: agent.name,
state: "joined",
})}
onLeave={() => membershipMutation.mutate({
resourceType: "agent",
resourceId: agent.id,
resourceName: agent.name,
state: "left",
})}
/>
<button
type="button"
className="h-6 w-6 shrink-0 text-yellow-100/70 hover:text-yellow-100"
aria-label="Dismiss agent membership notice"
onClick={() => setDismissedLeftAgentIds((current) => new Set(current).add(agent.id))}
>
×
</button>
</div>
) : null}
{/* Header */}
<div className="flex items-center justify-between gap-2">
<div className="flex items-center gap-3 min-w-0">

View file

@ -1,11 +1,12 @@
// @vitest-environment jsdom
import { act } from "react";
import type { ReactNode } from "react";
import { flushSync } from "react-dom";
import { createRoot } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type { Agent } from "@paperclipai/shared";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ToastProvider } from "../context/ToastContext";
import { Agents } from "./Agents";
const mockAgentsApi = vi.hoisted(() => ({
@ -17,6 +18,11 @@ const mockHeartbeatsApi = vi.hoisted(() => ({
liveRunsForCompany: vi.fn(),
}));
const mockResourceMembershipsApi = vi.hoisted(() => ({
listMine: vi.fn(),
updateAgent: vi.fn(),
}));
const mockOpenNewAgent = vi.hoisted(() => vi.fn());
const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
@ -52,6 +58,10 @@ vi.mock("../api/heartbeats", () => ({
heartbeatsApi: mockHeartbeatsApi,
}));
vi.mock("../api/resourceMemberships", () => ({
resourceMembershipsApi: mockResourceMembershipsApi,
}));
vi.mock("../adapters/adapter-display-registry", () => ({
getAdapterLabel: (type: string) => type,
}));
@ -59,6 +69,14 @@ vi.mock("../adapters/adapter-display-registry", () => ({
// eslint-disable-next-line @typescript-eslint/no-explicit-any
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
async function act(callback: () => void | Promise<void>) {
let result: void | Promise<void> = undefined;
flushSync(() => {
result = callback();
});
await result;
}
function makeAgent(overrides: Partial<Agent>): Agent {
return {
id: "agent-1",
@ -120,6 +138,17 @@ describe("Agents", () => {
},
]);
mockHeartbeatsApi.liveRunsForCompany.mockResolvedValue([]);
mockResourceMembershipsApi.listMine.mockResolvedValue({
projectMemberships: {},
agentMemberships: {},
updatedAt: null,
});
mockResourceMembershipsApi.updateAgent.mockResolvedValue({
resourceType: "agent",
resourceId: "agent-1",
state: "left",
updatedAt: new Date("2026-01-02T00:00:00Z"),
});
});
afterEach(async () => {
@ -140,7 +169,9 @@ describe("Agents", () => {
await act(async () => {
root!.render(
<QueryClientProvider client={queryClient}>
<Agents />
<ToastProvider>
<Agents />
</ToastProvider>
</QueryClientProvider>,
);
});

View file

@ -9,6 +9,7 @@ import { useBreadcrumbs } from "../context/BreadcrumbContext";
import { useSidebar } from "../context/SidebarContext";
import { queryKeys } from "../lib/queryKeys";
import { StatusBadge } from "../components/StatusBadge";
import { MembershipAction } from "../components/MembershipAction";
import { agentStatusDot, agentStatusDotDefault } from "../lib/status-colors";
import { EntityRow } from "../components/EntityRow";
import { EmptyState } from "../components/EmptyState";
@ -19,6 +20,11 @@ import { Tabs } from "@/components/ui/tabs";
import { Button } from "@/components/ui/button";
import { Bot, Plus, List, GitBranch, SlidersHorizontal } from "lucide-react";
import { AGENT_ROLE_LABELS, type Agent } from "@paperclipai/shared";
import {
resourceMembershipState,
useResourceMembershipMutation,
useResourceMemberships,
} from "../hooks/useResourceMemberships";
import { getAdapterLabel } from "../adapters/adapter-display-registry";
@ -93,6 +99,8 @@ export function Agents() {
enabled: !!selectedCompanyId,
refetchInterval: 15_000,
});
const membershipsQuery = useResourceMemberships(selectedCompanyId);
const membershipMutation = useResourceMembershipMutation(selectedCompanyId);
// Map agentId -> first live run + live run count
const liveRunByAgent = useMemo(() => {
@ -231,7 +239,11 @@ export function Agents() {
title={agent.name}
subtitle={`${roleLabels[agent.role] ?? agent.role}${agent.title ? ` - ${agent.title}` : ""}`}
to={agentUrl(agent)}
className={agent.pausedAt && tab !== "paused" ? "opacity-50" : ""}
className={cn(
"group",
agent.pausedAt && tab !== "paused" ? "opacity-50" : "",
resourceMembershipState(membershipsQuery.data, "agent", agent.id) === "left" ? "text-foreground/55" : "",
)}
leading={
<span className="relative flex h-2.5 w-2.5">
<span
@ -276,6 +288,34 @@ export function Agents() {
<StatusBadge status={agent.status} />
</span>
</div>
<MembershipAction
state={resourceMembershipState(membershipsQuery.data, "agent", agent.id)}
pending={
membershipMutation.isPending &&
membershipMutation.variables?.resourceType === "agent" &&
membershipMutation.variables.resourceId === agent.id
}
pendingState={
membershipMutation.isPending &&
membershipMutation.variables?.resourceType === "agent" &&
membershipMutation.variables.resourceId === agent.id
? membershipMutation.variables.state
: null
}
resourceName={agent.name}
onJoin={() => membershipMutation.mutate({
resourceType: "agent",
resourceId: agent.id,
resourceName: agent.name,
state: "joined",
})}
onLeave={() => membershipMutation.mutate({
resourceType: "agent",
resourceId: agent.id,
resourceName: agent.name,
state: "left",
})}
/>
</div>
}
/>
@ -294,7 +334,16 @@ export function Agents() {
{effectiveView === "org" && filteredOrg.length > 0 && (
<div className="border border-border py-1">
{filteredOrg.map((node) => (
<OrgTreeNode key={node.id} node={node} depth={0} agentMap={agentMap} liveRunByAgent={liveRunByAgent} tab={tab} />
<OrgTreeNode
key={node.id}
node={node}
depth={0}
agentMap={agentMap}
liveRunByAgent={liveRunByAgent}
tab={tab}
memberships={membershipsQuery.data}
membershipMutation={membershipMutation}
/>
))}
</div>
)}
@ -320,14 +369,22 @@ function OrgTreeNode({
agentMap,
liveRunByAgent,
tab,
memberships,
membershipMutation,
}: {
node: OrgNode;
depth: number;
agentMap: Map<string, Agent>;
liveRunByAgent: Map<string, { runId: string; liveCount: number }>;
tab: FilterTab;
memberships: ReturnType<typeof useResourceMemberships>["data"];
membershipMutation: ReturnType<typeof useResourceMembershipMutation>;
}) {
const agent = agentMap.get(node.id);
const membershipState = resourceMembershipState(memberships, "agent", node.id);
const pending = membershipMutation.isPending &&
membershipMutation.variables?.resourceType === "agent" &&
membershipMutation.variables.resourceId === node.id;
const statusColor = agentStatusDot[node.status] ?? agentStatusDotDefault;
@ -335,7 +392,11 @@ function OrgTreeNode({
<div style={{ paddingLeft: depth * 24 }}>
<Link
to={agent ? agentUrl(agent) : `/agents/${node.id}`}
className={cn("flex items-center gap-3 px-3 py-2 hover:bg-accent/30 transition-colors w-full text-left no-underline text-inherit", agent?.pausedAt && tab !== "paused" && "opacity-50")}
className={cn(
"group flex items-center gap-3 px-3 py-2 hover:bg-accent/30 transition-colors w-full text-left no-underline text-inherit",
agent?.pausedAt && tab !== "paused" && "opacity-50",
membershipState === "left" && "text-foreground/55",
)}
>
<span className="relative flex h-2.5 w-2.5 shrink-0">
<span className={`absolute inline-flex h-full w-full rounded-full ${statusColor}`} />
@ -387,12 +448,39 @@ function OrgTreeNode({
<StatusBadge status={node.status} />
</span>
</div>
<MembershipAction
state={membershipState}
pending={pending}
pendingState={pending ? membershipMutation.variables?.state : null}
resourceName={node.name}
onJoin={() => membershipMutation.mutate({
resourceType: "agent",
resourceId: node.id,
resourceName: node.name,
state: "joined",
})}
onLeave={() => membershipMutation.mutate({
resourceType: "agent",
resourceId: node.id,
resourceName: node.name,
state: "left",
})}
/>
</div>
</Link>
{node.reports && node.reports.length > 0 && (
<div className="border-l border-border/50 ml-4">
{node.reports.map((child) => (
<OrgTreeNode key={child.id} node={child} depth={depth + 1} agentMap={agentMap} liveRunByAgent={liveRunByAgent} tab={tab} />
<OrgTreeNode
key={child.id}
node={child}
depth={depth + 1}
agentMap={agentMap}
liveRunByAgent={liveRunByAgent}
tab={tab}
memberships={memberships}
membershipMutation={membershipMutation}
/>
))}
</div>
)}

View file

@ -124,6 +124,7 @@ import { InlineEditor } from "@/components/InlineEditor";
import { PageSkeleton } from "@/components/PageSkeleton";
import { Identity } from "@/components/Identity";
import { IssueReferencePill } from "@/components/IssueReferencePill";
import { MembershipAction } from "@/components/MembershipAction";
/* ------------------------------------------------------------------ */
/* Section wrapper */
@ -896,6 +897,66 @@ export function DesignGuide() {
selected
/>
</div>
<SubSection title="Membership action">
<div className="border border-border rounded-md">
<EntityRow
title="Joined resource"
subtitle="Hover or focus the row to reveal the reserved action slot."
className="group"
trailing={
<MembershipAction
state="joined"
resourceName="Joined resource"
onJoin={() => {}}
onLeave={() => {}}
/>
}
/>
<EntityRow
title="Left resource"
subtitle="Persistent action with dimmed row content."
className="group text-foreground/55"
trailing={
<MembershipAction
state="left"
resourceName="Left resource"
onJoin={() => {}}
onLeave={() => {}}
/>
}
/>
<EntityRow
title="Leaving resource"
subtitle="Disabled while the optimistic mutation is pending."
className="group text-foreground/55"
trailing={
<MembershipAction
state="left"
pending
pendingState="left"
resourceName="Leaving resource"
onJoin={() => {}}
onLeave={() => {}}
/>
}
/>
<EntityRow
title="Joining resource"
subtitle="The target state is visible immediately while the server confirms."
className="group"
trailing={
<MembershipAction
state="joined"
pending
pendingState="joined"
resourceName="Joining resource"
onJoin={() => {}}
onLeave={() => {}}
/>
}
/>
</div>
</SubSection>
</Section>
{/* ============================================================ */}

View file

@ -2,7 +2,8 @@
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type { Project } from "@paperclipai/shared";
import { act, type ReactNode } from "react";
import type { ReactNode } from "react";
import { flushSync } from "react-dom";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ProjectDetail } from "./ProjectDetail";
@ -24,6 +25,10 @@ const mockBudgetsApi = vi.hoisted(() => ({ overview: vi.fn(), upsertPolicy: vi.f
const mockExecutionWorkspacesApi = vi.hoisted(() => ({ list: vi.fn() }));
const mockInstanceSettingsApi = vi.hoisted(() => ({ getExperimental: vi.fn() }));
const mockAssetsApi = vi.hoisted(() => ({ uploadImage: vi.fn() }));
const mockResourceMembershipsApi = vi.hoisted(() => ({
listMine: vi.fn(),
updateProject: vi.fn(),
}));
const mockNavigate = vi.hoisted(() => vi.fn());
const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
const mockIssuesList = vi.hoisted(() => vi.fn());
@ -36,6 +41,7 @@ vi.mock("../api/budgets", () => ({ budgetsApi: mockBudgetsApi }));
vi.mock("../api/execution-workspaces", () => ({ executionWorkspacesApi: mockExecutionWorkspacesApi }));
vi.mock("../api/instanceSettings", () => ({ instanceSettingsApi: mockInstanceSettingsApi }));
vi.mock("../api/assets", () => ({ assetsApi: mockAssetsApi }));
vi.mock("../api/resourceMemberships", () => ({ resourceMembershipsApi: mockResourceMembershipsApi }));
vi.mock("@/lib/router", () => ({
Link: ({ children, to }: { children?: ReactNode; to: string }) => <a href={to}>{children}</a>,
@ -87,6 +93,14 @@ vi.mock("../components/IssuesList", () => ({
},
}));
async function act(callback: () => void | Promise<void>) {
let result: void | Promise<void> = undefined;
flushSync(() => {
result = callback();
});
await result;
}
function project(overrides: Partial<Project> = {}): Project {
const now = new Date("2026-05-01T00:00:00Z");
return {
@ -152,10 +166,21 @@ describe("ProjectDetail", () => {
mockBudgetsApi.overview.mockResolvedValue({ policies: [] });
mockInstanceSettingsApi.getExperimental.mockResolvedValue({ enableIsolatedWorkspaces: false });
mockExecutionWorkspacesApi.list.mockResolvedValue([]);
mockResourceMembershipsApi.listMine.mockResolvedValue({
projectMemberships: {},
agentMemberships: {},
updatedAt: null,
});
mockResourceMembershipsApi.updateProject.mockResolvedValue({
resourceType: "project",
resourceId: "project-1",
state: "left",
updatedAt: new Date("2026-05-01T00:00:00Z"),
});
});
afterEach(() => {
act(() => root?.unmount());
afterEach(async () => {
await act(() => root?.unmount());
root = null;
container.remove();
vi.clearAllMocks();

View file

@ -23,6 +23,7 @@ import { IssuesList } from "../components/IssuesList";
import { PageSkeleton } from "../components/PageSkeleton";
import { PageTabBar } from "../components/PageTabBar";
import { ProjectWorkspacesContent } from "../components/ProjectWorkspacesContent";
import { MembershipAction } from "../components/MembershipAction";
import { buildProjectWorkspaceSummaries } from "../lib/project-workspaces-tab";
import { collectLiveIssueIds } from "../lib/liveIssueIds";
import { projectRouteRef } from "../lib/utils";
@ -30,6 +31,11 @@ import { Button } from "@/components/ui/button";
import { Tabs } from "@/components/ui/tabs";
import { PluginLauncherOutlet } from "@/plugins/launchers";
import { PluginSlotMount, PluginSlotOutlet, usePluginSlots } from "@/plugins/slots";
import {
resourceMembershipState,
useResourceMembershipMutation,
useResourceMemberships,
} from "../hooks/useResourceMemberships";
/* ── Top-level tab types ── */
@ -286,6 +292,7 @@ export function ProjectDetail() {
const navigate = useNavigate();
const location = useLocation();
const [fieldSaveStates, setFieldSaveStates] = useState<Partial<Record<ProjectConfigFieldKey, ProjectFieldSaveState>>>({});
const [dismissedLeftProjectIds, setDismissedLeftProjectIds] = useState<Set<string>>(() => new Set());
const fieldSaveRequestIds = useRef<Partial<Record<ProjectConfigFieldKey, number>>>({});
const fieldSaveTimers = useRef<Partial<Record<ProjectConfigFieldKey, ReturnType<typeof setTimeout>>>>({});
const routeProjectRef = projectId ?? "";
@ -311,6 +318,11 @@ export function ProjectDetail() {
const canonicalProjectRef = project ? projectRouteRef(project) : routeProjectRef;
const projectLookupRef = project?.id ?? routeProjectRef;
const resolvedCompanyId = project?.companyId ?? selectedCompanyId;
const membershipsQuery = useResourceMemberships(resolvedCompanyId);
const membershipMutation = useResourceMembershipMutation(resolvedCompanyId);
const projectMembershipState = project?.id
? resourceMembershipState(membershipsQuery.data, "project", project.id)
: "joined";
const experimentalSettingsQuery = useQuery({
queryKey: queryKeys.instance.experimentalSettings,
queryFn: () => instanceSettingsApi.getExperimental(),
@ -476,6 +488,16 @@ export function ProjectDetail() {
return () => closePanel();
}, [closePanel]);
useEffect(() => {
if (!project?.id || projectMembershipState !== "joined") return;
setDismissedLeftProjectIds((current) => {
if (!current.has(project.id)) return current;
const next = new Set(current);
next.delete(project.id);
return next;
});
}, [project?.id, projectMembershipState]);
useEffect(() => {
return () => {
Object.values(fieldSaveTimers.current).forEach((timer) => {
@ -607,6 +629,12 @@ export function ProjectDetail() {
if (isLoading) return <PageSkeleton variant="detail" />;
if (error) return <p className="text-sm text-destructive">{error.message}</p>;
if (!project) return null;
const showLeftProjectNotice =
projectMembershipState === "left" && !dismissedLeftProjectIds.has(project.id);
const projectMembershipPending =
membershipMutation.isPending &&
membershipMutation.variables?.resourceType === "project" &&
membershipMutation.variables.resourceId === project.id;
const handleTabChange = (tab: ProjectTab) => {
// Cache the active tab per project
@ -634,6 +662,40 @@ export function ProjectDetail() {
return (
<div className="space-y-6">
{showLeftProjectNotice ? (
<div className="flex items-center gap-3 border border-yellow-300/35 bg-yellow-300/10 px-3 py-2 text-sm text-yellow-100">
<p className="min-w-0 flex-1">
You left this project. It no longer appears in your sidebar.
</p>
<MembershipAction
compact
state="left"
pending={projectMembershipPending}
pendingState={projectMembershipPending ? membershipMutation.variables?.state : null}
resourceName={project.name}
onJoin={() => membershipMutation.mutate({
resourceType: "project",
resourceId: project.id,
resourceName: project.name,
state: "joined",
})}
onLeave={() => membershipMutation.mutate({
resourceType: "project",
resourceId: project.id,
resourceName: project.name,
state: "left",
})}
/>
<button
type="button"
className="h-6 w-6 shrink-0 text-yellow-100/70 hover:text-yellow-100"
aria-label="Dismiss project membership notice"
onClick={() => setDismissedLeftProjectIds((current) => new Set(current).add(project.id))}
>
×
</button>
</div>
) : null}
<div className="flex items-start gap-3">
<div className="h-7 flex items-center">
<ColorPicker

View file

@ -1,49 +1,81 @@
// @vitest-environment jsdom
import type { ReactNode } from "react";
import { flushSync } from "react-dom";
import { createRoot } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type { Project } from "@paperclipai/shared";
import { act, type ReactNode } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { ToastProvider } from "../context/ToastContext";
import { Projects } from "./Projects";
(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
const mockProjectsApi = vi.hoisted(() => ({
list: vi.fn(),
}));
const mockResourceMembershipsApi = vi.hoisted(() => ({
listMine: vi.fn(),
updateProject: vi.fn(),
}));
const mockOpenNewProject = vi.hoisted(() => vi.fn());
const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
vi.mock("../api/projects", () => ({ projectsApi: mockProjectsApi }));
vi.mock("@/lib/router", () => ({
Link: ({ children, to }: { children?: ReactNode; to: string }) => <a href={to}>{children}</a>,
Link: ({ children, to, ...props }: { children?: ReactNode; to: string }) => (
<a href={to} {...props}>{children}</a>
),
}));
vi.mock("../context/CompanyContext", () => ({
useCompany: () => ({ selectedCompanyId: "company-1" }),
}));
vi.mock("../context/DialogContext", () => ({
useDialogActions: () => ({ openNewProject: mockOpenNewProject }),
}));
vi.mock("../context/BreadcrumbContext", () => ({
useBreadcrumbs: () => ({ setBreadcrumbs: mockSetBreadcrumbs }),
}));
function project(overrides: Partial<Project>): Project {
const now = new Date("2026-05-01T00:00:00Z");
vi.mock("../api/projects", () => ({
projectsApi: mockProjectsApi,
}));
vi.mock("../api/resourceMemberships", () => ({
resourceMembershipsApi: mockResourceMembershipsApi,
}));
(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
if (!globalThis.PointerEvent) {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
(globalThis as any).PointerEvent = MouseEvent;
}
async function act(callback: () => void | Promise<void>) {
let result: void | Promise<void> = undefined;
flushSync(() => {
result = callback();
});
await result;
}
function makeProject(overrides: Partial<Project>): Project {
return {
id: "project-1",
id: "project-a",
companyId: "company-1",
urlKey: "project-1",
urlKey: "alpha",
goalId: null,
goalIds: [],
goals: [],
name: "Project",
name: "Alpha",
description: null,
status: "in_progress",
leadAgentId: null,
targetDate: null,
color: "#14b8a6",
color: "#ef4444",
env: null,
pauseReason: null,
pausedAt: null,
@ -55,103 +87,150 @@ function project(overrides: Partial<Project>): Project {
defaultRef: null,
repoName: null,
localFolder: null,
managedFolder: "/tmp/project-1",
effectiveLocalFolder: "/tmp/project-1",
origin: "managed_checkout",
managedFolder: "/tmp/project-a",
effectiveLocalFolder: "/tmp/project-a",
origin: "local_folder",
},
workspaces: [],
primaryWorkspace: null,
managedByPlugin: null,
archivedAt: null,
createdAt: now,
updatedAt: now,
createdAt: new Date("2026-01-01T00:00:00Z"),
updatedAt: new Date("2026-01-01T00:00:00Z"),
...overrides,
};
}
async function renderProjects(container: HTMLElement) {
const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
let root: Root | null = null;
async function flushReact() {
await act(async () => {
root = createRoot(container);
root.render(
<QueryClientProvider client={queryClient}>
<Projects />
</QueryClientProvider>,
);
});
await act(async () => {
await new Promise((resolve) => setTimeout(resolve, 0));
await new Promise((resolve) => setTimeout(resolve, 0));
});
return root;
}
function projectLinkNames(container: HTMLElement): string[] {
return Array.from(container.querySelectorAll<HTMLAnchorElement>("a[href^='/projects/']")).map((link) => {
const title = link.querySelector("span.truncate");
return title?.textContent ?? "";
await Promise.resolve();
await new Promise((resolve) => window.setTimeout(resolve, 0));
});
}
describe("Projects", () => {
let root: Root | null = null;
let container: HTMLDivElement;
let root: ReturnType<typeof createRoot> | null;
let queryClient: QueryClient;
beforeEach(() => {
container = document.createElement("div");
document.body.appendChild(container);
root = null;
queryClient = new QueryClient({
defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
});
mockProjectsApi.list.mockResolvedValue([
project({
id: "project-bravo",
makeProject({
id: "project-c",
urlKey: "charlie",
name: "Charlie",
updatedAt: new Date("2026-01-10T00:00:00Z"),
}),
makeProject({
id: "project-b",
urlKey: "bravo",
name: "Bravo",
description: null,
updatedAt: new Date("2026-05-02T00:00:00Z"),
updatedAt: new Date("2026-01-05T00:00:00Z"),
}),
project({
id: "project-alpha",
makeProject({
id: "project-a",
urlKey: "alpha",
name: "Alpha",
description: "First project",
updatedAt: new Date("2026-05-01T00:00:00Z"),
}),
project({
id: "project-charlie",
urlKey: "charlie",
name: "Charlie",
description: null,
updatedAt: new Date("2026-05-03T00:00:00Z"),
updatedAt: new Date("2026-01-01T00:00:00Z"),
}),
]);
mockResourceMembershipsApi.listMine.mockResolvedValue({
projectMemberships: { "project-b": "left" },
agentMemberships: {},
updatedAt: null,
});
mockResourceMembershipsApi.updateProject.mockResolvedValue({
resourceType: "project",
resourceId: "project-b",
state: "joined",
updatedAt: new Date("2026-01-05T00:00:00Z"),
});
});
afterEach(() => {
act(() => root?.unmount());
root = null;
afterEach(async () => {
const currentRoot = root;
if (currentRoot) {
await act(async () => {
currentRoot.unmount();
});
}
queryClient.clear();
container.remove();
document.body.innerHTML = "";
vi.clearAllMocks();
});
it("sorts projects by name by default and can switch sort mode", async () => {
root = await renderProjects(container);
expect(projectLinkNames(container)).toEqual(["Alpha", "Bravo", "Charlie"]);
const select = container.querySelector("select");
expect(select).not.toBeNull();
async function renderProjects() {
const currentRoot = createRoot(container);
root = currentRoot;
await act(async () => {
select!.value = "updated";
select!.dispatchEvent(new Event("change", { bubbles: true }));
currentRoot.render(
<QueryClientProvider client={queryClient}>
<ToastProvider>
<Projects />
</ToastProvider>
</QueryClientProvider>,
);
});
await flushReact();
await flushReact();
}
expect(projectLinkNames(container)).toEqual(["Charlie", "Bravo", "Alpha"]);
async function openSortMenu() {
const trigger = container.querySelector<HTMLButtonElement>('button[title="Sort"]');
expect(trigger).not.toBeNull();
await act(async () => {
trigger?.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, button: 0 }));
trigger?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
}
async function chooseSortField(label: string) {
const item = Array.from(document.body.querySelectorAll("button"))
.find((element) => element.textContent?.includes(label));
expect(item).toBeTruthy();
await act(async () => {
item?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
});
await flushReact();
}
it("groups joined projects above left projects and defaults sorting by name", async () => {
await renderProjects();
const content = container.textContent ?? "";
expect(container.querySelector('button[title="Sort"]')?.textContent).toContain("Sort: Name");
expect(content.indexOf("My Projects")).toBeLessThan(content.indexOf("Alpha"));
expect(content.indexOf("Alpha")).toBeLessThan(content.indexOf("Charlie"));
expect(content.indexOf("Charlie")).toBeLessThan(content.indexOf("Other Projects"));
expect(content.indexOf("Other Projects")).toBeLessThan(content.indexOf("Bravo"));
expect(content).toContain("in progress");
});
it("sorts grouped projects by the selected field", async () => {
await renderProjects();
await openSortMenu();
await chooseSortField("Updated");
const content = container.textContent ?? "";
expect(content.indexOf("My Projects")).toBeLessThan(content.indexOf("Charlie"));
expect(content.indexOf("Charlie")).toBeLessThan(content.indexOf("Alpha"));
expect(content.indexOf("Alpha")).toBeLessThan(content.indexOf("Other Projects"));
});
it("reserves description line height for projects without descriptions", async () => {
root = await renderProjects(container);
await renderProjects();
const bravoLink = Array.from(container.querySelectorAll<HTMLAnchorElement>("a")).find((link) =>
link.textContent?.includes("Bravo"),

View file

@ -8,63 +8,67 @@ import { useBreadcrumbs } from "../context/BreadcrumbContext";
import { queryKeys } from "../lib/queryKeys";
import { EntityRow } from "../components/EntityRow";
import { StatusBadge } from "../components/StatusBadge";
import { MembershipAction } from "../components/MembershipAction";
import { EmptyState } from "../components/EmptyState";
import { PageSkeleton } from "../components/PageSkeleton";
import { formatDate, projectUrl } from "../lib/utils";
import {
resourceMembershipState,
useResourceMembershipMutation,
useResourceMemberships,
} from "../hooks/useResourceMemberships";
import { Button } from "@/components/ui/button";
import { ArrowUpDown, Hexagon, Plus } from "lucide-react";
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
import { ArrowUpDown, Check, Hexagon, Plus } from "lucide-react";
type ProjectSortMode = "name" | "updated" | "targetDate" | "status";
type ProjectSortField = "name" | "updated" | "created" | "targetDate";
type ProjectSortDir = "asc" | "desc";
const PROJECT_SORT_LABELS: Record<ProjectSortMode, string> = {
name: "Name",
updated: "Recently updated",
targetDate: "Target date",
status: "Status",
};
const PROJECT_SORT_OPTIONS: Array<{ field: ProjectSortField; label: string }> = [
{ field: "name", label: "Name" },
{ field: "updated", label: "Updated" },
{ field: "created", label: "Created" },
{ field: "targetDate", label: "Target date" },
];
const PROJECT_STATUS_RANK: Record<Project["status"], number> = {
in_progress: 0,
planned: 1,
backlog: 2,
completed: 3,
cancelled: 4,
};
function projectTime(project: Project, field: "createdAt" | "updatedAt"): number {
const value = project[field];
const time = value instanceof Date ? value.getTime() : new Date(value).getTime();
return Number.isFinite(time) ? time : 0;
}
function compareProjectNames(left: Project, right: Project): number {
function compareProjectNames(left: Project, right: Project) {
const nameDiff = left.name.localeCompare(right.name, undefined, { sensitivity: "base" });
return nameDiff !== 0 ? nameDiff : left.id.localeCompare(right.id);
}
function compareTargetDates(left: Project, right: Project): number {
if (!left.targetDate && !right.targetDate) return compareProjectNames(left, right);
if (!left.targetDate) return 1;
if (!right.targetDate) return -1;
const dateDiff = left.targetDate.localeCompare(right.targetDate);
return dateDiff !== 0 ? dateDiff : compareProjectNames(left, right);
function projectTime(value: Date | string | null | undefined): number | null {
if (!value) return null;
const time = new Date(value).getTime();
return Number.isFinite(time) ? time : null;
}
function sortProjects(projects: Project[], sortMode: ProjectSortMode): Project[] {
function compareOptionalTime(
left: Date | string | null | undefined,
right: Date | string | null | undefined,
sortDir: ProjectSortDir,
) {
const leftTime = projectTime(left);
const rightTime = projectTime(right);
if (leftTime === null && rightTime === null) return 0;
if (leftTime === null) return 1;
if (rightTime === null) return -1;
return sortDir === "asc" ? leftTime - rightTime : rightTime - leftTime;
}
function sortProjects(projects: Project[], sortField: ProjectSortField, sortDir: ProjectSortDir) {
return [...projects].sort((left, right) => {
if (sortMode === "updated") {
const updatedDiff = projectTime(right, "updatedAt") - projectTime(left, "updatedAt");
return updatedDiff !== 0 ? updatedDiff : compareProjectNames(left, right);
let comparison = 0;
if (sortField === "name") {
comparison = compareProjectNames(left, right);
return sortDir === "asc" ? comparison : -comparison;
}
if (sortMode === "targetDate") {
return compareTargetDates(left, right);
}
if (sortMode === "status") {
const statusDiff = PROJECT_STATUS_RANK[left.status] - PROJECT_STATUS_RANK[right.status];
return statusDiff !== 0 ? statusDiff : compareProjectNames(left, right);
}
return compareProjectNames(left, right);
if (sortField === "updated") comparison = compareOptionalTime(left.updatedAt, right.updatedAt, sortDir);
else if (sortField === "created") comparison = compareOptionalTime(left.createdAt, right.createdAt, sortDir);
else comparison = compareOptionalTime(left.targetDate, right.targetDate, sortDir);
if (comparison === 0) comparison = compareProjectNames(left, right);
return comparison;
});
}
@ -72,7 +76,8 @@ export function Projects() {
const { selectedCompanyId } = useCompany();
const { openNewProject } = useDialogActions();
const { setBreadcrumbs } = useBreadcrumbs();
const [sortMode, setSortMode] = useState<ProjectSortMode>("name");
const [sortField, setSortField] = useState<ProjectSortField>("name");
const [sortDir, setSortDir] = useState<ProjectSortDir>("asc");
useEffect(() => {
setBreadcrumbs([{ label: "Projects" }]);
@ -83,14 +88,31 @@ export function Projects() {
queryFn: () => projectsApi.list(selectedCompanyId!),
enabled: !!selectedCompanyId,
});
const membershipsQuery = useResourceMemberships(selectedCompanyId);
const membershipMutation = useResourceMembershipMutation(selectedCompanyId);
const projects = useMemo(
() => (allProjects ?? []).filter((p) => !p.archivedAt),
[allProjects],
);
const sortedProjects = useMemo(
() => sortProjects(projects, sortMode),
[projects, sortMode],
() => sortProjects(projects, sortField, sortDir),
[projects, sortDir, sortField],
);
const groupedProjects = useMemo(() => {
const groups = {
mine: [] as typeof sortedProjects,
other: [] as typeof sortedProjects,
};
for (const project of sortedProjects) {
const state = resourceMembershipState(membershipsQuery.data, "project", project.id);
if (state === "left") groups.other.push(project);
else groups.mine.push(project);
}
return groups;
}, [membershipsQuery.data, sortedProjects]);
const sortLabel = PROJECT_SORT_OPTIONS.find((option) => option.field === sortField)?.label ?? "Name";
if (!selectedCompanyId) {
return <EmptyState icon={Hexagon} message="Select a company to view projects." />;
@ -102,22 +124,46 @@ export function Projects() {
return (
<div className="space-y-4">
<div className="flex flex-wrap items-center justify-between gap-3">
<label className="flex items-center gap-2 text-sm text-muted-foreground">
<ArrowUpDown className="h-4 w-4" />
<span>Sort</span>
<select
className="rounded-md border border-border bg-background px-2.5 py-1.5 text-sm text-foreground outline-none transition-colors hover:bg-accent/50 focus-visible:ring-2 focus-visible:ring-ring"
value={sortMode}
onChange={(event) => setSortMode(event.target.value as ProjectSortMode)}
>
{(Object.keys(PROJECT_SORT_LABELS) as ProjectSortMode[]).map((value) => (
<option key={value} value={value}>
{PROJECT_SORT_LABELS[value]}
</option>
))}
</select>
</label>
<div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
<Popover>
<PopoverTrigger asChild>
<Button variant="ghost" size="sm" className="w-fit text-xs" title="Sort">
<ArrowUpDown className="h-3.5 w-3.5 sm:h-3 sm:w-3 sm:mr-1" />
<span>Sort: {sortLabel}</span>
</Button>
</PopoverTrigger>
<PopoverContent align="start" className="w-44 p-0">
<div className="p-2 space-y-0.5">
{PROJECT_SORT_OPTIONS.map((option) => (
<button
key={option.field}
type="button"
className={`flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm ${
sortField === option.field
? "bg-accent/50 text-foreground"
: "text-muted-foreground hover:bg-accent/50"
}`}
onClick={() => {
if (sortField === option.field) {
setSortDir((current) => (current === "asc" ? "desc" : "asc"));
return;
}
setSortField(option.field);
setSortDir(option.field === "name" || option.field === "targetDate" ? "asc" : "desc");
}}
>
<span>{option.label}</span>
{sortField === option.field ? (
<span className="flex items-center gap-1 text-xs text-muted-foreground">
<Check className="h-3 w-3" />
{sortDir === "asc" ? "Asc" : "Desc"}
</span>
) : null}
</button>
))}
</div>
</PopoverContent>
</Popover>
<Button size="sm" variant="outline" onClick={openNewProject}>
<Plus className="h-4 w-4 mr-1" />
Add Project
@ -136,26 +182,70 @@ export function Projects() {
)}
{projects.length > 0 && (
<div className="border border-border">
{sortedProjects.map((project) => (
<EntityRow
key={project.id}
title={project.name}
subtitle={project.description ?? undefined}
reserveSubtitleSpace
to={projectUrl(project)}
trailing={
<div className="flex items-center gap-3">
{project.targetDate && (
<span className="text-xs text-muted-foreground">
{formatDate(project.targetDate)}
</span>
)}
<StatusBadge status={project.status} />
<div className="space-y-6">
{([
["My Projects", groupedProjects.mine],
["Other Projects", groupedProjects.other],
] as const).map(([label, sectionProjects]) => {
if (sectionProjects.length === 0) return null;
return (
<section key={label} className="space-y-2">
<div className="flex items-center justify-between">
<h2 className="text-sm font-medium">{label}</h2>
<span className="text-xs text-muted-foreground">
{sectionProjects.length} project{sectionProjects.length === 1 ? "" : "s"}
</span>
</div>
}
/>
))}
<div className="border border-border">
{sectionProjects.map((project) => {
const state = resourceMembershipState(membershipsQuery.data, "project", project.id);
const pending = membershipMutation.isPending &&
membershipMutation.variables?.resourceType === "project" &&
membershipMutation.variables.resourceId === project.id;
return (
<EntityRow
key={project.id}
title={project.name}
subtitle={project.description ?? undefined}
reserveSubtitleSpace
to={projectUrl(project)}
className={state === "left" ? "group text-foreground/55" : "group"}
trailing={
<div className="flex items-center gap-3">
{project.targetDate && (
<span className="text-xs text-muted-foreground">
{formatDate(project.targetDate)}
</span>
)}
<StatusBadge status={project.status} />
<MembershipAction
state={state}
pending={pending}
pendingState={pending ? membershipMutation.variables?.state : null}
resourceName={project.name}
onJoin={() => membershipMutation.mutate({
resourceType: "project",
resourceId: project.id,
resourceName: project.name,
state: "joined",
})}
onLeave={() => membershipMutation.mutate({
resourceType: "project",
resourceId: project.id,
resourceName: project.name,
state: "left",
})}
/>
</div>
}
/>
);
})}
</div>
</section>
);
})}
</div>
)}
</div>