Add maintained peer lab command script rendering

Author: ammarheidari

README.md

@@ -208,7 +208,7 @@ The roadmap is intentionally conservative:
 4. Harden TCAP with external interoperability vectors and MAP profile validation.
 
 Phase 27 completed the maintained external peer lab foundation, including package-neutral binding, host prerequisites, validated lab configuration, deterministic artifact planning, command planning, traffic vectors, manual self-hosted CI policy, digest-covered retained evidence gates, and status reporting.
-Phase 28 builds the automation and evidence handoff layer above that foundation, starting with a single run manifest, deterministic environment file rendering, and digest manifests for retained lab artifacts.
+Phase 28 builds the automation and evidence handoff layer above that foundation, starting with a single run manifest, deterministic environment file rendering, command script rendering, and digest manifests for retained lab artifacts.
 5. Harden MAP SMS with external interoperability vectors and operator-profile validation.
 6. Use completed interoperability tooling to run external lab validation, native SCTP verification, and release automation hardening.
 7. Complete commercial readiness gates and publish governed release candidates.

docs/PHASE28_MAINTAINED_PEER_LAB_AUTOMATION.md

@@ -37,6 +37,17 @@ This gives real lab scripts a stable input file while keeping package-specific v
 
 The manifest does not generate digests itself. Real lab automation must calculate the digests from retained files and pass them into this contract.
 
+## Unit 4 - Command Script Renderer
+
+`SigtranMaintainedPeerLabCommandScripts` now renders the ordered command plan as a shell script with:
+
+- `#!/usr/bin/env bash`
+- `set -euo pipefail`
+- A sourced environment file.
+- The ordered prepare, capture, peer, SDK, compare, and collect commands.
+
+The renderer gives operators a deterministic script body while still allowing local lab automation to map package-neutral runner commands to site-specific scripts.
+
 ## Validation
 
 Each unit in this phase is validated with:

docs/SDK_ROADMAP.md

@@ -251,7 +251,7 @@ Status: Phase 27 is foundation-complete. It has canonical `Sigtran.NET` naming,
 - Render environment files, command scripts, workflow templates, comparison reports, and evidence handoff bundles.
 - Keep automation package-neutral and separate planned contracts from retained commercial evidence.
 
-Status: Phase 28 has a run manifest that aggregates binding, configuration, artifact, command, traffic vector, and CI contracts, deterministic environment file rendering for lab scripts, and artifact digest manifests for evidence handoff.
+Status: Phase 28 has a run manifest that aggregates binding, configuration, artifact, command, traffic vector, and CI contracts, deterministic environment file rendering, command script rendering, and artifact digest manifests for evidence handoff.
 
 ## Recommended First Deliverable
 

src/Sigtran.NET.Tests/Program.cs

@@ -48,6 +48,7 @@
 Run("SIGTRAN maintained peer lab run manifest aggregates executable contracts", SigtranMaintainedPeerLabRunManifestAggregatesExecutableContracts);
 Run("SIGTRAN maintained peer lab environment file renders manifest values", SigtranMaintainedPeerLabEnvironmentFileRendersManifestValues);
 Run("SIGTRAN maintained peer lab artifact digest manifest gates handoff", SigtranMaintainedPeerLabArtifactDigestManifestGatesHandoff);
+Run("SIGTRAN maintained peer lab command script renders command plan", SigtranMaintainedPeerLabCommandScriptRendersCommandPlan);
 Run("SIGTRAN trace comparison reports ordered mismatches", SigtranTraceComparisonReportsOrderedMismatches);
 Run("SIGTRAN interoperability evidence promotion requires passing lab run", SigtranInteropEvidencePromotionRequiresPassingLabRun);
 Run("SIGTRAN interoperability lab CI profile is opt-in", SigtranInteropLabCiProfileIsOptIn);
@@ -965,6 +966,20 @@ static void SigtranMaintainedPeerLabArtifactDigestManifestGatesHandoff()
     Assert(!invalid.HasValidDigests, invalid.Describe());
 }
 
