Merge pull request #566 from Chris0Jeky/feat/pkg-04-first-run-autoconfig

feat: first-run auto-config (JWT secret, DB path, browser open) (PKG-04 #536)

Author: Chris0Jeky

.gitignore

@@ -62,6 +62,9 @@ lerna-debug.log*
 
 # Claude Code local settings (personal overrides, not shared)
 .claude/settings.local.json
+
+# Auto-generated first-run config (contains JWT secret — never commit)
+appsettings.local.json
 *.swp
 *.swo
 *~

backend/src/Taskdeck.Api/FirstRun/FirstRunBootstrapper.cs

@@ -0,0 +1,258 @@
+using System.Security.Cryptography;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Configuration.EnvironmentVariables;
+
+namespace Taskdeck.Api.FirstRun;
+
+/// <summary>
+/// Runs synchronously before the DI container is built.
+/// Ensures that auto-generated configuration values (JWT secret, DB path)
+/// are written to <c>appsettings.local.json</c> so they are available to
+/// all subsequent configuration consumers.
+/// </summary>
+public static class FirstRunBootstrapper
+{
+    // Placeholder values that indicate "not configured"
+    private static readonly HashSet<string> PlaceholderSecrets =
+        new(StringComparer.OrdinalIgnoreCase)
+        {
+            string.Empty,
+            "TaskdeckDevelopmentOnlySecretKeyChangeMe123!"
+        };
+
+    /// <summary>
+    /// Registers <c>appsettings.local.json</c> as an optional configuration
+    /// source so that previously generated secrets are picked up.
+    /// Call this before building <see cref="WebApplication"/>.
+    /// </summary>
+    /// <remarks>
+    /// The source is inserted <em>before</em> any
+    /// <see cref="EnvironmentVariablesConfigurationSource"/> entries so that
+    /// environment variables always win over the auto-generated file.  This
+    /// preserves 12-factor / container deployment patterns where operators
+    /// supply <c>Jwt__SecretKey</c> (or similar) via environment variables
+    /// and must not be silently overridden by a previously written file.
+    /// </remarks>
+    public static WebApplicationBuilder AddLocalConfigFile(this WebApplicationBuilder builder)
+    {
+        var sources = builder.Configuration.Sources;
+
+        // Find the first EnvironmentVariablesConfigurationSource so we can
+        // insert the file source before it, giving env vars higher priority.
+        var envIndex = -1;
+        for (var i = 0; i < sources.Count; i++)
+        {
+            if (sources[i] is EnvironmentVariablesConfigurationSource)
+            {
+                envIndex = i;
+                break;
+            }
+        }
+
+        var fileSource = new Microsoft.Extensions.Configuration.Json.JsonConfigurationSource
+        {
+            Path = LocalConfigPath,
+            Optional = true,
+            ReloadOnChange = false
+        };
+        // Resolve the file provider so the source can locate the file.
+        fileSource.ResolveFileProvider();
+
+        if (envIndex >= 0)
+        {
+            sources.Insert(envIndex, fileSource);
+        }
+        else
+        {
+            // No env-var source found (unusual); append at end.
+            sources.Add(fileSource);
+        }
+
+        return builder;
+    }
+
+    /// <summary>
+    /// Runs the first-run checks. Must be called after
+    /// <see cref="AddLocalConfigFile"/> and after the standard
+    /// <c>appsettings.json</c> / <c>appsettings.{env}.json</c> files have been
+    /// loaded (i.e. after the builder is constructed).
+    /// </summary>
+    /// <remarks>
+    /// Checks are skipped in Development and in CI/headless environments.
+    /// They are intended for the packaged self-hosted production scenario.
+    /// </remarks>
+    public static WebApplicationBuilder RunFirstRunChecks(
+        this WebApplicationBuilder builder,
+        ILogger logger)
+    {
+        // First-run checks are for the self-hosted packaged distribution.
+        // In Development the developer supplies their own config values.
+        if (builder.Environment.IsDevelopment())
+        {
+            return builder;
+        }
+
+        // Also skip in CI / automated environments.
+        if (IsHeadlessEnvironment())
+        {
+            return builder;
+        }
+
+        EnsureJwtSecret(builder.Configuration, logger);
+        EnsureDbPath(builder.Configuration, logger);
+        return builder;
+    }
+
+    // -------------------------------------------------------------------------
+
+    internal static string LocalConfigPath
+    {
+        get
+        {
+            var dir = AppContext.BaseDirectory;
+            return Path.Combine(dir, "appsettings.local.json");
+        }
+    }
+
+    internal static bool IsPlaceholder(string value)
+        => string.IsNullOrWhiteSpace(value) || PlaceholderSecrets.Contains(value.Trim());
+
+    internal static string GenerateSecret()
+        => Convert.ToBase64String(RandomNumberGenerator.GetBytes(32));
+
+    private static void EnsureJwtSecret(IConfiguration configuration, ILogger logger)
+    {
+        var configured = configuration["Jwt:SecretKey"] ?? string.Empty;
+
+        if (!IsPlaceholder(configured))
+        {
+            return;
+        }
+
+        var generated = GenerateSecret();
+        PersistValue("Jwt", "SecretKey", generated);
+        // Reload so subsequent configuration reads get the new value.
+        if (configuration is IConfigurationRoot root)
+        {
+            root.Reload();
+        }
+
+        logger.LogInformation(
+            "First-run: JWT secret was not configured. A random secret has been " +
+            "generated and saved to {ConfigFile}.", LocalConfigPath);
+    }
+
+    private static void EnsureDbPath(IConfiguration configuration, ILogger logger)
+    {
+        var resolveAppData = configuration.GetValue<bool?>("FirstRun:ResolveAppDataDbPath") ?? true;
+        if (!resolveAppData)
+        {
+            return;
+        }
+
+        var connectionString = configuration.GetConnectionString("DefaultConnection")
+            ?? string.Empty;
+        var dataSource = ExtractDataSource(connectionString);
+
+        // Already an absolute path — nothing to do.
+        if (!string.IsNullOrWhiteSpace(dataSource) && Path.IsPathRooted(dataSource))
+        {
+            return;
+        }
+
+        var appDataDir = GetAppDataPath();
+        Directory.CreateDirectory(appDataDir);
+
+        var dbFile = string.IsNullOrWhiteSpace(dataSource)
+            ? "taskdeck.db"
+            : Path.GetFileName(dataSource);
+
+        var resolvedPath = Path.Combine(appDataDir, dbFile);
+        var resolvedConnectionString = $"Data Source={resolvedPath}";
+
+        // Write into the local config file so the value is picked up by
+        // AddInfrastructure later in the startup pipeline.
+        PersistValue("ConnectionStrings", "DefaultConnection", resolvedConnectionString);
+
+        if (configuration is IConfigurationRoot root)
+        {
+            root.Reload();
+        }
+
+        logger.LogInformation(
+            "First-run: SQLite DB path resolved to AppData location: {DbPath}", resolvedPath);
+    }
+
+    internal static bool IsHeadlessEnvironment()
+    {
+        return !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("CI"))
+            || !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("TF_BUILD"))
+            || !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS"))
+            || !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("TASKDECK_HEADLESS"));
+    }
+
+    internal static string GetAppDataPath()
+    {
+        var localAppData = Environment.GetFolderPath(
+            Environment.SpecialFolder.LocalApplicationData,
+            Environment.SpecialFolderOption.Create);
+        return Path.Combine(localAppData, "Taskdeck");
+    }
+
+    private static string ExtractDataSource(string connectionString)
+    {
+        if (string.IsNullOrWhiteSpace(connectionString))
+            return string.Empty;
+
+        try
+        {
+            var builder = new Microsoft.Data.Sqlite.SqliteConnectionStringBuilder(connectionString);
+            return builder.DataSource;
+        }
+        catch (ArgumentException)
+        {
+            return string.Empty;
+        }
+    }
+
+    private static void PersistValue(string section, string key, string value)
+    {
+        var path = LocalConfigPath;
+
+        JsonObject root;
+        if (File.Exists(path))
+        {
+            try
+            {
+                var existing = File.ReadAllText(path);
+                root = JsonNode.Parse(existing)?.AsObject() ?? new JsonObject();
+            }
+            catch (Exception ex)
+            {
+                // Logger is not available at this pre-DI stage; warn to stderr and start fresh
+                // rather than silently discarding the corrupt file.
+                Console.Error.WriteLine(
+                    $"[FirstRun] WARNING: {path} contains invalid JSON and will be overwritten. " +
+                    $"Details: {ex.Message}");
+                root = new JsonObject();
+            }
+        }
+        else
+        {
+            root = new JsonObject();
+        }
+
+        if (root[section] is not JsonObject sectionNode)
+        {
+            sectionNode = new JsonObject();
+            root[section] = sectionNode;
+        }
+
+        sectionNode[key] = value;
+
+        var options = new JsonSerializerOptions { WriteIndented = true };
+        File.WriteAllText(path, root.ToJsonString(options));
+    }
+}

