kennel 0.2.0 → 0.2.2

package/kernel/packages/api/src/server/contracts.ts

@@ -0,0 +1,85 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  folderMetadataSchema,
+  metadataSchemas,
+  routes,
+  type MetadataPart,
+} from "../contracts/schemas";
+
+const routeFor = (url: URL) =>
+  Object.values(routes).find((route) => route.path === url.pathname);
+
+/** Validate before invoking a handler, without changing host/origin authorization. */
+export function validateQuery(
+  request: IncomingMessage,
+  response: ServerResponse,
+  url: URL,
+) {
+  const route = routeFor(url);
+  // Mutation handlers perform origin/remote checks before parsing their inputs.
+  // Do not let validation change their authorization status or error precedence.
+  if (!route || route.method === "post" || route === routes.openPath)
+    return true;
+  if ((request.method ?? "GET").toLowerCase() !== route.method) {
+    response.writeHead(405, { Allow: route.method.toUpperCase() });
+    response.end("Method not allowed");
+    return false;
+  }
+  const parsed = route.query.safeParse(Object.fromEntries(url.searchParams));
+  if (!parsed.success) {
+    response.writeHead(400, { "Content-Type": "application/json" });
+    response.end(
+      JSON.stringify({
+        error: { code: "invalid_request", message: "Invalid query parameters" },
+      }),
+    );
+    return false;
+  }
+  return true;
+}
+
+/** Only core JSON payloads use this; streams, errors and plugin data keep their own protocols. */
+export function sendContract(
+  response: ServerResponse,
+  url: URL,
+  body: unknown,
+  headers: Record<string, string> = {},
+) {
+  const route = routeFor(url);
+  const part = url.searchParams.get("part") as MetadataPart | null;
+  const schema =
+    route === routes.metadata
+      ? part
+        ? metadataSchemas[part]
+        : folderMetadataSchema
+      : route && "response" in route
+        ? route.response
+        : undefined;
+  // Validate the serialized representation, not in-memory values such as undefined.
+  const parsed = schema?.safeParse(JSON.parse(JSON.stringify(body)));
+  if (!parsed?.success) {
+    console.error(
+      "API response contract failed",
+      url.pathname,
+      parsed?.error.issues.map((issue) => ({
+        path: issue.path,
+        message: issue.message,
+      })),
+    );
+    response.writeHead(500, { "Content-Type": "application/json" });
+    response.end(
+      JSON.stringify({
+        error: {
+          code: "invalid_response",
+          message: "Server response violated the API contract",
+        },
+      }),
+    );
+    return;
+  }
+  response.writeHead(200, {
+    "Content-Type": "application/json; charset=utf-8",
+    ...headers,
+  });
+  response.end(JSON.stringify(parsed.data));
+}

package/kernel/packages/api/src/server/entity-folder.ts

