kennel-plugins 0.0.0-stage → 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,67 @@
+import { FolderPluginManifest, FolderPluginDetection } from './types.js';
+export { FolderPluginDataset, FolderPluginPayload, FolderPluginPayloadError } from './types.js';
+
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+declare class FolderPluginFailure extends Error {
+    constructor(message: string);
+}
+/**
+ * Files a plugin wants scaffolding to create, paths relative to the
+ * authorized folder root (containment is enforced by the scaffolder).
+ */
+type FolderPluginInitFile = {
+    path: string;
+    content: string;
+};
+type FolderPluginInitResult = {
+    files: FolderPluginInitFile[];
+};
+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>;
+};
+
+export { type FolderPluginContext, type FolderPluginData, FolderPluginDetection, FolderPluginFailure, type FolderPluginInitFile, type FolderPluginInitResult, type FolderPluginServer };

package/dist/server.js

@@ -0,0 +1,7 @@
+import {
+  FolderPluginFailure
+} from "./chunk-AX4A4GYF.js";
+import "./chunk-MLKGABMK.js";
+export {
+  FolderPluginFailure
+};

package/dist/subpath.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+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.
+ */
+declare function matchSubpath<Source, Item>(sources: Source[], subpath: string, itemsOf: (source: Source) => Iterable<Item>, matches: (item: Item, id: string) => boolean): SubpathMatch<Source, Item> | undefined;
+
+export { type SubpathMatch, matchSubpath };

package/dist/subpath.js

@@ -0,0 +1,16 @@
+import "./chunk-MLKGABMK.js";
+
+// src/subpath.ts
+function matchSubpath(sources, subpath, itemsOf, matches) {
+  const id = subpath.trim();
+  if (!id) return void 0;
+  for (const source of sources) {
+    for (const item of itemsOf(source)) {
+      if (matches(item, id)) return { item, source };
+    }
+  }
+  return void 0;
+}
+export {
+  matchSubpath
+};

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+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.
+ */
+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";
+};
+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.
+ */
+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.
+ */
+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.
+ */
+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>`.
+ */
+type FolderPluginPayload<T> = {
+    data: FolderPluginDataset<T> | FolderPluginPayloadError;
+    kind: "available";
+} | {
+    kind: "unavailable";
+};
+/** True when the decoded data is an in-band error payload. */
+declare function isPluginPayloadError(data: unknown): data is FolderPluginPayloadError;
+
+export { type ContentIssue, type FolderPluginDataset, type FolderPluginDetection, type FolderPluginId, type FolderPluginManifest, type FolderPluginPayload, type FolderPluginPayloadError, isPluginPayloadError };

package/dist/types.js

@@ -0,0 +1,7 @@
+import {
+  isPluginPayloadError
+} from "./chunk-YLSYYX2L.js";
+import "./chunk-MLKGABMK.js";
+export {
+  isPluginPayloadError
+};

package/dist/validation.d.ts

@@ -0,0 +1,30 @@
+import { ContentIssue } from './types.js';
+
+/**
+ * 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.
+ */
+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.
+ */
+declare function parseJsonSource<T>(source: string, validate: (value: unknown) => ContentIssue[]): Validated<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.
+ */
+declare function issueSummary(issues: ContentIssue[], file?: string): string;
+
+export { ContentIssue, type Validated, issueSummary, parseJsonSource };

package/dist/validation.js

@@ -0,0 +1,29 @@
+import "./chunk-MLKGABMK.js";
+
+// src/validation.ts
+function parseJsonSource(source, validate) {
+  let value;
+  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 };
+}
+function issueSummary(issues, file = "content file") {
+  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} \u2014 ${first.message})`;
+}
+export {
+  issueSummary,
+  parseJsonSource
+};

package/package.json

@@ -1,6 +1,104 @@
 {
+  "$schema": "https://json.schemastore.org/package.json",
   "name": "kennel-plugins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Small shared contract for trusted folder view plugins in the Kennel web viewer.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raggle-ai/kennel.git",
+    "directory": "packages/plugins"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "prettier": "@raggle-ai/prettier-config",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./endpoint": {
+      "types": "./dist/endpoint.d.ts",
+      "import": "./dist/endpoint.js"
+    },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "import": "./dist/page.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./subpath": {
+      "types": "./dist/subpath.d.ts",
+      "import": "./dist/subpath.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./validation": {
+      "types": "./dist/validation.d.ts",
+      "import": "./dist/validation.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "bun run build",
+    "test": "bun test test/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier . --check --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
+    "format:fix": "prettier . --write --cache --cache-location .cache/.prettiercache --ignore-path ../../.prettierignore",
+    "lint": "eslint . --cache --cache-location .cache/.eslintcache",
+    "lint:fix": "eslint . --fix --cache --cache-location .cache/.eslintcache",
+    "clean": "git clean -xdf dist node_modules .cache .turbo/cache"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "lucide-react": "^0.562.0",
+    "next-themes": "^0.4.6",
+    "radix-ui": "^1.6.7",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.4.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.3.0",
+    "react-dom": ">=18.3.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "catalog:eslint",
+    "@eslint/eslintrc": "catalog:eslint",
+    "@ianvs/prettier-plugin-sort-imports": "catalog:prettier",
+    "@prettier/plugin-oxc": "catalog:prettier",
+    "@raggle-ai/eslint-config": "workspace:*",
+    "@raggle-ai/prettier-config": "workspace:*",
+    "@raggle-ai/tsconfig": "workspace:*",
+    "@raggle-ai/ui": "workspace:*",
+    "kennel-client": "workspace:*",
+    "@types/node": "catalog:",
+    "@types/react": "catalog:react19",
+    "eslint": "catalog:eslint",
+    "eslint-plugin-unused-imports": "catalog:eslint",
+    "prettier": "catalog:prettier",
+    "prettier-plugin-classnames": "catalog:prettier",
+    "prettier-plugin-merge": "catalog:prettier",
+    "prettier-plugin-tailwindcss": "catalog:prettier",
+    "react": "catalog:react19",
+    "tsup": "8.5.1",
+    "typescript": "catalog:",
+    "typescript-eslint": "catalog:eslint"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.