dev_context 1.0.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 230f85766b6c9c36e855be5be7db4b6c395e813a392d7a4bb55f8f9e5ae43917
-  data.tar.gz: f5fe1a5d23f665c60c2e62f44239ca74bf058bd6eadcb1b93cadccb35c0a6f36
+  metadata.gz: a909bb66276763e6e8cf92b56a703f63a7a81637977dd4e2c2ac6a2495ac6a0f
+  data.tar.gz: dbf0c96d8324235871af7ffda020f761287d66c980d7d34ae58082c7018ebffa
 SHA512:
-  metadata.gz: e9bef6e3ecd74e07c89c15e374c414dca442d45947da635d97df64a716949f05fdd0b25b6a4ab6090e5f8f057bf3bd89b60498cca2e7d9cef2ef0be2146d42b1
-  data.tar.gz: d067ebfeb63297953a98452856d853771d2c4d8e0589b00643a007cc70a5ef5b28ccbc4c9a3f1a289113710b0bb18a6e1471e31152d1ec94be17ba1bf80a76b8
+  metadata.gz: d6169e888f0c0d6ec0ad01828ccbf24f1e961616f7ff01d044c63b9bef40cccc03b131a6b77ddae3ad05161c0a6a105545d555ceeec3659c1c3ec43bbcbdb903
+  data.tar.gz: 45842d4f6b81a31a2323683313bf11772318e62c45a2ef5fa9df4fa80809cc8e83dfe3f167b4bfe036ae8fe48a6bd7768d89284206698bdd2d767de703055558

data/CHANGELOG.md

@@ -1,5 +1,47 @@
 ## [Unreleased]
 
+### Monorepo tooling (root-level)
+
+- Add `CLAUDE.md` with codebase guidance for Claude Code.
+- Add root `Gemfile` proxying to `implementations/ruby/` via `eval_gemfile` so `bundle install` works from repo root.
+- Add root `.rspec` and `spec/` symlinks so `bundle exec rspec` works from repo root without `cd`.
+- Add `ruby-bundle-ready` Makefile prerequisite so `test-ruby`, `install-ruby`, and `release-ruby` ensure Bundler state before running.
+
+## [2.0.1] - 2026-06-25
+
+- cleaned up erb and updated psych gems to avoid ARM crash on an older version of psych.
+
+## [2.0.0] - 2026-06-23
+
+### Added
+
+- Add `dx import` to ingest shell dirstack into `dx` active stack and resynchronize shell stack via eval script.
+- Add optional auto-reconcile gate via `DX_AUTO_IMPORT_SHELL_STACK=true` for stateful commands (`activate|cd`, `pushd`, `popd`).
+- Add shell wrapper transport of live dirstack via `DX_SHELL_STACK` for wrapped stack-aware commands.
+- Add end-to-end coverage in `bash` and `zsh` for mixed shell/dx dirstack mutations and reconciliation.
+
+### Changed
+
+- Strengthen `dx`/shell stack interoperability so manual shell `pushd`/`popd` changes can be reconciled by `dx import`.
+- Extend wrapped command handling in shell integration to include `import`.
+
+### Breaking Changes
+
+- Shell integration semantics now include dirstack payload transport (`DX_SHELL_STACK`) and `import` in wrapped eval paths.
+- Users relying on previous loose coupling between shell dirstack and `dx` active stack should treat this release as a behavior-boundary change.
+
+### Migration Notes
+
+- Run `dx init` and re-source `~/.dx.sh` after upgrading.
+- Use `dx import` to reconcile shell stack changes into `dx` state on demand.
+- Enable `DX_AUTO_IMPORT_SHELL_STACK=true` only if you want reconciliation to happen automatically before stateful `dx` commands.
+
+## [1.1.0] - 2026-05-15
+
+- Add `dx doctor` diagnostics command with `dx check` alias.
+- Add shell integration version marker in `~/.dx.sh` and doctor warning for stale shell script versions.
+- Complete `CLI` modularization by extracting remaining command and support logic into command modules.
+
 ## [0.1.0] - 2026-05-01
 
 - Initial release

data/README.md

@@ -2,19 +2,26 @@
 
 This repo contains `dx` (`dev_context`), a script for managing developer context across repository directories and branches.
 
+> Note: this Ruby implementation now lives in `implementations/ruby` within the
+> multi-language `dev_context` monorepo.
+
 A context is one `(repo_dir, branch)` pair. Context names can be explicit, or implicit as `<repo_basename>:<branch>` (stored lowercase), and resolved with exact then FSF-style fuzzy matching.
 
 ## Installation
 
     gem install -n ~/bin dev_context
 
-Install the gem in the current ruby gem path, with the executable installed as `~/bin/dev_context.rb`.
+Install the gem in the current ruby gem path, with executables installed as:
+
+- `~/bin/dev_context` (launcher, honors `DX_IMPL`)
+- `~/bin/dev_context-rb` (Ruby implementation entrypoint)
+- `~/bin/dev_context-ruby` (legacy Ruby implementation alias)
 
 To clone from the github repo:
 
     cd ~/src/github    # or wherever you keep github repos
     git clone https://github.com/aks/dev_context.git
-    cd dev_context
+    cd dev_context/implementations/ruby
     bundle install
     bundle exec rake install
 
