@dxos/plugin-registry 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/capabilities/index.ts

@@ -2,8 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { lazy } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
 
-export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
-export const IntentResolver = lazy(() => import('./intent-resolver'));
-export const ReactSurface = lazy(() => import('./react-surface'));
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
+export const DevPluginLoader = Capability.lazy('DevPluginLoader', () => import('./dev-plugin-loader'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const RegistrySettings = Capability.lazy('RegistrySettings', () => import('./settings'));

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { RegistryOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, RegistryOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -2,89 +2,125 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { useCallback, useMemo } from 'react';
+import * as Effect from 'effect/Effect';
+import React, { type ComponentProps, useMemo } from 'react';
 
-import { Capabilities, Plugin, contributes, createSurface, usePluginManager } from '@dxos/app-framework';
-import { StackItem } from '@dxos/react-ui-stack';
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { Surface, usePluginManager } from '@dxos/app-framework/ui';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 
-import { PluginDetail, RegistryContainer } from '../components';
-import { REGISTRY_KEY, REGISTRY_PLUGIN } from '../meta';
+import { DisableDependentsAlert } from '#components';
+import {
+  LOAD_PLUGIN_DIALOG,
+  LoadPluginDialog,
+  PluginArticle,
+  PublicRegistryArticle,
+  RegistryArticle,
+  RegistrySettingsContainer,
+} from '#containers';
+import { DISABLE_DEPENDENTS_DIALOG, meta, registryCategoryId } from '#meta';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: `${REGISTRY_PLUGIN}/all`,
-      role: 'article',
-      filter: (data): data is any => data.subject === `${REGISTRY_KEY}+all`,
-      component: () => {
-        const manager = usePluginManager();
-        const filtered = useMemo(() => manager.plugins.filter(({ meta }) => !manager.core.includes(meta.id)), []);
+import { type PluginPredicate, getCategoryPredicate } from '../categories';
+import { useAutoTags, useRegistryPlugins, useRemotePluginIds } from '../hooks';
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+all`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${REGISTRY_PLUGIN}/installed`,
-      role: 'article',
-      filter: (data): data is any => data.subject === `${REGISTRY_KEY}+installed`,
-      component: () => {
-        const manager = usePluginManager();
-        const filtered = useMemo(
-          () =>
-            manager.plugins
-              .filter(({ meta }) => !manager.core.includes(meta.id))
-              .filter(({ meta }) => manager.enabled.includes(meta.id)),
-          [],
-        );
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'bundled',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('bundled')),
+        component: () => {
+          const predicate = useCategoryPredicate(registryCategoryId('bundled'));
+          return <FilteredRegistryArticle id={registryCategoryId('bundled')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'installed',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('installed')),
+        component: () => {
+          const predicate = useCategoryPredicate(registryCategoryId('installed'));
+          return <FilteredRegistryArticle id={registryCategoryId('installed')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'recommended',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('recommended')),
+        component: () => {
+          const predicate = useCategoryPredicate(registryCategoryId('recommended'));
+          return <FilteredRegistryArticle id={registryCategoryId('recommended')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'labs',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('labs')),
+        component: () => {
+          const predicate = useCategoryPredicate(registryCategoryId('labs'));
+          return <FilteredRegistryArticle id={registryCategoryId('labs')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'registry',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('registry')),
+        component: () => <PublicRegistryArticle id={registryCategoryId('registry')} />,
+      }),
+      Surface.create({
+        id: 'pluginDetails',
+        filter: AppSurface.subject(AppSurface.Article, Plugin.isPlugin),
+        component: ({ data: { subject } }) => {
+          return <PluginArticle subject={subject} />;
+        },
+      }),
+      Surface.create({
+        id: LOAD_PLUGIN_DIALOG,
+        filter: AppSurface.component(AppSurface.Dialog, LOAD_PLUGIN_DIALOG),
+        component: () => <LoadPluginDialog />,
+      }),
+      Surface.create({
+        id: DISABLE_DEPENDENTS_DIALOG,
+        filter: AppSurface.component<ComponentProps<typeof DisableDependentsAlert>>(
+          AppSurface.Dialog,
+          DISABLE_DEPENDENTS_DIALOG,
+        ),
+        component: ({ data }) => <DisableDependentsAlert {...data.props} />,
+      }),
+      Surface.create({
+        id: 'pluginSettings',
+        role: 'article',
+        filter: (data): data is { subject: AppCapabilities.Settings } =>
+          AppCapabilities.isSettings(data.subject) && data.subject.prefix === meta.id,
+        component: ({ data: { subject } }) => <RegistrySettingsContainer subject={subject} />,
+      }),
+    ]),
+  ),
+);
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+installed`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${REGISTRY_PLUGIN}/recommended`,
-      role: 'article',
-      filter: (data): data is any => data.subject === `${REGISTRY_KEY}+recommended`,
-      component: () => {
-        const manager = usePluginManager();
-        const filtered = useMemo(
-          () =>
-            manager.plugins
-              .filter(({ meta }) => !manager.core.includes(meta.id))
-              .filter(({ meta }) => !meta.tags?.includes('labs')),
-          [],
-        );
+/**
+ * Resolves the {@link PluginPredicate} for a registry category against the live plugin list.
+ * Shared with the graph builder via {@link getCategoryPredicate} so the category lists and their counts agree.
+ */
+const useCategoryPredicate = (category: string): PluginPredicate => {
+  const manager = usePluginManager();
+  const remoteIds = useRemotePluginIds();
+  const core = useMemo(() => manager.getCore(), [manager]);
+  const enabled = useMemo(() => manager.getEnabled(), [manager]);
+  return useMemo(
+    () => getCategoryPredicate(category, { core, enabled, remoteIds }),
+    [category, core, enabled, remoteIds],
+  );
+};
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+recommended`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${REGISTRY_PLUGIN}/labs`,
-      role: 'article',
-      filter: (data): data is any => data.subject === `${REGISTRY_KEY}+labs`,
-      component: () => {
-        const manager = usePluginManager();
-        const filtered = useMemo(() => manager.plugins.filter(({ meta }) => meta.tags?.includes('labs')), []);
+/**
+ * Renders the {@link RegistryArticle} surface filtered by an arbitrary
+ * predicate computed against the live plugin list. Centralises the
+ * `usePluginManager` + `useRegistryPlugins` + `useAutoTags` wiring shared
+ * by every category surface.
+ */
+const FilteredRegistryArticle = ({ id, filter }: { id: string; filter: PluginPredicate }) => {
+  const manager = usePluginManager();
+  const { entries } = useRegistryPlugins();
+  const extraTagsById = useAutoTags(entries);
+  const filtered = useMemo(() => manager.getPlugins().filter(filter), [manager, filter]);
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+labs`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${REGISTRY_PLUGIN}/plugin-details`,
-      role: 'article',
-      filter: (data): data is { subject: Plugin } => data.subject instanceof Plugin,
-      component: ({ data: { subject } }) => {
-        const manager = usePluginManager();
-        const enabled = manager.enabled.includes(subject.meta.id);
-        const handleEnable = useCallback(
-          () => (enabled ? manager.disable(subject.meta.id) : manager.enable(subject.meta.id)),
-          [manager, subject.meta.id, enabled],
-        );
-
-        return (
-          <StackItem.Content>
-            <PluginDetail plugin={subject} enabled={enabled} onEnable={handleEnable} />
-          </StackItem.Content>
-        );
-      },
-    }),
-  ]);
+  return <RegistryArticle id={id} plugins={filtered} extraTagsById={extraTagsById} />;
+};

