kennel 0.2.0 → 0.2.2

package/kernel/packages/ui/src/lib/folder-filter.ts

@@ -0,0 +1,284 @@
+/**
+ * Generalized folder filtering for lists of items that carry an owning
+ * folder path.
+ *
+ * Pure string/array logic — no React, no DOM, no `node:` builtins — so the
+ * exact same helpers power web chips, folder-plugin views, and CLI
+ * filtering. The model mirrors the mail plugin's draft selector but is
+ * accessor-driven: you hand over your items, a function that reads each
+ * item's owning folder, and the viewed root folder; you get back the
+ * distinct folder choices (root first, then descendants by relative path,
+ * each with a count) and a predicate that decides which items a selection
+ * keeps.
+ *
+ * CLI example (no React):
+ *
+ * ```ts
+ * import {
+ *   folderFilterChoices,
+ *   folderFilterMatches,
+ * } from "@raggle-ai/ui/lib/folder-filter"
+ *
+ * const choices = folderFilterChoices(items, root, (item) => item.folder)
+ * const visible = items.filter((item) =>
+ *   folderFilterMatches(item.folder, flags.folder, "subtree"),
+ * )
+ * ```
+ */
+
+/** How a selected folder applies to an item's owning folder. */
+export type FolderFilterMode = "exact" | "subtree"
+
+/**
+ * One clickable chip: a distinct owning folder in the item list. `folder`
+ * is the full owning path and the exact filter key (duplicate leaf names
+ * stay distinct); `label` is the short display text (basename for the
+ * root, relative path for descendants).
+ */
+export type FolderFilterChoice = {
+  /** Exact owning folder path — the filter key. */
+  folder: string
+  /** Number of items owned by this folder. */
+  count: number
+  /** Short display label: basename for the root, relative path for descendants. */
+  label: string
+  /** Path relative to the viewed root; "" for the root itself. */
+  relativePath: string
+}
+
+/**
+ * A selection for folder filtering: a single owning folder, several
+ * (multi-select — an item passes when any of them matches), or null/
+ * empty for "all items". Single-string callers keep working unchanged.
+ */
+export type FolderSelection = string | readonly string[] | null
+
+function normalized(value: string) {
+  return value.replaceAll("\\", "/").replace(/\/+$/, "")
+}
+
+/**
+ * Relative path of `folder` below `rootFolder`, "" for the root itself, or
+ * null when `folder` is not the root or a real descendant. Pure string
+ * traversal so it stays browser-safe (no `node:path`): sibling prefixes,
+ * ".." escapes, and outside ancestors resolve to null.
+ */
+export function folderFilterRelativePath(
+  folder: string,
+  rootFolder: string,
+): string | null {
+  const root = normalized(rootFolder)
+  const candidate = normalized(folder)
+  if (!root || !candidate) return null
+  if (candidate === root) return ""
+  if (!candidate.startsWith(`${root}/`)) return null
+  const relative = candidate.slice(root.length + 1)
+  if (!relative) return null
+  if (
+    relative.split("/").some((segment) => segment === ".." || segment === ".")
+  )
+    return null
+  return relative
+}
+
+function rootLabel(rootFolder: string) {
+  return (
+    normalized(rootFolder)
+      .split("/")
+      .filter((segment) => Boolean(segment))
+      .at(-1) ?? "This folder"
+  )
+}
+
+function baseName(value: string) {
+  return (
+    normalized(value)
+      .split("/")
+      .filter((segment) => Boolean(segment))
+      .at(-1) ?? value
+  )
+}
+
+/**
+ * Display text for a folder relative to the viewed root: basename for
+ * root-owned items, relative path for descendants. Null when the folder is
+ * absent or does not live under the viewed root.
+ */
+export function folderFilterLabel(
+  folder: string | null,
+  rootFolder: string,
+): string | null {
+  if (!folder) return null
+  const relative = folderFilterRelativePath(folder, rootFolder)
+  if (relative === null) return null
+  return relative || rootLabel(rootFolder)
+}
+
+export type FolderFilterChoicesOptions = {
+  /**
+   * Include folders that are not the root or a descendant (e.g. ancestor
+   * "parent" folders, repository or global directories). Their chips use the
+   * leaf basename as the label so they stay compact. Defaults to false —
+   * mail-style exact scoping keeps outside folders out of the chips.
+   */
+  allowOutside?: boolean
+}
+
+/**
+ * Distinct owning-folder choices with per-folder counts for filtering an
+ * item list. Keyed by the full folder path so duplicate leaf names stay
+ * distinct; ordered with the root folder first, then descendants
+ * alphabetically by relative path. Items without a folder are skipped.
+ *
+ * By default folders outside the viewed root are skipped; pass `{
+ * allowOutside: true }` to also surface ancestor/parent and unrelated
+ * folders as chips (leaf name labels).
+ */
+export function folderFilterChoices<T>(
+  items: readonly T[],
+  rootFolder: string,
+  getFolder: (item: T) => string | null,
+  options?: FolderFilterChoicesOptions,
+): FolderFilterChoice[] {
+  const counts = new Map<string, number>()
+  for (const item of items) {
+    const folder = getFolder(item)
+    if (!folder) continue
+    const contained = folderFilterRelativePath(folder, rootFolder)
+    if (contained === null && !options?.allowOutside) continue
+    counts.set(folder, (counts.get(folder) ?? 0) + 1)
+  }
+
+  const choices: FolderFilterChoice[] = []
+  for (const [folder, count] of counts) {
+    const contained = folderFilterRelativePath(folder, rootFolder)
+    const relativePath =
+      contained ?? (options?.allowOutside ? baseName(folder) : "")
+    choices.push({
+      count,
+      folder,
+      label: relativePath || rootLabel(rootFolder),
+      relativePath,
+    })
+  }
+  return choices.sort((a, b) => {
+    if (a.relativePath === "") return -1
+    if (b.relativePath === "") return 1
+    return a.relativePath.localeCompare(b.relativePath)
+  })
+}
+
+function matchTarget(
+  folder: string | null,
+  target: string,
+  mode: FolderFilterMode,
+): boolean {
+  if (!folder) return false
+  const candidate = normalized(folder)
+  const goal = normalized(target)
+  if (mode === "subtree")
+    return candidate === goal || candidate.startsWith(`${goal}/`)
+  return candidate === goal
+}
+
+/**
+ * Does an item's owning folder survive the current selection?
+ *
+ * - `selected` null or [] → every item passes ("all").
+ * - `selected` a single folder with `mode: "exact"` → only items owned by
+ *   that folder exactly.
+ * - `selected` a single folder with `mode: "subtree"` → items in that
+ *   folder or any descendant, so picking a parent folder keeps everything
+ *   beneath it.
+ * - `selected` an array → items matching *any* entry (each with `mode`),
+ *   so a multi-select keeps the union of the chosen folders.
+ *
+ * Paths are normalized on both sides so trailing slashes never break a
+ * match.
+ */
+export function folderFilterMatches(
+  folder: string | null,
+  selected: FolderSelection,
+  mode: FolderFilterMode = "exact",
+): boolean {
+  if (selected === null || selected === "") return true
+  if (Array.isArray(selected)) {
+    if (selected.length === 0) return true
+    return selected.some((entry) => folderFilterMatches(folder, entry, mode))
+  }
+  // `Array.isArray` does not narrow `readonly string[]` out of the union,
+  // but the array branch already returned — remaining value is a string.
+  return matchTarget(folder, selected as string, mode)
+}
+
+export type FolderFilterApply<T> = {
+  /** Owning folder of each item, or null when the item has none. */
+  getFolder: (item: T) => string | null
+  /** Items to filter. */
+  items: readonly T[]
+  /** Folder everything is shown relative to (the viewed root). */
+  rootFolder: string
+  /** "exact" matches the selected folder only; "subtree" also matches its descendants. */
+  mode?: FolderFilterMode
+  /** Include ancestor/outside folders as chips (see `folderFilterChoices`). */
+  allowOutside?: boolean
+  /**
+   * Raw selection (owning folder path(s)) or null for "all items". Entries
+   * that no longer match any item — e.g. after a refetch removed their last
+   * draft — are dropped from `effectiveSelected` rather than showing a
+   * dead-end list.
+   */
+  selected: FolderSelection
+}
+
+export type FolderFilterResult<T> = {
+  /** Distinct owning-folder choices with counts, root first. */
+  choices: FolderFilterChoice[]
+  /**
+   * Selection entries that still match items. Empty means "all items" —
+   * either nothing was selected or every selected folder lost its items.
+   */
+  effectiveSelected: readonly string[]
+  /** Number of items before filtering — shown on the "All" chip. */
+  total: number
+  /** Items after applying the effective selection. */
+  visibleItems: T[]
+}
+
+/**
+ * One-shot derivation for a folder-filtered list: build the choices,
+ * reconcile the selection against the current items, and filter. This is
+ * the pure core the `useFolderFilter` hook wraps — call it directly from
+ * CLI or non-React code.
+ */
+export function applyFolderFilter<T>(
+  input: FolderFilterApply<T>,
+): FolderFilterResult<T> {
+  const {
+    allowOutside,
+    getFolder,
+    items,
+    mode = "exact",
+    rootFolder,
+    selected,
+  } = input
+  const choices = folderFilterChoices(items, rootFolder, getFolder, {
+    allowOutside,
+  })
+
+  const rawEntries =
+    selected === null ? [] : Array.isArray(selected) ? selected : [selected]
+  // Drop selections whose folders no longer own any item (stale refetch).
+  const effectiveSelected = rawEntries.filter((entry) =>
+    items.some((item) => folderFilterMatches(getFolder(item), entry, mode)),
+  )
+
+  const visibleItems =
+    effectiveSelected.length === 0
+      ? [...items]
+      : items.filter((item) =>
+          folderFilterMatches(getFolder(item), effectiveSelected, mode),
+        )
+
+  return { choices, effectiveSelected, total: items.length, visibleItems }
+}

