kennel 0.2.1 → 0.2.2

package/kernel/packages/api/src/server/host.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+export type Middleware = (
+  request: IncomingMessage,
+  response: ServerResponse,
+  next: () => void,
+) => void | Promise<void>;
+export type ApiEvent = {
+  event: string;
+  data: { path: string };
+  type: "custom";
+};
+
+/** Transport seam shared by standalone HTTP and the transitional Vite adapter. */
+export type ApiHost = {
+  host?: string | boolean;
+  use(handler: Middleware): void;
+  watch(paths: string | string[]): void;
+  onChange(listener: (path: string) => void): void;
+  emit(event: ApiEvent): void;
+};

package/kernel/packages/api/src/server/index.ts

@@ -0,0 +1,197 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { extname, isAbsolute, relative, resolve } from "node:path";
+import { createWatcher } from "./watcher";
+import {
+  createFolderApi,
+  apiHostAllowed,
+  isLoopbackServerHost,
+  type FolderMetadataPluginOptions,
+} from "./folder-metadata-plugin";
+import { createAcpApi } from "./acp-live-plugin";
+import type { ApiHost, Middleware } from "./host";
+
+export type KennelApiOptions = FolderMetadataPluginOptions & {
+  host?: string;
+  webRoot?: string;
+};
+
+/** Owns all API state, watchers and child processes. Does not listen until asked. */
+export function createKennelApi(options: KennelApiOptions) {
+  const remote = options.remoteAccess || !isLoopbackServerHost(options.host);
+  let closed = false;
+  const middleware: Middleware[] = [];
+  const streams = new Set<ServerResponse>();
+  const active = new Set<ServerResponse>();
+  const listeners = new Set<(path: string) => void>();
+  const watcher = createWatcher((path) => {
+    for (const listener of listeners) listener(path);
+  });
+  const host: ApiHost = {
+    host: options.host,
+    use: (handler) => {
+      middleware.push(handler);
+    },
+    watch: (paths) => {
+      if (!closed) watcher.add(paths);
+    },
+    onChange: (listener) => {
+      listeners.add(listener);
+    },
+    emit: (event) => {
+      for (const stream of streams)
+        stream.write(
+          `event: ${event.event}\ndata: ${JSON.stringify(event.data)}\n\n`,
+        );
+    },
+  };
+  const folder = createFolderApi({
+    mailDir: process.env.KENNEL_MAIL_DIR || undefined,
+    ...options,
+    remoteAccess: remote,
+  });
+  const acp = createAcpApi({ remoteAccess: remote });
+  folder.attach(host);
+  acp.attach(host);
+
+  async function handle(
+    request: IncomingMessage,
+    response: ServerResponse,
+    next = () => {
+      response.writeHead(404);
+      response.end("Not found");
+    },
+  ) {
+    try {
+      if (closed) {
+        response.writeHead(503);
+        response.end();
+        return;
+      }
+      active.add(response);
+      response.once("close", () => active.delete(response));
+      if (!apiHostAllowed(request.headers.host, !!remote)) {
+        response.writeHead(403);
+        response.end("Untrusted Host header");
+        return;
+      }
+      const url = new URL(request.url ?? "/", "http://localhost");
+      if (url.pathname === "/api/events") {
+        if (request.method !== "GET") {
+          response.writeHead(405);
+          response.end();
+          return;
+        }
+        response.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-store",
+          "X-Accel-Buffering": "no",
+        });
+        response.write(": connected\n\n");
+        streams.add(response);
+        response.on("close", () => streams.delete(response));
+        return;
+      }
+      for (const handler of middleware) {
+        let pass = false;
+        await handler(request, response, () => {
+          pass = true;
+        });
+        if (!pass) return;
+      }
+      if (url.pathname.startsWith("/api/")) {
+        response.writeHead(404);
+        response.end("Unknown API endpoint");
+        return;
+      }
+      if (
+        options.webRoot &&
+        (request.method === "GET" || request.method === "HEAD")
+      ) {
+        const root = await realpath(options.webRoot);
+        let target = resolve(root, `.${decodeURIComponent(url.pathname)}`);
+        const inside = (path: string) => {
+          const local = relative(root, path);
+          return (
+            local !== ".." && !local.startsWith("../") && !isAbsolute(local)
+          );
+        };
+        if (!inside(target)) {
+          response.writeHead(403);
+          response.end();
+          return;
+        }
+        if (!(await stat(target).catch(() => null))?.isFile())
+          target = resolve(root, "index.html");
+        target = await realpath(target);
+        if (!inside(target)) {
+          response.writeHead(403);
+          response.end();
+          return;
+        }
+        const types: Record<string, string> = {
+          ".html": "text/html",
+          ".js": "text/javascript",
+          ".css": "text/css",
+          ".json": "application/json",
+          ".svg": "image/svg+xml",
+          ".png": "image/png",
+          ".ico": "image/x-icon",
+          ".woff2": "font/woff2",
+        };
+        response.writeHead(200, {
+          "Content-Type": types[extname(target)] ?? "application/octet-stream",
+          "X-Content-Type-Options": "nosniff",
+        });
+        response.end(
+          request.method === "HEAD" ? undefined : await readFile(target),
+        );
+        return;
+      }
+      next();
+    } catch (error) {
+      if (!response.headersSent)
+        response.writeHead(500, { "Content-Type": "application/json" });
+      response.end(
+        JSON.stringify({
+          error: { code: "failed", message: "Request failed" },
+        }),
+      );
+    }
+  }
+  const server = createServer((request, response) => {
+    void handle(request, response);
+  });
+  return {
+    handle,
+    async listen(port = 5181) {
+      await new Promise<void>((done, fail) => {
+        server.once("error", fail);
+        server.listen(port, options.host ?? "127.0.0.1", () => {
+          server.off("error", fail);
+          done();
+        });
+      });
+      return server.address();
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      for (const response of active) response.end();
+      active.clear();
+      streams.clear();
+      listeners.clear();
+      server.closeAllConnections();
+      await Promise.all([
+        new Promise<void>((done) => server.close(() => done())),
+        watcher.close(),
+        folder.close(),
+        acp.close(),
+      ]);
+    },
+  };
+}

