d365fo-mcp 1.10.0 → 1.11.0

package/dist/bridge/bridgeAdapter.js

@@ -25,7 +25,7 @@ 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 { pageFields, fieldsHeading, fieldsFooter, createControlBudget, chargeControl, chargeSkippedSubtree, controlsFooter, } from '../utils/payloadBudget.js';
 // TABLE
@@ -176,11 +176,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`;

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

package/dist/cli/commands/doctor.js

@@ -13,7 +13,7 @@ import { bridgeBuildCommand, dataRoot, installMode, isWindows, paths, repoRoot }
 import { commandExists } from '../exec.js';
 import { isLegacyInstanceLayout, listInstances } from '../instances.js';
 import { checkRelease } from '../npmRegistry.js';
-import { conflictingLegacyValues, readPath, readSetting } from '../settingsStore.js';
+import { conflictingLegacyValues, readPath, readSetting, settingSource } from '../settingsStore.js';
 import { instanceTarget, rootTarget } from '../target.js';
 import { isXppConfigStale, listXppConfigs, xppConfigDir } from '../xppConfig.js';
 import { describePackagesRootScan, packagesRoots } from '../../utils/packagesRoot.js';
@@ -89,8 +89,8 @@ function checkConfig(target, label) {
 function checkPackagesRoot(store, label) {
     if (!isWindows)
         return [];
-    const configured = String(readSetting(store, settingByPath('environment.packagePath')) ?? '').trim();
     const detected = packagesRoots();
+    const configured = String(readSetting(store, settingByPath('environment.packagePath')) ?? '').trim();
     if (!configured) {
         // UDE resolves its roots from the XPP config, so silence here is normal.
         if (detected.length === 0)
@@ -100,18 +100,124 @@ function checkPackagesRoot(store, label) {
                 message: `${label}: packages root not configured — the server will use ${detected[0]}`,
             }];
     }
+    return checkPathSetting(store, label, 'environment.packagePath');
+}
+/**
+ * One configured path setting against what the machine actually has.
+ *
+ * Unset is silent: for the two UDE roots that is the normal and recommended
+ * state (they resolve live from the active XPP config, which is how the server
+ * notices a platform update), and packagePath has its own not-configured
+ * branch above.
+ */
+function checkPathSetting(store, label, settingPath) {
+    if (!isWindows)
+        return [];
+    const setting = settingByPath(settingPath);
+    const facts = PATH_FACTS[settingPath];
+    const configured = String(readSetting(store, setting) ?? '').trim();
+    if (!configured)
+        return [];
     if (fs.existsSync(configured)) {
-        return [{ severity: 'ok', message: `${label}: packages root OK (${configured})` }];
+        return [{ severity: 'ok', message: `${label}: ${facts.humanName} 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})`,
+            ...missingPathFix(setting, facts, label, configured, environmentKind(store), settingSource(store, setting) === 'env'),
         }];
 }
+/**
+ * Which of the two this install is. The configured value wins; with nothing
+ * configured this falls back to the same XPP-config detection the server itself
+ * uses (see environment.type in config/settings.ts), so doctor's diagnosis
+ * matches the runtime's behaviour rather than a second guess at it.
+ */
+function environmentKind(store) {
+    const configured = String(readSetting(store, settingByPath('environment.type')) ?? '').trim().toLowerCase();
+    if (configured === 'ude' || configured === 'traditional')
+        return configured;
+    return listXppConfigs().length > 0 ? 'ude' : 'traditional';
+}
+export const PATH_FACTS = {
+    'environment.packagePath': {
+        humanName: 'packages root',
+        autoSource: kind => kind === 'ude'
+            ? 'the active XPP config'
+            : (packagesRoots().length > 0 ? 'the drive scan for AosService\\PackagesLocalDirectory' : null),
+        // On UDE the XPP config is the authority; a stray empty C:\AosService stub
+        // is exactly the wrong thing to propose there.
+        candidates: kind => kind === 'ude' ? [] : packagesRoots(),
+        target: () => "this machine's PackagesLocalDirectory",
+        note: kind => kind === 'ude' ? null : describePackagesRootScan(),
+    },
+    'environment.customPackagesPath': {
+        humanName: 'custom X++ root',
+        // Traditional: not auto-detected at all. It is a deliberate pin naming the
+        // repo that holds custom metadata outside PackagesLocalDirectory.
+        autoSource: kind => kind === 'ude' ? 'the active XPP config (ModelStoreFolder)' : null,
+        candidates: () => [],
+        target: kind => kind === 'ude'
+            ? 'the ModelStoreFolder of the active XPP config'
+            : 'the folder your custom model metadata actually lives in',
+        note: () => null,
+    },
+    'environment.microsoftPackagesPath': {
+        humanName: 'Microsoft X++ root',
+        autoSource: kind => kind === 'ude' ? 'the active XPP config (FrameworkDirectory)' : null,
+        candidates: () => [],
+        target: () => 'the read-only Microsoft packages folder (FrameworkDirectory)',
+        note: kind => kind === 'ude' ? null : 'this setting applies to UDE installs only',
+    },
+};
+/**
+ * "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 function missingPathFix(setting, facts, label, configured, kind, pinnedByEnv) {
+    const auto = facts.autoSource(kind);
+    const candidates = facts.candidates(kind);
+    const note = candidates.length > 0 ? `found instead: ${candidates.join(', ')}` : facts.note(kind);
+    const message = `${label}: ${facts.humanName} does not exist (${configured})` +
+        (pinnedByEnv ? `\n   pinned by legacy .env (${setting.env}), not the JSON config` : '') +
+        (note ? `\n   ${note}` : '');
+    // Deleting the key IS the whole fix here: the value it hides is already right.
+    if (pinnedByEnv && auto) {
+        return {
+            message,
+            fix: `remove ${setting.env} from .env — ${facts.humanName} is resolved from ${auto}, and a hardcoded ` +
+                `copy silently overrides that once a platform update moves or deletes the folder`,
+        };
+    }
+    const dropEnvFirst = pinnedByEnv ? `remove ${setting.env} from .env, then set` : `set`;
+    if (candidates.length > 0) {
+        return { message, fix: `${dropEnvFirst} ${setting.path} to ${candidates[0]} (${SETUP_COMMAND})` };
+    }
+    if (auto) {
+        // Naming `target` again here would only repeat `auto` in other words — on
+        // UDE the folder to point at IS the one the XPP config would have supplied.
+        return {
+            message,
+            fix: `clear ${setting.path} so it resolves from ${auto}, or repoint it if this install genuinely ` +
+                `keeps ${facts.humanName} elsewhere (${SETUP_COMMAND})`,
+        };
+    }
+    // Nothing would resolve this value on its own, so the pin is the configuration
+    // — it needs correcting, not deleting.
+    return {
+        message,
+        fix: `point ${setting.path} at ${facts.target(kind)} (${SETUP_COMMAND})` +
+            (pinnedByEnv ? `, and note that ${setting.env} in .env currently outranks the JSON config` : ''),
+    };
+}
 /**
  * Which detection source resolves the workspace — and which model it lands on.
  *
@@ -160,10 +266,36 @@ async function checkWorkspaceDetection(store, label) {
  * 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 function checkPrefixResolution(configuredPrefix, modelName, modelObjectNames, label) {
+export function checkPrefixResolution(configuredPrefix, modelName, modelObjectNames, label, pinned = false) {
     const inferred = modelName ? inferPrefixFromObjectNames(modelObjectNames, modelName) : null;
     const bare = (s) => s.replace(/_+$/, '').toLowerCase();
+    if (pinned) {
+        // Inference is off, so naming.prefix is the whole answer — and an empty one
+        // is worse here than anywhere else: pinning it leaves nothing to fall back
+        // to but the model name.
+        if (!configuredPrefix) {
+            return [{
+                    severity: 'warn',
+                    message: `${label}: naming.prefixSource=config pins the configured prefix, but naming.prefix is empty ` +
+                        `— new objects will be prefixed with the model name`,
+                    fix: `set naming.prefix to your ISV prefix (${SETUP_COMMAND})`,
+                }];
+        }
+        const ignored = inferred?.regular && bare(inferred.regular) !== bare(configuredPrefix)
+            ? ` — model "${modelName}"'s objects use "${inferred.regular}", ignored while the prefix is pinned`
+            : '';
+        return [{
+                severity: 'ok',
+                message: `${label}: prefix "${configuredPrefix}" (naming.prefix, pinned by naming.prefixSource=config)${ignored}`,
+            }];
+    }
     if (!inferred?.regular) {
         if (!configuredPrefix) {
             return [{
@@ -185,7 +317,8 @@ export function checkPrefixResolution(configuredPrefix, modelName, modelObjectNa
             message: `${label}: prefix conflict — model "${modelName}"'s objects use "${inferred.regular}" ` +
                 `(${inferred.coverage}/${inferred.sampleSize}), naming.prefix says "${configuredPrefix}". ` +
                 `The model's own naming wins, so new objects are named "${inferred.regular}…".`,
-            fix: 'EXTENSION_PREFIX_SOURCE=config pins the configured value instead',
+            fix: `set naming.prefixSource=config to pin the configured value instead (${SETUP_COMMAND}, or ` +
+                `EXTENSION_PREFIX_SOURCE=config in the environment)`,
         }];
 }
 /**
@@ -348,6 +481,10 @@ export async function doctorCommand() {
         emit(r);
     for (const r of checkPackagesRoot(root.store, 'Root'))
         emit(r);
+    for (const r of checkPathSetting(root.store, 'Root', 'environment.customPackagesPath'))
+        emit(r);
+    for (const r of checkPathSetting(root.store, 'Root', 'environment.microsoftPackagesPath'))
+        emit(r);
     // Database (root)
     emit(checkDb(root.store, paths.defaultDb, 'Root'));
     // Which source resolves the workspace, and the prefix that follows from it —
@@ -359,7 +496,11 @@ export async function doctorCommand() {
     const names = detection.modelName
         ? await modelObjectNames(readPath(root.store, settingByPath('index.dbPath'), paths.defaultDb), detection.modelName)
         : [];
-    for (const r of checkPrefixResolution(configuredPrefix, detection.modelName, names, 'Naming'))
+    // Same precedence the server applies: the real environment outranks the
+    // config file (loadEnv), and the CLI never projects one onto the other.
+    const prefixSource = (process.env.EXTENSION_PREFIX_SOURCE
+        ?? String(readSetting(root.store, settingByPath('naming.prefixSource')) ?? '')).trim().toLowerCase();
+    for (const r of checkPrefixResolution(configuredPrefix, detection.modelName, names, 'Naming', prefixSource === 'config'))
         emit(r);
     // C# bridge: the only write path; Windows-only.
     if (isWindows) {
@@ -402,6 +543,10 @@ export async function doctorCommand() {
                 emit(r);
             for (const r of checkPackagesRoot(target.store, `Instance '${inst.name}'`))
                 emit(r);
+            for (const r of checkPathSetting(target.store, `Instance '${inst.name}'`, 'environment.customPackagesPath'))
+                emit(r);
+            for (const r of checkPathSetting(target.store, `Instance '${inst.name}'`, 'environment.microsoftPackagesPath'))
+                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/settingsStore.d.ts

@@ -19,6 +19,13 @@ export interface SettingsStore {
 export declare function openStore(baseDir: string, legacyEnvFile: string | null, fallbackConfigPath?: string): SettingsStore;
 /** Store rooted at an instance folder: instances/<name>/d365fo-mcp.json. */
 export declare function openInstanceStore(instanceDir: string): SettingsStore;
+/**
+ * Where a setting's effective value actually comes from — the JSON config,
+ * the legacy .env fallback, or nowhere. Mirrors readSetting's own precedence
+ * so callers can tell "explicitly configured" apart from "inherited from a
+ * .env that may have gone stale" without re-deriving the value themselves.
+ */
+export declare function settingSource(store: SettingsStore, setting: Setting): 'config' | 'env' | 'none';
 /** Effective value of a setting, or undefined when nothing configures it. */
 export declare function readSetting(store: SettingsStore, setting: Setting): unknown;
 /** Effective value, falling back to the documented default. */

package/dist/cli/settingsStore.js

@@ -35,6 +35,26 @@ export function openInstanceStore(instanceDir) {
     // layout (not the config/ repo layout) so listInstances() can find it.
     return openStore(instanceDir, join(instanceDir, '.env'), join(instanceDir, 'd365fo-mcp.json'));
 }
+/**
+ * Where a setting's effective value actually comes from — the JSON config,
+ * the legacy .env fallback, or nowhere. Mirrors readSetting's own precedence
+ * so callers can tell "explicitly configured" apart from "inherited from a
+ * .env that may have gone stale" without re-deriving the value themselves.
+ */
+export function settingSource(store, setting) {
+    const fromJson = getAtPath(setting.tier === 'secret' ? store.secrets : store.config, setting.path);
+    if (fromJson !== undefined && fromJson !== null && fromJson !== '')
+        return 'config';
+    if (store.legacyEnvFile) {
+        // stripInlineComment, exactly as readSetting applies it: `KEY=  # note` has
+        // no value, and reporting 'env' for one would have this function disagree
+        // with the value the caller reads a line later.
+        const raw = readEnvValue(store.legacyEnvFile, setting.env);
+        if (raw !== null && stripInlineComment(raw) !== '')
+            return 'env';
+    }
+    return 'none';
+}
 /** Effective value of a setting, or undefined when nothing configures it. */
 export function readSetting(store, setting) {
     const fromJson = getAtPath(setting.tier === 'secret' ? store.secrets : store.config, setting.path);

package/dist/config/settings.d.ts

@@ -11,8 +11,9 @@
  * Everything else — the wizard, the config loader, the doctor and the docs
  * table — is generated from this list, so a new setting only has to be added
  * here. Purely operational variables the user should never have to set
- * (NODE_ENV, WEBSITES_PORT, CI/TERM detection, ENV_FILE, MCP_STDIO_MODE) are
- * deliberately absent: they are runtime/platform inputs, not configuration.
+ * (NODE_ENV, WEBSITES_PORT, CI/TERM detection, ENV_FILE, MCP_STDIO_MODE,
+ * ALLOW_UNAUTHENTICATED) are deliberately absent: they are runtime/platform
+ * inputs, not configuration.
  */
 export type SettingType = 'string' | 'path' | 'boolean' | 'int' | 'list' | 'enum';
 /**
@@ -30,13 +31,21 @@ export interface Setting {
     /**
      * Dotted path inside the JSON config, e.g. "environment.packagePath".
      *
-     * Absent for `env-only` settings: consent-style switches whose whole point is
-     * that they are re-read from the environment (or the .env file) between tool
-     * calls, so writing them into the wizard-managed JSON would misrepresent when
-     * a change takes effect. They are still registered here — without an entry
-     * the docs generator silently drops them, which is how three cross-model
-     * variables disappeared from docs/CONFIGURATION.md the last time it was
-     * regenerated.
+     * Absent for `env-only` settings: values whose reader is somewhere the
+     * wizard-managed JSON cannot honestly describe — the cross-model consent
+     * switches, re-read from the .env before every guard decision so a grant
+     * applies without a restart (loadEnv.reloadWritePolicy), and the lock
+     * heartbeat, read at acquire time in a process the wizard never configures.
+     * A JSON key would misrepresent when a change takes effect.
+     *
+     * "The runtime reads it straight from process.env" is NOT that reason — every
+     * setting here does, via toEnvRecord. EXTENSION_PREFIX_SOURCE sat in this
+     * group on that basis alone until #893, which cost a multi-instance install a
+     * whole second configuration file for one static naming preference.
+     *
+     * env-only settings are still registered — without an entry the docs
+     * generator silently drops them, which is how three cross-model variables
+     * disappeared from docs/CONFIGURATION.md the last time it was regenerated.
      */
     path?: string;
     /** Environment variable the server/scripts read at runtime. */

package/dist/config/settings.js

@@ -11,8 +11,9 @@
  * Everything else — the wizard, the config loader, the doctor and the docs
  * table — is generated from this list, so a new setting only has to be added
  * here. Purely operational variables the user should never have to set
- * (NODE_ENV, WEBSITES_PORT, CI/TERM detection, ENV_FILE, MCP_STDIO_MODE) are
- * deliberately absent: they are runtime/platform inputs, not configuration.
+ * (NODE_ENV, WEBSITES_PORT, CI/TERM detection, ENV_FILE, MCP_STDIO_MODE,
+ * ALLOW_UNAUTHENTICATED) are deliberately absent: they are runtime/platform
+ * inputs, not configuration.
  */
 export const SECTIONS = [
     {
@@ -214,13 +215,21 @@ export const SETTINGS = [
         required: true,
     },
     {
+        path: 'naming.prefixSource',
         env: 'EXTENSION_PREFIX_SOURCE',
         section: 'naming',
-        tier: 'env-only',
-        type: 'string',
-        label: 'Pin the configured prefix',
-        description: 'Set to `config` to make `EXTENSION_PREFIX` authoritative again instead of learning each model\'s prefix from ' +
-            'its own objects.',
+        tier: 'advanced',
+        type: 'enum',
+        label: 'Where the prefix comes from',
+        description: 'Whether the effective prefix is learned from the active model\'s own objects or pinned to the configured ' +
+            '`naming.prefix`. Pin it when one model carries several feature prefixes that share a stem — inference learns ' +
+            'the shared stem, while the objects you write need the full one. See ' +
+            '[Where the prefix comes from](CUSTOM_EXTENSIONS.md#where-the-prefix-comes-from).',
+        default: 'model',
+        choices: [
+            { value: 'model', hint: 'the model\'s own objects decide, falling back to naming.prefix' },
+            { value: 'config', hint: 'always naming.prefix, inference off (pre-1.8.2 behaviour)' },
+        ],
     },
     {
         path: 'naming.suffix',
@@ -411,8 +420,10 @@ export const SETTINGS = [
         tier: 'advanced',
         type: 'string',
         label: 'HTTP bind address',
-        description: 'Interface the HTTP transport binds to. The default accepts connections from anywhere, which is what a ' +
-            'container or App Service needs; set 127.0.0.1 to make a local server unreachable from the network.',
+        description: 'Interface the HTTP transport binds to. Left unset it follows the API key: 0.0.0.0 once a key (or ' +
+            'ALLOW_UNAUTHENTICATED) is configured, which is what a container or App Service needs, and 127.0.0.1 when ' +
+            'neither is, so an unauthenticated server stays off the network. Setting it to a public interface without a ' +
+            'key is refused at startup.',
         default: '0.0.0.0',
     },
     {
@@ -705,8 +716,11 @@ export const SETTINGS = [
         tier: 'secret',
         type: 'string',
         label: 'API key required from HTTP clients',
-        description: 'When set, every HTTP request must present this key. Leave empty for a localhost-only server; set it whenever ' +
-            'the port is reachable from another machine.',
+        description: 'Every HTTP request must present this key as X-Api-Key (or Authorization: Bearer). Required for any server ' +
+            'reachable from the network — without it the listener serves your indexed X++ source to anyone who can reach ' +
+            'the port, so with no key set the server binds 127.0.0.1 instead, and refuses to start if HOST asks for a ' +
+            'public interface anyway. May be left empty only for a localhost-only development server. Generate with ' +
+            '`openssl rand -hex 32`.',
     },
     {
         path: 'behavior.groundingSecret',

package/dist/index.js

@@ -21,7 +21,7 @@ import { initializeDatabase } from './database/download.js';
 import { initializeConfig, getConfigManager } from './utils/configManager.js';
 import { SERVER_MODE, LOCAL_TOOLS, TOOL_PROFILE, EXTRA_TOOLS, isToolEnabled } from './server/serverMode.js';
 import { TOOL_ANNOTATIONS } from './server/toolAnnotations.js';
-import { apiKeyAuth } from './middleware/apiKeyAuth.js';
+import { apiKeyAuth, authStartupError, resolveBindHost } from './middleware/apiKeyAuth.js';
 import { VERSION } from './version.js';
 import { setInitializeParams } from './utils/stdioSessionInfo.js';
 import { setModelObjectNameSource } from './utils/modelPrefixInference.js';
@@ -645,7 +645,18 @@ async function main() {
         // Branded banner first — connection details are known immediately, before
         // the (potentially long) database load. Symbol counts are intentionally NOT
         // shown here; they appear once during the load (`✓ Loaded … symbols`).
-        const host = process.env.HOST || '0.0.0.0';
+        // Fail closed before anything binds: a network-reachable listener with no
+        // API_KEY would serve the whole read surface to anonymous callers.
+        const authError = authStartupError();
+        if (authError) {
+            console.error('');
+            console.error(authError);
+            console.error('');
+            process.exit(1);
+        }
+        // Not `process.env.HOST || '0.0.0.0'` — with no key configured the default
+        // is loopback, so forgetting the key costs reachability, not secrecy.
+        const host = resolveBindHost();
         const W = 50;
         console.log('');
         for (const line of box([
@@ -656,6 +667,13 @@ async function main() {
         }
         console.log('');
         console.log(kv('Mode', `HTTP ${c.dim(glyph.dot)} ${SERVER_MODE}`));
+        // Three states, and the guard above has already ruled out the fourth
+        // (no key on a public interface), so "none" here always means loopback.
+        console.log(kv('Auth', process.env.API_KEY?.trim()
+            ? `API key ${c.dim(glyph.dot)} X-Api-Key`
+            : process.env.ALLOW_UNAUTHENTICATED === 'true'
+                ? c.yellow(`delegated upstream ${c.dim(glyph.dot)} nothing is checked here`)
+                : `none ${c.dim(glyph.dot)} ${c.dim('loopback only, not reachable from the network')}`));
         console.log(kv('Endpoint', c.cyan(`http://${host}:${PORT}/mcp`)));
         console.log(kv('Health', c.cyan(`http://localhost:${PORT}/health`)));
         console.log(kv('Runtime', `Node ${process.version} ${c.dim(glyph.dot)} pid ${process.pid}`));

package/dist/knowledge/tableDataMethods.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The data methods every table inherits from `xRecord` / `Common`.
+ *
+ * Those are kernel types with no AOT metadata, and the symbol index stores
+ * declared members only, so a table's `validateWrite` has no row anywhere.
+ * prepare(mode="change") and get_method both reported that as "not found",
+ * which reads as "the method does not exist" for the most common CoC target
+ * there is and leaves the caller to invent the wrapper unaided.
+ *
+ * The contract below is the part a green build cannot teach — above all that
+ * the pre-image is `this.orig()`, already in memory, so re-reading the row by
+ * its own RecId is a database round trip per write AND a different value: the
+ * current stored state rather than what this buffer was fetched with.
+ *
+ * A FALLBACK only: consulted when neither index, bridge nor XML declares the
+ * method, so a table that overrides `insert()` still reports its own signature.
+ */
+export interface TableDataMethod {
+    /** Canonical AOT spelling. */
+    name: string;
+    /** The declaration a CoC wrapper has to match exactly. */
+    signature: string;
+    /** Kernel type that declares it. */
+    declaredOn: 'xRecord' | 'Common';
+    /** What wrapping it is for, in one line. */
+    purpose: string;
+    /** Non-negotiables a green build will not teach. */
+    contract: string[];
+}
+/** Keyed by lower-cased method name. */
+export declare const TABLE_DATA_METHODS: Record<string, TableDataMethod>;
+/** The inherited data method by that name, or undefined. Case-insensitive, as X++ is. */
+export declare function lookupTableDataMethod(methodName: string): TableDataMethod | undefined;
+/**
+ * True for the object types this fallback speaks for.
+ *
+ * Tables only, deliberately. Views, maps and data entities descend from `Common`
+ * too, but they do not all wrap through `tableStr` and not every one of these
+ * methods fires on them — a fallback that guessed there would be inventing a
+ * signature, which is the failure it exists to prevent.
+ */
+export declare function hasTableDataMethods(objectType: string | undefined): boolean;
+/** The `### Method signature` body when only this fallback knows the method. */
+export declare function renderTableDataMethodSignature(method: TableDataMethod, objectName: string): string;
+/** The `### CoC eligibility` body, plus the contract that is the reason this exists. */
+export declare function renderTableDataMethodEligibility(method: TableDataMethod, objectName: string): string;
+//# sourceMappingURL=tableDataMethods.d.ts.map