kennel 0.2.5 → 0.2.7

package/README.md

@@ -116,14 +116,17 @@ diagnostics come from the declared schema and Markdown frontmatter. Pass
 list. See [Core folders and metadata indexing](../docs/core-folders.md) for
 patterns, parser support, navigation labels and refresh semantics.
 
-`kennel view` starts the source Vite viewer from a Kennel checkout when no
+`kennel view` starts the source Vite viewer from a Kennel checkout, also when
 external plugins are installed. React and CSS changes use HMR. Changes to
 schema and content files cause a metadata refetch without a full page reload.
-When external plugins are installed, `kennel view` uses the composed static
-kernel so `view`, `pop`, `serve`, default, `core`, and `init` all use the same
-kernel key. `kennel serve` starts the packaged static viewer. The hot viewer
-uses the current directory when no folder is given. It also reuses a Kennel Vite
-server that already runs on the selected port.
+The Vite viewer loads the installed external plugins and reports a
+runtime-independent plugin-set key from `/api/health`. `kennel serve` starts
+the packaged static viewer with its own runtime-specific cache key. The hot
+viewer uses the current directory when no folder is given. It reuses a Kennel Vite
+server on the selected port only when that server has the same kernel key. If
+the plugin set changed, stop the running viewer and run the command again. A
+local Vite viewer can open any local folder; the static viewer is reused only
+for its own root or a folder below it.
 
 `kennel publish init cloudflare` is the exception for deploy wiring: it scaffolds
 a Cloudflare Worker email-code gate for an existing docs workspace by writing

package/dist/cli/src/plugins/external.d.ts

@@ -26,6 +26,9 @@ export declare function readExternalPlugins(): ExternalPluginEntry[];
 export declare function installExternalPlugin(url: string, options?: {
     directory?: string;
 }): Promise<ExternalPluginEntry>;
