Expand plugin host surface (#5205)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - The plugin system is the extension boundary for optional product
capabilities
> - Rich plugins need more than a worker entrypoint: they need scoped
database storage, local project folders, managed agents/routines, host
navigation, and reusable UI components
> - The LLM Wiki work exposed those missing host surfaces while keeping
plugin code outside the core control plane
> - This pull request expands the core plugin host, SDK, server APIs,
and UI bridge so plugins can declare and use those surfaces
> - The benefit is that future plugins can integrate with Paperclip
through documented, validated contracts instead of bespoke server or UI
imports

## What Changed

- Added plugin-managed database namespaces and migration tracking,
including Drizzle schema/migration files and SQL validation for
namespace isolation.
- Added server support for plugin local folders, managed agents, managed
routines, scoped plugin APIs, and plugin operation visibility.
- Expanded shared plugin manifest/types/validators and SDK
host/testing/UI exports for richer plugin surfaces.
- Added reusable UI pieces for file trees, managed routines, resizable
sidebars, route sidebars, and plugin bridge initialization.
- Updated plugin docs and example plugins to use the expanded host and
SDK surface.

## Verification

- `pnpm install --frozen-lockfile`
- `pnpm run preflight:workspace-links && pnpm exec vitest run
packages/shared/src/validators/plugin.test.ts
server/src/__tests__/plugin-database.test.ts
server/src/__tests__/plugin-local-folders.test.ts
server/src/__tests__/plugin-managed-agents.test.ts
server/src/__tests__/plugin-managed-routines.test.ts
server/src/__tests__/plugin-orchestration-apis.test.ts
ui/src/api/plugins.test.ts ui/src/components/FileTree.test.tsx
ui/src/components/ResizableSidebarPane.test.tsx
ui/src/pages/PluginPage.test.tsx ui/src/plugins/bridge.test.ts` passed:
11 files, 67 tests.
- Confirmed this PR changes 89 files and does not include
`pnpm-lock.yaml` or `.github/workflows/*`.

## Risks

- Medium: this expands plugin host contracts across db/shared/server/ui
and includes a new core migration (`0076_useful_elektra.sql`).
- The plugin database namespace validator is intentionally restrictive;
plugin authors may need follow-up affordances for SQL patterns that
remain blocked.
- Merge this before the LLM Wiki plugin PR so the plugin can resolve the
new SDK and host APIs.

> 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-enabled shell/git/GitHub
workflow. Context window size was not exposed by the 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>

ui/src/components/PackageFileTree.tsx

@@ -1,326 +1,24 @@
-import type { ReactNode } from "react";
-import { cn } from "../lib/utils";
-import {
-  ChevronDown,
-  ChevronRight,
-  FileCode2,
-  FileText,
-  Folder,
-  FolderOpen,
-} from "lucide-react";
+import { FileTree } from "./FileTree";
+import type { FileTreeProps } from "./FileTree";
 
-// ── Tree types ────────────────────────────────────────────────────────
-
-export type FileTreeNode = {
-  name: string;
-  path: string;
-  kind: "dir" | "file";
-  children: FileTreeNode[];
-  /** Optional per-node metadata (e.g. import action) */
-  action?: string | null;
-};
-
-const TREE_BASE_INDENT = 16;
-const TREE_STEP_INDENT = 24;
-const TREE_ROW_HEIGHT_CLASS = "min-h-9";
-
-// ── Helpers ───────────────────────────────────────────────────────────
-
-export function buildFileTree(
-  files: Record<string, unknown>,
-  actionMap?: Map<string, string>,
-): FileTreeNode[] {
-  const root: FileTreeNode = { name: "", path: "", kind: "dir", children: [] };
-
-  for (const filePath of Object.keys(files)) {
-    const segments = filePath.split("/").filter(Boolean);
-    let current = root;
-    let currentPath = "";
-    for (let i = 0; i < segments.length; i++) {
-      const segment = segments[i];
-      currentPath = currentPath ? `${currentPath}/${segment}` : segment;
-      const isLeaf = i === segments.length - 1;
-      let next = current.children.find((c) => c.name === segment);
-      if (!next) {
-        next = {
-          name: segment,
-          path: currentPath,
-          kind: isLeaf ? "file" : "dir",
-          children: [],
-          action: isLeaf ? (actionMap?.get(filePath) ?? null) : null,
-        };
-        current.children.push(next);
-      }
-      current = next;
-    }
-  }
-
-  function sortNode(node: FileTreeNode) {
-    node.children.sort((a, b) => {
-      // Files before directories so PROJECT.md appears above tasks/
-      if (a.kind !== b.kind) return a.kind === "file" ? -1 : 1;
-      return a.name.localeCompare(b.name);
-    });
-    node.children.forEach(sortNode);
-  }
-
-  sortNode(root);
-  return root.children;
+export function PackageFileTree({ wrapLabels = false, ...props }: FileTreeProps) {
+  return <FileTree {...props} wrapLabels={wrapLabels} />;
 }
 
-export function countFiles(nodes: FileTreeNode[]): number {
-  let count = 0;
-  for (const node of nodes) {
-    if (node.kind === "file") count++;
-    else count += countFiles(node.children);
-  }
-  return count;
-}
-
-export function collectAllPaths(
-  nodes: FileTreeNode[],
-  type: "file" | "dir" | "all" = "all",
-): Set<string> {
-  const paths = new Set<string>();
-  for (const node of nodes) {
-    if (type === "all" || node.kind === type) paths.add(node.path);
-    for (const p of collectAllPaths(node.children, type)) paths.add(p);
-  }
-  return paths;
-}
-
-function fileIcon(name: string) {
-  if (name.endsWith(".yaml") || name.endsWith(".yml")) return FileCode2;
-  return FileText;
-}
-
-// ── Frontmatter helpers ───────────────────────────────────────────────
-
-export type FrontmatterData = Record<string, string | string[]>;
-
-export function parseFrontmatter(content: string): { data: FrontmatterData; body: string } | null {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
-  if (!match) return null;
-
-  const data: FrontmatterData = {};
-  const rawYaml = match[1];
-  const body = match[2];
-
-  let currentKey: string | null = null;
-  let currentList: string[] | null = null;
-
-  for (const line of rawYaml.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed || trimmed.startsWith("#")) continue;
-
-    if (trimmed.startsWith("- ") && currentKey) {
-      if (!currentList) currentList = [];
-      currentList.push(trimmed.slice(2).trim().replace(/^["']|["']$/g, ""));
-      continue;
-    }
-
-    if (currentKey && currentList) {
-      data[currentKey] = currentList;
-      currentList = null;
-      currentKey = null;
-    }
-
-    const kvMatch = trimmed.match(/^([a-zA-Z_][\w-]*)\s*:\s*(.*)$/);
-    if (kvMatch) {
-      const key = kvMatch[1];
-      const val = kvMatch[2].trim().replace(/^["']|["']$/g, "");
-      if (val === "null") {
-        currentKey = null;
-        continue;
-      }
-      if (val) {
-        data[key] = val;
-        currentKey = null;
-      } else {
-        currentKey = key;
-      }
-    }
-  }
-
-  if (currentKey && currentList) {
-    data[currentKey] = currentList;
-  }
-
-  return Object.keys(data).length > 0 ? { data, body } : null;
-}
-
-export const FRONTMATTER_FIELD_LABELS: Record<string, string> = {
-  name: "Name",
-  title: "Title",
-  kind: "Kind",
-  reportsTo: "Reports to",
-  skills: "Skills",
-  status: "Status",
-  description: "Description",
-  priority: "Priority",
-  assignee: "Assignee",
-  project: "Project",
-  recurring: "Recurring",
-  targetDate: "Target date",
-};
-
-// ── File tree component ───────────────────────────────────────────────
-
-export function PackageFileTree({
-  nodes,
-  selectedFile,
-  expandedDirs,
-  checkedFiles,
-  onToggleDir,
-  onSelectFile,
-  onToggleCheck,
-  renderFileExtra,
-  fileRowClassName,
-  showCheckboxes = true,
-  wrapLabels = false,
-  depth = 0,
-}: {
-  nodes: FileTreeNode[];
-  selectedFile: string | null;
-  expandedDirs: Set<string>;
-  checkedFiles?: Set<string>;
-  onToggleDir: (path: string) => void;
-  onSelectFile: (path: string) => void;
-  onToggleCheck?: (path: string, kind: "file" | "dir") => void;
-  /** Optional extra content rendered at the end of each file row (e.g. action badge) */
-  renderFileExtra?: (node: FileTreeNode, checked: boolean) => ReactNode;
-  /** Optional additional className for file rows */
-  fileRowClassName?: (node: FileTreeNode, checked: boolean) => string | undefined;
-  showCheckboxes?: boolean;
-  /** Allow long file and directory names to wrap instead of forcing horizontal overflow. */
-  wrapLabels?: boolean;
-  depth?: number;
-}) {
-  const effectiveCheckedFiles = checkedFiles ?? new Set<string>();
-
-  return (
-    <div>
-      {nodes.map((node) => {
-        const expanded = node.kind === "dir" && expandedDirs.has(node.path);
-        if (node.kind === "dir") {
-          const childFiles = collectAllPaths(node.children, "file");
-          const allChecked = [...childFiles].every((p) => effectiveCheckedFiles.has(p));
-          const someChecked = [...childFiles].some((p) => effectiveCheckedFiles.has(p));
-          return (
-            <div key={node.path}>
-              <div
-                className={cn(
-                  showCheckboxes
-                    ? "group grid w-full grid-cols-[auto_minmax(0,1fr)_2.25rem] items-center gap-x-1 pr-3 text-left text-sm text-muted-foreground hover:bg-accent/30 hover:text-foreground"
-                    : "group grid w-full grid-cols-[minmax(0,1fr)_2.25rem] items-center gap-x-1 pr-3 text-left text-sm text-muted-foreground hover:bg-accent/30 hover:text-foreground",
-                  TREE_ROW_HEIGHT_CLASS,
-                )}
-                style={{
-                  paddingInlineStart: `${TREE_BASE_INDENT + depth * TREE_STEP_INDENT - 8}px`,
-                }}
-              >
-                {showCheckboxes && (
-                  <label className="flex items-center pl-2">
-                    <input
-                      type="checkbox"
-                      checked={allChecked}
-                      ref={(el) => { if (el) el.indeterminate = someChecked && !allChecked; }}
-                      onChange={() => onToggleCheck?.(node.path, "dir")}
-                      className="mr-2 accent-foreground"
-                    />
-                  </label>
-                )}
-                <button
-                  type="button"
-                  className="flex min-w-0 items-center gap-2 py-1 text-left"
-                  onClick={() => onToggleDir(node.path)}
-                >
-                  <span className="flex h-4 w-4 shrink-0 items-center justify-center">
-                    {expanded ? (
-                      <FolderOpen className="h-3.5 w-3.5" />
-                    ) : (
-                      <Folder className="h-3.5 w-3.5" />
-                    )}
-                  </span>
-                  <span className={cn("min-w-0", wrapLabels ? "break-all leading-4" : "truncate")}>
-                    {node.name}
-                  </span>
-                </button>
-                <button
-                  type="button"
-                  className="flex h-9 w-9 items-center justify-center self-center rounded-sm text-muted-foreground opacity-70 transition-[background-color,color,opacity] hover:bg-accent hover:text-foreground group-hover:opacity-100"
-                  onClick={() => onToggleDir(node.path)}
-                >
-                  {expanded ? (
-                    <ChevronDown className="h-3.5 w-3.5" />
-                  ) : (
-                    <ChevronRight className="h-3.5 w-3.5" />
-                  )}
-                </button>
-              </div>
-              {expanded && (
-                <PackageFileTree
-                  nodes={node.children}
-                  selectedFile={selectedFile}
-                  expandedDirs={expandedDirs}
-                  checkedFiles={effectiveCheckedFiles}
-                  onToggleDir={onToggleDir}
-                  onSelectFile={onSelectFile}
-                  onToggleCheck={onToggleCheck}
-                  renderFileExtra={renderFileExtra}
-                  fileRowClassName={fileRowClassName}
-                  showCheckboxes={showCheckboxes}
-                  wrapLabels={wrapLabels}
-                  depth={depth + 1}
-                />
-              )}
-            </div>
-          );
-        }
-
-        const FileIcon = fileIcon(node.name);
-        const checked = effectiveCheckedFiles.has(node.path);
-        const extraClassName = fileRowClassName?.(node, checked);
-        return (
-          <div
-            key={node.path}
-            className={cn(
-              "flex w-full items-center gap-1 pr-3 text-left text-sm text-muted-foreground hover:bg-accent/30 hover:text-foreground cursor-pointer",
-              TREE_ROW_HEIGHT_CLASS,
-              node.path === selectedFile && "text-foreground bg-accent/20",
-              extraClassName,
-            )}
-            style={{
-              paddingInlineStart: `${TREE_BASE_INDENT + depth * TREE_STEP_INDENT - 8}px`,
-            }}
-            onClick={() => onSelectFile(node.path)}
-          >
-            {showCheckboxes && (
-              <label className="flex items-center pl-2">
-                <input
-                  type="checkbox"
-                  checked={checked}
-                  onChange={() => onToggleCheck?.(node.path, "file")}
-                  className="mr-2 accent-foreground"
-                />
-              </label>
-            )}
-            <button
-              type="button"
-              className="flex min-w-0 flex-1 items-center gap-2 py-1 text-left"
-              onClick={() => onSelectFile(node.path)}
-            >
-              <span className="flex h-4 w-4 shrink-0 items-center justify-center">
-                <FileIcon className="h-3.5 w-3.5" />
-              </span>
-              <span className={cn("min-w-0", wrapLabels ? "break-all leading-4" : "truncate")}>
-                {node.name}
-              </span>
-            </button>
-            {renderFileExtra?.(node, checked)}
-          </div>
-        );
-      })}
-    </div>
-  );
-}
+export {
+  FRONTMATTER_FIELD_LABELS,
+  buildFileTree,
+  collectAllPaths,
+  countFiles,
+  parseFrontmatter,
+} from "./FileTree";
+export type {
+  FileTreeBadge,
+  FileTreeBadgeVariant,
+  FileTreeEmptyState,
+  FileTreeErrorState,
+  FileTreeNode,
+  FileTreeProps,
+  FileTreeTone,
+  FrontmatterData,
+} from "./FileTree";