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

package/src/containers/RegistrySettingsContainer/RegistrySettingsContainer.tsx

@@ -0,0 +1,59 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback } from 'react';
+
+import { useSettingsState, usePluginManager } from '@dxos/app-framework/ui';
+import { type AppCapabilities } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { RegistrySettings } from '../../components';
+import { type RegistrySettings as RegistrySettingsType } from '../../types';
+
+export type RegistrySettingsContainerProps = {
+  subject: AppCapabilities.Settings;
+};
+
+/**
+ * Wires the {@link RegistrySettings} presentational component to the plugin
+ * manager and the settings atom: subscribes to `manager.devPluginIds` for the
+ * "currently loaded" indicator and exposes enable/disable callbacks that drive
+ * the manager's add/enable/remove flow.
+ */
+export const RegistrySettingsContainer = ({ subject }: RegistrySettingsContainerProps) => {
+  const manager = usePluginManager();
+  const { settings, updateSettings } = useSettingsState<RegistrySettingsType>(subject.atom);
+  const activeDevPluginIds = useAtomValue(manager.devPluginIds);
+
+  const onEnableDev = useCallback(
+    async (url: string) => {
+      await runAndForwardErrors(
+        Effect.gen(function* () {
+          const plugin = yield* manager.add(url);
+          yield* manager.enable(plugin.meta.id);
+        }),
+      );
+    },
+    [manager],
+  );
+
+  const onDisableDev = useCallback(
+    async (id: string) => {
+      await runAndForwardErrors(manager.remove(id));
+    },
+    [manager],
+  );
+
+  return (
+    <RegistrySettings
+      settings={settings}
+      onSettingsChange={updateSettings}
+      activeDevPluginIds={activeDevPluginIds}
+      onEnableDev={onEnableDev}
+      onDisableDev={onDisableDev}
+    />
+  );
+};

package/src/containers/RegistrySettingsContainer/index.ts

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

package/src/containers/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export { LOAD_PLUGIN_DIALOG } from './LoadPluginDialog/LoadPluginDialog';
+export const LoadPluginDialog: ComponentType<any> = lazy(() => import('./LoadPluginDialog'));
+export const PluginArticle: ComponentType<any> = lazy(() => import('./PluginArticle'));
+export const PublicRegistryArticle: ComponentType<any> = lazy(() => import('./PublicRegistryArticle'));
+export const RegistryArticle: ComponentType<any> = lazy(() => import('./RegistryArticle'));
+export const RegistrySettingsContainer: ComponentType<any> = lazy(() => import('./RegistrySettingsContainer'));

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './use-auto-tags';
+export * from './use-disable-confirmation';
+export * from './use-registry-plugins';
+export * from './use-update-available';

package/src/hooks/use-auto-tags.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { type Registry, UrlLoader } from '@dxos/app-framework';
+
+/**
+ * Auto-tags that are derived at display time rather than persisted to `Plugin.Meta`.
+ * - `registry`: plugin id appears in the registry catalog manifest.
+ * - `local`: plugin was loaded from a `localhost` / `127.0.0.1` / `::1` URL.
+ */
+export type AutoTagsMap = Record<string, readonly string[]>;
+
+/**
+ * Computes the per-plugin-id extra tags the UI should display.
+ *
+ * Reads the persisted remote-plugin entries synchronously to derive `local`, and
+ * adds `registry` for any plugin id found in the supplied registry manifest entries.
+ */
+export const useAutoTags = (registryEntries: readonly Registry.Plugin[]): AutoTagsMap =>
+  useMemo(() => {
+    const byId: Record<string, string[]> = {};
+    const addTag = (id: string, tag: string) => {
+      const existing = byId[id];
+      if (!existing) {
+        byId[id] = [tag];
+      } else if (!existing.includes(tag)) {
+        existing.push(tag);
+      }
+    };
+
+    for (const entry of UrlLoader.getRemoteEntries()) {
+      if (UrlLoader.isLocalUrl(entry.url)) {
+        addTag(entry.id, 'local');
+      }
+    }
+    for (const entry of registryEntries) {
+      addTag(entry.id, 'registry');
+    }
+
+    return byId;
+  }, [registryEntries]);
+
+/**
+ * Returns the set of plugin ids known to originate from a remote URL (not bundled).
+ * Used to filter the Official/Recommended sections so third-party plugins are excluded.
+ */
+export const useRemotePluginIds = (): ReadonlySet<string> =>
+  useMemo(() => new Set(UrlLoader.getRemoteEntries().map((entry) => entry.id)), []);

package/src/hooks/use-disable-confirmation.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/use-registry-plugins.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/use-update-available.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/index.ts

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

