kennel 0.2.21 → 0.2.23

package/README.md

@@ -31,10 +31,12 @@ kennel pop plan.md --watch
 kennel pop artifacts/pricing-card.html --lan
 kennel view /path/to/workspace
 kennel serve /path/to/workspace
+knl tasks /path/to/workspace
+knl mail /path/to/workspace --item draft-id
 kennel dev /path/to/docs-site --config index.json
 kennel init .
-kennel plugin add https://github.com/example/kennel-transcripts-plugin.git#main
-kennel plugin add https://github.com/raggle-ai/kennel-plugins.git --path plugins/calendar
+kennel plugin add https://github.com/<owner>/<plugin-repo>.git#main
+kennel plugin add https://github.com/raggle-ai/kennel-starter-plugins.git --path plugins/calendar
 kennel core-folders .
 kennel mcp generate . --config index.json
 kennel publish init cloudflare .
@@ -44,7 +46,7 @@ kennel dp .
 
 `kennel pop <file>` is the pop-up preview: it starts the static viewer rooted at
 the file's folder, prints a clickable `/folder/<id>/document/<id>` URL, and
-opens it in the default pop-up window. Markdown, HTML artifacts, text, images,
+opens it in the default browser only when `--open` is supplied. Markdown, HTML artifacts, text, images,
 code, CSV/TSV tables, and `.eml` files are recognized by extension; images and
 binary files are served through `/api/raw`. `--watch` makes the pop-up refresh
 on save (the URL carries `?watch=1`). Folder mode (`--lan`/`--tailscale`)
@@ -63,6 +65,30 @@ endpoints (`/api/open-path`, `/api/open-folder`) return 403, ACP sessions are
 disabled, HTML is never streamed inline from `/api/raw`, and mutation POSTs
 require a same-origin `Origin`/`Referer`. The default host stays `127.0.0.1`.
 
+### Terminal output
+
+`knl`, file previews, and plugin commands show a named terminal link:
+
+```text
+(open my-folder)
+
+shortcuts:
+  o - open in browser
+  ctrl+c - exit
+```
+
+The `open my-folder` label is clickable in terminals that support hyperlinks. File previews use the file name instead. Press `o` without Enter to open the printed link in the default browser. Ctrl+C restores the terminal and exits the command; it does not stop a viewer that the command reused.
+
+When output is redirected, Kennel prints the label and full URL without colors, terminal escape codes, or keyboard controls. `--open` still opens the browser explicitly; `--dry-run` remains non-interactive.
+
+### Installed plugins as commands
+
+Every installed plugin ID is a top-level command: `knl tasks`, `knl calendar`, or `knl flights`. The current folder is used unless you pass another folder. Add `--item <id>` to select a plugin-owned detail view.
+
+Plugins can declare optional `aliases` in `package.json > kennel.plugin` or `kennel.plugin.json`. The `kennel-email` package uses ID `email` with alias `mail`, so `knl email` and `knl mail` select the same view. Other plugins need no alias declaration when their ID is already the desired command. Reinstall a plugin after changing aliases.
+
+Built-in commands take priority over plugin IDs; plugin IDs take priority over aliases. Ambiguous aliases are refused. Use `./tasks` rather than `tasks` to open a folder whose name is also a plugin command. Plugin commands use the same viewer startup as other previews, not a plugin-specific server.
+
 ### Localhost convention (one viewer on port 5180)
 
 Kennel can keep one always-running localhost viewer at
@@ -88,8 +114,11 @@ The same user config stores trusted external folder plugins added with
 command pins the requested ref, or `HEAD` with no fragment, to a full commit,
 selects the repository root or the requested subdirectory as the plugin package
 root, validates package metadata and explicit client/server/manifest exports
-plus optional API/CSS exports, compiles the plugin in the XDG cache, and only
-then atomically updates config. Installed plugin imports are derived from
+plus optional API/CSS exports, installs the package's declared production
+`dependencies` with npm (no dev or peer dependencies, no install scripts),
+compiles the plugin in the XDG cache, and only then atomically updates config.
+React, `kennel-plugins` and the other shared viewer packages always come from
+Kennel, so plugins declare them as peers. Installed plugin imports are derived from
 package metadata, not from URL text. The transcripts plugin contract is package
 `kennel-transcripts-plugin`, id `memos`, trigger `memos.json`.
 
@@ -139,7 +168,7 @@ well-known scratch folder across any AI client.
 `kennel init` scaffolds starter content files for installed folder plugins into
 the current folder (or the given path). The external Tasks and Calendar plugins
 provide `todo.json` and `calendar.json` templates after they are installed from