@@ -0,0 +1,353 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import {
+  basename,
+  dirname,
+  extname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
+import YAML from "yaml";
+
+const CONFIG_FILE = join("kennel", "config.json");
+const IGNORED_DIRECTORIES = new Set([
+  ".git",
+  ".gtl",
+  ".vitepress",
+  "dist",
+  "node_modules",
+]);
+
+import type { FolderEntity, EntityWorkspace } from "../contracts";
+export type { FolderEntity, EntityWorkspace } from "../contracts";
+
+type MarkdownDocument = {
+  body: string;
+  frontmatter: Record<string, unknown>;
+};
+
+function parseMarkdown(source: string): MarkdownDocument {
+  if (!source.startsWith("---\n"))
+    return { body: source.trim(), frontmatter: {} };
+
+  const end = source.indexOf("\n---", 4);
+  if (end === -1) return { body: source.trim(), frontmatter: {} };
+
+  const document = YAML.parseDocument(source.slice(4, end));
+  const value = document.errors.length === 0 ? document.toJS() : {};
+
+  return {
+    body: source.slice(end + 4).trim(),
+    frontmatter:
+      value && typeof value === "object" && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : {},
+  };
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function stringValues(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter(
+        (item): item is string =>
+          typeof item === "string" && Boolean(item.trim()),
+      )
+    : [];
+}
+
+function heading(body: string): string | null {
+  const line = body.split("\n").find((item) => item.startsWith("# "));
+  return line?.slice(2).trim() ?? null;
+}
+
+function paragraph(body: string): string {
+  return (
+    body
+      .split("\n\n")
+      .map((item) => item.trim())
+      .find(
+        (item) => item && !item.startsWith("#") && !item.startsWith("- "),
+      ) ?? ""
+  );
+}
+
+type EntityRootConfig = {
+  allowedRoots: string[];
+};
+
+function configPath(): string {
+  const xdg = process.env.XDG_CONFIG_HOME?.trim();
+  return xdg ? join(xdg, CONFIG_FILE) : join(homedir(), ".config", CONFIG_FILE);
+}
+
+async function readConfig(path: string): Promise<EntityRootConfig | null> {
+  try {
+    return parseConfig(await readFile(path, "utf8"));
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "ENOENT"
+    )
+      return null;
+    throw error;
+  }
+}
+
+function parseConfig(source: string): EntityRootConfig {
+  let value: unknown;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error("Invalid Kennel entity root config");
+  }
+
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid Kennel entity root config");
+
+  const roots = (value as { allowedRoots?: unknown }).allowedRoots;
+  if (!Array.isArray(roots))
+    throw new Error("Invalid Kennel entity root config");
+
+  const allowedRoots = roots.map((root) => {
+    if (typeof root !== "string" || !root.trim() || !isAbsolute(root))
+      throw new Error("Invalid Kennel entity root config");
+    return root.trim();
+  });
+
+  return { allowedRoots };
+}
+
+async function allowedRoots(
+  currentWorkspaceRoot: string | undefined,
+): Promise<string[]> {
+  const config = await readConfig(configPath());
+  if (config) return config.allowedRoots;
+  return currentWorkspaceRoot?.trim() ? [currentWorkspaceRoot] : [];
+}
+
+function inside(root: string, path: string): boolean {
+  const local = relative(root, path);
+  return local === "" || (!local.startsWith("..") && !isAbsolute(local));
+}
+
+async function normalizeRoot(
+  rootPath: string | undefined,
+  currentWorkspaceRoot: string | undefined,
+): Promise<string | null> {
+  const trimmed = rootPath?.trim();
+  const fallback = currentWorkspaceRoot?.trim();
+  if (!trimmed && !fallback) return null;
+
+  const requested = resolve(trimmed || fallback!); // eslint-disable-line @typescript-eslint/prefer-nullish-coalescing
+  const resolved = await realpath(requested);
+  const info = await stat(resolved);
+  if (!info.isDirectory()) throw new Error(`${resolved} is not a folder`);
+
+  const roots = await allowedRoots(currentWorkspaceRoot);
+  const realAllowedRoots = await Promise.all(
+    roots.map((root) => realpath(root)),
+  );
+  const allowed = realAllowedRoots.some((root) => inside(root, resolved));
+  if (!allowed) throw new Error("Entity root is outside the configured roots");
+
+  return resolved;
+}
+
+async function markdownFiles(folderPath: string): Promise<string[]> {
+  const files: string[] = [];
+
+  async function walk(currentPath: string) {
+    const entries = await readdir(currentPath, { withFileTypes: true });
+
+    for (const entry of entries.sort((left, right) =>
+      left.name.localeCompare(right.name),
+    )) {
+      if (entry.name.startsWith(".") || IGNORED_DIRECTORIES.has(entry.name))
+        continue;
+
+      const entryPath = join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        if (entryPath !== folderPath && (await hasIndex(entryPath))) continue;
+        await walk(entryPath);
+        continue;
+      }
+
+      if (
+        entry.isFile() &&
+        extname(entry.name) === ".md" &&
+        entry.name !== "README.md"
+      )
+        files.push(entryPath);
+    }
+  }
+
+  await walk(folderPath);
+  return files;
+}
+
+async function hasIndex(folderPath: string): Promise<boolean> {
+  return stat(join(folderPath, "index.md"))
+    .then((value) => value.isFile())
+    .catch(() => false);
+}
+
+async function schemaPath(
+  folderPath: string,
+  rootPath: string,
+): Promise<string | null> {
+  let current = folderPath;
+
+  while (current === rootPath || current.startsWith(`${rootPath}/`)) {
+    for (const name of ["schema.json", "_schema.json"]) {
+      const candidate = join(current, name);
+      if (
+        await stat(candidate)
+          .then((value) => value.isFile())
+          .catch(() => false)
+      )
+        return candidate;
+    }
+
+    if (current === rootPath) return null;
+    current = dirname(current);
+  }
+
+  return null;
+}
+
+async function readEntity(
+  folderPath: string,
+  rootPath: string,
+): Promise<FolderEntity> {
+  const indexPath = join(folderPath, "index.md");
+  const index = parseMarkdown(await readFile(indexPath, "utf8"));
+  const files = await markdownFiles(folderPath);
+  const documents = await Promise.all(
+    files.map(async (filePath) => {
+      const document = parseMarkdown(await readFile(filePath, "utf8"));
+      return {
+        content: document.body,
+        path: relative(folderPath, filePath),
+        title:
+          stringValue(document.frontmatter.title) ??
+          heading(document.body) ??
+          basename(filePath, extname(filePath)),
+      };
+    }),
+  );
+  const title =
+    stringValue(index.frontmatter.title) ??
+    heading(index.body) ??
+    basename(folderPath);
+  const relativePath = relative(rootPath, folderPath) || ".";
+
+  return {
+    aliases: stringValues(index.frontmatter.aliases),
+    content: [
+      index.body,
+      ...documents.map((document) => document.content),
+    ].join("\n\n"),
+    description:
+      stringValue(index.frontmatter.description) ?? paragraph(index.body),
+    documents: documents.map(({ path, title: documentTitle }) => ({
+      path,
+      title: documentTitle,
+    })),
+    folderPath,
+    relativePath,
+    schemaPath: await schemaPath(folderPath, rootPath),
+    slug:
+      stringValue(index.frontmatter.slug) ??
+      relativePath
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, ""),
+    status: stringValue(index.frontmatter.status),
+    title,
+    type: stringValue(index.frontmatter.type) ?? "folder",
+  };
+}
+
+async function discover(rootPath: string): Promise<FolderEntity[]> {
+  const folders: string[] = [];
+
+  async function walk(folderPath: string) {
+    if (await hasIndex(folderPath)) folders.push(folderPath);
+
+    const entries = await readdir(folderPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (
+        !entry.isDirectory() ||
+        entry.name.startsWith(".") ||
+        IGNORED_DIRECTORIES.has(entry.name)
+      )
+        continue;
+      await walk(join(folderPath, entry.name));
+    }
+  }
+
+  await walk(rootPath);
+  return Promise.all(
+    folders.map((folderPath) => readEntity(folderPath, rootPath)),
+  );
+}
+
+export function rankEntity(entity: FolderEntity, query: string): number {
+  if (!query) return 1;
+
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  const title =
+    `${entity.title} ${entity.aliases.join(" ")} ${entity.slug}`.toLowerCase();
+  const metadata =
+    `${entity.type} ${entity.status ?? ""} ${entity.relativePath}`.toLowerCase();
+  const content = entity.content.toLowerCase();
+
+  return terms.reduce((score, term) => {
+    if (title.includes(term)) return score + 20;
+    if (metadata.includes(term)) return score + 8;
+    if (content.includes(term)) return score + 2;
+    return score - 100;
+  }, 0);
+}
+
+export async function loadEntityWorkspace(
+  root: string | undefined,
+  query: string,
+  selectedPath: string | null,
+  currentWorkspaceRoot?: string,
+) {
+  const rootPath = await normalizeRoot(root, currentWorkspaceRoot);
+  if (!rootPath)
+    return {
+      entities: [],
+      query,
+      rootPath: "",
+      selected: null,
+    } satisfies EntityWorkspace;
+
+  const entities = (await discover(rootPath))
+    .map((entity) => ({ entity, score: rankEntity(entity, query) }))
+    .filter(({ score }) => score > 0)
+    .sort(
+      (left, right) =>
+        right.score - left.score ||
+        left.entity.title.localeCompare(right.entity.title),
+    )
+    .map(({ entity }) => entity);
+  const selected =
+    entities.find(
+      (entity) =>
+        entity.relativePath === selectedPath || entity.slug === selectedPath,
+    ) ??
+    entities[0] ??
+    null;
+
+  return { entities, query, rootPath, selected } satisfies EntityWorkspace;
+}

