@framework-m/plugin-sdk 0.2.3

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,YAAY,EACV,QAAQ,EACR,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,gBAAgB,EAChB,MAAM,EACN,gBAAgB,EAChB,mBAAmB,EACnB,wBAAwB,EACxB,gCAAgC,GACjC,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAG3D,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAGnF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,594 @@
+var P = Object.defineProperty;
+var C = (r, e, t) => e in r ? P(r, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : r[e] = t;
+var c = (r, e, t) => C(r, typeof e != "symbol" ? e + "" : e, t);
+import { jsx as S } from "react/jsx-runtime";
+import { createContext as O, useState as l, useEffect as d, useContext as f, useMemo as p } from "react";
+class N {
+  constructor() {
+    c(this, "factories", /* @__PURE__ */ new Map());
+    c(this, "instances", /* @__PURE__ */ new Map());
+  }
+  /**
+   * Register a service factory.
+   *
+   * @param name — unique service name
+   * @param factory — factory function (sync or async)
+   */
+  register(e, t) {
+    this.factories.set(e, t), this.instances.delete(e);
+  }
+  /**
+   * Get a service by name. Lazily instantiates on first call (singleton).
+   *
+   * @throws Error if service is not registered
+   */
+  async get(e) {
+    if (this.instances.has(e))
+      return this.instances.get(e);
+    const t = this.factories.get(e);
+    if (!t)
+      throw new Error(`Service "${e}" is not registered`);
+    const i = await Promise.resolve(t());
+    return this.instances.set(e, i), i;
+  }
+  /**
+   * Check if a service is registered.
+   */
+  has(e) {
+    return this.factories.has(e);
+  }
+  /**
+   * Get all registered service names.
+   */
+  getAll() {
+    return Array.from(this.factories.keys());
+  }
+  /**
+   * Clear all registered factories and cached instances.
+   */
+  clear() {
+    this.factories.clear(), this.instances.clear();
+  }
+}
+const v = "0.1.0", w = {
+  Sales: "shopping-cart",
+  Inventory: "package",
+  HR: "users",
+  Finance: "dollar-sign",
+  Core: "settings",
+  Other: "folder"
+};
+function M() {
+  const r = globalThis.__FRAMEWORK_M_PLUGIN_DEBUG__;
+  if (typeof r == "boolean")
+    return r;
+  if (typeof r == "string")
+    return ["1", "true", "yes", "on"].includes(r.toLowerCase());
+  const e = globalThis.process;
+  if (e != null && e.env) {
+    const t = e.env.FRAMEWORK_M_PLUGIN_DEBUG;
+    if (typeof t == "string")
+      return ["1", "true", "yes", "on"].includes(t.toLowerCase());
+  }
+  return !1;
+}
+const I = {
+  debug(r, ...e) {
+    M() && console.debug(`[PluginRegistry] ${r}`, ...e);
+  }
+};
+class R {
+  constructor() {
+    c(this, "plugins", /* @__PURE__ */ new Map());
+    c(this, "menuCache", null);
+    c(this, "serviceContainer", new N());
+    c(this, "routeOwners", /* @__PURE__ */ new Map());
+    c(this, "menuNameOwners", /* @__PURE__ */ new Map());
+    c(this, "menuRouteOwners", /* @__PURE__ */ new Map());
+    c(this, "serviceOwners", /* @__PURE__ */ new Map());
+    c(this, "diagnostics", []);
+    c(this, "permissionChecker", null);
+    c(this, "eventListeners", {
+      "plugin:registered": /* @__PURE__ */ new Set(),
+      "plugin:error": /* @__PURE__ */ new Set()
+    });
+  }
+  /**
+   * Register a plugin with the registry.
+   *
+   * validates that the plugin has name and version, checks collisions,
+   * stores it, registers any services into the ServiceContainer,
+   * and invalidates the menu cache.
+   *
+   * @throws Error if plugin has no name or version
+   */
+  async register(e) {
+    if (!e.name || !e.version)
+      throw new Error("Plugin must have name and version");
+    const t = this.validateRegistration(e), i = t.filter((o) => o.severity === "error");
+    if (i.length > 0) {
+      const o = new Error(
+        `Plugin "${e.name}" registration failed: ${i.map((a) => a.message).join("; ")}`
+      );
+      throw this.emit("plugin:error", { plugin: e, error: o }), o;
+    }
+    const s = this.plugins.get(e.name);
+    this.plugins.set(e.name, e), this.rebuildIndexesAndServices(), this.menuCache = null;
+    try {
+      e.onInit && await Promise.resolve(e.onInit());
+    } catch (o) {
+      throw s ? this.plugins.set(e.name, s) : this.plugins.delete(e.name), this.rebuildIndexesAndServices(), this.menuCache = null, this.emit("plugin:error", { plugin: e, error: o }), o;
+    }
+    s != null && s.onDestroy && s !== e && await Promise.resolve(s.onDestroy()), this.emit("plugin:registered", { plugin: e });
+    const n = t.filter((o) => o.severity === "warning");
+    n.length > 0 && I.debug(
+      `Registered plugin "${e.name}" with warnings`,
+      n
+    );
+  }
+  /**
+   * Get merged menu tree from all plugins.
+   *
+   * Collects all MenuItem entries, groups them by `module` (default: "Other"),
+   * optionally sub-groups by `category`, and sorts by `order`.
+   * Result is cached until a new plugin is registered.
+   */
+  getMenu() {
+    if (this.menuCache) return this.menuCache;
+    const e = [];
+    for (const t of this.plugins.values())
+      t.menu && e.push(...t.menu);
+    return e.length === 0 ? (this.menuCache = [], this.menuCache) : (this.menuCache = this.mergeMenus(e), this.menuCache);
+  }
+  /**
+   * Get aggregated routes from all plugins.
+   */
+  getRoutes() {
+    const e = [];
+    for (const t of this.plugins.values())
+      t.routes && e.push(...t.routes);
+    return e;
+  }
+  /**
+   * Get a specific plugin by name.
+   */
+  getPlugin(e) {
+    return this.plugins.get(e);
+  }
+  /**
+   * Get all registered plugins.
+   */
+  getAllPlugins() {
+    return Array.from(this.plugins.values());
+  }
+  /**
+   * Get the service container for DI.
+   */
+  getServiceContainer() {
+    return this.serviceContainer;
+  }
+  /**
+   * Unregister a plugin by name and run cleanup lifecycle if provided.
+   */
+  async unregister(e) {
+    const t = this.plugins.get(e);
+    return t ? (this.plugins.delete(e), this.rebuildIndexesAndServices(), this.menuCache = null, t.onDestroy && await Promise.resolve(t.onDestroy()), !0) : !1;
+  }
+  /**
+   * Resolve a service instance from the registry-level DI container.
+   */
+  async getService(e) {
+    return this.serviceContainer.get(e);
+  }
+  /**
+   * Aggregate all widgets contributed by registered plugins.
+   */
+  getWidgets() {
+    const e = [];
+    for (const t of this.plugins.values())
+      t.widgets && e.push(...t.widgets);
+    return e;
+  }
+  /**
+   * Configure a permission checker used by consumer hooks.
+   */
+  setPermissionChecker(e) {
+    this.permissionChecker = e;
+  }
+  /**
+   * Get the configured permission checker.
+   */
+  getPermissionChecker() {
+    return this.permissionChecker;
+  }
+  /**
+   * Subscribe to plugin lifecycle events.
+   */
+  on(e, t) {
+    return this.eventListeners[e].add(
+      t
+    ), () => {
+      this.eventListeners[e].delete(
+        t
+      );
+    };
+  }
+  /**
+   * Get emitted diagnostics.
+   */
+  getDiagnostics(e) {
+    return e ? this.diagnostics.filter((t) => t.severity === e) : [...this.diagnostics];
+  }
+  /**
+   * Clear diagnostics.
+   */
+  clearDiagnostics() {
+    this.diagnostics = [];
+  }
+  // -------------------------------------------------------------------------
+  // Version Compatibility
+  // -------------------------------------------------------------------------
+  /**
+   * Check compatibility of all registered plugins.
+   *
+   * Returns a report of all plugins with their compatibility status:
+   * - SDK version compatibility
+   * - Peer plugin dependency satisfaction
+   */
+  checkCompatibility() {
+    const e = [];
+    for (const t of this.plugins.values()) {
+      const i = {
+        name: t.name,
+        version: t.version,
+        sdkCompatible: !0,
+        missingPeerPlugins: []
+      };
+      if (t.minSdkVersion && (i.sdkCompatible = this.checkSemverCompat(
+        v,
+        t.minSdkVersion
+      )), t.peerPlugins)
+        for (const s of t.peerPlugins)
+          this.plugins.has(s) || i.missingPeerPlugins.push(s);
+      e.push(i);
+    }
+    return e;
+  }
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+  /**
+   * Simple semver compatibility check.
+   * Checks if `current` satisfies `>=required`.
+   */
+  checkSemverCompat(e, t) {
+    const i = t.replace(/^>=?/, ""), [s, n = 0, o = 0] = e.split(".").map(Number), [a, u = 0, m = 0] = i.split(".").map(Number);
+    return s !== a ? s > a : n !== u ? n > u : o >= m;
+  }
+  validateRegistration(e) {
+    return [
+      ...this.validateSdkCompatibility(e),
+      ...this.validateDuplicatePlugin(e),
+      ...this.validateRouteCollisions(e),
+      ...this.validateMenuCollisions(e),
+      ...this.validateServiceCollisions(e)
+    ];
+  }
+  validateSdkCompatibility(e) {
+    const t = [];
+    return e.minSdkVersion && (this.checkSemverCompat(
+      v,
+      e.minSdkVersion
+    ) || t.push(
+      this.addDiagnostic({
+        code: "SDK_INCOMPATIBLE",
+        severity: "warning",
+        message: `Plugin ${e.name} requires SDK >=${e.minSdkVersion}, current SDK is ${v}. Plugin may not work correctly.`,
+        pluginName: e.name,
+        key: e.minSdkVersion
+      })
+    )), t;
+  }
+  validateDuplicatePlugin(e) {
+    const t = [];
+    return this.plugins.has(e.name) && t.push(
+      this.addDiagnostic({
+        code: "PLUGIN_DUPLICATE",
+        severity: "warning",
+        message: `Plugin ${e.name} is already registered and will be replaced`,
+        pluginName: e.name,
+        conflictingPluginName: e.name,
+        key: e.name
+      })
+    ), t;
+  }
+  validateRouteCollisions(e) {
+    const t = [], i = /* @__PURE__ */ new Set();
+    for (const s of e.routes ?? []) {
+      if (i.has(s.path)) {
+        t.push(
+          this.addDiagnostic({
+            code: "ROUTE_COLLISION",
+            severity: "error",
+            message: `Duplicate route path "${s.path}" inside plugin ${e.name}`,
+            pluginName: e.name,
+            conflictingPluginName: e.name,
+            key: s.path
+          })
+        );
+        continue;
+      }
+      i.add(s.path);
+      const n = this.routeOwners.get(s.path);
+      n && n !== e.name && t.push(
+        this.addDiagnostic({
+          code: "ROUTE_COLLISION",
+          severity: "error",
+          message: `Route path "${s.path}" from plugin ${e.name} conflicts with plugin ${n}`,
+          pluginName: e.name,
+          conflictingPluginName: n,
+          key: s.path
+        })
+      );
+    }
+    return t;
+  }
+  validateMenuCollisions(e) {
+    const t = [], i = /* @__PURE__ */ new Set(), s = /* @__PURE__ */ new Set();
+    for (const n of e.menu ?? []) {
+      if (i.has(n.name))
+        t.push(
+          this.addDiagnostic({
+            code: "MENU_NAME_COLLISION",
+            severity: "error",
+            message: `Duplicate menu name "${n.name}" inside plugin ${e.name}`,
+            pluginName: e.name,
+            conflictingPluginName: e.name,
+            key: n.name
+          })
+        );
+      else {
+        i.add(n.name);
+        const o = this.menuNameOwners.get(n.name);
+        o && o !== e.name && t.push(
+          this.addDiagnostic({
+            code: "MENU_NAME_COLLISION",
+            severity: "error",
+            message: `Menu name "${n.name}" from plugin ${e.name} conflicts with plugin ${o}`,
+            pluginName: e.name,
+            conflictingPluginName: o,
+            key: n.name
+          })
+        );
+      }
+      if (s.has(n.route))
+        t.push(
+          this.addDiagnostic({
+            code: "MENU_ROUTE_COLLISION",
+            severity: "error",
+            message: `Duplicate menu route "${n.route}" inside plugin ${e.name}`,
+            pluginName: e.name,
+            conflictingPluginName: e.name,
+            key: n.route
+          })
+        );
+      else {
+        s.add(n.route);
+        const o = this.menuRouteOwners.get(n.route);
+        o && o !== e.name && t.push(
+          this.addDiagnostic({
+            code: "MENU_ROUTE_COLLISION",
+            severity: "error",
+            message: `Menu route "${n.route}" from plugin ${e.name} conflicts with plugin ${o}`,
+            pluginName: e.name,
+            conflictingPluginName: o,
+            key: n.route
+          })
+        );
+      }
+    }
+    return t;
+  }
+  validateServiceCollisions(e) {
+    const t = [], i = /* @__PURE__ */ new Set();
+    for (const s of Object.keys(e.services ?? {})) {
+      if (i.has(s)) {
+        t.push(
+          this.addDiagnostic({
+            code: "SERVICE_COLLISION",
+            severity: "error",
+            message: `Duplicate service "${s}" inside plugin ${e.name}`,
+            pluginName: e.name,
+            conflictingPluginName: e.name,
+            key: s
+          })
+        );
+        continue;
+      }
+      i.add(s);
+      const n = this.serviceOwners.get(s);
+      n && n !== e.name && t.push(
+        this.addDiagnostic({
+          code: "SERVICE_COLLISION",
+          severity: "error",
+          message: `Service "${s}" from plugin ${e.name} conflicts with plugin ${n}`,
+          pluginName: e.name,
+          conflictingPluginName: n,
+          key: s
+        })
+      );
+    }
+    return t;
+  }
+  addDiagnostic(e) {
+    const t = {
+      ...e,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    return this.diagnostics.push(t), t;
+  }
+  /**
+   * Merge flat menu items into a grouped tree:
+   *   Module → (optional) Category → Items
+   *
+   * Items without a `module` are placed under "Other".
+   */
+  mergeMenus(e) {
+    var i;
+    const t = /* @__PURE__ */ new Map();
+    for (const s of e) {
+      const n = s.module || "Other";
+      t.has(n) || t.set(n, {
+        name: n.toLowerCase(),
+        label: n,
+        route: `/${n.toLowerCase()}`,
+        icon: this.getModuleIcon(n),
+        order: s.order,
+        children: []
+      });
+      const o = t.get(n);
+      if (s.order !== void 0 && (o.order === void 0 || s.order < o.order) && (o.order = s.order), s.category) {
+        let a = (i = o.children) == null ? void 0 : i.find(
+          (u) => u.label === s.category
+        );
+        a || (a = {
+          name: s.category.toLowerCase(),
+          label: s.category,
+          route: `/${n.toLowerCase()}/${s.category.toLowerCase()}`,
+          children: []
+        }, o.children.push(a)), a.children.push(s);
+      } else
+        o.children.push(s);
+    }
+    return Array.from(t.values()).sort(
+      (s, n) => (s.order ?? 999) - (n.order ?? 999)
+    );
+  }
+  getModuleIcon(e) {
+    return w[e] || w.Other;
+  }
+  rebuildIndexesAndServices() {
+    this.routeOwners.clear(), this.menuNameOwners.clear(), this.menuRouteOwners.clear(), this.serviceOwners.clear(), this.serviceContainer.clear();
+    for (const e of this.plugins.values())
+      this.registerPluginServices(e), this.registerPluginRoutes(e), this.registerPluginMenuItems(e);
+  }
+  registerPluginServices(e) {
+    for (const [t, i] of Object.entries(e.services ?? {}))
+      this.serviceContainer.register(t, i), this.serviceOwners.set(t, e.name);
+  }
+  registerPluginRoutes(e) {
+    for (const t of e.routes ?? [])
+      this.routeOwners.set(t.path, e.name);
+  }
+  registerPluginMenuItems(e) {
+    for (const t of e.menu ?? [])
+      this.menuNameOwners.set(t.name, e.name), this.menuRouteOwners.set(t.route, e.name);
+  }
+  emit(e, t) {
+    for (const i of this.eventListeners[e])
+      i(t);
+  }
+}
+const h = O(null);
+function b({
+  children: r,
+  registry: e
+}) {
+  const [t] = l(
+    () => e ?? new R()
+  ), [i, s] = l(!1);
+  return d(() => {
+    s(!0);
+  }, []), i ? /* @__PURE__ */ S(h.Provider, { value: t, children: r }) : null;
+}
+async function y(r, e) {
+  const t = [];
+  for (const i of r) {
+    if (i.hidden || i.permissions && i.permissions.length > 0 && !await Promise.resolve(e(i.permissions)))
+      continue;
+    const s = i.children ? await y(i.children, e) : void 0;
+    i.children && ((s == null ? void 0 : s.length) ?? 0) === 0 || t.push({ ...i, children: s });
+  }
+  return t;
+}
+function $() {
+  const r = f(h), [e, t] = l([]);
+  if (!r)
+    throw new Error("usePluginMenu must be used within PluginRegistryProvider");
+  return d(() => {
+    let i = !1;
+    return (async () => {
+      const n = r.getMenu(), o = r.getPermissionChecker();
+      if (!o) {
+        i || t(n.filter((u) => !u.hidden));
+        return;
+      }
+      const a = await y(n, o);
+      i || t(a);
+    })(), () => {
+      i = !0;
+    };
+  }, [r]), e;
+}
+function _(r) {
+  const e = f(h);
+  if (!e)
+    throw new Error("usePlugin must be used within PluginRegistryProvider");
+  return p(() => e.getPlugin(r), [e, r]);
+}
+function A(r) {
+  const e = f(h);
+  if (!e)
+    throw new Error("useService must be used within PluginRegistryProvider");
+  const [t, i] = l(null), [s, n] = l(!0), [o, a] = l(null), u = p(
+    () => e.getService(r),
+    [e, r]
+  );
+  return d(() => {
+    let m = !1;
+    return n(!0), a(null), u.then((g) => {
+      m || (i(g), n(!1));
+    }).catch((g) => {
+      m || (a(g instanceof Error ? g : new Error(String(g))), n(!1));
+    }), () => {
+      m = !0;
+    };
+  }, [u]), { service: t, isLoading: s, error: o };
+}
+async function k(r, e) {
+  const t = [];
+  for (const i of r)
+    i.permissions && i.permissions.length > 0 && !await Promise.resolve(e(i.permissions)) || t.push(i);
+  return t;
+}
+function U() {
+  const r = f(h), [e, t] = l([]);
+  if (!r)
+    throw new Error("useWidgets must be used within PluginRegistryProvider");
+  return d(() => {
+    let i = !1;
+    return (async () => {
+      const n = r.getWidgets(), o = r.getPermissionChecker();
+      if (!o) {
+        i || t(n);
+        return;
+      }
+      const a = await k(n, o);
+      i || t(a);
+    })(), () => {
+      i = !0;
+    };
+  }, [r]), e;
+}
+export {
+  R as PluginRegistry,
+  h as PluginRegistryContext,
+  b as PluginRegistryProvider,
+  v as SDK_VERSION,
+  N as ServiceContainer,
+  _ as usePlugin,
+  $ as usePluginMenu,
+  A as useService,
+  U as useWidgets
+};
+//# sourceMappingURL=index.js.map