carton 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3d0c8755a90c3eb40d7ee29a16a174a89f1c678e43ba08275fab4502b298fae
+  data.tar.gz: 582512d0d84c6e3dfa2b49c9d95b5e77e4fac4a25a45b63b17bf9ed6087d65c1
+SHA512:
+  metadata.gz: f48e9cdd2c5c64d12f323de0acc65498f7e0c0aa7f230decdf5fae538337e268c07686e9f2b5017b4d38dd1b4c22bb2120bc5c54b5ce6884f59d7b319779b0e5
+  data.tar.gz: 1470bb044aaacf574535228f1bc9f12a84f0654651c3fbaa52fe52bcde0f215c9262eb0d603c6cc98239c29f4f44854b07534ff608af0bc206e701f2498f1cc0

data/AGENTS.md

@@ -0,0 +1,47 @@
+# Agents
+
+Guidance and memory for agents working on this repo.
+
+## Memory bank
+
+- Goal: make Carton feel like part of Ruby: built-in, simple, streamlined, and not verbose.
+- Prefer simpler implementation over complexity.
+- Keep the public API small and Ruby-like.
+- The project should work with or without Bundler.
+- A package in this system is called a carton, though docs can still use "package" in plain English when it reads better.
+- Current reliable bundled-carton pattern: use `Carton.with_bundle(gemfile) { import ... }` for the entry import that should activate a carton-local bundle.
+- Conflicting bundles still need a subprocess workaround today.
+- Ruby::Box boxes start from root-box load paths/loaded features, so Carton must copy parent non-gem load paths forward itself.
+- `$LOAD_PATH` is box-local, but `Gem.loaded_specs` is shared across boxes in practice, so conflicting bundle activation still collides there.
+- Duplicating `Gem.loaded_specs` inside a box isolates a single bundled import from root state, but conflicting bundles still fail because Bundler also rewrites shared RubyGems entrypoints/spec state such as `Gem::Specification.all`.
+- Never push. Make local commits only; the user handles pushes.
+
+## Working rules
+
+- Everything should have tests. Write tests for new behaviour, run targeted tests as you go, and `RUBY_BOX=1 bundle exec rake` before finishing.
+- If you only changed an example, run that example during iteration and the full suite before finishing.
+- Run `bundle exec rake format` after every change.
+- Keep implementation and docs concise.
+- Do not over-engineer.
+- Never use thread local variables in implementation.
+- Always review https://docs.ruby-lang.org/en/4.0/Ruby/Box.html on how `Ruby::Box` works.
+- Never bump the version or publish the gem.
+- When multiple implementation choices are viable, present a menu with your recommendation.
+- Commit as you go with descriptive messages and the required Co-authored-by trailer.
+- Never push; the user will do that.
+
+## Docs
+
+- Keep `README.md`, `USAGE.md`, `DESIGN.md`, `TODO.md`, `AGENTS.md`, and example READMEs up to date when behavior, workflow, or plans change.
+- Keep the root `README.md` minimal; move detail into focused docs.
+- Put future work, open questions, and upstream ideas in `TODO.md`.
+- Update `AGENTS.md` whenever the user gives durable project guidance or you discover stable context worth remembering.
+- Use `AGENTS.md` as a concise memory bank, not a changelog.
+
+## Commands
+
+- `RUBY_BOX=1 bundle exec rake` - full suite
+- `RUBY_BOX=1 bundle exec rake test` - unit tests only
+- `RUBY_BOX=1 bundle exec rake example:minimal` - minimal example
+- `RUBY_BOX=1 bundle exec rake example:complex` - complex example
+- `bundle exec rake format` - format code

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-16
+
+Initial release.
+
+[Unreleased]: https://github.com/dtcristo/carton/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dtcristo/carton/releases/tag/v0.1.0

data/DESIGN.md

