mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 00:05:49 +02:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The board currently uses issues for execution, but longer-lived content work needs a separate object that can survive beyond a single task thread. > - The Cases subsystem adds an experimental, company-scoped record for content artifacts and their supporting metadata. > - The backend needs durable storage, API routes, revision history, issue linkage, and company-boundary enforcement before the UI can depend on Cases. > - The UI needs an opt-in navigation surface, list/detail views, reference chips, and issue-page context so operators can inspect Cases without making them the default workflow. > - The agent-facing skills need a contract for creating and updating Cases so automated content workflows can dogfood the feature. > - This pull request ships that experimental end-to-end path behind the `enableCases` flag. > - The benefit is a first-class place to collect content work, references, attachments, revisions, and related execution threads without polluting the core issue model. ## Linked Issues or Issue Description No public GitHub issue exists for this experimental feature. Feature request fields: ### Problem Content-oriented work such as release notes, announcements, docs, and campaigns can span many execution issues, which makes the final artifact hard to find and reason about after the execution thread moves on. ### Proposed solution Add an experimental Cases object that is company-scoped, linked to issues, queryable through the API, inspectable in the board UI, and writable by agent workflows through documented conventions. ### Alternatives considered Continue encoding content artifacts directly in issues or documents only. That keeps the data model smaller, but it does not give operators a stable artifact-centric view or a clean way to link related execution history. ### Roadmap alignment Checked `ROADMAP.md`; this PR does not duplicate an existing planned core roadmap item. ## What Changed - Added the `cases` data model, migration, schema exports, and experimental `enableCases` instance setting. - Added company-scoped Cases API routes for list/detail/update, issue links, revisions, children, activity events, annotations, attachments, and idempotent agent-oriented upserts. - Scoped case and issue lookup helpers before access checks so inaccessible cross-company identifiers resolve as not found rather than leaking existence. - Fixed case PATCH timestamp handling so non-status updates cannot overwrite `completedAt` from a stale pre-transaction row snapshot. - Moved Cases list type/status/project filters into the server request before the server-side limit is applied, including multi-select filters and no-project filtering. - Added backend route coverage for creation, updates, idempotency, issue linking, attribution, company-boundary enforcement, OpenAPI registration, list filtering, timestamp patch behavior, and inaccessible lookup regressions. - Added the experimental Cases UI surface: sidebar entry, gated routes, list filters/grouping, detail overview, activity, revisions, children, attachments, and issue-page case rail. - Added case reference rendering and company-prefixed case href generation so case links resolve directly inside the active company route. - Added Paperclip skill documentation for agent workflows that create or update Cases. - Wired release-content skills to emit Cases for dogfooding. - Rebased onto current `master` and renumbered the Cases migrations to `0143`/`0144` after the latest upstream migration sequence. ## Verification - Current PR head: `ecc13be0d`. - Rebased on current `master` (`606aa4f266`) and pushed to the existing PR branch. - `git diff --check origin/master...HEAD` — passed before the first update push; subsequent committed diffs were also checked with `git diff --check` before commit. - Guardrails checked: no `pnpm-lock.yaml` changes, no `.github/workflows` changes, and changed-file count is below the Greptile 100-file limit. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/cases-routes.test.ts src/__tests__/instance-settings-service.test.ts src/__tests__/openapi-routes.test.ts` — passed, 3 files / 26 tests before review-fix commits. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/cases-routes.test.ts` — passed after each server-side Greptile fix, latest 1 file / 15 tests. - `pnpm --filter @paperclipai/server typecheck` — passed after the timestamp and lookup fixes. - `pnpm --filter @paperclipai/ui exec vitest run src/pages/Cases.test.tsx src/pages/CaseDetail.test.tsx src/pages/CompanySkills.test.tsx src/App.cases-routing.test.tsx` — passed, 4 files / 30 tests before review-fix commits. - `pnpm --filter @paperclipai/ui exec vitest run src/pages/Cases.test.tsx` — passed after the list-filter fix, 1 file / 12 tests. - `pnpm --filter @paperclipai/ui typecheck` — passed after the list-filter fix. - `pnpm check:token-gates` — passed after UI changes. - Remote PR checks on head `ecc13be0d` are green: Paperclip CI, build, typecheck, test matrix, e2e, Canary Dry Run, policy, commit review, Superagent Security Scan, Socket, Snyk, and Greptile passed; Storybook visual regression is skipped and security-review is neutral. - Greptile Review: 5/5 confidence, zero unresolved Greptile threads. ## Risks - Medium feature risk because this introduces a new experimental domain object across database, server, shared contracts, skills, and UI. - The feature is gated behind `enableCases`, which limits default operator exposure while the model is exercised. - Case links now prefer company-prefixed hrefs; the unprefixed redirect remains for externally entered URLs. - Cases list filtering now sends multi-select filters to the server before limiting; the UI still applies the same local filters as a second pass for ancestor/context rows. - Migrations were renumbered on top of current master; the SQL uses guarded `IF NOT EXISTS` / `ADD COLUMN IF NOT EXISTS` patterns where relevant for safer replay. > 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 in the Paperclip local coding environment was used for this PR curation, rebase verification, review-fix implementation, push, and PR description update. The runtime exposes tool use and shell execution; context-window size is not exposed by this Paperclip adapter. Several implementation commits also include AI co-author trailers recorded in git history. ## 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 searched the GitHub PR list for similar PRs and confirmed this is not a duplicate - [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) - [ ] 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> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
287 lines
12 KiB
TypeScript
287 lines
12 KiB
TypeScript
import { useEffect, useState } from "react";
|
|
import { useQuery } from "@tanstack/react-query";
|
|
import { Link } from "@/lib/router";
|
|
import { casesApi, type CaseDocumentRevision } from "@/api/cases";
|
|
import { queryKeys } from "@/lib/queryKeys";
|
|
import { buildLineDiff, type DiffRow } from "@/lib/line-diff";
|
|
import { Button } from "@/components/ui/button";
|
|
import { Card } from "@/components/ui/card";
|
|
import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog";
|
|
import { MarkdownBody } from "@/components/MarkdownBody";
|
|
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
|
|
import { cn, relativeTime } from "@/lib/utils";
|
|
import { Diff } from "lucide-react";
|
|
|
|
/** Author + via-issue attribution line for a revision. */
|
|
function RevisionByline({ revision }: { revision: CaseDocumentRevision }) {
|
|
const author = revision.actorAgentName ?? (revision.createdByUserId ? "User" : "System");
|
|
return (
|
|
<span className="flex flex-wrap items-center gap-x-1 text-(length:--text-micro) text-muted-foreground">
|
|
<span>{author}</span>
|
|
{revision.issue && (
|
|
<>
|
|
<span aria-hidden>·</span>
|
|
<span>via</span>
|
|
<Link
|
|
to={`/issues/${revision.issue.identifier}`}
|
|
className="font-mono text-foreground/80 hover:underline"
|
|
onClick={(e) => e.stopPropagation()}
|
|
title={revision.issue.title}
|
|
>
|
|
{revision.issue.identifier}
|
|
</Link>
|
|
</>
|
|
)}
|
|
</span>
|
|
);
|
|
}
|
|
|
|
function getRevisionLabel(revision: CaseDocumentRevision) {
|
|
const actor = revision.actorAgentName ?? (revision.createdByUserId ? "board" : "system");
|
|
return `rev ${revision.revisionNumber} - ${relativeTime(revision.createdAt)} - ${actor}`;
|
|
}
|
|
|
|
function CaseDocumentDiffModal({
|
|
documentKey,
|
|
revisions,
|
|
latestRevisionNumber,
|
|
open,
|
|
onOpenChange,
|
|
}: {
|
|
documentKey: string;
|
|
revisions: CaseDocumentRevision[];
|
|
latestRevisionNumber: number;
|
|
open: boolean;
|
|
onOpenChange: (open: boolean) => void;
|
|
}) {
|
|
const [leftRevisionId, setLeftRevisionId] = useState<string | null>(null);
|
|
const [rightRevisionId, setRightRevisionId] = useState<string | null>(null);
|
|
|
|
const effectiveLeftId = leftRevisionId ?? revisions.find(
|
|
(revision) => revision.revisionNumber === latestRevisionNumber - 1,
|
|
)?.id ?? null;
|
|
const effectiveRightId = rightRevisionId ?? revisions.find(
|
|
(revision) => revision.revisionNumber === latestRevisionNumber,
|
|
)?.id ?? null;
|
|
const leftRevision = revisions.find((revision) => revision.id === effectiveLeftId) ?? null;
|
|
const rightRevision = revisions.find((revision) => revision.id === effectiveRightId) ?? null;
|
|
const diffRows = buildLineDiff(leftRevision?.body ?? "", rightRevision?.body ?? "");
|
|
const lineClassesByKind: Record<DiffRow["kind"], string> = {
|
|
context: "bg-transparent",
|
|
removed: "bg-red-500/10 text-red-900 dark:text-red-100",
|
|
added: "bg-green-500/10 text-green-900 dark:text-green-100",
|
|
};
|
|
const markerByKind: Record<DiffRow["kind"], string> = {
|
|
context: " ",
|
|
removed: "-",
|
|
added: "+",
|
|
};
|
|
|
|
return (
|
|
<Dialog open={open} onOpenChange={onOpenChange}>
|
|
<DialogContent className="!max-w-(--pct-90) flex max-h-(--sz-85vh) w-full flex-col overflow-hidden">
|
|
<div className="flex items-center justify-between gap-4">
|
|
<DialogHeader className="shrink-0">
|
|
<DialogTitle>
|
|
Diff - <span className="font-mono text-sm">{documentKey}</span>
|
|
</DialogTitle>
|
|
</DialogHeader>
|
|
<div className="flex shrink-0 items-center gap-4">
|
|
<div className="flex items-center gap-2">
|
|
<span className="rounded-full border border-red-500/30 bg-red-500/10 px-2 py-0.5 text-(length:--text-nano) font-medium uppercase tracking-(--tracking-caps) text-red-400">Old</span>
|
|
<Select value={effectiveLeftId ?? ""} onValueChange={setLeftRevisionId}>
|
|
<SelectTrigger className="h-7 w-60 border-border/60 text-xs">
|
|
<SelectValue placeholder="Select revision" />
|
|
</SelectTrigger>
|
|
<SelectContent>
|
|
{revisions.map((revision) => (
|
|
<SelectItem key={revision.id} value={revision.id} className="text-xs">
|
|
{getRevisionLabel(revision)}
|
|
</SelectItem>
|
|
))}
|
|
</SelectContent>
|
|
</Select>
|
|
</div>
|
|
<div className="flex items-center gap-2">
|
|
<span className="rounded-full border border-green-500/30 bg-green-500/10 px-2 py-0.5 text-(length:--text-nano) font-medium uppercase tracking-(--tracking-caps) text-green-400">New</span>
|
|
<Select value={effectiveRightId ?? ""} onValueChange={setRightRevisionId}>
|
|
<SelectTrigger className="h-7 w-60 border-border/60 text-xs">
|
|
<SelectValue placeholder="Select revision" />
|
|
</SelectTrigger>
|
|
<SelectContent>
|
|
{revisions.map((revision) => (
|
|
<SelectItem key={revision.id} value={revision.id} className="text-xs">
|
|
{getRevisionLabel(revision)}
|
|
</SelectItem>
|
|
))}
|
|
</SelectContent>
|
|
</Select>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div className="flex-1 overflow-auto rounded-md border border-border text-xs">
|
|
{!leftRevision || !rightRevision ? (
|
|
<div className="p-6 text-center text-sm text-muted-foreground">Select two revisions to compare.</div>
|
|
) : leftRevision.id === rightRevision.id ? (
|
|
<div className="p-6 text-center text-sm text-muted-foreground">Both sides are the same revision.</div>
|
|
) : (
|
|
<div className="font-mono text-xs leading-6">
|
|
<div className="grid grid-cols-(--gtc-1) border-b border-border/60 bg-muted/30 px-3 py-2 text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">
|
|
<span>Old</span>
|
|
<span>New</span>
|
|
<span />
|
|
<span>Content</span>
|
|
</div>
|
|
{diffRows.map((row, index) => (
|
|
<div
|
|
key={`${row.kind}-${index}-${row.oldLineNumber ?? "x"}-${row.newLineNumber ?? "x"}`}
|
|
className={cn("grid grid-cols-(--gtc-1) gap-0 border-b border-border/30 px-3", lineClassesByKind[row.kind])}
|
|
>
|
|
<span className="select-none border-r border-border/30 pr-3 text-right text-muted-foreground">
|
|
{row.oldLineNumber ?? ""}
|
|
</span>
|
|
<span className="select-none border-r border-border/30 px-3 text-right text-muted-foreground">
|
|
{row.newLineNumber ?? ""}
|
|
</span>
|
|
<span className="select-none px-3 text-center text-muted-foreground">
|
|
{markerByKind[row.kind]}
|
|
</span>
|
|
<pre className="overflow-x-auto whitespace-pre-wrap break-words px-3 py-0 text-inherit">
|
|
{row.text.length > 0 ? row.text : " "}
|
|
</pre>
|
|
</div>
|
|
))}
|
|
</div>
|
|
)}
|
|
</div>
|
|
</DialogContent>
|
|
</Dialog>
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Revision rail (P4 §2): read-only body document with a per-revision list. The
|
|
* newest revision is selected by default; picking another swaps the rendered
|
|
* body. No editing UI in v1.
|
|
*/
|
|
export function CaseRevisionRail({
|
|
caseIdentifier,
|
|
documentKey = "body",
|
|
}: {
|
|
caseIdentifier: string;
|
|
documentKey?: string;
|
|
}) {
|
|
const revisionsQuery = useQuery({
|
|
queryKey: queryKeys.cases.revisions(caseIdentifier, documentKey),
|
|
queryFn: () => casesApi.listRevisions(caseIdentifier, documentKey),
|
|
});
|
|
const revisions = revisionsQuery.data?.revisions ?? [];
|
|
const [selectedId, setSelectedId] = useState<string | null>(null);
|
|
const [diffOpen, setDiffOpen] = useState(false);
|
|
|
|
// Default to the latest revision once loaded; keep a valid selection if the
|
|
// list changes underneath us.
|
|
useEffect(() => {
|
|
if (revisions.length === 0) return;
|
|
if (!selectedId || !revisions.some((r) => r.id === selectedId)) {
|
|
setSelectedId(revisions[0]!.id);
|
|
}
|
|
}, [revisions, selectedId]);
|
|
|
|
if (revisionsQuery.isLoading) {
|
|
return <p className="py-6 text-center text-sm text-muted-foreground">Loading revisions…</p>;
|
|
}
|
|
if (revisionsQuery.isError) {
|
|
return <p className="py-6 text-center text-sm text-muted-foreground">Could not load revisions.</p>;
|
|
}
|
|
if (revisions.length === 0) {
|
|
return <p className="py-6 text-center text-sm text-muted-foreground">No revisions yet.</p>;
|
|
}
|
|
|
|
const selected = revisions.find((r) => r.id === selectedId) ?? revisions[0]!;
|
|
const latestRevisionNumber = revisionsQuery.data?.document.latestRevisionNumber ?? selected.revisionNumber;
|
|
|
|
return (
|
|
<div className="grid gap-4 md:grid-cols-(--gtc-case-revisions)">
|
|
<aside className="space-y-1">
|
|
<div className="flex items-center justify-between gap-2 px-1">
|
|
<h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
|
|
Revisions
|
|
</h3>
|
|
{revisions.length > 1 ? (
|
|
<Button
|
|
type="button"
|
|
variant="ghost"
|
|
size="sm"
|
|
className="h-7 gap-1 px-2 text-xs"
|
|
onClick={() => setDiffOpen(true)}
|
|
>
|
|
<Diff className="h-3.5 w-3.5" />
|
|
Diff
|
|
</Button>
|
|
) : null}
|
|
</div>
|
|
<ol className="space-y-1">
|
|
{revisions.map((rev, index) => (
|
|
<li key={rev.id}>
|
|
<button
|
|
type="button"
|
|
onClick={() => setSelectedId(rev.id)}
|
|
aria-current={rev.id === selected.id}
|
|
className={cn(
|
|
"w-full rounded-md border px-2.5 py-1.5 text-left transition-colors",
|
|
rev.id === selected.id
|
|
? "border-primary bg-primary/5"
|
|
: "border-border hover:bg-accent/50",
|
|
)}
|
|
>
|
|
<div className="flex items-center justify-between gap-2">
|
|
<span className="text-xs font-medium">
|
|
rev {rev.revisionNumber}
|
|
{index === 0 && (
|
|
<span className="ml-1.5 rounded bg-muted px-1 py-0.5 text-(length:--text-nano) text-muted-foreground">
|
|
latest
|
|
</span>
|
|
)}
|
|
</span>
|
|
<span className="text-(length:--text-micro) text-muted-foreground">{relativeTime(rev.createdAt)}</span>
|
|
</div>
|
|
{rev.changeSummary && (
|
|
<p className="mt-0.5 truncate text-(length:--text-micro) text-muted-foreground" title={rev.changeSummary}>
|
|
{rev.changeSummary}
|
|
</p>
|
|
)}
|
|
<RevisionByline revision={rev} />
|
|
</button>
|
|
</li>
|
|
))}
|
|
</ol>
|
|
</aside>
|
|
|
|
<Card className="min-w-0 px-4 py-3">
|
|
<div className="mb-2 flex items-baseline justify-between border-b border-border pb-2">
|
|
<span className="text-sm font-medium">rev {selected.revisionNumber}</span>
|
|
<RevisionByline revision={selected} />
|
|
</div>
|
|
{selected.body ? (
|
|
<MarkdownBody linkIssueReferences linkCaseReferences>
|
|
{selected.body}
|
|
</MarkdownBody>
|
|
) : (
|
|
<p className="text-sm text-muted-foreground">This revision has no body.</p>
|
|
)}
|
|
</Card>
|
|
{revisions.length > 1 ? (
|
|
<CaseDocumentDiffModal
|
|
documentKey={documentKey}
|
|
revisions={revisions}
|
|
latestRevisionNumber={latestRevisionNumber}
|
|
open={diffOpen}
|
|
onOpenChange={setDiffOpen}
|
|
/>
|
|
) : null}
|
|
</div>
|
|
);
|
|
}
|