inquirex-tools 0.8.0 → 0.9.4

data/lib/inquirex/tools/publisher.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "colored2"
+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
+      }
+
+      # @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
+      def initialize(workspace: Workspace.new,
+        out: $stdout,
+        runner: DEFAULT_RUNNER,
+        otp_reader: DEFAULT_OTP_READER)
+        @workspace = workspace
+        @out = out
+        @runner = runner
+        @otp_reader = otp_reader
+      end
+
+      # Publishes every lockstep package, or prints what it would publish.
+      #
+      # @param dry_run [Boolean] print the commands and run nothing
+      # @param args [Array<String>] extra arguments forwarded verbatim to each
+      #   package's `just publish`
+      # @return [Boolean] true when every package published (or was printed)
+      def call(dry_run: false, args: [])
+        out.puts(dry_run ? "DRY RUN — these commands would run, in this order:" : "Publishing the family:")
+
+        last_otp = nil
+        Workspace::LOCKSTEP.each do |name, kind|
+          dir = File.join(workspace.root, name)
+          raise Error, "no checkout for #{name} at #{dir}" unless Dir.exist?(dir)
+
+          argv = ["publish", *args]
+          if dry_run
+            row(name, kind, "just #{argv.join(" ")}")
+            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)
+        end
+
+        out.puts
+        out.puts(dry_run ? "Nothing was published." : "Published every package.".green)
+        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 [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
+    end
+  end
+end

data/lib/inquirex/tools/version.rb

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

data/lib/inquirex/tools/version_bumper.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "colored2"
+require "rubygems/version"
+require_relative "workspace"
+
+module Inquirex
+  module Tools
+    # Moves every lockstep package to one version, then proves each one still
+    # builds — the write half of the pair whose read half is {VersionChecker}.
+    #
+    # The family shares a serialization format, so a version that identifies
+    # one package identifies all of them. Bumping is therefore all-or-nothing:
+    # there is no supported way to move a single package.
+    #
+    # Writing a version and verifying it are one command on purpose. A version
+    # written but never checked is the failure this is meant to prevent: the
+    # number says the family agrees while one package no longer passes its own
+    # suite.
+    #
+    # @example Move the family to 0.9.2 and check every package
+    #   Inquirex::Tools::VersionBumper.new.call("0.9.2")   # => false if any check fails
+    class VersionBumper
+      # A version must be exactly MAJOR.MINOR.PATCH — no prereleases, because
+      # the npm packages and the gems would spell them differently.
+      SEMVER_RE = /\A\d+\.\d+\.\d+\z/
+
+      # Prefix for the refusal messages. This command's only feedback is what
+      # it prints, so the word carries weight.
+      ERROR = "ERROR"
+
+      # What each package is verified with. One recipe for gems and npm
+      # packages alike — every repo's justfile defines it, which is the point
+      # of having a justfile in each.
+      CHECK = %w[just check-all].freeze
+
+      # Rule across the report, sized to the rows.
+      RULE = ("—" * 52).freeze
+
+      # @param workspace [Workspace] the ecosystem checkout to rewrite
+      # @param out [IO] where report output goes
+      def initialize(workspace: Workspace.new, out: $stdout)
+        @workspace = workspace
+        @out = out
+      end
+
+      # Rewrites every lockstep package to the target version, then runs each
+      # package's own `just check-all`.
+      #
+      # Refuses to move backwards: a version already published cannot be
+      # reissued, so the target must be at least the highest current value.
+      #
+      # @param version [String] target, MAJOR.MINOR.PATCH
+      # @param verify [Boolean] run `just check-all` per package afterwards
+      # @return [Boolean] true when every package was written and checked
+      def call(version, verify: true)
+        return false unless valid?(version)
+
+        out.puts "Setting all lockstep packages to #{version} 🚨:"
+        each_package { |name, kind| write(name, kind, version) }
+        return true unless verify
+
+        out.puts
+        out.puts "Verifying each package with `#{CHECK.join(" ")}`:"
+        results = each_package { |name, _kind| check(name) }
+        report(results)
+      end
+
+      private
+
+      # @return [Workspace] the ecosystem checkout being rewritten
+      attr_reader :workspace
+
+      # @return [IO] where report output goes
+      attr_reader :out
+
+      # The one place the package list is walked, so adding a package changes
+      # nothing here.
+      #
+      # @yieldparam name [String] package name
+      # @yieldparam kind [Symbol] :gem or :npm
+      # @return [Hash{String => Object}] name => whatever the block returned
+      def each_package
+        Workspace::LOCKSTEP.to_h { |name, kind| [name, yield(name, kind)] }
+      end
+
+      # @return [void]
+      def write(name, kind, version)
+        workspace.write_version(name, version, kind)
+        row(name, kind.to_s.cyan, version.green)
+      end
+
+      # Runs one package's checks in its own directory.
+      #
+      # A package with no justfile is reported and skipped rather than failed:
+      # the fixture used by the specs has none, and a repo that has not grown
+      # one yet should not make a legitimate bump look broken.
+      #
+      # @param name [String] package name
+      # @return [Boolean, nil] pass/fail, or nil when skipped
+      def check(name)
+        dir = File.join(workspace.root, name)
+        passed = Dir.chdir(dir) do
+          row(name, "running #{CHECK.join(" ")} in ".yellow, dir)
+          out.puts RULE
+          system("git fetch")
+          system("test -n $(git status --porcelain) && { git stash -u; echo 'Stashing locally modified files...'; }")
+          system("git pull origin main")
+          system("git fetch --tags")
+          system("git rebase origin/main")
+          unless File.exist?(File.join(dir, "justfile"))
+            row(name, "skip".yellow, "no justfile".yellow)
+            return nil
+          end
+          row(name, "Pulled in #{name}, current version is #{system("just version")}", dir)
+          system(*CHECK)
+        end
+        row(name, passed ? "[ OK ]".on.green : "[ 🅧 ]".on_red, dir)
+        passed
+      end
+
+      # The single formatting site for every line of the report.
+      #
+      # `format`, never `printf`: printf writes straight to $stdout and returns
+      # nil, so an injected out would receive one blank line per package while
+      # the real output went elsewhere.
+      #
+      # @return [void]
+      def row(name, state, detail)
+        out.puts format(" → %<name>-24s %<state>-6s %<detail>s", name: name.yellow, state:, detail:)
+      end
+
+      # @param results [Hash{String => Boolean, nil}] per-package check outcome
+      # @return [Boolean] true when nothing failed
+      def report(results)
+        failed = results.select { |_name, passed| passed == false }.keys
+        out.puts RULE
+        if failed.empty?
+          out.puts "OK: every package checked out".green
+          true
+        else
+          out.puts "#{ERROR.bold.red}: #{failed.join(", ")} failed `#{CHECK.join(" ")}`"
+          false
+        end
+      end
+
+      # Whether the target is well-formed and moves the family forward.
+      # Reports the reason it does not, since this is the CLI's only feedback.
+      #
+      # @param version [String] proposed target
+      # @return [Boolean]
+      def valid?(version)
+        unless SEMVER_RE.match?(version.to_s)
+          out.puts "#{ERROR.bold.red}: #{version.inspect} is not MAJOR.MINOR.PATCH"
+          return false
+        end
+
+        highest = workspace.versions.values.compact.max_by { Gem::Version.new(it) }
+        if highest && Gem::Version.new(highest) > Gem::Version.new(version)
+          out.puts "#{ERROR.bold.red}: #{version} is below the highest existing " \
+                   "version (#{highest}) — versions only go forward"
+          return false
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/inquirex/tools/version_checker.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "colored2"
+require_relative "workspace"
+
+module Inquirex
+  module Tools
+    # Reports version parity across the lockstep packages.
+    #
+    # Read-only by construction: nothing here writes a version file. Bumping is
+    # {VersionBumper}'s job. The split means a check can be run anywhere — CI, a
+    # dirty tree, a colleague's checkout — with no chance of editing something,
+    # and the two behaviours no longer share a flag that decides which happens.
+    #
+    # @example Check for drift
+    #   Inquirex::Tools::VersionChecker.new.call   # => false when versions differ
+    class VersionChecker
+      # @param workspace [Workspace] the ecosystem checkout to inspect
+      # @param out [IO] where report output goes
+      def initialize(workspace: Workspace.new, out: $stdout)
+        @workspace = workspace
+        @out = out
+      end
+
+      # Prints the current state of every lockstep package.
+      #
+      # @return [Boolean] true when all packages agree on one version
+      def call
+        versions = workspace.versions
+        print_table(versions)
+        verdict(versions)
+      end
+
+      # Parity plus git readiness: clean tree, on main, tagged at the version.
+      #
+      # @return [Boolean] true when every package could be published now
+      def preflight
+        ok = call
+        target = workspace.versions.values.compact.uniq.first
+        out.puts
+        out.puts "Release readiness:"
+
+        Workspace::LOCKSTEP.each_key do |name|
+          problems = readiness_problems(name, target)
+          out.puts format("  %<name>-16s %<state>s", name: name, state: problems.empty? ? "ready".bright_green : problems.join(", ").red)
+          ok &&= problems.empty?
+        end
+
+        out.puts
+        out.puts ok ? "ALL READY — publish with `gem push` / `npm publish`" : "NOT READY — resolve the above"
+        ok
+      end
+
+      private
+
+      # @return [Workspace] the ecosystem checkout being inspected
+      attr_reader :workspace
+
+      # @return [IO] where report output goes
+      attr_reader :out
+
+      # @param versions [Hash{String => String, nil}]
+      # @return [void]
+      def print_table(versions)
+        versions.each do |name, version|
+          # format, not printf: printf writes straight to $stdout and returns
+          # nil, so the injected out saw one blank line per package and the
+          # real table bypassed it entirely.
+          out.puts format(" → %<name>-30s %<kind>5s %<version>6s",
+            name:    name.to_s.yellow,
+            kind:    Workspace::LOCKSTEP[name].to_s.cyan,
+            version: (version || "MISSING").to_s.green)
+        end
+      end
+
+      # @param versions [Hash{String => String, nil}]
+      # @return [Boolean] true when every package agrees on one version
+      def verdict(versions)
+        out.puts "——————————————————————————————————"
+        distinct = versions.values.compact.uniq
+        if versions.value?(nil)
+          out.puts "DRIFT: a version could not be read (MISSING above)".red
+          false
+        elsif distinct.one?
+          out.puts "OK: all #{versions.size} at #{distinct.first}".green
+          true
+        else
+          out.puts "DRIFT: #{distinct.sort.join(", ")} — run `inquirex versions-bump <version>`".yellow
+          false
+        end
+      end
+
+      # Why a package is not publishable right now.
+      #
+      # @param name [String] package name
+      # @param target [String, nil] the version its tag must match
+      # @return [Array<String>] empty when ready
+      def readiness_problems(name, target)
+        state = workspace.git_state(name)
+        return ["no git checkout"] if state[:clean].nil?
+
+        problems = []
+        problems << "DIRTY" unless state[:clean]
+        problems << "on #{state[:branch]}" unless state[:branch] == "main"
+        problems << "untagged" unless state[:tags].any? { |tag| tag.delete_prefix("v") == target }
+        problems
+      end
+    end
+  end
+end

data/lib/inquirex/tools/workspace.rb

@@ -11,34 +11,34 @@ module Inquirex
     # walking up from the working directory looking for the sibling checkouts,
     # or taken from INQUIREX_ROOT.
     class Workspace
-      # Packages that must always carry the same version. They share one
-      # serialization format — the gem defines the DSL and emits step JSON,
-      # inquirex-js renders it, inquirex-webui prints it back to DSL,
-      # inquirex-llm extends the vocabulary, and inquirex-tools is the tooling
-      # that ships alongside them. A verb present in one and absent in another
-      # does not fail loudly; it drops data.
+      # Every package in the family, all carrying the same version. They share
+      # one serialization format — the gem defines the DSL and emits step JSON,
+      # inquirex-widget (npm; formerly @kigster/inquirex-js) renders it,
+      # inquirex-webui prints it back to DSL, inquirex-llm extends the
+      # vocabulary, inquirex-tty walks a flow in the terminal, and
+      # inquirex-tools is the tooling that ships alongside them. A verb present
+      # in one and absent in another does not fail loudly; it drops data.
       #
-      # `inquirex-tty` is deliberately absent: a developer tool outside the
-      # wire contract, versioned on its own cadence.
+      # Nothing is excluded. One version number across the whole family means
+      # "which combination has this bug?" is a lookup rather than an
+      # investigation.
       LOCKSTEP = {
-        "inquirex" => :gem,
-        "inquirex-llm" => :gem,
-        "inquirex-tools" => :gem,
-        "inquirex-js" => :npm,
-        "inquirex-webui" => :npm
+        "inquirex"        => :gem,
+        "inquirex-llm"    => :gem,
+        "inquirex-tools"  => :gem,
+        "inquirex-tty"    => :gem,
+        "inquirex-widget" => :npm,
+        "inquirex-webui"  => :npm
       }.freeze
 
-      # Excluded from lockstep, documented so the omission reads as deliberate.
-      EXCLUDED = %w[inquirex-tty].freeze
-
       # Repositories that carry a generated CHANGELOG.md but are not versioned
       # in lockstep.
-      CHANGELOG_ONLY = %w[inquirex-tty qualified-at].freeze
+      CHANGELOG_ONLY = %w[qualified-at].freeze
 
       GEM_VERSION_RE = /VERSION\s*=\s*"([^"]+)"/
 
       # Directories whose presence identifies the ecosystem root.
