rails-worktree 0.2.0 → 0.3.1

data/lib/worktree/commands/init.rb

@@ -1,182 +1,299 @@
 require "fileutils"
+require "json"
+require "open3"
 
 module RailsWorktree
   module Commands
+    # Provisions the current checkout at a level: minimal (configuration files),
+    # test (minimal plus an isolated test setup) or full (minimal plus own
+    # development and test databases). Safe to repeat.
     class Init
-      def initialize(args, skip_seeds: false)
-        @worktree_name = args[0]
-        @skip_seeds = skip_seeds
+      ENV_FILES = {"development" => ".env.development.local", "test" => ".env.test.local"}.freeze
+
+      attr_reader :root, :main_worktree, :name, :level
+
+      def initialize(args, level: nil, seed: false, base: nil, force: false, skip_seeds: nil)
+        @requested_name = args[0]
+        @requested_level = level
+        @seed = seed
+        @base = base
+        @force = force
       end
 
       def run
-        unless @worktree_name
-          puts "Error: Worktree name is required"
-          puts "Usage: worktree --init <worktree-name>"
-          exit 1
+        @context = Context.new
+        @root = @context.root
+        @main_worktree = main_worktree_path
+        raise Error, "Run init inside a linked worktree, not the main checkout #{@main_worktree}." if @root == @main_worktree
+
+        @config = Config.load(File.exist?(File.join(@root, Config::FILE)) ? @root : @main_worktree)
+        @name = @requested_name || File.basename(@root)
+        @level = @requested_level || @config.level
+        raise Error, "Unknown level #{@level}; use #{Config::LEVELS.join(", ")}." unless Config::LEVELS.include?(@level)
+
+        puts "Provisioning #{@root} (#{@level}) from #{@main_worktree}"
+        Dir.chdir(@root) do
+          record_base if @base
+          copy_files
+          create_directories
+          touch_files
+          link_node_modules
+          case @level
+          when "test" then setup_test
+          when "full" then setup_databases
+          end
         end
+        puts "✓ Worktree #{@name} provisioned (#{@level})"
+      end
+
+      def development_database = "#{database_prefix}_#{database_slug}_development"
+      def test_database = "#{database_prefix}_#{database_slug}_test"
 
-        @main_worktree = get_main_worktree
-        @db_prefix = get_db_prefix
-        @dev_database_name = "#{@db_prefix}_#{@worktree_name}_development"
-        @test_database_name = "#{@db_prefix}_#{@worktree_name}_test"
+      private
 
-        puts "Initializing worktree '#{@worktree_name}'..."
-        puts "Main worktree: #{@main_worktree}"
-        puts "Development database: #{@dev_database_name}"
-        puts "Test database: #{@test_database_name}"
+      def main_worktree_path
+        output = @context.git(@root, "worktree", "list", "--porcelain")
+        File.realpath(output.lines.grep(/^worktree /).first.delete_prefix("worktree ").strip)
+      end
 
-        @context = Context.new
-        @context_environment = @context.environment
+      def record_base
+        output, error, status = Open3.capture3(Context::GIT_ENVIRONMENT, "git", "-C", @root, "rev-parse", "--verify", "--end-of-options", "#{@base}^{commit}")
+        raise Error, "Invalid base #{@base}: #{error.strip}" unless status.success?
+        branch = @context.git(@root, "branch", "--show-current").strip
+        raise Error, "Cannot record a base on a detached HEAD." if branch.empty?
+        @context.record(@base, output.strip, branch)
+        @context.verify
+        Launcher.install(@root, replace: true)
+        PushHook.install(@root)
+        puts "Recorded base #{@base} for branch #{branch}"
+      end
 
-        copy_config_files
-        set_database_names
-        update_database_yml
-        copy_node_modules
-        setup_database
+      def copy_files
+        @config.copy_patterns.each do |pattern|
+          Dir.glob(pattern, base: @main_worktree).sort.each do |relative|
+            source = File.join(@main_worktree, relative)
+            next unless File.file?(source)
+            next if File.exist?(relative) && !@force
 
-        puts ""
-        puts "✓ Worktree initialized successfully!"
-        puts "  Development database: #{@dev_database_name}"
-        puts "  Test database: #{@test_database_name}"
-        puts "  Configuration files copied"
+            FileUtils.mkdir_p(File.dirname(relative))
+            FileUtils.cp(source, relative)
+            puts "  copied #{relative}"
+          end
+        end
       end
 
