ruby-repo-kit 0.1.0

data/templates/cli/README.md.erb

@@ -0,0 +1,53 @@
+# <%= @name %>
+
+A small Ruby CLI that prints its text arguments separated by spaces.
+
+Requires Ruby 3.4 or newer. This initial implementation has no external service
+dependencies.
+
+## Usage
+
+    <%= @name %> hello world
+    <%= @name %> --help
+    <%= @name %> --version
+    <%= @name %> -- --text-starting-with-a-dash
+
+Successful output goes to stdout. Invalid options and missing text go to stderr
+with exit status 2. A closed output pipe exits cleanly.
+
+## Install from source
+
+    gem build <%= @name %>.gemspec
+    gem install ./<%= @name %>-0.1.0.gem
+
+This repository's creation does not publish the gem or reserve its name.
+After a release has actually been published, RubyGems installation is available:
+
+    gem install <%= @name %>
+
+## Development
+
+    bin/setup
+    bundle exec rake check
+    bundle exec rake audit
+
+Commit Gemfile.lock after dependency installation. It pins development tools;
+users installing the gem resolve the dependencies declared in its gemspec.
+The versioned ruby-repo-kit development dependency supplies repository and release
+operations. That gem version must be available from the configured source before
+contributors or hosted CI can install the development bundle.
+
+Local checks include Ruby linting, tests with coverage (90% lines, 80% branches),
+repository checks and installation of the built package.
+The separate audit task updates a vulnerability database and
+needs network access. CI additionally checks pull-request commits and exercises
+Ruby 3.4/4.0 on Linux and Ruby 4.0 on macOS. These are configured checks, not a
+claim that a new repository has already passed them.
+
+See [contributing](CONTRIBUTING.md), [architecture](ARCHITECTURE.md),
+[security](SECURITY.md), [conduct](CODE_OF_CONDUCT.md), and
+[release setup](docs/releasing.md).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/templates/cli/Rakefile.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+require "rubocop/rake_task"
+require "fileutils"
+require "ruby_repo_kit"
+require "ruby_repo_kit/rake_tasks"
+
+RubyRepoKit::RakeTasks.install(project: RubyRepoKit::Project.load(root: __dir__))
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "lib" << "test"
+  task.pattern = "test/**/*_test.rb"
+  task.warning = true
+end
+
+RuboCop::RakeTask.new(:rubocop)
+
+namespace :test do
+  desc "Run tests with line and branch coverage"
+  task :cov do
+    FileUtils.rm_f("coverage/.resultset.json")
+    sh({ "COVERAGE" => "1" }, "bundle", "exec", "rake", "test")
+  end
+end
+
+desc "Regenerate project-owned artifacts (none are configured yet)"
+task :generate
+
+namespace :generate do
+  desc "Check generated artifacts (none are configured yet)"
+  task :check
+end
+
+desc "Run local lint, tests, repository and installed-package checks"
+task check: %w[rubocop test:cov repo:check generate:check package:check]
+
+task default: :check

data/templates/cli/SECURITY.md.erb

@@ -0,0 +1,11 @@
+# Security
+
+Report suspected vulnerabilities privately to <%= @email %>. Include the affected
+version, impact and a minimal reproduction; do not disclose private credentials.
+Please avoid a public issue until maintainers have coordinated a fix.
+
+Security fixes target the latest released version. If no version has been
+published yet, report issues against the current main branch.
+
+The project does not promise a response deadline. Maintainers will assess the
+report, agree on disclosure where possible, and document any published fix.

data/templates/cli/__name__.gemspec.erb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "lib/<%= @require_path %>/version"
+
+Gem::Specification.new do |spec|
+  spec.name = <%= ruby_literal(@name) %>
+  spec.version = <%= @namespace %>::VERSION
+  spec.authors = [<%= ruby_literal(@author) %>]
+  spec.email = [<%= ruby_literal(@email) %>]
+  spec.summary = "A small command-line tool that prints text"
+  spec.description = "Prints positional arguments separated by spaces; includes help and version commands."
+  spec.homepage = "https://github.com/<%= @repository %>"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.4"
+  spec.metadata = {
+    "source_code_uri" => spec.homepage,
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "documentation_uri" => "#{spec.homepage}#readme",
+    "rubygems_mfa_required" => "true",
+    "allowed_push_host" => "https://rubygems.org"
+  }
+  # Build from a source archive too; development infrastructure is not shipped.
+  spec.files = Dir.chdir(__dir__) do
+    Dir.glob("lib/**/*.rb") + %w[exe/<%= @name %> README.md CHANGELOG.md LICENSE.txt SECURITY.md]
+  end
+  spec.bindir = "exe"
+  spec.executables = [<%= ruby_literal(@name) %>]
+  spec.require_paths = ["lib"]
+  spec.add_dependency "optparse", ">= 0.6", "< 1"
+end

data/templates/cli/bin/release.erb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "ruby_repo_kit/cli"
+
+exit RubyRepoKit::CLI.run(["release", *ARGV], root: File.expand_path("..", __dir__))

