@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/server/routes/panels/bindings.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { bindingsFor, type HandlerBinding } from '@/server/lib/route-adapter';
+import * as panelsRegistry from '@/server/routes/panels/registry';
+import * as panelsBundle from '@/server/routes/panels/bundle';
+import * as panelsCss from '@/server/routes/panels/css';
+import * as panelsIcon from '@/server/routes/panels/icon';
+import * as panelsReadme from '@/server/routes/panels/readme';
+import * as panelsInstall from '@/server/routes/panels/install';
+import * as panelsBuild from '@/server/routes/panels/build';
+
+export const panelsBindings: HandlerBinding[] = [
+  ...bindingsFor(panelsRegistry, '/api/panels'),
+  ...bindingsFor(panelsBundle, '/api/panels/bundle/:plugin'),
+  ...bindingsFor(panelsCss, '/api/panels/css/:plugin'),
+  ...bindingsFor(panelsIcon, '/api/panels/icon/:plugin/*'),
+  ...bindingsFor(panelsReadme, '/api/panels/readme/:plugin/*'),
+  ...bindingsFor(panelsInstall, '/api/panels/install'),
+  ...bindingsFor(panelsBuild, '/api/panels/build'),
+];

package/src/server/routes/panels/build.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `POST /api/panels/build` — run a plugin's build.
+ *
+ * A plugin is a Bun package, so its panels are served from a build output. That
+ * makes "the manifest is valid but the build has not run" a real state a user can
+ * be in — a fresh clone, an interrupted install, a source edit — and this is the
+ * one action that resolves it without re-installing.
+ *
+ * The plugin is named by its id, which the scan resolves to a directory; a
+ * caller never supplies a path, so this cannot be pointed at an arbitrary
+ * package. Answers with the whole payload, like the install route, so the pane
+ * shows the post-build state rather than a guess.
+ */
+
+import { json, type ActionFunctionArgs } from '@/server/lib/remix-compat';
+import { methodNotAllowed } from '@/server/lib/route-adapter';
+import { join } from 'path';
+import {
+  discoverPanelPlugins,
+  getMarketplacePluginsDir,
+  invalidatePanelScan,
+} from '@/server/lib/panels/registry.server';
+import { readPluginManifest } from '@/server/lib/panels/files.server';
+import { buildPanelPlugin } from '@/server/lib/panels/build.server';
+import { toManifest } from '@/server/lib/panels/manifest';
+
+export async function action({ request }: ActionFunctionArgs) {
+  if (request.method !== 'POST') return methodNotAllowed({ request, params: {} });
+
+  let body: Record<string, unknown>;
+  try {
+    body = (await request.json()) as Record<string, unknown>;
+  } catch {
+    return json({ error: 'Expected a JSON body.' }, { status: 400 });
+  }
+
+  const pluginId = typeof body.pluginId === 'string' ? body.pluginId.trim() : '';
+  if (!pluginId) return json({ error: 'A plugin id is required.' }, { status: 400 });
+
+  // Resolved against the scan, not the request: an id that is not installed
+  // cannot name a directory.
+  const { plugins } = await discoverPanelPlugins();
+  const installed = plugins.find((plugin) => plugin.pluginId === pluginId);
+  if (!installed) return json({ error: `No installed plugin with id "${pluginId}".` }, { status: 404 });
+  if (!installed.isPackage) {
+    return json({ error: `${pluginId} is not a Bun package, so it has nothing to build.` }, { status: 400 });
+  }
+
+  const root = join(getMarketplacePluginsDir(), pluginId);
+  const read = await readPluginManifest(root);
+  if (read.kind !== 'manifest') {
+    return json({ error: read.kind === 'error' ? read.reason : 'no manifest found' }, { status: 400 });
+  }
+  const manifest = toManifest(read.value, root);
+  if ('error' in manifest) return json({ error: manifest.error }, { status: 400 });
+
+  const result = await buildPanelPlugin(root, manifest);
+  invalidatePanelScan();
+
+  if (result.status !== 'built') {
+    return json(
+      { error: result.reason ?? 'the build failed', ...(await discoverPanelPlugins()) },
+      { status: 400 },
+    );
+  }
+  return json({ ok: true, ...(await discoverPanelPlugins()) });
+}

