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

package/src/core/registry.ts

@@ -0,0 +1,163 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Atom, type Registry as AtomRegistry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+
+/**
+ * A registry plugin entry as seen by the plugin manager layer.
+ * Populated from the registry catalog; represents the latest available version of a plugin.
+ *
+ * Independently defined from @dxos/protocols PluginEntry — similar shape but not the same type.
+ * Implementations of {@link PluginProvider} (e.g. {@link EdgeRegistryPluginProvider})
+ * are responsible for mapping their wire-format entries to this shape.
+ */
+export type Plugin = {
+  id: string;
+  name: string;
+  description?: string;
+  homePage?: string;
+  source?: string;
+  screenshots?: string[];
+  tags?: string[];
+  icon?: string;
+  iconHue?: string;
+  /**
+   * IDs of plugins this entry declares as runtime dependencies. Mirrors
+   * {@link Plugin.Meta.dependsOn}. Surfaced in the catalog so the manager can
+   * resolve and auto-install transitive deps before they are first loaded.
+   */
+  dependsOn?: string[];
+  /** URL to dynamic-import the latest version of this plugin module. */
+  moduleUrl: string;
+  /** GitHub repository slug, e.g. `owner/name`. Used to fetch version history. */
+  repo: string;
+  /**
+   * Latest known version string, e.g. `v1.2.0`.
+   * Corresponds to releaseTag in the wire-format PluginEntry; named `version` here
+   * because the plugin manager layer speaks versions, not release tags.
+   */
+  version: string;
+};
+
+/**
+ * A single installable version of a registry plugin.
+ */
+export type PluginVersion = {
+  /** Version string, e.g. `v1.2.0`. */
+  tag: string;
+  /** URL to dynamic-import this specific version of the plugin module. */
+  moduleUrl: string;
+  /** Unix ms of when this version was published (optional; omitted when unknown). */
+  releasedAt?: number;
+};
+
+/**
+ * Abstraction over the plugin registry catalog backend.
+ * Implementations may call Edge, a local cache, or a stub.
+ *
+ * The interface itself is transport-agnostic; concrete implementations live
+ * alongside it in this package (see {@link EdgeRegistryPluginProvider}) so we
+ * avoid `app-framework ↔ edge-client` cycles, but they only need to satisfy
+ * this shape — callers can substitute their own.
+ */
+export interface PluginProvider {
+  /**
+   * Returns all healthy registry plugins (latest version of each).
+   */
+  listPlugins(): Effect.Effect<readonly Plugin[], Error>;
+
+  /**
+   * Returns all known versions of a plugin identified by its GitHub repo slug.
+   * Until the backend implements a versions endpoint, implementations MUST
+   * return at least one entry representing the current/latest release.
+   */
+  listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error>;
+
+  /**
+   * Returns a single plugin entry for the given repo.
+   * If `version` is omitted, returns the latest.
+   * Fails if the specified version is not found.
+   */
+  getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error>;
+}
+
+/**
+ * Atomic snapshot of the registry catalog as observed by the host.
+ * Exposed via {@link Manager.plugins} so consumers can subscribe reactively
+ * (loading state, list contents, last error).
+ */
+export type PluginsState = {
+  entries: readonly Plugin[];
+  loading: boolean;
+  error: Error | null;
+};
+
+/**
+ * Default no-op provider used when no `PluginProvider` is supplied at construction
+ * time (e.g. tests, stories, environments without an Edge connection).
+ *
+ * `listPlugins` returns an empty list (so `Manager.plugins` settles to a stable
+ * empty state). `listVersions` and `getPlugin` fail with an explicit error so
+ * callers know they need to configure a real provider.
+ */
+const NULL_PROVIDER: PluginProvider = {
+  listPlugins: () => Effect.succeed([] as readonly Plugin[]),
+  listVersions: () => Effect.fail(new Error('No plugin registry provider configured')),
+  getPlugin: () => Effect.fail(new Error('No plugin registry provider configured')),
+};
+
+/**
+ * Owns the cached registry catalog state and forwards `listVersions` / `getPlugin`
+ * calls to the underlying {@link PluginProvider}. Lives on the `PluginManager`
+ * (as `manager.pluginRegistry`) so consumers can reach it through the manager
+ * without a separate capability lookup.
+ *
+ * On construction the manager kicks off a background fetch via `provider.listPlugins()`
+ * and writes the result into the {@link plugins} atom. Subscribers see `loading: true`
+ * during the fetch and `loading: false` once it settles.
+ */
+export class Manager {
+  readonly plugins: Atom.Writable<PluginsState>;
+  readonly #provider: PluginProvider;
+
+  constructor(provider: PluginProvider | undefined, atomRegistry: AtomRegistry.Registry) {
+    this.#provider = provider ?? NULL_PROVIDER;
+    const initialLoading = provider !== undefined;
+    this.plugins = Atom.make<PluginsState>({ entries: [], loading: initialLoading, error: null }).pipe(Atom.keepAlive);
+
+    if (provider !== undefined) {
+      // Fire-and-forget initial load. Errors are surfaced via the atom's `error` field.
+      void runAndForwardErrors(
+        provider.listPlugins().pipe(
+          Effect.match({
+            onSuccess: (entries) => atomRegistry.set(this.plugins, { entries, loading: false, error: null }),
+            onFailure: (error) => {
+              log.catch(error);
+              atomRegistry.set(this.plugins, { entries: [], loading: false, error });
+            },
+          }),
+        ),
+      );
+    }
+  }
+
+  /** Forwards to the underlying provider. */
+  listPlugins(): Effect.Effect<readonly Plugin[], Error> {
+    return this.#provider.listPlugins();
+  }
+
+  /** Forwards to the underlying provider. */
+  listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error> {
+    return this.#provider.listVersions(repo);
+  }
+
+  /** Forwards to the underlying provider. */
+  getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error> {
+    return this.#provider.getPlugin(repo, version);
+  }
+}

