@forgeax/engine-plugin 0.1.21 → 0.1.24

package/src/__tests__/public-api.test-d.ts

@@ -0,0 +1,70 @@
+// Public consumer imports validated by scripts/check-public-import-examples.mjs:
+// import { definePluginGroup, usePlugin } from '@forgeax/engine/plugin';
+// import { projectPluginEntries } from '@forgeax/engine/plugin/loader';
+// import { GameProjectSchema } from '@forgeax/engine/project';
+
+import type { Plugin as ForgePlugin, PluginCompositionError } from '../index.js';
+import { definePluginGroup, usePlugin } from '../index.js';
+import type { CatalogLoader, CatalogLoaderError, GamePluginEntry } from '../loader.js';
+import { projectPluginEntries } from '../loader.js';
+
+const child: ForgePlugin = { name: 'child', apply: () => undefined };
+const configuredChild: ForgePlugin.Object<{ readonly speed: number }> = {
+  name: 'configured-child',
+  apply: (_ctx, config) => config.speed,
+};
+// @ts-expect-error Plugin.Object config must preserve the declared field type.
+usePlugin(configuredChild, { speed: 'not-a-number' }, { key: 'invalid' });
+const group = definePluginGroup({
+  name: 'gameplay',
+  children: () => [usePlugin(child, undefined, { key: 'child' })],
+});
+const groupUse = usePlugin(group, undefined, { key: 'gameplay' });
+const entry: GamePluginEntry = { id: 'gameplay', name: './assets/gameplay.plugin.ts' };
+const projectedEntries = projectPluginEntries([entry], 'engine');
+async function retryLastKnownGood(
+  loader: CatalogLoader,
+  entries: Parameters<CatalogLoader['root']['update']>[0],
+): Promise<void> {
+  await loader.root.update(entries);
+  await loader.await();
+}
+type Assert<T extends true> = T;
+type PublicApiAssertions = [
+  Assert<typeof group extends ForgePlugin ? true : false>,
+  Assert<typeof groupUse.key extends string | undefined ? true : false>,
+  Assert<ReturnType<typeof projectPluginEntries> extends readonly object[] ? true : false>,
+];
+declare const publicApiAssertions: PublicApiAssertions;
+void publicApiAssertions;
+void projectedEntries;
+void retryLastKnownGood;
+
+function recoverPlugin(error: PluginCompositionError | CatalogLoaderError): string {
+  switch (error.code) {
+    case 'plugin-config-invalid':
+      return error.detail.plugin;
+    case 'plugin-group-child-failed':
+      return error.detail.child;
+    case 'plugin-group-dependency-cycle':
+      return error.detail.path.join(' > ');
+    case 'plugin-group-key-duplicate':
+      return error.detail.key;
+    case 'plugin-group-key-required':
+      return error.detail.plugin;
+    case 'plugin-group-provider-missing':
+      return error.detail.service;
+    case 'plugin-catalog-missing':
+      return error.detail.name;
+    case 'plugin-realm-mismatch':
+      return error.detail.actual;
+    case 'plugin-entry-realm-mixed':
+      return error.detail.group;
+    case 'plugin-realm-unsupported':
+      return error.detail.realm;
+    case 'plugin-catalog-digest-mismatch':
+      return error.detail.actual;
+  }
+}
+
+void recoverPlugin;

package/src/__tests__/realm-loader.integration.test.ts

@@ -0,0 +1,56 @@
+import { Context, type Plugin } from '@forgeax/engine-plugin';
+import { describe, expect, it } from 'vitest';
+import {
+  installCatalogLoader,
+  type PluginCatalog,
+  type PluginRealm,
+  projectPluginEntries,
+} from '../loader.js';
+
+function catalogOf(realm: PluginRealm, plugin: Plugin): PluginCatalog {
+  return new Map([[`@game/${realm}`, { realm, load: async () => ({ default: plugin }) }]]);
+}
+
+describe('realm loader integration', () => {
+  it('installs and cleans each physical realm from the same Catalog shape', async () => {
+    const events: string[] = [];
+    const plugin: Plugin = {
+      apply(ctx) {
+        events.push('apply');
+        ctx.effect(() => () => events.push('dispose'));
+      },
+    };
+
+    for (const realm of ['host', 'engine', 'build'] as const) {
+      const context = new Context();
+      const { loader } = await installCatalogLoader(context, catalogOf(realm, plugin), realm);
+      await loader.root.update([{ id: `${realm}-plugin`, name: `@game/${realm}` }]);
+      await loader.await();
+      expect([...loader.entries()]).toHaveLength(1);
+      await context.fiber.dispose();
+    }
+
+    expect(events).toEqual(['apply', 'dispose', 'apply', 'dispose', 'apply', 'dispose']);
+  });
+
+  it('rejects an entry that crosses a physical realm before activation', async () => {
+    expect(() =>
+      projectPluginEntries(
+        [
+          {
+            id: 'root',
+            name: 'cordis:group',
+            group: true,
+            realm: 'engine',
+            config: [{ id: 'host', name: '@game/host', realm: 'host' }],
+          },
+        ],
+        'engine',
+      ),
+    ).toThrowError(
+      expect.objectContaining({
+        code: 'plugin-entry-realm-mixed',
+      }),
+    );
+  });
+});

package/src/browser.ts

@@ -9,6 +9,24 @@
  */
 export * from '@deepseek-ai/cordis';
 export { createContextCapabilityResolver } from './capability.js';
+export {
+  definePluginGroup,
+  PluginCompositionError,
+  type PluginCompositionErrorArgs,
+  type PluginCompositionErrorCode,
+  type PluginCompositionErrorDetailByCode,
+  type PluginGroupOptions,
+  type PluginUse,
+  type PluginUseOptions,
+  usePlugin,
+} from './composition.js';
+export {
+  type CatalogPluginFiberState,
+  type CatalogPluginInspection,
+  type CatalogPluginInspectionEntry,
+  type CatalogPluginInspectionFailure,
+  inspectCatalogPlugins,
+} from './inspection.js';
 export {
   defineToolPlugin,
   isToolPlugin,