@dxos/plugin-registry 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/capabilities/react-surface.tsx

@@ -2,84 +2,119 @@
 // 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 { AppSurface } from '@dxos/app-toolkit/ui';
 
-import { PluginDetail, RegistryContainer } from '../components';
-import { REGISTRY_KEY, meta } from '../meta';
+import { CommunityRegistry, LOAD_PLUGIN_DIALOG, LoadPluginDialog, PluginArticle, PluginRegistry } from '#containers';
+import { registryCategoryId } from '#meta';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: `${meta.id}/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, useCommunityPlugins, useRemotePluginIds } from '../hooks';
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+all`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${meta.id}/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 { entries } = useCommunityPlugins();
+          const extraTagsById = useAutoTags(entries);
+          const filtered = useMemo(
+            () =>
+              manager
+                .getPlugins()
+                .filter(({ meta }) => !manager.getCore().includes(meta.id))
+                .filter(({ meta }) => !remoteIds.has(meta.id)),
+            [manager, remoteIds],
+          );
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+installed`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${meta.id}/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 (
+            <PluginRegistry id={registryCategoryId('official')} plugins={filtered} extraTagsById={extraTagsById} />
+          );
+        },
+      }),
+      Surface.create({
+        id: 'installed',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('installed')),
+        component: () => {
+          const manager = usePluginManager();
+          const { entries } = useCommunityPlugins();
+          const extraTagsById = useAutoTags(entries);
+          const filtered = useMemo(
+            () =>
+              manager
+                .getPlugins()
+                .filter(({ meta }) => !manager.getCore().includes(meta.id))
+                .filter(({ meta }) => manager.getEnabled().includes(meta.id)),
+            [manager],
+          );
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+recommended`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${meta.id}/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 (
+            <PluginRegistry id={registryCategoryId('installed')} plugins={filtered} extraTagsById={extraTagsById} />
+          );
+        },
+      }),
+      Surface.create({
+        id: 'recommended',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('recommended')),
+        component: () => {
+          const manager = usePluginManager();
+          const remoteIds = useRemotePluginIds();
+          const { entries } = useCommunityPlugins();
+          const extraTagsById = useAutoTags(entries);
+          const filtered = useMemo(
+            () =>
+              manager
+                .getPlugins()
+                .filter(({ meta }) => !manager.getCore().includes(meta.id))
+                .filter(({ meta }) => !remoteIds.has(meta.id))
+                .filter(({ meta }) => !meta.tags?.includes('labs')),
+            [manager, remoteIds],
+          );
 
-        return <RegistryContainer id={`${REGISTRY_KEY}+labs`} plugins={filtered} />;
-      },
-    }),
-    createSurface({
-      id: `${meta.id}/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 (
+            <PluginRegistry id={registryCategoryId('recommended')} plugins={filtered} extraTagsById={extraTagsById} />
+          );
+        },
+      }),
+      Surface.create({
+        id: 'labs',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('labs')),
+        component: () => {
+          const manager = usePluginManager();
+          const { entries } = useCommunityPlugins();
+          const extraTagsById = useAutoTags(entries);
+          const filtered = useMemo(
+            () => manager.getPlugins().filter(({ meta }) => meta.tags?.includes('labs')),
+            [manager],
+          );
 
-        return <PluginDetail plugin={subject} enabled={enabled} onEnable={handleEnable} />;
-      },
-    }),
-  ]);
+          return <PluginRegistry id={registryCategoryId('labs')} plugins={filtered} extraTagsById={extraTagsById} />;
+        },
+      }),
+      Surface.create({
+        id: 'community',
+        filter: AppSurface.literal(AppSurface.Article, registryCategoryId('community')),
+        component: () => <CommunityRegistry id={registryCategoryId('community')} />,
+      }),
+      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 />,
+      }),
+    ]),
+  ),
+);

package/src/capabilities/state.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { log } from '@dxos/log';
+import { ClientCapabilities } from '@dxos/plugin-client/types';
+
+import { RegistryCapabilities, type CommunityPluginsState } from '#types';
+
+import { loadCommunityPlugins } from '../hooks';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const client = yield* Capability.get(ClientCapabilities.Client);
+
+    const communityPluginsAtom = Atom.make<CommunityPluginsState>({ entries: [], loading: true, error: null }).pipe(
+      Atom.keepAlive,
+    );
+
+    yield* loadCommunityPlugins(client.edge.http).pipe(
+      Effect.match({
+        onSuccess: (entries) => registry.set(communityPluginsAtom, { entries, loading: false, error: null }),
+        onFailure: (error) => {
+          log.catch(error);
+          registry.set(communityPluginsAtom, { entries: [], loading: false, error });
+        },
+      }),
+      Effect.forkDaemon,
+    );
+
+    return Capability.contributes(RegistryCapabilities.State, communityPluginsAtom);
+  }),
+);

package/src/cli/index.ts

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

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: 'example.com/plugin/test-plugin',
+      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,106 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { Button, Icon, Input, Link, ScrollArea, useTranslation } from '@dxos/react-ui';
+import { composable, composableProps, getStyles, mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+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;
+};
+
+export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
+  ({ plugin, enabled, onEnabledChange, onUninstall, onInstall, installing, ...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 role='none' className='dx-document grid grid-cols-[min-content_1fr] gap-4 p-4'>
+            <div role='none'>
+              <Icon classNames={mx('p-1 rounded-md', styles.fill, styles.surfaceText)} icon={icon} size={14} />
+            </div>
+            <div role='none' className='flex flex-col gap-6'>
+              <div role='none' className='grid grid-cols-[1fr_min-content] gap-x-3 w-full pt-1'>
+                <h2 className='text-xl'>{name}</h2>
+                {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 role='none'>
+                <p className='text-description'>{description}</p>
+              </div>
+              {screenshots && screenshots.length > 0 && (
+                <div role='none' className='flex flex-col gap-2'>
+                  <h2>Preview</h2>
+                  <img src={screenshots[0]} alt={name} className='aspect-video object-fit' />
+                </div>
+              )}
+              <div role='none' 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>
+              {onUninstall && (
+                <div role='none'>
+                  <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';