package/src/core/url-loader.test.ts

@@ -0,0 +1,221 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { assert, describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { runAndForwardErrors } from '@dxos/effect';
+
+import * as Plugin from './plugin';
+import * as PluginAssetCache from './plugin-asset-cache';
+import * as UrlLoader from './url-loader';
+
+const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
+
+const memoryStorage = (initial: string | null = null): UrlLoader.Storage => {
+  let value = initial;
+  return {
+    get: () => value,
+    set: (_key, next) => {
+      value = next;
+    },
+  };
+};
+
+type CacheCall = { method: 'cache' | 'evict' | 'resolve'; pluginId: string; urls?: readonly string[]; url?: string };
+
+const recordingCache = (): { cache: PluginAssetCache.Cache; calls: CacheCall[] } => {
+  const calls: CacheCall[] = [];
+  return {
+    calls,
+    cache: {
+      cache: (pluginId, urls) =>
+        Effect.sync(() => {
+          calls.push({ method: 'cache', pluginId, urls });
+        }),
+      evict: (pluginId) =>
+        Effect.sync(() => {
+          calls.push({ method: 'evict', pluginId });
+        }),
+      resolve: (pluginId, url) =>
+        Effect.sync(() => {
+          calls.push({ method: 'resolve', pluginId, url });
+          return url;
+        }),
+      list: () => Effect.succeed([] as readonly string[]),
+    },
+  };
+};
+
+describe('UrlLoader', () => {
+  describe('isLocalUrl', () => {
+    it('matches localhost, 127.0.0.1, and ::1', ({ expect }) => {
+      expect(UrlLoader.isLocalUrl('http://localhost:5173/plugin.mjs')).toBe(true);
+      expect(UrlLoader.isLocalUrl('https://LOCALHOST/plugin.mjs')).toBe(true);
+      expect(UrlLoader.isLocalUrl('http://127.0.0.1:8080/plugin.mjs')).toBe(true);
+      expect(UrlLoader.isLocalUrl('http://[::1]:8080/plugin.mjs')).toBe(true);
+    });
+
+    it('rejects public and malformed URLs', ({ expect }) => {
+      expect(UrlLoader.isLocalUrl('https://example.com/plugin.mjs')).toBe(false);
+      expect(UrlLoader.isLocalUrl('https://192.168.1.10/plugin.mjs')).toBe(false);
+      expect(UrlLoader.isLocalUrl('not a url')).toBe(false);
+      expect(UrlLoader.isLocalUrl('')).toBe(false);
+    });
+  });
+
+  describe('getRemoteEntries', () => {
+    it('returns persisted entries from storage', ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '[{"id":"p1","url":"http://localhost:5173/p.mjs"}]',
+        set: () => {},
+      };
+      expect(UrlLoader.getRemoteEntries({ storage })).toEqual([{ id: 'p1', url: 'http://localhost:5173/p.mjs' }]);
+    });
+
+    it('returns an empty array when storage is empty or malformed', ({ expect }) => {
+      const empty: UrlLoader.Storage = { get: () => null, set: () => {} };
+      const malformed: UrlLoader.Storage = { get: () => '{not json', set: () => {} };
+      expect(UrlLoader.getRemoteEntries({ storage: empty })).toEqual([]);
+      expect(UrlLoader.getRemoteEntries({ storage: malformed })).toEqual([]);
+    });
+  });
+
+  describe('setInstalledVersion / getInstalledVersion', () => {
+    it('stores and retrieves an installed version', ({ expect }) => {
+      const stored: Record<string, string> = {};
+      const storage: UrlLoader.Storage = {
+        get: (key) => stored[key] ?? null,
+        set: (key, value) => {
+          stored[key] = value;
+        },
+      };
+
+      // Seed a remote entry without a version.
+      storage.set('test-key', JSON.stringify([{ id: 'org.dxos.plugin.foo', url: 'http://example.com/p.mjs' }]));
+
+      UrlLoader.setInstalledVersion('org.dxos.plugin.foo', 'v1.0.0', { storage, key: 'test-key' });
+
+      expect(UrlLoader.getInstalledVersion('org.dxos.plugin.foo', { storage, key: 'test-key' })).toBe('v1.0.0');
+    });
+
+    it('returns undefined when plugin is not persisted', ({ expect }) => {
+      const storage: UrlLoader.Storage = { get: () => null, set: () => {} };
+      expect(UrlLoader.getInstalledVersion('org.dxos.plugin.missing', { storage })).toBeUndefined();
+    });
+
+    it('overwrites an existing version when called again', ({ expect }) => {
+      const stored: Record<string, string> = {};
+      const storage: UrlLoader.Storage = {
+        get: (key) => stored[key] ?? null,
+        set: (key, value) => {
+          stored[key] = value;
+        },
+      };
+      storage.set(
+        'test-key',
+        JSON.stringify([{ id: 'org.dxos.plugin.foo', url: 'http://example.com/p.mjs', version: 'v1.0.0' }]),
+      );
+
+      UrlLoader.setInstalledVersion('org.dxos.plugin.foo', 'v2.0.0', { storage, key: 'test-key' });
+      expect(UrlLoader.getInstalledVersion('org.dxos.plugin.foo', { storage, key: 'test-key' })).toBe('v2.0.0');
+    });
+  });
+
+  describe('make', () => {
+    it.effect('resolves built-in plugins by meta.id', () =>
+      Effect.gen(function* () {
+        const testPlugin = Plugin.make(Plugin.define(testMeta))();
+        const loader = UrlLoader.make([testPlugin]);
+        const result = yield* loader(testMeta.id);
+        assert.strictEqual(result.plugin.meta.id, testMeta.id);
+        // Builtins are not dev plugins.
+        assert.notOk(result.dev);
+      }),
+    );
+
+    it.effect('fails for unknown non-URL locator', () =>
+      Effect.gen(function* () {
+        const loader = UrlLoader.make([]);
+        const exit = yield* Effect.exit(loader('not-a-url'));
+        assert.isTrue(exit._tag === 'Failure');
+      }),
+    );
+  });
+
+  describe('preload', () => {
+    it('returns empty array when storage has no entries', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => null,
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage has invalid JSON', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '{{invalid json',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage contains null', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => 'null',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage contains an object', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '{}',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when entries are missing required fields', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '[{"title":"no url"}]',
+        set: () => {},
+      };
+      const result = await runAndForwardErrors(UrlLoader.preload({ storage }));
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('uninstall', () => {
+    it('removes the persisted entry and evicts cached assets', async ({ expect }) => {
+      const storage = memoryStorage('[{"id":"p1","url":"https://x/p1.json"},{"id":"p2","url":"https://x/p2.json"}]');
+      const { cache, calls } = recordingCache();
+      await runAndForwardErrors(UrlLoader.uninstall('p1', { storage, cache }));
+      expect(UrlLoader.getRemoteEntries({ storage })).toEqual([{ id: 'p2', url: 'https://x/p2.json' }]);
+      expect(calls).toEqual([{ method: 'evict', pluginId: 'p1' }]);
+    });
+
+    it('still removes entry when cache eviction fails', async ({ expect }) => {
+      const storage = memoryStorage('[{"id":"p1","url":"https://x/p1.json"}]');
+      const cache: PluginAssetCache.Cache = {
+        cache: () => Effect.void,
+        evict: () =>
+          Effect.fail(
+            new PluginAssetCache.PluginAssetCacheError({
+              context: { operation: 'evict', pluginId: 'p1' },
+              cause: 'boom',
+            }),
+          ),
+        resolve: (_id, url) => Effect.succeed(url),
+        list: () => Effect.succeed([] as readonly string[]),
+      };
+      await runAndForwardErrors(UrlLoader.uninstall('p1', { storage, cache }));
+      expect(UrlLoader.getRemoteEntries({ storage })).toEqual([]);
+    });
+  });
+});