kennel 0.2.1 → 0.2.3

package/kernel/apps/web/src/deferred-ask-tray.tsx

@@ -0,0 +1,20 @@
+import { lazy, Suspense } from "react"
+
+import { useAskAi } from "./use-ask-ai"
+import { useAskDraft } from "./use-ask-draft"
+
+const AskTray = lazy(async () => ({
+  default: (await import("./ask-tray")).AskTray,
+}))
+
+export function DeferredAskTray({ folder }: { folder: string }) {
+  const { enabled } = useAskAi()
+  const { draft } = useAskDraft(folder)
+  if (!enabled && !draft.comments.length && !draft.attachments.length)
+    return null
+  return (
+    <Suspense fallback={null}>
+      <AskTray folder={folder} />
+    </Suspense>
+  )
+}

package/kernel/apps/web/src/document-url.ts

@@ -0,0 +1,46 @@
+import type { DocumentResponse } from "~/api-client"
+import { api } from "~/api-client"
+
+import { parseViewerRoute } from "./viewer-route.js"
+
+export type { DocumentResponse } from "~/api-client"
+
+export function documentViewerParams(href: string) {
+  return new URL(href, window.location.origin).searchParams
+}
+
+export function documentUrl(origin: string, search: string, file: string) {
+  const url = new URL("/api/document", origin)
+  const { folder } = parseViewerRoute(search)
+  if (folder?.startsWith("/")) url.searchParams.set("path", folder)
+  url.searchParams.set("file", file)
+  return `${url.pathname}${url.search}`
+}
+
+export { documentResponse } from "~/api-client"
+
+export async function fetchDocument(href: string, file: string) {
+  return api.document(href, file)
+}
+
+/**
+ * Download URL for a served document. Non-text kinds already carry a
+ * `rawUrl`; text kinds derive the same raw endpoint for the file. HTML is
+ * always served as an attachment by `/api/raw`, so this is never inline
+ * active content.
+ */
+export function documentDownloadUrl(
+  document: DocumentResponse,
+): string | undefined {
+  if (document.rawUrl) {
+    return `${document.rawUrl}${document.rawUrl.includes("?") ? "&" : "?"}download=1`
+  }
+  if (document.root) {
+    const url = new URL("/api/raw", window.location.origin)
+    url.searchParams.set("path", document.root)
+    url.searchParams.set("file", document.path)
+    url.searchParams.set("download", "1")
+    return `${url.pathname}${url.search}`
+  }
+  return undefined
+}

package/kernel/apps/web/src/documents-url.ts

@@ -0,0 +1,23 @@
+import { parseViewerRoute } from "./viewer-route.js"
+
+export function viewerParams(search: string) {
+  return parseViewerRoute(search)
+}
+
+export function isEmbeddedViewer(search: string) {
+  return viewerParams(search).embedded
+}
+
+export function documentsUrl(origin: string, search: string) {
+  const url = new URL("/api/documents", origin)
+  const { folder } = viewerParams(search)
+  if (folder?.startsWith("/")) url.searchParams.set("path", folder)
+  return `${url.pathname}${url.search}`
+}
+
+export function openFolderUrl(origin: string, search: string) {
+  return documentsUrl(origin, search).replace(
+    "/api/documents",
+    "/api/open-folder",
+  )
+}

package/kernel/apps/web/src/dropped-folder.ts

