devex 0.3.5

data/.rubocop.yml

@@ -0,0 +1,231 @@
+# Archema RuboCop Configuration
+#
+# Layout/alignment settings come from tablecop.
+# This file contains archema-specific settings.
+
+plugins:
+  - rubocop-minitest
+  - rubocop-tablecop
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "tmp/**/*"
+    - "vendor/**/*"
+    - "coverage/**/*"
+    - "examples/**/*"
+    - "docs/msc/**/*"  # Experimental analysis scripts, not production code
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Style
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Allow both single and double quotes - use double by convention,
+# single when semantically meaningful (e.g., JSON-style string keys)
+Style/StringLiterals:
+  Enabled: false
+
+# Prefer explicit bracket syntax for symbol arrays
+Style/SymbolArray:
+  EnforcedStyle: brackets
+
+# Prefer %w[] for word arrays
+Style/WordArray:
+  EnforcedStyle: percent
+
+# Require class/module documentation (except for internal modules)
+Style/Documentation:
+  Enabled: true
+  AllowedConstants:
+    - ClassMethods  # Internal mixin modules don't need separate docs
+    - DSL           # DSL namespace modules documented at parent level
+  Exclude:
+    - "lib/archema/schema/differ.rb"    # Operation classes are internal data structures
+    - "lib/archema/shared_types.rb"     # Module reopening, documented in main file
+    - "lib/archema/stores.rb"           # Module reopening, documented in main file
+    - "test/**/*"                       # Test classes don't need documentation
+
+# Allow multi-line block chains when readable
+Style/MultilineBlockChain:
+  Enabled: false
+
+# DANGEROUS: Autocorrect converts !!value to !value.nil? which has
+# different semantics for boolean values (!!false → false, !false.nil? → true)
+Style/DoubleNegation:
+  Enabled: false
+
+# DANGEROUS: Changes semantics with mixed key types.
+# reject { |k, _| keys.include?(k) } handles symbol/string keys correctly,
+# but hash.except(*keys) treats :key and "key" as different.
+Style/HashExcept:
+  Enabled: false
+
+# DANGEROUS: Converts `Module % [args]` to `format(Module, args)` which breaks
+# custom % methods (like ANSI % ["text", :style] for nested color spans).
+Style/FormatString:
+  Enabled: false
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Layout
+# ─────────────────────────────────────────────────────────────────────────────
+
+Layout/LineLength:
+  Max: 140
+
+# Allow RBS inline type comments like #: Type
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Naming
+# ─────────────────────────────────────────────────────────────────────────────
+
+# DISABLED: Renames @data_layer_instance to @data_layer, but tests
+# use instance_variable_set(:@data_layer_instance, nil) to reset state.
+Naming/MemoizedInstanceVariableName:
+  Enabled: false
+
+# DISABLED: Too pedantic about underscores in numbers (last_5, chain_from_11, 1_0_0)
+Naming/VariableNumber:
+  Enabled: false
+
+# Allow common short parameter names
+Naming/MethodParameterName:
+  AllowedNames:
+    - a
+    - b
+    - c
+    - e   # exception, element, entry
+    - i   # index
+    - j   # secondary index
+    - k   # key
+    - v   # value
+    - h   # hash
+    - n   # number, count
+    - x   # coordinate, generic
+    - y   # coordinate
+    - id  # identifier
+    - io  # IO object
+    - op  # operation
+    - db  # database
+    - fn  # function
+    - s1  # string comparison (levenshtein)
+    - s2  # string comparison (levenshtein)
+    - sc  # sub_constraint in composition constraints
+    - ds  # dataset (Sequel)
+    - to  # destination (from:, to:)
+    - of  # element type (array of:)
+    - _   # explicitly unused
+
+# Allow has_* prefix for methods that genuinely "have" something (not just predicates)
+# has_default?, has_role?, etc. are clearer than default?, role? in context
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_default?
+    - has_role?
+    - has_managed_data?
+    - has_cardinality_constraints?
+    - has_temporal_defaults?
+    - has_irreversible_operations?
+    - has_one       # DSL method: has_one :profile, Profile
+    - has_many      # DSL method: has_many :posts, Post
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Lint
+# ─────────────────────────────────────────────────────────────────────────────
+
+Lint/UselessAssignment:
+  Enabled: true
+
+# DISABLED: Forces combining case branches that happen to have the same result,
+# but often they represent distinct semantic intents. With tablecop alignment,
+# separate branches read as visual lookup tables which is clearer.
+Lint/DuplicateBranch:
+  Enabled: false
+
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+  IgnoreEmptyMethods: true
+
+Lint/MissingSuper:
+  Enabled: false
+
+# DANGEROUS: Removes `require "set"` as "redundant" in Ruby 3.2+, but code
+# using Set.new will fail if Set isn't explicitly required.
+Lint/RedundantRequireStatement:
+  Enabled: false
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Metrics - Lenient thresholds for real-world code
+# ─────────────────────────────────────────────────────────────────────────────
+
+Metrics/MethodLength:
+  Max: 40
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+  Exclude:
+    - "lib/chiridion/engine/inline_rbs_loader.rb"
+
+Metrics/AbcSize:
+  Max: 50
+  Exclude:
+    - "lib/chiridion/engine/inline_rbs_loader.rb"
+
+Metrics/CyclomaticComplexity:
+  Max: 20
+
+Metrics/PerceivedComplexity:
+  Max: 15
+  Exclude:
+    - "lib/chiridion/engine/inline_rbs_loader.rb"
+
+Metrics/ClassLength:
+  Max: 300
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Metrics/BlockLength:
+  Max: 40
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+  Exclude:
+    - "test/**/*"
+    - "spec/**/*"
+    - "features/**/*"
+    - "lib/chiridion/engine/inline_rbs_loader.rb"
+  AllowedMethods:
+    - describe
+    - context
+    - define
+    - configure
+    - namespace
+
+Metrics/ParameterLists:
+  Max: 15
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Minitest
+# ─────────────────────────────────────────────────────────────────────────────
+
+Minitest/EmptyLineBeforeAssertionMethods:
+  Enabled: false
+
+Minitest/MultipleAssertions:
+  Max: 8
+
+# DANGEROUS: Converts `assert obj.foo?` to `assert_predicate obj, :foo?`
+# which breaks refinements since assert_predicate uses send() internally
+# and refinements are lexically scoped (don't work with send).
+Minitest/AssertPredicate:
+  Enabled: false
+
+Minitest/RefutePredicate:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+All notable changes to devex will be documented in this file.
+
+## [0.3.5] - 2025-12-29
+
+### Fixed
+- **Version detection fallback**: `dx version` now searches effective working directory when no project markers found, handling pre-git-init projects
+- **`--dx-from-dir` flag**: Now correctly affects project root discovery (was being ignored)
+- **Subtool helper methods**: Nested tools (`tool "name" do...end`) can now access helper methods defined in parent file (fixes `dx version bump` which was broken)
+
+## [0.3.4] - 2025-12-13
+
+### Added
+- `prj.linter` convention in ProjectPaths - finds .standard.yml or .rubocop.yml
+- `Path#rm`, `Path#delete`, `Path#unlink` - delete a file
+- `Path#rm_rf` - delete directory recursively
+
+### Changed
+- Built-ins now fully trust ProjectPaths fail-fast behavior - no more rescue/re-error patterns
+- `dx lint` and `dx format` use `prj.linter` instead of manual detection
+- `dx test` uses `prj.test`, `dx gem` uses `prj.gemspec` - all with clean fail-fast
+
+## [0.3.3] - 2025-12-13
+
+### Fixed
+- **Built-in tools now run from project root** - `dx test`, `dx lint`, `dx format`, `dx gem` now properly discover project root via `Devex::Dirs.project_dir` and run commands from there, regardless of current directory
+- Built-ins now use `ProjectPaths` (`prj.test`, `prj.gemspec`, etc.) for conventional path discovery instead of manual File.exist? checks
+
+## [0.3.2] - 2025-12-13
+
+### Fixed
+- ExecutionContext now includes Devex::Exec automatically, so nested tools (inside `tool "name" do ... end` blocks) have access to `cmd`, `capture`, etc. without explicit include
+- Moved exec.rb require before tool.rb to ensure proper load order
+
+## [0.3.1] - 2025-12-13
+
+### Added
+- `--no-verbose` flag to reset verbosity level (useful in subtools)
+- `--no-quiet` flag to unset quiet mode
+- `default:` option for flags to specify non-nil defaults
+
+### Changed
+- Built-in tools (`test`, `lint`, `format`, `gem`) now use `Devex::Exec` module with `cmd` pattern
+- `lint.rb` uses `capture()` with `.stdout_lines` for git diff (demonstrates capture API)
+- `gem.rb` uses `.then { }` chaining for sequential build/install operations
+- Documentation updated with comprehensive Exec examples showing result objects, chaining, capture
+
+### Fixed
+- Documentation examples now consistently use `cmd`/`cmd?` inside `def run` blocks
+
+## [0.3.0] - 2025-12-13
+
+### Added
+- **Built-in `dx test`**: Auto-detects minitest or RSpec, runs with coverage flag
+- **Built-in `dx lint`**: Auto-detects RuboCop or StandardRB, with `--fix` and `--diff` options
+- **Built-in `dx format`**: Auto-formats code (equivalent to `dx lint --fix`)
+- **Built-in `dx gem`**: Subcommands for `build`, `install`, and `clean`
+- **`cmd` and `cmd?` aliases**: Use these in tools to avoid `def run` collision with `Devex::Exec.run`
+- **Reserved flag validation**: Tools that define flags conflicting with global flags (`-v`, `-f`, `-q`, etc.) now fail fast with a helpful error message
+
+### Fixed
+- Boolean flags now default to `false` instead of `nil`, fixing method access in tools
+- Fixed missing requires for `Devex::Exec`, `Devex::ProjectPaths`, and `Devex::WorkingDir` modules
+- Tools can now use `run`, `capture`, `spawn`, and other Exec methods without errors
+
+## [0.2.0] - 2025-12-13
+
+### Added
+- **Environment wrapper chain**: `[dotenv] [mise exec --] [bundle exec] command`
+  - `mise` auto-detected from `.mise.toml` or `.tool-versions`
+  - `bundle exec` auto-detected from `Gemfile` for gem commands
+  - `dotenv` requires explicit opt-in (`dotenv: true`)
+- **Auto-require for project lib/**: Tools can `require "myproject/foo"` without `require_relative`
+- **String case transforms**: `snake_case`, `kebab_case`, `camel_case`, `pascal_case`, `title_case`, `scream_case`, `up_case`, `down_case` with aliases
+- `--dx-from-dir` flag for operating on projects remotely
+- `.dx-use-local` delegation for version consistency
+- `prj.hooks` and `prj.templates` path conventions
+
+### Changed
+- ADRs updated from Draft to Accepted status
+
+## [0.1.0] - 2025-12-13
+
+### Added
+- Initial release
+- CLI framework with tool routing and nested subcommands
+- Help system (`dx help`, `dx tool --help`, `dx tool help`)
+- DSL for defining tools: `desc`, `long_desc`, `flag`, `required_arg`, `optional_arg`, `remaining_args`, `tool`
+- Agent mode detection (non-tty, CI, explicit env var)
+- Environment detection (development, test, staging, production)
+- Output helpers with color support
+- Built-in `dx version` command with bump support
+- Support library: Path class, ANSI colors, core extensions
+- Directory context: `Dirs`, `ProjectPaths`, `WorkingDir`
+- Command execution: `run`, `capture`, `spawn`, `shell`, `ruby`, `tool`
+- Result monad with `then`, `map`, `exit_on_failure!`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joseph A Wecker
+
+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,314 @@
+![Devex](devex-logo.jpg)
+
+# Devex
+
+A lightweight, zero-heavy-dependency Ruby CLI providing a unified `dx` command for common development tasks. Projects can extend with local tasks. Clean-room implementation inspired by toys-core patterns.
+
+## Vision
+
+- **Single entry point**: `dx` command for all dev tasks
+- **Zero-dependency core**: Support library uses only Ruby stdlib
+- **Project-local tools**: Override or extend built-ins with `tools/*.rb`
+- **Agent-aware**: Automatically detects AI agent invocation and adapts output
+- **Environment-aware**: Rails-style environment detection (dev/test/staging/prod)
+- **Command execution**: Clean subprocess management with environment orchestration
+
+## Installation
+
+```bash
+gem install devex
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "devex"
+```
+
+## Usage
+
+```bash
+# Show available commands
+dx help
+
+# Show/manage version
+dx version
+dx version bump patch
+dx version set 2.0.0
+
+# With JSON output (auto-detected in agent mode)
+dx version --format=json
+```
+
+## Project-Local Tools
+
+Create a `tools/` directory in your project root with Ruby files:
+
+```ruby
+# tools/build.rb
+desc "Build and test the project"
+
+long_desc <<~DESC
+  Runs the full build pipeline: install dependencies, run tests,
+  and optionally lint the code.
+DESC
+
+flag :skip_lint, "-s", "--skip-lint", desc: "Skip linting step"
+flag :coverage, "-c", "--coverage", desc: "Run with code coverage"
+
+include Devex::Exec
+
+def run
+  # Use `cmd` instead of `run` to avoid conflict with `def run`
+  cmd("bundle", "install").exit_on_failure!
+
+  # Access flags as methods (boolean flags default to false)
+  env = coverage ? { "COVERAGE" => "1" } : {}
+  cmd("bundle", "exec", "rake", "test", env: env).exit_on_failure!
+
+  unless skip_lint
+    cmd("bundle", "exec", "rubocop").exit_on_failure!
+  end
+
+  # Check global verbose flag
+  puts "Build complete!" if verbose?
+end
+```
+
+Then run:
+```bash
+dx build                    # Full build
+dx build --skip-lint        # Skip linting
+dx build --coverage         # With coverage
+dx -v build                 # Verbose output
+```
+
+### Nested Tools
+
+```ruby
+# tools/db.rb
+desc "Database operations"
+
+tool "migrate" do
+  desc "Run migrations"
+  def run
+    # ...
+  end
+end
+
+tool "seed" do
+  desc "Seed the database"
+  def run
+    # ...
+  end
+end
+```
+
+Access as: `dx db migrate`, `dx db seed`
+
+## Command Execution
+
+Tools have access to smart command execution that automatically handles your environment.
+Use `cmd` (not `run`) inside tools to avoid shadowing the `def run` entry point:
+
+```ruby
+# tools/deploy.rb
+desc "Deploy the application"
+
+flag :skip_tests, "--skip-tests", desc: "Skip test suite"
+flag :dry_run, "-n", "--dry-run", desc: "Show what would be done"
+
+include Devex::Exec
+
+def run
+  # ─── Basic execution with exit_on_failure! ───
+  cmd("bundle", "install").exit_on_failure!
+
+  # ─── Boolean check: cmd? returns true/false ───
+  unless skip_tests || cmd?("which", "rspec")
+    cmd("rake", "test").exit_on_failure!
+  end
+
+  # ─── Capture output into result object ───
+  result = capture("git", "rev-parse", "--short", "HEAD")
+  commit = result.stdout.strip
+  puts "Deploying commit #{commit}..."
+
+  # ─── Chain sequential operations with .then ───
+  cmd("docker", "build", "-t", "myapp:#{commit}", ".")
+    .then { cmd("docker", "push", "myapp:#{commit}") }
+    .exit_on_failure!
+
+  # ─── Transform captured output with .map ───
+  tag = capture("git", "describe", "--tags", "--abbrev=0")
+          .map { |stdout| stdout.strip }
+
+  # ─── Result object has rich info ───
+  result = cmd("kubectl", "apply", "-f", "k8s/")
+  if result.failed?
+    $stderr.puts "Deploy failed (exit #{result.exit_code})"
+    $stderr.puts result.stderr if result.stderr
+    exit 1
+  end
+
+  puts "Deployed #{tag || commit} successfully!" if verbose?
+end
+```
+
+### Execution Methods
+
+| Method | Purpose | Returns |
+|--------|---------|---------|
+| `cmd(*args)` | Run command, stream output | `Result` |
+| `cmd?(*args)` | Test if command succeeds | `Boolean` |
+| `capture(*args)` | Run command, capture output | `Result` with `.stdout`, `.stderr` |
+| `shell(string)` | Run shell command (pipes, globs) | `Result` |
+| `shell?(string)` | Test if shell command succeeds | `Boolean` |
+| `spawn(*args)` | Start background process | `Controller` |
+
+### Result Object
+
+```ruby
+result = cmd("make", "test")
+
+result.success?      # => true if exit code is 0
+result.failed?       # => true if non-zero exit
+result.exit_code     # => Integer exit code
+result.stdout        # => captured stdout (if using capture)
+result.stderr        # => captured stderr
+result.stdout_lines  # => stdout split into lines
+result.duration      # => execution time in seconds
+
+# Chaining
+result.exit_on_failure!           # Exit process if failed
+result.then { cmd("next") }       # Chain if successful
+result.map { |out| out.strip }    # Transform stdout
+```
+
+### Environment Wrappers
+
+Commands are automatically wrapped based on your project:
+
+| Wrapper | When Applied |
+|---------|--------------|
+| `mise exec --` | Auto if `.mise.toml` or `.tool-versions` exists |
+| `bundle exec` | Auto if `Gemfile` exists and command looks like a gem |
+| `dotenv` | Explicit opt-in only (`dotenv: true`) |
+
+Control wrappers explicitly:
+
+```ruby
+cmd "rspec"                      # auto-detect mise + bundle
+cmd "rspec", mise: false         # skip mise wrapping
+cmd "rspec", bundle: false       # skip bundle exec
+cmd "echo", "hi", raw: true      # skip all wrappers
+cmd "rails", "s", dotenv: true   # enable dotenv loading
+```
+
+## Configuration
+
+Create `.dx.yml` in your project root:
+
+```yaml
+# Custom tools directory (default: tools)
+tools_dir: dev/tools
+```
+
+## Global Options
+
+```bash
+dx --help                    # Show help with global options
+dx --dx-version              # Show devex gem version
+dx -f json version           # Output in JSON format
+dx --format=yaml version     # Output in YAML format
+dx -v version                # Verbose mode
+dx -q version                # Quiet mode
+dx --no-color version        # Disable colors
+dx --color=always version    # Force colors
+```
+
+## Environment Variables
+
+- `DX_ENV` / `DEVEX_ENV` - Set environment (development, test, staging, production)
+- `DX_AGENT_MODE=1` - Force agent mode (structured output, no colors)
+- `DX_INTERACTIVE=1` - Force interactive mode
+- `NO_COLOR=1` - Disable colored output
+- `FORCE_COLOR=1` - Force colored output
+
+## Debug Flags
+
+Hidden flags for testing and bug reproduction (not shown in `--help`):
+
+```bash
+dx --dx-agent-mode version      # Force agent mode
+dx --dx-no-agent-mode version   # Force interactive mode
+dx --dx-env=production version  # Force environment
+dx --dx-terminal version        # Force terminal detection
+```
+
+## Built-in Commands
+
+**Testing & Quality**
+- `dx test` - Run tests (auto-detects minitest/RSpec)
+- `dx lint` - Run linter (auto-detects RuboCop/StandardRB)
+- `dx lint --fix` - Auto-fix linter issues
+- `dx format` - Auto-format code (alias for `dx lint --fix`)
+
+**Version Management**
+- `dx version` - Show project version
+- `dx version bump <major|minor|patch>` - Bump semantic version
+- `dx version set <version>` - Set explicit version
+
+**Gem Packaging**
+- `dx gem build` - Build the gem
+- `dx gem install` - Build and install locally
+- `dx gem clean` - Remove built gem files
+
+More built-ins planned: `types`, `pre-commit`, `init`
+
+## Building Custom CLIs with Devex::Core
+
+Devex exposes its CLI framework for building your own command-line tools:
+
+```ruby
+require "devex/core"
+
+config = Devex::Core::Configuration.new(
+  executable_name: "mycli",
+  flag_prefix: "mycli",              # --mycli-version, --mycli-agent-mode
+  project_markers: %w[.mycli.yml .git Gemfile],
+  env_prefix: "MYCLI"                # MYCLI_AGENT_MODE, MYCLI_ENV
+)
+
+cli = Devex::Core::CLI.new(config: config)
+cli.load_tools("/path/to/tools")
+exit cli.run(ARGV)
+```
+
+This gives you:
+- Tool routing with nested subcommands
+- Automatic help generation
+- Agent mode detection (adapts output for AI agents)
+- Environment detection (dev/test/staging/prod)
+- Command execution with environment wrappers
+- Project path conventions
+- Zero-dependency support library (Path, ANSI, CoreExt)
+
+See [docs/developing-tools.md](docs/developing-tools.md) for the full API.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec exe/dx --help
+```
+
+## Documentation
+
+- **[Developing Tools](docs/developing-tools.md)** - How to create tools, available interfaces, best practices
+- **[CHANGELOG](CHANGELOG.md)** - Version history and release notes
+
+## License
+
+MIT - see [LICENSE](LICENSE)

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+task default: :test