mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-13 17:40:38 +09:00
## Thinking Path > - Paperclip orchestrates AI-agent companies through issues, documents, runs, and durable company-scoped state. > - Issue documents are where agents and operators capture plans, handoffs, and work products. > - Before this change, document collaboration could only happen through whole-document edits and detached issue comments. > - Inline document annotations need stable anchors, revision-aware persistence, and UI affordances that do not break existing document editing. > - This pull request adds company-scoped document annotation threads, comments, anchor snapshots, API routes, and board UI. > - The benefit is that operators and agents can discuss specific document passages without losing context as documents evolve. ## What Changed - Added document annotation tables, schema exports, shared types, validators, anchor hashing, and text-anchor helpers. - Added server-side document annotation services and issue routes for listing, creating, commenting, resolving, and reopening annotation threads. - Included annotation summaries in relevant issue document reads and backup/recovery document workspace behavior. - Added React UI for inline document highlights, comment panels, mobile sheet behavior, deep-link focus, and resolved/open filtering. - Added annotation design artifacts, Storybook coverage, screenshots, and a screenshot helper script. - Rebased the branch onto current `paperclipai/paperclip` `master` and renumbered the annotation migration from `0085_old_swarm` to `0091_old_swarm`; the SQL uses `IF NOT EXISTS` guards so environments that previously applied the old migration number can safely apply the new one. - Adjusted the new annotation UI tests to use a local async flush helper because this workspace's React 19.2.4 export does not expose `React.act`. ## Verification - `pnpm run preflight:workspace-links && pnpm exec vitest run packages/shared/src/document-anchors.test.ts server/src/__tests__/document-annotation-routes.test.ts server/src/__tests__/document-annotations-service.test.ts ui/src/components/DocumentAnnotationLayer.test.tsx ui/src/components/IssueDocumentAnnotations.test.tsx ui/src/lib/document-annotation-hash.test.ts ui/src/lib/document-annotation-selection.test.ts` - Confirmed `git diff --check` passes. - Confirmed no `pnpm-lock.yaml` or `.github/workflows/*` files are included in the PR diff. ## Risks - Medium risk: this adds new persisted annotation tables and routes across db/shared/server/ui. - Migration risk is reduced by moving the branch migration to `0091_old_swarm` after upstream `0090_resource_memberships` and keeping the SQL idempotent for old `0085_old_swarm` adopters. - UI risk is mostly around text range anchoring and panel positioning across long documents, folded content, and mobile layouts; the PR includes focused unit coverage and design screenshots. > 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, GPT-5 coding agent, tool-using software engineering mode. Context window size is not exposed in this Paperclip 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
70 lines
3.4 KiB
TypeScript
70 lines
3.4 KiB
TypeScript
import type {
|
|
DocumentAnnotationAnchorConfidence,
|
|
DocumentAnnotationAnchorSelector,
|
|
DocumentAnnotationAnchorState,
|
|
DocumentAnnotationThreadStatus,
|
|
} from "@paperclipai/shared";
|
|
import { index, integer, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
|
|
import { agents } from "./agents.js";
|
|
import { companies } from "./companies.js";
|
|
import { documentRevisions } from "./document_revisions.js";
|
|
import { documents } from "./documents.js";
|
|
import { issues } from "./issues.js";
|
|
|
|
export const documentAnnotationThreads = pgTable(
|
|
"document_annotation_threads",
|
|
{
|
|
id: uuid("id").primaryKey().defaultRandom(),
|
|
companyId: uuid("company_id").notNull().references(() => companies.id),
|
|
issueId: uuid("issue_id").notNull().references(() => issues.id, { onDelete: "cascade" }),
|
|
documentId: uuid("document_id").notNull().references(() => documents.id, { onDelete: "cascade" }),
|
|
documentKey: text("document_key").notNull(),
|
|
status: text("status").$type<DocumentAnnotationThreadStatus>().notNull().default("open"),
|
|
anchorState: text("anchor_state").$type<DocumentAnnotationAnchorState>().notNull().default("active"),
|
|
originalRevisionId: uuid("original_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
|
|
originalRevisionNumber: integer("original_revision_number").notNull(),
|
|
currentRevisionId: uuid("current_revision_id").references(() => documentRevisions.id, { onDelete: "set null" }),
|
|
currentRevisionNumber: integer("current_revision_number").notNull(),
|
|
selectedText: text("selected_text").notNull(),
|
|
prefixText: text("prefix_text").notNull().default(""),
|
|
suffixText: text("suffix_text").notNull().default(""),
|
|
normalizedStart: integer("normalized_start").notNull(),
|
|
normalizedEnd: integer("normalized_end").notNull(),
|
|
markdownStart: integer("markdown_start").notNull(),
|
|
markdownEnd: integer("markdown_end").notNull(),
|
|
anchorConfidence: text("anchor_confidence")
|
|
.$type<DocumentAnnotationAnchorConfidence>()
|
|
.notNull()
|
|
.default("exact"),
|
|
anchorSelector: jsonb("anchor_selector").$type<DocumentAnnotationAnchorSelector>().notNull(),
|
|
createdByAgentId: uuid("created_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
|
createdByUserId: text("created_by_user_id"),
|
|
resolvedByAgentId: uuid("resolved_by_agent_id").references(() => agents.id, { onDelete: "set null" }),
|
|
resolvedByUserId: text("resolved_by_user_id"),
|
|
resolvedAt: timestamp("resolved_at", { withTimezone: true }),
|
|
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
|
|
updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
|
|
},
|
|
(table) => ({
|
|
companyDocumentStatusIdx: index("document_annotation_threads_company_document_status_idx").on(
|
|
table.companyId,
|
|
table.documentId,
|
|
table.status,
|
|
),
|
|
companyIssueStatusIdx: index("document_annotation_threads_company_issue_status_idx").on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.status,
|
|
),
|
|
companyCurrentRevisionOpenIdx: index("document_annotation_threads_company_current_revision_open_idx").on(
|
|
table.companyId,
|
|
table.documentId,
|
|
table.currentRevisionId,
|
|
table.status,
|
|
),
|
|
companyAnchorStateIdx: index("document_annotation_threads_company_anchor_state_idx").on(
|
|
table.companyId,
|
|
table.anchorState,
|
|
),
|
|
}),
|
|
);
|