boxwerk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45cabb7d61d5029a494703a95c1b974f1af7ee1286001d457ea7aaf8b870496c
+  data.tar.gz: fb14ec2556787d19618ee3599685a06a06a4d1ed40a3113c47f61420f84fb202
+SHA512:
+  metadata.gz: 8e11bee2fd442bc29b537d4e7099e4380b19bed851f4f40bd42e119c35f139ee680866bd0f6189334e46652881c224559e10c6ab4dcf722c4d50c455fccdf16e
+  data.tar.gz: 0c69bf3a342d8fd502d6e64d085edfa9d1a2864b60d8f3f683addc680080f5762246f9901926c81667c40ddad82fdae7ead6e939ea3f297c0f907c983e21622f

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0] - 2026-01-05
+
+Initial release.
+
+[unreleased]: https://github.com/dtcristo/boxwerk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dtcristo/boxwerk/releases/tag/v0.1.0

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,376 @@
+# Boxwerk
+
+Boxwerk is a runtime package system for Ruby with strict isolation of constants using Ruby 4.0's [`Ruby::Box`](https://docs.ruby-lang.org/en/master/Ruby/Box.html). It is used to organize code into packages with explicit dependency graphs and strict access to constants between packages. It is inspired by [Packwerk](https://github.com/Shopify/packwerk), a static package system.
+
+## Features
+
+- **Strict Isolation**: Each package runs in its own `Ruby::Box`, preventing constants from leaking without explicit imports or exports.
+- **Explicit Dependencies**: Dependencies are declared in `package.yml` files, forming a validated DAG.
+- **Ergonomic Imports**: Flexible import strategies (namespaced, aliased, selective, renamed).
+
+## Limtations
+
+- There is no isolation of gems.
+- Gems are required to be eager loaded in the root box to be accessible in packages.
+- No support for reloading of constants.
+- Exported constants must follow Zeitwerk naming conventions for their source location.
+
+## Requirements
+
+- Ruby 4.0+ with [`Ruby::Box`](https://docs.ruby-lang.org/en/master/Ruby/Box.html) support
+- `RUBY_BOX=1` environment variable must be set at process startup
+
+## Quick Start
+
+### 1. Create a Package Structure
+
+```
+my_app/
+├── Gemfile                  # Your gem dependencies
+├── package.yml              # Root package
+├── app.rb                   # Your application entrypoint
+└── packages/
+    └── billing/
+        ├── package.yml      # Package manifest
+        └── lib/
+            └── invoice.rb   # Package code
+```
+
+### 2. Define Your Gemfile
+
+**`Gemfile`:**
+```ruby
+source 'https://rubygems.org'
+
+gem 'boxwerk'
+gem 'money' # Example: gems are auto-required and globally accessible
+```
+
+### 3. Define Packages
+
+**Root `package.yml`:**
+```yaml
+imports:
+  - packages/finance # Will define a `Finance` module to hold finance package exports
+```
+
+**`packages/finance/package.yml`:**
+```yaml
+exports:
+  - Invoice
+  - TaxCalculator
+```
+
+**`packages/finance/lib/invoice.rb`:**
+```ruby
+class Invoice
+  def initialize(amount_cents)
+    # Money gem is accessible because it's in the Gemfile
+    @amount = Money.new(amount_cents, 'USD')
+  end
+
+  def total
+    @amount
+  end
+end
+```
+
+**`packages/finance/lib/tax_calculator.rb`:**
+```ruby
+class TaxCalculator
+  # ...
+end
+```
+
+### 4. Use in Your Application
+
+**`app.rb`:**
+```ruby
+# No requires needed - imports are wired by Boxwerk
+invoice = Finance::Invoice.new(10_000)
+puts invoice.total  # => #<Money fractional:10000 currency:USD>
+```
+
+### 5. Run Your Application
+
+```bash
+RUBY_BOX=1 boxwerk run app.rb
+```
+
+Boxwerk automatically:
+1. Sets up Bundler
+2. Requires all gems from your Gemfile in the root box
+3. Loads and wires all packages
+4. Executes your script in the root package context
+
+## Usage
+
+### Running Scripts
+
+Execute a Ruby script in the root package context:
+
+```bash
+boxwerk run script.rb [args...]
+```
+
+The script has access to:
+- All gems from your Gemfile (automatically required)
+- All imports defined in the root `package.yml`
+
+### Interactive Console
+
+TODO: This feature is currenly broken and will run IRB from the root box, not the root package as desired.
+
+Start an IRB session in the root package context:
+
+```bash
+boxwerk console [irb-args...]
+```
+
+All imports and gems are available for interactive exploration.
+
+### Help
+
+```bash
+boxwerk help
+```
+
+## Package Configuration
+
+A `package.yml` defines what a package exports and imports:
+
+```yaml
+exports:
+  - PublicClass
+  - PublicModule
+
+imports:
+  - packages/dependency1
+  - packages/dependency2: Alias
+```
+
+### Exports
+
+Constants that should be visible to packages that import this one.
+
+### Imports
+
+Dependencies this package needs. **Note**: Dependencies are NOT transitive. If package A imports B, and B imports C, then A cannot access C unless it explicitly imports it.
+
+## Import Strategies
+
+Boxwerk supports four import strategies in `package.yml`:
+
+### 1. Default Namespace
+
+Import all exports under a module named after the package:
+
+```yaml
+imports:
+  - packages/finance
+```
+
+Result: `Finance::Invoice`, `Finance::TaxCalculator`
+
+### 2. Aliased Namespace
+
+Import under a custom module name:
+
+```yaml
+imports:
+  - packages/finance: Billing
+```
+
+Result: `Billing::Invoice`, `Billing::TaxCalculator`
+
+**Single Export Optimization**: If a package exports only one constant, it's imported directly (not wrapped in a module):
+
+```yaml
+# util exports only Calculator
+imports:
+  - packages/util: Calc
+```
+
+Result: `Calc` (not `Calc::Calculator`)
+
+### 3. Selective Import
+
+Import specific constants directly:
+
+```yaml
+imports:
+  - packages/finance:
+    - Invoice
+    - TaxCalculator
+```
+
+Result: `Invoice`, `TaxCalculator` (no namespace)
+
+### 4. Selective Rename
+
+Import specific constants with custom names:
+
+```yaml
+imports:
+  - packages/finance:
+      Invoice: Bill
+      TaxCalculator: Calculator
+```
+
+Result: `Bill`, `Calculator`
+
+## Gems and Packages
+
+### How Gems Work in Boxwerk
+
+When you run `boxwerk`, all gems in your `Gemfile` are:
+1. Automatically loaded via Bundler in the root box
+2. Accessible globally in all package boxes (gems are not isolated)
+
+This means:
+- You can use any gem from your Gemfile in any package.
+- Gems don't need to be declared in `package.yml`.
+- You do not `require` gems manually.
+
+### Isolation Model
+
+- **Root Box**: The box where Ruby bootstraps and all builtin classes/modules are defined. In Boxwerk, the root box performs all setup operations (Bundler setup, gem loading, dependency graph building, package box creation, and import wiring).
+- **Main Box**: The first user box created automatically by Ruby (copied from root box). In Boxwerk, it only runs the `exe/boxwerk` executable file, which then calls into the root box to execute the setup. The main box has no other purpose.
+- **Package Boxes**: Each package (including root package) runs in its own isolated `Ruby::Box` (created by copying from root box after gems are loaded).
+- **Box Inheritance**: All boxes are created via copy-on-write from the root box, inheriting builtin classes and loaded gems.
+- **Gems are Global**: All gems from Gemfile are accessible in all boxes (loaded in root box before package boxes are created).
+- **Package Exports are Isolated**: Only explicit imports from packages are accessible.
+- **No Transitive Access**: Packages can only see their explicit imports.
+
+For more details on how Ruby::Box works, see the [official Ruby::Box documentation](https://docs.ruby-lang.org/en/master/Ruby/Box.html).
+
+## Known Issues
+
+These issues are related to the current state of Ruby::Box in Ruby 4.0+. See the [Ruby::Box documentation](https://docs.ruby-lang.org/en/master/Ruby/Box.html) for known issues with the feature itself.
+
+### Gem Requiring in Boxes
+
+Requiring any gem from within a box (after boot) currently crashes the Ruby VM. This is likely an issue with Ruby::Box itself. As a workaround, Boxwerk automatically requires all gems from the Gemfile in the root box before creating package boxes, so gems are already loaded and accessible everywhere.
+
+### Console Context
+
+The console does not correctly run in the root package box—it runs in the context of the root box instead. It should run in the root package box. However, if we attempt to `require 'irb'` in the root package box, the Ruby VM crashes due to the gem requiring issue described above.
+
+### IRB Autocomplete
+
+Autocomplete is disabled for the console/IRB by default. When enabled, the Ruby VM crashes as soon as any key is pressed. This appears to be an issue with Ruby::Box and IRB's autocomplete feature interacting poorly.
+
+## Architecture
+
+### Boot Process
+
+1. Setup Bundler and require all gems in the root box
+2. Find root `package.yml` (searches up from current directory)
+3. Build dependency graph from package manifests
+4. Validate dependency graph (no circular dependencies)
+5. Boot packages in topological order
+6. Wire imports into each package box
+7. Execute command in root package context
+
+### Internal Components
+
+Boxwerk consists of several internal components that work together to provide package isolation:
+
+#### `Boxwerk::CLI`
+
+The command-line interface handler that:
+- Parses commands (`run`, `console`, `help`)
+- Validates the Ruby environment (checks for `RUBY_BOX=1` and Ruby::Box support)
+- Delegates to `Boxwerk::Setup` for the boot process
+- Executes the requested command in the root package's box context
+
+#### `Boxwerk::Setup`
+
+The setup orchestrator that:
+- Searches up the directory tree to find the root `package.yml`
+- Creates a `Boxwerk::Graph` instance to build and validate the dependency graph
+- Creates a `Boxwerk::Registry` instance to track booted packages
+- Calls `Boxwerk::Loader.boot_all` to boot all packages in topological order
+- Returns the loaded graph for introspection
+
+#### `Boxwerk::Graph`
+
+The dependency graph builder that:
+- Parses the root `package.yml` and recursively discovers all package dependencies
+- Builds a directed acyclic graph (DAG) of package relationships
+- Validates that there are no circular dependencies
+- Performs topological sorting to determine boot order (dependencies before consumers)
+- Provides access to all packages in the graph
+
+#### `Boxwerk::Package`
+
+The package manifest parser that:
+- Represents a single package with its configuration
+- Parses `package.yml` files to extract exports and imports
+- Normalizes the polymorphic import syntax (String, Array, Hash)
+- Stores the package path, name, exports, imports, and box reference
+- Tracks which exports have been loaded via `loaded_exports` hash (export name → file path)
+- Tracks whether the package has been booted
+
+#### `Boxwerk::Loader`
+
+The package loader that:
+- Creates a new `Ruby::Box` for each package (including the root package)
+- Loads exported constants lazily on-demand when they are imported by other packages
+- Uses Zeitwerk naming conventions to discover file locations for exported constants
+- Caches loaded exports in `package.loaded_exports` to avoid redundant file loading
+- Wires imports by injecting constants from dependency boxes into consumer boxes
+- Implements all four import strategies (default namespace, aliased namespace, selective import, selective rename)
+- Handles the single-export optimization for namespace imports
+- Registers each booted package in the registry
+- Only loads files that define exported constants, never loading non-exported code
+
+#### `Boxwerk::Registry`
+
+The package registry that:
+- Tracks all booted package instances
+- Allows packages to be retrieved by name during the wiring phase
+- Ensures each package is only booted once
+- Provides a clean interface for package lookup
+
+## Example
+
+See the [example/](example/) directory for a complete working example with:
+
+- Multi-package application
+- Gem usage
+- Transitive dependency demonstration
+- Isolation verification
+- Console usage examples
+
+Run it with:
+
+```bash
+cd example
+RUBY_BOX=1 boxwerk run app.rb
+```
+
+Or explore interactively:
+
+```bash
+cd example
+RUBY_BOX=1 boxwerk console
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run the tests:
+
+```bash
+RUBY_BOX=1 bundle exec rake test
+```
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+task default: :test

data/example/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'boxwerk', path: '..'
+gem 'money'

data/example/Gemfile.lock

@@ -0,0 +1,66 @@
+PATH
+  remote: ..
+  specs:
+    boxwerk (0.1.0)
+      irb (~> 1.16)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    bigdecimal (4.0.1)
+    concurrent-ruby (1.3.6)
+    date (3.5.1)
+    erb (6.0.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.2)
+    irb (1.16.0)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    money (7.0.0)
+      bigdecimal
+      i18n (~> 1.9)
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.3.1)
+      date
+      stringio
+    rdoc (7.0.3)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    reline (0.6.3)
+      io-console (~> 0.5)
+    stringio (3.2.0)
+    tsort (0.2.0)
+
+PLATFORMS
+  arm64-darwin-25
+  ruby
+
+DEPENDENCIES
+  boxwerk!
+  money
+
+CHECKSUMS
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  boxwerk (0.1.0)
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
+  erb (6.0.1) sha256=28ecdd99c5472aebd5674d6061e3c6b0a45c049578b071e5a52c2a7f13c197e5
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
+  io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
+  irb (1.16.0) sha256=2abe56c9ac947cdcb2f150572904ba798c1e93c890c256f8429981a7675b0806
+  money (7.0.0) sha256=6de776ee00aced8b9a435d3aac25ce8c600566625809b3d69bbe0c319e941dd5
+  pp (0.6.3) sha256=2951d514450b93ccfeb1df7d021cae0da16e0a7f95ee1e2273719669d0ab9df6
+  prettyprint (0.2.0) sha256=2bc9e15581a94742064a3cc8b0fb9d45aae3d03a1baa6ef80922627a0766f193
+  psych (5.3.1) sha256=eb7a57cef10c9d70173ff74e739d843ac3b2c019a003de48447b2963d81b1974
+  rdoc (7.0.3) sha256=dfe3d0981d19b7bba71d9dbaeb57c9f4e3a7a4103162148a559c4fc687ea81f9
+  reline (0.6.3) sha256=1198b04973565b36ec0f11542ab3f5cfeeec34823f4e54cebde90968092b1835
+  stringio (3.2.0) sha256=c37cb2e58b4ffbd33fe5cd948c05934af997b36e0b6ca6fdf43afa234cf222e1
+  tsort (0.2.0) sha256=9650a793f6859a43b6641671278f79cfead60ac714148aabe4e3f0060480089f
+
+BUNDLED WITH
+  4.0.3

data/example/README.md

@@ -0,0 +1,130 @@
+# Boxwerk Example Application
+
+This directory contains a complete example of a Boxwerk application demonstrating strict package isolation and dependency management.
+
+## Architecture
+
+```
+example/
+├── Gemfile                  # Gem dependencies (money gem)
+├── package.yml              # Root package (imports finance)
+├── app.rb                   # Application entry point
+└── packages/
+    ├── finance/
+    │   ├── package.yml      # Exports Invoice, TaxCalculator; imports util
+    │   └── lib/
+    │       ├── invoice.rb
+    │       └── tax_calculator.rb
+    └── util/
+        ├── package.yml      # Exports Calculator, Geometry
+        └── lib/
+            ├── calculator.rb
+            └── geometry.rb
+```
+
+## Dependency Graph
+
+```
+util (isolated box)
+  └── Calculator, Geometry
+
+finance (isolated box) 
+  ├── imports: util (Calculator renamed to UtilCalculator)
+  └── Invoice, TaxCalculator
+
+root (isolated box)
+  ├── imports: finance
+  └── Finance::Invoice, Finance::TaxCalculator available
+```
+
+## Running the Example
+
+```bash
+cd example
+RUBY_BOX=1 boxwerk run app.rb
+```
+
+**Architecture:**
+- Root box: Contains gems (including money gem) and Boxwerk runtime
+- Util box: Contains Calculator and Geometry classes
+- Finance box: Contains Invoice and TaxCalculator (imports Calculator from Util box as UtilCalculator)
+- Root package box: Runs app.rb (imports from Finance box)
+
+**Important:** ALL packages (including root) run in isolated boxes. The main Ruby process only contains gems and the Boxwerk runtime.
+
+### Interactive Console
+
+You can also start an IRB console in the root package context:
+
+```bash
+cd example
+RUBY_BOX=1 boxwerk console
+```
+
+This gives you an interactive session with all imports available (e.g., `Finance::Invoice`).
+
+## What This Demonstrates
+
+### ✓ Strict Isolation
+- `Finance::Invoice` and `Finance::TaxCalculator` are accessible (explicit import)
+- `Calculator` and `Geometry` are NOT accessible (transitive dependency - not imported)
+- `UtilCalculator` is NOT accessible (only available in Finance package's box)
+- `Invoice` at top level is NOT accessible (must use `Finance::` namespace)
+
+### ✓ Namespace Control
+- Finance package exports are grouped under `Finance::` module
+- Import strategies control how dependencies are wired
+
+### ✓ Selective Rename Strategy
+- Finance imports `Calculator` from util and renames it to `UtilCalculator`
+- This demonstrates the selective rename import strategy
+
+### ✓ Transitive Dependency Blocking
+- Root imports Finance
+- Finance imports Util
+- Root cannot access Util classes (no transitive access)
+
+### ✓ Gem Access
+- Money gem is globally accessible in all packages
+- Gems from Gemfile are auto-required and available everywhere
+
+### ✓ Clean API Surface
+- Each package explicitly declares exports
+- Consumers only see what's exported
+- Internal implementation details remain hidden
+
+## Package Configuration
+
+### Root Package (`package.yml`)
+
+```yaml
+imports:
+  - packages/finance  # Default namespace strategy
+```
+
+### Finance Package (`packages/finance/package.yml`)
+
+```yaml
+exports:
+  - Invoice
+  - TaxCalculator
+
+imports:
+  # Import Calculator from util and rename it to UtilCalculator
+  - packages/util:
+      Calculator: UtilCalculator
+```
+
+### Util Package (`packages/util/package.yml`)
+
+```yaml
+exports:
+  - Calculator
+  - Geometry
+```
+
+## Requirements
+
+- Ruby 4.0+ with `Ruby::Box` support
+- `RUBY_BOX=1` environment variable must be set
+- Boxwerk gem installed or loaded from `../lib`