kennel 0.2.41 → 0.2.43

package/dist/cli/plugin.js

@@ -3,6 +3,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const USAGE = `Usage:
   kennel plugin add <git-repository-url-or-local-path> [--path <subdirectory>] [--install-skill]
+  kennel plugin remove <plugin-id>
   kennel plugin skill install <plugin-id> [--force]
   kennel plugin list
   kennel plugin new <id>`;
@@ -77,6 +78,15 @@ export async function plugin(args) {
             console.log(`Plugin declares skill ${entry.skill.name}; install it with \`kennel plugin skill install ${entry.id}\``);
         return;
     }
+    if (subcommand === 'remove') {
+        const [id] = rest;
+        if (!id || id.startsWith('-') || rest.length !== 1)
+            usageError();
+        const { removeExternalPlugin } = await import('../plugins/external.js');
+        await removeExternalPlugin(id);
+        console.log(`Removed plugin ${id}; source folders, caches, and installed skills were kept.`);
+        return;
+    }
     if (subcommand === 'skill' && rest[0] === 'install') {
         const [, id, ...flags] = rest;
         if (!id || id.startsWith('-') || flags.some((flag) => flag !== '--force'))

package/dist/cli/usage.js

@@ -3,6 +3,7 @@ export function usage() {
   knl core [folder] [--host <host>] [--port <port>] [--api-only] [--web-root <dir>]
   kennel init [path] [--plugin <id>] [--force] [--list]
   kennel plugin add <git-repository-url-or-local-path> [--path <subdirectory>] [--install-skill]
+  kennel plugin remove <plugin-id>
   kennel plugin skill install <plugin-id> [--force]
   kennel plugin list
   kennel plugin new <id>
@@ -37,6 +38,7 @@ Without an interactive terminal, the viewer prints its URL without a menu.
 
 Installed plugin ids are commands, for example knl tasks or knl calendar.
 Plugins can declare extra aliases, for example knl mail for plugin id email.
+Removing a plugin keeps its source folders, caches, and separately installed skills.
 Use --item <id> for a plugin detail view. Built-in commands take priority.
 
 knl llm prints only agent instructions, profiles, and the research write destination.

package/dist/package/preview.js

@@ -242,7 +242,7 @@ function repositoryName(folder) {
     return;
   }
 }
-function previewTerminal(url, target, startShare) {
+function previewTerminal(url, target, startShare, views) {
   url = new URL(url).href;
   const input = process.stdin;
   const output = process.stdout;
@@ -253,8 +253,9 @@ function previewTerminal(url, target, startShare) {
   const repository = interactive ? repositoryName(target.root) : undefined;
   const color = terminal && process.env.NO_COLOR === undefined && output.hasColors();
   const accent = (text) => color ? `\x1B[32m${text}\x1B[39m` : text;
-  const link = (label) => terminal ? `\x1B]8;;${url}\x1B\\${accent(label)}\x1B]8;;\x1B\\` : `${label}
-  ${url}`;
+  const linkTo = (label, href, plain = `${label}
+${href}`) => terminal ? `\x1B]8;;${href}\x07${accent(label)}\x1B]8;;\x07` : plain;
+  const link = (label) => linkTo(label, url);
   const wasRaw = Boolean(input.isRaw);
   const wasFlowing = input.readableFlowing === true;
   let resolveClosed;
@@ -271,27 +272,28 @@ function previewTerminal(url, target, startShare) {
       return;
     cursorTo(output, 0, 0);
     clearScreenDown(output);
-    const width = Math.max(1, (output.columns || 80) - 5);
+    const width = Math.max(1, (output.columns || 80) - 1);
     const fit = (text) => {
       const characters = Array.from(terminalText(text));
       return characters.length > width ? characters.slice(0, width - 1).join("") + "…" : characters.join("");
     };
-    const count = Math.max(1, Math.min(8, (output.rows || 24) - 12));
-    const start = Math.max(0, Math.min(selected - Math.floor(count / 2), actions.length - count));
-    const choices = actions.slice(start, start + count).map((item, index) => {
+    const choices = [];
+    actions.forEach((item, index) => {
       const label = fit(item.shortcut ? `[${item.shortcut}] ${item.label}` : item.label);
-      return start + index === selected ? accent(`  › ${label}`) : `    ${label}`;
+      let text = index === selected ? accent(`› ${label}`) : `  ${label}`;
+      if (item.view !== undefined)
+        text = linkTo(text, item.view, accent(text));
+      choices.push(text);
     });
     output.write([
-      `  \x1B[1m${link(fit(title))}\x1B[22m`,
-      ...repository ? [`  ${color ? "\x1B[2m" : ""}${fit(repository)}${color ? "\x1B[22m" : ""}`] : [],
-      ...target.target ? [`  File: ${fit(name)}`] : [],
+      `\x1B[1m${link(fit(title))}\x1B[22m`,
+      ...repository ? [`${color ? "\x1B[2m" : ""}${fit(repository)}${color ? "\x1B[22m" : ""}`] : [],
+      ...target.target ? [`File: ${fit(name)}`] : [],
       "",
       ...choices,
       "",
-      "  ↑ ↓ to move · Enter to choose · Esc or Ctrl+C to exit",
-      ...actions.length > count ? [`  ${selected + 1} / ${actions.length}`] : [],
-      ...status ? ["", `  ${status}`] : [],
+      "↑ ↓ to move · Enter to choose · Esc or Ctrl+C to exit",
+      ...status ? ["", status] : [],
       ""
     ].join(`
 `));
@@ -356,6 +358,10 @@ function previewTerminal(url, target, startShare) {
       resolveClosed();
   };
   const actions = [
+    ...(views ?? []).map((view) => ({ label: view.id, run: () => {
+      openPreview(view.url);
+      status = "Browser open requested.";
+    }, view: view.url })),
     { label: "Open in browser", shortcut: "o", run: () => {
       openPreview(url);
       status = "Browser open requested.";
@@ -415,7 +421,7 @@ function previewTerminal(url, target, startShare) {
     render();
   else
     console.log(`
-  ${link(name)}
+${link(name)}
 `);
   return { close, closed, interactive };
 }

package/dist/plugins/definition.d.ts

@@ -0,0 +1,9 @@
+import type { FolderPluginDefinition, FolderPluginManifest } from "kennel-plugins/types";
+/** Reads metadata only. Discovery must never import plugin code. */
+export declare function readPluginDefinition(path: string): FolderPluginDefinition;
+/** The host's display record has no authoring paths or component bindings. */
+export declare function pluginDisplayManifest(plugin: FolderPluginDefinition): FolderPluginManifest;
+/** Named imports let the compiler reject missing exports without running React. */
+export declare function pluginClientSource(index: string, plugin: FolderPluginDefinition): string;
+/** Compose trusted hooks with JSON metadata; hooks cannot change the identity. */
+export declare function pluginServerSource(server: string, plugin: FolderPluginDefinition): string;

package/dist/plugins/definition.js

@@ -0,0 +1,62 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+const schema = z.fromJSONSchema(JSON.parse(readFileSync(fileURLToPath(import.meta.resolve("kennel-plugins/schema.json")), "utf8")));
+/** Reads metadata only. Discovery must never import plugin code. */
+export function readPluginDefinition(path) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`Cannot read plugin definition ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const result = schema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`Invalid plugin definition ${path}:\n${result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("\n")}`);
+    }
+    const { plugin } = result.data;
+    const paths = plugin.views.map((view) => view.subpath);
+    if (new Set(paths).size !== paths.length || (paths.length > 1 && paths.includes(""))) {
+        throw new Error(`${path}: plugin.views must have unique subpaths; an empty subpath must be the only view`);
+    }
+    return plugin;
+}
+/** The host's display record has no authoring paths or component bindings. */
+export function pluginDisplayManifest(plugin) {
+    const first = plugin.views[0];
+    const icon = first.subpath === "" ? first.icon ?? plugin.icon : plugin.icon;
+    return {
+        id: plugin.id,
+        label: first.subpath === "" ? first.label : plugin.label,
+        ...(icon ? { icon } : {}),
+        ...(first.subpath === "" ? {} : {
+            views: plugin.views.map(({ component: _component, ...view }) => view),
+        }),
+    };
+}
+/** Named imports let the compiler reject missing exports without running React. */
+export function pluginClientSource(index, plugin) {
+    return `import { createElement } from "react";
+import { ${plugin.views.map((view, i) => `${view.component} as Page${i}`).join(", ")} } from ${JSON.stringify(index)};
+const views = [${plugin.views.map((view, i) => `{ subpath: ${JSON.stringify(view.subpath)}, component: Page${i} }`).join(", ")}];
+function PluginPage(props) {
+  const route = props.subpath.split("?")[0];
+  const view = route ? views.find((view) => view.subpath === "" || view.subpath === route.split("/")[0]) : views[0];
+  return view
+    ? createElement(view.component, { ...props, key: props.folderId + ":" + props.subpath })
+    : createElement("p", { role: "alert" }, "That plugin view does not exist.");
+}
+export default { component: PluginPage };
+`;
+}
+/** Compose trusted hooks with JSON metadata; hooks cannot change the identity. */
+export function pluginServerSource(server, plugin) {
+    return `import entry from ${JSON.stringify(server)};
+const manifest = ${JSON.stringify(pluginDisplayManifest(plugin))};
+export default (...args) => {
+  const hooks = typeof entry === "function" ? entry(...args) : entry;
+  return { ...hooks, ...manifest, icon: manifest.icon, views: manifest.views };
+};
+`;
+}

package/dist/plugins/external.d.ts

@@ -10,9 +10,9 @@ export type ExternalPluginEntry = {
     path?: string;
     trigger?: string;
     entries: {
-        client: string;
+        index: string;
         server: string;
-        manifest: string;
+        definition: string;
         api?: string;
         css?: string;
     };
@@ -25,6 +25,11 @@ export type ExternalPluginEntry = {
             digest: string;
         };
     };
+    /** Manifest-declared subviews, recorded at install time. */
+    views?: {
+        subpath: string;
+        label: string;
+    }[];
 };
 export declare function kennelConfigPath(): string;
 export declare const PLUGIN_SOURCE_IGNORED: Set<string>;
@@ -35,6 +40,7 @@ export declare function readExternalPlugins(): ExternalPluginEntry[];
 export declare function installExternalPlugin(url: string, options?: {
     directory?: string;
 }): Promise<ExternalPluginEntry>;
+export declare function removeExternalPlugin(id: string): Promise<void>;
 /** Installs a declared skill from local source or the pinned cached checkout. */
 export declare function installPluginSkill(id: string, options?: {
     force?: boolean;

package/dist/plugins/external.js

@@ -15,8 +15,8 @@ import { pathToFileURL, fileURLToPath } from "node:url";
 import { spawnSync } from "node:child_process";
 import { z } from "zod";
 import { duplicateSkills, readPluginSkill, skillDestination, skillState, writeSkill } from "./skills.js";
+import { readPluginDefinition, pluginDisplayManifest, pluginClientSource, pluginServerSource } from "./definition.js";
 const CONFIG_FILE = join("kennel", "config.json");
-const VALID_ID = /^[a-z][a-z0-9-]*$/u;
 const CORE_IDS = new Set(["agents", "notes"]);
 function xdgConfigHome() {
     return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
@@ -162,7 +162,7 @@ function pluginRoot(repoRoot, directory) {
         return repoRoot;
     if (isAbsolute(directory) || directory.includes("\0"))
         throw new Error(`Unsafe plugin directory: ${directory}`);
-    const target = resolve(repoRoot, directory);
+    const target = realpathSync(resolve(repoRoot, directory));
     const rel = relative(repoRoot, target);
     if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
         throw new Error(`Unsafe plugin directory: ${directory}`);
@@ -179,9 +179,11 @@ function installPluginDependencies(root, dependencies) {
 function safeRelativeFile(root, value, label) {
     if (typeof value !== "string" || !value.trim())
         throw new Error(`Missing ${label}`);
-    if (isAbsolute(value) || value.includes("\0"))
+    if (isAbsolute(value) || value.includes("\0") || value.includes("\\") || /^[a-z][a-z0-9+.-]*:/iu.test(value) || value.split("/").includes(".."))
         throw new Error(`Unsafe ${label}: ${value}`);
-    const target = resolve(root, value);
+    if (!existsSync(resolve(root, value)))
+        throw new Error(`Missing ${label}: ${value}`);
+    const target = realpathSync(resolve(root, value));
     const rel = relative(root, target);
     if (rel === "" || rel.startsWith("..") || isAbsolute(rel))
         throw new Error(`Unsafe ${label}: ${value}`);
@@ -189,16 +191,11 @@ function safeRelativeFile(root, value, label) {
         throw new Error(`Missing ${label}: ${value}`);
     return target;
 }
-function entryByConvention(root, file, required) {
-    const rootCandidate = join(root, file);
-    const srcCandidate = join(root, "src", file);
-    if (existsSync(rootCandidate) && statSync(rootCandidate).isFile())
-        return rootCandidate;
-    if (existsSync(srcCandidate) && statSync(srcCandidate).isFile())
-        return srcCandidate;
-    if (!required)
-        return undefined;
-    throw new Error(`Missing required plugin entry ${file} (expected ${file} or src/${file})`);
+function pluginDefinition(entry) {
+    const definition = readPluginDefinition(entry.entries.definition);
+    if (definition.id !== entry.id)
+        throw new Error(`Plugin definition id changed: reinstall ${entry.id}`);
+    return definition;
 }
 // Generated files do not change the plugin source or trigger development rebuilds.
 export const PLUGIN_SOURCE_IGNORED = new Set([".git", "node_modules", ".cache", ".turbo", "dist", "coverage"]);
@@ -225,11 +222,6 @@ function contentHash(root) {
     visit(root);
     return digest.digest("hex");
 }
-function stringField(value, label) {
-    if (typeof value !== "string" || !value.trim())
-        throw new Error(`Missing ${label}`);
-    return value.trim();
-}
 // Specifiers the host shares with plugin browser bundles at runtime. Keep in
 // sync with pluginHostModules in apps/web/src/plugin-host-modules.ts and
 // apps/desktop/src/renderer/plugin-host-modules.ts.
@@ -298,14 +290,16 @@ module.exports = host.modules[${JSON.stringify(args.path)}];`,
         },
     };
 }
-async function bundleForImport(entry, outfile, platform) {
+async function bundleForImport(entry, outfile, platform, contents) {
     const esbuild = await import("esbuild");
     await esbuild.build({
         banner: platform === "node"
             ? { js: 'import { createRequire as __kennelCreateRequire } from "node:module"; const require = __kennelCreateRequire(import.meta.url);' }
             : undefined,
         bundle: true,
-        entryPoints: [entry],
+        ...(contents === undefined ? { entryPoints: [entry] } : {
+            stdin: { contents, loader: "js", resolveDir: dirname(entry), sourcefile: "kennel-adapter.js" },
+        }),
         external: ["bun:ffi", "koffi"],
         format: "esm",
         jsx: "automatic",
@@ -318,56 +312,27 @@ async function bundleForImport(entry, outfile, platform) {
         target: platform === "node" ? "node20" : "es2022",
     });
 }
-function assertManifest(value, id, label) {
-    if (!value || typeof value !== "object")
-        throw new Error(`${label} is not an object`);
-    if (value.id !== id)
-        throw new Error(`${label} id mismatch`);
-    if (typeof value.label !== "string" || !value.label.trim())
-        throw new Error(`${label} missing label`);
-    if (value.views !== undefined) {
-        if (!Array.isArray(value.views) || value.views.length === 0)
-            throw new Error(`${label} views must be a nonempty array`);
-        const paths = new Set();
-        for (const view of value.views) {
-            if (!view || typeof view.subpath !== "string" || !VALID_ID.test(view.subpath) ||
-                typeof view.label !== "string" || !view.label.trim() || paths.has(view.subpath)) {
-                throw new Error(`${label} views need unique route segments and labels`);
-            }
-            paths.add(view.subpath);
-        }
-    }
-}
 async function validateImports(entry) {
     const dir = await mkdtemp(join(tmpdir(), "kennel-plugin-validate-"));
     try {
-        const manifestOut = join(dir, "manifest.mjs");
+        const definition = pluginDefinition(entry);
         const serverOut = join(dir, "server.mjs");
-        const clientOut = join(dir, "client.mjs");
         const apiOut = join(dir, "api.mjs");
-        await bundleForImport(entry.entries.manifest, manifestOut, "browser");
         await bundleForImport(entry.entries.server, serverOut, "node");
-        await bundleForImport(entry.entries.client, clientOut, "node");
+        await bundleForImport(entry.entries.index, join(dir, "client.mjs"), "browser", pluginClientSource(entry.entries.index, definition));
         if (entry.entries.api)
             await bundleForImport(entry.entries.api, apiOut, "node");
-        const manifestModule = await import(__rewriteRelativeImportExtension(pathToFileURL(manifestOut).href));
         const serverModule = await import(__rewriteRelativeImportExtension(pathToFileURL(serverOut).href));
-        const clientModule = await import(__rewriteRelativeImportExtension(pathToFileURL(clientOut).href));
-        const manifest = manifestModule.default;
         const serverExport = serverModule.default;
         const server = typeof serverExport === "function" ? serverExport({}) : serverExport;
-        const client = clientModule.default;
-        assertManifest(manifest, entry.id, "manifest export");
-        if (!server || typeof server !== "object" || server.id !== entry.id)
-            throw new Error("server id mismatch");
+        if (!server || typeof server !== "object")
+            throw new Error("server default export must provide hooks or a hook factory");
         if (typeof server.detect !== "function" || typeof server.handle !== "function")
             throw new Error("server export missing detect/handle");
-        if (server.llm !== undefined && typeof server.llm !== "function")
-            throw new Error("server export llm hook must be a function");
-        if (!client || typeof client !== "object" || client.id !== entry.id)
-            throw new Error("client id mismatch");
-        if (typeof client.component !== "function")
-            throw new Error("client export missing component");
+        for (const hook of ["init", "llm"]) {
+            if (server[hook] !== undefined && typeof server[hook] !== "function")
+                throw new Error(`server export ${hook} hook must be a function`);
+        }
         if (entry.entries.api) {
             const apiModule = await import(__rewriteRelativeImportExtension(pathToFileURL(apiOut).href));
             if (typeof apiModule.default !== "function")
@@ -386,40 +351,18 @@ export async function validateExternalPlugin(inputUrl, options = {}) {
     const root = pluginRoot(checkoutRoot, directory);
     const pkgPath = join(root, "package.json");
     const pkg = existsSync(pkgPath) ? JSON.parse(await readFile(pkgPath, "utf8")) : {};
-    const metadataPath = join(root, "kennel.plugin.json");
-    const fileMetadata = existsSync(metadataPath)
-        ? JSON.parse(await readFile(metadataPath, "utf8"))
-        : undefined;
-    const metadata = (pkg.kennel?.plugin && typeof pkg.kennel.plugin === "object"
-        ? pkg.kennel.plugin
-        : fileMetadata && typeof fileMetadata === "object"
-            ? fileMetadata
-            : undefined);
-    const id = metadata?.id === undefined ? basename(root) : stringField(metadata.id, "plugin id");
-    if (!VALID_ID.test(id))
-        throw new Error(`Invalid plugin id: ${id}`);
+    const definition = safeRelativeFile(root, "kennel.json", "plugin definition");
+    const metadata = readPluginDefinition(definition);
+    const { id, aliases, trigger } = metadata;
     if (CORE_IDS.has(id))
         throw new Error(`External plugin id collides with core plugin: ${id}`);
     const packageName = typeof pkg.name === "string" && pkg.name.trim() ? pkg.name.trim() : id;
-    let aliases;
-    if (metadata?.aliases !== undefined) {
-        if (!Array.isArray(metadata.aliases))
-            throw new Error("Plugin aliases must be an array of command names");
-        aliases = metadata.aliases.map((alias) => stringField(alias, "plugin alias"));
-        if (aliases.some((alias) => !VALID_ID.test(alias)) || new Set(aliases).size !== aliases.length) {
-            throw new Error("Plugin aliases must be unique lowercase command names");
-        }
-    }
-    const trigger = metadata?.trigger === undefined ? undefined : stringField(metadata.trigger, "trigger file");
-    if (trigger && (trigger.includes("/") || trigger.includes("\\") || trigger === "." || trigger === ".."))
-        throw new Error(`Invalid trigger file: ${trigger}`);
-    const client = entryByConvention(root, "client.tsx", true);
-    const server = entryByConvention(root, "server.ts", true);
-    const manifest = entryByConvention(root, "manifest.ts", true);
-    const api = entryByConvention(root, "api.ts", false);
-    const cssValue = metadata?.exports?.css;
-    const css = cssValue === undefined ? undefined : safeRelativeFile(root, cssValue, "css export path");
-    const skill = metadata?.skill === undefined ? undefined : readPluginSkill(root, metadata.skill);
+    const index = safeRelativeFile(root, "src/index.ts", "browser entry");
+    const server = safeRelativeFile(root, "src/server.ts", "server entry");
+    const api = existsSync(join(root, "src/api.ts")) ? safeRelativeFile(root, "src/api.ts", "API entry") : undefined;
+    const css = metadata.css === undefined ? undefined : safeRelativeFile(root, metadata.css, "css export path");
+    const skill = metadata.skill === undefined ? undefined : readPluginSkill(root, metadata.skill);
+    const views = pluginDisplayManifest(metadata).views?.map(({ subpath, label }) => ({ subpath, label }));
     const entry = {
         url: source.url,
         ...(source.requestedRef ? { requestedRef: source.requestedRef } : {}),
@@ -431,13 +374,14 @@ export async function validateExternalPlugin(inputUrl, options = {}) {
         ...(source.path ? { path: source.path } : {}),
         ...(trigger ? { trigger } : {}),
         entries: {
-            client,
+            index,
             server,
-            manifest,
+            definition,
             ...(api ? { api } : {}),
             ...(css ? { css } : {}),
         },
         ...(skill ? { skill: { entry: skill.entry, name: skill.name } } : {}),
+        ...(views ? { views } : {}),
     };
     installPluginDependencies(root, pkg.dependencies);
     await validateImports(entry);
@@ -470,6 +414,18 @@ export async function installExternalPlugin(url, options = {}) {
     }
     return entry;
 }
+export async function removeExternalPlugin(id) {
+    const path = kennelConfigPath();
+    const config = readJson(path);
+    const plugins = config.externalPlugins ?? [];
+    if (!plugins.some((plugin) => plugin.id === id))
+        throw new Error(`No installed plugin with id ${id}`);
+    const externalPlugins = plugins.filter((plugin) => plugin.id !== id);
+    const nextConfig = { ...config, externalPlugins };
+    assertUserConfig(nextConfig, path);
+    await ensurePluginBuild(externalPlugins);
+    writeJsonAtomic(path, nextConfig);
+}
 /** Uses local source or checks out the pinned cached commit without fetching. */
 function pinnedPackageRoot(plugin) {
     if (plugin.path)
@@ -491,7 +447,7 @@ export function installPluginSkill(id, options = {}) {
     if (!plugin)
         throw new Error(`No installed plugin with id ${id}`);
     if (!plugin.skill)
-        throw new Error(`Plugin ${id} declares no skill (kennel.plugin.skill or kennel.plugin.json > skill)`);
+        throw new Error(`Plugin ${id} declares no skill (kennel.json > plugin.skill)`);
     const skill = readPluginSkill(pinnedPackageRoot(plugin), plugin.skill.entry);
     if (skill.name !== plugin.skill.name)
         throw new Error(`Pinned skill name ${skill.name} does not match recorded name ${plugin.skill.name}`);
@@ -529,7 +485,7 @@ function cliRoot() {
 export function webRoot() {
     return resolve(cliRoot(), "web");
 }
-const BUILD_IDENTITY = "kennel-external-plugins-v1";
+const BUILD_IDENTITY = "kennel-json-plugins-v2";
 function cliVersion() {
     return JSON.parse(readFileSync(join(cliRoot(), "package.json"), "utf8")).version;
 }
@@ -633,7 +589,7 @@ async function buildPluginStyles(plugin, outdir, theme) {
         import("@tailwindcss/oxide"),
         import("esbuild"),
     ]);
-    const source = dirname(plugin.entries.client);
+    const source = dirname(plugin.entries.index);
     const input = [
         '@import "tailwindcss/theme.css" layer(theme);',
         `@import ${JSON.stringify(theme)};`,
@@ -713,8 +669,13 @@ async function buildPluginClient(plugin, outdir) {
         bundle: true,
         chunkNames: "chunks/[name]-[hash]",
         define: { "process.env.NODE_ENV": '"production"' },
-        entryNames: "[name]",
-        entryPoints: { client: plugin.entries.client },
+        entryNames: "client",
+        stdin: {
+            contents: pluginClientSource(plugin.entries.index, pluginDefinition(plugin)),
+            loader: "js",
+            resolveDir: dirname(plugin.entries.index),
+            sourcefile: "client.js",
+        },
         format: "esm",
         jsx: "automatic",
         loader: ASSET_LOADERS,
@@ -731,12 +692,6 @@ async function buildPluginClient(plugin, outdir) {
     const output = Object.entries(result.metafile.outputs).find(([, value]) => value.entryPoint)?.[1];
     return output?.cssBundle ? [relative(outdir, resolve(output.cssBundle))] : [];
 }
-async function pluginManifest(plugin, outfile) {
-    await bundleForImport(plugin.entries.manifest, outfile, "browser");
-    const manifest = (await import(__rewriteRelativeImportExtension(pathToFileURL(outfile).href))).default;
-    assertManifest(manifest, plugin.id, "manifest export");
-    return JSON.parse(JSON.stringify(manifest));
-}
 async function buildPlugins(temp, target, key, plugins, theme) {
     const serverEntries = [];
     const apiEntries = [];
@@ -746,11 +701,11 @@ async function buildPlugins(temp, target, key, plugins, theme) {
         const clientStyles = await buildPluginClient(plugin, clientDir);
         const styles = [await buildPluginStyles(plugin, clientDir, theme), ...clientStyles];
         registry.push({
-            manifest: await pluginManifest(plugin, join(temp, "manifest", `${plugin.id}.js`)),
+            manifest: pluginDisplayManifest(pluginDefinition(plugin)),
             module: `/_kennel/plugins/${plugin.id}/client.js`,
             styles: styles.map((style) => `/_kennel/plugins/${plugin.id}/${style}`),
         });
-        await bundleForImport(plugin.entries.server, join(temp, "server", `${plugin.id}.js`), "node");
+        await bundleForImport(plugin.entries.server, join(temp, "server", `${plugin.id}.js`), "node", pluginServerSource(plugin.entries.server, pluginDefinition(plugin)));
         serverEntries.push({ id: plugin.id, module: join(target, "server", `${plugin.id}.js`), symbol: "default", trigger: plugin.trigger });
         if (plugin.entries.api) {
             await bundleForImport(plugin.entries.api, join(temp, "server", `${plugin.id}-api.js`), "node");

package/dist/plugins/skills.d.ts

@@ -8,7 +8,7 @@ export type SkillState = "missing" | "installed" | "conflict";
 export declare function agentSkillsRoot(): string;
 export declare function skillDestination(name: string): string;
 /**
- * Resolves `package.json > kennel.plugin.skill` inside a plugin package root.
+ * Resolves `kennel.json > plugin.skill` inside a plugin package root.
  * The entry must be a contained, non-symlinked `SKILL.md` with a valid name and description.
  */
 export declare function readPluginSkill(packageRoot: string, entry: unknown): PluginSkill;

package/dist/plugins/skills.js

@@ -38,12 +38,12 @@ function frontmatter(path) {
     return data;
 }
 /**
- * Resolves `package.json > kennel.plugin.skill` inside a plugin package root.
+ * Resolves `kennel.json > plugin.skill` inside a plugin package root.
  * The entry must be a contained, non-symlinked `SKILL.md` with a valid name and description.
  */
 export function readPluginSkill(packageRoot, entry) {
     if (typeof entry !== "string" || !entry.trim())
-        throw new Error("kennel.plugin.skill must be a relative path to SKILL.md");
+        throw new Error("kennel.json > plugin.skill must be a relative path to SKILL.md");
     if (isAbsolute(entry) || entry.includes("\0") || entry.includes("\\"))
         throw new Error(`Unsafe skill path: ${entry}`);
     if (basename(entry) !== "SKILL.md")

package/dist/site/hot-viewer.js

@@ -6,7 +6,7 @@ import { createConnection } from 'node:net';
 import { tmpdir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { popUrl } from './viewer.js';
+import { popUrl, pluginViewLinks } from './viewer.js';
 import { createKennelClient } from '../core/api-client.js';
 import { pluginSetKey } from '../plugins/external.js';
 import { openPreview, previewTerminal } from './terminal.js';
@@ -179,7 +179,7 @@ export async function hotViewer(options, restarting = false) {
                 return hotViewer(options, true);
             throw new Error(stale);
         }
-        const terminal = previewTerminal(viewerUrl, options);
+        const terminal = previewTerminal(viewerUrl, options, pluginViewLinks(viewerUrl, options.root));
         if (options.open)
             openPreview(viewerUrl);
         try {
@@ -245,7 +245,7 @@ export async function hotViewer(options, restarting = false) {
         },
         stdio: ['ignore', 'inherit', 'inherit'],
     });
-    const terminal = previewTerminal(viewerUrl, options);
+    const terminal = previewTerminal(viewerUrl, options, pluginViewLinks(viewerUrl, options.root));
     void terminal.closed.then(() => {
         if (child.exitCode === null && child.signalCode === null)
             child.kill('SIGTERM');

package/dist/site/terminal.d.ts

@@ -1,8 +1,13 @@
 export { openPreview } from "kennel-preview/terminal";
+/** Extra list entries rendered as hyperlinked plugin view links. */
+export type PluginView = {
+    id: string;
+    url: string;
+};
 export declare function previewTerminal(url: string, target: {
     root: string;
     target?: string;
-}): {
+}, views: PluginView[]): {
     close: () => void;
     closed: Promise<void>;
     interactive: boolean;

package/dist/site/terminal.js

@@ -31,7 +31,7 @@ function repositoryName(folder) {
     return;
   }
 }
-function previewTerminal(url, target, startShare) {
+function previewTerminal(url, target, startShare, views) {
   url = new URL(url).href;
   const input = process.stdin;
   const output = process.stdout;
@@ -42,8 +42,9 @@ function previewTerminal(url, target, startShare) {
   const repository = interactive ? repositoryName(target.root) : undefined;
   const color = terminal && process.env.NO_COLOR === undefined && output.hasColors();
   const accent = (text) => color ? `\x1B[32m${text}\x1B[39m` : text;
-  const link = (label) => terminal ? `\x1B]8;;${url}\x1B\\${accent(label)}\x1B]8;;\x1B\\` : `${label}
-  ${url}`;
+  const linkTo = (label, href, plain = `${label}
+${href}`) => terminal ? `\x1B]8;;${href}\x07${accent(label)}\x1B]8;;\x07` : plain;
+  const link = (label) => linkTo(label, url);
   const wasRaw = Boolean(input.isRaw);
   const wasFlowing = input.readableFlowing === true;
   let resolveClosed;
@@ -60,27 +61,28 @@ function previewTerminal(url, target, startShare) {
       return;
     cursorTo(output, 0, 0);
     clearScreenDown(output);
-    const width = Math.max(1, (output.columns || 80) - 5);
+    const width = Math.max(1, (output.columns || 80) - 1);
     const fit = (text) => {
       const characters = Array.from(terminalText(text));
       return characters.length > width ? characters.slice(0, width - 1).join("") + "…" : characters.join("");
     };
-    const count = Math.max(1, Math.min(8, (output.rows || 24) - 12));
-    const start = Math.max(0, Math.min(selected - Math.floor(count / 2), actions.length - count));
-    const choices = actions.slice(start, start + count).map((item, index) => {
+    const choices = [];
+    actions.forEach((item, index) => {
       const label = fit(item.shortcut ? `[${item.shortcut}] ${item.label}` : item.label);
-      return start + index === selected ? accent(`  › ${label}`) : `    ${label}`;
+      let text = index === selected ? accent(`› ${label}`) : `  ${label}`;
+      if (item.view !== undefined)
+        text = linkTo(text, item.view, accent(text));
+      choices.push(text);
     });
     output.write([
-      `  \x1B[1m${link(fit(title))}\x1B[22m`,
-      ...repository ? [`  ${color ? "\x1B[2m" : ""}${fit(repository)}${color ? "\x1B[22m" : ""}`] : [],
-      ...target.target ? [`  File: ${fit(name)}`] : [],
+      `\x1B[1m${link(fit(title))}\x1B[22m`,
+      ...repository ? [`${color ? "\x1B[2m" : ""}${fit(repository)}${color ? "\x1B[22m" : ""}`] : [],
+      ...target.target ? [`File: ${fit(name)}`] : [],
       "",
       ...choices,
       "",
-      "  ↑ ↓ to move · Enter to choose · Esc or Ctrl+C to exit",
-      ...actions.length > count ? [`  ${selected + 1} / ${actions.length}`] : [],
-      ...status ? ["", `  ${status}`] : [],
+      "↑ ↓ to move · Enter to choose · Esc or Ctrl+C to exit",
+      ...status ? ["", status] : [],
       ""
     ].join(`
 `));
@@ -145,6 +147,10 @@ function previewTerminal(url, target, startShare) {
       resolveClosed();
   };
   const actions = [
+    ...(views ?? []).map((view) => ({ label: view.id, run: () => {
+      openPreview(view.url);
+      status = "Browser open requested.";
+    }, view: view.url })),
     { label: "Open in browser", shortcut: "o", run: () => {
       openPreview(url);
       status = "Browser open requested.";
@@ -204,17 +210,17 @@ function previewTerminal(url, target, startShare) {
     render();
   else
     console.log(`
-  ${link(name)}
+${link(name)}
 `);
   return { close, closed, interactive };
 }
 
 // packages/cli/src/site/terminal.ts
-function previewTerminal2(url, target) {
+function previewTerminal2(url, target, views) {
   return previewTerminal(url, target, async (password = false) => {
     const { startPreviewShare } = await import(new URL("../package/preview.js", import.meta.url).href);
     return startPreviewShare({ ...target, ...password ? { password: true } : {} });
-  });
+  }, views);
 }
 export {
   openPreview,

package/dist/site/viewer.d.ts

@@ -1,3 +1,6 @@
+import { type PluginView } from "./terminal.js";
+/** Installed-plugin view links for the terminal menu; each is hyperlinked. */
+export declare function pluginViewLinks(viewerUrl: string, root: string): PluginView[];
 export type ViewerOptions = {
     dryRun: boolean;
     host: string;

package/dist/site/viewer.js

@@ -2,8 +2,25 @@ import { execFileSync } from "node:child_process";
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { createServer } from "node:net";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { readExternalPlugins } from "../plugins/external.js";
 import { previewKind } from "./kinds.js";
 import { openPreview, previewTerminal } from "./terminal.js";
+/** Installed-plugin view links for the terminal menu; each is hyperlinked. */
+export function pluginViewLinks(viewerUrl, root) {
+    return readExternalPlugins().flatMap((plugin) => {
+        const view = (subpath) => {
+            const url = new URL(viewerUrl);
+            url.pathname = `/folder/${encodeBase64Url(root)}/views/${encodeURIComponent(plugin.id)}${subpath ? `/${encodeURIComponent(subpath)}` : ""}`;
+            // A query `folder` makes the route parser ignore the path and select Notes.
+            url.searchParams.delete("folder");
+            return url.href;
+        };
+        const views = [{ id: plugin.id, url: view() }];
+        for (const item of plugin.views ?? [])
+            views.push({ id: `${plugin.id} · ${item.label}`, url: view(item.subpath) });
+        return views;
+    });
+}
 export function viewerFolder(root, value) {
     return resolve(value ?? root);
 }
@@ -312,7 +329,7 @@ export async function viewer(input, plugin) {
                 existing.kernelKey === plugins.key &&
                 isSameOrDescendant(existing.root, options.root)))) {
         const viewerUrl = popUrl(displayHost, options.port, options);
-        const terminal = previewTerminal(viewerUrl, options);
+        const terminal = previewTerminal(viewerUrl, options, pluginViewLinks(viewerUrl, options.root));
         if (options.open)
             openPreview(viewerUrl);
         try {
@@ -342,7 +359,7 @@ export async function viewer(input, plugin) {
             execFileSync("tailscale", ["serve", "--bg", "--yes", options.port]);
         }
         const viewerUrl = popUrl(displayHost, options.port, options);
-        const terminal = previewTerminal(viewerUrl, options);
+        const terminal = previewTerminal(viewerUrl, options, pluginViewLinks(viewerUrl, options.root));
         if (options.open)
             openPreview(viewerUrl);
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kennel",
-  "version": "0.2.41",
+  "version": "0.2.43",
   "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",
@@ -69,7 +69,7 @@
     "effect": "^3.19.7",
     "esbuild": "^0.27.0",
     "kennel-mcp": "https://registry.npmjs.org/%40raggle-ai%2fkennel-mcp/-/kennel-mcp-0.1.8.tgz",
-    "kennel-plugins": "0.1.20",
+    "kennel-plugins": "0.1.21",
     "koffi": "^3.3.1",
     "lucide-react": "^0.562.0",
     "radix-ui": "^1.6.7",

package/schemas/config.schema.json

@@ -100,6 +100,20 @@
           "pattern": "^(?!\\.{1,2}$)[^/\\\\]+$"
         },
         "skill": { "$ref": "#/$defs/pluginSkill" },
+        "views": {
+          "description": "Undirected views declared by the plugin manifest, recorded at install time.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["subpath", "label"],
+            "properties": {
+              "subpath": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+              "label": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
         "entries": {
           "description": "Resolved absolute convention entry files. api is optional.",
           "oneOf": [
@@ -110,7 +124,7 @@
       }
     },
     "pluginSkill": {
-      "description": "Agent skill declared by package.json > kennel.plugin.skill or kennel.plugin.json > skill. Managed by `kennel plugin add` and `kennel plugin skill install`.",
+      "description": "Agent skill declared by kennel.json > plugin.skill. Managed by `kennel plugin add` and `kennel plugin skill install`.",
       "type": "object",
       "additionalProperties": false,
       "required": ["entry", "name"],
@@ -141,22 +155,22 @@
     "entriesWithoutApi": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["client", "server", "manifest"],
+      "required": ["index", "server", "definition"],
       "properties": {
-        "client": { "$ref": "#/$defs/absolutePath" },
+        "index": { "$ref": "#/$defs/absolutePath" },
         "server": { "$ref": "#/$defs/absolutePath" },
-        "manifest": { "$ref": "#/$defs/absolutePath" },
+        "definition": { "$ref": "#/$defs/absolutePath" },
         "css": { "$ref": "#/$defs/absolutePath" }
       }
     },
     "entriesWithApi": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["client", "server", "manifest", "api"],
+      "required": ["index", "server", "definition", "api"],
       "properties": {
-        "client": { "$ref": "#/$defs/absolutePath" },
+        "index": { "$ref": "#/$defs/absolutePath" },
         "server": { "$ref": "#/$defs/absolutePath" },
-        "manifest": { "$ref": "#/$defs/absolutePath" },
+        "definition": { "$ref": "#/$defs/absolutePath" },
         "api": { "$ref": "#/$defs/absolutePath" },
         "css": { "$ref": "#/$defs/absolutePath" }
       }

package/templates/plugin/kennel.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://raggle.co/kennel/plugin.json",
+  "plugin": {
+    "id": "__PLUGIN_ID__",
+    "label": "__PLUGIN_ID__",
+    "views": [
+      {
+        "subpath": "",
+        "label": "__PLUGIN_ID__",
+        "component": "PluginPage"
+      }
+    ]
+  }
+}

package/templates/plugin/src/index.ts

@@ -0,0 +1 @@
+export { PluginPage } from "./page.tsx";

package/templates/plugin/src/page.tsx

@@ -0,0 +1,5 @@
+import type { FolderPluginViewProps } from "kennel-plugins/client";
+
+export function PluginPage(_props: FolderPluginViewProps) {
+  return <p>__PLUGIN_ID__ plugin</p>;
+}

package/templates/plugin/{server.ts → src/server.ts}

@@ -1,8 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import type { FolderPluginServer } from "kennel-plugins/server";
-
-import manifest from "./manifest";
+import type { FolderPluginServerHooks } from "kennel-plugins/server";
 
 // Example content file read by the `llm` hook below: a JSON array of items
 // with a string `title`, for example [{ "title": "First item" }].
@@ -25,12 +23,11 @@ async function readItems(folder: string) {
 }
 
 export default {
-  ...manifest,
   async detect() {
     return { status: "available" };
   },
   async handle() {
-    return { data: { items: [] } };
+    return { kind: "available", data: { items: [] } };
   },
   // Optional `knl llm` context. Read only: no writes, network calls, or other
   // side effects. Return [] when the folder has no content for this plugin.

package/templates/plugin/tsconfig.json

@@ -7,5 +7,5 @@
     "target": "ES2022",
     "types": ["node"]
   },
-  "include": ["*.ts", "*.tsx"]
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
 }

package/templates/plugin/client.tsx

@@ -1,12 +0,0 @@
-import type { FolderPluginClient } from "kennel-plugins/client";
-
-import manifest from "./manifest";
-
-function ExamplePluginView() {
-  return <div>{manifest.label} plugin</div>;
-}
-
-export default {
-  ...manifest,
-  component: ExamplePluginView,
-} satisfies FolderPluginClient;

package/templates/plugin/kennel.plugin.json

@@ -1,3 +0,0 @@
-{
-  "id": "__PLUGIN_ID__"
-}

package/templates/plugin/manifest.ts

@@ -1,6 +0,0 @@
-import type { FolderPluginManifest } from "kennel-plugins";
-
-export default {
-  id: "__PLUGIN_ID__",
-  label: "Example",
-} satisfies FolderPluginManifest;