fix: MQ quality audit — 12 critical/high fixes, dead code removal, docs corrections (#176)

Comprehensive MAX QUALITY audit (15-step, 4-wave pipeline) identifying and
fixing security vulnerabilities, race conditions, goroutine leaks, and code
health issues.

Critical fixes (4):
- WebSocket readMessage returns sentinel error instead of nil on normal closure
- Stop() reordered — close HTTP server before nilling shared fields
- Pipeline: atomic stopped flag prevents send-on-closed-channel panic
- build.sh ldflags updated for Version package path

High fixes (8):
- Path traversal prefix check hardened with filepath.Separator
- Goroutine leak: WaitGroup closes output channel when readers finish
- Secret redaction for env var display in info and MCP tools
- Context threading through service orchestration for Key Vault
- Buffered stopCleanup channel prevents goroutine hang
- errors.As replaces direct type assertion for wrapped errors
- ParsePortSpec returns errors instead of silently producing port 0
- Version moved to internal/version — skills no longer imports cmd

Dead code removed (~844 lines net):
- 4 unused packages, 36 unused constants, unused exports

Documentation corrections:
- README: Go version 1.26.0->1.26.1, MCP tool count 10->12
- CONTRIBUTING: Go prerequisite 1.25->1.26.1, project structure rewritten

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jongio

CONTRIBUTING.md

@@ -8,7 +8,7 @@ Thank you for your interest in contributing to azd-app! This document provides g
 
 Before contributing, ensure you have the following installed:
 
-- **Go**: 1.25 or later
+- **Go**: 1.26.1 or later
 - **Node.js**: 20.0.0 or later
 - **npm**: 10.0.0 or later  
 - **PowerShell**: 7.4 or later (recommended: 7.5.4 for full compatibility)
@@ -17,7 +17,7 @@ Before contributing, ensure you have the following installed:
 
 You can verify your versions:
 ```bash
-go version                  # Should be 1.25+
+go version                  # Should be 1.26.1+
 node --version             # Should be v20.0.0+
 npm --version              # Should be 10.0.0+
 pwsh --version            # Should be 7.4+ or 7.5.4
@@ -188,18 +188,30 @@ Then create a Pull Request on GitHub.
 ## Project Structure
 
 ```
-src/
-├── cmd/              # Command implementations
-├── internal/
-│   ├── detector/     # Project detection logic
-│   ├── installer/    # Dependency installation
-│   └── runner/       # Project execution
-└── types/            # Shared types
-
-tests/
-└── projects/         # Test fixtures
-
-docs/                 # Documentation
+cli/
+├── src/
+│   ├── cmd/app/commands/   # CLI command implementations
+│   └── internal/
+│       ├── azure/          # Azure integration (credentials, logs)
+│       ├── config/         # Configuration loading
+│       ├── dashboard/      # Web dashboard server
+│       ├── detector/       # Project detection logic
+│       ├── docker/         # Docker/container support
+│       ├── executor/       # Process execution
+│       ├── healthcheck/    # Service health monitoring
+│       ├── installer/      # Dependency installation
+│       ├── logging/        # Structured logging
+│       ├── monitor/        # Service state monitoring
+│       ├── notifications/  # Desktop notifications
+│       ├── orchestrator/   # Service lifecycle orchestration
+│       ├── portmanager/    # Port allocation
+│       ├── runner/         # Project execution
+│       ├── service/        # Service management core
+│       └── workspace/      # Workspace utilities
+├── dashboard/              # React dashboard (Vite)
+├── tests/projects/         # Test fixture projects
+└── magefile.go             # Build tasks (mage)
+web/                        # Astro documentation site
 ```
 
 ## Adding a New Command

README.md

@@ -15,7 +15,7 @@ One command starts all services, manages dependencies, and provides real-time mo
 [![Go Reference](https://pkg.go.dev/badge/github.com/jongio/azd-app/cli.svg)](https://pkg.go.dev/github.com/jongio/azd-app/cli)
 [![govulncheck](https://img.shields.io/badge/govulncheck-passing-brightgreen)](https://github.com/jongio/azd-app/actions/workflows/govulncheck.yml)
 [![golangci-lint](https://img.shields.io/badge/golangci--lint-enabled-blue)](https://github.com/jongio/azd-app/actions/workflows/ci.yml)
-[![Go Version](https://img.shields.io/badge/go-1.26.0-blue)](https://go.dev/)
+[![Go Version](https://img.shields.io/badge/go-1.26.1-blue)](https://go.dev/)
 [![Platform Support](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)](https://github.com/jongio/azd-app)
 
 <br />
@@ -153,9 +153,9 @@ azd app run
 
 azd app includes a Model Context Protocol (MCP) server that connects your running application to AI assistants like GitHub Copilot.
 
-**10 AI Tools Available:**
-- **Observability**: `get_services`, `get_service_logs`, `get_project_info`
-- **Operations**: `run_services`, `stop_services`, `restart_service`, `install_dependencies`
+**12 AI Tools Available:**
+- **Observability**: `get_services`, `get_service_logs`, `get_service_errors`, `get_project_info`
+- **Operations**: `run_services`, `stop_services`, `start_service`, `restart_service`, `install_dependencies`
 - **Configuration**: `check_requirements`, `get_environment_variables`, `set_environment_variable`
 
 Ask Copilot things like:
@@ -186,7 +186,7 @@ Ask Copilot things like:
 
 <div align="center">
 
-| 10+ MCP Tools | <5 min Setup | 100% Open Source | Works with Copilot |
+| 12 MCP Tools | <5 min Setup | 100% Open Source | Works with Copilot |
 |:-------------:|:------------:|:----------------:|:------------------:|
 | Full AI integration | Quick start | MIT License | GitHub Copilot ready |
 

cli/build.ps1

@@ -190,6 +190,7 @@ else {
 }
 
 $APP_PATH = "github.com/jongio/azd-app/cli/src/cmd/app/commands"
+$VERSION_PATH = "github.com/jongio/azd-app/cli/src/internal/version"
 
 # Loop through platforms and build
 foreach ($PLATFORM in $PLATFORMS) {
@@ -223,7 +224,7 @@ foreach ($PLATFORM in $PLATFORMS) {
     $env:GOOS = $OS
     $env:GOARCH = $ARCH
 
-    $ldflags = "-s -w -X '$APP_PATH.Version=$env:EXTENSION_VERSION' -X '$APP_PATH.BuildTime=$BUILD_DATE' -X '$APP_PATH.Commit=$COMMIT'"
+    $ldflags = "-s -w -X '$VERSION_PATH.Version=$env:EXTENSION_VERSION' -X '$APP_PATH.BuildTime=$BUILD_DATE' -X '$APP_PATH.Commit=$COMMIT'"
 
     go build `
         "-ldflags=$ldflags" `

cli/build.sh

@@ -169,6 +169,7 @@ else
 fi
 
 APP_PATH="github.com/jongio/azd-app/cli/src/cmd/app/commands"
+VERSION_PATH="github.com/jongio/azd-app/cli/src/internal/version"
 
 # Loop through platforms and build
 for PLATFORM in "${PLATFORMS[@]}"; do
@@ -186,7 +187,7 @@ for PLATFORM in "${PLATFORMS[@]}"; do
     # Delete the output file if it already exists
     [ -f "$OUTPUT_NAME" ] && rm -f "$OUTPUT_NAME"
 
-    LDFLAGS="-s -w -X '$APP_PATH.Version=$EXTENSION_VERSION' -X '$APP_PATH.BuildTime=$BUILD_DATE' -X '$APP_PATH.Commit=$COMMIT'"
+    LDFLAGS="-s -w -X '$VERSION_PATH.Version=$EXTENSION_VERSION' -X '$APP_PATH.BuildTime=$BUILD_DATE' -X '$APP_PATH.Commit=$COMMIT'"
 
     # Set environment variables for Go build
     GOOS=$OS GOARCH=$ARCH go build \

cli/src/cmd/app/commands/core_helpers.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 
 	"github.com/jongio/azd-app/cli/src/internal/cache"
 	"github.com/jongio/azd-app/cli/src/internal/detector"
@@ -544,3 +545,20 @@ func handleNoProjectsCase(searchRoot string, serviceFilter []string) error {
 	}
 	return nil
 }
+
+// redactSecretValue masks the value of environment variables whose names
+// suggest they contain secrets (passwords, tokens, keys, connection strings).
+// Values with 4 or fewer characters are fully masked.
+func redactSecretValue(key, value string) string {
+	upper := strings.ToUpper(key)
+	sensitivePatterns := []string{"PASSWORD", "SECRET", "TOKEN", "KEY", "CONNECTION_STRING", "CONNECTIONSTRING"}
+	for _, pattern := range sensitivePatterns {
+		if strings.Contains(upper, pattern) {
+			if len(value) <= 4 {
+				return "***"
+			}
+			return value[:2] + "***" + value[len(value)-2:]
+		}
+	}
+	return value
+}

cli/src/cmd/app/commands/info.go

@@ -105,7 +105,7 @@ func printInfoJSON(projectDir string, services []*serviceinfo.ServiceInfo, azure
 				// Include environment variables related to this service
 				if strings.HasPrefix(envKeyUpper, serviceName+"_") ||
 					strings.HasPrefix(envKeyUpper, "SERVICE_"+serviceName+"_") {
-					svc.EnvironmentVars[envKey] = envValue
+					svc.EnvironmentVars[envKey] = redactSecretValue(envKey, envValue)
 				}
 			}
 		}
@@ -229,7 +229,7 @@ func printInfoDefault(projectDir string, services []*serviceinfo.ServiceInfo, az
 			cliout.Newline()
 			cliout.Info("  Environment Variables:")
 			for key, value := range envVars {
-				cliout.Item("  %s = %s", key, value)
+				cliout.Item("  %s = %s", key, redactSecretValue(key, value))
 			}
 		}
 	}

cli/src/cmd/app/commands/mcp.go

@@ -13,6 +13,7 @@ import (
 	"time"
 
 	"github.com/azure/azure-dev/cli/azd/pkg/azdext"
+	internalversion "github.com/jongio/azd-app/cli/src/internal/version"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 	"github.com/spf13/cobra"
@@ -118,7 +119,7 @@ This server complements azd's core MCP capabilities:
 
 	// Build MCP server using the azdext SDK builder
 	// Server name follows azd extension naming convention: {namespace}-mcp-server
-	builder := azdext.NewMCPServerBuilder("app-mcp-server", Version).
+	builder := azdext.NewMCPServerBuilder("app-mcp-server", internalversion.Version).
 		WithRateLimit(burstSize, float64(maxToolCallsPerMinute)/60.0).
 		WithInstructions(instructions).
 		WithResourceCapabilities(false, true). // subscribe=false, listChanged=true

cli/src/cmd/app/commands/mcp_resources.go

@@ -52,7 +52,7 @@ func newAzureYamlResource() server.ServerResource {
 			}
 
 			// Ensure resolved path is still within the validated directory
-			if !strings.HasPrefix(resolvedPath, validatedDir) {
+			if !strings.HasPrefix(resolvedPath, validatedDir+string(filepath.Separator)) && resolvedPath != validatedDir {
 				return nil, fmt.Errorf("azure.yaml path escapes project directory")
 			}
 

cli/src/cmd/app/commands/run.go

@@ -137,7 +137,7 @@ func runServicesFromAzureYaml(ctx context.Context, azureYamlPath string, runtime
 }
 
 // runAzdMode runs services in azd mode with individual service orchestration.
-func runAzdMode(_ context.Context, azureYamlPath, azureYamlDir string) error {
+func runAzdMode(ctx context.Context, azureYamlPath, azureYamlDir string) error {
 	cwd, err := os.Getwd()
 	if err != nil {
 		return fmt.Errorf("failed to get current directory: %w", err)
@@ -179,7 +179,7 @@ func runAzdMode(_ context.Context, azureYamlPath, azureYamlDir string) error {
 	}
 
 	// Execute and monitor services
-	return executeAndMonitorServices(runtimes, cwd, azureYaml, azureYamlDir)
+	return executeAndMonitorServices(ctx, runtimes, cwd, azureYaml, azureYamlDir)
 }
 
 // showNoServicesMessage displays a message when no services are defined.
@@ -238,7 +238,7 @@ func detectServiceRuntimes(services map[string]service.Service, azureYamlDir, ru
 }
 
 // executeAndMonitorServices starts services and monitors them until interrupted.
-func executeAndMonitorServices(runtimes []*service.ServiceRuntime, cwd string, azureYaml *service.AzureYaml, azureYamlDir string) error {
+func executeAndMonitorServices(ctx context.Context, runtimes []*service.ServiceRuntime, cwd string, azureYaml *service.AzureYaml, azureYamlDir string) error {
 	// Create logger
 	logger := service.NewServiceLogger(runVerbose)
 	logger.LogStartup(len(runtimes))
@@ -250,7 +250,7 @@ func executeAndMonitorServices(runtimes []*service.ServiceRuntime, cwd string, a
 	}
 
 	// Orchestrate services with dependency ordering
-	result, err := service.OrchestrateServices(runtimes, azureYaml.Services, envVars, logger, runRestartContainers)
+	result, err := service.OrchestrateServices(ctx, runtimes, azureYaml.Services, envVars, logger, runRestartContainers)
 	if err != nil {
 		return fmt.Errorf("service orchestration failed: %w", err)
 	}

cli/src/cmd/app/commands/version.go

@@ -1,13 +1,11 @@
 package commands
 
 import (
+	internalversion "github.com/jongio/azd-app/cli/src/internal/version"
 	coreversion "github.com/jongio/azd-core/version"
 	"github.com/spf13/cobra"
 )
 
-// Version is set at build time via -ldflags.
-var Version = "dev"
-
 // BuildTime is set at build time via -ldflags.
 var BuildTime = "unknown"
 
@@ -18,7 +16,7 @@ var Commit = "unknown"
 var VersionInfo = coreversion.New("jongio.azd.app", "azd app")
 
 func init() {
-	VersionInfo.Version = Version
+	VersionInfo.Version = internalversion.Version
 	VersionInfo.BuildDate = BuildTime
 	VersionInfo.GitCommit = Commit
 }