polyrun 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65a84fc362b402e23a550b5ea4f9980a5f6fc896fb5d1c445c3c8d2b22849604
-  data.tar.gz: 55c8baa0261b1e012c5b82592c82ae68409481eb7bee01503a0408d7b837fafe
+  metadata.gz: e3162ed760c231d4fa78ff396f55f708af13bda62808ba340f3c1494cf2dd97e
+  data.tar.gz: f401bd075462bafa14905c08a996fa46370025be9872f6a4d7aefbfdde251d2d
 SHA512:
-  metadata.gz: 50b5673497a1454363faf29781f9c5fc6f231cb5e8f85b570da61e036af3cb78450e2b6dc4854db1fe99528c292fece8f022c4e6cf69638bc8c09881fdb63a18
-  data.tar.gz: b10cf9ec6d80d0aeecfda0965ec6d7473d4c69a70a520bb3fb5b911679a0ba00d28be163f90458b7d4c3f5a62aa1de94739fb70811a5e82fe136651ca2c07c14
+  metadata.gz: 3d0bf0e8ac88d3d0a007f53ce340c324bcd65c6397b4b67905d428d104ebff3078bc41220873b0b7d741e6cc65be06d5d103f8b8abd64e18ce0dc2d8f3e55bc1
+  data.tar.gz: 42906169eeeae14b3531d870359ce8fe9bd59261770553a6e7e6872e48e47b7b1013709eedea5c176a94ccee5c1e498551e8d6285ffc68b37c51d05169b184b1

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## 1.3.0 (2026-04-15)
+
+- Add safe parsing for `ci-shard-run` / `ci-shard-rspec` `--shard-processes` and `--workers` (warn + exit 2 on missing or non-integer values).
+- Fix `shard_child_env` when `matrix_total > 1` and `matrix_index` is nil: omit `POLYRUN_SHARD_MATRIX_*` and warn (avoid `Integer(nil)`).
+- Document in `polyrun help` that `POLYRUN_SHARD_PROCESSES` and ci-shard `--workers` / `--shard-processes` are local processes per matrix job, distinct from `POLYRUN_WORKERS` / `run-shards`.
+- BREAKING: Multi-worker shard runs may emit coverage JSON fragments whose basenames include `shard*` and `worker*` segments; `merge-coverage` still matches `polyrun-fragment-*.json`.
+
+## 1.2.0 (2026-04-15)
+
+- Add `polyrun config <dotted.path>` to print values from `Polyrun::Config::Effective` (same effective tree as runtime: arbitrary YAML paths, merged `prepare.env.<KEY>` as for `polyrun prepare`, resolved `partition.shard_index`, `partition.shard_total`, `partition.timing_granularity`, and `workers`).
+- Memoize `Polyrun::Config::Effective.build` per thread (keyed by config path, object id, and env fingerprint) so repeated `dig` calls do not rebuild the merged tree.
+- Add `DISPATCH_SUBCOMMAND_NAMES` and `IMPLICIT_PATH_EXCLUSION_TOKENS`; route implicit path-only argv against one list (includes `ci-shard-*`, `help`, `version`); add spec that dispatch names match `when` branches in `lib/polyrun/cli.rb`.
+- Run `polyrun` with no subcommand to fan out parallel tests: pick RSpec (`start`), Minitest (`bundle exec rails test` or `bundle exec ruby -I test`), or Polyrun Quick (`bundle exec polyrun quick`) from `spec/**/*_spec.rb` vs `test/**/*_test.rb` vs Quick globs.
+- Accept path-only argv (and optional `run-shards` options before paths, e.g. `--workers`) to shard those files without naming a subcommand; infer suite from `_spec.rb` / `_test.rb` vs other `.rb` files.
+- Add optional `partition.suite` (`auto`, `rspec`, `minitest`, `quick`) when resolving globbed paths for `run-shards` / `parallel-rspec` / default runs.
+- Document implicit argv (known subcommand first vs path-like implicit parallel) and parallel Quick `bundle exec` from app root in `polyrun help` and `examples/README.md`.
+- Comment `detect_auto_suite` glob order in `lib/polyrun/partition/paths.rb` (RSpec/Minitest globs before Quick discovery).
+- Remove redundant `OptionParser` from `polyrun config` (no options; banner only).
+
 ## 1.1.0 (2026-04-15)
 
 - Add `ci-shard-run` / `ci-shard-rspec` for matrix-style sharding (one job per `POLYRUN_SHARD_INDEX` / `POLYRUN_SHARD_TOTAL`): resolve paths via the same plan as `polyrun plan`, then `exec` the given command with this shard’s paths (unlike `run-shards`, which fans out multiple workers on one host).

