@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.9735255

package/src/core/plugin.ts

@@ -2,12 +2,75 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type MaybePromise } from '@dxos/util';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
 
-import { type AnyCapability, type PluginContext } from './capabilities';
-import { type ActivationEvent, type ActivationEvents } from './events';
+import { invariant } from '@dxos/invariant';
 
-interface PluginModuleInterface {
+import type * as ActivationEvent from './activation-event';
+import * as Capability from './capability';
+import type * as PluginManager from './plugin-manager';
+
+//
+// Plugin Service Layer
+//
+
+/**
+ * Effect Context.Tag for accessing PluginManager via the Effect layer system.
+ * This allows lifecycle operations to access the plugin manager without having it passed as an argument.
+ */
+export class Service extends Context.Tag('@dxos/app-framework/PluginManager')<Service, PluginManager.PluginManager>() {}
+
+//
+// Lifecycle Functions
+//
+
+/**
+ * Activates plugins based on the activation event.
+ * Accesses the PluginManager via the Effect layer system.
+ * @param event The activation event.
+ * @returns Whether the activation was successful.
+ */
+export const activate = (event: ActivationEvent.ActivationEvent): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.activate(event));
+
+/**
+ * Re-activates the modules that were activated by the event.
+ * Accesses the PluginManager via the Effect layer system.
+ * @param event The activation event.
+ * @returns Whether the reset was successful.
+ */
+export const reset = (event: ActivationEvent.ActivationEvent): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.reset(event));
+
+/**
+ * Computes a module ID from plugin ID and export name.
+ */
+const computeModuleId = (pluginId: string, moduleName: string): string => {
+  return `${pluginId}/module/${moduleName}`;
+};
+
+/**
+ * Identifier denoting a PluginModule.
+ */
+export const PluginModuleTypeId: unique symbol = Symbol.for('@dxos/app-framework/PluginModule');
+export type PluginModuleTypeId = typeof PluginModuleTypeId;
+
+/**
+ * Type guard to check if a value is a PluginModule.
+ */
+export const isPluginModule = (value: unknown): value is PluginModule => {
+  return typeof value === 'object' && value !== null && PluginModuleTypeId in value;
+};
+
+/**
+ * A unit of containment of modular functionality that can be provided to an application.
+ * Activation of a module is async allowing for code to split and loaded lazily.
+ */
+export interface PluginModule {
+  readonly [PluginModuleTypeId]: PluginModuleTypeId;
   /**
    * Unique id of the module.
    */
@@ -16,43 +79,41 @@ interface PluginModuleInterface {
   /**
    * Events for which the module will be activated.
    */
-  activatesOn: ActivationEvents;
+  activatesOn: ActivationEvent.Events;
 
   /**
    * Events which the plugin depends on being activated.
    * Plugin is marked as needing reset a plugin activated by a dependent event is removed.
    * Events are automatically activated before activation of the plugin.
    */
-  activatesBefore?: ActivationEvent[];
+  activatesBefore?: ActivationEvent.ActivationEvent[];
 
   /**
    * Events which this plugin triggers upon activation.
    */
-  activatesAfter?: ActivationEvent[];
+  activatesAfter?: ActivationEvent.ActivationEvent[];
 
   /**
    * Called when the module is activated.
-   * @param context The plugin context.
+   * CapabilityManager is accessed via the Effect layer system (Capability.Service).
+   * PluginManager is accessed via Plugin.Service.
+   * @param props Optional props passed to the module.
    * @returns The capabilities of the module.
    */
-  activate: (
-    context: PluginContext,
-  ) => MaybePromise<AnyCapability | AnyCapability[]> | Promise<() => Promise<AnyCapability | AnyCapability[]>>;
+  activate: (props?: any) => Effect.Effect<Capability.ModuleReturn, Error, Capability.Service | Service | never>;
 }
 
-/**
- * A unit of containment of modular functionality that can be provided to an application.
- * Activation of a module is async allowing for code to split and loaded lazily.
- */
-// NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
-export class PluginModule implements PluginModuleInterface {
-  readonly id: PluginModuleInterface['id'];
-  readonly activatesOn: PluginModuleInterface['activatesOn'];
-  readonly activatesBefore?: PluginModuleInterface['activatesBefore'];
-  readonly activatesAfter?: PluginModuleInterface['activatesAfter'];
-  readonly activate: PluginModuleInterface['activate'];
+export type PluginModuleOptions = Omit<PluginModule, 'id' | typeof PluginModuleTypeId> & { id?: string };
+
+class PluginModuleImpl implements PluginModule {
+  readonly [PluginModuleTypeId]: PluginModuleTypeId = PluginModuleTypeId;
+  readonly id: PluginModule['id'];
+  readonly activatesOn: PluginModule['activatesOn'];
+  readonly activatesBefore?: PluginModule['activatesBefore'];
+  readonly activatesAfter?: PluginModule['activatesAfter'];
+  readonly activate: PluginModule['activate'];
 
-  constructor(options: PluginModuleInterface) {
+  constructor(options: Omit<PluginModule, typeof PluginModuleTypeId>) {
     this.id = options.id;
     this.activatesOn = options.activatesOn;
     this.activatesBefore = options.activatesBefore;
@@ -61,12 +122,7 @@ export class PluginModule implements PluginModuleInterface {
   }
 }
 
-/**
- * Helper to define a module.
- */
-export const defineModule = (options: PluginModuleInterface) => new PluginModule(options);
-
-export type PluginMeta = {
+export type Meta = {
   /**
    * Globally unique ID.
    *
@@ -110,23 +166,160 @@ export type PluginMeta = {
    * A grep-able symbol string which can be resolved to an icon asset by @ch-ui/icons, via @ch-ui/vite-plugin-icons.
    */
   icon?: string;
+
+  /**
+   * Icon hue (ChromaticPalette).
+   */
+  iconHue?: string;
+};
+
+/**
+ * Identifier denoting a Plugin.
+ */
+export const PluginTypeId: unique symbol = Symbol.for('@dxos/app-framework/Plugin');
+export type PluginTypeId = typeof PluginTypeId;
+
+/**
+ * Type guard to check if a value is a Plugin.
+ */
+export const isPlugin = (value: unknown): value is Plugin => {
+  return typeof value === 'object' && value !== null && PluginTypeId in value;
 };
 
 /**
  * A collection of modules that are be enabled/disabled as a unit.
  * Plugins provide things such as components, state, actions, etc. to the application.
  */
-// NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
-export class Plugin {
+export interface Plugin {
+  readonly [PluginTypeId]: PluginTypeId;
+  readonly meta: Readonly<Meta>;
+  readonly modules: ReadonlyArray<PluginModule>;
+}
+
+/**
+ * Internal implementation of Plugin.
+ * @internal
+ */
+class PluginImpl implements Plugin {
+  readonly [PluginTypeId]: PluginTypeId = PluginTypeId;
+
   constructor(
-    readonly meta: PluginMeta,
-    readonly modules: PluginModule[],
+    private readonly _meta: Meta,
+    private readonly _modules: PluginModule[],
   ) {}
+
+  get meta(): Readonly<Meta> {
+    return this._meta;
+  }
+
+  get modules(): ReadonlyArray<PluginModule> {
+    return this._modules;
+  }
+}
+
+/**
+ * Builder interface for creating plugins incrementally.
+ */
+export interface PluginBuilder<T = void> extends Pipeable.Pipeable {
+  readonly meta: Meta;
+  readonly modules: ReadonlyArray<PluginModuleOptions | ((options: T) => PluginModuleOptions)>;
+  addModule(moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): PluginBuilder<T>;
+}
+
+/**
+ * Builder implementation for creating plugins incrementally.
+ */
+class PluginBuilderImpl<T = void> implements PluginBuilder<T> {
+  readonly meta: Meta;
+  private readonly _modules: Array<PluginModuleOptions | ((options: T) => PluginModuleOptions)> = [];
+
+  constructor(meta: Meta) {
+    this.meta = meta;
+  }
+
+  get modules(): ReadonlyArray<PluginModuleOptions | ((options: T) => PluginModuleOptions)> {
+    return this._modules;
+  }
+
+  addModule(moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): PluginBuilder<T> {
+    this._modules.push(moduleOptions);
+    return this;
+  }
+
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
+  }
+}
+
+/**
+ * Creates a new PluginBuilder to start building a plugin.
+ */
+export const define = <T = void>(meta: Meta): PluginBuilder<T> => new PluginBuilderImpl<T>(meta);
+
+/**
+ * Adds a module to a plugin builder.
+ * Supports both pipeline and direct call styles.
+ * Modules can be either PluginModuleOptions or functions that receive options.
+ */
+export function addModule<T>(
+  moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions),
+): (builder: PluginBuilder<T>) => PluginBuilder<T>;
+export function addModule<T>(
+  builder: PluginBuilder<T>,
+  moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions),
+): PluginBuilder<T>;
+export function addModule<T>(
+  moduleOptionsOrBuilder: PluginModuleOptions | ((options: T) => PluginModuleOptions) | PluginBuilder<T>,
+  moduleOptions?: PluginModuleOptions | ((options: T) => PluginModuleOptions),
+): ((builder: PluginBuilder<T>) => PluginBuilder<T>) | PluginBuilder<T> {
+  // If second arg is provided, it's the direct call style: addModule(builder, moduleOptions)
+  if (moduleOptions !== undefined) {
+    return (moduleOptionsOrBuilder as PluginBuilder<T>).addModule(moduleOptions);
+  }
+  // Otherwise it's pipeline style: addModule(moduleOptions) returns a function
+  const moduleOpts = moduleOptionsOrBuilder as PluginModuleOptions | ((options: T) => PluginModuleOptions);
+  return (builder: PluginBuilder<T>) => builder.addModule(moduleOpts);
 }
 
+export type PluginFactory<T = void> = ((options: T) => Plugin) & { meta: Meta };
+
 /**
- * Helper to define a plugin.
+ * Resolves a module from either PluginModuleOptions or a function that returns PluginModuleOptions.
  */
-export const definePlugin = (meta: PluginMeta, modules: PluginModule[]) => {
-  return new Plugin(meta, modules);
+const resolveModule = (
+  meta: Meta,
+  module: PluginModuleOptions | ((options: any) => PluginModuleOptions),
+  options?: any,
+): PluginModuleImpl => {
+  const moduleOptions = typeof module === 'function' ? module(options) : module;
+  const id = Option.fromNullable(moduleOptions.id).pipe(
+    Option.match({
+      onNone: () => {
+        const exportName = Capability.getModuleTag(moduleOptions.activate);
+        invariant(exportName, `Plugin module missing name. Plugin: ${meta.id}`);
+        return computeModuleId(meta.id, exportName);
+      },
+      onSome: (id) => computeModuleId(meta.id, id),
+    }),
+  );
+  return new PluginModuleImpl({ ...moduleOptions, id });
 };
+
+/**
+ * Creates a Plugin from a builder.
+ * Supports both pipeline and direct call styles.
+ * Always returns a factory function (options: T) => Plugin.
+ * When T is void, the function takes no arguments: () => Plugin.
+ */
+export function make<T>(builder: PluginBuilder<T>): PluginFactory<T>;
+export function make<T>(builder: PluginBuilder<T>): PluginFactory<T> {
+  const meta = builder.meta;
+
+  const factory = (options: T) => {
+    const modules = builder.modules.map((module) => resolveModule(meta, module, options));
+    return new PluginImpl(meta, modules);
+  };
+
+  return Object.assign(factory, { meta });
+}

package/src/helpers.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, it, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
 import { topologicalSort } from './helpers';
 

package/src/index.ts

@@ -2,9 +2,10 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './App';
-export * from './common';
+export * from './cli';
+export * as Common from './common';
+export * from './context';
 export * from './core';
-export * from './plugin-intent';
+export * from './plugin-operation';
+export * from './plugin-runtime';
 export * from './plugin-settings';
-export * from './react';

package/src/playground/debug/Debug.tsx

@@ -2,38 +2,48 @@
 // Copyright 2025 DXOS.org
 //
 
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
 import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
 
-import { Capabilities, createSurface } from '../../common';
-import { contributes } from '../../core';
+import * as Common from '../../common';
+import { Capability } from '../../core';
 import { usePluginManager } from '../../react';
 
 export const Debug = () => {
   const manager = usePluginManager();
+  const core = useAtomValue(manager.core);
+  const enabled = useAtomValue(manager.enabled);
+  const active = useAtomValue(manager.active);
+  const pendingReset = useAtomValue(manager.pendingReset);
+  const eventsFired = useAtomValue(manager.eventsFired);
 
   const object = {
-    core: manager.core,
-    enabled: manager.enabled,
-    active: manager.active,
-    pendingReset: manager.pendingReset,
-    eventsFired: manager.eventsFired,
+    core,
+    enabled,
+    active,
+    pendingReset,
+    eventsFired,
   };
 
   return (
-    <SyntaxHighlighter language='json' classNames='flex w-full text-xs opacity-75 rounded'>
+    <SyntaxHighlighter language='json' classNames='text-xs opacity-75 rounded'>
       {JSON.stringify(object, undefined, 2)}
     </SyntaxHighlighter>
   );
 };
 
-export default () =>
-  contributes(
-    Capabilities.ReactSurface,
-    createSurface({
-      id: 'dxos.org/test/debug/main',
-      role: 'secondary',
-      component: Debug,
-    }),
-  );
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(
+      Common.Capability.ReactSurface,
+      Common.createSurface({
+        id: 'dxos.org/test/debug/main',
+        role: 'secondary',
+        component: Debug,
+      }),
+    ),
+  ),
+);

package/src/playground/debug/plugin.ts

@@ -2,16 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Events } from '../../common';
-import { defineModule, definePlugin, lazy } from '../../core';
+import * as Common from '../../common';
+import { Capability, Plugin } from '../../core';
 
-const Debug = lazy(() => import('./Debug'));
+const Debug = Capability.lazy('Debug', () => import('./Debug'));
 
-export const DebugPlugin = () =>
-  definePlugin({ id: 'dxos.org/test/plugin-debug', name: 'Debug' }, [
-    defineModule({
-      id: 'dxos.org/test/debug/main',
-      activatesOn: Events.Startup,
-      activate: Debug,
-    }),
-  ]);
+export const DebugPlugin = Plugin.define({ id: 'dxos.org/test/plugin-debug', name: 'Debug' }).pipe(
+  Plugin.addModule({
+    activatesOn: Common.ActivationEvent.Startup,
+    activate: Debug,
+  }),
+  Plugin.make,
+);

package/src/playground/generator/Main.tsx

@@ -2,12 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
 import React, { useCallback } from 'react';
 
 import { IconButton, List, ListItem } from '@dxos/react-ui';
 
-import { Capabilities } from '../../common';
-import { contributes } from '../../core';
+import * as Common from '../../common';
+import { Capability } from '../../core';
 import { usePluginManager } from '../../react';
 
 const Item = ({
@@ -30,7 +32,6 @@ const Item = ({
           variant='ghost'
           icon='ph--x--regular'
           label='Remove'
-          size={5}
           disabled={disabled}
           onClick={handleRemove}
         />
@@ -41,6 +42,8 @@ const Item = ({
 
 export const Main = () => {
   const manager = usePluginManager();
+  const plugins = useAtomValue(manager.plugins);
+  const core = useAtomValue(manager.core);
 
   const handleRemove = useCallback(
     async (id: string) => {
@@ -51,11 +54,11 @@ export const Main = () => {
 
   return (
     <List itemSizes='one'>
-      {manager.plugins.map((plugin) => (
+      {plugins.map((plugin) => (
         <Item
           key={plugin.meta.id}
           id={plugin.meta.id}
-          disabled={manager.core.includes(plugin.meta.id)}
+          disabled={core.includes(plugin.meta.id)}
           onRemove={handleRemove}
         />
       ))}
@@ -63,9 +66,15 @@ export const Main = () => {
   );
 };
 
-export default () =>
-  contributes(Capabilities.ReactSurface, {
-    id: 'dxos.org/test/generator/main',
-    role: 'primary',
-    component: Main,
-  });
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(
+      Common.Capability.ReactSurface,
+      Common.createSurface({
+        id: 'dxos.org/test/generator/main',
+        role: 'primary',
+        component: Main,
+      }),
+    ),
+  ),
+);

package/src/playground/generator/Toolbar.tsx

@@ -2,35 +2,40 @@
 // Copyright 2025 DXOS.org
 //
 
+import { useAtomValue } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
 import React, { useCallback } from 'react';
 
 import { Button } from '@dxos/react-ui';
 
-import { createGeneratorIntent, createPluginId, Number } from './generator';
-import { Capabilities } from '../../common';
-import { contributes } from '../../core';
-import { createIntent } from '../../plugin-intent';
-import { useCapabilities, useIntentDispatcher, usePluginManager } from '../../react';
+import * as Common from '../../common';
+import { Capability, type Plugin } from '../../core';
+import { useCapabilities, useOperationInvoker, usePluginManager } from '../../react';
+
+import { Number, createAlertOperation, createPluginId } from './generator';
 
 export const Toolbar = () => {
   const manager = usePluginManager();
-  const { dispatchPromise: dispatch } = useIntentDispatcher();
+  const plugins = useAtomValue(manager.plugins);
+  const { invokePromise } = useOperationInvoker();
 
   const handleAdd = useCallback(async () => {
     const id = createPluginId(Math.random().toString(16).substring(2, 8));
     await manager.add(id);
   }, [manager]);
 
-  const count = useCapabilities(Number).reduce((acc, curr) => acc + curr, 0);
+  const count = useCapabilities(Number).reduce((acc: number, curr: number) => acc + curr, 0);
 
-  const generatorPlugins = manager.plugins.filter((plugin) => plugin.meta.id.startsWith('dxos.org/test/generator/'));
+  const generatorPlugins = plugins.filter((plugin: Plugin.Plugin) =>
+    plugin.meta.id.startsWith('dxos.org/test/generator/'),
+  );
 
   return (
     <>
       <Button onClick={handleAdd}>Add</Button>
       <div className='flex items-center'>Count: {count}</div>
-      {generatorPlugins.map((plugin) => (
-        <Button key={plugin.meta.id} onClick={() => dispatch(createIntent(createGeneratorIntent(plugin.meta.id)))}>
+      {generatorPlugins.map((plugin: Plugin.Plugin) => (
+        <Button key={plugin.meta.id} onClick={() => invokePromise(createAlertOperation(plugin.meta.id))}>
           {plugin.meta.id.replace('dxos.org/test/generator/', '')}
         </Button>
       ))}
@@ -38,9 +43,15 @@ export const Toolbar = () => {
   );
 };
 
-export default () =>
-  contributes(Capabilities.ReactSurface, {
-    id: 'dxos.org/test/generator/toolbar',
-    role: 'toolbar',
-    component: Toolbar,
-  });
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(
+      Common.Capability.ReactSurface,
+      Common.createSurface({
+        id: 'dxos.org/test/generator/toolbar',
+        role: 'toolbar',
+        component: Toolbar,
+      }),
+    ),
+  ),
+);

package/src/playground/generator/generator.ts

@@ -2,47 +2,47 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
 
-import { Capabilities, Events } from '../../common';
-import { contributes, defineEvent, defineCapability, defineModule, definePlugin } from '../../core';
-import { createResolver, type IntentSchema } from '../../plugin-intent';
+import { Operation, OperationResolver } from '@dxos/operation';
 
-export const Number = defineCapability<number>('dxos.org/test/generator/number');
+import * as Common from '../../common';
+import { ActivationEvent, Capability, Plugin } from '../../core';
 
-export const CountEvent = defineEvent('dxos.org/test/generator/count');
+export const Number = Capability.make<number>('dxos.org/test/generator/number');
 
-export const createPluginId = (id: string) => `dxos.org/test/generator/${id}`;
+export const CountEvent = ActivationEvent.make('dxos.org/test/generator/count');
 
-export const createGeneratorIntent = (id: string) => {
-  class Alert extends Schema.TaggedClass<Alert>()(`${createPluginId(id)}/action/alert`, {
-    input: Schema.Void,
-    output: Schema.Void,
-  }) {}
+export const createPluginId = (id: string) => `dxos.org/test/generator/${id}`;
 
-  return Alert as unknown as IntentSchema<any, any>;
-};
+export const createAlertOperation = (id: string) =>
+  Operation.make({
+    meta: { key: `${createPluginId(id)}/operation/alert`, name: 'Alert' },
+    schema: { input: Schema.Void, output: Schema.Void },
+  });
 
 export const createNumberPlugin = (id: string) => {
   const number = Math.floor(Math.random() * 100);
+  const AlertOperation = createAlertOperation(id);
 
-  return definePlugin({ id, name: `Plugin ${id}` }, [
-    defineModule({
-      id: `${id}/main`,
+  return Plugin.define({ id, name: `Plugin ${id}` }).pipe(
+    Plugin.addModule({
+      id: 'Main',
       activatesOn: CountEvent,
-      activate: () => contributes(Number, number),
+      activate: () => Effect.succeed(Capability.contributes(Number, number)),
     }),
-    defineModule({
-      id: `${id}/intent-resolver`,
-      activatesOn: Events.SetupIntentResolver,
+    Common.Plugin.addOperationResolverModule({
       activate: () =>
-        contributes(
-          Capabilities.IntentResolver,
-          createResolver({
-            intent: createGeneratorIntent(id),
-            resolve: () => window.alert(JSON.stringify({ number })),
-          }),
+        Effect.succeed(
+          Capability.contributes(Common.Capability.OperationResolver, [
+            OperationResolver.make({
+              operation: AlertOperation,
+              handler: () => Effect.sync(() => window.alert(JSON.stringify({ number }))),
+            }),
+          ]),
         ),
     }),
-  ]);
+    Plugin.make,
+  )();
 };