@ciqol/resenv 0.1.0-beta.1

package/doppler/auth.cjs

@@ -0,0 +1,125 @@
+'use strict';
+
+var promises = require('node:timers/promises');
+var node_module = require('node:module');
+var errors = require('../errors.cjs');
+var values = require('../values.cjs');
+var http = require('./http.cjs');
+var system = require('./system.cjs');
+
+const manifest = node_module.createRequire(require('node:url').pathToFileURL(__filename).href)('@ciqol/resenv/package.json');
+if (!values.isRecord(manifest) || typeof manifest.version !== 'string')
+    throw new Error('Invalid package version');
+const { version } = manifest;
+function credential(env, system$1 = system.createSystem()) {
+    return Promise.resolve().then(() => {
+        // An explicitly selected identity is never replaced after an API rejection.
+        if (env.DOPPLER_TOKEN !== undefined)
+            return http.validateToken(env.DOPPLER_TOKEN);
+        let saved;
+        try {
+            saved = system$1.read();
+        }
+        catch (err) {
+            if (!values.hasErrorCode(err, 'DOPPLER_KEYRING_UNAVAILABLE'))
+                throw err;
+        }
+        if (saved)
+            return saved;
+        const token = system$1.cliToken();
+        if (token)
+            return token;
+        throw new errors.ResenvError('DOPPLER_AUTH_REQUIRED', 'Run resenv login doppler, or supply DOPPLER_TOKEN. Startup never opens a login prompt.');
+    });
+}
+async function login({ cli = false, noBrowser = false } = {}, { request = http.createClient(), system: system$1 = system.createSystem(), output = text => process.stderr.write(`${text}\n`), interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY), env = process.env, sleep = promises.setTimeout, now = Date.now } = {}) {
+    if (!interactive || env.CI)
+        throw new errors.ResenvError('DOPPLER_INTERACTIVE_REQUIRED', 'Login requires an interactive local terminal outside CI. Supply DOPPLER_TOKEN for unattended runs.');
+    if (env.DOPPLER_TOKEN !== undefined)
+        throw new errors.ResenvError('DOPPLER_TOKEN_OVERRIDE', 'Unset DOPPLER_TOKEN before logging in; it overrides saved credentials.');
+    const fallback = ({ storeUnavailable = false } = {}) => {
+        output('Using Doppler CLI login.');
+        system$1.cliLogin();
+        if (system$1.canStore && !storeUnavailable) {
+            // Keep the identity chosen by this login ahead of an older resenv token.
+            try {
+                system$1.write(http.validateToken(system$1.cliToken()));
+            }
+            catch {
+                throw new errors.ResenvError('DOPPLER_KEYRING_UNAVAILABLE', 'CLI login completed, but resenv could not update its saved credential. Unlock the credential store and retry.');
+            }
+        }
+        output('Done: Doppler CLI login completed.');
+        return 'cli';
+    };
+    if (cli || !system$1.canStore)
+        return fallback();
+    // Check keyring access before creating an authorization session.
+    try {
+        system$1.read();
+    }
+    catch (err) {
+        if (!values.hasErrorCode(err, 'DOPPLER_KEYRING_UNAVAILABLE'))
+            throw err;
+        return fallback({ storeUnavailable: true });
+    }
+    let challenge;
+    try {
+        // Observed in Doppler's official MCP client, not a public OAuth contract.
+        // Identify resenv honestly rather than impersonating Doppler's MCP client.
+        const query = new URLSearchParams({ hostname: 'resenv', version: `v${version}`, os: process.platform, arch: process.arch });
+        challenge = await request(`/v3/auth/cli/generate/2?${query.toString()}`);
+    }
+    catch (err) {
+        if (values.hasErrorCode(err, 'DOPPLER_ENDPOINT_UNAVAILABLE'))
+            return fallback();
+        throw err;
+    }
+    let url;
+    try {
+        url = new URL(typeof challenge?.auth_url === 'string' ? challenge.auth_url : '');
+    }
+    catch (err) {
+        if (!(err instanceof TypeError))
+            throw err;
+    }
+    if (!challenge || !url || url.origin !== 'https://dashboard.doppler.com' || url.username || url.password || url.pathname !== '/workplace/auth/cli' ||
+        typeof challenge.code !== 'string' || !/^[A-Za-z0-9_-]{8,256}$/.test(challenge.code) ||
+        typeof challenge.polling_code !== 'string' || !/^[A-Za-z0-9_.-]{8,512}$/.test(challenge.polling_code)) {
+        throw new errors.ResenvError('DOPPLER_INVALID_RESPONSE', 'Doppler returned an invalid browser authorization challenge.');
+    }
+    // Display the human authorization code only in the explicit login command.
+    output(`Authorize resenv at ${url.href}`);
+    output(`Authorization code: ${challenge.code}`);
+    if (!noBrowser)
+        system$1.openBrowser(url.href);
+    const deadline = now() + 300000;
+    while (now() < deadline) {
+        const result = await request('/v3/auth/cli/authorize', { body: { code: challenge.polling_code }, pending: true });
+        if (result) {
+            const token = http.validateToken(result.token);
+            try {
+                system$1.write(token);
+            }
+            catch {
+                // Do not leave a newly minted, unpersisted credential active if storage fails.
+                try {
+                    await request('/v3/auth/revoke', { token, body: { token } });
+                }
+                catch (err) {
+                    if (!(err instanceof errors.ResenvError)) {
+                        throw new errors.ResenvError('DOPPLER_KEYRING_UNAVAILABLE', 'Could not save or revoke the login credential. Check Doppler CLI Tokens before retrying.');
+                    }
+                }
+                throw new errors.ResenvError('DOPPLER_KEYRING_UNAVAILABLE', 'Could not save the login credential. Revocation was attempted; check Doppler CLI Tokens, then try resenv login doppler --cli.');
+            }
+            output('Done: Doppler login saved in the OS credential store.');
+            return 'native';
+        }
+        await sleep(2000);
+    }
+    throw new errors.ResenvError('DOPPLER_LOGIN_TIMEOUT', 'Doppler login timed out. Run resenv login doppler to try again.');
+}
+
+exports.credential = credential;
+exports.login = login;

