kennel 0.2.12 → 0.2.15

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

@@ -1,52 +0,0 @@
-// The complete public surface for external folder plugins. Plugins should
-// import this module only; it deliberately exposes selected shared UI, not
-// the underlying @raggle-ai/ui package.
-export {
-  CopyContextButton,
-  FilePreview,
-  FilePreviewList,
-  FolderFilterBar,
-  PluginPage,
-  PluginPageError,
-  PluginPageStatus,
-  useFolderFilter,
-} from "./page.ts"
-export { folderPathId } from "./client.ts"
-export {
-  apiError,
-  ApiError,
-  jsonError,
-  jsonResponse,
-  parseJsonBody,
-  readBoundedBody,
-  runApiRoute,
-  sameOrigin,
-} from "./endpoint.ts"
-export { FolderPluginFailure } from "./server.ts"
-export { isPluginPayloadError } from "./types.ts"
-export type {
-  FolderPluginDataset,
-  FolderPluginDetection,
-  FolderPluginId,
-  FolderPluginManifest,
-  FolderPluginPayload,
-  FolderPluginPayloadError,
-} from "./types.ts"
-export type {
-  FolderPluginClient,
-  FolderPluginHostActions,
-  FolderPluginViewProps,
-} from "./client.ts"
-export type { ApiErrorCode, ApiRouteHandle, ApiRouteSpec } from "./endpoint.ts"
-export type {
-  FolderPluginContext,
-  FolderPluginData,
-  FolderPluginInitFile,
-  FolderPluginInitResult,
-  FolderPluginServer,
-} from "./server.ts"
-export type {
-  FolderFilterChoice,
-  FolderFilterMode,
-  FolderSelection,
-} from "./page.ts"

package/kernel/packages/plugins/src/page.ts

@@ -1,17 +0,0 @@
-export {
-  EntityError as PluginPageError,
-  EntityPage as PluginPage,
-  EntityStatus as PluginPageStatus,
-} from "@raggle-ai/ui/pages/entity-page"
-export { CopyContextButton } from "@raggle-ai/ui/components/copy-context"
-export {
-  FilePreview,
-  FilePreviewList,
-} from "@raggle-ai/ui/components/file-preview"
-export { FolderFilterBar } from "@raggle-ai/ui/components/folder-filter-bar"
-export { useFolderFilter } from "@raggle-ai/ui/hooks/use-folder-filter"
-export type {
-  FolderFilterChoice,
-  FolderFilterMode,
-  FolderSelection,
-} from "@raggle-ai/ui/lib/folder-filter"

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

@@ -1,78 +0,0 @@
-import type { FolderPluginDetection, FolderPluginManifest } from "./types.ts"
-
-export type {
-  FolderPluginDataset,
-  FolderPluginDetection,
-  FolderPluginPayload,
-  FolderPluginPayloadError,
-} from "./types.ts"
-
-/**
- * Context the host passes to a plugin's server entry. The host performs the
- * authorized folder resolution and root containment before calling any
- * plugin, so a plugin id or subpath is never an access grant.
- */
-export type FolderPluginContext = {
-  /** Absolute authorized folder path, already realpath-resolved by the host. */
-  folder: string
-  /**
-   * Folders connected to the viewed folder by repository links, resolved by
-   * the host (same relation graph that powers linked notes). Plugins may
-   * read read-only content there (notes, tasks, instructions) but never
-   * write. Empty for remote, restricted, or machine-root hosts.
-   */
-  linkedFolders?: string[]
-}
-
-/**
- * Payload a plugin returns from its data handler. The host serializes it to
- * the client. `unavailable` lets a direct plugin URL render an explicit
- * empty state without blocking core folder navigation.
- */
-export type FolderPluginData =
-  { kind: "available"; data: unknown } | { kind: "unavailable" }
-
-/**
- * Node-side entry for a trusted folder plugin: an id/label manifest plus
- * content detection and a generic list/detail data handler. Plugins may not
- * touch the host shell; the host owns routing, layout, and dispatch.
- */
-/**
- * Thrown by a plugin to signal a server-side failure (like a preview read
- * error). The host maps this to an HTTP 5xx so it can never be mistaken for
- * an empty but healthy result. All other thrown errors in a handler map to a
- * not-found (4xx) response.
- */
-export class FolderPluginFailure extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = "FolderPluginFailure"
-  }
-}
-
-/**
- * Files a plugin wants scaffolding to create, paths relative to the
- * authorized folder root (containment is enforced by the scaffolder).
- */
-export type FolderPluginInitFile = {
-  path: string
-  content: string
-}
-
-export type FolderPluginInitResult = {
-  files: FolderPluginInitFile[]
-}
-
-export type FolderPluginServer = FolderPluginManifest & {
-  detect(context: FolderPluginContext): Promise<FolderPluginDetection>
-  handle(
-    context: FolderPluginContext,
-    subpath: string,
-  ): Promise<FolderPluginData>
-  /**
-   * Optional starter content scaffolding (`kennel init` / host init
-   * commands). Returns files to create; the host skips files that already
-   * exist unless forced. Absent for read-only views with no content file.
-   */
-  init?(context: FolderPluginContext): Promise<FolderPluginInitResult>
-}