package/kernel/packages/api/src/server/linked-folder-discovery.ts

@@ -0,0 +1,158 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export type LinkedFolderState = {
+  folders: string[];
+  status: "pending" | "ready" | "error";
+};
+export type LinkedFolderLoader = (folder: string, signal: AbortSignal) => Promise<string[]>;
+
+// Scout performs synchronous catalog/native work. A promise or timeout around
+// that work in this process cannot protect HTTP/SSE from event-loop starvation.
+const script = `
+const local = require(process.argv[1]);
+const { stat } = require('node:fs/promises');
+(async () => {
+  const folder = process.argv[2];
+  const connected = await local.listConnectedProjects(folder, { depth: 1, focused: true });
+  const folders = [...new Set(connected.relations
+    .filter(r => r.type === 'notes' && (r.target === connected.selectedWorktree || r.source === connected.selectedWorktree))
+    .map(r => r.target === connected.selectedWorktree ? r.source : r.target))]
+    .filter(path => path !== folder);
+  const existing = await Promise.all(folders.map(async path =>
+    (await stat(path).catch(() => null))?.isDirectory() ? path : null));
+  process.stdout.write(JSON.stringify(existing.filter(Boolean)));
+})().catch(error => { console.error(error); process.exitCode = 1; });
+`;
+
+/**
+ * Resolve an `@raggle-ai/local` module that exports `listConnectedProjects`.
+ * The published package versions expose only the older local-file API, so a
+ * standalone kennel CLI bundled with one of them cannot run linked-folder
+ * discovery. Prefer a module that actually has the capability: first the
+ * caller's own resolution, then a sibling Scout development checkout (the
+ * workspace dev graph resolves it too).
+ */
+export function resolveLocalModule(
+  from: string = import.meta.url,
+): string {
+  const require = createRequire(from);
+  const candidates: string[] = [];
+  try {
+    candidates.push(require.resolve("@raggle-ai/local"));
+  } catch {
+    // No installed copy; fall through to the dev checkout.
+  }
+  // Walk up from the caller to a kennel checkout marker, then look for the
+  // Scout checkout as a sibling of the kennel repo root.
+  let directory = dirname(fileURLToPath(from));
+  while (dirname(directory) !== directory) {
+    if (existsSync(join(directory, "raggle.json"))) {
+      for (const candidate of [
+        join(dirname(directory), "raggle-ai-scout", "packages", "local"),
+        join(directory, "..", "..", "raggle-ai-scout", "packages", "local"),
+      ]) {
+        if (!candidates.includes(candidate)) candidates.push(candidate);
+      }
+      break;
+    }
+    directory = dirname(directory);
+  }
+  for (const candidate of candidates) {
+    try {
+      const mod = require(candidate);
+      if (typeof mod.listConnectedProjects === "function") return candidate;
+    } catch {
+      // Unresolvable or broken; try the next candidate.
+    }
+  }
+  return candidates[0] ?? join(dirname(fileURLToPath(from)), "..", "..", "..", "raggle-ai-scout", "packages", "local");
+}
+
+export function discoverLinkedFolders(
+  folder: string,
+  signal: AbortSignal,
+  modulePath = resolveLocalModule(),
+): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    execFile(process.execPath, ["-e", script, modulePath, folder], {
+      signal,
+      timeout: 60_000,
+      maxBuffer: 8 * 1024 * 1024,
+      // Do not inherit debugging/preload flags into background catalog jobs.
+      env: { ...process.env, NODE_OPTIONS: "" },
+    }, (error, stdout) => {
+      if (error) return reject(error);
+      try {
+        const folders: unknown = JSON.parse(stdout);
+        if (!Array.isArray(folders) || !folders.every(path => typeof path === "string"))
+          throw new Error("Invalid linked folder discovery response");
+        resolve(folders);
+      } catch (error) { reject(error); }
+    });
+  });
+}
+
+/** Per-folder, single-flight cache; only one catalog process runs at a time. */
+export function createLinkedFolderDiscovery(
+  load: LinkedFolderLoader = discoverLinkedFolders,
+  changed: (folder: string) => void = () => {},
+) {
+  const controller = new AbortController();
+  const entries = new Map<string, {
+    state: LinkedFolderState;
+    updated: number;
+    pending?: Promise<void>;
+  }>();
+  let queue = Promise.resolve();
+  function read(folder: string): LinkedFolderState {
+    let entry = entries.get(folder);
+    if (controller.signal.aborted) return { folders: [], status: "error" };
+    if (entry && (entry.pending || Date.now() - entry.updated < 60_000)) return entry.state;
+    if (!entry) {
+      entry = { state: { folders: [], status: "pending" }, updated: 0 };
+      entries.set(folder, entry);
+    }
+    const current = entry;
+    current.state = { folders: current.state.folders, status: "pending" };
+    current.pending = queue.then(async () => {
+      if (controller.signal.aborted) return;
+      try {
+        const folders = await load(folder, controller.signal);
+        current.state = { folders, status: "ready" };
+      } catch {
+        current.state = { folders: current.state.folders, status: "error" };
+      } finally {
+        current.updated = Date.now();
+        current.pending = undefined;
+        if (!controller.signal.aborted) changed(folder);
+      }
+    });
+    queue = current.pending;
+    return current.state;
+  }
+  return {
+    read,
+    peek(folder: string): LinkedFolderState {
+      return entries.get(folder)?.state ?? { folders: [], status: "ready" };
+    },
+    retry(folder: string) {
+      const entry = entries.get(folder);
+      if (entry && !entry.pending) entry.updated = 0;
+      return read(folder);
+    },
+    async folders(folder: string) {
+      read(folder);
+      // Serve the last completed result during refresh, including empty lists.
+      // Other open folders may have slow catalog jobs queued ahead of this one.
+      const entry = entries.get(folder);
+      if (entry?.updated) return entry.state.folders;
+      await entry?.pending;
+      return entries.get(folder)?.state.folders ?? [];
+    },
+    close() { controller.abort(); entries.clear(); },
+  };
+}

