@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/lib/plugins/background.test.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Background work and the on-disk plugin path.
+ *
+ * Split from `platform.test.ts` (which owns storage, settings, rpc, realtime and
+ * events) because the two halves have different fixtures: everything here works
+ * from a declared schedule or a directory on disk, while the rest needs the
+ * isolated database.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { mkdir, mkdtemp, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { createPluginBackground } from '@/server/lib/plugins/background.server';
+import { createPluginLogger } from '@/server/lib/plugins/log.server';
+import { loadPluginServer } from '@/server/lib/plugins/loader.server';
+import { toManifest } from '@/server/lib/panels/manifest';
+
+let root = '';
+
+beforeAll(async () => {
+  root = await mkdtemp(join(tmpdir(), 'omp-plugin-background-'));
+  isolateDb();
+});
+
+afterAll(async () => {
+  releaseDb();
+  await rm(root, { recursive: true, force: true });
+});
+
+describe('background', () => {
+  test('a service starts at declaration and is recorded for disposal', () => {
+    const started: string[] = [];
+    const { api, handle } = createPluginBackground('alpha');
+    api.service('poller', { start: () => void started.push('start'), stop: () => void started.push('stop') });
+    expect(started).toEqual(['start']);
+    expect(handle.services).toHaveLength(1);
+    expect(handle.services[0]?.id).toBe('poller');
+  });
+
+  test('a schedule resolves its next fire with Kabmo own grammar', () => {
+    const { api, handle } = createPluginBackground('alpha', 1_000_000);
+    api.schedule('sweep', '5m', () => {});
+    api.schedule('cronny', '0 * * * *', () => {});
+    expect(handle.schedules.map((entry) => entry.kind)).toEqual(['every', 'cron']);
+    expect(handle.schedules[0]?.nextRunAt).toBe(1_000_000 + 300_000);
+  });
+
+  test('a spec that is neither an interval nor a cron is refused by name', () => {
+    const { api } = createPluginBackground('alpha');
+    expect(() => api.schedule('bad', 'whenever', () => {})).toThrow('neither an interval');
+  });
+});
+
+describe('logger', () => {
+  test('every line carries the plugin id', () => {
+    const lines: string[] = [];
+    const original = console.log;
+    console.log = (...args: unknown[]) => void lines.push(args.join(' '));
+    try {
+      createPluginLogger('alpha').info('connected', { host: 'x' });
+    } finally {
+      console.log = original;
+    }
+    expect(lines).toEqual(['[plugin:alpha] connected {"host":"x"}']);
+  });
+});
+
+describe('a plugin directory on disk', () => {
+  test('the loader reports a plugin that declares no server entry as a skip, not an error', async () => {
+    // `findPluginDir` resolves through the marketplace scan, so an id that is
+    // not installed is the reachable failure here.
+    await expect(loadPluginServer('definitely-not-installed')).rejects.toThrow('no installed plugin');
+  });
+
+  test('the manifest refuses a server entry that escapes the plugin directory', async () => {
+    const dir = join(root, 'escaping');
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'marker'), '');
+    const result = toManifest({ id: 'escaping', name: 'Escaping', version: '1.0.0', server: '../outside.js' }, dir);
+    expect('error' in result && result.error).toContain('escapes');
+  });
+});

package/src/server/lib/plugins/build-server.test.ts

