lua-cli 3.1.0 → 3.2.0-alpha.1

package/dist/commands/marketplace.js

@@ -897,8 +897,9 @@ async function handleInstallerActions(marketplaceApi, config, apiKey) {
         }
     }
 }
+const MARKETPLACE_PAGE_SIZE = 10;
 /**
- * Browse and select a skill from marketplace (with optional search)
+ * Browse and select a skill from marketplace (with optional search and pagination)
  * Returns the selected skill or null if cancelled
  */
 async function browseAndSelectSkill(marketplaceApi, purpose, publishedVersionsOnly) {
@@ -914,49 +915,93 @@ async function browseAndSelectSkill(marketplaceApi, purpose, publishedVersionsOn
         if (searchAnswer === null)
             return null; // User cancelled
         const searchQuery = searchAnswer?.query?.trim() || "";
-        // 2. Search/browse marketplace skills
-        writeProgress(searchQuery
-            ? `\n🔍 Searching for "${searchQuery}"...`
-            : "\n🔍 Loading marketplace skills...");
-        const filters = {};
-        if (searchQuery)
-            filters.search = searchQuery;
-        if (publishedVersionsOnly !== undefined)
-            filters.publishedVersionsOnly = publishedVersionsOnly;
-        const searchResults = await marketplaceApi.searchSkills(Object.keys(filters).length > 0 ? filters : undefined);
-        const skills = searchResults || [];
-        if (skills.length === 0) {
-            if (searchQuery) {
-                writeInfo(`\n📦 No skills found matching "${searchQuery}".`);
+        let currentPage = 1;
+        // Pagination loop
+        while (true) {
+            // 2. Search/browse marketplace skills with pagination
+            writeProgress(searchQuery
+                ? `\n🔍 Searching for "${searchQuery}"...`
+                : "\n🔍 Loading marketplace skills...");
+            const filters = {
+                limit: MARKETPLACE_PAGE_SIZE,
+                page: currentPage
+            };
+            if (searchQuery)
+                filters.search = searchQuery;
+            if (publishedVersionsOnly !== undefined)
+                filters.publishedVersionsOnly = publishedVersionsOnly;
+            const searchResults = await marketplaceApi.searchSkills(filters);
+            const skills = searchResults?.data || [];
+            const pagination = searchResults?.pagination;
+            const totalCount = pagination?.totalCount || skills.length;
+            const totalPages = pagination?.totalPages || 1;
+            const hasNextPage = pagination?.hasNextPage || false;
+            const hasPrevPage = pagination?.hasPrevPage || false;
+            if (skills.length === 0 && currentPage === 1) {
+                if (searchQuery) {
+                    writeInfo(`\n📦 No skills found matching "${searchQuery}".`);
+                }
+                else {
+                    writeInfo("\n📦 No skills available on the marketplace yet.");
+                }
+                writeInfo("💡 Be the first to publish a skill!\n");
+                return null;
             }
-            else {
-                writeInfo("\n📦 No skills available on the marketplace yet.");
+            // 3. Display results with pagination info
+            const pageInfo = totalPages > 1 ? ` (Page ${currentPage}/${totalPages})` : "";
+            console.log(`\n📊 Found ${totalCount} skill${totalCount === 1 ? "" : "s"}${pageInfo}:\n`);
+            // 4. Build choices with pagination navigation
+            const choices = [
+                ...skills.map((s) => ({
+                    name: `${s.displayName} - ${s.description || "No description"}`,
+                    value: { type: "skill", skill: s },
+                })),
+            ];
+            // Add pagination options
+            if (hasNextPage || hasPrevPage) {
+                choices.push(new inquirer.Separator());
+                if (hasPrevPage) {
+                    choices.push({
+                        name: `← Previous page (${currentPage - 1}/${totalPages})`,
+                        value: { type: "prev" }
+                    });
+                }
+                if (hasNextPage) {
+                    choices.push({
+                        name: `→ Next page (${currentPage + 1}/${totalPages})`,
+                        value: { type: "next" }
+                    });
+                }
+            }
+            choices.push(new inquirer.Separator());
+            choices.push({ name: "← Back to menu", value: { type: "back" } });
+            // 5. Prompt user to select
+            const message = purpose || "Select a skill:";
+            const answer = await safePrompt([
+                {
+                    type: "list",
+                    name: "selection",
+                    message,
+                    choices,
+                    pageSize: MARKETPLACE_PAGE_SIZE + 5, // Show all items + navigation options
+                },
+            ]);
+            if (!answer || !answer.selection)
+                return null;
+            const { selection } = answer;
+            if (selection.type === "skill" && selection.skill) {
+                return selection.skill;
+            }
+            else if (selection.type === "next") {
+                currentPage++;
+            }
+            else if (selection.type === "prev") {
+                currentPage--;
+            }
+            else if (selection.type === "back") {
+                return null;
             }
-            writeInfo("💡 Be the first to publish a skill!\n");
-            return null;
         }
-        // 3. Display results
-        console.log(`\n📊 Found ${skills.length} skill${skills.length === 1 ? "" : "s"}:\n`);
-        // 4. Prompt user to select a skill
-        const message = purpose || "Select a skill (or press ESC to go back):";
-        const skillAnswer = await safePrompt([
-            {
-                type: "list",
-                name: "skill",
-                message,
-                choices: [
-                    ...skills.map((s) => ({
-                        name: `${s.displayName} - ${s.description || "No description"}`,
-                        value: s,
-                    })),
-                    new inquirer.Separator(),
-                    { name: "← Back to menu", value: null },
-                ],
-            },
-        ]);
-        if (!skillAnswer || !skillAnswer.skill)
-            return null;
-        return skillAnswer.skill;
     }
     catch (error) {
         console.error(`\n❌ Error browsing marketplace: ${error.message}\n`);
@@ -1123,7 +1168,7 @@ async function installMarketplaceSkill(marketplaceApi, config, apiKey) {
                 creatorId: directAnswer.creatorId,
                 publishedVersionsOnly: true,
             });
-            const skills = searchResults || [];
+            const skills = searchResults?.data || [];
             if (skills.length === 0) {
                 console.error(`\n❌ Skill "${directAnswer.name}" by creator "${directAnswer.creatorId}" not found on the marketplace.\n`);
                 return;

package/dist/commands/persona.js

@@ -2,9 +2,6 @@
  * Persona Command
  * Manages agent persona for sandbox and production environments
  */
-import fs from 'fs';
-import path from 'path';
-import yaml from 'js-yaml';
 import inquirer from 'inquirer';
 import { loadApiKey, checkApiKey } from '../services/auth.js';
 import { readSkillConfig } from '../utils/files.js';
@@ -12,6 +9,7 @@ import { withErrorHandling, writeProgress, writeSuccess, writeInfo } from '../ut
 import { BASE_URLS } from '../config/constants.js';
 import { safePrompt } from '../utils/prompt-handler.js';
 import { validateConfig, validateAgentConfig, } from '../utils/dev-helpers.js';
+import { loadPersonaFromCode, savePersonaToCode } from '../utils/agent-code-utils.js';
 /**
  * Main persona command - manages agent persona
  *
@@ -96,8 +94,8 @@ export async function personaCommand(env) {
 async function manageSandboxPersona(context) {
     let continueManaging = true;
     while (continueManaging) {
-        // Load current persona
-        const currentPersona = loadSandboxPersona();
+        // Load current persona directly from code
+        const currentPersona = loadPersonaFromCode();
         // Show menu
         console.log("\n" + "=".repeat(60));
         console.log("🌙 Sandbox Persona Management");
@@ -188,46 +186,6 @@ async function manageProductionPersona(context) {
         }
     }
 }
-/**
- * Load sandbox persona from lua.skill.yaml
- */
-function loadSandboxPersona() {
-    try {
-        const config = readSkillConfig();
-        return config.agent?.persona || '';
-    }
-    catch (error) {
-        return '';
-    }
-}
-/**
- * Save sandbox persona to lua.skill.yaml
- */
-function saveSandboxPersona(persona) {
-    try {
-        const configPath = path.join(process.cwd(), 'lua.skill.yaml');
-        // Read current config
-        const fileContent = fs.readFileSync(configPath, 'utf8');
-        const config = yaml.load(fileContent);
-        // Ensure agent object exists
-        if (!config.agent) {
-            config.agent = {};
-        }
-        // Update persona
-        config.agent.persona = persona;
-        // Write back to file
-        const newContent = yaml.dump(config, {
-            lineWidth: -1,
-            noRefs: true
-        });
-        fs.writeFileSync(configPath, newContent, 'utf8');
-        return true;
-    }
-    catch (error) {
-        console.error('❌ Error saving persona to lua.skill.yaml:', error);
-        return false;
-    }
-}
 /**
  * View full persona content
  */
@@ -287,13 +245,13 @@ async function editSandboxPersona(context, currentPersona) {
         return;
     const { newPersona } = personaAnswer;
     const trimmedPersona = newPersona.trim();
-    writeProgress("🔄 Saving persona to lua.skill.yaml...");
-    const success = saveSandboxPersona(trimmedPersona);
+    writeProgress("🔄 Saving persona to code (LuaAgent)...");
+    const success = savePersonaToCode(trimmedPersona);
     if (success) {
-        writeSuccess("✅ Persona saved to lua.skill.yaml successfully");
+        writeSuccess("✅ Persona saved to code successfully");
     }
     else {
-        console.error("❌ Failed to save persona to lua.skill.yaml");
+        console.error("❌ Failed to save persona to code");
     }
 }
 /**

package/dist/commands/push.js

@@ -17,6 +17,7 @@ import { BASE_URLS } from '../config/constants.js';
 import PreProcessorApi from '../api/preprocessor.api.service.js';
 import PostProcessorApi from '../api/postprocessor.api.service.js';
 import DeveloperApi from '../api/developer.api.service.js';
+import { loadPersonaFromCode } from '../utils/agent-code-utils.js';
 /**
  * Main push command - pushes a skill or persona version to the server.
  *
@@ -239,8 +240,8 @@ async function pushPersonaVersion() {
         console.error("❌ No agent configuration found. Please run 'lua init' first.");
         process.exit(1);
     }
-    // Step 2: Load current persona
-    const currentPersona = config.agent?.persona || '';
+    // Step 2: Load current persona from code
+    const currentPersona = loadPersonaFromCode();
     if (!currentPersona || !currentPersona.trim()) {
         console.error("❌ No persona found in configuration. Please edit your persona first using 'lua persona'.");
         process.exit(1);

package/dist/commands/sync.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Sync Command
+ * Detects drift between server state and local code, allowing users to sync
+ */
+/**
+ * Main sync command - detects and resolves drift between server and local code.
+ *
+ * Features:
+ * - Fetches current deployed state from server
+ * - Compares with local code
+ * - Shows diff for drifted components
+ * - Allows user to update local code from server
+ *
+ * @returns Promise that resolves when sync completes
+ */
+export declare function syncCommand(): Promise<void>;
+/**
+ * Run sync check during compile flow (non-interactive or with prompts).
+ * Returns true if compilation should continue, false if user cancelled.
+ *
+ * @param apiKey - API key for authentication
+ * @param agentId - Agent ID
+ * @param options - Sync options
+ * @returns Promise<boolean> - true to continue, false to cancel
+ */
+export declare function runSyncCheck(apiKey: string, agentId: string, options?: {
+    noSync?: boolean;
+    forceSync?: boolean;
+}): Promise<boolean>;

package/dist/commands/sync.js

@@ -0,0 +1,194 @@
+/**
+ * Sync Command
+ * Detects drift between server state and local code, allowing users to sync
+ */
+import { loadApiKey, checkApiKey } from '../services/auth.js';
+import { readSkillConfig } from '../utils/files.js';
+import { withErrorHandling, writeProgress, writeSuccess, writeInfo } from '../utils/cli.js';
+import { safePrompt } from '../utils/prompt-handler.js';
+import { validateConfig, validateAgentConfig, } from '../utils/dev-helpers.js';
+import { savePersonaToCode, saveNameToCode } from '../utils/agent-code-utils.js';
+import { checkPersonaDrift, checkNameDrift, showPersonaDiff, showNameDiff, } from '../utils/sync-helpers.js';
+/**
+ * Main sync command - detects and resolves drift between server and local code.
+ *
+ * Features:
+ * - Fetches current deployed state from server
+ * - Compares with local code
+ * - Shows diff for drifted components
+ * - Allows user to update local code from server
+ *
+ * @returns Promise that resolves when sync completes
+ */
+export async function syncCommand() {
+    return withErrorHandling(async () => {
+        writeProgress('🔄 Checking for drift between server and local code...');
+        // Step 1: Load configuration
+        const config = readSkillConfig();
+        validateConfig(config);
+        validateAgentConfig(config);
+        const agentId = config.agent.agentId;
+        // Step 2: Authenticate
+        const apiKey = await loadApiKey();
+        if (!apiKey) {
+            console.error("❌ No API key found. Please run 'lua auth configure' to set up your API key.");
+            process.exit(1);
+        }
+        await checkApiKey(apiKey);
+        // Step 3: Check for drift
+        const nameDrift = await checkNameDrift(apiKey, agentId);
+        const personaDrift = await checkPersonaDrift(apiKey, agentId);
+        if (!nameDrift && !personaDrift) {
+            writeSuccess('✅ No drift detected. Local code is in sync with server.');
+            return;
+        }
+        // Step 4: Handle name drift
+        if (nameDrift) {
+            await handleNameDrift(nameDrift);
+        }
+        // Step 5: Handle persona drift
+        if (personaDrift) {
+            await handlePersonaDrift(personaDrift);
+        }
+        writeSuccess('\n✅ Sync complete.');
+    }, 'sync');
+}
+/**
+ * Handle name drift interactively.
+ */
+async function handleNameDrift(drift) {
+    showNameDiff(drift.serverName, drift.localName);
+    const answer = await safePrompt([
+        {
+            type: 'list',
+            name: 'action',
+            message: 'What would you like to do with the name?',
+            choices: [
+                { name: '📥 Update local from server', value: 'update' },
+                { name: '⏭️  Skip (keep local)', value: 'skip' },
+            ],
+        },
+    ]);
+    if (!answer || answer.action === 'skip') {
+        writeInfo('Skipped name sync.');
+        return;
+    }
+    if (answer.action === 'update' && drift.serverName) {
+        writeProgress('📝 Updating name in code...');
+        const success = saveNameToCode(drift.serverName);
+        if (success) {
+            writeSuccess('✅ Name updated in src/index.ts');
+        }
+        else {
+            console.error('❌ Failed to update name in code.');
+        }
+    }
+}
+/**
+ * Handle persona drift interactively.
+ */
+async function handlePersonaDrift(drift) {
+    // Show diff
+    showPersonaDiff(drift.serverPersona, drift.localPersona);
+    // Prompt user for action
+    const answer = await safePrompt([
+        {
+            type: 'list',
+            name: 'action',
+            message: 'What would you like to do with persona?',
+            choices: [
+                { name: '📥 Update local from server', value: 'update' },
+                { name: '⏭️  Skip (keep local)', value: 'skip' },
+            ],
+        },
+    ]);
+    if (!answer || answer.action === 'skip') {
+        writeInfo('Skipped persona sync.');
+        return;
+    }
+    if (answer.action === 'update') {
+        if (drift.serverPersona) {
+            writeProgress('📝 Updating persona in code...');
+            const success = savePersonaToCode(drift.serverPersona);
+            if (success) {
+                writeSuccess('✅ Persona updated in src/index.ts');
+            }
+            else {
+                console.error('❌ Failed to update persona in code.');
+            }
+        }
+        else {
+            writeInfo('ℹ️  No server persona to sync from.');
+        }
+    }
+}
+/**
+ * Run sync check during compile flow (non-interactive or with prompts).
+ * Returns true if compilation should continue, false if user cancelled.
+ *
+ * @param apiKey - API key for authentication
+ * @param agentId - Agent ID
+ * @param options - Sync options
+ * @returns Promise<boolean> - true to continue, false to cancel
+ */
+export async function runSyncCheck(apiKey, agentId, options = {}) {
+    // Skip sync if --no-sync flag is set
+    if (options.noSync) {
+        return true;
+    }
+    // Check for drift
+    const nameDrift = await checkNameDrift(apiKey, agentId);
+    const personaDrift = await checkPersonaDrift(apiKey, agentId);
+    if (!nameDrift && !personaDrift) {
+        return true; // No drift, continue
+    }
+    // If --force-sync, auto-update without prompting
+    if (options.forceSync) {
+        if (nameDrift?.serverName) {
+            writeProgress('🔄 Auto-syncing name from server (--force-sync)...');
+            saveNameToCode(nameDrift.serverName);
+            writeSuccess('✅ Name synced from server');
+        }
+        if (personaDrift?.serverPersona) {
+            writeProgress('🔄 Auto-syncing persona from server (--force-sync)...');
+            savePersonaToCode(personaDrift.serverPersona);
+            writeSuccess('✅ Persona synced from server');
+        }
+        return true;
+    }
+    // Show diffs
+    console.log('\n⚠️  Drift detected!\n');
+    if (nameDrift) {
+        showNameDiff(nameDrift.serverName, nameDrift.localName);
+    }
+    if (personaDrift) {
+        showPersonaDiff(personaDrift.serverPersona, personaDrift.localPersona);
+    }
+    const answer = await safePrompt([
+        {
+            type: 'list',
+            name: 'action',
+            message: 'How would you like to proceed?',
+            choices: [
+                { name: '📥 Update local from server', value: 'update' },
+                { name: '⏭️  Continue with local (will overwrite server on push)', value: 'continue' },
+                { name: '❌ Cancel', value: 'cancel' },
+            ],
+        },
+    ]);
+    if (!answer || answer.action === 'cancel') {
+        console.log('\n❌ Compilation cancelled due to unresolved drift.');
+        return false;
+    }
+    if (answer.action === 'update') {
+        if (nameDrift?.serverName) {
+            saveNameToCode(nameDrift.serverName);
+            writeSuccess('✅ Name synced from server');
+        }
+        if (personaDrift?.serverPersona) {
+            savePersonaToCode(personaDrift.serverPersona);
+            writeSuccess('✅ Persona synced from server');
+        }
+    }
+    return true;
+}

package/dist/commands/test.js

@@ -10,7 +10,7 @@ import { loadApiKey } from "../services/auth.js";
 import { executeTool, executeWebhook, executeJob, executePreProcessor, executePostProcessor, loadEnvironmentVariables } from "../utils/sandbox.js";
 import { readSkillConfig } from "../utils/files.js";
 import { safePrompt } from "../utils/prompt-handler.js";
-import { decompressCode, readDeployJson, extractToolsFromDeployData, hasEnvFile, hasConfigEnvVars, } from "../utils/test-helpers.js";
+import { decompressCode, readDeployJson, extractToolsFromDeployData, hasEnvFile, } from "../utils/test-helpers.js";
 import { promptToolSelection, generatePromptsForObject } from "../utils/test-prompts.js";
 /**
  * Main test command - tests tools, webhooks, jobs, preprocessors, or postprocessors.
@@ -110,9 +110,6 @@ async function testSkill() {
     if (hasEnvFile()) {
         writeProgress(`📄 Loaded environment variables from .env file`);
     }
-    if (hasConfigEnvVars(config)) {
-        writeProgress(`📄 Loaded environment variables from lua.skill.yaml`);
-    }
     // Step 5: Let user select a tool
     const selectedTool = await promptToolSelection(allTools);
     clearPromptLines(2);
@@ -138,7 +135,8 @@ async function testSkill() {
             toolCode,
             inputs: inputValues,
             apiKey,
-            agentId
+            agentId,
+            channel: 'dev',
         });
         writeSuccess("✅ Tool execution successful!");
         console.log(`Output: ${JSON.stringify(result, null, 2)}`);

package/dist/interfaces/index.d.ts

@@ -10,3 +10,5 @@ export { ApiResponse, Pagination } from "./common.js";
 export { SkillTool, SkillVersion, Skill, GetSkillsResponse, DeleteSkillResponse, } from "./skills.js";
 export { ImmutableUserProfile, UserAgentData } from "./user.js";
 export { MCPServerResponse, MCPServerStdioResponse, MCPServerSSEResponse, CreateMCPServerRequest, UpdateMCPServerRequest, } from "./mcp.js";
+export { PersonaVersion, PersonaVersionsResponse, CreatePersonaVersionResponse, SetPersonaVersionResponse, } from "./persona.js";
+export { Channel, LuaRequest, LuaRuntime, } from "./lua.js";

package/dist/interfaces/lua.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Lua Runtime Interfaces
+ * Request-level runtime information available in the execution sandbox
+ */
+/**
+ * Channel type.
+ * Represents the communication channel through which a request originated.
+ * Known channels are typed as string literals, unrecognized channels are unknown.
+ */
+export type Channel = 'web' | 'whatsapp' | 'facebook' | 'instagram' | 'slack' | 'api' | 'dev' | 'email' | string;
+/**
+ * Lua request context.
+ * Contains information about the current request.
+ */
+export interface LuaRequest {
+    /** The channel through which the request originated */
+    channel: Channel;
+}
+/**
+ * Lua runtime API.
+ * Provides access to request-level runtime information.
+ */
+export interface LuaRuntime {
+    /** Request context information */
+    request: LuaRequest;
+}

package/dist/interfaces/lua.js

@@ -0,0 +1,5 @@
+/**
+ * Lua Runtime Interfaces
+ * Request-level runtime information available in the execution sandbox
+ */
+export {};

package/dist/interfaces/marketplace.d.ts

@@ -97,3 +97,23 @@ export interface UnlistSkillResponse {
     unlisted: boolean;
     versionsUnpublished: number;
 }
+/**
+ * Pagination metadata
+ */
+export interface MarketplacePaginationResponse {
+    currentPage: number;
+    totalPages: number;
+    totalCount: number;
+    limit: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+    nextPage: number | null;
+    prevPage: number | null;
+}
+/**
+ * Paginated marketplace skills response
+ */
+export interface PaginatedMarketplaceSkillsResponse {
+    data: MarketplaceSkillWithVersionsResponse[];
+    pagination: MarketplacePaginationResponse;
+}

package/dist/interfaces/persona.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Persona Interfaces
+ * Matches lua-api/src/dto/persona.dto.ts
+ */
+/**
+ * Persona version structure
+ * Matches PersonaVersionDto
+ */
+export interface PersonaVersion {
+    version: number;
+    persona: string;
+    createdDate: number;
+    createdBy?: string;
+    isCurrent: boolean;
+}
+/**
+ * Response for getVersions
+ * Matches PersonaVersionsResponseDto
+ */
+export interface PersonaVersionsResponse {
+    status: string;
+    message: string;
+    versions: PersonaVersion[];
+}
+/**
+ * Response for createVersion
+ * Matches CreatePersonaVersionResponseDto
+ */
+export interface CreatePersonaVersionResponse {
+    status: string;
+    message: string;
+    version: number;
+}
+/**
+ * Response for deployVersion (setPersonaVersion)
+ * Matches SetPersonaVersionResponseDto
+ */
+export interface SetPersonaVersionResponse {
+    status: string;
+    message: string;
+    version: number;
+}

package/dist/interfaces/persona.js

@@ -0,0 +1,5 @@
+/**
+ * Persona Interfaces
+ * Matches lua-api/src/dto/persona.dto.ts
+ */
+export {};

package/dist/interfaces/user.d.ts

@@ -17,3 +17,24 @@ export interface UserAgentData extends Record<string, any> {
      */
     userId?: string;
 }
+/**
+ * Profile response from user lookup endpoints
+ */
+export interface ProfileResponse {
+    id: string;
+    fullName: string;
+    mobileNumbers: Array<{
+        number: string;
+        validated: boolean;
+        validatedAt: number;
+    }>;
+    emailAddresses: Array<{
+        address: string;
+        validated: boolean;
+        validatedAt: number;
+    }>;
+    country?: {
+        code?: string;
+        name?: string;
+    };
+}

package/dist/types/index.d.ts

@@ -23,3 +23,4 @@ export { BasketStatus, BasketItem, Basket } from '../interfaces/baskets.js';
 export { OrderStatus, OrderResponse } from '../interfaces/orders.js';
 export { Product } from '../interfaces/product.js';
 export { ApiResponse, Pagination } from '../interfaces/common.js';
+export { Channel, LuaRequest, LuaRuntime } from '../interfaces/lua.js';

package/dist/types/skill.d.ts

@@ -9,9 +9,7 @@ import { JobInstance } from "../common/job.instance.js";
  * Safe environment variable access function.
  * Gets injected at runtime with skill-specific environment variables.
  *
- * Checks in order:
- * 1. Process environment variables (.env file)
- * 2. lua.skill.yaml configuration
+ * Checks process environment variables (.env file)
  *
  * @param key - The environment variable key to retrieve
  * @returns The environment variable value or undefined if not found