d365fo-mcp 1.5.1 → 1.6.0

package/.github/copilot-instructions.md

@@ -0,0 +1,86 @@
+# D365 Finance & Operations X++ Development
+
+<!-- Thin pointer — full rules are delivered via the MCP `xpp_system_instructions` prompt.
+     This file provides only the minimum static context needed when the MCP server
+     is not yet connected or the prompt hasn't been loaded.
+     Serves Claude Code too: copy it to a parent of your solution folders as
+     CLAUDE.md (docs/SETUP.md § Claude Code CLI, Step 3). -->
+
+## Tool Priority
+
+This workspace contains a D365FO MCP server. **Always use the specialized MCP tools** for D365FO objects (`.xml`, `.xpp`, `.rnrproj`, `.label.txt`). Built-in file/search tools are fine for `.cs`, `.json`, `.yml`, `.md`, `.config` files.
+
+## Mandatory First Check
+
+Call `get_workspace_info()` before doing anything with D365FO objects.
+
+| Response | Action |
+|----------|--------|
+| Call fails | STOP. MCP server not connected. Ask user to start it. |
+| `⛔ CONFIGURATION PROBLEM` | STOP. Relay message. Wait for user. |
+| `✅ Configuration looks valid` | Note model name. Proceed. |
+
+## Terminal Prohibition
+
+PowerShell / any terminal command **WILL HANG** in VS 2022 / VS 2026 MCP integration. Never use `run_in_terminal` or generate scripts as a fallback when an MCP tool fails — STOP and report the error verbatim.
+
+## Core Tool Mapping
+
+| Action | Tool |
+|--------|------|
+| Plan an extension before changing code | `prepare(mode="change", goal, objectName, methodName?)` — returns signature, existing CoC wrappers, strategy + `groundingToken` |
+| Plan a new object before creating it | `prepare(mode="create", goal, objectName, objectType)` — returns collision check, naming, EDT/label hints + `groundingToken` |
+| Create a D365FO object | `d365fo_file(action="create")` (never `create_file`) |
+| Edit an existing object | `d365fo_file(action="modify")` (applies immediately — confirm in chat first) |
+| Revert the last write | `undo_last_modification` |
+| Search objects | `search` — multiple via `search(queries[])`, custom-only via `search(scope="extensions")` |
+| Read any object's metadata | `get_object_info(objectType, name, options?)` — objectType ∈ class/table/form/query/view/enum/edt/report/data-entity/menu-item/service/map/config-key/security-policy/macro. 2+ known names: `batch_get_info(objects[])` |
+| Method signature for CoC | `get_method(include="signature")` (already returned by `prepare(mode="change")`) |
+| Validate X++ before write | `validate_code(mode="syntax", code)` — offline BP check, <50 ms |
+| X++ rules & patterns | `get_knowledge(kind="knowledge", topic)` — select grammar, CoC, BP rules, SysOperation, workflow, … |
+| Create a NEW form | `object_patterns(domain="form", action="analyze", recommend={...})` → `object_patterns(domain="form", action="spec", pattern)` → `generate_object(mode="scaffold", objectType="form", cloneFrom=referenceForm, tableMapping={...})` → `object_patterns(domain="form", action="validate", xml)` |
+| Validate form XML against its pattern | `object_patterns(domain="form", action="validate", xml \| formName \| filePath)` — structural errors block form writes (FORM_PATTERN_ENFORCE) |
+| Resolve label / EDT / class refs | `validate_code(mode="references", code)` |
+| Build / BP / Sync | `build_d365fo_project` / `run_bp_check` / `trigger_db_sync` |
+| Error diagnosis | `get_knowledge(kind="error", errorText)` |
+
+## Key Rules
+
+### Workspace & model targeting
+
+1. **The target model comes from `.mcp.json`** — never infer it from search results or object names. The symbol database contains objects from all models (Microsoft + ISV + custom); the model on a search/`get_*_info` result is the source model, not where new files belong.
+
+### Writes & file editing
+
+2. **`d365fo_file` (action=create/modify) applies immediately** (no dry-run / preview). Describe the change in chat and wait for explicit user confirmation ("apply", "ok", "yes") before calling. Revert with `undo_last_modification` (or pass `createBackup=true` to keep a `.bak`).
+3. **Never** use `replace_string_in_file`, `edit_file`, `apply_patch`, or any built-in file-write tool on `.xml` or `.xpp` files — **not even as a fallback** when `d365fo_file(action="modify")` fails. These bypass `IMetadataProvider` and corrupt VS 2022's in-memory model. If `d365fo_file(action="modify")` errors, STOP and report the error verbatim.
+
+### Build automation
+
+4. Never run `build_d365fo_project()` automatically — only on explicit user request ("build", "compile", "check errors").
+
+### X++ correctness (BP-clean code)
+
+5. Never copy default parameter values into CoC wrapper signatures.
+6. Never use `today()` — use `DateTimeUtil::getToday(DateTimeUtil::getUserPreferredTimeZone())`.
+7. Never use hardcoded strings in `Info()` / `warning()` / `error()` — use `@Model:Label` references.
+8. Call `labels(action="search")` before `labels(action="create")` — reuse existing labels.
+
+### Extension naming
+
+9. Extension naming follows `EXTENSION_NAMING_STYLE` (see `get_workspace_info`):
+   - `prefix` (default) → class `{Target}{Prefix}_Extension`, element `{Target}.{Prefix}Extension`
+   - `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.
+
+### Reuse & diff safety
+
+10. **Reuse before creating** — `prepare(mode="change")` lists existing CoC wrappers and event handlers. If an extension or handler class in the custom model already owns the target, add the new method there. Never create a parallel feature-named class (`<Target>_<Feature>_Extension`, `<Form>_<Feature>_EH`) unless the user explicitly asks for a separate class. The suffix comes from `EXTENSION_NAMING_STYLE` / existing artifacts — never from feature, ticket, or customer names; if it cannot be derived, ask.
+11. **The post-write diff must be additive or narrowly targeted** — verify via `review_workspace_changes` (or re-read with `get_*_info`) that no unrelated XML nodes (`<DataSources>`, `<Controls>`, methods, pattern metadata) disappeared. If they did, the edit failed: `undo_last_modification`.
+12. **An example form named by the user is a pattern contract** — keep its pattern family and required scaffolding (datasources, ActionPane/Tab/grid/QuickFilter); missing pattern elements are a failed generation even if the XML is well-formed.
+
+## Full Instructions
+
+The complete X++ rules, query grammar, CoC authoring rules, and workflow details are delivered via the MCP prompt `xpp_system_instructions`. If that prompt is not loaded, request it or consult [src/prompts/systemInstructions.ts](../src/prompts/systemInstructions.ts) directly.
+

package/README.md

@@ -10,7 +10,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
 [![Tests](https://img.shields.io/badge/tests-1400%2B-brightgreen.svg)](docs/TESTING.md)
 <!-- coverage-badge:start -->
-[![Core coverage](https://img.shields.io/badge/core_coverage-100%25-brightgreen.svg)](eval/COVERAGE.md) [![Total coverage](https://img.shields.io/badge/total_coverage-72.7%25-lightgrey.svg)](eval/COVERAGE.md)
+[![Core coverage](https://img.shields.io/badge/core_coverage-100%25-brightgreen.svg)](eval/COVERAGE.md) [![Total coverage](https://img.shields.io/badge/total_coverage-85.9%25-lightgrey.svg)](eval/COVERAGE.md)
 <!-- coverage-badge:end -->
 
 *Grounded AI development for Dynamics 365 Finance & Operations — works with GitHub Copilot and Claude Code*

package/bridge/D365MetadataBridge/D365MetadataBridge.csproj

@@ -23,10 +23,18 @@
 
   <!--
     D365FO bin directory — contains all Microsoft.Dynamics.*.dll assemblies.
-    Every D365FO development desktop has this directory available.
+    Every D365FO development desktop has this directory available, but WHICH
+    volume it sits on is decided by the VM image: K: on cloud-hosted
+    environments, C: on the downloadable VHD, J: on newer images (#769), and
+    nothing stops the next image from using another letter again.
+
+    So the drive is swept rather than guessed: the first
+    <drive>:\AosService\PackagesLocalDirectory\bin that exists wins, with the
+    historically standard letters tried first and the rest of the alphabet
+    after them. MSBuild has no loop at evaluation time, and the property has to
+    be resolved before Reference items are globbed — hence one line per letter.
+    A: and B: are left out on purpose (floppy letters stall the probe).
 
-    Traditional VM:  K:\AosService\PackagesLocalDirectory\bin
-    Cloud-hosted:    C:\AosService\PackagesLocalDirectory\bin
     UDE (Unified Developer Experience): path from .mcp.json microsoftPackagesPath/bin
 
     Override per-machine via:
@@ -36,6 +44,28 @@
   <PropertyGroup>
     <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('K:\AosService\PackagesLocalDirectory\bin')">K:\AosService\PackagesLocalDirectory\bin</D365BinPath>
     <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('C:\AosService\PackagesLocalDirectory\bin')">C:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('J:\AosService\PackagesLocalDirectory\bin')">J:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('I:\AosService\PackagesLocalDirectory\bin')">I:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('D:\AosService\PackagesLocalDirectory\bin')">D:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('E:\AosService\PackagesLocalDirectory\bin')">E:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('F:\AosService\PackagesLocalDirectory\bin')">F:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('G:\AosService\PackagesLocalDirectory\bin')">G:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('H:\AosService\PackagesLocalDirectory\bin')">H:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('L:\AosService\PackagesLocalDirectory\bin')">L:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('M:\AosService\PackagesLocalDirectory\bin')">M:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('N:\AosService\PackagesLocalDirectory\bin')">N:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('O:\AosService\PackagesLocalDirectory\bin')">O:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('P:\AosService\PackagesLocalDirectory\bin')">P:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('Q:\AosService\PackagesLocalDirectory\bin')">Q:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('R:\AosService\PackagesLocalDirectory\bin')">R:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('S:\AosService\PackagesLocalDirectory\bin')">S:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('T:\AosService\PackagesLocalDirectory\bin')">T:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('U:\AosService\PackagesLocalDirectory\bin')">U:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('V:\AosService\PackagesLocalDirectory\bin')">V:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('W:\AosService\PackagesLocalDirectory\bin')">W:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('X:\AosService\PackagesLocalDirectory\bin')">X:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('Y:\AosService\PackagesLocalDirectory\bin')">Y:\AosService\PackagesLocalDirectory\bin</D365BinPath>
+    <D365BinPath Condition="'$(D365BinPath)' == '' And Exists('Z:\AosService\PackagesLocalDirectory\bin')">Z:\AosService\PackagesLocalDirectory\bin</D365BinPath>
   </PropertyGroup>
 
   <!-- NuGet packages -->

package/bridge/D365MetadataBridge/Program.cs

@@ -416,7 +416,7 @@ Usage:
   D365MetadataBridge.exe [options]
 
 Options:
-  --packages-path <path>            Path to primary PackagesLocalDirectory (default: K:\AosService\PackagesLocalDirectory)
+  --packages-path <path>            Path to primary PackagesLocalDirectory (required; the server detects it per machine)
   --reference-packages-path <path>  UDE: secondary packages path (Microsoft FrameworkDirectory). Objects not found in
                                     the primary path are looked up here, enabling resolution of both custom and
                                     Microsoft-shipped metadata in UDE environments.

package/dist/bridge/bridgeAdapter.d.ts

@@ -358,7 +358,7 @@ export declare function bridgeDiscoverFormPatterns(bridge: BridgeClient | undefi
 export declare function tryBridgeSecurityArtifact(bridge: BridgeClient | undefined, name: string, artifactType: 'privilege' | 'duty' | 'role', includeChain: boolean): Promise<ToolResult | null>;
 export declare function tryBridgeMenuItem(bridge: BridgeClient | undefined, name: string, itemType?: string): Promise<ToolResult | null>;
 export declare function tryBridgeTableExtensions(bridge: BridgeClient | undefined, baseTableName: string): Promise<ToolResult | null>;
-export declare function tryBridgeCompletion(bridge: BridgeClient | undefined, symbolName: string, prefix?: string): Promise<ToolResult | null>;
+export declare function tryBridgeCompletion(bridge: BridgeClient | undefined, symbolName: string, prefix?: string, ancestors?: string[]): Promise<ToolResult | null>;
 export declare function tryBridgeCocExtensions(bridge: BridgeClient | undefined, baseClassName: string, methodName?: string): Promise<ToolResult | null>;
 export declare function tryBridgeEventHandlers(bridge: BridgeClient | undefined, targetName: string, eventName?: string, handlerType?: string): Promise<ToolResult | null>;
 export declare function tryBridgeApiUsageCallers(bridge: BridgeClient | undefined, apiName: string, limit?: number): Promise<ToolResult | null>;

package/dist/bridge/bridgeAdapter.js

@@ -1911,13 +1911,38 @@ function formatTableExtensions(r) {
     return out;
 }
 // CODE COMPLETION (Phase 6)
-export async function tryBridgeCompletion(bridge, symbolName, prefix) {
+export async function tryBridgeCompletion(bridge, symbolName, prefix, ancestors) {
     if (!bridge?.isReady || !bridge.metadataAvailable)
         return null;
     try {
         const result = await bridge.getCompletionMembers(symbolName);
         if (!result || !result.members || result.members.length === 0)
             return null;
+        // IMetadataProvider returns DECLARED members only, so a subclass lists
+        // nothing it inherits and the reader concludes the member does not exist.
+        // Merge the base classes in, nearest first; a name already present wins,
+        // since that is the subclass's own override.
+        if (ancestors?.length) {
+            const seen = new Set(result.members.map(m => m.name.toLowerCase()));
+            for (const ancestor of ancestors) {
+                let inherited = null;
+                try {
+                    inherited = await bridge.getCompletionMembers(ancestor);
+                }
+                catch (e) {
+                    // One unreadable link must not discard the members already merged.
+                    console.error(`[BridgeAdapter] getCompletionMembers(${ancestor}) failed: ${e}`);
+                    continue;
+                }
+                for (const m of inherited?.members ?? []) {
+                    const key = m.name.toLowerCase();
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    result.members.push({ ...m, inheritedFrom: inherited?.symbolName || ancestor });
+                }
+            }
+        }
         return { content: [{ type: 'text', text: formatCompletion(result, prefix) }] };
     }
     catch (e) {
@@ -1943,9 +1968,15 @@ function formatCompletion(r, prefix) {
     const methodMembers = members.filter(m => m.kind === 'method');
     const fieldMembers = members.filter(m => m.kind === 'field');
     if (methodMembers.length > 0) {
+        const inheritedCount = methodMembers.filter(m => m.inheritedFrom).length;
         out += `## Methods (${methodMembers.length})\n`;
         for (const m of methodMembers) {
-            out += m.signature ? `- \`${m.signature}\`\n` : `- ${m.name}\n`;
+            const body = m.signature ? `\`${m.signature}\`` : m.name;
+            out += m.inheritedFrom ? `- ${body} _(inherited from ${m.inheritedFrom})_\n` : `- ${body}\n`;
+        }
+        if (inheritedCount > 0) {
+            out += `\n> ${inheritedCount} of these are inherited — callable on ${r.symbolName}, but ` +
+                `declared on a base class. To read or wrap one, target the class named beside it.\n`;
         }
     }
     if (fieldMembers.length > 0) {

package/dist/bridge/bridgeClient.d.ts

@@ -19,7 +19,7 @@ export * from './bridgeTypes.js';
 export interface BridgeClientOptions {
     /** Path to the D365MetadataBridge.exe (auto-detected if omitted) */
     bridgeExePath?: string;
-    /** K:\AosService\PackagesLocalDirectory */
+    /** e.g. K:\AosService\PackagesLocalDirectory — the volume varies by VM image */
     packagesPath: string;
     /**
      * Optional secondary packages path.

package/dist/bridge/bridgeClient.js

@@ -17,6 +17,7 @@ import { EventEmitter } from 'events';
 import * as path from 'path';
 import * as fs from 'fs';
 import { fileURLToPath } from 'url';
+import { packagesRoots } from '../utils/packagesRoot.js';
 export * from './bridgeTypes.js';
 const BRIDGE_EXE_NAME = 'D365MetadataBridge.exe';
 /** Parse a positive-integer env var with a fallback (ignores invalid/non-positive values). */
@@ -751,11 +752,8 @@ function detectPackagesPath() {
     const candidates = [
         process.env.D365FO_PACKAGE_PATH ?? '',
         process.env.PACKAGES_PATH ?? '',
-        // Well-known fallback locations (traditional D365FO VM layouts)
-        'C:\\AosService\\PackagesLocalDirectory',
-        'C:\\AOSService\\PackagesLocalDirectory',
-        'J:\\AosService\\PackagesLocalDirectory',
-        'K:\\AosService\\PackagesLocalDirectory',
+        // Whatever AosService volumes this machine actually has (C:, J:, K:, …)
+        ...packagesRoots(),
     ].filter(Boolean);
     for (const p of candidates) {
         // Traditional: bin is directly under packagesPath

package/dist/bridge/bridgeTypes.d.ts

@@ -92,6 +92,14 @@ export interface BridgeMethodInfo {
     returnType?: string;
     source?: string;
     isStatic?: boolean;
+    /**
+     * ⚠️ Never sent by the bridge. The C# MethodInfoModel behind readClass carries
+     * only name/source/isStatic, so this is always undefined on bridge-sourced
+     * methods — it is populated exclusively by the XML parser path
+     * (xmlParser.parseClassFile). Reading it off a readClass result silently
+     * yields nothing; for a bridge-sourced modifier parse the declaration line out
+     * of getCompletionMembers().members[].signature instead.
+     */
     visibility?: string;
 }
 export interface BridgeEnumInfo {
@@ -499,6 +507,13 @@ export interface BridgeCompletionMember {
     name: string;
     signature?: string;
     kind: string;
+    /**
+     * Set by the caller (not the bridge) when the member was picked up from a
+     * base class rather than declared on the requested one. IMetadataProvider
+     * returns declared members only, so inherited members are merged in on the
+     * TypeScript side and tagged here.
+     */
+    inheritedFrom?: string;
 }
 export interface BridgeCompletionResult {
     symbolName: string;

package/dist/cli/commands/doctor.js

@@ -16,6 +16,7 @@ import { checkRelease } from '../npmRegistry.js';
 import { conflictingLegacyValues, readPath, readSetting } from '../settingsStore.js';
 import { instanceTarget, rootTarget } from '../target.js';
 import { isXppConfigStale, listXppConfigs, xppConfigDir } from '../xppConfig.js';
+import { describePackagesRootScan, packagesRoots } from '../../utils/packagesRoot.js';
 const REQUIRED_NODE_MAJOR = 24;
 /**
  * How to reach the wizard from here. `npm run setup` only exists in a checkout
@@ -74,6 +75,40 @@ function checkConfig(target, label) {
         fix: SETUP_COMMAND,
     };
 }
+/**
+ * The configured packages root against what the machine actually has.
+ *
+ * A packagePath pointing at a drive this image does not use is the failure
+ * behind "setup can't find the namespaces" (#769) — the index then builds from
+ * nothing and every lookup comes back empty, with no error saying why. Naming
+ * the detected volume turns that into a one-line fix.
+ */
+function checkPackagesRoot(store, label) {
+    if (!isWindows)
+        return [];
+    const configured = String(readSetting(store, settingByPath('environment.packagePath')) ?? '').trim();
+    const detected = packagesRoots();
+    if (!configured) {
+        // UDE resolves its roots from the XPP config, so silence here is normal.
+        if (detected.length === 0)
+            return [];
+        return [{
+                severity: 'info',
+                message: `${label}: packages root not configured — the server will use ${detected[0]}`,
+            }];
+    }
+    if (fs.existsSync(configured)) {
+        return [{ severity: 'ok', message: `${label}: packages root OK (${configured})` }];
+    }
+    return [{
+            severity: 'fail',
+            message: `${label}: packages root does not exist (${configured})` +
+                (detected.length > 0 ? `\n   found instead: ${detected.join(', ')}` : `\n   ${describePackagesRootScan()}`),
+            fix: detected.length > 0
+                ? `set environment.packagePath to ${detected[0]} (${SETUP_COMMAND})`
+                : `point environment.packagePath at this machine's PackagesLocalDirectory (${SETUP_COMMAND})`,
+        }];
+}
 /** A legacy .env that disagrees with the config is a trap: the config wins. */
 function legacyEnvChecks(target, label) {
     if (!target.envFile || !fs.existsSync(target.store.configPath))
@@ -205,6 +240,8 @@ export async function doctorCommand() {
     emit(checkConfig(root, 'Root'));
     for (const r of legacyEnvChecks(root, 'Root'))
         emit(r);
+    for (const r of checkPackagesRoot(root.store, 'Root'))
+        emit(r);
     // Database (root)
     emit(checkDb(root.store, paths.defaultDb, 'Root'));
     // C# bridge: the only write path; Windows-only.
@@ -246,6 +283,8 @@ export async function doctorCommand() {
                 emit(r);
             for (const r of legacyEnvChecks(target, `Instance '${inst.name}'`))
                 emit(r);
+            for (const r of checkPackagesRoot(target.store, `Instance '${inst.name}'`))
+                emit(r);
             emit(checkDb(target.store, resolve(inst.dir, 'data', 'xpp-metadata.db'), `Instance '${inst.name}'`));
             if (isWindows && isXppConfigStale(target.store)) {
                 emit({

package/dist/cli/commands/instance.js

@@ -8,6 +8,7 @@ import * as fs from 'node:fs';
 import { resolve } from 'node:path';
 import { settingByPath, settingsInSection } from '../../config/settings.js';
 import { pinBridgeExe } from '../bridgePath.js';
+import { maybePrepareCopilotInstructions } from '../copilotFiles.js';
 import { createInstance, getInstance, listInstances, normalizeInstanceLayout, suggestPort } from '../instances.js';
 import { mcpJsonNote, placementNote, stdioServer } from '../mcpJson.js';
 import { selectXppConfig } from './config.js';
@@ -16,6 +17,7 @@ import { openInstanceStore, readPath, readSetting, saveStore, writeSetting } fro
 import { instanceTarget } from '../target.js';
 import { askConfirm, askSelect, askText, p } from '../ui.js';
 import { listXppConfigs, xppConfigDir } from '../xppConfig.js';
+import { findPackagesRoot } from '../../utils/packagesRoot.js';
 import { rebuildIndex } from './indexCmd.js';
 const dbPathSetting = settingByPath('index.dbPath');
 const xppConfigNameSetting = settingByPath('environment.xppConfigName');
@@ -92,17 +94,25 @@ export async function instanceAddCommand(name, portArg) {
         await selectXppConfig(store);
     }
     else {
-        await askSetting(store, settingByPath('environment.packagePath'), { required: true });
+        await askSetting(store, settingByPath('environment.packagePath'), {
+            required: true,
+            initial: findPackagesRoot() ?? undefined,
+        });
         await askSetting(store, settingByPath('environment.customModels'), { required: true });
     }
     p.log.step('Workspace and naming');
     await askSetting(store, settingByPath('workspace.modelName'));
     await askSetting(store, settingByPath('workspace.path'));
+    await askSetting(store, settingByPath('workspace.solutionsPath'));
     await askSettings(store, settingsInSection('naming', 'basic'));
     p.log.step('Metadata index');
     await askSettings(store, settingsInSection('index', 'basic'));
     await askAdvanced(store, ['environment', 'workspace', 'index', 'server', 'bridge', 'behavior']);
     saveStore(store);
+    // Copilot needs the instructions file just as much as it needs .mcp.json,
+    // and an instance is somebody's only setup run — asking here is the only
+    // chance scenario F gets.
+    await maybePrepareCopilotInstructions(String(readSetting(store, settingByPath('workspace.solutionsPath')) ?? ''));
     // Both ways to reach this instance: the IDE spawning it over stdio with its
     // own config, or an HTTP client on the port it was given.
     mcpJsonNote({

package/dist/cli/commands/setup.js

@@ -15,10 +15,12 @@ import { DOTNET_MISSING, dataRoot, installMode, isWindows, paths, repoRoot, setD
 import { settingByPath, settingsInSection } from '../../config/settings.js';
 import { commandExists, runExe, runShell } from '../exec.js';
 import { pinBridgeExe } from '../bridgePath.js';
+import { maybePrepareCopilotInstructions } from '../copilotFiles.js';
 import { mcpJsonNote, placementNote, stdioServer } from '../mcpJson.js';
 import { checkRelease } from '../npmRegistry.js';
 import { askAdvanced, askSecrets, askSetting, askSettings } from '../settingsPrompt.js';
 import { migrateLegacyEnv, openStore, readSetting, saveStore, writeSetting } from '../settingsStore.js';
+import { findPackagesRoot } from '../../utils/packagesRoot.js';
 import { rootTarget } from '../target.js';
 import { askConfirm, askSelect, askText, p, requireFullInstall } from '../ui.js';
 import { listXppConfigs } from '../xppConfig.js';
@@ -187,7 +189,13 @@ async function configureEnvironment(store, scenario) {
         }
         return 'ude';
     }
-    await askSetting(store, setting('environment.packagePath'), { required: true });
+    // Offer the AosService volume this machine actually has. Which drive that is
+    // differs per VM image (K:, C:, J:, …), and a wrong guess is what turns the
+    // rest of setup into "no namespaces found" (#769).
+    const detected = findPackagesRoot();
+    if (detected)
+        p.log.success(`Found PackagesLocalDirectory at ${detected}`);
+    await askSetting(store, setting('environment.packagePath'), { required: true, initial: detected ?? undefined });
     await askSetting(store, setting('environment.customModels'), { required: true });
     return 'traditional';
 }
@@ -198,6 +206,10 @@ async function configureWorkspace(store, scenario) {
     await askSetting(store, setting('workspace.path'), { required: scenario === 'hybrid' || scenario === 'ude' });
     await askSetting(store, setting('workspace.solutionsPath'));
 }
+/** Where the user keeps the .sln folders — the copy target for the client files. */
+function solutionsPath(store) {
+    return String(readSetting(store, setting('workspace.solutionsPath')) ?? '');
+}
 async function configureNaming(store) {
     p.log.step('Naming');
     await askSettings(store, settingsInSection('naming', 'basic'));
@@ -216,67 +228,6 @@ async function maybeBuildIndex() {
     }
     return rebuildIndex(rootTarget());
 }
-function writeCopilotSetupReadme(stageDir, includeLocalMcpCopy) {
-    const readmePath = resolve(stageDir, 'README.md');
-    const lines = [
-        '# VS setup quick guide',
-        '',
-        'This folder is generated by `d365fo-mcp setup` to simplify Visual Studio onboarding.',
-        '',
-        '1. Copy .mcp.json',
-        '   - Recommended (all solutions): %USERPROFILE%\\.mcp.json',
-        '   - Per solution: place .mcp.json next to your .sln file',
-        includeLocalMcpCopy
-            ? '   - Local copy prepared here: .mcp.json'
-            : `   - Local copy path: ${paths.mcpSuggestion}`,
-        '',
-        '2. Copy .github/copilot-instructions.md',
-        '   - Destination: a parent folder of your solution directories',
-        '   - Why: provides mandatory D365FO tool-routing and safety rules for Copilot',
-        '',
-        '3. Restart Visual Studio after copying files.',
-    ];
-    fs.writeFileSync(readmePath, lines.join('\n') + '\n', 'utf8');
-}
-async function maybePrepareCopilotInstructions(store) {
-    const source = resolve(repoRoot, '.github', 'copilot-instructions.md');
-    if (!fs.existsSync(source)) {
-        p.log.warn('Cannot find .github\\copilot-instructions.md in the package; skipping copy helper.');
-        return {};
-    }
-    const wantsDirectCopy = await askConfirm('Create/copy .github/copilot-instructions.md into the solutions folder now?', true);
-    const solutionsPath = String(readSetting(store, setting('workspace.solutionsPath')) ?? '').trim();
-    if (wantsDirectCopy && solutionsPath) {
-        const targetDir = resolve(solutionsPath, '.github');
-        fs.mkdirSync(targetDir, { recursive: true });
-        fs.copyFileSync(source, resolve(targetDir, 'copilot-instructions.md'));
-        p.log.success(`Prepared: ${resolve(targetDir, 'copilot-instructions.md')}`);
-        return {};
-    }
-    const stageDir = resolve(dataRoot(), 'copilot-setup');
-    const stageGitHubDir = resolve(stageDir, '.github');
-    fs.mkdirSync(stageGitHubDir, { recursive: true });
-    fs.copyFileSync(source, resolve(stageGitHubDir, 'copilot-instructions.md'));
-    writeCopilotSetupReadme(stageDir, false);
-    if (wantsDirectCopy && !solutionsPath) {
-        p.log.warn('Solutions folder is empty, so files were prepared in the local staging folder instead.');
-    }
-    else {
-        p.log.info('Copy was skipped; files were prepared in a local staging folder for later use.');
-    }
-    p.log.info(`Staging folder: ${stageDir}`);
-    return { stagingDir: stageDir };
-}
-function finalizeStagedCopilotFiles(plan) {
-    if (!plan.stagingDir)
-        return;
-    const localMcp = paths.mcpSuggestion;
-    if (fs.existsSync(localMcp)) {
-        fs.copyFileSync(localMcp, resolve(plan.stagingDir, '.mcp.json'));
-        writeCopilotSetupReadme(plan.stagingDir, true);
-        p.log.success(`Prepared: ${resolve(plan.stagingDir, '.mcp.json')}`);
-    }
-}
 export function savedNote(store) {
     const rel = relative(dataRoot(), store.configPath) || store.configPath;
     const lines = [`Settings written to ${rel}`];
@@ -332,7 +283,7 @@ export async function setupCommand() {
         const url = await askText({ message: 'Azure server URL', placeholder: 'https://your-server.azurewebsites.net/mcp/', required: true });
         await configureEnvironment(store, scenario);
         await configureWorkspace(store, scenario);
-        const copilotPlan = await maybePrepareCopilotInstructions(store);
+        await maybePrepareCopilotInstructions(solutionsPath(store));
         await configureNaming(store);
         await askSecrets(store, ['behavior']);
         await askAdvanced(store, ['environment', 'workspace', 'naming', 'bridge', 'behavior', 'server']);
@@ -342,7 +293,6 @@ export async function setupCommand() {
             'd365fo-azure': { url },
             'd365fo-local': stdioServer(store),
         });
-        finalizeStagedCopilotFiles(copilotPlan);
         placementNote();
         p.outro('Hybrid setup complete — no local index needed (Azure serves the search).');
         return;
@@ -351,7 +301,7 @@ export async function setupCommand() {
     writeSetting(store, setting('server.mode'), 'full');
     await configureEnvironment(store, scenario);
     await configureWorkspace(store, scenario);
-    const copilotPlan = await maybePrepareCopilotInstructions(store);
+    await maybePrepareCopilotInstructions(solutionsPath(store));
     await configureNaming(store);
     await configureIndex(store);
     let port = Number(readSetting(store, setting('server.port')) ?? 8080);
@@ -369,7 +319,6 @@ export async function setupCommand() {
     }
     if (scenario === 'local-http') {
         mcpJsonNote({ 'd365fo-mcp-tools': { url: `http://localhost:${port}/mcp/` } });
-        finalizeStagedCopilotFiles(copilotPlan);
         placementNote();
         p.outro('Done. Start the server with: d365fo-mcp start');
         return;
@@ -377,7 +326,6 @@ export async function setupCommand() {
     // D / E — the IDE spawns dist/index.js itself and is pointed at the config
     // file; every other setting comes from there.
     mcpJsonNote({ 'd365fo-mcp-tools': stdioServer(store) });
-    finalizeStagedCopilotFiles(copilotPlan);
     placementNote();
     p.outro('Done. VS spawns the server automatically — no manual start needed.');
 }

package/dist/cli/copilotFiles.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Offer to place copilot-instructions.md, falling back to a staging folder.
+ *
+ * `solutionsPath` is what the user gave for workspace.solutionsPath; when it
+ * is empty there is nowhere to copy to, so the file is staged instead and the
+ * README says where it has to end up.
+ */
+export declare function maybePrepareCopilotInstructions(solutionsPath: string): Promise<void>;
+//# sourceMappingURL=copilotFiles.d.ts.map