devex 0.3.7 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 706b385515967e798d258c20f07925a64d65fc023dcf11a9bbb95cbe7daaa896
4
- data.tar.gz: '06242720010835019af12d6a732778600d4ac82dc04957a9fbaa7b4e6e051fb7'
3
+ metadata.gz: 63d30abae077b9da745cbee6677950dd8f762674f90c78ab42f10073191a10e2
4
+ data.tar.gz: 2d94983e5b70cb7872485be76a27b432d852e51a97b71a6dfcf7138065da099b
5
5
  SHA512:
6
- metadata.gz: 266a7d54b5005b3276fcfe7c259ae8799a721550ec3b79e949fbdbfef0a326fb2ec0ffe49d6a86399c9aa45ebb66a752cfde065985997ce4e3fb33e4ead02ad6
7
- data.tar.gz: 9e004411ef987e6eb20b14d6e7436b518598923e44dc9c74427223cd70d947b6a5919b37d3dd8e7f80647191ecd85c371342ba1704a7c66ffd62decfd5aac500
6
+ metadata.gz: bc57c8ee43f849232f4408022a8d7aba30f7bfe7ed576ce25234323752b275d954f383057555676c60acd2af8e698dfbc8f6d09ea629b78f0cc275e96b60dcf0
7
+ data.tar.gz: d51afcd36c281f9bffee5c2cf622a51bf68bf225bc147f77d3425044156b6d1c764fb784fab1213e7c6a08c582ef403cb7f04f73e443524e92f5cffb815463c0
data/CHANGELOG.md CHANGED
@@ -2,6 +2,74 @@
2
2
 
3
3
  All notable changes to devex will be documented in this file.
4
4
 