package/doppler/bridge.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+var node_child_process = require('node:child_process');
+var node_module = require('node:module');
+var node_path = require('node:path');
+var errors = require('../errors.cjs');
+var assertSafeDiagnostics = require('../assert-safe-diagnostics.cjs');
+var values = require('../values.cjs');
+var references = require('./references.cjs');
+var system = require('./system.cjs');
+
+const require$1 = node_module.createRequire(require('node:url').pathToFileURL(__filename).href);
+function resolveDopplerSync(env, run = node_child_process.spawnSync) {
+    const entries = references.references(env);
+    if (!entries.length)
+        return values.copyEnvironment({});
+    assertSafeDiagnostics.assertSafeDiagnostics();
+    const input = Object.fromEntries(entries.map(({ name }) => [name, env[name]]));
+    if (env.DOPPLER_TOKEN !== undefined)
+        input.DOPPLER_TOKEN = env.DOPPLER_TOKEN;
+    // Package self-resolution works both in the checkout and the packed artifact.
+    const manifestPath = require$1.resolve('@ciqol/resenv/package.json');
+    const manifest = require$1(manifestPath);
+    if (!values.isRecord(manifest) || typeof manifest.main !== 'string')
+        throw new errors.ResenvError('DOPPLER_RESOLUTION_FAILED', 'Invalid package entry point.');
+    const worker = node_path.join(node_path.dirname(manifestPath), node_path.dirname(manifest.main), 'doppler-worker.cjs');
+    const result = run(process.execPath, [worker], {
+        input: JSON.stringify(input), env: system.helperEnvironment(),
+        encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], shell: false,
+        timeout: 60000, killSignal: 'SIGKILL', maxBuffer: 1048576,
+        detached: process.platform !== 'win32'
+    });
+    if (result.error || result.signal) {
+        if (result.pid && process.platform !== 'win32') {
+            try {
+                process.kill(-result.pid, 'SIGKILL');
+            }
+            catch (err) {
+                if (!values.hasErrorCode(err, 'ESRCH')) {
+                    throw new errors.ResenvError('DOPPLER_RESOLUTION_FAILED', 'Could not stop resolver child processes after a resolution failure.');
+                }
+            }
+        }
+        throw new errors.ResenvError('DOPPLER_RESOLUTION_FAILED', 'Doppler resolution exceeded its startup time or output limit.');
+    }
+    let response;
+    try {
+        response = JSON.parse(result.stdout);
+    }
+    catch (err) {
+        if (!(err instanceof SyntaxError))
+            throw err;
+    }
+    const error = values.isRecord(response) ? response.error : undefined;
+    if (values.isRecord(error) && typeof error.code === 'string' && /^DOPPLER_[A-Z_]+$/.test(error.code) && typeof error.message === 'string') {
+        throw new errors.ResenvError(error.code, error.message);
+    }
+    const values$1 = values.isRecord(response) ? response.values : undefined;
+    if (result.status !== 0 || !values.isEnvironment(values$1) || Object.keys(values$1).length !== entries.length ||
+        entries.some(({ name }) => typeof values$1[name] !== 'string' || values$1[name]?.includes('\0'))) {
+        throw new errors.ResenvError('DOPPLER_RESOLUTION_FAILED', 'Doppler resolution returned an invalid result.');
+    }
+    return values$1;
+}
+
+exports.resolveDopplerSync = resolveDopplerSync;

