@dxos/app-framework 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/core/plugin-manager.ts

@@ -341,7 +341,9 @@ class ManagerImpl implements PluginManager {
     // Core plugins are derived from `meta.tags.includes('system')`; the set is
     // a snapshot of the initial `plugins` array (later `add()` calls do not
     // promote plugins to core).
-    const core: string[] = plugins.filter(({ meta }) => meta.tags?.includes('system')).map(({ meta }) => meta.id);
+    const core: string[] = plugins
+      .filter(({ meta }) => meta.profile.tags?.includes('system'))
+      .map(({ meta }) => meta.profile.key);
     this.registry = registry ?? Registry.make();
     this.capabilities = CapabilityManager.make({
       registry: this.registry,
@@ -531,7 +533,7 @@ class ManagerImpl implements PluginManager {
     return Effect.gen(this, function* () {
       log('add plugin', { id });
       const { plugin, dev = false } = yield* this._pluginLoader(id);
-      const pluginId = plugin.meta.id;
+      const pluginId = plugin.meta.profile.key;
       const existing = this._getPlugin(pluginId);
 
       if (dev && existing && existing !== plugin) {
@@ -547,7 +549,9 @@ class ManagerImpl implements PluginManager {
           yield* this.disable(pluginId);
         }
         this._markDev(pluginId, { plugin: existing, wasEnabled });
-        this._update(this._pluginsAtom, (plugins) => plugins.map((p) => (p.meta.id === pluginId ? plugin : p)));
+        this._update(this._pluginsAtom, (plugins) =>
+          plugins.map((p) => (p.meta.profile.key === pluginId ? plugin : p)),
+        );
       } else {
         this._addPlugin(plugin);
         if (dev) {
@@ -721,7 +725,7 @@ class ManagerImpl implements PluginManager {
       if (!Plugin.isLazy(plugin)) {
         return plugin;
       }
-      const id = plugin.meta.id;
+      const id = plugin.meta.profile.key;
 
       const existing = this._resolvingPlugins.get(id);
       if (existing) {
@@ -747,7 +751,9 @@ class ManagerImpl implements PluginManager {
               }),
           }),
         );
-        this._update(this._pluginsAtom, (plugins) => plugins.map((p) => (p.meta.id === id ? resolvedPlugin : p)));
+        this._update(this._pluginsAtom, (plugins) =>
+          plugins.map((p) => (p.meta.profile.key === id ? resolvedPlugin : p)),
+        );
         yield* PubSub.publish(this.activation, { event: '', state: 'activated', module: `lazy:${id}` });
         return resolvedPlugin;
       }).pipe(
@@ -1015,17 +1021,17 @@ class ManagerImpl implements PluginManager {
   }
 
   private _getPlugin(id: string): Plugin.Plugin | undefined {
-    return this._get(this._pluginsAtom).find((plugin) => plugin.meta.id === id);
+    return this._get(this._pluginsAtom).find((plugin) => plugin.meta.profile.key === id);
   }
 
   private _getPluginIdForModule(moduleId: string): string | undefined {
     return this._get(this._pluginsAtom).find((plugin) => plugin.modules.some((module) => module.id === moduleId))?.meta
-      .id;
+      .profile.key;
   }
 
   /** Looks up an id in the cached registry catalog, returning the entry or `undefined`. */
-  private _getCatalogEntry(id: string): PluginRegistry.Plugin | undefined {
-    return this._get(this.pluginRegistry.plugins).entries.find((entry) => entry.id === id);
+  private _getCatalogEntry(id: string): Plugin.Meta | undefined {
+    return this._get(this.pluginRegistry.plugins).entries.find((entry) => entry.profile.key === id);
   }
 
   /**
@@ -1037,10 +1043,10 @@ class ManagerImpl implements PluginManager {
   private _directDependencies(id: string): string[] {
     const plugin = this._getPlugin(id);
     if (plugin) {
-      return [...(plugin.meta.dependsOn ?? [])];
+      return [...(plugin.meta.profile.dependsOn ?? [])];
     }
     const catalog = this._getCatalogEntry(id);
-    return catalog?.dependsOn ? [...catalog.dependsOn] : [];
+    return catalog?.profile.dependsOn ? [...catalog.profile.dependsOn] : [];
   }
 
   /**
@@ -1068,8 +1074,8 @@ class ManagerImpl implements PluginManager {
     let cycle: string[] | undefined;
 
     const knownIds = new Set<string>([
-      ...this._get(this._pluginsAtom).map((plugin) => plugin.meta.id),
-      ...this._get(this.pluginRegistry.plugins).entries.map((entry) => entry.id),
+      ...this._get(this._pluginsAtom).map((plugin) => plugin.meta.profile.key),
+      ...this._get(this.pluginRegistry.plugins).entries.map((entry) => entry.profile.key),
     ]);
 
     const visit = (currentId: string): void => {
@@ -1120,8 +1126,8 @@ class ManagerImpl implements PluginManager {
    */
   private _collectDependents(id: string, opts: { transitive: boolean; enabledOnly: boolean }): string[] {
     const direct = this._get(this._pluginsAtom)
-      .filter((plugin) => plugin.meta.dependsOn?.some((dep) => dep === id))
-      .map((plugin) => plugin.meta.id);
+      .filter((plugin) => plugin.meta.profile.dependsOn?.some((dep) => dep === id))
+      .map((plugin) => plugin.meta.profile.key);
 
     if (!opts.transitive) {
       return opts.enabledOnly
@@ -1137,8 +1143,8 @@ class ManagerImpl implements PluginManager {
       }
       visited.add(currentId);
       const parents = this._get(this._pluginsAtom)
-        .filter((plugin) => plugin.meta.dependsOn?.some((dep) => dep === currentId))
-        .map((plugin) => plugin.meta.id);
+        .filter((plugin) => plugin.meta.profile.dependsOn?.some((dep) => dep === currentId))
+        .map((plugin) => plugin.meta.profile.key);
       for (const parentId of parents) {
         visit(parentId);
         if (parentId !== id && !result.includes(parentId)) {
@@ -1281,14 +1287,14 @@ class ManagerImpl implements PluginManager {
   //
 
   private _addPlugin(plugin: Plugin.Plugin): void {
-    log('add plugin', { id: plugin.meta.id });
+    log('add plugin', { id: plugin.meta.profile.key });
     // TODO(wittjosiah): Find a way to add a warning for duplicate plugins that doesn't cause log spam.
     this._update(this._pluginsAtom, (plugins) => (plugins.includes(plugin) ? plugins : [...plugins, plugin]));
   }
 
   private _removePlugin(id: string): void {
     log('remove plugin', { id });
-    this._update(this._pluginsAtom, (plugins) => plugins.filter((plugin) => plugin.meta.id !== id));
+    this._update(this._pluginsAtom, (plugins) => plugins.filter((plugin) => plugin.meta.profile.key !== id));
   }
 
   private _addModule(module: Plugin.PluginModule): void {

package/src/core/plugin-manifest.test.ts

@@ -10,12 +10,12 @@ describe('PluginManifest', () => {
   describe('parse', () => {
     test('resolves entry and assets relative to manifest URL', ({ expect }) => {
       const resolved = PluginManifest.parse('https://example.com/plugins/foo/manifest.json', {
-        id: 'com.example.foo',
+        key: 'com.example.foo',
         name: 'Foo',
         version: '1.0.0',
         assets: ['index.mjs', 'style.css', 'chunks/lib-abc.js'],
       });
-      expect(resolved.id).toBe('com.example.foo');
+      expect(resolved.key).toBe('com.example.foo');
       expect(resolved.dev).toBe(false);
       expect(resolved.entryUrl).toBe('https://example.com/plugins/foo/index.mjs');
       expect(resolved.assetUrls).toEqual([
@@ -28,7 +28,7 @@ describe('PluginManifest', () => {
     test('throws if the canonical entry filename is not listed in assets', ({ expect }) => {
       expect(() =>
         PluginManifest.parse('https://example.com/manifest.json', {
-          id: 'a',
+          key: 'a',
           name: 'A',
           version: '0.0.1',
           assets: ['style.css'],
@@ -48,7 +48,7 @@ describe('PluginManifest', () => {
 
     test('devEntry flips dev mode and resolves the entry against the manifest URL', ({ expect }) => {
       const resolved = PluginManifest.parse('http://localhost:3967/manifest.json', {
-        id: 'com.example.foo',
+        key: 'com.example.foo',
         name: 'Foo',
         version: '0.0.0-dev',
         assets: [],
@@ -63,7 +63,7 @@ describe('PluginManifest', () => {
       // No `index.mjs` in assets — would throw without devEntry.
       expect(() =>
         PluginManifest.parse('http://localhost:3967/manifest.json', {
-          id: 'a',
+          key: 'a',
           name: 'A',
           version: '0.0.0-dev',
           assets: [],

package/src/core/plugin-manifest.ts

@@ -10,7 +10,7 @@ import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
 import { BaseError } from '@dxos/errors';
-import { PLUGIN_ENTRY_FILENAME } from '@dxos/protocols';
+import { PLUGIN_ENTRY_FILENAME, PluginManifestSchema } from '@dxos/protocols';
 
 /**
  * Default port the Vite plugin (`composerPlugin`) binds the dev server to.
@@ -48,11 +48,16 @@ export class PluginManifestError extends BaseError.extend('PluginManifestError',
  * the dev server on demand.
  */
 export const Manifest = Schema.Struct({
-  id: Schema.String,
-  name: Schema.String,
-  version: Schema.String,
+  // Reuse the build manifest field definitions from `@dxos/protocols` (the shape `composerPlugin`
+  // emits), minus `assets` which we relax below, plus the dev-only `devEntry`.
+  ...PluginManifestSchema.omit('assets').fields,
+  /**
+   * Relative asset paths. Relaxed vs the build `PluginManifestSchema` (which requires >= 1) because
+   * dev-server manifests list no assets — chunks/styles flow through the dev server on demand.
+   */
   assets: Schema.Array(Schema.String),
-  devEntry: Schema.String.pipe(Schema.optional),
+  /** Present only for dev-server manifests; points at the unbundled source entry. */
+  devEntry: Schema.optional(Schema.String),
 });
 
 export type Manifest = Schema.Schema.Type<typeof Manifest>;
@@ -64,10 +69,7 @@ export type Manifest = Schema.Schema.Type<typeof Manifest>;
  * on this to skip offline caching and stylesheet injection — both are no-ops (or
  * actively wrong) when the plugin is being served by a Vite dev server.
  */
-export type ResolvedManifest = {
-  id: string;
-  name: string;
-  version: string;
+export type ResolvedManifest = Pick<Manifest, 'key' | 'name' | 'version' | 'dependencies'> & {
   entryUrl: string;
   assetUrls: readonly string[];
   dev: boolean;
@@ -81,12 +83,13 @@ export type ResolvedManifest = {
 const resolve = (manifestUrl: string, manifest: Manifest): ResolvedManifest => {
   const dev = manifest.devEntry !== undefined;
   return {
-    id: manifest.id,
+    key: manifest.key,
     name: manifest.name,
     version: manifest.version,
     entryUrl: new URL(dev ? manifest.devEntry! : PLUGIN_ENTRY_FILENAME, manifestUrl).toString(),
     assetUrls: manifest.assets.map((asset) => new URL(asset, manifestUrl).toString()),
     dev,
+    ...(manifest.dependencies !== undefined ? { dependencies: manifest.dependencies } : {}),
   };
 };
 

package/src/core/plugin.ts

@@ -6,10 +6,12 @@ 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 * as Schema from 'effect/Schema';
 
 import { BaseError } from '@dxos/errors';
 import { invariant } from '@dxos/invariant';
 import { DXN } from '@dxos/keys';
+import { Config2, PluginProfileSchema, PluginReleaseSchema } from '@dxos/protocols';
 
 import type * as ActivationEvent from './activation-event';
 import * as Capability from './capability';
@@ -148,125 +150,64 @@ class PluginModuleImpl implements PluginModule {
   }
 }
 
-export type Meta = {
-  /**
-   * Bare NSID (the name portion of {@link key}, e.g. `org.dxos.plugin.example`).
-   * Stable across versions; used for module-id namespacing, i18n namespaces,
-   * enable/disable, and registry lookups. Derived from `key` by {@link makeMeta} —
-   * do not set directly.
-   */
-  id: string;
-
-  /**
-   * Canonical identity DXN, including version when published
-   * (e.g. `dxn:org.dxos.plugin.example:0.8.3`). The validated source of truth
-   * from which {@link id} and {@link version} are derived.
-   *
-   * @example DXN.make('org.dxos.plugin.example', '0.8.3')
-   */
-  key: DXN.DXN;
+/**
+ * Runtime plugin metadata, derived from the `@dxos/protocols` registry schemas (protocols owns the
+ * config + registry schemas; the runtime projection lives here).
+ *
+ * - {@link Profile}: version-independent identity + display + provenance — the wire `PluginProfileSchema`
+ *   (which carries `key`, the display fields, `dependsOn`, `spec`) plus `author` (resolved at runtime
+ *   from the publisher's handle/DID for registry plugins, or self-declared for bundled).
+ * - {@link Release}: a specific hosted release — the wire `PluginReleaseSchema` (version, moduleUrl, dependencies).
+ * - {@link Meta}: a resolved single-release view — `{ profile, release? }`, both nested. `release` is
+ *   unset for bundled plugins (compiled in) and set for registry plugins.
+ */
+export const Profile = Schema.Struct({
+  ...PluginProfileSchema.fields,
+  author: Schema.optional(Schema.String),
+});
+export type Profile = Schema.Schema.Type<typeof Profile>;
 
-  /**
-   * Human-readable name.
-   */
-  name: string;
+export const Release = PluginReleaseSchema;
+export type Release = Schema.Schema.Type<typeof Release>;
 
-  /**
-   * Semver version string of the plugin, typically the publishing package's
-   * `package.json` version. Derived from the version segment of {@link key} by
-   * {@link makeMeta} — do not set directly.
-   */
-  version?: string;
+export const Meta = Schema.Struct({
+  profile: Profile,
+  release: Schema.optional(Release),
+});
+export type Meta = Schema.Schema.Type<typeof Meta>;
 
-  /**
-   * Short description of plugin functionality.
-   */
+/** Options for {@link makeMeta}: the {@link Profile} content fields plus the canonical DXN `key`. */
+export type MakeMetaOptions = {
+  key: DXN.DXN;
+  name: string;
   description?: string;
-
-  /**
-   * Name of the author or organization that created the plugin.
-   */
-  // TODO(burdon): DID or domain name?
   author?: string;
-
-  /**
-   * URL of home page.
-   */
   homePage?: string;
-
-  /**
-   * URL of source code.
-   */
   source?: string;
-
-  /**
-   * Relative path (inside the published package) to the plugin's bundled MDL
-   * specification file — e.g. `'PLUGIN.mdl'` or `'docs/PLUGIN.mdl'`. The file
-   * is shipped via the package's `files` entry and resolved by registry
-   * surfaces to render an in-app viewer and/or external link.
-   */
+  tags?: readonly string[];
+  dependsOn?: readonly string[];
   spec?: string;
+  icon?: Config2.Icon;
+  screenshots?: ReadonlyArray<Config2.Screenshot>;
+};
 
-  /**
-   * URL of screenshot.
-   */
-  screenshots?: string[];
-
-  /**
-   * Tags to help categorize the plugin.
-   */
-  tags?: string[];
-
-  /**
-   * 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;
-
-  /**
-   * IDs of plugins this plugin functionally depends on.
-   *
-   * Treated as a convenience by the default `PluginManager` flow:
-   * - Enabling this plugin auto-enables the transitive closure of `dependsOn`
-   *   (installing missing entries from the plugin registry when possible).
-   * - Disabling a depended-upon plugin surfaces dependents to the caller; the
-   *   `PluginManager.disable` API supports an opt-in cascade.
-   *
-   * Not an invariant: low-level `PluginManager` APIs accept opt-outs
-   * (`resolveDependencies: false`, `ignoreDependents: true`) so a caller may
-   * substitute an alternative implementation that satisfies the dependent's
-   * capability needs in its own way.
-   */
-  dependsOn?: string[];
+/** Constructs a bundled-plugin {@link Meta} from a canonical DXN. `profile.key` is the bare NSID derived from `key`. */
+export const makeMeta = (options: MakeMetaOptions): Meta => {
+  const { key, ...rest } = options;
+  return { profile: { ...rest, key: DXN.getName(key) } };
 };
 
-/**
- * Options for {@link makeMeta}: a {@link Meta} minus the fields derived from `key`.
- * Identity and version are specified solely through the `key` DXN — `id` and
- * `version` cannot be passed directly.
- */
-export type MakeMetaOptions = Omit<Meta, 'id' | 'version'>;
+/** Returns the plugin's canonical DXN URI, constructed from `meta.profile.key` and `meta.release?.version`. */
+export const getURI = (meta: Meta): DXN.DXN => DXN.make(meta.profile.key, meta.release?.version);
 
 /**
- * Constructs a plugin {@link Meta} from a single canonical DXN. The `key` DXN is
- * the one source of truth; `id` (bare NSID) and `version` (semver) are derived
- * from it so each datum has exactly one home and cannot drift out of sync.
- *
- * @example
- * export const meta = Plugin.makeMeta({
- *   key: DXN.make('org.dxos.plugin.example', '0.8.3'),
- *   name: 'Example',
- * });
+ * Derives a runtime {@link Meta} from a loaded `dx.config.ts` (the `@dxos/protocols` `Config2.Config`).
+ * Maps the flat authoring config to the nested profile; bundled plugins have no `release`.
  */
-export const makeMeta = (options: MakeMetaOptions): Meta => ({
-  ...options,
-  id: DXN.getName(options.key),
-  version: DXN.getVersion(options.key),
-});
+export const getMetaFromConfig = ({ plugin }: Config2.Config): Meta => {
+  const { key, ...rest } = plugin;
+  return makeMeta({ key: DXN.make(key), ...rest });
+};
 
 /**
  * Identifier denoting a Plugin.
@@ -389,12 +330,12 @@ const resolveModule = (
   options?: any,
 ): PluginModuleImpl => {
   const moduleOptions = typeof module === 'function' ? module(options) : module;
-  const pluginName = meta.id;
+  const pluginName = meta.profile.key;
   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}`);
+        invariant(exportName, `Plugin module missing name. Plugin: ${meta.profile.key}`);
         return computeModuleId(pluginName, exportName);
       },
       onSome: (id) => computeModuleId(pluginName, id),
@@ -412,8 +353,11 @@ const resolveModule = (
 export function make<T>(builder: PluginBuilder<T>): PluginFactory<T>;
 export function make<T>(builder: PluginBuilder<T>): PluginFactory<T> {
   const meta = builder.meta;
-  // `dependsOn` entries and `id` are both bare NSIDs, so compare directly.
-  invariant(!meta.dependsOn?.includes(meta.id), `Plugin ${meta.id} declares itself as a dependency.`);
+  // `dependsOn` entries and `key` are both bare NSIDs, so compare directly.
+  invariant(
+    !meta.profile.dependsOn?.includes(meta.profile.key),
+    `Plugin ${meta.profile.key} declares itself as a dependency.`,
+  );
 
   const factory = (options: T) => {
     const modules = builder.modules.map((module) => resolveModule(meta, module, options));
@@ -448,7 +392,7 @@ type LazyPayload = { loader: LazyLoader<any>; options: unknown };
  * Defines a lazy plugin whose body is loaded on first enable.
  *
  * The returned factory produces a stub `Plugin` that exposes `meta`
- * synchronously (so callers can read `Plugin.meta.id` for free) but defers
+ * synchronously (so callers can read `Plugin.meta.profile.key` for free) but defers
  * loading the real plugin's modules until the manager calls
  * `Plugin.resolveLazy`. This lets the plugin's main entry point ship as a
  * tiny meta-only chunk — the heavy capabilities, schema, React surfaces,
@@ -487,7 +431,7 @@ export const isLazy = (plugin: Plugin): boolean => LazyTag in plugin;
 
 /**
  * Tagged error for failures during lazy plugin resolution. `context.id` is
- * the lazy plugin's `meta.id`; `context.reason` discriminates the failure
+ * the lazy plugin's `meta.profile.key`; `context.reason` discriminates the failure
  * mode (`'load-failed' | 'missing-default' | 'invalid-plugin' |
  * 'meta-mismatch'`) so callers can route on it.
  */
@@ -522,7 +466,7 @@ export const resolveLazy = (plugin: Plugin): Effect.Effect<Plugin, LazyPluginErr
     if (!isLazy(plugin)) {
       return plugin;
     }
-    const id = plugin.meta.id;
+    const id = plugin.meta.profile.key;
     const { loader, options } = (plugin as unknown as { [LazyTag]: LazyPayload })[LazyTag];
     const mod = yield* Effect.tryPromise({
       try: loader,
@@ -535,9 +479,9 @@ export const resolveLazy = (plugin: Plugin): Effect.Effect<Plugin, LazyPluginErr
     if (!isPlugin(result)) {
       return yield* Effect.fail(new LazyPluginError({ context: { id, reason: 'invalid-plugin' } }));
     }
-    if (result.meta.id !== id) {
+    if (result.meta.profile.key !== id) {
       return yield* Effect.fail(
-        new LazyPluginError({ context: { id, reason: 'meta-mismatch', returnedId: result.meta.id } }),
+        new LazyPluginError({ context: { id, reason: 'meta-mismatch', returnedId: result.meta.profile.key } }),
       );
     }
     return result;

package/src/core/registry.ts

@@ -8,53 +8,14 @@ import * as Effect from 'effect/Effect';
 import { EffectEx } 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;
-};
+import type * as Plugin from './plugin';
 
 /**
- * A single installable version of a registry plugin.
+ * A registry catalog entry is a {@link Plugin.Meta} (profile + the latest release), the same
+ * runtime type bundled plugins use. {@link PluginProvider} implementations (e.g.
+ * {@link EdgeRegistryPluginProvider}) map their wire-format entries (`PluginView`) to this shape.
+ * A single installable version is a {@link Plugin.Release}.
  */
-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.
@@ -67,23 +28,22 @@ export type PluginVersion = {
  */
 export interface PluginProvider {
   /**
-   * Returns all healthy registry plugins (latest version of each).
+   * Returns all registry plugins (latest version of each).
    */
-  listPlugins(): Effect.Effect<readonly Plugin[], Error>;
+  listPlugins(): Effect.Effect<readonly Plugin.Meta[], 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.
+   * Returns all known versions of a plugin, identified by its composer plugin id (NSID).
+   * Ordered newest-first. Must return at least one entry.
    */
-  listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error>;
+  listVersions(id: string): Effect.Effect<readonly Plugin.Release[], Error>;
 
   /**
-   * Returns a single plugin entry for the given repo.
+   * Returns a single plugin entry for the given id.
    * If `version` is omitted, returns the latest.
-   * Fails if the specified version is not found.
+   * Fails if the plugin or version is not found.
    */
-  getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error>;
+  getPlugin(id: string, version?: string): Effect.Effect<Plugin.Meta, Error>;
 }
 
 /**
@@ -92,7 +52,7 @@ export interface PluginProvider {
  * (loading state, list contents, last error).
  */
 export type PluginsState = {
-  entries: readonly Plugin[];
+  entries: readonly Plugin.Meta[];
   loading: boolean;
   error: Error | null;
 };
@@ -106,7 +66,7 @@ export type PluginsState = {
  * callers know they need to configure a real provider.
  */
 const NULL_PROVIDER: PluginProvider = {
-  listPlugins: () => Effect.succeed([] as readonly Plugin[]),
+  listPlugins: () => Effect.succeed([] as readonly Plugin.Meta[]),
   listVersions: () => Effect.fail(new Error('No plugin registry provider configured')),
   getPlugin: () => Effect.fail(new Error('No plugin registry provider configured')),
 };
@@ -147,17 +107,17 @@ export class Manager {
   }
 
   /** Forwards to the underlying provider. */
-  listPlugins(): Effect.Effect<readonly Plugin[], Error> {
+  listPlugins(): Effect.Effect<readonly Plugin.Meta[], Error> {
     return this.#provider.listPlugins();
   }
 
   /** Forwards to the underlying provider. */
-  listVersions(repo: string): Effect.Effect<readonly PluginVersion[], Error> {
-    return this.#provider.listVersions(repo);
+  listVersions(id: string): Effect.Effect<readonly Plugin.Release[], Error> {
+    return this.#provider.listVersions(id);
   }
 
   /** Forwards to the underlying provider. */
-  getPlugin(repo: string, version?: string): Effect.Effect<Plugin, Error> {
-    return this.#provider.getPlugin(repo, version);
+  getPlugin(id: string, version?: string): Effect.Effect<Plugin.Meta, Error> {
+    return this.#provider.getPlugin(id, version);
   }
 }

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

@@ -129,8 +129,8 @@ describe('UrlLoader', () => {
       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);
+        const result = yield* loader(testMeta.profile.key);
+        assert.strictEqual(result.plugin.meta.profile.key, testMeta.profile.key);
         // Builtins are not dev plugins.
         assert.notOk(result.dev);
       }),