Codex: add sync plan/apply commands backed by shared deploying lib

docs-builder.slnx

@@ -70,6 +70,7 @@
   <Folder Name="/src/services/">
     <Project Path="src/services/Elastic.Changelog/Elastic.Changelog.csproj" />
     <Project Path="src/services/Elastic.Documentation.Assembler/Elastic.Documentation.Assembler.csproj" />
+    <Project Path="src/services/Elastic.Documentation.Deploying/Elastic.Documentation.Deploying.csproj" />
     <Project Path="src/services/Elastic.Documentation.Isolated/Elastic.Documentation.Isolated.csproj" />
     <Project Path="src/services/Elastic.Documentation.Integrations/Elastic.Documentation.Integrations.csproj" />
     <Project Path="src/services/Elastic.Documentation.Services/Elastic.Documentation.Services.csproj" />

docs/cli-schema.json

@@ -4754,7 +4754,225 @@
           ]
         }
       ],
-      "namespaces": []
+      "namespaces": [
+        {
+          "segment": "sync",
+          "summary": "Sync built codex output to S3 using a two-step plan/apply workflow.",
+          "options": [],
+          "commands": [
+            {
+              "path": [
+                "codex",
+                "sync"
+              ],
+              "name": "apply",
+              "summary": "Upload the changes described in a plan file to S3.",
+              "notes": "Run after codex sync plan. Applies the pre-computed diff to the S3 bucket.",
+              "usage": "docs-builder codex sync apply \u003Cconfig\u003E --s3-bucket-name \u003Cstring\u003E --plan-file \u003Cfile\u003E",
+              "examples": [],
+              "parameters": [
+                {
+                  "role": "positional",
+                  "name": "config",
+                  "type": "string",
+                  "required": true,
+                  "summary": "Path to the codex.yml configuration file.",
+                  "validations": [
+                    {
+                      "kind": "rejectSymbolicLinks"
+                    },
+                    {
+                      "kind": "existing"
+                    },
+                    {
+                      "kind": "fileExtensions",
+                      "values": [
+                        "yml",
+                        "yaml"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "s3-bucket-name",
+                  "type": "string",
+                  "required": true,
+                  "summary": "S3 bucket to deploy to."
+                },
+                {
+                  "role": "flag",
+                  "name": "plan-file",
+                  "type": "string",
+                  "required": true,
+                  "summary": "Path to the plan file produced by codex sync plan.",
+                  "validations": [
+                    {
+                      "kind": "rejectSymbolicLinks"
+                    },
+                    {
+                      "kind": "existing"
+                    },
+                    {
+                      "kind": "fileExtensions",
+                      "values": [
+                        "json",
+                        "plan"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "log-level",
+                  "shortName": "l",
+                  "type": "enum",
+                  "required": false,
+                  "summary": "Minimum log level. Default: information",
+                  "enumValues": [
+                    "trace",
+                    "debug",
+                    "information",
+                    "warning",
+                    "error",
+                    "critical",
+                    "none"
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "config-source",
+                  "shortName": "c",
+                  "type": "enum",
+                  "required": false,
+                  "summary": "Override the configuration source: local, remote",
+                  "enumValues": [
+                    "local",
+                    "remote",
+                    "embedded"
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "skip-private-repositories",
+                  "type": "boolean",
+                  "required": false,
+                  "summary": "Skip cloning private repositories"
+                }
+              ],
+              "intent": {
+                "destructive": true,
+                "scope": "global",
+                "requiresAuth": true
+              }
+            },
+            {
+              "path": [
+                "codex",
+                "sync"
+              ],
+              "name": "plan",
+              "summary": "Compute a diff of what would change when deploying to S3 and write it to a plan file.",
+              "notes": "Two-step deployment: plan computes the diff and writes a plan file; apply executes it.\nReview the plan before applying to avoid accidental mass deletions.",
+              "usage": "docs-builder codex sync plan \u003Cconfig\u003E --s3-bucket-name \u003Cstring\u003E [options]",
+              "examples": [],
+              "parameters": [
+                {
+                  "role": "positional",
+                  "name": "config",
+                  "type": "string",
+                  "required": true,
+                  "summary": "Path to the codex.yml configuration file.",
+                  "validations": [
+                    {
+                      "kind": "rejectSymbolicLinks"
+                    },
+                    {
+                      "kind": "existing"
+                    },
+                    {
+                      "kind": "fileExtensions",
+                      "values": [
+                        "yml",
+                        "yaml"
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "s3-bucket-name",
+                  "type": "string",
+                  "required": true,
+                  "summary": "S3 bucket to deploy to."
+                },
+                {
+                  "role": "flag",
+                  "name": "out",
+                  "type": "string",
+                  "required": false,
+                  "summary": "Path to write the plan file. Defaults to stdout.",
+                  "validations": [
+                    {
+                      "kind": "rejectSymbolicLinks"
+                    }
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "delete-threshold",
+                  "type": "number",
+                  "required": false,
+                  "summary": "Abort if the plan would delete more than this percentage of objects (0\u2013100).",
+                  "defaultValue": "default"
+                },
+                {
+                  "role": "flag",
+                  "name": "log-level",
+                  "shortName": "l",
+                  "type": "enum",
+                  "required": false,
+                  "summary": "Minimum log level. Default: information",
+                  "enumValues": [
+                    "trace",
+                    "debug",
+                    "information",
+                    "warning",
+                    "error",
+                    "critical",
+                    "none"
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "config-source",
+                  "shortName": "c",
+                  "type": "enum",
+                  "required": false,
+                  "summary": "Override the configuration source: local, remote",
+                  "enumValues": [
+                    "local",
+                    "remote",
+                    "embedded"
+                  ]
+                },
+                {
+                  "role": "flag",
+                  "name": "skip-private-repositories",
+                  "type": "boolean",
+                  "required": false,
+                  "summary": "Skip cloning private repositories"
+                }
+              ],
+              "intent": {
+                "scope": "global",
+                "requiresAuth": true
+              }
+            }
+          ],
+          "namespaces": []
+        }
+      ]
     },
     {
       "segment": "inbound-links",

src/Elastic.Codex/CodexContext.cs

@@ -5,6 +5,7 @@
 using System.IO.Abstractions;
 using Elastic.Documentation.Configuration;
 using Elastic.Documentation.Configuration.Codex;
+using Elastic.Documentation.Deploying.Synchronization;
 using Elastic.Documentation.Diagnostics;
 using Nullean.ScopedFileSystem;
 
@@ -13,7 +14,7 @@ namespace Elastic.Codex;
 /// <summary>
 /// Context for codex operations containing configuration, file systems, and directories.
 /// </summary>
-public class CodexContext
+public class CodexContext : IDocsSyncContext
 {
 	public ScopedFileSystem ReadFileSystem { get; }
 	public ScopedFileSystem WriteFileSystem { get; }
@@ -27,9 +28,10 @@ public class CodexContext
 	/// The Elasticsearch index namespace for this codex, derived from the environment name.
 	/// Falls back to "codex" when no environment is specified.
 	/// </summary>
-	public string IndexNamespace => string.IsNullOrEmpty(Configuration.Environment)
-		? "codex"
-		: $"codex-{Configuration.Environment}";
+	public string IndexNamespace => string.IsNullOrEmpty(Configuration.Environment) ? "codex" : $"codex-{EnvironmentName}";
+
+	/// <inheritdoc cref="IDocsSyncContext.EnvironmentName"/>
+	public string EnvironmentName { get; }
 
 	public CodexContext(
 		CodexConfiguration configuration,
@@ -46,6 +48,8 @@ public CodexContext(
 		ReadFileSystem = readFileSystem;
 		WriteFileSystem = writeFileSystem;
 
+		EnvironmentName = string.IsNullOrEmpty(configuration.Environment) ? "codex" : configuration.Environment;
+
 		var defaultCheckoutDirectory = Path.Join(Paths.ApplicationData.FullName, "codex", "clone");
 		CheckoutDirectory = checkoutDirectory is null
 			? FileSystemFactory.AppData.DirectoryInfo.New(defaultCheckoutDirectory)

src/Elastic.Codex/Elastic.Codex.csproj

@@ -31,6 +31,7 @@
     <ProjectReference Include="..\Elastic.Documentation.ServiceDefaults\Elastic.Documentation.ServiceDefaults.csproj"/>
     <ProjectReference Include="..\services\Elastic.Documentation.Services\Elastic.Documentation.Services.csproj"/>
     <ProjectReference Include="..\services\Elastic.Documentation.Isolated\Elastic.Documentation.Isolated.csproj"/>
+    <ProjectReference Include="..\services\Elastic.Documentation.Deploying\Elastic.Documentation.Deploying.csproj"/>
     <ProjectReference Include="..\Elastic.Markdown\Elastic.Markdown.csproj"/>
   </ItemGroup>
 

src/services/Elastic.Documentation.Assembler/AssembleContext.cs

@@ -9,12 +9,13 @@
 using Elastic.Documentation.Configuration.Products;
 using Elastic.Documentation.Configuration.Search;
 using Elastic.Documentation.Configuration.Versions;
+using Elastic.Documentation.Deploying.Synchronization;
 using Elastic.Documentation.Diagnostics;
 using Nullean.ScopedFileSystem;
 
 namespace Elastic.Documentation.Assembler;
 
-public class AssembleContext : IDocumentationConfigurationContext
+public class AssembleContext : IDocumentationConfigurationContext, IDocsSyncContext
 {
 	public ScopedFileSystem ReadFileSystem { get; }
 	public ScopedFileSystem WriteFileSystem { get; }
@@ -57,6 +58,9 @@ public class AssembleContext : IDocumentationConfigurationContext
 
 	public PublishEnvironment Environment { get; }
 
+	/// <inheritdoc cref="IDocsSyncContext.EnvironmentName"/>
+	public string EnvironmentName => Environment.Name;
+
 	public AssembleContext(
 		AssemblyConfiguration configuration,
 		IConfigurationContext configurationContext,

src/services/Elastic.Documentation.Assembler/Elastic.Documentation.Assembler.csproj

@@ -31,6 +31,7 @@
     <ProjectReference Include="..\..\Elastic.Markdown\Elastic.Markdown.csproj" />
     <ProjectReference Include="..\Elastic.Documentation.Services\Elastic.Documentation.Services.csproj" />
     <ProjectReference Include="..\Elastic.Documentation.Integrations\Elastic.Documentation.Integrations.csproj" />
+    <ProjectReference Include="..\Elastic.Documentation.Deploying\Elastic.Documentation.Deploying.csproj" />
   </ItemGroup>
 
 </Project>

src/services/Elastic.Documentation.Deploying/Elastic.Documentation.Deploying.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+	<PropertyGroup>
+		<TargetFramework>net10.0</TargetFramework>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<Nullable>enable</Nullable>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<PackageReference Include="AWSSDK.S3" />
+		<PackageReference Include="GitHub.Actions.Core" />
+		<PackageReference Include="Nullean.ScopedFileSystem" />
+		<PackageReference Include="Microsoft.Extensions.Logging" />
+		<PackageReference Include="System.IO.Abstractions" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<ProjectReference Include="$(SolutionRoot)\src\Elastic.Documentation\Elastic.Documentation.csproj" />
+		<ProjectReference Include="$(SolutionRoot)\src\Elastic.Documentation.ServiceDefaults\Elastic.Documentation.ServiceDefaults.csproj" />
+		<ProjectReference Include="..\Elastic.Documentation.Services\Elastic.Documentation.Services.csproj" />
+		<ProjectReference Include="..\Elastic.Documentation.Integrations\Elastic.Documentation.Integrations.csproj" />
+	</ItemGroup>
+
+</Project>