package/doppler/http.cjs

@@ -0,0 +1,77 @@
+'use strict';
+
+var errors = require('../errors.cjs');
+var values = require('../values.cjs');
+
+const API_ORIGIN = 'https://api.doppler.com';
+// No environment-controlled endpoint or redirects: credentials stay at Doppler.
+function createClient(fetchImpl = globalThis.fetch) {
+    return async function request(path, { token, body, pending = false } = {}) {
+        let response;
+        try {
+            response = await fetchImpl(new URL(path, API_ORIGIN), {
+                method: body === undefined ? 'GET' : 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    'user-agent': 'ciqol-resenv',
+                    ...(token ? { authorization: `Bearer ${token}` } : {})
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+                redirect: 'error',
+                signal: AbortSignal.timeout(10000)
+            });
+            if (pending && response.status === 409) {
+                await response.body?.cancel();
+                return null;
+            }
+            if (!response.ok) {
+                await response.body?.cancel();
+                const code = response.status === 401 ? 'DOPPLER_AUTH_REQUIRED'
+                    : response.status === 403 ? 'DOPPLER_ACCESS_DENIED'
+                        : [404, 405, 501].includes(response.status) ? 'DOPPLER_ENDPOINT_UNAVAILABLE'
+                            : 'DOPPLER_REQUEST_FAILED';
+                throw new errors.ResenvError(code, `Doppler request failed (HTTP ${response.status}). Check your login and access.`);
+            }
+            const chunks = [];
+            let size = 0;
+            if (!response.body)
+                throw new errors.ResenvError('DOPPLER_INVALID_RESPONSE', 'Doppler returned an empty response.');
+            for await (const raw of response.body) {
+                const chunk = raw;
+                if (!(chunk instanceof Uint8Array))
+                    throw new errors.ResenvError('DOPPLER_INVALID_RESPONSE', 'Doppler returned invalid response bytes.');
+                size += chunk.length;
+                if (size > 1048576)
+                    throw new errors.ResenvError('DOPPLER_INVALID_RESPONSE', 'Doppler response exceeded the size limit.');
+                chunks.push(chunk);
+            }
+            let result;
+            try {
+                result = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+            }
+            catch (err) {
+                if (!(err instanceof TypeError || err instanceof SyntaxError))
+                    throw err;
+                throw new errors.ResenvError('DOPPLER_INVALID_RESPONSE', 'Doppler returned invalid UTF-8 or JSON.');
+            }
+            if (!values.isRecord(result) || result.success === false || result.error) {
+                throw new errors.ResenvError('DOPPLER_INVALID_RESPONSE', 'Doppler returned an unsuccessful or malformed response.');
+            }
+            return result;
+        }
+        catch (err) {
+            if (err instanceof errors.ResenvError)
+                throw err;
+            throw new errors.ResenvError('DOPPLER_REQUEST_FAILED', 'Could not complete the HTTPS request to Doppler. Check your connection and retry.');
+        }
+    };
+}
+function validateToken(token) {
+    if (typeof token !== 'string' || !/^dp\.[a-z]+\.[A-Za-z0-9_.-]{10,512}$/.test(token)) {
+        throw new errors.ResenvError('DOPPLER_INVALID_TOKEN', 'The Doppler credential is malformed. Run resenv login doppler or supply a valid DOPPLER_TOKEN.');
+    }
+    return token;
+}
+
+exports.createClient = createClient;
+exports.validateToken = validateToken;

