@dxos/plugin-registry 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/containers/PluginArticle/PluginArticle.tsx

@@ -0,0 +1,378 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { type Dispatch, type SetStateAction, useCallback, useEffect, useMemo, useState } from 'react';
+
+import { type Plugin, type PluginManager, type Registry, UrlLoader } from '@dxos/app-framework';
+import { useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { PluginDetail } from '#components';
+import { getPluginPath } from '#meta';
+
+import { useDisableConfirmation, useRegistryPluginProvider, useRegistryPlugins, useRemotePluginIds } from '../../hooks';
+
+// TODO(burdon): Convert to ECHO type.
+export type PluginArticleProps = { subject: Plugin.Plugin };
+
+export const PluginArticle = ({ subject: plugin }: PluginArticleProps) => {
+  const pluginId = plugin.meta.id;
+  const manager = usePluginManager();
+  const plugins = useAtomValue(manager.plugins);
+  const remotePluginIds = useRemotePluginIds();
+  const provider = useRegistryPluginProvider();
+  const { invokePromise } = useOperationInvoker();
+
+  const { catalogEntry, moduleUrl, repo } = useCatalogEntry(pluginId);
+  const { installedVersionTag, syncInstalledVersion } = useInstalledVersionTag(pluginId, plugins);
+  const { pickerVersions, selectedVersionTag, setSelectedVersionTag } = useVersionPicker({
+    provider,
+    pluginId,
+    repo,
+    moduleUrl,
+    installedVersionTag,
+  });
+
+  const enabled = manager.getEnabled().includes(pluginId);
+  const failed = useAtomValue(manager.failed);
+  const failure = useMemo(() => failed.find((entry) => entry.id === pluginId), [failed, pluginId]);
+  const isInstalled = useMemo(() => plugins.some((candidate) => candidate.meta.id === pluginId), [plugins, pluginId]);
+  const isCore = manager.getCore().includes(pluginId);
+  const canUninstall = isInstalled && !isCore && remotePluginIds.has(pluginId);
+  const hasUpdate =
+    isInstalled && !!catalogEntry && !!installedVersionTag && installedVersionTag !== catalogEntry.version;
+
+  // Recompute graph slices whenever the plugin list changes, so installs /
+  // removals through other surfaces (or this article's own actions) keep the
+  // detail view in sync.
+  const dependencies = useMemo(
+    () => manager.getDependencies(pluginId, { transitive: false }),
+    [manager, pluginId, plugins],
+  );
+  const dependents = useMemo(
+    () => manager.getDependents(pluginId, { transitive: false }),
+    [manager, pluginId, plugins],
+  );
+
+  // Resolves a plugin id to its display name. A plugin's translations are
+  // only loaded when it is activated, so the always-available `meta.name`
+  // from the registered plugin set is the right source for chip labels.
+  const handleResolvePluginName = useCallback(
+    (id: string): string => plugins.find((candidate) => candidate.meta.id === id)?.meta.name ?? id,
+    [plugins],
+  );
+
+  const handleNavigateToPlugin = useCallback(
+    (targetId: string) => {
+      void invokePromise(LayoutOperation.Open, {
+        subject: [getPluginPath(targetId)],
+      });
+    },
+    [invokePromise],
+  );
+
+  const actions = usePluginActions({
+    manager,
+    pluginId,
+    isInstalled,
+    moduleUrl,
+    catalogEntry,
+    pickerVersions,
+    selectedVersionTag,
+    syncInstalledVersion,
+  });
+
+  return (
+    <PluginDetail
+      plugin={plugin}
+      enabled={enabled}
+      installing={actions.installing}
+      updating={actions.updating}
+      hasUpdate={hasUpdate}
+      installedVersionTag={installedVersionTag}
+      selectedVersionTag={selectedVersionTag}
+      versions={pickerVersions}
+      dependencies={dependencies}
+      dependents={dependents}
+      failure={failure}
+      onEnabledChange={actions.handleEnableChange}
+      onInstall={!isInstalled && moduleUrl ? actions.handleInstall : undefined}
+      onInstallVersion={pickerVersions.length > 0 ? actions.handleInstallVersion : undefined}
+      onNavigateToPlugin={handleNavigateToPlugin}
+      onResolvePluginName={handleResolvePluginName}
+      onUninstall={canUninstall ? actions.handleUninstall : undefined}
+      onUpdate={hasUpdate ? actions.handleUpdate : undefined}
+      onVersionChange={setSelectedVersionTag}
+    />
+  );
+};
+
+//
+// Hooks
+//
+// Each of the hooks below isolates a self-contained slice of the article's
+// state machine. They're declared at module scope (rather than inline in
+// `PluginArticle`) to keep the component readable as a thin wiring layer over
+// `PluginDetail`.
+//
+
+/**
+ * Resolves the registry catalog entry for a plugin by id, plus the two fields
+ * (`moduleUrl`, `repo`) the rest of the article cares about.
+ */
+const useCatalogEntry = (
+  pluginId: string,
+): {
+  catalogEntry: Registry.Plugin | undefined;
+  moduleUrl: string | undefined;
+  repo: string | undefined;
+} => {
+  const { entries } = useRegistryPlugins();
+  const catalogEntry = useMemo(() => entries.find((entry) => entry.id === pluginId), [entries, pluginId]);
+  return { catalogEntry, moduleUrl: catalogEntry?.moduleUrl, repo: catalogEntry?.repo };
+};
+
+/**
+ * Tracks the per-plugin installed version (sourced from `UrlLoader` localStorage)
+ * as React state so post-install/update re-renders are deterministic — the value
+ * lives in component state rather than being read inline on every render.
+ *
+ * - Initialised from localStorage at mount.
+ * - Auto-resyncs when the plugin manager's plugin list changes (catches external
+ *   installs / removes triggered by the list view).
+ * - `syncInstalledVersion()` is the explicit handle install/update operations
+ *   call inside their `Effect.ensuring` so the post-mutation render sees both
+ *   the new version and the cleared `installing`/`updating` flag together.
+ */
+const useInstalledVersionTag = (
+  pluginId: string,
+  plugins: readonly Plugin.Plugin[],
+): {
+  installedVersionTag: string | undefined;
+  syncInstalledVersion: () => void;
+} => {
+  const [installedVersionTag, setInstalledVersionTag] = useState<string | undefined>(() =>
+    UrlLoader.getInstalledVersion(pluginId),
+  );
+
+  const syncInstalledVersion = useCallback(() => {
+    setInstalledVersionTag(UrlLoader.getInstalledVersion(pluginId));
+  }, [pluginId]);
+
+  useEffect(() => {
+    syncInstalledVersion();
+  }, [plugins, syncInstalledVersion]);
+
+  return { installedVersionTag, syncInstalledVersion };
+};
+
+/**
+ * Owns the version picker's state machine: fetches the available versions list
+ * from the provider, prepends the installed version when the catalog stub omits
+ * it, and keeps the selection clamped to whatever's currently in the list (so
+ * an external update doesn't strand the trigger on a tag that's no longer
+ * available).
+ */
+const useVersionPicker = ({
+  provider,
+  pluginId,
+  repo,
+  moduleUrl,
+  installedVersionTag,
+}: {
+  provider: Registry.Manager;
+  pluginId: string;
+  repo: string | undefined;
+  moduleUrl: string | undefined;
+  installedVersionTag: string | undefined;
+}): {
+  pickerVersions: readonly Registry.PluginVersion[];
+  selectedVersionTag: string | undefined;
+  setSelectedVersionTag: Dispatch<SetStateAction<string | undefined>>;
+} => {
+  const [versions, setVersions] = useState<readonly Registry.PluginVersion[]>([]);
+  const [selectedVersionTag, setSelectedVersionTag] = useState<string | undefined>();
+
+  // Load version list once the catalog entry's repo is known.
+  useEffect(() => {
+    if (!repo) {
+      return;
+    }
+    void provider.listVersions(repo).pipe(
+      Effect.match({
+        onSuccess: (vs) => {
+          setVersions(vs);
+          // Default selection: the currently installed version, or the latest.
+          const installedVersion = UrlLoader.getInstalledVersion(pluginId);
+          setSelectedVersionTag(installedVersion ?? vs[0]?.tag);
+        },
+        onFailure: () => {
+          // Non-critical; version picker stays empty.
+        },
+      }),
+      runAndForwardErrors,
+    );
+  }, [provider, repo, pluginId]);
+
+  // Make sure the picker always lists the installed version, even if the catalog
+  // hasn't surfaced it (the current `listVersions` stub only returns latest).
+  const pickerVersions = useMemo<readonly Registry.PluginVersion[]>(() => {
+    if (!installedVersionTag) {
+      return versions;
+    }
+    if (versions.some((entry) => entry.tag === installedVersionTag)) {
+      return versions;
+    }
+    const installedEntry: Registry.PluginVersion = {
+      tag: installedVersionTag,
+      // Picker won't be re-installing this entry unless the user selects + clicks Install,
+      // and the catalog moduleUrl is the closest stand-in we have.
+      moduleUrl: moduleUrl ?? '',
+    };
+    return [installedEntry, ...versions];
+  }, [versions, installedVersionTag, moduleUrl]);
+
+  // Keep `selectedVersionTag` in sync when picker contents change (e.g. the user
+  // updated the plugin from the list view — installed version moved, picker
+  // shrunk, prior selection is no longer in the list).
+  useEffect(() => {
+    if (pickerVersions.length === 0) {
+      return;
+    }
+    if (selectedVersionTag && pickerVersions.some((entry) => entry.tag === selectedVersionTag)) {
+      return;
+    }
+    setSelectedVersionTag(installedVersionTag ?? pickerVersions[0]?.tag);
+  }, [pickerVersions, selectedVersionTag, installedVersionTag]);
+
+  return { pickerVersions, selectedVersionTag, setSelectedVersionTag };
+};
+
+/**
+ * The user-facing actions the article exposes — enable/disable, uninstall,
+ * install (latest), update (to latest catalog version), and install-from-picker —
+ * plus the `installing`/`updating` flags they drive. Each handler ends with a
+ * `syncInstalledVersion()` call inside its `Effect.ensuring` so the cached
+ * installed version snaps to the freshly-written localStorage value in the same
+ * render that clears the in-flight flag.
+ */
+const usePluginActions = ({
+  manager,
+  pluginId,
+  isInstalled,
+  moduleUrl,
+  catalogEntry,
+  pickerVersions,
+  selectedVersionTag,
+  syncInstalledVersion,
+}: {
+  manager: PluginManager.PluginManager;
+  pluginId: string;
+  isInstalled: boolean;
+  moduleUrl: string | undefined;
+  catalogEntry: Registry.Plugin | undefined;
+  pickerVersions: readonly Registry.PluginVersion[];
+  selectedVersionTag: string | undefined;
+  syncInstalledVersion: () => void;
+}) => {
+  const [installing, setInstalling] = useState(false);
+  const [updating, setUpdating] = useState(false);
+  const requestDisable = useDisableConfirmation(manager, (id) => void runAndForwardErrors(manager.disable(id)));
+
+  const handleEnableChange = useCallback(
+    (enabled: boolean) => {
+      if (enabled) {
+        void runAndForwardErrors(manager.enable(pluginId));
+        return;
+      }
+      requestDisable(pluginId);
+    },
+    [manager, pluginId, requestDisable],
+  );
+
+  const handleUninstall = useCallback(() => {
+    void runAndForwardErrors(manager.remove(pluginId));
+  }, [manager, pluginId]);
+
+  const handleInstall = useCallback(() => {
+    if (!moduleUrl) {
+      return;
+    }
+    setInstalling(true);
+    void Effect.gen(function* () {
+      const added = yield* manager.add(moduleUrl);
+      yield* manager.enable(added.meta.id);
+      if (catalogEntry) {
+        UrlLoader.setInstalledVersion(added.meta.id, catalogEntry.version);
+      }
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          setInstalling(false);
+          syncInstalledVersion();
+        }),
+      ),
+      runAndForwardErrors,
+    );
+  }, [manager, moduleUrl, catalogEntry, syncInstalledVersion]);
+
+  const handleUpdate = useCallback(() => {
+    if (!moduleUrl || !catalogEntry) {
+      return;
+    }
+    setUpdating(true);
+    void Effect.gen(function* () {
+      yield* manager.remove(pluginId);
+      const added = yield* manager.add(moduleUrl);
+      yield* manager.enable(added.meta.id);
+      UrlLoader.setInstalledVersion(added.meta.id, catalogEntry.version);
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          setUpdating(false);
+          syncInstalledVersion();
+        }),
+      ),
+      runAndForwardErrors,
+    );
+  }, [manager, pluginId, moduleUrl, catalogEntry, syncInstalledVersion]);
+
+  const handleInstallVersion = useCallback(() => {
+    const version = pickerVersions.find((candidate) => candidate.tag === selectedVersionTag);
+    if (!version || !version.moduleUrl) {
+      return;
+    }
+    setInstalling(true);
+    void Effect.gen(function* () {
+      // Remove existing version before installing a different one.
+      if (isInstalled) {
+        yield* manager.remove(pluginId);
+      }
+      const added = yield* manager.add(version.moduleUrl);
+      yield* manager.enable(added.meta.id);
+      UrlLoader.setInstalledVersion(added.meta.id, version.tag);
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          setInstalling(false);
+          syncInstalledVersion();
+        }),
+      ),
+      runAndForwardErrors,
+    );
+  }, [manager, pluginId, isInstalled, selectedVersionTag, pickerVersions, syncInstalledVersion]);
+
+  return {
+    installing,
+    updating,
+    handleEnableChange,
+    handleUninstall,
+    handleInstall,
+    handleUpdate,
+    handleInstallVersion,
+  };
+};