package/kernel/packages/ui/src/lib/live-tool-call.tsx

@@ -0,0 +1,109 @@
+/**
+ * Pure state machine for a single live ACP tool call.
+ *
+ * Consumes `tool-call-start`/`tool-call-end` events from the
+ * {@link import("../../../../apps/web/server/acp/live-agent-connection.ts") | LiveAgentConnection}
+ * protocol. Every transition returns a new state object.
+ */
+
+export type ToolCallStatus = "pending" | "running" | "completed" | "failed"
+
+export type ToolCallState = Readonly<{
+  callId: string
+  name: string
+  input: unknown
+  output?: string
+  error?: string
+  status: ToolCallStatus
+  requiresPermission: boolean
+}>
+
+/**
+ * Create the initial state from a `tool-call-start` event.
+ *
+ * When `requiresPermission` is true the call starts in `"pending"` so
+ * the caller can present approve/reject controls.
+ */
+export function createToolCall(
+  callId: string,
+  name: string,
+  input: unknown,
+  requiresPermission = false,
+): ToolCallState {
+  return {
+    callId,
+    name,
+    input,
+    status: requiresPermission ? "pending" : "running",
+    requiresPermission,
+  }
+}
+
+/** Move a pending tool call to running. No-op for other statuses. */
+export function approveToolCall(state: ToolCallState): ToolCallState {
+  if (state.status !== "pending") return state
+  return { ...state, status: "running" }
+}
+
+/** Reject a pending tool call. Moves to failed with a rejection error. */
+export function rejectToolCall(
+  state: ToolCallState,
+  reason?: string,
+): ToolCallState {
+  if (state.status !== "pending") return state
+  return {
+    ...state,
+    status: "failed",
+    error: reason ?? "Tool call rejected by user",
+  }
+}
+
+/** Complete a running tool call with its output. No-op for other statuses. */
+export function completeToolCall(
+  state: ToolCallState,
+  output: string,
+): ToolCallState {
+  if (state.status !== "running") return state
+  return { ...state, status: "completed", output }
+}
+
+/** Fail a running tool call with an error message. No-op for other statuses. */
+export function failToolCall(
+  state: ToolCallState,
+  error: string,
+): ToolCallState {
+  if (state.status !== "running") return state
+  return { ...state, status: "failed", error }
+}
+
+/** Derive a `ToolCallState` from a raw `tool-call-end` event. */
+export function applyToolCallEnd(
+  state: ToolCallState,
+  output?: string,
+  error?: string,
+): ToolCallState {
+  if (state.status !== "running") return state
+  if (error) return failToolCall(state, error)
+  return completeToolCall(state, output ?? "")
+}
+
+/** Descriptive label for each status. */
+export function statusLabel(status: ToolCallStatus): string {
+  switch (status) {
+    case "pending":
+      return "Pending approval"
+    case "running":
+      return "Running"
+    case "completed":
+      return "Completed"
+    case "failed":
+      return "Failed"
+  }
+}
+
+/** Tighten `input` to a human-friendly one-line summary. */
+export function summarizeInput(input: unknown): string {
+  if (input === null || input === undefined) return ""
+  if (typeof input === "string") return input
+  return JSON.stringify(input)
+}

