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

package/dist/discover.js

@@ -0,0 +1,178 @@
+/**
+ * Discovery — turns configuration into an ordered list of candidate entries, each tagged with
+ * where it came from. Order matters: the ClassFactory's load-order priority means a later
+ * registration wins, so the host's generated packages go first, then installed Open Apps
+ * (from `dynamicPackages`), then the app whose repository we are standing in (from
+ * `mj-app.json`), so the most local definition overrides the most generic one.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * `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 const GENERATED_PACKAGE_TYPES_BY_TIER = {
+    server: ['entities', 'actions', 'graphqlResolvers'],
+    client: ['entities', 'actions', 'angularForms'],
+};
+/** The manifest file every Open App repository carries at its root. */
+export const APP_MANIFEST_FILE_NAME = 'mj-app.json';
+/** Reads the `dynamicPackages` section off a raw config object, tolerating any shape. */
+export function ReadDynamicPackagesConfig(config) {
+    const raw = config?.dynamicPackages;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return {};
+    }
+    const section = raw;
+    return {
+        server: sanitizeEntries(section.server),
+        client: sanitizeEntries(section.client),
+        policy: sanitizePolicy(section.policy),
+    };
+}
+function sanitizeEntries(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const entries = [];
+    for (const item of raw) {
+        if (!item || typeof item !== 'object') {
+            continue;
+        }
+        const rec = item;
+        const name = typeof rec.PackageName === 'string' ? rec.PackageName.trim() : '';
+        if (!name) {
+            continue;
+        }
+        entries.push({
+            PackageName: name,
+            StartupExport: typeof rec.StartupExport === 'string' && rec.StartupExport.trim() ? rec.StartupExport.trim() : undefined,
+            AppName: typeof rec.AppName === 'string' ? rec.AppName : undefined,
+            Enabled: rec.Enabled === false ? false : true,
+            Processes: stringList(rec.Processes),
+            ExcludeProcesses: stringList(rec.ExcludeProcesses),
+        });
+    }
+    return entries;
+}
+function stringList(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    const list = raw.filter((v) => typeof v === 'string' && v.trim().length > 0);
+    return list.length > 0 ? list : undefined;
+}
+function sanitizePolicy(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const policy = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value === 'string') {
+            // Kept as-is (typed loosely); mode parsing decides validity and reports it.
+            policy[key] = value;
+        }
+    }
+    return Object.keys(policy).length > 0 ? policy : undefined;
+}
+/** Entries for the host's own generated packages (`codeGeneration.packages`). */
+export function DiscoverGeneratedPackages(config, tier) {
+    const codeGeneration = config?.codeGeneration;
+    const packages = codeGeneration?.packages;
+    if (!packages || typeof packages !== 'object') {
+        return [];
+    }
+    const found = [];
+    for (const type of GENERATED_PACKAGE_TYPES_BY_TIER[tier]) {
+        const name = packages[type]?.name;
+        if (typeof name === 'string' && name.trim().length > 0) {
+            found.push({ Source: 'generated', Entry: { PackageName: name.trim(), Enabled: true } });
+        }
+    }
+    return found;
+}
+/**
+ * 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 function DiscoverAppManifestPackages(repoDir, tier) {
+    const manifestPath = path.join(repoDir, APP_MANIFEST_FILE_NAME);
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Could not parse ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const appName = typeof manifest.name === 'string' ? manifest.name : path.basename(repoDir);
+    const sourceDirectory = typeof manifest.code?.sourceDirectory === 'string' && manifest.code.sourceDirectory.trim()
+        ? manifest.code.sourceDirectory.trim()
+        : 'packages';
+    const entries = [];
+    const push = (pkg) => {
+        const name = typeof pkg?.name === 'string' ? pkg.name.trim() : '';
+        if (!name) {
+            return;
+        }
+        entries.push({
+            Source: 'manifest',
+            WorkspaceHome: { RepoDir: repoDir, SourceDirectory: sourceDirectory },
+            Entry: {
+                PackageName: name,
+                StartupExport: typeof pkg.startupExport === 'string' && pkg.startupExport.trim() ? pkg.startupExport.trim() : undefined,
+                AppName: appName,
+                Enabled: true,
+            },
+        });
+    };
+    for (const pkg of manifest.packages?.shared ?? []) {
+        push(pkg);
+    }
+    for (const pkg of manifest.packages?.[tier] ?? []) {
+        push(pkg);
+    }
+    return { RepoDir: repoDir, AppName: appName, SourceDirectory: sourceDirectory, Entries: entries };
+}
+/**
+ * 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 function FindWorkspacePackageDir(repoDir, sourceDirectory, packageName) {
+    const root = path.resolve(repoDir, sourceDirectory);
+    if (!existsSync(root)) {
+        return null;
+    }
+    let children;
+    try {
+        children = readdirSync(root);
+    }
+    catch {
+        return null;
+    }
+    for (const child of children) {
+        const pkgJsonPath = path.join(root, child, 'package.json');
+        if (!existsSync(pkgJsonPath)) {
+            continue;
+        }
+        try {
+            const pkgJson = JSON.parse(readFileSync(pkgJsonPath, 'utf8'));
+            if (pkgJson.name === packageName) {
+                return path.join(root, child);
+            }
+        }
+        catch {
+            // unreadable package.json — not the one we want
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=discover.js.map

package/dist/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../src/discover.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAChE,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAkD;IAC1F,MAAM,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,kBAAkB,CAAC;IACnD,MAAM,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,cAAc,CAAC;CAClD,CAAC;AAEF,uEAAuE;AACvE,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEpD,yFAAyF;AACzF,MAAM,UAAU,yBAAyB,CAAC,MAAkD;IACxF,MAAM,GAAG,GAAG,MAAM,EAAE,eAAe,CAAC;IACpC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,EAAE,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,GAA8B,CAAC;IAC/C,OAAO;QACH,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;QACvC,MAAM,EAAE,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC;QACvC,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC;KACzC,CAAC;AACN,CAAC;AAED,SAAS,eAAe,CAAC,GAAY;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YACpC,SAAS;QACb,CAAC;QACD,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,SAAS;QACb,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACT,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;YACvH,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;YAClE,OAAO,EAAE,GAAG,CAAC,OAAO,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;YAC7C,SAAS,EAAE,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC;YACpC,gBAAgB,EAAE,UAAU,CAAC,GAAG,CAAC,gBAAgB,CAAC;SACrD,CAAC,CAAC;IACP,CAAC;IACD,OAAO,OAAO,CAAC;AACnB,CAAC;AAED,SAAS,UAAU,CAAC,GAAY;IAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC;AAED,SAAS,cAAc,CAAC,GAAY;IAChC,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,MAAM,GAAoC,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAA8B,CAAC,EAAE,CAAC;QACxE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,4EAA4E;YAC5E,MAAM,CAAC,GAAG,CAAC,GAAG,KAAwB,CAAC;QAC3C,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,yBAAyB,CACrC,MAAkD,EAClD,IAAwB;IAExB,MAAM,cAAc,GAAG,MAAM,EAAE,cAA+E,CAAC;IAC/G,MAAM,QAAQ,GAAG,cAAc,EAAE,QAAQ,CAAC;IAC1C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,EAAE,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAA+B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,+BAA+B,CAAC,IAAI,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5F,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC;AAwBD;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,OAAe,EAAE,IAAwB;IACjF,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,QAAqB,CAAC;IAC1B,IAAI,CAAC;QACD,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC,CAAgB,CAAC;IAC7E,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,YAAY,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACpI,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3F,MAAM,eAAe,GAAG,OAAO,QAAQ,CAAC,IAAI,EAAE,eAAe,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE;QAC9G,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE;QACtC,CAAC,CAAC,UAAU,CAAC;IAEjB,MAAM,OAAO,GAA+B,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,CAAC,GAAuB,EAAQ,EAAE;QAC3C,MAAM,IAAI,GAAG,OAAO,GAAG,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,OAAO;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,UAAU;YAClB,aAAa,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE;YACrE,KAAK,EAAE;gBACH,WAAW,EAAE,IAAI;gBACjB,aAAa,EAAE,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS;gBACvH,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,IAAI;aAChB;SACJ,CAAC,CAAC;IACP,CAAC,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;QAChD,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAChD,IAAI,CAAC,GAAG,CAAC,CAAC;IACd,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACtG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,OAAe,EAAE,eAAuB,EAAE,WAAmB;IACjG,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;IACpD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACD,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC;QAC3D,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YAC3B,SAAS;QACb,CAAC;QACD,IAAI,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAuB,CAAC;YACpF,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;gBAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAClC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACL,gDAAgD;QACpD,CAAC;IACL,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/host-import.d.ts

@@ -0,0 +1,43 @@
+/**
+ * True when the error is a module-RESOLUTION failure (the module could not be found or
+ * reached), as opposed to a module that was found but threw while loading — the latter is
+ * a real error that must surface. ESM raises ERR_MODULE_NOT_FOUND, CommonJS resolution
+ * (createRequire) raises MODULE_NOT_FOUND, and an exports-map mismatch raises
+ * ERR_PACKAGE_PATH_NOT_EXPORTED. Some ESM loader shims (ts-node's, notably — the loader
+ * MJAPI runs under) throw resolution failures as PLAIN Errors with no code at all, so
+ * when there is no code, recognize Node's own resolver message instead.
+ *
+ * ⚠ Under ts-node's shim the coded branch never fires (the shim strips custom error
+ * properties crossing the module-hooks thread), so the message branch is LOAD-BEARING
+ * there: if a future Node rewords its resolver messages, this predicate must be updated
+ * or the pnpm fallback silently stops working under ts-node hosts.
+ *
+ * Keep in sync with `IsModuleResolutionFailure` in @memberjunction/open-app-engine's
+ * `src/install/migration-runner.ts` — same heuristic, duplicated because the engine
+ * cannot depend on this package and cross-package re-exports are disallowed.
+ */
+export declare function isResolutionFailure(error: unknown): boolean;
+/**
+ * Resolves the on-disk `package.json` of a host-visible package so callers can
+ * introspect `memberjunction.serverExtensions` without relying on an exports map.
+ * Returns `null` when no host anchor can see the package.
+ */
+export declare function resolvePackageJsonFromHost(pkgName: string, configFilePath?: string): string | null;
+/**
+ * Imports a runtime-configured package from the HOST application's context.
+ *
+ * Resolution and evaluation are handled separately on the fallback path: an anchor that
+ * cannot SEE the package means "try the next anchor", but once an anchor resolves it,
+ * any failure from loading the module (a missing transitive dependency, a throw in its
+ * top-level code) is the module's own problem and is surfaced as-is — never masked by
+ * the original "cannot find package" error.
+ *
+ * Note on the resolver: `createRequire().resolve` runs under CommonJS conditions, so a
+ * package whose exports map declares ONLY an `"import"` condition cannot be resolved by
+ * the fallback (surfaced with an actionable error). On a dual CJS/ESM package it selects
+ * the CJS entry, so `import()` of that file would load a second physical module instance
+ * alongside any ESM copy already in the process — fine for MJ-shaped single-condition
+ * packages, but keep it in mind before widening this mechanism.
+ */
+export declare function importFromHost(pkgName: string, configFilePath?: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=host-import.d.ts.map

package/dist/host-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-import.d.ts","sourceRoot":"","sources":["../src/host-import.ts"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM3D;AAuCD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAyBlG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyC/G"}

