Fixed column ordering in Owl tables

Author: matthewsinclair

intent/st/ST0008/design.md intent/st/COMPLETED/ST0008/design.mdintent/st/ST0008/design.md renamed to intent/st/COMPLETED/ST0008/design.md

@@ -1,9 +1,9 @@
 ---
 verblock: "22 Sep 2025:v0.1: Matthew Sinclair - Initial version"
 intent_version: 2.2.0
-status: WIP
+status: Completed
 created: 20250922
-completed: 
+completed: 20251006
 ---
 # ST0008: Orthogonalised formatting and outputting
 

intent/st/ST0008/done.md intent/st/COMPLETED/ST0008/done.mdintent/st/ST0008/done.md renamed to intent/st/COMPLETED/ST0008/done.md

@@ -39,6 +39,6 @@ This document provides an overview of all steel threads in the project. It helps
 4. Use this document to quickly locate specific steel thread documents
 
 The detailed information for each steel thread is contained in its individual document (e.g., ST0001.md).
-| ST0008 | Orthogonalised formatting and outputting | WIP | 2025-09-22 |  |
+| ST0008 | Orthogonalised formatting and outputting | Completed |  | 2025-10-06 |
 | ST0009 | 8 | Not Started | 2025-09-22 |  |
 | ST0003 | REPL Output Callback System | Completed |  | 2025-09-22 |

intent/st/ST0008/impl.md intent/st/COMPLETED/ST0008/impl.mdintent/st/ST0008/impl.md renamed to intent/st/COMPLETED/ST0008/impl.md

@@ -91,13 +91,56 @@ arca_cli --help
 
 Configure Arca.Cli behavior using these environment variables:
 
+#### Configuration Variables
+
 | Variable                     | Purpose                           | Default                           |
 |------------------------------|-----------------------------------|-----------------------------------|
 | APP_NAME_CONFIG_PATH         | Configuration directory path      | .app_name/ (e.g., .arca_cli/)     |
 | APP_NAME_CONFIG_FILE         | Configuration filename            | config.json                       |
 
 Note: The actual environment variable names are derived from the application name (in UPPERCASE). For example, for the `arca_cli` application, the environment variables would be `ARCA_CLI_CONFIG_PATH` and `ARCA_CLI_CONFIG_FILE`.
 