-      MARKERS = %w[inquirex inquirex-js].freeze
+      MARKERS = %w[inquirex inquirex-widget].freeze
 
       # @return [String] absolute path to the ecosystem root
       attr_reader :root
@@ -92,18 +92,21 @@ module Inquirex
       #
       # @param name [String] package name
       # @param version [String] new version
+      # @param kind [Symbol] :gem or :npm — which version line to rewrite.
+      #   Passed by the caller rather than looked up here so a caller that
+      #   already knows the kind does not pay for a second lookup.
       # @return [void]
-      def write_version(name, version)
+      def write_version(name, version, kind)
         file = version_file(name)
         raise Error, "no version file for #{name}" unless file
 
         src = File.read(file)
-        updated =
-          if LOCKSTEP[name] == :gem
-            src.sub(GEM_VERSION_RE, %(VERSION = "#{version}"))
-          else
-            src.sub(/"version":\s*"[^"]*"/, %("version": "#{version}"))
-          end
+        updated = case kind
+                  when :gem
+                    src.sub(GEM_VERSION_RE, %(VERSION = "#{version}"))
+                  when :npm
+                    src.sub(/"version":\s*"[^"]*"/, %("version": "#{version}"))
+                  end
         File.write(file, updated)
       end
 
@@ -114,9 +117,9 @@ module Inquirex
         return { clean: nil, branch: nil, tags: [] } unless File.exist?(File.join(dir, ".git"))
 
         {
-          clean: `git -C #{dir} status --porcelain 2>/dev/null`.strip.empty?,
+          clean:  `git -C #{dir} status --porcelain 2>/dev/null`.strip.empty?,
           branch: `git -C #{dir} rev-parse --abbrev-ref HEAD 2>/dev/null`.strip,
-          tags: `git -C #{dir} tag --points-at HEAD 2>/dev/null`.split("\n").map(&:strip).reject(&:empty?)
+          tags:   `git -C #{dir} tag --points-at HEAD 2>/dev/null`.split("\n").map(&:strip).reject(&:empty?)
         }
       end
 