package/kernel/packages/plugins/src/subpath.ts

@@ -1,34 +0,0 @@
-/**
- * Shared subpath matching for folder plugins: a detail subpath selects one
- * item across every discovered source, first match wins. Plugins with a
- * richer address scheme (tasks' `<folderRef>@<id>` qualified ids) parse
- * their own scheme first, then fall back to this helper for bare ids so
- * not-found semantics stay consistent across plugins.
- */
-export type SubpathMatch<Source, Item> = {
-  /** The full source object the caller supplied, kept intact for reuse. */
-  source: Source
-  item: Item
-}
-
-/**
- * Resolve a detail subpath to one item across the given sources. A source
- * earlier in the list wins over a later one, mirroring the "first source
- * that contains it wins" behavior of the reference plugins. Returns
- * undefined when no item matches; callers render their not-found state.
- */
-export function matchSubpath<Source, Item>(
-  sources: Source[],
-  subpath: string,
-  itemsOf: (source: Source) => Iterable<Item>,
-  matches: (item: Item, id: string) => boolean,
-): SubpathMatch<Source, Item> | undefined {
-  const id = subpath.trim()
-  if (!id) return undefined
-  for (const source of sources) {
-    for (const item of itemsOf(source)) {
-      if (matches(item, id)) return { item, source }
-    }
-  }
-  return undefined
-}

package/kernel/packages/plugins/src/types.ts

