inquirex-tools 0.8.0 → 0.9.5

data/lib/inquirex/tools/commands/create_release.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Tools
+    module Commands
+      # `inquirex create-release` — tags and publishes a GitHub release for
+      # every package in the family.
+      #
+      # The orchestrator runs each package's own `just release` in that
+      # package's directory, so how a repository tags and writes its notes
+      # stays that repository's business. What this adds is the order, refusing
+      # to tag a dirty tree or a feature branch, and one command instead of six.
+      #
+      # Separate from `publish` on purpose. Publishing is irreversible and
+      # authenticated; releasing is neither, and the two fail for entirely
+      # different reasons — a release that cannot find `gh` should not leave a
+      # half-published family behind it.
+      class CreateRelease < Dry::CLI::Command
+        desc "Tag and create a GitHub release for every package in the family"
+
+        option :dry_run,
+          type:    :boolean,
+          default: false,
+          desc:    "Print what would run; tag nothing"
+
+        option :force,
+          type:    :boolean,
+          default: false,
+          desc:    "Release even from a dirty tree or a branch other than main"
+
+        example [
+          "                # release every package at its current version",
+          "--dry-run       # print what would happen, tag nothing",
+          "--force         # skip the clean-tree and main-branch checks"
+        ]
+
+        # Safe to re-run: each package's recipe force-moves its tag and
+        # recreates its GitHub release, so a run that stopped halfway can be
+        # fixed and reissued rather than unpicked.
+        #
+        # @param options [Hash] parsed CLI options
+        # @return [void]
+        def call(**options)
+          ok = Inquirex::Tools::Releaser.new.call(
+            dry_run: options.fetch(:dry_run, false),
+            force:   options.fetch(:force, false)
+          )
+          exit(1) unless ok
+        rescue Inquirex::Tools::Error => e
+          warn "ERROR: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tools/commands/publish.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Tools
+    module Commands
+      # `inquirex publish` — publishes every package in the family.
+      #
+      # The orchestrator runs each package's own `just publish` in that
+      # package's directory, so how a package reaches its registry stays that
+      # package's business. What this adds is the order, a fresh 2FA code per
+      # gem, and stopping at the first failure.
+      class Publish < Dry::CLI::Command
+        desc "Publish every package in the family to RubyGems and npm"
+
+        option :dry_run,
+          type:    :boolean,
+          default: false,
+          desc:    "Print the commands that would run; publish nothing"
+
+        option :force,
+          type:    :boolean,
+          default: false,
+          desc:    "Attempt every package, even ones already on their registry"
+
+        example [
+          "                # publish whatever is not out yet",
+          "--dry-run       # print what would happen, touch no registry",
+          "--force         # skip the already-published check"
+        ]
+
+        # Idempotent by default: a package whose version is already on its
+        # registry is skipped, so re-running after a mid-release failure
+        # resumes rather than throwing rejections at RubyGems and npm.
+        #
+        # @param options [Hash] parsed CLI options
+        # @return [void]
+        def call(**options)
+          ok = Inquirex::Tools::Publisher.new.call(
+            dry_run: options.fetch(:dry_run, false),
+            force:   options.fetch(:force, false)
+          )
+          exit(1) unless ok
+        rescue Inquirex::Tools::Error => e
+          warn "ERROR: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tools/commands/versions_bump.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Tools
+    module Commands
+      # `inquirex versions-bump` — moves every lockstep package to one version.
+      #
+      # The write counterpart of `inquirex versions-check`. Separate commands
+      # rather than one command with a `--set` flag, so nothing that writes can
+      # be reached by accident from a command meant to report.
+      class VersionsBump < Dry::CLI::Command
+        desc "Set every lockstep package to one version"
+
+        argument :version,
+          type:     :string,
+          required: true,
+          desc:     "Target version, MAJOR.MINOR.PATCH — must not go backwards"
+
+        example [
+          "0.9.0           # move every lockstep package to 0.9.0"
+        ]
+
+        # @param version [String, nil] target version
+        # @return [void]
+        def call(version: nil, **)
+          exit(1) unless Inquirex::Tools::VersionBumper.new.call(version)
+        rescue Inquirex::Tools::Error => e
+          warn "ERROR: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tools/commands/versions_check.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Inquirex
+  module Tools
+    module Commands
+      # `inquirex versions-check` — reports the family's lockstep version.
+      #
+      # Plural on purpose: `inquirex version` prints this tool's own version,
+      # `inquirex versions-check` reports the family's. Read-only; the write
+      # counterpart is `inquirex versions-bump`.
+      class VersionsCheck < Dry::CLI::Command
+        desc "Report lockstep version parity across the family"
+
+        option :preflight,
+          type:    :boolean,
+          default: false,
+          desc:    "Also check clean trees, main branch, and tags"
+
+        example [
+          "                      # report parity, exit 1 on drift",
+          "--preflight           # release readiness"
+        ]
+
+        # @param preflight [Boolean] also report git release readiness
+        # @return [void]
+        def call(preflight: false, **)
+          checker = Inquirex::Tools::VersionChecker.new
+          exit(1) unless preflight ? checker.preflight : checker.call
+        rescue Inquirex::Tools::Error => e
+          warn "ERROR: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/inquirex/tools/commands.rb

