inquirex-tools 0.9.4 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a86b68b3b9abc13c3046754f8b5f43a69f84360e3b581e5760ab9145049da76a
-  data.tar.gz: 5001830e113f7c7b63547f9f49ca10cb290b946c90a0916313e83dee0e1f479a
+  metadata.gz: d8f0e3e2dc5bcc9d45d3c9cba64f8a7d96400b6d1296d316ff56460ece229166
+  data.tar.gz: 3ee07acd2e8e731115e0a5552bbbdaeea2979198195e396fc946765f8b6deef6
 SHA512:
-  metadata.gz: ab2d90315649ab9d2465156964f6436b96a79a5fb0a32c4489ef2910d8a991166da17bcd1731bae08d830097bb2249b91ca9c7ad339e171d48004b812363c8f7
-  data.tar.gz: f7258bdb64b70a46a21b09ccb0f58111077e326b290fdaa3fc72e5cfea1c661abe546e005bce892ec69662fed81c938cbf1645a9cad4eb8e61f0061b56ff721f
+  metadata.gz: 81ca8eed0f60037439fd3c8ab6aafe9b35114082f2c02db488bf279a3d52577c7fb7c8c7e04a41ab48e0c8ab6be1e8e71e324d32b566cbc865ce861e4855601e
+  data.tar.gz: 3adc9867dab085361badf7b00ff38ef9965345efa2ef610bddb27e35e2a34945ebaa2459bdf068e18118cd2121ec67f952564f2f9df562e00d53df49ebb63578

data/docs/badges/coverage_badge.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="99" height="20">
+  <linearGradient id="b" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <mask id="a">
+    <rect width="99" height="20" rx="3" fill="#fff"/>
+  </mask>
+  <g mask="url(#a)">
+    <path fill="#555" d="M0 0h63v20H0z"/>
+    <path fill="#4c1" d="M63 0h36v20H63z"/>
+    <path fill="url(#b)" d="M0 0h99v20H0z"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+    <text x="31.5" y="15" fill="#010101" fill-opacity=".3">coverage</text>
+    <text x="31.5" y="14">coverage</text>
+    <text x="80" y="15" fill="#010101" fill-opacity=".3">97%</text>
+    <text x="80" y="14">97%</text>
+  </g>
+</svg>

data/docs/monorepo-migration.md

