d365fo-mcp 1.11.0 → 1.13.0

package/dist/bridge/bridgeAdapter.js

@@ -27,6 +27,7 @@ import { xppMethodSourceForXml } from '../utils/xppFormat.js';
 import { ensureXppDocComment, ensureBlankLineBeforeClosingBrace } from '../utils/xppDocGen.js';
 import { parseXppDeclaration, parseXppClassHeader } from '../metadata/xppDeclaration.js';
 import { rankCustomFirst, isExactNameMatch } from '../utils/exactMatchRanking.js';
+import { COMPACT_METHODS_HINT, fullBodyHint } from '../utils/methodBodyHint.js';
 import { pageFields, fieldsHeading, fieldsFooter, createControlBudget, chargeControl, chargeSkippedSubtree, controlsFooter, } from '../utils/payloadBudget.js';
 // TABLE
 const TABLE_METHOD_PAGE_SIZE = 25;
@@ -215,13 +216,35 @@ function formatClass(cls, compact, methodOffset) {
             out += `### ${m.name}\n\n`;
             if (m.source) {
                 const preview = m.source.substring(0, 500);
-                out += `\`\`\`xpp\n${preview}${m.source.length > 500 ? '\n// ... (use get_method(include="source") for full body)' : ''}\n\`\`\`\n\n`;
+                // Same call syntax as COMPACT_METHODS_HINT below — two different ways to
+                // ask for one method body, fifteen lines apart, is the inconsistency
+                // this hint exists to remove.
+                out += `\`\`\`xpp\n${preview}${m.source.length > 500 ? `\n// ... (${fullBodyHint(m.name)})` : ''}\n\`\`\`\n\n`;
             }
         }
     }
     if (hasMore) {
         out += `> ⚠️ **${total - methodOffset - CLASS_METHOD_PAGE_SIZE} more methods.** Call again with \`methodOffset: ${methodOffset + CLASS_METHOD_PAGE_SIZE}\`.\n\n`;
     }
+    // compact=true is the default, and this list is the only place a caller who
+    // didn't read the tool schema learns that bodies exist but were withheld —
+    // the DB-only fallback (classInfo.ts buildDbOnlyResponse) already says this;
+    // the bridge path (the primary, "always available on VM" path) silently gave
+    // signatures with no pointer to the escape hatch, which read as "no source
+    // available for this class" when it was really "not requested".
+    //
+    // Gated on the RENDERED page carrying source, not on `total`. Bridge method
+    // source is Safe(() => method.Source) and BridgeMethodInfo.source is
+    // optional, so a class can come back with none: the compact:false branch
+    // above then prints `### name` and no code block at all (`if (m.source)`),
+    // which is strictly LESS than the signature line compact just gave — a round
+    // trip spent to lose information, on exactly the classes where the caller was
+    // already unsure whether source existed. The same guard covers an out-of-range
+    // methodOffset, where `visible` is empty and there is no signature on the page
+    // for "signatures only" to be describing.
+    if (compact && visible.some(m => m.source)) {
+        out += `${COMPACT_METHODS_HINT}\n\n`;
+    }
     return out;
 }
 // METHOD SOURCE
