ace-handbook 0.19.0

data/handbook/guides/cli-dry-cli.g.md

@@ -0,0 +1,276 @@
+---
+doc-type: guide
+title: dry-cli CLI Framework Guide
+purpose: Documentation for ace-handbook/handbook/guides/cli-dry-cli.g.md
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# dry-cli CLI Framework Guide
+
+Complete reference for implementing CLI interfaces in ace-* gems using dry-cli.
+
+## Overview
+
+All ACE CLI gems use dry-cli. See [ADR-023](../../../docs/decisions/ADR-023-dry-cli-framework.md) for decision rationale.
+
+**Two patterns:**
+- **Multi-command**: Subcommand tools (ace-bundle, ace-taskflow)
+- **Single-command**: One-action tools (ace-git-commit, ace-search)
+
+## Multi-Command Pattern
+
+For CLIs with subcommands, use the Registry pattern with `HelpCommand.build()`:
+
+```ruby
+# lib/ace/gem/cli.rb
+require "dry/cli"
+require "ace/core"
+require_relative "cli/commands/process"
+require_relative "cli/commands/status"
+
+module Ace::Gem
+  module CLI
+    extend Dry::CLI::Registry
+
+    PROGRAM_NAME = 'ace-gem'
+
+    # Commands with descriptions for help output
+    REGISTERED_COMMANDS = [
+      ['process', 'Process files with auto-detection'],
+      ['status',  'Show current status']
+    ].freeze
+
+    HELP_EXAMPLES = [
+      'ace-gem process file.txt',
+      'ace-gem status --verbose'
+    ].freeze
+
+    register 'process', Commands::Process.new
+    register 'status', Commands::Status.new
+
+    # Version command
+    version_cmd = Ace::Core::CLI::DryCli::VersionCommand.build(
+      gem_name: 'ace-gem',
+      version: Ace::Gem::VERSION
+    )
+    register 'version', version_cmd
+    register '--version', version_cmd
+
+    # Help command (standard pattern)
+    help_cmd = Ace::Core::CLI::DryCli::HelpCommand.build(
+      program_name: PROGRAM_NAME,
+      version: Ace::Gem::VERSION,
+      commands: REGISTERED_COMMANDS,
+      examples: HELP_EXAMPLES
+    )
+    register 'help', help_cmd
+    register '--help', help_cmd
+    register '-h', help_cmd
+  end
+end
+```
+
+**Exe wrapper:**
+```ruby
+#!/usr/bin/env ruby
+require "ace/gem"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+begin
+  Dry::CLI.new(Ace::Gem::CLI).call(arguments: args)
+rescue Ace::Core::CLI::Error => e
+  warn e.message
+  exit(e.exit_code)
+end
+```
+
+## Single-Command Pattern
+
+For CLIs with one primary action, skip the registry:
+
+```ruby
+# lib/ace/gem/cli/commands/search.rb
+module Ace::Gem
+  module CLI
+    module Commands
+      class Search < Dry::CLI::Command
+        include Ace::Core::CLI::DryCli::Base
+
+        desc "Search files and content"
+        argument :pattern, required: false
+        option :files, type: :boolean, aliases: ["-f"]
+
+        def call(pattern: nil, **options)
+          # ... implementation
+        end
+      end
+    end
+  end
+end
+```
+
+**Exe wrapper:**
+```ruby
+#!/usr/bin/env ruby
+require "ace/gem"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+begin
+  Dry::CLI.new(Ace::Gem::CLI::Commands::Search).call(arguments: args)
+rescue Ace::Core::CLI::Error => e
+  warn e.message
+  exit(e.exit_code)
+end
+```
+
+## Command Class Pattern
+
+Commands use `CLI::Commands::` namespace (Hanami pattern):
+
+```ruby
+# lib/ace/gem/cli/commands/process.rb
+module Ace::Gem
+  module CLI
+    module Commands
+      class Process < Dry::CLI::Command
+        include Ace::Core::CLI::DryCli::Base
+
+        desc "Process file with auto-detection"
+
+        argument :file, required: false, desc: "File to process"
+        option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+        option :verbose, type: :boolean, aliases: %w[-v], desc: "Verbose output"
+        option :debug, type: :boolean, aliases: %w[-d], desc: "Debug output"
+
+        def call(file: nil, **options)
+          ProcessCommand.new(file, options).execute
+        end
+      end
+    end
+  end
+end
+```
+
+**Directory structure**: `lib/ace/gem/cli/commands/` (not `lib/ace/gem/commands/`)
+
+## Nested Commands
+
+For hierarchical commands (ace-taskflow, ace-git-worktree):
+
+```ruby
+# lib/ace/taskflow/cli.rb
+module Ace::Taskflow
+  module CLI
+    extend Dry::CLI::Registry
+
+    # Hierarchical registration with space-separated names
+    register "task show", Commands::Task::Show
+    register "task list", Commands::Task::List
+    register "release bump", Commands::Release::Bump
+
+    # Help and version
+    help_cmd = Ace::Core::CLI::DryCli::HelpCommand.build(...)
+    register "help", help_cmd
+    register "--help", help_cmd
+    register "-h", help_cmd
+  end
+end
+
+# Directory structure:
+# lib/ace/taskflow/cli/commands/task/show.rb
+# lib/ace/taskflow/cli/commands/task/list.rb
+# lib/ace/taskflow/cli/commands/release/bump.rb
+```
+
+## Type Conversion
+
+dry-cli returns strings for all options. Use the `convert_types` helper:
+
+```ruby
+# Single option
+opts = convert_types(options, timeout: :integer)
+
+# Multiple options
+opts = convert_types(options, limit: :integer, ratio: :float)
+```
+
+## Help Documentation
+
+Use `desc` with heredoc and `example` array:
+
+```ruby
+desc <<~DESC.strip
+  Main description here.
+
+  Additional context:
+    - Point one
+    - Point two
+DESC
+
+example ['pattern --flag', '"*.rb" -f']
+```
+
+## Exit Code Handling
+
+**IMPORTANT**: dry-cli's `call()` method returns `nil`, NOT command return values. Use exception-based exit codes:
+
+```ruby
+# In command - raise exception for non-zero exit
+def call(file: nil, **options)
+  raise Ace::Core::CLI::Error.new("file required") if file.nil?
+
+  result = do_work(file)
+  raise Ace::Core::CLI::Error.new(result[:error]) unless result[:success]
+
+  puts result[:message]
+  # Success - no exception, exits 0
+end
+```
+
+**Exe wrapper catches exceptions:**
+```ruby
+#!/usr/bin/env ruby
+require "ace/gem"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+begin
+  Dry::CLI.new(Ace::Gem::CLI).call(arguments: args)
+rescue Ace::Core::CLI::Error => e
+  warn e.message
+  exit(e.exit_code)
+rescue Interrupt
+  warn "\nInterrupted"
+  exit(130)
+end
+```
+
+**Exit Code Values:**
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General failure |
+| 2 | Invalid arguments |
+| 130 | SIGINT (Ctrl+C) |
+
+See [ADR-023](../../../docs/decisions/ADR-023-dry-cli-framework.md) for full exit code documentation.
+
+## Reserved Short Flags
+
+| Flag | Meaning | Notes |
+|------|---------|-------|
+| `-h` | help | dry-cli default |
+| `-v` | verbose | NOT version |
+| `-q` | quiet | Suppress output |
+| `-d` | debug | Debug output |
+| `-o` | output | Output destination |
+
+## Related
+
+- [ADR-023](../../../docs/decisions/ADR-023-dry-cli-framework.md) - Decision record
+- [ace-gems.g.md](../../../docs/ace-gems.g.md) - Gem development overview
+- Task 179 - Migration details

