kennel 0.2.13 → 0.2.15

package/kernel/packages/api/src/server/folder-metadata-plugin.ts

@@ -1,1591 +0,0 @@
-import { createHash } from "node:crypto";
-import { sendContract, validateQuery } from "./contracts";
-import { realpathSync } from "node:fs";
-import { readdir, readFile, stat } from "node:fs/promises";
-import { homedir } from "node:os";
-import {
-  basename,
-  dirname,
-  extname,
-  isAbsolute,
-  relative,
-  resolve,
-  sep,
-} from "node:path";
-import type { ServerResponse } from "node:http";
-import type { ApiHost } from "./host";
-import { markdownMetadata } from "@raggle-ai/markdown";
-import { readFolder } from "@raggle-ai/markdown/node";
-import { execFile } from "node:child_process";
-import { sameOrigin } from "kennel-plugins/endpoint";
-
-import type { FolderPluginServer } from "kennel-plugins/server";
-import type { LocalMarkdownFileSummary, LocalProject } from "@raggle-ai/local";
-import { runApiRoute } from "kennel-plugins/endpoint";
-import { FolderPluginFailure } from "kennel-plugins/server";
-import { folderWorkspace } from "@raggle-ai/schemas/workspace";
-import { createSchemaCollectionServer } from "@raggle-ai/schemas/server";
-import local from "@raggle-ai/local";
-import {
-  listFolderSessions,
-  readSessionTranscript,
-} from "@raggle-ai/session-finding";
-
-import { loadEntityWorkspace } from "./entity-folder.js";
-import { documentEditRoute } from "./api/document-edit";
-import { createAgentFileRoute } from "./api/create-agent-file";
-import { openPathRoute } from "./api/open-path";
-import { folderWebsite } from "./folder-favicon.js";
-import { folderIcon, workspaceBreadcrumbIcons } from "./folder-icons.js";
-import { faviconService } from "@raggle-ai/schemas/favicon";
-import {
-  configuredFolderServerRegistry,
-  externalApiHandlers,
-  folderServerRegistryAsync,
-  type FolderPluginRegistryConfig,
-} from "./plugins.js";
-import { createProjectDiscovery } from "./project-discovery";
-import {
-  createLinkedFolderDiscovery,
-  type LinkedFolderLoader,
-} from "./linked-folder-discovery";
-import {
-  mediaRawMime,
-  previewKind,
-  previewRawMime,
-  previewTextKind,
-} from "@raggle-ai/kennel-kinds";
-
-const {
-  applyProjectFavorites,
-  buildProjectCatalog,
-  buildProjectSearchIndex,
-  catalogProjectToLocalProject,
-  discoverProjectIcon,
-  discoverProjectsUnderFolder,
-  listLocalMarkdownFiles,
-  projectRepositoryAccessory,
-  projectSubtitle,
-  projectTitle,
-  readRaggleUserSettings,
-  searchProjectIndex,
-  sortProjectList,
-} = local;
-
-type IconAsset = {
-  mediaType: "image/jpeg" | "image/png";
-  source: "local" | "favicon";
-  url: string;
-};
-
-type ProjectWithIcon = {
-  iconAssetKey?: string;
-  worktree: string;
-};
-
-const maxIconBytes = 512 * 1024;
-const iconTypes = new Map<string, "image/jpeg" | "image/png">([
-  [".jpeg", "image/jpeg"],
-  [".jpg", "image/jpeg"],
-  [".png", "image/png"],
-]);
-const iconExtensions = new Map<"image/jpeg" | "image/png", string>([
-  ["image/jpeg", "jpg"],
-  ["image/png", "png"],
-]);
-const searchIconTypes = new Map<string, string>([
-  [".gif", "image/gif"],
-  [".ico", "image/x-icon"],
-  [".jpeg", "image/jpeg"],
-  [".jpg", "image/jpeg"],
-  [".png", "image/png"],
-  [".svg", "image/svg+xml"],
-  [".webp", "image/webp"],
-]);
-
-type SessionFinding = {
-  listFolderSessions: typeof listFolderSessions;
-  readSessionTranscript: typeof readSessionTranscript;
-};
-
-export type FolderMetadataPluginOptions = {
-  viewerName?: string;
-  restrictToRoot?: boolean;
-  root: string;
-  sessionFinding?: SessionFinding;
-  /** Override isolated linked-project discovery, for tests. */
-  linkedFolderLoader?: LinkedFolderLoader;
-  /**
-   * Serve an explicitly remote address (0.0.0.0/LAN). Disables server host
-   * actions (open in default app) and ACP live sessions; the plugin reports
-   * a capability surface the client can render against.
-   */
-  remoteAccess?: boolean;
-  /**
-   * Single-file pop lock (`kennel pop <file>`): document reads (and metadata
-   * file listings) resolve only this one file; siblings are not served.
-   */
-  lockedFile?: string;
-};
-
-type LocalProjectSearchCache = {
-  index: ReturnType<typeof buildProjectSearchIndex<LocalProject>>;
-  loadedAt: number;
-};
-
-const projectSearchCacheMs = 5_000;
-
-const metadataExtensions = new Set([
-  ".html",
-  ".jpeg",
-  ".jpg",
-  ".json",
-  ".md",
-  ".png",
-  ".rtf",
-  ".svg",
-  ".txt",
-]);
-
-function metadataFile(path: string, root: string) {
-  const candidate = relative(root, path);
-  if (!candidate || candidate.startsWith("..") || isAbsolute(candidate))
-    return false;
-  const parts = candidate.split(sep);
-  if (parts.some((part) => part === "node_modules")) return false;
-  return metadataExtensions.has(extname(candidate).toLowerCase());
-}
-
-async function configuredAiInputModule(folder: string) {
-  const config = folderWorkspace(folder).config as {
-    aiInput?: { module?: unknown };
-  };
-  const module = config.aiInput?.module;
-  return typeof module === "string" && module.trim() ? module.trim() : null;
-}
-
-function label(value: string) {
-  return value
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .replace(/[-_]+/g, " ")
-    .replace(/\b\w/g, (match) => match.toUpperCase());
-}
-
-function folderPath(value: string | null, root: string, lockedRoot?: string) {
-  const folder = realpathSync(resolve(value ?? root));
-  if (!lockedRoot) return folder;
-  const path = relative(lockedRoot, folder);
-  if (!path || (!path.startsWith("..") && !isAbsolute(path))) return folder;
-  throw new Error(`Folder is outside the viewer root: ${folder}`);
-}
-
-function openPathHref(path: string) {
-  const url = new URL("/api/open-path", "http://127.0.0.1");
-  url.searchParams.set("path", path);
-  return `${url.pathname}${url.search}`;
-}
-
-const loopbackServerHosts = new Set([
-  "127.0.0.1",
-  "::1",
-  "localhost",
-  undefined,
-  false,
-] as const);
-
-export function isLoopbackServerHost(host: unknown): boolean {
-  if (host === undefined || host === false) return true;
-  if (typeof host !== "string") return false;
-  return (
-    loopbackServerHosts.has(host as "localhost") ||
-    host.startsWith("127.") ||
-    host === "::ffff:127.0.0.1"
-  );
-}
-
-/**
- * DNS-rebinding guard for the API middleware. Loopback aliases always pass;
- * remote servers additionally accept IP literals, `.local` mDNS names, and
- * hosts from the environment allowlist (`KENNEL_VIEWER_HOSTS`). Arbitrary
- * domain Host headers are rejected before any data is served.
- */
-export function apiHostAllowed(
-  value: string | undefined,
-  remote: boolean,
-): boolean {
-  // A request without a Host header is not a browser (curl, tests, bots):
-  // DNS-rebinding protection targets browser requests, which always send
-  // Host, so missing-host requests stay allowed. Arbitrary domain Host
-  // headers are still rejected before any data is served.
-  if (!value) return true;
-  let hostname = value;
-  try {
-    const parsed = new URL(
-      hostname.includes("://") ? hostname : `http://${hostname}`,
-    );
-    hostname = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
-  } catch {
-    return false;
-  }
-  if (isLoopbackServerHost(hostname)) return true;
-  if (!remote) return false;
-  if (/^[\d.]+$/.test(hostname) || hostname.includes(":")) return true;
-  if (hostname.endsWith(".local") || !hostname.includes(".")) return true;
-  const allowlist = (process.env.KENNEL_VIEWER_HOSTS ?? "")
-    .split(",")
-    .map((host) => host.trim().toLowerCase())
-    .filter(Boolean);
-  return allowlist.includes(hostname);
-}
-
-function assetKey(value: Buffer) {
-  return createHash("sha256").update(value).digest("hex");
-}
-
-function encodeBase64Url(value: string) {
-  return Buffer.from(value, "utf8")
-    .toString("base64")
-    .replaceAll("+", "-")
-    .replaceAll("/", "_")
-    .replaceAll("=", "");
-}
-
-function decodeBase64Url(value: string) {
-  const padded = `${value}${"=".repeat((4 - (value.length % 4)) % 4)}`;
-  return Buffer.from(
-    padded.replaceAll("-", "+").replaceAll("_", "/"),
-    "base64",
-  ).toString("utf8");
-}
-
-function iconUrl(
-  folder: string,
-  hash: string,
-  mediaType: IconAsset["mediaType"],
-) {
-  return `/api/folders/${encodeBase64Url(folder)}/assets/${hash}.${iconExtensions.get(mediaType)}`;
-}
-
-async function searchIconDataUrl(icon: string | undefined) {
-  if (!icon) return undefined;
-  if (icon.startsWith("data:")) return icon;
-
-  const mediaType = searchIconTypes.get(extname(icon).toLowerCase());
-  if (!mediaType) return undefined;
-
-  const details = await stat(icon).catch(() => undefined);
-  if (!details?.size || details.size > maxIconBytes) return undefined;
-
-  return `data:${mediaType};base64,${(await readFile(icon)).toString("base64")}`;
-}
-
-async function iconWithFaviconFallback(
-  folder: string,
-  assets: Record<string, IconAsset>,
-  assetFiles: Map<string, { mediaType: IconAsset["mediaType"]; path: string }>,
-) {
-  return folderIcon(folder, assets, assetFiles, async (folderName) => {
-    if (process.env.KENNEL_EXTERNAL_ICONS !== "1") return undefined;
-    const host = await folderWebsite(folderName);
-    if (!host) return undefined;
-    const key = `favicon:${host}`;
-    assets[key] = {
-      mediaType: "image/png",
-      source: "favicon",
-      url: `/api/folder-favicon?path=${encodeURIComponent(folderName)}&host=${encodeURIComponent(host)}`,
-    };
-    return key;
-  });
-}
-
-async function hydrateAssets(
-  metadata: {
-    folder: string;
-    projects?: { items: ProjectWithIcon[] };
-  },
-  assetFiles: Map<string, { mediaType: IconAsset["mediaType"]; path: string }>,
-) {
-  const assets: Record<string, IconAsset> = {};
-  const projects = metadata.projects?.items ?? [];
-  const [iconAssetKey, projectItems] = await Promise.all([
-    iconWithFaviconFallback(metadata.folder, assets, assetFiles),
-    Promise.all(
-      projects.map(async (project) => ({
-        ...project,
-        iconAssetKey: await iconWithFaviconFallback(
-          project.worktree,
-          assets,
-          assetFiles,
-        ),
-      })),
-    ),
-  ]);
-  return {
-    assets,
-    iconAssetKey,
-    projects: { items: projectItems },
-  };
-}
-
-function unique(values: string[]) {
-  return [...new Set(values)];
-}
-
-function isMachineRoot(folder: string) {
-  return folder === homedir() || dirname(folder) === folder;
-}
-
-async function shallowMetadata(folder: string) {
-  const entries = await readdir(folder, { withFileTypes: true });
-  const visible = entries.filter(
-    (entry) => !entry.name.startsWith(".") && entry.name !== "node_modules",
-  );
-  const files = await Promise.all(
-    visible
-      .filter(
-        (entry) =>
-          entry.isFile() &&
-          [".markdown", ".md"].includes(extname(entry.name).toLowerCase()),
-      )
-      .map(async (entry) => {
-        const path = resolve(folder, entry.name);
-        const details = await stat(path);
-        const content = await readFile(path, "utf8").catch(() => "");
-        const title = markdownMetadata(content).title;
-        return {
-          activityAt: details.mtimeMs,
-          localEditAt: details.mtimeMs,
-          name: title ?? entry.name,
-          openHref: openPathHref(path),
-          path,
-          relativePath: entry.name,
-          size: details.size,
-        };
-      }),
-  );
-  const projects = visible
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => ({
-      id: createHash("sha1").update(resolve(folder, entry.name)).digest("hex"),
-      name: entry.name,
-      relativePath: entry.name,
-      worktree: resolve(folder, entry.name),
-    }))
-    .sort((left, right) => left.name.localeCompare(right.name));
-
-  return {
-    changes: { items: [] },
-    files: {
-      items: files.sort((left, right) => right.activityAt - left.activityAt),
-    },
-    folder,
-    instructions: { items: [] },
-    projects: { items: projects },
-    schemaVersion: 3 as const,
-    sessions: { items: [] },
-  };
-}
-
-async function loadFolderData(folder: string) {
-  const [files, projects] = await Promise.all([
-    listLocalMarkdownFiles({ folder, limit: 200 }),
-    discoverProjectsUnderFolder({ folder }),
-  ]);
-  return {
-    files: { items: files },
-    folder,
-    projects: {
-      items: projects.map((project) => ({
-        id: project.id,
-        worktree: project.worktree,
-        name: project.name ?? basename(project.worktree),
-        relativePath: relative(folder, project.worktree),
-      })),
-    },
-  };
-}
-
-async function notesFiles(
-  folder: string,
-  files: LocalMarkdownFileSummary[],
-  origin?: string,
-) {
-  return {
-    items: await Promise.all(
-      files.map(async (file) => {
-        const path =
-          file.path ??
-          (file.relativePath ? resolve(folder, file.relativePath) : undefined);
-        if (!path) return origin ? { ...file, folder: origin } : file;
-        const content = [".markdown", ".md"].includes(
-          extname(path).toLowerCase(),
-        )
-          ? await readFile(path, "utf8").catch(() => "")
-          : "";
-        const title = content ? markdownMetadata(content).title : undefined;
-        return {
-          ...file,
-          folder: origin,
-          name: title ?? file.name,
-          openHref: openPathHref(path),
-        };
-      }),
-    ),
-  };
-}
-
-async function localProjectSearchCache(
-  cache: LocalProjectSearchCache | undefined,
-) {
-  if (cache && Date.now() - cache.loadedAt < projectSearchCacheMs) return cache;
-
-  const settings = readRaggleUserSettings();
-  const projects = applyProjectFavorites(
-    (
-      await buildProjectCatalog({
-        cloneSources: settings.cloneDirectories.map((cloneDirectory) => ({
-          cloneDirectory,
-        })),
-        localRepositoryLinks: settings.localRepositoryLinks,
-        projectRoots: settings.projectDirectories,
-        repositoryLocations: settings.repositoryLocations,
-        schemaScanRoots: settings.projectDirectories,
-      })
-    ).map(catalogProjectToLocalProject),
-    settings.favoriteProjects,
-  );
-  const ordered = sortProjectList(projects, "recentActivity");
-  return {
-    index: buildProjectSearchIndex(ordered),
-    loadedAt: Date.now(),
-  };
-}
-
-/**
- * Resolves a media file (image/video/audio) referenced by a document. Mirrors
- * `documentTarget` containment: the target must live inside the folder, must
- * be a regular file, and must have a servable media type. Unlike documents,
- * no preview-kind gating — any media-typed file inside the folder is fair
- * game, since notes legitimately reference assets in sibling directories.
- */
-function mediaTarget(
-  folder: string,
-  file: string | null,
-  lockedTarget?: string,
-) {
-  if (!file) return undefined;
-  const rootReal = realpathSync(resolve(folder));
-  const path = resolve(folder, file);
-  let pathReal: string;
-  try {
-    pathReal = realpathSync(path);
-  } catch {
-    // Missing, unreadable, or dangling-symlink targets are not media.
-    return undefined;
-  }
-  const rel = relative(rootReal, pathReal);
-  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
-  // Single-file pop lock: only the popped file is previewable.
-  if (lockedTarget && pathReal !== lockedTarget) return undefined;
-  const mime = mediaRawMime(pathReal);
-  if (!mime) return undefined;
-  return { mime, path: pathReal, root: rootReal };
-}
-
-/** Parses a single `bytes=start-end` Range header into a satisfiable slice. */
-export function parseByteRange(
-  header: string | undefined,
-  size: number,
-): { end: number; start: number } | "invalid" | undefined {
-  if (!header) return undefined;
-  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
-  if (!match) return undefined;
-  const [, rawStart, rawEnd] = match;
-  if (!rawStart && !rawEnd) return undefined;
-  if (!rawStart) {
-    // Suffix range: last N bytes.
-    const length = Number(rawEnd);
-    if (!length) return "invalid";
-    return { end: size - 1, start: Math.max(0, size - length) };
-  }
-  const start = Number(rawStart);
-  const end = rawEnd ? Math.min(Number(rawEnd), size - 1) : size - 1;
-  if (start >= size || start > end) return "invalid";
-  return { end, start };
-}
-
-function documentError(response: ServerResponse) {
-  response.writeHead(404, {
-    "Content-Type": "application/json; charset=utf-8",
-  });
-  response.end(JSON.stringify({ error: "Document not found." }));
-}
-
-function documentTarget(
-  folder: string,
-  file: string | null,
-  lockedTarget?: string,
-) {
-  if (!file) return undefined;
-  const rootReal = realpathSync(resolve(folder));
-  const path = resolve(folder, file);
-  let pathReal: string;
-  try {
-    pathReal = realpathSync(path);
-  } catch {
-    // Missing, unreadable, or dangling-symlink targets are not documents.
-    return undefined;
-  }
-  const rel = relative(rootReal, pathReal);
-  if (rel.startsWith("..") || isAbsolute(rel)) return undefined;
-  // Single-file pop lock: only the popped file is previewable.
-  if (lockedTarget && pathReal !== lockedTarget) return undefined;
-  const kind = previewKind(pathReal);
-  if (!kind) return undefined;
-  return { kind, path: pathReal, root: rootReal };
-}
-
-function documentEtag(details: { mtimeMs: number; size: number }) {
-  return `"${createHash("sha256")
-    .update(`${details.mtimeMs}:${details.size}`)
-    .digest("hex")}"`;
-}
-
-async function projectSearchItem(
-  project: LocalProject,
-  match?: {
-    matchedField: string;
-    matchTier: string;
-    score: number;
-  },
-) {
-  const icon =
-    (await searchIconDataUrl(project.icon)) ??
-    (await searchIconDataUrl(discoverProjectIcon(project.worktree)));
-
-  return {
-    id: project.id,
-    icon,
-    latestSessionTitle: project.latestSessionTitle,
-    matchedField: match?.matchedField ?? "none",
-    matchTier: match?.matchTier ?? "emptyQuery",
-    relativePath: project.relativePath,
-    repositoryLabel: projectRepositoryAccessory(project),
-    score: match?.score ?? 0,
-    subtitle: projectSubtitle(project),
-    title: projectTitle(project.name, project.worktree),
-    worktree: project.worktree,
-  };
-}
-
-const defaultPluginRegistryConfig: FolderPluginRegistryConfig = {
-  plugins: { disable: [], order: [] },
-};
-
-type RawPluginRegistryConfig = {
-  plugins?: {
-    disable?: unknown;
-    order?: unknown;
-  };
-};
-
-function stringArray(value: unknown): string[] {
-  return Array.isArray(value)
-    ? value.filter((item): item is string => typeof item === "string")
-    : [];
-}
-
-function parsePluginRegistryConfig(content: string): FolderPluginRegistryConfig {
-  const parsed = JSON.parse(content) as unknown;
-  const config: RawPluginRegistryConfig =
-    parsed && typeof parsed === "object"
-      ? (parsed as RawPluginRegistryConfig)
-      : {};
-  return {
-    plugins: {
-      disable: stringArray(config.plugins?.disable),
-      order: stringArray(config.plugins?.order),
-    },
-  };
-}
-
-async function nearestKennelConfig(folder: string) {
-  for (let current = folder; ; current = dirname(current)) {
-    const candidate = resolve(current, "kennel.json");
-    const details = await stat(candidate).catch(() => undefined);
-    if (details?.isFile()) return candidate;
-    if (dirname(current) === current) return undefined;
-  }
-}
-
-async function folderPluginRegistryConfig(
-  folder: string,
-): Promise<FolderPluginRegistryConfig> {
-  const path = await nearestKennelConfig(folder);
-  if (!path) return defaultPluginRegistryConfig;
-  try {
-    return parsePluginRegistryConfig(await readFile(path, "utf8"));
-  } catch {
-    return defaultPluginRegistryConfig;
-  }
-}
-
-function pluginConfigWarnings(
-  registry: Map<string, FolderPluginServer>,
-  config: FolderPluginRegistryConfig,
-) {
-  const ids = unique([...config.plugins.disable, ...config.plugins.order]);
-  return ids
-    .filter((id) => !registry.has(id))
-    .map((id) => `unknown plugin id "${id}" — not installed in this build`);
-}
-
-async function pluginAvailability(
-  registry: Map<string, FolderPluginServer>,
-  folder: string,
-  linkedFolders: string[],
-  configWarnings: string[] = [],
-) {
-  const items: Array<{
-    count?: number;
-    error?: string;
-    icon?: { paths: string[] };
-    id: string;
-    label: string;
-  }> = [];
-  for (const plugin of registry.values()) {
-    try {
-      const detection = await plugin.detect({
-        folder,
-        linkedFolders,
-      });
-      if (detection.status === "available") {
-        items.push({
-          count: detection.count,
-          icon: plugin.icon,
-          id: plugin.id,
-          label: plugin.label,
-        });
-      } else if (detection.status === "error") {
-        // A plugin that found its content file but could not validate it is
-        // still a hit: keep the item visible and flag the problem so the
-        // shell can surface it instead of treating it as absent content.
-        items.push({
-          error: detection.error,
-          icon: plugin.icon,
-          id: plugin.id,
-          label: plugin.label,
-        });
-      }
-    } catch {
-      // Isolate plugin detection: a failure hides the item but never blocks
-      // the folder or other plugins.
-    }
-  }
-  return { configWarnings, items };
-}
-
-export function createFolderApi({
-  viewerName = "kennel-core",
-  restrictToRoot = false,
-  root,
-  sessionFinding,
-  linkedFolderLoader,
-  remoteAccess = false,
-  lockedFile,
-}: FolderMetadataPluginOptions) {
-  let lockedRoot = restrictToRoot ? realpathSync(root) : undefined;
-  const lockedTarget = lockedFile ? realpathSync(lockedFile) : undefined;
-  const resolveSession = sessionFinding ?? {
-    listFolderSessions,
-    readSessionTranscript,
-  };
-  const basePlugins = folderServerRegistryAsync();
-  const baseExternalApiHandlers = externalApiHandlers();
-  const assetFiles = new Map<
-    string,
-    { mediaType: IconAsset["mediaType"]; path: string }
-  >();
-  let projectSearchCache: LocalProjectSearchCache | undefined;
-  const projectDiscovery = createProjectDiscovery();
-  let discoveryChanged = (_folder: string) => {};
-  const linkedDiscovery = createLinkedFolderDiscovery(
-    linkedFolderLoader,
-    (folder) => discoveryChanged(folder),
-  );
-  const linkedState = (folder: string) =>
-    lockedRoot || isMachineRoot(folder)
-      ? { folders: [], status: "ready" as const }
-      : linkedDiscovery.read(folder);
-  const resolveLinkedFolders = (folder: string) =>
-    lockedRoot || isMachineRoot(folder)
-      ? Promise.resolve([])
-      : linkedDiscovery.folders(folder);
-  const favicon = faviconService();
-
-  return {
-    name: "kennel-folder-metadata",
-    close() {
-      linkedDiscovery.close();
-      projectDiscovery.close();
-    },
-    attach(server: ApiHost) {
-      discoveryChanged = (path) =>
-        server.emit({
-          data: { path },
-          event: "kennel:linked-folders-changed",
-          type: "custom",
-        });
-      // Effective remote mode comes from the explicit flag OR the resolved
-      // Vite host (0.0.0.0/true/non-loopback), so a bare `vite dev
-      // --host 0.0.0.0` gets the same restricted surface as the CLI's --lan.
-      const serverHost = server.host;
-      const remote =
-        remoteAccess ||
-        serverHost === true ||
-        (typeof serverHost === "string" && !isLoopbackServerHost(serverHost));
-      if (remote) lockedRoot = lockedRoot ?? realpathSync(root);
-
-      const collectionServer = createSchemaCollectionServer(server, {
-        boundary: lockedRoot,
-        lockedTarget,
-      });
-      const readWorkspace = collectionServer.summaries;
-      const watched = new Set<string>();
-      const contexts = new Set<string>();
-      const watch = (folder: string) => {
-        if (watched.has(folder)) return;
-        watched.add(folder);
-        server.watch(folder);
-      };
-      const refresh = (path: string) => {
-        collectionServer.invalidate(path);
-        if (contexts.has(path))
-          server.emit({
-            data: { path },
-            event: "kennel:workspace-changed",
-            type: "custom",
-          });
-        const folder = [...watched].find((candidate) =>
-          metadataFile(path, candidate),
-        );
-        if (!folder) return;
-        server.emit({
-          data: { path: relative(folder, path) },
-          event: "kennel:metadata-changed",
-          type: "custom",
-        });
-      };
-
-      if (restrictToRoot || remote) watch(root);
-      server.onChange(refresh);
-
-      server.use(async (request, response, next) => {
-        const url = new URL(request.url ?? "/", "http://127.0.0.1");
-        if (!apiHostAllowed(request.headers.host, remote)) {
-          response.writeHead(403, {
-            "Content-Type": "text/plain; charset=utf-8",
-          });
-          response.end("Untrusted Host header");
-          return;
-        }
-        if (!validateQuery(request, response, url)) return;
-        if (url.pathname === "/api/capabilities") {
-          sendContract(
-            response,
-            url,
-            {
-              acp: !remote,
-              download: true,
-              hostActions: remote ? "none" : "local",
-              local: !remote,
-              viewer: viewerName,
-            },
-            { "Cache-Control": "no-store" },
-          );
-          return;
-        }
-
-        if (url.pathname === "/api/config") {
-          const folder = folderPath(
-            url.searchParams.get("path"),
-            root,
-            lockedRoot,
-          );
-          sendContract(
-            response,
-            url,
-            { aiInputModule: await configuredAiInputModule(folder) },
-            { "Cache-Control": "no-store" },
-          );
-          return;
-        }
-
-        if (url.pathname === "/api/health") {
-          sendContract(
-            response,
-            url,
-            { viewer: viewerName, root, kernelKey: process.env.KENNEL_KERNEL_KEY ?? "core" },
-            { "Cache-Control": "no-store" },
-          );
-          return;
-        }
-        if (url.pathname === "/api/folder-favicon") {
-          const data = await (async () => {
-            if (process.env.KENNEL_EXTERNAL_ICONS !== "1") return undefined;
-            const folder = folderPath(
-              url.searchParams.get("path"),
-              root,
-              lockedRoot,
-            );
-            const host = await folderWebsite(folder);
-            if (!host || host !== url.searchParams.get("host"))
-              return undefined;
-            return favicon(host);
-          })().catch(() => undefined);
-          response.writeHead(data ? 200 : 404, {
-            "Cache-Control": data
-              ? "private, max-age=86400"
-              : "private, max-age=300",
-            "Content-Type": data ? "image/png" : "text/plain; charset=utf-8",
-            "X-Content-Type-Options": "nosniff",
-          });
-          response.end(data ?? "Icon unavailable");
-          return;
-        }
-        const assetMatch =
-          /^\/api\/folders\/([^/]+)\/assets\/([a-f0-9]{64})\.(?:jpg|png)$/.exec(
-            url.pathname,
-          );
-        if (assetMatch) {
-          try {
-            const [, folderId, hash] = assetMatch;
-            if (!folderId || !hash) throw new Error("Asset not found");
-            const folder = folderPath(
-              decodeBase64Url(folderId),
-              root,
-              lockedRoot,
-            );
-            watch(folder);
-            let asset = assetFiles.get(hash);
-            if (!asset) {
-              const assets: Record<string, IconAsset> = {};
-              await iconWithFaviconFallback(folder, assets, assetFiles);
-              asset = assetFiles.get(hash);
-            }
-            if (!asset) {
-              response.writeHead(404, {
-                "Content-Type": "text/plain; charset=utf-8",
-              });
-              response.end("Asset not found");
-              return;
-            }
-            response.writeHead(200, {
-              "Cache-Control": "private, max-age=31536000, immutable",
-              "Content-Type": asset.mediaType,
-              ETag: `"${hash}"`,
-            });
-            response.end(await readFile(asset.path));
-          } catch (error) {
-            response.writeHead(404, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end(
-              error instanceof Error ? error.message : "Asset not found",
-            );
-          }
-          return;
-        }
-        if (
-          remote &&
-          ["/api/project-search", "/api/entities"].includes(url.pathname)
-        ) {
-          response.writeHead(403);
-          response.end("Global discovery is disabled for remote access");
-          return;
-        }
-        if (url.pathname === "/api/project-search") {
-          const query = url.searchParams.get("q")?.trim() ?? "";
-          const cache = await localProjectSearchCache(projectSearchCache);
-          projectSearchCache = cache;
-          const result = searchProjectIndex(cache.index, query, {
-            limit: query ? 40 : 20,
-          });
-          sendContract(
-            response,
-            url,
-            {
-              items: await Promise.all(
-                result.hits.map((hit) => projectSearchItem(hit.project, hit)),
-              ),
-              query,
-              scanned: result.scanned,
-              total: result.total,
-            },
-            { "Cache-Control": "no-store" },
-          );
-          return;
-        }
-        if (url.pathname === "/api/entities") {
-          try {
-            const workspace = await loadEntityWorkspace(
-              url.searchParams.get("root") ?? undefined,
-              url.searchParams.get("q") ?? "",
-              url.searchParams.get("entity"),
-              root,
-            );
-            sendContract(response, url, workspace, {
-              "Cache-Control": "no-store",
-            });
-          } catch (error) {
-            response.writeHead(400, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end(
-              error instanceof Error
-                ? error.message
-                : "Could not load entities",
-            );
-          }
-          return;
-        }
-        if (url.pathname === "/api/document/edit") {
-          if (remote) {
-            response.writeHead(403, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end("Host actions are disabled for remote access");
-            return;
-          }
-          await runApiRoute(request, response, url, documentEditRoute, {
-            lockedFile: lockedTarget,
-            authorize: (folder) => folderPath(folder, root, lockedRoot),
-          });
-          return;
-        }
-        if (url.pathname === "/api/open-folder") {
-          if (remote || request.method !== "POST" || !sameOrigin(request)) {
-            response.writeHead(remote || request.method === "POST" ? 403 : 405);
-            response.end("Folder action not allowed");
-            return;
-          }
-          const folder = folderPath(
-            url.searchParams.get("path"),
-            root,
-            lockedRoot,
-          );
-          const command =
-            process.platform === "darwin"
-              ? "open"
-              : process.platform === "win32"
-                ? "explorer.exe"
-                : "xdg-open";
-          await new Promise<void>((done, fail) =>
-            execFile(command, [folder], (error) =>
-              error ? fail(error) : done(),
-            ),
-          );
-          response.writeHead(204);
-          response.end();
-          return;
-        }
-        if (url.pathname === "/api/documents") {
-          const folder = folderPath(
-            url.searchParams.get("path"),
-            root,
-            lockedRoot,
-          );
-          const target = lockedTarget
-            ? documentTarget(
-                folder,
-                relative(folder, lockedTarget),
-                lockedTarget,
-              )
-            : undefined;
-          const dataset = lockedTarget
-            ? {
-                root: folder,
-                documents: target
-                  ? [
-                      {
-                        path: relative(folder, target.path),
-                        kind: target.kind,
-                        content: previewTextKind(target.kind)
-                          ? await readFile(target.path, "utf8")
-                          : "",
-                      },
-                    ]
-                  : [],
-              }
-            : await readFolder(folder);
-          watch(folder);
-          sendContract(response, url, dataset, { "Cache-Control": "no-store" });
-          return;
-        }
-        if (url.pathname === "/api/document") {
-          try {
-            const folder = folderPath(
-              url.searchParams.get("path"),
-              root,
-              lockedRoot,
-            );
-            const target = documentTarget(
-              folder,
-              url.searchParams.get("file"),
-              lockedTarget,
-            );
-            if (!target) {
-              documentError(response);
-              return;
-            }
-            const details = await stat(target.path);
-            if (!details.isFile()) {
-              documentError(response);
-              return;
-            }
-            const etag = documentEtag(details);
-            if (request.headers["if-none-match"] === etag) {
-              response.writeHead(304, { ETag: etag });
-              response.end();
-              return;
-            }
-            watch(folder);
-            const content = previewTextKind(target.kind)
-              ? await readFile(target.path, "utf8")
-              : "";
-            sendContract(
-              response,
-              url,
-              {
-                content,
-                kind: target.kind,
-                path: relative(target.root, target.path),
-                root: folder,
-                ...(previewTextKind(target.kind)
-                  ? {}
-                  : {
-                      rawUrl: `/api/raw?${new URLSearchParams({
-                        path: folder,
-                        file: relative(target.root, target.path),
-                      })}`,
-                    }),
-              },
-              {
-                "Cache-Control": "private, max-age=0, must-revalidate",
-                ETag: etag,
-              },
-            );
-          } catch (error) {
-            documentError(response);
-          }
-          return;
-        }
-        if (url.pathname === "/api/raw") {
-          try {
-            const folder = folderPath(
-              url.searchParams.get("path"),
-              root,
-              lockedRoot,
-            );
-            const target = documentTarget(
-              folder,
-              url.searchParams.get("file"),
-              lockedTarget,
-            );
-            if (!target) {
-              documentError(response);
-              return;
-            }
-            const details = await stat(target.path);
-            if (!details.isFile()) {
-              documentError(response);
-              return;
-            }
-            const etag = documentEtag(details);
-            if (request.headers["if-none-match"] === etag) {
-              response.writeHead(304, { ETag: etag });
-              response.end();
-              return;
-            }
-            watch(folder);
-            // Active content stays inert from the raw endpoint: HTML download
-            // only as opaque bytes; SVG (scripts allowed in top-level/iframe
-            // navigation) always downloads as an attachment with nosniff.
-            const active =
-              target.kind === "html" ||
-              target.path.toLowerCase().endsWith(".svg");
-            const download = url.searchParams.get("download") === "1" || active;
-            const mime =
-              target.kind === "html"
-                ? "application/octet-stream"
-                : (previewRawMime(target.path) ?? "application/octet-stream");
-            response.writeHead(200, {
-              "Cache-Control": "private, max-age=0, must-revalidate",
-              "Content-Type": mime,
-              ETag: etag,
-              "X-Content-Type-Options": "nosniff",
-              ...(download
-                ? {
-                    "Content-Disposition": `attachment; filename="${basename(target.path)}"`,
-                  }
-                : {}),
-            });
-            response.end(await readFile(target.path));
-          } catch (error) {
-            documentError(response);
-          }
-          return;
-        }
-        if (url.pathname === "/api/media") {
-          try {
-            const folder = folderPath(
-              url.searchParams.get("path"),
-              root,
-              lockedRoot,
-            );
-            const target = mediaTarget(
-              folder,
-              url.searchParams.get("file"),
-              lockedTarget,
-            );
-            if (!target) {
-              documentError(response);
-              return;
-            }
-            const details = await stat(target.path);
-            if (!details.isFile()) {
-              documentError(response);
-              return;
-            }
-            const etag = documentEtag(details);
-            if (request.headers["if-none-match"] === etag) {
-              response.writeHead(304, { ETag: etag });
-              response.end();
-              return;
-            }
-            watch(folder);
-            // Media is read whole and sliced for ranges: clips are small
-            // (single-digit MB) and browsers need 206 support to seek.
-            const data = await readFile(target.path);
-            const baseHeaders = {
-              "Accept-Ranges": "bytes",
-              "Cache-Control": "private, max-age=0, must-revalidate",
-              "Content-Type": target.mime,
-              ETag: etag,
-              "X-Content-Type-Options": "nosniff",
-            };
-            const range = parseByteRange(request.headers.range, data.length);
-            if (range === "invalid") {
-              response.writeHead(416, {
-                ...baseHeaders,
-                "Content-Range": `bytes */${data.length}`,
-              });
-              response.end();
-              return;
-            }
-            if (range) {
-              const slice = data.subarray(range.start, range.end + 1);
-              response.writeHead(206, {
-                ...baseHeaders,
-                "Content-Length": String(slice.length),
-                "Content-Range": `bytes ${range.start}-${range.end}/${data.length}`,
-              });
-              response.end(slice);
-              return;
-            }
-            response.writeHead(200, {
-              ...baseHeaders,
-              "Content-Length": String(data.length),
-            });
-            response.end(data);
-          } catch (error) {
-            documentError(response);
-          }
-          return;
-        }
-        if (url.pathname === "/api/session") {
-          try {
-            const sessionId = url.searchParams.get("sessionId");
-            if (!sessionId) throw new Error("No sessionId parameter");
-            const session =
-              await resolveSession.readSessionTranscript(sessionId);
-            response.writeHead(200, {
-              "Cache-Control": "private, max-age=10, must-revalidate",
-              "Content-Type": "application/json; charset=utf-8",
-            });
-            response.end(JSON.stringify(session));
-          } catch (error) {
-            response.writeHead(404, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end(
-              error instanceof Error ? error.message : "Session not found",
-            );
-          }
-          return;
-        }
-        const pluginMatch = /^\/api\/plugins\/([^/]+)$/.exec(url.pathname);
-        if (pluginMatch) {
-          try {
-            const pluginId = pluginMatch[1];
-            if (!pluginId) throw new Error("Unknown plugin");
-            const folder = folderPath(
-              url.searchParams.get("path"),
-              root,
-              lockedRoot,
-            );
-            const pluginConfig = await folderPluginRegistryConfig(folder);
-            const plugins = configuredFolderServerRegistry(
-              await basePlugins,
-              pluginConfig,
-            );
-            const plugin = plugins.get(pluginId);
-            if (!plugin) throw new Error("Unknown plugin");
-            watch(folder);
-            const subpath = url.searchParams.get("subpath") ?? "";
-            // Local content never waits for optional linked-project discovery.
-            if (
-              !lockedRoot &&
-              !isMachineRoot(folder) &&
-              request.headers["x-kennel-retry-linked"] === "1"
-            )
-              linkedDiscovery.retry(folder);
-            const discovery = linkedState(folder);
-            const result = await plugin.handle(
-              {
-                folder,
-                linkedFolders: discovery.folders,
-              },
-              subpath,
-            );
-            if (result.kind === "unavailable") {
-              response.writeHead(200, {
-                "Cache-Control": "private, max-age=0, must-revalidate",
-                "Content-Type": "application/json; charset=utf-8",
-              });
-              response.end(
-                JSON.stringify({
-                  folder,
-                  plugin: pluginId,
-                  status: "unavailable",
-                  linkedStatus: discovery.status,
-                }),
-              );
-              return;
-            }
-            response.writeHead(200, {
-              "Cache-Control": "private, max-age=0, must-revalidate",
-              "Content-Type": "application/json; charset=utf-8",
-            });
-            const data = result.data as Record<string, unknown>;
-            response.end(
-              JSON.stringify({
-                folder,
-                plugin: pluginId,
-                ...data,
-                linkedStatus: discovery.status,
-              }),
-            );
-          } catch (error) {
-            if (error instanceof FolderPluginFailure) {
-              response.writeHead(500, {
-                "Content-Type": "text/plain; charset=utf-8",
-              });
-              response.end(error.message);
-              return;
-            }
-            response.writeHead(404, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end(
-              error instanceof Error ? error.message : "Plugin not found",
-            );
-          }
-          return;
-        }
-        for (const handler of await baseExternalApiHandlers) {
-          if (
-            await handler(request, response, {
-              authorizeFolder: (value) => folderPath(value, root, lockedRoot),
-              readOnly: remote,
-              watch,
-            })
-          )
-            return;
-        }
-        if (url.pathname === "/api/create-agent-file") {
-          if (remote) {
-            response.writeHead(403, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end("Host actions are disabled for remote access");
-            return;
-          }
-          await runApiRoute(request, response, url, createAgentFileRoute, {
-            resolve: (value: string | null) =>
-              folderPath(value, root, lockedRoot),
-          });
-          return;
-        }
-        if (url.pathname === "/api/open-path") {
-          if (remote) {
-            response.writeHead(403, {
-              "Content-Type": "text/plain; charset=utf-8",
-            });
-            response.end("Host actions are disabled for remote access");
-            return;
-          }
-          await runApiRoute(request, response, url, openPathRoute, {
-            resolve: (value: string | null) =>
-              folderPath(value, root, lockedRoot),
-          });
-          return;
-        }
-        if (url.pathname !== "/api/metadata") {
-          next();
-          return;
-        }
-
-        try {
-          const part = url.searchParams.get("part");
-          const folder = folderPath(
-            url.searchParams.get("path"),
-            root,
-            lockedRoot,
-          );
-          if (lockedTarget && part !== "workspace") {
-            // Single-file pop lock: workspace stays (config resolution, no
-            // file contents); every other metadata part returns a folder-only
-            // body so siblings are never listed or summarized.
-            if (part === "collections") {
-              response.writeHead(404, { "Content-Type": "application/json" });
-              response.end(JSON.stringify({ error: "Collection not found" }));
-              return;
-            }
-            sendContract(
-              response,
-              url,
-              {
-                assets: {},
-                files: { items: [] },
-                folder,
-                projects: { items: [] },
-                sessions: { items: [] },
-                workspace: await readWorkspace(folder),
-              },
-              { "Cache-Control": "private, max-age=0, must-revalidate" },
-            );
-            return;
-          }
-          if (part === "workspace") {
-            const workspace = await readWorkspace(folder);
-            workspace.breadcrumbs = await workspaceBreadcrumbIcons(
-              workspace.breadcrumbs ?? [],
-              assetFiles,
-            );
-            const files = [
-              workspace.configPath,
-              resolve(workspace.root, "raggle.json"),
-            ].filter((path): path is string => Boolean(path));
-            for (const path of files) contexts.add(path);
-            server.watch(files);
-            sendContract(
-              response,
-              url,
-              { folder, workspace },
-              { "Cache-Control": "private, max-age=0, must-revalidate" },
-            );
-            return;
-          }
-          watch(folder);
-          if (part === "collections") {
-            const sort = url.searchParams.get("sort");
-            await collectionServer.handleMetadataPart({
-              folder,
-              id: url.searchParams.get("id"),
-              response,
-              send: (body, headers) =>
-                sendContract(response, url, body, headers),
-              sort: sort === "alpha" || sort === "recent" ? sort : undefined,
-              url,
-            });
-            return;
-          }
-
-          // Sessions functionality is commented out (can be re-enabled).
-          // if (part === "sessions") {
-          //   const sessions = isMachineRoot(folder)
-          //     ? { items: [] }
-          //     : await resolveSession.listFolderSessions({ folder, limit: 100 })
-          //   response.writeHead(200, {
-          //     "Cache-Control": "private, max-age=0, must-revalidate",
-          //     "Content-Type": "application/json; charset=utf-8",
-          //   })
-          //   response.end(JSON.stringify({ folder, sessions }))
-          //   return
-          // }
-
-          const machine = isMachineRoot(folder);
-
-          if (part === "notes") {
-            // The viewer requests local and linked notes independently so slow
-            // repository discovery cannot hold the local list hostage. Omitted
-            // scope preserves the combined API response for existing clients.
-            const scope = url.searchParams.get("notesScope");
-            const localFiles =
-              scope === "linked"
-                ? Promise.resolve({ items: [] })
-                : (machine
-                    ? shallowMetadata(folder).then((data) => data.files.items)
-                    : listLocalMarkdownFiles({ folder, limit: 200 })
-                  ).then((files) => notesFiles(folder, files));
-            const linkedFiles = async () => {
-              if (scope === "local" || machine || lockedRoot) return [];
-              if (request.headers["x-kennel-retry-linked"] === "1")
-                linkedDiscovery.retry(folder);
-              const linkedFolders = await resolveLinkedFolders(folder);
-              if (linkedState(folder).status === "error")
-                throw new Error(
-                  "Linked notes discovery failed. Retry to try again.",
-                );
-              return Promise.all(
-                linkedFolders.map(async (linkedFolder) => {
-                  watch(linkedFolder);
-                  return notesFiles(
-                    linkedFolder,
-                    await listLocalMarkdownFiles({
-                      folder: linkedFolder,
-                      limit: 200,
-                    }),
-                    linkedFolder,
-                  );
-                }),
-              );
-            };
-            const [files, linked] = await Promise.all([
-              localFiles,
-              linkedFiles(),
-            ]);
-            sendContract(
-              response,
-              url,
-              {
-                files: {
-                  items: [
-                    ...files.items,
-                    ...linked.flatMap((group) => group.items),
-                  ],
-                },
-                folder,
-              },
-              { "Cache-Control": "private, max-age=0, must-revalidate" },
-            );
-            return;
-          }
-
-          // Plugin availability is isolated from core discovery: a plugin
-          // failure hides its own item but never blocks Notes or other plugins.
-          if (part === "plugins") {
-            const pluginConfig = await folderPluginRegistryConfig(folder);
-            const registry = await basePlugins;
-            const plugins = configuredFolderServerRegistry(
-              registry,
-              pluginConfig,
-            );
-            const configWarnings = pluginConfigWarnings(
-              registry,
-              pluginConfig,
-            );
-            sendContract(
-              response,
-              url,
-              {
-                configWarnings,
-                folder,
-                plugins: await pluginAvailability(
-                  plugins,
-                  folder,
-                  lockedRoot || isMachineRoot(folder)
-                    ? []
-                    : linkedDiscovery.peek(folder).folders,
-                  configWarnings,
-                ),
-              },
-              { "Cache-Control": "private, max-age=0, must-revalidate" },
-            );
-            return;
-          }
-
-          const respond = (body: unknown) =>
-            sendContract(response, url, body, {
-              "Cache-Control": "private, max-age=0, must-revalidate",
-            });
-
-          if (part === "identity") {
-            const hydrated = await hydrateAssets({ folder }, assetFiles);
-            respond({
-              assets: hydrated.assets,
-              folder,
-              iconAssetKey: hydrated.iconAssetKey,
-            });
-            return;
-          }
-
-          if (part === "discovery") {
-            // Navigation needs projects, not a recursive Markdown inventory.
-            const controller = new AbortController();
-            const cancel = () => controller.abort();
-            response.once("close", cancel);
-            let projects;
-            try {
-              projects = machine
-                ? (await shallowMetadata(folder)).projects.items
-                : await projectDiscovery.read(folder, controller.signal);
-            } finally {
-              response.off("close", cancel);
-            }
-            const [hydrated, workspace] = await Promise.all([
-              hydrateAssets(
-                { folder, projects: { items: projects } },
-                assetFiles,
-              ),
-              readWorkspace(folder),
-            ]);
-            workspace.breadcrumbs = await workspaceBreadcrumbIcons(
-              workspace.breadcrumbs ?? [],
-              assetFiles,
-              hydrated.assets,
-            );
-            respond({
-              assets: hydrated.assets,
-              folder,
-              projects: hydrated.projects,
-              workspace,
-            });
-            return;
-          }
-
-          const metadata = machine
-            ? await shallowMetadata(folder)
-            : await loadFolderData(folder);
-
-          const assets = await hydrateAssets(metadata, assetFiles);
-          const body = {
-            ...metadata,
-            ...assets,
-            sessions: { items: [] },
-            files: await notesFiles(metadata.folder, metadata.files.items),
-          };
-          respond(body);
-        } catch (error) {
-          response.writeHead(404, {
-            "Content-Type": "text/plain; charset=utf-8",
-          });
-          response.end(
-            error instanceof Error ? error.message : "Folder activity failed",
-          );
-        }
-      });
-    },
-  };
-}