Schema Documentation and Error Messages

Part of #7435 — Multi-Language Hook Support

User Story

As a template author, I want clear documentation on how to configure language hooks in azure.yaml so I can adopt the feature without guessing.

Solution Approach

1. Schema updates (if JSON schema files exist in resources/):

   • Add language field to HookConfig schema (enum: python, js, ts, dotnet).
   • Add dir field to HookConfig schema (string, optional).
   • Update run field description to mention language script support.

2. Code documentation:

   • GoDoc comments on HookConfig struct (mention language field).
   • GoDoc on validate() method (document resolution order).
   • GoDoc on ScriptExecutor interface (document contract).

3. Error messages (verify all use ErrorWithSuggestion):

   • Runtime not found: "Python runtime not found. Install Python 3.7.6+ from https://..."
   • Dependency install failure: "Failed to install Python dependencies for hook '%s': %w"
   • Inline rejection: "Inline scripts are not supported for language hooks (language: %s). Use a file path instead."
   • Build failure (future, for TS/.NET): "Failed to build hook '%s': %w"

4. Example configurations to validate:

   # Auto-detect Python from .py extension
   hooks:
     preprovision:
       run: scripts/setup.py
   
   # Explicit language override
   hooks:
     preprovision:
       run: scripts/setup
       language: python
   
   # Platform-specific language hooks
   hooks:
     postdeploy:
       windows:
         run: scripts/notify.py
       posix:
         run: scripts/notify.py

Files: resources/ schema files (MODIFY), code comments across new files

Acceptance Criteria

• Schema documentation reflects new language and dir fields
• Code comments are accurate and complete on all new public types
• Error messages follow existing azd patterns (ErrorWithSuggestion)
• Example azure.yaml configs are valid and demonstrative

References

• Contributes to: Multi-Language Hook Support: Python, JavaScript, TypeScript, .NET #7435