kennel 0.2.1 → 0.2.3

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

@@ -0,0 +1,22 @@
+export { collectionsManifest } from "./manifest.ts"
+export type {
+  CoreCollection,
+  CoreCollectionSummary,
+  CoreCollectionSummaryPayload,
+  CoreFolderIndex,
+  CoreRecord,
+  IndexIssue,
+  KennelCollectionSort,
+  KennelCollectionUi,
+  KennelDocumentConfig,
+  KennelSchemaConfig,
+} from "./data/contract.ts"
+export {
+  collectionSummary,
+  collectionSummarySchema,
+  coreCollectionSchema,
+  coreCollectionSortSchema,
+  coreCollectionUiSchema,
+  coreRecordSchema,
+  issueSchema,
+} from "./data/contract.ts"

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

@@ -0,0 +1,4 @@
+export const collectionsManifest = {
+  id: "collections",
+  label: "Collections",
+} as const

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

@@ -0,0 +1,384 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises"
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from "node:path"
+import type { ErrorObject, ValidateFunction } from "ajv"
+import type { Matcher } from "picomatch"
+import picomatch from "picomatch"
+import YAML from "yaml"
+
+import type { CoreCollection, CoreRecord, IndexIssue } from "./data/contract.ts"
+import { collectionSummary } from "./data/contract.ts"
+import { expandAllFilters, fieldValue } from "./data/fields.ts"
+import { recordIcon } from "./data/icon.ts"
+import { hash, loadCollectionSchema, text } from "./data/load.ts"
+import { folderWorkspace } from "./data/workspace.ts"
+
+type CollectionDeclaration = { folder: string; schemaPath: string }
+type CollectionConfig = {
+  documents: Array<{ glob?: unknown; parser?: unknown; path?: unknown }>
+  icon?: string
+  title?: string
+  ui: {
+    filters: string | string[]
+    numericFilters: string[]
+    navLabel?: string
+    primaryField: string
+    secondaryField?: string
+    sort?: Array<{ direction: "asc" | "desc"; field: string }>
+  }
+}
+type Pattern = { depth: number; glob: string; matches: Matcher }
+type ParsedRecord = {
+  body: string
+  errors: IndexIssue[]
+  fields: Record<string, unknown>
+  fingerprint: string
+  heading?: string
+}
+/** Standard setup files are workspace tooling, not collection records. */
+const setupFiles = new Set(["AGENTS.md", "README.md", "SKILL.md"])
+
+type CollectionCacheEntry = CollectionDeclaration & {
+  configPaths: string[]
+  data: CoreCollection
+  dirty: boolean
+}
+
+const inside = (root: string, path: string) => {
+  const child = relative(root, path)
+  return !isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`)
+}
+const posix = (path: string) => path.split(sep).join("/")
+const issue = (path: string, message: string): IndexIssue => ({ path, message })
+
+export { collectionSummary }
+
+/** Per-host cache. Notifications invalidate only dependent collections/records. */
+export function createCoreFolderIndex() {
+  const collections = new Map<string, CollectionCacheEntry>()
+  const records = new Map<string, ParsedRecord>()
+  const scopes = new Map<string, Set<string>>()
+  const stats = { collectionsBuilt: 0, recordsRead: 0 }
+  let generation = 0
+
+  function invalidate(changed: string) {
+    const path = resolve(changed)
+    generation++
+    const affected = new Set<string>()
+    for (const [key, entry] of collections) {
+      if (
+        path === entry.schemaPath ||
+        inside(entry.folder, path) ||
+        inside(path, entry.folder)
+      ) {
+        entry.dirty = true
+        for (const [scope, keys] of scopes)
+          if (keys.has(key)) affected.add(scope)
+      }
+    }
+    for (const [scope, keys] of scopes) {
+      for (const key of keys) {
+        const entry = collections.get(key)
+        if (entry?.configPaths.includes(path)) {
+          entry.dirty = true
+          affected.add(scope)
+        }
+      }
+      // Includes declaration changes when the previous result was empty.
+      if (
+        inside(path, scope) ||
+        (basename(path) === "raggle.json" && inside(dirname(path), scope)) ||
+        (["schema.json", "_schema.json"].includes(basename(path)) &&
+          dirname(path) === scope)
+      )
+        affected.add(scope)
+    }
+    for (const file of records.keys())
+      if (inside(path, file)) records.delete(file)
+    return [...affected]
+  }
+
+  async function load(
+    entry: CollectionDeclaration,
+    owner: string,
+    configPaths: string[],
+    boundary: string,
+  ) {
+    const key = `${owner}\0${entry.folder}\0${entry.schemaPath}\0${boundary}`
+    const cached = collections.get(key)
+    if (cached && !cached.dirty) return { key, data: cached.data }
+    stats.collectionsBuilt++
+    const startedAtGeneration = generation
+    const relativeId = posix(relative(owner, entry.folder))
+    const id = relativeId === "" ? "." : relativeId
+    const diagnostics: IndexIssue[] = []
+    let schema: Record<string, unknown> | undefined
+    let validate: ValidateFunction | undefined
+    let config: CollectionConfig = {
+      documents: [],
+      ui: { filters: [], numericFilters: [], primaryField: "title" },
+    }
+    const patterns: Pattern[] = []
+    let schemaVersion = ""
+    const indexedRecords: CoreRecord[] = []
+    try {
+      const canonicalFolder = await realpath(entry.folder)
+      const canonicalSchema = await realpath(entry.schemaPath)
+      if (
+        !inside(boundary, canonicalFolder) ||
+        !inside(boundary, canonicalSchema)
+      )
+        throw new Error("Collection paths escape the authorized root")
+      // Reject redirected collection roots instead of indexing symlink targets.
+      if (canonicalFolder !== entry.folder)
+        throw new Error("Symlinked collection folders are not indexed")
+      ;({ schema, config, schemaVersion, validate } =
+        await loadCollectionSchema(canonicalSchema))
+      const documents = config.documents
+      for (const document of documents) {
+        const glob = document?.glob ?? document?.path
+        if (
+          typeof glob !== "string" ||
+          isAbsolute(glob) ||
+          glob.split(/[\\/]/).includes("..")
+        ) {
+          diagnostics.push(
+            issue(
+              entry.schemaPath,
+              "Document glob must stay inside its collection",
+            ),
+          )
+          continue
+        }
+        if (document.parser !== "markdown-frontmatter") {
+          diagnostics.push(
+            issue(
+              entry.schemaPath,
+              `Unsupported parser: ${document.parser ?? "missing"}`,
+            ),
+          )
+          continue
+        }
+        // Traverse only as deep as these patterns can match.
+        const depth = glob.includes("**")
+          ? Infinity
+          : glob.split("/").length - 1
+        patterns.push({ depth, glob, matches: picomatch(glob, { dot: false }) })
+      }
+      // A pattern that names a setup file explicitly targets it: folder records
+      // whose frontmatter lives in an internal AGENTS.md and the like stay
+      // records. Every other pattern keeps the default ignore.
+      const explicitSetupFiles = new Set(
+        patterns.flatMap((pattern) =>
+          pattern.glob
+            .split(/[\\/]/)
+            .filter((segment) => setupFiles.has(segment)),
+        ),
+      )
+      const maxDepth = Math.max(-1, ...patterns.map((pattern) => pattern.depth))
+      async function walk(directory: string, depth: number) {
+        if (depth > maxDepth) return
+        for (const child of await readdir(directory, { withFileTypes: true })) {
+          if (child.name.startsWith(".") || child.name === "node_modules")
+            continue
+          const path = resolve(directory, child.name)
+          if (child.isDirectory()) {
+            await walk(path, depth + 1)
+            continue
+          }
+          if (
+            !child.isFile() ||
+            path === canonicalSchema ||
+            ["schema.json", "_schema.json"].includes(child.name) ||
+            (setupFiles.has(child.name) && !explicitSetupFiles.has(child.name))
+          )
+            continue
+          const localPath = posix(relative(entry.folder, path))
+          if (!patterns.some((pattern) => pattern.matches(localPath))) continue
+          const info = await stat(path)
+          const fingerprint = `${info.ino}:${info.mtimeMs}:${info.ctimeMs}:${info.size}`
+          let parsed = records.get(path)
+          if (parsed?.fingerprint !== fingerprint) {
+            stats.recordsRead++
+            const source = await readFile(path, "utf8")
+            let fields: Record<string, unknown> = {}
+            let body = source
+            const errors: IndexIssue[] = []
+            const frontmatter =
+              /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source)
+            try {
+              if (frontmatter) {
+                const document = YAML.parseDocument(frontmatter[1] ?? "")
+                if (document.errors.length) throw document.errors[0]
+                const value = document.toJS({ maxAliasCount: 100 })
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                  throw new Error("Frontmatter must be an object")
+                fields = value as Record<string, unknown>
+                body = source.slice(frontmatter[0].length)
+              }
+            } catch (error) {
+              errors.push(
+                issue(
+                  path,
+                  error instanceof Error ? error.message : String(error),
+                ),
+              )
+            }
+            parsed = {
+              body,
+              fingerprint,
+              fields,
+              errors,
+              heading: /^#\s+(.+)$/m.exec(body)?.[1]?.trim(),
+            }
+            records.set(path, parsed)
+          }
+          const validationErrors = [...parsed.errors]
+          if (validate && !validate(parsed.fields))
+            validationErrors.push(
+              ...(validate.errors ?? []).map((error: ErrorObject) =>
+                issue(
+                  error.instancePath === "" ? "/" : error.instancePath,
+                  error.message ?? "Invalid field",
+                ),
+              ),
+            )
+          const primary = config.ui.primaryField
+          indexedRecords.push({
+            id: posix(relative(owner, path)),
+            path,
+            relativePath: localPath,
+            modifiedAt: info.mtimeMs,
+            title:
+              text(fieldValue(parsed.fields, primary)) ??
+              text(parsed.fields.title) ??
+              parsed.heading ??
+              basename(path, ".md"),
+            fields: parsed.fields,
+            validationErrors,
+            icon: await recordIcon(
+              parsed.fields,
+              path,
+              entry.folder,
+              parsed.body,
+            ),
+          })
+        }
+      }
+      await walk(entry.folder, 0)
+    } catch (error) {
+      diagnostics.push(
+        issue(
+          entry.schemaPath,
+          error instanceof Error ? error.message : String(error),
+        ),
+      )
+    }
+    // Stable transport order. Call-side ordering lives in data/sort.ts and the
+    // collections API response applies it per request.
+    indexedRecords.sort((a, b) => a.id.localeCompare(b.id))
+    const ui: {
+      filters: string[]
+      numericFilters: string[]
+      primaryField: string
+      secondaryField?: string
+      sort?: Array<{ direction: "asc" | "desc"; field: string }>
+    } = {
+      primaryField: config.ui?.primaryField ?? "title",
+      secondaryField: config.ui?.secondaryField,
+      filters: [],
+      numericFilters: config.ui?.numericFilters.filter((field) =>
+        indexedRecords.some(
+          (record) => typeof fieldValue(record.fields, field) === "number",
+        ),
+      ),
+      sort: config.ui?.sort,
+    }
+    ui.filters = expandAllFilters(
+      {
+        ui: { ...ui, filters: config.ui?.filters ?? [] },
+        records: indexedRecords,
+      },
+      schema,
+    )
+    const data = {
+      id,
+      ...entry,
+      title: text(schema?.title) ?? config.title ?? basename(entry.folder),
+      navLabel: config.ui?.navLabel,
+      icon: config.icon,
+      count: indexedRecords.length,
+      diagnostics,
+      ui,
+      records: indexedRecords,
+      state: diagnostics.length ? ("error" as const) : ("ready" as const),
+    }
+    const result = {
+      ...data,
+      revision: hash({ data, schemaVersion }),
+      indexedAt: new Date().toISOString(),
+    }
+    collections.set(key, {
+      ...entry,
+      configPaths,
+      dirty: generation !== startedAtGeneration,
+      data: result,
+    })
+    return { key, data: result }
+  }
+
+  async function list(input: string, options: { boundary?: string } = {}) {
+    const folder = await realpath(input)
+    const workspace = folderWorkspace(folder, { allowMissingSchemas: true })
+    const boundary = options.boundary
+      ? await realpath(options.boundary)
+      : workspace.root
+    if (!inside(boundary, folder))
+      throw new Error("Folder escapes the authorized root")
+    const declarations = [...workspace.schemas]
+    // A directly opened, locally schema-backed folder also forms a collection.
+    if (
+      workspace.schemaPath &&
+      dirname(workspace.schemaPath) === folder &&
+      !declarations.some((entry) => entry.folder === folder)
+    )
+      declarations.unshift({ folder, schemaPath: workspace.schemaPath })
+    const configPaths = [
+      ...new Set(
+        [workspace.configPath, resolve(workspace.root, "raggle.json")].filter(
+          (path): path is string => Boolean(path),
+        ),
+      ),
+    ]
+    const entries = await Promise.all(
+      declarations.map((entry) =>
+        load(entry, workspace.root, configPaths, boundary),
+      ),
+    )
+    scopes.set(folder, new Set(entries.map((entry) => entry.key)))
+    const result = entries.map((entry) => entry.data)
+    const dependencies = [
+      ...new Set([
+        ...configPaths,
+        ...declarations.flatMap((entry) => [entry.folder, entry.schemaPath]),
+      ]),
+    ]
+    return {
+      folder,
+      root: workspace.root,
+      revision: hash(result.map((entry) => entry.revision)),
+      state: result.some((entry) => entry.state === "error")
+        ? "error"
+        : "ready",
+      collections: result,
+      dependencies,
+    }
+  }
+  return { list, invalidate, stats }
+}

package/kernel/packages/schemas/src/pages/collection.tsx

@@ -0,0 +1,252 @@
+import { useState } from "react"
+import { Filter, Search, X } from "lucide-react"
+
+import { Button } from "@raggle-ai/ui/components/button"
+import { Collapsible } from "@raggle-ai/ui/components/collapsible"
+import { CollectionIcon } from "@raggle-ai/ui/components/collection-icon"
+
+import type { CoreCollection, CoreRecord } from "../data/contract.ts"
+import type { CollectionSort, NumericRange } from "../data/params.ts"
+import { readCollectionSearchParams } from "../data/params.ts"
+import { collectionRecords } from "../data/query.ts"
+import { SchemaEntityList } from "../ui/schema-entity-list.tsx"
+import { SchemaFilters } from "../ui/schema-filters.tsx"
+import { SchemaSearch } from "../ui/schema-search.tsx"
+import { useQueryParamFilterSetting } from "../ui/use-query-param-filter-setting.tsx"
+
+export type CollectionViewProps = {
+  collection: CoreCollection
+  documentHref: (path: string) => string
+  folderHref: (path: string) => string
+  folder: string
+  href: string
+  onSort: (sort: CollectionSort) => void
+  refreshing?: boolean
+  sort: CollectionSort
+}
+
+export function CollectionView({
+  collection,
+  documentHref,
+  folderHref,
+  folder,
+  href,
+  onSort,
+  refreshing = false,
+  sort,
+}: CollectionViewProps) {
+  const [filtersOpen, setFiltersOpen] = useState(false)
+  const [searchOpen, setSearchOpen] = useState(false)
+
+  /** Read initial state from the URL; keep subsequent changes local. */
+  const [state, setState] = useState(() =>
+    readCollectionSearchParams(
+      href,
+      collection.ui.filters,
+      collection.ui.numericFilters,
+    ),
+  )
+
+  const updateParams = useQueryParamFilterSetting(sort)
+  const applyState = (
+    update: (previous: typeof state) => typeof state,
+    syncUrl = true,
+  ) => {
+    setState((previous) => {
+      const next = update(previous)
+      if (syncUrl) updateParams(next)
+      return next
+    })
+  }
+  const applyQuery = (query: string) =>
+    applyState((previous) => ({ ...previous, query }))
+  const applyFilters = (
+    update: (previous: Record<string, string>) => Record<string, string>,
+  ) =>
+    applyState((previous) => ({
+      ...previous,
+      filters: update(previous.filters),
+    }))
+  const updateRanges = (
+    update: (
+      previous: Record<string, NumericRange>,
+    ) => Record<string, NumericRange>,
+    syncUrl = true,
+  ) =>
+    applyState(
+      (previous) => ({
+        ...previous,
+        ranges: update(previous.ranges),
+      }),
+      syncUrl,
+    )
+  const applyRanges = (
+    update: (
+      previous: Record<string, NumericRange>,
+    ) => Record<string, NumericRange>,
+  ) => updateRanges(update)
+  const previewRanges = (
+    update: (
+      previous: Record<string, NumericRange>,
+    ) => Record<string, NumericRange>,
+  ) => updateRanges(update, false)
+
+  const records = collectionRecords(
+    collection,
+    state.filters,
+    state.query,
+    state.ranges,
+  ) as CoreRecord[]
+  const activeFilters = collection.ui.filters
+    .filter((field) => state.filters[field])
+    .map((field) => ({
+      key: `filter:${field}`,
+      label: `${field}: ${state.filters[field]}`,
+      remove: () =>
+        applyFilters((previous) => {
+          const next = { ...previous }
+          delete next[field]
+          return next
+        }),
+    }))
+  for (const field of collection.ui.numericFilters) {
+    const range = state.ranges[field]
+    if (!range || (range.min === undefined && range.max === undefined)) continue
+    const label = [
+      range.min === undefined ? "" : `≥ ${range.min}`,
+      range.max === undefined ? "" : `≤ ${range.max}`,
+    ]
+      .filter(Boolean)
+      .join(" · ")
+    activeFilters.push({
+      key: `range:${field}`,
+      label: `${field}: ${label}`,
+      remove: () =>
+        applyRanges((previous) => {
+          const next = { ...previous }
+          delete next[field]
+          return next
+        }),
+    })
+  }
+  if (state.query.trim()) {
+    activeFilters.push({
+      key: "query",
+      label: `Search: “${state.query.trim()}”`,
+      remove: () => applyQuery(""),
+    })
+  }
+
+  return (
+    <main
+      className="mx-auto grid w-full max-w-3xl gap-4 px-4 py-5"
+      aria-label={collection.title}
+    >
+      <header className="flex flex-wrap items-center justify-between gap-3">
+        <h1
+          className="m-0 flex items-center gap-2 text-2xl font-semibold
+            text-[#233025]"
+        >
+          <CollectionIcon name={collection.icon} />
+          {collection.title}
+        </h1>
+        <div className="flex items-center gap-2">
+          <span className="text-muted-foreground text-sm" role="status">
+            {activeFilters.length
+              ? `${records.length} ${records.length === 1 ? "result" : "results"}`
+              : collection.count}
+          </span>
+          <Button
+            variant="ghost"
+            size="icon"
+            aria-controls="collection-search"
+            aria-expanded={searchOpen}
+            aria-label={searchOpen ? "Hide search" : "Show search"}
+            onClick={() => setSearchOpen((open) => !open)}
+          >
+            {searchOpen ? (
+              <X aria-hidden="true" />
+            ) : (
+              <Search aria-hidden="true" />
+            )}
+          </Button>
+          <Button
+            variant="ghost"
+            size="icon"
+            aria-controls="collection-filters"
+            aria-expanded={filtersOpen}
+            aria-label={filtersOpen ? "Hide filters" : "Show filters"}
+            onClick={() => setFiltersOpen((open) => !open)}
+          >
+            {filtersOpen ? (
+              <X aria-hidden="true" />
+            ) : (
+              <Filter aria-hidden="true" />
+            )}
+          </Button>
+        </div>
+      </header>
+      {activeFilters.length ? (
+        <div
+          className="flex flex-wrap gap-2"
+          role="group"
+          aria-label="Active filters"
+        >
+          {activeFilters.map(({ key, label, remove }) => (
+            <Button
+              key={key}
+              type="button"
+              variant="secondary"
+              size="sm"
+              className="border-border h-auto max-w-full rounded-full border
+                py-1 text-xs"
+              aria-label={`Remove ${label}`}
+              title={label}
+              onClick={remove}
+            >
+              <span className="min-w-0 truncate">{label}</span>
+              <X aria-hidden="true" className="size-3" />
+            </Button>
+          ))}
+        </div>
+      ) : null}
+      <Collapsible open={searchOpen} onOpenChange={setSearchOpen}>
+        <SchemaSearch onQuery={applyQuery} query={state.query} />
+      </Collapsible>
+      <Collapsible open={filtersOpen} onOpenChange={setFiltersOpen}>
+        <SchemaFilters
+          collection={collection}
+          filters={state.filters}
+          onFilters={applyFilters}
+          onRanges={previewRanges}
+          onRangesCommit={applyRanges}
+          onClear={() =>
+            applyState((previous) => ({
+              ...previous,
+              filters: {},
+              ranges: {},
+            }))
+          }
+          ranges={state.ranges}
+          onSort={onSort}
+          refreshing={refreshing}
+          sort={sort}
+        />
+      </Collapsible>
+      {collection.diagnostics.length ? (
+        <ul role="alert" className="text-destructive m-0 text-sm">
+          {collection.diagnostics.map((issue, index) => (
+            <li key={index}>{issue.message}</li>
+          ))}
+        </ul>
+      ) : null}
+      <SchemaEntityList
+        collection={collection}
+        documentHref={documentHref}
+        folderHref={folderHref}
+        folder={folder}
+        records={records}
+      />
+    </main>
+  )
+}