boxwerk 0.1.0

data/example/app.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+# Example Boxwerk Application
+# Run with: RUBY_BOX=1 boxwerk app.rb
+
+puts '=' * 70
+puts 'Boxwerk Application'
+puts '=' * 70
+puts ''
+
+puts 'Creating invoice...'
+invoice = Finance::Invoice.new(tax_rate: 0.15)
+invoice.add_item('Web Development', 200_000) # $2000.00 in cents
+invoice.add_item('Design Work', 150_000) # $1500.00 in cents
+invoice.add_item('Consulting', 80_000) # $800.00 in cents
+
+data = invoice.to_h
+
+puts "\nInvoice Details:"
+data[:items].each_with_index do |item, i|
+  amount_dollars = item[:amount] / 100.0
+  puts "  #{i + 1}. #{item[:description]}: $#{format('%.2f', amount_dollars)}"
+end
+puts ''
+puts "  Subtotal: $#{format('%.2f', data[:subtotal] / 100.0)}"
+puts "  Tax (15%): $#{format('%.2f', data[:tax] / 100.0)}"
+puts "  Total: $#{format('%.2f', data[:total] / 100.0)}"
+puts ''
+
+puts 'Testing isolation...'
+# Finance::Invoice should be available
+begin
+  test_invoice = Finance::Invoice.new
+  puts '  ✓ Finance::Invoice accessible'
+rescue NameError => e
+  puts "  ✗ Finance::Invoice not accessible: #{e.message}"
+end
+
+# Finance::TaxCalculator should be available
+begin
+  Finance::TaxCalculator
+  puts '  ✓ Finance::TaxCalculator accessible'
+rescue NameError => e
+  puts "  ✗ Finance::TaxCalculator not accessible: #{e.message}"
+end
+
+# UtilCalculator should NOT be available (transitive dependency)
+begin
+  UtilCalculator.add(1, 2)
+  puts '  ✗ ERROR: UtilCalculator leaked from transitive dependency!'
+rescue NameError
+  puts '  ✓ UtilCalculator not accessible (correct isolation)'
+end
+
+# Invoice should NOT be at top level (only in Finance namespace)
+begin
+  Invoice.new
+  puts '  ✗ ERROR: Invoice available at top level!'
+rescue NameError
+  puts '  ✓ Invoice only accessible via Finance namespace'
+end
+
+# Calculator should NOT be available (transitive dependency from util package)
+begin
+  Calculator.add(1, 2)
+  puts '  ✗ ERROR: Calculator leaked from transitive dependency!'
+rescue NameError
+  puts '  ✓ Calculator not accessible (correct isolation)'
+end
+
+# Geometry should NOT be available (transitive dependency from util package)
+begin
+  Geometry.circle_area(5)
+  puts '  ✗ ERROR: Geometry leaked from transitive dependency!'
+rescue NameError
+  puts '  ✓ Geometry not accessible (correct isolation)'
+end
+
+# Money gem SHOULD be accessible (gems are global, not isolated)
+begin
+  test_money = Money.new(100, 'USD')
+  puts '  ✓ Money gem accessible (gems are global)'
+rescue NameError => e
+  puts "  ✗ ERROR: Money gem not accessible: #{e.message}"
+end
+
+puts ''
+puts '=' * 70
+puts '✓ Application completed successfully'
+puts '=' * 70
+puts ''
+puts 'Boxwerk CLI setup process:'
+puts '  1. `boxwerk run app.rb` found root package.yml'
+puts '  2. Built dependency graph (util → finance → root)'
+puts '  3. Validated no circular dependencies'
+puts '  4. Booted packages in topological order (all in isolated boxes)'
+puts '  5. Executed app.rb in root package box with Finance imported'
+puts ''
+puts 'Key difference: ALL packages (including root) run in isolated boxes.'
+puts 'The main Ruby process only contains gems and the Boxwerk runtime.'
+puts ''

