kennel 0.2.12 → 0.2.15

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

@@ -1,103 +0,0 @@
-export type CollectionSort = "alpha" | "recent"
-
-export type NumericRange = {
-  max?: number
-  min?: number
-}
-
-export type CollectionSearchParams = {
-  filters: Record<string, string>
-  query: string
-  ranges: Record<string, NumericRange>
-  sort?: CollectionSort
-}
-
-const filterPrefix = "f_"
-const maxPrefix = "max_"
-const minPrefix = "min_"
-const queryParam = "q"
-const sortParam = "sort"
-
-/** Read collection state from a page URL, ignoring unknown fields and empty values. */
-export function readCollectionSearchParams(
-  href: string,
-  filterFields: string[],
-  numericFields: string[],
-): CollectionSearchParams {
-  const url = new URL(href)
-  const fields = new Set(filterFields)
-  const numeric = new Set(numericFields)
-  const filters: Record<string, string> = {}
-  const ranges: Record<string, NumericRange> = {}
-  for (const [key, value] of url.searchParams) {
-    if (key.startsWith(filterPrefix) && value) {
-      const field = key.slice(filterPrefix.length)
-      if (fields.has(field)) filters[field] = value
-      continue
-    }
-    const prefix = key.startsWith(minPrefix)
-      ? minPrefix
-      : key.startsWith(maxPrefix)
-        ? maxPrefix
-        : undefined
-    if (!prefix || !value) continue
-    const field = key.slice(prefix.length)
-    const number = Number(value)
-    if (!numeric.has(field) || !Number.isFinite(number)) continue
-    ranges[field] = {
-      ...ranges[field],
-      [prefix === minPrefix ? "min" : "max"]: number,
-    }
-  }
-  return {
-    filters,
-    query: url.searchParams.get(queryParam) ?? "",
-    ranges,
-    sort: readCollectionSort(href),
-  }
-}
-
-/** Current URL order: "alpha" when set, else "recent". */
-export function readCollectionSort(href: string): CollectionSort {
-  const url = new URL(href)
-  return url.searchParams.get(sortParam) === "alpha" ? "alpha" : "recent"
-}
-
-/** URL with the order parameter set; "recent" stays default and off the URL. */
-export function collectionSortHref(href: string, sort: CollectionSort): string {
-  const url = new URL(href)
-  if (sort === "alpha") url.searchParams.set(sortParam, sort)
-  else url.searchParams.delete(sortParam)
-  return url.toString()
-}
-
-/** Build a URL with only the given collection state, preserving unrelated params. */
-export function collectionSearchParamsHref(
-  href: string,
-  params: CollectionSearchParams,
-): string {
-  const url = new URL(href)
-  url.searchParams.delete(queryParam)
-  for (const key of [...url.searchParams.keys()]) {
-    if (
-      key.startsWith(filterPrefix) ||
-      key.startsWith(minPrefix) ||
-      key.startsWith(maxPrefix)
-    )
-      url.searchParams.delete(key)
-  }
-  const query = params.query.trim()
-  if (query) url.searchParams.set(queryParam, query)
-  if (params.sort === "alpha") url.searchParams.set(sortParam, params.sort)
-  else url.searchParams.delete(sortParam)
-  for (const [field, value] of Object.entries(params.filters)) {
-    if (value) url.searchParams.set(`${filterPrefix}${field}`, value)
-  }
-  for (const [field, range] of Object.entries(params.ranges)) {
-    if (Number.isFinite(range.min))
-      url.searchParams.set(`${minPrefix}${field}`, String(range.min))
-    if (Number.isFinite(range.max))
-      url.searchParams.set(`${maxPrefix}${field}`, String(range.max))
-  }
-  return url.toString()
-}

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

@@ -1,33 +0,0 @@
-import type { CoreCollection, CoreRecord } from "./contract"
-import type { NumericRange } from "./params"
-import { fieldText, fieldValue } from "./fields"
-
-/** Records arrive sorted by the API. This pass only narrows them. */
-export function collectionRecords(
-  collection: CoreCollection,
-  filters: Record<string, string>,
-  query = "",
-  ranges: Record<string, NumericRange> = {},
-): CoreRecord[] {
-  const search = query.trim().toLocaleLowerCase()
-  return collection.records.filter(
-    (record) =>
-      (!search ||
-        `${record.title} ${Object.values(record.fields).map(fieldText).join(" ")}`
-          .toLocaleLowerCase()
-          .includes(search)) &&
-      collection.ui.filters.every(
-        (key) =>
-          !filters[key] ||
-          fieldText(fieldValue(record.fields, key)) === filters[key],
-      ) &&
-      Object.entries(ranges).every(([field, range]) => {
-        const value = fieldValue(record.fields, field)
-        return (
-          typeof value === "number" &&
-          (range.min === undefined || value >= range.min) &&
-          (range.max === undefined || value <= range.max)
-        )
-      }),
-  )
-}

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

