kennel 0.2.8 → 0.2.10

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);