+static void SigtranMaintainedPeerLabCommandScriptRendersCommandPlan()
+{
+    SigtranMaintainedPeerLabRunManifest runManifest = SigtranMaintainedPeerLabRunManifests.CreateDefault("phase28-unit4");
+    SigtranMaintainedPeerLabCommandScript script = SigtranMaintainedPeerLabCommandScripts.CreateDefault(runManifest);
+    string rendered = script.Render();
+
+    Assert(rendered.StartsWith("#!/usr/bin/env bash", StringComparison.Ordinal), rendered);
+    Assert(rendered.Contains("set -euo pipefail", StringComparison.Ordinal), rendered);
+    Assert(rendered.Contains("source 'artifacts/external-peer/maintained/config/phase28-unit4-peer.env'", StringComparison.Ordinal), rendered);
+    Assert(rendered.Contains("tcpdump -i lo", StringComparison.Ordinal), rendered);
+    Assert(rendered.Contains("sigtran-trace-compare", StringComparison.Ordinal), rendered);
+    Assert(script.CoversCommandPlan, script.Describe());
+}
+
 static void SigtranTraceComparisonReportsOrderedMismatches()
 {
     SigtranInteropLabTemplate template = SigtranInteropPeerProfiles.CreateExternalPeerM3uaAspToSgTemplate();

src/Sigtran.NET/Core/Utilities/SigtranMaintainedPeerLabCommandScript.cs

@@ -0,0 +1,83 @@
+using System.Text;
+
+namespace Sigtran.NET.Core.Utilities;
+
+/// <summary>
+/// Describes a rendered maintained external peer lab command script.
+/// </summary>
+public sealed class SigtranMaintainedPeerLabCommandScript
+{
+    /// <summary>Creates a maintained external peer lab command script.</summary>
+    /// <param name="runManifest">The run manifest.</param>
+    /// <param name="environmentFilePath">The environment file path sourced by the script.</param>
+    public SigtranMaintainedPeerLabCommandScript(
+        SigtranMaintainedPeerLabRunManifest runManifest,
+        string environmentFilePath)
+    {
+        ArgumentNullException.ThrowIfNull(runManifest);
+        RunManifest = runManifest;
+        EnvironmentFilePath = string.IsNullOrWhiteSpace(environmentFilePath)
+            ? throw new ArgumentException("Environment file path is required.", nameof(environmentFilePath))
+            : environmentFilePath;
+    }
+
+    /// <summary>The run manifest.</summary>
+    public SigtranMaintainedPeerLabRunManifest RunManifest { get; }
+
+    /// <summary>The environment file path sourced by the script.</summary>
+    public string EnvironmentFilePath { get; }
+
+    /// <summary>Renders the command script content.</summary>
+    /// <returns>The command script content.</returns>
+    public string Render()
+    {
+        StringBuilder builder = new();
+        builder.AppendLine("#!/usr/bin/env bash");
+        builder.AppendLine("set -euo pipefail");
+        builder.AppendLine();
+        builder.Append("source ");
+        builder.AppendLine(Quote(EnvironmentFilePath));
+        builder.AppendLine();
+
+        foreach (SigtranMaintainedPeerLabCommand command in RunManifest.CommandPlan.Commands)
+        {
+            builder.Append("# ");
+            builder.AppendLine(command.Describe());
+            builder.AppendLine(command.CommandLine);
+            builder.AppendLine();
+        }
+
+        return builder.ToString();
+    }
+
+    /// <summary>Whether the rendered script covers every command in the manifest.</summary>
+    public bool CoversCommandPlan => RunManifest.CommandPlan.Commands.All(command => Render().Contains(command.CommandLine, StringComparison.Ordinal));
+
+    /// <summary>Formats a compact command script summary.</summary>
+    /// <returns>The command script summary.</returns>
+    public string Describe()
+    {
+        return $"run={RunManifest.RunId} env={EnvironmentFilePath} commands={RunManifest.CommandPlan.Commands.Count} rendered={Render().Length}";
+    }
+
+    private static string Quote(string value)
+    {
+        return "'" + value.Replace("'", "'\"'\"'", StringComparison.Ordinal) + "'";
+    }
+}
+
+/// <summary>
+/// Provides maintained external peer lab command script helpers.
+/// </summary>
+public static class SigtranMaintainedPeerLabCommandScripts
+{
+    /// <summary>Creates the default command script for a maintained peer lab run.</summary>
+    /// <param name="runManifest">The run manifest.</param>
+    /// <returns>The rendered command script model.</returns>
+    public static SigtranMaintainedPeerLabCommandScript CreateDefault(SigtranMaintainedPeerLabRunManifest runManifest)
+    {
+        ArgumentNullException.ThrowIfNull(runManifest);
+        string environmentFilePath = $"{runManifest.ArtifactPlan.ArtifactRoot}/config/{runManifest.RunId}-peer.env";
+        return new(runManifest, environmentFilePath);
+    }
+}