package/doppler/references.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var errors = require('../errors.cjs');
+
+function references(env) {
+    const entries = Object.entries(env).filter((entry) => typeof entry[1] === 'string' && entry[1].startsWith('doppler://'));
+    if (entries.length > 128)
+        throw new errors.ResenvError('DOPPLER_TOO_MANY_REFERENCES', 'At most 128 Doppler references can be resolved per process.');
+    return entries.map(([name, value]) => {
+        // Parse the literal spelling: URL would lowercase hosts and normalize ../.
+        const match = /^doppler:\/\/([a-z0-9_-]+)\/([a-z0-9_-]+)\/([A-Za-z0-9_.:/%-]+)$/.exec(value);
+        let key;
+        try {
+            if (match?.[3])
+                key = decodeURIComponent(match[3]);
+        }
+        catch (err) {
+            if (!(err instanceof URIError))
+                throw err;
+        }
+        if (!match?.[1] || !match[2] || !key || key.length > 200 || !/^[A-Za-z0-9_.:/-]+$/.test(key) || key === '.' || key === '..') {
+            throw new errors.ResenvError('DOPPLER_INVALID_REFERENCE', `${JSON.stringify(name)} must use doppler://project/config/SECRET_NAME.`);
+        }
+        return { name, project: match[1], config: match[2], key };
+    });
+}
+
+exports.references = references;

package/doppler/resolve.cjs

@@ -0,0 +1,58 @@
+'use strict';
+
+var errors = require('../errors.cjs');
+var values = require('../values.cjs');
+var references = require('./references.cjs');
+var auth = require('./auth.cjs');
+var http = require('./http.cjs');
+
+// 2026-10-06: cap startup fan-out at four to overlap latency without a burst of
+// all 128 permitted references. The overall startup deadline still applies.
+const CONCURRENT_REQUESTS = 4;
+async function resolveReferences(env, { request = http.createClient(), getCredential = auth.credential } = {}) {
+    const entries = references.references(env);
+    const values$1 = values.copyEnvironment({});
+    if (!entries.length)
+        return values$1;
+    const groups = new Map();
+    for (const entry of entries) {
+        const query = new URLSearchParams({ project: entry.project, config: entry.config, name: entry.key });
+        const path = `/v3/configs/config/secret?${query.toString()}`;
+        const group = groups.get(path) || { path, names: [] };
+        group.names.push(entry.name);
+        groups.set(path, group);
+    }
+    const tasks = [...groups.values()];
+    const token = await getCredential(env);
+    let next = 0;
+    let failure;
+    const worker = async () => {
+        while (!failure && next < tasks.length) {
+            const task = tasks[next++];
+            if (!task)
+                return;
+            const { path, names } = task;
+            try {
+                const result = await request(path, { token });
+                const value = values.isRecord(result?.value) ? result.value.computed : undefined;
+                if (typeof value !== 'string' || !value.isWellFormed() || value.includes('\0') || Buffer.byteLength(value) > 65536) {
+                    throw new errors.ResenvError('DOPPLER_INVALID_VALUE', `Doppler did not return a usable value for ${JSON.stringify(names[0])}.`);
+                }
+                for (const name of names)
+                    values$1[name] = value;
+            }
+            catch (err) {
+                // Stop scheduling, but wait for already started requests to settle.
+                // No partial result escapes and no second credential is attempted.
+                failure ||= { err };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENT_REQUESTS, tasks.length) }, worker));
+    if (failure) {
+        throw failure.err;
+    }
+    return values$1;
+}
+
+exports.resolveReferences = resolveReferences;

