Files
PaperClipAI/ui/src/components/folders/FolderControls.test.tsx
T
DottaandPaperclip 52aea90263 feat: organize skills with nested folders and My Skills (#9633)
## 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>
2026-07-16 15:50:45 -05:00

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);
});
});