+/** Identifies the installed plugin set, independent of the Node runtime. */
+export declare function hotKernelKey(plugins?: ExternalPluginEntry[]): string;
+/** Identifies a runtime-specific static kernel cache entry. */
 export declare function kernelKey(plugins?: ExternalPluginEntry[]): string;
 export type ActiveKernel = {
     buildIdentity: string;

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

@@ -163,7 +163,7 @@ function internalSourceAliases(root = kernelSourceRoot()) {
     const aliases = {};
     for (const [name, path] of Object.entries({
         "@raggle-ai/agents": "packages/agents/src",
-        "@raggle-ai/folder-plugin": "packages/folder-plugin/src",
+        "kennel-plugins": "packages/plugins/src",
         "@raggle-ai/kennel-api": "packages/api/src",
         "@raggle-ai/markdown": "packages/markdown/src",
         "@raggle-ai/notes": "packages/notes/src",
@@ -373,21 +373,33 @@ export async function installExternalPlugin(url, options = {}) {
 function cliRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
 }
+function kernelPlugins(plugins) {
+    return plugins.map((plugin) => ({
+        url: plugin.url,
+        requestedRef: plugin.requestedRef ?? null,
+        packageName: plugin.packageName,
+        id: plugin.id,
+        directory: plugin.directory ?? null,
+        commit: plugin.commit,
+        trigger: plugin.trigger,
+        entries: plugin.entries,
+    }));
+}
+/** Identifies the installed plugin set, independent of the Node runtime. */
+export function hotKernelKey(plugins = readExternalPlugins()) {
+    return hash(JSON.stringify({
+        buildIdentity: BUILD_IDENTITY,
+        schema: KENNEL_KERNEL_SCHEMA,
+        plugins: kernelPlugins(plugins),
+    }));
+}
+/** Identifies a runtime-specific static kernel cache entry. */
 export function kernelKey(plugins = readExternalPlugins()) {
     return hash(JSON.stringify({
         buildIdentity: BUILD_IDENTITY,
         schema: KENNEL_KERNEL_SCHEMA,
         runtime: BUILD_RUNTIME,
-        plugins: plugins.map((plugin) => ({
-            url: plugin.url,
-            requestedRef: plugin.requestedRef ?? null,
-            packageName: plugin.packageName,
-            id: plugin.id,
-            directory: plugin.directory ?? null,
-            commit: plugin.commit,
-            trigger: plugin.trigger,
-            entries: plugin.entries,
-        })),
+        plugins: kernelPlugins(plugins),
     }));
 }
 function kernelRoot(key) {
@@ -448,7 +460,7 @@ export async function prepareExternalPluginModules(temp, target = temp, plugins
     const cssImports = plugins.map((plugin) => plugin.entries.css ? `import ${JSON.stringify(plugin.entries.css)};` : "").filter(Boolean).join("\n");
     const clientImports = plugins.map((plugin, index) => `import { ${plugin.entries.manifestSymbol} as manifest${index} } from ${JSON.stringify(plugin.entries.manifest)};`).join("\n");
     const clientItems = plugins.map((plugin, index) => `  { ...manifest${index}, component: lazy(async () => ({ default: (await import(${JSON.stringify(plugin.entries.client)}))[${JSON.stringify(plugin.entries.clientSymbol)}].component })) }`).join(",\n");
-    await writeFile(clientModule, `import { lazy } from "react";\nimport type { FolderPluginClient } from "@raggle-ai/folder-plugin/client";\n${cssImports}\n${clientImports}\nexport const externalFolderPlugins: FolderPluginClient[] = [\n${clientItems}\n];\n`);
+    await writeFile(clientModule, `import { lazy } from "react";\nimport type { FolderPluginClient } from "kennel-plugins/client";\n${cssImports}\n${clientImports}\nexport const externalFolderPlugins: FolderPluginClient[] = [\n${clientItems}\n];\n`);
     const serverEntries = [];
     const apiEntries = [];
     for (const plugin of plugins) {

package/dist/cli/src/site/hot-viewer.js

@@ -7,12 +7,15 @@ import { tmpdir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createKennelClient } from '../core/api-client.js';
+import { hotKernelKey, readExternalPlugins } from '../plugins/external.js';
 function sourceRoot() {
     return resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 }
 async function viewerStatus(url) {
     return createKennelClient({ baseUrl: url }).health({ signal: AbortSignal.timeout(1_000) })
-        .then((body) => body.viewer === 'kennel-vite' || body.viewer === 'kennel-core' ? 'running' : 'other')
+        .then((body) => body.viewer === 'kennel-vite' || body.viewer === 'kennel-core'
+        ? { viewer: body.viewer, kernelKey: body.kernelKey }
+        : 'other')
         .catch((error) => {
         // HTTP rejection means a different service owns the port; connection and
         // timeout failures mean the viewer is unavailable, so startup may retry.
@@ -20,17 +23,17 @@ async function viewerStatus(url) {
             ? 'other' : 'unavailable';
     });
 }
-async function viewerRunning(url, attempts = 1, waitOnOther = false) {
+async function runningViewer(url, attempts = 1, waitOnOther = false) {
     for (let attempt = 0; attempt < attempts; attempt += 1) {
         const status = await viewerStatus(url);
-        if (status === 'running')
-            return true;
+        if (typeof status === 'object')
+            return status;
         if (status === 'other' && !waitOnOther)
-            return false;
+            return undefined;
         if (attempt + 1 < attempts)
             await new Promise((done) => setTimeout(done, 250));
     }
-    return false;
+    return undefined;
 }
 async function portOpen(host, port) {
     return new Promise((done) => {
@@ -132,8 +135,20 @@ export async function hotViewer(options) {
         console.log(`bun ${[...args, ...(options.open ? ['--open', openPath] : [])].join(' ')}`);
         return;
     }
-    const status = await viewerStatus(url);
-    if (status === 'running') {
+    const plugins = readExternalPlugins();
+    // Must match the key apps/web/scripts/dev.mjs gives Vite as KENNEL_KERNEL_KEY.
+    const expectedKey = plugins.length > 0 ? hotKernelKey(plugins) : 'core';
+    // Reuse only a Vite viewer that serves the same plugin set. Anything else on
+    // the port is stale for this kernel and must be restarted, never reused.
+    const reuse = (running) => {
+        const restart = 'Stop that viewer (Ctrl+C in its terminal) and run this command again, or select another port.';
+        if (running.viewer !== 'kennel-vite') {
+            throw new Error(`Port ${options.port} runs the static Kennel viewer, not the hot viewer. ${restart}`);
+        }
+        if (running.kernelKey !== expectedKey) {
+            throw new Error(`The Kennel hot viewer on port ${options.port} uses kernel ${running.kernelKey}, `
+                + `but the installed plugins need kernel ${expectedKey}. ${restart}`);
+        }
         if (options.open) {
             // Do not stack another tab: the viewer is already open. Print the URL
             // so the caller can still get to it deliberately.
@@ -142,21 +157,19 @@ export async function hotViewer(options) {
         else {
             console.log('Kennel hot viewer is already running. Reusing it.');
         }
+    };
+    const status = await viewerStatus(url);
+    if (typeof status === 'object') {
+        reuse(status);
         return;
     }
     if (status === 'other') {
         throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
     }
     if (await portOpen(options.host, options.port)) {
-        if (await viewerRunning(url, 20, true)) {
-            if (options.open) {
-                // Do not stack another tab: the viewer is already open. Print the URL
-                // so the caller can still get to it deliberately.
-                console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-            }
-            else {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-            }
+        const running = await runningViewer(url, 20, true);
+        if (running) {
+            reuse(running);
             return;
         }
         throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
@@ -164,15 +177,9 @@ export async function hotViewer(options) {
     const lock = startupLock(options.host, options.port);
     let token = await acquireLock(lock);
     if (!token) {
-        if (await viewerRunning(url, 40, true)) {
-            if (options.open) {
-                // Do not stack another tab: the viewer is already open. Print the URL
-                // so the caller can still get to it deliberately.
-                console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-            }
-            else {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-            }
+        const running = await runningViewer(url, 40, true);
+        if (running) {
+            reuse(running);
             return;
         }
         await rm(lock, { force: true, recursive: true });
@@ -180,16 +187,10 @@ export async function hotViewer(options) {
     }
     if (!token)
         throw new Error(`Could not acquire the hot viewer startup lock for port ${options.port}.`);
-    if (await viewerRunning(url)) {
+    const running = await runningViewer(url);
+    if (running) {
         await releaseLock(lock, token);
-        if (options.open) {
-            // Do not stack another tab: the viewer is already open. Print the URL
-            // so the caller can still get to it deliberately.
-            console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-        }
-        else {
-            console.log('Kennel hot viewer is already running. Reusing it.');
-        }
+        reuse(running);
         return;
     }
     console.log(`bun ${args.join(' ')}`);
@@ -220,9 +221,15 @@ export async function hotViewer(options) {
                 done();
                 return;
             }
-            if (await viewerRunning(url, 20, true)) {
-                console.log('Kennel hot viewer is already running. Reusing it.');
-                done();
+            const existing = await runningViewer(url, 20, true);
+            if (existing) {
+                try {
+                    reuse(existing);
+                    done();
+                }
+                catch (error) {
+                    fail(error);
+                }
                 return;
             }
             fail(new Error(`Kennel hot viewer stopped with exit code ${code ?? 'unknown'}`));

package/dist/cli/src/site/server-plugins.d.ts

@@ -8,8 +8,8 @@
  * plain-`node` CLI never imports the plugin packages' runtime sources, while
  * staying type-checked against the one source of truth.
  */
-import type { FolderPluginServer } from "@raggle-ai/folder-plugin/server";
-export type { FolderPluginContext, FolderPluginData, FolderPluginDetection, FolderPluginServer, } from "@raggle-ai/folder-plugin/server";
+import type { FolderPluginServer } from "kennel-plugins/server";
+export type { FolderPluginContext, FolderPluginData, FolderPluginDetection, FolderPluginServer, } from "kennel-plugins/server";
 /**
  * Signal a server-side plugin failure (like a mail preview read error) so the
  * host maps it to an HTTP 5xx instead of a not-found. All other thrown errors

package/dist/cli/src/site/viewer.js

@@ -259,17 +259,15 @@ function tailscaleHost() {
 export async function viewer(input) {
     const portExplicit = viewerPortWasExplicit(input);
     const options = splitViewerArgs(input);
-    const { ensureKernel, readExternalPlugins } = await import("../plugins/external.js");
-    const externalPlugins = readExternalPlugins();
-    if (options.hot && externalPlugins.length === 0) {
+    if (options.hot) {
         const { hotViewer } = await import("./hot-viewer.js");
         await hotViewer(options);
         return;
     }
-    if (options.hot && externalPlugins.length > 0) {
-        console.log("Kennel hot viewer is disabled for external plugin kernels; using the composed static kernel.");
-    }
+    const { ensureKernel, hotKernelKey, readExternalPlugins } = await import("../plugins/external.js");
+    const externalPlugins = readExternalPlugins();
     const kernel = await ensureKernel(externalPlugins);
+    const viteKernelKey = externalPlugins.length > 0 ? hotKernelKey(externalPlugins) : "core";
     const web = kernel.webRoot;
     if (!existsSync(resolve(web, "index.html"))) {
         throw new Error(`Kennel web app not found. Run the CLI build first.`);
@@ -298,9 +296,16 @@ export async function viewer(input) {
             .join(",");
     const initialViewerUrl = `http://${options.host}:${options.port}`;
     const existing = await runningViewer(initialViewerUrl);
+    // A local Vite viewer is not root-restricted, so it can open any local
+    // folder. The static kennel-core viewer is root-scoped: reuse it only for
+    // its own root or a descendant.
     if (existing &&
-        existing.kernelKey === kernel.key &&
-        isSameOrDescendant(existing.root, options.root)) {
+        ((existing.viewer === "kennel-vite" &&
+            !remote &&
+            existing.kernelKey === viteKernelKey) ||
+            (existing.viewer !== "kennel-vite" &&
+                existing.kernelKey === kernel.key &&
+                isSameOrDescendant(existing.root, options.root)))) {
         const viewerUrl = popUrl(displayHost, options.port, options);
         console.log(viewerUrl);
         console.log(`Kennel is already running at ${viewerUrl}`);