@dxos/plugin-registry 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/hooks/useDisableConfirmation.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback } from 'react';
+
+import { type PluginManager } from '@dxos/app-framework';
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+
+import { DISABLE_DEPENDENTS_DIALOG } from '#meta';
+
+/**
+ * Returns `requestDisable(pluginId)` that gates `manager.disable` on a
+ * confirmation prompt when the target has currently-enabled dependents.
+ *
+ * `PluginManager.disable` cascades by default; this hook is the UX safeguard
+ * around that. The caller supplies a `dispatch` callback that performs the
+ * actual disable (wrapping it with observability or any other side effects).
+ * When there are no enabled dependents, dispatch runs immediately; otherwise
+ * we open the shared {@link DISABLE_DEPENDENTS_DIALOG} surface — its
+ * `onConfirm` runs the dispatch and closes the dialog.
+ *
+ * Display-name resolution for the dialog is delegated to the registered
+ * plugin set (`Plugin.Meta.name`). Per-plugin i18n translations only load
+ * when a plugin is activated, so `meta.name` is the only label always
+ * available regardless of enabled state.
+ */
+export const useDisableConfirmation = (manager: PluginManager.PluginManager, dispatch: (id: string) => void) => {
+  const { invokePromise } = useOperationInvoker();
+
+  return useCallback(
+    (pluginId: string): void => {
+      const enabledDependents = manager.getDependents(pluginId, { transitive: true, enabledOnly: true });
+      if (enabledDependents.length === 0) {
+        dispatch(pluginId);
+        return;
+      }
+      const resolveName = (id: string): string =>
+        manager.getPlugins().find((plugin) => plugin.meta.id === id)?.meta.name ?? id;
+      void invokePromise(LayoutOperation.UpdateDialog, {
+        subject: DISABLE_DEPENDENTS_DIALOG,
+        state: true,
+        type: 'alert',
+        props: {
+          pluginId,
+          dependents: enabledDependents,
+          onResolvePluginName: resolveName,
+          onConfirm: () => {
+            dispatch(pluginId);
+            void invokePromise(LayoutOperation.UpdateDialog, { state: false });
+          },
+        },
+      });
+    },
+    [manager, dispatch, invokePromise],
+  );
+};

package/src/hooks/useInstalledVersionTag.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback, useEffect, useState } from 'react';
+
+import { type Plugin, UrlLoader } from '@dxos/app-framework';
+
+/**
+ * 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.
+ */
+export 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 };
+};

package/src/hooks/usePluginActions.ts

@@ -0,0 +1,174 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { useCallback, useState } from 'react';
+
+import { type PluginManager, type Registry, UrlLoader } from '@dxos/app-framework';
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { runAndForwardErrors } from '@dxos/effect';
+import { useNode } from '@dxos/plugin-graph';
+
+import { getPluginSpecPath } from '#meta';
+
+import { useDisableConfirmation } from './useDisableConfirmation';
+
+export type PluginActionsProps = {
+  manager: PluginManager.PluginManager;
+  pluginId: string;
+  isInstalled: boolean;
+  moduleUrl: string | undefined;
+  catalogEntry: Registry.Plugin | undefined;
+  pickerVersions: readonly Registry.PluginVersion[];
+  selectedVersionTag: string | undefined;
+  syncInstalledVersion: () => void;
+};
+
+export type PluginActions = {
+  installing: boolean;
+  updating: boolean;
+  handleEnableChange: (enabled: boolean) => void;
+  handleUninstall: () => void;
+  handleInstall: () => void;
+  handleUpdate: () => void;
+  handleInstallVersion: () => void;
+  handleOpenSpec?: () => void;
+};
+
+/**
+ * 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.
+ *
+ * `handleOpenSpec` is included only when a `spec` child graph node exists for
+ * this plugin — contributed by whichever plugin can render MDL (today
+ * `plugin-code`). When that contributor isn't enabled, the action is absent
+ * and the detail view hides its "Open Specification" chip.
+ */
+export const usePluginActions = ({
+  manager,
+  pluginId,
+  isInstalled,
+  moduleUrl,
+  catalogEntry,
+  pickerVersions,
+  selectedVersionTag,
+  syncInstalledVersion,
+}: PluginActionsProps): PluginActions => {
+  const { invokePromise } = useOperationInvoker();
+  const { graph } = useAppGraph();
+
+  const [installing, setInstalling] = useState(false);
+  const [updating, setUpdating] = useState(false);
+  const requestDisable = useDisableConfirmation(manager, (id) => void runAndForwardErrors(manager.disable(id)));
+
+  const specPath = getPluginSpecPath(pluginId);
+  const hasSpecNode = !!useNode(graph, specPath);
+  const handleOpenSpec = useCallback(() => {
+    void invokePromise(LayoutOperation.Open, { subject: [specPath] });
+  }, [invokePromise, specPath]);
+
+  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,
+    handleOpenSpec: hasSpecNode ? handleOpenSpec : undefined,
+  };
+};