@@ -1,50 +0,0 @@
-import type { CoreRecord } from "./contract.ts"
-import { fieldText, fieldValue } from "./fields.ts"
-
-export type RecordSortEntry = { direction: "asc" | "desc"; field: string }
-
-export function compareDefinedField(
-  left: CoreRecord,
-  right: CoreRecord,
-  field: string,
-  direction: "asc" | "desc",
-) {
-  const leftValue = fieldValue(left.fields, field)
-  const rightValue = fieldValue(right.fields, field)
-  const leftMissing = leftValue === null || leftValue === undefined
-  const rightMissing = rightValue === null || rightValue === undefined
-  if (leftMissing || rightMissing) {
-    if (leftMissing && rightMissing) return 0
-    return leftMissing ? 1 : -1
-  }
-  const result =
-    typeof leftValue === "number" && typeof rightValue === "number"
-      ? leftValue - rightValue
-      : fieldText(leftValue).localeCompare(fieldText(rightValue))
-  return direction === "desc" ? -result : result
-}
-
-export function compareTail(left: CoreRecord, right: CoreRecord) {
-  const title = left.title.localeCompare(right.title)
-  return title === 0 ? left.id.localeCompare(right.id) : title
-}
-
-/** Declared sort order first; otherwise newest record first. Title/id break ties. */
-export function recordOrder(sort: RecordSortEntry[] | undefined) {
-  if (!Array.isArray(sort)) {
-    return (left: CoreRecord, right: CoreRecord) =>
-      right.modifiedAt - left.modifiedAt || compareTail(left, right)
-  }
-  return (left: CoreRecord, right: CoreRecord) => {
-    for (const entry of sort) {
-      const result = compareDefinedField(
-        left,
-        right,
-        entry.field,
-        entry.direction,
-      )
-      if (result) return result
-    }
-    return compareTail(left, right)
-  }
-}

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

@@ -1,101 +0,0 @@
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs"
-import {
-  basename,
-  dirname,
-  isAbsolute,
-  relative,
-  resolve,
-  sep,
-} from "node:path"
-
-type SchemaDeclaration = { folder: string; schemaPath: string }
-type SchemaMatch = { schema: string; target: string }
-type Breadcrumb = { path: string; schema: boolean; title: string }
-type RaggleConfig = Record<string, unknown> & {
-  schemas?: Array<{ path?: unknown; schema?: unknown }>
-}
-
-function inside(root: string, path: string) {
-  const child = relative(root, path)
-  return (
-    child === "" ||
-    (!isAbsolute(child) && child !== ".." && !child.startsWith(`..${sep}`))
-  )
-}
-
-// Resolve declarations relative to their owner, never the currently opened child.
-export function folderWorkspace(
-  input: string,
-  { allowMissingSchemas = false }: { allowMissingSchemas?: boolean } = {},
-) {
-  const folder = realpathSync(input)
-  let schemaPath: string | undefined
-  let configPath: string | undefined
-  let config: RaggleConfig = {}
-  let root = folder
-  const schemas: SchemaDeclaration[] = []
-  const schemaRoots: string[] = []
-  for (let current = folder; ; current = dirname(current)) {
-    const localSchema = ["schema.json", "_schema.json"]
-      .map((name) => resolve(current, name))
-      .find((path) => existsSync(path) && statSync(path).isFile())
-    if (localSchema) schemaRoots.push(current)
-    schemaPath ??= localSchema
-    const candidate = resolve(current, "raggle.json")
-    if (existsSync(candidate)) {
-      const value = JSON.parse(readFileSync(candidate, "utf8")) as RaggleConfig
-      // Nearest values override parents, while schema declarations retain their owner.
-      config = { ...value, ...config }
-      configPath ??= candidate
-      root = current
-      const declarations = Array.isArray(value.schemas) ? value.schemas : []
-      const matches = declarations
-        .flatMap((entry) => {
-          if (
-            typeof entry?.path !== "string" ||
-            typeof entry?.schema !== "string"
-          )
-            return []
-          const target = resolve(current, entry.path)
-          const schema = resolve(current, entry.schema)
-          if (!inside(current, target) || !inside(current, schema))
-            throw new Error(`Schema declaration escapes ${candidate}`)
-          if (!inside(target, folder) && !inside(folder, target)) return []
-          const present = existsSync(schema) && statSync(schema).isFile()
-          if (!present && !allowMissingSchemas)
-            throw new Error(`Schema not found: ${schema}`)
-          if (present && !inside(realpathSync(current), realpathSync(schema)))
-            throw new Error(`Schema declaration escapes ${candidate}`)
-          schemaRoots.push(target)
-          if (
-            inside(folder, target) &&
-            !schemas.some((entry: SchemaDeclaration) => entry.folder === target)
-          )
-            schemas.push({ folder: target, schemaPath: schema })
-          return inside(target, folder) ? [{ target, schema }] : []
-        })
-        .sort(
-          (a: SchemaMatch, b: SchemaMatch) => b.target.length - a.target.length,
-        )
-      schemaPath ??= matches[0]?.schema
-      // A schemas owner is the workspace boundary; do not inherit unrelated ancestors.
-      if (declarations.length) break
-    }
-    if (existsSync(resolve(current, ".git")) || dirname(current) === current)
-      break
-  }
-  const breadcrumbs: Breadcrumb[] = []
-  for (
-    let current = folder;
-    inside(root, current);
-    current = dirname(current)
-  ) {
-    breadcrumbs.unshift({
-      path: current,
-      title: basename(current),
-      schema: schemaRoots.some((owner) => inside(owner, current)),
-    })
-    if (current === root) break
-  }
-  return { root, configPath, schemaPath, config, breadcrumbs, schemas }
-}

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

@@ -1,22 +0,0 @@
-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

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

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

@@ -1,384 +0,0 @@
-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 }
-}