kennel 0.2.0 → 0.2.2

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

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@raggle-ai/schemas",
+  "version": "0.1.0",
+  "description": "Schema-backed collection contracts, indexing, server seams, and UI for Kennel.",
+  "type": "module",
+  "license": "MIT",
+  "prettier": "@raggle-ai/prettier-config",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "packages/schemas"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "SKILL.md",
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.tsx",
+    "./manifest": "./src/manifest.ts",
+    "./node": "./src/node.ts",
+    "./server": "./src/server.ts",
+    "./contract": "./src/data/contract.ts",
+    "./favicon": "./src/data/favicon.ts",
+    "./config-file": "./src/data/config-file.ts",
+    "./workspace": "./src/data/workspace.ts"
+  },
+  "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/ui": "workspace:*",
+    "@tanstack/react-query": "catalog:tanstack",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "lucide-react": "^0.562.0",
+    "picomatch": "^4.0.3",
+    "sharp": "^0.35.5",
+    "yaml": "^2.9.0",
+    "zod": "catalog:"
+  },
+  "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/picomatch": "^4.0.2",
+    "@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/schemas/src/client.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useState } from "react"
+import { useQuery, useQueryClient } from "@tanstack/react-query"
+
+import { folderBarActions } from "@raggle-ai/ui/components/app-options"
+import { AppViewHeader } from "@raggle-ai/ui/components/app-view-header"
+
+import type { CoreCollection } from "./data/contract.ts"
+import type { CollectionSort } from "./data/params.ts"
+// import { collectionSortHref } from "./data/params.ts"
+import { readCollectionSort } from "./data/params.ts"
+import { CollectionView } from "./pages/collection.tsx"
+
+export type CollectionApiEvent =
+  "kennel:metadata-changed" | "kennel:workspace-changed"
+
+export type CollectionMetadataResponse = {
+  collection: CoreCollection
+  folder: string
+}
+
+export type CollectionRoute = {
+  collectionId?: string
+  folder?: string
+}
+
+export type CollectionHostProps = {
+  collectionHref: (folder: string, id: string) => string
+  documentHref: (folder: string, path: string) => string
+  folderHref: (folder: string) => string
+  homeHref: (folder: string) => string
+  href: string
+  openFolder?: (folder: string) => void
+  parseRoute: (href: string) => CollectionRoute
+  request: (
+    href: string,
+    part: "collections",
+    options: { id: string; signal?: AbortSignal; sort?: CollectionSort },
+  ) => Promise<CollectionMetadataResponse>
+  subscribeApiEvent: (
+    event: CollectionApiEvent,
+    handler: () => void,
+  ) => () => void
+}
+
+export function CollectionPage({
+  collectionHref,
+  documentHref,
+  folderHref,
+  homeHref,
+  href,
+  openFolder,
+  parseRoute,
+  request,
+  subscribeApiEvent,
+}: CollectionHostProps) {
+  const { folder, collectionId } = parseRoute(href)
+  const client = useQueryClient()
+  const hrefSort = readCollectionSort(href)
+  const [sort, setSort] = useState(hrefSort)
+  useEffect(() => {
+    setSort(hrefSort)
+  }, [hrefSort])
+  const applySort = (next: CollectionSort) => {
+    setSort(next)
+    // URL writes are disabled until saved views use them.
+    // if (typeof window !== "undefined")
+    //   window.history.replaceState(
+    //     null,
+    //     "",
+    //     collectionSortHref(window.location.href, next),
+    //   )
+  }
+  useEffect(() => {
+    const refresh = () =>
+      void client.invalidateQueries({ queryKey: ["collection", folder] })
+    const unsubscribeMetadata = subscribeApiEvent(
+      "kennel:metadata-changed",
+      refresh,
+    )
+    const unsubscribeWorkspace = subscribeApiEvent(
+      "kennel:workspace-changed",
+      refresh,
+    )
+    return () => {
+      unsubscribeMetadata()
+      unsubscribeWorkspace()
+    }
+  }, [client, folder, subscribeApiEvent])
+
+  const query = useQuery<CollectionMetadataResponse>({
+    queryKey: ["collection", folder, collectionId, sort],
+    enabled: Boolean(folder && collectionId),
+    // Keep the controls and their filter state mounted during an order change.
+    // Never show records from a different folder or collection.
+    placeholderData: (previous, previousQuery) =>
+      previousQuery &&
+      previousQuery.queryKey[1] === folder &&
+      previousQuery.queryKey[2] === collectionId
+        ? previous
+        : undefined,
+    queryFn: ({ signal }) =>
+      request(href, "collections", { id: collectionId!, signal, sort }),
+  })
+
+  if (query.error)
+    return <p role="alert">Could not load collection: {query.error.message}</p>
+  if (!query.data) return <p role="status">Loading collection…</p>
+
+  return (
+    <>
+      <AppViewHeader
+        actions={folderBarActions({
+          folderPath: query.data.folder,
+          onOpenFolder: openFolder
+            ? () => openFolder(query.data.folder)
+            : undefined,
+        })}
+        className="collection-page-header"
+        collectionHref={(id) => collectionHref(query.data.folder, id)}
+        folder={query.data.folder}
+        folderHref={folderHref}
+        homeHref={homeHref(query.data.folder)}
+      />
+      <CollectionView
+        href={href}
+        key={`${folder}:${collectionId}`}
+        folder={query.data.folder}
+        collection={query.data.collection}
+        documentHref={(path) => documentHref(query.data.folder, path)}
+        folderHref={folderHref}
+        onSort={applySort}
+        refreshing={query.isFetching}
+        sort={sort}
+      />
+    </>
+  )
+}

