ace-support-config 0.9.2 → 0.11.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 20f6ee6bfb7995646918fb15521f6dda200991c386457e5eec4bce45cb210ad1
-  data.tar.gz: 7acffaaac26242bf93809168b2adabb08af4e1b448faed0d5cb02c8dd0ab3ac4
+  metadata.gz: 33ca9302021e76335a714f27321b3075dd172056154ed5d1769b6f7b9ea7d6c7
+  data.tar.gz: e06462886d8d07fa3104367a96d129957b8554b8ac4419651f51c220dcd09167
 SHA512:
-  metadata.gz: 7a4116d64e58de732db67e2d7d3f9f38eeef23c94c3aa27697081f06db5b3aae6eb9baad2973bab1520489b24941a6bfac96abd36e9d8f63789f5afe48e2a3d9
-  data.tar.gz: f6c7667642fd4cd3d0e9f99795694f3c389c7bd6c86dbc3e762aab83287bd5fa04540a7c880b6a41306d66a2face1a0ef0d4d5699c8f1c8ebdb8f0bdb89e9395
+  metadata.gz: 5f6377fe1c334cdf394a619c0548966317167789dd3214c87d7cbef778fe069d7e059af7db77d53fcc86aeb0acb445ef4eb644cbfb29e1f2006f73f74aa671ef
+  data.tar.gz: d21e340eb555a7457aabcf55e7ea26120b54b9ed282f7227658810377274501e5fac8ce1b1d0519f8a9868330502a8d0dbae4e2b69afd8805f8b37ac033de699

data/CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-04-13
+
+### Fixed
+- Made bootstrap `.gitignore` detection line-aware so commented or negated `.ace-local/` mentions no longer suppress appending the real ignore rule.
+
+### Technical
+- Added regression coverage for commented and negated `.gitignore` mentions during bootstrap merges.
+
+## [0.11.1] - 2026-04-13
+
+### Fixed
+- Preserve existing `.gitignore` rules even when `ace-config init --force` refreshes bootstrap files.
+- Anchor project-root bootstrap files (`.gitignore`, `AGENTS.md`, `CLAUDE.md`) to the detected repository root so subdirectory runs do not seed them into the wrong location.
+
+## [0.11.0] - 2026-04-13
+
+### Changed
+- **ace-support-config v0.11.0**: Taught `ace-config init` to bootstrap project-root guidance files, include dotfile defaults, and append `.ace-local/` to existing `.gitignore` files without overwriting user-owned `AGENTS.md` or `CLAUDE.md`.
+
+## [0.10.4] - 2026-04-13
+
+### Changed
+- **ace-support-config v0.10.4**: Standardized shared package tests to the fast-only layout and updated testing flow defaults.
+
+
+## [0.10.3] - 2026-04-11
+
+### Technical
+- Migrated package tests to the `fast`/`feat` layout by moving deterministic ATOM coverage to `test/fast/` and former `test/integration/` suites to `test/feat/`.
+- Updated package docs to publish the `ace-test ace-support-config` (`fast`), `feat`, and `all` contract and keep package scope deterministic-only.
+
+## [0.10.2] - 2026-03-31
+
+### Technical
+- Added integration test coverage that stubs config template discovery in CLI flows to keep package tests deterministic across environments.
+
+## [0.10.1] - 2026-03-31
+
+### Fixed
+- Initialize project-root handling in RubyGems verify-install workflow usage paths to avoid brittle Gemfile resolution.
+- Remove Bundler runtime dependency from `ace-config` executable startup.
+- Wire `ConfigDiff` local/verbose behavior through CLI execution paths.
+
+### Technical
+- Added reset support for `ConfigTemplates` cache state and regression coverage for CLI/config diff behavior.
+
+## [0.10.0] - 2026-03-31
+
+### Added
+- Introduced `ace-config` CLI as the canonical config command with parity for `init`, `diff`, `list`, `version`, and `help`.
+- Added package executable `exe/ace-config` and repo wrapper `bin/ace-config`.
+
+### Changed
+- Migrated config CLI runtime to `Ace::Support::Config` with in-package modules for CLI dispatch, template discovery, initialization, and diff operations.
+- Updated package docs to present `ace-config` as the primary interface.
+
+### Technical
+- Added integration tests for `ace-config` CLI behavior and bootstrap/config initialization flows.
+
 ## [0.9.2] - 2026-03-29
 
 ### Technical

