@dxos/plugin-registry 0.8.4-main.70d3990 → 0.8.4-main.74a063c4e0

package/src/capabilities/react-surface.tsx

@@ -2,85 +2,94 @@
 // 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 } from '@dxos/app-framework';
-import { usePluginManager } from '@dxos/app-framework/react';
+import { Capabilities, Capability } 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 { 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)), []);
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'all',
+        role: 'article',
+        filter: AppSurface.literalSection(registryCategoryId('all')),
+        component: () => {
+          const manager = usePluginManager();
+          const filtered = useMemo(
+            () => manager.getPlugins().filter(({ meta }) => !manager.getCore().includes(meta.id)),
+            [],
+          );
 
-        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)),
-          [],
-        );
+          return <PluginRegistry id={registryCategoryId('all')} plugins={filtered} />;
+        },
+      }),
+      Surface.create({
+        id: 'installed',
+        role: 'article',
+        filter: AppSurface.literalSection(registryCategoryId('installed')),
+        component: () => {
+          const manager = usePluginManager();
+          const filtered = useMemo(
+            () =>
+              manager
+                .getPlugins()
+                .filter(({ meta }) => !manager.getCore().includes(meta.id))
+                .filter(({ meta }) => manager.getEnabled().includes(meta.id)),
+            [],
+          );
 
-        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('installed')} plugins={filtered} />;
+        },
+      }),
+      Surface.create({
+        id: 'recommended',
+        role: 'article',
+        filter: AppSurface.literalSection(registryCategoryId('recommended')),
+        component: () => {
+          const manager = usePluginManager();
+          const filtered = useMemo(
+            () =>
+              manager
+                .getPlugins()
+                .filter(({ meta }) => !manager.getCore().includes(meta.id))
+                .filter(({ meta }) => !meta.tags?.includes('labs')),
+            [],
+          );
 
-        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('recommended')} plugins={filtered} />;
+        },
+      }),
+      Surface.create({
+        id: 'labs',
+        role: 'article',
+        filter: AppSurface.literalSection(registryCategoryId('labs')),
+        component: () => {
+          const manager = usePluginManager();
+          const filtered = useMemo(() => manager.getPlugins().filter(({ meta }) => meta.tags?.includes('labs')), []);
 
-        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 <PluginDetail plugin={subject} enabled={enabled} onEnable={handleEnable} />;
-      },
-    }),
-  ]);
+          return <PluginRegistry id={registryCategoryId('labs')} plugins={filtered} />;
+        },
+      }),
+      Surface.create({
+        id: 'plugin-details',
+        role: 'article',
+        filter: AppSurface.pluginSection(),
+        component: ({ data: { subject } }) => {
+          return <PluginArticle subject={subject} />;
+        },
+      }),
+      Surface.create({
+        id: LOAD_PLUGIN_DIALOG,
+        role: 'dialog',
+        filter: AppSurface.componentDialog(LOAD_PLUGIN_DIALOG),
+        component: () => <LoadPluginDialog />,
+      }),
+    ]),
+  ),
+);

package/src/cli/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/cli/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/cli/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/cli/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/cli/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/cli/index.ts

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

package/src/cli/plugin.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+
+import { plugin } from './commands';
+
+export const RegistryPlugin = Plugin.define(meta).pipe(
+  AppPlugin.addCommandModule({
+    commands: [plugin],
+  }),
+  Plugin.make,
+);

package/src/cli/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/components/PluginDetail/PluginDetail.stories.tsx

