d365fo-mcp 1.17.4 → 1.18.0

package/.github/copilot-instructions.md

@@ -74,6 +74,7 @@ PowerShell / any terminal command **WILL HANG** in VS 2022 / VS 2026 MCP integra
    - `model-name` → class `{Target}_{ModelName}_Extension`, element `{Target}.{ModelName}`
 
    Pass the BASE object name to `d365fo_file(action="create")` and let the tool inject the token — don't hand-build the infix.
+   These patterns describe how the tool names extensions, and the tool applies them itself — editing them here does not change the names it writes. Change the style with `d365fo-mcp config naming`.
 
 ### Reuse & diff safety
 

package/bridge/D365MetadataBridge/Services/MetadataWriteService.cs

@@ -3483,14 +3483,11 @@ namespace D365MetadataBridge.Services
                         ?? throw new ArgumentException($"Form extension '{objectName}' not found");
                     var msi = GetModelSaveInfoForObject(_provider.FormExtensions, objectName);
 
-                    // Same idempotency rule as the form branch below: skip on a name match,
-                    // and on a different-named data source already bound to the same table.
+                    // Same idempotency rule as the form branch below: skip on a NAME match only.
                     foreach (AxFormDataSourceRoot existing in axExt.DataSources)
                     {
                         if (string.Equals(existing.Name, dsName, StringComparison.OrdinalIgnoreCase))
                             return new { success = true, operation = "add-data-source", objectType, objectName, dsName, table, skipped = true, reason = $"data source '{dsName}' already exists", api = "IMetaFormExtensionProvider.Update" };
-                        if (string.Equals(existing.Table, table, StringComparison.OrdinalIgnoreCase))
-                            return new { success = true, operation = "add-data-source", objectType, objectName, dsName, table, skipped = true, reason = $"data source '{existing.Name}' already binds table '{table}'", api = "IMetaFormExtensionProvider.Update" };
                     }
 
                     axExt.DataSources.Add((AxFormDataSourceRoot)CreateFormDataSourceRoot(dsName, table, joinSource, linkType));
@@ -3506,18 +3503,23 @@ namespace D365MetadataBridge.Services
                         ?? throw new ArgumentException($"Form '{objectName}' not found");
                     var msi = GetModelSaveInfoForObject(_provider.Forms, objectName);
 
-                    // Idempotency: don't append a duplicate. If a data source with the same
-                    // NAME already exists, skip (it may be a template stub already bound to the
-                    // right table). If a DIFFERENT-named data source already binds the same
-                    // TABLE, skip too — adding a second binding to the same table is almost
-                    // always an accident (a stub the caller meant to replace, not duplicate).
+                    // Idempotency: don't append a duplicate. A data source with the same NAME
+                    // already there is a real conflict (it may be a template stub already bound
+                    // to the right table), so skip that one.
+                    //
+                    // A different-named data source already bound to the same TABLE is NOT a
+                    // conflict and must still be written. This used to skip too, on the theory
+                    // that "adding a second binding to the same table is almost always an
+                    // accident" — which is simply untrue: a form routinely joins one table into
+                    // several branches of its query. Microsoft's own PurchLineBackOrder carries
+                    // PurchTable and PurchTable1, both over PurchTable, with different link
+                    // types. The rule silently dropped three legitimate data sources and, because
+                    // `skipped` never reached the caller, reported all three as added.
                     foreach (var existing in axForm.DataSources)
                     {
                         dynamic dyn = existing;
                         if (string.Equals((string)dyn.Name, dsName, StringComparison.OrdinalIgnoreCase))
                             return new { success = true, operation = "add-data-source", objectType, objectName, dsName, table, skipped = true, reason = $"data source '{dsName}' already exists", api = "IMetaFormProvider.Update" };
-                        if (string.Equals((string)dyn.Table, table, StringComparison.OrdinalIgnoreCase))
-                            return new { success = true, operation = "add-data-source", objectType, objectName, dsName, table, skipped = true, reason = $"data source '{(string)dyn.Name}' already binds table '{table}'", api = "IMetaFormProvider.Update" };
                     }
 
                     axForm.AddDataSource(CreateFormDataSourceRoot(dsName, table, joinSource, linkType));

