@dxos/plugin-registry 0.8.4-main.dedc0f3 → 0.8.4-main.dfabb4ec29

package/src/capabilities/react-surface.tsx

@@ -2,84 +2,135 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { useCallback, useMemo } from 'react';
+import * as Effect from 'effect/Effect';
+import React, { useMemo } from 'react';
 
-import { Capabilities, Plugin, contributes, createSurface, usePluginManager } from '@dxos/app-framework';
+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 {
+  LOAD_PLUGIN_DIALOG,
+  LoadPluginDialog,
+  PluginArticle,
+  PublicRegistryArticle,
+  RegistryArticle,
+  RegistrySettingsContainer,
+} from '#containers';
+import { 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 { 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: 'official',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('official')),
+        component: () => {
+          const manager = usePluginManager();
+          const remoteIds = useRemotePluginIds();
+          const core = useMemo(() => manager.getCore(), [manager]);
+          const predicate = useMemo<PluginPredicate>(
+            () =>
+              ({ meta }) =>
+                !core.includes(meta.id) && !remoteIds.has(meta.id),
+            [core, remoteIds],
+          );
 
-        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')),
-          [],
-        );
+          return <FilteredRegistryArticle id={registryCategoryId('official')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'installed',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('installed')),
+        component: () => {
+          const manager = usePluginManager();
+          const core = useMemo(() => manager.getCore(), [manager]);
+          const enabled = useMemo(() => manager.getEnabled(), [manager]);
+          const predicate = useMemo<PluginPredicate>(
+            () =>
+              ({ meta }) =>
+                !core.includes(meta.id) && enabled.includes(meta.id),
+            [core, enabled],
+          );
 
-        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')), []);
+          return <FilteredRegistryArticle id={registryCategoryId('installed')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'recommended',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('recommended')),
+        component: () => {
+          const manager = usePluginManager();
+          const remoteIds = useRemotePluginIds();
+          const core = useMemo(() => manager.getCore(), [manager]);
+          const predicate = useMemo<PluginPredicate>(
+            () =>
+              ({ meta }) =>
+                !core.includes(meta.id) && !remoteIds.has(meta.id) && !meta.tags?.includes('labs'),
+            [core, remoteIds],
+          );
 
-        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 <FilteredRegistryArticle id={registryCategoryId('recommended')} filter={predicate} />;
+        },
+      }),
+      Surface.create({
+        id: 'labs',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('labs')),
+        component: () => {
+          const predicate = useMemo<PluginPredicate>(
+            () =>
+              ({ meta }) =>
+                meta.tags?.includes('labs') ?? false,
+            [],
+          );
 
-        return <PluginDetail plugin={subject} enabled={enabled} onEnable={handleEnable} />;
-      },
-    }),
-  ]);
+          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: 'plugin-details',
+        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: 'plugin-settings',
+        role: 'article',
+        filter: (data): data is { subject: AppCapabilities.Settings } =>
+          AppCapabilities.isSettings(data.subject) && data.subject.prefix === meta.id,
+        component: ({ data: { subject } }) => <RegistrySettingsContainer subject={subject} />,
+      }),
+    ]),
+  ),
+);
+
+type PluginPredicate = (plugin: Plugin.Plugin) => boolean;
+
+/**
+ * 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 <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/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/PluginDetail/PluginDetail.stories.tsx

@@ -0,0 +1,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { Plugin } from '@dxos/app-framework';
+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({
+      id: 'com.example.plugin.test',
+      name: 'Test Plugin',
+      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)(),
+  },
+};

package/src/components/PluginDetail/PluginDetail.tsx

@@ -0,0 +1,196 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Registry, type Plugin, type PluginManager } from '@dxos/app-framework';
+import { Button, Icon, Input, Link, ScrollArea, Select, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps, getStyles, mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { PluginFailureBadge } from '../PluginFailureBadge';
+
+export type PluginDetailProps = {
+  plugin: Plugin.Plugin;
+  enabled?: boolean;
+  onEnabledChange?: (enabled: boolean) => void;
+  /**
+   * When provided, an Uninstall button is rendered. Leave undefined for core
+   * or non-removable plugins.
+   */
+  onUninstall?: () => void;
+  /**
+   * When provided, the plugin is not installed and an Install button is shown
+   * in place of the enable Switch.
+   */
+  onInstall?: () => void;
+  installing?: boolean;
+  /**
+   * When provided and the plugin is installed with a newer catalog version available,
+   * an Update button is shown in place of the enable Switch.
+   */
+  onUpdate?: () => void;
+  /** True when the catalog has a newer version than the one installed. */
+  hasUpdate?: boolean;
+  /** True while an in-flight update is running. Forces the Update button disabled state. */
+  updating?: boolean;
+  /** Available versions of this plugin from the catalog. When non-empty, a version picker is shown. */
+  versions?: readonly Registry.PluginVersion[];
+  /** Currently selected version tag in the picker. */
+  selectedVersionTag?: string;
+  /** Called when the user selects a different version in the picker. */
+  onVersionChange?: (tag: string) => void;
+  /** Called when the user clicks Install on the version picker. */
+  onInstallVersion?: () => void;
+  /** Currently installed version tag (used to mark the matching select option). */
+  installedVersionTag?: string;
+  /**
+   * Failure record for this plugin, if any. When present a warning badge is
+   * rendered next to the plugin name in the header.
+   */
+  failure?: PluginManager.PluginFailure;
+};
+
+export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
+  (
+    {
+      plugin,
+      enabled,
+      onEnabledChange,
+      onUninstall,
+      onInstall,
+      installing,
+      onUpdate,
+      hasUpdate,
+      updating,
+      versions,
+      selectedVersionTag,
+      onVersionChange,
+      onInstallVersion,
+      installedVersionTag,
+      failure,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(meta.id);
+    const {
+      id,
+      name,
+      description,
+      homePage,
+      source,
+      screenshots,
+      icon = 'ph--circle--regular',
+      iconHue = 'neutral',
+    } = plugin.meta;
+    const styles = getStyles(iconHue);
+
+    return (
+      <ScrollArea.Root {...composableProps(props)} orientation='vertical' ref={forwardedRef}>
+        <ScrollArea.Viewport>
+          <div className='dx-document grid grid-cols-[min-content_1fr] gap-4 p-4'>
+            <div>
+              <Icon classNames={mx('p-1 rounded-md', styles.fill, styles.surfaceText)} icon={icon} size={14} />
+            </div>
+            <div className='flex flex-col gap-6'>
+              <div className='grid grid-cols-[1fr_min-content] gap-x-3 w-full pt-1'>
+                <div className='flex items-center gap-2'>
+                  <h2 className='text-xl'>{name}</h2>
+                  {failure && <PluginFailureBadge failure={failure} size={5} />}
+                </div>
+                {onInstall ? (
+                  <Button density='fine' variant='primary' disabled={installing} onClick={onInstall}>
+                    {installing ? t('installing.label') : t('install.label')}
+                  </Button>
+                ) : (
+                  <Input.Root>
+                    <Input.Switch classNames='self-center' checked={enabled} onCheckedChange={onEnabledChange} />
+                  </Input.Root>
+                )}
+                <p className='pt-0.5 text-sm text-description'>{id}</p>
+              </div>
+              <div>
+                <p className='text-description'>{description}</p>
+              </div>
+              {screenshots && screenshots.length > 0 && (
+                <div className='flex flex-col gap-2'>
+                  <h2>Preview</h2>
+                  <img src={screenshots[0]} alt={name} className='aspect-video object-fit' />
+                </div>
+              )}
+              <div className='flex flex-col gap-2'>
+                <h2>Resources</h2>
+                <div className='flex gap-2'>
+                  {homePage && (
+                    <Link href={homePage} target='_blank' rel='noreferrer' classNames='text-sm text-description'>
+                      {t('home-page.label')}
+                      <Icon icon='ph--arrow-square-out--bold' size={3} classNames='inline-block leading-none mx-1' />
+                    </Link>
+                  )}
+
+                  {source && (
+                    <Link href={source} target='_blank' rel='noreferrer' classNames='text-sm text-description'>
+                      {t('source.label')}
+                      <Icon icon='ph--arrow-square-out--bold' size={3} classNames='inline-block leading-none mx-1' />
+                    </Link>
+                  )}
+                </div>
+              </div>
+              {versions && versions.length > 0 && (
+                <div className='flex flex-col gap-2'>
+                  <h2>{t('versions.label')}</h2>
+                  <div className='flex gap-2 items-center'>
+                    <Select.Root value={selectedVersionTag} onValueChange={onVersionChange}>
+                      <Select.TriggerButton classNames='min-w-32' />
+                      <Select.Portal>
+                        <Select.Content>
+                          <Select.Viewport>
+                            {versions.map((versionEntry) => (
+                              <Select.Option key={versionEntry.tag} value={versionEntry.tag}>
+                                {versionEntry.tag}
+                                {installedVersionTag === versionEntry.tag ? ` (${t('installed.label')})` : ''}
+                              </Select.Option>
+                            ))}
+                          </Select.Viewport>
+                        </Select.Content>
+                      </Select.Portal>
+                    </Select.Root>
+                    {onInstallVersion && (
+                      <Button
+                        density='fine'
+                        variant='primary'
+                        disabled={installing || selectedVersionTag === installedVersionTag}
+                        onClick={onInstallVersion}
+                      >
+                        {installing ? t('installing.label') : t('install-version.label')}
+                      </Button>
+                    )}
+                  </div>
+                </div>
+              )}
+              {(onUninstall || (hasUpdate && onUpdate) || updating) && (
+                <div className='flex gap-2'>
+                  {updating ? (
+                    <Button variant='primary' disabled>
+                      {t('updating.label')}
+                    </Button>
+                  ) : hasUpdate && onUpdate ? (
+                    <Button variant='primary' onClick={onUpdate}>
+                      {t('update.label')}
+                    </Button>
+                  ) : null}
+                  {onUninstall && <Button onClick={onUninstall}>{t('uninstall.label')}</Button>}
+                </div>
+              )}
+            </div>
+          </div>
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+    );
+  },
+);
+
+PluginDetail.displayName = 'PluginDetail';

package/src/components/PluginDetail/index.ts

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