data/README.md

@@ -17,6 +17,30 @@
 [Usage Guide](docs/usage.md)
 `ace-support-config` provides layered configuration loading and merging for ACE, resolving values from `.ace` project files, user home defaults, and gem-bundled defaults with deterministic precedence. Used by [ace-llm](../ace-llm), [ace-search](../ace-search), [ace-review](../ace-review), and most other ACE packages.
 
+## ace-config CLI
+
+This package now owns the `ace-config` executable for managing `.ace` configuration files and templates.
+
+```bash
+ace-config init [GEM] [--force] [--dry-run] [--global] [--verbose]
+ace-config diff [GEM] [--global] [--local] [--file PATH] [--one-line]
+ace-config list [--verbose]
+ace-config version
+ace-config help
+```
+
+## Testing
+
+`ace-support-config` uses the ACE deterministic test taxonomy:
+
+```bash
+ace-test ace-support-config        # fast (default)
+ace-test ace-support-config feat   # deterministic feature coverage
+ace-test ace-support-config all    # fast + feat
+```
+
+This package does not define a package-owned `e2e` layer in this migration.
+
 ## How It Works
 
 1. A resolver builds a configuration cascade from the nearest `.ace` directory up to user-home and gem-default layers.

data/docs/demo/ace-config-bootstrap-root-files.tape.yml

@@ -0,0 +1,29 @@
+---
+description: Showcase ace-config init bootstrapping project-root guidance files from a subdirectory
+tags:
+- ace-config
+- ace-support-config
+- bootstrap
+settings:
+  font_size: 16
+  width: 1200
+  height: 700
+  format: gif
+scenes:
+- name: Initialize config from a nested working directory
+  commands:
+  - type: mkdir -p repo/subdir && cd repo && git init
+    sleep: 3s
+  - type: cd subdir && ace-config init support-core
+    sleep: 5s
+- name: Verify bootstrap files landed at the repository root
+  commands:
+  - type: cd ../ && find . -maxdepth 2 \\( -name '.gitignore' -o -name 'AGENTS.md' -o -name 'CLAUDE.md' \\) | sort
+    sleep: 4s
+  - type: printf '\n.gitignore contents:\n' && cat .gitignore
+    sleep: 4s
+setup:
+- sandbox
+- copy-fixtures
+teardown:
+- cleanup

data/docs/demo/ace-config-getting-started.tape.yml

@@ -0,0 +1,30 @@
+---
+description: Showcase ace-config CLI for listing, initializing, and diffing ace-* gem configurations
+tags:
+- ace-config
+- ace-support-config
+- getting-started
+settings:
+  font_size: 16
+  width: 1200
+  height: 700
+  format: gif
+scenes:
+- name: List available gem configs
+  commands:
+  - type: ace-config list
+    sleep: 3s
+- name: Preview config initialization
+  commands:
+  - type: ace-config init --dry-run
+    sleep: 4s
+- name: Diff configs against defaults
+  commands:
+  - type: ace-config diff --one-line
+    sleep: 3s
+teardown:
+- cleanup
+setup:
+- sandbox
+- git-init
+- copy-fixtures

data/docs/usage.md