package/kernel/packages/schemas/src/data/config-file.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+// Configuration lookup is shared by every Kennel renderer.
+
+export const indexConfigFilenames = ["raggle.json", "docs.config.json"]
+
+export function resolveIndexConfigPath(
+  root = process.cwd(),
+  filenames = indexConfigFilenames,
+) {
+  for (const filename of filenames) {
+    const candidate = join(root, filename)
+
+    if (existsSync(candidate)) return candidate
+  }
+
+  return undefined
+}
+
+export function readIndexDocsConfig(
+  root = process.cwd(),
+  options: { filenames?: string[] } = {},
+) {
+  const configPath = resolveIndexConfigPath(
+    root,
+    options.filenames ?? indexConfigFilenames,
+  )
+
+  if (!configPath) {
+    throw new Error(
+      `No index config found in ${root}. Expected one of: ${indexConfigFilenames.join(", ")}`,
+    )
+  }
+
+  return JSON.parse(readFileSync(configPath, "utf8"))
+}

package/kernel/packages/schemas/src/data/contract.ts

@@ -0,0 +1,174 @@
+import { z } from "zod"
+
+export type IndexIssue = { path: string; message: string }
+
+export type KennelDocumentConfig = Record<string, unknown> & {
+  glob?: unknown
+  parser?: unknown
+  path?: unknown
+}
+
+export type KennelCollectionSort = {
+  field: string
+  direction: "asc" | "desc"
+}
+
+export type KennelCollectionUi = {
+  primaryField: string
+  secondaryField?: string
+  filters: string[] | "all"
+  numericFilters?: string[]
+  sort?: KennelCollectionSort[]
+  navLabel?: string
+}
+
+export type KennelSchemaConfig = {
+  title?: string
+  icon?: string
+  documents: KennelDocumentConfig[]
+  ui: KennelCollectionUi
+}
+
+export type CoreRecordIcon = {
+  readonly source: "local" | "favicon"
+  readonly host?: string
+  readonly path?: string
+}
+
+/** Inline icon asset attached to a collection response. `data` is base64. */
+export type KennelIconAsset = {
+  readonly data?: string
+  readonly mediaType: string
+  readonly source?: "local" | "favicon"
+  readonly url?: string
+}
+
+export type CoreRecord = {
+  id: string
+  path: string
+  relativePath: string
+  title: string
+  modifiedAt: number
+  fields: Record<string, unknown>
+  validationErrors: IndexIssue[]
+  /** Icon detected from frontmatter; resolved to an asset per request. */
+  icon?: CoreRecordIcon
+  iconAssetKey?: string
+}
+
+export type CoreCollection = {
+  id: string
+  folder: string
+  schemaPath: string
+  title: string
+  navLabel?: string
+  icon?: string
+  count: number
+  diagnostics: IndexIssue[]
+  revision: string
+  indexedAt: string
+  state: "ready" | "error"
+  ui: {
+    primaryField: string
+    secondaryField?: string
+    filters: string[]
+    numericFilters: string[]
+    sort?: KennelCollectionSort[]
+  }
+  /** Per-request record icon assets; records reference them by `iconAssetKey`. */
+  assets?: Record<string, KennelIconAsset>
+  records: CoreRecord[]
+}
+
+export type CoreCollectionSummary = Omit<CoreCollection, "records">
+export type CoreCollectionSummaryPayload = Omit<CoreCollectionSummary, "ui">
+
+export type CoreFolderIndex = {
+  list(
+    input: string,
+    options?: { boundary?: string },
+  ): Promise<{
+    folder: string
+    root: string
+    revision: string
+    state: "ready" | "error"
+    collections: CoreCollection[]
+    dependencies: string[]
+  }>
+  invalidate(changed: string): string[]
+  stats: { collectionsBuilt: number; recordsRead: number }
+}
+
+export const issueSchema = z.object({ path: z.string(), message: z.string() })
+
+export const coreRecordIconSchema = z.object({
+  source: z.enum(["local", "favicon"]),
+  host: z.string().optional(),
+  path: z.string().optional(),
+})
+
+export const kennelIconAssetSchema = z.object({
+  data: z.string().optional(),
+  mediaType: z.string(),
+  source: z.enum(["local", "favicon"]).optional(),
+  url: z.string().optional(),
+})
+
+export const coreCollectionSortSchema = z.object({
+  field: z.string(),
+  direction: z.enum(["asc", "desc"]),
+})
+
+export const coreCollectionUiSchema = z.object({
+  primaryField: z.string(),
+  secondaryField: z.string().optional(),
+  filters: z.array(z.string()),
+  numericFilters: z.array(z.string()),
+  sort: z.array(coreCollectionSortSchema).optional(),
+})
+
+export const collectionSummarySchema = z.object({
+  id: z.string().optional(),
+  count: z.number().optional(),
+  navLabel: z.string().optional(),
+  icon: z.string().optional(),
+  revision: z.string().optional(),
+  indexedAt: z.string().optional(),
+  state: z.enum(["ready", "error"]).optional(),
+  diagnostics: z.array(issueSchema).optional(),
+  folder: z.string(),
+  schemaPath: z.string(),
+  title: z.string(),
+})
+
+export const coreRecordSchema = z.object({
+  icon: coreRecordIconSchema.optional(),
+  iconAssetKey: z.string().optional(),
+  id: z.string(),
+  path: z.string(),
+  relativePath: z.string(),
+  title: z.string(),
+  modifiedAt: z.number(),
+  fields: z.record(z.string(), z.unknown()),
+  validationErrors: z.array(issueSchema),
+})
+
+export const coreCollectionSchema = collectionSummarySchema.extend({
+  id: z.string(),
+  count: z.number(),
+  diagnostics: z.array(issueSchema),
+  revision: z.string(),
+  indexedAt: z.string(),
+  state: z.enum(["ready", "error"]),
+  ui: coreCollectionUiSchema,
+  assets: z.record(z.string(), kennelIconAssetSchema).optional(),
+  records: z.array(coreRecordSchema),
+})
+
+/** Omit record bodies from navigation payloads. */
+export function collectionSummary({
+  records: _records,
+  ...summary
+}: CoreCollection): CoreCollectionSummary {
+  return summary
+}