@@ -1,86 +0,0 @@
-export type FolderPluginId = string
-
-/**
- * One precise problem found in plugin content, shared by every plugin's
- * validation functions. `path` is JSON-pointer-ish (`tasks[2].status`) or
- * `#` for file-level problems.
- */
-export type ContentIssue = {
-  path: string
-  message: string
-  /** Advisory problem; absent means a hard error. Warnings never
-   * invalidate content — the file still detects as valid. */
-  severity?: "warning"
-}
-
-export type FolderPluginManifest = {
-  /** Stable identifier used in routes, URLs, and registries. Never a URL segment turned into an import path. */
-  id: FolderPluginId
-  /** Navigation label shown in the folder shell. */
-  label: string
-}
-
-/**
- * Result of a server-side content check. `available` reports an optional
- * count so the navigation item can show a number. `unavailable` means the
- * folder has no plugin content; `error` means detection failed and is not
- * proof of absence. The detect call never returns full content payloads.
- */
-export type FolderPluginDetection =
-  | { count?: number; status: "available" }
-  | { status: "unavailable" }
-  | { error: string; status: "error" }
-
-/**
- * Decoded-dataset payload: the plugin's typed dataset for the view plus
- * optional advisory warnings. Extra fields (like the owning folder) are
- * allowed; the index signature keeps host serialization flexible without
- * weakening the required `status` check.
- */
-export type FolderPluginDataset<T> = {
-  /** The plugin's decoded dataset for the view. */
-  dataset: T
-  status: "available"
-  /** Advisory problems; they never invalidate the dataset. */
-  warnings?: ContentIssue[]
-} & { [key: string]: unknown }
-
-/**
- * In-band error payload: precise issues or a message, never a throw. The
- * client renders the issue list (the shared `ContentIssues` panel) so a
- * broken content file shows exactly which fields are wrong.
- */
-export type FolderPluginPayloadError = {
-  /** Per-field issues for invalid content; empty for a not-found detail. */
-  issues?: ContentIssue[]
-  /** Human message for a not-found detail subpath. */
-  message?: string
-  status: "error"
-} & { [key: string]: unknown }
-
-/**
- * Typed payload a plugin returns from its data handler. The `kind`/`status`
- * pairing is the contract: a handler never throws for content problems — it
- * returns `{ kind: "available", data: { status: "error", issues } }` in
- * band, or `{ kind: "unavailable" }` when the folder has no content at all.
- * The host-side `FolderPluginData` stays the loose type for tolerance; new
- * plugins type their handler as `FolderPluginPayload<T>`.
- */
-export type FolderPluginPayload<T> =
-  | {
-      data: FolderPluginDataset<T> | FolderPluginPayloadError
-      kind: "available"
-    }
-  | { kind: "unavailable" }
-
-/** True when the decoded data is an in-band error payload. */
-export function isPluginPayloadError(
-  data: unknown,
-): data is FolderPluginPayloadError {
-  return (
-    typeof data === "object" &&
-    data !== null &&
-    "status" in data &&
-    (data as { status: unknown }).status === "error"
-  )
-}

package/kernel/packages/plugins/src/validation.ts

@@ -1,56 +0,0 @@
-import type { ContentIssue } from "./types.ts"
-
-export type { ContentIssue } from "./types.ts"
-
-/**
- * Result of validating a content source: a typed document, or a list of
- * precise per-field issues. Parsing never throws — invalid JSON becomes an
- * issue with the parser's position detail so callers can render it directly.
- */
-export type Validated<T> =
-  { ok: true; document: T } | { ok: false; issues: ContentIssue[] }
-
-/**
- * Shared "validation function" primitive for folder plugins: parse a JSON
- * source string, run the plugin's `validate` rules, and return either the
- * typed document or structured issues. This is what every plugin's
- * `src/parse.ts` should build on so detection, data loading, client rendering
- * and tests all share one rule set.
- */
-export function parseJsonSource<T>(
-  source: string,
-  validate: (value: unknown) => ContentIssue[],
-): Validated<T> {
-  let value: unknown
-  try {
-    value = JSON.parse(source)
-  } catch (error) {
-    const detail =
-      error instanceof Error && error.message
-        ? error.message
-        : "could not be parsed"
-    return {
-      ok: false,
-      issues: [{ path: "#", message: `not valid JSON: ${detail}` }],
-    }
-  }
-  const issues = validate(value)
-  if (issues.length > 0) return { ok: false, issues }
-  return { ok: true, document: value as T }
-}
-
-/**
- * Compact one-line summary of validation issues for nav badges and error
- * headers: the single issue when there is one, otherwise a count plus the
- * first problem.
- */
-export function issueSummary(
-  issues: ContentIssue[],
-  file = "content file",
-): string {
-  const first = issues[0]
-  if (!first) return `${file} is valid`
-  const label = first.path && first.path !== "#" ? first.path : file
-  if (issues.length === 1) return `${label}: ${first.message}`
-  return `${issues.length} problems found in ${file} (first: ${label} — ${first.message})`
-}

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