@@ -0,0 +1,215 @@
+---
+doc-type: user
+title: ace-support-config Usage Guide
+purpose: Documentation for ace-support-config/docs/usage.md
+ace-docs:
+  last-updated: '2026-03-31'
+  last-checked: '2026-03-31'
+---
+
+# ace-support-config Usage Guide
+
+## Configuration Cascade
+
+The `ace-support-config` gem provides a generic configuration cascade system that merges configuration from multiple sources with priority-based resolution.
+
+## ace-config Command
+
+`ace-support-config` ships the `ace-config` CLI for template discovery, initialization, and drift checks.
+
+```bash
+ace-config init [GEM] [--force] [--dry-run] [--global] [--verbose]
+ace-config diff [GEM] [--global] [--local] [--file PATH] [--one-line]
+ace-config list [--verbose]
+ace-config version
+ace-config help
+```
+
+## Testing Contract
+
+`ace-support-config` follows the ACE deterministic package targets:
+
+```bash
+ace-test ace-support-config
+ace-test ace-support-config feat
+ace-test ace-support-config all
+```
+
+- `fast` (default) runs isolated deterministic package tests under `test/fast/`.
+- `feat` runs deterministic feature tests under `test/feat/`.
+- `all` runs `fast` then `feat`.
+- This package does not publish a package-owned `e2e` target in this migration.
+
+### Cascade Priority (highest to lowest)
+
+1. **Project level** - `<project_root>/.ace/`
+2. **User level** - `~/.ace/`
+3. **Gem defaults** - `.ace-defaults/` (lowest priority)
+
+### Basic Usage
+
+```ruby
+require 'ace/support/config'
+
+# Create a configuration resolver
+config = Ace::Support::Config.create
+
+# Resolve configuration from all sources
+resolved = config.resolve
+
+# Get nested values
+value = resolved.get("key", "nested", "path")
+```
+
+## Deep Merging
+
+The gem provides several array merge strategies when combining configurations:
+
+### Strategies
+
+- **`:replace`** (default) - Overlay array replaces base array
+- **`:concat`** - Concatenate arrays
+- **`:union`** - Set union (deduplicated)
+- **`:coerce_union`** - Coerce scalars to arrays, union, filter blanks
+
+```ruby
+# Replace strategy (default)
+config = Ace::Support::Config.create(merge_strategy: :replace)
+
+# Concatenate arrays
+config = Ace::Support::Config.create(merge_strategy: :concat)
+
+# Set union
+config = Ace::Support::Config.create(merge_strategy: :union)
+
+# Coerce union - scalars become arrays, then union
+config = Ace::Support::Config.create(merge_strategy: :coerce_union)
+```
+
+### Custom Merge
+
+```ruby
+# Use Config.wrap for one-liner merging
+base_config = { "key" => "default" }
+user_config = { "key" => "override" }
+
+merged = Ace::Support::Config::Models::Config.wrap(base_config, user_config)
+# => { "key" => "override" }
+```
+
+## Namespace-Based Configuration
+
+Load configuration for a specific namespace (e.g., per-gem configuration):
+
+```ruby
+resolver = Ace::Support::Config.create
+
+# Resolves: .ace/gem_name/config.yml or .ace/gem_name/config.yaml
+gem_config = resolver.resolve_namespace("gem_name")
+
+# With custom filename
+# Resolves: .ace/docs/config.yml or .ace/docs/config.yaml
+docs_config = resolver.resolve_namespace("docs", filename: "settings")
+```
+
+## Test Mode
+
+For faster test execution, enable test mode to skip filesystem searches:
+
+### Thread-Local Test Mode
+
+```ruby
+# Enable test mode
+Ace::Support::Config.test_mode = true
+
+# Create config (returns empty config immediately)
+config = Ace::Support::Config.create
+
+# Provide mock data
+Ace::Support::Config.default_mock = { "key" => "value" }
+
+# Create config with mock data
+config = Ace::Support::Config.create
+```
+
+### Environment Variable Test Mode
+
+```bash
+# Enable test mode via environment variable
+ACE_CONFIG_TEST_MODE=1 ruby my_script.rb
+```
+
+## Virtual Filesystem View
+
+The `virtual_resolver` provides a "virtual filesystem" view where the nearest config file wins:
+
+```ruby
+resolver = Ace::Support::Config.virtual_resolver
+
+# Find all config files matching a pattern
+resolver.glob("presets/*.yml").each do |relative, absolute|
+  puts "Found: #{relative} at #{absolute}"
+end
+
+# Check if a file exists anywhere in the cascade
+if resolver.exists?("templates/default.md")
+  path = resolver.resolve_path("templates/default.md")
+  # Use the file...
+end
+```
+
+## Custom Folder Names
+
+Use custom configuration folder names instead of the default `.ace`:
+
+```ruby
+config = Ace::Support::Config.create(
+  config_dir: ".my-app",      # instead of .ace
+  defaults_dir: ".my-app-defaults"  # instead of .ace-defaults
+)
+```
+
+## Gem Defaults
+
+To provide default configuration from your gem:
+
+```ruby
+# In your gem's lib/your_gem.rb
+require 'ace/support/config'
+
+module YourGem
+  def self.config
+    @config ||= Ace::Support::Config.create(
+      gem_path: __dir__,  # Path to your gem root
+      defaults_dir: ".your-gem-defaults"
+    )
+  end
+end
+```
+
+## Path Expansion
+
+The gem integrates with `ace-support-fs` for path expansion:
+
+```ruby
+expander = Ace::Support::Config.path_expander(
+  source_dir: File.expand_path("../config", __FILE__),
+  project_root: Dir.pwd
+)
+
+# Expand paths relative to source directory
+absolute_path = expander.expand("../data/file.yml")
+```
+
+## Reset Configuration State
+
+Clear all cached configuration (useful for tests):
+
+```ruby
+Ace::Support::Config.reset_config!
+```
+
+This clears:
+- Project root cache
+- Thread-local test mode state
+- Thread-local mock data