@@ -1117,8 +1140,20 @@ const BRIDGE_MODIFY_OPS = new Set([
     'modify-property',
     'add-enum-value', 'modify-enum-value', 'remove-enum-value',
     'add-control', 'add-data-source',
+    // Removal of a control, and of a privilege's entry point, have no C# op either
+    // (MetadataWriteService exposes no RemoveControl, and security objects have no
+    // bridge write path at all) — both are served by a direct-XML writer and still
+    // pass through this gate.
+    'remove-control', 'remove-entry-point',
+    // AxIgnoreDiagnosticList is not an AOT object at all — MetadataWriteService has
+    // no concept of it — so this is XML-only for the same structural reason as the
+    // two above.
+    'remove-diagnostic-suppression', 'add-diagnostic-suppression',
     'add-display-method', 'add-table-method',
     'add-field-modification', 'add-menu-item-to-menu',
+    // No C# op exists for query ranges on entities — served entirely by a
+    // direct-XML writer (data-entity is already in BRIDGE_MODIFY_TYPES).
+    'add-query-range', 'remove-query-range',
 ]);
 /**
  * Supported object types for bridge-based modification.
@@ -1133,6 +1168,25 @@ const BRIDGE_MODIFY_TYPES = new Set([
     'menu-item-action', 'menu-item-display', 'menu-item-output',
     'menu',
 ]);
+/**
+ * Operation → the object types it may target that BRIDGE_MODIFY_TYPES does not
+ * cover, because a direct-XML writer serves the pair and the bridge never will.
+ *
+ * This gate is what EVERY modify operation clears before dispatch, whether or not
+ * a C# op backs it, so an XML-only writer for an XML-only type has nowhere else to
+ * be admitted. The pairing is per-operation rather than per-type on purpose:
+ * dropping 'security-privilege' into BRIDGE_MODIFY_TYPES would also claim
+ * add-method, replace-code and modify-property work on a privilege, which they do
+ * not — the bridge has no write path for security objects at all (the same reason
+ * they are absent from BRIDGE_CREATE_TYPES: a generic
+ * Dictionary<string,string> cannot carry <EntryPoints>). The caller would then get
+ * a bridge resolution failure instead of "not supported for this object type".
+ */
+const XML_ONLY_MODIFY_PAIRS = {
+    'remove-entry-point': new Set(['security-privilege']),
+    'remove-diagnostic-suppression': new Set(['ignore-diagnostic-list']),
+    'add-diagnostic-suppression': new Set(['ignore-diagnostic-list']),
+};
 /**
  * Names the properties the bridge could not write, for appending to a success message.
  *
@@ -1157,7 +1211,11 @@ export function canBridgeCreate(objectType) {
  * Checks if bridge can handle this modify operation.
  */
 export function canBridgeModify(objectType, operation) {
-    return BRIDGE_MODIFY_TYPES.has(objectType.toLowerCase()) && BRIDGE_MODIFY_OPS.has(operation.toLowerCase());
+    const type = objectType.toLowerCase();
+    const op = operation.toLowerCase();
+    if (!BRIDGE_MODIFY_OPS.has(op))
+        return false;
+    return BRIDGE_MODIFY_TYPES.has(type) || (XML_ONLY_MODIFY_PAIRS[op]?.has(type) ?? false);
 }
 /**
  * Give a create's X++ the same doc comments and indentation the XML fallback gives it.

package/dist/cli/commands/bpCatalog.d.ts

@@ -0,0 +1,25 @@
+import { commandExists, runExe } from '../exec.js';
+import { Target } from '../target.js';
+/** Injectable for tests — real implementations by default. */
+export interface BpCatalogDeps {
+    commandExists: typeof commandExists;
+    runExe: typeof runExe;
+}
+/**
+ * Regenerate this target's BP-moniker catalog when its resolved D365FO
+ * version has moved since the catalog file was last stamped (including
+ * "never generated" — covers first-time instance creation). A no-op on
+ * every other rebuild. Never throws and never fails the caller's reindex —
+ * a missing/stale BP catalog degrades one knowledge tool, not the server.
+ *
+ * "Never throws" is enforced here rather than left to the callee getting every
+ * path right. rebuildIndex() awaits this as its last step, unwrapped, *after*
+ * the multi-minute extract and database build have already succeeded and
+ * logged "Index rebuilt" — so anything escaping would turn a finished rebuild
+ * into a crashed command. And plenty can escape: runExe rejects on the child
+ * process's own 'error' event (commandExists only rules out ENOENT, not an
+ * EACCES on the interpreter), and saveStore writes two files that a locked or
+ * read-only instance config will refuse.
+ */
+export declare function ensureBpCatalogFresh(target: Target, deps?: BpCatalogDeps): Promise<void>;
+//# sourceMappingURL=bpCatalog.d.ts.map

package/dist/cli/commands/bpCatalog.js