@@ -1,133 +0,0 @@
-import assert from "node:assert/strict"
-import { readFile } from "node:fs/promises"
-import test from "node:test"
-
-import { FolderPluginFailure } from "../src/server.ts"
-import { matchSubpath } from "../src/subpath.ts"
-import { isPluginPayloadError } from "../src/types.ts"
-import { issueSummary, parseJsonSource } from "../src/validation.ts"
-
-const indexSource = await readFile(
-  new URL("../src/index.ts", import.meta.url),
-  "utf8",
-)
-const clientSource = await readFile(
-  new URL("../src/client.ts", import.meta.url),
-  "utf8",
-)
-
-test("the shared index re-exports browser-safe types only", () => {
-  assert.match(indexSource, /FolderPluginClient/)
-  assert.match(indexSource, /FolderPluginManifest/)
-  assert.doesNotMatch(indexSource, /node:/)
-})
-
-test("the client entry never imports the Node server entry", () => {
-  assert.doesNotMatch(clientSource, /node:/)
-  assert.doesNotMatch(clientSource, /server["']/)
-})
-
-test("the server failure class extends Error with a stable name and message", () => {
-  const failure = new FolderPluginFailure("Mail preview failed: boom")
-  assert.ok(failure instanceof FolderPluginFailure)
-  assert.ok(failure instanceof Error)
-  assert.equal(failure.name, "FolderPluginFailure")
-  assert.equal(failure.message, "Mail preview failed: boom")
-})
-
-test("parseJsonSource returns a document for valid input and issues otherwise", () => {
-  const valid = parseJsonSource(JSON.stringify({ name: "ok" }), (value) =>
-    value && typeof value === "object" && "name" in value
-      ? []
-      : [{ path: "#", message: "no name" }],
-  )
-  assert.equal(valid.ok, true)
-  if (valid.ok) assert.equal(valid.document.name, "ok")
-
-  const invalidJson = parseJsonSource("{ nope", () => [])
-  assert.equal(invalidJson.ok, false)
-  if (!invalidJson.ok) {
-    assert.equal(invalidJson.issues[0].path, "#")
-    assert.match(invalidJson.issues[0].message, /not valid JSON/)
-  }
-
-  const invalidValue = parseJsonSource("[]", () => [
-    { path: "#", message: "no name" },
-  ])
-  assert.equal(invalidValue.ok, false)
-})
-
-test("matchSubpath resolves one item across sources, first source wins", () => {
-  const sources = [
-    { folder: "/root", items: [{ id: "shared" }, { id: "root-only" }] },
-    { folder: "/linked", items: [{ id: "shared" }, { id: "linked-only" }] },
-  ]
-  const itemsOf = (source) => source.items
-
-  const shared = matchSubpath(
-    sources,
-    "shared",
-    itemsOf,
-    (item, id) => item.id === id,
-  )
-  assert.equal(shared.source.folder, "/root")
-  assert.equal(shared.item.id, "shared")
-
-  const linked = matchSubpath(
-    sources,
-    "linked-only",
-    itemsOf,
-    (item, id) => item.id === id,
-  )
-  assert.equal(linked.source.folder, "/linked")
-
-  assert.equal(
-    matchSubpath(sources, "missing", itemsOf, (item, id) => item.id === id),
-    undefined,
-  )
-  assert.equal(
-    matchSubpath(sources, "   ", itemsOf, (item, id) => item.id === id),
-    undefined,
-  )
-})
-
-test("isPluginPayloadError narrows in-band error payloads only", () => {
-  assert.equal(
-    isPluginPayloadError({
-      status: "error",
-      issues: [{ path: "a", message: "b" }],
-    }),
-    true,
-  )
-  assert.equal(
-    isPluginPayloadError({ message: "not found", status: "error" }),
-    true,
-  )
-  assert.equal(
-    isPluginPayloadError({ dataset: {}, status: "available" }),
-    false,
-  )
-  assert.equal(isPluginPayloadError(null), false)
-  assert.equal(isPluginPayloadError("error"), false)
-})
-
-test("issueSummary formats single and multiple issues", () => {
-  assert.equal(
-    issueSummary([{ path: "tasks[0].name", message: "required" }], "todo.json"),
-    "tasks[0].name: required",
-  )
-  assert.equal(
-    issueSummary([{ path: "#", message: "not valid JSON: boom" }], "todo.json"),
-    "todo.json: not valid JSON: boom",
-  )
-  assert.equal(
-    issueSummary(
-      [
-        { path: "a", message: "one" },
-        { path: "b", message: "two" },
-      ],
-      "todo.json",
-    ),
-    "2 problems found in todo.json (first: a — one)",
-  )
-})

package/kernel/packages/plugins/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "extends": "@raggle-ai/tsconfig/base.json",
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["dom", "dom.iterable", "esnext"],
-    "jsx": "preserve",
-    "baseUrl": ".",
-    "allowImportingTsExtensions": true,
-    // local copy: bun doesn't read paths inherited via `extends`
-    "paths": {
-      "~/*": ["${configDir}/../../packages/*/src"],
-      "kennel-plugins": ["./src/index.ts"],
-      "kennel-plugins/*": ["./src/*"],
-      "@raggle-ai/ui/*": ["../ui/src/*"],
-      "kennel-client": ["../api-client/src/index.ts"]
-    }
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist", "eslint.config.mjs"]
-}

package/kernel/packages/plugins/tsup.config.ts

@@ -1,25 +0,0 @@
-import { defineConfig } from "tsup"
-
-export default defineConfig({
-  entry: [
-    "src/index.ts",
-    "src/client.ts",
-    "src/endpoint.ts",
-    "src/page.ts",
-    "src/server.ts",
-    "src/subpath.ts",
-    "src/types.ts",
-    "src/validation.ts",
-  ],
-  format: ["esm"],
-  target: "es2022",
-  platform: "neutral",
-  clean: true,
-  esbuildOptions(options) {
-    options.jsx = "automatic"
-  },
-  splitting: true,
-  dts: { resolve: [/^@raggle-ai\/ui(?:\/|$)/, /^kennel-client(?:\/|$)/] },
-  noExternal: [/^@raggle-ai\/ui(?:\/|$)/, /^kennel-client(?:\/|$)/],
-  external: ["react", "react-dom", "react/jsx-runtime"],
-})

package/kernel/packages/schemas/ICON-POLICY.md

@@ -1,43 +0,0 @@
-# Record icon safety
-
-## Sources
-
-Schema records use a local PNG/JPEG from an explicit `icon` field first.
-Otherwise, they use an explicit `website` field or a labelled `Website:` line
-in the Markdown body. Evidence URLs and remote `icon` URLs are not used.
-
-A local image must resolve inside the record's own directory and the collection
-root. The server checks this again when it reads the image. Input is limited to
-512 KiB and one megapixel. PNG/JPEG files are decoded with Sharp and converted
-to small PNG images without source metadata. Invalid images are not displayed.
-
-## Network approval
-
-Cached icons remain available when network access is disabled. New downloads
-are disabled by default. To approve downloads, set both variables on the viewer:
-
-```sh
-KENNEL_EXTERNAL_ICONS=1
-KENNEL_FAVICON_ALLOWED_HOSTS=www.networkrail.co.uk,www.tpximpact.com
-```
-
-The list uses exact host names, separated by commas. It does not accept wildcards.
-Approving `example.org` does not approve `www.example.org` or other subdomains.
-Only approve public domains whose disclosure to Google's favicon service is
-acceptable. DNS and external requests are not made for unapproved cache misses.
-
-Set `KENNEL_EXTERNAL_ICONS=0`, or remove the approval list, to stop new downloads.
-This does not remove cached icons.
-
-## Disk cache
-
-Default location: `~/.cache/kennel/favicons`, or
-`$XDG_CACHE_HOME/kennel/favicons`. `KENNEL_FAVICON_CACHE_DIR` overrides it.
-
-Files use `sha256(host).png` names. Cache reads are size-limited and images are
-validated again. Valid images remain available without a network refresh.
-To replace an old icon, remove its cache file and approve its host before the
-next request. Failed approved downloads have a five-minute negative cache.
-
-Writes use a temporary file in the same directory, then an atomic rename.
-New directories have mode `0700`; new cache files have mode `0600`.