@amodalai/amodal 0.2.10 → 0.3.1

package/src/commands/dev.ts

@@ -5,13 +5,60 @@
  */
 
 import type {CommandModule} from 'yargs';
+import type {ChildProcess} from 'node:child_process';
 import {existsSync, readFileSync} from 'node:fs';
 import {createRequire} from 'node:module';
+import {spawn} from 'node:child_process';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {createLocalServer, initLogLevel, interceptConsole} from '@amodalai/runtime';
+import {createLocalServer, initLogLevel, interceptConsole, log} from '@amodalai/runtime';
+import {resolveAdminAgent} from '@amodalai/core';
 import {findRepoRoot} from '../shared/repo-discovery.js';
+import {findFreePort} from '../shared/find-free-port.js';
 import {runConnectionPreflight, printPreflightTable} from '../shared/connection-preflight.js';
+import {resolveEnv} from '../shared/env-resolution.js';
+import {getDb, ensureSchema, closeDb} from '@amodalai/db';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_RUNTIME_PORT = 3847;
+const DEFAULT_STUDIO_PORT = 3848;
+const DEFAULT_ADMIN_PORT = 3849;
+
+// ---------------------------------------------------------------------------
+// Studio resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Locate the @amodalai/studio package directory. Two strategies:
+ * 1. Sibling directory relative to the CLI package (works when symlinked)
+ * 2. Node module resolution via createRequire (works when installed)
+ */
+function resolveStudioDir(): string | null {
+  // scriptDir is packages/cli/dist/src/commands/ at runtime (or packages/cli/src/commands/ in source)
+  // CLI package root is 3 levels up, then ../studio is the sibling package
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const cliRoot = path.resolve(scriptDir, '..', '..', '..');
+  const siblingCandidate = path.resolve(cliRoot, '..', 'studio');
+  if (existsSync(path.join(siblingCandidate, 'package.json'))) {
+    return siblingCandidate;
+  }
+  const require = createRequire(import.meta.url);
+  try {
+    return path.dirname(require.resolve('@amodalai/studio/package.json'));
+  } catch (err: unknown) {
+    log.debug('studio_resolve_failed', {
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
 
 export interface DevOptions {
   cwd?: string;
@@ -20,12 +67,240 @@ export interface DevOptions {
   resume?: string;
   verbose?: number;
   quiet?: boolean;
+  /** Disable Studio subprocess. */
+  noStudio?: boolean;
+  /** Disable admin agent subprocess. */
+  noAdmin?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Subprocess helpers
+// ---------------------------------------------------------------------------
+
+/** Managed subprocess with a label for log output. */
+interface ManagedProcess {
+  label: string;
+  child: ChildProcess;
+}
+
+/**
+ * Pipe a child process's stdout/stderr to the parent's stderr, prefixed
+ * with a label. Lines are buffered per-stream to avoid interleaved output
+ * from concurrent subprocesses.
+ */
+function pipeWithLabel(child: ChildProcess, label: string): void {
+  const prefix = `[${label}] `;
+  for (const stream of [child.stdout, child.stderr]) {
+    if (!stream) continue;
+    let buffer = '';
+    stream.setEncoding('utf-8');
+    stream.on('data', (chunk: string) => {
+      buffer += chunk;
+      const lines = buffer.split('\n');
+      // Keep the last (potentially incomplete) line in the buffer
+      buffer = lines.pop() ?? '';
+      for (const line of lines) {
+        process.stderr.write(`${prefix}${line}\n`);
+      }
+    });
+    stream.on('end', () => {
+      if (buffer.length > 0) {
+        process.stderr.write(`${prefix}${buffer}\n`);
+        buffer = '';
+      }
+    });
+  }
+}
+
+/**
+ * Kill all managed subprocesses. Returns once all processes have exited
+ * or after a 5-second timeout (whichever comes first).
+ */
+async function killAll(processes: ManagedProcess[]): Promise<void> {
+  const KILL_TIMEOUT_MS = 5000;
+  const exitPromises: Array<Promise<void>> = [];
+
+  for (const {child, label} of processes) {
+    if (child.exitCode !== null) continue; // already exited
+    exitPromises.push(
+      new Promise<void>((resolve) => {
+        const timer = setTimeout(() => {
+          log.warn('subprocess_kill_timeout', {label});
+          child.kill('SIGKILL');
+          resolve();
+        }, KILL_TIMEOUT_MS);
+
+        child.once('exit', () => {
+          clearTimeout(timer);
+          resolve();
+        });
+
+        child.kill('SIGTERM');
+      }),
+    );
+  }
+
+  await Promise.all(exitPromises);
+}
+
+// ---------------------------------------------------------------------------
+// Studio subprocess
+// ---------------------------------------------------------------------------
+
+interface StudioSpawnResult {
+  process: ManagedProcess;
+  url: string;
+}
+
+function spawnStudio(opts: {
+  port: number;
+  runtimePort: number;
+  repoPath: string;
+  agentId?: string;
+}): StudioSpawnResult | null {
+  // Resolve @amodalai/studio package directory. Try two strategies:
+  // 1. Sibling directory relative to the CLI package (works when symlinked from outside)
+  // 2. Node module resolution via createRequire (works when installed as a dependency)
+  const studioDir = resolveStudioDir();
+  if (!studioDir) {
+    log.info('studio_not_available', {
+      hint: '@amodalai/studio package not found — Studio subprocess skipped',
+    });
+    return null;
+  }
+
+  // Resolve the `next` binary from the studio-app's dependency tree.
+  // In pnpm the binary may live in the package's own node_modules or in a
+  // hoisted location; createRequire resolves correctly in both cases.
+  let nextBin: string;
+  try {
+    const studioRequire = createRequire(path.join(studioDir, 'package.json'));
+    // next/dist/bin/next is the actual CLI entrypoint
+    nextBin = studioRequire.resolve('next/dist/bin/next');
+  } catch {
+    log.info('studio_next_not_found', {
+      hint: 'next binary not resolvable from @amodalai/studio — Studio subprocess skipped',
+    });
+    return null;
+  }
+
+  const studioUrl = `http://localhost:${String(opts.port)}`;
+  const child = spawn(
+    process.execPath,
+    [nextBin, 'dev', '--port', String(opts.port)],
+    {
+      cwd: studioDir,
+      env: {
+        ...process.env,
+        REPO_PATH: opts.repoPath,
+        STUDIO_CORS_ORIGINS: `http://localhost:${String(opts.runtimePort)}`,
+        RUNTIME_URL: `http://localhost:${String(opts.runtimePort)}`,
+        PORT: String(opts.port),
+        ...(opts.agentId ? {AGENT_ID: opts.agentId} : {}),
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+
+  child.once('error', (err) => {
+    log.warn('studio_spawn_error', {error: err.message});
+  });
+
+  const label = 'studio';
+  pipeWithLabel(child, label);
+
+  child.once('exit', (code, signal) => {
+    if (code !== null && code !== 0) {
+      log.warn('subprocess_exited', {label, code});
+    } else if (signal) {
+      log.debug('subprocess_signaled', {label, signal});
+    }
+  });
+
+  return {
+    process: {label, child},
+    url: studioUrl,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Admin agent subprocess
+// ---------------------------------------------------------------------------
+
+interface AdminSpawnResult {
+  process: ManagedProcess;
+  url: string;
+}
+
+async function spawnAdminAgent(opts: {
+  port: number;
+  studioUrl: string | null;
+  repoPath: string;
+}): Promise<AdminSpawnResult | null> {
+  const adminAgentPath = await resolveAdminAgent(opts.repoPath);
+  if (!adminAgentPath) {
+    log.info('admin_agent_not_available', {
+      hint: 'No admin agent found at ~/.amodal/admin-agent/ or in amodal.json — skipped',
+    });
+    return null;
+  }
+
+  // Verify it has an amodal.json (is a valid agent directory)
+  if (!existsSync(path.join(adminAgentPath, 'amodal.json'))) {
+    log.warn('admin_agent_invalid', {
+      path: adminAgentPath,
+      hint: 'Directory exists but has no amodal.json — skipped',
+    });
+    return null;
+  }
+
+  // Resolve the CLI entrypoint. We're running inside the CLI already, so
+  // use the same executable to spawn the admin agent's dev server.
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const cliEntrypoint = path.resolve(scriptDir, '..', 'main.js');
+
+  const adminUrl = `http://localhost:${String(opts.port)}`;
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+  };
+  if (opts.studioUrl) {
+    env['STUDIO_URL'] = opts.studioUrl;
+  }
+
+  const child = spawn(
+    process.execPath,
+    [cliEntrypoint, 'dev', '--port', String(opts.port)],
+    {
+      cwd: adminAgentPath,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    },
+  );
+
+  const label = 'admin';
+  pipeWithLabel(child, label);
+
+  child.once('exit', (code, signal) => {
+    if (code !== null && code !== 0) {
+      log.warn('subprocess_exited', {label, code});
+    } else if (signal) {
+      log.debug('subprocess_signaled', {label, signal});
+    }
+  });
+
+  return {
+    process: {label, child},
+    url: adminUrl,
+  };
 }
 
-const DEFAULT_PORT = 3847;
+// ---------------------------------------------------------------------------
+// Main dev command
+// ---------------------------------------------------------------------------
 
 /**
- * Starts a local development server for the repo with hot reload enabled.
+ * Starts a local development server for the repo with hot reload enabled,
+ * and optionally spawns Studio and admin agent as subprocesses.
  */
 export async function runDev(options: DevOptions = {}): Promise<void> {
   initLogLevel({verbosity: options.verbose ?? 0, quiet: options.quiet ?? false});
@@ -40,26 +315,133 @@ export async function runDev(options: DevOptions = {}): Promise<void> {
     process.exit(1);
   }
 
-  // Load .env file from the repo root (if present)
-  const envPath = path.join(repoPath, '.env');
-  if (existsSync(envPath)) {
-    const envContent = readFileSync(envPath, 'utf-8');
-    for (const line of envContent.split('\n')) {
-      const trimmed = line.trim();
-      if (!trimmed || trimmed.startsWith('#')) continue;
-      const eqIdx = trimmed.indexOf('=');
-      if (eqIdx === -1) continue;
-      const key = trimmed.slice(0, eqIdx).trim();
-      const value = trimmed.slice(eqIdx + 1).trim();
-      if (key && !(key in process.env)) {
-        process.env[key] = value;
+  // -------------------------------------------------------------------------
+  // Require DATABASE_URL
+  // -------------------------------------------------------------------------
+
+  const databaseUrl = resolveEnv('DATABASE_URL', repoPath);
+  if (!databaseUrl) {
+    log.error('database_url_required', {});
+    process.stderr.write(`
+DATABASE_URL is required. Start Postgres and configure it:
+
+  docker run -d --name amodal-pg -p 5432:5432 \\
+    -e POSTGRES_DB=amodal -e POSTGRES_HOST_AUTH_METHOD=trust postgres:17
+
+Then set the connection string:
+
+  echo 'DATABASE_URL=postgres://localhost:5432/amodal' >> ~/.amodal/.env
+
+Or add it to your agent's .env file:
+
+  echo 'DATABASE_URL=postgres://localhost:5432/amodal' >> .env
+
+`);
+    process.exit(1);
+  }
+
+  // Make DATABASE_URL available to child processes (runtime, Studio)
+  process.env['DATABASE_URL'] = databaseUrl;
+
+  // Read agent name from amodal.json for AGENT_ID
+  const amodalJsonPath = path.join(repoPath, 'amodal.json');
+  let agentId: string | undefined;
+  if (existsSync(amodalJsonPath)) {
+    try {
+      const amodalJson: unknown = JSON.parse(readFileSync(amodalJsonPath, 'utf-8'));
+      const parsed = typeof amodalJson === 'object' && amodalJson !== null
+        ? amodalJson
+        : undefined;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- JSON.parse boundary: validated with typeof guard above
+      const nameValue = parsed !== undefined ? (parsed as Record<string, unknown>)['name'] : undefined;
+      if (typeof nameValue === 'string') {
+        agentId = nameValue;
+        process.env['AGENT_ID'] = agentId;
       }
+    } catch (err: unknown) {
+      log.warn('amodal_json_parse_error', {
+        path: amodalJsonPath,
+        error: err instanceof Error ? err.message : String(err),
+      });
     }
   }
 
-  const port = options.port ?? DEFAULT_PORT;
+  // -------------------------------------------------------------------------
+  // Run schema migrations
+  // -------------------------------------------------------------------------
+
+  try {
+    const migrationDb = getDb(databaseUrl);
+    await ensureSchema(migrationDb);
+    await closeDb(); // Close migration connection — runtime and Studio open their own
+    log.info('schema_migration_complete', {});
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error('schema_migration_failed', {error: msg});
+    process.stderr.write(`[dev] Failed to run database migrations: ${msg}\n`);
+    process.stderr.write('[dev] Is Postgres running and DATABASE_URL correct?\n');
+    process.exit(1);
+  }
+
   const host = options.host ?? '0.0.0.0';
 
+  // -------------------------------------------------------------------------
+  // Port allocation
+  // -------------------------------------------------------------------------
+
+  const runtimePort = await findFreePort(options.port ?? DEFAULT_RUNTIME_PORT);
+  const studioPort = options.noStudio
+    ? DEFAULT_STUDIO_PORT
+    : await findFreePort(DEFAULT_STUDIO_PORT);
+  const adminPort = options.noAdmin
+    ? DEFAULT_ADMIN_PORT
+    : await findFreePort(DEFAULT_ADMIN_PORT);
+
+  log.info('ports_allocated', {
+    runtime: runtimePort,
+    studio: options.noStudio ? null : studioPort,
+    admin: options.noAdmin ? null : adminPort,
+  });
+
+  // -------------------------------------------------------------------------
+  // Spawn subprocesses
+  // -------------------------------------------------------------------------
+
+  const managedProcesses: ManagedProcess[] = [];
+  let studioUrl: string | null = null;
+  let adminAgentUrl: string | null = null;
+
+  // Studio
+  if (!options.noStudio) {
+    const studioResult = spawnStudio({
+      port: studioPort,
+      runtimePort,
+      repoPath,
+      agentId,
+    });
+    if (studioResult) {
+      managedProcesses.push(studioResult.process);
+      studioUrl = studioResult.url;
+    }
+  }
+
+  // Admin agent
+  if (!options.noAdmin) {
+    const adminResult = await spawnAdminAgent({
+      port: adminPort,
+      studioUrl,
+      repoPath,
+    });
+    if (adminResult) {
+      managedProcesses.push(adminResult.process);
+      adminAgentUrl = adminResult.url;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Start the runtime server
+  // -------------------------------------------------------------------------
+
   process.stderr.write(`[dev] Starting dev server for ${repoPath}\n`);
 
   try {
@@ -88,16 +470,30 @@ export async function runDev(options: DevOptions = {}): Promise<void> {
 
     const server = await createLocalServer({
       repoPath,
-      port,
+      port: runtimePort,
       host,
       hotReload: true,
       corsOrigin: '*',
       staticAppDir,
       resumeSessionId: options.resume,
+      studioUrl: studioUrl ?? undefined,
+      adminAgentUrl: adminAgentUrl ?? undefined,
     });
 
     await server.start();
 
+    // Print all URLs
+    process.stderr.write('\n');
+    process.stderr.write(`  Runtime:     http://localhost:${String(runtimePort)}\n`);
+    if (studioUrl) {
+      process.stderr.write(`  Studio:      ${studioUrl}\n`);
+    }
+    if (adminAgentUrl) {
+      process.stderr.write(`  Admin Agent: ${adminAgentUrl}\n`);
+    }
+    process.stderr.write(`  Database:    ${databaseUrl}\n`);
+    process.stderr.write('\n');
+
     // Preflight connection check (non-blocking)
     const preflight = await runConnectionPreflight(repoPath);
     if (preflight.results.length > 0) {
@@ -112,6 +508,13 @@ export async function runDev(options: DevOptions = {}): Promise<void> {
     // Graceful shutdown
     const shutdown = async (signal: string): Promise<void> => {
       process.stderr.write(`\n[dev] Received ${signal}, shutting down...\n`);
+
+      // Kill subprocesses first
+      if (managedProcesses.length > 0) {
+        log.info('subprocess_shutdown', {count: managedProcesses.length});
+        await killAll(managedProcesses);
+      }
+
       await server.stop();
       process.exit(0);
     };
@@ -119,6 +522,10 @@ export async function runDev(options: DevOptions = {}): Promise<void> {
     process.on('SIGTERM', () => void shutdown('SIGTERM'));
     process.on('SIGINT', () => void shutdown('SIGINT'));
   } catch (err) {
+    // Kill any already-spawned subprocesses before exiting
+    if (managedProcesses.length > 0) {
+      await killAll(managedProcesses);
+    }
     const msg = err instanceof Error ? err.message : String(err);
     process.stderr.write(`[dev] Failed to start: ${msg}\n`);
     process.exit(1);
@@ -153,6 +560,16 @@ export const devCommand: CommandModule = {
       describe: 'Only show errors',
       default: false,
     },
+    'no-studio': {
+      type: 'boolean',
+      describe: 'Do not spawn Studio subprocess',
+      default: false,
+    },
+    'no-admin': {
+      type: 'boolean',
+      describe: 'Do not spawn admin agent subprocess',
+      default: false,
+    },
   },
   handler: async (argv) => {
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
@@ -165,6 +582,10 @@ export const devCommand: CommandModule = {
     const verbose = argv['verbose'] as number;
     // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
     const quiet = argv['quiet'] as boolean;
-    await runDev({port, host, resume, verbose, quiet});
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const noStudio = argv['no-studio'] as boolean;
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+    const noAdmin = argv['no-admin'] as boolean;
+    await runDev({port, host, resume, verbose, quiet, noStudio, noAdmin});
   },
 };

package/src/shared/env-resolution.test.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {mkdtempSync, writeFileSync, mkdirSync, rmSync} from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {resolveEnv} from './env-resolution.js';
+
+describe('resolveEnv', () => {
+  let tmpDir: string;
+  let fakeHome: string;
+  let origHome: string;
+  let origEnvValue: string | undefined;
+  const TEST_KEY = 'AMODAL_TEST_RESOLVE_ENV_KEY';
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), 'env-resolution-test-'));
+    fakeHome = mkdtempSync(path.join(os.tmpdir(), 'env-resolution-home-'));
+    origHome = process.env['HOME'] ?? '';
+    origEnvValue = process.env[TEST_KEY];
+    delete process.env[TEST_KEY];
+    // Override HOME so ~/.amodal/env resolves to our temp dir
+    process.env['HOME'] = fakeHome;
+  });
+
+  afterEach(() => {
+    process.env['HOME'] = origHome;
+    if (origEnvValue !== undefined) {
+      process.env[TEST_KEY] = origEnvValue;
+    } else {
+      delete process.env[TEST_KEY];
+    }
+    rmSync(tmpDir, {recursive: true, force: true});
+    rmSync(fakeHome, {recursive: true, force: true});
+  });
+
+  it('resolves from agent .env file', () => {
+    writeFileSync(path.join(tmpDir, '.env'), `${TEST_KEY}=agent-value\n`);
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('agent-value');
+  });
+
+  it('resolves from ~/.amodal/env', () => {
+    mkdirSync(path.join(fakeHome, '.amodal'), {recursive: true});
+    writeFileSync(path.join(fakeHome, '.amodal', '.env'), `${TEST_KEY}=global-value\n`);
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('global-value');
+  });
+
+  it('resolves from process.env', () => {
+    process.env[TEST_KEY] = 'shell-value';
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('shell-value');
+  });
+
+  it('agent .env takes priority over global', () => {
+    writeFileSync(path.join(tmpDir, '.env'), `${TEST_KEY}=agent-value\n`);
+    mkdirSync(path.join(fakeHome, '.amodal'), {recursive: true});
+    writeFileSync(path.join(fakeHome, '.amodal', '.env'), `${TEST_KEY}=global-value\n`);
+    process.env[TEST_KEY] = 'shell-value';
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('agent-value');
+  });
+
+  it('global takes priority over process.env', () => {
+    mkdirSync(path.join(fakeHome, '.amodal'), {recursive: true});
+    writeFileSync(path.join(fakeHome, '.amodal', '.env'), `${TEST_KEY}=global-value\n`);
+    process.env[TEST_KEY] = 'shell-value';
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('global-value');
+  });
+
+  it('returns undefined when not found anywhere', () => {
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBeUndefined();
+  });
+
+  it('handles comments and empty lines in .env files', () => {
+    writeFileSync(
+      path.join(tmpDir, '.env'),
+      `# This is a comment\n\nIRRELEVANT=foo\n\n${TEST_KEY}=found-it\n# trailing comment\n`,
+    );
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('found-it');
+  });
+
+  it('strips quotes from values', () => {
+    writeFileSync(path.join(tmpDir, '.env'), `${TEST_KEY}="quoted-value"\n`);
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('quoted-value');
+  });
+
+  it('strips single quotes from values', () => {
+    writeFileSync(path.join(tmpDir, '.env'), `${TEST_KEY}='single-quoted'\n`);
+    expect(resolveEnv(TEST_KEY, tmpDir)).toBe('single-quoted');
+  });
+});

package/src/shared/env-resolution.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * Resolve a config value from (in priority order):
+ * 1. Agent .env file (cwd/.env)
+ * 2. Global ~/.amodal/env
+ * 3. Shell environment (process.env)
+ */
+export function resolveEnv(key: string, cwd: string): string | undefined {
+  // 1. Agent .env
+  const agentEnvPath = path.join(cwd, '.env');
+  const agentValue = readEnvFile(agentEnvPath, key);
+  if (agentValue !== undefined) return agentValue;
+
+  // 2. Global ~/.amodal/.env
+  const globalEnvPath = path.join(os.homedir(), '.amodal', '.env');
+  const globalValue = readEnvFile(globalEnvPath, key);
+  if (globalValue !== undefined) return globalValue;
+
+  // 3. Shell environment
+  return process.env[key];
+}
+
+/**
+ * Read a single key from a .env-style file. Returns undefined if the file
+ * does not exist, cannot be read, or does not contain the key.
+ */
+function readEnvFile(filePath: string, key: string): string | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith('#') || !trimmed.includes('=')) continue;
+      const eqIndex = trimmed.indexOf('=');
+      const k = trimmed.slice(0, eqIndex).trim();
+      const v = trimmed.slice(eqIndex + 1).trim().replace(/^["']|["']$/g, '');
+      if (k === key) return v;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}