mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-06 21:05:21 +02:00
## 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>
156 lines
6.1 KiB
TypeScript
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>
|
|
);
|
|
}
|