package/dist/host-import.js

@@ -0,0 +1,170 @@
+/**
+ * Host-anchored dynamic import for runtime-configured packages.
+ *
+ * A bare `import(pkgName)` resolves from THIS package (dynamic-packages), which cannot
+ * declare packages whose names are only known at runtime — mj.config.cjs supplies them.
+ * npm's hoisted node_modules let that bare import resolve by accident; pnpm's strict
+ * per-package layout does not, because the packages are declared by (and linked into) the
+ * HOST application, e.g. MJAPI. `importFromHost` tries the bare import first (identical
+ * behavior to before on npm layouts) and, when the package cannot be resolved, retries
+ * from each host anchor — the working directory, the mj.config.cjs that named the
+ * package, and the process entrypoint. (Dynamic import is justified here as runtime
+ * plugin discovery: the names come from configuration, not code.)
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import path from 'node:path';
+/**
+ * True when the error is a module-RESOLUTION failure (the module could not be found or
+ * reached), as opposed to a module that was found but threw while loading — the latter is
+ * a real error that must surface. ESM raises ERR_MODULE_NOT_FOUND, CommonJS resolution
+ * (createRequire) raises MODULE_NOT_FOUND, and an exports-map mismatch raises
+ * ERR_PACKAGE_PATH_NOT_EXPORTED. Some ESM loader shims (ts-node's, notably — the loader
+ * MJAPI runs under) throw resolution failures as PLAIN Errors with no code at all, so
+ * when there is no code, recognize Node's own resolver message instead.
+ *
+ * ⚠ Under ts-node's shim the coded branch never fires (the shim strips custom error
+ * properties crossing the module-hooks thread), so the message branch is LOAD-BEARING
+ * there: if a future Node rewords its resolver messages, this predicate must be updated
+ * or the pnpm fallback silently stops working under ts-node hosts.
+ *
+ * Keep in sync with `IsModuleResolutionFailure` in @memberjunction/open-app-engine's
+ * `src/install/migration-runner.ts` — same heuristic, duplicated because the engine
+ * cannot depend on this package and cross-package re-exports are disallowed.
+ */
+export function isResolutionFailure(error) {
+    const { code, message } = error ?? {};
+    if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND' || code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+        return true;
+    }
+    return code === undefined && typeof message === 'string' && /^Cannot find (package|module) /.test(message);
+}
+/**
+ * Host anchors used to resolve runtime-configured packages. The mj.config.cjs that
+ * named the package is first — cwd can be a different checkout.
+ */
+function hostAnchors(configFilePath) {
+    return [
+        configFilePath,
+        path.join(process.cwd(), 'package.json'),
+        process.argv[1],
+    ].filter((anchor) => typeof anchor === 'string' && anchor.length > 0);
+}
+/**
+ * Walks up from a resolved file looking for a `package.json` whose `name` matches.
+ * Used when the package's exports map does not expose `./package.json`.
+ */
+function findPackageJsonWithName(fromFile, pkgName) {
+    let dir = path.dirname(fromFile);
+    for (let i = 0; i < 8; i++) {
+        const candidate = path.join(dir, 'package.json');
+        try {
+            const json = JSON.parse(readFileSync(candidate, 'utf8'));
+            if (json.name === pkgName) {
+                return candidate;
+            }
+        }
+        catch {
+            // missing or unreadable — keep walking
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Resolves the on-disk `package.json` of a host-visible package so callers can
+ * introspect `memberjunction.serverExtensions` without relying on an exports map.
+ * Returns `null` when no host anchor can see the package.
+ */
+export function resolvePackageJsonFromHost(pkgName, configFilePath) {
+    for (const anchor of hostAnchors(configFilePath)) {
+        const req = createRequire(anchor);
+        try {
+            return req.resolve(`${pkgName}/package.json`);
+        }
+        catch (resolveError) {
+            if (resolveError?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+                // exports map omits package.json — resolve the main entry and walk up.
+            }
+            else if (!isResolutionFailure(resolveError)) {
+                throw resolveError;
+            }
+        }
+        try {
+            const main = req.resolve(pkgName);
+            const found = findPackageJsonWithName(main, pkgName);
+            if (found) {
+                return found;
+            }
+        }
+        catch (mainError) {
+            if (!isResolutionFailure(mainError) && mainError?.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+                throw mainError;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Imports a runtime-configured package from the HOST application's context.
+ *
+ * Resolution and evaluation are handled separately on the fallback path: an anchor that
+ * cannot SEE the package means "try the next anchor", but once an anchor resolves it,
+ * any failure from loading the module (a missing transitive dependency, a throw in its
+ * top-level code) is the module's own problem and is surfaced as-is — never masked by
+ * the original "cannot find package" error.
+ *
+ * Note on the resolver: `createRequire().resolve` runs under CommonJS conditions, so a
+ * package whose exports map declares ONLY an `"import"` condition cannot be resolved by
+ * the fallback (surfaced with an actionable error). On a dual CJS/ESM package it selects
+ * the CJS entry, so `import()` of that file would load a second physical module instance
+ * alongside any ESM copy already in the process — fine for MJ-shaped single-condition
+ * packages, but keep it in mind before widening this mechanism.
+ */
+export async function importFromHost(pkgName, configFilePath) {
+    try {
+        return (await import(pkgName));
+    }
+    catch (error) {
+        if (!isResolutionFailure(error)) {
+            throw error;
+        }
+        // Anchor priority: the mj.config.cjs that NAMED the package is the authoritative host,
+        // so it is consulted first — cwd can be a different checkout entirely (an operator
+        // launching instance A's server from instance B's directory would otherwise silently
+        // load B's copy). cwd and the process entrypoint are fallbacks for hosts whose config
+        // lives outside the tree that carries the packages (e.g. a workspace-root config with
+        // the packages linked into the app directory).
+        const anchors = hostAnchors(configFilePath);
+        let sawExportsMapMismatch = false;
+        for (const anchor of anchors) {
+            let resolved;
+            try {
+                resolved = createRequire(anchor).resolve(pkgName);
+            }
+            catch (resolveError) {
+                if (resolveError?.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED') {
+                    sawExportsMapMismatch = true;
+                    continue;
+                }
+                if (!isResolutionFailure(resolveError)) {
+                    throw resolveError;
+                }
+                continue; // this anchor can't see the package — try the next
+            }
+            // Resolved. Anything that fails from here is the module's own problem — surface it.
+            return (await import(pathToFileURL(resolved).href));
+        }
+        if (sawExportsMapMismatch) {
+            throw new Error(`Package '${pkgName}' is reachable from the host, but its exports map has no CJS-resolvable condition ` +
+                `(add a "default" or "require" condition to its package.json exports), so the host-anchored fallback cannot load it.`, { cause: error });
+        }
+        throw error; // no anchor resolved it — surface the original bare-import failure
+    }
+}
+//# sourceMappingURL=host-import.js.map

package/dist/host-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-import.js","sourceRoot":"","sources":["../src/host-import.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module @memberjunction/dynamic-packages
+ *
+ * Process-agnostic loader for packages whose names are only known at runtime: Open App server
+ * and client packages recorded in `mj.config.cjs` `dynamicPackages.*[]` by `mj app install`,
+ * a host's generated packages under `codeGeneration.packages`, and the packages of the Open App
+ * whose repository a process is standing in (`mj-app.json`).
+ *
+ * MJAPI loads these at boot so the ClassFactory hands back an app's entity/action/provider
+ * subclasses. 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 the same behaviour,
+ * and this package is where that behaviour lives so each host is one call:
+ *
+ * ```ts
+ * import { LoadDynamicPackages, DiscoverMJConfig } from '@memberjunction/dynamic-packages';
+ *
+ * const { config, configFilePath } = DiscoverMJConfig();
+ * await LoadDynamicPackages({ processId: 'mcp', config, configFilePath });
+ * ```
+ *
+ * Entries can be scoped per process with `Processes` / `ExcludeProcesses`, whole processes can
+ * be switched off with `dynamicPackages.policy`, and `MJ_DYNAMIC_PACKAGES=none` (or a host
+ * flag that sets it) disables loading for one invocation.
+ */
+export type { DiscoveredDynamicPackage, DynamicPackageEntry, DynamicPackageSkipReason, DynamicPackageSource, DynamicPackageTier, DynamicPackagesConfig, DynamicPackagesLogger, DynamicPackagesMode, DynamicPackagesModeSource, DynamicPackagesReport, FailedDynamicPackage, LoadDynamicPackagesOptions, LoadedDynamicPackage, SkippedDynamicPackage, WorkspaceHome, } from './types.js';
+export { importFromHost, isResolutionFailure, resolvePackageJsonFromHost } from './host-import.js';
+export { ANY_PROCESS, CliProcessId, DYNAMIC_PACKAGES_PROCESS_ENV_VAR, EffectiveProcessId, MatchesProcess, NormalizeProcessId, ProcessIdMatches, ResolveMostSpecific, } from './process-id.js';
+export { DYNAMIC_PACKAGES_MODE_ENV_VAR, ResolveDynamicPackagesMode } from './mode.js';
+export type { ResolvedDynamicPackagesMode } from './mode.js';
+export { APP_MANIFEST_FILE_NAME, DiscoverAppManifestPackages, DiscoverGeneratedPackages, FindWorkspacePackageDir, GENERATED_PACKAGE_TYPES_BY_TIER, ReadDynamicPackagesConfig, } from './discover.js';
+export type { AppManifestDiscovery } from './discover.js';
+export type { MJConfigSearchStrategy } from './loader.js';
+export { ConsoleDynamicPackagesLogger, DiscoverMJConfig, LoadDynamicPackages, mergeCandidates, ResetLoadedDynamicPackages, SilentDynamicPackagesLogger, StderrDynamicPackagesLogger, } from './loader.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,YAAY,EACR,wBAAwB,EACxB,mBAAmB,EACnB,wBAAwB,EACxB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,oBAAoB,EACpB,qBAAqB,EACrB,aAAa,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnG,OAAO,EACH,WAAW,EACX,YAAY,EACZ,gCAAgC,EAChC,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AACtF,YAAY,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EACH,sBAAsB,EACtB,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,GAC5B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EACH,4BAA4B,EAC5B,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,GAC9B,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { importFromHost, isResolutionFailure, resolvePackageJsonFromHost } from './host-import.js';
+export { ANY_PROCESS, CliProcessId, DYNAMIC_PACKAGES_PROCESS_ENV_VAR, EffectiveProcessId, MatchesProcess, NormalizeProcessId, ProcessIdMatches, ResolveMostSpecific, } from './process-id.js';
+export { DYNAMIC_PACKAGES_MODE_ENV_VAR, ResolveDynamicPackagesMode } from './mode.js';
+export { APP_MANIFEST_FILE_NAME, DiscoverAppManifestPackages, DiscoverGeneratedPackages, FindWorkspacePackageDir, GENERATED_PACKAGE_TYPES_BY_TIER, ReadDynamicPackagesConfig, } from './discover.js';
+export { ConsoleDynamicPackagesLogger, DiscoverMJConfig, LoadDynamicPackages, mergeCandidates, ResetLoadedDynamicPackages, SilentDynamicPackagesLogger, StderrDynamicPackagesLogger, } from './loader.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnG,OAAO,EACH,WAAW,EACX,YAAY,EACZ,gCAAgC,EAChC,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAEtF,OAAO,EACH,sBAAsB,EACtB,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,EACvB,+BAA+B,EAC/B,yBAAyB,GAC5B,MAAM,eAAe,CAAC;AAGvB,OAAO,EACH,4BAA4B,EAC5B,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,GAC9B,MAAM,aAAa,CAAC"}

package/dist/loader.d.ts

@@ -0,0 +1,114 @@
+import type { DiscoveredDynamicPackage, DynamicPackagesLogger, DynamicPackagesReport, LoadDynamicPackagesOptions } from './types.js';
+/** Default output channel: plain console, the way MJAPI has always logged its boot. */
+export declare const ConsoleDynamicPackagesLogger: DynamicPackagesLogger;
+/**
+ * A logger that keeps stdout clean: progress and warnings go to stderr, verbose detail is dropped.
+ * For CLI hosts whose stdout is a machine-readable envelope (`--format=json`, `--output=json`) —
+ * the default console logger would print "Loading Open App server packages..." ahead of the JSON.
+ */
+export declare const StderrDynamicPackagesLogger: DynamicPackagesLogger;
+/** A logger that says nothing — for hosts that read the report and render it themselves. */
+export declare const SilentDynamicPackagesLogger: DynamicPackagesLogger;
+/** cosmiconfig search strategies accepted by {@link DiscoverMJConfig}. */
+export type MJConfigSearchStrategy = 'none' | 'project' | 'global';
+/**
+ * Discovers `mj.config.cjs` with cosmiconfig (module name `mj`) and returns the RAW object plus its
+ * path. Hosts whose own config loader Zod-strips `dynamicPackages` use this to hand the loader an
+ * unstripped view.
+ *
+ * @param searchFrom - Directory to start from. Defaults to `process.cwd()`.
+ * @param options.searchStrategy - cosmiconfig's search strategy. Defaults to `'global'` (walk up
+ *   to the home directory — what MJAPI, the `mj` CLI and CodeGen do). A host whose own config
+ *   loader only looks in the working directory should pass `'none'` so the packages it loads come
+ *   from the same file its database settings came from.
+ *
+ * @example
+ * ```ts
+ * const { config, configFilePath } = DiscoverMJConfig();
+ * await LoadDynamicPackages({ processId: 'mcp', config, configFilePath });
+ * ```
+ */
+export declare function DiscoverMJConfig(searchFrom?: string, options?: {
+    searchStrategy?: MJConfigSearchStrategy;
+}): {
+    config: Record<string, unknown>;
+    configFilePath?: string;
+};
+/**
+ * Loads every dynamic package that applies to `options.processId` and returns a report of what
+ * happened to each entry. This is the one call a host makes; everything else in the package is a
+ * primitive it composes.
+ *
+ * @remarks
+ * **Order of operations.** Mode is resolved first (`MJ_DYNAMIC_PACKAGES` env var → `options.mode`
+ * → `dynamicPackages.policy` → `'load'`). Candidates are then discovered generic-to-specific —
+ * the host's `codeGeneration.packages`, then `dynamicPackages.<tier>[]`, then the `mj-app.json`
+ * beside the config — and merged by package name ({@link mergeCandidates}). Under mode `'none'`
+ * every candidate is reported as skipped and nothing is imported. Otherwise each candidate is
+ * filtered (`Enabled === false`, then `Processes` / `ExcludeProcesses` via {@link MatchesProcess}),
+ * served from the per-process cache when an earlier call already loaded it (module returned,
+ * startup export **not** re-run), or imported through {@link importFromHost} with an on-disk
+ * workspace fallback for manifest entries.
+ *
+ * **Why order matters.** `@RegisterClass` resolves by load-order priority — the last registration
+ * for a key wins — so importing generic-to-specific is what makes an Open App's server subclass
+ * beat its generated one, and the app you are standing in beat an installed copy.
+ *
+ * **When to call it.** After the host's class-registration manifest has been imported (so app
+ * registrations land last) and before any database provider exists (a `StartupExport` may rely on
+ * nothing but the ClassFactory).
+ *
+ * **Failure model.** Throws only when `processId` is missing. A package that no anchor can resolve
+ * is `NotFound` (expected before `npm install`, or for an unbuilt workspace member); one that
+ * resolves but throws while loading is `Failed` with its own error, logged on the warn path and
+ * never masked by a resolution message. Boot never crashes because of an app package.
+ *
+ * @param options - Process identity, the raw config and its path, tier, discovery switches, a
+ *   programmatic mode override, and the logger. See {@link LoadDynamicPackagesOptions}.
+ * @returns The {@link DynamicPackagesReport}: `Loaded`, `Skipped` (with a reason), `NotFound`,
+ *   `Failed`, plus the resolved mode and where it came from.
+ *
+ * @example Minimal host
+ * ```ts
+ * const { config, configFilePath } = DiscoverMJConfig();
+ * const report = await LoadDynamicPackages({ processId: 'mcp', config, configFilePath });
+ * for (const failed of report.Failed) {
+ *     console.error(`app package ${failed.Entry.PackageName} failed to load`, failed.Error);
+ * }
+ * ```
+ *
+ * @example Reading a convention off a loaded module (what MJAPI does for RESOLVER_PATHS)
+ * ```ts
+ * const resolverPaths = report.Loaded.flatMap((l) => {
+ *     const paths = l.Module.RESOLVER_PATHS;
+ *     return Array.isArray(paths) ? (paths as string[]) : [];
+ * });
+ * ```
+ *
+ * @example A nested host that inherits the outer process identity
+ * ```ts
+ * await LoadDynamicPackages({
+ *     processId: EffectiveProcessId('ai-cli'), // 'cli:ai:agents:run' when run under `mj ai …`
+ *     config, configFilePath,
+ *     log: StderrDynamicPackagesLogger,      // stdout may be a JSON envelope
+ * });
+ * ```
+ */
+export declare function LoadDynamicPackages(options: LoadDynamicPackagesOptions): Promise<DynamicPackagesReport>;
+/**
+ * Collapses candidates that name the same package into one, in discovery order.
+ *
+ * The `mj.config.cjs` entry is the operator's authority for a package: it carries `Enabled`
+ * (what `mj app disable` writes) and the process 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 — but the manifest's on-disk location is kept as the resolution fallback, so a package
+ * the host cannot `require.resolve` still loads from the workspace. Every later duplicate is
+ * returned separately so the report can list it as skipped.
+ */
+export declare function mergeCandidates(all: DiscoveredDynamicPackage[]): {
+    candidates: DiscoveredDynamicPackage[];
+    duplicates: DiscoveredDynamicPackage[];
+};
+/** Test seam: forget what has been loaded so a fresh process can be simulated. */
+export declare function ResetLoadedDynamicPackages(): void;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACR,wBAAwB,EAExB,qBAAqB,EACrB,qBAAqB,EACrB,0BAA0B,EAE7B,MAAM,YAAY,CAAC;AAEpB,uFAAuF;AACvF,eAAO,MAAM,4BAA4B,EAAE,qBAI1C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,qBAOzC,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,2BAA2B,EAAE,qBAIzC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEnE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC5B,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,cAAc,CAAC,EAAE,sBAAsB,CAAA;CAAE,GACtD;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAO9D;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAkF7G;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,wBAAwB,EAAE,GAAG;IAC9D,UAAU,EAAE,wBAAwB,EAAE,CAAC;IACvC,UAAU,EAAE,wBAAwB,EAAE,CAAC;CAC1C,CAuBA;AAiHD,kFAAkF;AAClF,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}