feat: project env runtime support (#68)

* chore: start issue 41 env runtime support

Open a draft branch for the project-specific environment variable runtime support work before implementation begins.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add project-specific environment variable runtime support (#68)

Implements Issue #41 - Project-specific environment variable runtime support

Changes:
- Add PersistedEnvVariable type and envVars field to PersistedProject
- Add .env file parsing utility with parseEnvFile and mergeEnvVars functions
- Add env-resolution helper for terminal spawn with variable expansion
- Extend DialogApi with selectFile method for .env file selection
- Update ProjectSettings to support .env import with error handling
- Pass resolved env vars through all terminal spawn paths:
  - WorkspaceLayout handleCreateTerminalInPane
  - use-terminal-restore restoreFromLayout and createDefaultTerminal
  - use-snapshots restoreFromSnapshot
- Print one-time terminal info line when env vars are applied
- Add comprehensive test coverage for env-parser utility

Technical details:
- Supports Unix ($VAR, ${VAR}) and Windows (%VAR%) variable references
- Only expands against inherited system/process env, not other project vars
- Normalizes env vars on save (trims keys, filters empty)
- Shows warnings for invalid lines during .env import

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address code review findings for env var runtime support

- Fix race condition in handleImportEnvFile by capturing project ID and using
  functional state updates
- Make inheritedEnv parameter required in resolveEnvForSpawn and add TODO
  for fetching system env from backend
- Use hasProjectEnv flag to conditionally pass env to terminal spawn
- Add env notice check in ConnectedTerminal for external terminal ID path
- Add TODO comments about secure storage for secret env var values

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: gnoviawan

src/renderer/components/terminal/ConnectedTerminal.tsx

@@ -614,6 +614,11 @@ function ConnectedTerminalComponent({
             if (initialScrollback && initialScrollback.length > 0) {
               restoreScrollback(terminal, initialScrollback)
             }
+            // Write one-time info line if project env vars were applied
+            if (memoizedSpawnOptions?.env && Object.keys(memoizedSpawnOptions.env).length > 0) {
+              const envCount = Object.keys(memoizedSpawnOptions.env).length
+              terminal.write(`\x1b[36m\r\n[Project env: ${envCount} variable${envCount !== 1 ? 's' : ''} applied]\x1b[0m\r\n`)
+            }
             // Restore scroll position if cached from previous pane
             restoreScrollPosition(result.data.id, terminal)
             if (onSpawned) {
@@ -646,6 +651,12 @@ function ConnectedTerminalComponent({
         if (initialScrollback && initialScrollback.length > 0) {
           restoreScrollback(terminal, initialScrollback)
         }
+        // Write one-time info line if project env vars were applied
+        // (env should be passed via spawnOptions by the caller if this terminal was spawned with env vars)
+        if (memoizedSpawnOptions?.env && Object.keys(memoizedSpawnOptions.env).length > 0) {
+          const envCount = Object.keys(memoizedSpawnOptions.env).length
+          terminal.write(`\x1b[36m\r\n[Project env: ${envCount} variable${envCount !== 1 ? 's' : ''} applied]\x1b[0m\r\n`)
+        }
         // Restore scroll position if cached from previous pane
         restoreScrollPosition(externalTerminalId, terminal)
         if (onBoundToStoreTerminalRef.current) {
@@ -667,7 +678,7 @@ function ConnectedTerminalComponent({
       const terminalId = ptyIdRef.current || externalTerminalId
       if (terminalId && terminalRef.current) {
         captureScrollPosition(terminalId)
-        void removeRendererRef(terminalId, instanceIdRef.current)
+        void removeRendererRef(terminalId, instanceId)
       }
 
       // Unregister terminal from registry

src/renderer/hooks/use-projects-persistence.ts

@@ -13,7 +13,15 @@ function toPersistedProject(project: Project): PersistedProject {
     path: project.path,
     isArchived: project.isArchived,
     gitBranch: project.gitBranch,
-    defaultShell: project.defaultShell
+    defaultShell: project.defaultShell,
+    // TODO: Secret values (isSecret===true) should be stored in secure OS storage (keyring/secureStore)
+    // instead of plaintext. For now, we persist all values but this is a security concern.
+    // A future PR should implement secure storage for secrets.
+    envVars: project.envVars?.map((envVar) => ({
+      key: envVar.key,
+      value: envVar.value,
+      isSecret: envVar.isSecret
+    }))
   }
 }
 
@@ -25,7 +33,12 @@ function fromPersistedProject(persisted: PersistedProject): Project {
     path: persisted.path,
     isArchived: persisted.isArchived,
     gitBranch: persisted.gitBranch,
-    defaultShell: persisted.defaultShell
+    defaultShell: persisted.defaultShell,
+    envVars: persisted.envVars?.map((envVar) => ({
+      key: envVar.key,
+      value: envVar.value,
+      isSecret: envVar.isSecret
+    }))
   }
 }
 

src/renderer/hooks/use-snapshots.ts

@@ -4,6 +4,7 @@ import { persistenceApi, terminalApi } from '@/lib/api'
 import { useTerminalStore } from '@/stores/terminal-store'
 import { useProjectStore } from '@/stores/project-store'
 import { getTerminal } from '@/utils/terminal-registry'
+import { resolveEnvForSpawn } from '@/lib/env-parser'
 import type { PersistedTerminal, PersistedSnapshot } from '../../shared/types/persistence.types'
 import { DEFAULT_SCROLLBACK_LIMIT } from '../../shared/types/persistence.types'
 import type { Snapshot } from '@/types/project'
@@ -109,6 +110,12 @@ export function useRestoreSnapshot(): (snapshotId: string) => Promise<void> {
  */
 async function restoreFromSnapshot(projectId: string, snapshot: PersistedSnapshot): Promise<void> {
   const terminalStore = useTerminalStore.getState()
+  const projectStore = useProjectStore.getState()
+  const project = projectStore.projects.find((p) => p.id === projectId)
+
+  // Resolve project env vars for spawn
+  // TODO: Pass actual system env from backend for variable expansion
+  const { env, hasProjectEnv } = resolveEnvForSpawn(project?.envVars, {})
 
   // Close all existing terminals for this project
   // CRITICAL: Kill PTYs before removing from store to prevent orphaned processes
@@ -131,7 +138,8 @@ async function restoreFromSnapshot(projectId: string, snapshot: PersistedSnapsho
   for (const persistedTerminal of snapshot.terminals) {
     const spawnResult = await terminalApi.spawn({
       shell: persistedTerminal.shell as 'powershell' | 'cmd' | 'bash' | 'zsh' | 'fish' | undefined,
-      cwd: persistedTerminal.cwd
+      cwd: persistedTerminal.cwd,
+      ...(hasProjectEnv ? { env } : {})
     })
 
     if (!spawnResult.success) {

src/renderer/hooks/use-terminal-restore.ts

@@ -5,6 +5,7 @@ import { useAppSettingsStore } from '../stores/app-settings-store'
 import { useWorkspaceStore, terminalTabId, findPaneContainingTab } from '../stores/workspace-store'
 import { terminalApi } from '@/lib/api'
 import { shellApi } from '@/lib/shell-api'
+import { resolveEnvForSpawn } from '@/lib/env-parser'
 import {
   loadPersistedTerminals,
   saveTerminalLayout,
@@ -493,6 +494,12 @@ async function restoreFromLayout(
     }
 
     const terminalStore = useTerminalStore.getState()
+    const projectStore = useProjectStore.getState()
+    const project = projectStore.projects.find((p) => p.id === projectId)
+
+    // Resolve project env vars for spawn
+    // TODO: Pass actual system env from backend for variable expansion
+    const { env, hasProjectEnv } = resolveEnvForSpawn(project?.envVars, {})
 
     debugLog('restoreFromLayout', `START [${restoreId}] ACQUIRING LOCK`, {
       projectId,
@@ -517,7 +524,7 @@ async function restoreFromLayout(
     // Map old IDs to new IDs for active terminal selection and pane remapping
     const idMap = new Map<string, string>()
 
-    for (const persistedTerminal of layout.terminals) {
+for (const persistedTerminal of layout.terminals) {
       if (isCancelled()) {
         await cleanupSpawnedPtys(newTerminals, restoreId, 'during restore loop')
         debugLog('restoreFromLayout', `CANCELLED [${restoreId}] during restore loop`)
@@ -548,7 +555,8 @@ async function restoreFromLayout(
         const normalizedShell = normalizeShellForStartup(resolvedShell)
         const spawnResult = await terminalApi.spawn({
           shell: normalizedShell,
-          cwd: persistedTerminal.cwd
+          cwd: persistedTerminal.cwd,
+          ...(hasProjectEnv ? { env } : {})
         })
 
         debugLog('restoreFromLayout', `Spawn result [${terminalCallId}]`, {
@@ -706,14 +714,19 @@ async function createDefaultTerminal(
 
     const shell = normalizeShellForStartup(resolvedShell)
 
+    // Resolve project env vars for spawn
+    // TODO: Pass actual system env from backend for variable expansion
+    const { env, hasProjectEnv } = resolveEnvForSpawn(project?.envVars, {})
+
     debugLog('createDefaultTerminal', `Spawning default terminal [${defaultId}]`, {
       shell,
       cwd: project?.path
     })
 
     const spawnResult = await terminalApi.spawn({
       shell,
-      cwd: project?.path
+      cwd: project?.path,
+      ...(hasProjectEnv ? { env } : {})
     })
 
     debugLog('createDefaultTerminal', `Spawn result [${defaultId}]`, {

src/renderer/layouts/WorkspaceLayout.tsx

@@ -67,6 +67,7 @@ import { useEditorPersistence } from '@/hooks/use-editor-persistence'
 import { DEFAULT_APP_SETTINGS } from '@/types/settings'
 import { toast } from 'sonner'
 import { TitleBar } from '@/components/TitleBar'
+import { resolveEnvForSpawn } from '@/lib/env-parser'
 
 export default function WorkspaceLayout(): React.JSX.Element {
   const location = useLocation()
@@ -353,7 +354,15 @@ export default function WorkspaceLayout(): React.JSX.Element {
       const shell = shellName || activeProject?.defaultShell || appDefaultShell || undefined
       const cwd = activeProject?.path
 
-      const spawnResult = await terminalApi.spawn({ shell, cwd })
+      // Resolve project env vars for spawn
+      // TODO: Pass actual system env from backend for variable expansion
+      const { env, hasProjectEnv } = resolveEnvForSpawn(activeProject?.envVars, {})
+
+      const spawnResult = await terminalApi.spawn({
+        shell,
+        cwd,
+        ...(hasProjectEnv ? { env } : {})
+      })
       if (!spawnResult.success) {
         toast.error(spawnResult.error || 'Failed to create terminal')
         return
@@ -368,7 +377,7 @@ export default function WorkspaceLayout(): React.JSX.Element {
         terminalId: terminal.id
       })
     },
-    [activeProject?.defaultShell, activeProject?.path, activeProjectId, addTerminal, appDefaultShell, maxTerminals, terminals.length]
+    [activeProject?.defaultShell, activeProject?.path, activeProject?.envVars, activeProjectId, addTerminal, appDefaultShell, maxTerminals, terminals.length]
   )
 
   const handleNewTerminal = useCallback(() => {

src/renderer/lib/dialog-api.ts

@@ -31,6 +31,25 @@ function createTauriDialogApi(): DialogApi {
       } catch (err) {
         return { success: false, error: String(err), code: 'DIALOG_ERROR' }
       }
+    },
+
+    async selectFile(options?: {
+      filters?: Array<{ name: string; extensions: string[] }>
+      title?: string
+    }): Promise<IpcResult<string>> {
+      try {
+        const selected = await open({
+          multiple: false,
+          filters: options?.filters,
+          title: options?.title || 'Select File'
+        })
+        if (!selected) {
+          return { success: false, error: 'No file selected', code: 'CANCELLED' }
+        }
+        return { success: true, data: selected as string }
+      } catch (err) {
+        return { success: false, error: String(err), code: 'DIALOG_ERROR' }
+      }
     }
   }
 }