@@ -0,0 +1,85 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The server-target build, end to end, on a real plugin directory.
+ *
+ * The bundled example is the fixture on purpose: it declares BOTH an `app` and
+ * a `server`, so this suite pins the two-target build against the one shape
+ * that exercises both. A unit test with a synthetic source would pass while the
+ * real plugin's `server.ts` failed to resolve `@kabmo-labs/kabmo-sdk` — which
+ * is exactly the failure the server target exists to avoid.
+ *
+ * Slow (an install plus two bundles), so the assertions are grouped into one
+ * test rather than spread across several that would each pay for it.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { cp, mkdtemp, readFile, rm, writeFile } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { buildPanelPlugin } from '@/server/lib/panels/build.server';
+import { toManifest } from '@/server/lib/panels/manifest';
+import { packageDir } from '@/server/lib/fs/package-root';
+
+const BUNDLED_PLUGIN = 'marketplace/plugins/session-info';
+
+/** The example plugin, copied out of the repo so a build cannot write into it. */
+async function copyExample(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'omp-plugin-build-'));
+  await cp(join(packageDir(), BUNDLED_PLUGIN), join(dir, 'session-info'), { recursive: true });
+  return join(dir, 'session-info');
+}
+
+describe('buildPanelPlugin with a server entry', () => {
+  test('a plugin declaring both app and server produces both bundles', async () => {
+    const root = await copyExample();
+    try {
+      const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) as { kabmo: unknown };
+      const manifest = toManifest(pkg.kabmo, root);
+      expect('error' in manifest).toBe(false);
+      if ('error' in manifest) return;
+
+      const result = await buildPanelPlugin(root, manifest);
+      expect(result.status).toBe('built');
+
+      // The app half is shimmed for the browser: it must NOT carry a Preact of
+      // its own, and it must read the host runtime.
+      const app = await readFile(join(root, manifest.app ?? ''), 'utf8');
+      expect(app).toContain('__kabmoPluginRuntime');
+      expect(app).not.toContain('preact/src');
+
+      // The server half is bundled for Bun and carries its dependency: it is
+      // imported by absolute path, so nothing would resolve an external one.
+      const server = await readFile(join(root, manifest.server ?? ''), 'utf8');
+      expect(server).toContain('session-info server half loaded');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }, 240_000);
+
+  test('a plugin whose server source is missing its declared entry reports the file by name', async () => {
+    const root = await copyExample();
+    try {
+      const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')) as {
+        kabmo: Record<string, unknown>;
+      };
+      // Declare a server entry nothing produces: the build must report THAT
+      // file rather than a generic failure, or the author has nothing to fix.
+      pkg.kabmo.server = 'dist/other.js';
+      await writeFile(join(root, 'package.json'), JSON.stringify(pkg, null, 2));
+
+      const manifest = toManifest(pkg.kabmo, root);
+      expect('error' in manifest).toBe(false);
+      if ('error' in manifest) return;
+
+      const result = await buildPanelPlugin(root, manifest);
+      expect(result.status).toBe('failed');
+      expect(result.reason).toContain('dist/other.js');
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  }, 240_000);
+});