data/README.md

@@ -19,7 +19,7 @@ Capybara and Playwright stay in your application; Polyrun does not replace brows
 
 ## How?
 
-1. Add the gem (path or RubyGems) and `require "polyrun"` where you integrate—for example coverage merge in CI or prepare hooks.
+1. Add the gem (path or RubyGems) and `require "polyrun"` where you integrate—for example coverage merge in CI or prepare hooks. To pin the executable in your app, run `bundle binstubs polyrun` (writes `bin/polyrun`; ensure `bin/` is on `PATH` or invoke `./bin/polyrun`).
 2. Add a `polyrun.yml` beside the app, or pass `-c` to point at one. Configure `partition` (paths, shard index and total, strategy), and optionally `databases` (Postgres template and `shard_db_pattern`), `prepare`, and `coverage`. If you use `partition.paths_build`, Polyrun can write `partition.paths_file` (for example `spec/spec_paths.txt`) from globs and ordered stages—substring priorities for integration specs, or a regex stage for “Rails-heavy files first”—without a per-project Ruby script. That step runs before `plan` and `run-shards`. Use `bin/polyrun build-paths` to refresh the paths file only.
 3. Run prepare once before fan-out—for example `script/ci_prepare` for Vite or webpack builds, and `Polyrun::Prepare::Assets` digest markers. See `examples/TESTING_REQUIREMENTS.md`.
 4. Run workers with `bin/polyrun run-shards --workers N -- bundle exec rspec`: N separate OS processes, each running RSpec with its own file list from `partition.paths_file`, or `spec/spec_paths.txt`, or else `spec/**/*_spec.rb`. Stderr shows where paths came from; after a successful multi-worker run it reminds you to run merge-coverage unless you use `parallel-rspec` or `run-shards --merge-coverage`.

data/lib/polyrun/cli/ci_shard_run_command.rb

@@ -6,6 +6,11 @@ module Polyrun
     # workers on a single host. Runs +build-paths+, +plan+ for that shard, then +exec+ of a user command
     # with that shard's paths appended (same argv pattern as +run-shards+ after +--+).
     #
+    # With +--shard-processes M+ (or +partition.shard_processes+ / +POLYRUN_SHARD_PROCESSES+), fans out
+    # +M+ OS processes on this host, each running a subset of this shard's paths (NxM: +N+ matrix jobs × +M+
+    # processes). Child processes get local +POLYRUN_SHARD_INDEX+ / +POLYRUN_SHARD_TOTAL+ (+0..M-1+, +M+);
+    # when +N+ > 1, also +POLYRUN_SHARD_MATRIX_INDEX+ / +POLYRUN_SHARD_MATRIX_TOTAL+ for unique coverage fragments.
+    #
     # After +--+, prefer **multiple argv tokens** (+bundle+, +exec+, +rspec+, …). A single token that
     # contains spaces is split with +Shellwords+ (not a full shell); exotic quoting differs from +sh -c+.
     module CiShardRunCommand
@@ -25,6 +30,60 @@ module Polyrun
         [paths, 0]
       end
 
