@memberjunction/dynamic-packages 0.0.0 → 6.1.0-edge.7

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,45 +1,402 @@
 # @memberjunction/dynamic-packages
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Process-agnostic loader for packages whose names are only known at runtime:
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+- Open App server / client packages recorded in `mj.config.cjs` `dynamicPackages.server[]` /
+  `dynamicPackages.client[]` by `mj app install`
+- a host's own generated packages under `codeGeneration.packages`
+- the packages of the Open App whose repository a process is standing in (`mj-app.json`)
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+Importing one of these packages fires its `@RegisterClass` decorators, so `Metadata.GetEntityObject`
+returns the app's entity subclass (validation, `Save()` overrides, lifecycle hooks) instead of a
+generic `BaseEntity`. MJAPI has always done this at boot. Every other MJ process — the `mj` CLI
+(`sync push`, `app …`, `test`, …), the MCP and A2A servers, the integration-test bootstrap, an ad-hoc
+script — needs exactly the same behaviour, and this package is where it lives so each host is one call.
 
-## Purpose
+The repo-wide story (why it exists, how a downstream app and an MJ install configure it, how to add
+it to a new host) is in [`guides/DYNAMIC_PACKAGE_LOADING_GUIDE.md`](../../guides/DYNAMIC_PACKAGE_LOADING_GUIDE.md).
+This README is the package reference.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/dynamic-packages`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## Contents
 
-## What is OIDC Trusted Publishing?
+1. [The problem in one picture](#the-problem-in-one-picture)
+2. [Usage](#usage)
+3. [How a call proceeds](#how-a-call-proceeds)
+4. [Discovery sources and merge rules](#discovery-sources-and-merge-rules)
+5. [Process IDs](#process-ids)
+6. [Scoping entries per process](#scoping-entries-per-process)
+7. [Mode: turning it off](#mode-turning-it-off)
+8. [Nested hosts](#nested-hosts)
+9. [Running inside an Open App repository](#running-inside-an-open-app-repository)
+10. [Resolution: how a package is found](#resolution-how-a-package-is-found)
+11. [Loading twice in one process](#loading-twice-in-one-process)
+12. [The report](#the-report)
+13. [Loggers](#loggers)
+14. [Contract for `StartupExport`](#contract-for-startupexport)
+15. [API](#api)
+16. [Testing a host against it](#testing-a-host-against-it)
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## The problem in one picture
 
-## Setup Instructions
+`MJGlobal.ClassFactory` is a registry keyed by `(baseClass, key)`. `@RegisterClass(BaseEntity, 'MJ_BizApps_Orders: Orders')`
+registers a subclass under that key **as a side effect of importing the module that declares it**.
+Nothing else ever puts it there. So a process that has not imported the app's package gets the fallback:
 
-To properly configure OIDC trusted publishing for this package:
+```mermaid
+flowchart LR
+    subgraph MJAPI["MJAPI (always loaded app packages)"]
+        A1["import '@mj-biz-apps/orders-server'"] --> A2["@RegisterClass fires"]
+        A2 --> A3["ClassFactory: Orders → OrderEntityServer"]
+        A3 --> A4["GetEntityObject('…Orders')<br/>→ OrderEntityServer<br/>Save() override runs ✅"]
+    end
+    subgraph CLI["mj sync push (before this package)"]
+        B1["no import"] --> B3["ClassFactory: Orders → (nothing)"]
+        B3 --> B4["GetEntityObject('…Orders')<br/>→ plain BaseEntity<br/>Save() override skipped ❌"]
+    end
+```
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+The fallback is silent: the push reports success, the row is written, and the app's validation and
+lifecycle logic simply never ran (MemberJunction/MJ#4199). The loader closes that gap for every process
+by making "import whatever the configuration names" a single call with one set of rules.
 
-## DO NOT USE THIS PACKAGE
+## Usage
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```ts
+import { LoadDynamicPackages, DiscoverMJConfig } from '@memberjunction/dynamic-packages';
 
