@mcp-abap-adt/proxy 2.0.0 → 4.0.1

package/README.md

@@ -13,9 +13,10 @@ Enable local MCP clients to connect to remote MCP servers with automatic JWT tok
 
 ## Features
 
-- ✅ **JWT Token Management** - Automatic token retrieval, caching, and refresh via auth-broker
+- ✅ **One shared credential** - the token is the auth-broker's business: it caches, knows expiry and renews behind the call. The proxy holds no token of its own
 - ✅ **Service Key Based** - MCP server URL is obtained from service key for BTP destination
-- ✅ **Error Handling** - Retry logic, circuit breaker, and comprehensive error handling
+- ✅ **Transparent forwarding** - the client's headers go through as sent; the proxy answers for the `Authorization` header and nothing else
+- ✅ **Error Handling** - token acquisition is retried with exponential backoff when the failure can get better; clear messages when it cannot
 - ✅ **Multiple Transport Modes** - HTTP, SSE, and stdio support
 - ✅ **Configuration Flexibility** - Environment variables, config files, or defaults
 
@@ -40,6 +41,58 @@ mcp-abap-adt-proxy --btp=ai
 mcp-abap-adt-proxy --btp=ai --unsafe
 ```
 
+## Two commands
+
+The package installs two binaries, for two different jobs.
+
+| Command | What it is for |
+|---|---|
+| `mcp-abap-adt-proxy` | **Be** a proxy. A client points at it and its requests are authenticated and forwarded. |
+| `mcp-abap-adt-proxy-mcp` | **Manage** proxies. Speaks MCP over stdio; its tools start and stop proxies on demand. |
+
+### The management mode
+
+Register it like any other MCP server:
+
+```json
+{
+  "mcpServers": {
+    "abap-proxy": { "command": "mcp-abap-adt-proxy-mcp" }
+  }
+}
+```
+
+It works from the proxy configs you already keep:
+
+```
+~/.config/mcp-abap-adt/proxy/<name>.yaml     (Windows: Documents\mcp-abap-adt\proxy\)
+```
+
+These are the same files `mcp-abap-adt-proxy --config <file>` takes. Starting a
+proxy is therefore **choosing a name**, not assembling settings — and
+credentials stay in the config, resolved through `${VAR}` interpolation, rather
+than travelling through a tool call.
+
+| Tool | What it does |
+|---|---|
+| `proxy_configs` | Lists the configs available, by the name `proxy_start` takes. Call it first — the names cannot be guessed. |
+| `proxy_start` | Starts a proxy from one of those configs and returns the URL it bound. The **port is not taken from the config**: a free one is bound instead. |
+| `proxy_stop` | Stops a proxy this session started, freeing its port and releasing its credential. Proxies started by other sessions are never touched. |
+| `proxy_status` | Lists this session's proxies and any others on this machine. Records whose process has died are pruned when read, so it cannot report a ghost. |
+
+**The config name is the unit, not the destination.** Several configs commonly
+name the same `btpDestination` and differ in target URL and headers — a
+destination cannot tell them apart.
+
+**Every proxy runs inside the management process.** Closing the session — or
+`SIGINT`, or `SIGTERM` — stops all of them and frees their ports. This is
+deliberate: a spawned child would be orphaned by any signal the parent did not
+forward and would go on holding its HTTP and OAuth callback ports.
+
+A proxy nobody has used for 30 minutes stops itself. That is a backstop for a
+client that finished and forgot, not a substitute for `proxy_stop` — which is
+why the tool descriptions say so, and say it again beside the URL.
+
 ### Configuration
 
 The proxy supports multiple configuration methods:
@@ -156,6 +209,8 @@ The proxy uses BTP/XSUAA authentication:
 
 ## Documentation
 
+- 🚚 **[Migration to 4.0](./docs/MIGRATION-4.0.md)** — the contracts leave the umbrella, an SSE response streams and carries your headers, `getJwtToken()` is replaced, the circuit breaker is gone
+
 - **[Client Setup Guide](./docs/CLIENT_SETUP.md)** - Step-by-step setup for Cline and GitHub Copilot
 - **[Configuration Guide](./docs/CONFIGURATION.md)** - Complete configuration reference
 - **[YAML Configuration Guide](./docs/YAML_CONFIG.md)** - Using YAML/JSON configuration files
@@ -221,7 +276,6 @@ Create `mcp-proxy-config.json`:
   "httpPort": 3001,
   "logLevel": "info",
   "maxRetries": 3,
-  "circuitBreakerThreshold": 5,
   "unsafe": false
 }
 ```
@@ -234,10 +288,9 @@ See [Configuration Guide](./docs/CONFIGURATION.md) for complete options.
 
 ## Error Handling & Resilience
 
-- **Retry Logic** - Exponential backoff for failed requests
-- **Circuit Breaker** - Prevents cascading failures
-- **Token Refresh** - Automatic token refresh on expiration
-- **Connection Pooling** - Efficient resource management
+- **Retry Logic** - exponential backoff while getting a token, for failures that can get better (5xx, network). A missing service key is not one of them and fails at once, with a message naming the file to create
+- **Token Refresh** - handled by the credential, which is asked per request and renews behind the call
+- **No circuit breaker** - it guarded the buffered forward that 4.0.0 removed. The forwarding path now streams, and there is nowhere to put one without buffering the response again. `circuitBreakerThreshold` and `circuitBreakerTimeout` are still accepted so existing configs load, and do nothing
 - **Request Timeouts** - Configurable timeout handling
 
 ## Requirements
@@ -277,7 +330,25 @@ See [ROADMAP.md](./ROADMAP.md) for details.
 
 ## License
 
-MIT
+**GNU General Public License v3.0 only** (`GPL-3.0-only`).
+Earlier published versions were MIT and stay MIT — a licence change is not
+retroactive.
+
+Copyright © 2025–2026 Oleksii Kyslytsia
+
+This program is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, version 3.
+
+It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE. See [`LICENSE`](LICENSE) for the full text.
+
+**What this means.** Running it, and using it on your own data, carries no
+conditions at all. Distributing it, or a modified version of it, means passing on
+the same freedoms — including the source. This is a finished tool rather than a
+library to build on; the libraries it is built from are LGPL, so they can be
+linked from programs under any licence.
 
 ## Links
 

package/bin/mcp-abap-adt-proxy-mcp.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+/**
+ * MCP ABAP ADT Proxy — management mode.
+ *
+ * Speaks MCP over stdio and exposes tools that start and stop proxies. This is
+ * the command a client registers when it wants to MANAGE proxies; a client that
+ * wants to BE proxied still points at `mcp-abap-adt-proxy`.
+ *
+ * Usage:
+ *   mcp-abap-adt-proxy-mcp [--config <file>] [--unsafe]
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  return {
+    help: args.includes('--help') || args.includes('-h'),
+    version: args.includes('--version') || args.includes('-v'),
+  };
+}
+
+function showHelp() {
+  const pkg = require('../package.json');
+  console.log(`
+MCP ABAP ADT Proxy — management mode v${pkg.version}
+
+Speaks MCP over stdio. Its tools start and stop authenticating proxies; it does
+not proxy anything itself.
+
+Usage:
+  mcp-abap-adt-proxy-mcp [options]
+
+Tools offered to the client:
+  proxy_configs  List the proxy configs on this machine, by the name
+                 proxy_start takes. Call this first — the names cannot be
+                 guessed.
+  proxy_start    Start a proxy from one of those configs. The config supplies
+                 the destination, target URL, default headers and timeouts;
+                 the PORT does not come from it — a free one is bound, so
+                 several proxies can run at once, and the URL returned is the
+                 one actually bound.
+  proxy_stop     Stop a proxy this session started, freeing its port and
+                 releasing its credential. Proxies belonging to other sessions
+                 are never touched.
+  proxy_status   List this session's proxies and any others on this machine.
+                 Records whose process has died are pruned when read.
+
+Where the configs live:
+  Unix:     ~/.config/mcp-abap-adt/proxy/<name>.yaml
+  Windows:  %USERPROFILE%\\Documents\\mcp-abap-adt\\proxy\\<name>.yaml
+
+  The same files 'mcp-abap-adt-proxy --config <file>' takes. Credentials stay
+  in them, resolved through \${VAR} interpolation, and are never passed
+  through a tool call.
+
+Options:
+  --config=<file>, -c     Load configuration from a YAML or JSON file
+  --env-file=<path>       Load a .env file for \${VAR} interpolation
+  --unsafe                Persist tokens to disk
+  --help, -h              Show this help message
+  --version, -v           Show version number
+
+Shutting down:
+  Every proxy runs in THIS process. Closing the session — or SIGINT, or SIGTERM
+  — stops all of them and frees their ports. A proxy nobody has used for 30
+  minutes stops itself; that is a backstop, not a substitute for proxy_stop.
+
+Registering it with a client:
+  {
+    "mcpServers": {
+      "abap-proxy": { "command": "mcp-abap-adt-proxy-mcp" }
+    }
+  }
+
+For more information, see: https://github.com/fr0ster/mcp-abap-adt-proxy
+`);
+}
+
+function main() {
+  const args = parseArgs();
+
+  if (args.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (args.version) {
+    console.log(require('../package.json').version);
+    process.exit(0);
+  }
+
+  const serverPath = path.resolve(__dirname, '../dist/mcp/cli.js');
+
+  if (!fs.existsSync(serverPath)) {
+    process.stderr.write(`[MCP Proxy] ✗ Server not found at: ${serverPath}\n`);
+    process.stderr.write(
+      `[MCP Proxy]   Make sure to build the project with 'npm run build' first.\n`,
+    );
+    process.exit(1);
+    return;
+  }
+
+  // Loaded in THIS process, never spawned — the same rule the proxy launcher
+  // follows, and it matters more here: the proxies the tools start are
+  // listeners in this process, and a spawned child would be orphaned by any
+  // signal this launcher did not forward, still holding their ports.
+  require(serverPath);
+}
+
+main();

package/dist/index.d.ts

@@ -17,6 +17,16 @@ export declare class McpAbapAdtProxyServer {
     private config;
     private httpServer?;
     private btpProxy?;
+    private builtProxyHandler?;
+    /**
+     * The request path, shared with the MCP mode. Here an authentication failure
+     * is fatal: the process exits so whatever started it can start it again with
+     * a credential that works.
+     *
+     * Built on first use rather than as a field initializer, because `config` is
+     * assigned in the constructor and a field initializer runs before that.
+     */
+    private get proxyHandler();
     private authExiting;
     constructor(transportConfig?: TransportConfig, configPath?: string);
     /**
@@ -31,10 +41,6 @@ export declare class McpAbapAdtProxyServer {
      * Start HTTP server with request interception
      */
     private startHttpServer;
-    /**
-     * Handle proxy request - get JWT token and forward transparently via reverse proxy
-     */
-    private handleProxyRequest;
     /**
      * Start SSE server
      */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwBH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAgElC;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAC5B,OAAO,CAAC,WAAW,CAAS;gBAEhB,eAAe,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM;IAoDlE;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA2E1B;;OAEG;YACW,eAAe;IAgG7B;;OAEG;YACW,kBAAkB;IAgEhC;;OAEG;YACW,cAAc;IA6T5B;;;;;OAKG;YACW,gBAAgB;IAiC9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAgElC;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,QAAQ,CAAC,CAAW;IAE5B,OAAO,CAAC,iBAAiB,CAAC,CAA+C;IAEzE;;;;;;;OAOG;IACH,OAAO,KAAK,YAAY,GAevB;IACD,OAAO,CAAC,WAAW,CAAS;gBAEhB,eAAe,CAAC,EAAE,eAAe,EAAE,UAAU,CAAC,EAAE,MAAM;IAoDlE;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IA2E1B;;OAEG;YACW,eAAe;IAiE7B;;OAEG;YACW,cAAc;IAiV5B;;;;;OAKG;YACW,gBAAgB;IAiC9B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAoBhC;AAGD,eAAe,qBAAqB,CAAC"}

package/dist/index.js

@@ -11,10 +11,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpAbapAdtProxyServer = void 0;
 const node_http_1 = require("node:http");