@@ -0,0 +1,163 @@
+# Monorepo Migration Plan
+
+Status: **proposed**, not started. Execute only after the open PRs listed under [Sequencing](#sequencing) have merged.
+
+## Why
+
+The Inquirex ecosystem implements the same semantics in two languages and enforces agreement by convention. Three independent implementations of "canonicalize an LLM answer against a question's allowed values" exist today:
+
+| Implementation            | Repo            | Exact | Case-insensitive value | Label fallback | Strips whitespace |
+| ------------------------- | --------------- | ----- | ---------------------- | -------------- | ----------------- |
+| `Node#resolve_option`     | inquirex        | yes   | yes                    | yes            | no                |
+| `Adapter#canonical_value` | inquirex-llm    | yes   | yes                    | **no**         | **yes**           |
+| `canonicalOption`         | inquirex-widget | yes   | yes                    | yes            | **no**            |
+
+They disagree on real inputs. `"US citizen or permanent resident"` resolves through the gem and the widget but returns `nil` through the LLM adapter. `" us_person "` resolves only through the LLM adapter. Nothing in CI can observe this, because no CI job sees more than one of them.
+
+This is the failure mode the family already has scar tissue for. The gem shipped `required false` in 0.7.0 and no consumer knew, because a verb present in one package and missing in another does not fail loudly — it silently drops data. The lockstep version rule exists to make "which combination has this bug?" a lookup rather than an investigation.
+
+The rule is not actually enforced. Every inter-family gemspec declares `~> 0.6`, which admits any 0.x from 0.6 upward. `inquirex-llm`'s checked-in `Gemfile.lock` currently resolves `inquirex-llm (0.9.2)` against `inquirex (0.8.0)`.
+
+A monorepo does not fix divergence by itself. It makes the fix — one shared fixture set, executed by every implementation in one CI run — cheap enough to actually build.
+
+## Scope
+
+**In**, as one public repository:
+
+- `inquirex` — the DSL, engine, and rule AST
+- `inquirex-llm` — LLM verbs
+- `inquirex-widget` — the embeddable TypeScript widget
+- `inquirex-tty` — terminal adapter
+- `inquirex-tools` — release and version tooling (largely absorbed; see below)
+
+**Out**, staying as they are:
+
+- `qualified-at` — the commercial Rails application. Private, its own release cadence, and it consumes the libraries as published packages. Folding a revenue product into the open-source repository forces a visibility decision on the whole tree and buys nothing.
+- `inquirex-webui` — private, React, a distinct product (visual builder). Revisit once the library tree has settled.
+- `inquirex-presentation`, `inquirex-slides`, `claude-setup` — unrelated artifacts.
+
+The in-scope set is exactly the packages bound by the lockstep rule, minus `inquirex-webui`, plus `inquirex-tty` (which PR #2 in this repo brings into lockstep).
+
+## Target layout
+
+```
+inquirex/
+  packages/
+    inquirex/            # gem: DSL, engine, rules
+    inquirex-llm/        # gem: LLM verbs
+    inquirex-tty/        # gem: terminal adapter
+    inquirex-widget/     # npm: TypeScript widget
+  conformance/
+    fixtures/            # language-neutral JSON cases
+    ruby/                # runner: executes fixtures against the gems
+    typescript/          # runner: executes fixtures against the widget
+  tools/                 # release tooling (from inquirex-tools)
+  justfile               # top-level recipes; per-package justfiles remain
+  .github/workflows/
+```
+
+Each package keeps its own gemspec / package.json, test suite, and justfile. The monorepo adds a layer above them, it does not merge their build systems.
+
+## Migration mechanics
+
+History is preserved. Do not squash the repositories into a single import commit.
+
+For each repository, in the order listed under Sequencing:
+
+```bash
+# 1. Clone a scratch copy — never run filter-repo against your working checkout
+git clone git@github.com:inquirex/<pkg>.git /tmp/mono/<pkg>
+cd /tmp/mono/<pkg>
+
+# 2. Rewrite every path to sit under packages/<pkg>/
+git filter-repo --to-subdirectory-filter packages/<pkg>
+
+# 3. Graft it into the monorepo as an unrelated history
+cd /path/to/inquirex-monorepo
+git remote add <pkg> /tmp/mono/<pkg>
+git fetch <pkg>
+git merge --allow-unrelated-histories <pkg>/main -m "Import <pkg> under packages/"
+git remote remove <pkg>
+```
+
+`git filter-repo` requires a fresh clone and refuses to run on a repo with an origin unless forced — that is a guardrail, not an obstacle. Install with `brew install git-filter-repo`.
+
+Path rewriting means `git log --follow packages/inquirex/lib/inquirex/node.rb` walks the full pre-migration history. Blame survives. Existing tags survive but become ambiguous across packages — retag as `<pkg>/vX.Y.Z` after the import, or accept that pre-migration tags refer to a single package's history.
+
+### What happens to the old repositories
+
+Archive, do not delete. Each keeps its issues, its pull requests, and its clone URLs. GitHub archived repos stay readable and redirect nothing, so add a line to each README pointing at the monorepo path. RubyGems and npm metadata should be updated at the next release to point `source_code_uri` / `repository.url` at `inquirex/inquirex` with the appropriate `directory`.
+
+Both npm and RubyGems support a subdirectory hint:
+
+```jsonc
+// packages/inquirex-widget/package.json
+"repository": { "type": "git", "url": "git+https://github.com/inquirex/inquirex.git", "directory": "packages/inquirex-widget" }
+```
+
+```ruby
+# packages/inquirex/inquirex.gemspec
+spec.metadata["source_code_uri"] = "https://github.com/inquirex/inquirex/tree/main/packages/inquirex"
+```
+
+## Versioning and release
+
+One version number for the tree, which is what the lockstep rule always wanted. A single `VERSION` file at the root; each gemspec and `package.json` reads from it at build time.
+
+This deletes most of `inquirex-tools`: cross-repo version checking and bumping becomes `just version <increment>` operating on one file. Keep the release recipes (tagging, GitHub release, publishing); drop the multi-repo coordination.
+
+Fix the constraint hole at the same time. Inter-package dependencies move from `~> 0.6` to `= <VERSION>` or `~> <MAJOR>.<MINOR>`, so bundler cannot resolve a mismatched pair. Do this **in the release that first ships from the monorepo**, not before — tightening `inquirex-llm` to `~> 0.9` while `inquirex` 0.9.x is unpublished breaks `bundle install`.
+
+## CI
+
+One workflow with path filters, so a widget-only change does not run the Ruby matrix:
+
+- `ruby.yml` — triggers on `packages/inquirex*/**` and `conformance/**`; runs each gem's suite
+- `typescript.yml` — triggers on `packages/inquirex-widget/**` and `conformance/**`; runs `bun test`, typecheck, lint, build
+- `conformance.yml` — triggers on **everything**; runs the shared fixtures against both language runners
+
+The third workflow is the point of the exercise. It must not be path-filtered.
+
+## The conformance suite
+
+A fixture is a JSON document describing a flow, a sequence of inputs, and the expected resulting state:
+
+```jsonc
+{
+  "name": "extraction resolves a label to its form value",
+  "flow": { "...": "flow definition" },
+  "steps": [
+    { "extract": { "residency_status": "US citizen or permanent resident" } }
+  ],
+  "expect": {
+    "answers": { "residency_status": "us_person" },
+    "current_step": "income_types",
+    "suggestions": {}
+  }
+}
+```
+
+Each language ships a thin runner that loads a fixture, drives its own engine, and asserts the expected state. Adding a case means adding one JSON file; both languages are then obliged to agree or fail.
+
+Seed it with the divergence table above — those are three cases that fail today. Then extend to transition resolution, `skip_if`, accumulators, and multi-select suggestion handling.
+
+This is the deliverable that justifies the migration. Everything else is filing.
+
+## Sequencing
+
+1. Merge the open work first. Migrating on top of open pull requests strands them: `inquirex-widget` #6-#9, `inquirex` #5/#6, `inquirex-llm` #3, `inquirex-tools` #1/#2, `inquirex-tty` #10. Close or rebase the stale ones (`inquirex-tty` #6 is conflicting and failing; `inquirex` #5 and `inquirex-tools` #1 appear superseded).
+1. Publish 0.9.2 from the existing repositories, so a known-good release exists on both registries before anything moves.
+1. Create the monorepo and import packages in dependency order: `inquirex`, `inquirex-llm`, `inquirex-tty`, `inquirex-widget`, `inquirex-tools`.
+1. Wire up the top-level justfile and per-language CI. Prove every existing suite still passes unchanged.
+1. Build the conformance harness with the three known-divergent cases. Watch them fail.
+1. Reconcile the three implementations. Decide the canonical rules — label fallback yes or no, whitespace stripping yes or no — and make all three obey.
+1. Move to a single root `VERSION`, tighten the inter-package constraints, release 0.10.0 from the monorepo.
+1. Archive the old repositories with a pointer in each README.
+
+Steps 1-2 are prerequisites. Steps 3-4 are reversible: if the imported tree is unsatisfactory, delete it — the original repositories are untouched until step 8.
+
+## Open decisions
+
+- **`inquirex-webui`** — in or out. It is bound by the lockstep rule but is private and a different product. Leaving it out means the rule stays partly manual.
+- **Visibility** — the monorepo must be public for the gems to remain credible open source. That is only tenable if nothing private is imported, which the scope above respects.
+- **Canonical matching rules** — the reconciliation in step 6 is a semantics decision, not a mechanical one. Whitespace stripping is almost certainly correct everywhere. The label fallback is the real question: it is most needed in `inquirex-llm`, which is the one implementation lacking it.

data/lib/inquirex/tools/changelogs.rb

@@ -18,11 +18,29 @@ module Inquirex
       # Never overwritten by generation, in any repo.
       PROTECTED = %w[INQUIREX_VERSION_LOG.md].freeze
 
+      # Reads a GitHub token from the `gh` session rather than a stored secret,
+      # so nothing here handles a credential in plain text.
+      DEFAULT_TOKEN_READER = -> { `gh auth token 2>/dev/null`.strip }
+
+      # Runs the generator in one repository, discarding its very chatty output.
+      DEFAULT_RUNNER = lambda { |dir, env|
+        system(env, "github_changelog_generator", chdir: dir, out: File::NULL, err: File::NULL)
+      }
+
       # @param workspace [Workspace]
       # @param out [IO]
-      def initialize(workspace: Workspace.new, out: $stdout)
+      # @param token_reader [#call] returns a GitHub token, or "" when there is
+      #   no session. Injected so a spec never needs one.
+      # @param runner [#call] invoked with (dir, env) to run the generator.
+      #   Injected so a spec never shells out to it.
+      def initialize(workspace: Workspace.new,
+        out: $stdout,
+        token_reader: DEFAULT_TOKEN_READER,
+        runner: DEFAULT_RUNNER)
         @workspace = workspace
         @out = out
+        @token_reader = token_reader
+        @runner = runner
       end
 
       # @return [Array<String>] every repo carrying a generator config
@@ -41,7 +59,7 @@ module Inquirex
       # @param names [Array<String>] repositories, or all configured when empty
       # @return [Boolean] true when every repository succeeded
       def generate(*names)
-        token = `gh auth token 2>/dev/null`.strip
+        token = @token_reader.call.to_s.strip
         if token.empty?
           @out.puts "ERROR: `gh auth token` returned nothing — run `gh auth login`"
           return false
@@ -69,7 +87,7 @@ module Inquirex
 
         @out.print format("  %<name>-16s ", name: name)
         env = { "CHANGELOG_GITHUB_TOKEN" => token, "RBENV_VERSION" => ENV.fetch("RBENV_VERSION", DEFAULT_RUBY) }
-        if system(env, "github_changelog_generator", chdir: dir, out: File::NULL, err: File::NULL)
+        if @runner.call(dir, env)
           @out.puts "ok (#{line_count(File.join(dir, "CHANGELOG.md"))} lines)"
           true
         else

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

@@ -17,15 +17,29 @@ module Inquirex
           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 the whole family",
-          "--dry-run       # print what would happen, touch no registry"
+          "                # 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)
-          exit(1) unless Inquirex::Tools::Publisher.new.call(dry_run: options.fetch(:dry_run, false))
+          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

data/lib/inquirex/tools/commands.rb

@@ -6,6 +6,7 @@ require_relative "commands/version"
 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
@@ -21,6 +22,9 @@ module Inquirex
       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
     end

data/lib/inquirex/tools/publisher.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "colored2"
+require "net/http"
+require "uri"
 require_relative "workspace"
 
 module Inquirex
@@ -53,39 +55,88 @@ module Inquirex
         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)
+        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`
-      # @return [Boolean] true when every package published (or was printed)
-      def call(dry_run: false, args: [])
+      # @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(" ")}")
+            row(name, kind, "just #{argv.join(" ")}#{"   (#{version})" if version}")
+            published += 1
             next
           end
 
@@ -98,10 +149,12 @@ module Inquirex
           out.puts
           out.puts "━━ #{name} (#{kind}) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
           return false unless run(name, dir, argv)
+
+          published += 1
         end
 
         out.puts
-        out.puts(dry_run ? "Nothing was published." : "Published every package.".green)
+        out.puts summary(dry_run:, published:, skipped:)
         true
       end
 
@@ -119,6 +172,9 @@ module Inquirex
       # @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)
@@ -155,6 +211,19 @@ module Inquirex
       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.9.4"
+    VERSION = "0.9.5"
   end
 end

data/lib/inquirex/tools/version_bumper.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "colored2"
+require "open3"
 require "rubygems/version"
 require_relative "workspace"
 
@@ -37,11 +38,43 @@ module Inquirex
       # Rule across the report, sized to the rows.
       RULE = ("—" * 52).freeze
 
+      # Bringing a checkout level with origin/main before its suite runs, so a
+      # bump is verified against what is actually on main rather than whatever
+      # the local clone last saw.
+      SYNC_STEPS = [
+        %w[fetch --tags origin],
+        %w[rebase origin/main]
+      ].freeze
+
+      # Runs one git command, capturing stdout *and* stderr.
+      #
+      # Capturing is the point. Left attached, a `git` run against a directory
+      # that is not a checkout writes "fatal: not a git repository" straight to
+      # the terminal — thirty such lines during the specs, which is noise the
+      # operator has to learn to ignore. The caller decides what is worth
+      # printing.
+      #
+      # @return [Array(Boolean, String)] success, and the combined output
+      DEFAULT_GIT = lambda { |dir, argv|
+        output, status = Open3.capture2e("git", "-C", dir, *argv)
+        [status.success?, output]
+      }
+
+      # Runs a package's own checks in its own directory.
+      DEFAULT_RUNNER = ->(dir, argv) { Dir.chdir(dir) { system(*argv) } }
+
       # @param workspace [Workspace] the ecosystem checkout to rewrite
       # @param out [IO] where report output goes
-      def initialize(workspace: Workspace.new, out: $stdout)
+      # @param git [#call] invoked with (dir, argv); returns [ok, output].
+      #   Injected so specs can assert what would run without touching a repo.
+      # @param runner [#call] invoked with (dir, argv) to run a package's
+      #   checks. Injected for the same reason: a unit test must not shell out
+      #   to six real suites.
+      def initialize(workspace: Workspace.new, out: $stdout, git: DEFAULT_GIT, runner: DEFAULT_RUNNER)
         @workspace = workspace
         @out = out
+        @git = git
+        @runner = runner
       end
 
       # Rewrites every lockstep package to the target version, then runs each
@@ -74,6 +107,12 @@ module Inquirex
       # @return [IO] where report output goes
       attr_reader :out
 
+      # @return [#call] runs one git command, returning [ok, output]
+      attr_reader :git
+
+      # @return [#call] runs a package's checks, returning truthy on success
+      attr_reader :runner
+
       # The one place the package list is walked, so adding a package changes
       # nothing here.
       #
@@ -100,25 +139,47 @@ module Inquirex
       # @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)
+        unless File.exist?(File.join(dir, "justfile"))
+          row(name, "skip".yellow, "no justfile".yellow)
+          return nil
         end
-        row(name, passed ? "[ OK ]".on.green : "[ 🅧 ]".on_red, dir)
+
+        sync(name, dir)
+        passed = runner.call(dir, CHECK)
+        row(name, passed ? "ok".green : "FAIL".red, dir)
         passed
       end
 
+      # Brings one package level with origin/main before its suite runs.
+      #
+      # Two states are reported and left alone rather than acted on:
+      #
+      # - **not a git checkout** — nothing to sync, and running git here is what
+      #   printed "fatal: not a git repository" once per command per package.
+      # - **uncommitted changes** — the tree is *not* stashed. A version bump
+      #   that silently runs `git stash -u` can bury work the operator never
+      #   agreed to move, and the stash stack is shared across worktrees, so it
+      #   is not even reliably theirs to pop back. Rebasing on top of local
+      #   edits is equally unwelcome. Skipping is the only non-destructive
+      #   answer; the checks still run against what is on disk.
+      #
+      # @param name [String] package name
+      # @param dir [String] absolute path to the package
+      # @return [void]
+      def sync(name, dir)
+        state = workspace.git_state(name)
+        return row(name, "sync".yellow, "not a git checkout".yellow) if state[:clean].nil?
+        return row(name, "sync".yellow, "uncommitted changes — left alone".yellow) unless state[:clean]
+
+        SYNC_STEPS.each do |argv|
+          ok, output = git.call(dir, argv)
+          next if ok
+
+          row(name, "sync".red, "git #{argv.first} failed: #{output.to_s.lines.first&.strip}".red)
+          break
+        end
+      end
+
       # The single formatting site for every line of the report.
       #
       # `format`, never `printf`: printf writes straight to $stdout and returns

data/lib/inquirex/tools/version_checker.rb

@@ -42,7 +42,10 @@ module Inquirex
 
         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)
+          # `.green`, not `.bright_green`: colored2 defines no such method, so
+          # the ready branch raised NoMethodError — and only the ready branch,
+          # which is why a preflight that found problems looked fine.
+          out.puts format("  %<name>-16s %<state>s", name: name, state: problems.empty? ? "ready".green : problems.join(", ").red)
           ok &&= problems.empty?
         end
 

data/lib/inquirex/tools.rb

@@ -5,6 +5,7 @@ require_relative "tools/workspace"
 require_relative "tools/version_checker"
 require_relative "tools/version_bumper"
 require_relative "tools/publisher"
+require_relative "tools/releaser"
 require_relative "tools/changelogs"
 
 module Inquirex
@@ -24,6 +25,7 @@ module Inquirex
   # - `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
+  # - `create-release` — tag and create a GitHub release for every package
   # - `changelogs`     — regenerate CHANGELOG.md from merged PRs
   # - `version`        — this gem's own version
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inquirex-tools
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.5
 platform: ruby
 authors:
 - Konstantin Gredeskoul
@@ -63,6 +63,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/badges/coverage_badge.svg
+- docs/monorepo-migration.md
 - exe/inquirex
 - exe/inquirexor
 - justfile
@@ -70,11 +72,13 @@ files:
 - lib/inquirex/tools/changelogs.rb
 - lib/inquirex/tools/commands.rb
 - lib/inquirex/tools/commands/changelogs.rb
+- lib/inquirex/tools/commands/create_release.rb
 - lib/inquirex/tools/commands/publish.rb
 - lib/inquirex/tools/commands/version.rb
 - lib/inquirex/tools/commands/versions_bump.rb
 - lib/inquirex/tools/commands/versions_check.rb
 - lib/inquirex/tools/publisher.rb
+- lib/inquirex/tools/releaser.rb
 - lib/inquirex/tools/version.rb
 - lib/inquirex/tools/version_bumper.rb
 - lib/inquirex/tools/version_checker.rb