package/kernel/packages/api/src/server/folder-favicon.ts

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { markdownMetadata } from "@raggle-ai/markdown";
+import { websiteHost } from "@raggle-ai/schemas/favicon";
+
+export async function folderWebsite(folder: string) {
+  for (const name of ["AGENTS.md", "README.md"]) {
+    const content = await readFile(join(folder, name), "utf8").catch(() => "");
+    const entry = markdownMetadata(content).entries.find(
+      ([key]) => key === "website",
+    );
+    // An explicit but invalid value must not silently fall through to another file.
+    if (entry) return websiteHost(entry[1]);
+  }
+  return undefined;
+}

package/kernel/packages/api/src/server/folder-icons.ts

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+
+import { discoverFolderIcon } from "@raggle-ai/local";
+
+export type IconMediaType = "image/jpeg" | "image/png";
+
+export type IconAsset = {
+  mediaType: IconMediaType;
+  source: "local" | "favicon";
+  url: string;
+};
+
+/**
+ * Optional fallback for folders without a local icon (external website
+ * favicon, data URL, ...). Receives the folder and the shared asset record
+ * and returns a new asset key when it produced an asset.
+ */
+export type FolderIconFallback = (
+  folder: string,
+  assets: Record<string, IconAsset>,
+) => Promise<string | undefined>;
+
+/**
+ * Folder icons are served as immutable, content-addressed assets, so the
+ * cap is generous: it only guards against pathological files, not normal
+ * photos that happen to be named icon.png (e.g. a 700 KiB folder photo).
+ */
+export const maxIconBytes = 4 * 1024 * 1024;
+const iconTypes = new Map<string, IconMediaType>([
+  [".jpeg", "image/jpeg"],
+  [".jpg", "image/jpeg"],
+  [".png", "image/png"],
+]);
+const iconExtensions = new Map<IconMediaType, string>([
+  ["image/jpeg", "jpg"],
+  ["image/png", "png"],
+]);
+
+export function assetKey(value: Buffer) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function encodeBase64Url(value: string) {
+  return Buffer.from(value, "utf8")
+    .toString("base64")
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "");
+}
+
+export function decodeBase64Url(value: string) {
+  const padded = `${value}${"=".repeat((4 - (value.length % 4)) % 4)}`;
+  return Buffer.from(
+    padded.replaceAll("-", "+").replaceAll("_", "/"),
+    "base64",
+  ).toString("utf8");
+}
+
+export function iconUrl(
+  folder: string,
+  hash: string,
+  mediaType: IconMediaType,
+) {
+  return `/api/folders/${encodeBase64Url(folder)}/assets/${hash}.${iconExtensions.get(mediaType)}`;
+}
+
+export async function folderIcon(
+  folder: string,
+  assets: Record<string, IconAsset>,
+  assetFiles: Map<string, { mediaType: IconMediaType; path: string }>,
+  fallback?: FolderIconFallback,
+): Promise<string | undefined> {
+  const icon = discoverFolderIcon(folder);
+  const mediaType = icon ? iconTypes.get(extname(icon).toLowerCase()) : null;
+  const details =
+    icon && mediaType ? await stat(icon).catch(() => undefined) : undefined;
+  if (!icon || !mediaType || !details?.size || details.size > maxIconBytes) {
+    return fallback ? await fallback(folder, assets) : undefined;
+  }
+  const data = await readFile(icon);
+  const hash = assetKey(data);
+  const key = `local:${hash}`;
+  assetFiles.set(hash, { mediaType, path: icon });
+  assets[key] = {
+    mediaType,
+    source: "local",
+    url: iconUrl(folder, hash, mediaType),
+  };
+  return key;
+}
+
+/**
+ * Attach the nearest ancestor icon to each workspace breadcrumb so the
+ * client can render folder icons in the header and breadcrumb dropdown.
+ * Icons are registered as immutable assets served by `/api/folders/...`.
+ */
+export async function workspaceBreadcrumbIcons<B extends { path: string }>(
+  breadcrumbs: B[],
+  assetFiles: Map<string, { mediaType: IconMediaType; path: string }>,
+  assets: Record<string, IconAsset> = {},
+): Promise<Array<B & { icon?: Pick<IconAsset, "mediaType" | "url"> }>> {
+  return Promise.all(
+    breadcrumbs.map(async (crumb) => {
+      const iconAssetKey = await folderIcon(crumb.path, assets, assetFiles);
+      const icon = iconAssetKey ? assets[iconAssetKey] : undefined;
+      return icon
+        ? { ...crumb, icon: { mediaType: icon.mediaType, url: icon.url } }
+        : crumb;
+    }),
+  );
+}