kennel 0.2.1 → 0.2.2

package/kernel/packages/kinds/package.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@raggle-ai/kennel-kinds",
+  "version": "0.0.0",
+  "description": "Leaf kind table shared by the Kennel API and the preview package.",
+  "type": "module",
+  "license": "MIT",
+  "private": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "packages/kinds"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/kinds.ts"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  }
+}

package/kernel/packages/kinds/src/kinds.ts

@@ -0,0 +1,172 @@
+/**
+ * Preview kinds for the Kennel pop-up viewer.
+ *
+ * One table for every server: the static viewer, the Vite hot viewer
+ * (apps/web/server/preview-kinds.ts re-exports this file), and the core API.
+ * Text kinds are delivered as UTF-8 `content` through
+ * `/api/document`; non-text kinds (images, binary) are delivered through
+ * `/api/raw` and referenced by the `rawUrl` field in the document response.
+ */
+
+export type PreviewKind =
+  "binary" | "code" | "eml" | "html" | "image" | "markdown" | "table" | "text";
+
+export const previewTextKinds = new Set<PreviewKind>([
+  "code",
+  "eml",
+  "html",
+  "markdown",
+  "table",
+  "text",
+]);
+
+export function previewTextKind(kind: PreviewKind): boolean {
+  return previewTextKinds.has(kind);
+}
+
+const codeExtensions = new Set([
+  ".astro",
+  ".bash",
+  ".c",
+  ".cc",
+  ".cpp",
+  ".cs",
+  ".css",
+  ".dart",
+  ".ex",
+  ".exs",
+  ".go",
+  ".graphql",
+  ".h",
+  ".hpp",
+  ".hs",
+  ".java",
+  ".js",
+  ".jsx",
+  ".json",
+  ".kt",
+  ".less",
+  ".lua",
+  ".ml",
+  ".mjs",
+  ".php",
+  ".proto",
+  ".py",
+  ".rb",
+  ".rs",
+  ".scss",
+  ".sh",
+  ".sql",
+  ".svelte",
+  ".swift",
+  ".toml",
+  ".ts",
+  ".tsx",
+  ".vue",
+  ".xml",
+  ".yaml",
+  ".yml",
+  ".zsh",
+]);
+
+const imageExtensions = new Set([
+  ".avif",
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".png",
+  ".svg",
+  ".webp",
+]);
+
+const knownExtensions = new Set([
+  ...codeExtensions,
+  ...imageExtensions,
+  ".csv",
+  ".eml",
+  ".htm",
+  ".html",
+  ".markdown",
+  ".md",
+  ".mdx",
+  ".pdf",
+  ".text",
+  ".tsv",
+  ".txt",
+]);
+
+export function previewKind(path: string): PreviewKind | undefined {
+  const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+  if (extension === ".htm" || extension === ".html") return "html";
+  if (extension === ".md" || extension === ".markdown" || extension === ".mdx")
+    return "markdown";
+  if (extension === ".text" || extension === ".txt") return "text";
+  if (extension === ".eml") return "eml";
+  if (extension === ".csv" || extension === ".tsv") return "table";
+  if (imageExtensions.has(extension)) return "image";
+  if (codeExtensions.has(extension)) return "code";
+  if (knownExtensions.has(extension)) return "binary";
+  return undefined;
+}
+
+const rawMime: Record<string, string> = {
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".gif": "image/gif",
+  ".htm": "text/html; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+};
+
+export function previewRawMime(path: string): string | undefined {
+  const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+  const mime = rawMime[extension];
+  if (mime) return mime;
+  if (previewKind(path) === "code" || previewKind(path) === "table")
+    return "text/plain; charset=utf-8";
+  return undefined;
+}
+
+/**
+ * Media types servable through `/api/media` for inline `<video>`, `<audio>`,
+ * and `<img>` sources referenced by documents. Deliberately separate from
+ * `rawMime`: document previews decide kind through `previewKind`, while media
+ * sources just need a safe Content-Type. No HTML/SVG here — active content
+ * must never be served inline as media.
+ */
+const mediaMime: Record<string, string> = {
+  ".aac": "audio/aac",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".flac": "audio/flac",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".m4a": "audio/mp4",
+  ".m4v": "video/mp4",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".oga": "audio/ogg",
+  ".ogg": "audio/ogg",
+  ".ogv": "video/ogg",
+  ".opus": "audio/opus",
+  ".png": "image/png",
+  ".wav": "audio/wav",
+  ".webm": "video/webm",
+  ".webp": "image/webp",
+};
+
+export function mediaRawMime(path: string): string | undefined {
+  const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+  return mediaMime[extension];
+}

package/kernel/packages/markdown/README.md

@@ -0,0 +1,40 @@
+# @raggle-ai/markdown
+
+Internal BarackDown re-export consumed by every Kennel package that renders
+Markdown (`packages/ui`, `packages/agents`, `packages/api`, `packages/dist`,
+`packages/core-components`, `plugins/mail`, `cli`, and `apps/web`). The
+purpose of this tiny package is to be the single place where Kennel decides
+which BarkDown implementation it uses.
+
+## Swapping between published and local BarkDown
+
+All Kennel packages import `@raggle-ai/markdown` (`workspace:*`), and this
+package's only dependency is `@raggle-ai/barkdown`. Edit that one line here,
+run `bun install` at the repo root, and the whole workspace follows.
+
+### Published npm version (default)
+
+```json
+"dependencies": {
+  "@raggle-ai/barkdown": "0.4.0"
+}
+```
+
+### Local barkdown git checkout
+
+```json
+"dependencies": {
+  "@raggle-ai/barkdown": "file:../../../barkdown/packages/barkdown"
+}
+```
+
+The relative path starts from `packages/markdown/` up to the sibling of this
+repository. Note that Bun copies `file:` dependencies at install time, so
+after changing anything in the barkdown repo (`pnpm build` there), run
+`bun install` again in the kennel root to refresh the copied build.
+
+Original file paths (`@raggle-ai/barkdown`, `@raggle-ai/barkdown/explorer`,
+…) are re-exported one-to-one, including the two CSS entry points, so
+consumer imports only change from `@raggle-ai/barkdown` to
+`@raggle-ai/markdown`. The root export also provides `markdownMetadata` to
+parse and strip YAML frontmatter before rendering Markdown.

package/kernel/packages/markdown/explorer.css

@@ -0,0 +1 @@
+@import "@raggle-ai/barkdown/explorer.css";

package/kernel/packages/markdown/package.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@raggle-ai/markdown",
+  "version": "0.1.0",
+  "description": "Internal BarkDown re-export used by Kennel packages. Swap @raggle-ai/barkdown between the published npm version and the local git checkout by editing the single dependency below (see README.md).",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "packages/markdown"
+  },
+  "files": [
+    "src",
+    "styles.css",
+    "explorer.css"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./documents": "./src/documents.ts",
+    "./explorer": "./src/explorer.ts",
+    "./node": "./src/node.ts",
+    "./styles.css": "./styles.css",
+    "./explorer.css": "./explorer.css"
+  },
+  "dependencies": {
+    "@raggle-ai/barkdown": "0.6.1",
+    "yaml": "^2.9.0"
+  }
+}