5
+ ## [0.3.9] - 2026-11-20
6
+
7
+ ### Added
8
+ - **Named version files.** A project with more than one version (a
9
+ specification and its implementation, say) can name further version files
10
+ in its dx config (`.dx.yml` or `.dx/config.yml`):
11
+
12
+ ```yaml
13
+ versions:
14
+ spec: VERSION.SPEC
15
+ ```
16
+
17
+ and address one by putting the name first: `dx version spec`,
18
+ `dx version spec bump pre`, `dx version spec set 2.0.0-beta.0`. Paths are
19
+ relative to the project root; a named file may be a bare version file or
20
+ Ruby source with a `VERSION = "…"` constant. `bump`, `set` and `help`
21
+ cannot be used as names.
22
+ - The unnamed commands are unchanged and keep finding the default version
23
+ file by convention. One addition: `dx version` in a project that has named
24
+ versions but no default file lists the named versions, where it used to
25
+ fall through to printing devex's own version.
26
+
27
+ ### Fixed
28
+ - `dx version <unknown word>` is now an error (exit 1). It used to ignore
29
+ the extra arguments and show the version, so a typo like
30
+ `dx version bmup patch` looked like success.
31
+
32
+ ## [0.3.8] - 2026-11-20
33
+
34
+ ### Fixed
35
+ - **`dx version bump` / `dx version set` now write a bare `VERSION` file.**
36
+ Previously only a Ruby `VERSION = "…"` constant was rewritten; for a bare
37
+ file the command printed `old → new`, exited 0, and left the file
38
+ unchanged.
39
+ - **A version command can no longer report a change it did not make.** The
40
+ new file content is checked before anything is written; if it would not
41
+ read back as the new version, nothing is written and the command exits 1.
42
+ - **`dx version bump` refuses versions that are not plain
43
+ `MAJOR.MINOR.PATCH`** (exit 1, file untouched) instead of mangling them.
44
+ `2.0.0.pre` used to "bump" to `2.0.1.0`, and `1.2` to `0.0.1`. What a
45
+ bump should mean for a prerelease is a convention devex does not assume;
46
+ use `dx version set`.
47
+ - **`dx version set` validates the whole string.** It accepts
48
+ `MAJOR.MINOR.PATCH` with an optional prerelease tail in RubyGems style
49
+ (`2.0.0.pre`) or SemVer style (`2.0.0-rc.1`, `+build`); `1.0.0garbage`
50
+ used to pass.
51
+ - `test_stable_compact` no longer depends on `Hash#inspect`'s format, which
52
+ changed in Ruby 3.4 (the test had been failing since).
53
+ - Rewriting a Ruby constant keeps the file's own quote style and spacing.
54
+
55
+ ### Added
56
+ - **`dx version bump pre`** increments the counter of a prerelease version,
57
+ in either spelling: `2.0.0-alpha.0` → `2.0.0-alpha.1`, `2.0.0.pre.1` →
58
+ `2.0.0.pre.2`. Refused when the version has no trailing prerelease
59
+ counter. Moving between stages, or releasing, is `dx version set`.
60
+
61
+ ### Added (2026-05-19)
62
+ - **Actionable LoadError hint in `CLI#run`.** When a project tool's
63
+ `require` fails AND the project has a Gemfile but no `.dx-use-local`
64
+ marker (and we aren't already inside a delegated re-exec), the bare
65
+ LoadError is surfaced AND a one-line actionable hint is appended
66
+ pointing at the existing `.dx-use-local` delegation affordance
67
+ (ADR-003). Purely additive: never swallows the underlying error,
68
+ never changes exit codes for the non-matching case. Resolves the
69
+ recurring confusion where a project tool that requires a bundle-only
70
+ path-gem (e.g. relata's `tools/docs.rb` → `chiridion`) raised a raw
71
+ 12-line backtrace with no signal that the affordance exists.
72
+
5
73
  ## [0.3.5] - 2025-12-29
6
74
 
7
75
  ### Fixed
data/README.md CHANGED
@@ -33,8 +33,9 @@ dx help
33
33
 
34
34
  # Show/manage version
35
35
  dx version
36
- dx version bump patch
37
- dx version set 2.0.0
36
+ dx version bump patch # 1.2.3 → 1.2.4
37
+ dx version bump pre # 2.0.0-alpha.0 → 2.0.0-alpha.1
38
+ dx version set 2.0.0-beta.0
38
39
 
39
40
  # With JSON output (auto-detected in agent mode)
40
41
  dx version --format=json
@@ -256,8 +257,27 @@ dx --dx-terminal version # Force terminal detection
256
257
 
257
258
  **Version Management**
258
259
  - `dx version` - Show project version
259
- - `dx version bump <major|minor|patch>` - Bump semantic version
260
- - `dx version set <version>` - Set explicit version
260
+ - `dx version bump <major|minor|patch>` - Bump a plain `MAJOR.MINOR.PATCH` version
261
+ - `dx version bump pre` - Increment a prerelease counter (`2.0.0-alpha.0` → `2.0.0-alpha.1`, or RubyGems-style `2.0.0.alpha.0`)
262
+ - `dx version set <version>` - Set explicit version, including prereleases; the way to change stage or release
263
+
264
+ The version lives in `lib/*/version.rb` (a `VERSION = "…"` constant), a bare `VERSION` file, or `version.rb`, looked for in that order. A bump that doesn't apply to the current version is refused with exit 1 and the file is left alone.
265
+
266
+ A project with more than one version can name further version files in `.dx.yml` (or `.dx/config.yml`) and address them by name:
267
+
268
+ ```yaml
269
+ # .dx.yml
270
+ versions:
271
+ spec: VERSION.SPEC
272
+ ```
273
+
274
+ ```bash
275
+ dx version spec # show
276
+ dx version spec bump pre # 2.0.0-alpha.0 → 2.0.0-alpha.1
277
+ dx version spec set 2.0.0-beta.0
278
+ ```
279
+
280
+ The unnamed commands keep working on the default file. If there is no default file, `dx version` lists the named versions.
261
281
 
262
282
  **Gem Packaging**
263
283
  - `dx gem build` - Build the gem
data/devex-0.3.7.gem ADDED
Binary file
@@ -9,7 +9,17 @@ VERSION_FILE_PATTERNS = [
9
9
  "version.rb"
10
10
  ].freeze
11
11
 
12
- VERSION_REGEX = /VERSION\s*=\s*["']([^"']+)["']/
12
+ VERSION_REGEX = /VERSION\s*=\s*(["'])([^"']+)\1/
13
+
14
+ # What `dx version set` accepts: MAJOR.MINOR.PATCH, optionally followed by a
15
+ # prerelease tail in either RubyGems style (2.0.0.pre, 2.0.0.rc.1) or SemVer
16
+ # style (2.0.0-rc.1), and optionally SemVer build metadata (+build.5).
17
+ # Deliberately neutral between the two conventions: which one a project uses
18
+ # is the project's choice, not ours.
19
+ SETTABLE_VERSION = /\A\d+\.\d+\.\d+(?:[.-][0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:[.-][0-9A-Za-z]+)*)?\z/
20
+
21
+ # What `dx version bump` can act on: exactly MAJOR.MINOR.PATCH.
22
+ BUMPABLE_VERSION = /\A(\d+)\.(\d+)\.(\d+)\z/
13
23
 
14
24
  def find_version_file(root)
15
25
  VERSION_FILE_PATTERNS.each do |pattern|
@@ -19,40 +29,78 @@ def find_version_file(root)
19
29
  nil
20
30
  end
21
31
 
22
- def read_version(file)
23
- content = File.read(file)
32
+ # Extract the version from a version file's content. Two shapes are
33
+ # understood: a Ruby source file with a `VERSION = "x"` constant, and a bare
34
+ # file whose whole content is the version (e.g. a top-level VERSION file).
35
+ def parse_version(content)
24
36
  if content =~ VERSION_REGEX
25
- Regexp.last_match(1)
37
+ Regexp.last_match(2)
26
38
  else
27
39
  content.strip
28
40
  end
29
41
  end
30
42
 
43
+ def read_version(file) = parse_version(File.read(file))
44
+
45
+ # Content of the version file with old_version replaced by new_version, or nil
46
+ # if this content isn't in a shape we know how to rewrite.
47
+ def replace_version(content, old_version, new_version)
48
+ if content =~ VERSION_REGEX
49
+ # Ruby constant: keep the file's own spacing and quote style.
50
+ content.sub(/(VERSION\s*=\s*)(["'])#{Regexp.escape(old_version)}\2/) do
51
+ "#{Regexp.last_match(1)}#{Regexp.last_match(2)}#{new_version}#{Regexp.last_match(2)}"
52
+ end
53
+ elsif content.strip == old_version && !old_version.empty? && old_version !~ /\s/
54
+ # Bare file: swap the version, keep surrounding whitespace (trailing newline).
55
+ content.sub(old_version) { new_version }
56
+ end
57
+ end
58
+
59
+ # Write new_version into file. The new content is checked *before* it is
60
+ # written: if it would not read back as new_version, nothing is written and the
61
+ # command fails. A version command must never report a change it did not make.
31
62
  def write_version(file, old_version, new_version)
32
- content = File.read(file)
33
- new_content = content.gsub(
34
- /VERSION\s*=\s*["']#{Regexp.escape(old_version)}["']/,
35
- %(VERSION = "#{new_version}")
36
- )
63
+ content = File.read(file)
64
+ new_content = replace_version(content, old_version, new_version)
65
+
66
+ unless new_content && parse_version(new_content) == new_version
67
+ version_error("Don't know how to write a version into #{file}. " \
68
+ "Expected a `VERSION = \"x.y.z\"` constant, or a file containing only the version. " \
69
+ "Nothing was changed.")
70
+ end
71
+
37
72
  File.write(file, new_content)
38
73
  end
39
74
 
75
+ # A prerelease version whose tail ends in a numeric counter, in either
76
+ # spelling: 2.0.0-alpha.0 (SemVer) or 2.0.0.alpha.0 (RubyGems). The stage
77
+ # label must contain a letter, so 1.2.3.4 is not mistaken for one.
78
+ PRERELEASE_COUNTER = /\A(\d+\.\d+\.\d+[.-](?:[0-9A-Za-z]+[.-])*?[0-9A-Za-z]*[A-Za-z][0-9A-Za-z]*[.-])(\d+)\z/
79
+
80
+ # Returns the bumped version string, or nil if this kind of bump doesn't
81
+ # apply to this version.
82
+ #
83
+ # major/minor/patch apply only to plain MAJOR.MINOR.PATCH: what they should do
84
+ # to a prerelease (release it? skip past it?) depends on a convention we don't
85
+ # assume. "pre" applies only to a prerelease ending in a numeric counter, and
86
+ # increments that counter; this means the same thing in both spellings.
87
+ # Moving between stages (alpha → beta → release) is `dx version set`.
40
88
  def bump_version(version, type)
41
- parts = version.split(".").map(&:to_i)
42
- parts = [0, 0, 0] if parts.length < 3
89
+ if type == "pre"
90
+ match = PRERELEASE_COUNTER.match(version)
91
+ return match && "#{match[1]}#{match[2].to_i + 1}"
92
+ end
93
+
94
+ match = BUMPABLE_VERSION.match(version)
95
+ return nil unless match
96
+
97
+ major, minor, patch = match.captures.map(&:to_i)
43
98
 
44
99
  case type
45
- when "major"
46
- parts[0] += 1
47
- parts[1] = 0
48
- parts[2] = 0
49
- when "minor"
50
- parts[1] += 1
51
- parts[2] = 0
52
- when "patch" then parts[2] += 1
100
+ when "major" then "#{major + 1}.0.0"
101
+ when "minor" then "#{major}.#{minor + 1}.0"
102
+ when "patch" then "#{major}.#{minor}.#{patch + 1}"
53
103
  end
54
-
55
- parts.join(".")
56
104
  end
57
105
 
58
106
  def version_error(message)
@@ -69,6 +117,8 @@ def version_output(data)
69
117
  else
70
118
  text = if data[:old_version] && data[:new_version]
71
119
  "#{data[:old_version]} → #{data[:new_version]}"
120
+ elsif data[:versions]
121
+ data[:versions].map { |name, v| "#{name} #{v[:version]}" }.join("\n")
72
122
  else
73
123
  data[:version].to_s
74
124
  end
@@ -76,11 +126,132 @@ def version_output(data)
76
126
  end
77
127
  end
78
128
 
129
+ # --- Named version files ---
130
+ #
131
+ # A project can have more than one version: a specification and the
132
+ # implementation that follows it, say. Additional version files are named in
133
+ # the project's dx config (.dx.yml, or .dx/config.yml):
134
+ #
135
+ # versions:
136
+ # spec: VERSION.SPEC
137
+ #
138
+ # and addressed by putting the name first: `dx version spec bump pre`.
139
+ # The unnamed commands are unaffected and keep finding the project's default
140
+ # version file by convention (VERSION_FILE_PATTERNS).
141
+
142
+ # Words that already mean something right after `dx version`.
143
+ RESERVED_VERSION_NAMES = %w[bump set help].freeze
144
+
145
+ # { "spec" => "/abs/path/VERSION.SPEC" } from the project's config; {} if none.
146
+ def named_version_files(root)
147
+ return {} unless root
148
+
149
+ entries = Devex.load_config(root)["versions"]
150
+ return {} if entries.nil?
151
+
152
+ version_error("Config `versions:` must map names to file paths, e.g. `spec: VERSION.SPEC`") unless entries.is_a?(Hash)
153
+
154
+ entries.to_h do |name, path|
155
+ name = name.to_s
156
+ if RESERVED_VERSION_NAMES.include?(name)
157
+ version_error("Version name '#{name}' in config is reserved (#{RESERVED_VERSION_NAMES.join(', ')})")
158
+ end
159
+ version_error("Version name '#{name}' in config must be letters, digits, '-' or '_'") unless name.match?(/\A[A-Za-z][A-Za-z0-9_-]*\z/)
160
+ version_error("Version '#{name}' in config needs a file path") unless path.is_a?(String) && !path.strip.empty?
161
+
162
+ [name, File.expand_path(path, root)]
163
+ end
164
+ end
165
+
166
+ # The file for a configured name; fails if the name or the file is missing.
167
+ def named_version_file!(name)
168
+ version_error("Not in a project directory") unless cli.project_root
169
+
170
+ files = named_version_files(cli.project_root)
171
+ unless files.key?(name)
172
+ known = files.empty? ? "none are configured" : "configured: #{files.keys.join(', ')}"
173
+ version_error("Unknown version name '#{name}' (#{known}). " \
174
+ "Name version files under `versions:` in the project's dx config.")
175
+ end
176
+
177
+ file = files[name]
178
+ version_error("Version file for '#{name}' not found: #{file}") unless File.file?(file)
179
+ file
180
+ end
181
+
182
+ # The project's default (unnamed) version file.
183
+ def default_version_file!
184
+ version_error("Not in a project directory") unless cli.project_root
185
+
186
+ file = find_version_file(cli.project_root)
187
+ return file if file
188
+
189
+ names = named_version_files(cli.project_root).keys
190
+ hint = names.empty? ? "" : " This project names its versions: use `dx version <name> ...` (#{names.join(', ')})."
191
+ version_error("Could not find version file.#{hint}")
192
+ end
193
+
194
+ # `dx version set`, with the name included when there is one (for messages).
195
+ def explicit_set_command(name) = ["dx version", name, "set <version>"].compact.join(" ")
196
+
197
+ def bump_version_file(file, type, name: nil)
198
+ version_error("Invalid version type '#{type}'. Use: major, minor, patch, or pre") unless %w[major minor patch pre].include?(type)
199
+
200
+ old_version = read_version(file)
201
+ new_version = bump_version(old_version, type)
202
+ unless new_version
203
+ reason = if type == "pre"
204
+ "'pre' needs a prerelease version ending in a numeric counter (e.g. 2.0.0-alpha.0)"
205
+ else
206
+ "'#{type}' only applies to a plain MAJOR.MINOR.PATCH version"
207
+ end
208
+ version_error("Can't bump '#{old_version}': #{reason}. " \
209
+ "Use `#{explicit_set_command(name)}` to choose the next version explicitly. Nothing was changed.")
210
+ end
211
+
212
+ write_version(file, old_version, new_version)
213
+ version_output({ old_version: old_version, new_version: new_version, type: type, name: name, file: file }.compact)
214
+ end
215
+
216
+ def assign_version_file(file, version, name: nil)
217
+ unless version.match?(SETTABLE_VERSION)
218
+ version_error("Invalid version format '#{version}'. " \
219
+ "Use MAJOR.MINOR.PATCH, optionally with a prerelease tail (e.g. 2.0.0.pre or 2.0.0-rc.1)")
220
+ end
221
+
222
+ old_version = read_version(file)
223
+ write_version(file, old_version, version)
224
+ version_output({ old_version: old_version, new_version: version, name: name, file: file }.compact)
225
+ end
226
+
79
227
  # --- Main tool ---
80
228
 
81
229
  desc "Show or manage version"
82
230
 
231
+ long_desc <<~DESC
232
+ dx version Show the project's version
233
+ (all named versions, if there is no default file)
234
+ dx version bump TYPE Bump it (major, minor, patch, or pre)
235
+ dx version set VERSION Set it
236
+
237
+ A project with more than one version can name further version files in its
238
+ dx config (.dx.yml or .dx/config.yml):
239
+
240
+ versions:
241
+ spec: VERSION.SPEC
242
+
243
+ and address one by putting its name first:
244
+
245
+ dx version NAME Show that version
246
+ dx version NAME bump TYPE Bump it
247
+ dx version NAME set VERSION Set it
248
+ DESC
249
+
250
+ remaining_args :named, desc: "[NAME] [bump TYPE | set VERSION] for a version file named in the dx config"
251
+
83
252
  def run
253
+ return run_named(*named) if named && !named.empty?
254
+
84
255
  # Try project root first, then fall back to effective working directory.
85
256
  # This handles cases where a project exists but isn't yet recognized
86
257
  # (e.g., no .git, Gemfile, or other project markers).
@@ -96,61 +267,71 @@ def run
96
267
  end
97
268
  end
98
269
 
99
- version_data ||= { version: Devex::VERSION, source: "devex" }
270
+ return version_output(version_data) if version_data
271
+
272
+ # No default version file. If the project names its versions, show those;
273
+ # only a project with no version of its own gets devex's.
274
+ names = named_version_files(cli.project_root).keys
275
+ return version_output({ version: Devex::VERSION, source: "devex" }) if names.empty?
100
276
 
101
- version_output(version_data)
277
+ versions = names.to_h do |name|
278
+ file = named_version_file!(name)
279
+ [name, { version: read_version(file), file: file }]
280
+ end
281
+ version_output({ versions: versions, source: "project" })
282
+ end
283
+
284
+ # dx version NAME [bump TYPE | set VERSION]
285
+ def run_named(name, action = nil, value = nil, *extra)
286
+ file = named_version_file!(name)
287
+ usage = "Usage: dx version #{name} [bump <major|minor|patch|pre> | set <version>]"
288
+
289
+ version_error("Too many arguments. #{usage}") unless extra.empty?
290
+
291
+ case action
292
+ when nil then version_output({ version: read_version(file), source: "project", name: name, file: file })
293
+ when "bump"
294
+ version_error("Missing bump type. #{usage}") unless value
295
+ bump_version_file(file, value, name: name)
296
+ when "set"
297
+ version_error("Missing version. #{usage}") unless value
298
+ assign_version_file(file, value, name: name)
299
+ else
300
+ version_error("Unknown action '#{action}'. #{usage}")
301
+ end
102
302
  end
103
303
 
104
304
  # --- Subtools ---
105
305
 
106
306
  tool "bump" do
107
- desc "Bump version (major, minor, or patch)"
307
+ desc "Bump version (major, minor, patch, or pre)"
108
308
  long_desc <<~DESC
109
309
  Bump the project version following semantic versioning.
110
310
 
111
311
  MAJOR version for incompatible API changes
112
312
  MINOR version for backwards-compatible new functionality
113
313
  PATCH version for backwards-compatible bug fixes
114
- DESC
115
-
116
- required_arg :type, desc: "Version component: major, minor, or patch"
117
-
118
- def run
119
- version_error("Invalid version type '#{type}'. Use: major, minor, or patch") unless %w[major minor patch].include?(type)
314
+ PRE the counter of a prerelease: 2.0.0-alpha.0 -> 2.0.0-alpha.1
315
+ (RubyGems spelling works too: 2.0.0.alpha.0 -> 2.0.0.alpha.1)
120
316
 
121
- version_error("Not in a project directory") unless cli.project_root
317
+ major, minor and patch apply only to a plain MAJOR.MINOR.PATCH version;
318
+ pre applies only to a prerelease that ends in a numeric counter. Anything
319
+ else is refused rather than guessed at. To move between stages or to
320
+ release (2.0.0-alpha.3 -> 2.0.0-beta.0 -> 2.0.0), use `dx version set`.
122
321
 
123
- version_file = find_version_file(cli.project_root)
124
- version_error("Could not find version file") unless version_file
322
+ For a version file named in the dx config: dx version NAME bump TYPE
323
+ DESC
125
324
 
126
- old_version = read_version(version_file)
127
- new_version = bump_version(old_version, type)
128
- write_version(version_file, old_version, new_version)
325
+ required_arg :type, desc: "Version component: major, minor, patch, or pre"
129
326
 
130
- version_output(
131
- { old_version: old_version, new_version: new_version, type: type, file: version_file }
132
- )
133
- end
327
+ def run = bump_version_file(default_version_file!, type)
134
328
  end
135
329
 
136
330
  tool "set" do
137
331
  desc "Set version to a specific value"
332
+ long_desc "For a version file named in the dx config: dx version NAME set VERSION"
138
333
 
139
- required_arg :version, desc: "Version string (e.g., 1.0.0)"
140
-
141
- def run
142
- version_error("Invalid version format '#{version}'. Use semantic versioning: MAJOR.MINOR.PATCH") unless version.match?(/^\d+\.\d+\.\d+/)
143
-
144
- version_error("Not in a project directory") unless cli.project_root
334
+ required_arg :version, desc: "Version string (e.g., 1.0.0, 2.0.0.pre, 2.0.0-rc.1)"
145
335
 
146
- version_file = find_version_file(cli.project_root)
147
- version_error("Could not find version file") unless version_file
148
-
149
- old_version = read_version(version_file)
150
- write_version(version_file, old_version, version)
151
-
152
- version_output(
153
- { old_version: old_version, new_version: version, file: version_file }
154
- )
155
- end
336
+ def run = assign_version_file(default_version_file!, version)
156
337
  end
data/lib/devex/cli.rb CHANGED
@@ -92,6 +92,20 @@ module Devex
92
92
  rescue OptionParser::ParseError => e
93
93
  Output.error(e.message)
94
94
  1
95
+ rescue LoadError => e
96
+ # Additive: surface the underlying LoadError cleanly, AND, only when
97
+ # the situation matches (in a project with a Gemfile but no
98
+ # delegation marker, and not already delegated), append an
99
+ # actionable hint pointing at the existing `.dx-use-local`
100
+ # affordance (ADR-003). Never swallows the real error — the hint
101
+ # is additional context. Without this, a project tool that
102
+ # requires a bundle-only path-gem (e.g. relata's tools/docs.rb →
103
+ # chiridion) raises a raw 12-line uncaught backtrace with no
104
+ # indication the dx-use-local mechanism exists.
105
+ Output.error(e.message)
106
+ hint = bundle_setup_hint(e)
107
+ warn hint if hint
108
+ 1
95
109
  end
96
110
  end
97
111
 
@@ -336,5 +350,42 @@ module Devex
336
350
  puts "#{@executable_name} #{VERSION}"
337
351
  end
338
352
  end
353
+
354
+ # Diagnostic hint for the LoadError rescue (#run). Returns a string
355
+ # actionable for the user when a project tool's `require` failed
356
+ # *and* this project has a Gemfile but no delegation marker (and we
357
+ # aren't already inside a delegated re-exec). Returns nil when the
358
+ # situation doesn't match — the underlying error stands on its own.
359
+ #
360
+ # The matched situation is the exact one ADR-003's `.dx-use-local`
361
+ # solves: a global `dx` runs project `tools/*.rb` in-process, so a
362
+ # `require` of a bundle-only path-gem fails until the project opts
363
+ # into bundle delegation. Without this hint the failure mode is a
364
+ # raw 12-line LoadError backtrace with no signal that the
365
+ # affordance exists.
366
+ def bundle_setup_hint(error)
367
+ return nil unless @config.respond_to?(:delegation_file)
368
+
369
+ delegation_file = @config.delegation_file
370
+ return nil if delegation_file.nil? || delegation_file.empty?
371
+ return nil if ENV[@config.env_var(:delegated)] # already delegated; another problem
372
+
373
+ dirs = Dirs.new(config: @config)
374
+ return nil unless dirs.in_project?
375
+
376
+ project_dir = dirs.project_dir
377
+ return nil unless (project_dir / "Gemfile").exist?
378
+ return nil if (project_dir / delegation_file).exist?
379
+
380
+ gem_name = error.message[/cannot load such file -- (\S+)/, 1] || "the missing file"
381
+ <<~HINT.chomp
382
+ hint: '#{gem_name}' may be a project dev-dependency in this project's Gemfile.
383
+ The global `#{@executable_name}` runs project tools/*.rb in-process, OUTSIDE
384
+ the project's bundle, so a path-gem or bundle-only gem isn't on $LOAD_PATH.
385
+ To make `#{@executable_name}` re-exec under `bundle exec` for this project:
386
+ touch #{delegation_file}
387
+ See devex ADR-003 for the delegation contract.
388
+ HINT
389
+ end
339
390
  end
340
391
  end
data/lib/devex/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Devex
4
- VERSION = "0.3.7"
4
+ VERSION = "0.3.9"
5
5
  end
metadata CHANGED
@@ -1,14 +1,13 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: devex
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.7
4
+ version: 0.3.9
5
5
  platform: ruby
6
6
  authors:
7
7
  - Joseph A Wecker
8
- autorequire:
9
8
  bindir: exe
10
9
  cert_chain: []
11
- date: 2026-01-07 00:00:00.000000000 Z
10
+ date: 1980-01-02 00:00:00.000000000 Z
12
11
  dependencies: []
13
12
  description: |
14
13
  Devex provides a unified `dx` command for common development tasks. Features include:
@@ -24,31 +23,13 @@ executables:
24
23
  extensions: []
25
24
  extra_rdoc_files: []
26
25
  files:
27
- - ".obsidian/app.json"
28
- - ".obsidian/appearance.json"
29
- - ".obsidian/community-plugins.json"
30
- - ".obsidian/core-plugins.json"
31
- - ".obsidian/plugins/obsidian-minimal-settings/data.json"
32
- - ".obsidian/plugins/obsidian-minimal-settings/main.js"
33
- - ".obsidian/plugins/obsidian-minimal-settings/manifest.json"
34
- - ".obsidian/plugins/obsidian-style-settings/data.json"
35
- - ".obsidian/plugins/obsidian-style-settings/main.js"
36
- - ".obsidian/plugins/obsidian-style-settings/manifest.json"
37
- - ".obsidian/plugins/obsidian-style-settings/styles.css"
38
- - ".obsidian/plugins/table-editor-obsidian/data.json"
39
- - ".obsidian/plugins/table-editor-obsidian/main.js"
40
- - ".obsidian/plugins/table-editor-obsidian/manifest.json"
41
- - ".obsidian/plugins/table-editor-obsidian/styles.css"
42
- - ".obsidian/themes/AnuPpuccin/manifest.json"
43
- - ".obsidian/themes/AnuPpuccin/theme.css"
44
- - ".obsidian/themes/Minimal/manifest.json"
45
- - ".obsidian/themes/Minimal/theme.css"
46
26
  - ".rubocop.yml"
47
27
  - CHANGELOG.md
48
28
  - LICENSE
49
29
  - README.md
50
30
  - Rakefile
51
31
  - config/rubocop-dx.yml
32
+ - devex-0.3.7.gem
52
33
  - devex-logo.jpg
53
34
  - docs/developing-tools.md
54
35
  - docs/ref/agent-mode.md
@@ -101,7 +82,6 @@ licenses:
101
82
  metadata:
102
83
  changelog_uri: https://github.com/v2-io/devex/blob/main/CHANGELOG.md
103
84
  rubygems_mfa_required: 'true'
104
- post_install_message:
105
85
  rdoc_options: []
106
86
  require_paths:
107
87
  - lib
@@ -116,8 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
116
96
  - !ruby/object:Gem::Version
117
97
  version: '0'
118
98
  requirements: []
119
- rubygems_version: 3.5.22
120
- signing_key:
99
+ rubygems_version: 4.0.3
121
100
  specification_version: 4
122
101
  summary: Lightweight Ruby CLI framework with unified dx command for development tasks
123
102
  test_files: []
data/.obsidian/app.json DELETED
@@ -1,6 +0,0 @@
1
- {
2
- "vimMode": true,
3
- "showInlineTitle": false,
4
- "readableLineLength": false,
5
- "showLineNumber": true
6
- }
@@ -1,4 +0,0 @@
1
- {
2
- "showRibbon": true,
3
- "cssTheme": "AnuPpuccin"
4
- }
@@ -1,5 +0,0 @@
1
- [
2
- "table-editor-obsidian",
3
- "obsidian-style-settings",
4
- "obsidian-minimal-settings"
5
- ]