data/lib/inquirex/tools.rb

@@ -2,7 +2,9 @@
 
 require_relative "tools/version"
 require_relative "tools/workspace"
-require_relative "tools/versions"
+require_relative "tools/version_checker"
+require_relative "tools/version_bumper"
+require_relative "tools/publisher"
 require_relative "tools/changelogs"
 
 module Inquirex
@@ -17,13 +19,16 @@ module Inquirex
   # required to have zero runtime dependencies, and nothing added here changes
   # that, because nothing here is loaded by the runtime gems.
   #
-  # Executables:
+  # It ships one executable, `inquirex`, with these subcommands:
   #
-  # - `inquirex-version`    — version parity across the lockstep packages
-  # - `inquirex-changelogs` — regenerate CHANGELOG.md from merged PRs
+  # - `versions-check` — version parity across the lockstep packages
+  # - `versions-bump`  — move every lockstep package to one version
+  # - `publish`        — publish every package to RubyGems and npm
+  # - `changelogs`     — regenerate CHANGELOG.md from merged PRs
+  # - `version`        — this gem's own version
   #
   # @example Check whether the family is releasable
-  #   Inquirex::Tools::Versions.new.preflight  # => true when every package is ready
+  #   Inquirex::Tools::VersionChecker.new.preflight  # => true when every package is ready
   module Tools
     class Error < StandardError; end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-tools
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.4
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: colored2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Ships the `inquirex` command: lockstep version management across the
   Inquirex gems and npm packages, changelog regeneration, and release
