Feat: workspace aware timeline export and storage

Store generated .gittrace files under the currently selected workspace instead of treating exports as standalone output files only.

Added

 Export flow
      - Resolves the currently active workspace from IWorkspaceContext
      - Updates export logic to save generated timeline data under the active workspace
      - Preserves explicit --output/-o fallback behavior
      - Adds validation to fail gracefully when no workspace is selected

 Workspace storage
      - Adds WorkspaceTimelineStorage to handle predictable workspace specific paths
      - Saves WorkspaceTimelineMetadata sidecar files to identify repository sources
      - Implements listing of stored timeline files for a workspace

 CLI integration
      - Adds WorkTimelinesCommand for listing workspace timelines
      - Adds WorkTimelinesCommandHandler to present timeline metadata in an organized table
      - Adds tests for workspace aware export path resolution

Result

 These changes make timeline exports workspace-aware, organizing generated .gittrace files automatically and providing the foundation to easily list and reuse them for workspace specific history views.

Author: rian-be

src/Cli/Commands/ExportCommand.cs

@@ -8,13 +8,13 @@
 namespace ChangeTrace.Cli.Commands;
 
 /// <summary>
-/// Represents 'export' CLI command that exports a repository timeline to  JSON file.
+/// Represents 'export' CLI command that exports a repository timeline to a .gittrace file.
 /// </summary>
 /// <remarks>
 /// <list type="bullet">
 /// <item>Implements <see cref="ICliCommand"/> to define the command structure and associate a handler.</item>
 /// <item>Registers itself as a singleton via <see cref="AutoRegisterAttribute"/>.</item>
-/// <item>Defines arguments and options for specifying the repository, output file, GitHub token, and verbosity.</item>
+/// <item>Defines arguments and options for specifying the repository, optional output file, GitHub token, and verbosity.</item>
 /// <item>The actual execution logic is handled by <see cref="ExportCommandHandler"/>.</item>
 /// </list>
 /// </remarks>
@@ -36,7 +36,10 @@ public Command Build()
         var cmd = new Command("export", "Export repository timeline");
 
         var repoArg = new Argument<string>("repository")  {  Description = "Local path or HTTPS URL to Git repository" };
-        var outputOpt = new Option<string>("--output", "-o")  { Description = "Output JSON file path",  DefaultValueFactory = _ => "timeline.gittrace" };
+        var outputOpt = new Option<string?>("--output", "-o")
+        {
+            Description = "Explicit output .gittrace path. When omitted, export is saved under the active workspace."
+        };
         var tokenOpt = new Option<string?>("--token", "-r")  { Description = "GitHub personal access token" };
         var verboseOpt = new Option<bool>("--verbose", "-v") { Description = "Enable verbose logging" };
 
@@ -47,4 +50,4 @@ public Command Build()
 
         return cmd;
     }
-}
+}

src/Cli/Commands/Profiles/Organizations/OrgCommand.cs

@@ -41,5 +41,9 @@ internal sealed class OrgCommand : ICliCommand
     /// </summary>
     /// <returns>Configured <see cref="Command"/> for organization subcommands.</returns>
     public Command Build()
-        => new("org", "Organization management");
-}
+    {
+        var cmd = new Command("org", "Organization management");
+        cmd.Aliases.Add("organization");
+        return cmd;
+    }
+}

src/Cli/Commands/Profiles/Workspaces/WorkCommand.cs

@@ -41,5 +41,9 @@ internal class WorkCommand : ICliCommand
     /// </summary>
     /// <returns>Configured <see cref="Command"/> for workspace subcommands.</returns>
     public Command Build()
-        => new("workspace", "Workspace management");
-}
+    {
+        var cmd = new Command("workspace", "Workspace management");
+        cmd.Aliases.Add("ws");
+        return cmd;
+    }
+}

src/Cli/Commands/Profiles/Workspaces/WorkCurrentCommand.cs

@@ -0,0 +1,23 @@
+using System.CommandLine;
+using ChangeTrace.Cli.Handlers.Profiles.Workspaces;
+using ChangeTrace.Cli.Interfaces;
+using ChangeTrace.Configuration.Discovery;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ChangeTrace.Cli.Commands.Profiles.Workspaces;
+
+[AutoRegister(ServiceLifetime.Singleton)]
+internal sealed class WorkCurrentCommand : ICliCommand
+{
+    public Type HandlerType => typeof(WorkCurrentCommandHandler);
+
+    public Type Parent => typeof(WorkCommand);
+
+    public Command Build()
+    {
+        var cmd = new Command("current", "Show active workspace");
+        cmd.Aliases.Add("status");
+        cmd.Aliases.Add("ctx");
+        return cmd;
+    }
+}