data/exe/ace-config

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ace/support/config"
+require "ace/support/config/cli"
+
+begin
+  Ace::Support::Config::CLI.start(ARGV)
+rescue SystemExit => e
+  exit(e.status)
+end

data/lib/ace/support/config/cli.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "organisms/config_initializer"
+require_relative "organisms/config_diff"
+require_relative "models/config_templates"
+
+module Ace
+  module Support
+    module Config
+      class CLI
+        def self.start(argv)
+          new.run(argv)
+        end
+
+        def run(argv)
+          return show_help if argv.empty?
+
+          command = argv.shift
+
+          case command
+          when "init"
+            run_init(argv)
+          when "diff"
+            run_diff(argv)
+          when "list"
+            run_list(argv)
+          when "version", "--version"
+            show_version
+          when "help", "--help", "-h"
+            show_help
+          else
+            puts "Unknown command: #{command}"
+            puts ""
+            show_help
+            exit 1
+          end
+        end
+
+        private
+
+        def run_init(argv)
+          options = {}
+
+          parser = OptionParser.new do |opts|
+            opts.banner = <<~BANNER.chomp
+              NAME
+                ace-config init - Initialize configuration for ace-* gems
+
+              USAGE
+                ace-config init [GEM] [OPTIONS]
+
+              OPTIONS
+            BANNER
+            opts.on("--force", "Overwrite existing files") { options[:force] = true }
+            opts.on("--dry-run", "Show what would be done") { options[:dry_run] = true }
+            opts.on("--global", "Use ~/.ace instead of ./.ace") { options[:global] = true }
+            opts.on("--verbose", "Show verbose output") { options[:verbose] = true }
+            opts.on("-h", "--help", "Show this help") do
+              puts opts
+              exit
+            end
+          end
+
+          parser.parse!(argv)
+          gem_name = argv.shift
+
+          initializer = Organisms::ConfigInitializer.new(**options)
+
+          if gem_name
+            initializer.init_gem(gem_name)
+          else
+            initializer.init_all
+          end
+        end
+
+        def run_diff(argv)
+          options = {}
+
+          parser = OptionParser.new do |opts|
+            opts.banner = <<~BANNER.chomp
+              NAME
+                ace-config diff - Compare configs with examples
+
+              USAGE
+                ace-config diff [GEM] [OPTIONS]
+
+              OPTIONS
+            BANNER
+            opts.on("--global", "Compare global configs") { options[:global] = true }
+            opts.on("--local", "Compare local configs (default)") { options[:local] = true }
+            opts.on("--file PATH", "Compare specific file") { |f| options[:file] = f }
+            opts.on("--one-line", "One-line summary per file") { options[:one_line] = true }
+            opts.on("--verbose", "Include unchanged files in one-line summary") { options[:verbose] = true }
+            opts.on("-h", "--help", "Show this help") do
+              puts opts
+              exit
+            end
+          end
+
+          parser.parse!(argv)
+          gem_name = argv.shift
+
+          differ = Organisms::ConfigDiff.new(**options)
+
+          if gem_name
+            differ.diff_gem(gem_name)
+          else
+            differ.run
+          end
+        end
+
+        def run_list(argv)
+          verbose = false
+
+          parser = OptionParser.new do |opts|
+            opts.banner = <<~BANNER.chomp
+              NAME
+                ace-config list - List available ace-* gems with example configs
+
+              USAGE
+                ace-config list [OPTIONS]
+
+              OPTIONS
+            BANNER
+            opts.on("--verbose", "Show detailed information") { verbose = true }
+            opts.on("-h", "--help", "Show this help") do
+              puts opts
+              exit
+            end
+          end
+
+          parser.parse!(argv)
+
+          puts "Available ace-* gems with example configurations:\n\n"
+
+          if Models::ConfigTemplates.all_gems.empty?
+            puts "No ace-* gems with example configurations found."
+            return
+          end
+
+          Models::ConfigTemplates.all_gems.each do |gem_name|
+            info = Models::ConfigTemplates.gem_info[gem_name]
+            source_label = case info[:source]
+            when :local then "[local]"
+            when :gem then "[gem]"
+            when :both then "[local+gem]"
+            end
+
+            puts "  #{gem_name} #{source_label}"
+
+            next unless verbose
+
+            puts "    Path: #{info[:path]}"
+            puts "    Gem: #{info[:gem_path]}" if info[:gem_path]
+            example_dir = Models::ConfigTemplates.example_dir_for(gem_name)
+            if example_dir && File.exist?(example_dir)
+              example_files = Dir.glob("#{example_dir}/**/*").reject { |f| File.directory?(f) }
+              puts "    Example files: #{example_files.size}"
+            end
+          end
+
+          puts "\nUse 'ace-config init [GEM]' to initialize a specific gem's configuration"
+          puts "Use 'ace-config init' to initialize all configurations"
+        end
+
+        def show_version
+          puts "ace-config #{Ace::Support::Config::VERSION}"
+        end
+
+        def show_help
+          puts <<~HELP
+            NAME
+              ace-config - Configuration management for ace-* gems
+
+            USAGE
+              ace-config COMMAND [OPTIONS]
+
+            COMMANDS
+              init [GEM]                        Initialize configuration for specific gem or all
+              diff [GEM]                        Compare configs with examples
+              list                              List available ace-* gems with example configs
+              version                           Show version
+              help                              Show this help
+
+            Run 'ace-config COMMAND --help' for more information on a command.
+          HELP
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/models/config_templates.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rubygems"
+
+module Ace
+  module Support
+    module Config
+      module Models
+        class ConfigTemplates
+          class << self
+            def all_gems
+              gem_info.keys.sort
+            end
+
+            def gem_exists?(gem_name)
+              gem_info.key?(gem_name)
+            end
+
+            def example_dir_for(gem_name)
+              info = gem_info[gem_name]
+              return nil unless info
+
+              path = (info[:source] == :gem) ? info[:path] : (info[:path] || info[:gem_path])
+              resolve_defaults_dir(path)
+            end
+
+            def gem_info
+              @gem_info ||= build_gem_info
+            end
+
+            def reset!
+              @gem_info = nil
+            end
+
+            def build_gem_info
+              gems = {}
+
+              parent_dir = File.expand_path("../../../../../../../", __FILE__)
+              Dir.glob("#{parent_dir}/ace-*").each do |dir|
+                next unless File.directory?(dir)
+
+                gem_name = File.basename(dir)
+                gems[gem_name] = {source: :local, path: dir} if has_example_dir?(dir)
+              end
+
+              begin
+                Gem::Specification.each do |spec|
+                  next unless spec.name.start_with?("ace-")
+
+                  gem_path = spec.gem_dir
+                  next unless has_example_dir?(gem_path)
+
+                  if gems.key?(spec.name)
+                    gems[spec.name][:source] = :both
+                    gems[spec.name][:gem_path] = gem_path
+                  else
+                    gems[spec.name] = {source: :gem, path: gem_path}
+                  end
+                end
+              rescue StandardError
+                # Fall back to local gems only when RubyGems traversal is unavailable.
+              end
+
+              gems
+            end
+
+            def docs_file_for(gem_name)
+              info = gem_info[gem_name]
+              return nil unless info
+
+              path = (info[:source] == :gem) ? info[:path] : (info[:path] || info[:gem_path])
+              File.join(path, "docs", "config.md")
+            end
+
+            private
+
+            def resolve_defaults_dir(gem_path)
+              File.join(gem_path, ".ace-defaults")
+            end
+
+            def has_example_dir?(gem_dir)
+              Dir.exist?(File.join(gem_dir, ".ace-defaults"))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/molecules/project_config_scanner.rb