@@ -32,24 +46,38 @@ email:
 - kigster@gmail.com
 executables:
 - inquirex
+- inquirexor
 extensions: []
 extra_rdoc_files: []
 files:
 - ".DS_Store"
+- ".env.encrypted"
+- ".env.example"
+- ".envrc"
 - ".github_changelog_generator"
+- ".relaxed_rubocop.yml"
+- ".sops.yaml"
+- ".sopsy.sha"
+- ".sopsy.yml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - exe/inquirex
+- exe/inquirexor
+- justfile
 - lib/inquirex/tools.rb
 - lib/inquirex/tools/changelogs.rb
 - lib/inquirex/tools/commands.rb
 - lib/inquirex/tools/commands/changelogs.rb
+- lib/inquirex/tools/commands/publish.rb
 - lib/inquirex/tools/commands/version.rb
-- lib/inquirex/tools/commands/versions.rb
+- lib/inquirex/tools/commands/versions_bump.rb
+- lib/inquirex/tools/commands/versions_check.rb
+- lib/inquirex/tools/publisher.rb
 - lib/inquirex/tools/version.rb
-- lib/inquirex/tools/versions.rb
+- lib/inquirex/tools/version_bumper.rb
+- lib/inquirex/tools/version_checker.rb
 - lib/inquirex/tools/workspace.rb
 - sig/inquirex/tools.rbs
 homepage: https://github.com/kigster/inquirex-tools