src/Cli/Commands/Profiles/Workspaces/WorkListCommand.cs

@@ -35,9 +35,13 @@ internal sealed class WorkListCommand : ICliCommand
     /// Builds <see cref="Command"/> representing <c>workspace list</c> command.
     /// </summary>
     /// <returns>Configured <see cref="Command"/> with optional filtering options.</returns>
-    public Command Build() =>
-        new("list", "List workspaces")
+    public Command Build()
+    {
+        var cmd = new Command("list", "List workspaces")
         {
-            new Option<string>("--org") { Description = "Organization name" }
+            new Option<string?>("--org", "-o") { Description = "Organization name. When omitted, all workspaces are listed." }
         };
-}
+        cmd.Aliases.Add("ls");
+        return cmd;
+    }
+}

src/Cli/Commands/Profiles/Workspaces/WorkPlayCommand.cs

@@ -0,0 +1,32 @@
+using System.CommandLine;
+using ChangeTrace.Cli.Handlers.Profiles.Workspaces;
+using ChangeTrace.Cli.Interfaces;
+using ChangeTrace.Configuration.Discovery;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ChangeTrace.Cli.Commands.Profiles.Workspaces;
+
+[AutoRegister(ServiceLifetime.Singleton)]
+internal sealed class WorkPlayCommand : ICliCommand
+{
+    public Type HandlerType => typeof(WorkPlayCommandHandler);
+
+    public Type Parent => typeof(WorkCommand);
+
+    public Command Build()
+        => new("play", "Play a timeline from the active workspace")
+        {
+            new Option<string?>("--repo", "-r")
+            {
+                Description = "Repository filter, for example microsoft/msquic or msquic. Defaults to the newest timeline."
+            },
+            new Option<bool>("--select", "-s")
+            {
+                Description = "Prompt for timeline selection instead of opening the newest match."
+            },
+            new Option<bool>("--workspace", "-w")
+            {
+                Description = "Prompt for workspace before playing."
+            }
+        };
+}

src/Cli/Commands/Profiles/Workspaces/WorkTimelinesCommand.cs

@@ -0,0 +1,23 @@
+using System.CommandLine;
+using ChangeTrace.Cli.Handlers.Profiles.Workspaces;
+using ChangeTrace.Cli.Interfaces;
+using ChangeTrace.Configuration.Discovery;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace ChangeTrace.Cli.Commands.Profiles.Workspaces;
+
+[AutoRegister(ServiceLifetime.Singleton)]
+internal sealed class WorkTimelinesCommand : ICliCommand
+{
+    public Type HandlerType => typeof(WorkTimelinesCommandHandler);
+
+    public Type Parent => typeof(WorkCommand);
+
+    public Command Build()
+    {
+        var cmd = new Command("timelines", "List timeline files stored for the active workspace");
+        cmd.Aliases.Add("timeline");
+        cmd.Aliases.Add("tl");
+        return cmd;
+    }
+}

src/Cli/Commands/Profiles/Workspaces/WorkUseCommand.cs

@@ -14,8 +14,8 @@ namespace ChangeTrace.Cli.Commands.Profiles.Workspaces;
 /// <list type="bullet">
 /// <item>Child command of <see cref="WorkCommand"/>.</item>
 /// <item>Delegates execution to <see cref="WorkUseCommandHandler"/>.</item>
-/// <item>Requires workspace name argument.</item>
-/// <item>Optionally specifies the organization using <c>--org</c> option.</item>
+/// <item>Accepts optional organization and workspace arguments.</item>
+/// <item>Prompts for missing values in interactive terminals.</item>
 /// <item>Registered automatically as singleton via <see cref="AutoRegisterAttribute"/>.</item>
 /// </list>
 /// </remarks>
@@ -36,9 +36,22 @@ internal sealed class WorkUseCommand : ICliCommand
     /// Builds the <see cref="Command"/> instance representing the <c>workspace use</c> command.
     /// </summary>
     /// <returns>A configured <see cref="Command"/> with required arguments and optional organization filter.</returns>
-    public Command Build() => new("use", "Select workspace to play")
+    public Command Build()
     {
-        new Argument<string>("org") { Description = "Organization name" },
-        new Argument<string>("name") { Description = "Workspace name" }
-    };
-}
+        var cmd = new Command("use", "Select active workspace");
+        cmd.Aliases.Add("switch");
+        cmd.Aliases.Add("select");
+        cmd.Arguments.Add(new Argument<string?>("org")
+        {
+            Description = "Organization name",
+            Arity = ArgumentArity.ZeroOrOne
+        });
+        cmd.Arguments.Add(new Argument<string?>("name")
+        {
+            Description = "Workspace name",
+            Arity = ArgumentArity.ZeroOrOne
+        });
+
+        return cmd;
+    }
+}