+      def ci_shard_local_plan!(paths, workers)
+        Polyrun::Partition::Plan.new(
+          items: paths,
+          total_shards: workers,
+          strategy: "round_robin",
+          root: Dir.pwd
+        )
+      end
+
+      # When +N+ > 1 and +M+ > 1, pass matrix index/total for coverage fragment names; else nil (see +shard_child_env+).
+      def ci_shard_matrix_context(pc, shard_processes)
+        n = resolve_shard_total(pc)
+        return [nil, nil] if n <= 1 || shard_processes <= 1
+
+        [resolve_shard_index(pc), n]
+      end
+
+      def ci_shard_run_fanout!(ctx)
+        pids = run_shards_spawn_workers(ctx)
+        return 1 if pids.empty?
+
+        run_shards_warn_interleaved(ctx[:parallel], pids.size)
+        shard_results = run_shards_wait_all_children(pids)
+        failed = shard_results.reject { |r| r[:success] }.map { |r| r[:shard] }
+
+        if failed.any?
+          Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (some failed)"
+          run_shards_log_failed_reruns(failed, shard_results, ctx[:plan], ctx[:parallel], ctx[:workers], ctx[:cmd])
+          return 1
+        end
+
+        Polyrun::Log.warn "polyrun ci-shard: finished #{pids.size} worker(s) (exit 0)"
+        0
+      end
+
+      def ci_shard_fanout_context(cfg:, pc:, paths:, shard_processes:, cmd:, config_path:)
+        plan = ci_shard_local_plan!(paths, shard_processes)
+        mx, mt = ci_shard_matrix_context(pc, shard_processes)
+        {
+          workers: shard_processes,
+          cmd: cmd,
+          cfg: cfg,
+          plan: plan,
+          run_t0: Process.clock_gettime(Process::CLOCK_MONOTONIC),
+          parallel: true,
+          merge_coverage: false,
+          merge_output: nil,
+          merge_format: nil,
+          config_path: config_path,
+          matrix_shard_index: mx,
+          matrix_shard_total: mt
+        }
+      end
+
       # Runner-agnostic matrix shard: +polyrun ci-shard-run [plan options] -- <command> [args...]+
       # Paths for this shard are appended after the command (like +run-shards+).
       def cmd_ci_shard_run(argv, config_path)
@@ -42,10 +101,27 @@ module Polyrun
         end
         cmd = Shellwords.split(cmd.first) if cmd.size == 1 && cmd.first.include?(" ")
 
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
         paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-run")
         return code if code != 0
 
-        exec(*cmd, *paths)
+        if shard_processes <= 1
+          exec(*cmd, *paths)
+          return 0
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-run: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
       end
 
       # Same as +ci-shard-run -- bundle exec rspec+ with an optional second segment for RSpec-only flags:
@@ -55,10 +131,29 @@ module Polyrun
         plan_argv = sep ? argv[0...sep] : argv
         rspec_argv = sep ? argv[(sep + 1)..] : []
 
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        pc = cfg.partition
+        shard_processes, perr = ci_shard_parse_shard_processes!(plan_argv, pc)
+        return perr if perr
+
+        shard_processes, err = ci_shard_normalize_shard_processes(shard_processes)
+        return err if err
+
         paths, code = ci_shard_planned_paths!(plan_argv, config_path, command_label: "ci-shard-rspec")
         return code if code != 0
 
-        exec("bundle", "exec", "rspec", *rspec_argv, *paths)
+        cmd = ["bundle", "exec", "rspec", *rspec_argv]
+
+        if shard_processes <= 1
+          exec(*cmd, *paths)
+          return 0
+        end
+
+        ctx = ci_shard_fanout_context(
+          cfg: cfg, pc: pc, paths: paths, shard_processes: shard_processes, cmd: cmd, config_path: config_path
+        )
+        Polyrun::Log.warn "polyrun ci-shard-rspec: #{paths.size} path(s) → #{shard_processes} process(es) on this host (NxM: matrix jobs × local processes)"
+        ci_shard_run_fanout!(ctx)
       end
     end
   end

data/lib/polyrun/cli/ci_shard_run_parse.rb