package/src/server/lib/plugins/e2e.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The whole server half, on a real plugin: build → load → call → dispose.
+ *
+ * The fixture is the bundled example, COPIED into a temp marketplace and built
+ * there, because that is the only path that exercises what a real install does.
+ * A test that imported `server.ts` directly would skip the build, the manifest
+ * resolution and the registry's own admission — which is where the failures
+ * this suite exists for actually live.
+ *
+ * The environment override (`KABMO_MARKETPLACE_DIR`) is the seam: the
+ * registry resolves the working marketplace from it, so the test never touches
+ * the developer's own `~/.kabmo`.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { cp, mkdir, mkdtemp, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+import { packageDir } from '@/server/lib/fs/package-root';
+import { invalidatePanelScan } from '@/server/lib/panels/registry.server';
+import { buildPanelPlugin } from '@/server/lib/panels/build.server';
+import { toManifest } from '@/server/lib/panels/manifest';
+import { loadPluginServer, disposePlugin, loadedPluginIds, pluginLoadErrors } from '@/server/lib/plugins/loader.server';
+import { callRpcMethod } from '@/server/lib/plugins/rpc.server';
+import { pluginTopicValue } from '@/server/lib/plugins/realtime.server';
+import { findHttpRoute } from '@/server/lib/plugins/http.server';
+
+const PLUGIN_ID = 'session-info';
+let marketplaceRoot = '';
+let previousOverride: string | undefined;
+
+beforeAll(async () => {
+  marketplaceRoot = await mkdtemp(join(tmpdir(), 'omp-plugin-e2e-'));
+  previousOverride = Bun.env.KABMO_MARKETPLACE_DIR;
+  Bun.env.KABMO_MARKETPLACE_DIR = marketplaceRoot;
+  isolateDb();
+
+  // Copy the bundled plugin into the working marketplace and build it there —
+  // the same two steps an install performs.
+  const pluginsRoot = join(marketplaceRoot, 'plugins');
+  await mkdir(pluginsRoot, { recursive: true });
+  const target = join(pluginsRoot, PLUGIN_ID);
+  await cp(join(packageDir(), 'marketplace/plugins', PLUGIN_ID), target, { recursive: true });
+
+  const pkg = (await Bun.file(join(target, 'package.json')).json()) as { kabmo: unknown };
+  const manifest = toManifest(pkg.kabmo, target);
+  if ('error' in manifest) throw new Error(manifest.error);
+  const built = await buildPanelPlugin(target, manifest);
+  if (built.status !== 'built') throw new Error(`fixture build failed: ${built.reason}`);
+  invalidatePanelScan();
+}, 240_000);
+
+afterAll(async () => {
+  await disposePlugin(PLUGIN_ID);
+  releaseDb();
+  if (previousOverride === undefined) delete Bun.env.KABMO_MARKETPLACE_DIR;
+  else Bun.env.KABMO_MARKETPLACE_DIR = previousOverride;
+  await rm(marketplaceRoot, { recursive: true, force: true });
+});
+
+describe('a real plugin server half', () => {
+  test('loads through the registry and registers everything it declared', async () => {
+    const record = await loadPluginServer(PLUGIN_ID);
+    expect(record.pluginId).toBe(PLUGIN_ID);
+    expect(loadedPluginIds()).toContain(PLUGIN_ID);
+    expect(pluginLoadErrors()).toEqual([]);
+    // The example registers one HTTP route and seeds its topic at load.
+    expect(findHttpRoute(PLUGIN_ID, '/notes')).toBeDefined();
+    expect(pluginTopicValue(PLUGIN_ID)).toEqual({ noteCount: 0 });
+  });
+
+  test('an RPC call reaches the plugin and writes to its own storage', async () => {
+    const context = { url: 'http://localhost/api/plugins/session-info/rpc/save', signal: new AbortController().signal };
+
+    const saved = await callRpcMethod(PLUGIN_ID, 'save', { sessionId: 's-1', note: 'hello' }, context);
+    expect(saved).toEqual({ ok: true, value: { saved: true } });
+
+    // The write is visible through the plugin's OWN read method...
+    const read = await callRpcMethod(PLUGIN_ID, 'get', 's-1', context);
+    expect(read.ok).toBe(true);
+    if (read.ok && read.value && typeof read.value === 'object' && 'note' in read.value) {
+      expect(read.value.note).toBe('hello');
+    } else {
+      throw new Error(`the plugin's get answered ${JSON.stringify(read)}`);
+    }
+
+    // ...and the topic moved, because the handler publishes the count.
+    expect(pluginTopicValue(PLUGIN_ID)).toEqual({ noteCount: 1 });
+  });
+
+  test('the input schema refuses a bad argument before the handler runs', async () => {
+    const context = { url: 'http://x', signal: new AbortController().signal };
+    const bad = await callRpcMethod(PLUGIN_ID, 'save', { sessionId: 's-1', note: 42 }, context);
+    expect(bad.ok).toBe(false);
+    if (!bad.ok) {
+      expect(bad.error.code).toBe('invalid_input');
+      expect(bad.error.issues?.[0]?.message).toContain('note must be a string');
+    }
+  });
+
+  test('the HTTP route answers a real Request', async () => {
+    const route = findHttpRoute(PLUGIN_ID, '/notes');
+    expect(route).toBeDefined();
+    const response = await route!.handler(new Request('http://localhost/api/plugins/session-info/http/notes'));
+    expect(response.status).toBe(200);
+    const body: unknown = await response.json();
+    expect(body).toEqual({ method: 'GET', count: 1, ids: ['s-1'] });
+  });
+
+  test('an undeclared path is absent rather than prefix-matched', () => {
+    expect(findHttpRoute(PLUGIN_ID, '/notes/detail')).toBeUndefined();
+    expect(findHttpRoute(PLUGIN_ID, '/')).toBeUndefined();
+  });
+
+  test('disposal takes every registration back', async () => {
+    await disposePlugin(PLUGIN_ID);
+
+    expect(loadedPluginIds()).not.toContain(PLUGIN_ID);
+    expect(findHttpRoute(PLUGIN_ID, '/notes')).toBeUndefined();
+    expect(pluginTopicValue(PLUGIN_ID)).toBeUndefined();
+    const after = await callRpcMethod(PLUGIN_ID, 'save', { sessionId: 's-1', note: 'x' }, {
+      url: 'http://x',
+      signal: new AbortController().signal,
+    });
+    expect(after.ok).toBe(false);
+    if (!after.ok) expect(after.error.code).toBe('unknown_method');
+  });
+});