data/templates/cli/bin/setup.erb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rbconfig"
+
+Dir.chdir(File.expand_path("..", __dir__)) do
+  abort "Dependency installation failed" unless system(RbConfig.ruby, "-S", "bundle", "install")
+end

data/templates/cli/docs/releasing.md.erb

@@ -0,0 +1,42 @@
+# Release setup and operation
+
+The scaffold does not create a GitHub repository, rulesets, environments, labels
+or RubyGems publisher. It does not reserve a public gem name or publish anything.
+The configured repository identity is <%= @repository %>.
+
+Before the first release:
+
+1. Confirm the repository and public gem name.
+2. Make the configured ruby-repo-kit version available to hosted dependency
+   installation and commit the generated Gemfile.lock.
+3. Push the repository and confirm every configured CI job passes.
+4. Configure branch protection or a ruleset using the required_checks values in
+   .ruby-repo.yml. Create the skip-changelog label if using that workflow.
+5. Create the GitHub release environment and its intended protection rules.
+6. Configure a RubyGems pending trusted publisher for this gem, repository,
+   release.yml workflow and release environment. For an existing gem, configure
+   its trusted publisher instead. No long-lived RubyGems API token is required.
+7. Run the Release workflow manually with dry_run enabled and inspect its
+   checks, package, digest and provenance before publishing.
+
+The toolkit's release CLI exposes preparation, PR and recovery operations:
+
+    bin/release --help
+
+Use its help for the installed version's commands and options. A protected
+release is prepared and reviewed before an immutable version tag is pushed.
+Do not push a release tag as an experiment: a matching tag authorizes publication
+once the hosted publisher is configured.
+
+The Release workflow runs CI, builds one artifact, tests that artifact and
+records its SHA-256 digest. Attestation, RubyGems publication and the GitHub
+release consume that same downloaded artifact, checking its digest again.
+The publish job uses OIDC credentials in the release environment. A branch
+dry-run builds and verifies without publishing.
+
+If a run stops after publishing, inspect both RubyGems and GitHub before retrying.
+Never move a published tag or replace a published gem version. Preserve the
+original artifact and use the toolkit's recovery diagnostics.
+
+Local package tests and a hosted dry-run do not prove RubyGems authentication.
+Record the actual successful publication and installation separately.

data/templates/cli/exe/__name__.erb

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "<%= @require_path %>"
+
+exit <%= @namespace %>::CLI.run(ARGV)

data/templates/cli/lib/__require_path__/cli.rb.erb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "version"
+
+module <%= @namespace %>
+  class CLI
+    def self.run(argv, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv)
+    end
+
+    def initialize(out:, err:)
+      @out = out
+      @err = err
+    end
+
+    def run(argv)
+      arguments = argv.dup
+      requested = nil
+      parser = OptionParser.new do |options|
+        options.banner = "Usage: <%= @name %> [options] TEXT..."
+        options.separator ""
+        options.separator "Print text, separating arguments with spaces."
+        options.on("-h", "--help", "Show this help") { requested = :help }
+        options.on("-v", "--version", "Show the version") { requested = :version }
+      end
+      parser.parse!(arguments)
+      return print_result(parser.to_s) if requested == :help
+      return print_result(VERSION) if requested == :version
+
+      raise OptionParser::MissingArgument, "TEXT (see --help)" if arguments.empty?
+
+      print_result(arguments.join(" "))
+    rescue OptionParser::ParseError => e
+      @err.puts "<%= @name %>: #{e.message}"
+      2
+    rescue Errno::EPIPE
+      0
+    end
+
+    private
+
+    def print_result(value)
+      @out.puts value
+      @out.flush
+      0
+    end
+  end
+end

data/templates/cli/lib/__require_path__/version.rb.erb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module <%= @namespace %>
+  VERSION = "0.1.0"
+end

data/templates/cli/lib/__require_path__.rb.erb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "<%= @require_path %>/version"
+require_relative "<%= @require_path %>/cli"

data/templates/cli/test/cli_test.rb.erb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class CLITest < Minitest::Test
+  def setup
+    @out = StringIO.new
+    @err = StringIO.new
+  end
+
+  def test_prints_text_without_changing_the_argument_array
+    arguments = %w[hello world]
+
+    assert_equal 0, run_cli(arguments)
+    assert_equal "hello world\n", @out.string
+    assert_empty @err.string
+    assert_equal %w[hello world], arguments
+  end
+
+  def test_help
+    assert_equal 0, run_cli(["--help"])
+    assert_includes @out.string, "Usage: <%= @name %>"
+    assert_empty @err.string
+  end
+
+  def test_version
+    assert_equal 0, run_cli(["--version"])
+    assert_equal "#{<%= @namespace %>::VERSION}\n", @out.string
+    assert_empty @err.string
+  end
+
+  def test_invalid_flag_uses_stderr
+    assert_equal 2, run_cli(["--not-an-option"])
+    assert_empty @out.string
+    assert_includes @err.string, "invalid option"
+  end
+
+  def test_missing_text_is_an_error
+    assert_equal 2, run_cli([])
+    assert_empty @out.string
+    assert_includes @err.string, "TEXT"
+  end
+
+  def test_option_separator_allows_text_beginning_with_a_dash
+    assert_equal 0, run_cli(["--", "--text"])
+    assert_equal "--text\n", @out.string
+  end
+
+  def test_a_closed_output_pipe_exits_cleanly
+    output = Object.new
+    def output.puts(*) = raise Errno::EPIPE
+
+    assert_equal 0, <%= @namespace %>::CLI.run(["hello"], out: output, err: @err)
+    assert_empty @err.string
+  end
+
+  private
+
+  def run_cli(arguments)
+    <%= @namespace %>::CLI.run(arguments, out: @out, err: @err)
+  end
+end