@@ -35,17 +42,28 @@ To support `cd`, `dx` should be wrapped by a shell function that evaluates shell
 
 ```bash
 dx() {
+  local bin
+  case "${DX_IMPL:-go}" in
+    go)
+      bin=dev_context-go ;;
+    ruby)
+      bin=dev_context-rb ;;
+    elixir)
+      bin=dev_context-ex ;;
+    *)
+      echo 1>&2 "No idea what $DX_IMPL means!" ; exit 1 ;;
+  esac
   case "$1" in
-    cd|activate|pushd|popd)
+    cd|activate|pushd|popd|pu|po)
       local out
-      out="$(DX_SHELL_WRAPPED=1 command dev_context.rb "$@")" || return $?
+      out="$(DX_SHELL_WRAPPED=1 command $bin "$@")" || return $?
       case "$out" in
         "# DX_SHELL_EVAL"*) eval "$out" ;;
         *) printf "%s\n" "$out" ;;
       esac
       ;;
     *)
-      command dev_context.rb "$@"
+      command $bin "$@"
       ;;
   esac
 }
@@ -81,8 +99,8 @@ dx create -v feature:abc-123 ~/src/github/dev_context feature/abc-123
 
 ### Context stack commands
 
-- `dx pushd CONTEXT|PATH|URL`: activate and push context to top of stack
-- `dx popd [CONTEXT]`: pop the top context (or a specific one); if a new top exists, switch CWD to it
+- `dx pushd [CONTEXT|PATH|URL|+N|-N]`: activate/push context, or rotate indexed stack entry to top
+- `dx popd [CONTEXT|+N|-N]`: pop selected entry; with no args, same as `dx popd +0`
 
 ### `DX_PATH` repo lookup
 
@@ -144,8 +162,8 @@ dx active
 dx activate CONTEXT|PATH|URL
 dx cd CONTEXT|PATH|URL
 dx deactivate CONTEXT
-dx pushd CONTEXT|PATH|URL
-dx popd [CONTEXT]
+dx pushd [CONTEXT|PATH|URL|+N|-N]
+dx popd [CONTEXT|+N|-N]
 dx status|wip [--all] [--dirty] [-b BRANCHPATTERN] [-p PATHPATTERN]
 dx repos [-b BRANCHPATTERN] [-p PATHPATTERN] [PATTERN]
 dx stashes [--list] [PATTERN]

data/bin/dev_context

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/dev_context"
+
+selected_impl = ENV["DX_IMPL"].to_s.strip.downcase
+selected_impl = "ruby" if selected_impl.empty?
+
+if %w[--version -V version].include?(ARGV.first)
+  if selected_impl == "ruby"
+    exit DevContext::CLI.run(ARGV)
+  end
+
+  candidate = "dev_context-#{selected_impl}"
+  begin
+    exec(candidate, *ARGV)
+  rescue Errno::ENOENT
+    warn("dx: selected implementation '#{selected_impl}' is not installed on PATH")
+    warn("dx: expected executable: #{candidate}")
+    warn("dx: set DX_IMPL=ruby or install #{candidate}")
+    exit 127
+  end
+end
+if selected_impl == "ruby"
+  exit DevContext::CLI.run(ARGV)
+end
+
+candidate = "dev_context-#{selected_impl}"
+begin
+  exec(candidate, *ARGV)
+rescue Errno::ENOENT
+  warn("dx: selected implementation not found on PATH: #{candidate}")
+  warn("dx: set DX_IMPL=ruby or install #{candidate}")
+  exit 127
+end

data/bin/dev_context-ruby

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/dev_context"
+
+exit DevContext::CLI.run(ARGV)

data/lib/dev_context/cli.rb

@@ -12,6 +12,7 @@ module DevContext
     include Commands::Support
     include Commands::ContextLifecycle
     include Commands::GitOps
+    include Commands::Doctor
     include Commands::SearchHelpers
     include Commands::Find
     include Commands::Repos
@@ -27,16 +28,17 @@ module DevContext
     COLOR_YELLOW = "\e[33m"
     COLOR_MAGENTA = "\e[35m"
 
-    def self.run(argv, out: $stdout, err: $stderr, env: ENV, pwd: Dir.pwd)
-      new(argv, out: out, err: err, env: env, pwd: pwd).run
+    def self.run(argv, out: $stdout, err: $stderr, env: ENV, pwd: Dir.pwd, stdin: STDIN)
+      new(argv, out: out, err: err, env: env, pwd: pwd, stdin: stdin).run
     end
 
-    def initialize(argv, out:, err:, env:, pwd:)
+    def initialize(argv, out:, err:, env:, pwd:, stdin: STDIN)
       @argv = argv.dup
       @out = out
       @err = err
       @env = env
       @pwd = pwd
+      @stdin = stdin
       @config = Config.new
       @matcher = Matcher.new(config: @config)
     end
@@ -45,6 +47,7 @@ module DevContext
       raw_command = argv.shift
 
       return default_action if raw_command.nil?
+      raw_command = "version" if %w[--version -V].include?(raw_command)
 
       resolution = resolve_command(raw_command)
       command = resolution[:command]
@@ -61,24 +64,31 @@ module DevContext
         return cmd_help_topic(command)
       end
 
+      maybe_auto_import_shell_stack!(command)
+
       case command
-      when "init" then cmd_init
-      when "help", "--help", "-h" then cmd_help
-      when "add" then cmd_add
-      when "clone" then cmd_clone
-      when "create" then cmd_create
-      when "remove" then cmd_remove
-      when "active" then cmd_active
-      when "deactivate" then cmd_deactivate
-      when "find" then cmd_find
-      when "stashes" then cmd_stashes
-      when "repos" then cmd_repos
-      when "status", "wip" then cmd_status(mode: command)
-      when "diff" then cmd_diff
-      when "branches", "br" then cmd_branches
-      when "co", "checkout" then cmd_checkout
-      when "cd", "activate", "pushd" then cmd_activate
-      when "popd" then cmd_pop
+      when "version"                 then cmd_version
+      when "init"                    then cmd_init
+      when "help", "--help", "-h"    then cmd_help
+      when "add"                     then cmd_add
+      when "clone"                   then cmd_clone
+      when "create"                  then cmd_create
+      when "remove"                  then cmd_remove
+      when "active"                  then cmd_active
+      when "deactivate"              then cmd_deactivate
+      when "doctor", "check"         then cmd_doctor
+      when "find"                    then cmd_find
+      when "import"                  then cmd_import
+      when "stash"                   then cmd_stash
+      when "stashes"                 then cmd_stashes
+      when "repos"                   then cmd_repos
+      when "status", "wip"           then cmd_status(mode: command)
+      when "diff"                    then cmd_diff
+      when "branches", "br"          then cmd_branches
+      when "co", "checkout"          then cmd_checkout
+      when "pushd"                   then cmd_push
+      when "cd", "activate"          then cmd_activate
+      when "popd"                    then cmd_pop
       else
         err.puts("dx: unknown command '#{raw_command}'")
         cmd_help
@@ -88,16 +98,31 @@ module DevContext
 
     private
 
-    attr_reader :argv, :out, :err, :env, :pwd, :config, :matcher
+    attr_reader :argv, :out, :err, :env, :pwd, :stdin, :config, :matcher
 
     COMMANDS = %w[
-      init help add clone create remove active deactivate find repos stashes status wip diff branches br co checkout cd activate pushd popd
+      version init help add clone create remove active deactivate doctor check find repos stash stashes status wip diff branches br co checkout cd activate pushd popd import
     ].freeze
 
+    STATEFUL_COMMANDS = %w[activate cd pushd popd].freeze
+
     def default_action
       return cmd_init unless config.initialized?
 
       cmd_status
     end
+
+    def cmd_version
+      out.puts("dx #{DevContext::VERSION} (impl: ruby)")
+      0
+    end
+
+    def maybe_auto_import_shell_stack!(command)
+      return unless STATEFUL_COMMANDS.include?(command)
+      return unless truthy?(env.fetch("DX_AUTO_IMPORT_SHELL_STACK", "false"))
+      return unless shell_stack_imbalanced?
+
+      cmd_import(emit_script: false)
+    end
   end
 end

data/lib/dev_context/commands/context_lifecycle.rb

@@ -70,7 +70,8 @@ module DevContext
         script = ShellEmitter.new(
           context: context,
           remote_name: env.fetch("DX_GIT_REMOTE_NAME", "USE-REPO"),
-          auto_create_local_branch: truthy?(env.fetch("DX_AUTO_CREATE_LOCAL_BRANCH", "true"))
+          auto_create_local_branch: truthy?(env.fetch("DX_AUTO_CREATE_LOCAL_BRANCH", "true")),
+          stack_paths: config.active_contexts.map { |ctx| ctx.fetch("repo_path") }
         ).activation_script
         out.write(script)
         0

data/lib/dev_context/commands/doctor.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+require "open3"
+
+module DevContext
+  module Commands
+    module Doctor
+      def cmd_doctor
+        return usage_error("dx doctor") unless argv.empty?
+
+        checks = []
+        checks.concat(shell_integration_checks)
+        checks.concat(config_structure_checks)
+        checks.concat(repo_integrity_checks)
+        checks.concat(environment_checks)
+
+        label_w = [checks.map { |c| c[:label].length }.max || 0, "Check".length].max
+        state_w = [checks.map { |c| c[:state].length }.max || 0, "State".length].max
+
+        out.puts(format("%-#{state_w}s  %-#{label_w}s  %s", "State", "Check", "Message"))
+        out.puts(format("%-#{state_w}s  %-#{label_w}s  %s", "-" * state_w, "-" * label_w, "-" * 7))
+        checks.each do |check|
+          out.puts(format("%-#{state_w}s  %-#{label_w}s  %s", check[:state], check[:label], check[:message]))
+        end
+
+        failures = checks.count { |c| c[:state] == "FAIL" }
+        warnings = checks.count { |c| c[:state] == "WARN" }
+        out.puts
+        out.puts("doctor summary: #{checks.length} checks, #{failures} failures, #{warnings} warnings")
+
+        failures.zero? ? 0 : 1
+      end
+
+      private
+
+      def shell_integration_checks
+        checks = []
+        shell_path = env.fetch("DX_SHELL_PATH", ShellSetup::DEFAULT_PATH)
+        if File.exist?(shell_path)
+          content = File.read(shell_path)
+          if content.include?(ShellSetup::MANAGED_MARKER)
+            checks << ok_check("shell-script", "Found managed shell integration at #{shell_path}")
+            shell_version = extract_shell_script_version(content)
+            if shell_version.nil?
+              checks << warn_check("shell-version", "Managed shell integration is missing version marker")
+            elsif shell_version == DevContext::SHELL_VERSION
+              checks << ok_check("shell-version", "Shell integration matches shell version #{DevContext::SHELL_VERSION}")
+            else
+              checks << warn_check("shell-version", "Shell integration is #{shell_version}; current shell version is #{DevContext::SHELL_VERSION} (run `dx init`)")
+            end
+          else
+            checks << warn_check("shell-script", "Shell file exists but is unmanaged: #{shell_path}")
+          end
+        else
+          checks << fail_check("shell-script", "Shell integration file missing: #{shell_path} (run `dx init`)")
+        end
+        checks
+      end
+
+      def config_structure_checks
+        checks = []
+        if config.initialized?
+          checks << ok_check("config-file", "Config file exists at #{config.path}")
+        else
+          checks << fail_check("config-file", "Config file missing at #{config.path} (run `dx init`)")
+          return checks
+        end
+
+        active_missing = config.active_stack.reject { |name| config.contexts.key?(name) }
+        if active_missing.empty?
+          checks << ok_check("active-stack", "Active stack entries map to known contexts")
+        else
+          checks << fail_check("active-stack", "Active stack has missing contexts: #{active_missing.join(', ')}")
+        end
+        checks
+      end
+
+      def repo_integrity_checks
+        paths = config.repos.values.map { |repo| repo["path"] }.compact.uniq
+        return [warn_check("known-repos", "No known repos in config")] if paths.empty?
+
+        missing = []
+        non_git = []
+        paths.each do |path|
+          expanded = File.expand_path(path)
+          unless File.directory?(expanded)
+            missing << expanded
+            next
+          end
+          non_git << expanded unless git_repo?(expanded)
+        end
+
+        checks = []
+        if missing.empty?
+          checks << ok_check("repo-paths", "All known repo paths exist")
+        elsif fixture_mode?
+          checks << warn_check("repo-paths", "Fixture mode enabled; ignoring missing repo paths: #{missing.join(', ')}")
+        else
+          checks << fail_check("repo-paths", "Missing repo paths: #{missing.join(', ')}")
+        end
+
+        if non_git.empty?
+          checks << ok_check("git-repos", "All existing known repos are git repos")
+        else
+          checks << warn_check("git-repos", "Non-git known paths: #{non_git.join(', ')}")
+        end
+        checks
+      end
+
+      def environment_checks
+        checks = []
+
+        found_exec = command_success?("sh", "-lc", "command -v dev_context >/dev/null 2>&1")
+        if found_exec
+          checks << ok_check("executable", "`dev_context` is on PATH")
+          if command_success?("dev_context", "help")
+            checks << ok_check("executable-run", "`dev_context help` executes successfully")
+          else
+            checks << warn_check("executable-run", "`dev_context` found but failed to execute `help`")
+          end
+        else
+          checks << warn_check("executable", "`dev_context` not found on PATH")
+        end
+
+        dx_path_raw = env["DX_PATH"]
+        if dx_path_raw.to_s.strip.empty?
+          checks << warn_check("DX_PATH", "DX_PATH is not set")
+        else
+          roots = dx_path_raw.split(/[:;]/).flat_map { |entry| Dir.glob(File.expand_path(entry.to_s.strip)) }.uniq
+          dirs = roots.select { |entry| File.directory?(entry) }
+          if dirs.empty?
+            checks << warn_check("DX_PATH", "No valid directories resolved from DX_PATH")
+          else
+            checks << ok_check("DX_PATH", "Resolved #{dirs.length} directory root(s)")
+          end
+        end
+
+        checks
+      end
+
+      def ok_check(label, message)
+        { state: "OK", label: label, message: message }
+      end
+
+      def warn_check(label, message)
+        { state: "WARN", label: label, message: message }
+      end
+
+      def fail_check(label, message)
+        { state: "FAIL", label: label, message: message }
+      end
+
+      def extract_shell_script_version(content)
+        escaped = Regexp.escape(ShellSetup::VERSION_MARKER_PREFIX)
+        match = content.match(/^\s*#\s*#{escaped}\s+(.+?)\s*$/)
+        return nil unless match
+
+        match[1]
+      end
+
+      def command_success?(*cmd)
+        _out, status = Open3.capture2e(env.to_h, *cmd)
+        status.success?
+      rescue StandardError
+        false
+      end
+
+      def fixture_mode?
+        value = env.fetch("DX_DOCTOR_FIXTURE_MODE", "")
+        %w[1 true yes on].include?(value.to_s.strip.downcase)
+      end
+    end
+  end
+end

data/lib/dev_context/commands/git_ops.rb

@@ -3,6 +3,17 @@
 module DevContext
   module Commands
     module GitOps
+      def cmd_import(emit_script: true)
+        imported_paths = parsed_shell_stack_paths
+        imported_contexts = import_contexts_for_paths(imported_paths)
+        config.active_stack.replace(imported_contexts.map { |ctx| ctx.fetch("name") })
+        config.send(:save!)
+        return 0 unless emit_script
+
+        out.write(stack_sync_script_for_active_contexts)
+        0
+      end
+
       def cmd_active
         active = config.active_contexts
         if active.empty?
@@ -29,8 +40,35 @@ module DevContext
         0
       end
 
+      def cmd_push
+        target = argv.shift
+        return usage_error("dx pushd [CONTEXT|+N|-N]") unless argv.empty?
+
+        if target&.match?(/\A[+-]\d+\z/)
+          return rotate_active_stack_to(target)
+        end
+
+        return usage_error("dx pushd [CONTEXT|+N|-N]") if blank?(target)
+
+        context, code = resolve_or_create_context(target)
+        return code unless code.zero?
+
+        config.activate_context!(context.fetch("name"))
+        script = ShellEmitter.new(
+          context: context,
+          remote_name: env.fetch("DX_GIT_REMOTE_NAME", "USE-REPO"),
+          auto_create_local_branch: truthy?(env.fetch("DX_AUTO_CREATE_LOCAL_BRANCH", "true")),
+          stack_paths: config.active_contexts.map { |ctx| ctx.fetch("repo_path") }
+        ).activation_script
+        out.write(script)
+        0
+      end
+
       def cmd_pop
         target = argv.shift
+        return usage_error("dx popd [CONTEXT|+N|-N]") unless argv.empty?
+        return pop_by_stack_index("+0") if target.nil?
+        return pop_by_stack_index(target) if target.match?(/\A[+-]\d+\z/)
 
         if target
           context = matcher.resolve(target)
@@ -39,7 +77,7 @@ module DevContext
           removed = config.deactivate_context!(context.fetch("name"))
           return not_found(target) unless removed
 
-          out.puts("Popped #{context.fetch('name')}")
+          print_pop_message("Popped #{context.fetch('name')}")
         else
           top_name = config.active_stack.first
           if top_name.nil?
@@ -49,13 +87,10 @@ module DevContext
 
           context = config.contexts.fetch(top_name)
           config.deactivate_context!(top_name)
-          out.puts("Popped #{context.fetch('name')}")
+          print_pop_message("Popped #{context.fetch('name')}")
         end
 
-        new_top = config.active_contexts.first
-        return 0 unless new_top
-
-        out.puts("cd #{Shellwords.escape(new_top.fetch('repo_path'))}")
+        out.write(stack_sync_script_for_active_contexts)
         0
       end
 
@@ -158,6 +193,142 @@ module DevContext
         out.puts("Checked out #{feature} in #{context_name}")
         0
       end
+
+      private
+
+      def parsed_shell_stack_paths
+        seen = {}
+        env.fetch("DX_SHELL_STACK", "")
+          .lines
+          .map(&:strip)
+          .reject(&:empty?)
+          .map { |path| File.expand_path(path, pwd) }
+          .select { |path| git_repo?(path) }
+          .reject do |path|
+            already_seen = seen[path]
+            seen[path] = true
+            already_seen
+          end
+      end
+
+      def import_contexts_for_paths(paths)
+        paths.map do |repo_path|
+          branch = current_branch(repo_path) || "main"
+          context = config.contexts.values.find { |ctx| ctx["repo_path"] == repo_path && ctx["branch"] == branch } ||
+                    config.contexts.values.find { |ctx| ctx["repo_path"] == repo_path }
+          unless context
+            name = implicit_context_name(repo_path, branch)
+            context_name = ensure_unique_import_context_name(name, repo_path, branch)
+            config.add_context(name: context_name, repo_path: repo_path, branch: branch)
+            context = config.get_context(context_name)
+          end
+          context
+        end.compact
+      end
+
+      def ensure_unique_import_context_name(base_name, repo_path, branch)
+        existing = config.contexts[base_name]
+        return base_name unless existing
+        return base_name if existing["repo_path"] == repo_path && existing["branch"] == branch
+
+        suffix = 2
+        loop do
+          candidate = "#{base_name}-#{suffix}"
+          match = config.contexts[candidate]
+          return candidate unless match
+          return candidate if match["repo_path"] == repo_path && match["branch"] == branch
+
+          suffix += 1
+        end
+      end
+
+      def shell_stack_imbalanced?
+        parsed_shell_stack_paths != config.active_contexts.map { |ctx| File.expand_path(ctx.fetch("repo_path")) }
+      end
+
+      def rotate_active_stack_to(token)
+        stack = config.active_stack
+        return no_active_contexts if stack.empty?
+
+        idx = parse_stack_index_token(token, stack.length)
+        if idx.nil?
+          err.puts("dx: invalid stack index '#{token}'")
+          return 2
+        end
+
+        context_name = stack[idx]
+        context = config.contexts[context_name]
+        unless context
+          err.puts("dx: active stack entry is missing context: #{context_name}")
+          return 1
+        end
+
+        config.active_stack.replace(stack.rotate(idx))
+        config.send(:save!)
+        script = ShellEmitter.new(
+          context: context,
+          remote_name: env.fetch("DX_GIT_REMOTE_NAME", "USE-REPO"),
+          auto_create_local_branch: truthy?(env.fetch("DX_AUTO_CREATE_LOCAL_BRANCH", "true")),
+          stack_paths: config.active_contexts.map { |ctx| ctx.fetch("repo_path") }
+        ).activation_script
+        out.write(script)
+        0
+      end
+
+      def pop_by_stack_index(token)
+        stack = config.active_stack
+        return no_active_contexts if stack.empty?
+
+        idx = parse_stack_index_token(token, stack.length)
+        if idx.nil?
+          err.puts("dx: invalid stack index '#{token}'")
+          return 2
+        end
+
+        context_name = stack.delete_at(idx)
+        context = config.contexts[context_name]
+        config.send(:save!)
+        print_pop_message("Popped #{context ? context.fetch('name') : context_name}")
+        out.write(stack_sync_script_for_active_contexts)
+        0
+      end
+
+      def parse_stack_index_token(token, stack_size)
+        return nil unless token.match?(/\A[+-]\d+\z/)
+
+        n = token[1..].to_i
+        idx = token.start_with?("+") ? n : (stack_size - 1 - n)
+        return nil if idx.negative? || idx >= stack_size
+
+        idx
+      end
+
+      def no_active_contexts
+        out.puts("No active contexts")
+        0
+      end
+
+      def stack_sync_script_for_active_contexts
+        paths = config.active_contexts.map { |ctx| File.expand_path(ctx.fetch("repo_path")) }
+        script = +"#{ShellEmitter::SCRIPT_MARKER}\n"
+        script << "dirs -c >/dev/null 2>&1 || true\n"
+        return script if paths.empty?
+
+        script << "cd #{Shellwords.escape(paths.first)}\n"
+        paths.drop(1).each do |path|
+          script << "pushd #{Shellwords.escape(path)} >/dev/null 2>&1\n"
+          script << "pushd +1 >/dev/null 2>&1\n"
+        end
+        script
+      end
+
+      def print_pop_message(message)
+        if env["DX_SHELL_WRAPPED"] == "1"
+          err.puts(message)
+        else
+          out.puts(message)
+        end
+      end
     end
   end
 end

data/lib/dev_context/commands/help.rb

@@ -25,17 +25,21 @@ module DevContext
             dx checkout|co [-b] FEATURE [CONTEXT]
             dx clone URL [PATH]
             dx create NAME [PATH] [BRANCH]
+            dx doctor|check
             dx deactivate CONTEXT
             dx diff [CONTEXT]
             dx find [--stashes|--branches|--paths] <pattern>
             dx find --all
             dx <pattern>  # shorthand for: dx find <pattern>
             dx help
-            dx init
-            dx popd [CONTEXT]
-            dx pushd CONTEXT|PATH|URL
+            dx init [ruby|go|elixir]
+            dx import
+            dx version
+            dx popd [CONTEXT|+N|-N]
+            dx pushd [CONTEXT|PATH|URL|+N|-N]
             dx repos [PATTERN]
             dx remove CONTEXT|PATH
+            dx stash [--list] [--all|-a] [PATTERN]
             dx stashes [--list] [PATTERN]
             dx status|wip
         HELP
@@ -48,20 +52,32 @@ module DevContext
                  "Usage: dx status [--all] [--dirty] [-b BRANCHPATTERN] [-p PATHPATTERN]\n       dx wip [--all] [--dirty] [-b BRANCHPATTERN] [-p PATHPATTERN]\n\nShow branch and git status for active contexts. Use --all for all known repos, --dirty to filter non-clean repos, and -b/-p to filter by branch/path."
                when "repos"
                  "Usage: dx repos [-b BRANCHPATTERN] [-p PATHPATTERN] [PATTERN]\n\nList all known repos without git status details. PATTERN is shorthand for path filtering."
+               when "stash"
+                 "Usage: dx stash [--list] [--all|-a] [PATTERN]\n\nShow stashes for the active top context by default. Use --all/-a to scan all known repos. Provide PATTERN to filter stash titles; use --list to print matching entries."
                when "stashes"
                  "Usage: dx stashes [--list] [PATTERN]\n\nShow repos with stashes. Provide PATTERN to filter stash titles; use --list to print matching entries."
                when "find"
                  "Usage: dx find [--stashes|--branches|--paths] <pattern>\n       dx find --all\n\nSearch stash titles, branches, and repo paths. Use --all to show likely-forgotten work."
+               when "doctor", "check"
+                 "Usage: dx doctor\n       dx check\n\nRun environment and config diagnostics."
+               when "init"
+                 "Usage: dx init [ruby|go|elixir]\n\nInitialize dx files. If IMPL is given, set DX_IMPL non-interactively."
+               when "version"
+                 "Usage: dx version\n       dx --version\n       dx -V\n\nPrint the active dx implementation and version."
                when "add"
                  "Usage: dx add [-c NAME] [-n] [-v] PATH|URL ..."
                when "clone"
                  "Usage: dx clone [-c NAME] [-n] [-v] URL [PATH]"
                when "create"
                  "Usage: dx create [-c NAME] [-n] [-v] NAME [PATH] [BRANCH]"
-               when "activate", "cd", "pushd"
+               when "activate", "cd"
                  "Usage: dx #{command} CONTEXT|PATH|URL"
+               when "pushd"
+                 "Usage: dx pushd [CONTEXT|PATH|URL|+N|-N]\n\nCONTEXT accepts exact or fuzzy-matched context names. PATH and URL resolve/create contexts. +N/-N select existing active-stack entries (+0 top/left, -0 bottom/right) and rotate that entry to top."
                when "popd"
-                 "Usage: dx popd [CONTEXT]"
+                 "Usage: dx popd [CONTEXT|+N|-N]\n\nWith no args, same as `dx popd +0`. CONTEXT accepts exact or fuzzy-matched context names. +N counts from top/left (+0 top), -N from bottom/right (-0 bottom)."
+               when "import"
+                 "Usage: dx import\n\nImport shell dirstack into dx active_stack (deduped by absolute path) and emit shell sync script."
                when "remove"
                  "Usage: dx remove CONTEXT|PATH"
                when "diff"

data/lib/dev_context/commands/init.rb

@@ -4,6 +4,13 @@ module DevContext
   module Commands
     module Init
       def cmd_init
+        explicit_impl = argv.shift
+        return usage_error("dx init [ruby|go|elixir]") unless argv.empty?
+        if explicit_impl && !valid_impl?(explicit_impl)
+          err.puts("dx: unknown implementation '#{explicit_impl}'")
+          return usage_error("dx init [ruby|go|elixir]")
+        end
+
         created = config.init!
         shell_status = ShellSetup.new.install!
 
@@ -15,8 +22,61 @@ module DevContext
                         end
         out.puts(shell_message)
         out.puts('Add `source ~/.dx.sh` to ~/.zshrc or ~/.bashrc')
+        impl = if explicit_impl
+                 explicit_impl.downcase
+               elsif stdin.tty?
+                 prompt_dx_impl
+               end
+        if impl
+          updated_files = persist_dx_impl_choice(impl)
+          out.puts("Set DX_IMPL=#{impl} in #{updated_files.join(', ')}")
+        end
         0
       end
+
+      private
+
+      def prompt_dx_impl
+        out.print("Choose DX implementation [ruby/go/elixir] (default: ruby): ")
+        raw = stdin.gets.to_s.strip.downcase
+        return "ruby" if raw.empty?
+        return raw if valid_impl?(raw)
+
+        err.puts("dx: unknown implementation '#{raw}', defaulting to ruby")
+        "ruby"
+      end
+
+      def valid_impl?(value)
+        %w[ruby go elixir].include?(value.to_s.strip.downcase)
+      end
+
+      def persist_dx_impl_choice(choice)
+        home = env.fetch("HOME", File.expand_path("~"))
+        zshrc = File.join(home, ".zshrc")
+        bashrc = File.join(home, ".bashrc")
+        preferred = env.fetch("SHELL", "").include?("bash") ? bashrc : zshrc
+        existing = [zshrc, bashrc].select { |path| File.exist?(path) }
+        targets = existing.empty? ? [preferred] : existing
+
+        targets.each { |path| write_dx_impl_to_rc(path, choice) }
+        targets
+      end
+
+      def write_dx_impl_to_rc(path, choice)
+        line = "export DX_IMPL=#{choice}"
+        current = File.exist?(path) ? File.read(path) : ""
+        updated =
+          if current.match?(/^\s*(?:export\s+)?DX_IMPL=.*$/)
+            current.gsub(/^\s*(?:export\s+)?DX_IMPL=.*$/, line)
+          elsif current.empty?
+            "#{line}\n"
+          elsif current.end_with?("\n")
+            "#{current}#{line}\n"
+          else
+            "#{current}\n#{line}\n"
+          end
+        File.write(path, updated)
+      end
     end
   end
 end

data/lib/dev_context/commands/stashes.rb

@@ -3,6 +3,41 @@
 module DevContext
   module Commands
     module Stashes
+      def cmd_stash
+        args = argv.dup
+        show_list = false
+        all = false
+        parser = OptionParser.new
+        parser.on("-l", "--list", "Show stash entry titles per repo") { show_list = true }
+        parser.on("-a", "--all", "Show stashes across all known repos") { all = true }
+        parser.parse!(args)
+        pattern = args.shift
+        return usage_error("dx stash [--list] [--all|-a] [PATTERN]") unless args.empty?
+
+        rows = if all
+                 known_repo_stash_rows(pattern: pattern)
+               else
+                 active_top_stash_rows(pattern: pattern)
+               end
+        if rows.empty?
+          out.puts("No repos with stashes")
+          return 0
+        end
+
+        render_stash_table(rows)
+        return 0 unless show_list
+
+        out.puts
+        rows.each do |row|
+          out.puts("#{display_path(row[:path])}:")
+          row[:entries].each { |entry| out.puts("  - #{entry}") }
+        end
+        0
+      rescue OptionParser::InvalidOption => e
+        err.puts("dx: #{e.message}")
+        usage_error("dx stash [--list] [--all|-a] [PATTERN]")
+      end
+
       def cmd_stashes
         args = argv.dup
         show_list = false
@@ -34,6 +69,26 @@ module DevContext
 
       private
 
+      def active_top_stash_rows(pattern: nil)
+        context = config.active_contexts.first
+        return [] unless context
+
+        path = context["repo_path"]
+        expanded = File.expand_path(path)
+        return [] unless File.directory?(expanded)
+
+        entries = stash_entries(expanded)
+        entries = entries.select { |entry| pattern_match?(entry, pattern) } if pattern
+        return [] if entries.empty?
+
+        [{
+          path: expanded,
+          branch: current_branch(expanded) || "-",
+          count: entries.length,
+          entries: entries
+        }]
+      end
+
       def render_stash_table(rows)
         display_rows = rows.map { |row| row.merge(path: display_path(row[:path])) }
         path_w = [display_rows.map { |r| r[:path].length }.max || 0, "Path".length].max

data/lib/dev_context/commands/support.rb

@@ -280,8 +280,9 @@ module DevContext
       end
 
       def render_status_table(rows)
-        display_rows = rows.map do |row|
-          row.merge(path: display_path(row[:path]))
+        display_rows = rows.each_with_index.map do |row, idx|
+          indexed_path = "[#{idx}] #{display_path(row[:path])}"
+          row.merge(path: indexed_path)
         end
 
         path_w = [display_rows.map { |r| r[:path].length }.max || 0, "Path".length].max

data/lib/dev_context/shell_emitter.rb

@@ -6,10 +6,11 @@ module DevContext
   class ShellEmitter
     SCRIPT_MARKER = "# DX_SHELL_EVAL".freeze
 
-    def initialize(context:, remote_name:, auto_create_local_branch:)
+    def initialize(context:, remote_name:, auto_create_local_branch:, stack_paths: nil)
       @context = context
       @remote_name = remote_name
       @auto_create_local_branch = auto_create_local_branch
+      @stack_paths = Array(stack_paths).map { |path| File.expand_path(path) }
     end
 
     def activation_script
@@ -51,11 +52,25 @@ module DevContext
           git remote get-url #{forced_remote} >/dev/null 2>&1 || __dx_fail "dx: remote '#{forced_remote}' does not exist in this repo" 19
           git pull --ff-only --autostash #{forced_remote} #{branch} || __dx_fail "dx: pull failed from #{forced_remote}/#{branch} (you are already in the target repo for investigation)" 20
         fi
+        #{stack_sync_script}
       SH
     end
 
     private
 
-    attr_reader :context, :remote_name, :auto_create_local_branch
+    attr_reader :context, :remote_name, :auto_create_local_branch, :stack_paths
+
+    def stack_sync_script
+      paths = stack_paths
+      return "dirs -c >/dev/null 2>&1 || true" if paths.empty?
+
+      lines = ["dirs -c >/dev/null 2>&1 || true", "cd #{Shellwords.escape(paths.first)} || __dx_fail \"dx: could not cd into #{Shellwords.escape(paths.first)}\" 21"]
+      paths.drop(1).each do |path|
+        escaped = Shellwords.escape(path)
+        lines << "pushd #{escaped} >/dev/null 2>&1 || __dx_fail \"dx: could not pushd #{escaped}\" 22"
+        lines << "pushd +1 >/dev/null 2>&1 || __dx_fail \"dx: could not rotate dirstack\" 23"
+      end
+      lines.join("\n")
+    end
   end
 end

data/lib/dev_context/shell_setup.rb

@@ -4,6 +4,7 @@ module DevContext
   class ShellSetup
     DEFAULT_PATH = File.expand_path("~/.dx.sh").freeze
     MANAGED_MARKER = "DevContext shell integration generated by `dx init`".freeze
+    VERSION_MARKER_PREFIX = "DX Shell Version:".freeze
 
     attr_reader :path
 
@@ -36,20 +37,32 @@ module DevContext
       <<~SH
         #!/usr/bin/env sh
         # #{MANAGED_MARKER}
+        # #{VERSION_MARKER_PREFIX} #{DevContext::SHELL_VERSION}
         # shellcheck shell=sh
 
         dx() {
+          local bin
+          case "${DX_IMPL:-go}" in
+            go)
+              bin=dev_context-go ;;
+            ruby)
+            bin=dev_context-rb ;;
+            elixir)
+              bin=dev_context-ex ;;
+            *)
+              echo 1>&2 "No idea what $DX_IMPL means!" ; exit 1 ;;
+          esac
           case "$1" in
-            cd|activate|pushd|popd)
+            cd|activate|pushd|popd|pu|po|import)
               local out
-              out="$(DX_SHELL_WRAPPED=1 command dev_context.rb "$@")" || return $?
+              out="$(DX_SHELL_WRAPPED=1 DX_SHELL_STACK="$(dirs -p 2>/dev/null || pwd)" command $bin "$@")" || return $?
               case "$out" in
                 "# DX_SHELL_EVAL"*) eval "$out" ;;
                 *) printf "%s\\n" "$out" ;;
               esac
               ;;
             *)
-              command dev_context.rb "$@"
+              command $bin "$@"
               ;;
           esac
         }

data/lib/dev_context/version.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 module DevContext
+  SHELL_VERSION = "2"
   RELEASES = [
+    ["2.0.1", '2026-06-25'],
+    ["2.0.0", '2026-06-23'],
+    ["1.2.0", '2026-05-28'],
+    ["1.1.0", '2026-05-15'],
     ["1.0.1", '2026-05-12']
   ].freeze
-  VERSION = RELEASES.last.first
+  VERSION = RELEASES[0][0]
 end

data/lib/dev_context.rb

@@ -8,6 +8,7 @@ require_relative "dev_context/commands/help"
 require_relative "dev_context/commands/support"
 require_relative "dev_context/commands/context_lifecycle"
 require_relative "dev_context/commands/git_ops"
+require_relative "dev_context/commands/doctor"
 require_relative "dev_context/commands/find"
 require_relative "dev_context/commands/search_helpers"
 require_relative "dev_context/commands/repos"

metadata

@@ -1,14 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: dev_context
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 2.0.1
 platform: ruby
 authors:
 - Alan Stebbens
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.4'
 - !ruby/object:Gem::Dependency
   name: fuubar
   requirement: !ruby/object:Gem::Requirement
@@ -53,12 +68,14 @@ dependencies:
         version: '3.0'
 description: |
   DevContext (aka `dx`) is a developer context manager that unifies directory-level context
-  switching, multi-repo awareness, and Git-aware introspection. It helps you manage multiple
-  active projects with an activation stack.
+  switching, branch awareness, multi-repo awareness, and Git-aware introspection. It helps
+  you manage multiple active projects with an active stack.
 email:
 - aks@stebbens.org
 executables:
-- dev_context.rb
+- dev_context
+- dev_context-rb
+- dev_context-ruby
 extensions: []
 extra_rdoc_files: []
 files:
@@ -68,11 +85,14 @@ files:
 - LICENSE.txt
 - README.md
 - bin/console
-- bin/dev_context.rb
+- bin/dev_context
+- bin/dev_context-rb
+- bin/dev_context-ruby
 - bin/setup
 - lib/dev_context.rb
 - lib/dev_context/cli.rb
 - lib/dev_context/commands/context_lifecycle.rb
+- lib/dev_context/commands/doctor.rb
 - lib/dev_context/commands/find.rb
 - lib/dev_context/commands/git_ops.rb
 - lib/dev_context/commands/help.rb
@@ -96,6 +116,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/aks/dev_context
   changelog_uri: https://github.com/aks/dev_context/blob/main/CHANGELOG.md
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -110,7 +131,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.11
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: A developer context manager for multi-repo workflows
 test_files: []