kennel 0.2.1 → 0.2.2

package/kernel/apps/web/src/use-folder-notes.ts

@@ -0,0 +1,49 @@
+import { useMemo, useRef } from "react"
+import { useQuery } from "@tanstack/react-query"
+
+import { fetchMetadataPart } from "./folder-metadata"
+import { folderPathId, parseViewerRoute } from "./viewer-route"
+
+// 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", {
+        signal,
+        notesScope,
+        headers: retry ? { "x-kennel-retry-linked": "1" } : undefined,
+      })
+    },
+    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/apps/web/src/use-linked-session.ts

@@ -0,0 +1,33 @@
+import { useQuery } from "@tanstack/react-query"
+
+import type { SessionTranscript } from "@raggle-ai/ui/chat"
+
+const sessionClients = ["claude", "codex", "cursor", "opencode", "pi"] as const
+
+/**
+ * Resolve a linked chat session id (`client:nativeId`) for the viewer. The
+ * provider client comes from the id prefix synchronously; the transcript
+ * metadata arrives from `/api/session` and shares the ["session", id] cache
+ * entry with the transcript page.
+ */
+export function useLinkedSession(session?: string) {
+  const linked = useQuery<SessionTranscript>({
+    enabled: Boolean(session),
+    queryFn: async () => {
+      const response = await fetch(
+        `/api/session?sessionId=${encodeURIComponent(session ?? "")}`,
+      )
+      if (!response.ok) throw new Error("Session not found")
+      return (await response.json()) as SessionTranscript
+    },
+    queryKey: ["session", session],
+    staleTime: 30_000,
+  })
+  const prefix = session?.slice(0, session.indexOf(":"))
+  const client = sessionClients.find((item) => item === prefix)
+  return {
+    client,
+    title: linked.data?.title ?? session,
+    transcript: linked.data,
+  }
+}

package/kernel/apps/web/src/view-context.tsx

@@ -0,0 +1,69 @@
+import type { ReactNode } from "react"
+import { createContext, useContext, useEffect, useMemo } from "react"
+import { useQuery, useQueryClient } from "@tanstack/react-query"
+
+import type { FolderMetadata } from "@raggle-ai/ui/lib/folder-activity"
+
+import { subscribeApiEvent } from "./api/events"
+import { fetchMetadataPart } from "./folder-metadata"
+import { folderSectionHref } from "./viewer-route"
+
+export type ViewContext = {
+  kind: "folder" | "document"
+  folder?: string
+  document?: { path: string; title: string }
+  workspace?: FolderMetadata["workspace"]
+  workspaceError?: string
+}
+
+const Context = createContext<ViewContext | undefined>(undefined)
+
+export function useWorkspace(folder?: string) {
+  const client = useQueryClient()
+  useEffect(() => {
+    const refresh = () => {
+      void client.invalidateQueries({ queryKey: ["folder-workspace", folder] })
+    }
+    return subscribeApiEvent("kennel:workspace-changed", refresh)
+  }, [client, folder])
+  return useQuery({
+    enabled: Boolean(folder?.startsWith("/")),
+    queryKey: ["folder-workspace", folder],
+    queryFn: () =>
+      fetchMetadataPart(
+        new URL(folderSectionHref(folder!, "notes"), window.location.origin)
+          .href,
+        "workspace",
+      ),
+    staleTime: 30_000,
+    gcTime: 30 * 60_000,
+  })
+}
+
+export function ViewProvider({
+  kind,
+  folder,
+  document,
+  children,
+}: Omit<ViewContext, "workspace" | "workspaceError"> & {
+  children: ReactNode
+}) {
+  const query = useWorkspace(folder)
+  const value = useMemo(
+    () => ({
+      kind,
+      folder,
+      document,
+      workspace: query.data?.workspace,
+      workspaceError: query.error?.message,
+    }),
+    [kind, folder, document, query.data, query.error],
+  )
+  return <Context.Provider value={value}>{children}</Context.Provider>
+}
+
+export function useView() {
+  const value = useContext(Context)
+  if (!value) throw new Error("ViewProvider is required")
+  return value
+}

