toys-ci 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7938bbe4359339e8e88a2db68b73a0fab34d7a56d451f81c93d829872ea2a84
-  data.tar.gz: fedf758753479cb8b575d2ccc35e10b1678e96a37e6fe89d7bfe09442561a91f
+  metadata.gz: 33be1026b282eba5ffd250b26046e6de597db1ca2330ffb076c38e906a204bd0
+  data.tar.gz: 0d3ef0fc6fc1b0a348ee9754f2ed62a3b7880f7785c539d7411e838961a60702
 SHA512:
-  metadata.gz: bb04a844fd4e312e36e8fa00c0259d6768ae1e1705c8946e4515e1307fe774d1ba1c6e9d94b8586943b11d4f2f5f82988f78de87a6c687637c26fd55d286c323
-  data.tar.gz: 4e20e3835a4e28485e649bb62ab7957aaead974647c6ae24afc6df263564ea870a0333bf8f3703c5ca3c2c8f9e8f665286dccab9350075bf46a1820b50d06e55
+  metadata.gz: c9cde4a096e1d9119ad8995f63cf66073a5ac53ff5f7974ace7c52d979f3177235e78515f6040f541ef29583977c2ab1bcbdb79562938bcf43ad9a966545c108
+  data.tar.gz: dbbb802c658ca28eba170292ded6f02178293373bcb8ca7ebaad4aa0673d32948dd065493e0819adf363968c4886cae9e02976a6925d673c4332eb47d99fa6ac

data/.yardopts

@@ -0,0 +1,10 @@
+--no-private
+--title=Toys CI System
+--markup=markdown
+--markup-provider redcarpet
+--main=README.md
+./lib/**/*.rb
+-
+README.md
+LICENSE.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release History
+
+### v0.1.0 / 2026-03-11
+
+* Initial release

data/LICENSE.md

@@ -0,0 +1,21 @@
+# License
+
+Copyright 2026 Daniel Azuma and the Toys 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.

data/README.md

@@ -1,9 +1,93 @@
-# Placeholder for toys-ci
+# Toys-CI
 
-This is a placeholder gem, which was generated on 2026-03-11 to
-reserve the gem "toys-ci".
-The actual gem is planned for release in the near future.
+Toys-CI is a framework for generating CI Toys tools.
 
