@mcp-abap-adt/proxy 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.0.1] - 2026-09-24
+
+**A variable from an env file could be silently lost, and the failure blamed the
+variable instead of naming the file.** Both hit Windows hardest, with the same
+config and the same `.env` that work on Linux.
+
+### Fixed
+
+- **An empty environment variable no longer shadows the env file.** The lookup
+  was `process.env[key] ?? envFileMap[key]`, and `??` skips only `undefined` — so
+  a `SAP_LOGIN=` sitting in the environment beat the file the user had pointed at
+  with `--env-file`, and the header went out empty with nothing reported. Windows
+  carries variables nobody set deliberately, which is why the same files behaved
+  differently there. A real value in the environment still wins.
+
+- **The interpolation failure now names where it looked.** It said only
+  `Config references undefined env variable: SAP_LOGIN`, so three different
+  causes produced one sentence and the cause had to be guessed:
+
+  ```
+  ... looked in process.env only — no env file was given (--env-file or envFile:)
+  ... looked in process.env, then /path/e19.env, which yielded NO variables
+      (0 bytes) — check its encoding, since a UTF-16 file reads as nothing here
+  ... looked in process.env, then /path/e19.env (1: SAP_PASSWORD)
+  ```
+
+  An env file that yields nothing is still not an error — an empty `.env` is
+  legitimate, and a config may take every value from the environment. It is
+  reported by whoever then needs a variable, where it can be said usefully.
+
+### Documentation
+
+- `docs/YAML_CONFIG.md`: a Windows path in **double** quotes is a YAML escape
+  context. `envFile: "C:\Users\..."` fails to parse (`\U` is a Unicode escape)
+  and `"C:\temp\e19.env"` parses *silently wrong* (`\e` becomes 0x1B). Use
+  single quotes, no quotes, or forward slashes.
+
 ## [4.0.0] - 2026-09-24
 
 **The proxy stops re-implementing the broker, there is one forwarding path

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGxC,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAG/B,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,CAoC3D;AAwED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,mBAAmB,CAQrB;AAkCD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYhC;AAmJD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAUD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAoDA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAGxC,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAG/B,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACzE,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,WAAW,CA8C3D;AAwED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,mBAAmB,CAQrB;AAkCD;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAYhC;AAmJD;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,GAAG,SAAS,CAElD;AAUD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAoDA"}

package/dist/lib/config.js