backend/src/Taskdeck.Api/FirstRun/FirstRunService.cs

@@ -0,0 +1,61 @@
+using System.Diagnostics;
+
+namespace Taskdeck.Api.FirstRun;
+
+/// <summary>
+/// Runtime first-run service. Handles post-startup concerns:
+/// browser auto-open after the host is ready.
+/// Configuration bootstrapping (JWT secret, DB path) is handled at build-time
+/// by <see cref="FirstRunBootstrapper"/>.
+/// </summary>
+public sealed class FirstRunService
+{
+    private readonly ILogger<FirstRunService> _logger;
+    private readonly FirstRunSettings _settings;
+
+    public FirstRunService(
+        ILogger<FirstRunService> logger,
+        FirstRunSettings settings)
+    {
+        _logger = logger;
+        _settings = settings;
+    }
+
+    /// <summary>
+    /// Opens the browser to the given URL when
+    /// <see cref="FirstRunSettings.AutoOpenBrowser"/> is enabled and the
+    /// process is not running in a headless/CI context.
+    /// </summary>
+    /// <param name="url">The URL to open. Typically the actual listening address
+    /// obtained from <c>IServerAddressesFeature</c>.</param>
+    public void TryOpenBrowser(string url)
+    {
+        if (!_settings.AutoOpenBrowser)
+        {
+            return;
+        }
+
+        if (FirstRunBootstrapper.IsHeadlessEnvironment())
+        {
+            _logger.LogDebug(
+                "First-run: AutoOpenBrowser skipped (headless/CI environment detected).");
+            return;
+        }
+
+        _logger.LogInformation("First-run: Opening browser at {Url}", url);
+
+        try
+        {
+            Process.Start(new ProcessStartInfo
+            {
+                FileName = url,
+                UseShellExecute = true
+            });
+        }
+        catch (Exception ex)
+        {
+            // Non-fatal: the user can always open the browser manually.
+            _logger.LogWarning(ex, "First-run: Failed to open browser at {Url}.", url);
+        }
+    }
+}

backend/src/Taskdeck.Api/FirstRun/FirstRunSettings.cs

@@ -0,0 +1,25 @@
+namespace Taskdeck.Api.FirstRun;
+
+/// <summary>
+/// Configuration for first-run automatic setup behaviour.
+/// </summary>
+public sealed class FirstRunSettings
+{
+    /// <summary>
+    /// When true the app opens the browser to the local URL after startup.
+    /// Defaults to false so it never fires in CI or server deployments.
+    /// </summary>
+    public bool AutoOpenBrowser { get; set; } = false;
+
+    /// <summary>
+    /// Port the API listens on. Used to build the browser URL.
+    /// </summary>
+    public int Port { get; set; } = 5000;
+
+    /// <summary>
+    /// When true the first-run service resolves the DB path to the OS
+    /// AppData/local-share folder if no explicit path is configured.
+    /// Defaults to true.
+    /// </summary>
+    public bool ResolveAppDataDbPath { get; set; } = true;
+}