@@ -0,0 +1,43 @@
+//
+// 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,84 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { 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;
+};
+
+export const PluginDetail = composable<HTMLDivElement, PluginDetailProps>(
+  ({ plugin, enabled, onEnabledChange, ...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>
+                <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>
+            </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';

package/src/components/{PluginItem.tsx → PluginList/PluginItem.tsx}

@@ -6,14 +6,14 @@ import React, { type MouseEvent, useCallback } from 'react';
 
 import { type Plugin } from '@dxos/app-framework';
 import { type ChromaticPalette, Icon, IconButton, Input, Link, ListItem, Tag, useTranslation } from '@dxos/react-ui';
-import { descriptionText, mx } from '@dxos/react-ui-theme';
-import { getStyles } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
+import { getStyles } from '@dxos/ui-theme';
 
-import { meta } from '../meta';
-import { type RegistryTagType } from '../types';
+import { meta } from '#meta';
+import { type RegistryTagType } from '#types';
 
 export type PluginItemProps = {
-  plugin: Plugin;
+  plugin: Plugin.Plugin;
   installed?: readonly string[];
   enabled?: readonly string[];
   onClick?: (id: string) => void;
@@ -27,7 +27,7 @@ export const PluginItem = ({
   enabled = [],
   onClick,
   onChange,
-  hasSettings: hasSettingsParam,
+  hasSettings: hasSettingsProp,
   onSettings,
 }: PluginItemProps) => {
   const { t } = useTranslation(meta.id);
@@ -46,7 +46,7 @@ export const PluginItem = ({
     [id, isEnabled, onChange],
   );
 
-  const hasSettings = hasSettingsParam?.(id) ?? false;
+  const hasSettings = hasSettingsProp?.(id) ?? false;
   const handleSettings = useCallback(() => onSettings?.(id), [id, onSettings]);
   const styles = getStyles(iconHue);
   const gridCols = 'grid grid-cols-[5rem_1fr]';
@@ -58,11 +58,15 @@ export const PluginItem = ({
       labelId={labelId}
       data-testid={`pluginList.${id}`}
       aria-describedby={descriptionId}
-      classNames={mx(gridCols, 'bs-[12rem] is-full gap-3 pie-2 border border-separator rounded-md overflow-hidden')}
+      classNames={mx(gridCols, 'h-[14rem] w-full gap-3 pe-2 bg-modal-surface rounded-md overflow-hidden')}
     >
-      <div className={mx(gridRows, 'justify-center rounded-l-md', styles.bg)}>
-        <div />
-        <Icon classNames={mx('cursor-pointer', styles.icon)} icon={icon} size={14} onClick={handleClick} />
+      <div className={mx(gridRows, 'justify-center rounded-l-md', styles.surface)}>
+        <Icon
+          classNames={mx('row-start-2 cursor-pointer', styles.surfaceText)}
+          icon={icon}
+          size={14}
+          onClick={handleClick}
+        />
       </div>
 
       <div className={mx(gridRows)}>
@@ -71,10 +75,10 @@ export const PluginItem = ({
         </div>
 
         <div>
-          <p className={mx(descriptionText, 'line-clamp-4 min-is-0')}>{description}</p>
+          <p className={mx('text-description', 'line-clamp-4 min-w-0')}>{description}</p>
         </div>
 
-        <div className='flex -mis-0.5 overflow-x-auto scrollbar-none'>
+        <div className='flex -ms-0.5 overflow-x-auto scrollbar-none'>
           {tags?.map((tag) => (
             <Tag key={tag} palette={tagColors[tag as RegistryTagType]} classNames='text-xs uppercase font-thin'>
               {tag}
@@ -87,7 +91,7 @@ export const PluginItem = ({
             aria-describedby={descriptionId}
             classNames='cursor-pointer'
             icon='ph--gear--regular'
-            label={t('settings label')}
+            label={t('settings.label')}
             iconOnly
             size={4}
             onClick={handleSettings}
@@ -95,11 +99,11 @@ export const PluginItem = ({
           />
 
           <Link aria-describedby={descriptionId} classNames='text-description cursor-pointer' onClick={handleClick}>
-            {t('details label')}
+            {t('details.label')}
           </Link>
 
           <div className='grow' />
-          <div className='pie-1'>
+          <div className='pe-1'>
             <Input.Root id={inputId}>
               <Input.Switch classNames='self-center' checked={isEnabled} onClick={handleChange} />
             </Input.Root>