@@ -68,7 +68,15 @@ function loadConfig(configPath) {
             const envFilePath = resolveEnvFilePath(fileConfig, finalConfigPath);
             const envFileMap = envFilePath ? (0, envInterpolation_js_1.loadEnvFile)(envFilePath) : {};
             const lookup = (0, envInterpolation_js_1.buildLookup)(envFileMap);
-            const interpolated = (0, envInterpolation_js_1.interpolateConfig)(fileConfig, lookup);
+            const keys = Object.keys(envFileMap);
+            const sources = !envFilePath
+                ? 'process.env only — no env file was given (--env-file or envFile:)'
+                : keys.length === 0
+                    ? `process.env, then ${envFilePath}, which yielded NO variables ` +
+                        `(${fs.statSync(envFilePath).size} bytes) — check its encoding, ` +
+                        `since a UTF-16 file reads as nothing here, and that lines look like KEY=value`
+                    : `process.env, then ${envFilePath} (${keys.length}: ${keys.join(', ')})`;
+            const interpolated = (0, envInterpolation_js_1.interpolateConfig)(fileConfig, lookup, '', sources);
             delete interpolated.envFile;
             const base = applyDefaults(interpolated);
             const cli = readCliOverrides();

package/dist/lib/envInterpolation.d.ts

@@ -8,14 +8,16 @@
  * default when one is given. A ${VAR} without a default that resolves to
  * undefined throws, naming the variable and the field it came from.
  */
-export declare function interpolateString(input: string, lookup: (key: string) => string | undefined, fieldPath: string): string;
+export declare function interpolateString(input: string, lookup: (key: string) => string | undefined, fieldPath: string, 
+/** Where values were looked for, named in the failure. */
+sources?: string): string;
 /**
  * Recursively interpolate all string values in a parsed config object.
  * Objects/arrays are walked; non-string scalars are returned unchanged.
  * The field path (e.g. `defaultHeaders.x-sap-password`) is threaded through for
  * error messages.
  */
-export declare function interpolateConfig(value: unknown, lookup: (key: string) => string | undefined, path?: string): unknown;
+export declare function interpolateConfig(value: unknown, lookup: (key: string) => string | undefined, path?: string, sources?: string): unknown;
 /**
  * Parse a .env file into a flat map. Throws if the path is given but missing —
  * a specified-yet-absent secret source is a configuration error, not a no-op.
@@ -23,6 +25,16 @@ export declare function interpolateConfig(value: unknown, lookup: (key: string)
 export declare function loadEnvFile(envFilePath: string): Record<string, string>;
 /**
  * Build a lookup over process.env (highest priority) then the parsed .env map.
+ *
+ * An EMPTY environment variable does not count as a value. It used to: `??`
+ * skips only `undefined`, so a `SAP_LOGIN=` sitting in the environment won
+ * against the env file the user had explicitly pointed at with `--env-file`,
+ * and the header went out empty with nothing reported. Windows carries
+ * variables nobody set deliberately, which is why the same config and the same
+ * `.env` behaved differently there.
+ *
+ * A real value in the environment still wins — that is the documented
+ * precedence, and it is how a one-off override is meant to work.
  */
 export declare function buildLookup(envFileMap: Record<string, string>): (key: string) => string | undefined;
 //# sourceMappingURL=envInterpolation.d.ts.map

package/dist/lib/envInterpolation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envInterpolation.d.ts","sourceRoot":"","sources":["../../src/lib/envInterpolation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,SAAS,EAAE,MAAM,GAChB,MAAM,CAiBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,IAAI,SAAK,GACR,OAAO,CAiBT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKvE;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAGrC"}
+{"version":3,"file":"envInterpolation.d.ts","sourceRoot":"","sources":["../../src/lib/envInterpolation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,SAAS,EAAE,MAAM;AACjB,0DAA0D;AAC1D,OAAO,SAAgB,GACtB,MAAM,CAsBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC3C,IAAI,SAAK,EACT,OAAO,SAAgB,GACtB,OAAO,CAsBT;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAQrC"}

package/dist/lib/envInterpolation.js

@@ -50,7 +50,9 @@ const PLACEHOLDER = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g;
  * default when one is given. A ${VAR} without a default that resolves to
  * undefined throws, naming the variable and the field it came from.
  */
-function interpolateString(input, lookup, fieldPath) {
+function interpolateString(input, lookup, fieldPath, 
+/** Where values were looked for, named in the failure. */
+sources = 'process.env') {
     return input.replace(PLACEHOLDER, (_match, name, defaultVal) => {
         const value = lookup(name);
         const isEmpty = value === undefined || value === '';
@@ -58,7 +60,12 @@ function interpolateString(input, lookup, fieldPath) {
             return isEmpty ? defaultVal : value;
         }
         if (value === undefined) {
-            throw new Error(`Config references undefined env variable: ${name} (referenced in ${fieldPath})`);
+            // Naming where it looked, because the old message named only the
+            // variable — so a file never read, a file read empty, and a value
+            // shadowed by the environment all produced the same sentence and the
+            // cause had to be guessed.
+            throw new Error(`Config references undefined env variable: ${name} ` +
+                `(referenced in ${fieldPath}; looked in ${sources})`);
         }
         return value;
     });
@@ -69,17 +76,17 @@ function interpolateString(input, lookup, fieldPath) {
  * The field path (e.g. `defaultHeaders.x-sap-password`) is threaded through for
  * error messages.
  */
-function interpolateConfig(value, lookup, path = '') {
+function interpolateConfig(value, lookup, path = '', sources = 'process.env') {
     if (typeof value === 'string') {
-        return interpolateString(value, lookup, path || '(root)');
+        return interpolateString(value, lookup, path || '(root)', sources);
     }
     if (Array.isArray(value)) {
-        return value.map((item, i) => interpolateConfig(item, lookup, `${path}[${i}]`));
+        return value.map((item, i) => interpolateConfig(item, lookup, `${path}[${i}]`, sources));
     }
     if (value !== null && typeof value === 'object') {
         const out = {};
         for (const [key, val] of Object.entries(value)) {
-            out[key] = interpolateConfig(val, lookup, path ? `${path}.${key}` : key);
+            out[key] = interpolateConfig(val, lookup, path ? `${path}.${key}` : key, sources);
         }
         return out;
     }
@@ -93,11 +100,31 @@ function loadEnvFile(envFilePath) {
     if (!fs.existsSync(envFilePath)) {
         throw new Error(`env file not found: ${envFilePath}`);
     }
+    // Not an error when it yields nothing: an empty `.env` is legitimate, and a
+    // config may take every value from the environment. But the emptiness is
+    // reported by whoever needs a variable — see the `sources` note threaded into
+    // the interpolation failure, which names the file, its size and its key count.
     return dotenv.parse(fs.readFileSync(envFilePath, 'utf-8'));
 }
 /**
  * Build a lookup over process.env (highest priority) then the parsed .env map.
+ *
+ * An EMPTY environment variable does not count as a value. It used to: `??`
+ * skips only `undefined`, so a `SAP_LOGIN=` sitting in the environment won
+ * against the env file the user had explicitly pointed at with `--env-file`,
+ * and the header went out empty with nothing reported. Windows carries
+ * variables nobody set deliberately, which is why the same config and the same
+ * `.env` behaved differently there.
+ *
+ * A real value in the environment still wins — that is the documented
+ * precedence, and it is how a one-off override is meant to work.
  */
 function buildLookup(envFileMap) {
-    return (key) => process.env[key] ?? envFileMap[key];
+    return (key) => {
+        const fromEnvironment = process.env[key];
+        if (fromEnvironment !== undefined && fromEnvironment !== '') {
+            return fromEnvironment;
+        }
+        return envFileMap[key];
+    };
 }

package/docs/YAML_CONFIG.md

@@ -206,6 +206,23 @@ requestTimeout: 120000
 | `maxRetries` | `number` | `3` | Maximum number of retry attempts |
 | `retryDelay` | `number` | `1000` | Delay between retries (milliseconds) |
 | `requestTimeout` | `number` | `60000` | Request timeout (milliseconds) |
+### Windows paths must not go in double quotes
+
+In YAML, a double-quoted string is an **escape context**, and a Windows path is
+full of backslashes. Measured with the parser this package uses:
+
+| written as | result |
+|---|---|
+| `envFile: "C:\Users\me\e19.env"` | **fails** — `expected hexadecimal character`, because `\U` starts a Unicode escape |
+| `envFile: "C:\temp\e19.env"` | **silently wrong** — `\e` becomes the escape character `0x1B`, so the path points nowhere |
+| `envFile: 'C:\Users\me\e19.env'` | correct |
+| `envFile: C:\Users\me\e19.env` | correct |
+| `envFile: "C:/Users/me/e19.env"` | correct |
+
+The second row is the dangerous one: it does not fail, it resolves to a path that
+does not exist. Forward slashes are the safest form — Node accepts them on
+Windows, and they carry no meaning inside quotes.
+
 | ~~`circuitBreakerThreshold`~~ | `number` | — | **No effect since 4.0.0.** Still accepted so existing files load; the circuit breaker guarded the buffered forward that release removed |
 | ~~`circuitBreakerTimeout`~~ | `number` | — | **No effect since 4.0.0.** As above |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-abap-adt/proxy",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "MCP proxy server for SAP ABAP ADT - proxies local requests to cloud-llm-hub with JWT authentication",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",