kennel 0.2.0 → 0.2.2

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

@@ -0,0 +1,352 @@
+import { execFile, 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 { previewKind } from "./kinds.js";
+export function viewerFolder(root, value) {
+    return resolve(value ?? root);
+}
+/**
+ * Resolve a client-supplied folder against the configured viewer root with a
+ * realpath check: the resolved candidate must be the root itself or a
+ * descendant of the root's real path. Symlink escapes, `..` traversal, and
+ * arbitrary absolute path overrides are rejected. Throws when out of scope.
+ * Used by the API routes; `viewerFolder` (multi-folder local reuse) stays
+ * permissive.
+ */
+export function scopedFolder(root, value) {
+    const base = resolve(root);
+    const baseReal = realpathSync(base);
+    const candidate = value === undefined || value === null || value === ""
+        ? base
+        : resolve(value);
+    if (candidate === base)
+        return base;
+    const candidateReal = realpathSync(candidate);
+    const rel = relative(baseReal, candidateReal);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return candidate;
+    throw new Error("Path is outside the configured viewer root");
+}
+const loopbackHosts = new Set([
+    "127.0.0.1",
+    "::1",
+    "::ffff:127.0.0.1",
+    "localhost",
+]);
+function isLoopbackHost(host) {
+    return loopbackHosts.has(host) || host.startsWith("127.");
+}
+function encodeBase64Url(value) {
+    return Buffer.from(value, "utf8")
+        .toString("base64")
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replaceAll("=", "");
+}
+export function splitViewerArgs(input) {
+    let hasHost = false;
+    let hasRoot = false;
+    const options = {
+        dryRun: false,
+        host: "127.0.0.1",
+        hot: process.env.KENNEL_VIEWER_HOT === "1",
+        lan: false,
+        open: false,
+        root: process.cwd(),
+        port: "5180",
+        tailscale: false,
+        target: undefined,
+        watch: false,
+    };
+    for (let index = 0; index < input.length; index += 1) {
+        const arg = input[index];
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--hot") {
+            options.hot = true;
+            continue;
+        }
+        if (arg === "--open") {
+            options.open = true;
+            continue;
+        }
+        if (arg === "--no-open") {
+            options.open = false;
+            continue;
+        }
+        if (arg === "--watch") {
+            options.watch = true;
+            continue;
+        }
+        if (arg === "--static") {
+            options.hot = false;
+            continue;
+        }
+        if (arg === "--port") {
+            options.port = input[index + 1] ?? "";
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--port=")) {
+            options.port = arg.slice("--port=".length);
+            continue;
+        }
+        if (arg === "--host") {
+            options.host = input[index + 1] ?? "";
+            hasHost = true;
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--host=")) {
+            options.host = arg.slice("--host=".length);
+            hasHost = true;
+            continue;
+        }
+        if (arg === "--lan") {
+            options.lan = true;
+            continue;
+        }
+        if (arg === "--tailscale") {
+            options.tailscale = true;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw new Error(`Unknown viewer option: ${arg}`);
+        const candidate = resolve(arg);
+        const isDirectory = existsSync(candidate) && statSync(candidate).isDirectory();
+        if (isDirectory) {
+            if (hasRoot)
+                throw new Error("kennel accepts one folder");
+            options.root = candidate;
+            hasRoot = true;
+            continue;
+        }
+        if (hasRoot)
+            throw new Error("kennel accepts one folder");
+        options.root = dirname(candidate);
+        options.target = candidate;
+        hasRoot = true;
+    }
+    // Opt out of opening the default browser even when a command implies it
+    // (`--no-open` wins over earlier flags; the env var always disables).
+    if (process.env.KENNEL_OPEN === "0")
+        options.open = false;
+    if (!options.port || !/^\d+$/.test(options.port)) {
+        throw new Error("kennel requires a numeric port");
+    }
+    if (!options.host)
+        throw new Error("kennel requires a host");
+    if ((options.lan || options.tailscale) && hasHost) {
+        throw new Error("kennel does not accept --host with --lan or --tailscale");
+    }
+    if (options.lan && options.tailscale) {
+        throw new Error("kennel accepts one remote access mode");
+    }
+    if (options.lan)
+        options.host = "0.0.0.0";
+    if (!existsSync(options.root) || !statSync(options.root).isDirectory()) {
+        throw new Error(`Folder not found: ${options.root}`);
+    }
+    if (options.target) {
+        const targetDetails = statSync(options.target);
+        if (!targetDetails.isFile()) {
+            throw new Error(`File not found: ${options.target}`);
+        }
+        if (!previewKind(options.target)) {
+            throw new Error(`Kennel cannot preview this file type: ${options.target}`);
+        }
+    }
+    return options;
+}
+export function popUrl(host, port, options) {
+    const scheme = options.tailscale ? "https" : "http";
+    const authority = options.tailscale ? host : `${host}:${port}`;
+    const url = new URL(`${scheme}://${authority}/`);
+    if (!options.target) {
+        url.pathname = `/folder/${encodeBase64Url(options.root)}/notes`;
+        return url.href;
+    }
+    url.pathname = `/folder/${encodeBase64Url(options.root)}/document/${encodeBase64Url(relative(options.root, options.target))}`;
+    if (options.watch)
+        url.searchParams.set("watch", "1");
+    return url.href;
+}
+function viewerPortWasExplicit(input) {
+    return input.some((arg) => arg === "--port" || arg.startsWith("--port="));
+}
+function isSameOrDescendant(parent, child) {
+    const parentReal = realpathSync(parent);
+    const childReal = realpathSync(child);
+    const childRelative = relative(parentReal, childReal);
+    return childRelative === "" || (!childRelative.startsWith("..") && !isAbsolute(childRelative));
+}
+async function runningViewer(url) {
+    try {
+        const response = await fetch(`${url}/api/health`, {
+            signal: AbortSignal.timeout(1_000),
+        });
+        if (!response.ok)
+            return undefined;
+        const body = await response.json();
+        if (body &&
+            typeof body === "object" &&
+            typeof body.root === "string" &&
+            typeof body.viewer === "string" &&
+            (body.viewer === "kennel-core" || body.viewer === "kennel-vite")) {
+            return {
+                kernelKey: typeof body.kernelKey === "string" ? body.kernelKey : "core",
+                root: body.root,
+                viewer: body.viewer,
+            };
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+function canListen(port, host) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once("error", () => resolve(false));
+        server.listen(port, host, () => server.close(() => resolve(true)));
+    });
+}
+async function availableViewerPort(start, host) {
+    for (let port = start; port <= 65535; port += 1) {
+        if (await canListen(port, host))
+            return port;
+    }
+    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";
+    execFile(command, [url], (error) => {
+        if (error)
+            console.error(`Could not open browser: ${error.message}`);
+    });
+}
+function lanHost() {
+    const route = execFileSync("/sbin/route", ["-n", "get", "default"], {
+        encoding: "utf8",
+    });
+    const device = route.match(/interface:\s+(\S+)/)?.[1];
+    if (!device)
+        throw new Error("kennel could not find the local network interface");
+    const host = execFileSync("/usr/sbin/ipconfig", ["getifaddr", device], {
+        encoding: "utf8",
+    }).trim();
+    if (!host)
+        throw new Error(`kennel could not find an address for ${device}`);
+    return host;
+}
+function tailscaleHost() {
+    const status = JSON.parse(execFileSync("tailscale", ["status", "--json"], { encoding: "utf8" }));
+    const host = typeof status.Self?.DNSName === "string"
+        ? status.Self.DNSName.replace(/\.$/, "")
+        : "";
+    if (host)
+        return host;
+    throw new Error("kennel could not find the Tailscale DNS name");
+}
+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) {
+        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 kernel = await ensureKernel(externalPlugins);
+    const web = kernel.webRoot;
+    if (!existsSync(resolve(web, "index.html"))) {
+        throw new Error(`Kennel web app not found. Run the CLI build first.`);
+    }
+    // The server only acts on the machine when it is reachable on loopback.
+    // Explicit --lan/--tailscale/--host bindings disable host actions (opening
+    // folders/files in apps on the server) and gate the capabilities reported
+    // to the client, so a remote phone can never trigger an app on the server.
+    const remote = options.tailscale || !isLoopbackHost(options.host);
+    // Single-file pop mode serves exactly the popped file, never siblings.
+    const lockedTarget = options.target
+        ? realpathSync(options.target)
+        : undefined;
+    const { createKennelApi } = await import("../core/runtime.js");
+    const displayHost = options.tailscale
+        ? tailscaleHost()
+        : options.lan
+            ? lanHost()
+            : options.host;
+    if (remote)
+        process.env.KENNEL_VIEWER_HOSTS = [
+            process.env.KENNEL_VIEWER_HOSTS,
+            displayHost,
+        ]
+            .filter(Boolean)
+            .join(",");
+    const initialViewerUrl = `http://${options.host}:${options.port}`;
+    const existing = await runningViewer(initialViewerUrl);
+    if (existing &&
+        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}`);
+        if (options.open)
+            openUrl(viewerUrl);
+        return;
+    }
+    if (!portExplicit) {
+        options.port = String(await availableViewerPort(Number(options.port), options.host));
+    }
+    process.env.KENNEL_KERNEL_KEY = kernel.key;
+    process.env.KENNEL_EXTERNAL_SERVER_ENTRIES = JSON.stringify(kernel.serverEntries);
+    const api = createKennelApi({
+        root: options.root,
+        host: options.host,
+        remoteAccess: remote,
+        restrictToRoot: true,
+        lockedFile: lockedTarget,
+        webRoot: web,
+    });
+    try {
+        await api.listen(Number(options.port));
+        console.log(`Reading documents from ${options.root}`);
+        if (options.tailscale) {
+            execFileSync("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.");
+        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);
+        });
+    }
+    finally {
+        await api.close();
+    }
+    if (options.tailscale) {
+        execFileSync("tailscale", ["serve", "--https=443", "off"]);
+    }
+}

package/dist/cli/src/site/vitepress.d.ts

@@ -0,0 +1 @@
+export * from './renderers.js';

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

@@ -0,0 +1 @@
+export * from './renderers.js';

package/dist/cli/usage.js

@@ -2,6 +2,7 @@ export function usage() {
     console.log(`Usage:
   knl core [folder] [--host <host>] [--port <port>] [--api-only]
   kennel init [path] [--plugin <id>] [--force] [--list]
+  kennel plugin add <git-repository-url>
   kennel core-folders [path] [--json]
   kennel [folder] [--host <host>] [--port <port>] [--lan|--tailscale]
   kennel pop|p <file|folder> [--open] [--watch] [--host <host>] [--port <port>] [--lan|--tailscale]

package/dist/core/api-client.js

@@ -447,7 +447,6 @@ function removeTrailingSlash(url) {
   }
   return url;
 }