package/src/server/routes/panels/bundle.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `GET /api/panels/bundle/:plugin.js` — a plugin's ESM bundle.
+ *
+ * This is the route that makes an in-process plugin possible: the host imports
+ * this URL as a real ES module, so the response must be `text/javascript` with
+ * the module's own bytes, unmodified. Nothing is injected and nothing is
+ * composed — there is no HTML document to build, because there is no frame.
+ *
+ * Two rules are load-bearing:
+ *
+ * - **The plugin is named by its DIRECTORY, and the file comes from the
+ *   REGISTRY.** A request can therefore only ever reach a bundle inside an
+ *   installed, enabled plugin; the caller never supplies a path. A disabled
+ *   plugin has no registry entry and its bundle is a 404, which is what makes
+ *   disabling stop the code rather than only hide the button.
+ * - **`no-store`.** The URL carries a content hash, so the browser's module
+ *   cache is what deduplicates a load — but the HTTP response itself must not be
+ *   cached, or a rebuilt plugin would be served from the old bytes under a URL
+ *   the registry has already changed.
+ */
+
+import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { findPluginDir } from '@/server/lib/panels/registry.server';
+import { pathExists } from '@/server/lib/omp/core/paths';
+import { join } from 'path';
+
+/** Strip a `.js` suffix the route adds for a readable URL. */
+function pluginNameOf(param: string | undefined): string {
+  const value = (param ?? '').trim();
+  return value.endsWith('.js') ? value.slice(0, -3) : value;
+}
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const pluginName = pluginNameOf(params.plugin);
+  if (!pluginName || /[/\\]/.test(pluginName)) return json({ error: 'Not found' }, { status: 404 });
+
+  const dir = await findPluginDir(pluginName);
+  if (!dir) return json({ error: `Unknown plugin: ${pluginName}` }, { status: 404 });
+
+  // The manifest is re-read rather than remembered in the scan: the scan's
+  // payload deliberately carries no filesystem paths, and the bundle's location
+  // is a property of the plugin, not of the request.
+  const manifestPath = join(dir, 'package.json');
+  let app = 'dist/app.js';
+  if (await pathExists(manifestPath)) {
+    const pkg = (await Bun.file(manifestPath).json()) as {
+      kabmo?: { app?: unknown };
+      ompchamber?: { app?: unknown };
+    };
+    const declared = pkg.kabmo?.app ?? pkg.ompchamber?.app;
+    if (typeof declared === 'string') app = declared;
+  }
+
+  const target = join(dir, app);
+  if (!(await pathExists(target))) return json({ error: `Bundle not built: ${app}` }, { status: 404 });
+
+  return new Response(Bun.file(target), {
+    headers: {
+      'content-type': 'text/javascript; charset=utf-8',
+      'cache-control': 'no-store',
+      // The bundle is loaded cross-directive from the app's own origin, so a
+      // MIME sniff must never turn it into something else.
+      'x-content-type-options': 'nosniff',
+    },
+  });
+}

package/src/server/routes/panels/css.test.ts