-      private
+      def create_directories
+        @config.directories.each { |directory| FileUtils.mkdir_p(directory) }
+      end
 
-      def get_main_worktree
-        output = `git worktree list --porcelain`
-        output.lines.grep(/^worktree /).first&.split(" ", 2)&.last&.strip
+      def touch_files
+        @config.touch.each do |file|
+          FileUtils.mkdir_p(File.dirname(file))
+          FileUtils.touch(file)
+        end
       end
 
-      def get_db_prefix
-        # Try to get prefix from database.yml first
-        database_yml = File.join(@main_worktree, "config/database.yml")
-        if File.exist?(database_yml)
-          content = File.read(database_yml)
-          match = content.match(/database:\s*(\w+)_development/)
-          return match[1] if match
+      def link_node_modules
+        source = File.join(@main_worktree, "node_modules")
+        return if @config.node_modules == "skip" || !Dir.exist?(source) || File.exist?("node_modules") || File.symlink?("node_modules")
+
+        if @config.node_modules == "link"
+          File.symlink(source, "node_modules")
+          puts "  linked node_modules to the main checkout"
+        else
+          FileUtils.cp_r(source, "node_modules")
+          puts "  copied node_modules"
         end
+      end
 
-        # Fall back to using the Rails app name (directory name of main worktree)
-        File.basename(@main_worktree)
+      def setup_test
+        if @config.test_command
+          puts "Running #{@config.test_command}..."
+          run_command(@context.environment, *@config.test_command.split(" ")) || raise(Error, "#{@config.test_command} failed")
+        else
+          case database_mode(%w[test])
+          when :files
+            prepare_schema("test", nil)
+          when :variable
+            write_env_file("test", test_database)
+            prepare_schema("test", test_database)
+          end
+        end
       end
 
-      def copy_config_files
-        puts "Copying configuration files..."
+      def setup_databases
+        case database_mode(%w[development test])
+        when :files then setup_sqlite_databases
+        when :variable then setup_named_databases
+        end
+      end
 
-        files_to_copy = [
-          ".env",
-          "config/database.yml",
-          "Procfile.dev",
-          "config/master.key"
-        ]
+      # How this checkout gets its own databases: :files when config/database.yml
+      # points at SQLite files inside the checkout, :variable when it reads the
+      # configured variable and dotenv loads .env.*.local. Otherwise nil, and the
+      # checkout keeps sharing the main databases.
+      def database_mode(environments)
+        unless File.executable?("bin/rails")
+          puts "Warning: bin/rails not found; skipping database setup"
+          return
+        end
 
-        files_to_copy += Dir.glob("config/credentials/*", base: @main_worktree)
+        @probe = probe_databases(environments)
+        unless @probe
+          puts "Warning: could not read config/database.yml (see above); skipping database setup"
+          return
+        end
 
-        files_to_copy.each do |file|
-          source = File.join(@main_worktree, file)
-          if File.exist?(source)
-            FileUtils.mkdir_p(File.dirname(file)) unless File.directory?(File.dirname(file))
-            FileUtils.cp(source, file)
-          else
-            puts "Warning: #{file} not found, skipping"
-          end
+        configs = environments.to_h { |environment| [environment, @probe[environment]] }
+        return :files if configs.values.all? { |config| sqlite_in_checkout?(config) }
+
+        environment, config = configs.find { |name, config| config.nil? || config["override"] != database_for(name) }
+        if environment
+          puts "Warning: config/database.yml does not read #{variable_for(environment)} for the #{environment} database, " \
+            "so this checkout would use #{config ? config["database"] : "no database"} like the main checkout. " \
+            "Skipping database setup; see Databases in the rails-worktree README."
+        elsif !@probe["dotenv"]
+          puts "Warning: dotenv is not loaded, so Rails would ignore .env.development.local and .env.test.local " \
+            "and use the main databases. Add gem \"dotenv-rails\" to the Gemfile. Skipping database setup."
+        else
+          :variable
         end
       end
 