package/kernel/apps/web/src/view-header.tsx

@@ -0,0 +1,66 @@
+import type { ComponentProps } from "react"
+import { FileText } from "lucide-react"
+
+import { AppViewHeader } from "@raggle-ai/ui/components/app-view-header"
+
+import { useView } from "./view-context"
+import {
+  folderCollectionHref,
+  folderDocumentHref,
+  folderSectionHref,
+} from "./viewer-route"
+
+export function ViewHeader(
+  props: Pick<
+    ComponentProps<typeof AppViewHeader>,
+    "actions" | "accessory" | "options"
+  >,
+) {
+  const view = useView()
+  const collectionId = new URLSearchParams(window.location.search).get(
+    "collection",
+  )
+  return (
+    <AppViewHeader
+      folder={view.folder}
+      name={view.document?.title}
+      icon={
+        view.kind === "document" ? <FileText aria-hidden="true" /> : undefined
+      }
+      workspace={view.workspace}
+      folderHref={(folder) => folderSectionHref(folder, "notes")}
+      collectionHref={
+        view.folder ? (id) => folderCollectionHref(view.folder!, id) : undefined
+      }
+      homeHref={
+        view.folder ? folderSectionHref(view.folder, "notes") : undefined
+      }
+      page={
+        view.folder && view.document
+          ? {
+              title: view.document.title,
+              href: folderDocumentHref(view.folder, view.document.path),
+            }
+          : undefined
+      }
+      {...props}
+      accessory={
+        <>
+          {view.folder && collectionId ? (
+            <a
+              className="text-sm underline"
+              href={folderCollectionHref(view.folder, collectionId)}
+            >
+              Back to collection
+            </a>
+          ) : null}
+          {props.accessory}
+        </>
+      }
+    >
+      {view.workspaceError ? (
+        <small role="status">Folder path unavailable.</small>
+      ) : null}
+    </AppViewHeader>
+  )
+}

package/kernel/apps/web/src/viewer-capabilities.ts

@@ -0,0 +1,33 @@
+import type { ViewerCapabilities } from "~/api-client"
+import { useQuery } from "@tanstack/react-query"
+import { api } from "~/api-client"
+
+export type { ViewerCapabilities } from "~/api-client"
+
+/**
+ * Server capability surface for the current viewer. The client renders
+ * server-backed actions (open in default app, ACP live sessions, download)
+ * from these capabilities instead of guessing from the folder path, so a
+ * remote phone can never attempt to open an app on the server.
+ */
+
+const empty: ViewerCapabilities = {
+  acp: false,
+  download: false,
+  hostActions: "none",
+  local: false,
+  viewer: "unknown",
+}
+
+export async function fetchViewerCapabilities(): Promise<ViewerCapabilities> {
+  return api.capabilities().catch(() => empty)
+}
+
+export function useViewerCapabilities() {
+  return useQuery({
+    gcTime: 5 * 60_000,
+    queryKey: ["viewer-capabilities"],
+    queryFn: fetchViewerCapabilities,
+    staleTime: 60_000,
+  })
+}

package/kernel/apps/web/src/viewer-route.ts

@@ -0,0 +1 @@
+export * from "@raggle-ai/kennel-api/shared/viewer-route"

package/kernel/apps/web/src/viewport-height.ts