+#### Output Style Variables
+
+| Variable                     | Purpose                           | Values                            | Default    |
+|------------------------------|-----------------------------------|-----------------------------------|------------|
+| ARCA_STYLE                   | Force specific output style       | ansi, plain, json, dump           | auto       |
+| NO_COLOR                     | Disable colored output            | 1 (to disable), unset (to enable) | unset      |
+| MIX_ENV                      | Elixir environment                | test, dev, prod                   | dev        |
+
+**Output Style Behavior:**
+
+- `ARCA_STYLE=ansi`: Force colored ANSI output with symbols and formatting
+- `ARCA_STYLE=plain`: Force plain text output without ANSI codes
+- `ARCA_STYLE=json`: Output structured JSON for programmatic consumption
+- `ARCA_STYLE=dump`: Output raw data structures for debugging
+- `NO_COLOR=1`: Disable colors (equivalent to `ARCA_STYLE=plain`)
+- `MIX_ENV=test`: Automatically uses plain style for test output
+
+**Style Detection Priority:**
+
+1. Test environment (`MIX_ENV=test`) → Plain style
+2. `NO_COLOR=1` → Plain style
+3. `ARCA_STYLE` value → Specified style
+4. Non-TTY environment → Plain style
+5. Interactive TTY → ANSI style (default)
+
+**Usage Examples:**
+
+```bash
+# Force plain output for scripting
+ARCA_STYLE=plain arca_cli command > output.txt
+
+# Disable colors for CI/CD pipelines
+NO_COLOR=1 arca_cli command
+
+# Get JSON for parsing
+ARCA_STYLE=json arca_cli command | jq '.output'
+
+# Debug with raw data structures
+ARCA_STYLE=dump arca_cli command
+```
+
 Example configuration in `.bashrc` or `.zshrc` for an application named `arca_cli`:
 
 ```bash

intent/st/ST0008/info.md intent/st/COMPLETED/ST0008/info.mdintent/st/ST0008/info.md renamed to intent/st/COMPLETED/ST0008/info.md

@@ -189,6 +189,191 @@ arca_cli dev.deps
 
 ## API Reference
 
+### Context Module (`Arca.Cli.Ctx`)
+
+The Context module provides a structured way to build command output.
+
+#### Context Structure
+
+```elixir
+%Arca.Cli.Ctx{
+  command: atom(),      # Command being executed
+  args: map(),          # Parsed arguments
+  options: map(),       # Command options
+  output: list(),       # Structured output items
+  errors: list(),       # Error messages
+  status: atom(),       # :ok | :error | :warning | :pending
+  cargo: map(),         # Command-specific data
+  meta: map()           # Style, format, and other metadata
+}
+```
+
+#### Core Functions
+
+**`Ctx.new(command, settings)`**
+
+Creates a new context for a command.
+
+```elixir
+ctx = Ctx.new(:my_command, settings)
+```
+
+**`Ctx.add_output(ctx, output_item)`**
+
+Adds an output item to the context.
+
+```elixir
+ctx = Ctx.add_output(ctx, {:success, "Operation completed"})
+```
+
+**`Ctx.add_error(ctx, error_message)`**
+
+Adds an error message to the context.
+
+```elixir
+ctx = Ctx.add_error(ctx, "File not found")
+```
+
+**`Ctx.complete(ctx, status)`**
+
+Marks the context as complete with a final status.
+
+```elixir
+ctx = Ctx.complete(ctx, :ok)  # or :error, :warning
+```
+
+**`Ctx.put_cargo(ctx, key, value)`** / **`Ctx.get_cargo(ctx, key)`**
+
+Stores and retrieves command-specific data.
+
+```elixir
+ctx = Ctx.put_cargo(ctx, :user_count, 42)
+count = Ctx.get_cargo(ctx, :user_count)
+```
+
+#### Output Item Types
+
+**Messages**
+
+```elixir
+{:success, message}  # Green checkmark in ANSI mode
+{:error, message}    # Red X in ANSI mode
+{:warning, message}  # Yellow warning symbol in ANSI mode
+{:info, message}     # Cyan info symbol in ANSI mode
+{:text, content}     # Plain text
+```
+
+**Tables**
+
+```elixir
+# With explicit headers (columns in header order)
+{:table, rows, headers: ["Name", "Age", "City"]}
+
+# Override column order
+{:table, rows,
+  headers: ["Name", "Age", "City"],
+  column_order: ["City", "Age", "Name"]
+}
+
+# First row as headers (preserves row order)
+{:table, [headers_row | data_rows], has_headers: true}
+
+# Alphabetical column order (default when no headers/column_order)
+{:table, rows, []}
+
+# Descending alphabetical
+{:table, rows, column_order: :desc}
+```
+
+**Table Options:**
+
+- `headers`: List of column header names (also sets column order)
+- `column_order`: Explicit column ordering (list, `:asc`, `:desc`, or custom function)
+- `has_headers`: Boolean, treats first row as headers
+- `border_style`: `:solid`, `:solid_rounded`, etc.
+- `divide_body_rows`: Boolean, add lines between rows
+- `padding_x`: Integer, horizontal padding in cells
+
+**Lists**
+
+```elixir
+# Simple list
+{:list, ["Item 1", "Item 2", "Item 3"]}
+
+# List with title
+{:list, items, title: "Available Options"}
+
+# List with custom bullet color (ANSI mode)
+{:list, items, bullet_color: :green}
+```
+
+**Interactive Elements (ANSI mode only)**
+
+```elixir
+# Spinner
+{:spinner, "Loading data", fn ->
+  result = perform_operation()
+  {:ok, result}
+end}
+
+# Progress indicator
+{:progress, "Processing files", fn ->
+  result = process_files()
+  {:ok, result}
+end}
+```
+
+### Output Module (`Arca.Cli.Output`)
+
+The Output module handles rendering of contexts to different formats.
+
+**`Output.render(ctx)`**
+
+Renders a context to a string using the appropriate style.
+
+```elixir
+output = Arca.Cli.Output.render(ctx)
+IO.puts(output)
+```
+
+**Style Detection**
+
+The output style is automatically determined:
+
+1. Plain style if `MIX_ENV=test`
+2. Plain style if `NO_COLOR=1`
+3. Style from `ARCA_STYLE` environment variable (ansi, plain, json, dump)
+4. Plain style if not a TTY
+5. ANSI style otherwise (default for interactive terminals)
+
+### Renderers
+
+**AnsiRenderer** - Colored output with formatting
+
+- Green checkmarks for success
+- Red X for errors
+- Yellow warnings
+- Cyan info messages
+- Rounded borders for tables
+- Colored bullet points for lists
+
+**PlainRenderer** - No ANSI codes
+
+- Simple symbols (✓, ✗, ⚠)
+- Box-drawing characters for tables
+- Plain bullet points for lists
+- Suitable for tests and non-TTY environments
+
+**JsonRenderer** - JSON structured output
+
+- Outputs context as JSON
+- Useful for programmatic consumption
+
+**DumpRenderer** - Raw data inspection
+
+- Shows internal structure
+- Useful for debugging
+
 ### Command Definition
 
 Commands are defined using the `Arca.Cli.Command.BaseCommand` module:
@@ -216,6 +401,58 @@ defmodule YourApp.Cli.Commands.GreetCommand do
 end
 ```
 
+### Context-Based Command Definition
+
+Commands can return structured output using the Context system:
+
+```elixir
+defmodule YourApp.Cli.Commands.UserCommand do
+  use Arca.Cli.Command.BaseCommand
+  alias Arca.Cli.Ctx
+
+  config :user,
+    name: "user",
+    about: "Display user information",
+    args: [
+      username: [
+        value_name: "USERNAME",
+        help: "Username to lookup",
+        required: true,
+        parser: :string
+      ]
+    ]
+
+  @impl true
+  def handle(args, settings, _optimus) do
+    username = args.args.username
+
+    Ctx.new(:user, settings)
+    |> fetch_user_data(username)
+    |> format_output()
+    |> Ctx.complete(:ok)
+  end
+
+  defp fetch_user_data(ctx, username) do
+    case Database.get_user(username) do
+      {:ok, user} ->
+        Ctx.put_cargo(ctx, :user, user)
+
+      {:error, reason} ->
+        ctx
+        |> Ctx.add_error("User not found: #{reason}")
+        |> Ctx.complete(:error)
+    end
+  end
+
+  defp format_output(%Ctx{status: :error} = ctx), do: ctx
+  defp format_output(%Ctx{cargo: %{user: user}} = ctx) do
+    ctx
+    |> Ctx.add_output({:success, "User found: #{user.name}"})
+    |> Ctx.add_output({:table, [user], headers: ["id", "name", "email", "created_at"]})
+  end
+end
+```
+
 ### Namespaced Command Definition
 
 Using the NamespaceCommandHelper for multiple related commands: