@zhin.js/runtime 1.1.7 → 1.1.9

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './config-composer.js';
+export * from './application-plugin-declaration.js';
 export { readPluginConfigSchema } from './plugin-config-schema.js';
 export * from './config-patch-planner.js';
 export * from './package-contract.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './config-composer.js';
+export * from './application-plugin-declaration.js';
 export { readPluginConfigSchema } from './plugin-config-schema.js';
 export * from './config-patch-planner.js';
 export * from './package-contract.js';

package/lib/manifest.d.ts

@@ -12,6 +12,10 @@ export interface ZhinPluginManifest {
     readonly entry: string;
     readonly engine?: string;
     readonly runtime?: 'trusted' | 'isolated';
+    readonly metadata?: Readonly<{
+        displayName?: string;
+        icon?: string;
+    }>;
     /**
      * When true (default), Root plugins receive official Stable Features
      * (`@zhin.js/adapter|command|component`) from the platform/CLI even if they

package/lib/manifest.js

@@ -75,11 +75,25 @@ function parseZhinManifest(value, source, issues) {
         entry,
         engine,
         runtime: runtime,
+        metadata: parsePluginMetadata(record.metadata, `${source}.metadata`, issues),
         platformFeatures,
         features: parseReferences(record.features, `${source}.features`, issues, false),
         plugins: parseReferences(record.plugins, `${source}.plugins`, issues, true),
     });
 }
+function parsePluginMetadata(value, source, issues) {
+    if (value === undefined)
+        return undefined;
+    const record = asRecord(value, source, issues);
+    for (const key of Object.keys(record)) {
+        if (key !== 'displayName' && key !== 'icon')
+            issues.push(`${source}.${key} is not supported`);
+    }
+    return Object.freeze({
+        ...(record.displayName !== undefined ? { displayName: readString(record, 'displayName', source, issues) } : {}),
+        ...(record.icon !== undefined ? { icon: readString(record, 'icon', source, issues) } : {}),
+    });
+}
 function parseReferences(value, source, issues, child) {
     if (value === undefined)
         return [];

package/lib/plugin-scope-assembler.d.ts

@@ -1,14 +1,15 @@
-import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type RuntimeSnapshot, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
+import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type RuntimeSnapshot, type RuntimeConfigDocument, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
 import { type RuntimeEnvironment } from './environment.js';
 import { type EnvironmentLayers } from './environment-store.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import type { PluginGraphNode } from './project-graph.js';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import { type PrimaryConfig } from './primary-config.js';
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 export interface PluginConfigResolver {
     (node: PluginGraphNode): unknown;
     schema?(node: PluginGraphNode): Readonly<Record<string, unknown>> | undefined;
+    /** Set by RootRuntime's actual composition branch, not by Plugin config values. */
+    compositionMode?: NonNullable<PrimaryConfig['compositionMode']>;
 }
 export interface RootResourceContext {
     /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
@@ -42,7 +43,6 @@ export declare class PluginScopeAssembler {
     private readonly modules;
     private readonly configResolver;
     private readonly environment;
-    private readonly primaryConfigDocument;
     private readonly generation;
     private readonly installResources?;
     private readonly isolation?;

package/lib/plugin-scope-assembler.js

@@ -2,13 +2,12 @@ import { resolve } from 'node:path';
 import { GenerationHandoffStack, Scope, capabilityId, createGenerationAdmissionGate, createToken, PluginDatabaseHost, PluginOutboundHost, PluginScheduleHost, databaseHostToken, databaseRootHostToken, outboundHostToken, outboundRootHostToken, featureId, rootPluginId, scheduleHostToken, scheduleRootHostToken, } from '@zhin.js/plugin-runtime';
 import { runtimeEnvironmentToken } from './environment.js';
 import { EnvStoreFactory, envStoreToken, } from './environment-store.js';
-import { createPrimaryConfig, primaryConfigToken, } from './primary-config.js';
+import { createPrimaryConfig, projectPrimaryConfigResources, primaryConfigToken, } from './primary-config.js';
 /** Assembles Plugin setup into mutable shadow maps without publishing them. */
 export class PluginScopeAssembler {
     modules;
     configResolver;
     environment;
-    primaryConfigDocument;
     generation;
     installResources;
     isolation;
@@ -22,20 +21,21 @@ export class PluginScopeAssembler {
     #admission = createGenerationAdmissionGate();
     #envStores;
     #candidateSnapshot;
+    #primaryConfig;
     #setupFeatureAliases = new Map();
     constructor(modules, configResolver, environment, primaryConfigDocument, generation, installResources, environmentLayers = {}, seed, isolation) {
         this.modules = modules;
         this.configResolver = configResolver;
         this.environment = environment;
-        this.primaryConfigDocument = primaryConfigDocument;
         this.generation = generation;
         this.installResources = installResources;
         this.isolation = isolation;
         this.#envStores = new EnvStoreFactory(environment, environmentLayers);
+        this.#primaryConfig = createPrimaryConfig(primaryConfigDocument, this.#envStores.create(rootPluginId()), configResolver.compositionMode);
         this.scopes = new Map(seed?.scopes);
         this.tree = new Map(seed?.tree);
         this.config = new Map(seed?.config);
-        this.resources = new Map(seed?.resources);
+        this.resources = projectPrimaryConfigResources(seed?.resources ?? new Map(), this.#primaryConfig);
     }
     removeSubtrees(roots) {
         // Seeded Scopes belong to a committed generation. Removing a map entry
@@ -64,12 +64,14 @@ export class PluginScopeAssembler {
         // Every owner shadows the inherited EnvStore with its exact overlay view.
         const environment = this.#envStores.create(node.id);
         scope.provide(envStoreToken, environment);
+        // New setup operations shadow a retained parent's construction-time value;
+        // operation contexts read the immutable projection from their own snapshot.
+        scope.provide(primaryConfigToken, this.#primaryConfig);
         const register = (feature, localName, capabilityDefinition) => this.#registerSetupCapability(node, manifest, feature, localName, capabilityDefinition);
         if (!node.parent) {
             scope.provide(runtimeEnvironmentToken, this.environment);
             scope.provide(rootGenerationAdmissionToken, this.#admission);
-            const config = createPrimaryConfig(this.primaryConfigDocument, environment);
-            scope.provide(primaryConfigToken, config);
+            const config = this.#primaryConfig;
             await this.installResources?.({
                 generation: this.generation,
                 readCandidateSnapshot: () => {
@@ -130,7 +132,7 @@ export class PluginScopeAssembler {
             }
             if (prepared.handoff)
                 this.#handoffs.add(prepared.handoff);
-            metadata = prepared.descriptor.metadata;
+            metadata = mergePluginMetadata(manifest, prepared.descriptor.metadata, node.id);
         }
         else {
             const module = await this.modules.load(resolve(node.package.root, manifest.entry));
@@ -139,6 +141,7 @@ export class PluginScopeAssembler {
             if (!definition || typeof definition.name !== 'string') {
                 throw new TypeError(`${node.package.name} does not default-export a Plugin definition`);
             }
+            metadata = mergePluginMetadata(manifest, definition.metadata, node.id);
             for (const token of definition.requires ?? []) {
                 if (!scope.has(token)) {
                     throw new Error(`Missing resource ${token.id} for Plugin ${node.id}`);
@@ -160,7 +163,6 @@ export class PluginScopeAssembler {
             signal.throwIfAborted();
             if (returned)
                 scope.disposers.add(returned);
-            metadata = definition.metadata;
         }
         scope.seal();
         this.tree.set(node.id, Object.freeze({
@@ -257,3 +259,11 @@ const rootGenerationAdmissionToken = createToken('zhin.runtime.root-generation-a
 function isWithin(plugin, root) {
     return plugin === root || plugin.startsWith(`${root}/`);
 }
+function mergePluginMetadata(manifest, code, owner) {
+    for (const key of ['displayName', 'icon']) {
+        if (manifest.metadata?.[key] !== undefined && code?.[key] !== undefined) {
+            throw new TypeError(`Plugin ${owner} declares metadata.${key} in both manifest and code`);
+        }
+    }
+    return manifest.metadata || code ? Object.freeze({ ...code, ...manifest.metadata }) : undefined;
+}

package/lib/primary-config.d.ts

@@ -1,5 +1,5 @@
+import { type PluginId, type RuntimeConfigDocument, type SnapshotState, type TokenId } from '@zhin.js/plugin-runtime';
 import type { EnvStore } from './environment-store.js';
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 /**
  * Generation-owned, validated Root configuration.
  *
@@ -8,9 +8,13 @@ import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
  * through the Root EnvStore instead of reading process.env themselves.
  */
 export interface PrimaryConfig {
+    /** Actual Runtime composition branch; absent on older authorities, never inferred from values. */
+    readonly compositionMode?: 'document' | 'custom' | 'unknown';
     readonly document: RuntimeConfigDocument;
     readonly expanded: RuntimeConfigDocument;
     get<T = unknown>(key: string): T | undefined;
 }
 export declare const primaryConfigToken: import("@zhin.js/plugin-runtime").Token<PrimaryConfig>;
-export declare function createPrimaryConfig(document: RuntimeConfigDocument, environment: EnvStore): PrimaryConfig;
+export declare function createPrimaryConfig(document: RuntimeConfigDocument, environment: EnvStore, compositionMode?: NonNullable<PrimaryConfig['compositionMode']>): PrimaryConfig;
+/** Copies bindings so retained Scopes never mutate a leased generation's view. */
+export declare function projectPrimaryConfigResources(resources: SnapshotState['resources'], config: PrimaryConfig): Map<PluginId, ReadonlyMap<TokenId, unknown>>;

package/lib/primary-config.js

@@ -1,9 +1,10 @@
 import { createToken } from '@zhin.js/plugin-runtime';
 export const primaryConfigToken = createToken('zhin.primary-config', 'Validated Root configuration for the current generation');
-export function createPrimaryConfig(document, environment) {
+export function createPrimaryConfig(document, environment, compositionMode = 'unknown') {
     const safeDocument = freezeConfig(structuredClone(document));
     const expanded = freezeConfig(environment.expandMissingAsEmpty(safeDocument));
     return Object.freeze({
+        compositionMode,
         document: safeDocument,
         expanded,
         get(key) {
@@ -11,6 +12,13 @@ export function createPrimaryConfig(document, environment) {
         },
     });
 }
+/** Copies bindings so retained Scopes never mutate a leased generation's view. */
+export function projectPrimaryConfigResources(resources, config) {
+    return new Map([...resources].map(([owner, bindings]) => [
+        owner,
+        new Map([...bindings, [primaryConfigToken.id, config]]),
+    ]));
+}
 function freezeConfig(value) {
     if (!value || typeof value !== 'object' || Object.isFrozen(value))
         return value;

package/lib/project-graph.d.ts

@@ -1,4 +1,4 @@
-import { type PluginId } from '@zhin.js/plugin-runtime';
+import { type PluginId, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { PackageReference } from './manifest.js';
 import { type PackageResolver, type ResolvedPackage } from './package-resolver.js';
 export interface FeatureRequirementNode {
@@ -28,5 +28,5 @@ export declare class ProjectGraphError extends Error {
 export declare class ProjectGraphService {
     #private;
     constructor(resolver: PackageResolver, engineVersionOrOptions?: string | ProjectGraphServiceOptions);
-    inspect(projectRoot: string): Promise<ProjectGraph>;
+    inspect(projectRoot: string, document?: RuntimeConfigDocument, pluginOrder?: readonly string[]): Promise<ProjectGraph>;
 }

package/lib/project-graph.js

@@ -1,7 +1,8 @@
 import { childPluginId, rootPluginId } from '@zhin.js/plugin-runtime';
+import { PLUGIN_INSTANCE_MIGRATION_GUIDE, readApplicationPluginDeclaration } from './application-plugin-declaration.js';
 import { assertFeatureApi, assertPackageEngine, runtimeEngineVersion, } from './package-contract.js';
 import { PackageResolutionError, } from './package-resolver.js';
-import { PLATFORM_FEATURE_CARRIER, PLATFORM_FEATURE_FACADE, declaredPackageDependency, mergeChildPluginReferences, mergeFeatureReferences, } from './platform-features.js';
+import { PLATFORM_FEATURE_CARRIER, PLATFORM_FEATURE_FACADE, declaredPackageDependency, mergeFeatureReferences, } from './platform-features.js';
 export class ProjectGraphError extends Error {
     constructor(message) {
         super(message);
@@ -21,11 +22,19 @@ export class ProjectGraphService {
             ? []
             : (engineVersionOrOptions.disabledPluginInstanceKeys ?? []));
     }
-    async inspect(projectRoot) {
+    async inspect(projectRoot, document = {}, pluginOrder) {
+        const declaration = readApplicationPluginDeclaration(document, 'Root config', pluginOrder);
+        if (this.#disabledPluginInstanceKeys.size > 0) {
+            throw new ProjectGraphError(`Legacy disabled Plugin state must move to disable_plugins; see ${PLUGIN_INSTANCE_MIGRATION_GUIDE}`);
+        }
         const rootPackage = await this.#resolver.root(projectRoot);
         assertPackageType(rootPackage, 'plugin');
+        if (rootPackage.packageJson.zhin.type === 'plugin'
+            && rootPackage.packageJson.zhin.plugins.length > 0) {
+            throw new ProjectGraphError(`Root package.json#zhin.plugins is no longer supported; see ${PLUGIN_INSTANCE_MIGRATION_GUIDE}`);
+        }
         const packages = new Map();
-        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages, true);
+        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages, true, declaration);
         for (const pkg of this.#resolver.workspacePackages())
             addPackage(packages, pkg);
         return Object.freeze({
@@ -34,7 +43,7 @@ export class ProjectGraphService {
             buildOrder: topologicalBuildOrder(packages),
         });
     }
-    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages, isRoot) {
+    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages, isRoot, declaration) {
         if (ancestors.includes(pkg.root)) {
             throw new ProjectGraphError(`Plugin cycle detected: ${[...ancestors, pkg.root].join(' -> ')}`);
         }
@@ -44,7 +53,8 @@ export class ProjectGraphService {
         let featureCarrier;
         let pluginFacade;
         let featureRefs = manifest.features;
-        let pluginRefs = manifest.plugins;
+        const pluginRefs = isRoot
+            ? declaration.instances.filter(item => item.enabled).map(item => ({ package: item.package, instanceKey: item.instanceKey })) : [];
         if (isRoot && manifest.platformFeatures !== false) {
             const platform = await tryResolvePlatform(this.#resolver, pkg);
             featureCarrier = platform.featureCarrier;
@@ -55,15 +65,8 @@ export class ProjectGraphService {
                 const inherited = carrierManifest.type === 'plugin' ? carrierManifest.features : [];
                 featureRefs = mergeFeatureReferences(manifest.features, inherited);
             }
-            if (pluginFacade) {
+            if (pluginFacade)
                 addPackage(packages, pluginFacade);
-                const facadeManifest = pluginFacade.packageJson.zhin;
-                const inheritedPlugins = facadeManifest.type === 'plugin' ? facadeManifest.plugins : [];
-                pluginRefs = mergeChildPluginReferences(manifest.plugins, inheritedPlugins);
-            }
-        }
-        if (isRoot && this.#disabledPluginInstanceKeys.size > 0) {
-            pluginRefs = pluginRefs.filter((reference) => !this.#disabledPluginInstanceKeys.has(reference.instanceKey));
         }
         const featurePackages = new Set();
         const features = await Promise.all(featureRefs.map(async (reference) => {
@@ -80,19 +83,17 @@ export class ProjectGraphService {
             addPackage(packages, resolved);
             return Object.freeze({ reference, package: resolved });
         }));
-        const ownPluginKeys = new Set(manifest.plugins.map((item) => item.instanceKey));
         const instanceKeys = new Set();
         const children = await Promise.all(pluginRefs.map(async (reference) => {
             if (instanceKeys.has(reference.instanceKey)) {
                 throw new ProjectGraphError(`Duplicate child instanceKey ${reference.instanceKey} in ${pkg.name}`);
             }
             instanceKeys.add(reference.instanceKey);
-            const resolveFrom = ownPluginKeys.has(reference.instanceKey) ? pkg : (pluginFacade ?? pkg);
-            const resolved = await resolveReference(this.#resolver, resolveFrom, reference);
+            const resolved = await resolveReference(this.#resolver, pkg, reference);
             if (!resolved)
                 return undefined;
             assertPackageType(resolved, 'plugin');
-            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages, false);
+            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages, false, declaration);
         }));
         return Object.freeze({
             id,

package/lib/root-runtime.d.ts

@@ -17,6 +17,8 @@ export interface RootRuntimeOptions {
     readonly environmentVariables?: EnvironmentLayers;
     readonly environmentSource?: EnvironmentLayersPort;
     readonly config?: PluginConfigResolver | RuntimeConfigDocument | ConfigDocumentPort;
+    /** Explicit v2 instance declaration when config is supplied by a custom resolver. */
+    readonly application?: RuntimeConfigDocument;
     readonly installResources?: RootResourceInstaller;
     readonly isolation?: IsolatedPluginRuntimePort;
     readonly onControlError?: ControlErrorHandler;