@@ -0,0 +1,141 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `GET /api/panels/css/:plugin.css` — the plugin stylesheet route.
+ *
+ * The route serves the file WRAPPED in `@scope ([data-plugin-surface="<id>"])`,
+ * and that wrapper is the whole reason this file exists. A plugin's CSS lands in
+ * the host's document, so unscoped it restyled the app: the demo plugin's
+ * `html[data-session-info] .code-block::before` drew a gradient rule over every
+ * code block in the chat, because `.code-block` is the HOST's class and
+ * `html[…]` is an ancestor of everything.
+ *
+ * The scope's id is the MANIFEST id, not the directory name, because that is
+ * what the host marks its surfaces with — a scope rooted at the wrong attribute
+ * applies to nothing, which is silent.
+ *
+ * The other rules are the ones the bundle route follows for the same reasons:
+ * the file comes from the manifest (never a request path), and a disabled plugin
+ * is unreachable so switching it off stops the bytes.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import fs from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { loader as cssLoader } from '@/server/routes/panels/css';
+import { getMarketplacePluginsDir, invalidatePanelScan } from '@/server/lib/panels/registry.server';
+import { setPluginEnabled } from '@/server/lib/panels/state.server';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+
+const MANIFEST = { id: 'demo', name: 'Demo', version: '1.0.0', app: 'dist/app.js', icon: 'icon.svg' };
+
+let root = '';
+let bundled = '';
+
+/** A plugin directory with a bundle, an icon and a README. */
+function writePlugin(dirName: string, dir: string, manifest: unknown = MANIFEST): string {
+  const pluginDir = join(dir, dirName);
+  fs.mkdirSync(join(pluginDir, 'dist'), { recursive: true });
+  fs.writeFileSync(join(pluginDir, 'kabmo.json'), JSON.stringify(manifest));
+  fs.writeFileSync(join(pluginDir, 'dist', 'app.js'), 'export default {};');
+  fs.writeFileSync(join(pluginDir, 'icon.svg'), '<svg></svg>');
+  fs.writeFileSync(join(pluginDir, 'README.md'), '# Demo\n\nHello.');
+  return pluginDir;
+}
+
+/** A plugin whose manifest declares a stylesheet, with the file written. */
+function writeCssPlugin(css: string, id = 'demo'): void {
+  writePlugin('demo', getMarketplacePluginsDir(), { ...MANIFEST, id, css: 'dist/app.css' });
+  fs.writeFileSync(join(getMarketplacePluginsDir(), 'demo', 'dist', 'app.css'), css);
+  invalidatePanelScan();
+}
+
+/** Call a loader with path params, as the router would. */
+function call(loader: (args: never) => unknown, params: Record<string, string>) {
+  return loader({ params, request: new Request('http://local/') } as never) as Promise<Response>;
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(join(tmpdir(), 'omc-panel-css-'));
+  bundled = fs.mkdtempSync(join(tmpdir(), 'omc-panel-store-'));
+  process.env.KABMO_MARKETPLACE_DIR = root;
+  process.env.KABMO_BUNDLED_MARKETPLACE_DIR = bundled;
+  // A database of this suite's own, BEFORE the first scan: the scan reads the
+  // disabled set, and a path set while a cached handle exists is never read.
+  isolateDb();
+  invalidatePanelScan();
+});
+
+afterEach(() => {
+  releaseDb();
+  delete process.env.KABMO_MARKETPLACE_DIR;
+  delete process.env.KABMO_BUNDLED_MARKETPLACE_DIR;
+  invalidatePanelScan();
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(bundled, { recursive: true, force: true });
+});
+
+describe('the css route', () => {
+  test('serves the stylesheet SCOPED to the plugin id', async () => {
+    // The fix for the leak: unscoped, the demo plugin's `html[…]
+    // .code-block::before` drew a rule over every code block in the chat.
+    writeCssPlugin('.badge { color: red; }');
+
+    const response = await call(cssLoader, { plugin: 'demo.css' });
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toContain('text/css');
+
+    const body = await response.text();
+    expect(body).toContain('@scope ([data-plugin-surface="demo"])');
+    expect(body).toContain('.badge { color: red; }');
+  });
+
+  test('scopes under the MANIFEST id, not the directory name', async () => {
+    // The host marks its surfaces with the manifest id (the registry publishes
+    // it as `pluginId`), so a scope built from the URL's basename would root at
+    // an attribute no surface carries — the stylesheet would apply to nothing.
+    writeCssPlugin('.x { color: red; }', 'other-id');
+
+    const body = await (await call(cssLoader, { plugin: 'demo.css' })).text();
+    expect(body).toContain('[data-plugin-surface="other-id"]');
+    expect(body).not.toContain('[data-plugin-surface="demo"]');
+  });
+
+  test('hoists @import above the scope so it is not discarded', async () => {
+    writeCssPlugin('@import url("./other.css");\n.a { color: red; }');
+
+    const body = await (await call(cssLoader, { plugin: 'demo.css' })).text();
+    expect(body.indexOf('@import')).toBeLessThan(body.indexOf('@scope'));
+  });
+
+  test('404s a plugin that declares no stylesheet', async () => {
+    writePlugin('demo', getMarketplacePluginsDir());
+    invalidatePanelScan();
+    expect((await call(cssLoader, { plugin: 'demo.css' })).status).toBe(404);
+  });
+
+  test('404s a declared stylesheet the build did not emit', async () => {
+    writePlugin('demo', getMarketplacePluginsDir(), { ...MANIFEST, css: 'dist/app.css' });
+    invalidatePanelScan();
+    expect((await call(cssLoader, { plugin: 'demo.css' })).status).toBe(404);
+  });
+
+  test('404s a disabled plugin, so disabling stops the stylesheet', async () => {
+    writeCssPlugin('.a { color: red; }');
+    expect((await call(cssLoader, { plugin: 'demo.css' })).status).toBe(200);
+
+    await setPluginEnabled('plugin:demo', false);
+    invalidatePanelScan();
+    expect((await call(cssLoader, { plugin: 'demo.css' })).status).toBe(404);
+  });
+
+  test('refuses a plugin name carrying a path separator', async () => {
+    writeCssPlugin('.a { color: red; }');
+    expect((await call(cssLoader, { plugin: '../demo.css' })).status).toBe(404);
+  });
+});