package/src/hooks/useRegistryPlugins.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+
+import { type Registry } from '@dxos/app-framework';
+import { usePluginManager } from '@dxos/app-framework/ui';
+
+/**
+ * Reads the registry plugin catalog from `manager.pluginRegistry.plugins`.
+ * The catalog is loaded once when the plugin manager is constructed (with a
+ * provider) so this hook is purely reactive — subscribers re-render as the
+ * `{entries, loading, error}` state settles.
+ */
+export const useRegistryPlugins = (): Registry.PluginsState => {
+  const manager = usePluginManager();
+  return useAtomValue(manager.pluginRegistry.plugins);
+};
+
+/**
+ * Returns the live `Registry.Manager` from the plugin manager so callers can
+ * issue `listVersions` / `getPlugin` calls directly. The catalog state itself
+ * is best read through {@link useRegistryPlugins} above.
+ */
+export const useRegistryPluginProvider = (): Registry.Manager => {
+  const manager = usePluginManager();
+  return manager.pluginRegistry;
+};

package/src/hooks/useUpdateAvailable.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Registry, UrlLoader } from '@dxos/app-framework';
+
+/**
+ * Returns a set of plugin ids for which the registry has a newer version
+ * than what was recorded at install time.
+ *
+ * Only flags plugins where a version was recorded at install time AND it differs
+ * from the catalog's current version. Legacy installs (no version stored) are ignored.
+ *
+ * NOTE: this is intentionally NOT memoised. The installed-version side of the
+ * comparison lives in localStorage and is mutated by `manager.add` /
+ * `manager.remove` / `UrlLoader.setInstalledVersion` outside React's view, so a
+ * memo keyed on `entries` would happily return stale data for the rest of the
+ * session after an update completes (the bug that produced "Update button
+ * reappears after Updating…"). The loop is O(catalog size) sync reads — cheap
+ * enough to do every render.
+ */
+export const useUpdateAvailableIds = (entries: readonly Registry.Plugin[]): ReadonlySet<string> => {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    const installedVersion = UrlLoader.getInstalledVersion(entry.id);
+    if (installedVersion !== undefined && installedVersion !== entry.version) {
+      ids.add(entry.id);
+    }
+  }
+  return ids;
+};

package/src/hooks/useVersionPicker.ts

