refactor(cli): migrate file/directory path params to FileInfo and DirectoryInfo

- ElasticsearchIndexOptions.CertificatePath: string? -> FileInfo? [FileExtensions("pem,der,crt,cer")]
- IsolatedBuildOptions.Path, Output: string? -> DirectoryInfo?
- Codex config params (all four commands): string -> FileInfo [FileExtensions("yml,yaml")]
- Codex output params: string? -> DirectoryInfo?
- DeployCommands: planFile -> FileInfo [json], @out -> FileInfo?, redirectsFile -> FileInfo? [json]
- CodexUpdateRedirectsCommand.redirectsFile: string? -> FileInfo? [json]
- NavigationCommands.ValidateLinkReference file: string? -> FileInfo? [json]
- InboundLinkCommands.ValidateLinkReference file: string? -> FileInfo? [json]
- BloomFilterCommands.Create builtDocsDir: string -> DirectoryInfo
- AssemblerCommands.Serve path: string? -> DirectoryInfo?
- ServeCommand path: string? -> DirectoryInfo?
- ChangelogCommand.Init path/changelogDir/bundlesDir: string? -> DirectoryInfo?
- ChangelogCommand config params (Add, Bundle, Remove, Render, GhRelease, Upload, EvaluatePr): string? -> FileInfo? [yml,yaml]
- ChangelogCommand directory params: string? -> DirectoryInfo?
- ChangelogCommand.BundleAmend bundlePath: string -> FileInfo [yml,yaml]
- Help text: path/file/dir params now show as <dir>, <file>, <path> with extension hints

Tilde expansion report (params needing future argh [ExpandTilde] attribute):
changelog init path/changelogDir/bundlesDir, all config params, all directory
params, assembler deploy planFile/@out, CertificatePath, build Path/Output.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: Mpdreamz

src/Elastic.Documentation.Configuration/ElasticsearchEndpointConfigurator.cs

@@ -88,7 +88,8 @@ public record ElasticsearchIndexOptions
 	public string? CertificateFingerprint { get; init; }
 
 	/// <summary>Path to a PEM or DER certificate file for SSL validation.</summary>
-	public string? CertificatePath { get; init; }
+	[FileExtensions(Extensions = "pem,der,crt,cer")]
+	public FileInfo? CertificatePath { get; init; }
 
 	/// <summary>Set when the certificate is an intermediate CA rather than the root.</summary>
 	public bool? CertificateNotRoot { get; init; }
