@dxos/app-framework 0.8.4-main.40e3dcdf1b → 0.8.4-main.43cb759274

package/src/plugin-process-manager/process-manager-capability.ts

@@ -0,0 +1,178 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom';
+import * as KeyValueStore from '@effect/platform/KeyValueStore';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+
+import { LayerSpec, OperationHandlerSet, Process, ServiceResolver, Trace } from '@dxos/compute';
+import { LayerStack, ProcessManager } from '@dxos/compute-runtime';
+import { invariant } from '@dxos/invariant';
+// Explicit import so the emitted `.d.ts` references the package via its public
+// alias instead of a relative `node_modules` path (TS2883).
+import { OperationInvoker } from '@dxos/operation';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Capability, Plugin } from '../core';
+
+//
+// Capability Module
+//
+// Hosts the {@link ProcessManager} runtime for the plugin system.
+//
+// Workflow:
+// 1. Activates {@link ActivationEvents.SetupProcessManager} so plugins can
+//    contribute {@link Capabilities.LayerSpec} entries and
+//    {@link Capabilities.OperationHandler} sets.
+// 2. Collects all contributed {@link LayerSpec.LayerSpec}s and builds a
+//    {@link LayerStack} whose {@link ServiceResolver} drives process-scoped
+//    service resolution.
+// 3. Wires a reactive {@link OperationHandlerSet} that tracks
+//    {@link Capabilities.OperationHandler} contributions and invalidates its
+//    cached merge when new handlers register.
+// 4. Composes the fixed runtime requirements (capability/plugin managers,
+//    service resolver, operation invoker, process manager) into a single
+//    {@link Layer} and builds a {@link ManagedRuntime} from it.
+// 5. Exposes a disposable-less wrapper as {@link Capabilities.ProcessManagerRuntime}
+//    (the plugin system manages its lifecycle).
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilityManager = yield* Capability.Service;
+    const pluginManager = yield* Plugin.Service;
+    const atomRegistry = yield* Capability.get(Capabilities.AtomRegistry);
+
+    yield* Plugin.activate(ActivationEvents.SetupProcessManager);
+
+    const layerSpecs = yield* Capability.getAll(Capabilities.LayerSpec);
+    const traceSinkFactories = yield* Capability.getAll(Capabilities.TraceSink);
+
+    // Forward reference to `ProcessManager.ProcessManagerService`. The runtime
+    // that owns the manager depends transitively on `ServiceResolver` (which is
+    // built from the `LayerStack` below), so we cannot materialise it before
+    // the stack exists. Instead we publish the manager into this holder as
+    // soon as the runtime is built, and the ambient layer reads it lazily via
+    // `Layer.effect` — slice init only runs once a process actually triggers
+    // service resolution, by which point the holder is populated.
+    let processManagerHolder: ProcessManager.Manager | undefined;
+
+    // Expose the foundational app-framework services through the LayerStack so
+    // that operations declaring `services: [Capability.Service]` (and friends)
+    // can resolve them via the ServiceResolver. Without this, only consumers
+    // sitting on the same ManagedRuntime layer graph can see them — process
+    // executions go through ServiceResolver.resolveAll and would fail.
+    const ambientLayerSpec = LayerSpec.make(
+      {
+        affinity: 'application',
+        requires: [],
+        provides: [Capability.Service, Plugin.Service, Registry.AtomRegistry, ProcessManager.ProcessManagerService],
+      },
+      () =>
+        Layer.mergeAll(
+          Layer.succeed(Capability.Service, capabilityManager),
+          Layer.succeed(Plugin.Service, pluginManager),
+          Layer.succeed(Registry.AtomRegistry, atomRegistry),
+          Layer.effect(
+            ProcessManager.ProcessManagerService,
+            Effect.sync(() => {
+              invariant(
+                processManagerHolder,
+                'ProcessManagerService accessed before the process-manager runtime was initialised',
+              );
+              return processManagerHolder;
+            }),
+          ),
+        ),
+    );
+
+    const layerStack = new LayerStack.LayerStack({ layers: [ambientLayerSpec, ...layerSpecs] });
+    const serviceResolver = layerStack.getServiceResolver();
+
+    const handlerSet = OperationHandlerSet.reactive(
+      atomRegistry,
+      capabilityManager.atom(Capabilities.OperationHandler),
+    );
+
+    const traceSinks = traceSinkFactories.map((factory) => factory({ resolver: serviceResolver }));
+    const mergedTraceSink = Trace.mergeSinks(traceSinks);
+
+    // Base services required by ProcessManager and the operation invoker.
+    // Sensible defaults are provided here; plugins that want alternative
+    // implementations (e.g. persistent KV store, real tracing) can contribute
+    // their own LayerSpec entries against the ServiceResolver.
+    const baseLayer = Layer.mergeAll(
+      Layer.succeed(Capability.Service, capabilityManager),
+      Layer.succeed(Plugin.Service, pluginManager),
+      Layer.succeed(Registry.AtomRegistry, atomRegistry),
+      Layer.succeed(ServiceResolver.ServiceResolver, serviceResolver),
+      OperationHandlerSet.provide(handlerSet),
+      KeyValueStore.layerMemory,
+      Layer.succeed(Trace.TraceSink, mergedTraceSink),
+    );
+
+    const processManagerLayer = ProcessManager.layer({ runtimeName: Trace.CommonRuntimeName.local }).pipe(
+      Layer.provide(baseLayer),
+    );
+    const operationInvokerLayer = ProcessManager.ProcessOperationInvoker.layer.pipe(
+      Layer.provide(Layer.mergeAll(processManagerLayer, baseLayer)),
+    );
+
+    const runtimeLayer = Layer.mergeAll(baseLayer, processManagerLayer, operationInvokerLayer);
+
+    const managedRuntime = ManagedRuntime.make(runtimeLayer as Layer.Layer<any, any, never>);
+
+    // TODO(dmaretskyi): Capability modules don't currently expose a teardown
+    // hook (`makeModule` only allows `Service | Plugin.Service` in the effect's
+    // requirements, ruling out `Effect.addFinalizer`). Once the plugin
+    // framework grows a shutdown lifecycle, dispose `managedRuntime` and then
+    // call `layerStack.destroy()` to tear down keep-alive slices.
+
+    const processManagerRuntime: Capabilities.ProcessManagerRuntime = {
+      runPromise: (effect, options) => managedRuntime.runPromise(effect as Effect.Effect<any, any, any>, options),
+      runPromiseExit: (effect, options) =>
+        managedRuntime.runPromiseExit(effect as Effect.Effect<any, any, any>, options),
+      runFork: (effect, options) => managedRuntime.runFork(effect as Effect.Effect<any, any, any>, options),
+      runSync: (effect) => managedRuntime.runSync(effect as Effect.Effect<any, any, any>),
+    };
+
+    // Eagerly extract the process monitor. Safe because it does not require a
+    // fresh scope and is a stable reference for the lifetime of the runtime.
+    const processMonitor = managedRuntime.runSync(
+      Effect.flatMap(Process.ProcessMonitorService, Effect.succeed) as Effect.Effect<Process.Monitor, never, never>,
+    );
+
+    // Publish the manager into the ambient-layer holder so that
+    // `ProcessManager.ProcessManagerService` becomes resolvable through the
+    // LayerStack alongside the other framework-supplied services.
+    processManagerHolder = managedRuntime.runSync(
+      Effect.flatMap(ProcessManager.ProcessManagerService, Effect.succeed) as Effect.Effect<
+        ProcessManager.Manager,
+        never,
+        never
+      >,
+    );
+
+    // Eagerly extract the operation invoker built by ProcessOperationInvoker.layer.
+    // Pulled via the ProcessOperationInvoker tag so the contributed value carries
+    // the full OperationInvoker interface (`invocations`, `pendingFollowups`,
+    // `awaitFollowups`, `_invokeCore`) that HistoryTracker requires.
+    const operationInvoker: OperationInvoker.OperationInvoker = managedRuntime.runSync(
+      Effect.flatMap(ProcessManager.ProcessOperationInvoker.Service, Effect.succeed) as unknown as Effect.Effect<
+        OperationInvoker.OperationInvoker,
+        never,
+        never
+      >,
+    );
+
+    return [
+      Capability.contributes(Capabilities.ProcessManagerRuntime, processManagerRuntime),
+      Capability.contributes(Capabilities.ServiceResolver, serviceResolver),
+      Capability.contributes(Capabilities.ProcessMonitor, processMonitor),
+      Capability.contributes(Capabilities.OperationInvoker, operationInvoker),
+    ];
+  }),
+);