package/src/meta.ts

@@ -2,17 +2,32 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { pinnedWorkspaceId } from '@dxos/app-toolkit';
+import { trim } from '@dxos/util';
 
-export const REGISTRY_PLUGIN = 'dxos.org/plugin/registry';
-
-// TODO(wittjosiah): Deck does not currently support `/` in ids.
-// TODO(wittjosiah): This is a hack to prevent the previous deck from being set for pinned items.
-//  Ideally this should be worked into the data model in a generic way.
-export const REGISTRY_ID = '!dxos:plugin-registry';
+export const REGISTRY_ID = pinnedWorkspaceId('dxos:plugin-registry');
 export const REGISTRY_KEY = 'plugin-registry';
 
-export const meta: PluginMeta = {
-  id: REGISTRY_PLUGIN,
+// 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}`;
+
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.registry',
   name: 'Plugins',
+  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/storage.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as FileSystem from '@effect/platform/FileSystem';
+import * as Path from '@effect/platform/Path';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import * as Yaml from 'yaml';
+
+import { DX_CONFIG } from '@dxos/client-protocol';
+
+// TODO(wittjosiah): Factor out to app-framework?
+
+const PluginsSchema = Schema.Array(Schema.String);
+
+/** CLI-only: path to plugins/<profile>.yml (sibling to profile/). */
+const getPluginsConfigPath = (profile: string) => `${DX_CONFIG}/plugins/${profile}.yml`;
+
+/**
+ * Load enabled plugins from plugins/<profile>.yml (sibling to profile/).
+ * Returns the list of enabled plugin IDs, or an empty array if the file doesn't exist.
+ */
+export const loadEnabledPlugins = Effect.fn(function* ({ profile }: { profile: string }) {
+  const fs = yield* FileSystem.FileSystem;
+  const pluginsPath = getPluginsConfigPath(profile);
+
+  const content = yield* fs
+    .readFileString(pluginsPath)
+    .pipe(Effect.catchTag('SystemError', () => Effect.succeed('[]')));
+
+  const raw = Yaml.parse(content);
+  const parsed = yield* Schema.decodeUnknown(PluginsSchema)(raw ?? []).pipe(
+    Effect.catchAll(() => Effect.succeed([] as string[])),
+  );
+
+  return parsed;
+});
+
+/**
+ * Save enabled plugins to plugins/<profile>.yml.
+ */
+export const saveEnabledPlugins = Effect.fn(function* ({ profile, enabled }: { profile: string; enabled: string[] }) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const pluginsPath = getPluginsConfigPath(profile);
+  yield* fs.makeDirectory(path.dirname(pluginsPath), { recursive: true });
+  const encoded = Yaml.stringify(enabled);
+  yield* fs.writeFileString(pluginsPath, encoded);
+});

package/src/translations.ts

@@ -4,26 +4,70 @@
 
 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',
+        'plugin-registry.label': 'Plugins',
+        'plugin-settings.label': 'Plugin Settings',
+        'official-plugins.label': 'Official',
+        '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': 'Requires',
+        'dependents.label': 'Required by',
+        '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',
       },
     },
   },

package/src/types.ts

@@ -2,12 +2,48 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import { type Atom } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
 
 export const RegistrySettingsSchema = Schema.mutable(
   Schema.Struct({
     experimental: Schema.optional(Schema.Boolean),
+    /**
+     * Manifest URL for a plugin served by a local Vite dev server. The
+     * registry settings panel pre-fills this with `localhost:3967`; authors
+     * iterating on a different port can edit it.
+     */
+    devPluginUrl: Schema.optional(Schema.String),
+    /**
+     * When true, the registry plugin attempts to load `devPluginUrl` on every
+     * app boot. Failures (dev server offline, manifest 404) are logged and
+     * the flag stays on so the next boot retries — the user explicitly turns
+     * it off when they're done iterating.
+     */
+    devPluginEnabled: Schema.optional(Schema.Boolean),
   }),
 );
 
 export type RegistrySettings = Schema.Schema.Type<typeof RegistrySettingsSchema>;
+
+/**
+ * Per-plugin capabilities exposed by `@dxos/plugin-registry`.
+ */
+export namespace RegistryCapabilities {
+  export const Settings = Capability.make<Atom.Writable<RegistrySettings>>('@dxos/plugin-registry/settings');
+}
+
+export const RegistryTagType = Schema.Literal(
+  'new',
+  'beta',
+  'labs',
+  'popular',
+  'featured',
+  'experimental',
+  'registry',
+  'local',
+);
+
+export type RegistryTagType = Schema.Schema.Type<typeof RegistryTagType>;