@@ -0,0 +1,84 @@
+# Design
+
+## Goal
+
+Keep the library small: a thin wrapper around `Ruby::Box` that makes isolated file-to-file imports feel like part of Ruby.
+
+## Main pieces
+
+| File | Role |
+| --- | --- |
+| `lib/carton.rb` | Entry point, version guard, `Carton.with_bundle`, and internal wiring |
+| `lib/carton/kernel_patch.rb` | Adds global `import`, `import_relative`, `export_default`, and `export` |
+| `lib/carton/runtime.rb` | Builds boxes, resolves targets, runs imports, and extracts exports |
+| `lib/carton/box.rb` | Box-specific helpers for requiring files, managing export state, and inheriting safe load paths |
+| `lib/carton/exports.rb` | Wraps named exports in a module-like namespace |
+| `lib/carton/export_methods.rb` | Shared `[]`, `fetch`, `fetch_values`, `values_at`, `key?`, and destructuring support |
+
+## Import flow
+
+1. `import` or `import_relative` delegates to `Carton::Runtime.import`.
+2. A fresh `Carton::Box` is created for that import.
+3. The carton entrypoint (`lib/carton.rb`) is required inside the box so the box has `export`, `import`, and `import_relative`.
+4. The target file is resolved either from the caller's base directory or from the current box's `$LOAD_PATH`.
+5. The target file is required inside the box.
+6. If the file called `export_default` or `export`, the exported value is returned.
+7. If the export was a hash, it is wrapped in `Carton::Exports`.
+8. If there was no export, the box itself is returned.
+
+Every import creates a fresh box. There is no module cache at the Carton layer.
+
+## Export model
+
+There are three return shapes:
+
+- single export: the exported object itself
+- named exports: `Carton::Exports`
+- no export: `Carton::Box`
+
+`export_default` is the explicit single-export form. `export` is the named-export form and only accepts keyword arguments. `Carton::Exports` exposes capitalized keys as constants and lowercase keys as singleton methods. Both `Carton::Exports` and `Carton::Box` share the same small fetch/deconstruction API through `ExportMethods`.
+
+## Load path model
+
+Ruby::Box creates new user boxes from the root box, not from the current caller box. In `box.c`, each new box starts by duplicating the root box's `load_path` and `loaded_features`, and `require` resolves against the loading box's local `$LOAD_PATH` / `$LOADED_FEATURES`.
+
+Carton therefore re-inherits the parent box's non-gem load paths manually so local carton directories can still be resolved by name across nested imports.
+
+The current filter deliberately tries to avoid leaking gem paths from a parent import chain into child boxes:
+
+- RubyGems paths are filtered
+- common Bundler vendor paths are filtered
+- local, non-gem carton paths are preserved
+
+This is why the examples add sibling `lib/` directories to `$LOAD_PATH` explicitly before using `import 'name'`.
+
+## Bundler model
+
+The current implementation works best when a carton bundle is selected before its entry file is evaluated. In practice that means selecting `BUNDLE_GEMFILE` around the `import` call for that carton; `Carton.with_bundle` is the small wrapper for that handoff.
+
+This keeps one carton-local bundle isolated from the caller, but current limitations remain:
+
+- a parent already running under Bundler is not a reliable place to import a child carton with its own bundle
+- switching between conflicting bundles in one process is not reliable today
+- the complex example uses a subprocess for the conflicting `loot` bundle for that reason
+
+The problem is not that Bundler has special C code mutating every box at once. Bundler and RubyGems do their activation work in Ruby:
+
+- `Bundler::SharedHelpers#find_gemfile` reads `ENV['BUNDLE_GEMFILE']`
+- `Bundler::Runtime#setup` calls `clean_load_path`, `replace_entrypoints`, `mark_loaded`, and `Gem.add_to_load_path`
+- RubyGems activation checks and writes `Gem.loaded_specs`
+
+What matters under `Ruby::Box` is which of those pieces are box-local. In practice:
+
+- `$LOAD_PATH` stays box-local; activating a bundle in an imported box does not inject its gem lib paths into the caller box
+- `Gem.loaded_specs` is still shared across boxes in practice unless it is explicitly replaced inside the box
+
+Duplicating `Gem.loaded_specs` inside an imported box was enough to keep a single bundled import from leaking back into the caller box, but it was still not enough to make two conflicting bundles coexist. Bundler also rewrites RubyGems entrypoints and spec state through code paths such as `replace_entrypoints`, `stub_rubygems`, `Gem::Specification.all = ...`, and `Gem.clear_paths`.
+
+That shared activation state is why a second box can see a gem version activated by the first one even though its own `$LOAD_PATH` is separate. In local probes, activating `dotenv 3.2.0` in one box caused a second box targeting `dotenv ~> 2.0` to fail its Bundler activation and then crash under Ruby 4.0 + `Ruby::Box`.
+
+See [TODO.md](TODO.md) for the upstream work that would help.
+
+## Why the complex example stays explicit
+
+The complex example keeps load-path setup and bundled imports visible in `main.rb` on purpose. It is meant to demonstrate Carton directly, not hide the mechanics behind another layer.

data/LICENSE.txt