-      def set_database_names
-        puts "Setting database names in .env..."
+      def probe_databases(environments)
+        script = File.expand_path("../database_probe.rb", __dir__)
+        arguments = environments.map { |environment| "#{environment}:#{variable_for(environment)}=#{database_for(environment)}" }
+        env = @context.environment.merge("RAILS_ENV" => "development")
+        output, status = Open3.capture2(env, *@context.command(["bin/rails", "runner", script, *arguments]), unsetenv_others: true)
+        line = output.lines.grep(/\ARAILS_WORKTREE_PROBE /).last
+        JSON.parse(line.delete_prefix("RAILS_WORKTREE_PROBE ")) if status.success? && line
+      end
 
-        env_file = ".env"
-        return unless File.exist?(env_file)
+      def sqlite_in_checkout?(config)
+        return false unless config && config["adapter"].include?("sqlite")
+        return false if config["database"].empty? || config["database"].start_with?(":memory:", "file:")
 
-        content = File.read(env_file)
+        File.expand_path(config["database"], @root).start_with?(@root + File::SEPARATOR)
+      end
 
-        # Set development database name
-        if content.match?(/^DATABASE_NAME_DEVELOPMENT=/)
-          content.gsub!(/^DATABASE_NAME_DEVELOPMENT=.*$/, "DATABASE_NAME_DEVELOPMENT=#{@dev_database_name}")
+      # SQLite files resolve inside each checkout, so the databases are separate
+      # already. The development database starts as a copy of the main checkout's.
+      def setup_sqlite_databases
+        if @config.template? && copy_sqlite_database(@probe.dig("development", "database"))
+          rails("development", nil, "db:migrate") || puts("Warning: migrations failed")
         else
-          content += "\nDATABASE_NAME_DEVELOPMENT=#{@dev_database_name}\n"
+          prepare_schema("development", nil)
         end
+        prepare_schema("test", nil)
+        seed(nil)
+      end
 
-        # Set test database name
-        if content.match?(/^DATABASE_NAME_TEST=/)
-          content.gsub!(/^DATABASE_NAME_TEST=.*$/, "DATABASE_NAME_TEST=#{@test_database_name}")
-        else
-          content += "DATABASE_NAME_TEST=#{@test_database_name}\n"
+      # Returns true when the checkout has its development database, copied now or before.
+      def copy_sqlite_database(database)
+        source = File.join(@main_worktree, database)
+        target = File.expand_path(database, @root)
+        return true if File.exist?(target)
+        return false unless File.file?(source)
+        if File.size(source) > @config.template_max_bytes
+          puts "Warning: #{database} in the main checkout is above database.template_max_gb; loading the schema instead"
+          return false
         end
 
-        File.write(env_file, content)
+        puts "Copying the development database #{database} from the main checkout..."
+        FileUtils.mkdir_p(File.dirname(target))
+        script = File.expand_path("../copy_sqlite.rb", __dir__)
+        return true if run_command(@context.environment, "bundle", "exec", "ruby", script, source, target)
+
+        puts "Warning: could not copy #{database} (see above); loading the schema instead"
+        false
+      end
+
+      def setup_named_databases
+        cloned = @config.template? && clone_development_database
+        write_env_file("development", development_database)
+        write_env_file("test", test_database)
+        if cloned
+          rails("development", development_database, "db:migrate") || puts("Warning: migrations failed")
+        else
+          prepare_schema("development", development_database)
+        end
+        prepare_schema("test", test_database)
+        seed(development_database)
       end
 
-      def update_database_yml
-        puts "Updating database.yml to use separate database names..."
+      def seed(database)
+        return unless @seed
 
-        database_yml = "config/database.yml"
-        return unless File.exist?(database_yml)
+        puts "Seeding #{database || "the development database"}..."
+        rails("development", database, "db:seed") || puts("Warning: seeding failed")
+      end
 
-        content = File.read(database_yml)
+      # Runs without the worktree database override so the configured development
+      # database is the main checkout's, then clones it. Returns false on failure.
+      def clone_development_database
+        return false if File.exist?(ENV_FILES["development"]) && !@force
 