package/src/{plugin-operation → plugin-process-manager}/testing.ts

@@ -9,84 +9,66 @@ import * as Ref from 'effect/Ref';
 import * as Schema from 'effect/Schema';
 import * as Stream from 'effect/Stream';
 
-import { Operation, type OperationInvoker, OperationResolver } from '@dxos/operation';
+import { Operation } from '@dxos/compute';
+import { DXN } from '@dxos/keys';
+import { OperationInvoker } from '@dxos/operation';
 
 //
 // Test Operations
 //
 
 export const Compute = Operation.make({
-  schema: {
-    input: Schema.Struct({ value: Schema.Number }),
-    output: Schema.Struct({ value: Schema.Number }),
-  },
-  meta: { key: 'test.compute' },
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
+  meta: { key: DXN.make('org.dxos.test.compute') },
 });
 
 export const HalveCompute = Operation.make({
-  schema: {
-    input: Schema.Struct({ value: Schema.Number }),
-    output: Schema.Struct({ value: Schema.Number }),
-  },
-  meta: { key: 'test.halve-compute' },
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
+  meta: { key: DXN.make('org.dxos.test.halveCompute') },
 });
 
 export const ToString = Operation.make({
-  schema: {
-    input: Schema.Struct({ value: Schema.Number }),
-    output: Schema.Struct({ string: Schema.String }),
-  },
-  meta: { key: 'test.to-string' },
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ string: Schema.String }),
+  meta: { key: DXN.make('org.dxos.test.toString') },
 });
 
 export const Add = Operation.make({
-  schema: {
-    input: Schema.Tuple(Schema.Number, Schema.Number),
-    output: Schema.Number,
-  },
-  meta: { key: 'test.add' },
+  input: Schema.Tuple(Schema.Number, Schema.Number),
+  output: Schema.Number,
+  meta: { key: DXN.make('org.dxos.test.add') },
 });
 
 export const SideEffect = Operation.make({
-  schema: {
-    input: Schema.Void,
-    output: Schema.Void,
-  },
-  meta: { key: 'test.side-effect' },
+  input: Schema.Void,
+  output: Schema.Void,
+  meta: { key: DXN.make('org.dxos.test.sideEffect') },
 });
 
 //
 // Test Handlers
 //
 