-If this is a problem, or if the actual gem has not been released
-in a timely manner, you can contact the owner at
-`dazuma@gmail.com`.
+## Description
+
+Continuous Integration (CI) in a project typically involves running a variety
+of jobs, such as dependency installation, code linting, unit testing, build
+verification, and so forth. A large code base, or a monorepo that includes a
+number of smaller components, may require a large number of these jobs. Often
+it is desirable to have a "coordinator" job that decides which CI jobs to run
+in what order, and collects and summarizes their results.
+
+Toys-CI is a framework for generating simple CI coordinator tools. It provides
+a declarative interface for configuring the tool and specifying individual jobs
+to run. The generated tool runs jobs specified using command line arguments,
+and produces a final report of the results.
+
+### Basic example
+
+Given the following `.toys.rb`:
+
+    # Create a "test" tool that runs minitest-based tests
+    expand :minitest, bundler: true
+
+    # Create a "rubocop" tool that checks the code base
+    expand :rubocop, bundler: true
+
+    # Create a "ci" tool that runs the above tools and
+    # summarizes their results
+    tool "ci" do
+      load_gem "toys-ci"
+
+      expand(Toys::CI::Template) do |ci|
+        ci.only_flag = true
+        ci.tool_job("Run Rubocop", ["rubocop"], flag: :rubocop)
+        ci.tool_job("Run tests", ["test"], flag: :tests)
+      end
+    end
+
+Now you can:
+
+    $ toys ci                 # Runs both jobs
+    $ toys ci --only --tests  # Runs only the tests
+
+### Key features
+
+* Two interfaces: a high level Template interface that generates an entire tool
+  for you including configuration flags, and a low-level Mixin interface that
+  provides convenient methods that you can call to write your own CI tool.
+
+* The high-level interface generates flags that allow selection of individual
+  jobs and groups of jobs to execute.
+
+* Optionally analyzes diffs and skips jobs that do not need executing because
+  no relevant changes have occurred.
+
+* Customize your tool, including implementing additional flags and
+  functionality, using the power of the Toys framework.
+
+### System requirements
+
+Toys-CI requires Ruby 2.7 or later, and Toys 0.20 or later. We recommend the
+latest version of Ruby, JRuby, or TruffleRuby. The Ruby provided by the
+standard `setup-ruby` GitHub Action is sufficient.
+
+### Learning more
+
+For more information on the underlying Toys framework, see the
+[Toys README](https://dazuma.github.io/toys/gems/toys/latest) and the
+[Toys User Guide](https://dazuma.github.io/toys/gems/toys/latest/file.guide.html).
+
+## License
+
+Copyright 2026 Daniel Azuma and the Toys 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.

data/lib/toys/ci/mixin.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require "toys-core"
+
+module Toys
+  module CI
+    ##
+    # A mixin that provides methods useful for implementing CI tools.
+    #
+    # This mixin is a lower-level mechanism that depends on you to write your
+    # own run method and define any needed flags. For a more batteries-included
+    # experience, consider {Toys::CI::Template}, which does that work for you.
+    #
+    # To implement a CI tool using this mixin, you will:
+    #
+    # * Include this mixin
+    # * Call {toys_ci_init} to initialize the tool
+    # * Make calls to various `toys_ci_*_job` methods to run CI jobs
+    # * Call {toys_ci_report_results} to report final results
+    #
+    # This mixin adds various public and private methods, and several instance
+    # variables to the tool. All added method and instance variable names begin
+    # with `toys_ci_`, so avoid that prefix for any other methods and variables
+    # you are using in your tool.
+    #
+    # @example
+    #
+    #     # Define the "test" tool
+    #     expand :minitest, bundler: true
+    #
+    #     # Define the "rubocop" tool
+    #     expand :rubocop, bundler: true
+    #
+    #     # Define a "ci" tool that runs both the above, controlled by
+    #     # flags "--tests", "--rubocop", and/or "--all".
+    #     tool "ci" do
+    #       # Activate the toys-ci gem and pull in the mixin
+    #       load_gem "toys-ci"
+    #       include Toys::CI::Mixin
+    #
+    #       flag :tests, desc: "Run tests"
+    #       flag :rubocop, desc: "Run rubocop"
+    #       flag :all, desc: "Run all CI tasks"
+    #
+    #       def run
+    #         toys_ci_init
+    #         toys_ci_tool_job("Tests", ["test"]) if tests || all
+    #         toys_ci_tool_job("Rubocop", ["rubocop"]) if rubocop || all
+    #         toys_ci_report_results
+    #       end
+    #     end
+    #
+    module Mixin
+      include ::Toys::Mixin
+
+      on_include do
+        include :exec unless include?(:exec)
+        include :terminal unless include?(:terminal)
+      end
+
+      ##
+      # Initialize the CI tool. This must be called first before any other
+      # `toys_ci_` methods.
+      #
+      # @param fail_fast [boolean] If true, CI will terminate once any job ends
+      #     in failure. Otherwise, all jobs will be run.
+      # @param limit_by_changes_since [String,nil] If set to a git ref, finds
+      #     all the changed files since that ref, and skips CI jobs that
+      #     declare trigger paths that do not match. Optional. By default, no
+      #     jobs are skipped for this reason.
+      #
+      # @return [self]
+      #
+      def toys_ci_init(fail_fast: false, limit_by_changes_since: nil)
+        @toys_ci_fail_fast = fail_fast
+        @toys_ci_changed_paths = toys_ci_find_changes_since(limit_by_changes_since)
+        @toys_ci_successful_jobs = []
+        @toys_ci_failed_jobs = []
+        @toys_ci_skipped_jobs = []
+        self
+      end
+
+      ##
+      # Look for environment variables set by a GitHub workflow, and attempt to
+      # extract a suitable change base. Returns a git SHA, or nil if one could
+      # not be obtained from the current environment.
+      #
+      # This may read the `GITHUB_EVENT_NAME` and `GITHUB_EVENT_PATH`
+      # environment variables, and may also read the event payload file if
+      # found. However, the exact logic is not specified.
+      #
+      # The result can be passed to the `:limit_by_changes_since` argument of
+      # {#toys_ci_init}.
+      #
+      # @return [String] The git SHA for the change base
+      # @return [nil] if no change base can be determined
+      #
+      def toys_ci_github_event_base_sha
+        event_path = ::ENV["GITHUB_EVENT_PATH"].to_s
+        if event_path.empty?
+          logger.info("GITHUB_EVENT_PATH is empty or unset; cannot determine event payload file")
+          return nil
+        end
+        event_payload = toys_ci_read_event_payload_file(event_path)
+        return nil unless event_payload
+
+        event_name = ::ENV["GITHUB_EVENT_NAME"]
+        case event_name
+        when "push"
+          logger.info("Getting change base from push event")
+          event_payload["before"]
+        when "pull_request"
+          logger.info("Getting change base from pull_request event")
+          event_payload.dig("pull_request", "base", "sha")
+        else
+          logger.info("Did not find a change base from event #{event_name.inspect}")
+          nil
+        end
+      end
+
+      ##
+      # Run a CI job implemented by a tool, and record the results.
+      #
+      # @param name [String] A user-visible name for the job. Required.
+      # @param tool [Array<String>] The Toys tool to run. Required.
+      # @param trigger_paths [Array<String>,String,nil] An array of file or
+      #     directory paths, relative to the repo root, that must have changes
+      #     in order to trigger the job. If not specified, the job is always
+      #     triggered.
+      # @param env [Hash{String=>String}] Environment variables to set during
+      #     the run. Optional.
+      # @param chdir [String] The working directory for the run. Optional.
+      #
+      # @return [:success] If the job succeeded
+      # @return [:failure] If the job failed
+      # @return [:skipped] If the job was skipped because it did not match the
+      #     trigger paths
+      #
+      def toys_ci_tool_job(name, tool, trigger_paths: nil, env: nil, chdir: nil)
+        toys_ci_job(name, trigger_paths: trigger_paths) do
+          opts = {name: name}
+          opts[:env] = env if env
+          opts[:chdir] = chdir if chdir
+          exec_separate_tool(tool, **opts).success?
+        end
+      end
+
+      ##
+      # Run a CI job implemented by an external process, and record the results.
+      #
+      # @param name [String] A user-visible name for the job. Required.
+      # @param cmd [Array<String>] The command to run. Required.
+      # @param trigger_paths [Array<String>,String,nil] An array of file or
+      #     directory paths, relative to the repo root, that must have changes
+      #     in order to trigger the job. If not specified, the job is always
+      #     triggered.
+      # @param env [Hash{String=>String}] Environment variables to set during
+      #     the run. Optional.
+      # @param chdir [String] The working directory for the run. Optional.
+      #
+      # @return [:success] If the job succeeded
+      # @return [:failure] If the job failed
+      # @return [:skipped] If the job was skipped because it did not match the
+      #     trigger paths
+      #
+      def toys_ci_cmd_job(name, cmd, trigger_paths: nil, env: nil, chdir: nil)
+        toys_ci_job(name, trigger_paths: trigger_paths) do
+          opts = {name: name}
+          opts[:env] = env if env
+          opts[:chdir] = chdir if chdir
+          exec(cmd, **opts).success?
+        end
+      end
+
+      ##
+      # Run a CI job implemented by a block, and record the results.
+      #
+      # @param name [String] A user-visible name for the job. Required.
+      # @param trigger_paths [Array<String>,String,nil] An array of file or
+      #     directory paths, relative to the repo root, that must have changes
+      #     in order to trigger the job. If not specified, the job is always
+      #     triggered.
+      # @param block [Proc] The block to run. It will be run with `self` set to
+      #     the tool context, and should return true or false indicating
+      #     success or failure.
+      #
+      # @return [:success] If the job succeeded
+      # @return [:failure] If the job failed
+      # @return [:skipped] If the job was skipped because it did not match the
+      #     trigger paths
+      #
+      def toys_ci_job(name, trigger_paths: nil, &block)
+        unless defined?(@toys_ci_successful_jobs)
+          raise ::Toys::ToolDefinitionError, "You must call toys_ci_init before running a job"
+        end
+        return :skipped unless toys_ci_check_trigger_paths(trigger_paths, name)
+        puts("**** RUNNING: #{name}", :cyan, :bold)
+        result =
+          begin
+            instance_exec(&block)
+          rescue ::StandardError => e
+            trace = e.backtrace
+            write("#{trace.first}: ")
+            puts("#{e.message} (#{e.class})", :bold)
+            Array(trace[1..]).each { |line| puts "        from #{line}" }
+            false
+          end
+        toys_ci_job_result(name, result)
+      end
+
+      ##
+      # Print out a final report of the results, including a summary of the
+      # failed jobs. By default, this will also exit and never return. You can
+      # instead get the exit value by passing `exit: false`.
+      #
+      # @param exit [boolean] Whether to exit. Default is true.
+      #
+      # @return [Integer] The exit value
+      #
+      def toys_ci_report_results(exit: true) # rubocop:disable Metrics/MethodLength
+        unless defined?(@toys_ci_successful_jobs)
+          raise ::Toys::ToolDefinitionError, "You must call toys_ci_init before reporting job results"
+        end
+        success_count = @toys_ci_successful_jobs.size
+        failure_count = @toys_ci_failed_jobs.size
+        skipped_count = @toys_ci_skipped_jobs.size
+        total_job_count = success_count + failure_count + skipped_count
+        result =
+          if total_job_count.zero?
+            puts("**** CI: NO JOBS REQUESTED", :red, :bold)
+            puts("Try passing --help to see how to activate CI jobs.")
+            2
+          elsif failure_count.positive?
+            puts("**** CI: SKIPPED #{skipped_count} OF #{total_job_count} JOBS", :bold) unless skipped_count.zero?
+            puts("**** CI: FAILED #{failure_count} OF #{success_count + failure_count} RUNNABLE JOBS:", :red, :bold)
+            @toys_ci_failed_jobs.each { |name| puts(name, :red) }
+            1
+          elsif success_count.positive?
+            puts("**** CI: SKIPPED #{skipped_count} OF #{total_job_count} JOBS", :bold) unless skipped_count.zero?
+            puts("**** CI: ALL #{success_count} RUNNABLE JOBS SUCCEEDED", :green, :bold)
+            0
+          else
+            puts("**** CI: ALL #{skipped_count} JOBS SKIPPED", :yellow, :bold)
+            0
+          end
+        self.exit(result) if exit
+        result
+      end
+
+      ##
+      # @return [Array<String>] The names of the failed jobs so far
+      #
+      attr_reader :toys_ci_failed_jobs
+
+      ##
+      # @return [Array<String>] The names of the successful jobs so far
+      #
+      attr_reader :toys_ci_successful_jobs
+
+      ##
+      # @return [Array<String>] The names of the skipped jobs so far
+      #
+      attr_reader :toys_ci_skipped_jobs
+
+      ##
+      # @private
+      # Read a GitHub event payload file
+      #
+      def toys_ci_read_event_payload_file(path)
+        require "json"
+        ::JSON.parse(::File.read(path))
+      rescue ::SystemCallError, ::JSON::ParserError => e
+        logger.error("Failed to read GitHub event payload from #{path.inspect}:")
+        logger.error(e.inspect)
+        nil
+      end
+
+      ##
+      # @private
+      # Find all the changed files since the given ref.
+      #
+      def toys_ci_find_changes_since(ref)
+        return nil unless ref
+        result = exec(["git", "rev-parse", ref], out: :capture)
+        unless result.success?
+          logger.error("Unable to find git ref #{ref.inspect}")
+          exit(1)
+        end
+        sha = result.captured_out.strip
+        logger.info("Filtering by changes since SHA: #{sha}")
+        result = exec(["git", "diff", "--name-only", sha], out: :capture)
+        unless result.success?
+          logger.error("Unable to get diff since SHA #{sha}")
+          exit(1)
+        end
+        result.captured_out.split("\n")
+      end
+
+      ##
+      # @private
+      # Go through the given trigger paths and see if any match the changes
+      #
+      # @return [boolean] True to run the job, or false to skip
+      #
+      def toys_ci_check_trigger_paths(trigger_paths, name)
+        return true if !@toys_ci_changed_paths || !trigger_paths
+        Array(trigger_paths).each do |trigger_path|
+          trigger_dir = trigger_path.end_with?("/") ? trigger_path : "#{trigger_path}/"
+          return true if @toys_ci_changed_paths.any? do |changed_path|
+            changed_path == trigger_path || changed_path.start_with?(trigger_dir)
+          end
+        end
+        @toys_ci_skipped_jobs << name
+        puts("**** SKIPPING BECAUSE NO CHANGES FOUND: #{name}", :cyan, :bold)
+        false
+      end
+
+      ##
+      # @private
+      # Report the result of a single job
+      #
+      # @param name [String] The name of the job
+      # @param result [boolean] The result of the job
+      # @return [:success] If the result was success
+      # @return [:failure] If the result was failure
+      #
+      def toys_ci_job_result(name, result)
+        if result
+          @toys_ci_successful_jobs << name
+          puts("**** SUCCEEDED: #{name}", :green, :bold)
+          :success
+        else
+          @toys_ci_failed_jobs << name
+          puts("**** FAILED: #{name}", :red, :bold)
+          if @toys_ci_fail_fast
+            puts("TERMINATING CI", :red, :bold)
+            exit(1)
+          end
+          :failure
+        end
+      end
+    end
+  end
+end

data/lib/toys/ci/template.rb

@@ -0,0 +1,532 @@
+# frozen_string_literal: true
+
+require "toys-core"
+
+module Toys
+  module CI
+    ##
+    # A template that can be used to implement a CI tool.
+    #
+    # This template generates flags and implementation methods in the current
+    # tool to implement CI. In particular, it generates the `run` method
+    # itself. If you need more control over the CI tool's implementation,
+    # consider using {Toys::CI::Mixin} which provides a lower-level interface.
+    #
+    # To implement a CI tool using this template, simply expand the template
+    # and provide the necessary configuration, including specifying at least
+    # one CI task to run. The generated tool will use {Toys::CI::Mixin} under
+    # the hood.
+    #
+    # @example
+    #
+    #     # Define the "test" tool
+    #     expand :minitest, bundler: true
+    #
+    #     # Define the "rubocop" tool
+    #     expand :rubocop, bundler: true
+    #
+    #     # Define a "ci" tool that runs both the above, controlled by
+    #     # flags "--tests", "--rubocop", and/or "--all".
+    #     tool "ci" do
+    #       # Activate the toys-ci gem and expand the template
+    #       load_gem "toys-ci"
+    #       expand Toys::CI::Template do |ci|
+    #         ci.all_flag = true
+    #         ci.tool_job("Tests", ["test"], flag: :tests)
+    #         ci.tool_job("Rubocop", ["rubocop"], flag: :rubocop)
+    #       end
+    #     end
+    #
+    class Template
+      include ::Toys::Template
+
+      ##
+      # Add a job implemented by a tool call.
+      #
+      # @param name [String] A user-visible name for the job. Required.
+      # @param tool [Array<String>] The Toys tool to run. Required.
+      # @param flag [Symbol] A flag key to control whether the job will run.
+      #     If provided, it will be used to generate two flags that can be
+      #     passed to the CI job. For example, passing `:unit_tests` will
+      #     generate the flags `--unit-tests` and `--no-unit-tests` and set the
+      #     context value `:unit_tests`. If not provided, no flag is generated
+      #     and runnability will be determined by the "all" or "only" flag.
+      # @param override_flags [String,Array<String>,nil] Generated flags to use
+      #     instead of the ones implied by the `:flag` argument. These must be
+      #     specified without the leading `--`, and will automatically have
+      #     `--[no-]` prepended. Optional. If not specified or nil, the flags
+      #     fall back to those implied by the `:flag` argument.
+      # @param trigger_paths [Array<String>,String,nil] An array of file or
+      #     directory paths, relative to the repo root, that must have changes
+      #     in order to trigger the job. If not specified, the job is always
+      #     triggered.
+      # @param env [Hash{String=>String}] Environment variables to set during
+      #     the run. Optional.
+      # @param chdir [String] The working directory for the run. Optional.
+      #
+      def tool_job(name, tool, flag: nil, override_flags: nil, trigger_paths: nil, env: nil, chdir: nil)
+        if override_flags && !flag
+          raise ::Toys::ToolDefinitionError, "override_flags is meaningless without a flag"
+        end
+        @jobs << ToolJob.new(name, flag, Array(override_flags), trigger_paths, tool, env, chdir)
+        self
+      end
+
+      ##
+      # Add a job implemented by an external process.
+      #
+      # @param name [String] A user-visible name for the job. Required.
+      # @param cmd [Array<String>] The command to run. Required.
+      # @param flag [Symbol] A flag key to control whether the job will run.
+      #     If provided, it will be used to generate two flags that can be
+      #     passed to the CI job. For example, passing `:unit_tests` will
+      #     generate the flags `--unit-tests` and `--no-unit-tests` and set the
+      #     context value `:unit_tests`. If not provided, no flag is generated
+      #     and runnability will be determined by the "all" or "only" flag.
+      # @param override_flags [String,Array<String>,nil] Generated flags to use
+      #     instead of the ones implied by the `:flag` argument. These must be
+      #     specified without the leading `--`, and will automatically have
+      #     `--[no-]` prepended. Optional. If not specified or nil, the flags
+      #     fall back to those implied by the `:flag` argument.
+      # @param trigger_paths [Array<String>,String,nil] An array of file or
+      #     directory paths, relative to the repo root, that must have changes
+      #     in order to trigger the job. If not specified, the job is always
+      #     triggered.
+      # @param env [Hash{String=>String}] Environment variables to set during
+      #     the run. Optional.
+      # @param chdir [String] The working directory for the run. Optional.
+      #
+      def cmd_job(name, cmd, flag: nil, override_flags: nil, trigger_paths: nil, env: nil, chdir: nil)
+        if override_flags && !flag
+          raise ::Toys::ToolDefinitionError, "override_flags is meaningless without a flag"
+        end
+        @jobs << CmdJob.new(name, flag, Array(override_flags), trigger_paths, cmd, env, chdir)
+        self
+      end
+
+      ##
+      # Add a job implemented by a block.
+      #
+      # The block should perform a CI job and return a boolean indicating
+      # whether or not the job succeeded. It will execute in the tool execution
+      # context, with `self` set to the `Toys::Context`.
+      #
+      # @param name [String] A user-visible name for the job. Required.
+      # @param block [Proc] A block that runs this job. Required.
+      # @param flag [Symbol,nil] A flag key to control whether the job will run.
+      #     If provided, it will be used to generate two flags that can be
+      #     passed to the CI job. For example, passing `:unit_tests` will
+      #     generate the flags `--unit-tests` and `--no-unit-tests` and set the
+      #     context value `:unit_tests`. If not provided, no flag is generated
+      #     and runnability will be determined by the "all" or "only" flag.
+      # @param override_flags [String,Array<String>,nil] Generated flags to use
+      #     instead of the ones implied by the `:flag` argument. These must be
+      #     specified without the leading `--`, and will automatically have
+      #     `--[no-]` prepended. Optional. If not specified or nil, the flags
+      #     fall back to those implied by the `:flag` argument.
+      # @param trigger_paths [Array<String>,String,nil] An array of file or
+      #     directory paths, relative to the repo root, that must have changes
+      #     in order to trigger the job. If not specified, the job is always
+      #     triggered.
+      #
+      def job(name, flag: nil, override_flags: nil, trigger_paths: nil, &block)
+        if override_flags && !flag
+          raise ::Toys::ToolDefinitionError, "override_flags is meaningless without a flag"
+        end
+        @jobs << BlockJob.new(name, flag, Array(override_flags), trigger_paths, block)
+        self
+      end
+
+      ##
+      # Define a collection of jobs that can be enabled/disabled as a group.
+      #
+      # @param name [String] A user-visible name for the collection. Required.
+      # @param flag [Symbol] A flag key to control the collection. Required.
+      #     Used to define two flags that can be passed to the CI job. For
+      #     example, passing `:unit_tests` will generate the flags
+      #     `--unit-tests` and `--no-unit-tests` and set the context value
+      #     `:unit_tests`.
+      # @param override_flags [String,Array<String>,nil] Generated flags to use
+      #     instead of the ones implied by the `:flag` argument. These must be
+      #     specified without the leading `--`, and will automatically have
+      #     `--[no-]` prepended. Optional. If not specified or nil, the flags
+      #     fall back to those implied by the `:flag` argument.
+      # @param job_flags [Array<Symbol>] The individual job flags that will be
+      #     controlled as a group by this collection. Must be nonempty.
+      #
+      def collection(name, flag, job_flags, override_flags: nil)
+        if job_flags.empty?
+          raise ::Toys::ToolDefinitionError, "You must provide at least one entry in job_flags"
+        end
+        @collections << Collection.new(name, flag, Array(override_flags), job_flags)
+        self
+      end
+
+      ##
+      # Provide a block that will be run at the beginning of the CI job.
+      # The block will run in the tool execution context, with `self` set to
+      # the `Toys::Context`.
+      #
+      # @param block [Proc] The block to execute.
+      #
+      def before_run(&block)
+        @prerun = block
+      end
+
+      ##
+      # Create a flag that will enable all jobs. All jobs will otherwise be
+      # disabled by default. This setting is mutually exclusive with
+      # {#only_flag=} and {#jobs_disabled_by_default=}.
+      #
+      # The value can either be the flag key as a symbol, `true` to use the
+      # default (which is `:all`), or `false` to disable such a flag.
+      # For example, passing `true` will define the flag `--all` which will set
+      # the context key `:all`.
+      #
+      # @param value [Symbol,boolean]
+      #
+      def all_flag=(value)
+        @all_flag = value
+      end
+
+      ##
+      # Create a flag that will disable all jobs. All jobs will otherwise be
+      # enabled by default. This setting is mutually exclusive with
+      # {#all_flag=} and {#jobs_disabled_by_default=}.
+      #
+      # The value can either be the flag key as a symbol, `true` to use the
+      # default (which is `:only`), or `false` to disable such a flag.
+      # For example, passing `true` will define the flag `--only` which will
+      # set the context key `:only`.
+      #
+      # @param value [Symbol,boolean]
+      #
+      def only_flag=(value)
+        @only_flag = value
+      end
+
+      ##
+      # If set to true, all jobs are disabled by default unless explicitly
+      # enabled by their individual flags.
+      #
+      # This setting is mutually exclusive with {#all_flag=} and {#only_flag=}.
+      # If you set up one of those flags, the default enabling behavior is also
+      # set implicitly.
+      #
+      # @param value [boolean]
+      #
+      def jobs_disabled_by_default=(value)
+        @jobs_disabled_by_default = value
+      end
+
+      ##
+      # Create flags that will enable and disable fail-fast. The flag should be
+      # specified by symbol, and the actual flag will be set accordingly. You
+      # can also use the value `true` which will set the default `:fail_fast`.
+      # For example, passing `true` will define the flags `--fail-fast` and
+      # `--no-fail-fast`.
+      #
+      # @param value [Symbol,boolean]
+      #
+      def fail_fast_flag=(value)
+        @fail_fast_flag = value
+      end
+
+      ##
+      # Set the default value of fail-fast. You can also create flags that can
+      # override this value using {fail_fast_flag=}. Default is false.
+      #
+      # @param value [boolean]
+      #
+      def fail_fast_default=(value)
+        @fail_fast_default = value
+      end
+
+      ##
+      # Create a flag that can be used to specify the base ref for the change
+      # directly. This can be used to filter CI jobs based on what has changed.
+      #
+      # A change base ref provided in this way will override any obtained from
+      # other means, such as from the GitHub environment using
+      # {#use_github_base_ref_flag=}.
+      #
+      # @param value [Symbol,boolean] If a symbol, it is used as the flag
+      #     key for a flag that specifies the base ref. You can also pass
+      #     `true` to use the default, `:base_ref`.
+      #
+      def base_ref_flag=(value)
+        @base_ref_flag = value
+      end
+
+      ##
+      # Create a flag that enables obtaining the change base ref from the
+      # GitHub workflow environment. This can be used to filter CI jobs based
+      # on what has changed in a GitHub Actions workflow. The flag should be
+      # specified by symbol, and the actual flag will be set accordingly. You
+      # can also use the value `true` which will set the default
+      # `:use_github_base_ref`. For example, passing `true` will define the
+      # flags `--use-github-base-ref` and `--no-use-github-base-ref`.
+      #
+      # @param value [Symbol,boolean]
+      #
+      def use_github_base_ref_flag=(value)
+        @use_github_base_ref_flag = value
+      end
+
+      # @private
+      def initialize
+        @jobs = []
+        @collections = []
+        @all_flag = nil
+        @only_flag = nil
+        @jobs_disabled_by_default = nil
+        @fail_fast_flag = nil
+        @fail_fast_default = false
+        @base_ref_flag = nil
+        @use_github_base_ref_flag = nil
+        @prerun = nil
+      end
+
+      # @private
+      BlockJob = ::Struct.new(:name, :flag, :override_flags, :trigger_paths, :block)
+
+      # @private
+      ToolJob = ::Struct.new(:name, :flag, :override_flags, :trigger_paths, :tool, :env, :chdir)
+
+      # @private
+      CmdJob = ::Struct.new(:name, :flag, :override_flags, :trigger_paths, :cmd, :env, :chdir)
+
+      # @private
+      Collection = ::Struct.new(:name, :flag, :override_flags, :job_flags)
+
+      # @private
+      attr_reader :jobs
+
+      # @private
+      attr_reader :collections
+
+      # @private
+      attr_reader :prerun
+
+      # @private
+      attr_reader :jobs_disabled_by_default
+
+      # @private
+      attr_reader :fail_fast_default
+
+      # @private
+      def all_flag?
+        !@all_flag.nil? && @all_flag != false
+      end
+
+      # @private
+      def only_flag?
+        !@only_flag.nil? && @only_flag != false
+      end
+
+      # @private
+      def fail_fast_flag?
+        !@fail_fast_flag.nil? && @fail_fast_flag != false
+      end
+
+      # @private
+      def base_ref_flag?
+        !@base_ref_flag.nil? && @base_ref_flag != false
+      end
+
+      # @private
+      def use_github_base_ref_flag?
+        !@use_github_base_ref_flag.nil? && @use_github_base_ref_flag != false
+      end
+
+      # @private
+      def all_flag(desired_format = :symbol)
+        format_flag(@all_flag, :all, desired_format)
+      end
+
+      # @private
+      def only_flag(desired_format = :symbol)
+        format_flag(@only_flag, :only, desired_format)
+      end
+
+      # @private
+      def fail_fast_flag(desired_format = :symbol)
+        format_flag(@fail_fast_flag, :fail_fast, desired_format)
+      end
+
+      # @private
+      def base_ref_flag(desired_format = :symbol)
+        format_flag(@base_ref_flag, :base_ref, desired_format)
+      end
+
+      # @private
+      def use_github_base_ref_flag(desired_format = :symbol)
+        format_flag(@use_github_base_ref_flag, :use_github_base_ref, desired_format)
+      end
+
+      # @private
+      def format_flag(raw_flag, default_symbol, desired_format)
+        value = raw_flag == true ? default_symbol : raw_flag
+        desired_format == :hyphenated ? value.to_s.tr("_", "-") : value
+      end
+
+      on_expand do |template|
+        if template.all_flag? && !template.only_flag? && template.jobs_disabled_by_default.nil?
+          template.jobs_disabled_by_default = true
+          flag(template.all_flag) do
+            flags("--#{template.all_flag(:hyphenated)}")
+            desc("Run all jobs unless explicitly disabled by their flags." \
+                 " (If not set, only explicitly enabled jobs run.)")
+          end
+        elsif !template.all_flag? && template.only_flag? && template.jobs_disabled_by_default.nil?
+          template.jobs_disabled_by_default = false
+          flag(template.only_flag) do
+            flags("--#{template.only_flag(:hyphenated)}")
+            desc("Run only jobs explicitly enabled by their flags." \
+                 " (If not set, all jobs run unless explicitly disabled.)")
+          end
+        elsif !template.all_flag? && !template.only_flag?
+          template.jobs_disabled_by_default ||= false
+        else
+          raise ::Toys::ToolDefinitionError, "all_flag, only_flag, and jobs_disabled_by_default are mutually exclusive"
+        end
+
+        if template.fail_fast_flag?
+          flag(template.fail_fast_flag) do
+            flags("--[no-]#{template.fail_fast_flag(:hyphenated)}")
+            default(template.fail_fast_default)
+            desc("Terminate CI as soon as any job fails (default is #{template.fail_fast_default})")
+          end
+        end
+
+        if template.base_ref_flag?
+          flag(template.base_ref_flag) do
+            flags("--#{template.base_ref_flag(:hyphenated)} REF")
+            desc("Filter jobs that do not match changes since this git ref")
+          end
+        end
+
+        if template.use_github_base_ref_flag?
+          flag(template.use_github_base_ref_flag) do
+            flags("--[no-]#{template.use_github_base_ref_flag(:hyphenated)}")
+            desc("Look up the change base from GitHub to determine which jobs to filter")
+          end
+        end
+
+        flag_desc_suffix =
+          if template.all_flag?
+            "(Jobs run by default if --#{template.all_flag(:hyphenated)} is set.)"
+          elsif template.only_flag?
+            "(Jobs run by default unless --#{template.only_flag(:hyphenated)} is set.)"
+          elsif template.jobs_disabled_by_default
+            "(Jobs do not run by default.)"
+          else
+            "(All jobs run by default.)"
+          end
+
+        flag_group(desc: "Jobs") do
+          template.jobs.each do |job|
+            next unless job.flag
+            flag(job.flag) do
+              if job.override_flags.empty?
+                hyphenated_flag = job.flag.to_s.tr("_", "-")
+                flags("--[no-]#{hyphenated_flag}")
+              else
+                job.override_flags.each { |override_flag| flags("--[no-]#{override_flag}") }
+              end
+              desc("Run or omit the job \"#{job.name}\". #{flag_desc_suffix}")
+            end
+          end
+        end
+
+        unless template.collections.empty?
+          flag_group(desc: "Collections") do
+            template.collections.each do |collection|
+              Array(collection.job_flags).each do |job_flag|
+                if template.jobs.none? { |job| job.flag == job_flag }
+                  raise ::Toys::ToolDefinitionError,
+                        "Collection \"#{collection.name}\" referenced nonexistent job flag: #{job_flag}"
+                end
+              end
+              flag(collection.flag) do
+                if collection.override_flags.empty?
+                  hyphenated_flag = collection.flag.to_s.tr("_", "-")
+                  flags("--[no-]#{hyphenated_flag}")
+                else
+                  collection.override_flags.each { |override_flag| flags("--[no-]#{override_flag}") }
+                end
+                desc("Run or omit all \"#{collection.name}\". #{flag_desc_suffix}")
+              end
+            end
+          end
+        end
+
+        static :toys_ci_template, template
+
+        include ::Toys::CI::Mixin
+
+        def run
+          ::Dir.chdir(context_directory) do
+            instance_exec(&toys_ci_template.prerun) if toys_ci_template.prerun
+            toys_ci_init(fail_fast: toys_ci_fail_fast_value, limit_by_changes_since: toys_ci_resolve_base_ref)
+            toys_ci_resolve_collections
+            toys_ci_run_all_jobs
+            toys_ci_report_results
+          end
+        end
+
+        def toys_ci_resolve_base_ref
+          base_ref = toys_ci_template.base_ref_flag? ? self[toys_ci_template.base_ref_flag] : nil
+          if toys_ci_template.use_github_base_ref_flag? && self[toys_ci_template.use_github_base_ref_flag]
+            base_ref ||= toys_ci_github_event_base_sha
+          end
+          base_ref
+        end
+
+        def toys_ci_fail_fast_value
+          if toys_ci_template.fail_fast_flag?
+            self[toys_ci_template.fail_fast_flag]
+          else
+            toys_ci_template.fail_fast_default
+          end
+        end
+
+        def toys_ci_resolve_collections
+          toys_ci_template.collections.each do |collection|
+            value = self[collection.flag]
+            next if value.nil?
+            Array(collection.job_flags).each do |job_flag|
+              set(job_flag, value) if self[job_flag].nil?
+            end
+          end
+        end
+
+        def toys_ci_run_all_jobs
+          toys_ci_template.jobs.each do |job|
+            next unless toys_ci_enabled_value(job.flag)
+            case job
+            when ToolJob
+              toys_ci_tool_job(job.name, job.tool, trigger_paths: job.trigger_paths, env: job.env, chdir: job.chdir)
+            when CmdJob
+              toys_ci_cmd_job(job.name, job.cmd, trigger_paths: job.trigger_paths, env: job.env, chdir: job.chdir)
+            when BlockJob
+              toys_ci_job(job.name, trigger_paths: job.trigger_paths, &job.block)
+            end
+          end
+        end
+
+        def toys_ci_enabled_value(flag)
+          flag_value = self[flag] if flag
+          return flag_value unless flag_value.nil?
+          if toys_ci_template.all_flag?
+            self[toys_ci_template.all_flag]
+          elsif toys_ci_template.only_flag?
+            !self[toys_ci_template.only_flag]
+          else
+            !toys_ci_template.jobs_disabled_by_default
+          end
+        end
+      end
+    end
+  end
+end

data/lib/toys/ci/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Toys
+  module CI
+    ##
+    # Current version of the Toys CI system.
+    # @return [String]
+    #
+    VERSION = "0.1.0"
+  end
+end

data/lib/toys-ci.rb

@@ -1,8 +1,35 @@
+# frozen_string_literal: true
+
+##
+# Toys is a configurable command line tool. Write commands in config files
+# using a simple DSL, and Toys will provide the command line executable and
+# take care of all the details such as argument parsing, online help, and error
+# reporting. Toys is designed for software developers, IT professionals, and
+# other power users who want to write and organize scripts to automate their
+# workflows. It can also be used as a Rake replacement, providing a more
+# natural command line interface for your project's build tasks.
 #
-# This is a placeholder Ruby file for gem "toys-ci".
-# It was generated on 2026-03-11 to reserve the gem name.
-# The actual gem is planned for release in the near future.
-# If this is a problem, or if the actual gem has not been
-# released in a timely manner, you can contact the owner at
-# dazuma@gmail.com
-#
+module Toys
+  ##
+  # The Toys CI system is a mixin and template useful for generating CI tools.
+  #
+  # In this system, a CI tool is a tool that calls some set of other tools or
+  # processes, each of which implements an individual job such as doing a build
+  # or running tests. The CI tool monitors and summarizes the results of those
+  # jobs.
+  #
+  # See {Toys::CI::Mixin} for a lower-level mixin that provides useful methods
+  # for implementing a CI tool, including methods for finding changed files,
+  # for running individual jobs, and for reporting results.
+  #
+  # See {Toys::CI::Template} for a higher-level template that generates a full
+  # CI tool, including flags for controlling how CI should behave and which
+  # jobs should be run.
+  #
+  module CI
+  end
+end
+
+require "toys/ci/mixin"
+require "toys/ci/template"
+require "toys/ci/version"

data/toys/.toys.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "toys-ci"

metadata

@@ -1,26 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: toys-ci
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
-- dazuma@gmail.com
+- Daniel Azuma
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
-description: This is a placeholder gem, which was generated on 2026-03-11 to reserve
-  the gem "toys-ci". The actual gem is planned for release in the near future. If
-  this is a problem, or if the actual gem has not been released in a timely manner,
-  you can contact the owner at dazuma@gmail.com.
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: toys-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.20'
+description: Toys-CI is a framework for generating simple CI coordinator tools. It
+  provides a declarative interface for configuring the tool and specifying individual
+  jobs to run. The generated tool runs jobs specified using command line arguments,
+  and produces a final report of the results.
+email:
+- dazuma@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
+- CHANGELOG.md
+- LICENSE.md
 - README.md
 - lib/toys-ci.rb
-licenses: []
-metadata: {}
+- lib/toys/ci/mixin.rb
+- lib/toys/ci/template.rb
+- lib/toys/ci/version.rb
+- toys/.toys.rb
+homepage: https://github.com/dazuma/toys
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://dazuma.github.io/toys/gems/toys-ci/v0.1.0/file.CHANGELOG.html
+  source_code_uri: https://github.com/dazuma/toys/tree/toys-ci/v0.1.0/toys-ci
+  bug_tracker_uri: https://github.com/dazuma/toys/issues
+  documentation_uri: https://dazuma.github.io/toys/gems/toys-ci/v0.1.0
 rdoc_options: []
 require_paths:
 - lib
@@ -28,7 +57,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -37,5 +66,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Placeholder gem
+summary: CI system using GitHub Actions and Toys
 test_files: []