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

package/dist/loader.js

@@ -0,0 +1,404 @@
+/**
+ * The loader. One call per process, right after configuration is discovered and BEFORE any
+ * database provider is set up — so registration happens exactly where it does in MJAPI, and a
+ * `StartupExport` can rely on nothing but the ClassFactory (the contract MJAPI has always
+ * imposed: startup exports register classes, they do not touch a provider).
+ *
+ * Robustness contract, identical to the loader this replaces in @memberjunction/server-bootstrap:
+ * no-op when nothing is configured, per-package try/catch, a package that cannot be resolved is
+ * reported as not-found (expected before `npm install`, and for a workspace member found on disk
+ * whose entry file has not been built yet), a
+ * package that resolves but throws surfaces its own error on the warn path, and boot never
+ * crashes because of an app package.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { cosmiconfigSync } from 'cosmiconfig';
+import { DiscoverAppManifestPackages, DiscoverGeneratedPackages, FindWorkspacePackageDir, ReadDynamicPackagesConfig, } from './discover.js';
+import { importFromHost, isResolutionFailure } from './host-import.js';
+import { ResolveDynamicPackagesMode } from './mode.js';
+import { MatchesProcess, NormalizeProcessId } from './process-id.js';
+/** Default output channel: plain console, the way MJAPI has always logged its boot. */
+export const ConsoleDynamicPackagesLogger = {
+    info: (message) => console.log(message),
+    warn: (message, error) => (error === undefined ? console.warn(message) : console.warn(message, error)),
+    verbose: () => undefined,
+};
+/**
+ * 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 const StderrDynamicPackagesLogger = {
+    info: (message) => process.stderr.write(`${message}\n`),
+    warn: (message, error) => {
+        const detail = error === undefined ? '' : ` ${error instanceof Error ? error.message : String(error)}`;
+        process.stderr.write(`${message}${detail}\n`);
+    },
+    verbose: () => undefined,
+};
+/** A logger that says nothing — for hosts that read the report and render it themselves. */
+export const SilentDynamicPackagesLogger = {
+    info: () => undefined,
+    warn: () => undefined,
+    verbose: () => undefined,
+};
+/**
+ * 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 function DiscoverMJConfig(searchFrom, options) {
+    const explorer = cosmiconfigSync('mj', { searchStrategy: options?.searchStrategy ?? 'global' });
+    const result = explorer.search(searchFrom ?? process.cwd());
+    return {
+        config: (result?.config ?? {}),
+        configFilePath: result?.filepath,
+    };
+}
+/** Human-readable label for a discovered entry's origin, used in log lines. */
+function describeSource(pkg, tier) {
+    switch (pkg.Source) {
+        case 'generated':
+            return 'generated package';
+        case 'manifest':
+            return `Open App ${tier} package (from mj-app.json${pkg.Entry.AppName ? ` of ${pkg.Entry.AppName}` : ''})`;
+        default:
+            return `Open App ${tier} package`;
+    }
+}
+/**
+ * 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 async function LoadDynamicPackages(options) {
+    const processId = NormalizeProcessId(options.processId);
+    if (!processId) {
+        throw new Error('LoadDynamicPackages: processId is required (e.g. "mjapi", "cli:sync:push", "mcp").');
+    }
+    const tier = options.tier ?? 'server';
+    const log = options.log ?? ConsoleDynamicPackagesLogger;
+    const config = options.config ?? null;
+    const section = ReadDynamicPackagesConfig(config);
+    const resolved = ResolveDynamicPackagesMode({ processId, option: options.mode, policy: section.policy });
+    if (resolved.ignoredInvalid) {
+        log.warn(`[dynamic-packages] Ignoring invalid ${resolved.ignoredInvalid} (expected 'load' or 'none')`);
+    }
+    log.verbose?.(`[dynamic-packages] process '${processId}', tier '${tier}', mode '${resolved.mode}' (source: ${resolved.source})`);
+    const report = {
+        ProcessId: processId,
+        Tier: tier,
+        Mode: resolved.mode,
+        ModeSource: resolved.source,
+        Loaded: [],
+        Skipped: [],
+        NotFound: [],
+        Failed: [],
+    };
+    const { candidates, duplicates } = mergeCandidates(collectCandidates(options, tier, config, section, log));
+    for (const duplicate of duplicates) {
+        report.Skipped.push({ ...duplicate, Reason: 'duplicate' });
+    }
+    if (candidates.length === 0) {
+        return report;
+    }
+    if (resolved.mode === 'none') {
+        for (const candidate of candidates) {
+            report.Skipped.push({ ...candidate, Reason: 'mode-none' });
+        }
+        log.info(`[dynamic-packages] Skipping ${candidates.length} package(s): mode 'none' (source: ${resolved.source})`);
+        return report;
+    }
+    const alreadyLoaded = loadedInThisProcess();
+    let announcedGenerated = false;
+    let announcedApps = false;
+    for (const candidate of candidates) {
+        const { Entry: entry } = candidate;
+        // Filters first — an entry disabled or out of scope must stay skipped even when an
+        // earlier call in this process loaded the same package (the cache is not a bypass).
+        if (entry.Enabled === false) {
+            report.Skipped.push({ ...candidate, Reason: 'disabled' });
+            log.verbose?.(`[dynamic-packages] Skipping ${entry.PackageName}: disabled`);
+            continue;
+        }
+        if (!MatchesProcess(processId, entry)) {
+            report.Skipped.push({ ...candidate, Reason: 'process-filter' });
+            log.verbose?.(`[dynamic-packages] Skipping ${entry.PackageName}: not scoped to process '${processId}'`);
+            continue;
+        }
+        const cached = alreadyLoaded.get(entry.PackageName);
+        if (cached) {
+            // A second host in the same process (e.g. `mj-ai` driven by `mj`) still needs the
+            // module — to read RESOLVER_PATHS, MJ_SERVER_EXTENSIONS, … — but must not re-run the
+            // startup export. ESM caches the module anyway; this only prevents the double hook.
+            report.Loaded.push({ ...candidate, Module: cached, RanStartupExport: false });
+            log.verbose?.(`[dynamic-packages] ${entry.PackageName} already loaded in this process; startup export not re-run`);
+            continue;
+        }
+        // Section headers mirror the lines MJAPI has printed at boot for years.
+        if (candidate.Source === 'generated' && !announcedGenerated) {
+            log.info('Loading generated packages...');
+            announcedGenerated = true;
+        }
+        else if (candidate.Source !== 'generated' && !announcedApps) {
+            log.info(`Loading Open App ${tier} packages...`);
+            announcedApps = true;
+        }
+        await loadOne(candidate, options, report, log);
+    }
+    return report;
+}
+/**
+ * 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 function mergeCandidates(all) {
+    const byName = new Map();
+    const candidates = [];
+    const duplicates = [];
+    for (const candidate of all) {
+        const name = candidate.Entry.PackageName;
+        const existing = byName.get(name);
+        if (!existing) {
+            const first = { ...candidate };
+            byName.set(name, first);
+            candidates.push(first);
+            continue;
+        }
+        if (candidate.Source === 'config' && existing.Source !== 'config') {
+            existing.Entry = candidate.Entry;
+            existing.Source = 'config';
+        }
+        if (!existing.WorkspaceHome && candidate.WorkspaceHome) {
+            existing.WorkspaceHome = candidate.WorkspaceHome;
+        }
+        duplicates.push(candidate);
+    }
+    return { candidates, duplicates };
+}
+/** Orders the three discovery sources. Manifest discovery failures are the operator's to see, not fatal. */
+function collectCandidates(options, tier, config, section, log) {
+    const candidates = [];
+    if (options.includeGeneratedPackages !== false) {
+        candidates.push(...DiscoverGeneratedPackages(config, tier));
+    }
+    for (const entry of section[tier] ?? []) {
+        candidates.push({ Source: 'config', Entry: entry });
+    }
+    if (options.discoverAppManifest !== false) {
+        const repoDir = options.appManifestDir ?? (options.configFilePath ? path.dirname(options.configFilePath) : process.cwd());
+        try {
+            const manifest = DiscoverAppManifestPackages(repoDir, tier);
+            if (manifest) {
+                candidates.push(...manifest.Entries);
+            }
+        }
+        catch (error) {
+            log.warn(`[dynamic-packages] Could not read ${path.join(repoDir, 'mj-app.json')}:`, error);
+        }
+    }
+    return candidates;
+}
+async function loadOne(candidate, options, report, log) {
+    const { Entry: entry } = candidate;
+    const pkgName = entry.PackageName;
+    const label = describeSource(candidate, report.Tier);
+    const manifestHome = candidate.WorkspaceHome;
+    try {
+        let mod;
+        try {
+            mod = await importFromHost(pkgName, options.configFilePath);
+        }
+        catch (error) {
+            // A manifest-sourced package may be a workspace member nothing can require.resolve
+            // (pnpm strict layout, root without the package as a dependency). Find it on disk.
+            const onDisk = manifestHome && isOwnResolutionFailure(error, pkgName)
+                ? FindWorkspacePackageDir(manifestHome.RepoDir, manifestHome.SourceDirectory, pkgName)
+                : null;
+            if (!onDisk) {
+                throw error;
+            }
+            const entryFile = resolvePackageEntryFile(onDisk);
+            if (!existsSync(entryFile)) {
+                // The workspace member exists but has not been built (no dist yet) — the expected
+                // state before the app's own build, not an error. Report it as not-found, with the
+                // file the build is expected to produce, and never on the warn path.
+                report.NotFound.push(candidate);
+                log.info(`  ${label} ${pkgName} found at ${onDisk} but not built (missing ${path.relative(onDisk, entryFile)}) — build it first`);
+                return;
+            }
+            mod = await importPackageDir(entryFile);
+        }
+        const startup = entry.StartupExport ? mod[entry.StartupExport] : undefined;
+        let ranStartupExport = false;
+        if (typeof startup === 'function') {
+            await Promise.resolve(startup());
+            ranStartupExport = true;
+        }
+        else if (entry.StartupExport) {
+            // A named export that is missing is a real mis-configuration (renamed export, stale
+            // config) — say so instead of silently skipping it.
+            log.warn(`  ${label} ${pkgName} has no export named '${entry.StartupExport}' — startup hook not run`);
+        }
+        const loaded = { ...candidate, Module: mod, RanStartupExport: ranStartupExport };
+        report.Loaded.push(loaded);
+        loadedInThisProcess().set(pkgName, mod);
+        log.info(`  Loaded ${label}: ${pkgName}${ranStartupExport ? ` (ran ${entry.StartupExport})` : ''}`);
+    }
+    catch (error) {
+        if (isOwnResolutionFailure(error, pkgName)) {
+            report.NotFound.push(candidate);
+            log.info(candidate.Source === 'generated'
+                ? `  Generated package not found (may not exist yet): ${pkgName}`
+                : `  Open App ${report.Tier} package not found (run 'npm install'?): ${pkgName}`);
+        }
+        else {
+            report.Failed.push({ ...candidate, Error: error });
+            log.warn(`  Error loading ${label} ${pkgName}:`, error);
+        }
+    }
+}
+/**
+ * Modules already loaded by ANY copy of this module in the process, by package name. Kept on
+ * `globalThis` (not a module variable) because a duplicated module copy — two dist paths under
+ * pnpm, a bundled and an unbundled copy — must still agree on what has run.
+ */
+const LOADED_STORE_KEY = Symbol.for('memberjunction.dynamic-packages.loaded');
+function loadedInThisProcess() {
+    const store = globalThis;
+    let map = store[LOADED_STORE_KEY];
+    if (!map) {
+        map = new Map();
+        store[LOADED_STORE_KEY] = map;
+    }
+    return map;
+}
+/** Test seam: forget what has been loaded so a fresh process can be simulated. */
+export function ResetLoadedDynamicPackages() {
+    loadedInThisProcess().clear();
+}
+/**
+ * True only when THIS package is the error's quoted subject ("Cannot find package '<name>'").
+ * A missing TRANSITIVE dependency of a package that WAS found quotes the transitive name
+ * instead (this package's name still appears unquoted in the imported-from path, which is why
+ * a bare `includes(pkgName)` is not enough); that message is the true cause and must reach
+ * the operator via the warn path.
+ */
+function isOwnResolutionFailure(error, pkgName) {
+    const message = error instanceof Error ? error.message : String(error);
+    return isResolutionFailure(error) && message.includes(`'${pkgName}'`);
+}
+/**
+ * Resolves a package directory's entry file, honouring a string/"."/conditional `exports` map,
+ * else `main`, else `index.js`. Pure path work — whether the file exists is the caller's question.
+ */
+function resolvePackageEntryFile(dir) {
+    const pkgJson = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const entry = resolveExportsEntry(pkgJson.exports) ?? (typeof pkgJson.main === 'string' ? pkgJson.main : 'index.js');
+    return path.resolve(dir, entry);
+}
+/**
+ * Imports a package by its resolved entry file. (Dynamic import is justified here as runtime
+ * plugin discovery: the path comes from a manifest on disk, not from code.)
+ */
+async function importPackageDir(entryFile) {
+    return (await import(pathToFileURL(entryFile).href));
+}
+function resolveExportsEntry(exportsField) {
+    if (typeof exportsField === 'string') {
+        return exportsField;
+    }
+    if (!exportsField || typeof exportsField !== 'object') {
+        return null;
+    }
+    const rec = exportsField;
+    const root = '.' in rec ? rec['.'] : rec;
+    if (typeof root === 'string') {
+        return root;
+    }
+    if (root && typeof root === 'object') {
+        const cond = root;
+        for (const key of ['import', 'default', 'require', 'node']) {
+            if (typeof cond[key] === 'string') {
+                return cond[key];
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

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

package/dist/mode.d.ts

@@ -0,0 +1,27 @@
+import type { DynamicPackagesMode, DynamicPackagesModeSource } from './types.js';
+/**
+ * Environment variable for a per-invocation override, e.g.
+ * `MJ_DYNAMIC_PACKAGES=none npx mj sync push` to push with generic BaseEntity only.
+ */
+export declare const DYNAMIC_PACKAGES_MODE_ENV_VAR = "MJ_DYNAMIC_PACKAGES";
+export interface ResolvedDynamicPackagesMode {
+    mode: DynamicPackagesMode;
+    source: DynamicPackagesModeSource;
+    /** Set when an env/policy value was present but unparseable — the caller should surface it. */
+    ignoredInvalid?: string;
+}
+/**
+ * Highest wins:
+ * 1. `MJ_DYNAMIC_PACKAGES` env var
+ * 2. `option` — programmatic override from the entry point (e.g. a CLI flag)
+ * 3. `policy` — `dynamicPackages.policy` from mj.config.cjs, most specific process key
+ * 4. `'load'`
+ *
+ * An invalid env/policy value never crashes a process; it is reported and falls through.
+ */
+export declare function ResolveDynamicPackagesMode(args: {
+    processId: string;
+    option?: DynamicPackagesMode;
+    policy?: Record<string, string> | null;
+}): ResolvedDynamicPackagesMode;
+//# sourceMappingURL=mode.d.ts.map

package/dist/mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../src/mode.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEjF;;;GAGG;AACH,eAAO,MAAM,6BAA6B,wBAAwB,CAAC;AA0BnE,MAAM,WAAW,2BAA2B;IACxC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,yBAAyB,CAAC;IAClC,+FAA+F;IAC/F,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,mBAAmB,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC1C,GAAG,2BAA2B,CAoB9B"}

package/dist/mode.js

@@ -0,0 +1,60 @@
+/**
+ * Mode resolution — the same precedence shape as `ResolveStartupMode` in @memberjunction/core
+ * (env var > programmatic option > config > default), so an operator who already knows
+ * `MJ_STARTUP_MODE=task npx mj sync push` can reach for `MJ_DYNAMIC_PACKAGES=none` the same way.
+ */
+import { ResolveMostSpecific } from './process-id.js';
+/**
+ * Environment variable for a per-invocation override, e.g.
+ * `MJ_DYNAMIC_PACKAGES=none npx mj sync push` to push with generic BaseEntity only.
+ */
+export const DYNAMIC_PACKAGES_MODE_ENV_VAR = 'MJ_DYNAMIC_PACKAGES';
+const MODES = ['load', 'none'];
+/** Accepts the canonical values plus the obvious spellings people will try. */
+function parseMode(value) {
+    if (!value) {
+        return undefined;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (normalized === 'off' || normalized === 'skip' || normalized === 'false' || normalized === '0') {
+        return 'none';
+    }
+    if (normalized === 'on' || normalized === 'true' || normalized === '1' || normalized === 'full') {
+        return 'load';
+    }
+    return MODES.find((m) => m === normalized);
+}
+function readEnv() {
+    if (typeof process === 'undefined' || !process.env) {
+        return undefined;
+    }
+    return process.env[DYNAMIC_PACKAGES_MODE_ENV_VAR];
+}
+/**
+ * Highest wins:
+ * 1. `MJ_DYNAMIC_PACKAGES` env var
+ * 2. `option` — programmatic override from the entry point (e.g. a CLI flag)
+ * 3. `policy` — `dynamicPackages.policy` from mj.config.cjs, most specific process key
+ * 4. `'load'`
+ *
+ * An invalid env/policy value never crashes a process; it is reported and falls through.
+ */
+export function ResolveDynamicPackagesMode(args) {
+    const envRaw = readEnv();
+    const envMode = parseMode(envRaw);
+    if (envMode) {
+        return { mode: envMode, source: 'env' };
+    }
+    const ignoredInvalid = envRaw && !envMode ? `${DYNAMIC_PACKAGES_MODE_ENV_VAR}='${envRaw}'` : undefined;
+    if (args.option) {
+        return { mode: args.option, source: 'option', ignoredInvalid };
+    }
+    const policyRaw = ResolveMostSpecific(args.processId, args.policy);
+    const policyMode = parseMode(policyRaw);
+    if (policyMode) {
+        return { mode: policyMode, source: 'policy', ignoredInvalid };
+    }
+    const policyInvalid = policyRaw && !policyMode ? `dynamicPackages.policy value '${policyRaw}'` : undefined;
+    return { mode: 'load', source: 'default', ignoredInvalid: ignoredInvalid ?? policyInvalid };
+}
+//# sourceMappingURL=mode.js.map

package/dist/mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mode.js","sourceRoot":"","sources":["../src/mode.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD;;;GAGG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;AAEnE,MAAM,KAAK,GAAmC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE/D,+EAA+E;AAC/E,SAAS,SAAS,CAAC,KAAgC;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,MAAM,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9C,IAAI,UAAU,KAAK,KAAK,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,OAAO,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QAChG,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,KAAK,MAAM,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC9F,OAAO,MAAM,CAAC;IAClB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,UAAU,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,OAAO;IACZ,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;QACjD,OAAO,SAAS,CAAC;IACrB,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAC;AACtD,CAAC;AASD;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,IAI1C;IACG,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,OAAO,EAAE,CAAC;QACV,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,6BAA6B,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAEvG,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IACnE,CAAC;IAED,MAAM,SAAS,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACnE,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IACxC,IAAI,UAAU,EAAE,CAAC;QACb,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAClE,CAAC;IACD,MAAM,aAAa,GAAG,SAAS,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,iCAAiC,SAAS,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3G,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,IAAI,aAAa,EAAE,CAAC;AAChG,CAAC"}

package/dist/process-id.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Process identity and prefix matching.
+ *
+ * Process IDs are hierarchical, colon-separated, lowercase strings: `mjapi`, `cli`,
+ * `cli:sync`, `cli:sync:push`, `mcp`. A pattern matches an ID when it equals the ID or names
+ * one of its ancestor segments — `cli:sync` matches `cli:sync:push` but not `cli:syncother`
+ * or `cli:migrate`. This is what lets a config author scope a package to "all of the CLI",
+ * "just mj sync", or exactly one command with the same field.
+ */
+/** Wildcard pattern that matches every process. */
+export declare const ANY_PROCESS = "*";
+/** Lowercases, trims, and collapses whitespace around the colon separators. */
+export declare function NormalizeProcessId(value: string): string;
+/**
+ * Builds a CLI process ID from an oclif command ID. oclif reports IDs as either `sync:push`
+ * or `sync push` (with `topicSeparator: ' '`); both become `cli:sync:push`.
+ */
+export declare function CliProcessId(commandId: string | undefined | null): string;
+/** True when `pattern` equals `processId` or is an ancestor prefix of it (segment-aware). */
+export declare function ProcessIdMatches(processId: string, pattern: string): boolean;
+/**
+ * Evaluates an entry's `Processes` / `ExcludeProcesses` against a process ID.
+ * No `Processes` (or an empty list) means "everywhere"; `ExcludeProcesses` is applied after.
+ */
+export declare function MatchesProcess(processId: string, filter: {
+    Processes?: string[] | null;
+    ExcludeProcesses?: string[] | null;
+} | null | undefined): boolean;
+/**
+ * Picks the value of the most specific key in `map` that matches `processId`.
+ * `'cli:sync'` beats `'cli'` beats `'*'`. Returns `undefined` when nothing matches.
+ */
+export declare function ResolveMostSpecific<T>(processId: string, map: Record<string, T> | null | undefined): T | undefined;
+/**
+ * Environment variable through which an OUTER host tells nested hosts which process they are
+ * running inside. The `mj` CLI's prerun hook sets it to its own ID (`cli:ai:agents:run`) before
+ * the command imports `@memberjunction/ai-cli` or `@memberjunction/testing-cli`; those packages'
+ * provider bootstraps then evaluate `Processes` / `ExcludeProcesses` / `policy` under the SAME
+ * ID instead of their standalone `ai-cli` / `testing-cli` identity. Without it, an entry an
+ * operator excluded from `cli` would be loaded by the nested host a moment later.
+ */
+export declare const DYNAMIC_PACKAGES_PROCESS_ENV_VAR = "MJ_DYNAMIC_PACKAGES_PROCESS";
+/**
+ * The process ID a host should load under: the one an enclosing host published through
+ * {@link DYNAMIC_PACKAGES_PROCESS_ENV_VAR} when there is one, else the host's own default.
+ *
+ * @example
+ * ```ts
+ * // packages/AI/AICLI — `mj-ai` standalone loads as 'ai-cli'; under `mj ai …` it inherits 'cli:ai:…'
+ * await LoadDynamicPackages({ processId: EffectiveProcessId('ai-cli'), ... });
+ * ```
+ */
+export declare function EffectiveProcessId(hostDefault: string): string;
+//# sourceMappingURL=process-id.d.ts.map

package/dist/process-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-id.d.ts","sourceRoot":"","sources":["../src/process-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,mDAAmD;AACnD,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAGzE;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAU5E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC1B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC/F,OAAO,CAUT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAkBlH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAE9E;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAI9D"}