@@ -0,0 +1,64 @@
+import type {
+  BarkdownDataset,
+  BarkdownDocument,
+} from "@raggle-ai/markdown/explorer"
+import { documentKind } from "@raggle-ai/markdown/documents"
+
+type DroppedFileHandle = {
+  kind: "file"
+  name: string
+  getFile(): Promise<File>
+}
+
+type DroppedDirectoryHandle = {
+  kind: "directory"
+  name: string
+  values(): AsyncIterable<DroppedDirectoryHandle | DroppedFileHandle>
+}
+
+async function readDirectory(
+  directory: DroppedDirectoryHandle,
+  parent = "",
+): Promise<BarkdownDocument[]> {
+  const documents: BarkdownDocument[] = []
+
+  for await (const handle of directory.values()) {
+    const path = parent ? `${parent}/${handle.name}` : handle.name
+    if (handle.kind === "directory") {
+      documents.push(...(await readDirectory(handle, path)))
+      continue
+    }
+
+    const kind = documentKind(handle.name)
+    if (!kind) continue
+    const file = await handle.getFile()
+    documents.push({ path, content: await file.text(), kind })
+  }
+
+  return documents
+}
+
+export async function readDroppedFolder(
+  directory: DroppedDirectoryHandle,
+): Promise<BarkdownDataset> {
+  const documents = await readDirectory(directory)
+  documents.sort((left, right) => left.path.localeCompare(right.path))
+  return { root: directory.name, documents }
+}
+
+export async function droppedDirectory(items: DataTransferItemList) {
+  for (const item of items) {
+    if (item.kind !== "file") continue
+    const getHandle = (
+      item as DataTransferItem & {
+        getAsFileSystemHandle?: () => Promise<FileSystemHandle | null>
+      }
+    ).getAsFileSystemHandle
+    if (!getHandle) throw new Error("This browser cannot read dropped folders.")
+    const handle = await getHandle.call(item)
+    if (handle?.kind === "directory") {
+      return handle as unknown as DroppedDirectoryHandle
+    }
+  }
+  throw new Error("Drop one folder to open it.")
+}

package/kernel/apps/web/src/external-plugins.ts

@@ -0,0 +1,3 @@
+import type { FolderPluginClient } from "@raggle-ai/folder-plugin/client"
+
+export const externalFolderPlugins: FolderPluginClient[] = []

package/kernel/apps/web/src/file-viewer.tsx