package/dist/bridge/bridgeAdapter.d.ts

@@ -234,6 +234,27 @@ export declare function bridgeResolveObject(bridge: BridgeClient | undefined, ob
 export declare function unappliedSuffix(result: {
     unsupportedProperties?: string[];
 }): string;
+/** What a bridge write returns when it declined to do anything. */
+export interface BridgeSkippable {
+    skipped?: boolean;
+    reason?: string;
+}
+/**
+ * Renders a bridge result that declined the write, or null when it did write.
+ *
+ * The bridge has long been able to answer `{ success: true, skipped: true, reason }`
+ * — it did the honest thing and said it changed nothing. Nothing on this side read
+ * `skipped`, so every decline fell through the caller's `result.success` branch and
+ * was rendered "✅ … added": a write that never happened, reported as one, with the
+ * bridge's own explanation discarded on the way past.
+ *
+ * `success` from the bridge means "this did not fail", NOT "the object changed".
+ * Any wrapper whose operation can skip must ask this before claiming a write.
+ *
+ * Exactly the lesson unappliedSuffix() above was added for, one field over — which
+ * is why both live here together.
+ */
+export declare function skippedMessage(result: BridgeSkippable, subject: string): string | null;
 /**
  * Checks if bridge can handle this create operation.
  */
@@ -319,6 +340,7 @@ export declare function bridgeAddField(bridge: BridgeClient | undefined, tableNa
 }): Promise<{
     success: boolean;
     message: string;
+    skipped?: boolean;
 } | null>;
 /**
  * Sets a property via the C# bridge (IMetadataProvider.Update()).
@@ -425,6 +447,7 @@ export declare function bridgeRemoveFieldGroup(bridge: BridgeClient | undefined,
 export declare function bridgeAddFieldToFieldGroup(bridge: BridgeClient | undefined, tableName: string, groupName: string, fieldName: string, extendBaseFieldGroup?: boolean): Promise<{
     success: boolean;
     message: string;
+    skipped?: boolean;
 } | null>;
 /**
  * Modifies field properties on a table via the C# bridge.
@@ -488,6 +511,7 @@ export declare function bridgeAddControl(bridge: BridgeClient | undefined, formN
 export declare function bridgeAddDataSource(bridge: BridgeClient | undefined, objectType: string, objectName: string, dsName: string, table: string, joinSource?: string, linkType?: string): Promise<{
     success: boolean;
     message: string;
+    skipped?: boolean;
 } | null>;
 /**
  * Adds or updates a FieldModification entry in a table-extension via the C# bridge.
@@ -503,6 +527,7 @@ export declare function bridgeAddFieldModification(bridge: BridgeClient | undefi
 export declare function bridgeAddMenuItemToMenu(bridge: BridgeClient | undefined, menuName: string, menuItemToAdd: string, menuItemToAddType?: string): Promise<{
     success: boolean;
     message: string;
+    skipped?: boolean;
 } | null>;
 /**
  * Executes multiple write operations on a single object in one bridge call.

package/dist/bridge/bridgeAdapter.js

@@ -1254,6 +1254,9 @@ const BRIDGE_MODIFY_OPS = new Set([
     // no concept of it — so this is XML-only for the same structural reason as the
     // two above.
     'remove-diagnostic-suppression', 'add-diagnostic-suppression',
+    // A model descriptor is not an AOT object either — it is the package's own
+    // manifest, outside the AOT entirely — so the same XML-only reasoning applies.
+    'add-module-reference', 'remove-module-reference',
     '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
@@ -1296,6 +1299,8 @@ 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']),
+    'add-module-reference': new Set(['model-descriptor']),
+    'remove-module-reference': new Set(['model-descriptor']),
     // An AxReport has no bridge write path at all — IMetadataProvider cannot express
     // a dataset field or a report parameter through a Dictionary<string,string> — and
     // `report` is deliberately absent from BRIDGE_MODIFY_TYPES for that reason. Without
@@ -1317,6 +1322,30 @@ export function unappliedSuffix(result) {
         return '';
     return `\n⚠️ NOT applied — this object type has nowhere to store them: ${dropped.join(', ')}`;
 }
+/**
+ * Renders a bridge result that declined the write, or null when it did write.
+ *
+ * The bridge has long been able to answer `{ success: true, skipped: true, reason }`
+ * — it did the honest thing and said it changed nothing. Nothing on this side read
+ * `skipped`, so every decline fell through the caller's `result.success` branch and
+ * was rendered "✅ … added": a write that never happened, reported as one, with the
+ * bridge's own explanation discarded on the way past.
+ *
+ * `success` from the bridge means "this did not fail", NOT "the object changed".
+ * Any wrapper whose operation can skip must ask this before claiming a write.
+ *
+ * Exactly the lesson unappliedSuffix() above was added for, one field over — which
+ * is why both live here together.
+ */
+export function skippedMessage(result, subject) {
+    if (result.skipped !== true)
+        return null;
+    const reason = result.reason?.trim();
+    return (`⏭️ NOT written — ${subject} was skipped by the bridge` +
+        (reason ? `: ${reason}` : ' (no reason given)') +
+        `\n   Nothing changed on disk. If you meant to replace what is already there, ` +
+        `remove or rename it first — re-sending this operation will skip again.`);
+}
 /**
  * Checks if bridge can handle this create operation.
  */