-        # Use a single-pass replacement to avoid one substitution creating
-        # a substring that matches the other pattern (e.g., replacing
-        # "app_development" first produces "app_test-branch_development",
-        # which contains "app_test" and would be wrongly matched by a
-        # second gsub for the test pattern).
-        replacements = {
-          "#{@db_prefix}_development" => @dev_database_name,
-          "#{@db_prefix}_test" => @test_database_name
-        }
-        pattern = Regexp.union(replacements.keys)
-        content.gsub!(pattern) { |match| replacements[match] }
+        puts "Cloning the development database into #{development_database}..."
+        script = File.expand_path("../clone_database.rb", __dir__)
+        env = @context.environment.merge("RAILS_ENV" => "development", "RAILS_WORKTREE_TEMPLATE_MAX_BYTES" => @config.template_max_bytes.to_s)
+        return true if run_command(env, "bin/rails", "runner", script, development_database)
 
-        File.write(database_yml, content)
+        puts "Warning: the template clone did not run (see above; a database in use or above template_max_gb); loading the schema instead"
+        false
       end
 
-      def copy_node_modules
-        source = File.join(@main_worktree, "node_modules")
-        dest = "node_modules"
+      # Creates the database and loads the schema, or runs the migrations in an
+      # application without a schema file yet. A nil database uses database.yml as is.
+      def prepare_schema(environment, database)
+        label = database || "the #{environment} database"
+        puts "Preparing #{label}..."
+        rails(environment, database, "db:create") || puts("Warning: could not create #{label}")
+        if %w[db/schema.rb db/structure.sql].any? { |file| File.file?(file) }
+          rails(environment, database, "db:schema:load") || puts("Warning: could not load the schema into #{label}")
+        else
+          rails(environment, database, "db:migrate") || puts("Warning: could not migrate #{label}")
+        end
+      end
 
