kennel 0.2.7 → 0.2.9

package/README.md

@@ -96,6 +96,28 @@ package metadata, not from URL text. The transcripts plugin contract is package
 When this file is absent, entity search allows only the workspace opened by
 `knl`. Invalid config fails closed.
 
+The config format is published as a JSON Schema (draft 2020-12):
+
+- URL: `https://raw.githubusercontent.com/raggle-ai/kennel/main/cli/schemas/config.schema.json`
+- npm: `kennel/config.schema.json` (file `schemas/config.schema.json` in the package)
+
+Add `$schema` to the file for editor completion and validation:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/raggle-ai/kennel/main/cli/schemas/config.schema.json",
+  "allowedRoots": ["/path/to/workspace"]
+}
+```
+
+The CLI validates the file against this schema each time it reads the config
+and stops with the failing field paths when a value is malformed. Unknown keys
+are rejected. `externalPlugins` records are resolved and written by
+`kennel plugin add` (pinned commit, absolute entry files, export symbols); do
+not write or edit them by hand. To change one, remove the record and add the
+plugin again. The schema checks only the record shape: the install-time checks
+for the cache path, package exports, and imports stay in the CLI.
+
 Suggested convention for agents: write generated HTML components to
 `.kennel/preview/<name>.html` and pop them with `knl pop
 .kennel/preview/<name>.html --watch` (reuses 5180), so preview items share one

package/dist/cli/src/plugins/external.js

@@ -13,6 +13,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { z } from "zod";
 const CONFIG_FILE = join("kennel", "config.json");
 const VALID_ID = /^[a-z][a-z0-9-]*$/u;
 const CORE_IDS = new Set(["agents", "notes"]);
@@ -57,10 +58,51 @@ function run(command, args, options = {}) {
     }
     return result.stdout.trim();
 }
+let configSchema;
+function userConfigSchema() {
+    if (!configSchema) {
+        const json = JSON.parse(readFileSync(join(cliRoot(), "schemas", "config.schema.json"), "utf8"));
+        configSchema = { id: json.$id, schema: z.fromJSONSchema(json) };
+    }
+    return configSchema;
+}
+function assertUserConfig(value, path) {
+    const { id, schema } = userConfigSchema();
+    const result = schema.safeParse(value);
+    if (result.success)
+        return;
+    throw new Error(`Invalid Kennel config at ${path} (schema ${id}):\n${describeIssues(result.error.issues).join("\n")}\nexternalPlugins records are managed by \`kennel plugin add\`; remove a malformed record and add the plugin again.`);
+}
+function issuePath(path) {
+    return path.reduce((text, key) => typeof key === "number" ? `${text}[${key}]` : text ? `${text}.${String(key)}` : String(key), "") || "(root)";
+}
+function describeIssues(issues, base = [], indent = "  ") {
+    return issues.flatMap((issue) => {
+        const path = [...base, ...issue.path];
+        if (issue.code !== "invalid_union" || issue.errors.length === 0)
+            return [`${indent}${issuePath(path)}: ${issue.message}`];
+        return [
+            `${indent}${issuePath(path)}: matches none of the allowed shapes`,
+            ...issue.errors.flatMap((branch, index) => [
+                `${indent}  shape ${index + 1}:`,
+                ...describeIssues(branch, path, `${indent}    `),
+            ]),
+        ];
+    });
+}
 function readJson(path) {
     if (!existsSync(path))
         return {};
-    return JSON.parse(readFileSync(path, "utf8"));
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid Kennel config at ${path}: ${message}`);
+    }
+    assertUserConfig(value, path);
+    return value;
 }
 function writeJsonAtomic(path, value) {
     mkdirSync(dirname(path), { recursive: true });
@@ -350,19 +392,20 @@ export async function validateExternalPlugin(inputUrl, existing = [], options =
     return entry;
 }
 export function readExternalPlugins() {
-    const config = readJson(kennelConfigPath());
-    return Array.isArray(config.externalPlugins) ? config.externalPlugins : [];
+    return readJson(kennelConfigPath()).externalPlugins ?? [];
 }
 export async function installExternalPlugin(url, options = {}) {
     const path = kennelConfigPath();
     const config = readJson(path);
-    const externalPlugins = Array.isArray(config.externalPlugins) ? config.externalPlugins : [];
+    const externalPlugins = config.externalPlugins ?? [];
     let entry;
     try {
         entry = await validateExternalPlugin(url, externalPlugins, options);
         const nextPlugins = [...externalPlugins, entry];
+        const nextConfig = { ...config, externalPlugins: nextPlugins };
+        assertUserConfig(nextConfig, path);
         await ensureKernel(nextPlugins);
-        writeJsonAtomic(path, { ...config, externalPlugins: nextPlugins });
+        writeJsonAtomic(path, nextConfig);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/plugins/external.js

@@ -13,6 +13,7 @@ import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, relative, resolve, } from "node:path";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
+import { z } from "zod";
 const CONFIG_FILE = join("kennel", "config.json");
 const VALID_ID = /^[a-z][a-z0-9-]*$/u;
 const CORE_IDS = new Set(["agents", "notes"]);
@@ -57,10 +58,51 @@ function run(command, args, options = {}) {
     }
     return result.stdout.trim();
 }
+let configSchema;
+function userConfigSchema() {
+    if (!configSchema) {
+        const json = JSON.parse(readFileSync(join(cliRoot(), "schemas", "config.schema.json"), "utf8"));
+        configSchema = { id: json.$id, schema: z.fromJSONSchema(json) };
+    }
+    return configSchema;
+}
+function assertUserConfig(value, path) {
+    const { id, schema } = userConfigSchema();
+    const result = schema.safeParse(value);
+    if (result.success)
+        return;
+    throw new Error(`Invalid Kennel config at ${path} (schema ${id}):\n${describeIssues(result.error.issues).join("\n")}\nexternalPlugins records are managed by \`kennel plugin add\`; remove a malformed record and add the plugin again.`);
+}
+function issuePath(path) {
+    return path.reduce((text, key) => typeof key === "number" ? `${text}[${key}]` : text ? `${text}.${String(key)}` : String(key), "") || "(root)";
+}
+function describeIssues(issues, base = [], indent = "  ") {
+    return issues.flatMap((issue) => {
+        const path = [...base, ...issue.path];
+        if (issue.code !== "invalid_union" || issue.errors.length === 0)
+            return [`${indent}${issuePath(path)}: ${issue.message}`];
+        return [
+            `${indent}${issuePath(path)}: matches none of the allowed shapes`,
+            ...issue.errors.flatMap((branch, index) => [
+                `${indent}  shape ${index + 1}:`,
+                ...describeIssues(branch, path, `${indent}    `),
+            ]),
+        ];
+    });
+}
 function readJson(path) {
     if (!existsSync(path))
         return {};
-    return JSON.parse(readFileSync(path, "utf8"));
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid Kennel config at ${path}: ${message}`);
+    }
+    assertUserConfig(value, path);
+    return value;
 }
 function writeJsonAtomic(path, value) {
     mkdirSync(dirname(path), { recursive: true });
@@ -350,19 +392,20 @@ export async function validateExternalPlugin(inputUrl, existing = [], options =
     return entry;
 }
 export function readExternalPlugins() {
-    const config = readJson(kennelConfigPath());
-    return Array.isArray(config.externalPlugins) ? config.externalPlugins : [];
+    return readJson(kennelConfigPath()).externalPlugins ?? [];
 }
 export async function installExternalPlugin(url, options = {}) {
     const path = kennelConfigPath();
     const config = readJson(path);
-    const externalPlugins = Array.isArray(config.externalPlugins) ? config.externalPlugins : [];
+    const externalPlugins = config.externalPlugins ?? [];
     let entry;
     try {
         entry = await validateExternalPlugin(url, externalPlugins, options);
         const nextPlugins = [...externalPlugins, entry];
+        const nextConfig = { ...config, externalPlugins: nextPlugins };
+        assertUserConfig(nextConfig, path);
         await ensureKernel(nextPlugins);
-        writeJsonAtomic(path, { ...config, externalPlugins: nextPlugins });
+        writeJsonAtomic(path, nextConfig);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);

package/dist/site/kinds.js

@@ -1 +1,159 @@
-export * from "@raggle-ai/kennel-preview/kinds";
+// packages/kinds/src/kinds.ts
+var previewTextKinds = new Set([
+  "code",
+  "eml",
+  "html",
+  "markdown",
+  "table",
+  "text"
+]);
+function previewTextKind(kind) {
+  return previewTextKinds.has(kind);
+}
+var codeExtensions = new Set([
+  ".astro",
+  ".bash",
+  ".c",
+  ".cc",
+  ".cpp",
+  ".cs",
+  ".css",
+  ".dart",
+  ".ex",
+  ".exs",
+  ".go",
+  ".graphql",
+  ".h",
+  ".hpp",
+  ".hs",
+  ".java",
+  ".js",
+  ".jsx",
+  ".json",
+  ".kt",
+  ".less",
+  ".lua",
+  ".ml",
+  ".mjs",
+  ".php",
+  ".proto",
+  ".py",
+  ".rb",
+  ".rs",
+  ".scss",
+  ".sh",
+  ".sql",
+  ".svelte",
+  ".swift",
+  ".toml",
+  ".ts",
+  ".tsx",
+  ".vue",
+  ".xml",
+  ".yaml",
+  ".yml",
+  ".zsh"
+]);
+var imageExtensions = new Set([
+  ".avif",
+  ".bmp",
+  ".gif",
+  ".ico",
+  ".jpeg",
+  ".jpg",
+  ".png",
+  ".svg",
+  ".webp"
+]);
+var knownExtensions = new Set([
+  ...codeExtensions,
+  ...imageExtensions,
+  ".csv",
+  ".eml",
+  ".htm",
+  ".html",
+  ".markdown",
+  ".md",
+  ".mdx",
+  ".pdf",
+  ".text",
+  ".tsv",
+  ".txt"
+]);
+function previewKind(path) {
+  const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+  if (extension === ".htm" || extension === ".html")
+    return "html";
+  if (extension === ".md" || extension === ".markdown" || extension === ".mdx")
+    return "markdown";
+  if (extension === ".text" || extension === ".txt")
+    return "text";
+  if (extension === ".eml")
+    return "eml";
+  if (extension === ".csv" || extension === ".tsv")
+    return "table";
+  if (imageExtensions.has(extension))
+    return "image";
+  if (codeExtensions.has(extension))
+    return "code";
+  if (knownExtensions.has(extension))
+    return "binary";
+  return;
+}
+var rawMime = {
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".gif": "image/gif",
+  ".htm": "text/html; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp"
+};
+function previewRawMime(path) {
+  const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+  const mime = rawMime[extension];
+  if (mime)
+    return mime;
+  if (previewKind(path) === "code" || previewKind(path) === "table")
+    return "text/plain; charset=utf-8";
+  return;
+}
+var mediaMime = {
+  ".aac": "audio/aac",
+  ".avif": "image/avif",
+  ".bmp": "image/bmp",
+  ".flac": "audio/flac",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".m4a": "audio/mp4",
+  ".m4v": "video/mp4",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".oga": "audio/ogg",
+  ".ogg": "audio/ogg",
+  ".ogv": "video/ogg",
+  ".opus": "audio/opus",
+  ".png": "image/png",
+  ".wav": "audio/wav",
+  ".webm": "video/webm",
+  ".webp": "image/webp"
+};
+function mediaRawMime(path) {
+  const extension = path.slice(path.lastIndexOf(".")).toLowerCase();
+  return mediaMime[extension];
+}
+export {
+  mediaRawMime,
+  previewKind,
+  previewRawMime,
+  previewTextKind,
+  previewTextKinds
+};

package/kernel/packages/plugins/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "kennel-plugins",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Small shared contract for trusted folder view plugins in the Kennel web viewer.",
   "type": "module",
   "license": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kennel",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Open-source pop-up previews for AI output: markdown, HTML artifacts, email, images, code, tables, notes, and calendars, from the terminal or your agent session.",
   "type": "module",
   "license": "MIT",
@@ -32,7 +32,8 @@
     "./automations/notifications": {
       "types": "./dist/automations/notifications.d.ts",
       "import": "./dist/automations/notifications.js"
-    }
+    },
+    "./config.schema.json": "./schemas/config.schema.json"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -41,6 +42,7 @@
   "files": [
     "bin",
     "dist",
+    "schemas",
     "templates",
     "web",
     "kernel"
@@ -69,9 +71,7 @@
     "@raggle-ai/barkdown": "0.6.1",
     "@raggle-ai/kennel-knowledge": "^0.1.0",
     "@raggle-ai/kennel-mcp": "^0.1.8",
-    "@raggle-ai/kennel-preview": "^0.1.0",
     "@raggle-ai/local": "0.14.0",
-    "@raggle-ai/markdown": "^0.1.0",
     "@raggle-ai/scout-ui": "0.1.3",
     "@tailwindcss/vite": "4.3.3",
     "@tanstack/react-query": "^5.66.5",
@@ -115,7 +115,8 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "kennel-plugins": "0.1.1",
+    "@raggle-ai/kennel-preview": "0.1.0",
+    "kennel-plugins": "0.1.2",
     "@types/node": "^22.13.4",
     "typescript": "^5.9.3"
   },

package/schemas/config.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/raggle-ai/kennel/main/cli/schemas/config.schema.json",
+  "title": "Kennel user config",
+  "description": "Kennel user config at $XDG_CONFIG_HOME/kennel/config.json (default ~/.config/kennel/config.json). externalPlugins records are written by `kennel plugin add`; do not edit them by hand.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "description": "JSON Schema reference for editor validation.",
+      "type": "string",
+      "minLength": 1
+    },
+    "allowedRoots": {
+      "description": "Absolute local folders that entity search may read.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/absolutePath" }
+    },
+    "externalPlugins": {
+      "description": "Resolved external folder plugins. Managed by `kennel plugin add`.",
+      "type": "array",
+      "items": { "$ref": "#/$defs/externalPlugin" }
+    }
+  },
+  "$defs": {
+    "absolutePath": {
+      "type": "string",
+      "description": "Absolute path: POSIX, Windows drive, or Windows UNC.",
+      "pattern": "^(/|[A-Za-z]:[\\\\/]|\\\\\\\\)"
+    },
+    "symbol": {
+      "description": "Export name in the bundled module, or \"default\".",
+      "type": "string",
+      "minLength": 1
+    },
+    "externalPlugin": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url", "commit", "packageName", "id", "entries"],
+      "properties": {
+        "url": {
+          "description": "Git repository URL, without the #ref fragment.",
+          "type": "string",
+          "minLength": 1
+        },
+        "requestedRef": {
+          "description": "Ref from the #ref fragment given at install time.",
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "description": "Full commit SHA the plugin is pinned to.",
+          "type": "string",
+          "pattern": "^[0-9a-f]{40}$"
+        },
+        "packageName": {
+          "type": "string",
+          "minLength": 1
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$"
+        },
+        "directory": {
+          "description": "Plugin package root relative to the repository root.",
+          "type": "string",
+          "minLength": 1
+        },
+        "trigger": {
+          "description": "File name that activates the plugin in a folder.",
+          "type": "string",
+          "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
+        },
+        "entries": {
+          "description": "Resolved absolute entry files and export symbols. api and apiSymbol appear together or not at all.",
+          "oneOf": [
+            { "$ref": "#/$defs/entriesWithoutApi" },
+            { "$ref": "#/$defs/entriesWithApi" }
+          ]
+        }
+      }
+    },
+    "entriesWithoutApi": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["client", "clientSymbol", "server", "serverSymbol", "manifest", "manifestSymbol"],
+      "properties": {
+        "client": { "$ref": "#/$defs/absolutePath" },
+        "clientSymbol": { "$ref": "#/$defs/symbol" },
+        "server": { "$ref": "#/$defs/absolutePath" },
+        "serverSymbol": { "$ref": "#/$defs/symbol" },
+        "manifest": { "$ref": "#/$defs/absolutePath" },
+        "manifestSymbol": { "$ref": "#/$defs/symbol" },
+        "css": { "$ref": "#/$defs/absolutePath" }
+      }
+    },
+    "entriesWithApi": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["client", "clientSymbol", "server", "serverSymbol", "manifest", "manifestSymbol", "api", "apiSymbol"],
+      "properties": {
+        "client": { "$ref": "#/$defs/absolutePath" },
+        "clientSymbol": { "$ref": "#/$defs/symbol" },
+        "server": { "$ref": "#/$defs/absolutePath" },
+        "serverSymbol": { "$ref": "#/$defs/symbol" },
+        "manifest": { "$ref": "#/$defs/absolutePath" },
+        "manifestSymbol": { "$ref": "#/$defs/symbol" },
+        "api": { "$ref": "#/$defs/absolutePath" },
+        "apiSymbol": { "$ref": "#/$defs/symbol" },
+        "css": { "$ref": "#/$defs/absolutePath" }
+      }
+    }
+  }
+}