@@ -1480,9 +1509,10 @@ export async function bridgeAddField(bridge, tableName, fieldName, fieldType, ed
         const result = await bridge.addField(tableName, fieldName, fieldType, edt, mandatory, label, mapped?.dataField, mapped?.dataSource, mapped?.fieldGroupName);
         return {
             success: result.success,
-            message: result.success
+            skipped: result.skipped === true,
+            message: skippedMessage(result, `Field '${fieldName}'`) ?? (result.success
                 ? `✅ Field '${fieldName}' added via ${result.api}`
-                : `Bridge addField returned success=false`,
+                : `Bridge addField returned success=false`),
         };
     }
     catch (e) {
@@ -1839,9 +1869,10 @@ export async function bridgeAddFieldToFieldGroup(bridge, tableName, groupName, f
             : '<FieldGroups>';
         return {
             success: result.success,
-            message: result.success
+            skipped: result.skipped === true,
+            message: skippedMessage(result, `Field '${fieldName}' → group '${groupName}'`) ?? (result.success
                 ? `✅ Field '${fieldName}' added to group '${groupName}' in ${target} via ${result.api}`
-                : `Bridge addFieldToFieldGroup returned success=false`,
+                : `Bridge addFieldToFieldGroup returned success=false`),
         };
     }
     catch (e) {
@@ -2053,11 +2084,13 @@ export async function bridgeAddDataSource(bridge, objectType, objectName, dsName
         return null;
     try {
         const result = await bridge.addDataSource(objectType, objectName, dsName, table, joinSource, linkType);
+        const skip = skippedMessage(result, `DataSource '${dsName}'`);
         return {
             success: result.success,
-            message: result.success
+            skipped: result.skipped === true,
+            message: skip ?? (result.success
                 ? `✅ DataSource '${dsName}' added via ${result.api}`
-                : `Bridge addDataSource returned success=false`,
+                : `Bridge addDataSource returned success=false`),
         };
     }
     catch (e) {
@@ -2106,9 +2139,10 @@ export async function bridgeAddMenuItemToMenu(bridge, menuName, menuItemToAdd, m
         const result = await bridge.addMenuItemToMenu(menuName, menuItemToAdd, menuItemToAddType);
         return {
             success: result.success,
-            message: result.success
+            skipped: result.skipped === true,
+            message: skippedMessage(result, `Menu item '${menuItemToAdd}'`) ?? (result.success
                 ? `✅ Menu item '${menuItemToAdd}' added via ${result.api}`
-                : `Bridge addMenuItemToMenu returned success=false`,
+                : `Bridge addMenuItemToMenu returned success=false`),
         };
     }
     catch (e) {

package/dist/bridge/bridgeTypes.d.ts

@@ -348,6 +348,20 @@ export interface BridgeWriteResult {
      * create ops and on add-control; the write itself still succeeded.
      */
     unsupportedProperties?: string[];
+    /**
+     * The bridge declined the operation and changed NOTHING — an element with that
+     * name is already there. `success` stays true because nothing failed, so a
+     * caller that reads only `success` reports a write that did not happen. Render
+     * it with skippedMessage() (bridgeAdapter.ts) rather than the success branch.
+     *
+     * Returned today by add-field (data-entity-extension), add-field-to-field-group,
+     * add-menu-item-to-menu and add-data-source. It was absent from this interface
+     * for as long as the bridge has been sending it, which is precisely why four
+     * wrappers could ignore it without so much as a type error.
+     */
+    skipped?: boolean;
+    /** Why the bridge skipped, in its own words. Only set alongside `skipped`. */
+    reason?: string;
     api?: string;
 }
 /** Result from createSmartTable — includes BP defaults summary */

package/dist/cli/ui.d.ts

@@ -6,8 +6,15 @@
 import * as p from '@clack/prompts';
 import type { Option } from '@clack/prompts';
 export { p };
-/** Unwrap a clack result; exit gracefully when the user cancelled. */
-export declare function ensure<T>(value: T | symbol): T;
+/**
+ * Unwrap a clack result; exit gracefully when the user cancelled.
+ *
+ * Typed as `Exclude<T, symbol>` rather than `(value: T | symbol): T`: since
+ * @clack/prompts 1.8.1 the prompts return `T | typeof CANCEL_SYMBOL`, a
+ * `unique symbol` that the `T | symbol` form no longer peeled off T, so every
+ * caller got the cancel symbol back in its type.
+ */
+export declare function ensure<T>(value: T): Exclude<T, symbol>;
 export declare function askText(opts: {
     message: string;
     placeholder?: string;

package/dist/cli/ui.js

@@ -6,7 +6,14 @@
 import * as p from '@clack/prompts';
 import { installOneLiner, isFullInstall } from './context.js';
 export { p };
-/** Unwrap a clack result; exit gracefully when the user cancelled. */
+/**
+ * Unwrap a clack result; exit gracefully when the user cancelled.
+ *
+ * Typed as `Exclude<T, symbol>` rather than `(value: T | symbol): T`: since
+ * @clack/prompts 1.8.1 the prompts return `T | typeof CANCEL_SYMBOL`, a
+ * `unique symbol` that the `T | symbol` form no longer peeled off T, so every
+ * caller got the cancel symbol back in its type.
+ */
 export function ensure(value) {
     if (p.isCancel(value)) {
         p.cancel('Cancelled.');

package/dist/config/settings.js

@@ -273,6 +273,24 @@ export const SETTINGS = [
             { value: 'model-name', hint: 'CustTable.ContosoRobotics — embeds the model name (VS default)' },
         ],
     },
+    {
+        path: 'naming.extensionClassStyle',
+        env: 'EXTENSION_CLASS_NAMING_STYLE',
+        section: 'naming',
+        tier: 'advanced',
+        type: 'enum',
+        label: 'How extension CLASSES are named',
+        description: 'Overrides naming.extensionStyle for CoC extension classes only, leaving element extensions alone. ' +
+            'Some conventions spell the two differently — Visual Studio elements (CustTable.ContosoRobotics) with ' +
+            'prefix-style classes (CustTableCtso_Extension) — which a single style cannot express: it renames one ' +
+            'or the other. Leave on inherit unless your convention names classes differently from elements.',
+        default: 'inherit',
+        choices: [
+            { value: 'inherit', hint: 'follow naming.extensionStyle — the default, behaviour unchanged' },
+            { value: 'prefix', hint: 'CustTableCtso_Extension — embeds the extension prefix' },
+            { value: 'model-name', hint: 'CustTable_ContosoRobotics_Extension — embeds the model name' },
+        ],
+    },
     // ── index ────────────────────────────────────────────────────────────────
     {
         path: 'index.extractMode',

package/dist/metadata/modelDescriptor.d.ts

@@ -16,8 +16,32 @@
  */
 /**
  * Extract every `<d2p1:string>` entry of a descriptor's `<ModuleReferences>`.
- * The sibling `<ModelReferences>` is `i:nil` in every descriptor observed on a
- * real box, so the flat scan cannot pick up entries from it.
+ *
+ * Scoped to that ELEMENT, not scanned flat over the document. The flat scan this
+ * replaces reasoned only about `<ModelReferences>` — `i:nil` in every descriptor
+ * observed on a real box, so it contributes nothing — and missed the OTHER
+ * `<d2p1:string>` arrays a descriptor carries: `<InternalsVisibleTo>` and
+ * `<AppliedUpdates>`. Both are ordinary string lists, and `<InternalsVisibleTo>`
+ * sorts BEFORE `<ModuleReferences>` in the serialized document, so its entries
+ * came back as module references.
+ *
+ * Measured on a 10.0.2527 PackagesLocalDirectory plus the custom roots beside
+ * it: 112 of 176 descriptors over-reported, 606 phantom references in total.
+ * `Foundation.xml` answered 157 for a model that references 46;
+ * `ApplicationPlatform.xml` answered 19 for a model that references NONE.
+ *
+ * That is not cosmetic. Both readers of this function treat the result as the
+ * set of packages a model may see: build_d365fo_project orders its build queue
+ * by it, and getModelVisibility turns it into `visiblePackages`, the oracle
+ * resolve_references uses to decide an indexed type is invisible to the model
+ * being compiled. Every phantom entry made that oracle MORE permissive, so the
+ * missing-reference defect it exists to catch was silently waved through —
+ * which is the exact compile-time `classStr`/type failure this module's own
+ * header describes.
+ *
+ * Returns [] for a nil or absent element: a model that references nothing. The
+ * "descriptor unreadable" case is null, and it is readModuleReferences's to
+ * report, not this one's.
  */
 export declare function parseModuleReferences(descriptorXml: string): string[];
 /**
@@ -46,6 +70,119 @@ export interface ModelVisibility {
  * descriptor turning into a wall of errors is worse than the gap it closes.
  */
 export declare function getModelVisibility(packagesRoot: string | null | undefined, modelName: string | null | undefined): ModelVisibility | null;
+/**
+ * Drop the memoised visibility of `modelName` under every root.
+ *
+ * The descriptor writers call this after every successful write. Without it the
+ * oracle keeps the reference set the model had when it was first asked, so
+ * resolve_references goes on reporting `not-visible-from-model` — and telling
+ * the agent to add the very reference it has just added — until the server
+ * restarts; a remove leaves it too permissive the same way.
+ */
+export declare function invalidateModelVisibility(modelName: string): void;
 /** Uncached form — exported for tests, which need a fresh fixture each time. */
 export declare function buildModelVisibility(packagesRoot: string | null | undefined, modelName: string | null | undefined): ModelVisibility | null;
+export type AddModuleReferenceResult = 
+/** Added. `xml` is the updated document. */
+{
+    kind: 'added';
+    xml: string;
+}
+/** Already referenced — refuse rather than write a second `<d2p1:string>`. */
+ | {
+    kind: 'duplicate';
+    existing: string;
+}
+/** No `<ModuleReferences>` element at all; the caller declines rather than inventing one. */
+ | {
+    kind: 'no-element';
+}
+/** Not a package folder name — see isValidModuleReferenceName. */
+ | {
+    kind: 'invalid-name';
+};
+export type RemoveModuleReferenceResult = 
+/** Removed. `xml` is the updated document, `removed` the entry as it was spelled. */
+{
+    kind: 'removed';
+    xml: string;
+    removed: string;
+}
+/** Not referenced. `present` is what IS referenced, for the message. */
+ | {
+    kind: 'not-found';
+    present: string[];
+}
+/** No `<ModuleReferences>` element at all. */
+ | {
+    kind: 'no-element';
+};
+/**
+ * Could `name` be a package folder name?
+ *
+ * Checked before anything is written, because the entry is interpolated into
+ * `<d2p1:string>…</d2p1:string>` verbatim: whitespace inside the name writes an
+ * entry parseModuleReferences cannot read back (so it is neither a detected
+ * duplicate nor removable), an all-blank name writes an empty entry, and `&`/`<`
+ * write a malformed descriptor. Package folders on a real install use letters,
+ * digits and `_`, plus `-` in custom ones (`fm-mcp`); `.` is admitted for
+ * dotted ISV names, but never leading, so the name cannot step out of a
+ * packages root when probed as a folder.
+ */
+export declare function isValidModuleReferenceName(name: string): boolean;
+/**
+ * Add one `<d2p1:string>` entry to `<ModuleReferences>`.
+ *
+ * Idempotent by refusal, matching add-diagnostic-suppression: a duplicate comes
+ * back as 'duplicate' rather than as a silent no-op, because a caller who does
+ * not know the reference is already there learns more from being told than from
+ * a ✅ over an unchanged file. Comparison is case-insensitive — a package folder
+ * name is, and two entries differing only in case are one reference to xppc and
+ * two lines to a reviewer.
+ *
+ * Placement follows the file's OWN convention, the same way the indentation
+ * does. A descriptor that is already sorted gets the entry in sorted position;
+ * one that is not gets it appended.
+ *
+ * An earlier version of this docblock asserted that no shipped descriptor is
+ * sorted and always appended. That was wrong, and measurably so: across the 176
+ * descriptors of a 10.0.2527 PackagesLocalDirectory plus the custom and ISV
+ * roots beside it, 137 of the 173 with two or more references are in ascending
+ * case-insensitive order, and every custom model on the box was among them —
+ * i.e. the sorted convention is the one the files a write actually targets keep.
+ * Appending to a sorted list puts the new entry out of order, which is a line a
+ * reviewer stops at and which the next Visual Studio save silently re-sorts,
+ * turning one intended change into two diffs.
+ *
+ * The 36 unsorted ones (Foundation, SCMControls, several *Integration models)
+ * are left alone rather than tidied: re-sorting a file to add one line to it is
+ * the larger diff, not the smaller one.
+ */
+export declare function addModuleReference(xml: string, moduleName: string): AddModuleReferenceResult;
+/**
+ * Remove one `<d2p1:string>` entry from `<ModuleReferences>`, matched
+ * case-insensitively on its text.
+ *
+ * Removing the LAST entry collapses the element to `<ModuleReferences … />`,
+ * keeping its attributes — the shape a shipped descriptor with no references
+ * actually has, and the one that makes add-then-remove a byte-identical round
+ * trip on a file that started empty. (The one nuance: a list that started
+ * `i:nil="true"` comes back as the self-closing form WITHOUT the nil, because
+ * adding a reference is what dropped it. "No list" and "empty list" both mean
+ * the model references nothing, so nothing is lost.)
+ */
+export declare function removeModuleReference(xml: string, moduleName: string): RemoveModuleReferenceResult;
+/**
+ * Where a model's descriptor actually is under `packagesRoot`, or null when it
+ * is not there — the write side's equivalent of readModuleReferences, which
+ * collapses "no such file" into the same null as "unreadable".
+ *
+ * Reuses findDescriptor's probe order (package == model first, then a bounded
+ * sweep for an ISV model inside a differently-named package) so a write lands on
+ * the file the readers read.
+ */
+export declare function findDescriptorPath(packagesRoot: string, modelName: string): {
+    filePath: string;
+    packageName: string;
+} | null;
 //# sourceMappingURL=modelDescriptor.d.ts.map