package/doppler/system.cjs

@@ -0,0 +1,99 @@
+'use strict';
+
+var node_child_process = require('node:child_process');
+var node_fs = require('node:fs');
+var node_os = require('node:os');
+var errors = require('../errors.cjs');
+var assertSafeDiagnostics = require('../assert-safe-diagnostics.cjs');
+var http = require('./http.cjs');
+
+// Preserve saved logins from before the package rename.
+const SERVICE = 'ciqol.envref.doppler';
+const ACCOUNT = 'default';
+// Do not pass application secrets, NODE_OPTIONS, loader variables or a
+// repository's PATH to credential helpers. No helper is invoked via a shell.
+function helperEnvironment() {
+    const env = { HOME: node_os.userInfo().homedir, PATH: '/usr/bin:/bin', LANG: 'C.UTF-8' };
+    for (const key of ['SystemRoot', 'USERPROFILE', 'DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR', 'DISPLAY', 'WAYLAND_DISPLAY']) {
+        if (process.env[key])
+            env[key] = process.env[key];
+    }
+    return env;
+}
+function createSystem({ platform = process.platform, run = node_child_process.spawnSync, exists = node_fs.existsSync } = {}) {
+    const invoke = (file, args, options = {}) => {
+        assertSafeDiagnostics.assertSafeDiagnostics();
+        return run(file, args, {
+            env: helperEnvironment(), encoding: 'utf8', timeout: 15000,
+            maxBuffer: 16384, stdio: ['pipe', 'pipe', 'pipe'], shell: false, ...options
+        });
+    };
+    const mac = platform === 'darwin' && exists('/usr/bin/security');
+    const linux = platform === 'linux' && exists('/usr/bin/secret-tool');
+    const cli = ['/opt/homebrew/bin/doppler', '/usr/local/bin/doppler', '/usr/bin/doppler'].find(exists);
+    const unavailable = () => new errors.ResenvError('DOPPLER_KEYRING_UNAVAILABLE', 'The OS credential store is unavailable. Use the Doppler CLI or supply DOPPLER_TOKEN.');
+    function read() {
+        if (!mac && !linux)
+            return undefined;
+        const result = mac
+            ? invoke('/usr/bin/security', ['find-generic-password', '-s', SERVICE, '-a', ACCOUNT, '-w'])
+            : invoke('/usr/bin/secret-tool', ['lookup', 'service', SERVICE, 'account', ACCOUNT]);
+        if (!result.error && result.status === 0)
+            return http.validateToken(result.stdout.trim());
+        if (!result.error && ((mac && result.status === 44) || (linux && result.status === 1 && !result.stderr)))
+            return undefined;
+        throw unavailable();
+    }
+    function write(token) {
+        http.validateToken(token);
+        if (!mac && !linux)
+            throw unavailable();
+        // security's interactive interpreter receives the token on stdin, never
+        // the OS process argument list. The token alphabet excludes separators.
+        const result = mac
+            ? invoke('/usr/bin/security', ['-i'], { input: `add-generic-password -U -s ${SERVICE} -a ${ACCOUNT} -w ${token}\n` })
+            : invoke('/usr/bin/secret-tool', ['store', '--label=resenv Doppler', 'service', SERVICE, 'account', ACCOUNT], { input: token });
+        if (result.error || result.status !== 0)
+            throw unavailable();
+        // security -i may report a subcommand failure with a zero process status.
+        if (read() !== token)
+            throw unavailable();
+    }
+    function remove() {
+        if (!mac && !linux)
+            throw unavailable();
+        const result = mac
+            ? invoke('/usr/bin/security', ['delete-generic-password', '-s', SERVICE, '-a', ACCOUNT])
+            : invoke('/usr/bin/secret-tool', ['clear', 'service', SERVICE, 'account', ACCOUNT]);
+        if (result.error || (result.status !== 0 && !(mac && result.status === 44)))
+            throw unavailable();
+    }
+    function cliToken() {
+        if (!cli)
+            return undefined;
+        const result = invoke(cli, ['configure', 'get', 'token', '--plain']);
+        if (result.error || result.status !== 0 || !result.stdout.trim())
+            return undefined;
+        return http.validateToken(result.stdout.trim());
+    }
+    function cliLogin() {
+        if (!cli)
+            throw new errors.ResenvError('DOPPLER_CLI_UNAVAILABLE', 'Doppler CLI fallback is unavailable. Install Doppler or supply DOPPLER_TOKEN.');
+        const result = invoke(cli, ['login'], { stdio: 'inherit', timeout: 300000 });
+        if (result.error || result.status !== 0)
+            throw new errors.ResenvError('DOPPLER_LOGIN_FAILED', 'Doppler CLI login did not complete.');
+        if (!cliToken())
+            throw new errors.ResenvError('DOPPLER_LOGIN_FAILED', 'Doppler CLI login did not provide a credential.');
+    }
+    function openBrowser(url) {
+        const file = mac ? '/usr/bin/open' : '/usr/bin/xdg-open';
+        if (!exists(file))
+            return false;
+        const result = invoke(file, [url]);
+        return !result.error && result.status === 0;
+    }
+    return { read, write, remove, cliToken, cliLogin, openBrowser, canStore: mac || linux };
+}
+
+exports.createSystem = createSystem;
+exports.helperEnvironment = helperEnvironment;