package/src/server/lib/plugins/events.server.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A plugin's event surface.
+ *
+ * The Kabmo's signal bus is a CLOSED union (`RealtimeSignal`), and that is a
+ * property worth keeping: a listener for a name that does not exist is a
+ * subscription to nothing, and the union is what makes the compiler say so for
+ * Kabmo's own code. A plugin's event names are therefore held in their
+ * own map rather than being forced into the union — a plugin may announce any
+ * name, and two plugins announcing `ready` are two channels because the plugin
+ * id is part of the key.
+ *
+ * What a plugin does NOT get is a name that collides with Kabmo's own.
+ * Every key here is prefixed, so `ready` from a plugin can never reach a
+ * listener Kabmo registered for its own `ready`.
+ */
+
+import type { PluginEventsApi, PluginJson } from '@kabmo-labs/kabmo-sdk';
+
+type Listener = (payload: PluginJson | undefined) => void;
+
+/**
+ * The listeners, keyed `<pluginId>\0<name>`.
+ *
+ * Process-wide for the same reason every other plugin registry is: under
+ * `bun --hot` this module re-evaluates while a loaded plugin still holds the
+ * unsubscribe it was handed, and a module-level map would come back empty —
+ * the unsubscribe would then be a no-op against a registry nobody reads.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoPluginEventListeners: Map<string, Set<Listener>> | undefined;
+}
+
+const eventKey = (pluginId: string, name: string) => `${pluginId}\u0000${name}`;
+
+function listeners(): Map<string, Set<Listener>> {
+  return (globalThis.__kabmoPluginEventListeners ??= new Map());
+}
+
+/** The API one plugin is handed at load. */
+export function createPluginEvents(pluginId: string): PluginEventsApi {
+  return {
+    on<T = PluginJson>(name: string, listener: (payload: T) => void) {
+      const map = listeners();
+      const key = eventKey(pluginId, name);
+      const set = map.get(key) ?? new Set<Listener>();
+      set.add(listener as Listener);
+      map.set(key, set);
+      return () => {
+        set.delete(listener as Listener);
+        // The empty set is removed rather than kept: a plugin that unsubscribes
+        // everything should not leave a key behind that a later listener would
+        // find already present.
+        if (set.size === 0) map.delete(key);
+      };
+    },
+    emit(name, payload) {
+      // A throwing listener never stops the others — the rule Kabmo's own
+      // signal bus follows, for the same reason: this sits on a write path.
+      for (const listener of [...(listeners().get(eventKey(pluginId, name)) ?? [])]) {
+        try {
+          listener(payload);
+        } catch {
+          // Deliberately swallowed: see above.
+        }
+      }
+    },
+  };
+}
+
+/** Drop every listener a plugin registered — called from its disposal pass. */
+export function clearPluginEvents(pluginId: string): void {
+  const map = listeners();
+  const prefix = `${pluginId}\u0000`;
+  for (const key of [...map.keys()]) {
+    if (key.startsWith(prefix)) map.delete(key);
+  }
+}
+
+/** Test seam: forget every registration. */
+export function resetPluginEvents(): void {
+  listeners().clear();
+}

package/src/server/lib/plugins/http.server.ts