@@ -0,0 +1,112 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { type Dispatch, type SetStateAction, useEffect, useMemo, useState } from 'react';
+
+import { type Registry, UrlLoader } from '@dxos/app-framework';
+import { runAndForwardErrors } from '@dxos/effect';
+
+/**
+ * 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).
+ */
+export 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. Reset state
+  // when `repo` is absent or the fetch fails so a previous plugin's
+  // versions don't leak into the picker for the current plugin. The
+  // `cancelled` flag guards against a stale in-flight `listVersions`
+  // response overwriting the newer state after `repo`/`pluginId` changes.
+  useEffect(() => {
+    if (!repo) {
+      setVersions([]);
+      setSelectedVersionTag(undefined);
+      return;
+    }
+    // Clear stale picker state before fetching so the UI doesn't display the
+    // previous plugin's versions/selection while `listVersions` is pending.
+    setVersions([]);
+    setSelectedVersionTag(undefined);
+    let cancelled = false;
+    void provider.listVersions(repo).pipe(
+      Effect.match({
+        onSuccess: (vs) => {
+          if (cancelled) {
+            return;
+          }
+          setVersions(vs);
+          // Default selection: the currently installed version, or the latest.
+          const installedVersion = UrlLoader.getInstalledVersion(pluginId);
+          setSelectedVersionTag(installedVersion ?? vs[0]?.tag);
+        },
+        onFailure: () => {
+          if (cancelled) {
+            return;
+          }
+          setVersions([]);
+          setSelectedVersionTag(undefined);
+        },
+      }),
+      runAndForwardErrors,
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [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 };
+};

package/src/index.ts

@@ -3,4 +3,4 @@
 //
 
 export * from './meta';
-export * from './RegistryPlugin';
+export * from './storage';

package/src/meta.ts

@@ -3,19 +3,44 @@
 //
 
 import { type Plugin } from '@dxos/app-framework';
+import { pinnedWorkspaceId } from '@dxos/app-toolkit';
 import { trim } from '@dxos/util';
 
-export const REGISTRY_ID = '!dxos:plugin-registry';
+export const REGISTRY_ID = pinnedWorkspaceId('dxos:plugin-registry');
 export const REGISTRY_KEY = 'plugin-registry';
 
+// TODO(wittjosiah): Should this be a special separator or use the standard path separator?
+const CATEGORY_SEPARATOR = '>';
+
+/** Build a registry category node ID. */
+export const registryCategoryId = (category: string): string => `${REGISTRY_KEY}${CATEGORY_SEPARATOR}${category}`;
+
 /** Qualified graph path to a specific plugin node. */
 export const getPluginPath = (pluginId: string): string => `root/${REGISTRY_ID}/${pluginId}`;
 
+/**
+ * Qualified graph path to the bundled MDL spec child node for a plugin.
+ *
+ * The child is contributed by whichever plugin can render MDL (today:
+ * `plugin-code`). plugin-registry only knows the path convention so it can:
+ *  - dispatch `LayoutOperation.Open` to open the spec viewer, and
+ *  - probe the app graph for the child's existence to gate the "View
+ *    specification" button. If no plugin contributes a renderer for the
+ *    child, the node is absent and the button stays hidden.
+ */
+export const getPluginSpecPath = (pluginId: string): string => `${getPluginPath(pluginId)}/spec`;
+
 export const meta: Plugin.Meta = {
   id: 'org.dxos.plugin.registry',
   name: 'Plugins',
+  author: 'DXOS',
   description: trim`
     Plugin management system for discovering, installing, and configuring workspace extensions.
     Browse available plugins and customize your workspace capabilities.
   `,
+  icon: 'ph--squares-four--regular',
+  tags: ['system'],
 };
+
+/** Cascade-disable confirmation dialog surface id. */
+export const DISABLE_DEPENDENTS_DIALOG = `${meta.id}.disable-dependents-dialog`;

package/src/operations/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const RegistryOperationHandlerSet = OperationHandlerSet.lazy(() => import('./open-plugin-registry'));

package/src/operations/open-plugin-registry.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { LayoutOperation, SettingsOperation, getSpacePath } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+
+import { REGISTRY_ID } from '#meta';
+
+const handler: Operation.WithHandler<typeof SettingsOperation.OpenPluginRegistry> =
+  SettingsOperation.OpenPluginRegistry.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* () {
+        yield* Operation.invoke(LayoutOperation.SwitchWorkspace, { subject: getSpacePath(REGISTRY_ID) });
+      }),
+    ),
+  );
+
+export default handler;

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const RegistryPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { RegistryOperationHandlerSet } from './operations';