package/kernel/packages/markdown/src/documents.ts

@@ -0,0 +1 @@
+export * from "@raggle-ai/barkdown/documents";

package/kernel/packages/markdown/src/explorer.ts

@@ -0,0 +1 @@
+export * from "@raggle-ai/barkdown/explorer";

package/kernel/packages/markdown/src/index.ts

@@ -0,0 +1,2 @@
+export * from "@raggle-ai/barkdown";
+export { markdownMetadata, type MarkdownMetadata } from "./metadata.ts";

package/kernel/packages/markdown/src/metadata.ts

@@ -0,0 +1,63 @@
+import { parseDocument } from "yaml";
+
+export type MarkdownMetadata = {
+  body: string;
+  entries: [string, unknown][];
+  lineOffset: number;
+  title?: string;
+};
+
+function frontmatter(content: string) {
+  const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(content);
+  if (!match) return undefined;
+
+  const parsed = parseDocument(match[1] ?? "");
+  const value = parsed.errors.length ? undefined : parsed.toJS();
+  const entries =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? Object.entries(value)
+      : [];
+  const title = entries.find(([key]) => key === "title")?.[1];
+  return {
+    body: content.slice(match[0].length),
+    entries,
+    lineOffset: (match[0].match(/\n/g) ?? []).length,
+    title: typeof title === "string" && title.trim() ? title.trim() : undefined,
+  };
+}
+
+function inlineTitle(value: string) {
+  return value
+    .replaceAll(/[`*_~[\]]/g, "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+}
+
+function leadingHeading(content: string) {
+  const lines = content.replace(/^\uFEFF/, "").split(/\r?\n/);
+  let index = 0;
+  while (index < lines.length && !lines[index]?.trim()) index += 1;
+
+  const first = lines[index]?.trimEnd();
+  if (!first) return undefined;
+
+  const atx = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(first);
+  if (atx?.[2]) return inlineTitle(atx[2]);
+
+  const second = lines[index + 1]?.trim();
+  if (second && /^(=+|-+)$/.test(second)) return inlineTitle(first.trim());
+
+  return undefined;
+}
+
+/** Extract valid YAML frontmatter before rendering the Markdown body. */
+export function markdownMetadata(content: string): MarkdownMetadata {
+  const metadata = frontmatter(content);
+  const body = metadata?.body ?? content;
+  return {
+    body,
+    entries: metadata?.entries ?? [],
+    lineOffset: metadata?.lineOffset ?? 0,
+    title: metadata?.title ?? leadingHeading(body),
+  };
+}

package/kernel/packages/markdown/src/node.ts

@@ -0,0 +1 @@
+export * from "@raggle-ai/barkdown/node";

package/kernel/packages/markdown/styles.css

@@ -0,0 +1 @@
+@import "@raggle-ai/barkdown/styles.css";

package/kernel/packages/notes/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: kennel-notes-plugin
+description: Maintain the Kennel Notes folder-view plugin.
+---
+
+# Kennel Notes plugin
+
+The Notes plugin owns the browser Notes tab UI and the notes-loading hook that
+keeps local Markdown notes separate from linked notes so the local list can
+render first.
+
+Unlike Calendar and Tasks, Notes does not use a single content file. The data
+comes from the Kennel metadata API, which scans Markdown files on the server and
+hydrates titles/open-path links. Keep that API-backed loading server-side; the
+client should only call the existing `/api/metadata?part=notes` endpoints and
+render the returned list.
+
+Keep the client entry browser-only. Do not import `./server` or `node:` modules
+from `src/client.tsx` or from modules that it imports.

package/kernel/packages/notes/eslint.config.js

@@ -0,0 +1,10 @@
+import baseConfig from "@raggle-ai/eslint-config/base"
+import reactConfig from "@raggle-ai/eslint-config/react"
+
+export default [
+  ...baseConfig,
+  ...reactConfig,
+  {
+    ignores: ["dist/**", "**/_generated/", "vendor/**"],
+  },
+]

package/kernel/packages/notes/package.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@raggle-ai/notes",
+  "version": "0.1.0",
+  "description": "Notes folder plugin: server-backed Markdown notes loading and React notes view for Kennel folders.",
+  "type": "module",
+  "license": "MIT",
+  "prettier": "@raggle-ai/prettier-config",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "plugins/notes"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.tsx",
+    "./manifest": "./src/manifest.ts",
+    "./parse": "./src/data/parse.ts",
+    "./pages/single-note-page": "./src/pages/single-note-page.tsx",
+    "./server": "./src/server.ts",
+    "./ui/folder-notes-list": "./src/ui/folder-notes-list.tsx"
+  },
+  "scripts": {
+    "test": "bun test test/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier . --check --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
+    "format:fix": "prettier . --write --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
+    "lint": "eslint . --cache --cache-location .cache/.eslintcache",
+    "lint:fix": "eslint . --fix --cache --cache-location .cache/.eslintcache",
+    "clean": "git clean -xdf dist node_modules .cache .turbo/cache",
+    "pack:check": "npm pack --dry-run",
+    "publish:public:dry-run": "npm --@raggle-ai:registry=https://registry.npmjs.org publish --dry-run --access public --registry=https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@raggle-ai/folder-plugin": "workspace:*",
+    "@raggle-ai/ui": "workspace:*",
+    "@tanstack/react-query": "catalog:tanstack",
+    "lucide-react": "^0.562.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.3.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "catalog:eslint",
+    "@eslint/eslintrc": "catalog:eslint",
+    "@ianvs/prettier-plugin-sort-imports": "catalog:prettier",
+    "@prettier/plugin-oxc": "catalog:prettier",
+    "@raggle-ai/eslint-config": "workspace:*",
+    "@raggle-ai/prettier-config": "workspace:*",
+    "@raggle-ai/tsconfig": "workspace:*",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:react19",
+    "@types/react-dom": "catalog:react19",
+    "eslint": "catalog:eslint",
+    "eslint-plugin-unused-imports": "catalog:eslint",
+    "prettier": "catalog:prettier",
+    "prettier-plugin-classnames": "catalog:prettier",
+    "prettier-plugin-merge": "catalog:prettier",
+    "prettier-plugin-tailwindcss": "catalog:prettier",
+    "react": "catalog:react19",
+    "react-dom": "catalog:react19",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:eslint"
+  }
+}

package/kernel/packages/notes/src/client.tsx

@@ -0,0 +1,12 @@
+import type { FolderPluginClient } from "@raggle-ai/folder-plugin/client"
+
+import { notesManifest } from "./manifest.ts"
+import { NotesPage } from "./pages/notes-page.tsx"
+
+export { NotesPage } from "./pages/notes-page.tsx"
+export { useFolderNotes } from "./data/use-folder-notes.ts"
+
+export const notesClient = {
+  ...notesManifest,
+  component: NotesPage,
+} satisfies FolderPluginClient

package/kernel/packages/notes/src/data/ai-input.ts

@@ -0,0 +1,58 @@
+import type { ComponentType } from "react"
+import { useEffect, useState } from "react"
+
+export type AiInputAdapter = {
+  Composer: ComponentType
+  install?: () => void | Promise<void>
+}
+
+const adapterPromises = new Map<string, Promise<AiInputAdapter>>()
+
+async function loadAiInput(folder?: string) {
+  const url = new URL("/api/config", window.location.origin)
+  if (folder) url.searchParams.set("path", folder)
+  const response = await fetch(url)
+  if (!response.ok) return null
+  const config = (await response.json()) as { aiInputModule?: unknown }
+  const moduleUrl = config.aiInputModule
+  if (typeof moduleUrl !== "string" || !moduleUrl) return null
+  const existing = adapterPromises.get(moduleUrl)
+  if (existing) return existing
+
+  const adapterPromise = import(/* @vite-ignore */ moduleUrl).then((module) => {
+    const adapter = module.default as AiInputAdapter | undefined
+    if (!adapter?.Composer) {
+      throw new Error(
+        "The AI input module must default-export an adapter with a Composer component.",
+      )
+    }
+    return adapter
+  })
+  adapterPromises.set(moduleUrl, adapterPromise)
+  return adapterPromise
+}
+
+export function useAiInput(folder?: string) {
+  const [loaded, setLoaded] = useState<{
+    folder?: string
+    adapter: AiInputAdapter | null
+  }>()
+
+  useEffect(() => {
+    let active = true
+    void loadAiInput(folder)
+      .then(async (value) => {
+        if (!active) return
+        await value?.install?.()
+        if (active) setLoaded({ folder, adapter: value })
+      })
+      .catch((error: unknown) => {
+        console.error("Could not load the configured AI input adapter.", error)
+      })
+    return () => {
+      active = false
+    }
+  }, [folder])
+
+  return loaded?.folder === folder ? (loaded?.adapter ?? null) : null
+}

package/kernel/packages/notes/src/data/api.ts

@@ -0,0 +1,40 @@
+import type { FolderFile } from "@raggle-ai/ui/lib/folder-activity"
+
+export type NotesScope = "local" | "linked"
+
+export type NotesMetadata = {
+  files: { items: FolderFile[] }
+  folder: string
+}
+
+export async function fetchMetadataPart(
+  href: string,
+  part: "notes",
+  options: {
+    signal?: AbortSignal
+    notesScope?: NotesScope
+    headers?: Record<string, string>
+  } = {},
+): Promise<NotesMetadata> {
+  const current = new URL(href, window.location.origin)
+  const url = new URL("/api/metadata", window.location.origin)
+  const route = current.pathname.split("/").filter(Boolean)
+  const encoded = route[0] === "folder" ? route[1] : undefined
+  const folder = current.searchParams.get("folder")
+  if (folder) url.searchParams.set("path", folder)
+  else if (encoded) {
+    const base64 = encoded.replaceAll("-", "+").replaceAll("_", "/")
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=")
+    const binary = atob(padded)
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0))
+    url.searchParams.set("path", new TextDecoder().decode(bytes))
+  }
+  url.searchParams.set("part", part)
+  if (options.notesScope) url.searchParams.set("notesScope", options.notesScope)
+  const response = await fetch(url, {
+    headers: options.headers,
+    signal: options.signal,
+  })
+  if (!response.ok) throw new Error(await response.text())
+  return (await response.json()) as NotesMetadata
+}

package/kernel/packages/notes/src/data/parse.ts

@@ -0,0 +1,15 @@
+export type NotesFile = Record<string, unknown>
+export type NotesDataset = {
+  files: { items: NotesFile[] }
+  folder: string
+}
+
+export function parseNotesDataset(value: unknown): NotesDataset | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const data = value as { files?: unknown; folder?: unknown }
+  const files = data.files as { items?: unknown } | undefined
+  if (typeof data.folder !== "string" || !Array.isArray(files?.items)) {
+    return undefined
+  }
+  return { files: { items: files.items as NotesFile[] }, folder: data.folder }
+}

package/kernel/packages/notes/src/data/routing.ts

@@ -0,0 +1,33 @@
+export function folderPathId(path: string) {
+  const bytes = new TextEncoder().encode(path)
+  let binary = ""
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replaceAll("=", "")
+}
+
+export function parseViewerRoute(href: string) {
+  const url = new URL(href, window.location.origin)
+  const parts = url.pathname.split("/").filter(Boolean)
+  const folderIndex = parts.indexOf("folder")
+  const encoded = folderIndex >= 0 ? parts[folderIndex + 1] : undefined
+  let folder = url.searchParams.get("folder") ?? undefined
+  if (!folder && encoded) {
+    const base64 = encoded.replaceAll("-", "+").replaceAll("_", "/")
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=")
+    const binary = atob(padded)
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0))
+    folder = new TextDecoder().decode(bytes)
+  }
+  return { folder }
+}
+
+export function folderSectionHref(folder: string, section: string) {
+  return `/folder/${folderPathId(folder)}/${section}`
+}
+
+export function folderDocumentHref(folder: string, document: string) {
+  return `/folder/${folderPathId(folder)}/document/${folderPathId(document)}`
+}

package/kernel/packages/notes/src/data/use-folder-notes.ts

@@ -0,0 +1,49 @@
+import { useMemo, useRef } from "react"
+import { useQuery } from "@tanstack/react-query"
+
+import { fetchMetadataPart } from "./api.ts"
+import { folderPathId, parseViewerRoute } from "./routing.ts"
+
+// Shared keys let the shell start requests before the lazy Notes page arrives.
+// Both observers reuse the same requests and keep sidebar counts in sync.
+export function useFolderNotes(href: string, enabled = true) {
+  const retryLinked = useRef(false)
+  const folder = parseViewerRoute(href).folder
+  const folderId = folder ? folderPathId(folder) : "none"
+  const options = (notesScope: "local" | "linked") => ({
+    enabled: enabled && Boolean(folder),
+    gcTime: 5 * 60_000,
+    queryFn: ({ signal }: { signal: AbortSignal }) => {
+      const retry = notesScope === "linked" && retryLinked.current
+      if (retry) retryLinked.current = false
+      return fetchMetadataPart(href, "notes", {
+        headers: retry ? { "x-kennel-retry-linked": "1" } : undefined,
+        notesScope,
+        signal,
+      })
+    },
+    queryKey: ["folder", folderId, "notes", notesScope],
+    staleTime: 15_000,
+  })
+  const local = useQuery(options("local"))
+  const linked = useQuery(options("linked"))
+  const files = useMemo(
+    () =>
+      local.data || linked.data
+        ? [
+            ...(local.data?.files.items ?? []),
+            ...(linked.data?.files.items ?? []),
+          ]
+        : undefined,
+    [local.data, linked.data],
+  )
+  return {
+    local,
+    linked,
+    files,
+    retryLinked: () => {
+      retryLinked.current = true
+      void linked.refetch()
+    },
+  }
+}

package/kernel/packages/notes/src/index.ts

@@ -0,0 +1,2 @@
+export { notesClient, NotesPage } from "./client.tsx"
+export { notesManifest } from "./manifest.ts"