pixelweaver 0.1.0

package/src/lib/core/plugin-discovery.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  enablePlugin,
+  disablePlugin,
+  isPluginEnabled,
+  _resetForTesting,
+} from './plugin-discovery.js';
+
+describe('plugin-discovery', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should report a plugin as disabled by default', () => {
+    expect(isPluginEnabled('test-plugin')).toBe(false);
+  });
+
+  it('should enable a plugin', () => {
+    enablePlugin('test-plugin');
+    expect(isPluginEnabled('test-plugin')).toBe(true);
+  });
+
+  it('should disable an enabled plugin', () => {
+    enablePlugin('test-plugin');
+    disablePlugin('test-plugin');
+    expect(isPluginEnabled('test-plugin')).toBe(false);
+  });
+
+  it('should track multiple plugins independently', () => {
+    enablePlugin('plugin-a');
+    enablePlugin('plugin-b');
+    expect(isPluginEnabled('plugin-a')).toBe(true);
+    expect(isPluginEnabled('plugin-b')).toBe(true);
+
+    disablePlugin('plugin-a');
+    expect(isPluginEnabled('plugin-a')).toBe(false);
+    expect(isPluginEnabled('plugin-b')).toBe(true);
+  });
+
+  it('should handle enabling an already-enabled plugin (idempotent)', () => {
+    enablePlugin('test-plugin');
+    enablePlugin('test-plugin');
+    expect(isPluginEnabled('test-plugin')).toBe(true);
+    disablePlugin('test-plugin');
+    expect(isPluginEnabled('test-plugin')).toBe(false);
+  });
+
+  it('should handle disabling a non-enabled plugin gracefully', () => {
+    // Should not throw
+    disablePlugin('nonexistent');
+    expect(isPluginEnabled('nonexistent')).toBe(false);
+  });
+});

package/src/lib/core/plugin-discovery.ts

