kennel 0.2.13 → 0.2.16

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

@@ -1,273 +0,0 @@
-import type { IncomingMessage, ServerResponse } from "node:http"
-
-export type ApiErrorCode =
-  | "aborted"
-  | "bad-request"
-  | "conflict"
-  | "failed"
-  | "forbidden"
-  | "internal"
-  | "method-not-allowed"
-  | "not-found"
-  | "payload-too-large"
-  | "timeout"
-
-const statusByCode: Record<ApiErrorCode, number> = {
-  aborted: 400,
-  "bad-request": 400,
-  conflict: 409,
-  failed: 500,
-  forbidden: 403,
-  internal: 500,
-  "method-not-allowed": 405,
-  "not-found": 404,
-  "payload-too-large": 413,
-  timeout: 504,
-}
-
-export class ApiError extends Error {
-  readonly code: ApiErrorCode
-  readonly status: number
-
-  constructor(code: ApiErrorCode, message: string) {
-    super(message)
-    this.name = "ApiError"
-    this.code = code
-    this.status = statusByCode[code]
-  }
-}
-
-export function apiError(code: ApiErrorCode, message: string) {
-  return new ApiError(code, message)
-}
-
-export function jsonResponse(
-  response: ServerResponse,
-  status: number,
-  body: unknown,
-  extraHeaders: Record<string, string> = {},
-) {
-  // Guard against double emission: a handler that already finished the
-  // response (or a client that disconnected after completion) must never
-  // trigger a `writeHead after end` crash.
-  if (response.writableEnded || response.headersSent || response.destroyed) {
-    return
-  }
-  response.writeHead(status, {
-    "Cache-Control": "no-store",
-    "Content-Type": "application/json; charset=utf-8",
-    ...extraHeaders,
-  })
-  response.end(JSON.stringify(body))
-}
-
-export function jsonError(
-  response: ServerResponse,
-  status: number,
-  code: ApiErrorCode,
-  message: string,
-  extraHeaders: Record<string, string> = {},
-) {
-  jsonResponse(response, status, { error: { code, message } }, extraHeaders)
-}
-
-/**
- * Same-origin guard for mutating requests (POST/DELETE). A browser sends
- * `Origin` (or `Referer`) on cross-site requests; require the header, when
- * present, to match the requested host and reject mutations without any
- * origin signal. GET requests never mutate and are exempt.
- */
-export function sameOrigin(request: IncomingMessage): boolean {
-  const host = request.headers.host
-  if (!host) return false
-
-  const origin = request.headers.origin
-  if (origin) {
-    try {
-      return new URL(origin).host === host
-    } catch {
-      return false
-    }
-  }
-
-  const referer = request.headers.referer
-  if (referer) {
-    try {
-      return new URL(referer).host === host
-    } catch {
-      return false
-    }
-  }
-
-  return false
-}
-
-/**
- * Read a request body bounded to `maxBytes` bytes. Real Node requests are
- * async-iterable; the caller must set `Content-Length` expectations too. An
- * oversized body or a cancellation aborts with a structured ApiError.
- */
-export async function readBoundedBody(
-  request: IncomingMessage,
-  maxBytes: number,
-  signal: AbortSignal,
-): Promise<string> {
-  const iterable = request as IncomingMessage & {
-    [Symbol.asyncIterator]?: () => AsyncIterableIterator<Buffer>
-  }
-  if (typeof iterable[Symbol.asyncIterator] !== "function") return ""
-
-  let total = 0
-  const chunks: Buffer[] = []
-  for await (const chunk of iterable) {
-    if (signal.aborted) throw apiError("aborted", "Request aborted")
-    total += chunk.length
-    if (total > maxBytes) {
-      throw apiError("payload-too-large", "Request body too large")
-    }
-    chunks.push(chunk)
-  }
-  return Buffer.concat(chunks).toString("utf8")
-}
-
-/**
- * JSON body helper for mutations. Returns the parsed object or throws a
- * structured bad-request error; non-Object payloads are rejected.
- */
-export function parseJsonBody(body: string): Record<string, unknown> {
-  if (!body.trim()) throw apiError("bad-request", "Request body required")
-  let value: unknown
-  try {
-    value = JSON.parse(body)
-  } catch {
-    throw apiError("bad-request", "Request body is not valid JSON")
-  }
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw apiError("bad-request", "Request body must be a JSON object")
-  }
-  return value as Record<string, unknown>
-}
-
-export type ApiRouteHandle<Context> = (ctx: {
-  body: string
-  context: Context
-  query: URLSearchParams
-  request: IncomingMessage
-  response: ServerResponse
-  signal: AbortSignal
-  url: URL
-}) => Promise<void> | void
-
-export type ApiRouteSpec<Context> = {
-  /** Only this HTTP method is accepted; anything else gets a 405. */
-  method: "GET" | "POST" | "DELETE"
-  /** Bounded request body in bytes; mutations without a body may set 0. */
-  maxBodyBytes?: number
-  /** Hard cap on handler execution; the child/request is cancelled after. */
-  timeoutMs?: number
-  /**
-   * Height of `ctx.body` before validation. Sizes over `maxBodyBytes` are
-   * rejected as 413, non-mutating methods never read a body.
-   */
-  handle: ApiRouteHandle<Context>
-}
-
-const methodAllowHeader = (method: string) => ({ Allow: method })
-
-/**
- * Run one declarative API route. Handles explicit method restriction,
- * same-origin protection for mutations, bounded bodies, abort on client
- * disconnect, timeouts, and structured JSON errors. Handlers never see raw
- * internals; unexpected errors become a generic 500 that cannot leak
- * command output or credentials.
- */
-export async function runApiRoute<Context>(
-  request: IncomingMessage,
-  response: ServerResponse,
-  url: URL,
-  spec: ApiRouteSpec<Context>,
-  context: Context,
-): Promise<void> {
-  const method = (request.method ?? "GET").toUpperCase()
-  if (method !== spec.method) {
-    jsonError(
-      response,
-      405,
-      "method-not-allowed",
-      `Method ${method} not allowed`,
-      methodAllowHeader(spec.method),
-    )
-    return
-  }
-
-  const controller = new AbortController()
-  const disconnect = () => controller.abort()
-  request.on?.("aborted", disconnect)
-  response.on?.("close", disconnect)
-
-  let timer: ReturnType<typeof setTimeout> | undefined
-  const timeoutPromise = spec.timeoutMs
-    ? new Promise<never>((_resolve, reject) => {
-        timer = setTimeout(() => {
-          // Cancel the child first (signal-aware handlers die immediately),
-          // then surface the timeout through the race below.
-          controller.abort()
-          reject(apiError("timeout", "Request timed out"))
-        }, spec.timeoutMs)
-      })
-    : null
-
-  try {
-    if (method !== "GET" && !sameOrigin(request)) {
-      throw apiError("forbidden", "Cross-origin mutations are not allowed")
-    }
-    const maxBody = spec.maxBodyBytes ?? (method === "GET" ? 0 : 1024 * 1024)
-    const body =
-      method === "GET"
-        ? ""
-        : await readBoundedBody(request, maxBody, controller.signal)
-    const ctx = {
-      body,
-      context,
-      query: url.searchParams,
-      request,
-      response,
-      signal: controller.signal,
-      url,
-    }
-    // The handler is raced against the deadline so an unresponsive handler
-    // cannot hang the server. Its own failures are collected and rethrown
-    // after the race (a late failure after a timeout is dropped silently).
-    let handlerError: unknown
-    const handlerPromise = (async () => {
-      await spec.handle(ctx)
-    })().catch((error: unknown) => {
-      handlerError = error
-    })
-    if (timeoutPromise) await Promise.race([handlerPromise, timeoutPromise])
-    else await handlerPromise
-    if (handlerError !== undefined) throw handlerError
-  } catch (error) {
-    if (error instanceof ApiError && error.code === "timeout") {
-      jsonError(response, 504, "timeout", error.message)
-      return
-    }
-    if (controller.signal.aborted) {
-      // Client is gone; nothing useful left to write.
-      return
-    }
-    if (error instanceof ApiError) {
-      jsonError(response, error.status, error.code, error.message)
-      return
-    }
-    if (error instanceof Error && error.name === "AbortError") {
-      jsonError(response, 400, "aborted", "Request aborted")
-      return
-    }
-    jsonError(response, 500, "internal", "Internal server error")
-  } finally {
-    if (timer) clearTimeout(timer)
-    request.removeListener?.("aborted", disconnect)
-    response.removeListener?.("close", disconnect)
-  }
-}

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