package/src/containers/PluginArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { PluginArticle as default } from './PluginArticle';

package/src/containers/PublicRegistryArticle/PublicRegistryArticle.tsx

@@ -0,0 +1,192 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { type Registry, Plugin, UrlLoader } from '@dxos/app-framework';
+import { useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import { runAndForwardErrors } from '@dxos/effect';
+import { ObservabilityOperation } from '@dxos/plugin-observability';
+import { useTranslation } from '@dxos/react-ui';
+import { composable } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { useAutoTags, useRegistryPlugins, useUpdateAvailableIds } from '../../hooks';
+import { BaseRegistryArticle } from '../BaseRegistryArticle';
+
+const sortEntries = (a: Registry.Plugin, b: Registry.Plugin) => (a.name ?? a.id).localeCompare(b.name ?? b.id);
+
+const sortPlugins = (a: Plugin.Plugin, b: Plugin.Plugin) =>
+  (a.meta.name ?? a.meta.id).localeCompare(b.meta.name ?? b.meta.id);
+
+/**
+ * Turns a registry catalog entry into a minimal Plugin object so we can reuse
+ * {@link BaseRegistryArticle} for rendering. The synthesized plugin has no
+ * modules — it exists only for display until the user installs it.
+ */
+const toDisplayPlugin = (plugin: Registry.Plugin): Plugin.Plugin =>
+  ({
+    [Plugin.PluginTypeId]: Plugin.PluginTypeId,
+    meta: {
+      id: plugin.id,
+      name: plugin.name,
+      description: plugin.description,
+      homePage: plugin.homePage,
+      source: plugin.source,
+      screenshots: plugin.screenshots,
+      tags: plugin.tags,
+      icon: plugin.icon,
+      iconHue: plugin.iconHue,
+    },
+    modules: [],
+  }) as Plugin.Plugin;
+
+export type PublicRegistryArticleProps = {
+  id: string;
+};
+
+export const PublicRegistryArticle = composable<HTMLDivElement, PublicRegistryArticleProps>(
+  ({ id, ...props }, forwardedRef) => {
+    const { t } = useTranslation(meta.id);
+    const manager = usePluginManager();
+    const { invoke } = useOperationInvoker();
+    const { entries, loading, error } = useRegistryPlugins();
+    const plugins = useAtomValue(manager.plugins);
+    const installedIds = useMemo(() => plugins.map((plugin) => plugin.meta.id), [plugins]);
+    const extraTagsById = useAutoTags(entries);
+
+    // Snapshot of installed plugin ids at mount time. Used to sort installed
+    // plugins to the top without having newly-installed rows jump up mid-session.
+    const [installedSnapshot] = useState<ReadonlySet<string>>(
+      () => new Set(manager.getPlugins().map((plugin) => plugin.meta.id)),
+    );
+
+    const [installingIds, setInstallingIds] = useState<readonly string[]>([]);
+    const [updatingIds, setUpdatingIds] = useState<readonly string[]>([]);
+    const updateAvailableIds = useUpdateAvailableIds(entries);
+
+    const sortedEntries = useMemo(() => [...entries].sort(sortEntries), [entries]);
+    const moduleUrlById = useMemo(() => {
+      const map: Record<string, string> = {};
+      for (const entry of sortedEntries) {
+        map[entry.id] = entry.moduleUrl;
+      }
+      return map;
+    }, [sortedEntries]);
+
+    // Maps plugin id → current registry version (i.e. plugin.version from the catalog).
+    const versionById = useMemo(() => {
+      const map: Record<string, string> = {};
+      for (const entry of sortedEntries) {
+        map[entry.id] = entry.version;
+      }
+      return map;
+    }, [sortedEntries]);
+
+    // Single list with installed-at-mount plugins sorted to the top. Sort order
+    // is based on the mount-time snapshot so rows don't jump as the user
+    // installs plugins during the session.
+    const items = useMemo(() => {
+      const catalogIds = new Set(sortedEntries.map((entry) => entry.id));
+      const remoteIds = new Set(UrlLoader.getRemoteEntries().map((entry) => entry.id));
+      const fromCatalog = sortedEntries.map(toDisplayPlugin);
+      const fromUrlOnly = plugins.filter((plugin) => remoteIds.has(plugin.meta.id) && !catalogIds.has(plugin.meta.id));
+      const installedFirst = [...fromCatalog, ...fromUrlOnly].sort((a, b) => {
+        const aInstalled = installedSnapshot.has(a.meta.id);
+        const bInstalled = installedSnapshot.has(b.meta.id);
+        if (aInstalled !== bInstalled) {
+          return aInstalled ? -1 : 1;
+        }
+        return sortPlugins(a, b);
+      });
+      return installedFirst;
+    }, [sortedEntries, installedSnapshot, plugins]);
+
+    const handleInstall = useCallback(
+      (pluginId: string) => {
+        const moduleUrl = moduleUrlById[pluginId];
+        const version = versionById[pluginId];
+        if (!moduleUrl) {
+          return;
+        }
+        setInstallingIds((prev) => (prev.includes(pluginId) ? prev : [...prev, pluginId]));
+        void Effect.gen(function* () {
+          const plugin = yield* manager.add(moduleUrl);
+          yield* manager.enable(plugin.meta.id);
+          // Persist the installed version for future update detection.
+          if (version) {
+            UrlLoader.setInstalledVersion(plugin.meta.id, version);
+          }
+          yield* invoke(ObservabilityOperation.SendEvent, {
+            name: 'plugins.install',
+            properties: { plugin: plugin.meta.id, source: 'registry' },
+          });
+        }).pipe(
+          Effect.ensuring(Effect.sync(() => setInstallingIds((prev) => prev.filter((pid) => pid !== pluginId)))),
+          runAndForwardErrors,
+        );
+      },
+      [invoke, manager, moduleUrlById, versionById],
+    );
+
+    const handleUpdate = useCallback(
+      (pluginId: string) => {
+        const moduleUrl = moduleUrlById[pluginId];
+        const version = versionById[pluginId];
+        if (!moduleUrl) {
+          return;
+        }
+        setUpdatingIds((prev) => (prev.includes(pluginId) ? prev : [...prev, pluginId]));
+        void Effect.gen(function* () {
+          // Unload the old version then re-install from the new URL.
+          yield* manager.remove(pluginId);
+          const plugin = yield* manager.add(moduleUrl);
+          yield* manager.enable(plugin.meta.id);
+          if (version) {
+            UrlLoader.setInstalledVersion(plugin.meta.id, version);
+          }
+          yield* invoke(ObservabilityOperation.SendEvent, {
+            name: 'plugins.update',
+            properties: { plugin: plugin.meta.id, source: 'registry' },
+          });
+        }).pipe(
+          Effect.ensuring(Effect.sync(() => setUpdatingIds((prev) => prev.filter((pid) => pid !== pluginId)))),
+          runAndForwardErrors,
+        );
+      },
+      [invoke, manager, moduleUrlById, versionById],
+    );
+
+    const empty = error ? (
+      <div className='p-4 text-description'>{t('registry.error.label', { message: error.message })}</div>
+    ) : loading ? (
+      <div className='p-4 text-description'>{t('registry.loading.label')}</div>
+    ) : (
+      <div className='p-4 text-description'>{t('registry.empty.label')}</div>
+    );
+
+    return (
+      <BaseRegistryArticle
+        {...props}
+        id={id}
+        source='registry'
+        plugins={items}
+        installed={installedIds}
+        installing={installingIds}
+        updating={updatingIds}
+        updateAvailableIds={updateAvailableIds}
+        extraTagsById={extraTagsById}
+        onInstall={handleInstall}
+        onUpdate={handleUpdate}
+        empty={empty}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+
+PublicRegistryArticle.displayName = 'PublicRegistryArticle';

package/src/containers/PublicRegistryArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { PublicRegistryArticle as default, PublicRegistryArticle } from './PublicRegistryArticle';

package/src/containers/RegistryArticle/RegistryArticle.tsx

@@ -0,0 +1,53 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import React, { useMemo } from 'react';
+
+import { type Plugin, type PluginManager } from '@dxos/app-framework';
+import { usePluginManager } from '@dxos/app-framework/ui';
+import { composable } from '@dxos/ui-theme';
+
+import { BaseRegistryArticle } from '../BaseRegistryArticle';
+
+const sortByPluginMeta = (a: Plugin.Plugin, b: Plugin.Plugin) =>
+  (a.meta.name ?? a.meta.id).localeCompare(b.meta.name ?? b.meta.id);
+
+export type RegistryArticleProps = {
+  id: string;
+  plugins: Plugin.Plugin[];
+  /**
+   * Map from plugin id → display-only tags (e.g. `registry`, `local`) computed by the caller.
+   */
+  extraTagsById?: Record<string, readonly string[]>;
+};
+
+export const RegistryArticle = composable<HTMLDivElement, RegistryArticleProps>(
+  ({ id, plugins: pluginsProp, extraTagsById, ...props }, forwardedRef) => {
+    const manager = usePluginManager();
+    const failed = useAtomValue(manager.failed);
+    const plugins = useMemo(() => [...pluginsProp].sort(sortByPluginMeta), [pluginsProp]);
+    const failuresById = useMemo(
+      () =>
+        failed.reduce<Record<string, PluginManager.PluginFailure>>((acc, failure) => {
+          acc[failure.id] = failure;
+          return acc;
+        }, {}),
+      [failed],
+    );
+
+    return (
+      <BaseRegistryArticle
+        {...props}
+        id={id}
+        plugins={plugins}
+        extraTagsById={extraTagsById}
+        failuresById={failuresById}
+        ref={forwardedRef}
+      />
+    );
+  },
+);
+
+RegistryArticle.displayName = 'RegistryArticle';

package/src/containers/RegistryArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { RegistryArticle as default, RegistryArticle } from './RegistryArticle';