src/Cli/Commands/ShowTimelineCommand.cs

@@ -1,7 +1,6 @@
 using System.CommandLine;
 using ChangeTrace.Cli.Handlers;
 using ChangeTrace.Cli.Interfaces;
-using ChangeTrace.Configuration;
 using ChangeTrace.Configuration.Discovery;
 using Microsoft.Extensions.DependencyInjection;
 
@@ -27,7 +26,7 @@ internal sealed class ShowTimelineCommand : ICliCommand
     public Type HandlerType => typeof(ShowTimelineCommandHandler);
 
     public Type? Parent => null;
-    
+
     /// <summary>
     /// Builds the <see cref="Command"/> instance representing the 'show' CLI command.
     /// </summary>
@@ -40,4 +39,4 @@ public Command Build()
         cmd.Arguments.Add(fileArg);
         return cmd;
     }
-}
+}

src/Cli/Handlers/ExportCommandHandler.cs

@@ -12,34 +12,46 @@
 namespace ChangeTrace.Cli.Handlers;
 
 /// <summary>
-/// CLI handler responsible for exporting a Git repository into a ChangeTrace timeline file.
+/// Exports Git repository into ChangeTrace timeline file.
 /// </summary>
-/// <remarks>
-/// <list type="bullet">
-/// <item>Resolves authentication token from CLI option or stored session.</item>
-/// <item>Detects repository provider automatically.</item>
-/// <item>Invokes <see cref="IRepositoryExporter"/> to perform export pipeline.</item>
-/// <item>Displays progress and result using Spectre.Console UI.</item>
-/// </list>
-/// </remarks>
 [AutoRegister(ServiceLifetime.Transient, typeof(ExportCommandHandler))]
 internal sealed class ExportCommandHandler(
     IAuthService sessionAuthStore,
+    IWorkspaceContext workspaceContext,
+    IWorkspaceTimelineStorage workspaceTimelineStorage,
     IRepositoryExporter exporter) : ICliHandler
 {
     /// <summary>
-    /// Executes the export command.
+    /// Runs the repository export command.
     /// </summary>
-    /// <param name="parseResult">Parsed CLI arguments.</param>
-    /// <param name="ct">Cancellation token.</param>
-    /// <returns>Task representing asynchronous command execution.</returns>
     public async Task HandleAsync(ParseResult parseResult, CancellationToken ct)
     {
         var repo = parseResult.GetValue<string>("repository")!;
-        var output = parseResult.GetValue<string>("--output")!;
+        var explicitOutput = parseResult.GetValue<string?>("--output");
         var token = parseResult.GetValue<string?>("--token");
         var verbose = parseResult.GetValue<bool>("--verbose");
-        
+        var exportedAt = DateTimeOffset.UtcNow;
+
+        var output = explicitOutput;
+        var workspace = workspaceContext.Current;
+
+        if (string.IsNullOrWhiteSpace(output))
+        {
+            if (workspace == null)
+            {
+                AnsiConsole.MarkupLine(
+                    "[red]Failed:[/] no active workspace selected. Use [yellow]workspace use <org> <name>[/] or pass [yellow]--output/-o[/].");
+                return;
+            }
+
+            output = await workspaceTimelineStorage.CreateTimelinePathAsync(
+                workspace,
+                repo,
+                exportedAt,
+                Ulid.NewUlid().ToString(),
+                ct);
+        }
+
         if (string.IsNullOrWhiteSpace(token))
         {
             var provider = ProviderUrlHelper.DetectProvider(repo);
@@ -71,8 +83,15 @@ public async Task HandleAsync(ParseResult parseResult, CancellationToken ct)
                 return await exporter.ExportAndSaveAsync(repo, output, options, progress, ct);
             });
 
-        AnsiConsole.MarkupLine(result.IsSuccess
-            ? $"[green]Exported successfully to {output}[/]"
-            : $"[red]Failed: {result.Error}[/]");
+        if (result.IsFailure)
+        {
+            AnsiConsole.MarkupLine($"[red]Failed:[/] {Markup.Escape(result.Error ?? "Unknown error")}");
+            return;
+        }
+
+        if (string.IsNullOrWhiteSpace(explicitOutput) && workspace != null)
+            await workspaceTimelineStorage.SaveMetadataAsync(output, workspace, repo, exportedAt, ct);
+
+        AnsiConsole.MarkupLine($"[green]Exported successfully to[/] {Markup.Escape(output)}");
     }
 }