[Eng] Improve typespec devexp with Update-DevTSPModule

tools/AzDev/AzDev/AzDev.psd1

@@ -76,7 +76,7 @@ FunctionsToExport = 'Connect-DevCommonRepo', 'Disconnect-DevCommonRepo'
 CmdletsToExport = 'Get-DevContext', 'Set-DevContext',
     'Get-DevModule', 'Get-DevProject',
     'Update-DevAssembly',
-    'Open-DevSwagger'
+    'Open-DevSwagger', 'Update-DevTSPModule'
 
 # Variables to export from this module
 VariablesToExport = '*'

tools/AzDev/build.ps1

@@ -1,5 +1,6 @@
 $module = 'AzDev'
 $artifacts = "$PSScriptRoot/../../artifacts"
 
+rm -r "$artifacts/$module"
 dotnet publish $PSScriptRoot/src --sc -o "$artifacts/$module/bin"
-Copy-Item "$PSScriptRoot/$module/*" "$artifacts/$module" -Recurse -Force
+Copy-Item "$PSScriptRoot/$module/*" "$artifacts/$module" -Recurse -Force

tools/AzDev/src/Services/YamlHelper.cs

@@ -20,13 +20,23 @@ internal static class YamlHelper
     private static IDeserializer Deserializer => _lazyDeserializer.Value;
     private static Lazy<IDeserializer> _lazyDeserializer = new Lazy<IDeserializer>(BuildDeserializer);
 
+    private static ISerializer Serializer => _lazySerializer.Value;
+    private static Lazy<ISerializer> _lazySerializer = new Lazy<ISerializer>(BuildSerializer);
+
     private static IDeserializer BuildDeserializer()
     {
         return new DeserializerBuilder()
             .IgnoreUnmatchedProperties()
             .Build();
     }
 
+    private static ISerializer BuildSerializer()
+    {
+        return new SerializerBuilder()
+            .WithNamingConvention(YamlDotNet.Serialization.NamingConventions.CamelCaseNamingConvention.Instance)
+            .Build();
+    }
+
     public static T Deserialize<T>(string yaml)
     {
         return Deserializer.Deserialize<T>(yaml);
@@ -48,6 +58,6 @@ public static bool TryDeserialize<T>(string yaml, out T obj)
 
     public static string Serialize<T>(T obj)
     {
-        throw new NotImplementedException();
+        return Serializer.Serialize(obj);
     }
 }

tools/AzDev/src/Typespec/README.md