package/src/capabilities/settings.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability, PLUGIN_DEV_SERVER_PORT } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
+
+import { meta } from '#meta';
+
+import { RegistryCapabilities, RegistrySettingsSchema } from '../types';
+
+const DEFAULT_DEV_PLUGIN_URL = `http://localhost:${PLUGIN_DEV_SERVER_PORT}/manifest.json`;
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: RegistrySettingsSchema,
+      defaultValue: () => ({ devPluginUrl: DEFAULT_DEV_PLUGIN_URL }),
+    });
+
+    return [
+      Capability.contributes(RegistryCapabilities.Settings, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.id,
+        schema: RegistrySettingsSchema,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/categories.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Plugin, UrlLoader } from '@dxos/app-framework';
+
+import { registryCategoryId } from './meta';
+
+export type PluginPredicate = (plugin: Plugin.Plugin) => boolean;
+
+export type CategoryFilterContext = {
+  /** Core (bundled-by-default) plugin ids. */
+  core: readonly string[];
+  /** Enabled plugin ids. */
+  enabled: readonly string[];
+  /** Plugin ids loaded from a remote URL (not bundled). */
+  remoteIds: ReadonlySet<string>;
+};
+
+/**
+ * Predicate selecting the plugins shown in a registry category, computed against the live plugin list.
+ * The `registry` category is sourced from the catalog rather than the local plugin list and is not handled here.
+ */
+export const getCategoryPredicate = (
+  category: string,
+  { core, enabled, remoteIds }: CategoryFilterContext,
+): PluginPredicate => {
+  switch (category) {
+    case registryCategoryId('bundled'):
+      return ({ meta }) => !core.includes(meta.id) && !remoteIds.has(meta.id);
+    case registryCategoryId('installed'):
+      return ({ meta }) => !core.includes(meta.id) && enabled.includes(meta.id);
+    case registryCategoryId('recommended'):
+      return ({ meta }) => !core.includes(meta.id) && !remoteIds.has(meta.id) && !meta.tags?.includes('labs');
+    case registryCategoryId('labs'):
+      return ({ meta }) => meta.tags?.includes('labs') ?? false;
+    default:
+      return () => false;
+  }
+};
+
+/** Set of plugin ids known to originate from a remote URL (not bundled). */
+export const getRemotePluginIds = (): ReadonlySet<string> =>
+  new Set(UrlLoader.getRemoteEntries().map((entry) => entry.id));

package/src/commands/disable.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Args from '@effect/cli/Args';
+import * as Command from '@effect/cli/Command';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { Plugin } from '@dxos/app-framework';
+import { CommandConfig } from '@dxos/cli-util';
+import { invariant } from '@dxos/invariant';
+
+import { saveEnabledPlugins } from '../storage';
+
+export const handler = Effect.fn(function* ({ id }: { id: string }) {
+  const { json, profile } = yield* CommandConfig;
+  const manager = yield* Plugin.Service;
+
+  const plugins = manager.getPlugins();
+  const plugin = plugins.find((p: Plugin.Plugin) => p.meta.id === id);
+  invariant(plugin, `Plugin not found: ${id}`);
+
+  const core = manager.getCore();
+  invariant(!core.includes(id), `Cannot disable core plugin: ${id}`);
+
+  const disabled = yield* manager.disable(id);
+  invariant(disabled, `Failed to disable plugin: ${id}`);
+
+  // Save enabled plugins to storage
+  const enabledPlugins = manager.getEnabled();
+  yield* saveEnabledPlugins({ profile, enabled: [...enabledPlugins] });
+
+  if (json) {
+    yield* Console.log(JSON.stringify({ id, enabled: false }, null, 2));
+  } else {
+    yield* Console.log(`Plugin "${plugin.meta.name ?? id}" disabled.`);
+  }
+});
+
+export const disable = Command.make(
+  'disable',
+  {
+    id: Args.text({ name: 'id' }).pipe(Args.withDescription('The ID of the plugin to disable.')),
+  },
+  handler,
+).pipe(Command.withDescription('Disable a plugin.'));

package/src/commands/enable.ts

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Args from '@effect/cli/Args';
+import * as Command from '@effect/cli/Command';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { Plugin } from '@dxos/app-framework';
+import { CommandConfig } from '@dxos/cli-util';
+import { invariant } from '@dxos/invariant';
+
+import { saveEnabledPlugins } from '../storage';
+
+export const handler = Effect.fn(function* ({ id }: { id: string }) {
+  const { json, profile } = yield* CommandConfig;
+  const manager = yield* Plugin.Service;
+
+  const plugins = manager.getPlugins();
+  const plugin = plugins.find((p: Plugin.Plugin) => p.meta.id === id);
+  invariant(plugin, `Plugin not found: ${id}`);
+
+  const enabled = yield* manager.enable(id);
+  invariant(enabled, `Failed to enable plugin: ${id}`);
+
+  // Save enabled plugins to storage
+  const enabledPlugins = manager.getEnabled();
+  yield* saveEnabledPlugins({ profile, enabled: [...enabledPlugins] });
+
+  if (json) {
+    yield* Console.log(JSON.stringify({ id, enabled: true }, null, 2));
+  } else {
+    yield* Console.log(`Plugin "${plugin.meta.name ?? id}" enabled.`);
+  }
+});
+
+export const enable = Command.make(
+  'enable',
+  {
+    id: Args.text({ name: 'id' }).pipe(Args.withDescription('The ID of the plugin to enable.')),
+  },
+  handler,
+).pipe(Command.withDescription('Enable a plugin.'));

package/src/commands/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+
+import { disable } from './disable';
+import { enable } from './enable';
+import { list } from './list';
+
+export const plugin: Command.Command<any, any, any, any> = Command.make('plugin').pipe(
+  Command.withDescription('Manage plugins.'),
+  Command.withSubcommands([enable, disable, list]),
+);

package/src/commands/list.ts

@@ -0,0 +1,41 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Command from '@effect/cli/Command';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import { Plugin } from '@dxos/app-framework';
+import { CommandConfig, printList } from '@dxos/cli-util';
+
+import { type FormattedPlugin, printPlugin } from './util';
+
+export const handler = Effect.fn(function* () {
+  const { json } = yield* CommandConfig;
+  const manager = yield* Plugin.Service;
+
+  const plugins = manager.getPlugins();
+  const enabled = manager.getEnabled();
+  const core = manager.getCore();
+
+  const formattedPlugins: FormattedPlugin[] = plugins.map((plugin: Plugin.Plugin) => {
+    const isEnabled = enabled.includes(plugin.meta.id);
+    const isCore = core.includes(plugin.meta.id);
+    return {
+      id: plugin.meta.id,
+      name: plugin.meta.name ?? plugin.meta.id,
+      enabled: isEnabled,
+      core: isCore,
+    };
+  });
+
+  if (json) {
+    yield* Console.log(JSON.stringify(formattedPlugins, null, 2));
+  } else {
+    const formatted = formattedPlugins.map(printPlugin);
+    yield* Console.log(printList(formatted));
+  }
+});
+
+export const list = Command.make('list', {}, handler).pipe(Command.withDescription('List all available plugins.'));

package/src/commands/util.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { FormBuilder } from '@dxos/cli-util';
+
+export type FormattedPlugin = {
+  id: string;
+  name: string;
+  enabled: boolean;
+  core: boolean;
+};
+
+/**
+ * Pretty prints a plugin with ANSI colors.
+ */
+export const printPlugin = (plugin: FormattedPlugin) => {
+  const status = plugin.core ? 'core' : plugin.enabled ? 'enabled' : 'disabled';
+  return FormBuilder.make({ title: plugin.name }).pipe(
+    FormBuilder.set('id', plugin.id),
+    FormBuilder.set('status', status),
+    FormBuilder.build,
+  );
+};

package/src/components/DisableDependentsAlert/DisableDependentsAlert.tsx

@@ -0,0 +1,69 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { AlertDialog, Button, useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+export type DisableDependentsAlertProps = {
+  /** Id of the plugin the user requested to disable. */
+  pluginId: string;
+  /** Ids of the currently-enabled dependents that would also be disabled. */
+  dependents: readonly string[];
+  /**
+   * Resolves a plugin id to its display name. The component delegates this so
+   * the parent can choose how to source names (typically the registered
+   * `Plugin.Meta.name`). Falls back to the id when omitted.
+   */
+  onResolvePluginName?: (pluginId: string) => string;
+  onConfirm: () => void;
+};
+
+/**
+ * Confirmation prompt shown when a user toggles off a plugin that has
+ * currently-enabled dependents. Rendered inside the layout's dialog surface
+ * (via `LayoutOperation.UpdateDialog` with `type: 'alert'`), which provides
+ * the `AlertDialog.Root` / `Overlay` wrappers — this component renders only
+ * the content. `onConfirm` runs the cascade disable and closes the dialog;
+ * cancel is handled by the layout's open-change wiring.
+ */
+export const DisableDependentsAlert = ({
+  pluginId,
+  dependents,
+  onResolvePluginName,
+  onConfirm,
+}: DisableDependentsAlertProps) => {
+  const { t } = useTranslation(meta.id);
+  const resolveName = onResolvePluginName ?? ((id: string) => id);
+  return (
+    <AlertDialog.Content>
+      <AlertDialog.Body>
+        <AlertDialog.Title>{t('disable-dependents-dialog.title')}</AlertDialog.Title>
+        <AlertDialog.Description>
+          {t('disable-dependents-dialog.description', { plugin: resolveName(pluginId) })}
+        </AlertDialog.Description>
+        <ul className='mt-2 list-disc pl-6 text-sm text-description'>
+          {dependents.map((dependentId) => (
+            <li key={dependentId} title={dependentId}>
+              {resolveName(dependentId)}
+            </li>
+          ))}
+        </ul>
+      </AlertDialog.Body>
+      <AlertDialog.ActionBar>
+        <div className='grow' />
+        <AlertDialog.Cancel asChild>
+          <Button>{t('cancel.label')}</Button>
+        </AlertDialog.Cancel>
+        <AlertDialog.Action asChild>
+          <Button variant='primary' onClick={onConfirm}>
+            {t('disable-dependents-dialog.confirm.label')}
+          </Button>
+        </AlertDialog.Action>
+      </AlertDialog.ActionBar>
+    </AlertDialog.Content>
+  );
+};

package/src/components/DisableDependentsAlert/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './DisableDependentsAlert';

package/src/components/PluginDetail/PluginDetail.stories.tsx

@@ -0,0 +1,48 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { random } from '@dxos/random';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { PluginDetail } from './PluginDetail';
+
+const meta = {
+  title: 'plugins/plugin-registry/components/PluginDetail',
+  component: PluginDetail,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof PluginDetail>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    plugin: Plugin.define(
+      Plugin.makeMeta({
+        key: DXN.make('com.example.plugin.test'),
+        name: 'Test Plugin',
+        author: 'DXOS',
+        description: random.lorem.paragraphs(2),
+        icon: 'ph--bug--regular',
+        iconHue: 'sky',
+        homePage: 'https://example.com',
+        source: 'https://github.com/example/test-plugin',
+        screenshots: [
+          'https://media.gcflearnfree.org/content/55e073de7dd48174331f51b3_01_17_2014/getting_started_interactive2.png',
+        ],
+      }),
+    ).pipe(Plugin.make)(),
+  },
+};