-export const computeHandler = OperationResolver.make({
-  operation: Compute,
-  handler: (data) =>
-    Effect.gen(function* () {
-      yield* Effect.sleep(data.value * 10);
-      return { value: data.value * 2 };
-    }),
-});
+export const computeHandler = Operation.withHandler(Compute, (data) =>
+  Effect.gen(function* () {
+    yield* Effect.sleep(data.value * 10);
+    return { value: data.value * 2 };
+  }),
+);
 
-export const halveComputeHandler = OperationResolver.make({
-  operation: HalveCompute,
-  handler: (data) => Effect.succeed({ value: data.value / 2 }),
-});
+export const halveComputeHandler = Operation.withHandler(HalveCompute, (data) =>
+  Effect.succeed({ value: data.value / 2 }),
+);
 
-export const toStringHandler = OperationResolver.make({
-  operation: ToString,
-  handler: (data) => Effect.succeed({ string: data.value.toString() }),
-});
+export const toStringHandler = Operation.withHandler(ToString, (data) =>
+  Effect.succeed({ string: data.value.toString() }),
+);
 
-export const addHandler = OperationResolver.make({
-  operation: Add,
-  handler: (data) => Effect.succeed(data[0] + data[1]),
-});
+export const addHandler = Operation.withHandler(Add, (data) => Effect.succeed(data[0] + data[1]));
 
-export const sideEffectHandler = OperationResolver.make({
-  operation: SideEffect,
-  handler: () => Effect.succeed(undefined),
-});
+export const sideEffectHandler = Operation.withHandler(SideEffect, () => Effect.succeed(undefined));
 
 //
 // Test Utilities

package/src/testing/harness.ts