@@ -0,0 +1,112 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A plugin's own HTTP surface, under `/api/plugins/<id>/http/*`.
+ *
+ * Separate from RPC because the two answer different callers. An RPC method is
+ * named and called by the plugin's OWN client half; an HTTP route is a plain
+ * `Request → Response` handler, which is what a webhook receiver, a shareable
+ * URL or a stream needs. A plugin author writes the same shape a route module's
+ * loader is, so there is nothing new to learn.
+ *
+ * Paths are matched EXACTLY (after the plugin's prefix). A prefix rule would
+ * swallow paths the plugin never declared, and since the prefix is the plugin's
+ * own id the failure mode of a loose match is a route answering for another
+ * route's URL — the kind of bug that is invisible until two plugins both use
+ * `/status`.
+ */
+
+import type { PluginHttpApi } from '@kabmo-labs/kabmo-sdk';
+
+/** One registered route: the path as the plugin wrote it, and its handler. */
+export interface RegisteredHttpRoute {
+  pluginId: string;
+  path: string;
+  handler: (request: Request) => Response | Promise<Response>;
+}
+
+/**
+ * The routes, keyed `<pluginId>\0<path>`.
+ *
+ * Process-wide for the reason every other plugin registry is: under `bun --hot`
+ * this module re-evaluates while loaded plugins still hold the disposers they
+ * were handed, and a module-level map would come back empty.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoPluginHttpRoutes: Map<string, RegisteredHttpRoute> | undefined;
+}
+
+const routeKey = (pluginId: string, path: string) => `${pluginId}\u0000${path}`;
+
+function routes(): Map<string, RegisteredHttpRoute> {
+  return (globalThis.__kabmoPluginHttpRoutes ??= new Map());
+}
+
+/** Normalize a declared path: one leading slash, no trailing one. */
+function normalizePath(path: string): string | null {
+  const trimmed = path.trim();
+  if (!trimmed.startsWith('/')) return null;
+  const collapsed = trimmed.replace(/\/+$/, '') || '/';
+  // `..` and a NUL are refused here as well as at the route, because this is
+  // the value that reaches the URL match: a path the plugin could not have
+  // meant is better refused at declaration, where the plugin author sees it.
+  if (collapsed.includes('..') || collapsed.includes('\u0000')) return null;
+  return collapsed;
+}
+
+/** The API one plugin is handed at load. */
+export function createPluginHttp(pluginId: string): PluginHttpApi {
+  return {
+    route(path, handler) {
+      const normalized = normalizePath(path);
+      if (!normalized) throw new Error(`http route "${path}" must be a path starting with "/" and without ".."`);
+      if (typeof handler !== 'function') throw new Error(`http route "${normalized}" has no handler`);
+      const map = routes();
+      const key = routeKey(pluginId, normalized);
+      if (map.has(key)) throw new Error(`http route "${normalized}" is already registered by this plugin`);
+      map.set(key, { pluginId, path: normalized, handler });
+      return () => {
+        map.delete(key);
+      };
+    },
+  };
+}
+
+/**
+ * Resolve a request to a route's handler.
+ *
+ * `path` is what follows `/api/plugins/<id>/http` in the URL. The lookup is a
+ * map hit, never a filesystem read or a prefix walk, so a path the plugin did
+ * not declare is simply absent.
+ */
+export function findHttpRoute(
+  pluginId: string,
+  path: string,
+): RegisteredHttpRoute | undefined {
+  return routes().get(routeKey(pluginId, normalizePath(path) ?? ''));
+}
+
+/** Whether a plugin has any route registered, so the route can 404 early. */
+export function hasHttpRoutes(pluginId: string): boolean {
+  for (const route of routes().values()) {
+    if (route.pluginId === pluginId) return true;
+  }
+  return false;
+}
+
+/** Drop every route a plugin registered — called from its disposal pass. */
+export function clearPluginHttpRoutes(pluginId: string): void {
+  const map = routes();
+  for (const [key, route] of map) {
+    if (route.pluginId === pluginId) map.delete(key);
+  }
+}
+
+/** Test seam: forget every registration. */
+export function resetPluginHttp(): void {
+  routes().clear();
+}