@@ -0,0 +1,33 @@
+/**
+ * Keyboard-aware viewport height.
+ *
+ * Mobile browsers shrink the visual viewport when the on-screen keyboard
+ * opens, but `100dvh` does not follow it. Mirror `visualViewport.height`
+ * into `--kennel-vh` so panel and tray surfaces can size themselves to the
+ * area the user can actually see. Falls back to `100dvh` when the visual
+ * viewport API is unavailable (and to nothing when unchanged).
+ */
+export function installViewportHeight(): () => void {
+  const viewport = window.visualViewport
+  if (!viewport) return () => {}
+  const update = () => {
+    document.documentElement.style.setProperty(
+      "--kennel-vh",
+      `${Math.round(viewport.height)}px`,
+    )
+  }
+  viewport.addEventListener("resize", update)
+  viewport.addEventListener("scroll", update)
+  update()
+  return () => {
+    viewport.removeEventListener("resize", update)
+    viewport.removeEventListener("scroll", update)
+  }
+}
+
+/** Current keyboard-safe height for `height: var(--kennel-vh, 100dvh)`. */
+export function viewportHeight(): string {
+  return window.visualViewport
+    ? `${Math.round(window.visualViewport.height)}px`
+    : "100dvh"
+}

package/kernel/apps/web/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@raggle-ai/tsconfig/base.json",
+  "include": [
+    "server/**/*.ts",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "test/**/*.test.ts",
+    "vite.config.ts",
+    "../../plugins/mail/src/bun-ffi.d.ts"
+  ],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "paths": {
+      "@/*": ["./src/*"],
+      "~/*": ["../../packages/*/src"]
+    },
+    "types": ["vite/client", "node", "bun"],
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  }
+}

package/kernel/apps/web/vite.config.ts