package/kernel/packages/schemas/src/data/favicon.ts

@@ -0,0 +1,218 @@
+import { createHash, randomUUID } from "node:crypto"
+import { lookup } from "node:dns/promises"
+import { mkdir, rename, stat, unlink, writeFile } from "node:fs/promises"
+import { BlockList, isIP } from "node:net"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+import { maxIconBytes, normalizeIcon, readIconFile } from "./icon-image.ts"
+
+export function websiteHost(value: unknown) {
+  if (typeof value !== "string") return undefined
+  const url = URL.parse(value)
+  if (!url || !["http:", "https:"].includes(url.protocol)) return undefined
+  if (url.username || url.password || url.port) return undefined
+  const host = url.hostname.toLowerCase().replace(/\.$/, "")
+  if (isIP(host) || !/^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/.test(host))
+    return undefined
+  if (
+    /\.(local|localhost|internal|test|invalid|example|home|lan|onion)$/.test(
+      host,
+    )
+  )
+    return undefined
+  return host
+}
+
+export function websiteHostFromText(value: unknown) {
+  if (typeof value !== "string") return undefined
+  const trimmed = value.trim()
+  if (/\s/.test(trimmed)) return undefined
+  if (/^https?:\/\//i.test(trimmed)) return websiteHost(trimmed)
+  if (!/^(?:[a-z0-9-]+\.)+[a-z0-9-]+\/?$/i.test(trimmed)) return undefined
+  return websiteHost(`https://${trimmed}`)
+}
+
+const globalV6 = new BlockList()
+globalV6.addSubnet("2000::", 3, "ipv6")
+const reservedV6 = new BlockList()
+reservedV6.addSubnet("2001::", 23, "ipv6")
+reservedV6.addSubnet("2001:db8::", 32, "ipv6")
+reservedV6.addSubnet("2002::", 16, "ipv6")
+reservedV6.addSubnet("3fff::", 20, "ipv6")
+
+function publicAddress(address: string) {
+  if (isIP(address) === 6)
+    return globalV6.check(address, "ipv6") && !reservedV6.check(address, "ipv6")
+  if (isIP(address) !== 4) return false
+  const [a = 0, b = 0, c = 0] = address.split(".").map(Number)
+  return !(
+    a === 0 ||
+    a === 10 ||
+    a === 127 ||
+    a >= 224 ||
+    (a === 100 && b >= 64 && b <= 127) ||
+    (a === 169 && b === 254) ||
+    (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && (b === 0 || b === 168 || (b === 88 && c === 99))) ||
+    (a === 198 && (b === 18 || b === 19 || (b === 51 && c === 100))) ||
+    (a === 203 && b === 0 && c === 113)
+  )
+}
+
+const missTtl = 300_000
+
+function cacheRoot() {
+  return (
+    process.env.KENNEL_FAVICON_CACHE_DIR ??
+    join(
+      process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"),
+      "kennel",
+      "favicons",
+    )
+  )
+}
+
+function cachePaths(host: string) {
+  const key = createHash("sha256").update(host).digest("hex")
+  const root = cacheRoot()
+  return {
+    file: join(root, `${key}.png`),
+    miss: join(root, `${key}.miss`),
+    root,
+  }
+}
+
+function fresh(mtimeMs: number, ttl: number, now: number) {
+  return now - mtimeMs < ttl
+}
+
+async function readDiskCache(host: string, now: number) {
+  const { file, miss } = cachePaths(host)
+  // Retain valid cached icons offline, even after their refresh date.
+  const bytes = await readIconFile(file).catch(() => undefined)
+  const data = bytes ? await normalizeIcon(bytes) : undefined
+  if (data) return { data, hit: true }
+  const details = await stat(miss).catch(() => undefined)
+  if (details && fresh(details.mtimeMs, missTtl, now))
+    return { data: undefined, hit: true }
+  return undefined
+}
+
+async function writeDiskCache(host: string, data: Buffer | undefined) {
+  const { file, miss, root } = cachePaths(host)
+  await mkdir(root, { recursive: true, mode: 0o700 })
+  const target = data ? file : miss
+  const temporary = join(root, `.${randomUUID()}.tmp`)
+  try {
+    await writeFile(temporary, data ?? "", { flag: "wx", mode: 0o600 })
+    await rename(temporary, target)
+    if (data) await unlink(miss).catch(() => undefined)
+  } finally {
+    await unlink(temporary).catch(() => undefined)
+  }
+}
+
+/** Exact host approval; no wildcards or automatic subdomain approval. */
+function approvedHost(host: string) {
+  if (process.env.KENNEL_EXTERNAL_ICONS !== "1") return false
+  return (process.env.KENNEL_FAVICON_ALLOWED_HOSTS ?? "")
+    .split(",")
+    .some((entry) => entry.trim().toLowerCase() === host)
+}
+
+// Provider fetches never target the supplied host. DNS is used only to reject
+// private destinations before disclosing their names to the provider.
+export function faviconService({
+  fetcher = fetch,
+  resolve = (host: string) => lookup(host, { all: true }),
+  now = Date.now,
+}: {
+  fetcher?: typeof fetch
+  resolve?: (host: string) => Promise<{ address: string }[]>
+  now?: () => number
+} = {}) {
+  const cache = new Map<string, { expires: number; data?: Buffer }>()
+  const pending = new Map<string, Promise<Buffer | undefined>>()
+  const limit = maxIconBytes
+  return async (host: string): Promise<Buffer | undefined> => {
+    if (websiteHost(`https://${host}`) !== host) return undefined
+    const currentTime = now()
+    const cached = cache.get(host)
+    if (cached && cached.expires > currentTime) return cached.data
+    const disk = await readDiskCache(host, currentTime)
+    if (disk?.hit) {
+      cache.set(host, {
+        data: disk.data,
+        expires: currentTime + (disk.data ? 86_400_000 : 300_000),
+      })
+      return disk.data
+    }
+    // Do not perform DNS or disclose a domain until it has explicit approval.
+    if (!approvedHost(host)) return undefined
+    if (pending.has(host)) return pending.get(host)
+    if (pending.size >= 8) return undefined
+    const task = (async () => {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      const addresses = await Promise.race([
+        resolve(host),
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => reject(new Error("DNS timeout")), 2000)
+        }),
+      ]).finally(() => clearTimeout(timer))
+      if (
+        !addresses.length ||
+        !addresses.every(({ address }) => publicAddress(address))
+      )
+        return undefined
+      // The /s2 endpoint redirects; use Google's fixed image origin directly
+      // so provider redirects can remain disabled.
+      const url = new URL("https://t3.gstatic.com/faviconV2")
+      url.searchParams.set("client", "SOCIAL")
+      url.searchParams.set("type", "FAVICON")
+      url.searchParams.set("fallback_opts", "TYPE,SIZE,URL")
+      url.searchParams.set("url", `https://${host}`)
+      url.searchParams.set("size", "64")
+      const response = await fetcher(url, {
+        redirect: "error",
+        signal: AbortSignal.timeout(3000),
+      })
+      if (
+        !response.ok ||
+        response.headers.get("content-type")?.split(";")[0] !== "image/png"
+      ) {
+        await response.body?.cancel()
+        return undefined
+      }
+      if (!response.body) return undefined
+      const reader = response.body.getReader()
+      const chunks: Uint8Array[] = []
+      let size = 0
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.byteLength
+        if (size > limit) {
+          await reader.cancel()
+          return undefined
+        }
+        chunks.push(value)
+      }
+      const data = Buffer.concat(chunks)
+      return normalizeIcon(data)
+    })()
+      .catch(() => undefined)
+      .then(async (data) => {
+        if (cache.size >= 128) cache.delete(cache.keys().next().value!)
+        cache.set(host, {
+          data,
+          expires: now() + (data ? 86_400_000 : 300_000),
+        })
+        await writeDiskCache(host, data).catch(() => undefined)
+        return data
+      })
+      .finally(() => pending.delete(host))
+    pending.set(host, task)
+    return task
+  }
+}