kennel 0.2.0 → 0.2.2

package/kernel/packages/schemas/src/server.ts

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto"
+import { basename, relative } from "node:path"
+import type { ServerResponse } from "node:http"
+
+import type {
+  CoreCollection,
+  CoreRecord,
+  KennelIconAsset,
+} from "./data/contract.ts"
+import type { CollectionSort } from "./data/params.ts"
+import { collectionSummary } from "./data/contract.ts"
+import { faviconService } from "./data/favicon.ts"
+import { localRecordIcon } from "./data/icon.ts"
+import { compareTail, recordOrder } from "./data/sort.ts"
+import { folderWorkspace } from "./data/workspace.ts"
+import { createCoreFolderIndex } from "./node.ts"
+
+export type SchemaCollectionServerHost = {
+  emit(event: {
+    data: { path: string }
+    event: "kennel:metadata-changed" | "kennel:workspace-changed"
+    type: "custom"
+  }): void
+  watch(paths: string | string[]): void
+}
+
+export type SchemaCollectionServerOptions = {
+  boundary?: string
+  lockedTarget?: string
+}
+
+/** The payload carries the requested order: declared ui.sort, else alpha or
+ * recency. The index itself stays in stable id order. */
+const orderCollection = (collection: CoreCollection, sort?: CollectionSort) => {
+  const order = Array.isArray(collection.ui.sort)
+    ? recordOrder(collection.ui.sort)
+    : sort === "alpha"
+      ? compareTail
+      : recordOrder(undefined)
+  return { ...collection, records: [...collection.records].sort(order) }
+}
+
+export function createSchemaCollectionServer(
+  host: SchemaCollectionServerHost,
+  options: SchemaCollectionServerOptions = {},
+) {
+  const collectionIndex = createCoreFolderIndex()
+  const collectionScopes = new Set<string>()
+  let collectionRefresh: ReturnType<typeof setTimeout> | undefined
+
+  const list = async (folder: string) => {
+    const result = await collectionIndex.list(folder, {
+      boundary: options.boundary,
+    })
+    collectionScopes.add(folder)
+    host.watch(
+      result.dependencies.filter(
+        (path) =>
+          !options.boundary ||
+          !relative(options.boundary, path).startsWith(".."),
+      ),
+    )
+    return result
+  }
+
+  const get = async (folder: string, id: string | null) => {
+    if (options.lockedTarget) return undefined
+    const index = await list(folder)
+    const indexed = index.collections.find((entry) => entry.id === id)
+    if (!indexed) return undefined
+    const collection = {
+      ...indexed,
+      records: indexed.records.map((record) => ({ ...record })),
+    }
+    await attachRecordIcons(collection)
+    return collection
+  }
+
+  const summaries = async (folder: string) => {
+    const {
+      config: _config,
+      schemas: _schemas,
+      ...workspace
+    } = folderWorkspace(folder, { allowMissingSchemas: true })
+    if (options.lockedTarget)
+      return {
+        ...workspace,
+        schemas: [],
+        revision: undefined,
+        state: undefined,
+      }
+    const index = await list(folder)
+    return {
+      ...workspace,
+      schemas: index.collections.map(collectionSummary),
+      revision: index.revision,
+      state: index.state,
+    }
+  }
+
+  const invalidate = (path: string) => {
+    const affected = collectionIndex.invalidate(path)
+    if (
+      affected.length ||
+      (basename(path) === "raggle.json" && collectionScopes.size)
+    ) {
+      clearTimeout(collectionRefresh)
+      collectionRefresh = setTimeout(() => {
+        host.emit({
+          data: { path },
+          event: "kennel:workspace-changed",
+          type: "custom",
+        })
+        host.emit({
+          data: { path },
+          event: "kennel:metadata-changed",
+          type: "custom",
+        })
+      }, 50)
+      collectionRefresh.unref?.()
+    }
+    return affected
+  }
+
+  const handleMetadataPart = async ({
+    folder,
+    id,
+    response,
+    send,
+    sort,
+    url,
+  }: {
+    folder: string
+    id: string | null
+    response: ServerResponse
+    send: (body: unknown, headers?: Record<string, string>) => void
+    sort?: CollectionSort
+    url: URL
+  }) => {
+    const collection = await get(folder, id)
+    if (collection) {
+      send(
+        { folder, collection: orderCollection(collection, sort) },
+        { "Cache-Control": "no-store" },
+      )
+    } else {
+      response.writeHead(404, { "Content-Type": "application/json" })
+      response.end(JSON.stringify({ error: "Collection not found" }))
+    }
+  }
+
+  // The service always reads the local cache; only approved hosts use the network.
+  const favicon = faviconService()
+
+  /** Resolve detected record icons to inline assets. Detection stored
+   * `record.icon` at index time; here bytes are read or fetched and keyed by
+   * content, so repeated collection requests reuse the favicon cache and
+   * identical files share one asset entry. */
+  const attachRecordIcons = async (collection: CoreCollection) => {
+    const sourced = collection.records.filter(
+      (record: CoreRecord) => record?.icon,
+    )
+    if (!sourced.length) return
+    const assets: Record<string, KennelIconAsset> = {}
+    const attach = async (record: CoreRecord) => {
+      const icon = record.icon! // guarded by the filter above
+      record.iconAssetKey = undefined
+      try {
+        if (icon.source === "local" && icon.path) {
+          const data = await localRecordIcon(
+            icon.path,
+            record.path,
+            collection.folder,
+          )
+          if (!data) return
+          const key = `local:${createHash("sha256").update(data).digest("hex")}`
+          record.iconAssetKey = key
+          assets[key] = {
+            data: data.toString("base64"),
+            mediaType: "image/png",
+            source: "local",
+          }
+          return
+        }
+        if (icon.source === "favicon" && icon.host) {
+          const data = await favicon(icon.host)
+          if (!data) return
+          const key = `favicon:${createHash("sha256").update(data).digest("hex")}`
+          record.iconAssetKey = key
+          assets[key] = {
+            data: data.toString("base64"),
+            mediaType: "image/png",
+            source: "favicon",
+          }
+        }
+      } catch {
+        record.iconAssetKey = undefined
+      }
+    }
+    for (let index = 0; index < sourced.length; index += 8)
+      await Promise.all(sourced.slice(index, index + 8).map(attach))
+    collection.assets = assets
+  }
+
+  const dispose = () => clearTimeout(collectionRefresh)
+
+  return { dispose, get, handleMetadataPart, invalidate, list, summaries }
+}

