mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - A task that fails shows a banner with a Retry button. The user
clicks Retry to run the task again.
> - Self-hosted boards also show a "You completed 5 tasks! Star on
GitHub" modal (#20453).
> - The modal can open on the task page while the task shows its Retry
banner.
> - The modal is a Radix dialog. It sets `aria-hidden="true"` on the
rest of the page and sets `pointer-events: none` on the body. The Retry
button is visible, but a click does not reach it and assistive
technology cannot find it.
> - This pull request makes the star prompt wait for a calm moment. It
does not open on a task or agent chat page, and it does not open while a
task Retry or status banner is on screen.
> - The benefit is that a visible Retry is always reachable.
## Linked Issues or Issue Description
Refs #20453
**What happened?**
A restart chaos run left a task in the failed state with the Retry
banner. The "You completed 5 tasks!" star modal opened over the same
page. The Retry button was in the DOM and visible. Playwright
`getByRole('button', { name: 'Retry' })` did not find it, because the
modal had set `aria-hidden="true"` on the banner. The body also had
`pointer-events: none`, so a user click on Retry did not reach the
button.
**Expected behavior**
A promotional prompt never covers a task that needs the user. A visible
Retry is always reachable.
**Steps to reproduce**
1. On a self-hosted instance, finish five tasks in one company. Do not
open the star prompt before.
2. Let a sixth task fail so that it shows "Couldn't finish this attempt"
with Retry.
3. Open that task. The star modal opens over the Retry banner.
**Paperclip version or commit**
master at 200c6e40e2
## What Changed
- `GitHubStarPrompt` waits while the location is one task
(`/:prefix/issues/:ref`) or one agent chat (`/:prefix/chats/:agent`).
Task list views (`issues/all`, `issues/done`, and so on) do not count as
one task.
- `GitHubStarPrompt` waits while a task Retry
(`data-testid="task-execution-retry"`) or a task status banner
(`role="status"` with `aria-label="Task status"`) is on screen. It uses
the same DOM observer that already waits for other dialogs.
- If the prompt is open and the user goes back to a task or chat page,
or a task Retry or status banner appears, the prompt closes.
- `useModalOpen` in `AnnouncementWell.tsx` takes an optional selector.
The default is the existing modal selector, so other callers do not
change.
- New tests in `GitHubStarPrompt.test.tsx`: the prompt stays closed
while a Retry banner is on screen and the banner is not `aria-hidden`;
the prompt stays closed on a task and a chat page and opens on the task
list. The prompt closes when the user goes back to a task, and when a
Retry appears.
## Verification
- Red first: the two new tests failed on master. A temporary probe in
the red run showed the prompt open, the banner with
`aria-hidden="true"`, and `document.body.style.pointerEvents ===
"none"`.
- Green: `cd ui && npx vitest run
src/components/GitHubStarPrompt.test.tsx
src/components/BoardDialogs.test.tsx` passes.
- `pnpm verify` passes (481 UI test files).
- `pnpm check:token-gates`: all gates clean.
- `npx tsc --noEmit -p ui`: no errors in the changed files.
## Risks
- Low risk. The prompt can show later than before, because it waits for
a non-task page. It still shows only once per browser.
- The "seen" marker is written only when the prompt opens, so a user who
stays on task pages does not lose the prompt.
> 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
- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use (shell, file edit, test runs).
## 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
- [ ] All Paperclip CI gates are green
- [ ] 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 <noreply@anthropic.com>
160 lines
7.3 KiB
TypeScript
160 lines
7.3 KiB
TypeScript
// @vitest-environment jsdom
|
||
import { act } from "react";
|
||
import { createRoot, type Root } from "react-dom/client";
|
||
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
||
import { MemoryRouter, useNavigate, type NavigateFunction } from "react-router-dom";
|
||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||
import { ONBOARDING_FIRST_TASK_ORIGIN_KIND } from "@paperclipai/shared";
|
||
import type { HealthStatus } from "@/api/health";
|
||
import { GitHubStarPrompt, STAR_PROMPT_SEEN_KEY } from "./GitHubStarPrompt";
|
||
|
||
const state = vi.hoisted(() => ({ companyId: "company", loading: false, onboardingOpen: false, onboardingStatus: null as string | null, done: 5, listCompact: vi.fn() }));
|
||
vi.mock("@/context/CompanyContext", () => ({ useCompany: () => ({ selectedCompanyId: state.companyId, loading: state.loading }) }));
|
||
vi.mock("@/context/DialogContext", () => ({ useDialogState: () => ({ onboardingOpen: state.onboardingOpen }) }));
|
||
vi.mock("@/api/issues", () => ({ issuesApi: {
|
||
list: () => Promise.resolve(state.onboardingStatus ? [{ id: "onboarding", originKind: ONBOARDING_FIRST_TASK_ORIGIN_KIND, status: state.onboardingStatus }] : []),
|
||
listCompact: (...args: unknown[]) => {
|
||
state.listCompact(...args);
|
||
return Promise.resolve(Array.from({ length: state.done }, (_, i) => ({ id: `issue-${i}` })));
|
||
},
|
||
} }));
|
||
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
|
||
|
||
describe("GitHub star prompt", () => {
|
||
let container: HTMLDivElement;
|
||
let root: Root;
|
||
let navigate: NavigateFunction | null = null;
|
||
function NavigateHandle() { navigate = useNavigate(); return null; }
|
||
const render = async (health: Partial<HealthStatus> | null = { deploymentMode: "local_trusted" }, path = "/CHA/dashboard") => {
|
||
const client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
|
||
if (health) client.setQueryData(["health"], health);
|
||
await act(async () => root.render(<QueryClientProvider client={client}><MemoryRouter initialEntries={[path]}>
|
||
<NavigateHandle /><GitHubStarPrompt />
|
||
</MemoryRouter></QueryClientProvider>));
|
||
// Let the onboarding and done-count queries settle, however slow the run.
|
||
for (let idle = 0, tick = 0; idle < 2 && tick < 100; tick++) {
|
||
await act(async () => { await new Promise((resolve) => setTimeout(resolve, 20)); });
|
||
idle = client.isFetching() === 0 ? idle + 1 : 0;
|
||
}
|
||
};
|
||
const visible = () => Boolean(document.querySelector('[data-testid="github-star-prompt"]'));
|
||
beforeEach(() => {
|
||
Object.assign(state, { companyId: "company", loading: false, onboardingOpen: false, onboardingStatus: null, done: 5 });
|
||
state.listCompact.mockClear();
|
||
window.localStorage.clear();
|
||
container = document.createElement("div"); document.body.append(container); root = createRoot(container);
|
||
});
|
||
afterEach(async () => { await act(async () => root.unmount()); container.remove(); });
|
||
|
||
it("opens once a self-hosted company has five done tasks, and only once", async () => {
|
||
await render();
|
||
expect(visible()).toBe(true);
|
||
expect(state.listCompact).toHaveBeenCalledWith("company", { status: "done", limit: 5 }, expect.anything());
|
||
expect(window.localStorage.getItem(STAR_PROMPT_SEEN_KEY)).not.toBeNull();
|
||
const star = document.querySelector<HTMLAnchorElement>('a[href="https://github.com/paperclipai/paperclip"]');
|
||
expect(star?.target).toBe("_blank");
|
||
|
||
await act(async () => root.unmount());
|
||
root = createRoot(container);
|
||
await render();
|
||
expect(visible()).toBe(false);
|
||
});
|
||
|
||
it("waits for another open dialog to close", async () => {
|
||
const other = document.createElement("div");
|
||
other.setAttribute("role", "dialog"); other.setAttribute("data-state", "open");
|
||
document.body.append(other);
|
||
await render();
|
||
expect(visible()).toBe(false);
|
||
await act(async () => { other.remove(); });
|
||
expect(visible()).toBe(true);
|
||
});
|
||
|
||
it("never covers a task's Retry: it waits until no Retry banner is on screen", async () => {
|
||
const banner = document.createElement("div");
|
||
banner.setAttribute("role", "status"); banner.setAttribute("aria-label", "Task status");
|
||
banner.innerHTML = '<span>Couldn’t finish this attempt. Your message is saved.</span><button data-testid="task-execution-retry">Retry</button>';
|
||
document.body.append(banner);
|
||
try {
|
||
await render();
|
||
expect(visible()).toBe(false);
|
||
expect(banner.closest('[aria-hidden="true"]')).toBeNull();
|
||
await act(async () => { banner.remove(); });
|
||
expect(visible()).toBe(true);
|
||
} finally { banner.remove(); }
|
||
});
|
||
|
||
it("does not interrupt while the user is looking at a task or a chat", async () => {
|
||
await render(undefined, "/CHA/issues/CHA-4");
|
||
expect(visible()).toBe(false);
|
||
await act(async () => { navigate!("/CHA/chats/claude"); });
|
||
expect(visible()).toBe(false);
|
||
expect(window.localStorage.getItem(STAR_PROMPT_SEEN_KEY)).toBeNull();
|
||
await act(async () => { navigate!("/CHA/issues"); });
|
||
expect(visible()).toBe(true);
|
||
});
|
||
|
||
it("closes when the user goes back to a task, or a task asks for Retry", async () => {
|
||
await render();
|
||
expect(visible()).toBe(true);
|
||
await act(async () => { navigate!("/CHA/issues/CHA-4"); });
|
||
expect(visible()).toBe(false);
|
||
|
||
window.localStorage.clear();
|
||
await act(async () => root.unmount());
|
||
root = createRoot(container);
|
||
await render();
|
||
expect(visible()).toBe(true);
|
||
const retry = document.createElement("button");
|
||
retry.setAttribute("data-testid", "task-execution-retry");
|
||
document.body.append(retry);
|
||
try {
|
||
await act(async () => { await new Promise((resolve) => setTimeout(resolve, 20)); });
|
||
expect(visible()).toBe(false);
|
||
expect(retry.closest('[aria-hidden="true"]')).toBeNull();
|
||
} finally { retry.remove(); }
|
||
});
|
||
|
||
it("does not open after another tab has shown it", async () => {
|
||
const other = document.createElement("div");
|
||
other.setAttribute("role", "dialog"); other.setAttribute("data-state", "open");
|
||
document.body.append(other);
|
||
await render();
|
||
window.localStorage.setItem(STAR_PROMPT_SEEN_KEY, new Date().toISOString());
|
||
await act(async () => { window.dispatchEvent(new StorageEvent("storage", { key: STAR_PROMPT_SEEN_KEY })); });
|
||
await act(async () => { other.remove(); });
|
||
expect(visible()).toBe(false);
|
||
});
|
||
|
||
it("waits until the onboarding task is finished", async () => {
|
||
state.onboardingStatus = "in_progress";
|
||
await render();
|
||
expect(visible()).toBe(false);
|
||
expect(state.listCompact).not.toHaveBeenCalled();
|
||
await act(async () => root.unmount());
|
||
root = createRoot(container);
|
||
state.onboardingStatus = "done";
|
||
await render();
|
||
expect(visible()).toBe(true);
|
||
});
|
||
|
||
it("stays hidden below five done tasks", async () => {
|
||
state.done = 4;
|
||
await render();
|
||
expect(visible()).toBe(false);
|
||
expect(window.localStorage.getItem(STAR_PROMPT_SEEN_KEY)).toBeNull();
|
||
});
|
||
|
||
it("stays hidden on cloud, during onboarding, and before health is known", async () => {
|
||
await render({ deploymentMode: "authenticated", cloud: {} as HealthStatus["cloud"] });
|
||
expect(visible()).toBe(false);
|
||
state.onboardingOpen = true;
|
||
await render();
|
||
expect(visible()).toBe(false);
|
||
state.onboardingOpen = false;
|
||
await render(null);
|
||
expect(visible()).toBe(false);
|
||
expect(state.listCompact).not.toHaveBeenCalled();
|
||
});
|
||
});
|