@@ -21,7 +21,7 @@ module Ace
         class ProjectConfigScanner
           # Directories to skip during traversal
           SKIP_DIRS = %w[.git .cache vendor node_modules tmp coverage
-            .bundle _legacy .ace-local .ace-tasks .ace-taskflow].freeze
+            .bundle _legacy .ace-local .ace-tasks .ace-task].freeze
 
           # @param project_root [String, nil] Root directory to scan (default: Dir.pwd)
           # @param config_dir [String] Config folder name (default: ".ace")

data/lib/ace/support/config/organisms/config_diff.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+require_relative "../models/config_templates"
+
+module Ace
+  module Support
+    module Config
+      module Organisms
+        class ConfigDiff
+          def initialize(global: false, local: false, file: nil, one_line: false, verbose: false)
+            @global = global
+            @local = local
+            @file = file
+            @one_line = one_line
+            @verbose = verbose
+            @diffs = []
+          end
+
+          def run
+            if @file
+              diff_file(@file)
+            else
+              diff_all_configs
+            end
+
+            print_results
+          end
+
+          def diff_gem(gem_name)
+            normalized_name = gem_name.start_with?("ace-") ? gem_name : "ace-#{gem_name}"
+
+            unless Models::ConfigTemplates.gem_exists?(normalized_name)
+              puts "Error: Gem '#{normalized_name}' not found or has no example configurations"
+              exit 1
+            end
+
+            diff_gem_configs(normalized_name)
+            print_results
+          end
+
+          private
+
+          def config_directory
+            return ".ace" if @local
+
+            @global ? File.expand_path("~/.ace") : ".ace"
+          end
+
+          def diff_all_configs
+            Models::ConfigTemplates.all_gems.each do |gem_name|
+              diff_gem_configs(gem_name)
+            end
+          end
+
+          def diff_gem_configs(gem_name)
+            source_dir = Models::ConfigTemplates.example_dir_for(gem_name)
+            return unless source_dir && File.exist?(source_dir)
+
+            Dir.glob("#{source_dir}/**/*").each do |source_file|
+              next if File.directory?(source_file)
+
+              relative_path = Pathname.new(source_file).relative_path_from(Pathname.new(source_dir))
+              target_file = File.join(config_directory, relative_path.to_s)
+
+              compare_files(source_file, target_file, gem_name)
+            end
+          end
+
+          def diff_file(file_path)
+            unless file_path.start_with?(config_directory)
+              puts "File #{file_path} is not in a configuration directory"
+              return
+            end
+
+            relative_path = Pathname.new(file_path).relative_path_from(Pathname.new(config_directory))
+            parts = relative_path.to_s.split(File::SEPARATOR)
+            return if parts.empty?
+
+            config_subdir = parts.first
+            gem_name = "ace-#{config_subdir}"
+            return unless Models::ConfigTemplates.gem_exists?(gem_name)
+
+            source_dir = Models::ConfigTemplates.example_dir_for(gem_name)
+            relative_file = parts[1..].join(File::SEPARATOR)
+            source_file = File.join(source_dir, relative_file)
+
+            if File.exist?(source_file)
+              compare_files(source_file, file_path, gem_name)
+            else
+              puts "No example file found for #{file_path}"
+            end
+          end
+
+          def compare_files(source_file, target_file, gem_name)
+            @diffs << if !File.exist?(target_file)
+              {
+                gem: gem_name,
+                file: target_file,
+                status: :missing,
+                source: source_file
+              }
+            elsif files_differ?(source_file, target_file)
+              {
+                gem: gem_name,
+                file: target_file,
+                status: :different,
+                source: source_file,
+                diff_output: get_diff_output(source_file, target_file)
+              }
+            else
+              {
+                gem: gem_name,
+                file: target_file,
+                status: :same,
+                source: source_file
+              }
+            end
+          end
+
+          def files_differ?(file1, file2)
+            File.read(file1) != File.read(file2)
+          rescue StandardError
+            true
+          end
+
+          def get_diff_output(source_file, target_file)
+            output, _status = Open3.capture2("diff", "-u", target_file, source_file)
+            output
+          rescue StandardError
+            "Unable to generate diff"
+          end
+
+          def print_results
+            if @one_line
+              print_one_line_summary
+            else
+              print_detailed_diffs
+            end
+          end
+
+          def print_one_line_summary
+            @diffs.each do |diff|
+              case diff[:status]
+              when :missing
+                puts "MISSING: #{diff[:file]}"
+              when :different
+                puts "CHANGED: #{diff[:file]}"
+              when :same
+                puts "SAME:    #{diff[:file]}" if @verbose
+              end
+            end
+
+            puts "\nSummary:"
+            puts "  Missing: #{@diffs.count { |d| d[:status] == :missing }}"
+            puts "  Changed: #{@diffs.count { |d| d[:status] == :different }}"
+            puts "  Same: #{@diffs.count { |d| d[:status] == :same }}"
+          end
+
+          def print_detailed_diffs
+            missing = @diffs.select { |d| d[:status] == :missing }
+            changed = @diffs.select { |d| d[:status] == :different }
+
+            if missing.any?
+              puts "Missing configuration files:"
+              missing.each do |diff|
+                puts "  #{diff[:file]}"
+                puts "  -> Example: #{diff[:source]}"
+              end
+              puts
+            end
+
+            if changed.any?
+              puts "Changed configuration files:"
+              changed.each do |diff|
+                puts "\n#{diff[:file]}:"
+                puts diff[:diff_output]
+              end
+            end
+
+            if missing.empty? && changed.empty?
+              puts "All configuration files match the examples."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/organisms/config_initializer.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require_relative "../models/config_templates"
+
+module Ace
+  module Support
+    module Config
+      module Organisms
+        class ConfigInitializer
+          PROJECT_ROOT_DIR = "project-root"
+          GITIGNORE_ACE_LOCAL_ENTRY = ".ace-local/"
+
+          def initialize(force: false, dry_run: false, global: false, verbose: false)
+            @force = force
+            @dry_run = dry_run
+            @global = global
+            @verbose = verbose
+            @copied_files = []
+            @skipped_files = []
+          end
+
+          def init_all
+            puts "Initializing all ace-* gem configurations..." if @verbose
+
+            Models::ConfigTemplates.all_gems.each do |gem_name|
+              init_gem(gem_name)
+            end
+
+            print_summary
+          end
+
+          def init_gem(gem_name)
+            gem_name = normalize_gem_name(gem_name)
+
+            unless Models::ConfigTemplates.gem_exists?(gem_name)
+              puts "Warning: No configuration found for #{gem_name}"
+              return
+            end
+
+            puts "\nInitializing #{gem_name}..." if @verbose
+
+            source_dir = Models::ConfigTemplates.example_dir_for(gem_name)
+            target_dir = target_directory
+
+            unless File.exist?(source_dir)
+              puts "Warning: No .ace-defaults directory found for #{gem_name}"
+              return
+            end
+
+            show_config_docs_if_needed(gem_name, target_dir)
+            copy_config_files(source_dir, target_dir)
+          end
+
+          private
+
+          def normalize_gem_name(name)
+            name.start_with?("ace-") ? name : "ace-#{name}"
+          end
+
+          def target_directory
+            return File.expand_path("~/.ace") if @global
+
+            File.join(project_root, ".ace")
+          end
+
+          def show_config_docs_if_needed(gem_name, target_dir)
+            config_subdir = gem_name.sub("ace-", "")
+            existing_configs = Dir.glob("#{target_dir}/#{config_subdir}/**/*").reject { |f| File.directory?(f) }
+
+            return if existing_configs.any? || @dry_run
+
+            docs_file = Models::ConfigTemplates.docs_file_for(gem_name)
+            puts "\n#{File.read(docs_file)}\n" if docs_file && File.exist?(docs_file)
+          end
+
+          def copy_config_files(source_dir, target_dir)
+            glob_pattern = File.join(source_dir, "**", "*")
+
+            Dir.glob(glob_pattern, File::FNM_DOTMATCH).each do |source_file|
+              basename = File.basename(source_file)
+              next if basename == "." || basename == ".."
+              next if File.directory?(source_file)
+
+              relative_path = Pathname.new(source_file).relative_path_from(Pathname.new(source_dir))
+              target_file = target_file_for(relative_path, target_dir)
+              next unless target_file
+
+              copy_file(source_file, target_file)
+            end
+          end
+
+          def copy_file(source, target)
+            if File.basename(target) == ".gitignore"
+              merge_gitignore(source, target)
+              return
+            end
+
+            if File.exist?(target) && !@force
+              @skipped_files << target
+              puts "  Skipped: #{target} (already exists)" if @verbose
+              return
+            end
+
+            if @dry_run
+              puts "  Would copy: #{source} -> #{target}"
+            else
+              FileUtils.mkdir_p(File.dirname(target))
+              FileUtils.cp(source, target)
+              @copied_files << target
+              puts "  Copied: #{target}" if @verbose
+            end
+          end
+
+          def target_file_for(relative_path, target_dir)
+            relative_str = relative_path.to_s
+
+            if relative_str.start_with?("#{PROJECT_ROOT_DIR}/")
+              return nil if @global
+
+              return File.join(project_root, relative_str.delete_prefix("#{PROJECT_ROOT_DIR}/"))
+            end
+
+            File.join(target_dir, relative_str)
+          end
+
+          def merge_gitignore(source, target)
+            target_exists = File.exist?(target)
+
+            if target_exists
+              merge_gitignore_entry_if_missing(source, target)
+              return
+            end
+
+            if @dry_run
+              puts "  Would copy: #{source} -> #{target}"
+            else
+              FileUtils.mkdir_p(File.dirname(target))
+              FileUtils.cp(source, target)
+              @copied_files << target
+              puts "  Copied: #{target}" if @verbose
+            end
+          end
+
+          def merge_gitignore_entry_if_missing(source, target)
+            existing_content = File.read(target)
+            return if gitignore_entry_present?(existing_content, GITIGNORE_ACE_LOCAL_ENTRY)
+
+            line = File.readlines(source, chomp: true).find do |entry|
+              entry == GITIGNORE_ACE_LOCAL_ENTRY
+            end
+            return unless line
+
+            if @dry_run
+              puts "  Would append: #{line} -> #{target}"
+              return
+            end
+
+            File.open(target, "a") do |file|
+              file.write("\n") unless existing_content.end_with?("\n") || existing_content.empty?
+              file.puts line
+            end
+
+            @copied_files << target
+            puts "  Appended: #{line} -> #{target}" if @verbose
+          end
+
+          def gitignore_entry_present?(content, entry)
+            content.each_line.any? do |line|
+              normalized = line.strip
+              next false if normalized.empty? || normalized.start_with?("#")
+
+              normalized == entry
+            end
+          end
+
+          def project_root
+            @project_root ||= Ace::Support::Config.find_project_root(start_path: Dir.pwd) || Dir.pwd
+          end
+
+          def print_summary
+            return if @dry_run
+
+            puts "\nConfiguration initialization complete:"
+            puts "  Files copied: #{@copied_files.size}"
+            puts "  Files skipped: #{@skipped_files.size}"
+
+            if @skipped_files.any? && !@force
+              puts "\nUse --force to overwrite existing files"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/support/config/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Support
     module Config