package/kernel/packages/api/src/server/plugins.ts

@@ -0,0 +1,205 @@
+import type { FolderPluginContext } from "@raggle-ai/folder-plugin/server";
+import type { FolderPluginServer } from "@raggle-ai/folder-plugin/server";
+import type { MailCreatePluginOptions } from "@raggle-ai/mail/server";
+import { pathToFileURL } from "node:url";
+import { existsSync } from "node:fs";
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { createAgentsPlugin } from "@raggle-ai/agents/server";
+import { createCalendarPlugin } from "@raggle-ai/calendar/server";
+import { FolderPluginFailure } from "@raggle-ai/folder-plugin/server";
+import { createMailPlugin } from "@raggle-ai/mail/server";
+import { createNotesPlugin } from "@raggle-ai/notes/server";
+import { createProjectsPlugin } from "@raggle-ai/projects/server";
+import { createTasksPlugin } from "@raggle-ai/tasks/server";
+
+export { FolderPluginFailure };
+export { handleMailApiRoutes } from "@raggle-ai/mail/api";
+
+export type FolderServerRegistryOptions = MailCreatePluginOptions & {
+  /** Override the home directory used for Agent global files. Intended for tests. */
+  agentsHomeDir?: string;
+};
+
+export type FolderPluginRegistryConfig = {
+  plugins: {
+    disable: string[];
+    order: string[];
+  };
+};
+
+/**
+ * Narrows and reorders the trusted build-time registry. Config never creates
+ * plugins; unknown ids are ignored here and can be reported by the caller.
+ */
+export function configuredFolderServerRegistry(
+  registry: Map<string, FolderPluginServer>,
+  resolvedConfig: FolderPluginRegistryConfig,
+): Map<string, FolderPluginServer> {
+  const disabled = new Set(resolvedConfig.plugins.disable);
+  const orderedIds = resolvedConfig.plugins.order.filter(
+    (id) => registry.has(id) && !disabled.has(id),
+  );
+  const ids = [
+    ...orderedIds,
+    ...[...registry.keys()].filter(
+      (id) => !disabled.has(id) && !orderedIds.includes(id),
+    ),
+  ];
+  return new Map(ids.map((id) => [id, registry.get(id)!]));
+}
+
+/**
+ * Explicit server-only plugin registry. Mail preview execution and the mail
+ * directory are injected here so the host and tests can keep their existing
+ * seams while the plugin owns its folder authorization.
+ */
+export function createFolderServerPlugins(
+  options: FolderServerRegistryOptions = {},
+): FolderPluginServer[] {
+  return [
+    createCalendarPlugin(),
+    createMailPlugin(options),
+    createAgentsPlugin({
+      homeDir: options.agentsHomeDir,
+    }),
+    createNotesPlugin(),
+    createTasksPlugin(),
+    createProjectsPlugin(),
+  ];
+}
+
+export function folderServerRegistry(
+  options: FolderServerRegistryOptions = {},
+): Map<string, FolderPluginServer> {
+  return new Map(
+    createFolderServerPlugins(options).map((plugin) => [plugin.id, plugin]),
+  );
+}
+
+type ExternalServerEntry = {
+  id: string;
+  module: string;
+  symbol: string;
+  trigger?: string;
+};
+
+function externalServerEntries(): ExternalServerEntry[] {
+  const source = process.env.KENNEL_EXTERNAL_SERVER_ENTRIES;
+  if (!source) return [];
+  const value = JSON.parse(source) as unknown;
+  if (!Array.isArray(value)) throw new Error("Invalid external plugin server config");
+  return value.map((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      throw new Error("Invalid external plugin server config");
+    const item = entry as Partial<ExternalServerEntry>;
+    if (
+      typeof item.id !== "string" ||
+      typeof item.module !== "string" ||
+      typeof item.symbol !== "string"
+    )
+      throw new Error("Invalid external plugin server config");
+    if (item.trigger !== undefined && typeof item.trigger !== "string")
+      throw new Error("Invalid external plugin server config");
+    return { id: item.id, module: item.module, symbol: item.symbol, trigger: item.trigger };
+  });
+}
+
+export async function folderServerRegistryAsync(
+  options: FolderServerRegistryOptions = {},
+): Promise<Map<string, FolderPluginServer>> {
+  const registry = folderServerRegistry(options);
+  for (const entry of externalServerEntries()) {
+    if (registry.has(entry.id))
+      throw new Error(`External plugin id collides with core plugin: ${entry.id}`);
+    const imported = await import(pathToFileURL(entry.module).href);
+    const value = imported[entry.symbol];
+    const plugin =
+      typeof value === "function" ? value(options) : value;
+    if (!plugin || typeof plugin !== "object")
+      throw new Error(`External plugin ${entry.id} did not export ${entry.symbol}`);
+    const server = plugin as FolderPluginServer;
+    if (server.id !== entry.id)
+      throw new Error(`External plugin id mismatch: expected ${entry.id}, got ${server.id}`);
+    if (registry.has(server.id))
+      throw new Error(`Duplicate external plugin id: ${server.id}`);
+    const withTrigger = entry.trigger
+      ? {
+          ...server,
+          async detect(context: FolderPluginContext) {
+            const detection = await server.detect(context);
+            if (
+              detection.status === "unavailable" &&
+              existsSync(resolve(context.folder, entry.trigger!))
+            ) {
+              return { status: "available" as const };
+            }
+            return detection;
+          },
+        }
+      : server;
+    registry.set(server.id, withTrigger);
+  }
+  return registry;
+}
+
+export type FolderPluginScaffoldFile = {
+  plugin: string;
+  path: string;
+};
+
+export type FolderPluginScaffoldResult = {
+  /** Files that were written. */
+  created: FolderPluginScaffoldFile[];
+  /** Files that already existed and were left untouched (unless forced). */
+  skipped: FolderPluginScaffoldFile[];
+  /** Files each plugin with an `init` capability would create. */
+  supported: Array<{ id: string; files: string[] }>;
+};
+
+/**
+ * General `kennel init` scaffolding: run every registered plugin's `init`
+ * capability and write the returned starter files into `folder`, skippping
+ * files that already exist (unless `force`). Files are containment-checked
+ * against the folder root; plugins never reach outside it.
+ */
+export async function scaffoldFolderPlugins(
+  folder: string,
+  options: FolderServerRegistryOptions & { force?: boolean; write?: boolean } = {},
+): Promise<FolderPluginScaffoldResult> {
+  const root = resolve(folder);
+  const registry = folderServerRegistry(options);
+  const created: FolderPluginScaffoldFile[] = [];
+  const skipped: FolderPluginScaffoldFile[] = [];
+  const supported: FolderPluginScaffoldResult["supported"] = [];
+
+  for (const plugin of registry.values()) {
+    if (!plugin.init) continue;
+    const context: FolderPluginContext = { folder: root };
+    const result = await plugin.init(context);
+    const files = result.files.filter((file) => {
+      const target = resolve(root, file.path);
+      const contained =
+        target === root || target.startsWith(root + sep);
+      return contained && file.path !== ".";
+    });
+    supported.push({
+      id: plugin.id,
+      files: files.map((file) => file.path),
+    });
+    for (const file of files) {
+      const target = resolve(root, file.path);
+      const exists = await stat(target).then(() => true).catch(() => false);
+      if (exists && !options.force) {
+        skipped.push({ path: file.path, plugin: plugin.id });
+        continue;
+      }
+      if (options.write === false) continue;
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, file.content);
+      created.push({ path: file.path, plugin: plugin.id });
+    }
+  }
+
+  return { created, skipped, supported };
+}

