@dxos/app-framework 0.8.4-main.fffef41 → 0.9.0

package/src/plugin-process-manager/history/history-tracker.test.ts

@@ -0,0 +1,353 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+import * as TestClock from 'effect/TestClock';
+import { describe, expect } from 'vitest';
+
+import { Operation } from '@dxos/compute';
+import { OperationInvoker } from '@dxos/operation';
+
+const testRuntime = ManagedRuntime.make(Layer.empty) as unknown as ManagedRuntime.ManagedRuntime<any, any>;
+
+import {
+  Compute,
+  HalveCompute,
+  ToString,
+  computeHandler,
+  createEventCollector,
+  halveComputeHandler,
+  toStringHandler,
+  waitUntil,
+} from '../testing';
+import * as HistoryTracker from './history-tracker';
+import * as UndoMapping from './undo-mapping';
+import * as UndoRegistry from './undo-registry';
+
+describe('HistoryTracker', () => {
+  it.effect('tracks undoable operations', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Fork compute operation and advance clock.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      expect(tracker.canUndo()).toBe(true);
+    }),
+  );
+
+  it.effect('does not track operations without undo mapping', () =>
+    Effect.gen(function* () {
+      const invoker = OperationInvoker.make(() => Effect.succeed([toStringHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => []);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      yield* invoker.invoke(ToString, { value: 42 });
+
+      // Wait for the pending + success events to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Without an undo mapping, canUndo should remain false.
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('undo invokes inverse operation', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      let halveWasCalled = false;
+      const trackingHalveHandler = Operation.withHandler(HalveCompute, (data) => {
+        halveWasCalled = true;
+        return Effect.succeed({ value: data.value / 2 });
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, trackingHalveHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      // Fork compute operation: 2 * 2 = 4.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+      expect(tracker.canUndo()).toBe(true);
+
+      // Undo should invoke halve with { value: 4 }.
+      yield* tracker.undo();
+      expect(halveWasCalled).toBe(true);
+      expect(tracker.canUndo()).toBe(false);
+    }),
+  );
+
+  it.effect('undo uses _invokeCore to skip event emission', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      // Fork compute operation (emits one success event).
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      yield* collector.waitForEvents(1);
+      expect(collector.events.length).toBe(1);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // Undo (should NOT emit events because it uses _invokeCore).
+      yield* tracker.undo();
+
+      // Verify no new events were emitted.
+      expect(collector.events.length).toBe(1);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('multiple undos work in LIFO order', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const halveInputs: number[] = [];
+      const trackingHalveHandler = Operation.withHandler(HalveCompute, (data) => {
+        halveInputs.push(data.value);
+        return Effect.succeed({ value: data.value / 2 });
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, trackingHalveHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      // Fork compute with 2 → 4.
+      const fiber1 = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber1);
+
+      // Fork compute with 3 → 6.
+      const fiber2 = yield* Effect.fork(invoker.invoke(Compute, { value: 3 }));
+      yield* TestClock.adjust('30 millis');
+      yield* Fiber.join(fiber2);
+
+      // Each invoke emits one success event.
+      yield* collector.waitForEvents(2);
+
+      // First undo should halve 6 (the output of the second compute).
+      yield* tracker.undo();
+      expect(halveInputs[0]).toBe(6);
+
+      // Second undo should halve 4 (the output of the first compute).
+      yield* tracker.undo();
+      expect(halveInputs[1]).toBe(4);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('undo on empty history returns error', () =>
+    Effect.gen(function* () {
+      const invoker = OperationInvoker.make(() => Effect.succeed([]), testRuntime);
+      const tracker = HistoryTracker.make(
+        invoker,
+        UndoRegistry.make(() => []),
+      );
+
+      const result = yield* tracker.undo().pipe(Effect.either);
+      expect(result._tag).toBe('Left');
+      if (result._tag === 'Left') {
+        expect(result.left.message).toContain('empty');
+      }
+    }),
+  );
+
+  it.effect('publishes an undoable event with the resolved message', () =>
+    Effect.gen(function* () {
+      const testMessage: [string, { ns: string }] = ['test-undo.message', { ns: 'test' }];
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+        message: testMessage,
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const undoables = yield* PubSub.subscribe(tracker.undoable);
+
+          // Fork compute operation and advance clock.
+          const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+          yield* TestClock.adjust('20 millis');
+          yield* Fiber.join(fiber);
+
+          const undoable = yield* Queue.take(undoables);
+          expect(undoable.message).toEqual(testMessage);
+        }),
+      );
+      expect(tracker.canUndo()).toBe(true);
+    }),
+  );
+
+  it.effect('undo message can be derived from input and output', () =>
+    Effect.gen(function* () {
+      // Dynamic message that depends on input/output.
+      const dynamicMessage = (input: { value: number }, output: { value: number }): [string, { ns: string }] => [
+        `computed-${input.value}-to-${output.value}`,
+        { ns: 'test' },
+      ];
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+        message: dynamicMessage,
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      yield* Effect.scoped(
+        Effect.gen(function* () {
+          const undoables = yield* PubSub.subscribe(tracker.undoable);
+
+          // Fork compute operation and advance clock (2 * 2 = 4).
+          const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+          yield* TestClock.adjust('20 millis');
+          yield* Fiber.join(fiber);
+
+          const undoable = yield* Queue.take(undoables);
+          expect(undoable.message).toEqual(['computed-2-to-4', { ns: 'test' }]);
+        }),
+      );
+    }),
+  );
+
+  it.effect('does not track operations when deriveContext returns undefined', () =>
+    Effect.gen(function* () {
+      // Undo mapping that conditionally returns undefined to indicate not undoable.
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => {
+          // Return undefined for values less than 10 to indicate not undoable.
+          if (output.value < 10) {
+            return undefined;
+          }
+          return { value: output.value };
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Compute 2 * 2 = 4, which is < 10, so deriveContext returns undefined.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait for the pending + success events to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Even though there's an undo mapping, deriveContext returned undefined,
+      // so this operation should not be tracked as undoable.
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('tracks operations when deriveContext returns a value', () =>
+    Effect.gen(function* () {
+      // Undo mapping that conditionally returns undefined to indicate not undoable.
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => {
+          // Return undefined for values less than 10 to indicate not undoable.
+          if (output.value < 10) {
+            return undefined;
+          }
+          return { value: output.value };
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Compute 5 * 2 = 10, which is >= 10, so deriveContext returns a value.
+      // Handler sleeps for value * 10 = 50ms.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 5 }));
+      yield* TestClock.adjust('50 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait for the pending + success events to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // This operation should be tracked as undoable.
+      expect(tracker.canUndo()).toBe(true);
+
+      yield* collector.dispose;
+    }),
+  );
+});

package/src/plugin-process-manager/history/history-tracker.ts

@@ -0,0 +1,144 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as PubSub from 'effect/PubSub';
+import * as Stream from 'effect/Stream';
+
+import { EffectEx } from '@dxos/effect';
+import { log } from '@dxos/log';
+import { OperationInvoker } from '@dxos/operation';
+
+import { type Label } from '../../common';
+import { EmptyHistoryError } from './errors';
+import type { HistoryEntry } from './types';
+import { resolveMessage } from './undo-mapping';
+import type { UndoRegistry } from './undo-registry';
+
+const HISTORY_LIMIT = 100;
+
+//
+// Public Interface
+//
+
+/**
+ * Emitted when a new undoable action is recorded; consumed by the UI to surface an undo affordance
+ * (e.g. the deck notification tracker's undo toast).
+ */
+export type UndoableEvent = {
+  /** Message describing the undoable action. */
+  message?: Label;
+};
+
+/**
+ * HistoryTracker interface - tracks operation history and provides undo.
+ */
+export interface HistoryTracker {
+  undo: () => Effect.Effect<void, Error>;
+  undoPromise: () => Promise<{ error?: Error }>;
+  canUndo: () => boolean;
+  /** Stream of undoable actions, published as they are recorded. */
+  undoable: PubSub.PubSub<UndoableEvent>;
+}
+
+//
+// Factory
+//
+
+/**
+ * Creates a HistoryTracker that subscribes to (successful) invocation events, derives undoability from
+ * the undo registry, maintains the undo stack, and publishes an {@link UndoableEvent} for each undoable
+ * action so the UI can offer an undo affordance. The invoker itself is undo-agnostic.
+ */
+export const make = (
+  invoker: OperationInvoker.OperationInvokerInternal,
+  undoRegistry: UndoRegistry,
+): HistoryTracker => {
+  const history: HistoryEntry[] = [];
+  const undoable = Effect.runSync(PubSub.unbounded<UndoableEvent>());
+
+  // Record an invocation; returns the undoable event to publish, or undefined if not undoable.
+  const recordInvocation = (event: OperationInvoker.InvocationEvent): UndoableEvent | undefined => {
+    const mapping = undoRegistry.lookup(event.operation);
+    if (!mapping) {
+      // Operation is not undoable.
+      return undefined;
+    }
+
+    const inverseInput = mapping.deriveContext(event.input, event.output);
+    if (inverseInput === undefined) {
+      // Operation is conditionally not undoable (deriveContext returned undefined).
+      return undefined;
+    }
+
+    const entry: HistoryEntry = {
+      operation: event.operation,
+      input: event.input,
+      output: event.output,
+      inverse: mapping.inverse,
+      inverseInput,
+      timestamp: event.timestamp,
+    };
+
+    history.push(entry);
+    log('history entry added', { key: event.operation.meta.key, historyLength: history.length });
+
+    // Trim history if it exceeds limit.
+    if (history.length > HISTORY_LIMIT) {
+      history.splice(0, history.length - HISTORY_LIMIT);
+    }
+
+    return { message: resolveMessage(mapping.message, event.input, event.output) };
+  };
+
+  // Fork a fiber to consume the invocation stream.
+  Effect.runFork(
+    Stream.fromPubSub(invoker.invocations).pipe(
+      Stream.runForEach((event) =>
+        Effect.gen(function* () {
+          const undoableEvent = recordInvocation(event);
+          if (undoableEvent) {
+            yield* PubSub.publish(undoable, undoableEvent);
+          }
+        }),
+      ),
+    ),
+  );
+
+  const undo = (): Effect.Effect<void, Error> => {
+    return Effect.gen(function* () {
+      const entry = history.pop();
+      if (!entry) {
+        return yield* Effect.fail(new EmptyHistoryError());
+      }
+
+      log('undoing operation', { key: entry.operation.meta.key, inverseKey: entry.inverse.meta.key });
+
+      // Use _invokeCore to skip event emission (avoid undo-of-undo loops).
+      yield* invoker._invokeCore(entry.inverse, entry.inverseInput);
+
+      log('undo completed', { key: entry.operation.meta.key });
+    });
+  };
+
+  const undoPromise = async (): Promise<{ error?: Error }> => {
+    return EffectEx.runAndForwardErrors(undo())
+      .then(() => ({}))
+      .catch((error) => {
+        log.catch(error);
+        return { error };
+      });
+  };
+
+  const canUndo = (): boolean => {
+    return history.length > 0;
+  };
+
+  return {
+    undo,
+    undoPromise,
+    canUndo,
+    undoable,
+  };
+};

package/src/plugin-process-manager/history/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './errors';
+export * from './types';
+export * as UndoMapping from './undo-mapping';
+export * as UndoRegistry from './undo-registry';
+export * as HistoryTracker from './history-tracker';

package/src/plugin-process-manager/history/types.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/compute';
+
+/**
+ * History entry stored by HistoryTracker.
+ */
+export type HistoryEntry = {
+  operation: Operation.Definition<any, any>;
+  input: any;
+  output: any;
+  inverse: Operation.Definition<any, any>;
+  inverseInput: any;
+  timestamp: number;
+};

package/src/plugin-process-manager/history/undo-mapping.ts

@@ -0,0 +1,135 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/compute';
+
+/**
+ * Label type for translatable text (canonical definition in @dxos/app-toolkit).
+ */
+type Label = string | [string, { ns: string | readonly string[]; count?: number; defaultValue?: string }];
+
+/**
+ * Extract the input type from an OperationDefinition.
+ */
+export type InputOf<T> = T extends Operation.Definition<infer I, any> ? I : never;
+
+/**
+ * Extract the output type from an OperationDefinition.
+ */
+export type OutputOf<T> = T extends Operation.Definition<any, infer O> ? O : never;
+
+/**
+ * Message provider for undo toast.
+ * Can be a static Label or a function that derives the message from input/output.
+ */
+export type MessageProvider<Op extends Operation.Definition<any, any>> =
+  | Label
+  | ((input: InputOf<Op>, output: OutputOf<Op>) => Label);
+
+/**
+ * Undo mapping that links a forward operation to its inverse.
+ * Type parameters ensure deriveContext has correctly typed arguments.
+ *
+ * @template Op - The forward operation definition type.
+ * @template Inv - The inverse operation definition type.
+ */
+export interface UndoMapping<
+  Op extends Operation.Definition<any, any> = Operation.Definition<any, any>,
+  Inv extends Operation.Definition<any, any> = Operation.Definition<any, any>,
+> {
+  /** The forward operation. */
+  readonly operation: Op;
+
+  /** The inverse operation to invoke for undo. */
+  readonly inverse: Inv;
+
+  /**
+   * Derives the input for the inverse operation from the forward operation's input and output.
+   * @param input - The input that was passed to the forward operation.
+   * @param output - The output that was returned by the forward operation.
+   * @returns The input to pass to the inverse operation, or undefined to indicate the operation is not undoable.
+   */
+  readonly deriveContext: (input: InputOf<Op>, output: OutputOf<Op>) => InputOf<Inv> | undefined;
+
+  /**
+   * Optional message to show in the undo toast.
+   * Can be a static Label or a function that derives the message from input/output.
+   */
+  readonly message?: MessageProvider<Op>;
+}
+
+/**
+ * Props for creating an UndoMapping.
+ */
+export interface UndoMappingProps<
+  Op extends Operation.Definition<any, any>,
+  Inv extends Operation.Definition<any, any>,
+> {
+  /** The forward operation. */
+  operation: Op;
+
+  /** The inverse operation to invoke for undo. */
+  inverse: Inv;
+
+  /**
+   * Derives the input for the inverse operation from the forward operation's input and output.
+   * Return undefined to indicate the operation is not undoable.
+   */
+  deriveContext: (input: InputOf<Op>, output: OutputOf<Op>) => InputOf<Inv> | undefined;
+
+  /**
+   * Optional message to show in the undo toast.
+   * Can be a static Label or a function that derives the message from input/output.
+   */
+  message?: MessageProvider<Op>;
+}
+
+/**
+ * Creates a type-safe undo mapping.
+ *
+ * @example
+ * ```ts
+ * // Static message
+ * const mapping = UndoMapping.make({
+ *   operation: DeleteThread,
+ *   inverse: RestoreThread,
+ *   deriveContext: (input, output) => ({
+ *     thread: output.thread,
+ *     anchor: output.anchor,
+ *   }),
+ *   message: ['thread deleted label', { ns: '@dxos/plugin-thread' }],
+ * });
+ *
+ * // Dynamic message based on input/output
+ * const mapping = UndoMapping.make({
+ *   operation: RemoveObjects,
+ *   inverse: RestoreObjects,
+ *   deriveContext: (_input, output) => output,
+ *   message: (input, _output) =>
+ *     input.objects.length === 1
+ *       ? ['object deleted label', { ns: getTypename(input.objects[0]) }]
+ *       : ['objects deleted label', { ns: '@dxos/plugin-space' }],
+ * });
+ * ```
+ */
+export const make = <Op extends Operation.Definition<any, any>, Inv extends Operation.Definition<any, any>>(
+  props: UndoMappingProps<Op, Inv>,
+): UndoMapping<Op, Inv> => props;
+
+/**
+ * Resolves a message provider to a Label.
+ */
+export const resolveMessage = <Op extends Operation.Definition<any, any>>(
+  message: MessageProvider<Op> | undefined,
+  input: InputOf<Op>,
+  output: OutputOf<Op>,
+): Label | undefined => {
+  if (message === undefined) {
+    return undefined;
+  }
+  if (typeof message === 'function') {
+    return message(input, output);
+  }
+  return message;
+};