every-plugin 3.0.0-rc.0 → 3.0.0-rc.11

package/src/plugin.ts

@@ -5,6 +5,7 @@ import type { ContractedRouter, Implementer } from "@orpc/server";
 import { implement } from "@orpc/server";
 import type { Scope } from "effect";
 import { Context, Effect, Layer } from "effect";
+import type { PluginWarningInfo } from "./runtime/errors";
 import { type PluginRuntimeError, toPluginRuntimeError } from "./runtime/errors";
 
 type ContextOutput<T> = T extends AnySchema ? InferSchemaOutput<T> : Record<string, never>;
@@ -19,11 +20,26 @@ export type PluginConfigFor<
   context: TRequestContext;
 };
 
-type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+export type PluginInitializeInput<V extends AnySchema, S extends AnySchema> = {
+  /**
+   * The framework-assigned plugin id — the same key the host uses for secret
+   * injection and per-plugin database namespacing. Arrives as a value so
+   * plugin code never needs the ambient `PluginIdTag`.
+   */
+  pluginId: string;
   variables: InferSchemaOutput<V>;
   secrets: InferSchemaOutput<S>;
 };
 
+/**
+ * A plugin's own config-derived warnings, evaluated once with the validated
+ * config after initialization. Declaring `warnings` opts the plugin out of
+ * the loader's default missing-secret warning — these messages replace it.
+ */
+export type PluginWarningsFn<V extends AnySchema, S extends AnySchema> = (
+  config: PluginInitializeInput<V, S>,
+) => PluginWarningInfo[] | string[];
+
 export class PluginIdTag extends Context.Service<PluginIdTag, string>()("PluginId") {}
 
 /**
@@ -50,6 +66,13 @@ type PluginDefinition<
    * module statically.
    */
   servicesTag?: Context.Key<any, any>;