package/doppler-worker.cjs

@@ -0,0 +1,28 @@
+'use strict';
+
+var node_fs = require('node:fs');
+var errors = require('./errors.cjs');
+var values = require('./values.cjs');
+var resolve = require('./doppler/resolve.cjs');
+
+// Private pipe protocol for the synchronous Node preload. Tokens and resolved
+// values never appear in process arguments, inherited env, or worker diagnostics.
+async function main() {
+    try {
+        const input = node_fs.readFileSync(0, 'utf8');
+        if (Buffer.byteLength(input) > 1048576)
+            throw new Error('Input exceeds limit');
+        const env = JSON.parse(input);
+        if (!values.isEnvironment(env))
+            throw new Error('Invalid environment input');
+        const values$1 = await resolve.resolveReferences(env);
+        process.stdout.write(JSON.stringify({ values: values$1 }));
+    }
+    catch (err) {
+        process.stdout.write(JSON.stringify({ error: err instanceof errors.ResenvError
+                ? { code: err.code, message: err.message }
+                : { code: 'DOPPLER_RESOLUTION_FAILED', message: 'Doppler resolution failed.' } }));
+        process.exitCode = 1;
+    }
+}
+void main();

package/doppler-worker.mjs

@@ -0,0 +1 @@
+import './doppler-worker.cjs';

package/errors.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+class ResenvError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ResenvError';
+        this.code = code;
+    }
+}
+
+exports.ResenvError = ResenvError;

