gemchain 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cfa66ea15e541d38928f3f19469437e021e4e40566af6dbc68c17bdda991c986
+  data.tar.gz: c9870c9615acd4f464302d282bf50ba722f098d5ed6e4e1da3c4ef60c46ab25e
+SHA512:
+  metadata.gz: 0e4133d289e5b13d797ec17a8b57093e1cb0a4d74b5b65c865f9b7317d9e6714461e2b7d15cd873cbf0890fec66ec8cb7b1bd3c5290ebe247ffd63ea9c8bc9f4
+  data.tar.gz: 0e00b7f943cf3ba4f39f831eebe8b128a4a5e6582d101f9b69cf46663ebfe8b639d74a858eb39921aa6d4c31eb7b336c6b8492a3aa016e15aca7389559611a70

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## [0.2.0] — 2026-08-10
+
+### Added
+
+- **Cascade execution pipeline** — `gemchain update` now executes the plan
+  instead of printing it:
+  - `:bump` — rewrites the `VERSION` constant (quote style preserved,
+    idempotent)
+  - `:update_dependency` — rewrites the gemspec constraint
+    (`add_dependency`/`add_runtime_dependency`, both quote styles, adds a
+    constraint when missing)
+  - `:test` — `bundle install` + `bundle update <gem>` + `bundle exec rake
+    test` in each gem dir
+  - `:release` — patch/minor/major bump for dependents (configurable via
+    `bump:` in cascade.yml), git commit, `gem build`, `gem push`, git tag,
+    push — with a [y/N] confirmation per release unless `--yes` is given
+  - Source gem: if it isn't already at the target version, it is bumped,
+    tested, and released first; if it is (post-release flow), only
+    dependents are processed
+  - Any test failure stops the cascade immediately and reports; nothing
+    after the failure is touched
+- `--test-only` flag — run dependents' test suites only, editing or
+  releasing nothing
+- Executor is fully injectable (command runner, confirmation, output), so
+  the whole pipeline is tested without touching bundler, git, or RubyGems
+
+## [0.1.0] — 2026-07-26
+
+### Added
+
+- Initial release
+- `gemchain check` — visualize gem ecosystem and dependencies
+- `gemchain guard <gem>` — pre-release warnings about dependents
+- `gemchain update <gem> <version>` — cascade plan with dry-run support
+- `gemchain link` — generate Gemfile path references for local development
+- Config via `cascade.yml` with glob include/exclude and explicit gem paths
+- Dependency graph with topological sort and cycle detection
+- Full test suite

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,134 @@
+# gemchain
+
+**Cascade gem updates through interdependent gem ecosystems.**
+
+When you maintain multiple gems that depend on each other, releasing an update
+to one gem means testing and releasing every gem that depends on it. Gemchain
+automates this — it warns you before you release, and can cascade updates
+through the entire dependency chain.
+
+## Installation
+
+```bash
+gem install gemchain
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "gemchain"
+```
+
+## Usage
+
+### 1. Create a config file
+
+```yaml
+# cascade.yml
+workspace: .
+include: ask-*
+```
+
+Or specify gems explicitly:
+
+```yaml
+# cascade.yml
+workspace: .
+gems:
+  ask-core: ./ask-core
+  ask-agent: ./ask-agent
+```
+
+### 2. Check your ecosystem
+
+```bash
+gemchain check
+```
+
+Shows every gem, its version, its dependencies, and how many gems depend on it.
+
+### 3. Guard a release
+
+```bash
+gemchain guard ask-core
+```
+
+```
+⚠  Pre-release Guard: ask-core v0.7.0
+
+  7 gem(s) directly depend on ask-core:
+    • ask-llm-providers (0.10.0) — requires: ask-core >= 0.1
+    • ask-state-providers (0.3.0) — requires: ask-core >= 0.1
+    ...
+
+  Before releasing ask-core, make sure these gems still work:
+    ⬜ ask-llm-providers (0.10.0)
+    ⬜ ask-state-providers (0.3.0)
+    ...
+```
+
+### 4. Cascade an update
+
+```bash
+gemchain update ask-core 0.8.0 --dry-run    # show the plan, change nothing
+gemchain update ask-core 0.8.0 --test-only  # run dependents' suites, change nothing
+gemchain update ask-core 0.8.0              # execute: bump, test, release in order
+gemchain update ask-core 0.8.0 --yes        # skip per-release confirmations
+```
+
+Execution is end to end: if the source gem isn't already at the target
+version it is bumped, tested, and released first (dependents resolve the new
+version from RubyGems); then each dependent gets its constraint updated,
+tested, and released in topological order — commit, `gem build`, `gem push`,
+git tag, push. Every release asks for confirmation on stdin unless `--yes`
+is given. If a test suite fails, the cascade stops immediately and reports —
+nothing after the failure is touched.
+
+If the source gem is already released at the target version (the common
+post-release flow — `gemchain update ask-tools-shell 0.5.1` right after
+releasing it), only the dependents are processed.
+
+### 5. Generate local dev links
+
+```bash
+gemchain link
+```
+
+Prints Gemfile content to add `path:` references for all workspace gems.
+
+## Configuration
+
+### `cascade.yml` options
+
+| Option | Description |
+|---|---|
+| `workspace` | Base directory for relative paths |
+| `include` | Glob pattern(s) for gem directories |
+| `exclude` | Glob pattern(s) to exclude |
+| `gems` | Explicit gem name → path mappings |
+| `bump` | Version bump level for dependent releases: `patch`, `minor`, or `major` (default `patch`) |
+
+## How it works
+
+1. Discovers gems in your workspace (via glob patterns or explicit paths)
+2. Loads each gem's gemspec to build a dependency graph
+3. When you check or guard a gem, it shows all dependents
+4. When you cascade, the executor runs the plan in topological order:
+   - Rewrite the version constraint in the dependent's gemspec
+   - `bundle install`, `bundle update <gem>`, and `bundle exec rake test`
+   - If tests pass: bump the dependent's version, commit, `gem build`,
+     `gem push`, git tag, push
+   - If tests fail: stop and report — nothing after the failure is touched
+
+## Development
+
+```bash
+git clone https://github.com/ask-rb/gemchain
+cd gemchain
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/exe/gemchain

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/gemchain"
+
+Gemchain::CLI.start

data/lib/gemchain/cascade.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Gemchain
+  class Cascade
+    Result = Struct.new(:success, :message, :details, keyword_init: true)
+
+    def initialize(workspace)
+      @workspace = workspace
+    end
+
+    # Pre-release guard: warns about gems that depend on +gem_name+.
+    # Returns a hash with dependency info, or nil if gem not found.
+    def guard(gem_name)
+      gem = @workspace.find(gem_name)
+      return nil unless gem
+
+      direct = @workspace.dependents_of(gem_name)
+      transitive = @workspace.transitive_dependents(gem_name)
+
+      {
+        gem: gem,
+        direct_dependents: direct.size,
+        dependents: direct,
+        transitive_dependents: transitive,
+        all_downstream: transitive.map { |n| @workspace.find(n) }.compact
+      }
+    end
+
+    # Returns a full ecosystem check.
+    def check
+      gems_info = @workspace.gems.map do |gem|
+        deps = @workspace.dependents_of(gem.name)
+        {
+          name: gem.name,
+          version: gem.version.to_s,
+          path: gem.path,
+          dependencies: gem.dependencies,
+          dependents: deps.map(&:name),
+          dependent_count: deps.size
+        }
+      end
+
+      {gems: gems_info}
+    end
+
+    # Performs the full cascade update:
+    # 1. If the source gem isn't already at +new_version+: bump, test, release it
+    # 2. For each dependent (topological order): update constraint, test, bump, release
+    #
+    # With test_only: true, only the dependents' :test steps are emitted —
+    # verify compatibility without editing or releasing anything.
+    def update(gem_name, new_version, dry_run: false, test_only: false)
+      gem = @workspace.find(gem_name)
+      return Result.new(success: false, message: "Gem '#{gem_name}' not found in workspace") unless gem
+
+      unless new_version.match?(/\A\d+\.\d+\.\d+\z/)
+        return Result.new(success: false, message: "Invalid version: #{new_version.inspect} — expected X.Y.Z")
+      end
+
+      steps = []
+      order = @workspace.cascade_order(gem_name)
+
+      if !test_only && gem.version.to_s != new_version
+        # The source must be released before dependents' `bundle update`
+        # can resolve the new version from RubyGems.
+        steps << {action: :bump, gem: gem_name, version: new_version}
+        steps << {action: :test, gem: gem_name}
+        steps << {action: :release, gem: gem_name, version: new_version}
+      end
+
+      order.each do |dep_name|
+        next if dep_name == gem_name
+        dep_gem = @workspace.find(dep_name)
+        next unless dep_gem
+        next unless dep_gem.dependencies.key?(gem_name)
+
+        if test_only
+          steps << {action: :test, gem: dep_name, dependency: gem_name}
+        else
+          steps << {action: :update_dependency, gem: dep_name, dependency: gem_name, constraint: ">= #{new_version}"}
+          steps << {action: :test, gem: dep_name, dependency: gem_name}
+          steps << {action: :release, gem: dep_name}
+        end
+      end
+
+      {steps: steps, dry_run: dry_run, test_only: test_only}
+    end
+
+    # Generates Gemfile content with local path references for all workspace gems.
+    def link_content(workspace: nil)
+      workspace ||= Dir.pwd
+      lines = []
+      lines << "# Auto-generated by gemchain — local development path references"
+      lines << "# Replace in your Gemfile to test against local copies"
+      lines << ""
+      lines << "# Add this block to your Gemfile:"
+      lines << "ask_rb_root = File.expand_path(\"..\", __dir__)" if workspace
+      lines << ""
+
+      gem_names = @workspace.gems.map(&:name).sort
+      lines << "%w[#{gem_names.join(' ')}].each do |gem_name|"
+      lines << "  gem gem_name, path: File.join(ask_rb_root, gem_name)"
+      lines << "end"
+      lines << ""
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/gemchain/cli.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Gemchain
+  class CLI < Thor
+    CONFIG_FILENAME = "cascade.yml"
+
+    desc "check", "Show the gem ecosystem dependency graph and constraint status"
+    def check
+      workspace = load_workspace
+      return unless workspace
+
+      cascade = Cascade.new(workspace)
+      result = cascade.check
+
+      puts "\n📊 Gem Ecosystem Status\n#{'=' * 50}"
+
+      result[:gems].each do |info|
+        dep_count = info[:dependent_count]
+        icon = dep_count > 0 ? "⤷" : "  "
+        puts "\n#{info[:name]} (#{info[:version]}) #{icon} #{dep_count} #{dep_count == 1 ? 'dependent' : 'dependents'}"
+
+        info[:dependencies].each do |dep_name, constraint|
+          puts "    #{dep_name} (#{constraint})"
+        end
+      end
+
+      total = result[:gems].size
+      puts "\n#{'─' * 50}"
+      puts "#{total} #{total == 1 ? 'gem' : 'gems'} in workspace\n\n"
+    end
+
+    desc "guard GEM_NAME", "Check what depends on a gem before releasing it"
+    def guard(gem_name = nil)
+      unless gem_name
+        puts "Usage: gemchain guard GEM_NAME"
+        puts "  e.g. gemchain guard ask-core"
+        return
+      end
+
+      workspace = load_workspace
+      return unless workspace
+
+      cascade = Cascade.new(workspace)
+      result = cascade.guard(gem_name)
+
+      unless result
+        puts "✖ Gem '#{gem_name}' not found in workspace."
+        return
+      end
+
+      gem = result[:gem]
+      puts "\n⚠  Pre-release Guard: #{gem.name} v#{gem.version}\n#{'=' * 50}"
+
+      if result[:dependents].empty?
+        puts "  No gems in the workspace depend on #{gem.name}."
+        puts "  Safe to release without cascade."
+      else
+        puts "  #{result[:direct_dependents]} gem(s) directly depend on #{gem.name}:"
+        result[:dependents].each do |dep|
+          deps_str = dep.dependencies.map { |n, c| "#{n} #{c}" }.join(", ")
+          puts "    • #{dep.name} (#{dep.version}) — requires: #{deps_str}"
+        end
+
+        puts "\n  Before releasing #{gem.name}, make sure these gems still work:"
+        result[:all_downstream].each do |g|
+          puts "    ⬜ #{g.name} (#{g.version})"
+        end
+
+        puts "\n  Run: gemchain update #{gem_name} <new-version>"
+        puts "  to cascade the update automatically."
+      end
+      puts
+    end
+
+    desc "update GEM_NAME NEW_VERSION", "Cascade a gem update through all dependents"
+    method_option :"dry-run", type: :boolean, aliases: "-n", desc: "Show what would be done without doing it"
+    method_option :yes, type: :boolean, aliases: "-y", desc: "Skip release confirmations"
+    method_option :"test-only", type: :boolean, desc: "Run dependent test suites without editing or releasing"
+    def update(gem_name = nil, new_version = nil)
+      unless gem_name && new_version
+        puts "Usage: gemchain update GEM_NAME NEW_VERSION"
+        puts "  e.g. gemchain update ask-core 0.8.0"
+        puts "  e.g. gemchain update ask-core 0.8.0 --dry-run"
+        puts "  e.g. gemchain update ask-core 0.8.0 --test-only"
+        return
+      end
+
+      dry_run = !!options[:"dry-run"]
+      test_only = !!options[:"test-only"]
+      workspace = load_workspace
+      return unless workspace
+
+      cascade = Cascade.new(workspace)
+      plan = cascade.update(gem_name, new_version, dry_run: dry_run, test_only: test_only)
+
+      unless plan[:success] != false
+        puts "✖ #{plan[:message]}"
+        return
+      end
+
+      puts "\n📋 Cascade Plan for #{gem_name} → #{new_version}\n#{'=' * 50}"
+
+      if dry_run
+        puts "  (dry run — no changes will be made)\n"
+        render_steps(plan[:steps])
+        puts "\n  ✅ Dry run complete. Run without --dry-run to execute."
+      else
+        executor = Executor.new(workspace: workspace, steps: plan[:steps],
+                                yes: options[:yes], bump: workspace.config.bump)
+        result = executor.run
+
+        if result.success
+          puts "\n  ✅ Released: #{result.released.join(', ')}" unless result.released.empty?
+          puts "  ⏭ Skipped: #{result.skipped.join(', ')}" unless result.skipped.empty?
+          if result.released.empty? && result.skipped.empty?
+            puts "\n  No releases needed — dependents verified."
+          else
+            puts "\n  Cascade complete."
+          end
+        else
+          gem, message = result.failed.first
+          puts "\n  ✖ Cascade stopped at #{gem}:"
+          puts "     #{message}"
+          puts "  Released so far: #{result.released.join(', ')}" unless result.released.empty?
+        end
+      end
+      puts
+    end
+
+    desc "link", "Generate Gemfile path references for local development"
+    def link
+      workspace = load_workspace
+      return unless workspace
+
+      cascade = Cascade.new(workspace)
+      content = cascade.link_content(workspace: Dir.pwd)
+
+      puts "\n🔗 Gemfile Local Path References\n#{'=' * 50}"
+      puts
+      puts content
+      puts
+      puts "Add the block above to each gem's Gemfile to use local copies"
+      puts "during development instead of published versions."
+      puts
+    end
+
+    desc "version", "Show gemchain version"
+    def version
+      puts "gemchain #{Gemchain::VERSION}"
+    end
+
+    no_commands do
+      def render_steps(steps)
+        steps.each do |step|
+          case step[:action]
+          when :bump
+            puts "  1. Bump #{step[:gem]} from current → #{step[:version]}"
+          when :update_dependency
+            puts "  #{'─' * 40}"
+            puts "  #{step[:gem]}: update #{step[:dependency]} constraint to #{step[:constraint]}"
+          when :test
+            puts "  #{step[:gem]}: bundle exec rake test"
+          when :release
+            puts "  #{step[:gem]}: bump version & release"
+          end
+        end
+      end
+
+      def load_workspace
+        config_path = find_config
+        unless config_path
+          puts "No cascade.yml found in current directory."
+          puts "Create one with:"
+          puts "  workspace: ."
+          puts "  include: ask-*"
+          puts "  # or specify gems explicitly:"
+          puts "  # gems:"
+          puts "  #   ask-core: ./ask-core"
+          return nil
+        end
+
+        config = Config.load(config_path)
+        Workspace.new(config)
+      rescue Config::NotFoundError => e
+        puts "✖ #{e.message}"
+        nil
+      end
+
+      def find_config
+        path = File.join(Dir.pwd, CONFIG_FILENAME)
+        return path if File.exist?(path)
+
+        # Also check parent directories
+        dir = Dir.pwd
+        loop do
+          parent = File.dirname(dir)
+          break if parent == dir
+
+          path = File.join(parent, CONFIG_FILENAME)
+          return path if File.exist?(path)
+
+          dir = parent
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/gemchain/config.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Gemchain
+  class Config
+    class NotFoundError < Gemchain::Error; end
+
+    attr_reader :workspace, :include_patterns, :exclude_patterns, :gems, :bump
+
+    def initialize(workspace: Dir.pwd, include: [], exclude: [], gems: {}, bump: :patch)
+      @workspace = File.expand_path(workspace)
+      @include_patterns = [include].flatten.compact
+      @exclude_patterns = [exclude].flatten.compact
+      @gems = gems
+      @bump = (bump || :patch).to_sym
+    end
+
+    def self.load(path)
+      path = File.expand_path(path)
+      raise NotFoundError, "Config file not found: #{path}" unless File.exist?(path)
+
+      data = YAML.safe_load(File.read(path), permitted_classes: [Regexp]) || {}
+      new(
+        workspace: data["workspace"] || Dir.pwd,
+        include: data["include"] || [],
+        exclude: data["exclude"] || [],
+        gems: data["gems"] || {},
+        bump: data["bump"] || :patch
+      )
+    end
+
+    def gem_dirs
+      if @gems.any?
+        @gems.values.map { |g| File.expand_path(g, @workspace) }
+      else
+        dirs = Dir.glob(@include_patterns, base: @workspace).select do |entry|
+          full_path = File.join(@workspace, entry)
+          File.directory?(full_path) && gemspec_in?(full_path)
+        end.map { |entry| File.join(@workspace, entry) }
+
+        if @exclude_patterns.any?
+          excluded = Dir.glob(@exclude_patterns, base: @workspace).map { |e| File.join(@workspace, e) }
+          dirs -= excluded
+        end
+
+        dirs
+      end
+    end
+
+    private
+
+    def gemspec_in?(dir)
+      Dir.glob(File.join(dir, "*.gemspec")).any?
+    end
+  end
+end

data/lib/gemchain/dependency_graph.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Gemchain
+  class DependencyGraph
+    class CircularDependencyError < Gemchain::Error; end
+
+    def initialize(gems)
+      @gems = gems
+      @graph = build_graph
+    end
+
+    # Gems that directly depend on +gem_name+.
+    def dependents_of(gem_name)
+      @gems.select { |g| g.dependencies.key?(gem_name) }
+    end
+
+    # Gems that +gem_name+ directly depends on (only workspace gems).
+    def dependencies_of(gem_name)
+      gem = find(gem_name)
+      return [] unless gem
+
+      gem.dependencies.keys.filter_map { |dep_name| find(dep_name) }
+    end
+
+    # All transitive dependents of +gem_name+, including the gem itself.
+    def transitive_dependents(gem_name)
+      result = Set.new
+      queue = [gem_name]
+
+      until queue.empty?
+        current = queue.shift
+        next if result.include?(current)
+
+        result.add(current)
+        dependents_of(current).each { |g| queue << g.name }
+      end
+
+      result.to_a
+    end
+
+    # Gems with no workspace dependencies — leaves of the dependency tree.
+    def leaf_gems
+      @gems.select { |g| dependencies_of(g.name).empty? }
+    end
+
+    # Topological order: dependencies before dependents.
+    # If +start_gem+ is given, only includes that gem and its transitive dependents.
+    def cascade_order(start_gem = nil)
+      if start_gem
+        relevant = transitive_dependents(start_gem)
+        subgraph = @graph.select { |k, _| relevant.include?(k) }
+        tsort(subgraph)
+      else
+        tsort(@graph)
+      end
+    end
+
+    private
+
+    def find(name)
+      @gems.find { |g| g.name == name }
+    end
+
+    def build_graph
+      graph = {}
+      @gems.each do |gem|
+        graph[gem.name] = gem.dependencies.keys.select { |dep_name| find(dep_name) }
+      end
+      graph
+    end
+
+    def tsort(graph)
+      sorted = []
+      visited = Set.new
+      temp_marked = Set.new
+
+      graph.keys.each do |node|
+        ts_visit(node, graph, visited, temp_marked, sorted) unless visited.include?(node)
+      end
+
+      sorted
+    end
+
+    def ts_visit(node, graph, visited, temp_marked, sorted)
+      return if visited.include?(node)
+      raise CircularDependencyError, "Circular dependency detected involving #{node}" if temp_marked.include?(node)
+
+      temp_marked.add(node)
+      (graph[node] || []).each do |dep|
+        ts_visit(dep, graph, visited, temp_marked, sorted)
+      end
+      temp_marked.delete(node)
+      visited.add(node)
+      sorted << node
+    end
+  end
+end

data/lib/gemchain/executor.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Gemchain
+  class ExecutionError < Error; end
+
+  # Executes a cascade plan: bumps versions, rewrites gemspec constraints,
+  # runs test suites, and releases gems to RubyGems — stopping at the first
+  # failure. All shell interaction goes through the +runner+ so the whole
+  # pipeline is testable without touching bundler, git, or RubyGems.
+  class Executor
+    Result = Struct.new(:success, :released, :skipped, :failed, keyword_init: true)
+
+    # Real command runner: executes via Open3, raises ExecutionError with
+    # output context on any non-zero exit.
+    class Runner
+      def run(command, chdir: nil)
+        out, err, status = Open3.capture3(*command, chdir: chdir)
+        return if status.success?
+
+        detail = err.lines.first(5).join.strip
+        detail = out.lines.first(5).join.strip if detail.empty?
+        raise ExecutionError, "Command failed: #{command.join(' ')}#{detail.empty? ? '' : "\n#{detail}"}"
+      end
+    end
+
+    BUMP_LEVELS = %i[patch minor major].freeze
+
+    # @param workspace [Workspace] the gem ecosystem
+    # @param steps [Array<Hash>] the plan from Cascade#update
+    # @param runner [#run] command runner (defaults to the real one)
+    # @param confirm [Proc] per-release confirmation, called with a message;
+    #   defaults to a [y/N] prompt on stdin
+    # @param yes [Boolean] skip confirmations entirely
+    # @param bump [Symbol] dependent version bump level (:patch, :minor, :major)
+    # @param output [#puts] progress output stream
+    def initialize(workspace:, steps:, runner: nil, confirm: nil, yes: false,
+                   bump: :patch, output: $stdout)
+      @workspace = workspace
+      @steps = steps
+      @runner = runner || Runner.new
+      @confirm = confirm
+      @yes = yes
+      @bump = bump.to_sym
+      @output = output
+      raise ArgumentError, "bump must be one of #{BUMP_LEVELS.inspect}" unless BUMP_LEVELS.include?(@bump)
+    end
+
+    def run
+      released = []
+      skipped = []
+
+      @steps.each do |step|
+        begin
+          case step[:action]
+          when :bump
+            progress(step) { bump_version(gem_dir(step[:gem]), step[:version]) }
+          when :update_dependency
+            progress(step) { update_dependency(gem_dir(step[:gem]), step[:dependency], step[:constraint]) }
+          when :test
+            progress(step) { run_tests(gem_dir(step[:gem]), step[:dependency]) }
+          when :release
+            if release_confirmed?(step)
+              progress(step) { release(step) }
+              released << step[:gem]
+            else
+              @output.puts "  ⏭ Skipped release of #{step[:gem]} (declined)"
+              skipped << step[:gem]
+            end
+          end
+        rescue ExecutionError => e
+          return Result.new(success: false, released: released, skipped: skipped,
+                            failed: {step[:gem] => e.message})
+        end
+      end
+
+      Result.new(success: true, released: released, skipped: skipped, failed: nil)
+    end
+
+    private
+
+    def progress(step)
+      @output.puts "  ▶ #{describe(step)}"
+      yield
+    end
+
+    def describe(step)
+      case step[:action]
+      when :bump then "Bump #{step[:gem]} → #{step[:version]}"
+      when :update_dependency then "#{step[:gem]}: #{step[:dependency]} constraint → #{step[:constraint]}"
+      when :test then "#{step[:gem]}: bundle exec rake test"
+      when :release then "Release #{step[:gem]}"
+      end
+    end
+
+    def gem_dir(name)
+      gem = @workspace.find(name)
+      raise ExecutionError, "Gem '#{name}' not found in workspace" unless gem
+
+      gem.path
+    end
+
+    # ── :bump — rewrite the VERSION constant, keeping the quote style ──
+
+    def bump_version(dir, version)
+      file = version_file(dir)
+      content = File.read(file)
+      updated = content.sub(/VERSION\s*=\s*(['"])[^'"]*\1/) do |match|
+        quote = match[/['"]/]
+        "VERSION = #{quote}#{version}#{quote}"
+      end
+      File.write(file, updated) unless updated == content
+    end
+
+    def version_file(dir)
+      file = Dir.glob(File.join(dir, "lib", "**", "version.rb")).find do |f|
+        File.read(f).match?(/VERSION\s*=\s*['"]/)
+      end
+      raise ExecutionError, "No VERSION constant found under #{dir}/lib" unless file
+
+      file
+    end
+
+    # ── :update_dependency — rewrite the gemspec constraint line ──
+
+    def update_dependency(dir, dependency, constraint)
+      file = gemspec_file(dir)
+      lines = File.readlines(file)
+      updated = lines.map do |line|
+        if (m = line.match(/\A(\s*)(spec\.(?:add_)?(?:runtime_)?dependency\s+)(['"])(#{Regexp.escape(dependency)})\3/))
+          q = m[3]
+          "#{m[1]}#{m[2]}#{q}#{m[4]}#{q}, #{q}#{constraint}#{q}\n"
+        else
+          line
+        end
+      end
+      File.write(file, updated.join) unless updated == lines
+    end
+
+    def gemspec_file(dir)
+      file = Dir.glob(File.join(dir, "*.gemspec")).first
+      raise ExecutionError, "No gemspec found in #{dir}" unless file
+
+      file
+    end
+
+    # ── :test — resolve the new dependency, then run the suite ──
+
+    def run_tests(dir, dependency = nil)
+      # A fresh checkout may not have its bundle installed yet; bundle
+      # install first so bundle update can resolve the new version.
+      @runner.run(["bundle", "install"], chdir: dir)
+      @runner.run(["bundle", "update", dependency], chdir: dir) if dependency
+      @runner.run(["bundle", "exec", "rake", "test"], chdir: dir)
+    end
+
+    # ── :release — bump, commit, build, push, tag ──
+
+    def release(step)
+      dir = gem_dir(step[:gem])
+      name = step[:gem]
+      version = step[:version] || bump_dependent(dir, name)
+
+      files = [gemspec_file(dir), version_file(dir), File.join(dir, "Gemfile.lock")]
+              .select { |f| File.exist?(f) }
+      @runner.run(["git", "add", *files], chdir: dir)
+
+      message = if step[:dependency]
+                  "Cascade: #{step[:dependency]} #{step[:constraint]} (gemchain)"
+                else
+                  "Bump to #{version} (gemchain)"
+                end
+      @runner.run(["git", "commit", "-m", message], chdir: dir)
+
+      @runner.run(["gem", "build", "#{name}.gemspec"], chdir: dir)
+      @runner.run(["gem", "push", "#{name}-#{version}.gem"], chdir: dir)
+      @runner.run(["git", "tag", "v#{version}"], chdir: dir)
+      @runner.run(["git", "push", "origin", "HEAD", "--tags"], chdir: dir)
+    end
+
+    # Dependents get an automatic version bump (they're being re-released
+    # with a tightened constraint); the source gem's version comes from the
+    # :bump step.
+    def bump_dependent(dir, name)
+      gem = @workspace.find(name)
+      raise ExecutionError, "Gem '#{name}' not found in workspace" unless gem
+
+      new_version = bump_number(gem.version.to_s, @bump)
+      bump_version(dir, new_version)
+      new_version
+    end
+
+    def bump_number(version, level)
+      parts = version.split(".").map(&:to_i)
+      case level
+      when :major then "#{parts[0] + 1}.0.0"
+      when :minor then "#{parts[0]}.#{parts[1] + 1}.0"
+      else "#{parts[0]}.#{parts[1]}.#{(parts[2] || 0) + 1}"
+      end
+    end
+
+    # ── confirmation ──
+
+    def release_confirmed?(step)
+      return true if @yes
+      return @confirm.call("Release #{step[:gem]}?") if @confirm
+
+      @output.print "  Release #{step[:gem]} to RubyGems? [y/N] "
+      $stdin.gets&.strip&.match?(/\Ay(es)?\z/i) || false
+    end
+  end
+end

data/lib/gemchain/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Gemchain
+  VERSION = "0.2.0"
+end

data/lib/gemchain/workspace.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Gemchain
+  class GemInfo
+    attr_reader :name, :version_string, :path, :dependency_map
+
+    def initialize(name:, version:, path:, dependencies: {})
+      @name = name
+      @version_string = version
+      @path = path
+      @dependency_map = dependencies
+    end
+
+    def version
+      Gem::Version.new(@version_string)
+    end
+
+    def dependencies
+      @dependency_map
+    end
+  end
+
+  class Workspace
+    attr_reader :gems, :graph, :config
+
+    def initialize(config)
+      @config = config
+      @gems = load_gems
+      @graph = DependencyGraph.new(@gems)
+    end
+
+    def dependents_of(gem_name)
+      @graph.dependents_of(gem_name)
+    end
+
+    def dependencies_of(gem_name)
+      @graph.dependencies_of(gem_name)
+    end
+
+    def cascade_order(start_gem = nil)
+      @graph.cascade_order(start_gem)
+    end
+
+    def find(name)
+      @gems.find { |g| g.name == name }
+    end
+
+    # All gems that directly or transitively depend on +gem_name+.
+    def transitive_dependents(gem_name)
+      @graph.transitive_dependents(gem_name)
+    end
+
+    private
+
+    def load_gems
+      @config.gem_dirs.filter_map do |dir|
+        gemspec_path = Dir.glob(File.join(dir, "*.gemspec")).first
+        next unless gemspec_path
+
+        spec = Gem::Specification.load(gemspec_path)
+        next unless spec
+
+        GemInfo.new(
+          name: spec.name,
+          version: spec.version.to_s,
+          path: dir,
+          dependencies: runtime_dependencies(spec)
+        )
+      end
+    end
+
+    def runtime_dependencies(spec)
+      deps = {}
+      spec.dependencies.each do |dep|
+        next if dep.type == :development
+        deps[dep.name] = dep.requirement.to_s
+      end
+      deps
+    end
+  end
+end

data/lib/gemchain.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Gemchain
+  class Error < StandardError; end
+end
+
+require_relative "gemchain/version"
+require_relative "gemchain/config"
+require_relative "gemchain/dependency_graph"
+require_relative "gemchain/workspace"
+require_relative "gemchain/cascade"
+require_relative "gemchain/executor"
+require_relative "gemchain/cli"

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: gemchain
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: When you maintain multiple gems that depend on each other, Gemchain helps
+  you coordinate releases. It warns you before releasing a gem that others depend
+  on, and can cascade updates through the dependency chain — updating constraints,
+  running tests, and releasing each dependent gem in order.
+email:
+- kaka@myrrlabs.com
+executables:
+- gemchain
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/gemchain
+- lib/gemchain.rb
+- lib/gemchain/cascade.rb
+- lib/gemchain/cli.rb
+- lib/gemchain/config.rb
+- lib/gemchain/dependency_graph.rb
+- lib/gemchain/executor.rb
+- lib/gemchain/version.rb
+- lib/gemchain/workspace.rb
+homepage: https://github.com/ask-rb/gemchain
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/gemchain
+  source_code_uri: https://github.com/ask-rb/gemchain
+  changelog_uri: https://github.com/ask-rb/gemchain/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Cascade gem updates through interdependent gem ecosystems
+test_files: []