@@ -0,0 +1,247 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Registry } from '@effect-atom/atom-react';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+
+import { type Operation } from '@dxos/compute';
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { ActivationEvent, type Capability, type CapabilityManager, type Plugin, PluginManager } from '../core';
+
+export type TestAppOptions = {
+  /**
+   * Plugins to register. Plugins whose `meta.tags` includes `'system'` are treated as core
+   * (force-enabled). For test convenience, plugins without a `'system'` tag are enabled by
+   * default unless `enabled` is provided.
+   */
+  plugins: Plugin.Plugin[];
+  /** Plugin ids that are enabled by default in addition to core. Defaults to all non-system plugin ids. */
+  enabled?: string[];
+  /** Additional activation events fired alongside SetupReactSurface. */
+  setupEvents?: ActivationEvent.ActivationEvent[];
+  /**
+   * Whether to automatically fire SetupReactSurface + Startup during setup.
+   * Defaults to true.
+   */
+  autoStart?: boolean;
+  /**
+   * Whether to register the PluginManager + AtomRegistry framework capabilities.
+   * Defaults to true.
+   */
+  registerFrameworkCapabilities?: boolean;
+};
+
+/**
+ * A running plugin manager plus helpers for driving it in tests.
+ */
+export interface TestHarness {
+  readonly manager: PluginManager.PluginManager;
+  readonly capabilities: CapabilityManager.CapabilityManager;
+  readonly registry: Registry.Registry;
+
+  /** Activate the given event. Equivalent to `manager.activate(event)`. */
+  fire(event: ActivationEvent.ActivationEvent | string): Promise<boolean>;
+  /** Re-activate all modules that were activated by the given event. */
+  reset(event: ActivationEvent.ActivationEvent | string): Promise<boolean>;
+
+  /** Returns the first contributed capability for the given interface. Throws if none are present. */
+  get<T>(iface: Capability.InterfaceDef<T>): T;
+  /** Returns all contributed capabilities for the given interface. */
+  getAll<T>(iface: Capability.InterfaceDef<T>): T[];
+  /** Waits until at least one capability is contributed for the given interface. */
+  waitForCapability<T>(iface: Capability.InterfaceDef<T>, opts?: { timeout?: number }): Promise<T>;
+  /** Waits until the given activation event has completed. */
+  waitForEvent(event: ActivationEvent.ActivationEvent | string, opts?: { timeout?: number }): Promise<void>;
+
+  /** Invokes an operation through the `Capabilities.OperationInvoker` capability. */
+  invoke<I, O>(op: Operation.Definition<I, O>, ...args: void extends I ? [input?: I] : [input: I]): Promise<O>;
+
+  /**
+   * Waits for `Capabilities.ProcessManagerRuntime` and runs the given effect on it.
+   * Convenience around `waitForCapability(ProcessManagerRuntime).runPromise(effect)`.
+   */
+  runPromise<A, E>(
+    effect: Effect.Effect<A, E, Capabilities.ProcessManagerRuntimeServices>,
+    options?: { readonly timeout?: number; readonly signal?: AbortSignal },
+  ): Promise<A>;
+
+  enable(id: string): Promise<boolean>;
+  disable(id: string): Promise<boolean>;
+
+  /** Shuts down the underlying plugin manager. */
+  dispose(): Promise<void>;
+
+  /** Async-disposable support so tests can use `await using harness = ...`. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+/**
+ * Creates a TestHarness with the same bootstrap sequence that `useApp` performs,
+ * minus the React provider tree.
+ *
+ * For Node-only tests, this is enough to fire activation events, read
+ * capabilities, and invoke operations.
+ *
+ * For React tests, pass the returned harness to `render` or `renderSurface`
+ * from `@dxos/app-framework/testing-react`.
+ */
+export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness> => {
+  const {
+    plugins,
+    enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map((plugin) => plugin.meta.id),
+    setupEvents = [],
+    autoStart = true,
+    registerFrameworkCapabilities = true,
+  } = opts;
+
+  const pluginLoader = (id: string) =>
+    Effect.sync(() => {
+      const plugin = plugins.find((plugin) => plugin.meta.id === id);
+      invariant(plugin, `Plugin not found: ${id}`);
+      return { plugin };
+    });
+
+  const manager = PluginManager.make({ pluginLoader, plugins, enabled });
+
+  if (registerFrameworkCapabilities) {
+    manager.capabilities.contribute({
+      interface: Capabilities.PluginManager,
+      implementation: manager,
+      module: 'org.dxos.app-framework.plugin-manager',
+    });
+    manager.capabilities.contribute({
+      interface: Capabilities.AtomRegistry,
+      implementation: manager.registry,
+      module: 'org.dxos.app-framework.atom-registry',
+    });
+  }
+
+  if (autoStart) {
+    try {
+      await runAndForwardErrors(
+        Effect.all([
+          ...setupEvents.map((event) => manager.activate(event)),
+          manager.activate(ActivationEvents.SetupReactSurface),
+          manager.activate(ActivationEvents.Startup),
+        ]),
+      );
+    } catch (err) {
+      await runAndForwardErrors(manager.shutdown()).catch(() => undefined);
+      throw err;
+    }
+  }
+
+  return new TestHarnessImpl(manager);
+};
+
+class TestHarnessImpl implements TestHarness {
+  constructor(readonly manager: PluginManager.PluginManager) {}
+
+  get capabilities(): CapabilityManager.CapabilityManager {
+    return this.manager.capabilities;
+  }
+
+  get registry(): Registry.Registry {
+    return this.manager.registry;
+  }
+
+  fire(event: ActivationEvent.ActivationEvent | string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.activate(event));
+  }
+
+  reset(event: ActivationEvent.ActivationEvent | string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.reset(event));
+  }
+
+  get<T>(iface: Capability.InterfaceDef<T>): T {
+    return this.manager.capabilities.get(iface);
+  }
+
+  getAll<T>(iface: Capability.InterfaceDef<T>): T[] {
+    return this.manager.capabilities.getAll(iface);
+  }
+
+  waitForCapability<T>(iface: Capability.InterfaceDef<T>, opts?: { timeout?: number }): Promise<T> {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    return runAndForwardErrors(
+      this.manager.capabilities.waitFor(iface).pipe(
+        Effect.timeoutFail({
+          duration: Duration.millis(timeout),
+          onTimeout: () => timeoutError(iface.identifier),
+        }),
+      ),
+    );
+  }
+
+  waitForEvent(event: ActivationEvent.ActivationEvent | string, opts?: { timeout?: number }): Promise<void> {
+    const key = typeof event === 'string' ? event : ActivationEvent.eventKey(event);
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+
+    const program = Effect.gen(this, function* () {
+      const queue = yield* PubSub.subscribe(this.manager.activation);
+      // Re-check after subscribing to avoid a race where the event fires
+      // between the caller invoking this and the subscription being installed.
+      if (this.manager.getEventsFired().includes(key)) {
+        return;
+      }
+      while (true) {
+        const message = yield* Queue.take(queue);
+        if (message.event === key && message.state === 'activated') {
+          return;
+        }
+      }
+    }).pipe(
+      Effect.scoped,
+      Effect.timeoutFail({
+        duration: Duration.millis(timeout),
+        onTimeout: () => timeoutError(key),
+      }),
+    );
+
+    return runAndForwardErrors(program);
+  }
+
+  async invoke<I, O>(op: Operation.Definition<I, O>, ...args: [input?: I]): Promise<O> {
+    const invoker = await this.waitForCapability(Capabilities.OperationInvoker);
+    const result = await invoker.invokePromise(op as any, ...(args as [any]));
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data as O;
+  }
+
+  async runPromise<A, E>(
+    effect: Effect.Effect<A, E, Capabilities.ProcessManagerRuntimeServices>,
+    options?: { readonly timeout?: number; readonly signal?: AbortSignal },
+  ): Promise<A> {
+    const runtime = await this.waitForCapability(Capabilities.ProcessManagerRuntime, { timeout: options?.timeout });
+    return runtime.runPromise(effect, options?.signal ? { signal: options.signal } : undefined);
+  }
+
+  enable(id: string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.enable(id));
+  }
+
+  disable(id: string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.disable(id));
+  }
+
+  async dispose(): Promise<void> {
+    await runAndForwardErrors(this.manager.shutdown());
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.dispose();
+  }
+}
+
+const timeoutError = (id: string) => new Error(`Timed out waiting for ${id}`);