@@ -138,11 +139,11 @@ public static async Task ApplyAsync(
 			cfg.ProxyUsername = options.ProxyUsername;
 		if (options.DisableSslVerification.HasValue)
 			cfg.DisableSslVerification = options.DisableSslVerification.Value;
-		if (!string.IsNullOrEmpty(options.CertificatePath))
+		if (options.CertificatePath is not null)
 		{
-			if (!fileSystem.File.Exists(options.CertificatePath))
-				collector.EmitGlobalError($"'{options.CertificatePath}' does not exist");
-			var bytes = await fileSystem.File.ReadAllBytesAsync(options.CertificatePath, ctx);
+			if (!fileSystem.File.Exists(options.CertificatePath.FullName))
+				collector.EmitGlobalError($"'{options.CertificatePath.FullName}' does not exist");
+			var bytes = await fileSystem.File.ReadAllBytesAsync(options.CertificatePath.FullName, ctx);
 			cfg.Certificate = X509CertificateLoader.LoadCertificate(bytes);
 		}
 		if (options.CertificateNotRoot.HasValue)

src/services/Elastic.Documentation.Isolated/IsolatedBuildOptions.cs

@@ -11,10 +11,10 @@ namespace Elastic.Documentation.Isolated;
 public record IsolatedBuildOptions
 {
 	/// <summary>-p, Root directory of the documentation source. Defaults to <c>cwd/docs</c>.</summary>
-	public string? Path { get; init; }
+	public DirectoryInfo? Path { get; init; }
 
 	/// <summary>-o, Destination for generated HTML. Defaults to <c>.artifacts/html</c>.</summary>
-	public string? Output { get; init; }
+	public DirectoryInfo? Output { get; init; }
 
 	/// <summary>URL path prefix prepended to every generated link.</summary>
 	public string? PathPrefix { get; init; }

src/services/Elastic.Documentation.Isolated/IsolatedBuildService.cs

@@ -50,8 +50,8 @@ public async Task<bool> Build(
 		Cancel ctx = default
 	)
 	{
-		var path = options.Path;
-		var output = options.Output;
+		var path = options.Path?.FullName;
+		var output = options.Output?.FullName;
 		var pathPrefix = options.PathPrefix;
 		var force = options.Force;
 		var strict = options.Strict;

src/services/Elastic.Documentation.Isolated/IsolatedIndexService.cs

@@ -35,7 +35,7 @@ public async Task<bool> Index(
 
 		return await Build(collector, fileSystem, new IsolatedBuildOptions
 		{
-			Path = path,
+			Path = path != null ? new DirectoryInfo(path) : null,
 			MetadataOnly = true,
 			Strict = false,
 			Force = true,

src/tooling/docs-builder/Commands/Assembler/AssemblerCommands.cs

@@ -157,9 +157,9 @@ static async (s, col, state, ctx) => await s.BuildAll(col, state.options, state.
 	/// <param name="port">Port to listen on. Default: 4000.</param>
 	/// <param name="path">Path to the built site. Defaults to <c>.artifacts/docs/</c>.</param>
 	[NoOptionsInjection]
-	public async Task Serve(int port = 4000, string? path = null, CancellationToken ct = default)
+	public async Task Serve(int port = 4000, DirectoryInfo? path = null, CancellationToken ct = default)
 	{
-		var host = new StaticWebHost(port, path);
+		var host = new StaticWebHost(port, path?.FullName);
 		await host.RunAsync(ct);
 		await host.StopAsync(ct);
 		await collector.StopAsync(ct);

src/tooling/docs-builder/Commands/Assembler/BloomFilterCommands.cs

@@ -22,11 +22,11 @@ internal sealed class BloomFilterCommands(ILoggerFactory logFactory, IDiagnostic
 	/// </remarks>
 	/// <param name="builtDocsDir">Path to the local legacy-docs repository checkout.</param>
 	[NoOptionsInjection]
-	public async Task<int> Create(string builtDocsDir, CancellationToken ct = default)
+	public async Task<int> Create(DirectoryInfo builtDocsDir, CancellationToken ct = default)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
-		var pagesProvider = new LocalPagesProvider(builtDocsDir);
+		var pagesProvider = new LocalPagesProvider(builtDocsDir.FullName);
 		var legacyPageService = new LegacyPageService(logFactory);
 
 		serviceInvoker.AddCommand(legacyPageService, pagesProvider, static (s, _, pagesProvider, _) =>

src/tooling/docs-builder/Commands/Assembler/DeployCommands.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.ComponentModel.DataAnnotations;
 using Actions.Core.Services;
 using Elastic.Documentation;
 using Elastic.Documentation.Assembler.Deploying;
@@ -33,13 +34,13 @@ ICoreService githubActionsService
 	/// <param name="out">Path to write the plan file. Defaults to <c>stdout</c>.</param>
 	/// <param name="deleteThreshold">Abort if the plan would delete more than this percentage of objects (0–100).</param>
 	[NoOptionsInjection]
-	public async Task<int> Plan(string environment, string s3BucketName, string @out = "", float? deleteThreshold = null, CancellationToken ct = default)
+	public async Task<int> Plan(string environment, string s3BucketName, FileInfo? @out = null, float? deleteThreshold = null, CancellationToken ct = default)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new IncrementalDeployService(logFactory, assemblyConfiguration, configurationContext, githubActionsService, FileSystemFactory.RealRead, FileSystemFactory.RealWrite);
 		serviceInvoker.AddCommand(service, (environment, s3BucketName, @out, deleteThreshold),
-			static async (s, collector, state, ctx) => await s.Plan(collector, state.environment, state.s3BucketName, state.@out, state.deleteThreshold, ctx)
+			static async (s, collector, state, ctx) => await s.Plan(collector, state.environment, state.s3BucketName, state.@out?.FullName ?? "", state.deleteThreshold, ctx)
 		);
 		return await serviceInvoker.InvokeAsync(ct);
 	}
@@ -50,13 +51,13 @@ static async (s, collector, state, ctx) => await s.Plan(collector, state.environ
 	/// <param name="s3BucketName">S3 bucket to deploy to.</param>
 	/// <param name="planFile">Path to the plan file produced by <c>assembler deploy plan</c>.</param>
 	[NoOptionsInjection]
-	public async Task<int> Apply(string environment, string s3BucketName, string planFile, CancellationToken ct = default)
+	public async Task<int> Apply(string environment, string s3BucketName, [FileExtensions(Extensions = "json")] FileInfo planFile, CancellationToken ct = default)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new IncrementalDeployService(logFactory, assemblyConfiguration, configurationContext, githubActionsService, FileSystemFactory.RealRead, FileSystemFactory.RealWrite);
 		serviceInvoker.AddCommand(service, (environment, s3BucketName, planFile),
-			static async (s, collector, state, ctx) => await s.Apply(collector, state.environment, state.s3BucketName, state.planFile, ctx)
+			static async (s, collector, state, ctx) => await s.Apply(collector, state.environment, state.s3BucketName, state.planFile.FullName, ctx)
 		);
 		return await serviceInvoker.InvokeAsync(ct);
 	}
@@ -66,14 +67,14 @@ static async (s, collector, state, ctx) => await s.Apply(collector, state.enviro
 	/// <param name="environment">Named deployment target.</param>
 	/// <param name="redirectsFile">Path to <c>redirects.json</c>. Defaults to <c>.artifacts/docs/redirects.json</c>.</param>
 	[NoOptionsInjection]
-	public async Task<int> UpdateRedirects(string environment, string? redirectsFile = null, CancellationToken ct = default)
+	public async Task<int> UpdateRedirects(string environment, [FileExtensions(Extensions = "json")] FileInfo? redirectsFile = null, CancellationToken ct = default)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var fs = FileSystemFactory.RealRead;
 		var service = new DeployUpdateRedirectsService(logFactory, fs);
 		serviceInvoker.AddCommand(service, (environment, redirectsFile),
-			static async (s, collector, state, ctx) => await s.UpdateRedirects(collector, state.environment, state.redirectsFile, ctx: ctx)
+			static async (s, collector, state, ctx) => await s.UpdateRedirects(collector, state.environment, state.redirectsFile?.FullName, ctx: ctx)
 		);
 		return await serviceInvoker.InvokeAsync(ct);
 	}

src/tooling/docs-builder/Commands/Assembler/NavigationCommands.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.ComponentModel.DataAnnotations;
 using System.IO.Abstractions;
 using Elastic.Documentation;
 using Elastic.Documentation.Assembler.Navigation;
@@ -35,11 +36,11 @@ public async Task<int> Validate(CancellationToken ct = default)
 	/// <summary>Check that no link in a local <c>links.json</c> conflicts with a path prefix defined in <c>navigation.yml</c>.</summary>
 	/// <param name="file">Path to <c>links.json</c>. Defaults to <c>.artifacts/docs/html/links.json</c>.</param>
 	[NoOptionsInjection]
-	public async Task<int> ValidateLinkReference([Argument] string? file = null, CancellationToken ct = default)
+	public async Task<int> ValidateLinkReference([Argument, FileExtensions(Extensions = "json")] FileInfo? file = null, CancellationToken ct = default)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
 		var service = new GlobalNavigationService(logFactory, configuration, configurationContext, FileSystemFactory.RealRead);
-		serviceInvoker.AddCommand(service, file, static async (s, collector, file, ctx) => await s.ValidateLocalLinkReference(collector, file, ctx));
+		serviceInvoker.AddCommand(service, file, static async (s, collector, file, ctx) => await s.ValidateLocalLinkReference(collector, file?.FullName, ctx));
 		return await serviceInvoker.InvokeAsync(ct);
 	}
 }