data/handbook/guides/cli-support-cli.g.md

@@ -0,0 +1,277 @@
+---
+doc-type: guide
+title: ace-support-cli CLI Framework Guide
+purpose: Documentation for ace-handbook/handbook/guides/cli-support-cli.g.md
+ace-docs:
+  last-updated: 2026-03-18
+  last-checked: 2026-03-21
+---
+
+# ace-support-cli CLI Framework Guide
+
+Complete reference for implementing CLI interfaces in ace-* gems using ace-support-cli.
+
+## Overview
+
+All ACE CLI gems use ace-support-cli. See [ADR-023](../../../docs/decisions/ADR-023-ace-support-cli-framework.md) for decision rationale.
+
+**Two patterns:**
+- **Multi-command**: Subcommand tools (ace-bundle, ace-taskflow)
+- **Single-command**: One-action tools (ace-git-commit, ace-search)
+
+## Multi-Command Pattern
+
+For CLIs with subcommands, use the Registry pattern with `HelpCommand.build()`:
+
+```ruby
+# lib/ace/gem/cli.rb
+require "ace/support/cli"
+require "ace/core"
+require_relative "cli/commands/process"
+require_relative "cli/commands/status"
+
+module Ace::Gem
+  module CLI
+    extend Ace::Core::CLI::RegistryDsl
+
+    PROGRAM_NAME = 'ace-gem'
+
+    # Commands with descriptions for help output
+    REGISTERED_COMMANDS = [
+      ['process', 'Process files with auto-detection'],
+      ['status',  'Show current status']
+    ].freeze
+
+    HELP_EXAMPLES = [
+      'ace-gem process file.txt',
+      'ace-gem status --verbose'
+    ].freeze
+
+    register 'process', Commands::Process
+    register 'status', Commands::Status
+
+    # Version command
+    version_cmd = Ace::Core::CLI::VersionCommand.build(
+      gem_name: 'ace-gem',
+      version: Ace::Gem::VERSION
+    )
+    register 'version', version_cmd
+    register '--version', version_cmd
+
+    # Help command (standard pattern)
+    help_cmd = Ace::Core::CLI::HelpCommand.build(
+      program_name: PROGRAM_NAME,
+      version: Ace::Gem::VERSION,
+      commands: REGISTERED_COMMANDS,
+      examples: HELP_EXAMPLES
+    )
+    register 'help', help_cmd
+    register '--help', help_cmd
+    register '-h', help_cmd
+  end
+end
+```
+
+**Exe wrapper:**
+```ruby
+#!/usr/bin/env ruby
+require "ace/gem"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+begin
+  Ace::Support::Cli::Runner.new(Ace::Gem::CLI).call(args: args)
+rescue Ace::Core::CLI::Error => e
+  warn e.message
+  exit(e.exit_code)
+end
+```
+
+## Single-Command Pattern
+
+For CLIs with one primary action, skip the registry:
+
+```ruby
+# lib/ace/gem/cli/commands/search.rb
+module Ace::Gem
+  module CLI
+    module Commands
+      class Search < Ace::Support::Cli::Command
+        include Ace::Core::CLI::Base
+
+        desc "Search files and content"
+        argument :pattern, required: false
+        option :files, type: :boolean, aliases: ["-f"]
+
+        def call(pattern: nil, **options)
+          # ... implementation
+        end
+      end
+    end
+  end
+end
+```
+
+**Exe wrapper:**
+```ruby
+#!/usr/bin/env ruby
+require "ace/gem"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+begin
+  Ace::Support::Cli::Runner.new(Ace::Gem::CLI::Commands::Search).call(args: args)
+rescue Ace::Core::CLI::Error => e
+  warn e.message
+  exit(e.exit_code)
+end
+```
+
+## Command Class Pattern
+
+Commands use `CLI::Commands::` namespace (Hanami pattern):
+
+```ruby
+# lib/ace/gem/cli/commands/process.rb
+module Ace::Gem
+  module CLI
+    module Commands
+      class Process < Ace::Support::Cli::Command
+        include Ace::Core::CLI::Base
+
+        desc "Process file with auto-detection"
+
+        argument :file, required: false, desc: "File to process"
+        option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+        option :verbose, type: :boolean, aliases: %w[-v], desc: "Verbose output"
+        option :debug, type: :boolean, aliases: %w[-d], desc: "Debug output"
+
+        def call(file: nil, **options)
+          ProcessCommand.new(file, options).execute
+        end
+      end
+    end
+  end
+end
+```
+
+**Directory structure**: `lib/ace/gem/cli/commands/` (not `lib/ace/gem/commands/`)
+
+## Nested Commands
+
+For hierarchical commands (ace-taskflow, ace-git-worktree):
+
+```ruby
+# lib/ace/taskflow/cli.rb
+module Ace::Taskflow
+  module CLI
+    extend Ace::Core::CLI::RegistryDsl
+
+    # Hierarchical registration with space-separated names
+    register "task show", Commands::Task::Show
+    register "task list", Commands::Task::List
+    register "release bump", Commands::Release::Bump
+
+    # Help and version
+    help_cmd = Ace::Core::CLI::HelpCommand.build(...)
+    register "help", help_cmd
+    register "--help", help_cmd
+    register "-h", help_cmd
+  end
+end
+
+# Directory structure:
+# lib/ace/taskflow/cli/commands/task/show.rb
+# lib/ace/taskflow/cli/commands/task/list.rb
+# lib/ace/taskflow/cli/commands/release/bump.rb
+```
+
+## Type Conversion
+
+Use the `coerce_types` helper from `Ace::Core::CLI::Base` when you need to coerce values manually:
+
+```ruby
+# Single option
+opts = coerce_types(options, timeout: :integer)
+
+# Multiple options
+opts = coerce_types(options, limit: :integer, ratio: :float)
+```
+
+## Help Documentation
+
+Use `desc` with heredoc and `example` array:
+
+```ruby
+desc <<~DESC.strip
+  Main description here.
+
+  Additional context:
+    - Point one
+    - Point two
+DESC
+
+example ['pattern --flag', '"*.rb" -f']
+```
+
+## Exit Code Handling
+
+**IMPORTANT**: `Ace::Support::Cli::Runner#call()` returns the command result, but normalizes `nil` to exit code `0`. Use exception-based exit codes for failures:
+
+```ruby
+# In command - raise exception for non-zero exit
+def call(file: nil, **options)
+  raise Ace::Core::CLI::Error.new("file required") if file.nil?
+
+  result = do_work(file)
+  raise Ace::Core::CLI::Error.new(result[:error]) unless result[:success]
+
+  puts result[:message]
+  # Success - no exception, exits 0
+end
+```
+
+**Exe wrapper catches exceptions:**
+```ruby
+#!/usr/bin/env ruby
+require "ace/gem"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+begin
+  exit_code = Ace::Support::Cli::Runner.new(Ace::Gem::CLI).call(args: args)
+  exit(exit_code) if exit_code.is_a?(Integer) && exit_code != 0
+rescue Ace::Core::CLI::Error => e
+  warn e.message
+  exit(e.exit_code)
+rescue Interrupt
+  warn "\nInterrupted"
+  exit(130)
+end
+```
+
+**Exit Code Values:**
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General failure |
+| 2 | Invalid arguments |
+| 130 | SIGINT (Ctrl+C) |
+
+See [ADR-023](../../../docs/decisions/ADR-023-ace-support-cli-framework.md) for full exit code documentation.
+
+## Reserved Short Flags
+
+| Flag | Meaning | Notes |
+|------|---------|-------|
+| `-h` | help | ace-support-cli default |
+| `-v` | verbose | NOT version |
+| `-q` | quiet | Suppress output |
+| `-d` | debug | Debug output |
+| `-o` | output | Output destination |
+
+## Related
+
+- [ADR-023](../../../docs/decisions/ADR-023-ace-support-cli-framework.md) - Decision record
+- [ace-gems.g.md](../../../docs/ace-gems.g.md) - Gem development overview
+- Task 179 - Migration details