@@ -0,0 +1,91 @@
+# Update-DevTSPModule
+
+`Update-DevTSPModule` is a PowerShell cmdlet designed to help manage TypeSpec (TSP) configurations for Azure PowerShell development. It facilitates the setup and update of `tspconfig.yaml` by resolving locations from local paths, remote URLs, or specific repository details. Then finally generate Azure-PowerShell module from TypeSpec configured.
+
+## Terminology
+
+- **TSP (TypeSpec)**: The language used for defining APIs: https://github.com/Azure/azure-rest-api-specs/tree/main/specification
+- **TSP Location**: The source of truth for the TypeSpec configuration. It can be a remote URL (e.g., GitHub) or a local file path. There must be ***tspconfig.yaml*** and ***typespec files*** under this location.
+    - ***remote***
+    - ***local***
+    - ***tsp-location.yaml***: Will be calculated from `./tsp-location.yaml` if not provided and tsp-location.yaml exists. See [`tsp-location.yaml`](#tsp-location-yaml)
+- **AzPSConfig**: An optional, additional TypeSpec configuration file (typically `tspconfig.yaml` in the local directory) that is merged with the main TSP configuration. This allows for Azure PowerShell-specific overrides or extensions. Will look for `./tspconfig.yaml` if not provided.
+- <a id="tsp-location-yaml"></a>**tsp-location.yaml**: A local file generated by this cmdlet to persist the source location of the TypeSpec configuration. This allows subsequent runs to resolve the configuration without needing to re-specify the location parameters.
+    - ***directory***: Directory to tsp location, e.g. `specification\azuredependencymap\DependencyMap.Management`
+    - ***commit***: Commit id. Empty when last generation was from local tsp
+    - ***repo***: `{ForkName}/{RepositoryName}`, e.g. `Azure/azure-rest-api-specs`. Empty when last generation was from local tsp
+- **RepoRoot**: Root directory of local azure-powershell. Can be provided in below ways
+    - ***Execute this cmdlet anywhere under $RootDirectory without explicitly providing it***: Run this cmdlet under any subdirectory of azure-powershell, `RepoRoot` will be calculated.
+    - ***Pass by parameter***: `Update-DevTSPModule -RepoRoot $RootDirectory`
+    - ***AzDev Cmdlet***: `Set-DevContext -RepoRoot $RootDirectory`
+- **Emitter**: The tool responsible for generating PowerShell code from the TypeSpec definition. This cmdlet specifically works witapprovedh the `@azure-tools/typespec-powershell` emitter.
+- **emitter-output-dir**: Emitter option to indicate the output directory of code generation. Usually `"{output-dir}/{service-dir}/${ModuleName}/${ModuleName}.Autorest"` under `tsp-config.yaml`. When not provided while AzPSConfig exists, fallback to directory of AzPSConfig.
+
+## Legacy Document
+https://microsoft.sharepoint.com/:fl:/s/39639d2e-2b30-484b-8cd0-b1da04c38d95/IQDW4AwiMVYdR4lhRhPz1a_mARd9gEu1L1Z4lf93opQMtIc?e=QQe2VB&nav=cz0lMkZzaXRlcyUyRjM5NjM5ZDJlLTJiMzAtNDg0Yi04Y2QwLWIxZGEwNGMzOGQ5NSZkPWIlMjFHR2xLSHJvQU1rbWJZa2d6Z1FqZzBvYjA4Z2lVSWRoTnFKN3NIeE5MSDFGTklBYXdpRzZ0VEo2bmJMWVdfUlRyJmY9MDFKSUdTU0Y2VzRBR0NFTUtXRFZEWVNZS0dDUFo1TEw3RyZjPSUyRiZhPUxvb3BBcHAmcD0lNDBmbHVpZHglMkZsb29wLXBhZ2UtY29udGFpbmVyJng9JTdCJTIydyUyMiUzQSUyMlQwUlRVSHh0YVdOeWIzTnZablF1YzJoaGNtVndiMmx1ZEM1amIyMThZaUZIUjJ4TFNISnZRVTFyYldKWmEyZDZaMUZxWnpCdllqQTRaMmxWU1dSb1RuRktOM05JZUU1TVNERkdUa2xCWVhkcFJ6WjBWRW8yYm1KTVdWZGZVbFJ5ZkRBeFNrbEhVMU5HTkVJMVVWUklVbHBEUzFsQ1JrdExWRmsyUzBWSFNqTlpNMGMlM0QlMjIlMkMlMjJpJTIyJTNBJTIyMDkxZjE5NjktMTA4Yi00ZmRlLWE0NWQtMWFiOTJhZGUzYWZiJTIyJTdE
+
+## Prerequisite
+- **node version >= 20**
+- **typespec compiler installed?**
+- **git clone/pull**
+
+## Build
+```powershell
+& {workspace}/azure-powershell/tools/AzDev/build.ps1
+import-module {workspace}/azure-powershell/artifacts/AzDev/AzDev.psd1
+```
+
+## Usage
+
+### Local TSP only
+
+```powershell
+Update-DevTSPModule -TSPLocation "D:\workspace\azure-rest-api-specs\specification\azuredependencymap\DependencyMap.Management\tspconfig.yaml"
+```
+
+### Remote TSP only
+
+```powershell
+Update-DevTSPModule -TSPLocation "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/29e9e3ca1a1bccba66a6cf092dbc317c639989b1/specification/azuredependencymap/DependencyMap.Management/tspconfig.yaml"
+```
+
+### Use tsp-location.yaml without providing `-TSPLocation`
+```powershell
+cd "D:/workspace/azure-powershell/src/DependencyMap/DependencyMap.Autorest"
+Update-DevTSPModule
+```
+
+### Use tsp-location.yaml with updated commit and fork When last time generated from remote
+```powershell
+cd "D:/workspace/azure-powershell/src/DependencyMap/DependencyMap.Autorest"
+Update-DevTSPModule -RemoteForkName "VeryEarly" -RemoteCommit "e952eed8b787d99d10ba9a5ea3789ed0a9877214"
+```
+
+### Use local `-AzPSConfig` to override or extend `tspconfig.yaml` from `-TSPLocation`
+```powershell
+Update-DevTSPModule -TSPLocation "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/29e9e3ca1a1bccba66a6cf092dbc317c639989b1/specification/azuredependencymap/DependencyMap.Management/tspconfig.yaml" -AzPSConfig "D:/workspace/azure-powershell/src/DependencyMap/DependencyMap.Autorest/tspconfig.yaml"
+```
+
+### Use local `-AzPSConfig` to override or extend `tspconfig.yaml` from `tsp-location.yaml` both under current directory
+```powershell
+cd "D:/workspace/azure-powershell/src/DependencyMap/DependencyMap.Autorest"
+Update-DevTSPModule
+```
+
+### Execute `Update-DevTSPModule` from directories outside of azure-powershell
+```powershell
+cd "C:/"
+Update-DevTSPModule -TSPLocation "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/29e9e3ca1a1bccba66a6cf092dbc317c639989b1/specification/azuredependencymap/DependencyMap.Management/tspconfig.yaml" -RepoRoot "D:/workspace/azure-powershell"
+```
+Or
+
+```powershell
+cd "C:/"
+Set-DevContext -RepoRoot "D:/workspace/azure-powershell"
+Update-DevTSPModule -TSPLocation "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/29e9e3ca1a1bccba66a6cf092dbc317c639989b1/specification/azuredependencymap/DependencyMap.Management/tspconfig.yaml" 
+```
+
+## Notes
+
+- The cmdlet relies on `npm` and the `@azure-tools/typespec-powershell` emitter.
+- It handles the download and setup of necessary TypeSpec files in a temporary directory (unless `SkipCleanTemp` is used).