Enhance port management and environment variable support in azure.yaml (#32)

Author: jongio

CONTRIBUTING.md

@@ -53,11 +53,22 @@ go build -o bin/app.exe ./src/cmd/app
 3. **Install locally for testing**:
    ```bash
    cd cli
-   # Install mage if not already installed
-   go install github.com/magefile/mage@latest
 
-   # Build and install
-   mage install
+   # First time setup: Uninstall any existing version and clean cache
+   azd extension uninstall jongio.azd.app
+   rm -r ~/.azd/extensions/jongio.azd.app  # On Windows: Remove-Item -Recurse -Force ~\.azd\extensions\jongio.azd.app
+   
+   # Build and install extension
+   azd x build --skip-install=false
+   
+   # Verify installation
+   azd app version
+   ```
+
+4. **Development workflow with watch mode**:
+   ```bash
+   # For active development, use watch mode to auto-rebuild on file changes
+   azd x watch
    ```
 
 ## Development Workflow
@@ -107,23 +118,16 @@ git checkout -b feature/your-feature-name
 
 ### 3. Test Your Changes
 ```bash
-# Run unit tests
-mage test
-
-# Run with coverage
-mage testcoverage
-
-# Run all tests including integration
-mage testall
+# Build and install for testing
+azd x build --skip-install=false
 
-# Run linter
-mage lint
+# Or use watch mode during active development
+azd x watch
 
-# Test locally
-mage install
+# Test the extension
 azd app <your-command>
 
-# Alternative: Use go directly
+# Run unit tests (legacy - use azd x build instead)
 go test ./...
 go test -cover ./...
 ```

cli/README.md

@@ -21,6 +21,7 @@ App automatically detects and manages dependencies for:
 - 📦 **Multi-Language Support**: Works with Node.js, Python, and .NET projects
 - 🚀 **One-Command Setup**: Install all dependencies with a single command
 - 🎯 **Environment-Aware**: Creates and manages virtual environments for Python
+- 🐳 **Docker Compose Compatible**: Environment variable syntax matches Docker Compose exactly
 - ⚡ **Fast Iteration**: Minimal test dependencies for quick validation
 
 ## Installation
@@ -257,6 +258,27 @@ azd app run --env-file .env.local
 - `--verbose, -v`: Enable verbose logging
 - `--dry-run`: Show what would be run without starting services
 
+**Environment Variables:**
+
+Services can define environment variables in `azure.yaml` using Docker Compose-compatible syntax:
+
+```yaml
+services:
+  api:
+    # Map format (recommended)
+    environment:
+      NODE_ENV: production
+      PORT: "3000"
+  
+  web:
+    # Array of strings (Docker Compose style)
+    environment:
+      - API_URL=http://localhost:5000
+      - DEBUG=true
+```
+
+See [Environment Variables Documentation](docs/environment-variables.md) for all supported formats and advanced usage.
+
 **Runtime Modes:**
 - **azd** (default): Runs services through azd's built-in dashboard, works with all project types
 - **aspire**: Uses native .NET Aspire dashboard via `dotnet run` (only for Aspire projects)

cli/docs/commands/run.md

@@ -713,7 +713,6 @@ STRIPE_API_KEY=sk_test_abc456
 # Application settings
 LOG_LEVEL=debug
 ENABLE_METRICS=true
-CORS_ORIGINS=http://localhost:3000
 ```
 
 ## Output Examples