data/example/package.yml

@@ -0,0 +1,6 @@
+# Main Application Package
+
+imports:
+  # Finance has multiple exports (Invoice, TaxCalculator)
+  # so this creates a Finance module containing both
+  - packages/finance

data/example/packages/finance/lib/invoice.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Invoice represents a financial invoice with line items and tax calculation
+# Uses the Money gem for precise currency handling
+class Invoice
+  attr_reader :items, :tax_rate
+
+  def initialize(tax_rate: TaxCalculator::STANDARD_RATE)
+    @items = []
+    @tax_rate = tax_rate
+  end
+
+  def add_item(description, amount_cents)
+    @items << {
+      description: description,
+      amount: Money.new(amount_cents, 'USD'),
+    }
+    self
+  end
+
+  def subtotal
+    @items.reduce(Money.new(0, 'USD')) { |sum, item| sum + item[:amount] }
+  end
+
+  def tax
+    (subtotal * tax_rate).round
+  end
+
+  def total
+    subtotal + tax
+  end
+
+  def to_h
+    {
+      items:
+        @items.map do |item|
+          { description: item[:description], amount: item[:amount].cents }
+        end,
+      subtotal: subtotal.cents,
+      tax_rate: tax_rate,
+      tax: tax.cents,
+      total: total.cents,
+    }
+  end
+
+  def self.quick_invoice(amount_cents, tax_rate: TaxCalculator::STANDARD_RATE)
+    invoice = new(tax_rate: tax_rate)
+    invoice.add_item('Service', amount_cents)
+    invoice
+  end
+end

data/example/packages/finance/lib/tax_calculator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# TaxCalculator provides tax calculation utilities
+# Uses the imported Util package for calculations
+class TaxCalculator
+  STANDARD_RATE = 0.10 # 10%
+  LUXURY_RATE = 0.20 # 20%
+
+  def self.calculate_tax(amount, rate = STANDARD_RATE)
+    # Use UtilCalculator from selective import
+    UtilCalculator.multiply(amount, rate)
+  end
+
+  def self.calculate_total(amount, rate = STANDARD_RATE)
+    tax = calculate_tax(amount, rate)
+    # Use UtilCalculator.add from selective import
+    UtilCalculator.add(amount, tax)
+  end
+
+  def self.reverse_calculate(total_with_tax, rate = STANDARD_RATE)
+    # Calculate original amount from total including tax
+    # Formula: original = total / (1 + rate)
+    divisor = UtilCalculator.add(1, rate)
+    UtilCalculator.divide(total_with_tax, divisor)
+  end
+end

data/example/packages/finance/package.yml

@@ -0,0 +1,10 @@
+# Finance Package
+
+exports:
+  - Invoice
+  - TaxCalculator
+
+imports:
+  # Import Calculator from util and rename it to UtilCalculator
+  - packages/util:
+      Calculator: UtilCalculator

data/example/packages/util/lib/calculator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Calculator provides basic arithmetic operations
+class Calculator
+  def self.add(a, b)
+    a + b
+  end
+
+  def self.subtract(a, b)
+    a - b
+  end
+
+  def self.multiply(a, b)
+    a * b
+  end
+
+  def self.divide(a, b)
+    raise ArgumentError, 'Cannot divide by zero' if b.zero?
+    a.to_f / b
+  end
+end

data/example/packages/util/lib/geometry.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Geometry provides geometric calculations
+class Geometry
+  PI = 3.14159265359
+
+  def self.circle_area(radius)
+    PI * radius * radius
+  end
+
+  def self.circle_circumference(radius)
+    2 * PI * radius
+  end
+
+  def self.rectangle_area(width, height)
+    width * height
+  end
+
+  def self.rectangle_perimeter(width, height)
+    2 * (width + height)
+  end
+
+  def self.triangle_area(base, height)
+    (base * height) / 2.0
+  end
+end

