kennel 0.2.0 → 0.2.2

package/kernel/packages/folder-plugin/src/endpoint.ts

@@ -0,0 +1,273 @@
+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/folder-plugin/src/index.ts

@@ -0,0 +1,15 @@
+export type {
+  FolderPluginDetection,
+  FolderPluginId,
+  FolderPluginManifest,
+} from "./types.ts"
+export type {
+  FolderPluginClient,
+  FolderPluginHostActions,
+  FolderPluginViewProps,
+} from "./client.ts"
+export type {
+  FolderPluginDataset,
+  FolderPluginPayload,
+  FolderPluginPayloadError,
+} from "./types.ts"

package/kernel/packages/folder-plugin/src/server.ts

@@ -0,0 +1,78 @@
+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/folder-plugin/src/subpath.ts

@@ -0,0 +1,34 @@
+/**
+ * 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/folder-plugin/src/types.ts

@@ -0,0 +1,86 @@
+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/folder-plugin/src/validation.ts

@@ -0,0 +1,56 @@
+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/folder-plugin/test/contract.test.mjs

@@ -0,0 +1,133 @@
+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/folder-plugin/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "$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"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "eslint.config.mjs"]
+}