@@ -0,0 +1,171 @@
+import { useEffect, useMemo, useState } from "react"
+import { ChevronDown } from "lucide-react"
+
+import type {
+  BarkdownDataset,
+  BarkdownSource,
+} from "@raggle-ai/markdown/explorer"
+import { BarkdownContent, markdownMetadata } from "@raggle-ai/markdown"
+import {
+  documentTitle,
+  resolveEmbeddedHtmlPath,
+} from "@raggle-ai/markdown/explorer"
+
+function MetadataValue({ value }: { value: unknown }) {
+  if (Array.isArray(value))
+    return (
+      <span className="flex flex-wrap gap-1.5">
+        {value.map((item, index) => (
+          <span key={`${index}-${String(item)}`}>{String(item)}</span>
+        ))}
+      </span>
+    )
+  if (typeof value === "boolean") return value ? "Yes" : "No"
+  if (typeof value === "object" && value) return JSON.stringify(value)
+  return String(value ?? "")
+}
+
+/**
+ * Document details panel from the Markdown frontmatter. Collapsed by default —
+ * the reader expands it when the metadata matters.
+ */
+function FolderFrontmatter({ entries }: { entries: [string, unknown][] }) {
+  return (
+    <details className="frontmatter">
+      <summary>
+        <span>Document details</span>
+        <small>{entries.length} fields</small>
+        <ChevronDown aria-hidden="true" />
+      </summary>
+      <dl>
+        {entries.map(([key, value]) => (
+          <div key={key}>
+            <dt>{key.replaceAll(/[-_]/g, " ")}</dt>
+            <dd>
+              <MetadataValue value={value} />
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </details>
+  )
+}
+
+/**
+ * Folder document content rendered by Kennel itself, with the same loading
+ * behavior as barkdown's `BarkdownDocument` but two deliberate differences:
+ * headings are never wrapped into collapse controls (sections stay flat and
+ * open), and the frontmatter details panel is collapsed by default. Barkdown's
+ * own `htmlEmbed` extension point stays wired from the in-memory folder
+ * list, so ```barkdown-html blocks keep embedding sibling HTML files.
+ */
+function FolderDocument({
+  dataset,
+  path,
+}: {
+  dataset: BarkdownDataset
+  path?: string
+}) {
+  const document = useMemo(() => {
+    if (path) return dataset.documents.find((item) => item.path === path)
+    return (
+      dataset.documents.find(
+        (item) => item.path.toLowerCase() === "readme.md",
+      ) ?? dataset.documents[0]
+    )
+  }, [dataset, path])
+
+  if (!document)
+    return <p className="barkdown-document-empty">No document found.</p>
+
+  const metadata =
+    document.kind === "markdown"
+      ? markdownMetadata(document.content)
+      : { body: document.content, entries: [] as [string, unknown][] }
+
+  return (
+    <article
+      className={document.kind === "html" ? "document is-html" : "document"}
+      tabIndex={-1}
+    >
+      {metadata.entries.length ? (
+        <FolderFrontmatter entries={metadata.entries} />
+      ) : null}
+      {document.kind === "html" ? (
+        <iframe
+          className="html-document"
+          sandbox=""
+          srcDoc={document.content}
+          title={documentTitle(document.path)}
+        />
+      ) : document.kind === "markdown" ? (
+        <BarkdownContent
+          headingCopyPath={
+            dataset.root
+              ? `${dataset.root.replace(/\/+$/, "")}/${document.path}`
+              : undefined
+          }
+          mode="markdown"
+          value={metadata.body}
+          htmlEmbed={(embed) => {
+            const resolved = resolveEmbeddedHtmlPath(document.path, embed)
+            const embedded = dataset.documents.find(
+              (item) => item.kind === "html" && item.path === resolved,
+            )
+            return embedded?.content
+          }}
+        />
+      ) : (
+        <pre className="text-document">{document.content}</pre>
+      )}
+    </article>
+  )
+}
+
+export function FileViewer({
+  path,
+  source,
+}: {
+  path?: string
+  source: BarkdownSource
+}) {
+  const [data, setData] = useState<BarkdownDataset>()
+  const [error, setError] = useState("")
+
+  useEffect(() => {
+    let active = true
+    void source
+      .read()
+      .then((result) => {
+        if (!active) return
+        setData(result)
+        setError("")
+      })
+      .catch((reason: unknown) => {
+        if (!active) return
+        setError(
+          reason instanceof Error ? reason.message : "Could not load file.",
+        )
+      })
+    return () => {
+      active = false
+    }
+  }, [source])
+
+  return (
+    <div
+      className="fixed inset-0 z-30 overflow-auto bg-white"
+      data-file-viewer=""
+    >
+      <div className="mx-auto max-w-[900px] px-6 py-8">
+        {error ? (
+          <p className="barkdown-document-error">{error}</p>
+        ) : !data ? (
+          <p className="barkdown-document-loading">Loading file…</p>
+        ) : (
+          <FolderDocument dataset={data} path={path} />
+        )}
+      </div>
+    </div>
+  )
+}

package/kernel/apps/web/src/folder-filter-icons.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from "react"
+import { useQuery } from "@tanstack/react-query"
+import { api } from "~/api-client"
+
+import { folderPathId } from "@raggle-ai/folder-plugin/client"
+import { FolderFilterIconProvider } from "@raggle-ai/ui/components/folder-filter-bar"
+import { FolderImage } from "@raggle-ai/ui/components/folder-image"
+
+import { folderSectionHref } from "./viewer-route"
+
+function MetadataFolderIcon({ folder }: { folder: string }) {
+  const { data } = useQuery({
+    // Reuse the folder shell's identity cache, including its invalidations.
+    queryKey: ["folder", folderPathId(folder), "identity"],
+    queryFn: ({ signal }) =>
+      api.metadata(folderSectionHref(folder, "notes"), "identity", { signal }),
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false,
+  })
+  const icon = data?.iconAssetKey ? data.assets[data.iconAssetKey] : undefined
+  // Missing, unauthorized, loading, and broken images all keep the fallback.
+  return <FolderImage icon={icon} />
+}
+
+function renderIcon(folder: string) {
+  return <MetadataFolderIcon key={folder} folder={folder} />
+}
+
+export function FolderFilterMetadataProvider({
+  children,
+}: {
+  children: ReactNode
+}) {
+  return (
+    <FolderFilterIconProvider renderIcon={renderIcon}>
+      {children}
+    </FolderFilterIconProvider>
+  )
+}

package/kernel/apps/web/src/folder-metadata.ts

@@ -0,0 +1,76 @@
+import type { MetadataOptions, MetadataPart } from "~/api-client"
+import { useEffect } from "react"
+import { useQuery } from "@tanstack/react-query"
+import { api } from "~/api-client"
+
+import { folderPathId, parseViewerRoute } from "./viewer-route.js"
+
+export type { MetadataPart } from "~/api-client"
+
+export function metadataUrl(
+  origin: string,
+  search: string,
+  options: { part?: MetadataPart; notesScope?: "local" | "linked" } = {},
+) {
+  const url = new URL("/api/metadata", origin)
+  const { folder } = parseViewerRoute(search)
+  if (folder?.startsWith("/")) url.searchParams.set("path", folder)
+  if (options.part) url.searchParams.set("part", options.part)
+  if (options.notesScope) url.searchParams.set("notesScope", options.notesScope)
+  return `${url.pathname}${url.search}`
+}
+
+export function fetchMetadataPart<P extends MetadataPart>(
+  href: string,
+  part: P,
+  options: MetadataOptions = {},
+) {
+  return api.metadata(href, part, options)
+}
+
+const defaultTitle = "Kennel"
+const defaultFavicon = "/favicon.svg"
+
+/** Leaf folder name, or undefined when the route carries no folder. */
+function folderName(folder: string | undefined) {
+  return folder?.replace(/\/+$/, "").split("/").pop()
+}
+
+function faviconLink() {
+  const existing =
+    document.head.querySelector<HTMLLinkElement>('link[rel="icon"]')
+  if (existing) return existing
+  const link = document.createElement("link")
+  link.rel = "icon"
+  document.head.append(link)
+  return link
+}
+
+/**
+ * Applies the folder's name and icon to the page metadata: the tab title is
+ * "%name - Kennel" and the favicon is the folder's own icon (local asset or
+ * website favicon). Shares the shell's identity query by key, so no extra
+ * request is made.
+ */
+export function useFolderPageMetadata(href: string, enabled = true) {
+  const folder = parseViewerRoute(href).folder
+  const folderId = folder ? folderPathId(folder) : "none"
+  const identity = useQuery({
+    enabled: enabled && Boolean(folder),
+    gcTime: Number.POSITIVE_INFINITY,
+    queryFn: ({ signal }) => fetchMetadataPart(href, "identity", { signal }),
+    queryKey: ["folder", folderId, "identity"] as const,
+    staleTime: Number.POSITIVE_INFINITY,
+  })
+  const name = folderName(folder)
+  const icon = identity.data?.iconAssetKey
+    ? identity.data.assets[identity.data.iconAssetKey]
+    : undefined
+  const src =
+    icon?.url ??
+    (icon?.data ? `data:${icon.mediaType};base64,${icon.data}` : undefined)
+  useEffect(() => {
+    document.title = name ? `${name} - Kennel` : defaultTitle
+    faviconLink().href = src ?? defaultFavicon
+  }, [name, src])
+}

package/kernel/apps/web/src/folder-plugin-view.tsx

@@ -0,0 +1,87 @@
+import { useParams } from "@tanstack/react-router"
+import { api } from "~/api-client"
+
+import type { FolderPluginViewProps } from "@raggle-ai/folder-plugin/client"
+
+import { FolderFilterMetadataProvider } from "./folder-filter-icons"
+import { getFolderPlugin } from "./plugins"
+import { useViewerCapabilities } from "./viewer-capabilities"
+import {
+  decodeFolderPathId,
+  folderDocumentHref,
+  folderPluginHref,
+  folderSectionHref,
+} from "./viewer-route"
+
+function pluginRequest(
+  pluginId: string,
+  folder: string,
+  subpath: string,
+  init?: RequestInit,
+) {
+  return api.plugin(pluginId, folder, subpath, init)
+}
+
+const unknownState = {
+  backHref: "/",
+  message: "That view is not registered.",
+}
+
+export function FolderPluginPage() {
+  const params = useParams({
+    strict: false,
+  }) as {
+    folderId?: string
+    pluginId?: string
+    subpath?: string
+  }
+  const capabilities = useViewerCapabilities()
+  const plugin = getFolderPlugin(params.pluginId)
+  if (!plugin || !params.folderId) {
+    return (
+      <div className="mx-auto grid w-full max-w-3xl gap-4 px-4 py-5">
+        <p className="text-muted-foreground m-0 text-sm">
+          {unknownState.message}
+        </p>
+        <a
+          className="bg-background inline-flex w-fit items-center justify-center
+            rounded-md border px-3 py-1.5 text-sm no-underline"
+          href={unknownState.backHref}
+        >
+          Back to folder
+        </a>
+      </div>
+    )
+  }
+
+  const folder = decodeFolderPathId(params.folderId)
+  const folderId = params.folderId
+  const hostActions =
+    capabilities.data?.hostActions === "local"
+      ? {
+          openPath: (path: string) => api.openPath(path),
+          createAgentFile: async (folder: string) => {
+            const created = await api.createAgentFile(folder)
+            await api.openPath(created.path)
+            return created
+          },
+        }
+      : undefined
+  const view: FolderPluginViewProps = {
+    documentHref: folderDocumentHref,
+    folder,
+    folderId,
+    homeHref: folderSectionHref(folder, "notes"),
+    hostActions,
+    href: (subpath) => folderPluginHref(folder, plugin.id, subpath),
+    listHref: folderPluginHref(folder, plugin.id),
+    request: (subpath, init) => pluginRequest(plugin.id, folder, subpath, init),
+    subpath: params.subpath ?? "",
+  }
+  const Component = plugin.component
+  return (
+    <FolderFilterMetadataProvider>
+      <Component {...view} />
+    </FolderFilterMetadataProvider>
+  )
+}

package/kernel/apps/web/src/folder-query-cache.ts

@@ -0,0 +1,66 @@
+const databaseName = "kennel-folder-query-cache"
+const storeName = "queries"
+const version = 1
+const maxAge = 7 * 24 * 60 * 60 * 1_000
+
+type CacheRecord<T> = {
+  data: T
+  savedAt: number
+  version: number
+}
+
+function openCache() {
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open(databaseName, version)
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(storeName)
+    }
+    request.onerror = () => reject(request.error)
+    request.onsuccess = () => resolve(request.result)
+  })
+}
+
+async function withStore<T>(
+  mode: IDBTransactionMode,
+  run: (store: IDBObjectStore) => IDBRequest<T>,
+) {
+  const database = await openCache()
+  return new Promise<T>((resolve, reject) => {
+    const transaction = database.transaction(storeName, mode)
+    const request = run(transaction.objectStore(storeName))
+    request.onerror = () => reject(request.error)
+    request.onsuccess = () => resolve(request.result)
+    transaction.oncomplete = () => database.close()
+    transaction.onerror = () => {
+      database.close()
+      reject(transaction.error)
+    }
+  })
+}
+
+export async function readFolderQueryCache<T>(key: readonly unknown[]) {
+  const record = await withStore<CacheRecord<T> | undefined>(
+    "readonly",
+    (store) => store.get(JSON.stringify(key)),
+  ).catch(() => undefined)
+  if (record?.version !== version) return undefined
+  if (Date.now() - record.savedAt > maxAge) return undefined
+  return record.data
+}
+
+export async function writeFolderQueryCache<T>(
+  key: readonly unknown[],
+  data: T | undefined,
+) {
+  if (!data) return
+  await withStore<IDBValidKey>("readwrite", (store) =>
+    store.put(
+      {
+        data,
+        savedAt: Date.now(),
+        version,
+      } satisfies CacheRecord<T>,
+      JSON.stringify(key),
+    ),
+  ).catch(() => undefined)
+}