package/kernel/packages/schemas/src/ui/schema-entity-list.tsx

@@ -0,0 +1,124 @@
+import { useState } from "react"
+
+import { CollectionIcon } from "@raggle-ai/ui/components/collection-icon"
+import { CopyContextButton } from "@raggle-ai/ui/components/copy-context"
+import { FolderList } from "@raggle-ai/ui/components/folder-list"
+
+import type {
+  CoreCollection,
+  CoreRecord,
+  IndexIssue,
+} from "../data/contract.ts"
+import { fieldText, fieldValue } from "../data/fields.ts"
+
+/** Collection icon sizing keeps parity with the `.landing-list-row >
+ * svg:first-child` rule. Record icons carry their own metadata media types. */
+function RecordIcon({
+  collection,
+  record,
+}: {
+  collection: CoreCollection
+  record: CoreRecord
+}) {
+  const [failed, setFailed] = useState<string | undefined>()
+  const asset = record.iconAssetKey
+    ? collection.assets?.[record.iconAssetKey]
+    : undefined
+  const src = asset
+    ? (asset.url ??
+      (asset.data ? `data:${asset.mediaType};base64,${asset.data}` : undefined))
+    : undefined
+  if (!src || failed === src) return <CollectionIcon name={collection.icon} />
+  return (
+    <img
+      alt=""
+      aria-hidden="true"
+      onError={() => setFailed(src)}
+      src={src}
+      style={{
+        width: 18,
+        height: 18,
+        borderRadius: 4,
+        objectFit: "contain",
+        flexShrink: 0,
+      }}
+    />
+  )
+}
+
+const recordFolderPath = (path: string) => path.replace(/[\\/][^\\/]+$/, "")
+
+/** Setup documents carry metadata for the folder that contains them. */
+const isFolderRecord = (path: string) =>
+  /(?:^|[\\/])(?:AGENTS|README|SKILL)\.md$/i.test(path)
+
+export type SchemaEntityListProps = {
+  collection: CoreCollection
+  documentHref: (path: string) => string
+  folderHref: (path: string) => string
+  folder: string
+  records: CoreRecord[]
+}
+
+/** Record rows of a schema-backed collection: title, secondary field, and
+ * metadata issues. The parent owns search and filter state. */
+export function SchemaEntityList({
+  collection,
+  documentHref,
+  folderHref,
+  folder,
+  records,
+}: SchemaEntityListProps) {
+  return (
+    <FolderList
+      className="landing-collection-records"
+      items={records}
+      renderActions={(record) => (
+        <CopyContextButton
+          className="landing-list-copy-context"
+          context={() => recordFolderPath(record.path)}
+          label={`Copy folder path for ${record.title}`}
+        />
+      )}
+      empty={
+        <p className="landing-empty">
+          {collection.count
+            ? "No matching records."
+            : "No records match this collection’s document patterns."}
+        </p>
+      }
+      getClassName={() => "has-copy-context"}
+      getKey={(record) => record.id}
+      getHref={(record) =>
+        isFolderRecord(record.path)
+          ? folderHref(recordFolderPath(record.path))
+          : `${documentHref(record.path.slice(folder.length + 1))}?collection=${encodeURIComponent(collection.id)}`
+      }
+      renderItem={(record) => (
+        <>
+          <RecordIcon collection={collection} record={record} />
+          <span>
+            <strong>{record.title}</strong>
+            <small>
+              {collection.ui.secondaryField
+                ? fieldText(
+                    fieldValue(record.fields, collection.ui.secondaryField),
+                  )
+                : record.relativePath}
+            </small>
+            {record.validationErrors.length ? (
+              <small
+                className="text-destructive"
+                title={record.validationErrors
+                  .map((error: IndexIssue) => `${error.path}: ${error.message}`)
+                  .join("\n")}
+              >
+                {record.validationErrors.length} metadata issues
+              </small>
+            ) : null}
+          </span>
+        </>
+      )}
+    />
+  )
+}