package/src/translations.ts

@@ -4,26 +4,73 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Registry',
-        'details label': 'Details',
-        'home page label': 'Website',
-        'source label': 'Source',
-        'plugin registry label': 'Plugin Registry',
-        'all plugins label': 'All',
-        'installed plugins label': 'Enabled',
-        'recommended plugins label': 'Recommended',
-        'labs plugins label': 'Labs',
-        'community plugins label': 'Community',
-        'load by url label': 'Load by URL (soon)',
-        'coming soon label': 'Coming soon!',
-        'open plugin registry label': 'Open plugin registry',
-        'settings label': 'Settings',
+        'plugin.name': 'Registry',
+        'details.label': 'Details',
+        'home-page.label': 'Website',
+        'source.label': 'Source',
+        'resources.label': 'Resources',
+        'plugin-registry.label': 'Plugins',
+        'plugin-settings.label': 'Plugin Settings',
+        'bundled-plugins.label': 'Bundled',
+        'installed-plugins.label': 'Enabled',
+        'recommended-plugins.label': 'Recommended',
+        'labs-plugins.label': 'Labs',
+        'registry-plugins.label': 'Registry',
+        'load-by-url.label': 'Load from URL',
+        'load-by-url-dialog.title': 'Load Plugin from URL',
+        'plugin-url.label': 'Plugin URL',
+        'load-plugin.label': 'Load Plugin',
+        'loading.label': 'Loading...',
+        'filter.label': 'Filter plugins',
+        'filter.placeholder': 'Filter…',
+        'registry.loading.label': 'Loading registry plugins…',
+        'registry.error.label': 'Failed to load registry plugins: {{message}}',
+        'registry.empty.label': 'No registry plugins available.',
+        'dev-plugin.section.title': 'Dev plugin',
+        'dev-plugin.description':
+          'Load a plugin from a local Vite dev server (the `composerPlugin` defaults to port 3967). Composer reattaches it on every reload, surviving HMR — useful when iterating on a community plugin against a live registry version.',
+        'dev-plugin.url.label': 'Manifest URL',
+        'dev-plugin.url.description':
+          'Defaults to the local dev server. Edit if your dev server runs on a different port.',
+        'dev-plugin.toggle.label': 'Dev plugin',
+        'dev-plugin.toggle.description':
+          'Stays on across reloads. If the dev server is offline at boot, a warning is logged and the next reload retries.',
+        'dev-plugin.enable.label': 'Enable',
+        'dev-plugin.disable.label': 'Disable',
+        'dev-plugin.busy.label': 'Loading…',
+        'dev-plugin.not-loaded.message':
+          'Dev plugin is enabled but not currently loaded. Check that the dev server is running, then reload.',
+        'coming-soon.label': 'Coming soon!',
+        'open-plugin-registry.label': 'Open plugin registry',
+        'install.label': 'Install',
+        'installing.label': 'Installing…',
+        'uninstall.label': 'Uninstall',
+        'update.label': 'Update',
+        'updating.label': 'Updating…',
+        'versions.label': 'Versions',
+        'installed.label': 'installed',
+        'install-version.label': 'Install version',
+        'failure-badge.label': 'Plugin failure details',
+        'failure-title.label': 'Plugin {{phase}} failed: {{reason}}',
+        'failure-phase-load.label': 'load',
+        'failure-phase-activation.label': 'activation',
+        'failure-reason-timeout.label': 'timed out',
+        'failure-reason-error.label': 'error',
+        'dependencies.label': 'Dependencies',
+        'dependents.label': 'Required by',
+        'spec.label': 'Specification',
+        'open-spec.label': 'Open Specification',
+        'disable-dependents-dialog.title': 'Disable dependent plugins?',
+        'disable-dependents-dialog.description':
+          'Disabling {{plugin}} will also disable the following plugins that depend on it:',
+        'disable-dependents-dialog.confirm.label': 'Disable',
+        'cancel.label': 'Cancel',
       },
     },
   },