+  /**
+   * Optional warnings function evaluated once with the validated config after
+   * initialization. Returns structured non-fatal warnings (e.g. an optional
+   * secret was not set, so the feature depending on it is disabled).
+   * Declaring it opts out of the loader's default missing-secret warning.
+   */
+  warnings?: PluginWarningsFn<V, S>;
   /**
    * Initialize the plugin by returning an Effect `Layer`.
    *
@@ -107,6 +130,7 @@ export interface Plugin<
   readonly contract: TContract;
   readonly configSchema: PluginConfigFor<TVariables, TSecrets, TRequestContext>;
   readonly servicesTag?: Context.Key<any, any>;
+  readonly warnings?: PluginWarningsFn<TVariables, TSecrets>;
 
   initialize(
     config: PluginInitializeInput<TVariables, TSecrets>,
@@ -156,6 +180,7 @@ export const createPlugin: CreatePluginFn = function createPlugin<
     readonly contract = config.contract;
     readonly configSchema = configSchema;
     readonly servicesTag = config.servicesTag;
+    readonly warnings = config.warnings;
 
     initialize(
       pluginConfig: PluginInitializeInput<V, S>,

package/src/remote-entry.ts

@@ -23,8 +23,7 @@ const DEFAULT_TIMEOUT_MS = 120_000;
 const RETRY_BASE_DELAY_MS = 500;
 const RETRY_MAX_DELAY_MS = 5_000;
 
-export const sleep = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(resolve, ms));
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
 
 /**
  * Deletes the failed remote's keys from the process-global entry-load cache.

package/src/runtime/errors.ts

@@ -282,6 +282,50 @@ export interface PluginLoadFailureInfo {
   dbUrlMasked?: string;
 }
 
+/**
+ * Structured, serializable warning surfaced alongside plugin failures in
+ * health endpoints and dashboards. Warnings are non-fatal: the plugin loaded
+ * and initialized successfully, but runs with reduced functionality (e.g. an
+ * optional secret was not set, so the feature depending on it is disabled).
+ */
+export interface PluginWarningInfo {
+  /** loader-side key (host entry key, dev plugin id) */
+  pluginKey: string;
+  message: string;
+  hint?: string;
+}
+
+/**
+ * The loader's default warning policy for declared-but-unset secrets: a
+ * successfully initialized plugin whose declared secret names resolved to
+ * nothing (missing or empty in the environment) gets one consolidated
+ * warning. `*_DATABASE_URL` keys are excluded — they have the shared-API-DB
+ * fallback, and a genuinely-missing DB URL fails initialization (a `failure`,
+ * not a warning). A plugin that declares its own `warnings` function opts out
+ * of this default.
+ */
+export const defaultMissingSecretWarnings = (
+  pluginKey: string,
+  declaredKeys: readonly string[],
+  resolvedKeys: readonly string[],
+): PluginWarningInfo[] => {
+  const resolved = new Set(resolvedKeys);
+  const missing = declaredKeys.filter(
+    (key) => !resolved.has(key) && !key.endsWith("_DATABASE_URL"),
+  );
+  if (missing.length === 0) return [];
+  return [
+    {
+      pluginKey,
+      message:
+        missing.length === 1
+          ? `Declared secret ${missing[0]} is not set — features depending on it are disabled`
+          : `${missing.length} declared secrets are not set: ${missing.join(", ")} — features depending on them are disabled`,
+      hint: "Set the secret(s) in your environment (.env in development); see the plugin's config schema for what each enables",
+    },
+  ];
+};
+
 const NETWORK_RETRYABLE_PATTERNS = ["ETIMEDOUT", "ECONNRESET", "timeout", "503", "429"] as const;
 const NETWORK_DEAD_PATTERNS = ["ECONNREFUSED", "ENOTFOUND", "EHOSTUNREACH"] as const;
 const RETRYABLE_ORPC_CODES = new Set([

package/src/runtime/services/module-federation.service.ts

@@ -111,13 +111,10 @@ const resolveRemoteSelfName = (pluginId: string, url: string) =>
     const memo = remoteSelfNames.get(memoKey);
     if (memo) return memo;
 
-    let selfName: string | null = null;
-    try {
-      const manifest = yield* Effect.promise(() => fetchRemoteIdentityManifest(url));
-      selfName = manifest?.metaData?.name?.trim() || null;
-    } catch {
-      selfName = null;
-    }
+    const manifest = yield* Effect.tryPromise(() => fetchRemoteIdentityManifest(url)).pipe(
+      Effect.orElseSucceed(() => null),
+    );
+    const selfName = manifest?.metaData?.name?.trim() || null;
 
     const resolved = selfName ?? getNormalizedRemoteName(pluginId);
     remoteSelfNames.set(memoKey, resolved);

package/src/runtime/services/plugin-loader.service.ts

@@ -11,11 +11,39 @@ import type {
   PluginMetadata,
   PluginRegistry,
 } from "../../types";
+import type { PluginWarningInfo } from "../errors";
 import { PluginRuntimeError, toPluginRuntimeError } from "../errors";
 import { validate } from "../validation";
 import { ModuleFederationService } from "./module-federation.service";
 import { SecretsService } from "./secrets.service";
 
+/**
+ * Evaluate a plugin's `warnings` function against the validated config.
+ * Fail-safe: a throwing warnings function becomes a warning itself rather
+ * than failing initialization. Strings are normalized to `PluginWarningInfo`
+ * with the plugin's registry key.
+ */
+const collectPluginWarnings = (
+  plugin: AnyPlugin,
+  config: { pluginId: string; variables: unknown; secrets: unknown },
+): PluginWarningInfo[] => {
+  const warningsFn = plugin.warnings;
+  if (!warningsFn) return [];
+  try {
+    const raw = warningsFn(config as never);
+    return raw.map((warning) =>
+      typeof warning === "string" ? { pluginKey: plugin.id, message: warning } : warning,
+    );
+  } catch (error) {
+    return [
+      {
+        pluginKey: plugin.id,
+        message: `Plugin warnings check failed: ${error instanceof Error ? error.message : String(error)}`,
+      },
+    ];
+  }
+};
+
 export class PluginRegistryTag extends Context.Service<PluginRegistryTag, PluginRegistry>()(
   "PluginRegistry",
 ) {}
@@ -271,7 +299,14 @@ export const PluginLoaderServiceDefault = Layer.effect(
           // initialization leaks until the process exits.
           const effectContext = yield* Effect.gen(function* () {
             const layer = yield* plugin
-              .initialize({ variables: _variables, secrets: hydratedConfig.secrets }, plugins ?? {})
+              .initialize(
+                {
+                  pluginId: plugin.id,
+                  variables: _variables,
+                  secrets: hydratedConfig.secrets,
+                },
+                plugins ?? {},
+              )
               .pipe(
                 Effect.provideService(PluginIdTag, plugin.id),
                 Effect.provideService(Scope.Scope, scope),
@@ -310,9 +345,18 @@ export const PluginLoaderServiceDefault = Layer.effect(
           return {
             plugin,
             metadata: pluginInstance.metadata,
-            config: { variables: _variables, secrets: hydratedConfig.secrets },
+            config: {
+              pluginId: plugin.id,
+              variables: _variables,
+              secrets: hydratedConfig.secrets,
+            },
             effectContext,
             scope,
+            warnings: collectPluginWarnings(plugin, {
+              pluginId: plugin.id,
+              variables: _variables,
+              secrets: hydratedConfig.secrets,
+            }),
           } satisfies InitializedPlugin<T>;
         }),
     };

package/src/runtime/services/shared-identity.ts

@@ -19,7 +19,7 @@ function manifestUrl(remoteUrl: string): string {
 
 function normalizeBaseUrl(remoteUrl: string): string {
   const withoutHash = remoteUrl.split("#")[0] ?? remoteUrl;
-  return withoutHash.replace(/\/(mf-manifest\.json|remoteEntry\.js)$/i, "");
+  return withoutHash.replace(/\/(mf-manifest\.json|remoteEntry(?:\.[^/]+)?\.js)$/i, "");
 }
 
 export function compareSharedIdentity(

package/src/types.ts

@@ -7,6 +7,7 @@ import type {
 import type { ContractedRouter, RouterClient } from "@orpc/server";
 import type { Context, Scope } from "effect";
 import type { Plugin } from "./plugin";
+import type { PluginWarningInfo } from "./runtime/errors";
 
 /**
  * Registry bindings interface - populated via module augmentation
@@ -23,6 +24,24 @@ import type { Plugin } from "./plugin";
 // biome-ignore lint/suspicious/noEmptyInterface: required for module augmentation pattern
 export interface RegisteredPlugins {}
 
+export type ModuleTransport = "inproc" | "rpc" | "mf";
+
+export type ModuleSurface = "api" | "ui" | "jobs";
+
+export interface ModuleEndpoint {
+  readonly transport: ModuleTransport;
+  readonly surface?: ModuleSurface;
+  readonly url: string;
+  readonly path?: `/${string}`;
+  readonly manifest?: string;
+}
+
+export type PluginTransport = ModuleTransport;
+
+export type PluginSurface = ModuleSurface;
+
+export type PluginEndpoint = ModuleEndpoint;
+
 /**
  * Base type for any plugin instance.
  */
@@ -45,8 +64,14 @@ export type AnyPluginConstructor = {
  * Registry entry that supports both direct module imports and remote URLs
  */
 export type PluginRegistryEntry =
-  | { module: AnyPluginConstructor; remote?: string; version?: string; description?: string }
-  | { remote: string; version?: string; description?: string };
+  | {
+      module: AnyPluginConstructor;
+      remote?: string;
+      endpoint?: PluginEndpoint;
+      version?: string;
+      description?: string;
+    }
+  | { remote: string; endpoint?: PluginEndpoint; version?: string; description?: string };
 
 /**
  * Extract plugin constructor type from registry entry
@@ -115,8 +140,18 @@ export type PluginClientType<T> = RouterClient<PluginRouterType<T>>;
 export type PluginServicesEntry<T = any> = {
   client: (context?: PluginContextInput<T>) => PluginClientType<T>;
   router: PluginRouterType<T>;
+  endpoint?: PluginEndpoint;
 };
 
+export type ModuleClientEntry<C extends AnyContractRouter = AnyContractRouter> = {
+  client: (context?: Record<string, unknown>) => RouterClient<ContractedRouter<C, any>>;
+  router?: ContractedRouter<C, any>;
+  endpoint?: PluginEndpoint;
+};
+
+export type PluginClientEntry<C extends AnyContractRouter = AnyContractRouter> =
+  ModuleClientEntry<C>;
+
 /**
  * Extract plugin type from registered plugins by key
  * @param K - The plugin key
@@ -194,6 +229,7 @@ export interface InitializedPlugin<T extends AnyPlugin = AnyPlugin> {
   readonly plugin: T;
   readonly metadata: PluginMetadata;
   readonly config: {
+    pluginId: string;
     variables: InferSchemaOutput<T["configSchema"]["variables"]>;
     secrets: InferSchemaOutput<T["configSchema"]["secrets"]>;
   };
@@ -204,6 +240,8 @@ export interface InitializedPlugin<T extends AnyPlugin = AnyPlugin> {
    */
   readonly effectContext: Context.Context<any>;
   readonly scope: Scope.Closeable;
+  /** Non-fatal config warnings collected during initialization (empty when none). */
+  readonly warnings: PluginWarningInfo[];
 }
 
 /**

package/src/ui/manifest/construct.ts

@@ -1,5 +1,6 @@
 import type { AnyRoute } from "@tanstack/react-router";
 import { createRootRoute, createRoute, Outlet, redirect } from "@tanstack/react-router";
+import { CORE_UI_PLUGIN_KEY } from "./contract";
 import { digestOf } from "./descriptor";
 import type { PluginManifest, RouteRecord } from "./manifest-schema";
 import { MOUNT_REGISTRY, type MountDef, type MountId, resolveMountSegment } from "./mount-registry";
@@ -177,23 +178,53 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
     resolved.push(await input.resolve(ref));
   }
 
+  const ordered = [
+    ...resolved.filter((plugin) => plugin.key === CORE_UI_PLUGIN_KEY),
+    ...resolved.filter((plugin) => plugin.key !== CORE_UI_PLUGIN_KEY),
+  ];
+
   const optionsByPlugin = new Map<string, Map<string, RouteOptionsBundle>>();
+  const skippedByPlugin = new Map<string, Set<string>>();
   for (const plugin of resolved) {
+    // A plugin with no manifest at all contributes no routes — skip it rather
+    // than crashing SSR composition (same contract as the missing-loader skip
+    // below).
+    if (!plugin.manifest?.routes) continue;
     const optionsById = new Map<string, RouteOptionsBundle>();
+    const skipped = new Set<string>();
     await Promise.all(
       plugin.manifest.routes.map(async (record) => {
         const loader = plugin.routeConfig.routeConfigLoaders[record.id];
         if (!loader) {
-          throw new Error(`routeConfig for "${plugin.key}" has no loader for route "${record.id}"`);
+          console.log(
+            `[Compose] skipping route "${record.id}" in "${plugin.key}" — no routeConfig loader`,
+          );
+          skipped.add(record.id);
+          return;
         }
         optionsById.set(record.id, await loader());
       }),
     );
+    // cascade: any route whose parent is skipped is also skipped
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const record of plugin.manifest.routes) {
+        if (skipped.has(record.id)) continue;
+        if (record.parentId && skipped.has(record.parentId)) {
+          skipped.add(record.id);
+          changed = true;
+        }
+      }
+    }
     optionsByPlugin.set(plugin.key, optionsById);
+    skippedByPlugin.set(plugin.key, skipped);
   }
 
   const declarations = new Map<MountId, MountDeclaration>();
-  for (const plugin of resolved) {
+  const mountByLayoutId = new Map<string, MountId>();
+  for (const plugin of ordered) {
+    if (!plugin.manifest?.routes) continue;
     for (const record of plugin.manifest.routes) {
       if (!record.mount) continue;
       const mountId = record.mount as MountId;
@@ -205,15 +236,24 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
       }
       const existing = declarations.get(mountId);
       if (existing) {
+        if (existing.key === CORE_UI_PLUGIN_KEY && plugin.key !== CORE_UI_PLUGIN_KEY) {
+          console.log(
+            `[Compose] mount declaration "${existing.key}:${existing.record.id}" (${mountId}) shadows "${plugin.key}:${record.id}" — core ui wins; shadowed declaration skipped`,
+          );
+          mountByLayoutId.set(record.id, mountId);
+          continue;
+        }
         throw new Error(
           `mount "${mountId}" declared by multiple sources: "${existing.key}" (${existing.record.file}) and "${plugin.key}" (${record.file})`,
         );
       }
+      if (skippedByPlugin.get(plugin.key)!.has(record.id)) continue;
       declarations.set(mountId, {
         key: plugin.key,
         record,
         options: optionsByPlugin.get(plugin.key)!.get(record.id)!,
       });
+      mountByLayoutId.set(record.id, mountId);
     }
   }
 
@@ -244,11 +284,6 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
     mountRoutes.set(mountId, toAnyRoute(route));
   }
 
-  const mountByLayoutId = new Map<string, MountId>();
-  for (const [mountId, declaration] of declarations) {
-    mountByLayoutId.set(declaration.record.id, mountId);
-  }
-
   const nav: NavItem[] = [];
   const mountCounts: Record<string, number> = {};
   const childrenByParent = new Map<AnyRoute, AnyRoute[]>();
@@ -260,7 +295,8 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
     childrenByParent.set(parent, list);
   };
 
-  for (const plugin of resolved) {
+  for (const plugin of ordered) {
+    if (!plugin.manifest?.routes) continue;
     const optionsById = optionsByPlugin.get(plugin.key)!;
     const fullPathById = new Map<string, string>();
     const mountById = new Map<string, MountId>();
@@ -301,18 +337,25 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
       throw new Error(`route "${record.id}" in "${plugin.key}" must live under a mount`);
     };
 
-    const pending = plugin.manifest.routes.filter((record) => !record.mount);
+    const pending = plugin.manifest.routes.filter(
+      (record) => !record.mount && !skippedByPlugin.get(plugin.key)!.has(record.id),
+    );
+    const shadowedIds = new Set<string>();
     let progressed = true;
     while (pending.length > 0 && progressed) {
       progressed = false;
       for (let i = 0; i < pending.length; i += 1) {
         const record = pending[i]!;
-        if (
-          record.parentId &&
-          !byId.has(record.parentId) &&
-          !mountByLayoutId.has(record.parentId)
-        ) {
-          continue;
+        const parentId = record.parentId;
+        if (parentId) {
+          if (shadowedIds.has(parentId)) {
+            shadowedIds.add(record.id);
+            pending.splice(i, 1);
+            i -= 1;
+            progressed = true;
+            continue;
+          }
+          if (!byId.has(parentId) && !mountByLayoutId.has(parentId)) continue;
         }
         pending.splice(i, 1);
         progressed = true;
@@ -325,6 +368,16 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
           const siblings = claimedPathsByParent.get(parent.route) ?? new Map<string, string>();
           const claimant = siblings.get(routePath);
           if (claimant) {
+            if (
+              plugin.key !== CORE_UI_PLUGIN_KEY &&
+              claimant.startsWith(`${CORE_UI_PLUGIN_KEY}:`)
+            ) {
+              console.log(
+                `[Compose] route claim "${claimant}" (${routePath}) shadows "${plugin.key}:${record.id}" — core ui wins; shadowed route skipped`,
+              );
+              shadowedIds.add(record.id);
+              break;
+            }
             throw new Error(
               `path collision: "${plugin.key}" route "${record.id}" declares "${routePath}" which is already claimed by "${claimant}" under the same parent`,
             );

package/src/version-manifest.ts

@@ -41,9 +41,26 @@ export const WorkspaceVersionManifestSchema = z.object({
    * ignore it (zod strips unknown keys). Participates in the version hash.
    */
   files: z.record(z.string(), SRI).optional(),
+  /**
+   * Source archive of the workspace subtree (object path → served-object SRI)
+   * published beside the dists when the runtime opts in via
+   * `publish.sourcePublish` — lets `bos import` dereference a published
+   * config slot to the exact source bytes that build came from, with no
+   * GitHub dependency. Readers that predate the field ignore it (zod strips
+   * unknown keys). Participates in the version hash.
+   */
+  source: z
+    .object({
+      file: z.string().min(1),
+      integrity: SRI,
+    })
+    .optional(),
 });
 export type WorkspaceVersionManifest = z.infer<typeof WorkspaceVersionManifestSchema>;
 
+/** A published-artifact coordinate: object path within the bundle namespace + its served SRI. */
+export type SourceRef = NonNullable<WorkspaceVersionManifest["source"]>;
+
 export interface VersionManifestInput {
   /** Omit: a per-build timestamp makes the same version id map to different
    * manifest bytes per machine, breaking the pin's SRI against the image's
@@ -57,6 +74,7 @@ export interface VersionManifestInput {
   assets?: Record<string, string>;
   shared?: Record<string, string>;
   files?: Record<string, string>;
+  source?: { file: string; integrity: string };
 }
 
 /**
@@ -67,7 +85,7 @@ export interface VersionManifestInput {
  * coordinate → a new version (and a new file).
  */
 export function composeVersionManifest(input: VersionManifestInput): WorkspaceVersionManifest {
-  const { builtAt, ...hashedInputs } = input;
+  const { builtAt: _builtAt, ...hashedInputs } = input;
   const version = createHash("sha256")
     .update(stableStringify(hashedInputs))
     .digest("hex")