-      VERSION = '0.9.2'
+      VERSION = '0.11.2'
     end
   end
 end

data/lib/ace/support/config.rb

@@ -26,6 +26,9 @@ require_relative "config/molecules/project_config_scanner"
 # Load organisms (depend on molecules)
 require_relative "config/organisms/config_resolver"
 require_relative "config/organisms/virtual_config_resolver"
+require_relative "config/organisms/config_initializer"
+require_relative "config/organisms/config_diff"
+require_relative "config/models/config_templates"
 
 module Ace
   # Generic configuration cascade management

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-support-config
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.11.2
 platform: ruby
 authors:
 - Michal Czyz
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2026-03-29 00:00:00.000000000 Z
+date: 2026-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-fs
@@ -56,7 +56,8 @@ description: Reusable configuration cascade with customizable folder names. Supp
   resolution.
 email:
 - mc@cs3b.com
-executables: []
+executables:
+- ace-config
 extensions: []
 extra_rdoc_files: []
 files:
@@ -65,20 +66,28 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/demo/ace-config-bootstrap-root-files.tape.yml
+- docs/demo/ace-config-getting-started.tape.yml
+- docs/usage.md
+- exe/ace-config
 - lib/ace/support.rb
 - lib/ace/support/config.rb
 - lib/ace/support/config/atoms/deep_merger.rb
 - lib/ace/support/config/atoms/path_rule_matcher.rb
 - lib/ace/support/config/atoms/path_validator.rb
 - lib/ace/support/config/atoms/yaml_parser.rb
+- lib/ace/support/config/cli.rb
 - lib/ace/support/config/errors.rb
 - lib/ace/support/config/models/cascade_path.rb
 - lib/ace/support/config/models/config.rb
 - lib/ace/support/config/models/config_group.rb
+- lib/ace/support/config/models/config_templates.rb
 - lib/ace/support/config/molecules/config_finder.rb
 - lib/ace/support/config/molecules/file_config_resolver.rb
 - lib/ace/support/config/molecules/project_config_scanner.rb
 - lib/ace/support/config/molecules/yaml_loader.rb
+- lib/ace/support/config/organisms/config_diff.rb
+- lib/ace/support/config/organisms/config_initializer.rb
 - lib/ace/support/config/organisms/config_resolver.rb
 - lib/ace/support/config/organisms/virtual_config_resolver.rb
 - lib/ace/support/config/version.rb