data/handbook/guides/coding-standards/ruby.md

@@ -0,0 +1,41 @@
+# Ruby Coding Standards
+
+This sub-guide captures conventions and idioms specific to Ruby development in this project. Follow these in
+addition to the generic standards in `../coding-standards.md`.
+
+## Idioms & Best Practices
+
+- Follow the community Ruby Style Guide (<https://rubystyle.guide/>) unless overridden here.
+- Prefer blocks and `yield` for configurability and iteration when appropriate.
+- Use metaprogramming judiciously; prioritize clarity over cleverness.
+- Leverage standard library features instead of reinventing the wheel.
+
+## Formatting
+
+- Indentation: 2 spaces (no tabs).
+- Line length: 100 characters max.
+- Use `standardrb` or `rubocop -A` to auto-correct formatting issues.
+
+## Error Handling
+
+- Derive custom errors from `Aira::Error` base class.
+- Include contextual data (e.g., `user_id`, `task_id`) when raising.
+
+## Testing Conventions
+
+- Use RSpec with the directory layout defined in `guide://testing` (Ruby/RSpec section).
+- Tag specs (`:unit`, `:integration`, `:e2e`) per the testing guide.
+
+## File Organization
+
+- Mirror production code structure under `spec/`.
+- Group concerns into modules; avoid deep inheritance trees.
+
+## Performance Tips
+
+- Prefer `each` over `map` when you don’t need the new array.
+- Avoid creating unnecessary objects in hot code paths.
+
+---
+
+Refer back to the main coding standards guide for cross-language principles.

data/handbook/guides/coding-standards/rust.md

@@ -0,0 +1,19 @@
+# Rust Coding Standards
+
+> This page is a language-specific companion to [../coding-standards.g.md](../coding-standards.g.md)
+
+## Formatting & Style
+
+- (Add Rust-specific formatting rules, e.g., `rustfmt` usage)
+
+## Naming Conventions
+
+- (Add Rust-specific naming conventions following Rust API guidelines)
+
+## Best Practices
+
+- (Add Rust-specific best practices, e.g., ownership, lifetimes, error handling with `Result`)
+
+## Tooling
+
+- (Mention relevant Rust linters like `clippy`, formatters like `rustfmt`)

data/handbook/guides/coding-standards/typescript.md

@@ -0,0 +1,20 @@
+
+# TypeScript Coding Standards
+
+> This page is a language-specific companion to [../coding-standards.g.md](../coding-standards.g.md)
+
+## Formatting & Style
+
+- (Add TypeScript-specific formatting rules, e.g., Prettier config, ESLint rules)
+
+## Naming Conventions
+
+- (Add TypeScript-specific naming conventions for variables, functions, classes, etc.)
+
+## Best Practices
+
+- (Add TypeScript-specific best practices, e.g., type safety, module usage)
+
+## Tooling
+
+- (Mention relevant TypeScript linters, formatters, etc.)