package/index.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+var node_util = require('node:util');
+var commands = require('./commands.cjs');
+var errors = require('./errors.cjs');
+var references = require('./doppler/references.cjs');
+var bridge = require('./doppler/bridge.cjs');
+var values = require('./values.cjs');
+
+const debug = node_util.debuglog('ciqol:resenv');
+/** Always return a resolved copy; optionally commit replacements to the input. */
+function resolve(env = process.env, options = {}) {
+    const replace = options.replace === true;
+    // Proxy traps can fail during a later write after earlier values were changed.
+    if (replace && node_util.types.isProxy(env)) {
+        throw new errors.ResenvError('INVALID_ENV_TARGET', 'In-place resolution requires process.env or a record with writable data properties, not a Proxy.');
+    }
+    const snapshot = values.copyEnvironment(env);
+    const commandReferences = options.commands === true
+        ? Object.values(snapshot).filter(value => typeof value === 'string' && value.includes('$(')).length
+        : 0;
+    const dopplerCount = Object.values(snapshot).filter(value => typeof value === 'string' && value.startsWith('doppler://')).length;
+    const total = commandReferences + dopplerCount;
+    if (total === 0) {
+        if (replace)
+            replaceEnvironment(env, snapshot);
+        debug('Nothing to handle.');
+        return snapshot;
+    }
+    try {
+        // Reject invalid references before any optional command can have effects.
+        const dopplerEntries = references.references(snapshot);
+        const resolved = options.commands === true
+            ? commands.resolveCommands(snapshot, options, debug)
+            : values.copyEnvironment(snapshot);
+        if (dopplerEntries.length) {
+            // Resolve only original references. Command and cloud output stays literal.
+            const cloudInput = Object.fromEntries(dopplerEntries.map(({ name }) => [name, snapshot[name]]));
+            if (resolved.DOPPLER_TOKEN !== undefined)
+                cloudInput.DOPPLER_TOKEN = resolved.DOPPLER_TOKEN;
+            let values;
+            try {
+                values = bridge.resolveDopplerSync(cloudInput);
+            }
+            catch (err) {
+                debug('Failed to resolve Doppler references.');
+                throw err;
+            }
+            for (const { name } of dopplerEntries) {
+                resolved[name] = values[name];
+                debug('Replaced secret value for %s.', JSON.stringify(name));
+            }
+        }
+        if (replace)
+            replaceEnvironment(env, resolved);
+        debug('Done: replaced %d secret value(s).', total);
+        return resolved;
+    }
+    catch (err) {
+        debug('Done: failed (%s); environment unchanged.', err instanceof errors.ResenvError ? err.code : 'STARTUP_FAILED');
+        throw err;
+    }
+}
+function replaceEnvironment(env, resolved) {
+    const updates = [];
+    for (const [name, value] of Object.entries(resolved)) {
+        const descriptor = Object.getOwnPropertyDescriptor(env, name);
+        if (descriptor && 'value' in descriptor && descriptor.value === value)
+            continue;
+        if (descriptor ? !descriptor.writable : !Object.isExtensible(env)) {
+            throw new errors.ResenvError('INVALID_ENV_TARGET', `Cannot replace ${JSON.stringify(name)} on a target without a writable data property.`);
+        }
+        updates.push([name, { ...(descriptor || { writable: true, enumerable: true, configurable: true }), value }]);
+    }
+    // Preflight every write. No setters or Proxy traps run during this commit.
+    for (const [name, descriptor] of updates) {
+        Object.defineProperty(env, name, descriptor);
+    }
+}
+function formatError(error) {
+    if (error instanceof errors.ResenvError)
+        return `[resenv] ${error.code}: ${error.message}`;
+    return '[resenv] STARTUP_FAILED: Environment resolution failed.';
+}
+
+exports.ResenvError = errors.ResenvError;
+exports.formatError = formatError;
+exports.resolve = resolve;

package/index.d.cts

@@ -0,0 +1 @@
+export * from './types/src/index.js'

package/index.d.mts

@@ -0,0 +1 @@
+export * from './types/src/index.js'

package/index.mjs

@@ -0,0 +1 @@
+export { ResenvError, formatError, resolve } from './index.cjs';