fix: parse dotenv files without shell execution

Author: devalade

src/domain/deploy/backend-strategy.ts

@@ -8,6 +8,7 @@ import { getInstallCommand, getRunCommand, detectPkgManager } from '../framework
 import { RSYNC_DEFAULT_EXCLUDES } from '../../shared/constants.js';
 import { DeployError } from '../../shared/errors.js';
 import type { DeploymentStrategy, StrategyContext } from './strategy.js';
+import { runWithDotenv } from './dotenv.js';
 
 function escapeSingleQuotes(s: string): string {
   return s.replace(/'/g, "\\'");
@@ -25,20 +26,6 @@ function parseCommand(command: string | undefined, pkgManager: string): { script
   return { script: parts[0], args: parts.slice(1).join(' ') };
 }
 
-/**
- * Shell snippet that sources the workDir-local `.env` into the current shell
- * so subsequent && commands inherit the variables. Returns empty string when
- * the project has no envFile so callers can interpolate it unconditionally.
- *
- * Used during install, build, and post-symlink relink. The PM2 wrapper takes
- * the same approach (see generateAppBlock) but sources `<shared>/<envFile>`
- * directly — it doesn't depend on the workDir symlink.
- */
-function sourceEnvCommand(envFile: string | undefined): string {
-  if (!envFile) return '';
-  return `set -a && . ./.env && set +a`;
-}
-
 export class BackendStrategy implements DeploymentStrategy {
   readonly name = 'backend';
 
@@ -98,11 +85,6 @@ export class BackendStrategy implements DeploymentStrategy {
         `{ echo ${shellSingleQuote(missingEnvMessage)} >&2; exit 1; }`,
       );
       commands.push(`ln -sf "${this.appPath}/shared/${this.app.envFile}" .env`);
-      // Source it so install/build see env vars (private-registry tokens in
-      // `.npmrc` via `${TOKEN}`, build-time secrets, etc.). Affects this shell
-      // chain only; the PM2 wrapper sources independently at process start.
-      const sourceCmd = sourceEnvCommand(this.app.envFile);
-      if (sourceCmd) commands.push(sourceCmd);
     }
 
     // Ensure third-party package managers are available on the remote
@@ -114,10 +96,10 @@ export class BackendStrategy implements DeploymentStrategy {
       commands.push(`command -v bun &>/dev/null || npm install -g bun`);
     }
 
-    commands.push(installCmd);
+    const envDependentCommands = [installCmd];
 
     if (!ctx.skipBuild) {
-      commands.push(`if [ -f package.json ] && jq -e '.scripts.build' package.json >/dev/null 2>&1; then ${runCmd} build; fi`);
+      envDependentCommands.push(`if [ -f package.json ] && jq -e '.scripts.build' package.json >/dev/null 2>&1; then ${runCmd} build; fi`);
     }
 
     // Symlink `.env` into compiled-output directories so frameworks whose env
@@ -128,7 +110,9 @@ export class BackendStrategy implements DeploymentStrategy {
     //   3. obvious monorepo layouts: `apps/*/build`, `packages/*/build`, dist twins
     // We never traverse into node_modules and never overwrite an existing
     // `.env` file.
-    commands.push(this.getEnvSymlinkCommand(ctx.workDir));
+    envDependentCommands.push(this.getEnvSymlinkCommand(ctx.workDir));
+
+    commands.push(runWithDotenv(this.app.envFile ? '.env' : undefined, envDependentCommands.join(' && ')));
 
     const installResult = await ctx.executor.exec(commands.join(' && '));
     this.assertNoBuildScriptsIgnored(pkgManager, installResult);
@@ -311,12 +295,8 @@ export class BackendStrategy implements DeploymentStrategy {
   ): Promise<void> {
     const baseInstall = this.workspace.installCommand ?? getInstallCommand(pkgManager);
     const relinkInstall = this.workspace.installCommand ? baseInstall : `${baseInstall} --prefer-offline`;
-    // Source env before relinking — private-registry tokens in `.npmrc` use
-    // env-var interpolation.
-    const sourceCmd = sourceEnvCommand(this.app.envFile);
-    const sourceStep = sourceCmd ? `${sourceCmd} && ` : '';
     const installResult = await ctx.executor.exec(
-      `cd "${cdPath}" && ${mise} && ${sourceStep}${relinkInstall}`,
+      `cd "${cdPath}" && ${mise} && ${runWithDotenv(this.app.envFile ? '.env' : undefined, relinkInstall)}`,
     );
     this.assertNoBuildScriptsIgnored(pkgManager, installResult);
     if (installResult.exitCode !== 0) {
@@ -393,16 +373,9 @@ ${appBlocks.join(',\n')}
 
     if (useWrapper) {
       const tail = origArgs ? `${origScript} ${origArgs}` : origScript;
-      // Sourcing the dotenv file happens inside the PM2-launched shell, so it
-      // can overwrite inline PM2 values such as the blue-green port. Re-apply
-      // the ecosystem's explicit values afterwards to preserve their normal
-      // precedence over the shared environment.
-      const explicitEnv = Object.entries(env)
-        .map(([key, value]) => `${key}=${shellSingleQuote(String(value))}`)
-        .join(' ');
-      const inner = `set -a && . '${escapeSingleQuotes(envFilePath)}' && set +a && export ${explicitEnv} && exec ${tail}`;
+      const runner = runWithDotenv(envFilePath, `exec ${tail}`, env);
       scriptLine = `script: 'bash',`;
-      argsLine = `\n      args: ['-c', '${escapeSingleQuotes(inner)}'],`;
+      argsLine = `\n      args: ['-c', '${escapeSingleQuotes(runner)}'],`;
     } else {
       scriptLine = `script: '${escapeSingleQuotes(origScript)}',`;
       argsLine = origArgs ? `\n      args: '${escapeSingleQuotes(origArgs)}',` : '';

src/domain/deploy/dotenv.ts

@@ -0,0 +1,25 @@
+function shellSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+
+// This program deliberately parses dotenv as data. It is passed to the remote
+// Node runtime with `-e`, so values from the dotenv file never become shell
+// syntax. It supports the dotenv forms Node applications commonly use:
+// comments, `export KEY=...`, quoted values and quoted multiline values.
+const dotenvRunner = String.raw`const fs=require('node:fs');const{spawn}=require('node:child_process');const[file,encodedEnv,command,...args]=process.argv.slice(1);const text=fs.readFileSync(file,'utf8').replace(/^\uFEFF/,'');const parsed={};const line=/(?:^|\n)\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*\x60(?:\\\x60|[^\x60])*\x60|[^\n]*)/g;let match;while((match=line.exec(text))!==null){let value=match[2].trim();const quote=value[0];if((quote==='"'||quote==="'"||quote==='\x60')&&value.at(-1)===quote){value=value.slice(1,-1);if(quote==='"')value=value.replace(/\\n/g,'\n').replace(/\\r/g,'\r');}else{value=value.replace(/\s+#.*$/,'').trim();}parsed[match[1]]=value;}const explicit=JSON.parse(Buffer.from(encodedEnv,'base64url').toString('utf8'));Object.assign(process.env,parsed,explicit);const child=spawn(command,args,{env:process.env,stdio:'inherit'});child.on('error',error=>{console.error(error.message);process.exit(1);});child.on('exit',(code,signal)=>process.exit(code??(signal?1:0)));`;
+
+/**
+ * Runs a shell command with values parsed from a dotenv file without sourcing
+ * that file. Explicit process values win over the dotenv file.
+ */
+export function runWithDotenv(
+  envFile: string | undefined,
+  command: string,
+  explicitEnvironment: Record<string, string | number> = {},
+): string {
+  if (!envFile) return command;
+
+  const encodedEnvironment = Buffer.from(JSON.stringify(explicitEnvironment)).toString('base64url');
+  return `node -e ${shellSingleQuote(dotenvRunner)} -- ` +
+    `${shellSingleQuote(envFile)} ${shellSingleQuote(encodedEnvironment)} bash -c ${shellSingleQuote(command)}`;
+}

src/domain/deploy/orchestrator.ts

@@ -18,6 +18,7 @@ import {
 import type { DeploymentStrategy, StrategyContext } from './strategy.js';
 import { BackendStrategy } from './backend-strategy.js';
 import { FrontendStrategy } from './frontend-strategy.js';
+import { runWithDotenv } from './dotenv.js';
 
 export class DeployOrchestrator {
   constructor(
@@ -241,9 +242,6 @@ export class DeployOrchestrator {
 
     const mise = `export PATH="$HOME/.local/bin:$HOME/.local/share/mise/shims:$PATH"`;
     const hookCwd = app.appRoot ? `${workDir}/${app.appRoot}` : workDir;
-    const envSource = app.envFile
-      ? `set -a && . "${workDir}/.env" && set +a && `
-      : '';
     const prefix = chalk.dim('  │ ');
 
     const onData = (chunk: string): void => {
@@ -257,7 +255,7 @@ export class DeployOrchestrator {
       env: 'production',
       exec: async (cmd: string): Promise<ExecResult> => {
         const result = await this.executor.exec(
-          `cd "${hookCwd}" && ${mise} && ${envSource}${cmd}`,
+          `cd "${hookCwd}" && ${mise} && ${runWithDotenv(app.envFile ? `${workDir}/.env` : undefined, cmd)}`,
           { onData },
         );
         if (result.exitCode !== 0) {

tests/unit/backend-strategy.test.ts

@@ -233,16 +233,17 @@ describe('BackendStrategy.setupEnvironment', () => {
     expect(cmd).toContain('"dist"');
   });
 
-  it('sources .env before install so private-registry tokens (npmrc ${VAR}) resolve', async () => {
+  it('loads .env with Node before install so private-registry tokens (npmrc ${VAR}) resolve', async () => {
     const strategy = makeStrategy(makeConfig({ pkgManager: 'pnpm' }), '/local/project');
     const executor = new FakeRemoteExecutor();
     await strategy.setupEnvironment!(makeCtx(executor));
 
     const cmd = executor.getLastCommand()!.command;
-    const sourceIdx = cmd.indexOf('set -a && . ./.env && set +a');
+    const sourceIdx = cmd.indexOf('node -e');
     const installIdx = cmd.indexOf('pnpm install');
     expect(sourceIdx).toBeGreaterThan(-1);
     expect(installIdx).toBeGreaterThan(sourceIdx);
+    expect(cmd).not.toContain('set -a');
   });
 
   it('links the shared env using the configured envFile name, not a hardcoded .env', async () => {
@@ -426,7 +427,7 @@ describe('BackendStrategy.startApp', () => {
     await expect(strategy.startApp!(makeCtx(executor))).rejects.toThrow('pnpm approve-builds');
   });
 
-  it('drops the env_file ecosystem entry in favor of a bash -c env wrapper (ADR-0003)', async () => {
+  it('drops the env_file ecosystem entry in favor of a Node dotenv wrapper (ADR-0003)', async () => {
     const strategy = makeStrategy(makeConfig({ envFile: '.env.production' }), '/local/project');
     const executor = new FakeRemoteExecutor();
     await strategy.startApp!(makeCtx(executor));
@@ -435,11 +436,11 @@ describe('BackendStrategy.startApp', () => {
     expect(writeCmd).not.toContain('env_file:');
     expect(writeCmd).toContain(`script: '"'"'bash'"'"',`);
     expect(writeCmd).toContain('shared/.env.production');
-    expect(writeCmd).toContain('set -a');
-    expect(writeCmd).toContain('export NODE_ENV=');
-    expect(writeCmd).toContain('PORT=');
+    expect(writeCmd).toContain('node -e');
+    expect(writeCmd).not.toContain('set -a');
+    expect(writeCmd).toContain('base64url');
+    expect(writeCmd).toContain('NODE_ENV');
     expect(writeCmd).toContain('3000');
-    expect(writeCmd.indexOf('export NODE_ENV=')).toBeGreaterThan(writeCmd.indexOf('set +a'));
     expect(writeCmd).toContain('exec');
   });
 

tests/unit/dotenv.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { execa } from 'execa';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runWithDotenv } from '../../src/domain/deploy/dotenv.js';
+
+const temporaryDirectories: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })));
+});
+
+describe('runWithDotenv', () => {
+  it('passes shell-sensitive and multiline values as data without executing them', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'shipnode-dotenv-'));
+    temporaryDirectories.push(directory);
+    const envFile = join(directory, '.env');
+    const marker = join(directory, 'must-not-exist');
+    await writeFile(envFile, `TOKEN="safe; touch ${marker}"\nMULTILINE="first\\nsecond"\n`);
+
+    const command = runWithDotenv(
+      envFile,
+      "node -e 'process.stdout.write(JSON.stringify({ token: process.env.TOKEN, multiline: process.env.MULTILINE }))'",
+    );
+    const result = await execa('bash', ['-c', command]);
+
+    expect(result.stdout).toBe(JSON.stringify({ token: `safe; touch ${marker}`, multiline: 'first\nsecond' }));
+    await expect(execa('test', ['-e', marker])).rejects.toMatchObject({ exitCode: 1 });
+  });
+
+  it('lets explicit process values override dotenv values', async () => {
+    const directory = await mkdtemp(join(tmpdir(), 'shipnode-dotenv-'));
+    temporaryDirectories.push(directory);
+    const envFile = join(directory, '.env');
+    await writeFile(envFile, 'PORT=3000\n');
+
+    const command = runWithDotenv(envFile, "node -e 'process.stdout.write(process.env.PORT)'", { PORT: 13000 });
+    const result = await execa('bash', ['-c', command]);
+
+    expect(result.stdout).toBe('13000');
+  });
+});

tests/unit/orchestrator.test.ts

@@ -65,7 +65,7 @@ describe('DeployOrchestrator', () => {
     expect(lockRelease.length).toBeGreaterThan(0);
   });
 
-  it('sources .env before user preDeploy commands when envFile is configured', async () => {
+  it('loads .env with Node before user preDeploy commands when envFile is configured', async () => {
     const executor = new FakeRemoteExecutor();
     let captured: string | undefined;
     const config = makeConfig({
@@ -106,10 +106,11 @@ describe('DeployOrchestrator', () => {
     await orchestrator.deploy({ cwd: '/test', skipBuild: false });
 
     expect(captured).toBeDefined();
-    const sourceIdx = captured!.search(/set -a && \. "[^"]*\/\.env" && set \+a/);
+    const sourceIdx = captured!.indexOf('node -e');
     const userIdx = captured!.indexOf('node ace.js migration:run');
     expect(sourceIdx).toBeGreaterThan(-1);
     expect(userIdx).toBeGreaterThan(sourceIdx);
+    expect(captured).not.toContain('set -a');
   });
 
   it('runs hooks from <workDir>/<appRoot> when appRoot is configured', async () => {