@@ -0,0 +1,287 @@
+/**
+ * Keeps one target's BP-moniker catalog (src/knowledge/bpMonikers/) matching
+ * its own pinned D365FO version, instead of every instance sharing the one
+ * snapshot committed in catalog.generated.ts (see that module's docblock).
+ *
+ * Called as a step of rebuildIndex() (indexCmd.ts) — the one place already
+ * reached by instance creation, upgrade, routine rebuild, `update`, and the
+ * first-time setup wizard. Regeneration only actually runs when the stamped
+ * version in the target's existing catalog file differs from what this
+ * target resolves to now (or the file does not exist yet); every other call
+ * is a cheap read-and-compare with no subprocess spawned.
+ *
+ * Two things this module will not do, both because the result would be
+ * self-perpetuating — whatever it stamps with the current version key is what
+ * every later rebuild treats as up to date: extract from an install that is
+ * not this target's (resolveSource), and accept an extraction that only
+ * partially read the one that is (verifyExtraction).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { settingByPath } from '../../config/settings.js';
+import { findPackagesRoot } from '../../utils/packagesRoot.js';
+import { commandExists, runExe } from '../exec.js';
+import { paths } from '../context.js';
+import { readPath, readSetting, saveStore, writeSetting } from '../settingsStore.js';
+import { p } from '../ui.js';
+import { isUdeTarget, resolvePinnedXppConfig } from '../xppConfig.js';
+const bpCatalogPathSetting = settingByPath('index.bpCatalogPath');
+const packagePathSetting = settingByPath('environment.packagePath');
+/**
+ * Relative on purpose — instance path settings stay portable so an instance
+ * folder can be renamed or moved (see configBaseDir in config/configFile.ts).
+ */
+const DEFAULT_CATALOG_RELATIVE = './data/bp-moniker-catalog.json';
+/** Where this target's real D365FO version + packages root come from. */
+function resolveSource(target) {
+    const xppConfig = resolvePinnedXppConfig(target.store);
+    if (xppConfig) {
+        // No frameworkDirectory means the config JSON could not be read —
+        // listXppConfigs() keeps those entries deliberately. Passing '' would not
+        // be "use the default", it would hand the script an empty -PackagesPath,
+        // whose own fallback auto-detects the NEWEST PackagesLocalDirectory on the
+        // box; the result then gets stamped with THIS target's version and treated
+        // as current. A catalog from the wrong install is worse than no catalog.
+        if (!xppConfig.frameworkDirectory)
+            return null;
+        return { versionKey: xppConfig.version, packagesPath: xppConfig.frameworkDirectory };
+    }
+    // A null from resolvePinnedXppConfig does NOT mean "traditional". It also
+    // covers a UDE target whose pin names a config that is gone — the
+    // stale-after-UDE-upgrade state `instance upgrade` exists to fix — and that
+    // function returns null there *deliberately*, rather than substituting a
+    // different environment. Falling through to the box-wide scan below would
+    // undo exactly that: findPackagesRoot() ranks every <drive>:\AosService\
+    // PackagesLocalDirectory on the machine and hands back the most plausible
+    // one, which on a mixed box is some other install entirely. Its catalog
+    // would then be stamped with this target's key and treated as current —
+    // the same "catalog from the wrong install" the branch above refuses.
+    if (isUdeTarget(target.store))
+        return null;
+    // Traditional environment: no version string on disk anywhere, so the state
+    // of the files the catalog is extracted FROM stands in for "has this install
+    // changed since we last extracted".
+    const packagesPath = readSetting(target.store, packagePathSetting)
+        || findPackagesRoot()
+        || undefined;
+    if (!packagesPath)
+        return null;
+    const versionKey = ruleSourceKey(packagesPath);
+    return versionKey ? { versionKey, packagesPath } : null;
+}
+/**
+ * A key that moves when the rule DLLs move — the actual input to half the
+ * catalog, and the half that cannot be reconstructed from names alone.
+ *
+ * The obvious cheap key, `statSync(packagesPath/bin).mtimeMs`, does not track
+ * that: a directory's mtime changes when its *direct* children are added,
+ * removed or renamed, so a platform hotfix that rewrites DLLs inside
+ * bin\BPExtensions\ in place leaves bin\ untouched, the key matches, and the
+ * catalog is never regenerated — the exact staleness the per-instance catalog
+ * exists to fix. Size and mtime of each rule DLL move whenever its content
+ * does.
+ *
+ * The file set mirrors what extract-bp-catalog.ps1 itself reflects over:
+ * bin\*.dll whose name contains 'BestPractice', plus every DLL in
+ * bin\BPExtensions. Measured on a real install that is 25 files, reached by
+ * two readdirs and 25 stats in ~5 ms — this runs on every rebuild, so it has
+ * to stay far cheaper than the multi-minute scan it decides against.
+ *
+ * What it deliberately does NOT cover: each model's AxRuleSet\BPRules.xml, the
+ * source of the canonical names. Finding those means recursing the whole
+ * packages root, which is most of the cost of the extraction itself. Neither
+ * did the bin\ mtime it replaces, and in practice a platform update that
+ * changes the rule set ships new rule DLLs with it.
+ */
+function ruleSourceKey(packagesPath) {
+    // join(), not a hardcoded '\bin' — this path is only ever real on Windows in
+    // production, but the test suite (and CI) exercises it on Linux too, where a
+    // literal backslash is just another filename character, not a separator.
+    const binDir = join(packagesPath, 'bin');
+    const extensionsDir = join(binDir, 'BPExtensions');
+    const parts = [];
+    for (const dir of [binDir, extensionsDir]) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.sort()) {
+            if (!/\.dll$/i.test(name))
+                continue;
+            if (dir === binDir && !/BestPractice/i.test(name))
+                continue;
+            try {
+                const stat = statSync(join(dir, name));
+                parts.push(`${name}:${stat.size}:${stat.mtimeMs}`);
+            }
+            catch { /* vanished between readdir and stat — just leave it out */ }
+        }
+    }
+    // No rule DLL anywhere means this is not a usable packages root, so there is
+    // nothing to extract and nothing to key on. Returning a key for the empty set
+    // would make every such path agree with every other one.
+    if (parts.length === 0)
+        return null;
+    return `rules:${createHash('sha1').update(parts.join('|')).digest('hex').slice(0, 16)}`;
+}
+/** The version this target's *existing* catalog file was stamped with, if any. */
+function existingVersionKey(catalogPath) {
+    if (!existsSync(catalogPath))
+        return null;
+    try {
+        // Strip a leading BOM before parsing: the script writes BOM-less UTF-8, but
+        // a catalog left behind by an older copy of it (or hand-edited in a Windows
+        // editor) still carries one, and JSON.parse throws on it. Throwing here is
+        // not visible — it just reads as "no catalog yet" and re-runs the whole scan.
+        const parsed = JSON.parse(readFileSync(catalogPath, 'utf-8').replace(/^\uFEFF/, ''));
+        return typeof parsed.version === 'string' ? parsed.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why a freshly extracted catalog must not be trusted as this target's current
+ * one — or null when it looks like a complete extraction.
+ *
+ * Exit code 0 does not mean "complete". Both of the script's scans are
+ * best-effort on purpose (`-ErrorAction SilentlyContinue`, a per-file catch on
+ * BPRules.xml, a per-DLL catch on assembly load), so a run that could read half
+ * the models, or none of the rule DLLs, still finishes and exits 0. Stamping
+ * that result is worse than not regenerating at all: the stamp matches on every
+ * later rebuild, so it is never retried, and loadCatalog() only rejects an
+ * exactly-empty override — a merely truncated one REPLACES the compiled
+ * snapshot, and bp_moniker starts answering "not in the extracted catalog" for
+ * monikers that are real.
+ *
+ * The failure counts are the script's own (`sources`), not a guess: measured
+ * against a real 214-model PackagesLocalDirectory, a healthy box skips zero of
+ * its 144 BPRules.xml files and zero of its 25 rule DLLs, so any skip at all is
+ * signal. The content checks below stand in for that on a catalog produced by
+ * an older copy of the script, which carries no `sources` block.
+ */
+function verifyExtraction(catalogPath) {
+    let parsed;
+    try {
+        // Same BOM strip as existingVersionKey — a catalog an older copy of the
+        // script produced under PowerShell 5.1 carries one, and this must reject a
+        // partial extraction, not a readable-but-BOM'd one.
+        parsed = JSON.parse(readFileSync(catalogPath, 'utf-8').replace(/^\uFEFF/, ''));
+    }
+    catch (err) {
+        return `it could not be read back (${err.message})`;
+    }
+    if (!Array.isArray(parsed.entries))
+        return 'it carries no entries array';
+    const { ruleSetFailures = 0, dllFailures = 0, ruleSetFiles = 0, ruleDlls = 0 } = parsed.sources ?? {};
+    if (ruleSetFailures > 0 || dllFailures > 0) {
+        return `the extraction skipped ${ruleSetFailures} of ${ruleSetFiles} BPRules.xml files and ${dllFailures} of ${ruleDlls} rule DLLs`;
+    }
+    const entries = parsed.entries;
+    if (entries.length === 0)
+        return 'it contains no monikers at all';
+    // Either source failing wholesale leaves a catalog that still looks populated
+    // but has lost the half that answers a question: no canonical name means no
+    // AxRuleSet was read, so `validate` cannot confirm anything; no rule text
+    // means no DLL yielded resources, so `search` matches nothing.
+    if (!entries.some(e => e.canonical))
+        return 'not one of its monikers came from an AxRuleSet/BPRules.xml';
+    if (!entries.some(e => e.message || e.description))
+        return 'not one of its monikers carries rule text';
+    return null;
+}
+const defaultDeps = { commandExists, runExe };
+/**
+ * Regenerate this target's BP-moniker catalog when its resolved D365FO
+ * version has moved since the catalog file was last stamped (including
+ * "never generated" — covers first-time instance creation). A no-op on
+ * every other rebuild. Never throws and never fails the caller's reindex —
+ * a missing/stale BP catalog degrades one knowledge tool, not the server.
+ *
+ * "Never throws" is enforced here rather than left to the callee getting every
+ * path right. rebuildIndex() awaits this as its last step, unwrapped, *after*
+ * the multi-minute extract and database build have already succeeded and
+ * logged "Index rebuilt" — so anything escaping would turn a finished rebuild
+ * into a crashed command. And plenty can escape: runExe rejects on the child
+ * process's own 'error' event (commandExists only rules out ENOENT, not an
+ * EACCES on the interpreter), and saveStore writes two files that a locked or
+ * read-only instance config will refuse.
+ */
+export async function ensureBpCatalogFresh(target, deps = defaultDeps) {
+    try {
+        await refreshCatalog(target, deps);
+    }
+    catch (err) {
+        p.log.warn(`BP catalog: skipped for ${target.label} (${err.message}) — the index rebuild itself is unaffected.`);
+    }
+}
+async function refreshCatalog(target, deps) {
+    const source = resolveSource(target);
+    if (!source) {
+        p.log.warn(isUdeTarget(target.store)
+            ? `BP catalog: could not resolve ${target.label}'s own D365FO install (its XPP config is missing or unreadable) — skipped rather than extracting from another install on this box. \`d365fo-mcp instance upgrade\` repoints a pin left behind by a UDE upgrade.`
+            : `BP catalog: could not resolve a packages path for ${target.label} — skipped.`);
+        return;
+    }
+    // The setting carries no registry default (see settings.ts for why), so this
+    // fallback is the normal path until the first successful extraction writes
+    // the value below.
+    const catalogPath = readPath(target.store, bpCatalogPathSetting, resolve(target.store.baseDir, DEFAULT_CATALOG_RELATIVE));
+    if (existingVersionKey(catalogPath) === source.versionKey) {
+        p.log.info(`BP catalog up to date (${target.label}).`);
+        return;
+    }
+    let shell = 'pwsh';
+    if (!await deps.commandExists(shell)) {
+        shell = 'powershell';
+        if (!await deps.commandExists(shell)) {
+            p.log.warn(`BP catalog: neither pwsh nor powershell is on PATH for ${target.label} — skipped, will retry next rebuild.`);
+            return;
+        }
+    }
+    p.log.step(`Refreshing BP moniker catalog (${target.label}, ${basename(source.packagesPath)})…`);
+    // Extract beside the real catalog, not over it. The script writes its output
+    // in one go with no staging of its own, so pointing it straight at the live
+    // file means a partial run destroys a good catalog before anything can judge
+    // it — and the caller cannot put it back. The move below is the only thing
+    // that makes this target's catalog change.
+    const stagedPath = `${catalogPath}.new`;
+    const exitCode = await deps.runExe(shell, [
+        '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', paths.extractBpCatalogScript,
+        '-PackagesPath', source.packagesPath,
+        '-OutFile', stagedPath,
+        '-Version', source.versionKey,
+    ]);
+    if (exitCode !== 0) {
+        rmSync(stagedPath, { force: true });
+        p.log.warn(`BP catalog: extraction failed for ${target.label} (exit ${exitCode}) — keeping the previous catalog.`);
+        return;
+    }
+    const problem = verifyExtraction(stagedPath);
+    if (problem) {
+        // Discarded rather than stamped: the file carries this target's current
+        // version key, so keeping it would make every later rebuild a no-op and
+        // freeze a half-read catalog in place. Dropping it leaves the previous
+        // catalog (or the compiled snapshot) in service and the version key stale,
+        // which is exactly what makes the next rebuild try again.
+        rmSync(stagedPath, { force: true });
+        p.log.warn(`BP catalog: discarded the extraction for ${target.label} — ${problem}. Keeping the previous catalog; the next rebuild will retry.`);
+        return;
+    }
+    renameSync(stagedPath, catalogPath);
+    // Write the RELATIVE literal, not the resolved catalogPath: an absolute path
+    // baked into the instance config survives neither a folder rename nor a move,
+    // and toEnvRecord() resolves a relative one against store.baseDir on its way
+    // into BP_CATALOG_PATH anyway. This write is also what turns the override on
+    // at all — the setting has no registry default.
+    if (readSetting(target.store, bpCatalogPathSetting) === undefined) {
+        writeSetting(target.store, bpCatalogPathSetting, DEFAULT_CATALOG_RELATIVE);
+        saveStore(target.store);
+    }
+    p.log.success(`BP catalog refreshed (${target.label}).`);
+}
+//# sourceMappingURL=bpCatalog.js.map

package/dist/cli/commands/indexCmd.js

@@ -4,6 +4,7 @@
  * instances/rebuild-instance.ps1 minus the git-pull step (that lives in
  * `d365fo-mcp update`).
  */
+import { ensureBpCatalogFresh } from './bpCatalog.js';
 import { dataRoot, installMode, isWindows, paths } from '../context.js';
 import { runNode } from '../exec.js';
 import { listInstances } from '../instances.js';
@@ -47,6 +48,9 @@ export async function rebuildIndex(target) {
         return false;
     }
     p.log.success(`Index rebuilt: ${target.label}`);
+    // Best-effort: a stale/missing BP catalog degrades one knowledge tool, not
+    // the metadata index rebuild that just succeeded above.
+    await ensureBpCatalogFresh(target);
     return true;
 }
 export async function indexCommand(instanceName, opts) {

package/dist/cli/context.d.ts

@@ -84,6 +84,14 @@ export declare const paths: {
     /** esbuild bundles of the two scripts above — what an npm install ships instead of the sources. */
     extractScriptDist: string;
     buildDbScriptDist: string;
+    /**
+     * Not compiled, not bundled — a raw PowerShell script that reflects over the
+     * .NET-authored BP-rule DLLs to pull real message/description text, which
+     * Node cannot do on its own. Same path for a git checkout and an npm
+     * install; ships as a listed file in package.json rather than through the
+     * dist/ pipeline the .ts scripts above use.
+     */
+    extractBpCatalogScript: string;
 };
 /**
  * The exact command that builds the bridge for this installation, for every

package/dist/cli/context.js

@@ -153,6 +153,14 @@ export const paths = {
     /** esbuild bundles of the two scripts above — what an npm install ships instead of the sources. */
     extractScriptDist: resolve(repoRoot, 'dist', 'scripts', 'extract-metadata.js'),
     buildDbScriptDist: resolve(repoRoot, 'dist', 'scripts', 'build-database.js'),
+    /**
+     * Not compiled, not bundled — a raw PowerShell script that reflects over the
+     * .NET-authored BP-rule DLLs to pull real message/description text, which
+     * Node cannot do on its own. Same path for a git checkout and an npm
+     * install; ships as a listed file in package.json rather than through the
+     * dist/ pipeline the .ts scripts above use.
+     */
+    extractBpCatalogScript: resolve(repoRoot, 'scripts', 'extract-bp-catalog.ps1'),
 };
 /**
  * The exact command that builds the bridge for this installation, for every

package/dist/cli/xppConfig.d.ts

@@ -13,6 +13,40 @@ export interface XppConfig {
 export declare function xppConfigDir(): string | null;
 /** All versioned configs, newest first. Empty when the directory is absent. */
 export declare function listXppConfigs(): XppConfig[];
+/**
+ * The full {@link XppConfig} a UDE target resolves to: the pinned one, or the
+ * newest available when nothing is pinned. Null for a traditional target, when
+ * no config exists at all, and — deliberately — when the pin names a config
+ * that is gone.
+ *
+ * Mirrors XppConfigProvider.getActiveConfig exactly, including that last case:
+ * it matches either form of the name and returns null rather than substituting
+ * a different environment. A pin that no longer resolves is the
+ * stale-after-UDE-upgrade state isXppConfigStale() flags and `instance upgrade`
+ * exists to fix; answering it with the newest config would have a caller
+ * extract from 10.0.2500 and stamp the result as this target's, while its index
+ * and server still reference the old pin.
+ */
+export declare function resolvePinnedXppConfig(store: SettingsStore): XppConfig | null;
+/**
+ * Is this target a UDE target at all — i.e. does a null from
+ * {@link resolvePinnedXppConfig} mean "its pin does not resolve" rather than
+ * "this is a traditional install"?
+ *
+ * That function returns null for three different reasons and a caller cannot
+ * tell them apart, which matters because the two answers call for opposite
+ * behaviour: a traditional target legitimately falls back to detecting the
+ * packages root on this box, while for a UDE target that fallback throws away
+ * the very guarantee the null was there to provide (see resolveSource in
+ * commands/bpCatalog.ts, and the docblock above).
+ *
+ * Mirrors the detection settings.ts documents for an unset environment.type:
+ * UDE when XPP config files exist in %LOCALAPPDATA%\Microsoft\Dynamics365\
+ * XPPConfig. So a box with no configs at all is traditional — the one case
+ * where falling through is correct — and anything else with an explicit
+ * `traditional` type is taken at its word.
+ */
+export declare function isUdeTarget(store: SettingsStore): boolean;
 /**
  * Expand a short config name (e.g. "myenv-dev") to the newest full versioned
  * name ("myenv-dev___10.0.2345.153") so a later staleness check is a plain

package/dist/cli/xppConfig.js

@@ -54,6 +54,54 @@ function pinnedConfigName(store) {
     const value = readSetting(store, xppConfigNameSetting);
     return typeof value === 'string' && value ? value : null;
 }
+/**
+ * The full {@link XppConfig} a UDE target resolves to: the pinned one, or the
+ * newest available when nothing is pinned. Null for a traditional target, when
+ * no config exists at all, and — deliberately — when the pin names a config
+ * that is gone.
+ *
+ * Mirrors XppConfigProvider.getActiveConfig exactly, including that last case:
+ * it matches either form of the name and returns null rather than substituting
+ * a different environment. A pin that no longer resolves is the
+ * stale-after-UDE-upgrade state isXppConfigStale() flags and `instance upgrade`
+ * exists to fix; answering it with the newest config would have a caller
+ * extract from 10.0.2500 and stamp the result as this target's, while its index
+ * and server still reference the old pin.
+ */
+export function resolvePinnedXppConfig(store) {
+    if (readSetting(store, envTypeSetting) === 'traditional')
+        return null;
+    const configs = listXppConfigs();
+    if (configs.length === 0)
+        return null;
+    const configName = pinnedConfigName(store);
+    if (!configName)
+        return configs[0];
+    return configs.find(c => c.fullName === configName || c.name === configName) ?? null;
+}
+/**
+ * Is this target a UDE target at all — i.e. does a null from
+ * {@link resolvePinnedXppConfig} mean "its pin does not resolve" rather than
+ * "this is a traditional install"?
+ *
+ * That function returns null for three different reasons and a caller cannot
+ * tell them apart, which matters because the two answers call for opposite
+ * behaviour: a traditional target legitimately falls back to detecting the
+ * packages root on this box, while for a UDE target that fallback throws away
+ * the very guarantee the null was there to provide (see resolveSource in
+ * commands/bpCatalog.ts, and the docblock above).
+ *
+ * Mirrors the detection settings.ts documents for an unset environment.type:
+ * UDE when XPP config files exist in %LOCALAPPDATA%\Microsoft\Dynamics365\
+ * XPPConfig. So a box with no configs at all is traditional — the one case
+ * where falling through is correct — and anything else with an explicit
+ * `traditional` type is taken at its word.
+ */
+export function isUdeTarget(store) {
+    if (readSetting(store, envTypeSetting) === 'traditional')
+        return false;
+    return listXppConfigs().length > 0;
+}
 /**
  * Expand a short config name (e.g. "myenv-dev") to the newest full versioned
  * name ("myenv-dev___10.0.2345.153") so a later staleness check is a plain

package/dist/config/configFile.d.ts

@@ -62,6 +62,12 @@ export declare function toEnvRecord(files: Pick<ResolvedConfigFiles, 'baseDir' |
  *
  * Emitting the defaults here pins them to the installation directory instead.
  * A checkout is its own data directory, so its paths do not move.
+ *
+ * BP_CATALOG_PATH is deliberately NOT one of them: index.bpCatalogPath carries
+ * no registry default precisely so that "unset" keeps meaning "use the
+ * compiled-in catalog". Giving it one here would make the variable permanently
+ * set and every install that has never regenerated a catalog warn about a
+ * missing file on each start.
  */
 export declare function defaultPathEnv(baseDir: string): Record<string, string>;
 /** Write the config file, creating its directory. Keys are emitted in registry order. */

package/dist/config/configFile.js

@@ -142,6 +142,12 @@ export function toEnvRecord(files) {
  *
  * Emitting the defaults here pins them to the installation directory instead.
  * A checkout is its own data directory, so its paths do not move.
+ *
+ * BP_CATALOG_PATH is deliberately NOT one of them: index.bpCatalogPath carries
+ * no registry default precisely so that "unset" keeps meaning "use the
+ * compiled-in catalog". Giving it one here would make the variable permanently
+ * set and every install that has never regenerated a catalog warn about a
+ * missing file on each start.
  */
 export function defaultPathEnv(baseDir) {
     const out = {};

package/dist/config/settings.js

@@ -331,6 +331,25 @@ export const SETTINGS = [
         description: 'Working folder for the XML dumped during extraction, before it is loaded into the database.',
         default: './extracted-metadata',
     },
+    {
+        path: 'index.bpCatalogPath',
+        env: 'BP_CATALOG_PATH',
+        section: 'index',
+        tier: 'advanced',
+        type: 'path',
+        label: 'BP moniker catalog file',
+        description: 'Per-instance JSON catalog of real BP-check monikers, extracted from this instance\'s own D365FO version ' +
+            '(scripts/extract-bp-catalog.ps1). Falls back to the compiled-in snapshot when absent — this setting is only ' +
+            'written once an instance has regenerated its own catalog.',
+        // Deliberately no `default`. defaultPathEnv() projects every path setting
+        // that has a string default onto process.env, which would make
+        // BP_CATALOG_PATH permanently set — the "unset → compiled-in catalog"
+        // branch in bpMonikers/loadCatalog() would be unreachable and every
+        // install that has never regenerated a catalog (all existing ones, every
+        // Linux deployment, every checkout) would warn about a missing file on
+        // each start. ensureBpCatalogFresh writes the value after a successful
+        // extraction instead, which is what the description above promises.
+    },
     {
         path: 'index.labelSortOrder',
         env: 'LABEL_SORT_ORDER',

package/dist/knowledge/bpMonikers/catalog.generated.d.ts

@@ -0,0 +1,31 @@
+/**
+ * GENERATED FILE — do not hand-edit. Regenerate with:
+ *   pwsh scripts/extract-bp-catalog.ps1
+ *
+ * BP-rule moniker catalog, extracted from a local D365FO install:
+ *   - `canonical: true` monikers come from the union of every model's
+ *     <Model>/<Model>/AxRuleSet/BPRules.xml — the authoritative name list.
+ *   - `message`/`description` come from the .NET-authored rule DLLs'
+ *     resx-backed resource classes (bin/BPExtensions/*.dll and a couple of
+ *     core bin/*.dll) where the rule author provided one. A `null` there
+ *     means "not found in a resource class", NOT "not a real rule".
+ *   - Presence in this file does NOT by itself mean "BP rule". The resource
+ *     dump also yields upgrade- and form-conversion-tool messages, which come
+ *     out with `canonical: false`. `canonical` is the field that answers
+ *     "is this a BP rule".
+ *
+ * Extracted from: C:\Users\laeliand\AppData\Local\Microsoft\Dynamics365\10.0.2527.174\PackagesLocalDirectory
+ * Generated at:   (stamp with the actual date when regenerating — omitted
+ *                  here so re-running with no real change produces no diff)
+ */
+export interface BpMonikerEntry {
+    moniker: string;
+    /** Message template (often with '{0}'-style placeholders), or null if not found in a resource class. */
+    message: string | null;
+    /** What the rule checks, or null if not found in a resource class. */
+    description: string | null;
+    /** True if this moniker appears in at least one model's AxRuleSet/BPRules.xml. */
+    canonical: boolean;
+}
+export declare const BP_MONIKER_CATALOG: BpMonikerEntry[];
+//# sourceMappingURL=catalog.generated.d.ts.map