data/example/packages/util/package.yml

@@ -0,0 +1,5 @@
+# Util Package
+
+exports:
+  - Calculator
+  - Geometry

data/exe/boxwerk

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Boxwerk CLI
+# Usage: boxwerk <command> [args...]
+
+# Check if Ruby::Box is available and enabled
+unless ENV['RUBY_BOX'] == '1'
+  puts "Error: Boxwerk requires Ruby::Box to be enabled"
+  puts "Please set RUBY_BOX=1 environment variable"
+  exit 1
+end
+
+# Verify Ruby::Box is actually available in this Ruby version
+unless defined?(Ruby::Box)
+  puts "Error: Ruby::Box is not available in this Ruby version"
+  puts "Boxwerk requires Ruby 4.0 or later with Box support"
+  exit 1
+end
+
+# Setup Bundler, require any gems and run Boxwerk - all in the root box
+Ruby::Box.root.eval(<<~RUBY)
+  require 'bundler/setup'
+  # Application gems need to be required in the root box to be accessible in package boxes
+  Bundler.require
+  # Run the CLI to handle the invocation
+  Boxwerk::CLI.run(ARGV)
+RUBY

data/lib/boxwerk/cli.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # CLI handles command-line execution of Boxwerk applications
+  module CLI
+    class << self
+      # Main entry point for CLI
+      # @param argv [Array<String>] Command line arguments
+      def run(argv)
+        if argv.empty?
+          print_usage
+          exit 1
+        end
+
+        command = argv[0]
+
+        case command
+        when 'run'
+          run_command(argv[1..-1])
+        when 'console'
+          console_command(argv[1..-1])
+        when 'help', '--help', '-h'
+          print_usage
+          exit 0
+        else
+          puts "Error: Unknown command '#{command}'"
+          puts ''
+          print_usage
+          exit 1
+        end
+      end
+
+      private
+
+      def print_usage
+        puts 'Boxwerk - Ruby package system with Box-powered constant isolation'
+        puts ''
+        puts 'Usage: boxwerk <command> [args...]'
+        puts ''
+        puts 'Commands:'
+        puts '  run <script.rb> [args...]    Run a script in the root package context'
+        puts '  console [irb-args...]        Start an IRB console in the root package context'
+        puts '  help                         Show this help message'
+        puts ''
+        puts 'All packages are loaded and wired before the command executes.'
+      end
+
+      def run_command(args)
+        if args.empty?
+          puts 'Error: No script specified'
+          puts ''
+          puts 'Usage: boxwerk run <script.rb> [args...]'
+          exit 1
+        end
+
+        script_path = args[0]
+        script_args = args[1..-1] || []
+
+        # Verify script exists
+        unless File.exist?(script_path)
+          puts "Error: Script not found: #{script_path}"
+          exit 1
+        end
+
+        # Perform Boxwerk setup (find package.yml, build graph, boot packages)
+        graph = perform_setup
+
+        # Execute the script in the root package's box
+        root_package = graph.root
+        execute_in_box(root_package.box, script_path, script_args)
+      end
+
+      def console_command(args)
+        # Require IRB while we're still in root box context
+        require 'irb'
+
+        # Perform Boxwerk setup
+        graph = perform_setup
+
+        # Start IRB in the root package's box with provided args
+        root_package = graph.root
+        start_console_in_box(root_package.box, args)
+      end
+
+      def perform_setup
+        begin
+          Boxwerk::Setup.run!(start_dir: Dir.pwd)
+        rescue => e
+          puts "Error: #{e.message}"
+          exit 1
+        end
+      end
+
+      def execute_in_box(box, script_path, script_args)
+        # Set ARGV for the script using eval
+        box.eval("ARGV.replace(#{script_args.inspect})")
+
+        # Run the script in the isolated box
+        absolute_script_path = File.expand_path(script_path)
+        box.require(absolute_script_path)
+      end
+
+      def start_console_in_box(box, irb_args = [])
+        puts '=' * 70
+        puts 'Boxwerk Console'
+        puts '=' * 70
+        puts ''
+        puts 'All packages have been loaded and wired.'
+        puts 'You are in the root package context.'
+        puts ''
+        puts 'Type "exit" or press Ctrl+D to quit.'
+        puts '=' * 70
+        puts ''
+
+        # Start IRB in the box context.
+        # TODO: This is currently broken. IRB runs the in the root box context.
+        # This should be fixed by calling `require 'irb'` inside the box, but
+        # that currently crashes the VM.
+        # Set ARGV to the provided IRB args so they can be processed by IRB.
+        # Always add --noautocomplete to disable autocomplete (currently broken with Ruby::Box)
+        # TODO: Enable autocomplete when it's not broken.
+        irb_args_with_noautocomplete = ['--noautocomplete'] + irb_args
+        box.eval(<<~RUBY)
+          ARGV.replace(#{irb_args_with_noautocomplete.inspect})
+          IRB.start
+        RUBY
+      end
+    end
+  end
+end

data/lib/boxwerk/graph.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Boxwerk
+  # Builds and validates the package dependency graph
+  class Graph
+    attr_reader :packages, :root
+
+    def initialize(root_path)
+      @root_path = root_path
+      @packages = {}
+      @root = load_package('root', root_path)
+      resolve_dependencies(@root, [])
+      validate!
+    end
+
+    # Returns packages in topological order (leaves first)
+    def topological_order
+      visited = {}
+      order = []
+
+      @packages.each_value { |package| visit(package, visited, order, []) }
+
+      order
+    end
+
+    private
+
+    # Validate that the graph is acyclic
+    def validate!
+      visited = {}
+      rec_stack = {}
+
+      @packages.each_value do |package|
+        if has_cycle?(package, visited, rec_stack, [])
+          raise 'Circular dependency detected in package graph'
+        end
+      end
+
+      true
+    end
+
+    def load_package(name, path)
+      return @packages[name] if @packages[name]
+
+      package = Package.new(name, path)
+      @packages[name] = package
+      package
+    end
+
+    def resolve_dependencies(package, path)
+      if path.include?(package.name)
+        cycle = (path + [package.name]).join(' -> ')
+        raise "Circular dependency detected: #{cycle}"
+      end
+
+      package.dependencies.each do |dep_path|
+        dep_name = File.basename(dep_path)
+        full_path = File.join(@root_path, dep_path)
+
+        unless File.directory?(full_path)
+          raise "Package not found: #{dep_path} (expected at #{full_path})"
+        end
+
+        dep_package = load_package(dep_name, full_path)
+        resolve_dependencies(dep_package, path + [package.name])
+      end
+    end
+
+    # DFS for topological sort
+    def visit(package, visited, order, path)
+      return if visited[package.name]
+
+      if path.include?(package.name)
+        raise "Circular dependency: #{(path + [package.name]).join(' -> ')}"
+      end
+
+      visited[package.name] = true
+
+      package.dependencies.each do |dep_path|
+        dep_name = File.basename(dep_path)
+        dep_package = @packages[dep_name]
+        visit(dep_package, visited, order, path + [package.name]) if dep_package
+      end
+
+      order << package
+    end
+
+    # Cycle detection
+    def has_cycle?(package, visited, rec_stack, path)
+      return false if visited[package.name]
+
+      return true if rec_stack[package.name]
+
+      visited[package.name] = true
+      rec_stack[package.name] = true
+
+      package.dependencies.each do |dep_path|
+        dep_name = File.basename(dep_path)
+        dep_package = @packages[dep_name]
+
+        if dep_package &&
+             has_cycle?(dep_package, visited, rec_stack, path + [package.name])
+          return true
+        end
+      end
+
+      rec_stack[package.name] = false
+      false
+    end
+  end
+end