@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/server/lib/panels/manifest.ts

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Validation for panel-plugin manifests and marketplace catalogs.
+ *
+ * Pure: every function takes an already-parsed JSON value and a root path, and
+ * returns either a normalized value or the sentence explaining why it was
+ * refused. Nothing here touches the filesystem, which is what makes the rules
+ * testable without a fixture tree — and the rules are the part that matters,
+ * because every one of them is a refusal that would otherwise be silent.
+ *
+ * A manifest no longer declares PANELS. A plugin's UI is what its bundle
+ * registers when it loads, so the manifest carries only what the HOST needs
+ * before the code runs: an identity, an icon, and the bundle to import. Slot
+ * titles and positions come from the registration — which is also why the
+ * server cannot list a plugin's panels and the client lists what loaded.
+ */
+
+import type {
+  PanelMarketplaceManifest,
+  PanelMarketplacePluginEntry,
+  PanelPluginManifest,
+} from '@/shared/types';
+import type { PluginSettingDefinition } from '@kabmo-labs/kabmo-sdk';
+import { isRecord } from '@/shared/lib/util/guards';
+import { isValidRange } from '@/shared/lib/updates/semver';
+import { resolveInsideRoot } from '@/shared/lib/panels/resolve-asset';
+
+/** An id segment: what a plugin id may look like. */
+const ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+
+function trimmed(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Parse a plugin manifest body.
+ *
+ * `app` and `server` name BUILT files (`dist/app.js`, `dist/server.js`), not
+ * sources, and each must resolve inside the plugin's own directory: a value
+ * becomes a filesystem read on the asset route, so an absolute path or a `../`
+ * segment would turn one plugin's manifest into a read of any file the server
+ * can open. `icon` is held to the same rule for the same reason.
+ *
+ * `engines` is where the honesty lives: a range that is NOT a range is a
+ * refusal here rather than a pass, because a range the host cannot read would
+ * otherwise be silently ignored and the plugin admitted on a requirement
+ * nobody checked. Whether the range is SATISFIED is a separate question — this
+ * module owns the shape, the scan owns the comparison.
+ */
+export function toManifest(raw: unknown, root: string): PanelPluginManifest | { error: string } {
+  if (!isRecord(raw)) return { error: 'manifest is not an object' };
+  const id = trimmed(raw.id);
+  const name = trimmed(raw.name);
+  const version = trimmed(raw.version);
+  const app = trimmed(raw.app);
+  const server = trimmed(raw.server);
+  if (!id || !ID_RE.test(id)) return { error: `manifest id ${JSON.stringify(raw.id)} is missing or invalid` };
+  if (!name) return { error: 'manifest has no name' };
+  if (!version) return { error: 'manifest has no version' };
+  // A plugin must declare something the host can run. A server-only plugin is
+  // the reason this is not simply "no app".
+  if (!app && !server) return { error: 'manifest has no "app" bundle or "server" entry' };
+  if (app && !resolveInsideRoot(root, app)) return { error: `manifest app "${app}" escapes the plugin directory` };
+  const css = trimmed(raw.css);
+  if (css && !resolveInsideRoot(root, css)) {
+    return { error: `manifest css "${css}" escapes the plugin directory` };
+  }
+  if (server && !resolveInsideRoot(root, server)) {
+    return { error: `manifest server "${server}" escapes the plugin directory` };
+  }
+
+  const icon = trimmed(raw.icon);
+  if (icon && !resolveInsideRoot(root, icon)) {
+    return { error: `manifest icon "${icon}" escapes the plugin directory` };
+  }
+
+  const readme = trimmed(raw.readme);
+  if (readme && !resolveInsideRoot(root, readme)) {
+    return { error: `manifest readme "${readme}" escapes the plugin directory` };
+  }
+
+  const branding = isRecord(raw.branding) ? trimmed(raw.branding.icon) : undefined;
+  const engines = toEngines(raw.engines);
+  if ('error' in engines) return engines;
+  const capabilities = toCapabilities(raw.capabilities);
+  if ('error' in capabilities) return capabilities;
+  const settings = toSettings(raw.settings);
+  if ('error' in settings) return settings;
+
+  return {
+    id,
+    name,
+    version,
+    ...(app ? { app } : {}),
+    ...(css ? { css } : {}),
+    ...(server ? { server } : {}),
+    ...(settings.value ? { settings: settings.value } : {}),
+    ...(engines.value ? { engines: engines.value } : {}),
+    ...(capabilities.value ? { capabilities: capabilities.value } : {}),
+    ...(trimmed(raw.description) ? { description: trimmed(raw.description) } : {}),
+    ...(trimmed(raw.homepage) ? { homepage: trimmed(raw.homepage) } : {}),
+    ...(icon ? { icon } : {}),
+    ...(readme ? { readme } : {}),
+    ...(branding ? { branding: { icon: branding } } : {}),
+  };
+}
+
+/**
+ * Validate `engines`: an optional object of the two host keys, each a range the
+ * module can read. An unknown key is a refusal rather than a silent ignore —
+ * `engines.kabmoSdk` is a typo that would otherwise remove the requirement
+ * the author meant to state.
+ *
+ * `ompchamber` is the pre-rename spelling of `kabmo` and is accepted as an
+ * alias, because a plugin written before the rename declares it and refusing
+ * the key would refuse the plugin. It is NORMALIZED to `kabmo`, so the scan
+ * compares one key and the two spellings cannot disagree.
+ */
+function toEngines(
+  raw: unknown,
+): { value?: { kabmo?: string; pluginSdk?: string } } | { error: string } {
+  if (raw === undefined) return {};
+  if (!isRecord(raw)) return { error: `manifest engines ${JSON.stringify(raw)} is not an object` };
+  const value: { kabmo?: string; pluginSdk?: string } = {};
+  for (const [key, entry] of Object.entries(raw)) {
+    const normalized = key === 'ompchamber' ? 'kabmo' : key;
+    if (normalized !== 'kabmo' && normalized !== 'pluginSdk') {
+      return { error: `manifest engines has an unknown key ${JSON.stringify(key)}` };
+    }
+    const range = trimmed(entry);
+    if (!range) return { error: `manifest engines.${key} ${JSON.stringify(entry)} is not a version range` };
+    if (!isValidRange(range)) {
+      return { error: `manifest engines.${key} "${range}" is not a valid version range` };
+    }
+    value[normalized] = range;
+  }
+  return Object.keys(value).length > 0 ? { value } : {};
+}
+
+/** Validate `capabilities`: an optional array of non-empty capability names. */
+function toCapabilities(raw: unknown): { value?: string[] } | { error: string } {
+  if (raw === undefined) return {};
+  if (!Array.isArray(raw)) return { error: `manifest capabilities ${JSON.stringify(raw)} is not an array` };
+  const value: string[] = [];
+  for (const entry of raw) {
+    const capability = trimmed(entry);
+    if (!capability) return { error: `manifest capabilities has an invalid entry ${JSON.stringify(entry)}` };
+    value.push(capability);
+  }
+  return value.length > 0 ? { value } : {};
+}
+
+/** Whether a value is one of the three primitives a setting may hold. */
+function isSettingValue(value: unknown): value is string | number | boolean {
+  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+
+/** Whether a value is one of the three setting types the host can render. */
+function isSettingType(value: unknown): value is PluginSettingDefinition['type'] {
+  return value === 'string' || value === 'number' || value === 'boolean';
+}
+
+/**
+ * Validate `settings`: an optional map of setting name → definition.
+ *
+ * Only the fields the host renders or validates are read, and each is checked
+ * rather than copied: a definition the host cannot render is worse than a
+ * refused one, because the pane would draw a form that writes a value the
+ * plugin's own contract says is the wrong shape.
+ */
+function toSettings(raw: unknown): { value?: Record<string, PluginSettingDefinition> } | { error: string } {
+  if (raw === undefined) return {};
+  if (!isRecord(raw)) return { error: `manifest settings ${JSON.stringify(raw)} is not an object` };
+  const value: Record<string, PluginSettingDefinition> = {};
+  for (const [key, entry] of Object.entries(raw)) {
+    if (!isRecord(entry)) return { error: `manifest settings "${key}" is not an object` };
+    const type = entry.type;
+    if (!isSettingType(type)) {
+      return { error: `manifest settings "${key}" has an unknown type ${JSON.stringify(type)}` };
+    }
+    const label = trimmed(entry.label);
+    if (!label) return { error: `manifest settings "${key}" has no label` };
+    const description = trimmed(entry.description);
+    const fallback = entry.default;
+    if (fallback !== undefined && !isSettingValue(fallback)) {
+      return { error: `manifest settings "${key}" has an invalid default ${JSON.stringify(fallback)}` };
+    }
+    const secret = entry.secret;
+    if (secret !== undefined && typeof secret !== 'boolean') {
+      return { error: `manifest settings "${key}" has an invalid secret ${JSON.stringify(secret)}` };
+    }
+    value[key] = {
+      type,
+      label,
+      ...(description ? { description } : {}),
+      ...(fallback !== undefined ? { default: fallback } : {}),
+      ...(secret !== undefined ? { secret } : {}),
+    };
+  }
+  return Object.keys(value).length > 0 ? { value } : {};
+}
+
+/**
+ * Parse a marketplace catalog.
+ *
+ * A catalog is optional metadata: its job is descriptions and grouping for
+ * plugins that are found on disk anyway, so a catalog that is absent or has no
+ * `plugins` array is a valid, empty catalog rather than an error. What is NOT
+ * optional is a catalog entry's `source` — it is the key that binds an entry to
+ * a directory, and an entry whose source escapes the marketplace root would let
+ * the catalog point at anything.
+ */
+export function toMarketplaceCatalog(raw: unknown, root: string): PanelMarketplaceManifest | { error: string } {
+  if (!isRecord(raw)) return { error: 'marketplace.json is not an object' };
+  const entries: PanelMarketplacePluginEntry[] = [];
+  const rawPlugins = raw.plugins;
+  if (rawPlugins !== undefined) {
+    if (!Array.isArray(rawPlugins)) return { error: 'marketplace.json "plugins" must be an array' };
+    for (const item of rawPlugins) {
+      if (!isRecord(item)) return { error: 'a marketplace plugin entry is not an object' };
+      const name = trimmed(item.name);
+      const source = trimmed(item.source);
+      if (!name) return { error: 'a marketplace plugin entry has no name' };
+      if (!source) return { error: `marketplace plugin "${name}" has no source` };
+      if (!resolveInsideRoot(root, source)) {
+        return { error: `marketplace plugin "${name}" source "${source}" escapes the marketplace directory` };
+      }
+      entries.push({
+        name,
+        source,
+        description: trimmed(item.description),
+        version: trimmed(item.version),
+        category: trimmed(item.category),
+      });
+    }
+  }
+  const owner = isRecord(raw.owner) ? { name: trimmed(raw.owner.name) } : undefined;
+  return {
+    name: trimmed(raw.name),
+    description: trimmed(raw.description),
+    ...(owner ? { owner } : {}),
+    plugins: entries,
+  };
+}

package/src/server/lib/panels/registry-bundled.server.test.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The bundled marketplace as a STORE.
+ *
+ * A plugin the package ships is an OFFER, not an install: it appears in the
+ * catalog, contributes nothing to the activity bar, and is never scanned as a
+ * panel. Installing it copies it into the working marketplace, where the scan
+ * picks it up as an ordinary install. The two facts this file pins are the ones
+ * a wrong answer hides: a store entry must not contribute a button before it is
+ * installed, and once installed it must be attributed to the store so the pane
+ * offers the right removal.
+ *
+ * Split from `registry.server.test.ts` because the two suites exercise different
+ * questions — that one is the working marketplace's scan rules, this one is the
+ * store list — and each needs its own fixture tree.
+ */
+
+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 { discoverPanelPlugins, invalidatePanelScan } from '@/server/lib/panels/registry.server';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+
+const VALID = { id: 'demo', name: 'Demo', version: '1.0.0', app: 'dist/app.js' };
+
+let root = '';
+
+/** A plugin directory in the WORKING marketplace, with its bundle. */
+function writeInstalled(dirName: string, manifest: unknown): void {
+  const dir = join(root, 'plugins', dirName);
+  fs.mkdirSync(join(dir, 'dist'), { recursive: true });
+  fs.writeFileSync(join(dir, 'kabmo.json'), JSON.stringify(manifest));
+  fs.writeFileSync(join(dir, 'dist', 'app.js'), 'export default {};');
+}
+
+/** A store directory holding one offer, and the env override that points at it. */
+function withStore(run: (bundled: string) => Promise<void>): Promise<void> {
+  const bundled = fs.mkdtempSync(join(root, 'bundled-'));
+  fs.mkdirSync(join(bundled, 'plugins', 'offer'), { recursive: true });
+  fs.writeFileSync(join(bundled, 'plugins', 'offer', 'kabmo.json'), JSON.stringify({ ...VALID, id: 'offer' }));
+  const previous = process.env.KABMO_BUNDLED_MARKETPLACE_DIR;
+  process.env.KABMO_BUNDLED_MARKETPLACE_DIR = bundled;
+  return run(bundled).finally(() => {
+    if (previous === undefined) delete process.env.KABMO_BUNDLED_MARKETPLACE_DIR;
+    else process.env.KABMO_BUNDLED_MARKETPLACE_DIR = previous;
+    fs.rmSync(bundled, { recursive: true, force: true });
+  });
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(join(tmpdir(), 'kabmo-store-'));
+  process.env.KABMO_MARKETPLACE_DIR = root;
+  // The scan reads the disabled set, so it needs a database of its own before
+  // the first read — see `@/test-support/isolated-db`.
+  isolateDb();
+  invalidatePanelScan();
+});
+
+afterEach(() => {
+  delete process.env.KABMO_MARKETPLACE_DIR;
+  releaseDb();
+  invalidatePanelScan();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('the bundled marketplace catalog', () => {
+  test('lists bundled plugins that are not installed, without scanning them as panels', async () => {
+    await withStore(async () => {
+      invalidatePanelScan();
+      const payload = await discoverPanelPlugins();
+      // Available, and nothing more: the store does not contribute a button.
+      expect(payload.catalog.map((entry) => entry.pluginId)).toEqual(['offer']);
+      expect(payload.catalog[0].installed).toBe(false);
+      // What a plugin CONTRIBUTES is known only once its bundle loads, so a
+      // store entry carries the identity alone — there is nothing to promise.
+      expect(payload.panels).toEqual([]);
+    });
+  });
+
+  test('marks a bundled plugin installed once it is present in the working marketplace', async () => {
+    await withStore(async (bundled) => {
+      // The same id, installed: the working copy is what the scan reads, and the
+      // store entry now reports itself as installed.
+      const dir = join(bundled, 'plugins', 'offer');
+      writeInstalled('offer', { ...VALID, id: 'offer' });
+      expect(fs.existsSync(dir)).toBe(true);
+      invalidatePanelScan();
+      const payload = await discoverPanelPlugins();
+      expect(payload.catalog[0].installed).toBe(true);
+      expect(payload.plugins[0].bundled).toBe(true);
+    });
+  });
+});

package/src/server/lib/panels/registry.server.test.ts

@@ -0,0 +1,315 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Panel-plugin discovery for the single bundled marketplace.
+ *
+ * The rules pinned here are the ones a wrong answer makes invisible:
+ *
+ * - a manifest naming a path that escapes its own root must be REJECTED, not
+ *   served — the asset route would otherwise read any file the server can open;
+ * - a directory with no manifest is not a plugin, so the root may hold a README;
+ * - a directory that IS a plugin but is broken must be REPORTED with its reason;
+ * - a plugin present under `plugins/` but absent from the catalog still loads —
+ *   that is what makes a hand-copied folder work;
+ * - a catalog entry naming a missing directory is reported, because the file says "installed";
+ * - a duplicate panel key is dropped and reported;
+ * - the cache is invalidated explicitly, so an install appears without a restart;
+ * - the disabled set is keyed by the PREFIXED panel id, one list for both kinds;
+ * - an unsatisfiable `engines` range or a capability this host lacks is refused
+ *   BY NAME, with both sides of the comparison in the reason.
+ */
+
+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 {
+  discoverPanelPlugins,
+  findPluginDir,
+  getMarketplaceCatalogPath,
+  getMarketplaceDir,
+  getMarketplacePluginsDir,
+  invalidatePanelScan,
+} from '@/server/lib/panels/registry.server';
+import { setPluginEnabled } from '@/server/lib/panels/state.server';
+import { isolateDb, releaseDb } from '@/test-support/isolated-db';
+
+let root = '';
+
+const VALID = {
+  id: 'demo',
+  name: 'Demo',
+  version: '1.0.0',
+  app: 'dist/app.js',
+};
+
+function writeCatalog(catalog: unknown): void {
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(getMarketplaceCatalogPath(), JSON.stringify(catalog));
+}
+
+function writePlugin(dirName: string, manifest: unknown): string {
+  const dir = join(getMarketplacePluginsDir(), dirName);
+  fs.mkdirSync(join(dir, 'dist'), { recursive: true });
+  fs.writeFileSync(join(dir, 'kabmo.json'), JSON.stringify(manifest));
+  // The scan only publishes a plugin whose bundle exists; an unbuilt one is
+  // reported as UNBUILT, which is a different list.
+  fs.writeFileSync(join(dir, 'dist', 'app.js'), 'export default {};');
+  return dir;
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(join(tmpdir(), 'kabmo-marketplace-'));
+  process.env.KABMO_MARKETPLACE_DIR = root;
+  // The scan reads the disabled set, which is a DATABASE read — so the suite
+  // needs a database of its own before the first scan, or it opens the real one
+  // and a `setPluginEnabled` below rewrites a live install.
+  isolateDb();
+  invalidatePanelScan();
+});
+
+afterEach(() => {
+  delete process.env.KABMO_MARKETPLACE_DIR;
+  releaseDb();
+  invalidatePanelScan();
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('getMarketplaceDir', () => {
+  test('honours the override so a test never reads the real marketplace', () => {
+    expect(getMarketplaceDir()).toBe(root);
+    expect(getMarketplacePluginsDir()).toBe(join(root, 'plugins'));
+  });
+});
+
+describe('discoverPanelPlugins', () => {
+  test('a missing marketplace is one empty entry, not an error', async () => {
+    fs.rmSync(root, { recursive: true, force: true });
+    invalidatePanelScan();
+    const payload = await discoverPanelPlugins();
+    expect(payload.panels).toEqual([]);
+    expect(payload.errors).toEqual([]);
+    // The pane still names the marketplace, so its empty state can explain
+    // where a plugin would go.
+    expect(payload.marketplaces).toHaveLength(1);
+    expect(payload.marketplaces[0].id).toBe('kabmo');
+  });
+
+  test('a plugin is loaded and attributed to the marketplace', async () => {
+    writeCatalog({ name: 'Kabmo' });
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { panels, marketplaces, errors } = await discoverPanelPlugins();
+    expect(errors).toEqual([]);
+    expect(panels).toHaveLength(1);
+    expect(panels[0].pluginId).toBe('demo');
+    expect(panels[0].appUrl).toContain('/api/panels/bundle/demo.js');
+    expect(marketplaces[0].panelCount).toBe(1);
+  });
+
+  test('the catalog supplies the marketplace display name and description', async () => {
+    writeCatalog({ name: 'Acme Tools', description: 'Internal panels.' });
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { marketplaces } = await discoverPanelPlugins();
+    expect(marketplaces[0].name).toBe('Acme Tools');
+    expect(marketplaces[0].description).toBe('Internal panels.');
+  });
+
+  test('a plugin absent from the catalog still loads', async () => {
+    writeCatalog({ name: 'Kabmo', plugins: [] });
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { panels, errors } = await discoverPanelPlugins();
+    expect(panels.map((p) => p.pluginId)).toEqual(['demo']);
+    expect(errors).toEqual([]);
+  });
+
+  test('a plugin loads with no catalog at all', async () => {
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { panels, marketplaces } = await discoverPanelPlugins();
+    expect(panels).toHaveLength(1);
+    expect(marketplaces[0].name).toBe('Kabmo');
+  });
+
+  test('a catalog entry pointing at a missing directory is reported', async () => {
+    writeCatalog({ plugins: [{ name: 'ghost', source: 'plugins/ghost' }] });
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors).toHaveLength(1);
+    expect(errors[0].reason).toContain('no plugin was found there');
+    expect(errors[0].marketplace).toBe('kabmo');
+    // The entry's own source rides along: that row is the only rejection a user
+    // can clear from the pane, and the entry is addressed by this path.
+    expect(errors[0].source).toBe('plugins/ghost');
+  });
+
+  test('a rejection that is not a dangling entry carries no source', async () => {
+    // Nothing to forget: the fault is in a manifest that will not parse, and a
+    // button that dropped the record would hide it rather than fix it.
+    const dir = join(getMarketplacePluginsDir(), 'corrupt');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(join(dir, 'kabmo.json'), '{ not json');
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors).toHaveLength(1);
+    expect(errors[0].source).toBeUndefined();
+  });
+
+  test('a catalog entry that escapes the marketplace root is refused', async () => {
+    writeCatalog({ plugins: [{ name: 'evil', source: '../../etc' }] });
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors.some((e) => e.reason.includes('escapes the marketplace directory'))).toBe(true);
+  });
+
+  test('a catalog whose plugins is not an array is reported', async () => {
+    writeCatalog({ plugins: 'nope' });
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors[0].reason).toContain('must be an array');
+  });
+
+  test('a catalog that is not JSON is reported', async () => {
+    fs.mkdirSync(root, { recursive: true });
+    fs.writeFileSync(getMarketplaceCatalogPath(), '{ not json');
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors[0].reason).toContain('not valid JSON');
+  });
+
+  test('a directory with no manifest is skipped silently', async () => {
+    fs.mkdirSync(join(getMarketplacePluginsDir(), 'notes'), { recursive: true });
+    fs.writeFileSync(join(getMarketplacePluginsDir(), 'notes', 'README.md'), 'scratch');
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { panels, errors } = await discoverPanelPlugins();
+    expect(panels).toHaveLength(1);
+    expect(errors.some((e) => e.dir.endsWith('notes'))).toBe(false);
+  });
+
+  test('reads the manifest from package.json#kabmo as well', async () => {
+    const dir = join(getMarketplacePluginsDir(), 'from-pkg');
+    fs.mkdirSync(join(dir, 'dist'), { recursive: true });
+    fs.writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'x', kabmo: VALID }));
+    fs.writeFileSync(join(dir, 'dist', 'app.js'), 'export default {};');
+    invalidatePanelScan();
+    const { panels } = await discoverPanelPlugins();
+    expect(panels).toHaveLength(1);
+  });
+
+  test('a plugin whose app escapes its directory is rejected by name', async () => {
+    writePlugin('escape', { ...VALID, app: '../../etc/passwd' });
+    invalidatePanelScan();
+    const { panels, errors } = await discoverPanelPlugins();
+    expect(panels).toEqual([]);
+    expect(errors[0].reason).toContain('escapes the plugin directory');
+  });
+
+  test('a broken manifest is reported with its reason', async () => {
+    writePlugin('broken', { id: 'broken', name: 'Broken', version: '1.0.0' });
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors[0].reason).toContain('no "app" bundle');
+  });
+
+  test('an unbuilt plugin is listed as not built, not as a rejection', async () => {
+    const dir = join(getMarketplacePluginsDir(), 'unbuilt');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(join(dir, 'kabmo.json'), JSON.stringify(VALID));
+    invalidatePanelScan();
+    const { panels, plugins, errors } = await discoverPanelPlugins();
+    expect(panels).toEqual([]);
+    expect(errors).toEqual([]);
+    expect(plugins[0]).toMatchObject({ pluginId: 'demo', built: false });
+  });
+
+  test('a manifest that exists but is not JSON is reported', async () => {
+    const dir = join(getMarketplacePluginsDir(), 'corrupt');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(join(dir, 'kabmo.json'), '{ not json');
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors[0].reason).toContain('not valid JSON');
+  });
+
+  test('an icon escaping the root is refused rather than served', async () => {
+    writePlugin('bad-icon', { ...VALID, icon: '../../x.svg' });
+    invalidatePanelScan();
+    const { errors } = await discoverPanelPlugins();
+    expect(errors[0].reason).toContain('escapes the plugin directory');
+  });
+
+  test('two directories claiming one plugin id: both are listed, keyed by directory', async () => {
+    // The registry is addressed by DIRECTORY, because that is what the bundle
+    // route can resolve to a file. Two directories with one manifest id is a
+    // packaging mistake, and reporting both is more honest than dropping one.
+    writePlugin('first', VALID);
+    writePlugin('second', VALID);
+    invalidatePanelScan();
+    const { panels } = await discoverPanelPlugins();
+    expect(panels.map((panel) => panel.pluginId)).toEqual(['demo', 'demo']);
+  });
+
+  test('the payload carries no filesystem path, but the dir lookup resolves one', async () => {
+    const dir = writePlugin('demo', VALID);
+    invalidatePanelScan();
+    const { panels } = await discoverPanelPlugins();
+    expect(Object.keys(panels[0])).not.toContain('pluginDir');
+    expect(await findPluginDir('demo')).toBe(dir);
+    expect(await findPluginDir('nope')).toBeUndefined();
+  });
+
+  test('invalidatePanelScan makes a newly written plugin visible', async () => {
+    writePlugin('demo', VALID);
+    invalidatePanelScan();
+    expect((await discoverPanelPlugins()).panels).toHaveLength(1);
+
+    writePlugin('second', { ...VALID, id: 'second' });
+    invalidatePanelScan();
+    expect((await discoverPanelPlugins()).panels).toHaveLength(2);
+  });
+
+  test('a disabled plugin contributes no panels and no dir map entry', async () => {
+    const dir = writePlugin('demo', VALID);
+    await setPluginEnabled('plugin:demo', false);
+    invalidatePanelScan();
+    const payload = await discoverPanelPlugins();
+    expect(payload.panels).toEqual([]);
+    // The bundle route resolves its root from the same scan, so a disabled
+    // plugin's code is unreachable as well as its button being gone.
+    expect(await findPluginDir('demo')).toBeUndefined();
+    // The row survives, with its switch off — that is what lets the user
+    // turn it back on. `enabled` is the SAME verdict the client's panel filter
+    // reaches, because both test the one prefixed key.
+    expect(payload.plugins.find((plugin) => plugin.pluginId === 'demo')?.enabled).toBe(false);
+    // The raw disabled list travels with the payload, because the client is
+    // what resolves a BUILT-IN view's bare id — the server has no built-in
+    // panel list and must not need one.
+    expect(payload.disabledPanels).toEqual(['plugin:demo']);
+
+    await setPluginEnabled('plugin:demo', true);
+    invalidatePanelScan();
+    expect((await discoverPanelPlugins()).panels).toHaveLength(1);
+    expect(await findPluginDir('demo')).toBe(dir);
+  });
+
+  test('a bare built-in view id does not switch a plugin off', async () => {
+    writePlugin('demo', VALID);
+    // The two kinds of panel share ONE list, so the keys must not collide: a
+    // built-in view's bare id must leave every plugin alone.
+    await setPluginEnabled('demo', false);
+    invalidatePanelScan();
+    const payload = await discoverPanelPlugins();
+    expect(payload.disabledPanels).toEqual(['demo']);
+    expect(payload.panels.map((panel) => panel.pluginId)).toEqual(['demo']);
+    expect(payload.plugins[0].enabled).toBe(true);
+  });
+
+});