Files
PaperClipAI/ui/src/components/DocumentFrameHeader.tsx
T
DottaandPaperclip 43b005b704 Add pipeline workflow primitives and operator UI (#7903)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The pipeline subsystem models repeatable work as items moving
through stages, with agent automation, review gates, blockers, drift
notices, and linked work.
> - Operators need this to be usable as one coherent workflow surface,
not just as backend primitives or disconnected route experiments.
> - The branch now carries the pipeline data model, service/routes,
CLI/tutorial path, aggregation feeds, operator UI, stage automation
controls, liveness/retry handling, and follow-up polish that make the
primitive reviewable end to end.
> - This pull request is the single review target for that pipeline
workflow primitive stack.
> - The benefit is that reviewers can evaluate the full operator
experience and server contract together against `master`.

## Linked Issues or Issue Description

No public GitHub issue exists for this work. The underlying feature
request is described inline.

### Problem or motivation

Paperclip needs a first-class way to model multi-stage agent/company
workflows where upstream items can spawn downstream work, request
review, carry fields across pipelines, surface drift, retry automation,
and show operators where work is blocked or active. Without a unified
pipeline primitive, these workflows spread across ad hoc issues,
routines, and comments, making the state hard to inspect or operate.

### Proposed solution

Add the pipeline workflow primitive stack: database schema and
migrations, shared validators/types, server services and REST routes,
aggregation and liveness helpers, CLI/tutorial smoke support, and the
React operator UI for pipeline lists, boards, item detail,
review/learnings views, settings, stage automation, secrets, carry-over
fields, and retry/recovery flows.

### Alternatives considered

- Keep workflows as loosely linked issues and routines: rejected because
operators need a single board/detail/settings surface for repeated
workflow patterns.
- Ship backend primitives first and defer UI: rejected for this branch
because the operator experience is the main way to validate the
primitive.
- Add a narrower one-off content workflow: rejected because the same
primitives are useful across future company processes.

## What Changed

- Added and evolved pipeline schema, migrations, shared contracts,
server services, REST routes, route tests, and CLI/tutorial smoke
support.
- Added pipeline aggregation, health/liveness, drift acknowledgment,
blocker/carry-over, automation retry, stage automation environment, and
permission recovery behavior.
- Added the operator UI for pipeline index/board/item
detail/settings/review/learnings flows, including stage secrets,
automation controls, markdown/item descriptions, linked issue assets,
liveness banners, and source automation metadata.
- Refactored issue document frame rendering through the shared
`DocumentFrameHeader` component to keep document controls consistent
with the pipeline document surfaces.
- Kept this PR as the single base-branch review target for the current
pipeline branch.

## Verification

Current branch refresh:

- `pnpm vitest run server/src/__tests__/pipelines-service.test.ts` — 31
passed
- `pnpm vitest run server/src/__tests__/pipelines-routes.test.ts` — 19
passed
- `pnpm --filter ./server typecheck` — passed
- `pnpm --filter ./ui typecheck` — passed
- Verified Pipelines remains gated by `enablePipelines === true`:
sidebar item is hidden unless the flag is enabled, direct pipeline
routes redirect to `/dashboard` when disabled, and the Experimental
settings UI still has no Pipelines toggle.
- GitHub status checks on `df071c710646de625131064c3fb6588b5e97964a` —
all complete with no failing conclusions, including Actions, Socket,
Superagent/Security, and Greptile Review
- Greptile summary on `df071c710646de625131064c3fb6588b5e97964a` —
Confidence Score 5/5
- GitHub review-thread sweep — 0 unresolved Greptile threads

Previously recorded during branch development:

- Server pipeline service/route and aggregation tests
- Shared validator tests
- UI pipeline page/settings/item-detail/learnings/liveness tests
- Pipeline tutorial smoke path

## Risks

- High review surface: this is a large feature branch spanning database,
shared contracts, server behavior, CLI/docs, and UI.
- Migration ordering and schema compatibility need reviewer attention
because this branch has been kept current across multiple `master`
syncs.
- GitHub still reports merge state `BLOCKED` because the PR is awaiting
normal human review/branch-protection completion; all current status
checks are green.
- Branch-name checklist exception: this PR uses the pre-existing
requested branch name, which predates the current public-branch naming
rule. The PR title/body avoid internal issue references.

> 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 Codex coding agent based on GPT-5, with repository tool use,
shell execution, git/GitHub CLI operations, and local verification
commands. Earlier commits in this branch were assisted by Paperclip
agents and other AI coding agents as recorded in commit authorship.

## 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)
- [ ] 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>
2026-06-26 12:02:44 -05:00

156 lines
6.1 KiB
TypeScript

import type { ReactNode } from "react";
import { ChevronDown, ChevronRight } from "lucide-react";
import { cn, relativeTime } from "../lib/utils";
import { Button } from "@/components/ui/button";
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu";
export type DocumentFrameHeaderRevision = {
id: string;
revisionNumber: number;
createdAt: string | Date;
actorLabel: string;
};
export type DocumentFrameHeaderRevisionMenu = {
open: boolean;
onOpenChange: (open: boolean) => void;
loading: boolean;
revisions: DocumentFrameHeaderRevision[];
selectedRevisionId: string | null;
currentRevisionId: string | null;
displayedRevisionNumber: number;
historicalPreview: boolean;
onSelectRevision: (revisionId: string, isCurrentRevision: boolean) => void;
};
export interface DocumentFrameHeaderProps {
documentKey: string;
documentLabel?: string;
folded: boolean;
onToggleFolded: () => void;
revisionMenu?: DocumentFrameHeaderRevisionMenu;
updatedAt?: string | Date | null;
updatedHref?: string;
sourceTrustSlot?: ReactNode;
annotationSlot?: ReactNode;
titleSlot?: ReactNode;
actionsSlot?: ReactNode;
}
export function DocumentFrameHeader({
documentKey,
documentLabel,
folded,
onToggleFolded,
revisionMenu,
updatedAt,
updatedHref,
sourceTrustSlot,
annotationSlot,
titleSlot,
actionsSlot,
}: DocumentFrameHeaderProps) {
return (
<div className="flex items-start justify-between gap-3">
<div className="min-w-0">
<div className="flex items-center gap-2 min-w-0">
<button
type="button"
className="inline-flex h-5 w-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors hover:bg-accent/60 hover:text-foreground"
onClick={onToggleFolded}
aria-label={folded ? `Expand ${documentKey} document` : `Collapse ${documentKey} document`}
aria-expanded={!folded}
>
{folded ? <ChevronRight className="h-3.5 w-3.5" /> : <ChevronDown className="h-3.5 w-3.5" />}
</button>
{documentLabel ? (
<>
<span className="truncate text-sm font-semibold text-foreground">{documentLabel}</span>
<span className="shrink-0 rounded-full border border-border px-2 py-0.5 font-mono text-[10px] uppercase tracking-[0.16em] text-muted-foreground">
{documentKey}
</span>
</>
) : (
<span className="shrink-0 rounded-full border border-border px-2 py-0.5 font-mono text-[10px] uppercase tracking-[0.16em] text-muted-foreground">
{documentKey}
</span>
)}
{sourceTrustSlot}
{revisionMenu ? (
<DropdownMenu open={revisionMenu.open} onOpenChange={revisionMenu.onOpenChange}>
<DropdownMenuTrigger asChild>
<Button
variant="ghost"
size="sm"
className={cn(
"h-auto px-1.5 py-0 text-[11px] font-normal text-muted-foreground hover:text-foreground",
revisionMenu.historicalPreview && "text-amber-300 hover:text-amber-200",
)}
>
rev {revisionMenu.displayedRevisionNumber}
<ChevronDown className="h-3 w-3" />
</Button>
</DropdownMenuTrigger>
<DropdownMenuContent align="start" className="w-72">
<DropdownMenuLabel>Revision history</DropdownMenuLabel>
{revisionMenu.loading && revisionMenu.revisions.length === 0 ? (
<DropdownMenuItem disabled>Loading revisions...</DropdownMenuItem>
) : revisionMenu.revisions.length > 0 ? (
<DropdownMenuRadioGroup value={revisionMenu.selectedRevisionId ?? revisionMenu.currentRevisionId ?? ""}>
{revisionMenu.revisions.map((revision) => {
const isCurrentRevision = revision.id === revisionMenu.currentRevisionId;
return (
<DropdownMenuRadioItem
key={revision.id}
value={revision.id}
onSelect={() => revisionMenu.onSelectRevision(revision.id, isCurrentRevision)}
className="items-start"
>
<div className="flex min-w-0 flex-col">
<div className="flex items-center gap-2">
<span className="font-medium">rev {revision.revisionNumber}</span>
{isCurrentRevision ? (
<span className="rounded-full border border-border px-1.5 py-0.5 text-[10px] uppercase tracking-[0.12em] text-muted-foreground">
Current
</span>
) : null}
</div>
<span className="text-xs text-muted-foreground">
{relativeTime(revision.createdAt)} • {revision.actorLabel}
</span>
</div>
</DropdownMenuRadioItem>
);
})}
</DropdownMenuRadioGroup>
) : (
<DropdownMenuItem disabled>No revisions yet</DropdownMenuItem>
)}
</DropdownMenuContent>
</DropdownMenu>
) : null}
{updatedAt ? (
<a
href={updatedHref ?? `#document-${encodeURIComponent(documentKey)}`}
className="truncate text-[11px] text-muted-foreground transition-colors hover:text-foreground hover:underline"
>
updated {relativeTime(updatedAt)}
</a>
) : null}
{annotationSlot}
</div>
{titleSlot}
</div>
{actionsSlot ? <div className="flex items-center gap-1 shrink-0">{actionsSlot}</div> : null}
</div>
);
}