@@ -0,0 +1,68 @@
+module Polyrun
+  class CLI
+    # Parsing for +ci-shard-run+ / +ci-shard-rspec+ plan argv (+--shard-processes+, +--workers+).
+    module CiShardRunParse
+      private
+
+      # Strips +--shard-processes+ / +--workers+ from +plan_argv+ and returns +[count, exit_code]+.
+      # +exit_code+ is +nil+ on success, +2+ on invalid or missing integer (no exception).
+      # Does not use +OptionParser+ so +plan+ flags (+--shard+, +--total+, …) pass through unchanged.
+      # Note: +--workers+ here means processes for this matrix job (+POLYRUN_SHARD_PROCESSES+), not +run-shards+ +POLYRUN_WORKERS+.
+      def ci_shard_parse_shard_processes!(plan_argv, pc)
+        workers = Polyrun::Config::Resolver.resolve_shard_processes(pc)
+        rest = []
+        i = 0
+        while i < plan_argv.size
+          case plan_argv[i]
+          when "--shard-processes"
+            n, err = ci_shard_parse_positive_int_flag!(plan_argv, i, "--shard-processes")
+            return [nil, err] if err
+
+            workers = n
+            i += 2
+          when "--workers"
+            n, err = ci_shard_parse_positive_int_flag!(plan_argv, i, "--workers")
+            return [nil, err] if err
+
+            workers = n
+            i += 2
+          else
+            rest << plan_argv[i]
+            i += 1
+          end
+        end
+        plan_argv.replace(rest)
+        [workers, nil]
+      end
+
+      # @return [Array(Integer or nil, Integer or nil)] +[value, exit_code]+ — +exit_code+ is +nil+ on success, +2+ on error
+      def ci_shard_parse_positive_int_flag!(argv, i, flag_name)
+        arg = argv[i + 1]
+        if arg.nil?
+          Polyrun::Log.warn "polyrun ci-shard: missing value for #{flag_name}"
+          return [nil, 2]
+        end
+        n = Integer(arg, exception: false)
+        if n.nil?
+          Polyrun::Log.warn "polyrun ci-shard: #{flag_name} must be an integer (got #{arg.inspect})"
+          return [nil, 2]
+        end
+        [n, nil]
+      end
+
+      # @return [Array(Integer, Integer, nil)] +[capped_workers, exit_code]+ — +exit_code+ is +nil+ when OK
+      def ci_shard_normalize_shard_processes(workers)
+        if workers < 1
+          Polyrun::Log.warn "polyrun ci-shard: --shard-processes / --workers must be >= 1"
+          return [workers, 2]
+        end
+        w = workers
+        if w > Polyrun::Config::MAX_PARALLEL_WORKERS
+          Polyrun::Log.warn "polyrun ci-shard: capping --shard-processes / --workers from #{w} to #{Polyrun::Config::MAX_PARALLEL_WORKERS}"
+          w = Polyrun::Config::MAX_PARALLEL_WORKERS
+        end
+        [w, nil]
+      end
+    end
+  end
+end

data/lib/polyrun/cli/config_command.rb

@@ -0,0 +1,42 @@
+require "json"
+
+require_relative "../config/effective"
+
+module Polyrun
+  class CLI
+    module ConfigCommand
+      private
+
+      def cmd_config(argv, config_path)
+        dotted = argv.shift
+        if dotted.nil? || dotted.strip.empty?
+          Polyrun::Log.warn "polyrun config: need a dotted path (e.g. prepare.env.PLAYWRIGHT_ENV, partition.paths_file, workers)"
+          return 2
+        end
+        unless argv.empty?
+          Polyrun::Log.warn "polyrun config: unexpected arguments: #{argv.join(" ")}"
+          return 2
+        end
+
+        cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
+        val = Polyrun::Config::Effective.dig(cfg, dotted)
+        if val.nil?
+          Polyrun::Log.warn "polyrun config: no value for #{dotted}"
+          return 1
+        end
+
+        Polyrun::Log.puts format_config_value(val)
+        0
+      end
+
+      def format_config_value(val)
+        case val
+        when Hash, Array
+          JSON.generate(val)
+        else
+          val.to_s
+        end
+      end
+    end
+  end
+end

data/lib/polyrun/cli/default_run.rb