-`raggle-ai/kennel-plugins` with `kennel plugin add ... --path plugins/<id>`.
+`raggle-ai/kennel-starter-plugins` with `kennel plugin add ... --path plugins/<id>`.
 Existing files are left untouched; `--plugin <id>` scaffolds one plugin,
 `--force` overwrites, and `--list` prints what would be created without
 writing.
@@ -151,8 +180,10 @@ 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, also when
-external plugins are installed. React and CSS changes use HMR. Changes to
+In a Kennel checkout, `kennel view` starts the source Vite viewer, also when
+external plugins are installed. An npm install has no source checkout, so
+`kennel view` and `kennel open` start the packaged static viewer, the same as
+`kennel serve`. React and CSS changes use HMR. Changes to
 schema and content files cause a metadata refetch without a full page reload.
 The Vite viewer and the packaged static viewer load the same compiled plugin
 build and report its plugin-set key from `/api/health`. The hot

package/dist/cli/dispatch.js

@@ -97,11 +97,6 @@ export async function dispatch(argv) {
         await viewer(['--hot', ...args]);
         return;
     }
-    if (command === 'mail') {
-        const { mail } = await import('../site/mail.js');
-        await mail(args);
-        return;
-    }
     if (command === 'serve') {
         const { viewer } = await import('../site/viewer.js');
         await viewer(['--static', ...args]);
@@ -155,6 +150,13 @@ export async function dispatch(argv) {
         deploy(args);
         return;
     }
+    // Built-in commands win; use an explicit path (./tasks) to open a folder
+    // whose name is also an installed plugin command.
+    if (/^[a-z][a-z0-9-]*$/u.test(command)) {
+        const { pluginCommand } = await import('../site/plugin.js');
+        if (await pluginCommand(command, args))
+            return;
+    }
     // Positionals that are flags or existing paths still go straight to the
     // viewer (`kennel [folder]`, `kennel note.md`, `kennel --lan .`). Unknown
     // command words fail loudly instead of silently opening a viewer.

package/dist/cli/usage.js

@@ -9,7 +9,7 @@ export function usage() {
   kennel pop|p <file|folder> [--open] [--watch] [--host <host>] [--port <port>] [--lan|--tailscale]
   kennel view [folder] [--host <host>] [--port <port>] [--dry-run]
   kennel open|o [folder] [--open] [--host <host>] [--port <port>] [--dry-run]
-  kennel mail [folder] [--open] [--host <host>] [--port <port>] [--dry-run]
+  knl <plugin-id|alias> [folder] [--item <id>] [--open] [--dry-run]
   kennel serve [folder] [--host <host>] [--port <port>] [--lan|--tailscale]
   kennel share [folder] [--lan|--tailscale] [--port <port>] [--dry-run]
   kennel dev [path] [--config <json-file>] [--port <port>] [--script <script>] [--dry-run] [-- <args...>]
@@ -22,5 +22,9 @@ export function usage() {
   kennel publish vercel [path] [--config <json-file>] [--dry-run] [--force] [--hostname <hostname>] [--skip-test]
   kennel deploy [path] [--config <json-file>] [legacy alias for publish]
   kennel dp [path] [--config <json-file>] [legacy alias for publish]
+
+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.
+Use --item <id> for a plugin detail view. Built-in commands take priority.
 `);
 }

package/dist/package/preview.js

@@ -215,6 +215,81 @@ var init_src = __esm(() => {
   init_kinds();
 });
 
+// packages/preview/src/terminal.ts
+import { execFile } from "node:child_process";
+import { basename } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+function openPreview(url) {
+  const command = process.platform === "darwin" ? "/usr/bin/open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
+  execFile(command, [url], (error) => {
+    if (error)
+      console.error(`Could not open browser: ${error.message}`);
+  });
+}
+function previewTerminal(url, target) {
+  url = new URL(url).href;
+  const input = process.stdin;
+  const output = process.stdout;
+  const terminal = Boolean(output.isTTY && process.env.TERM !== "dumb");
+  const interactive = terminal && Boolean(input.isTTY);
+  const name = (basename(target.target ?? target.root) || target.root).replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+  const label = `(open ${name})`;
+  const color = terminal && process.env.NO_COLOR === undefined && output.hasColors();
+  const accent = (text) => color ? `\x1B[36m${text}\x1B[39m` : text;
+  const link = terminal ? `\x1B]8;;${url}\x1B\\${accent(label)}\x1B]8;;\x1B\\` : `${label}
+  ${url}`;
+  const wasRaw = Boolean(input.isRaw);
+  const wasFlowing = input.readableFlowing === true;
+  let resolveClosed;
+  const closed = new Promise((resolve) => {
+    resolveClosed = resolve;
+  });
+  let finished = false;
+  const close = () => {
+    if (finished)
+      return;
+    finished = true;
+    process.off("SIGINT", close);
+    process.off("SIGTERM", close);
+    process.off("exit", close);
+    if (interactive) {
+      input.off("keypress", keypress);
+      input.off("end", close);
+      input.setRawMode(wasRaw);
+      if (!wasFlowing)
+        input.pause();
+    }
+    resolveClosed();
+  };
+  const keypress = (_text, key) => {
+    if (key.ctrl && (key.name === "c" || key.name === "d"))
+      close();
+    else if (key.name === "o" && !key.ctrl && !key.meta)
+      openPreview(url);
+  };
+  process.once("SIGINT", close);
+  process.once("SIGTERM", close);
+  process.once("exit", close);
+  if (interactive) {
+    emitKeypressEvents(input);
+    input.setRawMode(true);
+    input.on("keypress", keypress);
+    input.once("end", close);
+    input.resume();
+  }
+  console.log(`
+  ${link}
+`);
+  if (interactive) {
+    console.log(`  shortcuts:
+    ${accent("o")} - open in browser
+    ctrl+c - exit
+`);
+  }
+  return { close, closed, interactive };
+}
+var init_terminal = () => {};
+
 // node_modules/.bun/openapi-fetch@0.17.0/node_modules/openapi-fetch/dist/index.mjs
 function randomID() {
   return Math.random().toString(36).slice(2, 11);
@@ -6028,7 +6103,7 @@ var init_src2 = __esm(() => {
 });
 
 // packages/preview/src/hot-viewer.ts
-import { execFile, execFileSync, spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -6138,18 +6213,25 @@ async function hotViewer(options) {
   const displayHost = options.lan ? lanHost() : options.host;
   const viewerHosts = [displayHost, "localhost", "127.0.0.1"].join(",");
   const viewerUrl = `http://${displayHost}:${options.port}${openPath}`;
-  console.log(`Kennel hot viewer: ${viewerUrl}`);
   if (options.dryRun) {
+    console.log(`Kennel hot viewer: ${viewerUrl}`);
     console.log(`bun ${[...args, ...options.open ? ["--open", openPath] : []].join(" ")}`);
     return;
   }
+  const reuse = async () => {
+    const terminal = previewTerminal(viewerUrl, options);
+    if (options.open)
+      openPreview(viewerUrl);
+    try {
+      if (terminal.interactive)
+        await terminal.closed;
+    } finally {
+      terminal.close();
+    }
+  };
   const status = await viewerStatus(url);
   if (status === "running") {
-    if (options.open) {
-      console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-    } else {
-      console.log("Kennel hot viewer is already running. Reusing it.");
-    }
+    await reuse();
     return;
   }
   if (status === "other") {
@@ -6157,11 +6239,7 @@ async function hotViewer(options) {
   }
   if (await portOpen(options.host, options.port)) {
     if (await viewerRunning(url, 20, true)) {
-      if (options.open) {
-        console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-      } else {
-        console.log("Kennel hot viewer is already running. Reusing it.");
-      }
+      await reuse();
       return;
     }
     throw new Error(`Port ${options.port} is used by another service. Stop it or select another port.`);
@@ -6170,11 +6248,7 @@ async function hotViewer(options) {
   let token = await acquireLock(lock);
   if (!token) {
     if (await viewerRunning(url, 40, true)) {
-      if (options.open) {
-        console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-      } else {
-        console.log("Kennel hot viewer is already running. Reusing it.");
-      }
+      await reuse();
       return;
     }
     await rm(lock, { force: true, recursive: true });
@@ -6184,14 +6258,9 @@ async function hotViewer(options) {
     throw new Error(`Could not acquire the hot viewer startup lock for port ${options.port}.`);
   if (await viewerRunning(url)) {
     await releaseLock(lock, token);
-    if (options.open) {
-      console.log(`Kennel hot viewer is already running at ${viewerUrl}`);
-    } else {
-      console.log("Kennel hot viewer is already running. Reusing it.");
-    }
+    await reuse();
     return;
   }
-  console.log(`bun ${args.join(" ")}`);
   if (options.open)
     args.push("--open", openPath);
   const child = spawn("bun", args, {
@@ -6204,7 +6273,12 @@ async function hotViewer(options) {
       ...options.target ? { KENNEL_VIEWER_TARGET: options.target } : {},
       LC_ALL: "en_GB.UTF-8"
     },
-    stdio: "inherit"
+    stdio: ["ignore", "inherit", "inherit"]
+  });
+  const terminal = previewTerminal(viewerUrl, options);
+  terminal.closed.then(() => {
+    if (child.exitCode === null && child.signalCode === null)
+      child.kill("SIGTERM");
   });
   await new Promise((done, fail) => {
     child.once("error", fail);
@@ -6213,16 +6287,21 @@ async function hotViewer(options) {
         done();
         return;
       }
+      terminal.close();
       if (await viewerRunning(url, 20, true)) {
-        console.log("Kennel hot viewer is already running. Reusing it.");
+        await reuse();
         done();
         return;
       }
       fail(new Error(`Kennel hot viewer stopped with exit code ${code ?? "unknown"}`));
     });
-  }).finally(() => releaseLock(lock, token));
+  }).finally(async () => {
+    terminal.close();
+    await releaseLock(lock, token);
+  });
 }
 var init_hot_viewer = __esm(() => {
+  init_terminal();
   init_src2();
 });
 
@@ -28108,7 +28187,7 @@ var init_server = __esm(() => {
 // packages/schemas/src/data/workspace.ts
 import { existsSync as existsSync3, readFileSync, realpathSync, statSync as statSync2 } from "node:fs";
 import {
-  basename,
+  basename as basename2,
   dirname as dirname3,
   isAbsolute,
   relative as relative3,
@@ -28169,7 +28248,7 @@ function folderWorkspace(input, { allowMissingSchemas = false } = {}) {
   for (let current = folder;inside(root, current); current = dirname3(current)) {
     breadcrumbs.unshift({
       path: current,
-      title: basename(current),
+      title: basename2(current),
       schema: schemaRoots.some((owner) => inside(owner, current))
     });
     if (current === root)
@@ -37714,7 +37793,7 @@ var init_load = __esm(() => {
 // packages/schemas/src/node.ts
 import { readdir as readdir2, readFile as readFile4, realpath as realpath2, stat as stat2 } from "node:fs/promises";
 import {
-  basename as basename2,
+  basename as basename3,
   dirname as dirname5,
   isAbsolute as isAbsolute3,
   relative as relative5,
@@ -37747,7 +37826,7 @@ function createCoreFolderIndex() {
           affected.add(scope);
         }
       }
-      if (inside3(path, scope) || basename2(path) === "raggle.json" && inside3(dirname5(path), scope) || ["schema.json", "_schema.json"].includes(basename2(path)) && dirname5(path) === scope)
+      if (inside3(path, scope) || basename3(path) === "raggle.json" && inside3(dirname5(path), scope) || ["schema.json", "_schema.json"].includes(basename3(path)) && dirname5(path) === scope)
         affected.add(scope);
     }
     for (const file of records.keys())
@@ -37856,7 +37935,7 @@ function createCoreFolderIndex() {
             path,
             relativePath: localPath,
             modifiedAt: info.mtimeMs,
-            title: text(fieldValue(parsed.fields, primary)) ?? text(parsed.fields.title) ?? parsed.heading ?? basename2(path, ".md"),
+            title: text(fieldValue(parsed.fields, primary)) ?? text(parsed.fields.title) ?? parsed.heading ?? basename3(path, ".md"),
             fields: parsed.fields,
             validationErrors,
             icon: await recordIcon(parsed.fields, path, entry.folder, parsed.body)
@@ -37882,7 +37961,7 @@ function createCoreFolderIndex() {
     const data = {
       id,
       ...entry,
-      title: text(schema?.title) ?? config.title ?? basename2(entry.folder),
+      title: text(schema?.title) ?? config.title ?? basename3(entry.folder),
       navLabel: config.ui?.navLabel,
       icon: config.icon,
       count: indexedRecords.length,
@@ -37953,7 +38032,7 @@ var init_node3 = __esm(() => {
 
 // packages/schemas/src/server.ts
 import { createHash as createHash3 } from "node:crypto";
-import { basename as basename3, relative as relative6 } from "node:path";
+import { basename as basename4, relative as relative6 } from "node:path";
 function createSchemaCollectionServer(host, options = {}) {
   const collectionIndex = createCoreFolderIndex();
   const collectionScopes = new Set;
@@ -38003,7 +38082,7 @@ function createSchemaCollectionServer(host, options = {}) {
   };
   const invalidate = (path) => {
     const affected = collectionIndex.invalidate(path);
-    if (affected.length || basename3(path) === "raggle.json" && collectionScopes.size) {
+    if (affected.length || basename4(path) === "raggle.json" && collectionScopes.size) {
       clearTimeout(collectionRefresh);
       collectionRefresh = setTimeout(() => {
         host.emit({
@@ -38100,7 +38179,7 @@ var init_server2 = __esm(() => {
 import { readdir as readdir3, readFile as readFile5, realpath as realpath3, stat as stat3 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import {
-  basename as basename4,
+  basename as basename5,
   dirname as dirname6,
   extname as extname2,
   isAbsolute as isAbsolute4,
@@ -38245,10 +38324,10 @@ async function readEntity(folderPath, rootPath) {
     return {
       content: document2.body,
       path: relative7(folderPath, filePath),
-      title: stringValue(document2.frontmatter.title) ?? heading(document2.body) ?? basename4(filePath, extname2(filePath))
+      title: stringValue(document2.frontmatter.title) ?? heading(document2.body) ?? basename5(filePath, extname2(filePath))
     };
   }));
-  const title = stringValue(index.frontmatter.title) ?? heading(index.body) ?? basename4(folderPath);
+  const title = stringValue(index.frontmatter.title) ?? heading(index.body) ?? basename5(folderPath);
   const relativePath = relative7(rootPath, folderPath) || ".";
   return {
     aliases: stringValues(index.frontmatter.aliases),
@@ -38576,7 +38655,7 @@ var init_manifest = __esm(() => {
 
 // packages/notes/src/server.ts
 import { readdir as readdir4, stat as stat6 } from "node:fs/promises";
-import { basename as basename5, extname as extname5, relative as relative9, resolve as resolve10, sep as sep5 } from "node:path";
+import { basename as basename6, extname as extname5, relative as relative9, resolve as resolve10, sep as sep5 } from "node:path";
 async function listMarkdownFiles(folder) {
   const files = [];
   const visit = async (current) => {
@@ -38597,7 +38676,7 @@ async function listMarkdownFiles(folder) {
       });
       files.push({
         activityAt: details?.mtimeMs ?? 0,
-        name: basename5(entry.name, extname5(entry.name)),
+        name: basename6(entry.name, extname5(entry.name)),
         relativePath: relative9(folder, path).split(sep5).join("/")
       });
     }
@@ -38968,7 +39047,7 @@ import { realpathSync as realpathSync2 } from "node:fs";
 import { readdir as readdir5, readFile as readFile9, stat as stat7 } from "node:fs/promises";
 import { homedir as homedir3 } from "node:os";
 import {
-  basename as basename6,
+  basename as basename7,
   dirname as dirname10,
   extname as extname6,
   isAbsolute as isAbsolute6,
@@ -39163,7 +39242,7 @@ async function loadFolderData(folder) {
       items: projects.map((project) => ({
         id: project.id,
         worktree: project.worktree,
-        name: project.name ?? basename6(project.worktree),
+        name: project.name ?? basename7(project.worktree),
         relativePath: relative11(folder, project.worktree)
       }))
     }
@@ -39661,7 +39740,7 @@ function createFolderApi({
               ETag: etag,
               "X-Content-Type-Options": "nosniff",
               ...download ? {
-                "Content-Disposition": `attachment; filename="${basename6(target.path)}"`
+                "Content-Disposition": `attachment; filename="${basename7(target.path)}"`
               } : {}
             });
             response.end(await readFile9(target.path));
@@ -44803,7 +44882,7 @@ import { resolve as resolve15 } from "node:path";
 import { existsSync as existsSync7 } from "node:fs";
 
 // packages/preview/src/viewer.ts
-import { execFile as execFile6, execFileSync as execFileSync2 } from "node:child_process";
+import { execFileSync as execFileSync2 } from "node:child_process";
 import { existsSync as existsSync6, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
 import { createServer as createServer2 } from "node:net";
 import { dirname as dirname11, isAbsolute as isAbsolute8, relative as relative13, resolve as resolve14 } from "node:path";
@@ -44813,6 +44892,7 @@ import { fileURLToPath as fileURLToPath3 } from "node:url";
 init_src();
 
 // packages/preview/src/viewer.ts
+init_terminal();
 var loopbackHosts = new Set([
   "127.0.0.1",
   "::1",
@@ -44992,13 +45072,6 @@ async function availableViewerPort(start, host) {
   }
   throw new Error(`Kennel could not find a free port at or above ${start}`);
 }
-function openUrl(url) {
-  const command = process.platform === "darwin" ? "/usr/bin/open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
-  execFile6(command, [url], (error) => {
-    if (error)
-      console.error(`Could not open browser: ${error.message}`);
-  });
-}
 function lanHost2() {
   const route = execFileSync2("/sbin/route", ["-n", "get", "default"], {
     encoding: "utf8"
@@ -45045,10 +45118,15 @@ async function viewer(input) {
   const existing = await runningViewer(initialViewerUrl);
   if (existing && isSameOrDescendant(existing.root, options.root)) {
     const viewerUrl = popUrl(displayHost, options.port, options);
-    console.log(viewerUrl);
-    console.log(`Kennel is already running at ${viewerUrl}`);
+    const terminal = previewTerminal(viewerUrl, options);
     if (options.open)
-      openUrl(viewerUrl);
+      openPreview(viewerUrl);
+    try {
+      if (terminal.interactive)
+        await terminal.closed;
+    } finally {
+      terminal.close();
+    }
     return;
   }
   if (!portExplicit) {
@@ -45064,25 +45142,18 @@ async function viewer(input) {
   });
   try {
     await api.listen(Number(options.port));
-    console.log(`Reading documents from ${options.root}`);
     if (options.tailscale) {
       execFileSync2("tailscale", ["serve", "--bg", "--yes", options.port]);
     }
     const viewerUrl = popUrl(displayHost, options.port, options);
-    console.log(viewerUrl);
-    console.log(`Kennel is running at ${viewerUrl}`);
-    console.log("Press Ctrl+C to stop.");
+    const terminal = previewTerminal(viewerUrl, options);
     if (options.open)
-      openUrl(viewerUrl);
-    await new Promise((done) => {
-      const close = () => {
-        process.off("SIGINT", close);
-        process.off("SIGTERM", close);
-        done();
-      };
-      process.once("SIGINT", close);
-      process.once("SIGTERM", close);
-    });
+      openPreview(viewerUrl);
+    try {
+      await terminal.closed;
+    } finally {
+      terminal.close();
+    }
   } finally {
     await api.close();
   }

package/dist/plugins/external.d.ts

@@ -4,6 +4,7 @@ export type ExternalPluginEntry = {
     commit: string;
     packageName: string;
     id: string;
+    aliases?: string[];
     directory?: string;
     path?: string;
     trigger?: string;

package/dist/plugins/external.js

@@ -165,6 +165,12 @@ function pluginRoot(repoRoot, directory) {
         throw new Error(`Missing plugin directory: ${directory}`);
     return target;
 }
+// Peers (react, kennel-plugins) come from the host; scripts never run.
+function installPluginDependencies(root, dependencies) {
+    if (!dependencies || typeof dependencies !== "object" || Object.keys(dependencies).length === 0)
+        return;
+    run("npm", ["install", "--omit=dev", "--omit=peer", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: root });
+}
 function safeRelativeFile(root, value, label) {
     if (typeof value !== "string" || !value.trim())
         throw new Error(`Missing ${label}`);
@@ -376,6 +382,15 @@ export async function validateExternalPlugin(inputUrl, options = {}) {
     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}`);
@@ -391,6 +406,7 @@ export async function validateExternalPlugin(inputUrl, options = {}) {
         commit,
         packageName,
         id,
+        ...(aliases?.length ? { aliases } : {}),
         ...(directory ? { directory } : {}),
         ...(source.path ? { path: source.path } : {}),
         ...(trigger ? { trigger } : {}),
@@ -402,6 +418,7 @@ export async function validateExternalPlugin(inputUrl, options = {}) {
             ...(css ? { css } : {}),
         },
     };
+    installPluginDependencies(root, pkg.dependencies);
     await validateImports(entry);
     return entry;
 }

package/dist/site/hot-viewer.d.ts

@@ -1,2 +1,4 @@
-import type { ViewerOptions } from './viewer.js';
+import { type ViewerOptions } from './viewer.js';
+/** The hot viewer runs Vite from a Kennel source checkout; npm installs have none. */
+export declare function hotViewerAvailable(): boolean;
 export declare function hotViewer(options: ViewerOptions): Promise<void>;