@@ -1,24 +0,0 @@
-import { createContext, createElement, useContext } from "react"
-import type { ReactNode } from "react"
-
-const FolderPathContext = createContext<string | undefined>(undefined)
-
-/** Host boundary. The host and plugin must resolve this module once. */
-export function FolderPathProvider({
-  folder,
-  children,
-}: {
-  folder: string
-  children: ReactNode
-}) {
-  return createElement(FolderPathContext.Provider, { value: folder }, children)
-}
-
-/** Current viewed folder. This is not a filter selection or a permission check. */
-export function useFolderPath(): string {
-  const folder = useContext(FolderPathContext)
-  if (folder === undefined) {
-    throw new Error("useFolderPath must be used inside FolderPathProvider")
-  }
-  return folder
-}

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

@@ -1,46 +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,
-  PluginPage,
-  PluginPageError,
-  PluginPageStatus,
-} 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,
-  FolderPluginIcon,
-  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"

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

@@ -1,10 +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"

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,94 +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"
-}
-
-/** Plugin-owned SVG path data. No React or page imports are needed for tabs. */
-export type FolderPluginIcon = {
-  /** Paths use a 24 × 24 view box and the navigation text color. */
-  paths: string[]
-}
-
-export type FolderPluginManifest = {
-  /** Stable identifier used in routes, URLs, and registries. Never a URL segment turned into an import path. */
-  id: FolderPluginId
-  /** Optional plugin-owned navigation icon. Omit for a text-only tab. */
-  icon?: FolderPluginIcon
-  /** 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})`
-}