mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-27 19:35:13 +01:00
## Thinking Path > - Paperclip is the open source control plane people use to organize and govern AI-agent companies > - Company skills are durable resources that users browse, import, assign, and maintain over time > - A flat skill list plus tags does not provide a stable location or hierarchy for personal, company, project-imported, and bundled skills > - Folder paths need to be canonical, company-scoped, safe to move, and preserved across re-imports without changing skill IDs > - The `/skills` UI also needs traversal, breadcrumbs, move/create flows, and a dedicated My Skills namespace that work on desktop and mobile > - This pull request adds the folder data model and APIs, reserved-root lifecycle, project import behavior, and the folder-first skills experience > - The benefit is a predictable filesystem-like organization model while tags remain available for cross-cutting classification ## Linked Issues or Issue Description Refs #9619 — the reviewed folder foundation was intentionally closed and folded into this combined feature PR. Refs #9026 — earlier flat-folder attempt superseded by this integrated implementation. Refs #3281 — related skill organization proposal; this PR uses canonical persisted folders rather than deriving groups from skill keys, and does not add hidden-skill behavior. **Feature request** - **Problem:** Skills currently lack a canonical hierarchical location, making personal skills, project imports, bundled skills, and company-authored skills difficult to traverse and manage at scale. - **Proposed behavior:** Add nested company-scoped folders with stable paths, reserved My/Projects/Bundled roots, subtree queries, safe move/create operations, and a folder-first `/skills` library UI. - **Import behavior:** New project scans file skills under `projects/<project-slug>`; later imports update content without overriding a user-selected folder. - **Alternatives considered:** Tags alone remain useful for cross-cutting classification, but they do not provide canonical location, nesting, reserved namespaces, or stable import placement. - **Roadmap alignment:** Extends the completed Skills Manager and Scheduled Routines capabilities without duplicating an active roadmap item. ## What Changed - Adds `folders` persistence for routine and skill folders, nested canonical paths, parent/slug/system-key fields, migration backfills, and reapply-safe migrations `0174`–`0175` after current master migrations. - Adds company-scoped folder CRUD, cycle/depth/namespace validation, reserved My/Projects/Bundled lifecycle, item moves, subtree filtering, and folder paths on skill results. - Preserves project-import placement: first import files into the project folder, while re-import keeps user-owned placement and stable skill IDs. - Adds the `/skills` folder tree rail, tags facet, breadcrumbs, subfolder browser, move/new-folder dialog, canonical detail location, inline tag editing, and folder-aware Studio creation. - Keeps bundled skills read-only even when their source metadata is incomplete by detecting the reserved Bundled folder and hiding selection/move actions. - Extends routine folder UI and OpenAPI coverage, and adds regression tests across migrations, services, routes, tree helpers, pages, and Studio creation. ## Verification - `pnpm exec vitest run packages/db/src/nested-skill-folders-migration.test.ts server/src/__tests__/folders-routes.test.ts server/src/__tests__/folders-service.test.ts server/src/__tests__/company-skills-service.test.ts server/src/__tests__/routines-service.test.ts ui/src/components/folders/FolderControls.test.tsx ui/src/components/folders/SkillFolderTree.test.tsx ui/src/components/folders/skill-folder-tree.test.ts ui/src/pages/CompanySkills.test.tsx ui/src/pages/Routines.test.tsx ui/src/pages/SkillStudio.test.tsx ui/src/lib/company-skill-routes.test.ts ui/src/lib/skill-create.test.ts` — 13 files, 192 tests passed. - `pnpm exec vitest run ui/src/pages/CompanySkills.test.tsx ui/src/components/folders/SkillFolderTree.test.tsx` — 2 files, 20 tests passed after preserving the existing PR's bundled-skill fixes. - `pnpm -r typecheck` — passed for all workspace packages. - `pnpm test:run` — passed in an isolated CI-like environment with inherited Paperclip runtime identity and static AWS credential variables removed. - `pnpm build` — production build passed for all workspace packages. - Greptile iteration 2 — 5/5 confidence with zero unresolved threads on commit `ff2d67aa71`. - Latest-head GitHub checks — all success, neutral, or skipped; PR is mergeable with a clean merge state. - `pnpm check:token-gates` — reports nine existing `#9627` comment false positives already present on `master`; this PR introduces no new token violation. ## Risks - **Migration/backfill:** `0174` creates the foundation and `0175` adds nested/reserved semantics. Both are ordered after current master migration `0173`, are covered by numbering/safety checks, and are designed to be reapply-safe. - **Reserved namespaces:** My, Projects, and Bundled roots are service-managed. Regression coverage prevents namespace squatting, cross-company folder use, bundled writes, cycles, and excessive depth. - **Behavioral change:** Project scans choose a project folder only on initial creation; existing skills deliberately retain their current folder during refresh. - **UI scope:** The folder rail applies to the Installed library; Catalog retains the discovery-oriented category sidebar. > 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.5` in Codex CLI, medium reasoning mode; runtime did not expose a context-window value. Used repository/file tools, terminal execution, Git/GitHub operations, test execution, and code editing. ## 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 - [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>
481 lines
14 KiB
TypeScript
481 lines
14 KiB
TypeScript
// @vitest-environment jsdom
|
|
|
|
import { flushSync } from "react-dom";
|
|
import { createRoot, type Root } from "react-dom/client";
|
|
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
|
import type { FolderListResult } from "@paperclipai/shared";
|
|
import {
|
|
AllUnfiledBanner,
|
|
BulkBar,
|
|
DeleteFolderDialog,
|
|
FolderFormDialog,
|
|
FolderRail,
|
|
MobileFolderSheet,
|
|
MoveToMenu,
|
|
folderSearchValue,
|
|
normalizeFolderSelection,
|
|
} from "./FolderControls";
|
|
import {
|
|
DropdownMenu,
|
|
DropdownMenuContent,
|
|
DropdownMenuTrigger,
|
|
} from "@/components/ui/dropdown-menu";
|
|
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
|
|
|
|
if (!globalThis.PointerEvent) {
|
|
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
(globalThis as any).PointerEvent = MouseEvent;
|
|
}
|
|
if (!Element.prototype.hasPointerCapture) {
|
|
Element.prototype.hasPointerCapture = () => false;
|
|
}
|
|
if (!Element.prototype.scrollIntoView) {
|
|
Element.prototype.scrollIntoView = () => undefined;
|
|
}
|
|
|
|
function act(callback: () => void | Promise<void>) {
|
|
let result: void | Promise<void> | undefined;
|
|
flushSync(() => {
|
|
result = callback();
|
|
});
|
|
return result;
|
|
}
|
|
|
|
const folderResult: FolderListResult = {
|
|
kind: "routine",
|
|
allCount: 4,
|
|
unfiledCount: 1,
|
|
folders: [
|
|
{
|
|
id: "folder-reporting",
|
|
companyId: "company-1",
|
|
kind: "routine",
|
|
parentId: null,
|
|
name: "Reporting",
|
|
slug: "reporting",
|
|
systemKey: null,
|
|
path: "reporting",
|
|
depth: 1,
|
|
color: "indigo",
|
|
position: 0,
|
|
itemCount: 3,
|
|
createdAt: new Date("2026-07-01T00:00:00.000Z"),
|
|
updatedAt: new Date("2026-07-01T00:00:00.000Z"),
|
|
},
|
|
],
|
|
};
|
|
|
|
const skillFolderResult: FolderListResult = {
|
|
kind: "skill",
|
|
allCount: 8,
|
|
unfiledCount: 1,
|
|
folders: [
|
|
{
|
|
...folderResult.folders[0]!,
|
|
id: "my",
|
|
kind: "skill",
|
|
name: "my",
|
|
slug: "my",
|
|
systemKey: "my",
|
|
path: "my",
|
|
itemCount: 1,
|
|
},
|
|
{
|
|
...folderResult.folders[0]!,
|
|
id: "engineering",
|
|
kind: "skill",
|
|
name: "Engineering",
|
|
slug: "engineering",
|
|
path: "engineering",
|
|
itemCount: 3,
|
|
},
|
|
{
|
|
...folderResult.folders[0]!,
|
|
id: "code-review",
|
|
kind: "skill",
|
|
parentId: "engineering",
|
|
name: "Code Review",
|
|
slug: "code-review",
|
|
path: "engineering/code-review",
|
|
depth: 2,
|
|
itemCount: 2,
|
|
},
|
|
{
|
|
...folderResult.folders[0]!,
|
|
id: "projects",
|
|
kind: "skill",
|
|
name: "projects",
|
|
slug: "projects",
|
|
systemKey: "projects",
|
|
path: "projects",
|
|
itemCount: 2,
|
|
},
|
|
{
|
|
...folderResult.folders[0]!,
|
|
id: "bundled",
|
|
kind: "skill",
|
|
name: "bundled",
|
|
slug: "bundled",
|
|
systemKey: "bundled",
|
|
path: "bundled",
|
|
itemCount: 1,
|
|
},
|
|
],
|
|
};
|
|
|
|
describe("FolderControls", () => {
|
|
let container: HTMLDivElement;
|
|
let root: Root | null;
|
|
|
|
beforeEach(() => {
|
|
container = document.createElement("div");
|
|
document.body.appendChild(container);
|
|
root = null;
|
|
});
|
|
|
|
afterEach(() => {
|
|
if (root) {
|
|
act(() => {
|
|
root?.unmount();
|
|
});
|
|
}
|
|
container.remove();
|
|
document.body.innerHTML = "";
|
|
});
|
|
|
|
it("normalizes URL selection values for folder persistence", () => {
|
|
expect(normalizeFolderSelection(null)).toBe("all");
|
|
expect(normalizeFolderSelection("unfiled")).toBe("unfiled");
|
|
expect(normalizeFolderSelection("folder-reporting")).toBe("folder-reporting");
|
|
expect(folderSearchValue("all")).toBe("");
|
|
expect(folderSearchValue("unfiled")).toBe("unfiled");
|
|
expect(folderSearchValue("folder-reporting")).toBe("folder-reporting");
|
|
});
|
|
|
|
it("renders All, user folders, and Unfiled with counts and selection callbacks", () => {
|
|
const onSelect = vi.fn();
|
|
root = createRoot(container);
|
|
|
|
act(() => {
|
|
root?.render(
|
|
<FolderRail
|
|
result={folderResult}
|
|
selection="all"
|
|
itemLabelPlural="routines"
|
|
allLabel="All routines"
|
|
onSelect={onSelect}
|
|
onCreate={vi.fn()}
|
|
onRename={vi.fn()}
|
|
onEdit={vi.fn()}
|
|
onDelete={vi.fn()}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
expect(container.textContent).toContain("All routines");
|
|
expect(container.textContent).toContain("Reporting");
|
|
expect(container.textContent).toContain("Unfiled");
|
|
expect(container.textContent).toContain("4");
|
|
expect(container.textContent).toContain("3");
|
|
expect(container.textContent).toContain("1");
|
|
|
|
const reportingButton = Array.from(container.querySelectorAll("button")).find((button) =>
|
|
button.textContent?.includes("Reporting"),
|
|
);
|
|
expect(reportingButton).toBeTruthy();
|
|
|
|
act(() => {
|
|
reportingButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
|
|
expect(onSelect).toHaveBeenCalledWith("folder-reporting");
|
|
});
|
|
|
|
it("marks the active row with aria-current, including virtual Unfiled", () => {
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<FolderRail
|
|
result={folderResult}
|
|
selection="unfiled"
|
|
itemLabelPlural="routines"
|
|
allLabel="All routines"
|
|
onSelect={vi.fn()}
|
|
onCreate={vi.fn()}
|
|
onRename={vi.fn()}
|
|
onEdit={vi.fn()}
|
|
onDelete={vi.fn()}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
const current = container.querySelector('[aria-current="page"]');
|
|
expect(current?.textContent).toContain("Unfiled");
|
|
});
|
|
|
|
it("renames a folder inline via double-click and Enter", () => {
|
|
const onRename = vi.fn();
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<FolderRail
|
|
result={folderResult}
|
|
selection="all"
|
|
itemLabelPlural="routines"
|
|
allLabel="All routines"
|
|
onSelect={vi.fn()}
|
|
onCreate={vi.fn()}
|
|
onRename={onRename}
|
|
onEdit={vi.fn()}
|
|
onDelete={vi.fn()}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
const nameButton = Array.from(container.querySelectorAll("button")).find((button) =>
|
|
button.textContent?.includes("Reporting"),
|
|
);
|
|
act(() => {
|
|
nameButton?.dispatchEvent(new MouseEvent("dblclick", { bubbles: true, cancelable: true }));
|
|
});
|
|
|
|
const input = container.querySelector<HTMLInputElement>("input");
|
|
expect(input).toBeTruthy();
|
|
expect(input?.value).toBe("Reporting");
|
|
|
|
act(() => {
|
|
if (!input) return;
|
|
const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
|
|
setter?.call(input, "Monthly reports");
|
|
input.dispatchEvent(new Event("input", { bubbles: true }));
|
|
});
|
|
act(() => {
|
|
input?.dispatchEvent(new KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
|
|
});
|
|
|
|
expect(onRename).toHaveBeenCalledWith(folderResult.folders[0], "Monthly reports");
|
|
});
|
|
|
|
it("moves via MoveToMenu: Unfiled, a folder, and new-folder chaining", () => {
|
|
const onMove = vi.fn();
|
|
const onCreateAndMove = vi.fn();
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<DropdownMenu open modal={false}>
|
|
<DropdownMenuTrigger asChild>
|
|
<button type="button">Row actions</button>
|
|
</DropdownMenuTrigger>
|
|
<DropdownMenuContent>
|
|
<MoveToMenu
|
|
folders={folderResult.folders}
|
|
currentFolderId={null}
|
|
onMove={onMove}
|
|
onCreateAndMove={onCreateAndMove}
|
|
/>
|
|
</DropdownMenuContent>
|
|
</DropdownMenu>,
|
|
);
|
|
});
|
|
|
|
const subTrigger = Array.from(document.querySelectorAll("[data-radix-collection-item]")).find(
|
|
(element) => element.textContent?.includes("Move to"),
|
|
);
|
|
expect(subTrigger).toBeTruthy();
|
|
act(() => {
|
|
subTrigger?.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }));
|
|
});
|
|
|
|
const menuItems = Array.from(document.querySelectorAll('[role="menuitem"]'));
|
|
const unfiledItem = menuItems.find((element) => element.textContent?.includes("Unfiled"));
|
|
const folderItem = menuItems.find((element) => element.textContent?.includes("Reporting"));
|
|
const newFolderItem = menuItems.find((element) => element.textContent?.includes("New folder"));
|
|
expect(unfiledItem).toBeTruthy();
|
|
expect(folderItem).toBeTruthy();
|
|
expect(newFolderItem).toBeTruthy();
|
|
|
|
act(() => {
|
|
unfiledItem?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
expect(onMove).toHaveBeenCalledWith(null);
|
|
|
|
act(() => {
|
|
folderItem?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
expect(onMove).toHaveBeenCalledWith("folder-reporting");
|
|
|
|
act(() => {
|
|
newFolderItem?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
expect(onCreateAndMove).toHaveBeenCalled();
|
|
});
|
|
|
|
it("creates a folder through FolderFormDialog and disables submit on empty name", () => {
|
|
const onSubmit = vi.fn();
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<FolderFormDialog
|
|
open
|
|
kind="routine"
|
|
folder={null}
|
|
onOpenChange={vi.fn()}
|
|
onSubmit={onSubmit}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
const submit = Array.from(document.querySelectorAll("button")).find(
|
|
(button) => button.textContent === "Create folder",
|
|
) as HTMLButtonElement | undefined;
|
|
expect(submit).toBeTruthy();
|
|
expect(submit?.disabled).toBe(true);
|
|
|
|
const nameInput = document.querySelector<HTMLInputElement>("#folder-name");
|
|
act(() => {
|
|
if (!nameInput) return;
|
|
const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
|
|
setter?.call(nameInput, "Reporting");
|
|
nameInput.dispatchEvent(new Event("input", { bubbles: true }));
|
|
});
|
|
|
|
expect(submit?.disabled).toBe(false);
|
|
act(() => {
|
|
submit?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
expect(onSubmit).toHaveBeenCalledWith({ name: "Reporting", color: expect.any(String) });
|
|
});
|
|
|
|
it("states the forgiving delete behavior and confirms", () => {
|
|
const onConfirm = vi.fn();
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<DeleteFolderDialog
|
|
open
|
|
folder={folderResult.folders[0]!}
|
|
itemLabelPlural="routines"
|
|
onOpenChange={vi.fn()}
|
|
onConfirm={onConfirm}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
expect(document.body.textContent).toContain("3 routines in this folder won't be deleted");
|
|
expect(document.body.textContent).toContain("They'll move to Unfiled");
|
|
|
|
const confirmButton = Array.from(document.querySelectorAll("button")).find(
|
|
(button) => button.textContent === "Delete folder",
|
|
);
|
|
act(() => {
|
|
confirmButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
expect(onConfirm).toHaveBeenCalled();
|
|
});
|
|
|
|
it("selects a folder from the mobile sheet and dismisses", () => {
|
|
const onSelect = vi.fn();
|
|
const onOpenChange = vi.fn();
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<MobileFolderSheet
|
|
open
|
|
onOpenChange={onOpenChange}
|
|
result={folderResult}
|
|
selection="all"
|
|
allLabel="All routines"
|
|
itemLabelPlural="Routines"
|
|
onSelect={onSelect}
|
|
onCreate={vi.fn()}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
expect(document.body.textContent).toContain("All routines");
|
|
expect(document.body.textContent).toContain("Unfiled");
|
|
|
|
const reportingRow = Array.from(document.querySelectorAll("button")).find(
|
|
(button) => button.textContent?.includes("Reporting"),
|
|
);
|
|
act(() => {
|
|
reportingRow?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
|
|
expect(onSelect).toHaveBeenCalledWith("folder-reporting");
|
|
expect(onOpenChange).toHaveBeenCalledWith(false);
|
|
});
|
|
|
|
it("preserves skill root grouping and child hierarchy in the mobile sheet", () => {
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<MobileFolderSheet
|
|
open
|
|
onOpenChange={vi.fn()}
|
|
result={skillFolderResult}
|
|
selection="all"
|
|
allLabel="All skills"
|
|
itemLabelPlural="Skills"
|
|
onSelect={vi.fn()}
|
|
onCreate={vi.fn()}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
const body = document.body.textContent ?? "";
|
|
expect(body.indexOf("My Skills")).toBeLessThan(body.indexOf("Company"));
|
|
expect(body.indexOf("Company")).toBeLessThan(body.indexOf("Engineering"));
|
|
expect(body.indexOf("Engineering")).toBeLessThan(body.indexOf("Code Review"));
|
|
expect(body.indexOf("Code Review")).toBeLessThan(body.indexOf("Projects"));
|
|
expect(body.indexOf("Projects")).toBeLessThan(body.indexOf("Bundled"));
|
|
expect(document.querySelector('[data-folder-id="engineering"] > .pl-3 [data-folder-id="code-review"]')).not.toBeNull();
|
|
});
|
|
|
|
it("persists AllUnfiledBanner dismissal across mounts", () => {
|
|
const storageKey = "paperclip:test-folder-nudge";
|
|
window.localStorage.removeItem(storageKey);
|
|
const onCreateFolder = vi.fn();
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<AllUnfiledBanner
|
|
storageKey={storageKey}
|
|
itemLabelPlural="routines"
|
|
onCreateFolder={onCreateFolder}
|
|
/>,
|
|
);
|
|
});
|
|
|
|
expect(container.textContent).toContain("Create your first folder");
|
|
|
|
const dismissButton = container.querySelector<HTMLButtonElement>(
|
|
'button[aria-label="Dismiss folder suggestion"]',
|
|
);
|
|
act(() => {
|
|
dismissButton?.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
|
|
});
|
|
|
|
expect(container.textContent).not.toContain("Create your first folder");
|
|
expect(window.localStorage.getItem(storageKey)).toBe("1");
|
|
|
|
act(() => {
|
|
root?.unmount();
|
|
});
|
|
root = createRoot(container);
|
|
act(() => {
|
|
root?.render(
|
|
<AllUnfiledBanner
|
|
storageKey={storageKey}
|
|
itemLabelPlural="routines"
|
|
onCreateFolder={onCreateFolder}
|
|
/>,
|
|
);
|
|
});
|
|
expect(container.textContent).not.toContain("Create your first folder");
|
|
window.localStorage.removeItem(storageKey);
|
|
});
|
|
});
|