package/kernel/packages/ui/src/lib/media-urls.ts

@@ -0,0 +1,176 @@
+/**
+ * Render-time rewrite of local media references inside Markdown documents.
+ *
+ * Notes produced by agents and tools (e.g. BarkDown's `/@fs/` Vite convention)
+ * and notes with plain doc-relative media paths both point at files on disk
+ * that the viewer's static handler must not — and does not — serve. Instead
+ * they are rewritten to the gated `/api/media` endpoint, which only serves
+ * media-typed files contained inside the viewed folder.
+ *
+ * This runs on the render value only, never on `document.content`: the edit
+ * route verifies the client's copy against disk, so rewritten text must not
+ * be persisted anywhere.
+ */
+
+const mediaExtension =
+  /\.(?:aac|avif|bmp|flac|gif|ico|jpeg|jpg|m4a|m4v|mov|mp3|mp4|oga|ogg|ogv|opus|png|svg|wav|webm|webp)$/i
+
+/** Web-ish references that never point at folder files. */
+const nonLocalReference = /^(?:[a-z][a-z0-9+.-]*:|\/\/|[#~])/i
+
+export type MediaUrlResolver = (url: string) => string | undefined
+
+/** Builds the gated media endpoint URL for a folder-relative file. */
+export function mediaHref(root: string, file: string): string {
+  const url = new URL("/api/media", "http://localhost")
+  url.searchParams.set("path", root)
+  url.searchParams.set("file", file)
+  return `${url.pathname}${url.search}`
+}
+
+/** Directory part of a document path, including the trailing separator. */
+function documentDirectory(path: string) {
+  const separator = path.lastIndexOf("/")
+  return separator < 0 ? "" : path.slice(0, separator + 1)
+}
+
+function splitSegments(path: string) {
+  return path.split(/[\\/]+/).filter((segment) => segment && segment !== ".")
+}
+
+/** True when `candidate` resolves inside `root` (or equals it). */
+function insideRoot(root: string, candidate: string[]) {
+  const rootSegments = splitSegments(root)
+  if (candidate.length < rootSegments.length) return false
+  return rootSegments.every(
+    (segment, index) =>
+      segment.toLowerCase() === candidate[index]?.toLowerCase(),
+  )
+}
+
+function joinRelative(root: string, candidate: string[]) {
+  return candidate.slice(splitSegments(root).length).join("/")
+}
+
+/**
+ * Folder-relative form of an absolute path, or undefined when the path
+ * escapes the folder. Case-insensitive prefix match keeps Windows drive
+ * letters from breaking containment.
+ */
+export function containedRelative(
+  root: string,
+  target: string,
+): string | undefined {
+  if (!target) return undefined
+  const segments = splitSegments(target)
+  if (!insideRoot(root, segments)) return undefined
+  const relative = joinRelative(root, segments)
+  return relative || undefined
+}
+
+/**
+ * Folder-relative form of a document-relative reference resolved against the
+ * document's directory, or undefined when it escapes the folder.
+ */
+export function documentRelativeMedia(
+  root: string,
+  documentPath: string,
+  reference: string,
+): string | undefined {
+  // documentPath is folder-relative, so the resolved candidate is rooted at
+  // the folder root: <root>/<doc-dir>/<reference>.
+  const base = `${root.replace(/[\\/]+$/, "")}/${documentDirectory(documentPath)}`
+  const segments = splitSegments(`${base}${reference}`)
+  const resolved: string[] = []
+  for (const segment of segments) {
+    if (segment === "..") {
+      if (!resolved.length) return undefined
+      resolved.pop()
+      continue
+    }
+    resolved.push(segment)
+  }
+  if (!insideRoot(root, resolved)) return undefined
+  return joinRelative(root, resolved) || undefined
+}
+
+function fileFromFsUrl(url: string) {
+  if (!url.startsWith("/@fs/")) return undefined
+  try {
+    return decodeURIComponent(url.slice("/@fs".length))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Resolver bound to one document: rewrites `/@fs/<absolute>` and
+ * doc-relative media references to `/api/media`, leaving everything else
+ * (web URLs, data URIs, anchors, escaping paths) untouched.
+ */
+export function mediaUrlResolver(
+  root: string,
+  documentPath: string,
+): MediaUrlResolver {
+  return (raw) => {
+    const url = raw.trim().replaceAll("\\", "/")
+    if (!url) return undefined
+    const fsPath = fileFromFsUrl(url)
+    if (fsPath !== undefined) {
+      const relative = containedRelative(root, fsPath)
+      if (!relative || !mediaExtension.test(relative)) return undefined
+      return mediaHref(root, relative)
+    }
+    if (nonLocalReference.test(url)) return undefined
+    const bare = url.split(/[?#]/)[0] ?? ""
+    if (!mediaExtension.test(bare)) return undefined
+    const relative = documentRelativeMedia(root, documentPath, url)
+    return relative ? mediaHref(root, relative) : undefined
+  }
+}
+
+/** Rewrites the media URLs on one line, leaving non-media text alone. */
+function rewriteLine(line: string, resolve: MediaUrlResolver) {
+  // HTML attributes on raw <video>/<img>/<audio>/<source> blocks.
+  let rewritten = line.replaceAll(
+    /(\s(?:src|poster)\s*=\s*)("([^"]*)"|'([^']*)')/gi,
+    (match, head: string, _quoted: string, double: string, single: string) => {
+      const target = resolve(double ?? single ?? "")
+      return target ? `${head}"${target}"` : match
+    },
+  )
+  // Markdown inline destinations: images and links with media targets.
+  rewritten = rewritten.replaceAll(
+    /\]\(([^()\s]+)(?:\s+"[^"]*")?\)/g,
+    (match, destination: string) => {
+      const target = resolve(destination)
+      return target ? `](${target})` : match
+    },
+  )
+  return rewritten
+}
+
+/**
+ * Rewrites local media references across a Markdown document, skipping
+ * fenced code blocks so displayed samples stay verbatim.
+ */
+export function rewriteDocumentMedia(
+  value: string,
+  root: string,
+  documentPath: string,
+): string {
+  if (!root || !documentPath) return value
+  const resolve = mediaUrlResolver(root, documentPath)
+  let fenced = false
+  return value
+    .split("\n")
+    .map((line) => {
+      if (/^\s*```/.test(line)) {
+        fenced = !fenced
+        return line
+      }
+      if (fenced) return line
+      return rewriteLine(line, resolve)
+    })
+    .join("\n")
+}

package/kernel/packages/ui/src/lib/obsidian-links.ts

@@ -0,0 +1,120 @@
+const markdownExtension = /\.(?:md|markdown|mdown|mdx)$/i
+const unsafeReference = /^(?:\/|[a-z][a-z0-9+.-]*:)/i
+
+export type ObsidianLink = {
+  heading?: string
+  reference?: string
+}
+
+function documentDirectory(path: string) {
+  const separator = path.lastIndexOf("/")
+  return separator < 0 ? "" : path.slice(0, separator + 1)
+}
+
+function markdownLabel(value: string) {
+  return value.replaceAll(/([\\\[\]])/g, "\\$1")
+}
+
+function normalizedReference(reference: string) {
+  const value = reference.trim().replaceAll("\\", "/")
+  if (!value || unsafeReference.test(value)) return undefined
+  return markdownExtension.test(value) ? value : `${value}.md`
+}
+
+export function headingId(heading: string) {
+  return heading
+    .toLowerCase()
+    .replaceAll(/[^\w\s-]/g, "")
+    .trim()
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-|-$/g, "")
+}
+
+export function parseObsidianLink(value: string): ObsidianLink | undefined {
+  const target = value.split("|", 2)[0] ?? ""
+  const [reference = "", heading] = target.trim().split("#", 2)
+  if (!reference && !heading) return undefined
+  return {
+    ...(heading?.trim() ? { heading: heading.trim() } : {}),
+    ...(reference.trim() ? { reference: reference.trim() } : {}),
+  }
+}
+
+/**
+ * Converts Obsidian wikilinks into regular markdown links with an internal
+ * marker. The renderer resolves the marker against the open document.
+ */
+export function obsidianMarkdown(value: string) {
+  let fenced = false
+  return value
+    .split("\n")
+    .map((line) => {
+      if (/^\s*```/.test(line)) {
+        fenced = !fenced
+        return line
+      }
+      if (fenced) return line
+
+      return line.replaceAll(/(?<![!\\])\[\[([^\]\n]+)\]\]/g, (match, raw) => {
+        const link = parseObsidianLink(raw)
+        if (!link) return match
+        const label = raw.includes("|")
+          ? raw.slice(raw.indexOf("|") + 1).trim()
+          : link.heading
+            ? link.reference
+              ? `${link.reference}#${link.heading}`
+              : link.heading
+            : (link.reference ?? raw)
+        return `[${markdownLabel(label)}](/_obsidian-link/${encodeURIComponent(raw)})`
+      })
+    })
+    .join("\n")
+}
+
+function routePath(
+  reference: string,
+  currentDocument: string,
+  wikiLink: boolean,
+) {
+  const normalized = normalizedReference(reference)
+  if (!normalized) return undefined
+  const rootRelative =
+    wikiLink && !/^\.\.?\//.test(normalized) && normalized.includes("/")
+  const path = rootRelative
+    ? normalized
+    : `${documentDirectory(currentDocument)}${normalized}`
+  const segments: string[] = []
+  for (const segment of path.split("/")) {
+    if (!segment || segment === ".") continue
+    if (segment === "..") {
+      if (!segments.length) return undefined
+      segments.pop()
+    } else {
+      segments.push(segment)
+    }
+  }
+  return segments.join("/")
+}
+
+export function resolveObsidianLink(
+  raw: string,
+  currentDocument: string,
+): ObsidianLink | undefined {
+  const link = parseObsidianLink(raw)
+  if (!link) return undefined
+  if (!link.reference) return link
+  const reference = routePath(link.reference, currentDocument, true)
+  return reference ? { ...link, reference } : undefined
+}
+
+export function resolveMarkdownLink(href: string, currentDocument: string) {
+  const match = /^([^?#]+\.(?:md|markdown|mdown|mdx))(?:#(.*))?$/i.exec(href)
+  if (!match) return undefined
+  const reference = routePath(match[1]!, currentDocument, false)
+  if (!reference) return undefined
+  return {
+    ...(match[2] ? { heading: match[2] } : {}),
+    reference,
+  }
+}