@@ -0,0 +1,115 @@
+require "tempfile"
+
+module Polyrun
+  class CLI
+    # No-subcommand default (`polyrun`) and path-only argv (implicit parallel run).
+    module DefaultRun
+      private
+
+      def dispatch_default_parallel!(config_path)
+        suite = Polyrun::Partition::Paths.detect_auto_suite(Dir.pwd)
+        unless suite
+          Polyrun::Log.warn "polyrun: no tests found (spec/**/*_spec.rb, test/**/*_test.rb, or Polyrun quick files). See polyrun help."
+          return 2
+        end
+
+        Polyrun::Log.warn "polyrun: default → parallel #{suite} (use `polyrun help` for subcommands)" if @verbose
+
+        case suite
+        when :rspec
+          cmd_start([], config_path)
+        when :minitest
+          cmd_parallel_minitest([], config_path)
+        when :quick
+          cmd_parallel_quick([], config_path)
+        else
+          2
+        end
+      end
+
+      # If +argv[0]+ is in {IMPLICIT_PATH_EXCLUSION_TOKENS}, treat as a normal subcommand. Otherwise, path-like
+      # tokens may trigger implicit parallel sharding (see +print_help+).
+      def implicit_parallel_run?(argv)
+        return false if argv.empty?
+        return false if Polyrun::CLI::IMPLICIT_PATH_EXCLUSION_TOKENS.include?(argv[0])
+
+        argv.any? { |a| cli_implicit_path_token?(a) }
+      end
+
+      def cli_implicit_path_token?(s)
+        return false if s.start_with?("-") && s != "-"
+        return true if s == "-"
+        return true if s.start_with?("./", "../", "/")
+        return true if s.end_with?(".rb")
+        return true if File.exist?(File.expand_path(s))
+        return true if /[*?\[]/.match?(s)
+
+        false
+      end
+
+      def dispatch_implicit_parallel_targets!(argv, config_path)
+        path_tokens = argv.select { |a| cli_implicit_path_token?(a) }
+        head = argv.reject { |a| cli_implicit_path_token?(a) }
+        expanded = expand_implicit_target_paths(path_tokens)
+        if expanded.empty?
+          Polyrun::Log.warn "polyrun: no files matched path arguments"
+          return 2
+        end
+
+        suite = Polyrun::Partition::Paths.infer_suite_from_paths(expanded)
+        if suite == :invalid
+          Polyrun::Log.warn "polyrun: mixing _spec.rb and _test.rb paths in one run is not supported"
+          return 2
+        end
+        if suite.nil?
+          Polyrun::Log.warn "polyrun: could not infer suite from paths"
+          return 2
+        end
+
+        tmp = Tempfile.new(["polyrun-paths-", ".txt"])
+        begin
+          tmp.write(expanded.join("\n") + "\n")
+          tmp.close
+          combined = head + ["--paths-file", tmp.path]
+          case suite
+          when :rspec
+            cmd_start(combined, config_path)
+          when :minitest
+            cmd_parallel_minitest(combined, config_path)
+          when :quick
+            cmd_parallel_quick(combined, config_path)
+          else
+            2
+          end
+        ensure
+          tmp.close! unless tmp.closed?
+          begin
+            File.unlink(tmp.path)
+          rescue Errno::ENOENT
+            # already removed
+          end
+        end
+      end
+
+      def expand_implicit_target_paths(path_tokens)
+        path_tokens.flat_map do |p|
+          abs = File.expand_path(p)
+          if File.directory?(abs)
+            spec = Dir.glob(File.join(abs, "**", "*_spec.rb")).sort
+            test = Dir.glob(File.join(abs, "**", "*_test.rb")).sort
+            quick = Dir.glob(File.join(abs, "**", "*.rb")).sort.reject do |f|
+              File.basename(f).end_with?("_spec.rb", "_test.rb")
+            end
+            spec + test + quick
+          elsif /[*?\[]/.match?(p)
+            Dir.glob(abs).sort
+          elsif File.file?(abs)
+            [abs]
+          else
+            []
+          end
+        end.uniq
+      end
+    end
+  end
+end

data/lib/polyrun/cli/help.rb

@@ -0,0 +1,54 @@
+module Polyrun
+  class CLI
+    module Help
+      def print_help
+        Polyrun::Log.puts <<~HELP
+          usage: polyrun [global options] [<command> | <paths...>]
+
+          With no command, runs parallel tests for the detected suite: RSpec under spec/, Minitest under test/, or Polyrun Quick (same discovery as polyrun quick). If the first argument is a known subcommand name, it is dispatched. Otherwise, path-like tokens (optionally with run-shards flags such as --workers) shard those files in parallel; see commands below.
+
+          global:
+            -c, --config PATH    polyrun.yml path (or POLYRUN_CONFIG)
+            -v, --verbose
+            -h, --help
+
+          Trace timing (stderr): DEBUG=1 or POLYRUN_DEBUG=1
+          Branch coverage in JSON fragments: POLYRUN_COVERAGE_BRANCHES=1 (stdlib Coverage; merge-coverage merges branches)
+          polyrun quick coverage: POLYRUN_COVERAGE=1 or (config/polyrun_coverage.yml + POLYRUN_QUICK_COVERAGE=1); POLYRUN_COVERAGE_DISABLE=1 skips
+          Merge wall time (stderr): POLYRUN_PROFILE_MERGE=1 (or verbose / DEBUG)
+          Post-merge formats (run-shards): POLYRUN_MERGE_FORMATS (default: json,lcov,cobertura,console,html)
+          Skip optional script/build_spec_paths.rb before start: POLYRUN_SKIP_BUILD_SPEC_PATHS=1
+          Skip start auto-prepare / auto DB provision: POLYRUN_START_SKIP_PREPARE=1, POLYRUN_START_SKIP_DATABASES=1
+          Skip writing paths_file from partition.paths_build: POLYRUN_SKIP_PATHS_BUILD=1
+          Warn if merge-coverage wall time exceeds N seconds (default 10): POLYRUN_MERGE_SLOW_WARN_SECONDS (0 disables)
+          Parallel RSpec workers: POLYRUN_WORKERS default 5, max 10 (run-shards / parallel-rspec / start); distinct from POLYRUN_SHARD_PROCESSES / ci-shard --shard-processes (local processes per CI matrix job)
+          Partition timing granularity (default file): POLYRUN_TIMING_GRANULARITY=file|example (experimental per-example; see partition.timing_granularity)
+
+          commands:
+            version              print version
+            plan                 emit partition manifest JSON
+            prepare              run prepare recipe: default | assets (optional prepare.command overrides bin/rails assets:precompile) | shell (prepare.command required)
+            merge-coverage       merge SimpleCov JSON fragments (json/lcov/cobertura/console)
+            run-shards           fan out N parallel OS processes (POLYRUN_SHARD_*; not Ruby threads); optional --merge-coverage
+            parallel-rspec       run-shards + merge-coverage (defaults to: bundle exec rspec after --)
+            start                parallel-rspec; auto-runs prepare (shell/assets) and db:setup-* when polyrun.yml configures them; legacy script/build_spec_paths.rb if paths_build absent
+            ci-shard-run         CI matrix: build-paths + plan for POLYRUN_SHARD_INDEX / POLYRUN_SHARD_TOTAL (or config), then run your command with that shard's paths after --; optional --shard-processes M or --workers M (POLYRUN_SHARD_PROCESSES; not POLYRUN_WORKERS) for N×M jobs × processes on this host
+            ci-shard-rspec       same as ci-shard-run -- bundle exec rspec; optional --shard-processes / --workers / -- [rspec-only flags]
+            build-paths          write partition.paths_file from partition.paths_build (same as auto step before plan/run-shards)
+            init                 write a starter polyrun.yml or POLYRUN.md from built-in templates (see docs/SETUP_PROFILE.md)
+            queue                file-backed batch queue: init (optional --shard/--total etc. as plan, then claim/ack); M workers share one dir; no duplicate paths across claims
+            quick                run Polyrun::Quick (describe/it, before/after, let, expect…to, assert_*; optional capybara!)
+            report-coverage      write all coverage formats from one JSON file
+            report-junit         RSpec JSON or Polyrun testcase JSON → JUnit XML (CI)
+            report-timing        print slow-file summary from merged timing JSON
+            merge-timing         merge polyrun_timing_*.json shards
+            config               print effective config by dotted path (see Polyrun::Config::Effective; same tree as YAML plus merged prepare.env, resolved partition shard fields, workers)
+            env                  print shard + database env (see polyrun.yml databases)
+            db:setup-template    migrate template DB (PostgreSQL)
+            db:setup-shard       CREATE DATABASE shard FROM template (one POLYRUN_SHARD_INDEX)
+            db:clone-shards      migrate templates + DROP/CREATE all shard DBs (replaces clone_shard shell scripts)
+        HELP
+      end
+    end
+  end
+end

data/lib/polyrun/cli/helpers.rb

@@ -7,40 +7,16 @@ module Polyrun
     module Helpers
       private
 
-      def partition_int(pc, keys, default)
-        keys.each do |k|
-          v = pc[k] || pc[k.to_sym]
-          next if v.nil? || v.to_s.empty?
-
-          i = Integer(v, exception: false)
-          return i unless i.nil?
-        end
-        default
-      end
-
       def env_int(name, fallback)
-        s = ENV[name]
-        return fallback if s.nil? || s.empty?
-
-        Integer(s, exception: false) || fallback
+        Polyrun::Config::Resolver.env_int(name, fallback)
       end
 
       def resolve_shard_index(pc)
-        return Integer(ENV["POLYRUN_SHARD_INDEX"]) if ENV["POLYRUN_SHARD_INDEX"] && !ENV["POLYRUN_SHARD_INDEX"].empty?
-
-        ci = Polyrun::Env::Ci.detect_shard_index
-        return ci unless ci.nil?
-
-        partition_int(pc, %w[shard_index shard], 0)
+        Polyrun::Config::Resolver.resolve_shard_index(pc)
       end
 
       def resolve_shard_total(pc)
-        return Integer(ENV["POLYRUN_SHARD_TOTAL"]) if ENV["POLYRUN_SHARD_TOTAL"] && !ENV["POLYRUN_SHARD_TOTAL"].empty?
-
-        ci = Polyrun::Env::Ci.detect_shard_total
-        return ci unless ci.nil?
-
-        partition_int(pc, %w[shard_total total], 1)
+        Polyrun::Config::Resolver.resolve_shard_total(pc)
       end
 
       def expand_merge_input_pattern(path)
@@ -119,10 +95,7 @@ module Polyrun
 
       # CLI + polyrun.yml + POLYRUN_TIMING_GRANULARITY; default +:file+.
       def resolve_partition_timing_granularity(pc, cli_val)
-        raw = cli_val
-        raw ||= pc && (pc["timing_granularity"] || pc[:timing_granularity])
-        raw ||= ENV["POLYRUN_TIMING_GRANULARITY"]
-        Polyrun::Partition::TimingKeys.normalize_granularity(raw || "file")
+        Polyrun::Config::Resolver.resolve_partition_timing_granularity(pc, cli_val)
       end
     end
   end

data/lib/polyrun/cli/plan_command.rb

@@ -76,21 +76,31 @@ module Polyrun
         }
       end
 
+      # Partition flags shared by +polyrun plan+ and +queue init+ (excluding +--paths-file+, which each command registers once).
+      def plan_command_register_partition_options!(opts, ctx)
+        opts.on("--shard INDEX", Integer) { |v| ctx[:shard] = v }
+        opts.on("--total N", Integer) { |v| ctx[:total] = v }
+        opts.on("--strategy NAME", String) { |v| ctx[:strategy] = v }
+        opts.on("--seed VAL") { |v| ctx[:seed] = v }
+        opts.on("--constraints PATH", "YAML: pin / serial_glob (see spec_queue.md)") { |v| ctx[:constraints_path] = v }
+        opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
+          ctx[:timing_path] = v
+        end
+        opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
+          ctx[:timing_granularity] = v
+        end
+      end
+
+      # Shared by +polyrun plan+ and +queue init+ so partition flags match +Partition::Plan+ / +plan+ JSON.
+      def plan_command_register_options!(opts, ctx)
+        opts.on("--paths-file PATH", String) { |v| ctx[:paths_file] = v }
+        plan_command_register_partition_options!(opts, ctx)
+      end
+
       def plan_command_parse_argv!(argv, ctx)
         OptionParser.new do |opts|
           opts.banner = "usage: polyrun plan [options] [--] [paths...]"
-          opts.on("--shard INDEX", Integer) { |v| ctx[:shard] = v }
-          opts.on("--total N", Integer) { |v| ctx[:total] = v }
-          opts.on("--strategy NAME", String) { |v| ctx[:strategy] = v }
-          opts.on("--seed VAL") { |v| ctx[:seed] = v }
-          opts.on("--paths-file PATH", String) { |v| ctx[:paths_file] = v }
-          opts.on("--constraints PATH", "YAML: pin / serial_glob (see spec_queue.md)") { |v| ctx[:constraints_path] = v }
-          opts.on("--timing PATH", "path => seconds JSON; implies cost_binpack unless strategy is cost-based or hrw") do |v|
-            ctx[:timing_path] = v
-          end
-          opts.on("--timing-granularity VAL", "file (default) or example (experimental: path:line items)") do |v|
-            ctx[:timing_granularity] = v
-          end
+          plan_command_register_options!(opts, ctx)
         end.parse!(argv)
       end
 

data/lib/polyrun/cli/prepare_command.rb

@@ -19,8 +19,8 @@ module Polyrun
         cfg = Polyrun::Config.load(path: config_path || ENV["POLYRUN_CONFIG"])
         prep = cfg.prepare
         recipe = prep["recipe"] || prep[:recipe] || "default"
-        prep_env = (prep["env"] || prep[:env] || {}).transform_keys(&:to_s).transform_values(&:to_s)
-        child_env = prep_env.empty? ? nil : ENV.to_h.merge(prep_env)
+        prep_env = Polyrun::Config::Resolver.prepare_env_yaml_string_map(prep)
+        child_env = prep_env.empty? ? nil : Polyrun::Config::Resolver.merged_prepare_env(prep)
         manifest = prepare_build_manifest(recipe, dry, prep_env)
 
         exit_code = prepare_dispatch_recipe(manifest, prep, recipe, dry, child_env)