ST0008: orthogonalising output styling and formatting

Author: matthewsinclair

intent/st/ST0008/done.md

@@ -1,10 +1,10 @@
 # Completed Work - ST0008: Orthogonalised formatting and outputting
 
-## Progress: 20% Complete (2 of 10 work packages)
+## Progress: 40% Complete (4 of 10 work packages)
 
 ## Completed Work Packages
 
-### WP1: Context Module Foundation 
+### WP1: Context Module Foundation ✅
 
 **Completed**: 2025-09-22
 **Size**: S
@@ -31,7 +31,7 @@
 
 ---
 
-### WP2: Plain Renderer Implementation 
+### WP2: Plain Renderer Implementation ✅
 
 **Completed**: 2025-09-22
 **Size**: S
@@ -40,7 +40,7 @@
 
 - Created `lib/arca_cli/output/plain_renderer.ex`
 - Implemented message renderers for all semantic types:
-  - Success (), Error (), Warning (�), Info, Text
+  - Success (✓), Error (✗), Warning (⚠), Info, Text
 - Implemented table renderer using Owl with `:solid` border style
   - Automatic column width calculation
   - Header support with proper formatting
@@ -68,15 +68,100 @@
 
 ---
 
+### WP7: Global CLI Options
+
+**Completed**: 2025-09-22
+**Size**: S
+
+**Delivered**:
+
+- Added global `--cli-style` option with values: fancy, plain, dump
+- Added global `--cli-no-ansi` flag as alias for `--cli-style plain`
+- Implemented environment variable support:
+  - `NO_COLOR` sets style to plain
+  - `ARCA_STYLE` sets style to specified value
+- Established precedence order: CLI flags > CLI options > env vars > settings
+- Integrated style settings into command pipeline via `merge_style_settings/2`
+- Style automatically flows through to Context metadata
+- Prevented duplicate global options when multiple configurators are used
+
+**Files Modified**:
+
+- `lib/arca_cli/configurator/base_configurator.ex` - Added global options configuration
+- `lib/arca_cli/configurator/coordinator.ex` - Added single-point global option injection
+- `lib/arca_cli.ex` - Added merge_style_settings to pass style through pipeline
+
+**Files Created**:
+
+- `test/arca_cli/global_options_test.exs` - Comprehensive test suite (17 tests)
+
+**Key Implementation Notes**:
+
+- Used `--cli-` prefix to avoid conflicts with command-specific options
+- Global options added only once at Coordinator level to prevent duplicates
+- Environment variable handling includes proper precedence
+- Full test coverage including isolation of environment variables
+
+---
+
+### WP3: Fancy Renderer Implementation ✅
+
+**Completed**: 2025-09-22
+**Size**: M
+
+**Delivered**:
+
+- Created `lib/arca_cli/output/fancy_renderer.ex` with full color and symbol support
+- Implemented colored message renderers for all semantic types:
+  - Success (✓) with green color
+  - Error (✗) with red color
+  - Warning (⚠) with yellow color
+  - Info (ℹ) with cyan color
+- Implemented enhanced table renderer using Owl with `:solid_rounded` border style
+  - Smart cell colorization based on content (headers, numbers, keywords)
+  - Automatic conversion of list-of-lists format to maps for Owl compatibility
+- Implemented formatted lists with colored bullets
+  - Configurable bullet colors
+  - Optional titles with bright styling
+- Implemented spinner and progress display support
+  - Executes functions and shows results with appropriate coloring
+- Added automatic TTY detection and fallback to PlainRenderer
+  - Checks TERM environment variable
+  - Respects explicit style setting in context metadata
+- Refactored to use pure functional Elixir patterns:
+  - Pattern matching for render dispatch
+  - Function chaining instead of if/then conditionals
+  - Pipeline-based data transformations
+- Created comprehensive test suite with 24 tests
+- All tests passing (295 total in project)
+
+**Files Created**:
+
+- `lib/arca_cli/output/fancy_renderer.ex`
+- `test/arca_cli/output/fancy_renderer_test.exs`
+
+**Key Implementation Notes**:
+
+- Uses `:solid_rounded` border style for tables (not `:rounded` which doesn't exist in Owl)
+- Converts list-of-lists table format to maps for Owl compatibility
+- Smart cell colorization recognizes patterns (headers, numbers, success/error keywords)
+- TTY detection falls back gracefully to PlainRenderer when not in terminal
+- Follows pure functional patterns throughout with pattern matching and pipelines
+
+---
+
 ## Test Coverage
 
-- All tests passing (254 tests total in project)
+- All tests passing (295 tests total in project)
 - 100% coverage of implemented modules
 - Edge cases and error conditions fully tested
+- Environment variable isolation in tests
 
 ## Integration Status
 
 - Context module ready for integration with command execution
 - PlainRenderer ready for use via Output pipeline (WP4)
+- FancyRenderer ready for use via Output pipeline (WP4)
+- Global CLI options functional and tested
 - No breaking changes to existing code
-- Full backwards compatibility maintained
+- Full backwards compatibility maintained

intent/st/ST0008/tasks.md

@@ -2,36 +2,17 @@
 
 ## Progress Summary
 
-**Overall Status**: 20% Complete (2 of 10 work packages)
+**Overall Status**: 40% Complete (4 of 10 work packages)
 
-- ✅ Completed: WP1 (Context Module), WP2 (Plain Renderer) - See done.md
-- 🎯 Ready to Start: WP3 (Fancy Renderer), WP7 (Global Options)
+- ✅ Completed: WP1 (Context Module), WP2 (Plain Renderer), WP3 (Fancy Renderer), WP7 (Global Options) - See done.md
+- 🎯 Ready to Start: WP4 (Output Module Pipeline)
 - ⏸️ Blocked: WP4-WP6, WP8-WP10 (waiting on dependencies)
 
 ## Remaining Work Packages
 
-### WP3: Fancy Renderer Implementation
-
-**Status**: Ready to Start
-**Size**: M
-**Description**: Implement the fancy renderer with colors, symbols, and Owl formatting.
-
-**Tasks**:
-
-- [ ] Create `lib/arca_cli/output/fancy_renderer.ex`
-- [ ] Implement colored message renderers (success, error, warning, info)
-- [ ] Implement Owl.Table integration for `{:table, rows, opts}`
-- [ ] Implement formatted lists with colored bullets
-- [ ] Implement spinner support for `{:spinner, label, func}`
-- [ ] Handle non-TTY fallback to plain renderer
-- [ ] Add tests with Owl output verification
-- [ ] Document color scheme and symbols used
-
----
-
 ### WP4: Output Module Pipeline
 
-**Status**: Blocked (requires WP3)
+**Status**: Ready to Start
 **Size**: M
 **Description**: Create the main `Arca.Cli.Output` module that orchestrates the rendering pipeline.
 
@@ -160,18 +141,18 @@
 ## Dependencies Graph
 
 ```
-WP1 ✅ ──┬──> WP3 🎯 ──> WP4 ──┬──> WP5
+WP1 ✅ ──┬──> WP3 ✅ ──> WP4 🎯 ──┬──> WP5
         │                      ├──> WP6 ──┬──> WP8
 WP2 ✅ ──┘                      │          └──> WP9
                                └──> WP10
-WP7 🎯 (independent)
+WP7 ✅ (completed)
 ```
 
 ## Next Steps
 
-1. **Start WP3 (Fancy Renderer)** - Build on PlainRenderer pattern with colors and formatting
-2. **Start WP7 (Global Options)** - Can be done in parallel, no dependencies
-3. **Then WP4 (Output Pipeline)** - Once WP3 is complete, create the orchestration layer
+1. **Start WP4 (Output Module Pipeline)** - Create the main orchestration layer that uses the renderers
+2. **Then WP5 (Callback Integration)** - Register the new callback points
+3. **Then WP6 (Command Execution Integration)** - Update execute_command to handle Ctx returns
 
 ## Success Metrics
 

lib/arca_cli.ex

@@ -560,7 +560,9 @@ defmodule Arca.Cli do
   def handle_args(args, settings, optimus) do
     case args do
       {:ok, [subcmd], args} ->
-        handle_subcommand(subcmd, args, settings, optimus)
+        # Extract global CLI options and merge into settings
+        settings_with_style = merge_style_settings(args, settings)
+        handle_subcommand(subcmd, args, settings_with_style, optimus)
 
       {:ok, msg} when is_binary(msg) ->
         msg
@@ -738,6 +740,64 @@ defmodule Arca.Cli do
     end
   end
 
+  @doc """
+  Merges style-related settings from CLI options and environment variables.
+
+  Precedence order:
+  1. CLI flags (--cli-style, --cli-no-ansi)
+  2. Environment variables (NO_COLOR, ARCA_STYLE)
+  3. Existing settings
+
+  ## Parameters
+    - args: Parsed command arguments containing options and flags
+    - settings: Existing application settings
+
+  ## Returns
+    - Updated settings map with style preference
+  """
+  @spec merge_style_settings(map(), map()) :: map()
+  def merge_style_settings(args, settings) do
+    # Start with existing settings
+    settings
+    |> apply_env_style()
+    |> apply_cli_style(args)
+  end
+
+  # Apply style from environment variables
+  defp apply_env_style(settings) do
+    cond do
+      # NO_COLOR takes precedence over ARCA_STYLE
+      System.get_env("NO_COLOR") not in [nil, "", "0", "false"] ->
+        Map.put(settings, "style", "plain")
+
+      arca_style = System.get_env("ARCA_STYLE") ->
+        if arca_style in ["fancy", "plain", "dump"] do
+          Map.put(settings, "style", arca_style)
+        else
+          settings
+        end
+
+      true ->
+        settings
+    end
+  end
+
+  # Apply style from CLI options (highest precedence)
+  defp apply_cli_style(settings, args) do
+    cond do
+      # Check if --cli-no-ansi flag is set
+      Map.get(args, :flags, %{}) |> Map.get(:cli_no_ansi, false) ->
+        Map.put(settings, "style", "plain")
+
+      # Check if --cli-style option is set
+      cli_style = Map.get(args, :options, %{}) |> Map.get(:cli_style) ->
+        Map.put(settings, "style", Atom.to_string(cli_style))
+
+      true ->
+        settings
+    end
+  end
+
   @doc """
   Determines if help should be shown for a command with the given arguments.
 

lib/arca_cli/configurator/base_configurator.ex

@@ -140,6 +140,7 @@ defmodule Arca.Cli.Configurator.BaseConfigurator do
       @impl Arca.Cli.Configurator.ConfiguratorBehaviour
       def setup do
         create_base_config()
+        |> add_global_options()
         |> inject_subcommands()
         |> Optimus.new!()
       end
@@ -192,6 +193,33 @@ defmodule Arca.Cli.Configurator.BaseConfigurator do
         ]
       end
 
+      # Add global CLI options only once (will be called by setup/0 for single configurator)
+      def add_global_options(config) do
+        Keyword.merge(config,
+          options: [
+            cli_style: [
+              value_name: "STYLE",
+              long: "--cli-style",
+              help: "Set output style (fancy, plain, dump)",
+              required: false,
+              parser: fn s ->
+                case String.downcase(s) do
+                  style when style in ["fancy", "plain", "dump"] -> {:ok, String.to_atom(style)}
+                  _ -> {:error, "Invalid style. Must be one of: fancy, plain, dump"}
+                end
+              end
+            ]
+          ],
+          flags: [
+            cli_no_ansi: [
+              long: "--cli-no-ansi",
+              help: "Disable ANSI colors in output (same as --cli-style plain)",
+              multiple: false
+            ]
+          ]
+        )
+      end
+
       def inject_subcommands(optimus, commands \\ commands()) do
         # Process commands
         processed_commands =

lib/arca_cli/configurator/coordinator.ex

@@ -67,8 +67,11 @@ defmodule Arca.Cli.Configurator.Coordinator do
          {:ok, {combined_config, subcommand_names}} <- combine_configurator_data(unique_cfg8rs),
          :ok <- check_for_duplicated_commands(subcommand_names),
          {:ok, final_config} <- create_final_config(combined_config, unique_cfg8rs) do
+      # Add global options once at the coordinator level
+      final_config_with_options = add_global_cli_options(final_config)
+
       # Create the Optimus configuration
-      Optimus.new!(final_config)
+      Optimus.new!(final_config_with_options)
     else
       # Fallback to ensure we always return an Optimus configuration even if errors occurred
       {:error, _error_type, reason} ->
@@ -382,6 +385,47 @@ defmodule Arca.Cli.Configurator.Coordinator do
     end
   end
 
+  @doc """
+  Add global CLI options to the configuration.
+
+  These options are added at the coordinator level to ensure they're only added once,
+  even when multiple configurators are used.
+
+  ## Parameters
+    - config: Configuration keyword list
+
+  ## Returns
+    - Configuration with global options added
+  """
+  @spec add_global_cli_options(keyword()) :: keyword()
+  def add_global_cli_options(config) do
+    global_options = [
+      options: [
+        cli_style: [
+          value_name: "STYLE",
+          long: "--cli-style",
+          help: "Set output style (fancy, plain, dump)",
+          required: false,
+          parser: fn s ->
+            case String.downcase(s) do
+              style when style in ["fancy", "plain", "dump"] -> {:ok, String.to_atom(style)}
+              _ -> {:error, "Invalid style. Must be one of: fancy, plain, dump"}
+            end
+          end
+        ]
+      ],
+      flags: [
+        cli_no_ansi: [
+          long: "--cli-no-ansi",
+          help: "Disable ANSI colors in output (same as --cli-style plain)",
+          multiple: false
+        ]
+      ]
+    ]
+
+    Keyword.merge(config, global_options)
+  end
+
   @doc """
   Merges subcommands, with newer commands taking precedence.