package/src/testing/index.ts

@@ -2,5 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './harness';
 export * from './service';
 export * from './withPluginManager';

package/src/testing/react.test.tsx

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React from 'react';
+import { describe, test } from 'vitest';
+
+import { DXN } from '@dxos/keys';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Capability, Plugin } from '../core';
+import { Surface } from '../ui';
+import { createTestApp } from './harness';
+import { render, renderSurface } from './react';
+
+const testMeta = Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.test.reactHarness'), name: 'ReactHarnessTest' });
+
+const TestPlugin = Plugin.define(testMeta).pipe(
+  Plugin.addModule({
+    id: 'surfaces',
+    activatesOn: ActivationEvents.SetupReactSurface,
+    activate: () =>
+      Effect.succeed(
+        Capability.contributes(Capabilities.ReactSurface, [
+          Surface.create<{ message: string }>({
+            id: 'greeting',
+            role: 'greeting',
+            component: ({ data }) => <span data-testid='greeting'>hello {data.message}</span>,
+          }),
+        ]),
+      ),
+  }),
+  Plugin.make,
+);
+
+describe('testing/react', () => {
+  test('render wraps ui in the harness provider tree', async ({ expect }) => {
+    await using harness = await createTestApp({ plugins: [TestPlugin()] });
+    const view = render(harness, <span data-testid='hello'>world</span>);
+    expect(view.getByTestId('hello').textContent).toBe('world');
+  });
+
+  test('renderSurface mounts a surface registered by a plugin', async ({ expect }) => {
+    await using harness = await createTestApp({ plugins: [TestPlugin()] });
+    const view = renderSurface(harness, { role: 'greeting', data: { message: 'plugins' } });
+    const node = await view.findByTestId('greeting');
+    expect(node.textContent).toBe('hello plugins');
+  });
+});