-const interfaces_1 = require("@mcp-abap-adt/interfaces");
+const interfaces_network_1 = require("@mcp-abap-adt/interfaces-network");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const sse_js_1 = require("@modelcontextprotocol/sdk/server/sse.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const requestHandler_js_1 = require("./proxy/requestHandler.js");
 const reverseProxy_js_1 = require("./proxy/reverseProxy.js");
 const config_js_1 = require("./lib/config.js");
 const logger_js_1 = require("./lib/logger.js");
@@ -73,6 +74,30 @@ class McpAbapAdtProxyServer {
     config;
     httpServer;
     btpProxy;
+    builtProxyHandler;
+    /**
+     * The request path, shared with the MCP mode. Here an authentication failure
+     * is fatal: the process exits so whatever started it can start it again with
+     * a credential that works.
+     *
+     * Built on first use rather than as a field initializer, because `config` is
+     * assigned in the constructor and a field initializer runs before that.
+     */
+    get proxyHandler() {
+        if (!this.builtProxyHandler) {
+            this.builtProxyHandler = (0, requestHandler_js_1.createProxyRequestHandler)({
+                config: this.config,
+                proxy: async () => {
+                    if (!this.btpProxy) {
+                        this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
+                    }
+                    return this.btpProxy;
+                },
+                onAuthFailure: (error, destination) => this.fatalAuthFailure(error, destination, 'request'),
+            });
+        }
+        return this.builtProxyHandler;
+    }
     authExiting = false;
     constructor(transportConfig, configPath) {
         // Load config first to extract transport overrides from YAML/JSON file
@@ -203,39 +228,13 @@ Authorization source: BTP destination "${this.config.btpDestination}"`;
                 headers: sanitizedHeaders,
                 remoteAddress: req.socket.remoteAddress,
             });
-            // Intercept and analyze request (headers only, body is piped through)
-            const configOverrides = {
-                btpDestination: this.config.btpDestination,
-                targetUrl: this.config.targetUrl,
-            };
-            const intercepted = (0, requestInterceptor_js_1.interceptRequest)(req, undefined, configOverrides, {
-                skipHeaderValidation: true,
-            });
-            // Check routing decision
-            if (intercepted.routingDecision.strategy === headerAnalyzer_js_1.RoutingStrategy.UNKNOWN) {
-                logger_js_1.logger?.error('Routing decision failed', {
-                    type: 'ROUTING_DECISION_FAILED',
-                    reason: intercepted.routingDecision.reason,
-                });
-                res.writeHead(400, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    error: intercepted.routingDecision.reason,
-                }));
-                return;
-            }
-            // Forward request via reverse proxy
-            logger_js_1.logger?.info('=== PROXYING REQUEST ===', {
-                type: 'PROXY_REQUEST_START',
-                btpDestination: intercepted.routingDecision.btpDestination,
-            });
             try {
-                await this.handleProxyRequest(intercepted, req, res);
+                await this.proxyHandler(req, res);
             }
             catch (error) {
                 logger_js_1.logger?.error('Failed to process request', {
                     type: 'REQUEST_PROCESS_ERROR',
                     error: error instanceof Error ? error.message : String(error),
-                    strategy: intercepted.routingDecision.strategy,
                 });
                 if (!res.headersSent) {
                     res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -270,62 +269,6 @@ Authorization source: ${authSourceObj}`;
             });
         });
     }
