d365fo-mcp 1.10.1 → 1.12.0

package/dist/bridge/bridgeAdapter.js

@@ -25,8 +25,9 @@ import * as debouncedRefresh from './debouncedRefresh.js';
 import { debugLog } from '../utils/logger.js';
 import { xppMethodSourceForXml } from '../utils/xppFormat.js';
 import { ensureXppDocComment, ensureBlankLineBeforeClosingBrace } from '../utils/xppDocGen.js';
-import { parseXppDeclaration } from '../metadata/xppDeclaration.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;
@@ -176,11 +177,23 @@ function formatClass(cls, compact, methodOffset) {
     if (cls.isAbstract)
         modifiers.push('abstract');
     const modStr = modifiers.length > 0 ? ` (${modifiers.join(', ')})` : '';
+    // The bridge sends no access modifier of its own, but it does send the
+    // declaration verbatim — and that is where the modifier lives, since AxClass
+    // XML has no element for it either. Parsed rather than regexed so a modifier
+    // named in an attribute or a doc comment cannot be mistaken for the real one.
+    const visibility = cls.declaration
+        ? parseXppClassHeader(cls.declaration)?.visibility
+        : undefined;
     let out = `# Class: ${cls.name}${modStr}\n\n`;
     if (cls.extends)
         out += `**Extends:** ${cls.extends}\n`;
     if (cls.model)
         out += `**Model:** ${cls.model}\n`;
+    // Printed on every path, so a reader comparing two classes is not left to infer
+    // package scope from a line's absence. Silent only when there was no
+    // declaration to read at all (#902).
+    if (cls.declaration)
+        out += `**Access:** ${visibility ?? 'public'}\n`;
     out += `**Abstract:** ${cls.isAbstract ? 'Yes' : 'No'}\n`;
     out += `**Final:** ${cls.isFinal ? 'Yes' : 'No'}\n`;
     out += `_Source: C# bridge (IMetadataProvider)_\n\n`;
@@ -203,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

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/doctor.d.ts

@@ -4,6 +4,51 @@ interface CheckResult {
     message: string;
     fix?: string;
 }
+/** Classic AOSService VM, or Unified Developer Experience. */
+export type EnvKind = 'traditional' | 'ude';
+/**
+ * What a path setting IS, so that "this folder is missing" can name the right
+ * cause and the right cure for it.
+ *
+ * Without this the three settings shared one message, and it fitted only one of
+ * them: `packagePath` on UDE. It told a traditional VM that its packages root
+ * is "normally auto-detected from the active XPP config" (it is not — the drive
+ * scan finds it), and it offered `<drive>:\AosService\PackagesLocalDirectory`,
+ * a traditional-VM artifact, as the value to give the UDE ModelStoreFolder and
+ * FrameworkDirectory.
+ *
+ * `autoSource` is the load-bearing one: a stale pin is only a *stale pin* where
+ * something would otherwise resolve the value live. Where nothing would, the
+ * pin is the configuration, and telling the user to delete it is telling them
+ * to break their install — `customPackagesPath` on a traditional VM is exactly
+ * that case, the documented fix for junction layouts (docs/MCP_CONFIG.md).
+ */
+interface PathFacts {
+    humanName: string;
+    /** How the value resolves when nothing pins it, or null when nothing does. */
+    autoSource(kind: EnvKind): string | null;
+    /** Values doctor can actually propose — empty when it has no way to know one. */
+    candidates(kind: EnvKind): string[];
+    /** What the setting ought to point at, in words. */
+    target(kind: EnvKind): string;
+    /** Extra context line when there is no candidate to name, or null. */
+    note(kind: EnvKind): string | null;
+}
+export declare const PATH_FACTS: Record<string, PathFacts>;
+/**
+ * "Path setting points at a folder that isn't there" — with the cause named.
+ *
+ * A value pinned by the legacy .env instead of the JSON config is the likely bug
+ * whenever something else would have resolved it live: the .env copy goes stale
+ * the moment a platform update moves the folder, and it keeps outranking the
+ * now-correct detection at every startup (see configManager's envContext, which
+ * reads these env vars before consulting the XPP config). The server then dies
+ * with "C# bridge unavailable (ude)" and nothing points at the .env.
+ *
+ * Pure — every input is passed in — so the messages can be tested without a
+ * Windows box, an XPP config or a real .env.
+ */
+export declare function missingPathFix(setting: import('../../config/settings.js').Setting, facts: PathFacts, label: string, configured: string, kind: EnvKind, pinnedByEnv: boolean): Omit<CheckResult, 'severity'>;
 /**
  * The configured prefix against the one the model's own objects use.
  *
@@ -11,8 +56,14 @@ interface CheckResult {
  * for every model — but the server resolves the model's own naming ABOVE the
  * configuration, so a user reading only their config has the wrong answer. State
  * both, and how to pin the configured one.
+ *
+ * `pinned` is naming.prefixSource=config. This check used to call the inference
+ * directly and so never saw it — modelPrefixInference reads it in
+ * getInferredModelPrefix, one level above inferPrefixFromObjectNames — which
+ * meant a user who had already pinned the prefix was still told their model's
+ * naming wins (it does not) and offered the fix they had already applied (#893).
  */
-export declare function checkPrefixResolution(configuredPrefix: string, modelName: string | null, modelObjectNames: string[], label: string): CheckResult[];
+export declare function checkPrefixResolution(configuredPrefix: string, modelName: string | null, modelObjectNames: string[], label: string, pinned?: boolean): CheckResult[];
 export declare function doctorCommand(): Promise<void>;
 export {};
 //# sourceMappingURL=doctor.d.ts.map