@@ -0,0 +1,65 @@
+/**
+ * Plugin Discovery -- discovers plugins from a server endpoint and manages
+ * enable/disable state at runtime.
+ *
+ * The server is expected to respond with a JSON array of discovered plugin
+ * metadata at the /api/plugins endpoint.
+ */
+
+/** Metadata for a discovered plugin. */
+export interface DiscoveredPlugin {
+  path: string;
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  loaded: boolean;
+  enabled: boolean;
+  error?: string;
+}
+
+// --- Module state: enabled/disabled tracking ---
+
+const enabledPlugins = new Set<string>();
+
+/**
+ * Scan for plugins from the server's plugin directory.
+ *
+ * Fetches plugin metadata from `{serverUrl}/api/plugins` and returns
+ * the list with each plugin's `enabled` field reflecting local state.
+ */
+export async function discoverPlugins(serverUrl: string): Promise<DiscoveredPlugin[]> {
+  const url = `${serverUrl.replace(/\/$/, '')}/api/plugins`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to discover plugins: ${String(response.status)} ${response.statusText}`);
+  }
+  const plugins = (await response.json()) as DiscoveredPlugin[];
+  // Reconcile server data with local enabled state
+  return plugins.map((p) => ({
+    ...p,
+    enabled: enabledPlugins.has(p.name),
+  }));
+}
+
+/** Enable a plugin by name. */
+export function enablePlugin(name: string): void {
+  enabledPlugins.add(name);
+}
+
+/** Disable a plugin by name. */
+export function disablePlugin(name: string): void {
+  enabledPlugins.delete(name);
+}
+
+/** Check whether a plugin is currently enabled. */
+export function isPluginEnabled(name: string): boolean {
+  return enabledPlugins.has(name);
+}
+
+/**
+ * Reset discovery state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  enabledPlugins.clear();
+}

package/src/lib/core/plugin-loader.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { PluginModule } from './plugin-loader.js';
+import { loadPlugins, getLoadedPlugin, getAllLoadedPlugins, _resetForTesting } from './plugin-loader.js';
+import { _resetForTesting as resetDispatcher } from './dispatcher.js';
+
+// --- Helpers ---
+
+function makePlugin(
+  name: string,
+  deps: string[] = [],
+  register?: PluginModule['register'],
+): PluginModule {
+  return {
+    name,
+    version: '1.0.0',
+    description: `Test plugin: ${name}`,
+    author: 'Test Author',
+    dependencies: deps,
+    register: register ?? vi.fn(),
+  };
+}
+
+// --- Tests ---
+
+describe('Plugin Loader', () => {
+  beforeEach(() => {
+    _resetForTesting();
+    resetDispatcher();
+  });
+
+  it('should call register() on a single plugin', () => {
+    const plugin = makePlugin('alpha');
+    loadPlugins([plugin]);
+
+    expect(plugin.register).toHaveBeenCalledOnce();
+    // The register callback receives a PluginAPI object
+    // vitest's asymmetric matchers return `any`, which leaks through to
+    // no-unsafe-assignment. Wrap each in an explicit unknown cast.
+    expect(plugin.register).toHaveBeenCalledWith(
+      expect.objectContaining({
+        addCommand: expect.any(Function) as unknown,
+        addTool: expect.any(Function) as unknown,
+        dispatch: expect.any(Function) as unknown,
+      }),
+    );
+  });
+
+  it('should load plugins in dependency order (B before A when A depends on B)', () => {
+    const order: string[] = [];
+
+    const pluginB = makePlugin('B', [], () => order.push('B'));
+    const pluginA = makePlugin('A', ['B'], () => order.push('A'));
+
+    loadPlugins([pluginA, pluginB]);
+
+    expect(order).toEqual(['B', 'A']);
+  });
+
+  it('should handle a longer dependency chain', () => {
+    const order: string[] = [];
+
+    const pluginC = makePlugin('C', [], () => order.push('C'));
+    const pluginB = makePlugin('B', ['C'], () => order.push('B'));
+    const pluginA = makePlugin('A', ['B'], () => order.push('A'));
+
+    // Pass them in reverse order to prove sorting works
+    loadPlugins([pluginA, pluginB, pluginC]);
+
+    expect(order).toEqual(['C', 'B', 'A']);
+  });
+
+  it('should handle a diamond dependency pattern', () => {
+    const order: string[] = [];
+
+    const pluginD = makePlugin('D', [], () => order.push('D'));
+    const pluginB = makePlugin('B', ['D'], () => order.push('B'));
+    const pluginC = makePlugin('C', ['D'], () => order.push('C'));
+    const pluginA = makePlugin('A', ['B', 'C'], () => order.push('A'));
+
+    loadPlugins([pluginA, pluginC, pluginB, pluginD]);
+
+    // D must come first; B and C after D; A last
+    expect(order.indexOf('D')).toBe(0);
+    expect(order.indexOf('A')).toBe(3);
+    expect(order.indexOf('B')).toBeGreaterThan(order.indexOf('D'));
+    expect(order.indexOf('C')).toBeGreaterThan(order.indexOf('D'));
+  });
+
+  it('should throw on circular dependency', () => {
+    const pluginA = makePlugin('A', ['B']);
+    const pluginB = makePlugin('B', ['A']);
+
+    expect(() => loadPlugins([pluginA, pluginB])).toThrow('Circular dependency');
+  });
+
+  it('should throw on missing dependency', () => {
+    const plugin = makePlugin('A', ['nonexistent']);
+
+    expect(() => loadPlugins([plugin])).toThrow(
+      'Plugin "A" depends on "nonexistent", which is not in the plugin list.',
+    );
+  });
+
+  it('should store and retrieve plugin metadata', () => {
+    const plugin = makePlugin('my-plugin');
+    plugin.version = '2.3.1';
+    plugin.description = 'My cool plugin';
+    plugin.author = 'Jane Doe';
+
+    loadPlugins([plugin]);
+
+    const meta = getLoadedPlugin('my-plugin');
+    expect(meta).toBeDefined();
+    expect(meta?.name).toBe('my-plugin');
+    expect(meta?.version).toBe('2.3.1');
+    expect(meta?.description).toBe('My cool plugin');
+    expect(meta?.author).toBe('Jane Doe');
+  });
+
+  it('should list all loaded plugins', () => {
+    const pluginA = makePlugin('A');
+    const pluginB = makePlugin('B');
+
+    loadPlugins([pluginA, pluginB]);
+
+    const all = getAllLoadedPlugins();
+    expect(all.size).toBe(2);
+    expect(all.has('A')).toBe(true);
+    expect(all.has('B')).toBe(true);
+  });
+
+  it('should return the loaded plugins in load order', () => {
+    const pluginB = makePlugin('B');
+    const pluginA = makePlugin('A', ['B']);
+
+    const result = loadPlugins([pluginA, pluginB]);
+
+    expect(result).toHaveLength(2);
+    expect(result[0]?.name).toBe('B');
+    expect(result[1]?.name).toBe('A');
+  });
+
+  it('should load plugins with no dependencies in any order without error', () => {
+    const pluginA = makePlugin('A');
+    const pluginB = makePlugin('B');
+    const pluginC = makePlugin('C');
+
+    const result = loadPlugins([pluginA, pluginB, pluginC]);
+    expect(result).toHaveLength(3);
+  });
+
+  it('should throw on a three-node circular dependency', () => {
+    const pluginA = makePlugin('A', ['C']);
+    const pluginB = makePlugin('B', ['A']);
+    const pluginC = makePlugin('C', ['B']);
+
+    expect(() => loadPlugins([pluginA, pluginB, pluginC])).toThrow('Circular dependency');
+  });
+});

package/src/lib/core/plugin-loader.ts

@@ -0,0 +1,240 @@
+/**
+ * Plugin Loader -- discovers, orders, and initialises plugins.
+ *
+ * Responsibilities:
+ *   - Accepts an array of plugin modules
+ *   - Resolves load order via topological sort on declared dependencies
+ *   - Calls register(api) on each plugin in dependency order
+ *   - Reports circular or missing dependencies
+ *   - Maintains a registry of loaded plugin metadata
+ */
+
+import type { PluginAPI } from './plugin-api.js';
+import { createPluginAPI } from './plugin-api.js';
+import {
+  commandRegistry,
+  toolRegistry,
+  panelRegistry,
+  exporterRegistry,
+  importerRegistry,
+  shortcutRegistry,
+  menuRegistry,
+  toolbarRegistry,
+} from './registries.svelte.js';
+import { pluginState } from '../ui/plugin-state.svelte.js';
+import type { LoadedPluginRecord } from '../ui/plugin-state.svelte.js';
+
+// --- Plugin module interface ---
+
+export interface PluginModule {
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+  dependencies?: string[];
+  register: (api: PluginAPI) => void;
+}
+
+// --- Loaded plugin metadata ---
+
+export interface LoadedPlugin {
+  name: string;
+  version: string;
+  description?: string;
+  author?: string;
+}
+
+// --- Module state ---
+
+const loadedPlugins: Map<string, LoadedPlugin> = new Map();
+
+/**
+ * Topological sort using Kahn's algorithm.
+ * Returns the sorted plugin names or throws on circular / missing dependencies.
+ */
+function topologicalSort(plugins: PluginModule[]): string[] {
+  const nameSet = new Set(plugins.map((p) => p.name));
+
+  // Check for missing dependencies first
+  for (const plugin of plugins) {
+    for (const dep of plugin.dependencies ?? []) {
+      if (!nameSet.has(dep)) {
+        throw new Error(
+          `Plugin "${plugin.name}" depends on "${dep}", which is not in the plugin list.`,
+        );
+      }
+    }
+  }
+
+  // Build adjacency list and in-degree map
+  const inDegree = new Map<string, number>();
+  const dependents = new Map<string, string[]>(); // dep -> plugins that depend on it
+
+  for (const plugin of plugins) {
+    inDegree.set(plugin.name, 0);
+    dependents.set(plugin.name, []);
+  }
+
+  for (const plugin of plugins) {
+    for (const dep of plugin.dependencies ?? []) {
+      inDegree.set(plugin.name, (inDegree.get(plugin.name) ?? 0) + 1);
+      // Missing dependency: register an entry so `current`-driven traversal
+      // can still complete; the missing dep just never satisfies, which
+      // surfaces as a cycle error downstream.
+      const list = dependents.get(dep) ?? (() => {
+        const fresh: string[] = [];
+        dependents.set(dep, fresh);
+        return fresh;
+      })();
+      list.push(plugin.name);
+    }
+  }
+
+  // Seed queue with plugins that have no dependencies
+  const queue: string[] = [];
+  for (const [name, degree] of inDegree) {
+    if (degree === 0) queue.push(name);
+  }
+
+  const sorted: string[] = [];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) break;
+    sorted.push(current);
+
+    for (const dependent of dependents.get(current) ?? []) {
+      const newDegree = (inDegree.get(dependent) ?? 1) - 1;
+      inDegree.set(dependent, newDegree);
+      if (newDegree === 0) queue.push(dependent);
+    }
+  }
+
+  if (sorted.length !== plugins.length) {
+    // Some plugins were never added -- they form a cycle
+    const stuck = plugins
+      .map((p) => p.name)
+      .filter((n) => !sorted.includes(n));
+    throw new Error(`Circular dependency detected among plugins: ${stuck.join(', ')}`);
+  }
+
+  return sorted;
+}
+
+/**
+ * Load an array of plugin modules in dependency order.
+ * Each plugin's register() receives a PluginAPI scoped to that plugin.
+ *
+ * Returns the ordered list of loaded plugin metadata.
+ */
+export function loadPlugins(plugins: PluginModule[]): LoadedPlugin[] {
+  const order = topologicalSort(plugins);
+  const byName = new Map(plugins.map((p) => [p.name, p]));
+  const result: LoadedPlugin[] = [];
+
+  for (const name of order) {
+    const plugin = byName.get(name);
+    if (!plugin) continue; // topologicalSort only emits names from `plugins`
+    const api = createPluginAPI(plugin.name);
+
+    // Snapshot registry keys before register() so we can diff afterwards to
+    // attribute contributions to this specific plugin. Works because plugin
+    // order is deterministic (topological) and registrations happen inline.
+    const before = snapshotRegistryKeys();
+
+    let registerError: string | undefined;
+    try {
+      plugin.register(api);
+    } catch (err) {
+      registerError = err instanceof Error ? err.message : String(err);
+    }
+
+    const after = snapshotRegistryKeys();
+    const contributions = diffKeys(before, after);
+
+    // Omit description/author when absent (exactOptionalPropertyTypes)
+    const meta: LoadedPlugin = {
+      name: plugin.name,
+      version: plugin.version,
+    };
+    if (plugin.description !== undefined) meta.description = plugin.description;
+    if (plugin.author !== undefined) meta.author = plugin.author;
+    loadedPlugins.set(plugin.name, meta);
+    result.push(meta);
+
+    // Publish into the reactive plugin-state store so the Plugin Manager
+    // panel can display each plugin and its contributions.
+    const record: LoadedPluginRecord = {
+      name: plugin.name,
+      version: plugin.version,
+      dependencies: plugin.dependencies ?? [],
+      loaded: registerError === undefined,
+      contributions,
+    };
+    if (plugin.description !== undefined) record.description = plugin.description;
+    if (plugin.author !== undefined) record.author = plugin.author;
+    if (registerError !== undefined) record.error = registerError;
+    pluginState.addPlugin(record);
+  }
+
+  return result;
+}
+
+// --- Registry snapshot helpers (for attributing contributions to a plugin) ---
+
+interface RegistrySnapshot {
+  commands: Set<string>;
+  tools: Set<string>;
+  panels: Set<string>;
+  exporters: Set<string>;
+  importers: Set<string>;
+  shortcuts: Set<string>;
+  menuItems: Set<string>;
+  toolbarItems: Set<string>;
+}
+
+function snapshotRegistryKeys(): RegistrySnapshot {
+  return {
+    commands: new Set(commandRegistry.getAll().keys()),
+    tools: new Set(toolRegistry.getAll().keys()),
+    panels: new Set(panelRegistry.getAll().keys()),
+    exporters: new Set(exporterRegistry.getAll().keys()),
+    importers: new Set(importerRegistry.getAll().keys()),
+    shortcuts: new Set(shortcutRegistry.getAll().keys()),
+    menuItems: new Set(menuRegistry.getAll().keys()),
+    toolbarItems: new Set(toolbarRegistry.getAll().keys()),
+  };
+}
+
+function diffKeys(before: RegistrySnapshot, after: RegistrySnapshot) {
+  const added = (b: Set<string>, a: Set<string>) =>
+    [...a].filter((k) => !b.has(k)).sort();
+  return {
+    commands: added(before.commands, after.commands),
+    tools: added(before.tools, after.tools),
+    panels: added(before.panels, after.panels),
+    exporters: added(before.exporters, after.exporters),
+    importers: added(before.importers, after.importers),
+    shortcuts: added(before.shortcuts, after.shortcuts),
+    menuItems: added(before.menuItems, after.menuItems),
+    toolbarItems: added(before.toolbarItems, after.toolbarItems),
+  };
+}
+
+/** Get metadata for a loaded plugin by name */
+export function getLoadedPlugin(name: string): LoadedPlugin | undefined {
+  return loadedPlugins.get(name);
+}
+
+/** Get all loaded plugins */
+export function getAllLoadedPlugins(): ReadonlyMap<string, LoadedPlugin> {
+  return loadedPlugins;
+}
+
+/**
+ * Reset loader state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  loadedPlugins.clear();
+  pluginState._resetForTesting();
+}