package/src/server/routes/panels/css.ts

@@ -0,0 +1,89 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `GET /api/panels/css/:plugin.css` — a plugin's stylesheet, SCOPED.
+ *
+ * This route exists because a plugin's imported CSS would otherwise be INERT.
+ * `Bun.build` emits an imported stylesheet beside the bundle (`dist/app.js`
+ * beside `dist/app.css`) and the emitted JS never references it, so the file is
+ * built, never fetched, and silently not applied. Declaring `css` in the
+ * manifest is what makes the host load it — while the plugin has a live
+ * content-script generation, and not otherwise.
+ *
+ * The file is served WRAPPED in `@scope ([data-plugin-surface="<id>"])`, and
+ * that is the load-bearing part. A plugin's CSS lands in the host's document,
+ * so unscoped it restyled the app: the demo plugin's `html[data-session-info]
+ * .code-block::before` drew a gradient rule over every code block in the chat,
+ * because `.code-block` is the HOST's class and `html[…]` is an ancestor of
+ * everything. Scoping it to the plugin's own surfaces makes such a selector
+ * match nothing, which is the honest outcome — see `scopePluginCss`.
+ *
+ * Three rules, the same ones the bundle route follows:
+ *
+ * - **The plugin is named by its DIRECTORY, and the file comes from the
+ *   MANIFEST.** A request can only reach a stylesheet an installed, enabled
+ *   plugin declared; the caller never supplies a path. A disabled plugin has no
+ *   registry entry and its CSS is a 404, which is what keeps a switched-off
+ *   plugin's rules out of the document.
+ * - **The URL carries a content hash, so a long cache is correct.** A rebuilt
+ *   plugin with changed rules reaches a new URL; the same URL always means the
+ *   same bytes. That is the opposite of the bundle's `no-store`, and for the
+ *   same underlying reason — the module cache keys on URL, so the URL is what
+ *   has to change.
+ * - **The scope id is the MANIFEST id, not the directory name.** The host marks
+ *   its surfaces with `manifest.id` (that is what the registry publishes as
+ *   `pluginId`), so a scope built from the URL's basename would root at an
+ *   attribute no surface carries and the stylesheet would apply to nothing.
+ */
+
+import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { findPluginDir } from '@/server/lib/panels/registry.server';
+import { readPluginManifest } from '@/server/lib/panels/files.server';
+import { toManifest } from '@/server/lib/panels/manifest';
+import { pathExists } from '@/server/lib/omp/core/paths';
+import { scopePluginCss } from '@/shared/lib/panels/css-scope';
+import { join } from 'path';
+
+/** Strip the `.css` suffix the route adds for a readable URL. */
+function pluginNameOf(param: string | undefined): string {
+  const value = (param ?? '').trim();
+  return value.endsWith('.css') ? value.slice(0, -4) : value;
+}
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const pluginName = pluginNameOf(params.plugin);
+  if (!pluginName || /[/\\]/.test(pluginName)) return json({ error: 'Not found' }, { status: 404 });
+
+  const dir = await findPluginDir(pluginName);
+  if (!dir) return json({ error: `Unknown plugin: ${pluginName}` }, { status: 404 });
+
+  // Re-read rather than remembered in the scan: the scan's payload carries no
+  // filesystem paths, and the stylesheet's location — and the id the scope is
+  // rooted at — are properties of the plugin, not of the request.
+  const read = await readPluginManifest(dir);
+  if (read.kind !== 'manifest') return json({ error: 'Plugin declares no stylesheet' }, { status: 404 });
+  const manifest = toManifest(read.value, dir);
+  if ('error' in manifest || !manifest.css) {
+    return json({ error: 'Plugin declares no stylesheet' }, { status: 404 });
+  }
+
+  const target = join(dir, manifest.css);
+  if (!(await pathExists(target))) {
+    return json({ error: `Stylesheet not built: ${manifest.css}` }, { status: 404 });
+  }
+
+  // Read as TEXT, not streamed as a file: the scope wrapper is a transform, so
+  // the bytes served are not the bytes on disk.
+  const css = await Bun.file(target).text();
+  return new Response(scopePluginCss(css, manifest.id), {
+    headers: {
+      'content-type': 'text/css; charset=utf-8',
+      'cache-control': 'public, max-age=3600',
+      // A stylesheet is a MIME-sniffable resource on the app's own origin.
+      'x-content-type-options': 'nosniff',
+    },
+  });
+}

package/src/server/routes/panels/icon.ts

@@ -0,0 +1,64 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `GET /api/panels/icon/:plugin/<path>` — one icon file from a plugin's own
+ * directory.
+ *
+ * The plugin is named by its DIRECTORY and the path is resolved INSIDE that
+ * directory, so a request can only ever reach a file an installed plugin ships.
+ * A `../` segment is refused even though the manifest that named the icon was
+ * already validated — the URL is a second entrance, and it is the one an
+ * attacker controls.
+ *
+ * Images only. A plugin's bundle is served by its own route with the right
+ * content type; this one exists so a button can draw a plugin's mark.
+ */
+
+import { extname } from 'path';
+import { json, type LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { findPluginDir } from '@/server/lib/panels/registry.server';
+import { pathExists } from '@/server/lib/omp/core/paths';
+import { resolveInsideRoot } from '@/shared/lib/panels/resolve-asset';
+
+const CONTENT_TYPES: Record<string, string> = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+const MAX_ICON_BYTES = 512 * 1024;
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const pluginName = (params.plugin ?? '').trim();
+  const rel = (params['*'] ?? '').replace(/^\/+/, '');
+  if (!pluginName || /[/\\]/.test(pluginName) || !rel) return json({ error: 'Not found' }, { status: 404 });
+
+  const dir = await findPluginDir(pluginName);
+  if (!dir) return json({ error: `Unknown plugin: ${pluginName}` }, { status: 404 });
+
+  const target = resolveInsideRoot(dir, rel);
+  if (!target) return json({ error: 'Path escapes the plugin directory' }, { status: 403 });
+
+  const contentType = CONTENT_TYPES[extname(target).toLowerCase()];
+  if (!contentType) return json({ error: 'Unsupported icon type' }, { status: 415 });
+  if (!(await pathExists(target))) return json({ error: 'Icon not found' }, { status: 404 });
+
+  const file = Bun.file(target);
+  if (file.size > MAX_ICON_BYTES) return json({ error: 'Icon is too large' }, { status: 413 });
+
+  return new Response(file, {
+    headers: {
+      'content-type': contentType,
+      // The URL carries a content hash, so a long cache is safe and correct: a
+      // changed icon is a changed URL.
+      'cache-control': 'public, max-age=3600',
+      'x-content-type-options': 'nosniff',
+    },
+  });
+}