port_of_call 0.1.0.alpha1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5f861789c53684db6036135fcb5eb0057c90ea56c95aedd7fabd4cc85c9c0b2
+  data.tar.gz: 0eab14311169be6984ed29ac0a531b0c0ac0f1da8a403dc7af2561a098969267
+SHA512:
+  metadata.gz: 984c62a2c7dec18962070b1dd51b7a0149a21f4caa57c39a42832e5e460671f4ccc55a82445158102d26eb29a27a27f98a99ab7270ec1af9ac5fd900c71427cd
+  data.tar.gz: fcf8f557fa7763042ef1f0aae10f416d101d83413f9d9c5ec869266e217d3931b31dc7dc33afad5ef3cbfbc7f0bb107f9fb2943ae740945dd418a8f3fc59a878

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0.alpha1] - 2025-03-25
+
+### Added
+- Initial pre-release of Port of Call gem
+- Core port calculation functionality
+  - Project name extraction from git or directory
+  - Deterministic SHA256 hashing algorithm
+  - Configurable port range mapping
+- Rails integration via Railtie
+  - Automatic port assignment for Rails server
+  - Generator for configuration initializer
+- Command-line interface
+  - Server command for starting Rails
+  - Port command for displaying calculated port
+  - Set command for setting default port
+  - Version and help commands
+- Rake tasks for common operations
+  - port_of_call:port to show calculated port
+  - port_of_call:start to start server
+  - port_of_call:install to generate initializer
+  - port_of_call:set_default to update development.rb
+  - port_of_call:check to verify port availability
+  - port_of_call:info to display configuration
+- Configuration options
+  - Custom port range
+  - Base port setting
+  - Project name override
+  - Reserved ports list

data/LICENSE.txt

@@ -0,0 +1,31 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jonathan P. Berger and contributors
+
+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.
+
+ADDITIONAL DISCLAIMER:
+This software is provided for educational and informational purposes only.
+The author(s) of this software take no responsibility for any conflicts, errors, 
+or system issues that may arise from using this software. Users are advised 
+to thoroughly test this software in a controlled environment before deploying 
+it in production settings. Port conflicts, networking issues, or any other 
+problems that may occur when using this software are solely the responsibility 
+of the user. By using this software, you agree to hold the author(s) harmless 
+from any liability.

data/README.md