-
 // node_modules/.bun/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var exports_external = {};
 __export(exports_external, {
@@ -14724,6 +14723,65 @@ function date4(params) {
 
 // node_modules/.bun/zod@4.4.3/node_modules/zod/v4/classic/external.js
 config(en_default());
+// packages/schemas/src/data/contract.ts
+var issueSchema = exports_external.object({ path: exports_external.string(), message: exports_external.string() });
+var coreRecordIconSchema = exports_external.object({
+  source: exports_external.enum(["local", "favicon"]),
+  host: exports_external.string().optional(),
+  path: exports_external.string().optional()
+});
+var kennelIconAssetSchema = exports_external.object({
+  data: exports_external.string().optional(),
+  mediaType: exports_external.string(),
+  source: exports_external.enum(["local", "favicon"]).optional(),
+  url: exports_external.string().optional()
+});
+var coreCollectionSortSchema = exports_external.object({
+  field: exports_external.string(),
+  direction: exports_external.enum(["asc", "desc"])
+});
+var coreCollectionUiSchema = exports_external.object({
+  primaryField: exports_external.string(),
+  secondaryField: exports_external.string().optional(),
+  filters: exports_external.array(exports_external.string()),
+  numericFilters: exports_external.array(exports_external.string()),
+  sort: exports_external.array(coreCollectionSortSchema).optional()
+});
+var collectionSummarySchema = exports_external.object({
+  id: exports_external.string().optional(),
+  count: exports_external.number().optional(),
+  navLabel: exports_external.string().optional(),
+  icon: exports_external.string().optional(),
+  revision: exports_external.string().optional(),
+  indexedAt: exports_external.string().optional(),
+  state: exports_external.enum(["ready", "error"]).optional(),
+  diagnostics: exports_external.array(issueSchema).optional(),
+  folder: exports_external.string(),
+  schemaPath: exports_external.string(),
+  title: exports_external.string()
+});
+var coreRecordSchema = exports_external.object({
+  icon: coreRecordIconSchema.optional(),
+  iconAssetKey: exports_external.string().optional(),
+  id: exports_external.string(),
+  path: exports_external.string(),
+  relativePath: exports_external.string(),
+  title: exports_external.string(),
+  modifiedAt: exports_external.number(),
+  fields: exports_external.record(exports_external.string(), exports_external.unknown()),
+  validationErrors: exports_external.array(issueSchema)
+});
+var coreCollectionSchema = collectionSummarySchema.extend({
+  id: exports_external.string(),
+  count: exports_external.number(),
+  diagnostics: exports_external.array(issueSchema),
+  revision: exports_external.string(),
+  indexedAt: exports_external.string(),
+  state: exports_external.enum(["ready", "error"]),
+  ui: coreCollectionUiSchema,
+  assets: exports_external.record(exports_external.string(), kennelIconAssetSchema).optional(),
+  records: exports_external.array(coreRecordSchema)
+});
 // packages/api/src/contracts/schemas.ts
 var items = (item) => exports_external.object({ items: exports_external.array(item) });
 var icon = exports_external.object({
@@ -14763,20 +14821,7 @@ var session = exports_external.object({
   resumeCommand: exports_external.string().optional(),
   title: exports_external.string()
 });
-var issue2 = exports_external.object({ path: exports_external.string(), message: exports_external.string() });
-var collectionSummary = exports_external.object({
-  id: exports_external.string().optional(),
-  count: exports_external.number().optional(),
-  navLabel: exports_external.string().optional(),
-  icon: exports_external.string().optional(),
-  revision: exports_external.string().optional(),
-  indexedAt: exports_external.string().optional(),
-  state: exports_external.enum(["ready", "error"]).optional(),
-  diagnostics: exports_external.array(issue2).optional(),
-  folder: exports_external.string(),
-  schemaPath: exports_external.string(),
-  title: exports_external.string()
-});
+var collectionSummary2 = collectionSummarySchema;
 var workspace = exports_external.object({
   breadcrumbs: exports_external.array(exports_external.object({
     icon: icon.optional(),
@@ -14789,7 +14834,7 @@ var workspace = exports_external.object({
   schemaPath: exports_external.string().optional(),
   revision: exports_external.string().optional(),
   state: exports_external.enum(["ready", "error"]).optional(),
-  schemas: exports_external.array(collectionSummary).optional()
+  schemas: exports_external.array(collectionSummary2).optional()
 });
 var plugin = exports_external.object({
   count: exports_external.number().optional(),
@@ -14797,6 +14842,10 @@ var plugin = exports_external.object({
   id: exports_external.string(),
   label: exports_external.string()
 });
+var plugins = exports_external.object({
+  configWarnings: exports_external.array(exports_external.string()).optional(),
+  items: exports_external.array(plugin)
+});
 var folder = { folder: exports_external.string() };
 var assets = exports_external.record(exports_external.string(), icon);
 var folderMetadataSchema = exports_external.object({
@@ -14804,34 +14853,13 @@ var folderMetadataSchema = exports_external.object({
   assets,
   files: items(file2),
   iconAssetKey: exports_external.string().optional(),
-  plugins: items(plugin).optional(),
+  plugins: plugins.optional(),
   projects: items(project),
   sessions: items(session),
   skills: items(skill).optional(),
   workspace: workspace.optional()
 });
-var collection = collectionSummary.extend({
-  id: exports_external.string(),
-  count: exports_external.number(),
-  diagnostics: exports_external.array(issue2),
-  revision: exports_external.string(),
-  indexedAt: exports_external.string(),
-  state: exports_external.enum(["ready", "error"]),
-  ui: exports_external.object({
-    primaryField: exports_external.string(),
-    secondaryField: exports_external.string().optional(),
-    filters: exports_external.array(exports_external.string())
-  }),
-  records: exports_external.array(exports_external.object({
-    id: exports_external.string(),
-    path: exports_external.string(),
-    relativePath: exports_external.string(),
-    title: exports_external.string(),
-    modifiedAt: exports_external.number(),
-    fields: exports_external.record(exports_external.string(), exports_external.unknown()),
-    validationErrors: exports_external.array(issue2)
-  }))
-});
+var collection = coreCollectionSchema;
 var metadataSchemas = {
   notes: exports_external.object({ ...folder, files: items(file2) }),
   identity: exports_external.object({
@@ -14847,7 +14875,11 @@ var metadataSchemas = {
   }),
   workspace: exports_external.object({ ...folder, workspace }),
   collections: exports_external.object({ ...folder, collection }),
-  plugins: exports_external.object({ ...folder, plugins: items(plugin).optional() }),
+  plugins: exports_external.object({
+    ...folder,
+    configWarnings: exports_external.array(exports_external.string()).optional(),
+    plugins: plugins.optional()
+  }),
   skills: exports_external.object({ ...folder, skills: items(skill) }),
   sessions: folderMetadataSchema,
   calendar: folderMetadataSchema,
@@ -14858,6 +14890,7 @@ var metadataQuerySchema = exports_external.object({
   part: exports_external.enum(Object.keys(metadataSchemas)).optional(),
   notesScope: exports_external.enum(["local", "linked", "all"]).optional(),
   id: exports_external.string().optional(),
+  sort: exports_external.enum(["alpha", "recent"]).optional(),
   schema: exports_external.string().optional()
 });
 var documentEditSchema = exports_external.object({
@@ -14919,7 +14952,7 @@ var routes = {
     path: "/api/health",
     method: "get",
     query: emptyQuery,
-    response: exports_external.object({ viewer: exports_external.string(), root: exports_external.string() })
+    response: exports_external.object({ viewer: exports_external.string(), root: exports_external.string(), kernelKey: exports_external.string() })
   },
   capabilities: {
     path: "/api/capabilities",
@@ -15010,7 +15043,6 @@ var routes = {
     query: exports_external.object({ path: exports_external.string() })
   }
 };
-
 // packages/api/src/shared/viewer-route.ts
 function decodeBase64Url(value) {
   const padded = `${value}${"=".repeat((4 - value.length % 4) % 4)}`;
@@ -15034,7 +15066,6 @@ function tabSection(tab) {
 function decodeFolderPathId(id) {
   return decodeBase64Url(id);
 }
-var pluginIds = new Set(["calendar", "mail", "agents", "tasks"]);
 function parseViewerRoute(value) {
   const current = url2(value);
   const session2 = current.searchParams.get("session") ?? undefined;
@@ -15070,7 +15101,7 @@ function parseViewerRoute(value) {
   if (section === "collections" && parts[3]) {
     return { ...route, collectionId: decodeFolderPathId(parts[3]) };
   }
-  if (section === "views" && parts[3] && pluginIds.has(parts[3])) {
+  if (section === "views" && parts[3]) {
     return {
       ...route,
       view: {

package/dist/core/command.js

@@ -1,6 +1,5 @@
 import { existsSync, realpathSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
 import { createKennelApi } from "./runtime.js";
 export async function core(args) {
     let root = process.cwd();
@@ -39,9 +38,13 @@ export async function core(args) {
     root = realpathSync(root);
     if (!statSync(root).isDirectory())
         throw new Error("Core root must be a directory");
-    const webRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../web");
+    const { ensureKernel } = await import("../plugins/external.js");
+    const kernel = await ensureKernel();
+    const webRoot = kernel.webRoot;
     if (!apiOnly && !existsSync(resolve(webRoot, "index.html")))
         throw new Error("Web assets missing; build the CLI or use --api-only");
+    process.env.KENNEL_KERNEL_KEY = kernel.key;
+    process.env.KENNEL_EXTERNAL_SERVER_ENTRIES = JSON.stringify(kernel.serverEntries);
     const api = createKennelApi({
         root,
         host,