package/kernel/packages/api/src/server/project-discovery.ts

@@ -0,0 +1,69 @@
+import { execFile } from "node:child_process";
+import { resolveLocalModule } from "./linked-folder-discovery";
+
+export type DiscoveredProject = { id: string; worktree: string; name: string; relativePath: string };
+const script = `
+const local = require(process.argv[1]);
+const { basename, relative } = require('node:path');
+const folder = process.argv[2];
+local.discoverProjectsUnderFolder({folder}).then(projects => {
+  process.stdout.write(JSON.stringify(projects.map(p => ({id:p.id, worktree:p.worktree,
+    name:p.name ?? basename(p.worktree), relativePath:relative(folder,p.worktree)}))));
+}).catch(error => { console.error(error); process.exitCode = 1; });
+`;
+export function discoverProjects(folder: string, signal: AbortSignal): Promise<DiscoveredProject[]> {
+  return new Promise((resolve, reject) => {
+    execFile(process.execPath, ["-e", script, resolveLocalModule(), folder], {
+      signal, timeout: 60_000, maxBuffer: 8 * 1024 * 1024,
+      env: { ...process.env, NODE_OPTIONS: "" },
+    }, (error, stdout) => {
+      if (error) return reject(error);
+      try { resolve(JSON.parse(stdout)); } catch (error) { reject(error); }
+    });
+  });
+}
+
+/** One scan at a time, shared by callers, cancelled when its last caller leaves. */
+export function createProjectDiscovery(load = discoverProjects) {
+  const jobs = new Map<string, { controller: AbortController; promise: Promise<DiscoveredProject[]>; users: number }>();
+  let queue = Promise.resolve();
+  let closed = false;
+  return {
+    read(folder: string, signal: AbortSignal): Promise<DiscoveredProject[]> {
+      if (closed || signal.aborted) return Promise.reject(new Error("Discovery cancelled"));
+      let job = jobs.get(folder);
+      if (!job) {
+        const controller = new AbortController();
+        const promise = queue.then(() => {
+          controller.signal.throwIfAborted();
+          return load(folder, controller.signal);
+        });
+        job = { controller, promise, users: 0 };
+        jobs.set(folder, job);
+        const current = job;
+        queue = promise.then(() => {}, () => {}).finally(() => {
+          if (jobs.get(folder) === current) jobs.delete(folder);
+        });
+      }
+      const current = job;
+      current.users++;
+      return new Promise((resolve, reject) => {
+        let done = false;
+        const finish = (error?: unknown, value?: DiscoveredProject[]) => {
+          if (done) return;
+          done = true;
+          signal.removeEventListener("abort", abort);
+          if (--current.users === 0) {
+            current.controller.abort();
+            if (jobs.get(folder) === current) jobs.delete(folder);
+          }
+          if (error) reject(error); else resolve(value!);
+        };
+        const abort = () => finish(new Error("Discovery cancelled"));
+        signal.addEventListener("abort", abort, { once: true });
+        current.promise.then(value => finish(undefined, value), error => finish(error));
+      });
+    },
+    close() { closed = true; for (const job of jobs.values()) job.controller.abort(); jobs.clear(); },
+  };
+}