package/kernel/packages/schemas/src/ui/schema-filters.tsx

@@ -0,0 +1,186 @@
+import { Button } from "@raggle-ai/ui/components/button"
+import { CollapsibleContent } from "@raggle-ai/ui/components/collapsible"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@raggle-ai/ui/components/select"
+import { Slider } from "@raggle-ai/ui/components/slider"
+
+import type { CoreCollection } from "../data/contract.ts"
+import type { CollectionSort, NumericRange } from "../data/params.ts"
+import { fieldValue, filterOptions } from "../data/fields.ts"
+
+export type SchemaFiltersProps = {
+  collection: CoreCollection
+  filters: Record<string, string>
+  onClear: () => void
+  onFilters: (
+    update: (previous: Record<string, string>) => Record<string, string>,
+  ) => void
+  onRanges: (
+    update: (
+      previous: Record<string, NumericRange>,
+    ) => Record<string, NumericRange>,
+  ) => void
+  onRangesCommit: (
+    update: (
+      previous: Record<string, NumericRange>,
+    ) => Record<string, NumericRange>,
+  ) => void
+  onSort: (sort: CollectionSort) => void
+  ranges: Record<string, NumericRange>
+  refreshing?: boolean
+  sort: CollectionSort
+}
+
+function numericBounds(collection: CoreCollection, field: string) {
+  const values = collection.records
+    .map((record) => fieldValue(record.fields, field))
+    .filter((value): value is number => typeof value === "number")
+  return { max: Math.max(...values), min: Math.min(...values) }
+}
+
+const number = new Intl.NumberFormat()
+
+/** Inline collection controls, expanded by the header's filter button. */
+export function SchemaFilters({
+  collection,
+  filters,
+  onClear,
+  onFilters,
+  onRanges,
+  onRangesCommit,
+  onSort,
+  ranges,
+  refreshing = false,
+  sort,
+}: SchemaFiltersProps) {
+  const active =
+    Object.values(filters).some(Boolean) ||
+    Object.values(ranges).some(
+      (range) => range.min !== undefined || range.max !== undefined,
+    )
+  return (
+    <CollapsibleContent
+      id="collection-filters"
+      className="rounded-xl bg-white px-4 shadow-sm"
+      aria-label="Collection filters"
+      role="region"
+    >
+      <div className="flex items-center justify-between gap-2">
+        <p className="text-muted-foreground text-xs" role="status">
+          {refreshing
+            ? "Refreshing metadata…"
+            : `Indexed ${new Date(collection.indexedAt).toLocaleString()}`}
+          {collection.state === "error" ? " · Index has errors" : ""}
+        </p>
+        {active ? (
+          <Button variant="ghost" size="sm" onClick={onClear}>
+            Clear
+          </Button>
+        ) : null}
+      </div>
+      <div className="flex flex-wrap items-end gap-3 py-3">
+        {collection.ui.sort ? null : (
+          <label className="grid gap-1 text-sm">
+            Order
+            <Select
+              value={sort}
+              onValueChange={(value) => onSort(value as CollectionSort)}
+            >
+              <SelectTrigger aria-label="Order records">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="recent">Recently updated</SelectItem>
+                <SelectItem value="alpha">Alphabetical</SelectItem>
+              </SelectContent>
+            </Select>
+          </label>
+        )}
+        {collection.ui.filters.map((field) => {
+          const options = filterOptions(collection, field) as string[]
+          return (
+            <label key={field} className="grid gap-1 text-sm">
+              {field}
+              <Select
+                value={filters[field] ? `value:${filters[field]}` : "all"}
+                onValueChange={(value) =>
+                  onFilters((previous) => ({
+                    ...previous,
+                    [field]: value === "all" ? "" : value.slice(6),
+                  }))
+                }
+              >
+                <SelectTrigger aria-label={`Filter ${field}`}>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="all">All</SelectItem>
+                  {options.map((value) => (
+                    <SelectItem key={value} value={`value:${value}`}>
+                      {value}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </label>
+          )
+        })}
+        {collection.ui.numericFilters.map((field) => {
+          const bounds = numericBounds(collection, field)
+          const range = ranges[field] ?? {}
+          const min = Math.max(bounds.min, range.min ?? bounds.min)
+          const max = Math.min(bounds.max, range.max ?? bounds.max)
+          const updateRange =
+            (nextMin: number, nextMax: number) =>
+            (previous: Record<string, NumericRange>) => {
+              const nextRange = {
+                max: nextMax === bounds.max ? undefined : nextMax,
+                min: nextMin === bounds.min ? undefined : nextMin,
+              }
+              const next = { ...previous, [field]: nextRange }
+              if (nextRange.min === undefined && nextRange.max === undefined)
+                delete next[field]
+              return next
+            }
+          return (
+            <fieldset key={field} className="grid min-w-56 gap-1 text-sm">
+              <legend>{field}</legend>
+              <Slider
+                aria-label={`Filter ${field}`}
+                max={bounds.max}
+                min={bounds.min}
+                step={
+                  Number.isInteger(bounds.min) && Number.isInteger(bounds.max)
+                    ? 1
+                    : undefined
+                }
+                value={[Math.min(min, max), Math.max(min, max)]}
+                onValueChange={(value) => {
+                  const [nextMin, nextMax] = value
+                  if (nextMin !== undefined && nextMax !== undefined)
+                    onRanges(updateRange(nextMin, nextMax))
+                }}
+                onValueCommit={(value) => {
+                  const [nextMin, nextMax] = value
+                  if (nextMin !== undefined && nextMax !== undefined)
+                    onRangesCommit(updateRange(nextMin, nextMax))
+                }}
+              />
+              <span
+                className="text-muted-foreground flex justify-between text-xs"
+              >
+                <span>{number.format(Math.min(min, max))}</span>
+                <span>{number.format(Math.max(min, max))}</span>
+              </span>
+            </fieldset>
+          )
+        })}
+      </div>
+    </CollapsibleContent>
+  )
+}

package/kernel/packages/schemas/src/ui/schema-search.tsx

@@ -0,0 +1,35 @@
+import { Button } from "@raggle-ai/ui/components/button"
+import { CollapsibleContent } from "@raggle-ai/ui/components/collapsible"
+import { Input } from "@raggle-ai/ui/components/input"
+
+export type SchemaSearchProps = {
+  onQuery: (query: string) => void
+  query: string
+}
+
+/** Collection search, expanded by the header's search button. */
+export function SchemaSearch({ onQuery, query }: SchemaSearchProps) {
+  return (
+    <CollapsibleContent
+      id="collection-search"
+      className="rounded-xl border bg-white px-4 py-3 shadow-sm"
+      aria-label="Search collection"
+      role="region"
+    >
+      <div className="flex items-center gap-3">
+        <Input
+          className="max-w-sm"
+          aria-label="Search collection"
+          placeholder="Search records…"
+          value={query}
+          onChange={(event) => onQuery(event.target.value)}
+        />
+        {query.trim() ? (
+          <Button variant="ghost" size="sm" onClick={() => onQuery("")}>
+            Clear
+          </Button>
+        ) : null}
+      </div>
+    </CollapsibleContent>
+  )
+}

package/kernel/packages/schemas/src/ui/use-query-param-filter-setting.tsx

@@ -0,0 +1,15 @@
+import type { CollectionSearchParams, CollectionSort } from "../data/params.ts"
+import { collectionSearchParamsHref } from "../data/params.ts"
+
+/** URL persistence for collection filters, search, and order. */
+export function useQueryParamFilterSetting(sort: CollectionSort) {
+  return (next: CollectionSearchParams) => {
+    if (typeof window === "undefined") return
+    // Use the live URL to preserve unrelated query parameters.
+    window.history.replaceState(
+      null,
+      "",
+      collectionSearchParamsHref(window.location.href, { ...next, sort }),
+    )
+  }
+}

package/kernel/packages/schemas/test/contract.test.mjs

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict"
+import test from "node:test"
+
+import { coreCollectionSchema } from "../src/data/contract.ts"
+
+test("core collection schema accepts normalized ui filters and sort", () => {
+  const parsed = coreCollectionSchema.parse({
+    id: "test",
+    folder: "/tmp/test",
+    schemaPath: "/tmp/test/schema.json",
+    title: "Test",
+    count: 0,
+    diagnostics: [],
+    revision: "rev",
+    indexedAt: "2026-01-01T00:00:00.000Z",
+    state: "ready",
+    ui: {
+      primaryField: "title",
+      filters: ["status"],
+      sort: [{ field: "status", direction: "asc" }],
+    },
+    records: [],
+  })
+
+  assert.deepEqual(parsed.ui.sort, [{ field: "status", direction: "asc" }])
+})