-## More Information
+// 1. Discover the RAW mj.config.cjs (Zod-parsed configs usually strip `dynamicPackages`).
+const { config, configFilePath } = DiscoverMJConfig();
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+// 2. Load — BEFORE any database provider is set up, exactly where MJAPI does it.
+const report = await LoadDynamicPackages({ processId: 'mcp', config, configFilePath });
 
----
+report.Loaded;    // [{ Entry, Source, Module, RanStartupExport }]
+report.Skipped;   // disabled / process-filter / mode-none / duplicate
+report.NotFound;  // not resolvable from any anchor (expected before `npm install`)
+report.Failed;    // resolved but threw while loading — its own error, never masked
+```
 
-**Maintained for OIDC setup purposes only**
+Call it **after** the host's own class-registration manifest (`@memberjunction/server-bootstrap`,
+`@memberjunction/server-bootstrap-lite`) has been imported: the ClassFactory's load-order priority
+means the app's registrations land last and win. Call it **before** the provider is created: a
+`StartupExport` may rely on nothing but the ClassFactory.
+
+The package has one runtime dependency (`cosmiconfig`) and no MJ dependencies, so it can be the first
+MJ-shaped thing a process imports.
+
+## How a call proceeds
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Host as Host process<br/>(mjapi, cli:sync:push, mcp, …)
+    participant L as LoadDynamicPackages
+    participant D as Discovery
+    participant M as Mode
+    participant R as Resolution
+    participant CF as ClassFactory
+
+    Host->>L: { processId, config, configFilePath, tier }
+    L->>M: ResolveDynamicPackagesMode(env, option, policy)
+    M-->>L: 'load' | 'none' (+ source)
+    L->>D: codeGeneration.packages → dynamicPackages.<tier>[] → mj-app.json
+    D-->>L: ordered candidates (tagged generated / config / manifest)
+    L->>L: mergeCandidates() — dedupe by PackageName, config entry is authority
+    alt mode 'none'
+        L-->>Host: every candidate in Skipped (mode-none)
+    else mode 'load'
+        loop each candidate, in order
+            L->>L: Enabled === false? → Skipped (disabled)
+            L->>L: MatchesProcess(processId, entry)? no → Skipped (process-filter)
+            L->>L: already loaded in this process? → Loaded (RanStartupExport: false)
+            L->>R: importFromHost(name, configFilePath)
+            R-->>L: module | resolution failure | load error
+            opt manifest entry, resolution failed
+                L->>R: FindWorkspacePackageDir → import entry file by path
+            end
+            Note over CF: importing the module fires @RegisterClass
+            L->>L: run StartupExport (if named and exported)
+        end
+        L-->>Host: DynamicPackagesReport
+    end
+```
+
+Two properties of that loop are deliberate and worth knowing:
+
+- **Filters run before the cache check.** An entry that is disabled or out of scope stays skipped
+  even when an earlier call in the same process loaded the package. The cache is not a bypass.
+- **Order is priority.** `@RegisterClass` uses load-order priority — the last registration for a key
+  wins — so discovery is arranged generic-to-specific (see next section).
+
+## Discovery sources and merge rules
+
+Three sources, always in this order:
+
+| # | Source | Comes from | `Source` tag | Why this position |
+|---|---|---|---|---|
+| 1 | Generated packages | `codeGeneration.packages.{entities,actions,graphqlResolvers}.name` (server tier) / `{entities,actions,angularForms}` (client tier) | `generated` | The host's own schema subclasses — the most generic layer |
+| 2 | Installed Open Apps | `dynamicPackages.server[]` / `dynamicPackages.client[]`, written by `mj app install` | `config` | Apps layered on the host |
+| 3 | The app you are standing in | `mj-app.json` next to the config (or `appManifestDir`): `packages.shared` then `packages.<tier>` | `manifest` | The most local definition overrides everything |
+
+```mermaid
+flowchart TD
+    G["1 · generated<br/>codeGeneration.packages"] --> C["2 · config<br/>dynamicPackages.&lt;tier&gt;[]"] --> M["3 · manifest<br/>mj-app.json packages.shared + packages.&lt;tier&gt;"]
+    M --> MG["mergeCandidates()"]
+    MG --> OUT["one candidate per PackageName<br/>+ duplicates → Skipped (duplicate)"]
+    style G fill:#eef,stroke:#88a
+    style C fill:#efe,stroke:#8a8
+    style M fill:#fee,stroke:#a88
+```
+
+`mergeCandidates` collapses entries that name the same package:
+
+- The **`config` entry is the operator's authority**. It carries `Enabled` (what `mj app disable`
+  writes) and the `Processes` / `ExcludeProcesses` scoping, so when an `mj-app.json` beside the
+  config names a package the config also names, the config entry decides whether and where it loads.
+- The **manifest's on-disk location is kept as the resolution fallback** (`WorkspaceHome`), so a
+  package the host cannot `require.resolve` still loads from the workspace.
+- Every later duplicate is returned separately and lands in `report.Skipped` with `Reason: 'duplicate'`.
+
+Manifest discovery reads `mj-app.json` from the config file's directory by default; pass
+`appManifestDir` to point elsewhere, or `discoverAppManifest: false` to skip it. `includeGeneratedPackages: false`
+skips source 1.
+
+## Process IDs
+
+Every host names itself with a lowercase, colon-separated ID. IDs are hierarchical: a pattern matches
+an ID when it equals the ID or names one of its ancestor **segments**.
+
+```mermaid
+flowchart TD
+    ANY["'*' (matches everything)"]
+    ANY --> MJAPI["mjapi"]
+    ANY --> MCP["mcp"]
+    ANY --> A2A["a2a"]
+    ANY --> IT["integration-tests"]
+    ANY --> CR["component-registry"]
+    ANY --> CLI["cli"]
+    CLI --> SYNC["cli:sync"]
+    SYNC --> SP["cli:sync:push"]
+    SYNC --> SPL["cli:sync:pull"]
+    CLI --> CG["cli:codegen"]
+    CLI --> APP["cli:app"]
+    APP --> AI["cli:app:install"]
+    CLI --> CAI["cli:ai"]
+    CAI --> CAIR["cli:ai:agents:run"]
+```
+
+| Pattern | Matches | Does not match |
+|---|---|---|
+| `cli` | `cli`, `cli:sync:push`, `cli:codegen` | `mjapi` |
+| `cli:sync` | `cli:sync`, `cli:sync:push` | `cli:syncother`, `cli:migrate` |
+| `cli:sync:push` | `cli:sync:push` only | `cli:sync:pull` |
+| `*` | everything | — |
+
+`CliProcessId('sync push')` and `CliProcessId('sync:push')` both build `cli:sync:push` from an oclif
+command ID. `NormalizeProcessId` trims, lowercases and collapses whitespace around the separators.
+`ProcessIdMatches`, `MatchesProcess` and `ResolveMostSpecific` are the three matching primitives, all
+exported for hosts that need to evaluate scoping themselves.
+
+## Scoping entries per process
+
+`dynamicPackages.server[]` stays the single source of truth that `mj app install` writes. Two optional,
+hand-authored fields scope an entry:
+
+```js
+dynamicPackages: {
+  server: [
+    // written by `mj app install` — no Processes = loads wherever the server tier loads
+    { PackageName: '@mj-biz-apps/orders-server', StartupExport: 'LoadBizAppsOrdersServer', AppName: 'mj-bizapps-orders', Enabled: true },
+    // only when the CLI runs any `mj sync` command
+    { PackageName: '@acme/demo-seed-server', StartupExport: 'LoadDemoSeed', Processes: ['cli:sync'] },
+    // everywhere except CodeGen
+    { PackageName: '@acme/audit-server', StartupExport: 'LoadAudit', ExcludeProcesses: ['cli:codegen'] },
+  ],
+  // optional per-process on/off switch; the most specific key wins
+  policy: { 'cli:codegen': 'none' },
+}
+```
+
+`Processes` is evaluated first (omitted or empty means everywhere the tier loads), then
+`ExcludeProcesses`. An entry that fails either lands in `report.Skipped` with `Reason: 'process-filter'`.
+
+Scoping only applies to processes that run the loader. The `mj` CLI's *light* commands — `mj migrate`
+(and `migrate create` / `migrate convert`), `mj install`, `mj clean`, `mj bundle`, `mj doctor`,
+`mj version`, `help` and the `usage` pages — skip the class-registration manifest for instant
+startup and never load app packages, so a `Processes: ['cli:migrate']` entry or a `cli:migrate`
+policy key has no effect: migrations never run app entity subclasses in any mode.
+
+## Mode: turning it off
+
+Mode is resolved once per call, highest precedence first:
+
+```mermaid
+flowchart LR
+    ENV["MJ_DYNAMIC_PACKAGES<br/>env var"] -->|unset or invalid| OPT["mode option<br/>(programmatic, e.g. a CLI flag)"]
+    OPT -->|unset| POL["dynamicPackages.policy<br/>most specific process key"]
+    POL -->|no match or invalid| DEF["'load'"]
+    ENV -->|"load / none"| DONE["resolved<br/>(ModeSource: env)"]
+    OPT -->|set| DONE2["resolved<br/>(ModeSource: option)"]
+    POL -->|"load / none"| DONE3["resolved<br/>(ModeSource: policy)"]
+```
+
+`MJ_DYNAMIC_PACKAGES=none` (also `off`, `skip`, `false`, `0`; the positive spellings `on`, `true`,
+`1`, `full` mean `load`) disables loading for a single invocation. The `mj` CLI exposes it as the
+global `--no-app-packages` flag. An invalid value never crashes a process: it is reported on the warn
+path (`Ignoring invalid …`) and precedence falls through to the next source.
+
+Mode `none` skips every dynamic package: the installed Open App packages *and* the host's own
+`codeGeneration.packages` (generated entities/actions/resolvers), so a host that relies on the latter
+loses its custom entity subclasses too for that run. MJ core's own server subclasses still register
+through the host's manifest, so a "raw" run is raw for app and host entities only — which is why the
+CLI flag is not called `--raw`.
+
+## Nested hosts
+
+Some MJ processes host other MJ processes: `mj ai agents run` imports `@memberjunction/ai-cli`, and
+`mj test …` imports `@memberjunction/testing-cli`, each of which has its own provider bootstrap that
+calls the loader. Without coordination the inner host would evaluate scoping under its standalone
+identity (`ai-cli`, `testing-cli`) a moment after the outer host evaluated it under `cli:ai:agents:run`,
+and an entry the operator excluded from `cli` would load anyway.
+
+```mermaid
+sequenceDiagram
+    participant U as operator
+    participant CLI as mj (prerun hook)
+    participant ENV as process.env
+    participant AI as @memberjunction/ai-cli bootstrap
+
+    U->>CLI: mj ai agents run …
+    CLI->>CLI: LoadDynamicPackages({ processId: 'cli:ai:agents:run' })
+    CLI->>ENV: MJ_DYNAMIC_PACKAGES_PROCESS = 'cli:ai:agents:run'
+    CLI->>AI: import + run command
+    AI->>ENV: EffectiveProcessId('ai-cli') → 'cli:ai:agents:run'
+    AI->>AI: LoadDynamicPackages({ processId: 'cli:ai:agents:run' })
+    Note over AI: same scoping decisions as the outer host;<br/>already-loaded packages come back cached, startup export not re-run
+```
+
+The outer host publishes its ID through `DYNAMIC_PACKAGES_PROCESS_ENV_VAR` (`MJ_DYNAMIC_PACKAGES_PROCESS`);
+the inner host reads it with `EffectiveProcessId(hostDefault)`, which falls back to `hostDefault` when
+the variable is unset (the standalone `mj-ai` case). The mode env var propagates the same way, since it
+is plain `process.env`.
+
+## Running inside an Open App repository
+
+When `mj-app.json` sits next to the config (or in `appManifestDir`), the loader also imports that
+app's `packages.shared` libraries and its `packages.server` / `packages.client` bootstrap packages,
+running each `startupExport`. Under pnpm's strict layout nothing at the repo root can
+`require.resolve` a workspace member, so the loader finds the package under `code.sourceDirectory`
+(default `packages/`) and imports it by path. A member that exists but has not been built yet (its
+entry file is missing) is reported as **not found**, with the file the build is expected to produce,
+on the info path — the expected state before the app's own build, not an error.
+
+Dependency apps are **not** walked from the manifest: installed ones are already in the host's
+`dynamicPackages`, and dev-linked ones ride the workspace's env-supplied entries.
+
+## Resolution: how a package is found
+
+A bare `import(name)` resolves from *this* package, which cannot declare packages whose names come from
+configuration. npm's hoisted layout lets that work by accident; pnpm's strict layout does not, because
+the packages are declared by (and linked into) the **host** application. `importFromHost` therefore
+tries the bare import first and then retries from each host anchor:
+
+```mermaid
+flowchart TD
+    S["import(name)"] -->|ok| OK["module"]
+    S -->|resolution failure| A1["createRequire(configFilePath).resolve(name)"]
+    A1 -->|ok| IMP["import(resolved file)"]
+    A1 -->|cannot see it| A2["createRequire(cwd/package.json).resolve(name)"]
+    A2 -->|ok| IMP
+    A2 -->|cannot see it| A3["createRequire(process.argv[1]).resolve(name)"]
+    A3 -->|ok| IMP
+    A3 -->|cannot see it| MF{"manifest entry with<br/>WorkspaceHome?"}
+    MF -->|yes| WS["FindWorkspacePackageDir → entry file<br/>(package.json exports / main / index.js)"]
+    WS -->|file exists| IMP
+    WS -->|not built| NF["NotFound (info: 'build it first')"]
+    MF -->|no| NF2["NotFound (info: run npm install?)"]
+    IMP -->|throws| FAIL["Failed (warn: the module's OWN error)"]
+    IMP -->|ok| OK
+```
+
+Resolution and evaluation are kept apart on purpose: an anchor that cannot *see* the package means
+"try the next anchor", but once an anchor resolves it, anything that fails while loading (a missing
+transitive dependency, a throw in top-level code) is the module's own problem and surfaces as-is —
+never masked by the original "cannot find package" error. `isOwnResolutionFailure` checks that the
+quoted subject of the error is *this* package name, so a missing transitive dependency is reported as
+`Failed`, not `NotFound`.
+
+`resolvePackageJsonFromHost` uses the same anchors to find a package's `package.json` (for hosts that
+read `memberjunction.serverExtensions` off it), tolerating an exports map that omits `./package.json`
+by resolving the main entry and walking up.
+
+## Loading twice in one process
+
+The loader remembers what it has loaded, on a `globalThis` symbol store rather than a module variable,
+so two physical copies of this package (two dist paths under pnpm, a bundled and an unbundled copy)
+still agree. A second call in the same process gets the cached module back in `Loaded` so it can still
+read `RESOLVER_PATHS` / `MJ_SERVER_EXTENSIONS`, but the `StartupExport` is not run again
+(`RanStartupExport: false`). ESM already caches the module; this only prevents the double hook.
+`ResetLoadedDynamicPackages()` clears the store — a test seam, not something a host calls.
+
+## The report
+
+`LoadDynamicPackages` never throws for a package problem (it throws only for a missing `processId`).
+Everything it decided is in the returned `DynamicPackagesReport`:
+
+| Field | Meaning |
+|---|---|
+| `ProcessId`, `Tier` | Normalized inputs |
+| `Mode`, `ModeSource` | What was resolved and from where (`env` / `option` / `policy` / `default`) |
+| `Loaded[]` | `{ Entry, Source, WorkspaceHome?, Module, RanStartupExport }` — `Module` is the namespace object hosts read conventions off |
+| `Skipped[]` | `{ …, Reason }` with `disabled`, `process-filter`, `mode-none`, or `duplicate` |
+| `NotFound[]` | No anchor could resolve it, or an unbuilt workspace member — logged on the info path |
+| `Failed[]` | `{ …, Error }` — resolved but threw while loading; logged on the warn path |
+
+A named `StartupExport` that the module does not export is a real misconfiguration (renamed export,
+stale config) and is warned about; the package still counts as `Loaded` with `RanStartupExport: false`.
+
+## Loggers
+
+| Logger | Use when |
+|---|---|
+| `ConsoleDynamicPackagesLogger` (default) | Plain console, the way MJAPI has always logged boot |
+| `StderrDynamicPackagesLogger` | Stdout is a machine-readable envelope (`--format=json`, `--output=json`) — progress and warnings go to stderr, verbose detail is dropped |
+| `SilentDynamicPackagesLogger` | The host reads the report and renders it itself |
+
+Any object with `info(message)` and `warn(message, error?)` (and optionally `verbose(message)`)
+satisfies `DynamicPackagesLogger`; the `mj` CLI passes one that routes through its own output.
+
+## Contract for `StartupExport`
+
+The loader runs before any database provider exists. A startup export registers classes and returns —
+it may be sync or async, and it must not touch a provider, exactly the contract MJAPI has always
+imposed. It runs at most once per process for a given package.
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `LoadDynamicPackages(options)` | The loader. Never throws for a package problem; returns a `DynamicPackagesReport`. |
+| `DiscoverMJConfig(searchFrom?, { searchStrategy })` | cosmiconfig discovery of the raw `mj.config.cjs` + its path. `searchStrategy` defaults to `'global'` (walk up to the home directory, what MJAPI / the CLI / CodeGen do); pass `'none'` when the host's own config loader only looks in the working directory, so the packages come from the same file the database settings came from. |
+| `mergeCandidates(candidates)` | The dedupe rule described above, exported for hosts that assemble their own candidate lists. |
+| `ResetLoadedDynamicPackages()` | Test seam: forget what has been loaded. |
+| `ConsoleDynamicPackagesLogger`, `StderrDynamicPackagesLogger`, `SilentDynamicPackagesLogger` | Ready-made loggers. |
+| `importFromHost`, `resolvePackageJsonFromHost`, `isResolutionFailure` | Host-anchored resolution (moved here from `@memberjunction/server-bootstrap`). |
+| `CliProcessId`, `NormalizeProcessId`, `ProcessIdMatches`, `MatchesProcess`, `ResolveMostSpecific`, `ANY_PROCESS` | Process-ID utilities. |
+| `EffectiveProcessId`, `DYNAMIC_PACKAGES_PROCESS_ENV_VAR` | Nested-host identity propagation. |
+| `ResolveDynamicPackagesMode`, `DYNAMIC_PACKAGES_MODE_ENV_VAR` | Mode precedence. |
+| `DiscoverGeneratedPackages`, `DiscoverAppManifestPackages`, `FindWorkspacePackageDir`, `ReadDynamicPackagesConfig`, `GENERATED_PACKAGE_TYPES_BY_TIER`, `APP_MANIFEST_FILE_NAME` | Discovery primitives. |
+
+Every option and report field is documented inline in `src/types.ts`.
+
+## Testing a host against it
+
+Unit tests for the loader itself live in `src/__tests__/` and cover discovery, matching, mode
+precedence, host-anchored resolution and the loader loop with stubbed imports.
+
+The proof that a package **not statically imported anywhere** really registers into the calling
+process's ClassFactory lives with the first host that needed it: `packages/MJCLI/src/__tests__/dynamic-packages.registration.test.ts`
+loads a committed miniature Open App (`fixtures/fixture-open-app`, an `mj-app.json` plus plain-ESM
+entities and server packages) through both the `mj-app.json` path and a `dynamicPackages.server[]`
+entry resolved through a throwaway host `node_modules`, then asserts on `MJGlobal.Instance.ClassFactory.GetRegistration(BaseEntity, …)`.
+Copy that shape to prove the same thing for a new host.