@@ -0,0 +1,252 @@
+import { existsSync, realpathSync } from "node:fs"
+import { createRequire } from "node:module"
+import { dirname, resolve } from "node:path"
+import type { AliasOptions } from "vite"
+import tailwindcss from "@tailwindcss/vite"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+import { barkdownPlugin } from "@raggle-ai/barkdown/vite"
+
+import { corePlugin } from "./server/core-plugin"
+
+const root = resolve(import.meta.dirname)
+const workspace = resolve(
+  process.env.KENNEL_KERNEL_SOURCE_ROOT || resolve(root, "../.."),
+)
+const require = createRequire(import.meta.url)
+const packageDir = (name: string): string | undefined => {
+  try {
+    const packageName = name.startsWith("@")
+      ? name.split("/").slice(0, 2).join("/")
+      : name.split("/")[0]
+    return dirname(require.resolve(`${packageName}/package.json`))
+  } catch {
+    return undefined
+  }
+}
+const packageEntry = (name: string): string | undefined => {
+  try {
+    return require.resolve(name)
+  } catch {
+    return undefined
+  }
+}
+// The CLI propagates an explicit remote binding (--lan) through this flag:
+// remote servers restrict document/metadata reads to the real viewer root
+// (no multi-folder overrides), disable host actions (open in default app)
+// and disable ACP live sessions. Local loopback keeps the intentional
+// multi-folder hot-viewer workflows (linked notes, server reuse).
+const remoteAccess = process.env.KENNEL_VIEWER_REMOTE === "1"
+// BarkDown is declared only by packages/markdown, so its physical install
+// lives either hoisted at the workspace root or nested under the markdown
+// re-export package (Bun has used both layouts). Resolve it defensively so a
+// layout change or a missing copy degrades to normal node_modules resolution
+// instead of crashing config load — and so a stale hoisted copy can never
+// mask the version @raggle-ai/markdown actually depends on.
+const resolveBarkdown = (): string | undefined => {
+  for (const candidate of [
+    resolve(workspace, "node_modules/@raggle-ai/barkdown"),
+    resolve(
+      workspace,
+      "node_modules/@raggle-ai/markdown/node_modules/@raggle-ai/barkdown",
+    ),
+  ]) {
+    if (existsSync(candidate)) return realpathSync(candidate)
+  }
+  return undefined
+}
+const barkdown = resolveBarkdown()
+const internalPackages: Array<[RegExp, string]> = [
+  [/^@raggle-ai\/agents(\/.*)?$/, "packages/agents/src"],
+  [/^@raggle-ai\/calendar(\/.*)?$/, "plugins/calendar/src"],
+  [/^@raggle-ai\/folder-plugin(\/.*)?$/, "packages/folder-plugin/src"],
+  [/^@raggle-ai\/kennel-api(\/.*)?$/, "packages/api/src"],
+  [/^@raggle-ai\/mail(\/.*)?$/, "plugins/mail/src"],
+  [/^@raggle-ai\/markdown(\/.*)?$/, "packages/markdown/src"],
+  [/^@raggle-ai\/notes(\/.*)?$/, "packages/notes/src"],
+  [/^@raggle-ai\/projects(\/.*)?$/, "plugins/projects/src"],
+  [/^@raggle-ai\/schemas(\/.*)?$/, "packages/schemas/src"],
+  [/^@raggle-ai\/session-finding(\/.*)?$/, "packages/session-finding/src"],
+  [/^@raggle-ai\/tasks(\/.*)?$/, "plugins/tasks/src"],
+  [/^@raggle-ai\/ui(\/.*)?$/, "packages/ui/src"],
+  [/^kennel-client(\/.*)?$/, "packages/api-client/src"],
+]
+const hostPackageNames = [
+  "@tanstack/react-query",
+  "@tanstack/react-router",
+  "lucide-react",
+  "react",
+  "react-dom",
+  "react/jsx-runtime",
+  "yaml",
+]
+const hostPackageAliases = hostPackageNames.flatMap((name) => {
+  const replacement = packageEntry(name)
+  return replacement
+    ? [
+        {
+          find: new RegExp(`^${name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`),
+          replacement,
+        },
+      ]
+    : []
+})
+const hostPackageRoots = hostPackageNames
+  .map(packageDir)
+  .filter((path): path is string => Boolean(path))
+const aliases: AliasOptions = [
+  ...(process.env.KENNEL_EXTERNAL_CLIENT_MODULE
+    ? [
+        {
+          find: /^@\/external-plugins$/,
+          replacement: process.env.KENNEL_EXTERNAL_CLIENT_MODULE,
+        },
+      ]
+    : []),
+  ...(process.env.KENNEL_KERNEL_SOURCE_ROOT
+    ? [
+        {
+          find: /^@raggle-ai\/markdown\/styles\.css$/,
+          replacement: resolve(workspace, "packages/markdown/styles.css"),
+        },
+        {
+          find: /^@raggle-ai\/markdown\/explorer\.css$/,
+          replacement: resolve(workspace, "packages/markdown/explorer.css"),
+        },
+        {
+          find: /^@raggle-ai\/tasks\/todo-model\/styles\.css$/,
+          replacement: resolve(workspace, "plugins/tasks/src/styles.css"),
+        },
+        {
+          find: /^@raggle-ai\/ui\/folder-activity\.css$/,
+          replacement: resolve(
+            workspace,
+            "packages/ui/src/styles/folder-activity.css",
+          ),
+        },
+        ...internalPackages.map(([find, target]) => ({
+          find,
+          replacement: `${resolve(workspace, target)}$1`,
+        })),
+      ]
+    : []),
+  ...hostPackageAliases,
+  { find: "@", replacement: resolve(import.meta.dirname, "src") },
+  {
+    find: /^~\/([^/]+)$/,
+    replacement: `${workspace}/packages/$1/src/index.ts`,
+  },
+  ...(barkdown && existsSync(resolve(barkdown, "src"))
+    ? [
+        {
+          find: /^@raggle-ai\/barkdown$/,
+          replacement: resolve(barkdown, "src", "index.ts"),
+        },
+        {
+          find: /^@raggle-ai\/barkdown\/documents$/,
+          replacement: resolve(barkdown, "src", "documents.ts"),
+        },
+        {
+          find: /^@raggle-ai\/barkdown\/explorer$/,
+          replacement: resolve(barkdown, "src", "explorer.tsx"),
+        },
+      ]
+    : []),
+]
+
+export default defineConfig({
+  esbuild: process.env.KENNEL_EXTERNAL_CLIENT_MODULE
+    ? {
+        tsconfigRaw: {
+          compilerOptions: {
+            jsx: "react-jsx",
+            target: "ES2022",
+            useDefineForClassFields: true,
+          },
+        },
+      }
+    : undefined,
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          if (!id.includes("node_modules")) return undefined
+          if (id.includes("/react/") || id.includes("/react-dom/"))
+            return "react"
+          if (id.includes("/@tanstack/")) return "tanstack"
+          if (
+            id.includes("/react-markdown/") ||
+            id.includes("/remark-") ||
+            id.includes("/rehype-") ||
+            id.includes("/highlight.js/") ||
+            id.includes("/katex/") ||
+            id.includes("/unified/") ||
+            id.includes("/micromark") ||
+            id.includes("/mdast-") ||
+            id.includes("/hast-") ||
+            id.includes("/vfile")
+          )
+            return "markdown"
+          return undefined
+        },
+      },
+    },
+  },
+  plugins: [
+    corePlugin({
+      remoteAccess,
+      restrictToRoot: remoteAccess,
+      root: process.env.KENNEL_VIEWER_ROOT || root,
+      // `kennel pop <file>` (hot) locks document reads to exactly this file;
+      // the static viewer applies the same lock in-process.
+      lockedFile: process.env.KENNEL_VIEWER_TARGET || undefined,
+    }),
+    // Only non-API BarkDown assets remain here; core owns /api/*.
+    barkdownPlugin(root),
+    tailwindcss(),
+    react(),
+  ],
+  resolve: {
+    alias: aliases,
+    dedupe: ["react", "react-dom"],
+  },
+  server: {
+    // Preserve Host/Origin for the core's DNS-rebinding and mutation guards.
+    proxy: process.env.KENNEL_CORE_URL
+      ? { "/api": { target: process.env.KENNEL_CORE_URL, changeOrigin: false } }
+      : undefined,
+    // Host allowlist instead of `true`: loopback plus any hosts the CLI
+    // passed (LAN IP / Tailscale DNS name). This is the DNS-rebinding guard
+    // for Vite's own page/HMR responses; the API guard lives in the plugins.
+    allowedHosts: [
+      "localhost",
+      "127.0.0.1",
+      "0.0.0.0",
+      ...(process.env.KENNEL_VIEWER_HOSTS ?? "")
+        .split(",")
+        .map((host) => host.trim())
+        .filter(Boolean),
+    ],
+    fs: {
+      allow: barkdown
+        ? [workspace, barkdown, ...hostPackageRoots]
+        : [workspace, ...hostPackageRoots],
+    },
+    // Warm the biggest cold-transform graphs (measured ~1–5 s each on first
+    // request, stacking into the long first load / first HMR after a server
+    // restart) so the dev server pays the cost at startup, not in the browser.
+    warmup: {
+      clientFiles: [
+        "./src/main.tsx",
+        "./src/App.tsx",
+        "./src/markdown-page.tsx",
+        "../../packages/agents/src/viewer.tsx",
+        "../../packages/agents/src/node.ts",
+      ],
+    },
+    host: "127.0.0.1",
+    port: 5180,
+    strictPort: true,
+  },
+})

package/kernel/packages/agents/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/agents/package.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@raggle-ai/agents",
+  "version": "0.1.0",
+  "description": "Agents folder plugin: read-only instruction source discovery and viewer 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": "packages/agents"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.tsx",
+    "./manifest": "./src/manifest.ts",
+    "./node": "./src/node.ts",
+    "./profiles": "./src/profiles.ts",
+    "./resolve": "./src/resolve.ts",
+    "./server": "./src/server.ts",
+    "./types": "./src/types.ts",
+    "./viewer": "./src/viewer.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/markdown": "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"
+  }
+}