data/templates/cli/test/test_helper.rb.erb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+if ENV["COVERAGE"] == "1"
+  require "simplecov"
+
+  SimpleCov.start do
+    enable_coverage :branch
+    minimum_coverage line: 90, branch: 80
+    skip "/test/"
+  end
+end
+
+require "minitest/autorun"
+require "stringio"
+require "<%= @require_path %>"

metadata

@@ -0,0 +1,252 @@
+--- !ruby/object:Gem::Specification
+name: ruby-repo-kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Highlander Paiva
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: date
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: erb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: open3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: optparse
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: psych
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+description: Shared release, repository checks and focused Ruby CLI generation, installed
+  as a development dependency.
+email:
+- contact@hvpaiva.dev
+executables:
+- ruby-repo-kit
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/rubocop.yml
+- exe/ruby-repo-kit
+- lib/ruby_repo_kit.rb
+- lib/ruby_repo_kit/checks.rb
+- lib/ruby_repo_kit/checks/commits.rb
+- lib/ruby_repo_kit/cli.rb
+- lib/ruby_repo_kit/commands.rb
+- lib/ruby_repo_kit/github.rb
+- lib/ruby_repo_kit/github/client.rb
+- lib/ruby_repo_kit/github/configuration.rb
+- lib/ruby_repo_kit/github/policy.rb
+- lib/ruby_repo_kit/package.rb
+- lib/ruby_repo_kit/project.rb
+- lib/ruby_repo_kit/rake_tasks.rb
+- lib/ruby_repo_kit/release.rb
+- lib/ruby_repo_kit/release/artifact.rb
+- lib/ruby_repo_kit/release/metadata.rb
+- lib/ruby_repo_kit/release/preparation.rb
+- lib/ruby_repo_kit/release/publication.rb
+- lib/ruby_repo_kit/release/publisher.rb
+- lib/ruby_repo_kit/release/workflow.rb
+- lib/ruby_repo_kit/scaffold.rb
+- lib/ruby_repo_kit/specification.rb
+- lib/ruby_repo_kit/version.rb
+- templates/cli/.editorconfig.erb
+- templates/cli/.github/ISSUE_TEMPLATE/bug_report.yml.erb
+- templates/cli/.github/ISSUE_TEMPLATE/config.yml.erb
+- templates/cli/.github/ISSUE_TEMPLATE/feature_request.yml.erb
+- templates/cli/.github/PULL_REQUEST_TEMPLATE.md.erb
+- templates/cli/.github/dependabot.yml.erb
+- templates/cli/.github/workflows/ci.yml.erb
+- templates/cli/.github/workflows/release.yml.erb
+- templates/cli/.gitignore.erb
+- templates/cli/.rubocop.yml.erb
+- templates/cli/.ruby-repo.yml.erb
+- templates/cli/.ruby-version.erb
+- templates/cli/ARCHITECTURE.md.erb
+- templates/cli/CHANGELOG.md.erb
+- templates/cli/CODE_OF_CONDUCT.md.erb
+- templates/cli/CONTRIBUTING.md.erb
+- templates/cli/Gemfile.erb
+- templates/cli/LICENSE.txt.erb
+- templates/cli/README.md.erb
+- templates/cli/Rakefile.erb
+- templates/cli/SECURITY.md.erb
+- templates/cli/__name__.gemspec.erb
+- templates/cli/bin/release.erb
+- templates/cli/bin/setup.erb
+- templates/cli/docs/releasing.md.erb
+- templates/cli/exe/__name__.erb
+- templates/cli/lib/__require_path__.rb.erb
+- templates/cli/lib/__require_path__/cli.rb.erb
+- templates/cli/lib/__require_path__/version.rb.erb
+- templates/cli/test/cli_test.rb.erb
+- templates/cli/test/test_helper.rb.erb
+homepage: https://github.com/hvpaiva/ruby-repo-kit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/hvpaiva/ruby-repo-kit
+  changelog_uri: https://github.com/hvpaiva/ruby-repo-kit/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Versioned maintenance tools and scaffolding for Ruby CLI repositories
+test_files: []