@dxos/plugin-registry 0.8.4-main.72ec0f3 → 0.8.4-main.8360d9e660

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,44 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { Plugin } from '@dxos/app-framework';
+import { faker } 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: faker.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,81 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { Icon, Input, Link, useTranslation } from '@dxos/react-ui';
+import { ScrollArea } from '@dxos/react-ui';
+import { 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 = ({ plugin, enabled, onEnabledChange }: PluginDetailProps) => {
+  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 orientation='vertical'>
+      <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>
+  );
+};

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-[12rem] 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}
@@ -99,7 +103,7 @@ export const PluginItem = ({
           </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>

package/src/components/PluginList/PluginList.stories.tsx

@@ -0,0 +1,84 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { type Plugin, Plugin as PluginNS } from '@dxos/app-framework';
+import { faker } from '@dxos/random';
+import { ScrollArea } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { getHashHue } from '@dxos/ui-theme';
+
+import { translations } from '../../translations';
+import { RegistryTagType } from '../../types';
+
+import { PluginList } from './PluginList';
+
+faker.seed(1);
+
+const icons = [
+  'ph--bug--regular',
+  'ph--compass--regular',
+  'ph--kanban--regular',
+  'ph--table--regular',
+  'ph--gear--regular',
+  'ph--github-logo--regular',
+];
+
+const DefaultStory = () => {
+  const [plugins] = useState<Plugin.Plugin[]>(
+    faker.helpers.multiple(
+      () =>
+        PluginNS.define({
+          id: `org.dxos.plugin.plugin-${faker.string.uuid()}`,
+          name: `${faker.commerce.productName()}`,
+          description: faker.lorem.sentences(Math.ceil(Math.random() * 3)),
+          tags: faker.helpers.uniqueArray(RegistryTagType.literals as any, Math.floor(Math.random() * 3)),
+          icon: faker.helpers.arrayElement(icons),
+          iconHue: getHashHue(faker.string.uuid()),
+          homePage: faker.datatype.boolean({ probability: 0.5 }) ? faker.internet.url() : undefined,
+          source: faker.internet.url(),
+        }).pipe(PluginNS.make)(),
+      { count: 32 },
+    ),
+  );
+  const [enabled, setEnabled] = useState<string[]>([]);
+
+  const handleChange = (id: string, enabled: boolean) => {
+    setEnabled((plugins) => (enabled ? [...plugins, id] : plugins.filter((plugin) => plugin === id)));
+  };
+
+  return (
+    <ScrollArea.Root orientation='vertical'>
+      <ScrollArea.Viewport>
+        <PluginList plugins={plugins} enabled={enabled} onChange={handleChange} hasSettings={() => true} />
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-registry/components/PluginList',
+  component: PluginList,
+  render: DefaultStory,
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof PluginList>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+};
+
+export const FullScreen: Story = {
+  decorators: [withTheme(), withLayout({ scroll: true })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};

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

@@ -10,12 +10,12 @@ import { List } from '@dxos/react-ui';
 import { PluginItem, type PluginItemProps } from './PluginItem';
 
 export type PluginListProps = Omit<PluginItemProps, 'plugin'> & {
-  plugins?: readonly Plugin[];
+  plugins?: readonly Plugin.Plugin[];
 };
 
 export const PluginList = ({ plugins = [], ...props }: PluginListProps) => {
   return (
-    <List classNames='grid grid-cols-[repeat(auto-fill,minmax(18rem,1fr))] gap-4 p-4'>
+    <List classNames='grid grid-cols-[repeat(auto-fill,minmax(18rem,1fr))] auto-rows-[max-content] gap-4 p-4'>
       {plugins.map((plugin) => (
         <PluginItem key={plugin.meta.id} plugin={plugin} {...props} />
       ))}

package/src/components/PluginList/index.ts

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

package/src/components/index.ts

@@ -4,4 +4,3 @@
 
 export * from './PluginDetail';
 export * from './PluginList';
-export * from './RegistryContainer';

package/src/containers/PluginArticle/PluginArticle.tsx

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { usePluginManager } from '@dxos/app-framework/ui';
+import { runAndForwardErrors } from '@dxos/effect';
+
+import { PluginDetail } from '../../components';
+
+// TODO(burdon): Convert to ECHO type.
+export type PluginArticleProps = { subject: Plugin.Plugin };
+
+export const PluginArticle = ({ subject: plugin }: PluginArticleProps) => {
+  const manager = usePluginManager();
+  const enabled = manager.getEnabled().includes(plugin.meta.id);
+  const handleEnableChange = useCallback(
+    (enabled: boolean) =>
+      enabled
+        ? runAndForwardErrors(manager.enable(plugin.meta.id))
+        : runAndForwardErrors(manager.disable(plugin.meta.id)),
+    [manager, plugin.meta.id],
+  );
+
+  return <PluginDetail plugin={plugin} enabled={enabled} onEnabledChange={handleEnableChange} />;
+};

package/src/containers/PluginArticle/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { PluginArticle } from './PluginArticle';
+
+export default PluginArticle;

package/src/containers/PluginRegistry/PluginRegistry.tsx

@@ -0,0 +1,86 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import React, { useCallback, useMemo } from 'react';
+
+import { type Plugin } from '@dxos/app-framework';
+import { useCapabilities, useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import { AppCapabilities, LayoutOperation, SettingsOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { ObservabilityOperation } from '@dxos/plugin-observability/types';
+import { ScrollArea } from '@dxos/react-ui';
+
+import { PluginList } from '../../components';
+import { getPluginPath } from '../../meta';
+
+const sortByPluginMeta = ({ meta: { name: a = '' } }: Plugin.Plugin, { meta: { name: b = '' } }: Plugin.Plugin) =>
+  a.localeCompare(b);
+
+export type PluginRegistryProps = {
+  id: string;
+  plugins: Plugin.Plugin[];
+};
+
+export const PluginRegistry = ({ id, plugins: pluginsProp }: PluginRegistryProps) => {
+  const manager = usePluginManager();
+  const { invoke, invokePromise } = useOperationInvoker();
+  const plugins = useMemo(() => pluginsProp.sort(sortByPluginMeta), [pluginsProp]);
+  const enabled = useAtomValue(manager.enabled);
+  const allSettings = useCapabilities(AppCapabilities.Settings);
+
+  // TODO(wittjosiah): Factor out to an intent?
+  const handleChange = useCallback(
+    (id: string, enabled: boolean) =>
+      Effect.gen(function* () {
+        if (enabled) {
+          yield* manager.enable(id);
+        } else {
+          yield* manager.disable(id);
+        }
+
+        yield* invoke(ObservabilityOperation.SendEvent, {
+          name: 'plugins.toggle',
+          properties: {
+            plugin: id,
+            enabled,
+          },
+        });
+      }).pipe(runAndForwardErrors),
+    [invoke, manager],
+  );
+
+  const handleClick = useCallback(
+    (pluginId: string) =>
+      invokePromise(LayoutOperation.Open, {
+        subject: [getPluginPath(pluginId)],
+        pivotId: id,
+        positioning: 'end',
+      }),
+    [invokePromise, id],
+  );
+
+  const hasSettings = useCallback((pluginId: string) => allSettings.some((s) => s.prefix === pluginId), [allSettings]);
+
+  const handleSettings = useCallback(
+    (pluginId: string) => invokePromise(SettingsOperation.Open, { plugin: pluginId }),
+    [invokePromise],
+  );
+
+  return (
+    <ScrollArea.Root orientation='vertical'>
+      <ScrollArea.Viewport>
+        <PluginList
+          plugins={plugins}
+          enabled={enabled}
+          onClick={handleClick}
+          onChange={handleChange}
+          hasSettings={hasSettings}
+          onSettings={handleSettings}
+        />
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};

package/src/containers/PluginRegistry/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { PluginRegistry } from './PluginRegistry';
+
+export default PluginRegistry;

package/src/containers/index.ts

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

package/src/meta.ts

@@ -2,17 +2,17 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
 import { trim } from '@dxos/util';
 
-// 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_KEY = 'plugin-registry';
 
-export const meta: PluginMeta = {
-  id: 'dxos.org/plugin/registry',
+/** 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.