-    /**
-     * Handle proxy request - get JWT token and forward transparently via reverse proxy
-     */
-    async handleProxyRequest(intercepted, req, res) {
-        const destination = intercepted.routingDecision.btpDestination;
-        if (!destination) {
-            res.writeHead(400, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'No BTP destination specified' }));
-            return;
-        }
-        // Ensure proxy is initialized
-        if (!this.btpProxy) {
-            this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
-        }
-        // Authentication is separated from forwarding: an auth failure is fatal
-        // (the proxy exits so it can be restarted), while a downstream/forward error
-        // is returned to the client without killing the proxy.
-        let jwtToken;
-        try {
-            // Get JWT token (cached, auto-refresh)
-            jwtToken = await this.btpProxy.getJwtToken(destination);
-        }
-        catch (authError) {
-            logger_js_1.logger?.error('Proxy request failed: authentication error', {
-                type: 'PROXY_REQUEST_AUTH_ERROR',
-                destination,
-                error: authError instanceof Error ? authError.message : String(authError),
-            });
-            if (!res.headersSent) {
-                res.writeHead(502, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ error: 'Authentication failed' }));
-            }
-            await this.fatalAuthFailure(authError, destination, 'request');
-            return;
-        }
-        try {
-            // Get target URL
-            const targetUrl = intercepted.routingDecision.targetUrl ||
-                (await this.btpProxy.getTargetUrl(destination));
-            // Forward request transparently (inject default headers from config)
-            await (0, reverseProxy_js_1.forwardRequest)(req, res, targetUrl, jwtToken, this.config.defaultHeaders);
-        }
-        catch (error) {
-            logger_js_1.logger?.error('Proxy request failed', {
-                type: 'PROXY_REQUEST_ERROR',
-                destination,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            if (!res.headersSent) {
-                res.writeHead(502, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({
-                    error: error instanceof Error ? error.message : 'Proxy error',
-                }));
-            }
-        }
-    }
     /**
      * Start SSE server
      */
@@ -371,8 +314,8 @@ Authorization source: ${authSourceObj}`;
                 }
             }
             // Add config overrides if not present in headers
-            if (this.config.btpDestination && !headers[interfaces_1.HEADER_BTP_DESTINATION]) {
-                headers[interfaces_1.HEADER_BTP_DESTINATION] = this.config.btpDestination;
+            if (this.config.btpDestination && !headers[interfaces_network_1.HEADER_BTP_DESTINATION]) {
+                headers[interfaces_network_1.HEADER_BTP_DESTINATION] = this.config.btpDestination;
             }
             logger_js_1.logger?.debug('SSE request received', {
                 type: 'SSE_HTTP_REQUEST',
@@ -483,14 +426,15 @@ Authorization source: ${authSourceObj}`;
                 }
                 // Read request body
                 let body;
+                let rawBody;
                 try {
                     const chunks = [];
                     for await (const chunk of req) {
                         chunks.push(chunk);
                     }
                     if (chunks.length > 0) {
-                        const bodyString = Buffer.concat(chunks).toString('utf-8');
-                        body = JSON.parse(bodyString);
+                        rawBody = Buffer.concat(chunks);
+                        body = JSON.parse(rawBody.toString('utf-8'));
                     }
                 }
                 catch (error) {
@@ -532,19 +476,32 @@ Authorization source: ${authSourceObj}`;
                     }));
                     return;
                 }
-                // Handle proxy request via BtpProxy (JSON-RPC mode for SSE)
+                // Forward through the same transparent pipe the other path uses.
+                //
+                // This used to rebuild the request by hand and carry it over axios,
+                // which buffered the response and rewrapped it as a JSON-RPC envelope.
+                // The body above was already read — the JSON-RPC `id` in it is what the
+                // error envelopes below have to echo — so it is handed over rather than
+                // piped. The response still streams, which is the direction that
+                // carries an event stream.
                 try {
                     if (!this.btpProxy) {
                         this.btpProxy = await (0, btpProxy_js_1.createBtpProxy)(this.config);
                     }
-                    const proxyResponse = await this.btpProxy.proxyRequest({
-                        method: intercepted.method,
-                        url: intercepted.url,
-                        data: body,
-                        id: getBodyId(body),
-                    }, intercepted.routingDecision, intercepted.headers);
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify(proxyResponse));
+                    const destination = intercepted.routingDecision.btpDestination ??
+                        this.config.btpDestination;
+                    if (!destination) {
+                        throw new Error('No BTP destination for this request');
+                    }
+                    const authorization = await this.btpProxy.getAuthorizationHeader(destination);
+                    const targetUrl = intercepted.routingDecision.targetUrl ||
+                        (await this.btpProxy.getTargetUrl(destination));
+                    await (0, reverseProxy_js_1.forwardRequest)(req, res, targetUrl, authorization, this.config.defaultHeaders, 
+                    // The bytes as they arrived, not the parse re-serialised: the
+                    // client's `content-length` is forwarded unchanged, and a
+                    // re-serialised body differs from it by whatever whitespace the
+                    // sender used.
+                    rawBody);
                 }
                 catch (error) {
                     logger_js_1.logger?.error('Failed to process SSE POST request', {

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];
+    };
 }