@@ -3,7 +3,10 @@
 require "dry/cli"
 
 require_relative "commands/version"
-require_relative "commands/versions"
+require_relative "commands/versions_bump"
+require_relative "commands/versions_check"
+require_relative "commands/publish"
+require_relative "commands/create_release"
 require_relative "commands/changelogs"
 
 module Inquirex
@@ -16,9 +19,14 @@ module Inquirex
     module Commands
       extend Dry::CLI::Registry
 
-      register "versions",   Versions
+      register "versions-check", VersionsCheck
+      register "versions-bump", VersionsBump
+      register "publish", Publish
+      # `publish-all` reads naturally next to the justfile recipe of that name.
+      register "publish-all", Publish
+      register "create-release", CreateRelease
       register "changelogs", Changelogs
-      register "version",    Version
+      register "version", Version
     end
   end
 end

data/lib/inquirex/tools/publisher.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "colored2"
+require "net/http"
+require "uri"
+require_relative "workspace"
+
+module Inquirex
+  module Tools
+    # Publishes every package in the family by running each one's own
+    # `just publish` in its own directory.
+    #
+    # How a package reaches its registry stays that package's business: the
+    # gems build a .gem and `gem push` it, the npm packages run bun or yarn.
+    # This class only decides the order, supplies the one thing a package
+    # cannot work out for itself — a fresh 2FA code — and stops at the first
+    # failure.
+    #
+    # **A TOTP is single-use.** Reading 1Password once per gem inside a
+    # 30-second window returns the same six digits every time, and RubyGems
+    # rejects the second push as a replay. So a code is read per gem and the
+    # run waits for it to actually rotate before moving on, which is why
+    # publishing four gems takes minutes rather than seconds. The npm packages
+    # read their own code and are called with no argument.
+    #
+    # Order comes from {Workspace::LOCKSTEP}, so adding a package to the family
+    # adds it to the release. That order puts the core gem first, which matters:
+    # inquirex-llm and inquirex-tty depend on it and cannot resolve until it is
+    # on RubyGems.
+    #
+    # @example Preview a release without touching a registry
+    #   Inquirex::Tools::Publisher.new.call(dry_run: true)
+    class Publisher
+      # How long to wait for a TOTP to rotate before giving up and using what
+      # 1Password last returned. Codes rotate every 30 seconds; 90 covers a
+      # window boundary landing badly without hanging a release indefinitely.
+      ROTATE_TIMEOUT = 90
+
+      # Seconds between polls of 1Password while waiting for a new code.
+      ROTATE_INTERVAL = 2
+
+      # Shells out with the child's stdout and stderr left attached, so a
+      # failing package's own output is what the operator sees.
+      DEFAULT_RUNNER = lambda { |dir, argv|
+        Dir.chdir(dir) { system("just", *argv) }
+      }
+
+      # Reads the current RubyGems TOTP. `op` resolves the account from
+      # OP_ACCOUNT, which `just publish-all` exports by decrypting
+      # .env.encrypted. Returns nil when unavailable, so a release without
+      # 1Password degrades to `gem push` prompting rather than failing.
+      DEFAULT_OTP_READER = lambda {
+        ref = "op://open-source-repos/ruby-gems/one-time password?attribute=otp"
+        code = `op read #{ref.inspect} 2>/dev/null`.strip
+        code.empty? ? nil : code
+      }
+
+      # Asks the registry whether a version is already public.
+      #
+      # Returns nil rather than false when the answer cannot be obtained — no
+      # network, a 500, a timeout. The caller treats nil as "attempt it": the
+      # registry itself refuses a duplicate, so guessing "not published" and
+      # trying is safe, whereas guessing "published" would silently skip a
+      # package that never shipped.
+      DEFAULT_PUBLISHED_CHECKER = lambda { |name, kind, version|
+        url = case kind
+              when :gem then "https://rubygems.org/api/v2/rubygems/#{name}/versions/#{version}.json"
+              when :npm then "https://registry.npmjs.org/#{name}/#{version}"
+              end
+        begin
+          uri = URI.parse(url)
+          response = Net::HTTP.start(uri.host,
+            uri.port,
+            use_ssl:      true,
+            open_timeout: 5,
+            read_timeout: 5) do |http|
+            http.head(uri.request_uri)
+          end
+          case response
+          when Net::HTTPSuccess  then true
+          when Net::HTTPNotFound then false
+          end
+        rescue StandardError
+          nil
+        end
+      }
+
+      # @param workspace [Workspace] the ecosystem checkout to publish from
+      # @param out [IO] where report output goes
+      # @param runner [#call] invoked with (dir, argv) to run a command; the
+      #   default shells out. Injected so specs can assert what would run
+      #   without publishing anything.
+      # @param otp_reader [#call] returns the current 2FA code, or nil
+      # @param published_checker [#call] (name, kind, version) => true/false/nil
+      def initialize(workspace: Workspace.new,
+        out: $stdout,
+        runner: DEFAULT_RUNNER,
+        otp_reader: DEFAULT_OTP_READER,
+        published_checker: DEFAULT_PUBLISHED_CHECKER)
+        @workspace = workspace
+        @out = out
+        @runner = runner
+        @otp_reader = otp_reader
+        @published_checker = published_checker
+      end
+
+      # Publishes every lockstep package, or prints what it would publish.
+      #
+      # Idempotent: a package whose current version is already on its registry
+      # is skipped, so re-running after a mid-release failure picks up exactly
+      # where it stopped instead of throwing six rejections at two registries.
+      #
+      # @param dry_run [Boolean] print the commands and run nothing
+      # @param args [Array<String>] extra arguments forwarded verbatim to each
+      #   package's `just publish`
+      # @param force [Boolean] attempt every package even when it looks published
+      # @return [Boolean] true when every package published, skipped or printed
+      def call(dry_run: false, args: [], force: false)
+        out.puts(dry_run ? "DRY RUN — these commands would run, in this order:" : "Publishing the family:")
+
+        last_otp = nil
+        published = 0
+        skipped = 0
+
+        Workspace::LOCKSTEP.each do |name, kind|
+          dir = File.join(workspace.root, name)
+          raise Error, "no checkout for #{name} at #{dir}" unless Dir.exist?(dir)
+
+          version = workspace.version_of(name)
+          if !force && version && published_checker.call(name, kind, version)
+            row(name, kind, "already #{version} on #{registry(kind)} — skipping".dark)
+            skipped += 1
+            next
+          end
+
+          argv = ["publish", *args]
+          if dry_run
+            row(name, kind, "just #{argv.join(" ")}#{"   (#{version})" if version}")
+            published += 1
+            next
+          end
+
+          # Only the gems take a code: each npm package reads its own.
+          if kind == :gem
+            last_otp = fresh_otp(last_otp)
+            argv += [last_otp] if last_otp
+          end
+
+          out.puts
+          out.puts "━━ #{name} (#{kind}) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          return false unless run(name, dir, argv)
+
+          published += 1
+        end
+
+        out.puts
+        out.puts summary(dry_run:, published:, skipped:)
+        true
+      end
+
+      private
+
+      # @return [Workspace] the ecosystem checkout being published
+      attr_reader :workspace
+
+      # @return [IO] where report output goes
+      attr_reader :out
+
+      # @return [#call] command runner
+      attr_reader :runner
+
+      # @return [#call] source of 2FA codes
+      attr_reader :otp_reader
+
+      # @return [#call] asks a registry whether a version is already public
+      attr_reader :published_checker
+
+      # @return [Boolean] whether the package published cleanly
+      def run(name, dir, argv)
+        return true if runner.call(dir, argv)
+
+        out.puts
+        out.puts "#{"ERROR".bold.red}: #{name} failed `just #{argv.first}` — stopping here."
+        out.puts "Publishing is irreversible, so the packages after #{name} were left alone."
+        false
+      end
+
+      # Blocks until 1Password returns a code that has not already been spent.
+      #
+      # @param last [String, nil] the code the previous gem used
+      # @return [String, nil] a fresh code, or nil when 1Password is unavailable
+      def fresh_otp(last)
+        waited = 0
+        loop do
+          code = otp_reader.call
+          return nil if code.nil?
+          return code if code != last
+          return code if waited >= ROTATE_TIMEOUT
+
+          out.puts "  waiting for the 2FA code to rotate…" if waited.zero?
+          sleep ROTATE_INTERVAL
+          waited += ROTATE_INTERVAL
+        end
+      end
+
+      # Pads before colorizing: an ANSI escape is several characters wide to
+      # `format` and zero columns wide on screen, so colorizing first left the
+      # table ragged by exactly the length of the escape codes.
+      #
+      # @return [void]
+      def row(name, kind, detail)
+        out.puts "  #{name.ljust(18).yellow} #{kind.to_s.ljust(4).cyan}  #{detail}"
+      end
+
+      # @return [String] human-readable registry name for a package kind
+      def registry(kind) = kind == :gem ? "RubyGems" : "npm"
+
+      # @return [String] the closing line, which has to distinguish "nothing to
+      #   do because everything is already out" from "nothing happened"
+      def summary(dry_run:, published:, skipped:)
+        return "Everything is already published — nothing to do.".green if published.zero? && skipped.positive?
+
+        counted = "#{published} package#{"s" unless published == 1}"
+        note = skipped.positive? ? ", #{skipped} already published" : ""
+        dry_run ? "Would publish #{counted}#{note}. Nothing was published." : "Published #{counted}#{note}.".green
+      end
+    end
+  end
+end

data/lib/inquirex/tools/releaser.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "colored2"
+require_relative "workspace"
+
+module Inquirex
+  module Tools
+    # Cuts a GitHub release for every package in the family by running each
+    # one's own `just release` in its own directory.
+    #
+    # The counterpart to publishing: that puts packages on RubyGems and npm,
+    # this puts a `vX.Y.Z` tag and a GitHub release against the commit that
+    # shipped. Every package already owns a `release` recipe — it tags,
+    # force-pushes the tag, and recreates the GitHub release with generated
+    # notes — so how a repository releases stays that repository's business.
+    # What this adds is the order, the guards, and one command instead of six.
+    #
+    # Unlike publishing, a release is **reversible**: a tag can be moved and a
+    # GitHub release deleted, which is exactly what each recipe does on every
+    # run. That is why this is safe to re-run, and why a mid-run failure can be
+    # fixed and the command simply issued again.
+    #
+    # The guards exist because the recipe tags `HEAD`. Releasing from a dirty
+    # tree tags a commit that does not match what was tested; releasing from a
+    # feature branch tags work that was never merged. Both produce a `v0.9.5`
+    # pointing somewhere nobody can reproduce, and neither is fixed by
+    # re-running — so they are refused rather than warned about.
+    #
+    # @example Preview a release without tagging anything
+    #   Inquirex::Tools::Releaser.new.call(dry_run: true)
+    class Releaser
+      # The only branch a release may be cut from. A tag on anything else
+      # points at work that never went through review.
+      RELEASE_BRANCH = "main"
+
+      # Shells out with the child's stdout and stderr left attached, so a
+      # failing package's own `gh` output is what the operator sees.
+      DEFAULT_RUNNER = lambda { |dir, argv|
+        Dir.chdir(dir) { system("just", *argv) }
+      }
+
+      # @param workspace [Workspace] the ecosystem checkout to release from
+      # @param out [IO] where report output goes
+      # @param runner [#call] invoked with (dir, argv) to run a command; the
+      #   default shells out. Injected so specs can assert what would run
+      #   without creating a tag or a GitHub release.
+      def initialize(workspace: Workspace.new, out: $stdout, runner: DEFAULT_RUNNER)
+        @workspace = workspace
+        @out = out
+        @runner = runner
+      end
+
+      # Creates a GitHub release for every lockstep package.
+      #
+      # Stops at the first package that fails or is refused, and says so. The
+      # packages after it are left alone rather than half-tagged.
+      #
+      # @param dry_run [Boolean] print what would run; tag nothing
+      # @param force [Boolean] release despite a dirty tree or a non-main branch
+      # @param args [Array<String>] extra arguments forwarded to `just release`
+      # @return [Boolean] true when every package released or was printed
+      def call(dry_run: false, force: false, args: [])
+        out.puts(dry_run ? "DRY RUN — these releases would be created:" : "Creating GitHub releases for the family:")
+
+        released = 0
+
+        Workspace::LOCKSTEP.each_key do |name|
+          dir = File.join(workspace.root, name)
+          raise Error, "no checkout for #{name} at #{dir}" unless Dir.exist?(dir)
+
+          version = workspace.version_of(name)
+
+          blocker = force ? nil : blocker_for(name)
+          if blocker
+            row(name, version, blocker.red)
+            return refused(name)
+          end
+
+          argv = ["release", *args]
+          if dry_run
+            row(name, version, "just #{argv.join(" ")}")
+            released += 1
+            next
+          end
+
+          out.puts
+          out.puts "━━ #{name} v#{version} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+          return false unless run(name, dir, argv)
+
+          released += 1
+        end
+
+        out.puts
+        out.puts summary(dry_run:, released:)
+        true
+      end
+
+      private
+
+      # @return [Workspace] the ecosystem checkout being released
+      attr_reader :workspace
+
+      # @return [IO] where report output goes
+      attr_reader :out
+
+      # @return [#call] command runner
+      attr_reader :runner
+
+      # Why this package must not be released, or nil when it is fine.
+      #
+      # A `clean` of nil means the directory is not a git checkout at all. That
+      # is left for the recipe to fail on rather than pre-judged here: a state
+      # that cannot be read should never silently skip a package, because
+      # "unknown" and "not releasable" are different answers.
+      #
+      # @param name [String] package name
+      # @return [String, nil] human-readable blocker
+      def blocker_for(name)
+        state = workspace.git_state(name)
+        return "working tree is dirty — the tag would not match what was tested" if state[:clean] == false
+
+        branch = state[:branch]
+        return nil if branch.nil? || branch.empty? || branch == RELEASE_BRANCH
+
+        "on #{branch}, not #{RELEASE_BRANCH} — the tag would point at unmerged work"
+      end
+
+      # @param name [String] the package that was refused
+      # @return [Boolean] always false, so the caller can `return refused(name)`
+      def refused(name)
+        out.puts
+        out.puts "#{"ERROR".bold.red}: #{name} is not releasable — stopping here."
+        out.puts "Nothing was tagged. Fix the checkout, or re-run with --force to override."
+        false
+      end
+
+      # @return [Boolean] whether the package released cleanly
+      def run(name, dir, argv)
+        return true if runner.call(dir, argv)
+
+        out.puts
+        out.puts "#{"ERROR".bold.red}: #{name} failed `just #{argv.first}` — stopping here."
+        out.puts "A release is re-runnable, so fix the cause and issue the command again."
+        false
+      end
+
+      # Pads before colorizing: an ANSI escape is several characters wide to
+      # `String#ljust` and zero columns wide on screen, so colorizing first left
+      # the table ragged by exactly the length of the escape codes.
+      #
+      # @return [void]
+      def row(name, version, detail)
+        out.puts "  #{name.ljust(18).yellow} #{(version || "?").ljust(8).cyan}  #{detail}"
+      end
+
+      # @return [String] the closing line
+      def summary(dry_run:, released:)
+        counted = "#{released} release#{"s" unless released == 1}"
+        dry_run ? "Would create #{counted}. Nothing was tagged." : "Created #{counted}.".green
+      end
+    end
+  end
+end

data/lib/inquirex/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Inquirex
   module Tools
-    VERSION = "0.8.0"
+    VERSION = "0.9.5"
   end
 end