package/kernel/packages/api/src/server/watcher.ts

@@ -0,0 +1,46 @@
+import { existsSync, statSync, watch, type FSWatcher } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+/** Core owns native watchers synchronously, including watches for not-yet-created config files. */
+export function createWatcher(onChange: (path: string) => void) {
+  const watchers = new Map<string, FSWatcher>();
+  let closed = false;
+  return {
+    add(paths: string | string[]) {
+      if (closed) return;
+      for (const path of typeof paths === "string" ? [paths] : paths) {
+        let directory = resolve(path);
+        while (!existsSync(directory)) {
+          const parent = dirname(directory);
+          if (parent === directory) break;
+          directory = parent;
+        }
+        if (!statSync(directory).isDirectory()) directory = dirname(directory);
+        if (watchers.has(directory)) continue;
+        const watcher = watch(
+          directory,
+          { recursive: true, persistent: false },
+          (_, filename) => {
+            if (
+              closed ||
+              !filename ||
+              /(^|[/\\])(node_modules|\.git)([/\\]|$)/.test(String(filename))
+            )
+              return;
+            onChange(resolve(directory, String(filename)));
+          },
+        );
+        watcher.on("error", () => {
+          watcher.close();
+          watchers.delete(directory);
+        });
+        watchers.set(directory, watcher);
+      }
+    },
+    close() {
+      closed = true;
+      for (const watcher of watchers.values()) watcher.close();
+      watchers.clear();
+    },
+  };
+}