@@ -0,0 +1,86 @@
+⛵️ Why use Port of Call?
+=============================
+Do you have multiple Rails apps running on your machine? Tired of conflicts on port 3000? I was, so I vibe-coded this gem.
+
+Port of Call automatically assigns deterministic port numbers to each Rails application based on its name.
+
+⛵️⛵️ Who's Port of Call for?
+=============================
+Rails developers who tend to work on multiple applications simultaneously
+
+⛵️⛵️⛵️ What exactly does Port of Call do?
+=============================
+Port of Call deterministically assigns port numbers to Rails applications:
+
+1. It extracts your application's name from Git or directory name
+2. It creates a hash of the name using SHA256
+3. It maps this hash to a port number within your configured range (default: 3000-3999)
+4. It automatically sets this port when you start your Rails server
+
+The same app always gets the same port on any machine, avoiding conflicts!
+
+⛵️⛵️⛵️⛵️ How do I use it?
+=============================
+1. Install the gem:
+   ```ruby
+   # In your Gemfile
+   gem 'port_of_call'
+   ```
+
+2. Bundle install:
+   ```bash
+   $ bundle install
+   ```
+
+3. Generate the initializer (optional):
+   ```bash
+   $ rails generate port_of_call:install
+   ```
+
+4. Run your server as usual:
+   ```bash
+   $ rails server
+   ```
+
+CLI Commands:
+- `port_of_call server` - Start Rails server with calculated port
+- `port_of_call port` - Show the calculated port
+- `port_of_call set` - Set as default port in development.rb
+- `port_of_call -v` - Show version information
+- `port_of_call -h` - Show help
+
+Rake Tasks:
+- `rake port_of_call` - Show calculated port
+- `rake port_of_call:start` - Start Rails server
+- `rake poc` - Shorthand for starting the server
+
+⛵️⛵️⛵️⛵️⛵️ Extras
+=============================
+Configuration:
+```ruby
+# In config/initializers/port_of_call.rb
+PortOfCall.configure do |config|
+  # Change port range (default: 3000..3999)
+  config.port_range = 4000..4999
+  
+  # Set custom project name
+  config.project_name = "my_unique_app_name"
+  
+  # Avoid specific ports
+  config.reserved_ports = [4567, 5000]
+end
+```
+
+Troubleshooting:
+- If your port is already in use, Port of Call will warn you
+- To check port availability: `rake port_of_call:check`
+- For detailed info: `rake port_of_call:info`
+
+GitHub: [github.com/jonathanpberger/port-of-call](https://github.com/jonathanpberger/port-of-call)
+
+License: MIT with additional [disclaimer](LICENSE.txt)
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.

data/RELEASE_NOTES.md

@@ -0,0 +1,62 @@
+# Port of Call 0.1.0 Release Notes
+
+We're excited to announce the initial release of Port of Call!
+
+Port of Call is a Ruby gem that assigns each Rails application a consistent, deterministic port number based on the application's name or repository. This solves the common conflict of multiple Rails apps all defaulting to port 3000.
+
+## Features
+
+### Automatic Port Assignment
+- Simply install the gem, and your Rails server will use a unique port based on your project name
+- No configuration required - it just works!
+
+### Deterministic Ports
+- Same project always gets the same port on any machine
+- Consistent development experience across your team
+
+### Multiple Interface Options
+- Command-line interface with intuitive commands
+- Rake tasks for easy integration
+- Ruby API for programmatic use
+
+### Customization
+- Configurable port range
+- Custom project name option
+- Reserved ports list
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'port_of_call'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+$ rails generate port_of_call:install  # Optional
+```
+
+## Usage
+
+Start your Rails server as usual:
+
+```bash
+$ rails server
+```
+
+You should see output indicating the port that Port of Call has assigned.
+
+## Documentation
+
+For detailed usage instructions, see the [README](README.md).
+
+## Feedback
+
+We welcome feedback, bug reports, and feature requests! Please submit issues on GitHub.
+
+---
+
+Thank you for using Port of Call!

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/basic_usage.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# This is an example of how to use Port of Call programmatically
+
+require "port_of_call"
+
+# Get the calculated port for the current project
+puts "Project name: #{PortOfCall.project_name}"
+puts "Calculated port: #{PortOfCall.calculate_port}"
+
+# Check if the port is available
+port = PortOfCall.calculate_port
+if PortOfCall.port_in_use?(port)
+  puts "Port #{port} is already in use by another process"
+else
+  puts "Port #{port} is available"
+end
+
+# Configure Port of Call
+PortOfCall.configure do |config|
+  # Use a different port range
+  config.port_range = 4000..4999
+  
+  # Set a different base port
+  config.base_port = 4000
+  
+  # Set a custom project name
+  config.project_name = "my_custom_project"
+  
+  # Reserve specific ports
+  config.reserved_ports = [4000, 4001, 4002]
+end
+
+# Get the new calculated port after configuration
+puts "New project name: #{PortOfCall.project_name}"
+puts "New calculated port: #{PortOfCall.calculate_port}"
+
+# Get server options hash (useful for Rails server)
+options = PortOfCall.server_options
+puts "Server options: #{options.inspect}"

data/examples/rails_example.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# This file demonstrates how to use Port of Call in a Rails application
+
+# In your Gemfile:
+# -----------------
+# gem 'port_of_call'
+
+
+# In config/initializers/port_of_call.rb:
+# ----------------------------------------
+# PortOfCall.configure do |config|
+#   # The port range to use (default: 3000..3999)
+#   config.port_range = 3000..3999
+#   
+#   # The base port to start from (default: 3000)
+#   config.base_port = 3000
+#   
+#   # Optional: manually set a project name (default: nil, auto-detected)
+#   # config.project_name = "my_custom_app_name"
+#   
+#   # Optional: ports to avoid (default: [])
+#   # config.reserved_ports = [3333, 4567]
+# end
+
+
+# In your terminal:
+# -----------------
+# Show the calculated port:
+# $ rake port_of_call
+# 
+# Start the server with the calculated port:
+# $ rails server
+# 
+# Or use the CLI:
+# $ port_of_call server    # Start the server
+# $ port_of_call port      # Show the port
+# $ port_of_call set       # Set as default port
+# 
+# Use the shortcut task:
+# $ rake poc               # Start the server
+
+
+# In your Ruby code:
+# ------------------
+# # Get the calculated port:
+# port = PortOfCall.calculate_port
+# 
+# # Get the project name:
+# name = PortOfCall.project_name
+# 
+# # Check if the port is available:
+# if PortOfCall.port_in_use?(port)
+#   puts "Port #{port} is in use"
+# end
+# 
+# # Get server options for Rails:
+# options = PortOfCall.server_options  # Returns { Port: calculated_port }

data/exe/port_of_call

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "port_of_call"
+
+# This executable provides command-line functionality for Port of Call
+PortOfCall::CLI.start(ARGV)

data/lib/generators/port_of_call/install_generator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module PortOfCall
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      
+      desc "Creates a Port of Call initializer for your application"
+      
+      def copy_initializer
+        template "initializer.rb", "config/initializers/port_of_call.rb"
+      end
+      
+      def show_readme
+        readme "README.md" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/port_of_call/templates/README.md

@@ -0,0 +1,27 @@
+# Port of Call
+
+## Next Steps
+
+Port of Call has been installed and configured. Your Rails server will now
+automatically use a unique, deterministic port based on your project name.
+
+### Usage
+
+To start your Rails server with the calculated port:
+
+```bash
+$ rails server
+```
+
+To see the calculated port:
+
+```bash
+$ rake port_of_call
+```
+
+### Configuration
+
+Your configuration file is at `config/initializers/port_of_call.rb`. 
+You can edit this file to customize the behavior of Port of Call.
+
+For more information, see: https://github.com/jpb/port-of-claude

data/lib/generators/port_of_call/templates/initializer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Port of Call Configuration
+#
+# This initializer configures the Port of Call gem, which automatically
+# assigns a unique, deterministic port to your Rails application.
+#
+# For more information, see: https://github.com/jpb/port-of-claude
+
+PortOfCall.configure do |config|
+  # The port range to use (default: 3000..3999)
+  # config.port_range = 3000..3999
+  
+  # The base port to start from (default: 3000)
+  # config.base_port = 3000
+  
+  # Manually set a project name (default: nil, auto-detected)
+  # config.project_name = "my_custom_app_name"
+  
+  # Reserved ports to avoid (default: [])
+  # config.reserved_ports = [3333, 4567]
+end

data/lib/port_of_call/cli.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module PortOfCall
+  # Command Line Interface for Port of Call
+  #
+  # Provides command-line functionality for interacting with Port of Call.
+  # Available commands:
+  # - server: Start Rails server with calculated port
+  # - port: Show the calculated port
+  # - set: Set port as default in development.rb
+  # - version: Show version information
+  # - help: Display usage information
+  class CLI
+    # Start the CLI with the given arguments
+    # @param args [Array<String>] command-line arguments
+    # @return [void]
+    def self.start(args)
+      new.start(args)
+    end
+    
+    # Route to the appropriate command
+    # @param args [Array<String>] command-line arguments
+    # @return [void]
+    def start(args)
+      command = args.shift || "server"
+      
+      case command
+      when "server", "s"
+        start_server(args)
+      when "port", "p"
+        show_port
+      when "set"
+        set_default_port
+      when "version", "--version", "-v"
+        show_version
+      when "help", "--help", "-h"
+        show_help
+      else
+        puts "Unknown command: #{command}"
+        show_help
+      end
+    end
+    
+    private
+    
+    # Start the Rails server with the calculated port
+    # @param args [Array<String>] additional arguments for the server
+    # @return [void]
+    def start_server(args)
+      # Get the calculated port
+      port = PortOfCall.calculate_port
+      project_name = PortOfCall.project_name
+      
+      # Check if the port is already in use
+      if PortOfCall.port_in_use?(port)
+        puts "WARNING: Port #{port} is already in use by another process!"
+        exit 1
+      end
+      
+      # Construct server command
+      if defined?(Rails) && defined?(Rails::Server)
+        puts "Port of Call - Starting Rails server for #{project_name} on port #{port}"
+        
+        # Add -p option if not already specified
+        unless args.include?("-p") || args.include?("--port")
+          args.unshift("-p", port.to_s)
+        end
+        
+        # Start server
+        Rails::Server.new(args).tap do |server|
+          # Set port in server options
+          server.options[:Port] = port if server.options[:Port].nil?
+          
+          # Start server
+          server.start
+        end
+      else
+        # Fallback when not running in a Rails context
+        puts "Port of Call - Rails environment not detected"
+        puts "Calculated port for #{project_name}: #{port}"
+      end
+    end
+    
+    # Show the calculated port
+    # @return [void]
+    def show_port
+      port = PortOfCall.calculate_port
+      project_name = PortOfCall.project_name
+      
+      puts "Port of Call - Calculated port for #{project_name}: #{port}"
+      
+      # Check if the port is already in use
+      if PortOfCall.port_in_use?(port)
+        puts "WARNING: Port #{port} is already in use by another process!"
+      end
+    end
+    
+    # Set the calculated port as the default in development.rb
+    # @return [void]
+    def set_default_port
+      if defined?(Rails) && defined?(Rails.root)
+        # Use rake task for this
+        system("rake", "port_of_call:set_default")
+      else
+        puts "ERROR: Rails environment not detected"
+        exit 1
+      end
+    end
+    
+    # Show version information
+    # @return [void]
+    def show_version
+      puts "Port of Call v#{PortOfCall::VERSION}"
+    end
+    
+    # Show help information
+    # @return [void]
+    def show_help
+      puts <<~HELP
+        Port of Call v#{PortOfCall::VERSION} - Deterministic port assignment for Rails applications
+        
+        Usage: port_of_call [COMMAND] [OPTIONS]
+        
+        Commands:
+          server, s       Start the Rails server with the calculated port (default)
+          port, p         Show the calculated port for this application
+          set             Set the calculated port as the default in development.rb
+          version, -v     Display version information
+          help, -h        Show this help message
+        
+        Examples:
+          port_of_call            # Start the Rails server with the calculated port
+          port_of_call port       # Show the calculated port
+          port_of_call set        # Set the calculated port as the default
+      HELP
+    end
+  end
+end

data/lib/port_of_call/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PortOfCall
+  # Configuration class for Port of Call settings
+  #
+  # @attr [Range] port_range The range of port numbers to use
+  # @attr [Integer] base_port The base port number
+  # @attr [String, nil] custom_project_name Optional custom project name to override auto-detection
+  # @attr [Array<Integer>] reserved_ports List of ports to avoid using
+  class Configuration
+    attr_accessor :port_range, :base_port, :custom_project_name, :reserved_ports
+    
+    # Initialize a new configuration with default values
+    def initialize
+      @port_range = 3000..3999
+      @base_port = 3000
+      @custom_project_name = nil
+      @reserved_ports = []
+    end
+    
+    # Get the custom project name
+    # @return [String, nil] the custom project name or nil if not set
+    def project_name
+      @custom_project_name
+    end
+    
+    # Set a custom project name
+    # @param name [String] the project name to use
+    def project_name=(name)
+      @custom_project_name = name
+    end
+    
+    # Calculate the size of the port range
+    # @return [Integer] the number of ports in the range
+    def port_range_size
+      @port_range.end - @port_range.begin + 1
+    end
+    
+    # Check if a port is available within the configuration constraints
+    # @param port [Integer] the port to check
+    # @return [Boolean] true if the port is in range and not reserved
+    def available_port?(port)
+      port_range.include?(port) && !reserved_ports.include?(port)
+    end
+  end
+end

data/lib/port_of_call/port_calculator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PortOfCall
+  # Calculates deterministic port numbers based on project name
+  #
+  # This class is responsible for:
+  # 1. Extracting the project name from various sources
+  # 2. Hashing the project name consistently
+  # 3. Mapping the hash to a port number within the configured range
+  class PortCalculator
+    # @return [Configuration] the configuration instance
+    attr_reader :config
+    
+    # Initialize a new calculator with the given configuration
+    # @param config [Configuration] the configuration instance
+    def initialize(config)
+      @config = config
+    end
+    
+    # Calculate a deterministic port number for the current project
+    # @return [Integer] the calculated port number
+    def calculate
+      project_name = extract_project_name
+      hash_value = hash_project_name(project_name)
+      port_from_hash(hash_value)
+    end
+    
+    private
+    
+    # Extract the project name using various methods
+    # @return [String] the project name
+    def extract_project_name
+      # Use custom project name if set
+      return config.project_name if config.project_name
+      
+      # Try multiple methods to determine the project name
+      git_name || directory_name || fallback_name
+    end
+    
+    # Try to get the project name from git
+    # @return [String, nil] the project name from git, or nil if not available
+    def git_name
+      return nil unless File.exist?(File.join(root_path, '.git'))
+      
+      # Try to get name from git remote origin URL
+      remote_url = `cd #{root_path} && git config --get remote.origin.url 2>/dev/null`.strip
+      return extract_git_repo_name(remote_url) unless remote_url.empty?
+      
+      # Fallback to git directory name
+      nil
+    end
+    
+    # Extract repository name from git URL
+    # @param url [String] the git remote URL
+    # @return [String, nil] the repository name, or nil if not parseable
+    def extract_git_repo_name(url)
+      return nil if url.nil? || url.empty?
+      
+      # Match various git URL formats:
+      # - https://github.com/user/repo.git
+      # - git@github.com:user/repo.git
+      # - git://github.com/user/repo
+      if url =~ %r{/([^/]+?)(\.git)?$} || url =~ %r{:([^/]+?)(\.git)?$}
+        return $1
+      end
+      
+      nil
+    end
+    
+    # Get the project name from the directory name
+    # @return [String] the directory name
+    def directory_name
+      # Use base name of the root directory
+      File.basename(root_path)
+    end
+    
+    # Fallback project name to use if all else fails
+    # @return [String] the fallback name
+    def fallback_name
+      # Fallback name in case all else fails
+      "rails_app"
+    end
+    
+    # Hash the project name to an integer consistently
+    # @param name [String] the project name
+    # @return [Integer] a hash value
+    def hash_project_name(name)
+      # Use SHA256 for consistent hashing across platforms
+      # Take the first 8 hex chars (32 bits) and convert to integer
+      Digest::SHA256.hexdigest(name)[0, 8].to_i(16)
+    end
+    
+    # Map a hash value to a port number within the configured range
+    # @param hash_value [Integer] the hash value
+    # @return [Integer] a port number
+    def port_from_hash(hash_value)
+      # Get the size of the port range
+      range_size = config.port_range.size
+      
+      # Calculate offset based on hash value
+      offset = hash_value % range_size
+      
+      # Apply offset to base port
+      config.base_port + offset
+    end
+    
+    # Get the root path of the application
+    # @return [String] the root path
+    def root_path
+      if defined?(Rails) && Rails.respond_to?(:root)
+        Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    end
+  end
+end

data/lib/port_of_call/railtie.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PortOfCall
+  class Railtie < Rails::Railtie
+    # Load rake tasks
+    rake_tasks do
+      load File.expand_path("../tasks/port_of_call.rake", __dir__)
+    end
+    
+    # Override the server default port
+    initializer "port_of_call.set_default_port" do |app|
+      # Only override if no port is explicitly specified
+      if !ENV["PORT"] && !ENV["RAILS_PORT"]
+        port = PortOfCall.calculate_port
+        
+        # Set the port in the application configuration if available
+        if app.config.respond_to?(:server_timing) && app.config.server_timing.respond_to?(:set)
+          app.config.server_timing.set(Port: port)
+        end
+        
+        # Hook into Rails command
+        if defined?(Rails::Command) && Rails::Command.respond_to?(:invoke)
+          Rails::Command.singleton_class.prepend(PortCommandExtension)
+        end
+        
+        # Store the port for other components to use
+        ENV["PORT"] = port.to_s
+        
+        Rails.logger.info "Port of Call: Assigned port #{port} to #{PortOfCall.project_name}" if Rails.logger
+      end
+    end
+    
+    # Hook into Rails Server command
+    module PortCommandExtension
+      def invoke(command_name, *args)
+        if command_name == "server" && args.last.is_a?(Hash) && !args.last.key?(:Port)
+          args.last[:Port] = PortOfCall.calculate_port
+        end
+        super
+      end
+    end
+    
+    # Generate initializer
+    generators do
+      require_relative "../generators/port_of_call/install_generator"
+    end
+  end
+end

data/lib/port_of_call/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PortOfCall
+  # Version number for the gem
+  # Following Semantic Versioning (https://semver.org/)
+  VERSION = "0.1.0.alpha1"
+end

data/lib/port_of_call.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "port_of_call/version"
+require_relative "port_of_call/configuration"
+require_relative "port_of_call/port_calculator"
+require_relative "port_of_call/railtie" if defined?(Rails)
+require_relative "port_of_call/cli"
+
+# Port of Call is a Ruby gem that assigns each Rails application a consistent,
+# deterministic port number based on the application's name or repository.
+# This solves the common conflict of multiple Rails apps all defaulting to port 3000.
+#
+# @example Basic usage with Rails
+#   # In Gemfile
+#   gem 'port_of_call'
+#   
+#   # Your Rails server will automatically use a unique port
+#   # based on your project name
+#   
+# @example Configuration via initializer
+#   # In config/initializers/port_of_call.rb
+#   PortOfCall.configure do |config|
+#     config.port_range = 3000..3999
+#     config.base_port = 3000
+#     # config.project_name = "custom_name" # Optional
+#   end
+#
+# @example Ruby API usage
+#   require 'port_of_call'
+#   
+#   # Get the calculated port for the current project
+#   port = PortOfCall.calculate_port
+#   
+#   # Check if the port is available
+#   if PortOfCall.port_in_use?(port)
+#     puts "Port #{port} is already in use!"
+#   end
+module PortOfCall
+  # Standard error class for Port of Call exceptions
+  class Error < StandardError; end
+  
+  class << self
+    attr_writer :configuration
+    
+    # Returns the current configuration
+    # @return [Configuration] the current configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    
+    # Configures the gem with the given block
+    # @yield [config] The configuration object
+    # @example
+    #   PortOfCall.configure do |config|
+    #     config.port_range = 4000..4999
+    #     config.base_port = 4000
+    #   end
+    def configure
+      yield(configuration)
+    end
+    
+    # Resets the configuration to defaults
+    # @return [Configuration] the new configuration object
+    def reset
+      @configuration = Configuration.new
+    end
+    
+    # Calculates the port for the current project
+    # @return [Integer] the calculated port number
+    def calculate_port
+      calculator.calculate
+    end
+    
+    # Returns the detected or configured project name
+    # @return [String] the project name
+    def project_name
+      calculator.send(:extract_project_name)
+    end
+    
+    # Checks if the calculated port is available
+    # @return [Boolean] true if the port is available, false if in use
+    def available?
+      port = calculate_port
+      !port_in_use?(port)
+    end
+    
+    # Checks if a specific port is in use by another process
+    # @param port [Integer] the port to check
+    # @return [Boolean] true if the port is in use, false if available
+    def port_in_use?(port)
+      # Check if the port is already in use by another process
+      begin
+        socket = TCPServer.new('127.0.0.1', port)
+        socket.close
+        false
+      rescue Errno::EADDRINUSE
+        true
+      end
+    end
+    
+    # Returns options hash for Rails server
+    # @return [Hash] options with the Port key set
+    def server_options
+      { Port: calculate_port }
+    end
+    
+    private
+    
+    # Returns the port calculator instance
+    # @return [PortCalculator] the port calculator
+    def calculator
+      @calculator ||= PortCalculator.new(configuration)
+    end
+  end
+end

data/lib/tasks/port_of_call.rake

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+namespace :port_of_call do
+  desc "Print the calculated port for this Rails application"
+  task :port => :environment do
+    port = PortOfCall.calculate_port
+    project_name = PortOfCall.project_name
+    puts "Port of Call - Calculated port for #{project_name}: #{port}"
+    
+    # Check if the port is already in use
+    if PortOfCall.port_in_use?(port)
+      puts "WARNING: Port #{port} is already in use by another process!"
+    end
+  end
+  
+  desc "Start the Rails server with the calculated port"
+  task :start => :environment do
+    port = PortOfCall.calculate_port
+    project_name = PortOfCall.project_name
+    
+    puts "Port of Call - Starting Rails server for #{project_name} on port #{port}"
+    
+    # Check if the port is already in use
+    if PortOfCall.port_in_use?(port)
+      puts "WARNING: Port #{port} is already in use by another process!"
+      exit 1
+    end
+    
+    # Start the Rails server with the calculated port
+    system("rails", "server", "-p", port.to_s)
+  end
+  
+  desc "Generate an initializer for Port of Call"
+  task :install => :environment do
+    puts "Generating Port of Call initializer..."
+    system("rails", "generate", "port_of_call:install")
+  end
+  
+  desc "Set the calculated port as the default for this Rails application"
+  task :set_default => :environment do
+    port = PortOfCall.calculate_port
+    project_name = PortOfCall.project_name
+    
+    # Get Rails development.rb config file
+    config_file = Rails.root.join("config", "environments", "development.rb")
+    
+    if File.exist?(config_file)
+      content = File.read(config_file)
+      
+      if content.include?("config.port = ")
+        # Update existing port setting
+        updated_content = content.gsub(/config\.port\s*=\s*\d+/, "config.port = #{port}")
+      else
+        # Add new port setting at the end of the config block
+        updated_content = content.gsub(/(Rails\.application\.configure do.*?)(\nend)/m, "\\1\n  # Port of Call - Assigned port\n  config.port = #{port}\n\\2")
+      end
+      
+      # Write updated content back to the file
+      File.write(config_file, updated_content)
+      
+      puts "Port of Call - Set default port for #{project_name} to #{port} in #{config_file}"
+    else
+      puts "ERROR: Could not find development.rb config file"
+      exit 1
+    end
+  end
+  
+  desc "Check if the calculated port is available"
+  task :check => :environment do
+    port = PortOfCall.calculate_port
+    project_name = PortOfCall.project_name
+    
+    puts "Port of Call - Checking port #{port} for #{project_name}..."
+    
+    if PortOfCall.port_in_use?(port)
+      puts "WARNING: Port #{port} is already in use by another process!"
+      exit 1
+    else
+      puts "Port #{port} is available."
+    end
+  end
+  
+  desc "Show configuration information for Port of Call"
+  task :info => :environment do
+    port = PortOfCall.calculate_port
+    project_name = PortOfCall.project_name
+    config = PortOfCall.configuration
+    
+    puts "Port of Call - Configuration Information"
+    puts "---------------------------------------"
+    puts "Project name:     #{project_name}"
+    puts "Calculated port:  #{port}"
+    puts "Port range:       #{config.port_range}"
+    puts "Base port:        #{config.base_port}"
+    puts "Custom name:      #{config.custom_project_name || 'Not set'}"
+    puts "Reserved ports:   #{config.reserved_ports.empty? ? 'None' : config.reserved_ports.join(', ')}"
+    puts "---------------------------------------"
+    
+    if PortOfCall.port_in_use?(port)
+      puts "WARNING: Port #{port} is already in use by another process!"
+    else
+      puts "Port #{port} is available."
+    end
+  end
+end
+
+# Add shortcut tasks at the top level
+desc "Print the calculated port for this Rails application"
+task :port_of_call => "port_of_call:port"
+
+desc "Start the Rails server with the calculated port"
+task :poc => "port_of_call:start"

data/sig/port_of_call.rbs

@@ -0,0 +1,4 @@
+module PortOfCall
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: port_of_call
+version: !ruby/object:Gem::Version
+  version: 0.1.0.alpha1
+platform: ruby
+authors:
+- JPB
+bindir: exe
+cert_chain: []
+date: 2025-03-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: Port of Call assigns each Rails application a consistent, deterministic
+  port number based on the application's name or repository. This solves the common
+  conflict of multiple Rails apps all defaulting to port 3000.
+email:
+- jonathanpberger@gmail.com
+executables:
+- port_of_call
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- RELEASE_NOTES.md
+- Rakefile
+- examples/basic_usage.rb
+- examples/rails_example.rb
+- exe/port_of_call
+- lib/generators/port_of_call/install_generator.rb
+- lib/generators/port_of_call/templates/README.md
+- lib/generators/port_of_call/templates/initializer.rb
+- lib/port_of_call.rb
+- lib/port_of_call/cli.rb
+- lib/port_of_call/configuration.rb
+- lib/port_of_call/port_calculator.rb
+- lib/port_of_call/railtie.rb
+- lib/port_of_call/version.rb
+- lib/tasks/port_of_call.rake
+- sig/port_of_call.rbs
+homepage: https://github.com/jonathanpberger/port-of-call
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jonathanpberger/port-of-call
+  source_code_uri: https://github.com/jonathanpberger/port-of-call
+  changelog_uri: https://github.com/jonathanpberger/port-of-call/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  documentation_uri: https://github.com/jonathanpberger/port-of-call/blob/main/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Deterministic port assignment for Rails applications
+test_files: []