package/dist/discover.d.ts

@@ -0,0 +1,38 @@
+import type { DiscoveredDynamicPackage, DynamicPackageTier, DynamicPackagesConfig } from './types.js';
+/**
+ * `codeGeneration.packages.<type>.name` keys that make sense for each tier. `angularForms` is
+ * a browser library and must never be imported into a Node process; `graphqlResolvers` has no
+ * meaning in a browser bundle.
+ */
+export declare const GENERATED_PACKAGE_TYPES_BY_TIER: Record<DynamicPackageTier, readonly string[]>;
+/** The manifest file every Open App repository carries at its root. */
+export declare const APP_MANIFEST_FILE_NAME = "mj-app.json";
+/** Reads the `dynamicPackages` section off a raw config object, tolerating any shape. */
+export declare function ReadDynamicPackagesConfig(config: Record<string, unknown> | null | undefined): DynamicPackagesConfig;
+/** Entries for the host's own generated packages (`codeGeneration.packages`). */
+export declare function DiscoverGeneratedPackages(config: Record<string, unknown> | null | undefined, tier: DynamicPackageTier): DiscoveredDynamicPackage[];
+export interface AppManifestDiscovery {
+    /** Directory the manifest was read from. */
+    RepoDir: string;
+    /** `mj-app.json` `name`. */
+    AppName: string;
+    /** Directory under the repo that holds the app's workspace packages (`code.sourceDirectory`, default `packages`). */
+    SourceDirectory: string;
+    Entries: DiscoveredDynamicPackage[];
+}
+/**
+ * Reads `mj-app.json` from `repoDir` and returns the packages a process of `tier` should
+ * load: `shared` libraries first (entities/actions register on import), then the tier's own
+ * packages, with each `startupExport` carried through. Returns `null` when there is no
+ * manifest, and throws only when a manifest exists but is not valid JSON — a corrupt file is
+ * a problem the operator must see, an absent one is the common case.
+ */
+export declare function DiscoverAppManifestPackages(repoDir: string, tier: DynamicPackageTier): AppManifestDiscovery | null;
+/**
+ * Locates a workspace package by name under an app repo's source directory (one level deep,
+ * matching `code.sourceDirectory`), returning its directory. Used when the process runs inside
+ * the app's own repository: the package is a workspace member there, but under pnpm's strict
+ * layout nothing at the repo root can `require.resolve` it, so we find it on disk instead.
+ */
+export declare function FindWorkspacePackageDir(repoDir: string, sourceDirectory: string, packageName: string): string | null;
+//# sourceMappingURL=discover.d.ts.map

package/dist/discover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,wBAAwB,EAAuB,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3H;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,EAAE,MAAM,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAGzF,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD,yFAAyF;AACzF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,CAWnH;AAkDD,iFAAiF;AACjF,wBAAgB,yBAAyB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,IAAI,EAAE,kBAAkB,GACzB,wBAAwB,EAAE,CAc5B;AAcD,MAAM,WAAW,oBAAoB;IACjC,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,qHAAqH;IACrH,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,wBAAwB,EAAE,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,oBAAoB,GAAG,IAAI,CAwClH;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA0BpH"}