@@ -0,0 +1,19 @@
+The MIT License (MIT)
+
+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,67 @@
+<div align="center">
+  <h1>
+    Carton
+  </h1>
+  <img src="images/carton.png" alt="Carton logo" width="200" />
+  <p>
+    <strong>
+      Easily box your Ruby
+    </strong>
+  </p>
+</div>
+
+Carton is a thin wrapper around [`Ruby::Box`](https://docs.ruby-lang.org/en/4.0/Ruby/Box.html) for safe, ergonomic modularization in Ruby 4+. It gives you imports and exports that feel like ES Modules while still reading like Ruby. Each carton can isolate constants, gems, and monkey patches behind a small public API, so large apps can keep clear boundaries.
+
+## Minimal usage
+
+```ruby
+# user.rb
+class User
+  def initialize(name) = @name = name
+end
+
+export_default User
+```
+
+```ruby
+# main.rb
+require 'carton'
+
+User = import_relative 'user'
+alice = User.new('Alice')
+```
+
+Named exports return a namespace-like module:
+
+```ruby
+# math.rb
+def add(a, b) = a + b
+
+export PI: 3.14159, add: method(:add)
+```
+
+```ruby
+MathTools = import_relative 'math'
+MathTools::PI
+MathTools.add(2, 3)
+```
+
+## Docs
+
+- [USAGE.md](USAGE.md) - detailed import/export, load path, and Bundler usage
+- [DESIGN.md](DESIGN.md) - implementation overview and constraints
+- [TODO.md](TODO.md) - future improvements and Bundler upstream ideas
+- [examples/minimal/README.md](examples/minimal/README.md) - smallest example
+- [examples/complex/README.md](examples/complex/README.md) - multi-carton example
+
+## Development
+
+```sh
+bundle install                        # Install development deps
+RUBY_BOX=1 bundle exec rake           # Run all tests and examples
+bundle exec rake format               # Format code
+```
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+STREE_FILES = '"**/*.{rb,rake,gemspec}" "**/Rakefile" "**/Gemfile"'
+EXAMPLES = %w[minimal complex].freeze
+
+desc 'Run all tests'
+task :test do
+  test_files =
+    Dir.glob('test/**/*_test.rb').sort.map { |f| File.expand_path(f) }
+  sh "RUBY_BOX=1 ruby -Ilib -Itest -e 'ARGV.each { |f| require f }' #{test_files.join(' ')}",
+     verbose: false
+end
+
+namespace :example do
+  EXAMPLES.each do |name|
+    desc "Run the #{name} example"
+    task name.to_sym do
+      dir = File.join('examples', name)
+
+      puts
+      puts "== Running example/#{name} =="
+      puts
+
+      Bundler.with_unbundled_env do
+        # Install gems for any carton/local example gemfile.
+        Dir
+          .glob(File.join(dir, '**/Gemfile'))
+          .each do |gemfile|
+            pkg_dir = File.dirname(gemfile)
+            sh(
+              "cd #{pkg_dir} && " \
+                'BUNDLE_GEMFILE=Gemfile bundle check >/dev/null 2>&1 || ' \
+                'BUNDLE_GEMFILE=Gemfile bundle install --quiet',
+              verbose: false,
+            )
+          end
+
+        sh "RUBY_BOX=1 ruby #{File.join(dir, 'main.rb')}", verbose: false
+      end
+    end
+  end
+end
+
+desc 'Run all examples'
+task examples: EXAMPLES.map { |n| "example:#{n}" }
+
+desc 'Format code'
+task :format do
+  sh "bundle exec stree write #{STREE_FILES}", verbose: false
+end
+
+task default: %i[test examples]

data/TODO.md

@@ -0,0 +1,33 @@
+# TODO
+
+## Bundler / upstream
+
+- Add a Bundler API that can activate a specific Gemfile explicitly instead of relying on process-global `ENV['BUNDLE_GEMFILE']` and `bundler/setup`.
+- Make multiple bundle contexts safer for embedded runtimes. Today one carton-local bundle can work, but importing a second conflicting bundle in the same process still resolves against the first bundle's shared RubyGems activation state and can crash under `Ruby::Box`.
+- Expose resolved bundle load paths without forcing full `Bundler.setup` and RubyGems entrypoint replacement.
+- Make `Bundler.reset!`, `with_original_env`, and `with_unbundled_env` sufficient for re-entering Bundler with another Gemfile, or add a supported replacement for that workflow.
+- Improve support for a parent process already running under Bundler importing a child carton that needs a different bundle.
+- Make RubyGems activation state such as `Gem.loaded_specs` safely box-local or otherwise explicitly isolateable so two conflicting bundles can coexist under `Ruby::Box` without a subprocess.
+- Investigate whether `Bundler.rubygems.replace_entrypoints`, `stub_rubygems`, `Gem::Specification.all`, and `Gem.clear_paths` can be made box-local. Duplicating `Gem.loaded_specs` inside the box isolated a single bundled import from the root box, but it was not enough to make a second conflicting bundle work.
+
+## Ruby::Box / upstream
+
+- Expose more public APIs or clearer guarantees around box-local `$LOAD_PATH`, `$LOADED_FEATURES`, and feature resolution so libraries like Carton do not need to manually copy parent load paths and call `resolve_feature_path`.
+- Investigate the crash path after conflicting bundled imports under Ruby 4.0 + `Ruby::Box`, even when the immediate conflict is already surfaced as a Bundler/RubyGems activation error.
+
+## Library
+
+- Revisit `Carton::Box#gem_path?`; it still relies partly on path heuristics.
+- Add targeted tests for bundled carton imports instead of covering that behavior only through the complex example.
+- Remove the targeted Minitest `object_id` warning suppression once Ruby::Box or Minitest no longer emits it under Ruby 4.0.
+- Revisit whether `import` should always return a `Carton::Exports` wrapper with a `default` accessor, or whether the current duck-typed return values are the better long-term fit.
+
+## Examples / docs
+
+- Keep the root README intentionally short and push detail into focused docs.
+- Keep documenting current Bundler constraints plainly until the runtime or Bundler story improves.
+
+## Tooling ideas
+
+- Explore a Prism-based strict mode/linter that enforces `import`/`export` calls at file root and can build a static dependency graph without evaluating code.
+- If that exists, add graph validation ideas such as cycle detection, missing import targets, dead imports, and unused exports.

data/USAGE.md

@@ -0,0 +1,173 @@
+# Usage
+
+## Requirements
+
+- Ruby 4.0+
+- `RUBY_BOX=1`
+- `require 'carton'` before using `import`, `import_relative`, `export_default`, or `export`
+
+In Carton, an importable package is called a carton. This guide still says "package" sometimes in plain English, but "carton" is the project term.
+
+## Exporting
+
+### Single export
+
+Use a single export when the file represents one main thing.
+
+```ruby
+# user.rb
+class User
+  def initialize(name) = @name = name
+
+  def greet = "Hello, #{@name}!"
+end
+
+export_default User
+```
+
+Importing that file returns the exported object itself:
+
+```ruby
+User = import_relative 'user'
+User.new('Alice').greet
+```
+
+### Named exports
+
+Use keyword arguments when the file exports a small namespace.
+
+```ruby
+# math.rb
+def add(a, b) = a + b
+
+export(
+  PI: 3.14159,
+  version: '1.0.0',
+  add: method(:add)
+)
+```
+
+Importing named exports returns a `Carton::Exports` object, which behaves like a namespace module.
+
+```ruby
+MathTools = import_relative 'math'
+
+MathTools::PI
+MathTools.version
+MathTools.add(2, 3)
+```
+
+`Carton::Exports` and bare `Carton::Box` imports share a small lookup API: `[]`, `fetch`, `fetch_values`, `values_at`, and `key?`.
+
+Only one export call is allowed per imported file. Use `export_default value` for single exports or `export foo:, bar:` for named exports.
+
+## Importing
+
+### `import_relative`
+
+`import_relative path` resolves relative to the calling file, like `require_relative`.
+
+```ruby
+User = import_relative 'user'
+```
+
+### `import`
+
+`import path` resolves using the current box's `$LOAD_PATH` or an absolute path.
+
+```ruby
+Quest = import 'quest'
+Widget = import '/absolute/path/to/widget.rb'
+```
+
+When you want `import 'name'` to work across local cartons, add their `lib/` directories to `$LOAD_PATH` first.
+
+```ruby
+cartons_dir = File.expand_path('cartons', __dir__)
+
+Dir.glob(File.join(cartons_dir, '*/lib')).sort.each do |dir|
+  $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir)
+end
+```
+
+The complex example keeps that setup explicit in `examples/complex/main.rb`.
+
+## Destructuring
+
+Named exports support pattern matching through `deconstruct_keys`.
+
+```ruby
+import_relative('math') => { add:, version: }
+
+add.(2, 3)
+version
+```
+
+You can rename during destructuring:
+
+```ruby
+import_relative('math') => { add: sum }
+sum.(10, 10)
+```
+
+## Constants
+
+For exported constants, the simplest options are namespace access, `[]`, or `fetch`.
+
+```ruby
+MathTools = import_relative 'math'
+PI = MathTools::PI
+```
+
+```ruby
+PI = import('math')[:PI]
+```
+
+For multiple values:
+
+```ruby
+PI, version = import_relative('math').fetch_values(:PI, :version)
+```
+
+## Bare imports
+
+If a file does not call `export`, importing it returns the `Carton::Box` itself.
+
+```ruby
+Toolbox = import 'some_script'
+
+Toolbox::SomeConstant
+Toolbox.fetch(:helper)
+```
+
+## Bundler inside cartons
+
+The library works with or without Bundler. Plain cartons need no extra setup. For a bundled carton, the reliable pattern today is still: select the Gemfile around the `import` that loads that carton.
+
+```ruby
+gemfile = File.expand_path('cartons/adventure/Gemfile', __dir__)
+
+Adventure = Carton.with_bundle(gemfile) { import 'adventure' }
+```
+
+`Carton.with_bundle` is just a small wrapper around the same `BUNDLE_GEMFILE` handoff. The underlying constraint is still Bundler's: `bundler/setup` discovers the active Gemfile from env/process state, and RubyGems activation state (`Gem.loaded_specs`) is still shared across boxes in practice, so conflicting bundles still cannot be switched reliably in one process today.
+
+Current limits:
+
+- one carton-local bundle can be activated cleanly from an unbundled parent
+- a bundled parent process is not a reliable place to import a child carton with its own bundle
+- conflicting bundles in one process still need a subprocess workaround
+
+See [TODO.md](TODO.md) for the upstream Bundler work that would make this cleaner.
+
+## Examples
+
+```sh
+RUBY_BOX=1 ruby examples/minimal/main.rb
+RUBY_BOX=1 bundle exec rake example:complex
+```
+
+See the example READMEs for details:
+
+- [examples/minimal/README.md](examples/minimal/README.md)
+- [examples/complex/README.md](examples/complex/README.md)

data/examples/complex/README.md

@@ -0,0 +1,33 @@
+# Complex example
+
+Multi-carton example showing the library directly: explicit load-path setup, a bundled single export loaded by name, a plain carton loaded by name, and a destructured import.
+
+## Cartons
+
+| Carton | Purpose |
+| --- | --- |
+| `main` | explicit feature tour of the library |
+| `adventure` | bundled carton imported by name |
+| `quest` | plain carton imported by name |
+| `loot` | carton that demonstrates a conflicting `dotenv` version via subprocess |
+
+`main.rb` keeps the load-path setup and bundled import explicit on purpose so the example reads like a direct Carton feature tour. `Carton.with_bundle` shortens the `BUNDLE_GEMFILE` handoff, but it is still the same Bundler constraint under the hood.
+
+## Why `loot` still uses a subprocess
+
+One carton-local bundle can be activated from an unbundled parent today. The trouble starts when another box tries to activate a conflicting version: box-local `$LOAD_PATH` is not enough because RubyGems activation state is still shared. `loot` therefore loads its `dotenv` data in a subprocess and selects its Gemfile there instead of using `Carton.with_bundle` during the import itself. That is tracked in [../../TODO.md](../../TODO.md).
+
+## Run
+
+```sh
+RUBY_BOX=1 bundle exec rake example:complex
+```
+
+Or manually:
+
+```sh
+cd examples/complex/cartons/adventure && BUNDLE_GEMFILE=Gemfile bundle install
+cd ../loot && BUNDLE_GEMFILE=Gemfile bundle install
+cd ../../..
+RUBY_BOX=1 ruby examples/complex/main.rb
+```

data/examples/complex/cartons/adventure/.env

@@ -0,0 +1 @@
+BANNER=single export loaded from a bundled carton

data/examples/complex/cartons/adventure/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'dotenv', '~> 3.0'

data/examples/complex/cartons/adventure/Gemfile.lock

@@ -0,0 +1,17 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    dotenv (3.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  dotenv (~> 3.0)
+
+CHECKSUMS
+  dotenv (3.2.0) sha256=e375b83121ea7ca4ce20f214740076129ab8514cd81378161f11c03853fe619d
+
+BUNDLED WITH
+  4.0.3

data/examples/complex/cartons/adventure/lib/adventure.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'dotenv'
+
+module Adventure
+  CONFIG = Dotenv.parse(File.expand_path('../.env', __dir__))
+  def self.banner = CONFIG.fetch('BANNER')
+
+  def self.dotenv_version = Gem.loaded_specs.fetch('dotenv').version.to_s
+end
+
+export_default Adventure

data/examples/complex/cartons/loot/.env

@@ -0,0 +1 @@
+MESSAGE=loaded through a conflicting bundle in a subprocess

data/examples/complex/cartons/loot/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'dotenv', '~> 2.0'

data/examples/complex/cartons/loot/Gemfile.lock

@@ -0,0 +1,17 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    dotenv (2.8.1)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  dotenv (~> 2.0)
+
+CHECKSUMS
+  dotenv (2.8.1) sha256=c5944793349ae03c432e1780a2ca929d60b88c7d14d52d630db0508c3a8a17d8
+
+BUNDLED WITH
+  4.0.3

data/examples/complex/cartons/loot/lib/loot.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'open3'
+require 'rbconfig'
+
+Plans = import 'quest'
+
+# This carton is imported plainly by name. The subprocess below is where it
+# selects its own Gemfile, because doing the conflicting dotenv activation
+# directly in another box still collides through shared RubyGems activation
+# state and can even crash under Ruby::Box today.
+dotenv_payload =
+  begin
+    env_file = File.expand_path('../.env', __dir__)
+    gemfile = File.expand_path('../Gemfile', __dir__)
+    script = <<~'RUBY'
+      require 'json'
+      require 'bundler/setup'
+      require 'dotenv'
+
+      config = Dotenv.parse(ARGV.fetch(0))
+      version = Gem.loaded_specs.fetch('dotenv').version.to_s
+      puts JSON.generate(version:, config:)
+    RUBY
+
+    output, status =
+      Open3.capture2e(
+        { 'BUNDLE_GEMFILE' => gemfile },
+        RbConfig.ruby,
+        '-e',
+        script,
+        env_file,
+      )
+
+    unless status.success?
+      raise RuntimeError, "failed to load loot dotenv bundle: #{output}"
+    end
+
+    JSON.parse output
+  end
+
+dotenv_version = dotenv_payload.fetch 'version'
+legacy_message =
+  "#{dotenv_payload.fetch('config').fetch('MESSAGE')} | quest says: #{Plans.fetch :summary}"
+
+export legacy_message:, DOTENV_VERSION: dotenv_version

data/examples/complex/cartons/quest/lib/quest.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+FEATURES = ['single exports', 'named exports', 'import by name'].freeze
+SUMMARY = 'plain carton loaded by name'
+
+export FEATURES:, summary: SUMMARY

data/examples/complex/main.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/carton'
+
+cartons_dir = File.expand_path('cartons', __dir__)
+
+# Local carton lib directories still need to be on the caller's load path when
+# we want import 'name' to resolve inside nested boxes.
+Dir
+  .glob(File.join(cartons_dir, '*/lib'))
+  .sort
+  .each { |dir| $LOAD_PATH.unshift(dir) unless $LOAD_PATH.include?(dir) }
+
+adventure_gemfile = File.expand_path('cartons/adventure/Gemfile', __dir__)
+
+# Bundler still picks the active Gemfile from env/process state today, so the
+# bundled import stays explicit even though the wrapper is small.
+Adventure = Carton.with_bundle(adventure_gemfile) { import 'adventure' }
+
+Plans = import 'quest'
+
+# loot still imports by name, but it does not need Carton.with_bundle here
+# because the conflicting dotenv activation happens entirely in the subprocess
+# inside loot.rb, not during this import itself.
+import('loot') => { legacy_message:, DOTENV_VERSION: loot_dotenv_version }
+
+puts '-- Bundled single export --'
+puts "Adventure.banner = #{Adventure.banner}"
+puts "Adventure.dotenv_version = #{Adventure.dotenv_version}"
+puts
+puts '-- Named export loaded by name --'
+puts "Plans::FEATURES = #{Plans::FEATURES.join(', ')}"
+puts "Plans.summary = #{Plans.fetch :summary}"
+puts
+puts '-- Destructured named export --'
+puts "loot dotenv version = #{loot_dotenv_version}"
+puts "legacy_message = #{legacy_message}"

data/examples/minimal/README.md

@@ -0,0 +1,16 @@
+# Minimal example
+
+Smallest working example of the library.
+
+## What it shows
+
+- single export (`foo.rb`, `baz.rb`)
+- named exports (`bar.rb`)
+- `import_relative`
+- one carton importing another carton internally
+
+## Run
+
+```sh
+RUBY_BOX=1 ruby examples/minimal/main.rb
+```

data/examples/minimal/bar.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Bar depends on Baz via import_relative
+Baz = import_relative 'baz'
+
+def hello
+  "Hello from Bar! (#{Baz.hello})"
+end
+
+export hello: method(:hello), MAGIC: 42

data/examples/minimal/baz.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Baz
+  def self.hello = 'Hello from Baz!'
+end
+
+export_default Baz

data/examples/minimal/foo.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Foo
+  def self.hello = 'Hello from Foo!'
+end
+
+export_default Foo

data/examples/minimal/main.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/carton'
+
+# Single import — Foo exports a module
+Foo = import_relative 'foo'
+
+# Namespace import — Bar exports a hash with methods and constants
+Bar = import_relative 'bar'
+
+puts '-- Foo --'
+puts Foo.hello
+
+puts
+puts '-- Bar (uses Baz internally) --'
+puts Bar.hello
+puts "Bar::MAGIC = #{Bar::MAGIC}"

data/lib/carton/box.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Carton
+  class Box < Ruby::Box
+    include ExportMethods
+
+    UNSET_EXPORT = Object.new.freeze
+    private_constant :UNSET_EXPORT
+
+    def initialize
+      super
+      reset_export
+    end
+
+    private
+
+    def configure_for_import(parent_box:, entrypoint:, bundle_gemfile:)
+      inherit_load_path(parent_box)
+      reset_export
+      require_in_box(entrypoint)
+      set_bundle_gemfile(bundle_gemfile)
+      self
+    end
+
+    def require_in_box(feature)
+      eval("require #{feature.inspect}")
+    end
+
+    def resolve_feature_path_in_box(feature)
+      eval("$LOAD_PATH.resolve_feature_path(#{feature.inspect})")
+    end
+
+    def activate_bundle_if_configured
+      gemfile = ENV['BUNDLE_GEMFILE']
+      return unless gemfile && File.file?(gemfile)
+
+      require_in_box('bundler/setup')
+    end
+
+    def set_export(value)
+      if export_set?
+        raise RuntimeError, 'only one export is allowed per imported file'
+      end
+
+      @export = value
+    end
+
+    def export_set?
+      !@export.equal?(UNSET_EXPORT)
+    end
+
+    def export_value
+      @export
+    end
+
+    def reset_export
+      @export = UNSET_EXPORT
+    end
+
+    def set_bundle_gemfile(path)
+      return unless path
+
+      eval("ENV['BUNDLE_GEMFILE'] = #{path.inspect}")
+    end
+
+    def inherit_load_path(source_box)
+      return self unless source_box.respond_to?(:load_path)
+
+      source_box.load_path.each do |path|
+        next unless inherit_path?(path)
+
+        load_path << path unless load_path.include?(path)
+      end
+
+      self
+    end
+
+    def inherit_path?(path)
+      expanded = File.expand_path(path)
+      !gem_path?(expanded)
+    end
+
+    def gem_path?(path)
+      gem_roots = Gem.path.map { |root| File.expand_path(root) }
+      gem_roots.any? { |root| path == root || path.start_with?("#{root}/") } ||
+        path.include?('/vendor/bundle/') || path.include?('/bundler/gems/')
+    end
+
+    def lookup_entry(key)
+      name = key.to_s
+
+      if name.match?(/\A[A-Z]/)
+        lookup_constant_entry(name)
+      else
+        lookup_method_entry(name)
+      end
+    end
+
+    def lookup_constant_entry(name)
+      [true, const_get(name)]
+    rescue NameError
+      [false, nil]
+    end
+
+    def lookup_method_entry(name)
+      [true, eval(name)]
+    rescue NameError, NoMethodError
+      begin
+        [true, __send__(name)]
+      rescue NoMethodError
+        [false, nil]
+      end
+    end
+  end
+end

data/lib/carton/export_methods.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Carton
+  module ExportMethods
+    def deconstruct_keys(keys)
+      return {} unless keys
+
+      keys.each_with_object({}) do |key, hash|
+        found, value = lookup_entry(key)
+        hash[key] = value if found
+      end
+    end
+
+    def [](key)
+      found, value = lookup_entry(key)
+      found ? value : nil
+    end
+
+    def key?(key)
+      lookup_entry(key).first
+    end
+
+    alias has_key? key?
+
+    def fetch(key, *default)
+      if default.size > 1
+        raise ArgumentError,
+              "wrong number of arguments (given #{default.size + 1}, expected 1..2)"
+      end
+
+      found, value = lookup_entry(key)
+      return value if found
+      return yield key if block_given?
+      return default.first unless default.empty?
+
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    def fetch_values(*keys)
+      keys.map { |key| fetch(key) }
+    end
+
+    def values_at(*keys)
+      keys.map { |key| self[key] }
+    end
+  end
+end

data/lib/carton/exports.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Carton
+  class Exports < ::Module
+    include ExportMethods
+
+    def initialize(values = {})
+      super()
+      @values = values
+      @lookup = {}
+      define_exports
+    end
+
+    private
+
+    def define_exports
+      @values.each do |key, value|
+        @lookup[key.to_s] = value
+
+        if key.to_s.match?(/\A[A-Z]/)
+          const_set(key, value)
+        else
+          define_singleton_method(
+            key,
+          ) { |*args, **kwargs, &block| value.respond_to?(:call) ? value.call(*args, **kwargs, &block) : value }
+        end
+      end
+    end
+
+    def lookup_entry(key)
+      name = key.to_s
+      @lookup.key?(name) ? [true, @lookup[name]] : [false, nil]
+    end
+  end
+end

data/lib/carton/kernel_patch.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Carton
+  module KernelPatch
+    def import(path)
+      Runtime.import(path, base_dir: Dir.pwd)
+    end
+
+    def import_relative(path)
+      caller_dir = File.dirname(caller_locations(1, 1).first.path)
+      Runtime.import(path, base_dir: caller_dir)
+    end
+
+    def export(*args, **kwargs)
+      Runtime.export(args, kwargs)
+    end
+
+    def export_default(value)
+      Runtime.export_default(value)
+    end
+  end
+end
+
+# Inject only the Kernel patch module into Kernel.
+::Kernel.prepend(Carton::KernelPatch)

data/lib/carton/runtime.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Carton
+  module Runtime
+    ENTRYPOINT = File.expand_path('../carton.rb', __dir__)
+    private_constant :ENTRYPOINT
+
+    module_function
+
+    def import(path, base_dir:)
+      box = build_import_box
+      target = resolve_import_target(box, path, base_dir:)
+      box.__send__(:activate_bundle_if_configured) if target == path
+      box.__send__(:require_in_box, target)
+      extract_export(box)
+    end
+
+    def export(args, kwargs)
+      if args.any? || kwargs.empty?
+        raise ArgumentError,
+              'export takes keyword arguments; use export_default for a single export'
+      end
+
+      current_import_box.__send__(:set_export, kwargs)
+    end
+
+    def export_default(value)
+      current_import_box.__send__(:set_export, value)
+    end
+
+    def build_import_box
+      parent_box = Ruby::Box.current
+      box = Carton::Box.new
+      bundle_gemfile = parent_box.eval("ENV['BUNDLE_GEMFILE']")
+      box.__send__(
+        :configure_for_import,
+        parent_box:,
+        entrypoint: ENTRYPOINT,
+        bundle_gemfile:,
+      )
+      box
+    end
+    private_class_method :build_import_box
+
+    def extract_export(box)
+      return box unless box.__send__(:export_set?)
+
+      value = box.__send__(:export_value)
+      value.is_a?(Hash) ? Carton::Exports.new(value) : value
+    end
+    private_class_method :extract_export
+
+    def current_import_box
+      box = Ruby::Box.current
+
+      unless box.respond_to?(:set_export, true)
+        raise RuntimeError,
+              'export/export_default must be called from inside Carton.import/import_relative'
+      end
+
+      box
+    end
+    private_class_method :current_import_box
+
+    def resolve_import_target(box, path, base_dir:)
+      expanded = File.expand_path(path, base_dir)
+      return expanded if File.file?(expanded)
+
+      expanded_rb = "#{expanded}.rb"
+      return expanded_rb if File.file?(expanded_rb)
+
+      resolved = box.__send__(:resolve_feature_path_in_box, path)
+      return path unless resolved
+
+      type, resolved_path = resolved
+      return resolved_path if type == :rb && File.file?(resolved_path)
+
+      path
+    end
+    private_class_method :resolve_import_target
+  end
+end

data/lib/carton/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Carton
+  VERSION = '0.1.0'
+end

data/lib/carton.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+raise 'Ruby 4.0+ is required for Carton' if RUBY_VERSION.to_f < 4.0
+
+module Carton
+  module_function
+
+  def with_bundle(gemfile)
+    previous = ENV['BUNDLE_GEMFILE']
+    ENV['BUNDLE_GEMFILE'] = gemfile
+    yield
+  ensure
+    if previous
+      ENV['BUNDLE_GEMFILE'] = previous
+    else
+      ENV.delete 'BUNDLE_GEMFILE'
+    end
+  end
+end
+
+require_relative 'carton/export_methods'
+require_relative 'carton/exports'
+require_relative 'carton/box'
+require_relative 'carton/runtime'
+require_relative 'carton/kernel_patch'
+
+module Carton
+  private_constant :ExportMethods
+  private_constant :Runtime
+  private_constant :KernelPatch
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: carton
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- David Cristofaro
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Carton is a thin wrapper around Ruby::Box for safe, ergonomic modularization
+  in Ruby 4+. It gives you imports and exports that feel like ES Modules while still
+  reading like Ruby. Each carton can isolate constants, gems, and monkey patches behind
+  a small public API, so large apps can keep clear boundaries.
+email:
+- david@dtcristo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CHANGELOG.md
+- DESIGN.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- TODO.md
+- USAGE.md
+- examples/complex/README.md
+- examples/complex/cartons/adventure/.env
+- examples/complex/cartons/adventure/Gemfile
+- examples/complex/cartons/adventure/Gemfile.lock
+- examples/complex/cartons/adventure/lib/adventure.rb
+- examples/complex/cartons/loot/.env
+- examples/complex/cartons/loot/Gemfile
+- examples/complex/cartons/loot/Gemfile.lock
+- examples/complex/cartons/loot/lib/loot.rb
+- examples/complex/cartons/quest/lib/quest.rb
+- examples/complex/main.rb
+- examples/minimal/README.md
+- examples/minimal/bar.rb
+- examples/minimal/baz.rb
+- examples/minimal/foo.rb
+- examples/minimal/main.rb
+- images/carton.png
+- lib/carton.rb
+- lib/carton/box.rb
+- lib/carton/export_methods.rb
+- lib/carton/exports.rb
+- lib/carton/kernel_patch.rb
+- lib/carton/runtime.rb
+- lib/carton/version.rb
+homepage: https://github.com/dtcristo/carton
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/dtcristo/carton
+  source_code_uri: https://github.com/dtcristo/carton
+  changelog_uri: https://github.com/dtcristo/carton/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Easily box your Ruby
+test_files: []