-        if Dir.exist?(source) && !Dir.exist?(dest)
-          puts "Copying node_modules from main worktree..."
-          FileUtils.cp_r(source, dest)
-          puts "Note: node_modules copied."
+      def write_env_file(environment, database)
+        variable = variable_for(environment)
+        path = ENV_FILES.fetch(environment)
+        content = File.exist?(path) ? File.read(path) : "# Written by bin/worktree init; dotenv loads it in the #{environment} environment only.\n"
+        line = "#{variable}=#{database}"
+        if content.match?(/^#{Regexp.escape(variable)}=/)
+          content = content.gsub(/^#{Regexp.escape(variable)}=.*$/, line)
+        else
+          content += "\n" unless content.end_with?("\n")
+          content += "#{line}\n"
         end
+        File.write(path, content)
       end
 
-      def database_env
-        (@context_environment || {}).merge(
-          "BUNDLE_GEMFILE" => File.expand_path("Gemfile"),
-          "DATABASE_NAME_DEVELOPMENT" => @dev_database_name,
-          "DATABASE_NAME_TEST" => @test_database_name
-        )
+      def rails(environment, database, *arguments)
+        env = @context.environment.merge("RAILS_ENV" => environment, "DISABLE_DATABASE_ENVIRONMENT_CHECK" => "1")
+        env[variable_for(environment)] = database if database
+        run_command(env, "bin/rails", *arguments)
       end
 
+      def variable_for(environment) = environment == "test" ? @config.test_variable : @config.development_variable
+      def database_for(environment) = environment == "test" ? test_database : development_database
+
       def run_command(environment, *arguments)
-        command = @context ? @context.command(arguments) : arguments
-        system(environment, *command, unsetenv_others: !!@context_environment)
+        command = @context.command(arguments)
+        system(environment, *command, unsetenv_others: true)
       end
 
-      def setup_database
-        if File.executable?("bin/setup")
-          puts "Running bin/setup..."
-          run_command(database_env, "bin/setup") || puts("Warning: bin/setup failed")
-        else
-          puts "Creating databases..."
-          run_command(database_env.merge("RAILS_ENV" => "development"), "bin/rails", "db:create") || puts("Warning: Could not create development database")
-          run_command(database_env.merge("RAILS_ENV" => "test"), "bin/rails", "db:create") || puts("Warning: Could not create test database")
-
-          puts "Running migrations..."
-          run_command(database_env.merge("RAILS_ENV" => "development"), "bin/rails", "db:migrate") || puts("Warning: Could not run migrations")
-          run_command(database_env.merge("RAILS_ENV" => "test"), "bin/rails", "db:migrate") || puts("Warning: Could not run test migrations")
-
-          unless @skip_seeds
-            puts "Seeding development database..."
-            run_command(database_env.merge("RAILS_ENV" => "development"), "bin/rails", "db:seed") || puts("Warning: Could not seed database")
-          else
-            puts "Skipping database seeding..."
-          end
+      def database_prefix
+        @database_prefix ||= begin
+          database_yml = File.join(@main_worktree, "config/database.yml")
+          match = File.exist?(database_yml) && File.read(database_yml).match(/(\w+)_development\b/)
+          match ? match[1] : File.basename(@main_worktree).gsub(/[^A-Za-z0-9_]/, "_")
         end
       end
+
+      def database_slug
+        @name.gsub(/[^A-Za-z0-9_]/, "_")
+      end
     end
   end
 end

data/lib/worktree/config.rb

@@ -0,0 +1,114 @@
+require "yaml"
+
+module RailsWorktree
+  # Project configuration from .worktree.yml in the repository root.
+  class Config
+    FILE = ".worktree.yml".freeze
+    LEVELS = %w[minimal test full].freeze
+    NODE_MODULES_MODES = %w[link copy skip].freeze
+
+    DEFAULTS = {
+      "level" => "full",
+      "copy" => [
+        ".env",
+        ".env.*",
+        "config/database.yml",
+        "config/master.key",
+        "config/credentials/*.key",
+        "Procfile.dev"
+      ],
+      "directories" => [],
+      "touch" => [],
+      "node_modules" => "link",
+      "database" => {
+        "development_variable" => "DATABASE_NAME",
+        "test_variable" => "DATABASE_NAME",
+        "template" => true,
+        "template_max_gb" => 5
+      },
+      "test_command" => nil
+    }.freeze
+
+    TEMPLATE = <<~YAML.freeze
+      # rails-worktree configuration. Every key is optional; these are the defaults.
+      # Docs: https://github.com/FastTravelAS/rails-worktree
+
+      # Provisioning level used by `bin/worktree create` and `bin/worktree init`
+      # when --level is not given: minimal, test or full.
+      level: full
+
+      # Gitignored files to copy from the main checkout. Globs are relative to the
+      # repository root. The same list generates .worktreeinclude for Claude Code.
+      copy:
+        - .env
+        - .env.*
+        - config/database.yml
+        - config/master.key
+        - config/credentials/*.key
+        - Procfile.dev
+
+      # Directories to create and files to touch in every provisioned checkout.
+      directories: []
+      touch: []
+
+      # node_modules handling: link (symlink to the main checkout), copy or skip.
+      node_modules: link
+
+      database:
+        # Environment variables that config/database.yml reads for the database
+        # name. They are written to .env.development.local and .env.test.local.
+        development_variable: DATABASE_NAME
+        test_variable: DATABASE_NAME
+        # Clone the main development database with CREATE DATABASE ... TEMPLATE
+        # (PostgreSQL) or by copying the SQLite file, instead of loading the schema. Falls back when it fails or
+        # when the source database is larger than template_max_gb.
+        template: true
+        template_max_gb: 5
+
+      # Command for `--level test`, for example bin/agent-test-setup. Without it
+      # the test level creates an own test database and loads the schema.
+      test_command:
+    YAML
+
+    attr_reader :root, :data
+
+    def self.load(root)
+      path = File.join(root, FILE)
+      data = File.file?(path) ? YAML.safe_load(File.read(path)) : nil
+      raise Error, "#{FILE} must be a YAML mapping" if data && !data.is_a?(Hash)
+      new(root, data || {})
+    end
+
+    def initialize(root, data = {})
+      @root = root
+      @data = deep_merge(DEFAULTS, data)
+      validate
+    end
+
+    def level = @data["level"]
+    def copy_patterns = Array(@data["copy"]).map(&:to_s)
+    def directories = Array(@data["directories"]).map(&:to_s)
+    def touch = Array(@data["touch"]).map(&:to_s)
+    def node_modules = @data["node_modules"].to_s
+    def development_variable = @data.dig("database", "development_variable").to_s
+    def test_variable = @data.dig("database", "test_variable").to_s
+    def template? = @data.dig("database", "template") ? true : false
+    def template_max_bytes = (@data.dig("database", "template_max_gb").to_f * 1024**3).to_i
+    def test_command = @data["test_command"]&.to_s
+
+    private
+
+    def validate
+      raise Error, "#{FILE}: level must be one of #{LEVELS.join(", ")}" unless LEVELS.include?(level)
+      raise Error, "#{FILE}: node_modules must be one of #{NODE_MODULES_MODES.join(", ")}" unless NODE_MODULES_MODES.include?(node_modules)
+      raise Error, "#{FILE}: database variables must be set" if development_variable.empty? || test_variable.empty?
+      raise Error, "#{FILE}: database.template_max_gb must be a positive number" unless template_max_bytes.positive?
+    end
+
+    def deep_merge(base, overrides)
+      base.merge(overrides) do |_key, old, new|
+        old.is_a?(Hash) && new.is_a?(Hash) ? deep_merge(old, new) : new
+      end
+    end
+  end
+end

data/lib/worktree/context.rb

@@ -18,6 +18,7 @@ module RailsWorktree
     end
 
     def verify(push: false)
+      return if push && !File.file?(metadata_path)
       data = JSON.parse(File.read(metadata_path))
       raise Error, "Invalid worktree context in #{metadata_path}; expected an object with base, commit and branch." unless data.is_a?(Hash)
       verify_branch(data)
@@ -57,6 +58,12 @@ module RailsWorktree
       File.expand_path(git(root, "rev-parse", "--git-path", "rails-worktree.json").strip, root)
     end
 
+    def git(directory, *arguments)
+      output, error, status = Open3.capture3(GIT_ENVIRONMENT, "git", "-C", directory, *arguments)
+      raise Error, "Git context check failed (#{arguments.join(" ")}): #{error.strip}" unless status.success?
+      output
+    end
+
     private
 
     def executable_path(path)
@@ -122,11 +129,5 @@ module RailsWorktree
       _output, _error, status = Open3.capture3(GIT_ENVIRONMENT, "git", "-C", File.dirname(resolved), "rev-parse", "--show-toplevel")
       raise Error, "Binstub resolves outside this worktree: #{resolved}. Use this checkout's binstub through bin/worktree exec." if status.success?
     end
-
-    def git(directory, *arguments)
-      output, error, status = Open3.capture3(GIT_ENVIRONMENT, "git", "-C", directory, *arguments)
-      raise Error, "Git context check failed (#{arguments.join(" ")}): #{error.strip}" unless status.success?
-      output
-    end
   end
 end

data/lib/worktree/copy_sqlite.rb

@@ -0,0 +1,7 @@
+# Copies a SQLite database consistently, also while it is in use.
+# Usage: ruby copy_sqlite.rb SOURCE TARGET
+require "sqlite3"
+
+source, target = ARGV.fetch(0), ARGV.fetch(1)
+SQLite3::Database.new(source, readonly: true) { |database| database.execute("VACUUM INTO ?", [target]) }
+puts "Copied #{source} into #{target}"

data/lib/worktree/database_probe.rb

@@ -0,0 +1,27 @@
+# Runs inside `bin/rails runner` in the worktree. Prints how config/database.yml
+# resolves the primary database of each environment, without the worktree
+# variable and with it set, and whether dotenv is loaded to read .env.*.local.
+# Usage: bin/rails runner database_probe.rb ENVIRONMENT:VARIABLE=VALUE ...
+require "json"
+
+def resolve(environment, variable, value)
+  saved = ENV.to_h.slice(variable)
+  ENV.delete(variable)
+  ENV[variable] = value if value
+  configurations = ActiveRecord::DatabaseConfigurations.new(Rails.application.config.database_configuration)
+  config = configurations.configs_for(env_name: environment, name: "primary") || configurations.configs_for(env_name: environment).first
+  config && {"adapter" => config.adapter.to_s, "database" => config.database.to_s}
+ensure
+  ENV.delete(variable)
+  ENV.update(saved)
+end
+
+result = {"dotenv" => defined?(Dotenv) ? true : false}
+ARGV.each do |argument|
+  environment, assignment = argument.split(":", 2)
+  variable, value = assignment.split("=", 2)
+  default = resolve(environment, variable, nil)
+  override = resolve(environment, variable, value)
+  result[environment] = default && default.merge("override" => override && override["database"])
+end
+puts "RAILS_WORKTREE_PROBE #{JSON.generate(result)}"